` 灰色小字 | 字段下方描述（如"如需更新请重新输入"可用） | +| `FormMessage` | `
` 红色，自动显示 `error.message` | RHF 错误信息 | + +**用法范式（来自 `components/users/user-form-dialog.tsx` L149-161）**： + +```tsx + ( + + 用户名 + + + + + + )} +/> +``` + +### 本 phase 命名建议（kebab-case） + +仓库 `components/` 下业务子目录的文件**全部使用 kebab-case**： + +``` +components/songs/add-song-dialog.tsx +components/songs/song-detail-dialog.tsx +components/outfits/add-outfit-dialog.tsx +components/outfits/add-print-batch-dialog.tsx +components/users/user-form-dialog.tsx +components/permissions/role-dialog.tsx +components/dances/add-dance-dialog.tsx +components/achievements/add-achievement-dialog.tsx +components/food/add-food-dialog.tsx +``` + +**结论**：本 phase 文件命名 **`components/ai-model/credential-slot-dialog.tsx`（kebab-case）**，导出名 `CredentialSlotDialog`（PascalCase 默认或具名导出，沿用 `user-form-dialog.tsx` 的 `export function UserFormDialog` 写法）。 + +CONTEXT.md L32 写的 `CredentialSlotDialog.tsx` 是 PascalCase 文件名，本研究**强烈建议改为 kebab-case** 以保持仓库一致性。 + +## Architecture Patterns + +### System Architecture Diagram + +``` +┌──────────────────────────────────────────────────────────────────────┐ +│ User clicks "凭据槽位" Button (page.tsx L36-43) │ +└──────────────┬───────────────────────────────────────────────────────┘ + │ onClick → setIsCredentialDialogOpen(true) + ▼ +┌──────────────────────────────────────────────────────────────────────┐ +│ │ +│ ┌──────────────────────────────────────────────────────────────────┐ │ +│ │ useEffect on `open===true` │ │ +│ │ ↓ │ │ +│ │ getCredentialSlot() ◄── Phase 1 落地, lib/api/credential-slot.ts │ │ +│ │ ↓ axios GET /v1/admin/credential-slot/ │ │ +│ │ ↓ 适配 snake_case → camelCase │ │ +│ │ slot: CredentialSlot { appId, accessTokenMasked, updatedAt } │ │ +│ │ ↓ │ │ +│ │ form.reset({ appId: slot.appId, accessToken: '' }) │ │ +│ │ │ │ +│ └──────────────────────────────────────────────────────────────────┘ │ +│ │ +│ User edits → RHF state │ +│ User clicks "保存" → form.handleSubmit(onSubmit) │ +│ ↓ Zod 校验通过（accessToken min(1)） │ +│ ↓ │ +│ updateCredentialSlot({ appId, accessToken }) ◄── Phase 1 落地 │ +│ ↓ axios PUT /v1/admin/credential-slot/ │ +│ ├─ 成功 → toast.success("凭据槽位已更新") + onOpenChange(false) │ +│ └─ 失败 → handleApiError(e) → toast.error(message) │ +│ │ +└──────────────────────────────────────────────────────────────────────┘ + ▲ +┌─────────────────────────────┴────────────────────────────────────────┐ +│ from @/components/ui/sonner ◄─ MUST be mounted in │ +│ app/layout.tsx RootLayout (currently MISSING — gap) │ +└──────────────────────────────────────────────────────────────────────┘ +``` + +### Recommended Project Structure + +``` +components/ +└── ai-model/ # 新建目录（不存在） + └── credential-slot-dialog.tsx # 新建文件，~150 行 +app/ +├── layout.tsx # 修改：挂载 +└── ai-model/ + └── page.tsx # 修改：删 L473-485 占位 Dialog，import 新组件 +docs/ +└── 修改记录.md # 顶部追加 Phase 3 条目 +``` + +### Pattern 1：受控 Dialog + 内部 RHF 状态 + +**What**：Dialog 由 page 持有 `open` / `onOpenChange`，组件内部持有表单状态。 +**When to use**：本 phase 形态（page 级触发 + 子组件管理自身表单）。 +**Example**：见 `components/users/user-form-dialog.tsx` L57-66 props 形态（本 phase 简化为只有 `open` + `onOpenChange`）。 + +```typescript +// Source: components/users/user-form-dialog.tsx L65-67 +export function UserFormDialog({ open, onOpenChange, /* ... */ }) { + const [isSubmitting, setIsSubmitting] = useState(false) + const [dialogOpen, setDialogOpen] = useState(open || false) + // ... +} +``` + +### Pattern 2：`open` 变 true 时拉数据 + reset 表单 + +**What**：useEffect 监听 `open`，open 时 GET → form.reset(预填值)。 +**When to use**：本 phase 必须用（CONTEXT 锁定）。 +**Example**： + +```typescript +// Inspired by user-form-dialog.tsx L83-94 form.reset 模式 +const [slot, setSlot] = useState(null) +const [isLoading, setIsLoading] = useState(false) + +useEffect(() => { + if (!open) return + let cancelled = false + setIsLoading(true) + getCredentialSlot() + .then((data) => { + if (cancelled) return + setSlot(data) + form.reset({ appId: data.appId, accessToken: "" }) + }) + .catch((e) => { + if (cancelled) return + toast.error("加载失败", { description: handleApiError(e) }) + }) + .finally(() => { + if (!cancelled) setIsLoading(false) + }) + return () => { cancelled = true } +}, [open]) +``` + +### Pattern 3：Sonner 命令式 toast + +**What**：直接 `import { toast } from "sonner"` 调 `toast.success(...)` / `toast.error(...)`。 +**Why not `useToast`**：仓库 `hooks/use-toast.ts` 是 Radix Toast 实现，跟 Sonner 互不通信。Sonner 没有 hook 模式（命令式 API）。 +**Example**： + +```typescript +import { toast } from "sonner" + +toast.success("凭据槽位已更新", { description: "配置已生效" }) +toast.error("保存失败", { description: handleApiError(e) }) +``` + +### Anti-Patterns to Avoid + +- **使用 `hooks/use-toast.ts` 的 `useToast()` / `toast()`**：那是 Radix Toast 实现，跟 CONTEXT 锁定的 Sonner 不通信。 +- **从 `@/lib/api` barrel import `handleApiError`**：那是同名重复定义（`lib/api/index.ts:191`），CONTEXT 锁定从 `@/lib/api/error-handler` 引。 +- **PascalCase 文件名**（`CredentialSlotDialog.tsx`）：仓库一致 kebab-case，应为 `credential-slot-dialog.tsx`。 +- **把 `slot.accessTokenMasked` 当 `defaultValues.accessToken`**：会回写脱敏掩码（CONTEXT.md 反复强调），永远默认空串。 +- **关闭对话框时不 reset 表单**：会泄漏上次输入的 access_token 到下次打开。 +- **submit 后不调 `onOpenChange(false)`**：dialog 不会关。 +- **失败时关闭对话框 / 清空表单**：违反 CONTEXT.md "失败时不关闭对话框、不清空表单值"。 + +## Don't Hand-Roll + +| 问题 | Don't Build | Use Instead | Why | +|---------|-------------|-------------|-----| +| 表单受控状态 / 字段联动 / 错误信息显示 | 自己写 useState + 手写校验 | RHF + Zod + shadcn Form wrapper | 现成且仓库已用 | +| 异步校验状态 / submitting 状态 | 自己写 try/finally + setIsSubmitting | RHF `formState.isSubmitting` 或 sibling `isSubmitting` useState（仓库 user-form-dialog 风格） | 模板已成熟 | +| Dialog open/close 动画、ESC、焦点陷阱、portal | 自己写 | shadcn `` (`components/ui/dialog.tsx`) | Radix 完整封装 | +| Label + input 关联（`htmlFor`） | 自己手写 id | `` + ``（自动注入 id） | shadcn Form wrapper 已实现 | +| 错误信息红色显示 | 自己写条件 className | `` | shadcn Form wrapper 已实现 | +| 错误码 → 中文消息映射 | 自己写 switch | `handleApiError(e)` from `lib/api/error-handler.ts` | CONTEXT 锁定 | +| Toast 队列 / 动画 / 主题 | 自己写 | Sonner `toast.success/error/info` | 已在 deps | +| API 调用 / token 注入 / 解包 | 自己写 axios | `getCredentialSlot()` / `updateCredentialSlot()` from `lib/api/credential-slot.ts` | Phase 1 落地 | + +**Key insight**：本 phase 几乎所有模式都已在仓库现成，主要工作是**拼装**而非新造。 + +## Common Pitfalls + +### Pitfall 1：Sonner Toaster 全局未挂载 + +**What goes wrong**：调 `toast.success(...)` 后没有任何视觉反馈，用户以为没保存。 +**Why it happens**：`app/layout.tsx`（20 行）没有渲染任何 Toaster 组件；`components/dashboard-shell.tsx` 也没有；全仓库 grep `` 内追加 ``**： + +```tsx +// app/layout.tsx +import { Toaster } from "@/components/ui/sonner" +// ... + + {children} + + +``` + +**Warning signs**：手动测试 toast 后 console 无 error 但屏幕无任何视觉变化 → Toaster 没挂载。 + +### Pitfall 2：误用 hooks/use-toast.ts（Radix Toast） + +**What goes wrong**：`import { useToast } from '@/hooks/use-toast'` 然后 `const { toast } = useToast(); toast({ title, description })` —— 这是 Radix Toast 实现，跟 Sonner 完全不通信，即使两个 Toaster 都挂载也是各管各的。 +**Why it happens**：`hooks/use-toast.ts` 与 `components/ui/use-toast.ts` 是 **shadcn 默认生成的 Radix Toast 模板**（看 L6-9 import 的是 `@/components/ui/toast`，是 Radix 实现）；`components/ui/sonner.tsx` 是后来添加的 Sonner 包装，但仓库内**没有任何代码用过它**（grep 全仓 `from "@/components/ui/sonner"` 命中 0）。 +**How to avoid**：本 phase 严格 `import { toast } from "sonner"`（直接用 sonner npm 包），同时必须挂载 `` from `@/components/ui/sonner`。 + +### Pitfall 3：把脱敏掩码 `accessTokenMasked` 当 `defaultValues.accessToken` 回写 + +**What goes wrong**：用户没改 access_token，提交时把 `tk_***1234`（带 `*` 的脱敏字符串）当真值发给后端 PUT，后端按全字段覆写**清空真实 access_token**。 +**Why it happens**：直觉上 GET 返回什么就 reset 什么。 +**How to avoid**： +1. CONTEXT.md 已锁定**强制输入** access_token（Zod schema `accessToken: z.string().min(1)`）—— 用户每次都要重输； +2. `form.reset({ appId: slot.appId, accessToken: "" })` —— accessToken 永远默认空串； +3. `placeholder={slot?.accessTokenMasked}` —— 仅做视觉提示。 + +**Warning signs**：grep `defaultValues.*accessTokenMasked` 命中 → 错。grep `defaultValues.*accessToken: ""` 或 `accessToken: ''` → 对。 + +### Pitfall 4：`updated_at` 用 `new Date()` 在服务端渲染时序不一致 + +**What goes wrong**：Next.js App Router 默认在 server 渲染，`new Date(updatedAt).toLocaleString('zh-CN')` 在 server 与 client 时区可能不一致 → React hydration 警告。 +**Why it happens**：但本组件已 `"use client"`，且在 `useEffect` 后才有 slot 数据（mounted 守卫），这个 pitfall **本 phase 不适用**。但 plan-checker 应注意：组件首行必须 `"use client"`（user-form-dialog.tsx L1 是这么做的）。 +**How to avoid**：组件文件首行 `"use client"`；`updatedAt` 渲染时用 `slot && new Date(slot.updatedAt).toLocaleString('zh-CN')`。 + +### Pitfall 5：Dialog 关闭时不 reset 表单导致 access_token 残留 + +**What goes wrong**：用户输了 access_token 但点取消，下次打开 dialog 时 form 仍记着上次输入。 +**Why it happens**：RHF `useForm` 是组件级状态，dialog 即使关闭组件也没卸载（Dialog 用 portal，不卸载子组件）。 +**How to avoid**：参考 `user-form-dialog.tsx` L110-113，在 `handleOpenChange(false)` 时 `form.reset()`。 + +### Pitfall 6：useEffect open=true 拉数据时如果用户快速关再开 → race condition + +**What goes wrong**：第一次 open 触发的 GET 还没回来，用户已关闭再打开 —— 第二次 GET 也发出，两个 promise 竞态。 +**How to avoid**：useEffect cleanup 用 cancelled flag（见 Pattern 2 的 `let cancelled = false; return () => { cancelled = true }`）。 + +## Code Examples + +### 完整组件骨架（基于模板，简化适配本 phase） + +```typescript +// components/ai-model/credential-slot-dialog.tsx +"use client" + +import { useState, useEffect } from "react" +import { useForm } from "react-hook-form" +import { zodResolver } from "@hookform/resolvers/zod" +import * as z from "zod" +import { toast } from "sonner" +import { Loader2 } from "lucide-react" + +import { Button } from "@/components/ui/button" +import { + Dialog, + DialogContent, + DialogDescription, + DialogFooter, + DialogHeader, + DialogTitle, +} from "@/components/ui/dialog" +import { + Form, + FormControl, + FormDescription, + FormField, + FormItem, + FormLabel, + FormMessage, +} from "@/components/ui/form" +import { Input } from "@/components/ui/input" +import { + getCredentialSlot, + updateCredentialSlot, + type CredentialSlot, +} from "@/lib/api/credential-slot" +import { handleApiError } from "@/lib/api/error-handler" + +const formSchema = z.object({ + appId: z.string().min(1, { message: "App ID 不能为空" }), + accessToken: z.string().min(1, { message: "请输入 Access Token" }), +}) + +type FormValues = z.infer + +interface CredentialSlotDialogProps { + open: boolean + onOpenChange: (open: boolean) => void +} + +export function CredentialSlotDialog({ open, onOpenChange }: CredentialSlotDialogProps) { + const [slot, setSlot] = useState(null) + const [isLoading, setIsLoading] = useState(false) + const [isSubmitting, setIsSubmitting] = useState(false) + + const form = useForm({ + resolver: zodResolver(formSchema), + defaultValues: { appId: "", accessToken: "" }, + }) + + useEffect(() => { + if (!open) return + let cancelled = false + setIsLoading(true) + getCredentialSlot() + .then((data) => { + if (cancelled) return + setSlot(data) + form.reset({ appId: data.appId, accessToken: "" }) + }) + .catch((e) => { + if (cancelled) return + toast.error("加载失败", { description: handleApiError(e) }) + }) + .finally(() => { + if (!cancelled) setIsLoading(false) + }) + return () => { + cancelled = true + } + }, [open, form]) + + const handleOpenChange = (next: boolean) => { + onOpenChange(next) + if (!next) { + form.reset({ appId: "", accessToken: "" }) + setSlot(null) + } + } + + const handleSubmit = async (values: FormValues) => { + setIsSubmitting(true) + try { + await updateCredentialSlot({ + appId: values.appId, + accessToken: values.accessToken, + }) + toast.success("凭据槽位已更新", { description: "配置已生效" }) + handleOpenChange(false) + } catch (e) { + toast.error("保存失败", { description: handleApiError(e) }) + // 失败时不关闭对话框、不清空表单值 + } finally { + setIsSubmitting(false) + } + } + + return ( + + + + 通用凭据槽位 + + 管理 APP ID 与 Access Token；提交将全字段覆写后端记录。 + + + {isLoading ? ( + + + + ) : ( + + + ( + + APP ID + + + + + + )} + /> + ( + + Access Token + + + + + 每次保存都需要重新输入 Access Token（不会显示原值，避免回写脱敏掩码） + + + + )} + /> + {slot && ( + + 最后更新：{new Date(slot.updatedAt).toLocaleString("zh-CN")} + + )} + + handleOpenChange(false)} + disabled={isSubmitting} + > + 取消 + + + {isSubmitting ? ( + <> + + 保存中... + + ) : ( + "保存" + )} + + + +
+ 最后更新：{new Date(slot.updatedAt).toLocaleString("zh-CN")} +