# Admin User Detail Page Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Add `/admin/users/[id]` detail page with editable user info, period-based usage stats, recent trip list, and a plan tier foundation (free/paid + expiry) visible only to admins — no user-facing restrictions. **Architecture:** Server component fetches user + recent trips on page load. Two client components handle editing/plan/actions (`AdminUserDetailClient`) and stats tab switching (`AdminUserDetailStats`). Plan tier (`plan` + `planExpiresAt`) is stored in DB, surfaced only in admin UI, and enforced nowhere yet. **Tech Stack:** Next.js App Router, Prisma 5 (PostgreSQL), NextAuth, inline styles with CSS variables (`var(--text-primary)` etc.) --- ## File Map | Action | File | Responsibility | |--------|------|----------------| | Modify | `prisma/schema.prisma` | Add `plan` + `planExpiresAt` to User | | Create | `lib/plan.ts` | `isPaid()` gating helper (unused for now) | | Modify | `app/api/admin/users/[id]/route.ts` | Extend PATCH allowed fields | | Create | `app/api/admin/users/[id]/stats/route.ts` | GET period stats | | Modify | `app/admin/users/page.tsx` | Include `plan`/`planExpiresAt` in select | | Modify | `app/admin/users/AdminUsersClient.tsx` | Plan badge + "상세보기" link | | Create | `app/admin/users/[id]/page.tsx` | Server component, data fetch, ADMIN guard | | Create | `app/admin/users/[id]/AdminUserDetailStats.tsx` | Period tabs + stat cards + recent trips | | Create | `app/admin/users/[id]/AdminUserDetailClient.tsx` | Header + actions + info edit + plan UI | --- ## Task 1: Add plan fields to Prisma schema **Files:** - Modify: `prisma/schema.prisma` - [ ] **Step 1: Add plan fields to User model** In `prisma/schema.prisma`, add two lines after the `isActive` field inside the `User` model: ```prisma isActive Boolean @default(true) plan String @default("free") planExpiresAt DateTime? createdAt DateTime @default(now()) ``` - [ ] **Step 2: Run migration** ```bash cd /home/lucas/.www/transit && npx prisma migrate dev --name add_plan_fields ``` Expected output includes: `The following migration(s) have been applied: ...add_plan_fields` `prisma migrate dev` runs `prisma generate` automatically — no separate generate step needed. - [ ] **Step 3: Commit** ```bash git add prisma/schema.prisma prisma/migrations/ git commit -m "feat(db): add plan and planExpiresAt fields to User" ``` --- ## Task 2: Create plan utility **Files:** - Create: `lib/plan.ts` - [ ] **Step 1: Write the utility** Create `/home/lucas/.www/transit/lib/plan.ts`: ```ts export function isPaid(user: { plan: string; planExpiresAt: Date | null }): boolean { if (user.plan !== 'paid') return false; if (!user.planExpiresAt) return true; return new Date(user.planExpiresAt) > new Date(); } ``` This function is not called anywhere yet. It exists so future feature gates are a single import away. - [ ] **Step 2: Commit** ```bash git add lib/plan.ts git commit -m "feat(plan): add isPaid utility for future feature gating" ``` --- ## Task 3: Extend PATCH API to accept new fields **Files:** - Modify: `app/api/admin/users/[id]/route.ts` - [ ] **Step 1: Update the PATCH handler** Replace the `PATCH` function body in `app/api/admin/users/[id]/route.ts` with: ```ts export async function PATCH(req: NextRequest, { params }: { params: Promise<{ id: string }> }) { if (!await getAdminSession()) return NextResponse.json({ error: "Forbidden" }, { status: 403 }); const { id } = await params; const userId = parseInt(id); if (isNaN(userId)) return NextResponse.json({ error: "Invalid id" }, { status: 400 }); const body = await req.json(); const allowed = [ "approvalStatus", "role", "isActive", "transportMode", "transportModeConfirmed", "name", "phone", "vehicleNumber", "vehicleType", "vehicleTonnage", "bankName", "accountNumber", "accountHolder", "profileMemo", "plan", "planExpiresAt", ]; const data: Record = {}; for (const key of allowed) { if (key in body) data[key] = body[key]; } if ("transportMode" in body) { if (!["", "general", "trailer", "dump"].includes(body.transportMode)) { return NextResponse.json({ error: "Invalid transportMode" }, { status: 400 }); } } if ("plan" in body) { if (!["free", "paid"].includes(body.plan)) { return NextResponse.json({ error: "Invalid plan" }, { status: 400 }); } } if ("planExpiresAt" in body) { data.planExpiresAt = body.planExpiresAt ? new Date(body.planExpiresAt) : null; } const user = await prisma.user.update({ where: { id: userId }, data }); return NextResponse.json({ ok: true, approvalStatus: user.approvalStatus, isActive: user.isActive }); } ``` - [ ] **Step 2: Verify build** ```bash cd /home/lucas/.www/transit && npx tsc --noEmit 2>&1 | head -20 ``` Expected: no errors. - [ ] **Step 3: Commit** ```bash git add app/api/admin/users/[id]/route.ts git commit -m "feat(api): extend admin PATCH to accept user info and plan fields" ``` --- ## Task 4: Create stats API **Files:** - Create: `app/api/admin/users/[id]/stats/route.ts` - [ ] **Step 1: Create the route file** Create `app/api/admin/users/[id]/stats/route.ts`: ```ts import { NextRequest, NextResponse } from "next/server"; import { getServerSession } from "next-auth"; import { authOptions } from "@/app/api/auth/[...nextauth]/route"; import prisma from "@/lib/prisma"; export async function GET(req: NextRequest, { params }: { params: Promise<{ id: string }> }) { const session = await getServerSession(authOptions); if (!session?.user || session.user.role !== "ADMIN") { return NextResponse.json({ error: "Forbidden" }, { status: 403 }); } const { id } = await params; const userId = parseInt(id); if (isNaN(userId)) return NextResponse.json({ error: "Invalid id" }, { status: 400 }); const { searchParams } = new URL(req.url); const period = searchParams.get("period") ?? "thisMonth"; const now = new Date(); let dateFilter: { gte: Date; lt?: Date } | undefined; if (period === "thisMonth") { dateFilter = { gte: new Date(now.getFullYear(), now.getMonth(), 1) }; } else if (period === "lastMonth") { dateFilter = { gte: new Date(now.getFullYear(), now.getMonth() - 1, 1), lt: new Date(now.getFullYear(), now.getMonth(), 1), }; } const dateWhere = dateFilter ? { date: dateFilter } : {}; const base = { userId, ...dateWhere }; const [tripCount, trailerTripCount, income, expense, fuel] = await Promise.all([ prisma.trip.count({ where: base }), prisma.trailerTrip.count({ where: base }), prisma.incomeLog.aggregate({ where: base, _sum: { amount: true } }), prisma.expense.aggregate({ where: base, _sum: { amount: true } }), prisma.fuelLog.aggregate({ where: base, _sum: { totalAmount: true } }), ]); return NextResponse.json({ tripCount, trailerTripCount, totalIncome: income._sum.amount ?? 0, totalExpense: expense._sum.amount ?? 0, totalFuel: fuel._sum.totalAmount ?? 0, }); } ``` - [ ] **Step 2: Verify build** ```bash cd /home/lucas/.www/transit && npx tsc --noEmit 2>&1 | head -20 ``` Expected: no errors. - [ ] **Step 3: Commit** ```bash git add app/api/admin/users/[id]/stats/route.ts git commit -m "feat(api): add admin user stats endpoint with period filtering" ``` --- ## Task 5: Update admin user list (plan badge + detail link) **Files:** - Modify: `app/admin/users/page.tsx` - Modify: `app/admin/users/AdminUsersClient.tsx` - [ ] **Step 1: Add plan fields to the list page select** In `app/admin/users/page.tsx`, add `plan: true, planExpiresAt: true,` to the `select` object: ```ts select: { id: true, email: true, name: true, phone: true, vehicleNumber: true, vehicleType: true, vehicleTonnage: true, profileMemo: true, approvalStatus: true, profileComplete: true, role: true, googleId: true, kakaoId: true, isActive: true, createdAt: true, transportMode: true, transportModeConfirmed: true, bankName: true, accountNumber: true, accountHolder: true, plan: true, planExpiresAt: true, }, ``` - [ ] **Step 2: Add plan fields to the User type in AdminUsersClient.tsx** In the `type User` block at the top of `app/admin/users/AdminUsersClient.tsx`, add: ```ts plan: string; planExpiresAt: Date | null; ``` - [ ] **Step 3: Add plan badge helper and "상세보기" link** After the `STATUS_LABEL` constant, add: ```ts function PlanBadge({ plan, expiresAt }: { plan: string; expiresAt: Date | null }) { if (plan !== 'paid') return null; const expired = expiresAt && new Date(expiresAt) < new Date(); return ( {expired ? '만료' : '유료'} ); } ``` - [ ] **Step 4: Add the badge and detail link to the user row** In the user name row (around line 222 in `AdminUsersClient.tsx`), after the status badge span, add the `` and a link to the detail page. Also add the `Link` import at the top. Add to imports: ```ts import Link from 'next/link'; ``` In the name/badge row, after the `` showing the status badge, add: ```tsx e.stopPropagation()} style={{ fontSize: 11, padding: '2px 8px', borderRadius: 4, fontWeight: 600, background: 'rgba(59,130,246,0.1)', color: 'var(--accent-blue)', textDecoration: 'none', marginLeft: 'auto' }}> 상세보기 ``` - [ ] **Step 5: Verify build** ```bash cd /home/lucas/.www/transit && npx tsc --noEmit 2>&1 | head -20 ``` Expected: no errors. - [ ] **Step 6: Commit** ```bash git add app/admin/users/page.tsx app/admin/users/AdminUsersClient.tsx git commit -m "feat(admin): add plan badge and detail page link to user list" ``` --- ## Task 6: Create detail page server component **Files:** - Create: `app/admin/users/[id]/page.tsx` - [ ] **Step 1: Create the server component** Create `app/admin/users/[id]/page.tsx`: ```tsx import { getServerSession } from "next-auth/next"; import { authOptions } from "@/app/api/auth/[...nextauth]/route"; import { redirect, notFound } from "next/navigation"; import prisma from "@/lib/prisma"; import AdminUserDetailClient from "./AdminUserDetailClient"; export default async function AdminUserDetailPage({ params }: { params: Promise<{ id: string }> }) { const session = await getServerSession(authOptions); if (!session?.user || session.user.role !== "ADMIN") redirect("/login"); const { id } = await params; const userId = parseInt(id); if (isNaN(userId)) notFound(); const user = await prisma.user.findUnique({ where: { id: userId }, select: { id: true, email: true, name: true, phone: true, vehicleNumber: true, vehicleType: true, vehicleTonnage: true, profileMemo: true, approvalStatus: true, profileComplete: true, role: true, googleId: true, kakaoId: true, isActive: true, createdAt: true, transportMode: true, transportModeConfirmed: true, bankName: true, accountNumber: true, accountHolder: true, plan: true, planExpiresAt: true, }, }); if (!user) notFound(); const recentTrips = await prisma.trip.findMany({ where: { userId }, orderBy: { date: "desc" }, take: 10, select: { id: true, date: true, loadingLoc: true, unloadingLoc: true, fee: true, isSettled: true }, }); return ; } ``` - [ ] **Step 2: Verify build** ```bash cd /home/lucas/.www/transit && npx tsc --noEmit 2>&1 | head -20 ``` Expected: no errors. - [ ] **Step 3: Commit** ```bash git add app/admin/users/[id]/page.tsx git commit -m "feat(admin): add user detail page server component" ``` --- ## Task 7: Create AdminUserDetailStats component **Files:** - Create: `app/admin/users/[id]/AdminUserDetailStats.tsx` - [ ] **Step 1: Create the component** Create `app/admin/users/[id]/AdminUserDetailStats.tsx`: ```tsx 'use client'; import { useState, useEffect } from 'react'; type Stats = { tripCount: number; trailerTripCount: number; totalIncome: number; totalExpense: number; totalFuel: number; }; type RecentTrip = { id: number; date: Date; loadingLoc: string; unloadingLoc: string; fee: number; isSettled: boolean; }; type Period = 'thisMonth' | 'lastMonth' | 'all'; const PERIOD_LABELS: Record = { thisMonth: '이번달', lastMonth: '지난달', all: '전체', }; function fmt(n: number) { return n.toLocaleString('ko-KR') + '원'; } export default function AdminUserDetailStats({ userId, recentTrips }: { userId: number; recentTrips: RecentTrip[] }) { const [period, setPeriod] = useState('thisMonth'); const [stats, setStats] = useState(null); const [loading, setLoading] = useState(true); useEffect(() => { setLoading(true); fetch(`/api/admin/users/${userId}/stats?period=${period}`) .then(r => r.json()) .then(data => { setStats(data); setLoading(false); }) .catch(() => setLoading(false)); }, [userId, period]); return ( <> {/* Stats */}

사용량 통계

{(Object.keys(PERIOD_LABELS) as Period[]).map(p => ( ))}
{loading || !stats ? (
{loading ? '불러오는 중...' : '데이터 없음'}
) : (
{[ { label: '운행 횟수', value: `${stats.tripCount + stats.trailerTripCount}회`, sub: `일반 ${stats.tripCount} · 트레일러 ${stats.trailerTripCount}` }, { label: '총 수입', value: fmt(stats.totalIncome), color: 'var(--accent-green)' }, { label: '총 지출', value: fmt(stats.totalExpense), color: 'var(--accent-red)' }, { label: '연료비', value: fmt(stats.totalFuel), color: 'var(--accent-orange)' }, ].map(card => (
{card.label}
{card.value}
{card.sub &&
{card.sub}
}
))}
)}
{/* Recent Trips */}

최근 운행 내역

{recentTrips.length === 0 ? (
운행 내역 없음
) : ( recentTrips.map((trip, i) => (
{new Date(trip.date).toLocaleDateString('ko-KR', { month: 'short', day: 'numeric' })}
{trip.loadingLoc} → {trip.unloadingLoc}
{trip.fee.toLocaleString('ko-KR')}원
{trip.isSettled ? '정산완료' : '미정산'}
)) )}
); } ``` - [ ] **Step 2: Verify build** ```bash cd /home/lucas/.www/transit && npx tsc --noEmit 2>&1 | head -20 ``` Expected: no errors. - [ ] **Step 3: Commit** ```bash git add app/admin/users/[id]/AdminUserDetailStats.tsx git commit -m "feat(admin): add user detail stats and recent trips component" ``` --- ## Task 8: Create AdminUserDetailClient component **Files:** - Create: `app/admin/users/[id]/AdminUserDetailClient.tsx` - [ ] **Step 1: Create the component** Create `app/admin/users/[id]/AdminUserDetailClient.tsx`: ```tsx 'use client'; import { useState } from 'react'; import Link from 'next/link'; import AdminUserDetailStats from './AdminUserDetailStats'; type User = { id: number; email: string; name: string | null; phone: string | null; vehicleNumber: string | null; vehicleType: string | null; vehicleTonnage: string | null; profileMemo: string | null; approvalStatus: string; role: string; googleId: string | null; kakaoId: string | null; isActive: boolean; createdAt: Date; transportMode: string; bankName: string | null; accountNumber: string | null; accountHolder: string | null; plan: string; planExpiresAt: Date | null; }; type RecentTrip = { id: number; date: Date; loadingLoc: string; unloadingLoc: string; fee: number; isSettled: boolean; }; const STATUS = { pending: { label: '대기중', color: 'var(--accent-orange)' }, approved: { label: '승인됨', color: 'var(--accent-green)' }, rejected: { label: '거부됨', color: 'var(--accent-red)' } } as const; const MODES = [{ id: 'general', label: '일반' }, { id: 'trailer', label: '트레일러' }, { id: 'dump', label: '덤프' }]; const INFO_FIELDS = [ { label: '이름', key: 'name' }, { label: '전화번호', key: 'phone' }, { label: '차량번호', key: 'vehicleNumber' }, { label: '차종', key: 'vehicleType' }, { label: '톤수', key: 'vehicleTonnage' }, { label: '은행명', key: 'bankName' }, { label: '계좌번호', key: 'accountNumber' }, { label: '예금주', key: 'accountHolder' }, ] as const; function dateToInput(d: Date | null) { return d ? new Date(d).toISOString().split('T')[0] : ''; } function planLabel(plan: string, exp: Date | null) { if (plan !== 'paid') return { text: '무료', color: 'var(--text-muted)' }; if (!exp) return { text: '유료 (무기한)', color: 'var(--accent-green)' }; if (new Date(exp) < new Date()) return { text: '유료 (만료)', color: 'var(--accent-red)' }; const days = Math.ceil((new Date(exp).getTime() - Date.now()) / 86400000); return { text: `유료 · ${days}일 남음`, color: 'var(--accent-green)' }; } export default function AdminUserDetailClient({ user: init, recentTrips }: { user: User; recentTrips: RecentTrip[] }) { const [user, setUser] = useState(init); const [editing, setEditing] = useState(false); const [form, setForm] = useState({ name: init.name ?? '', phone: init.phone ?? '', vehicleNumber: init.vehicleNumber ?? '', vehicleType: init.vehicleType ?? '', vehicleTonnage: init.vehicleTonnage ?? '', bankName: init.bankName ?? '', accountNumber: init.accountNumber ?? '', accountHolder: init.accountHolder ?? '', profileMemo: init.profileMemo ?? '', transportMode: init.transportMode }); const [planForm, setPlanForm] = useState({ plan: init.plan, expiresAt: dateToInput(init.planExpiresAt) }); const [loading, setLoading] = useState(null); const [delConfirm, setDelConfirm] = useState(false); const [notify, setNotify] = useState<'sending' | 'ok' | 'fail' | null>(null); async function patch(data: Record) { const r = await fetch(`/api/admin/users/${user.id}`, { method: 'PATCH', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(data) }); return r.ok; } async function saveInfo() { setLoading('info'); if (await patch(form)) { setUser(u => ({ ...u, ...form })); setEditing(false); } setLoading(null); } async function savePlan() { setLoading('plan'); const planExpiresAt = planForm.plan === 'paid' && planForm.expiresAt ? new Date(planForm.expiresAt).toISOString() : null; if (await patch({ plan: planForm.plan, planExpiresAt })) { setUser(u => ({ ...u, plan: planForm.plan, planExpiresAt: planExpiresAt ? new Date(planExpiresAt) : null })); } setLoading(null); } async function updateStatus(s: string) { setLoading(s); if (await patch({ approvalStatus: s })) setUser(u => ({ ...u, approvalStatus: s })); setLoading(null); } async function toggleActive() { setLoading('active'); if (await patch({ isActive: !user.isActive })) setUser(u => ({ ...u, isActive: !u.isActive })); setLoading(null); } async function deleteUser() { if (!delConfirm) { setDelConfirm(true); return; } setLoading('del'); const r = await fetch(`/api/admin/users/${user.id}`, { method: 'DELETE' }); if (r.ok) window.location.href = '/admin/users'; else setLoading(null); } async function sendNotify() { setNotify('sending'); try { const r = await fetch(`/api/admin/notify-user/${user.id}`, { method: 'POST' }); const d = await r.json(); setNotify(d.result ?? 'fail'); } catch { setNotify('fail'); } } const busy = loading !== null; const st = STATUS[user.approvalStatus as keyof typeof STATUS]; const pl = planLabel(user.plan, user.planExpiresAt); return (
{/* Header */}
← 목록으로

{user.name || '(미입력)'}

{st && {st.label}} {!user.isActive && 비활성} {user.googleId && Google} {user.kakaoId && Kakao}
{user.approvalStatus === 'pending' && <> } {user.approvalStatus === 'rejected' && } {user.approvalStatus === 'approved' && } {user.kakaoId && }
{/* Basic Info */}

기본 정보

{editing ? (
) : ( )}
{INFO_FIELDS.map(({ label, key }) => (
{label}
{editing ? setForm(f => ({ ...f, [key]: e.target.value }))} style={{ width: '100%', padding: '5px 8px', borderRadius: 6, border: '1px solid var(--border-color)', background: 'var(--bg-input)', color: 'var(--text-primary)', fontSize: 13 }} /> :
{(user as any)[key] || '—'}
}
))}
운송방식
{editing ? (
{MODES.map(m => )}
) :
{user.transportMode || '미설정'}
}
메모
{editing ?