docs(phase-3): 调研 Phase 3 编辑对话框 + 提交反馈
This commit is contained in:
parent
814f49372b
commit
c21a16af5c
845
qy-lty-admin/.planning/phases/03-dialog-feedback/03-RESEARCH.md
Normal file
845
qy-lty-admin/.planning/phases/03-dialog-feedback/03-RESEARCH.md
Normal file
@ -0,0 +1,845 @@
|
|||||||
|
# Phase 3：编辑对话框 + 提交反馈 - Research
|
||||||
|
|
||||||
|
**调研日期**：2026-05-08
|
||||||
|
**Domain**：Next.js 15 (App Router) + React 19 + RHF + Zod + shadcn UI + Sonner（凭据槽位编辑对话框）
|
||||||
|
**Confidence**：HIGH（全部基于本仓库已落地代码 grep + read，无需外部文档查证）
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
本 phase 抽离独立组件 `components/ai-model/credential-slot-dialog.tsx`，把 Phase 2 落地的占位 Dialog（`app/ai-model/page.tsx` L473-485）替换为完整功能的编辑对话框：基于 React Hook Form + Zod 表单、调 `getCredentialSlot()` 预填、提交走 `updateCredentialSlot()`、成功/失败用 toast 反馈、错误经 `handleApiError` 映射。
|
||||||
|
|
||||||
|
**所有依赖均已在 deps 中**（`react-hook-form`、`@hookform/resolvers`、`zod`、`sonner`、`lucide-react`、shadcn UI 组件），**不需要新增任何依赖**。
|
||||||
|
|
||||||
|
仓库内已有两个高质量 RHF + Zod 1:1 模板可直接对照：`components/users/user-form-dialog.tsx`（更贴近本 phase 的 single-dialog + 表单 + submit pattern）与 `components/permissions/role-dialog.tsx`（更复杂，含动态字段，本 phase 用不到）。**首选模板：`components/users/user-form-dialog.tsx`**。
|
||||||
|
|
||||||
|
**Primary recommendation**：以 `components/users/user-form-dialog.tsx` 为蓝本，改造成 `components/ai-model/credential-slot-dialog.tsx`（kebab-case 命名，与 `add-outfit-dialog.tsx` / `add-song-dialog.tsx` / `user-form-dialog.tsx` / `role-dialog.tsx` 保持一致），表单两个字段 `appId` + `accessToken`，access_token **强制输入**（CONTEXT.md 锁定），提交走 `updateCredentialSlot({ appId, accessToken })`。
|
||||||
|
|
||||||
|
⚠️ **预警 1（必须告知 planner）**：仓库内全局**未挂载** `<Toaster />` 或 `<Sonner Toaster />` —— `app/layout.tsx` 仅 20 行裸结构，没有 Toaster 渲染；`components/dashboard-shell.tsx` 也没有。这意味着任何 `toast()` 调用**当前都会静默 no-op**（实测过 `add-dance-dialog.tsx` 等已有 `toast(...)` 调用也属于死代码）。Phase 3 必须**在 plan 中纳入"挂载 Sonner Toaster 到 `app/layout.tsx`"作为前置任务**，否则 toast 反馈完全不可见。
|
||||||
|
|
||||||
|
⚠️ **预警 2**：仓库内有**两个 `handleApiError` 函数**（`lib/api/error-handler.ts:38` 与 `lib/api/index.ts:191`），签名与行为相同（都是 `(error: unknown) => string`，先看 `error instanceof Error` 取 `.message`，否则返回中文兜底）。CONTEXT.md 锁定从 `lib/api/error-handler.ts` 引入（`import { handleApiError } from '@/lib/api/error-handler'`），不要从 barrel `@/lib/api` 引（barrel 里那个是同名重复定义，存在 namespace 歧义风险）。
|
||||||
|
|
||||||
|
⚠️ **预警 3**：仓库 `hooks/use-toast.ts` 与 `components/ui/use-toast.ts` 是**两份完全相同的 Radix Toast 实现**（不是 Sonner）—— 即使挂载了 `<Toaster />`（Radix 版本），也跟 Sonner 互不通信。CONTEXT.md 锁定 Sonner 反馈，意味着 plan 必须：(a) 挂载 `<Toaster />`（来自 `@/components/ui/sonner`），(b) 在 dialog 内 `import { toast } from "sonner"`（直接用 sonner 包导出的 `toast()`，**不**用 `useToast` hook —— Sonner 没有 hook 模式，是命令式 API）。
|
||||||
|
|
||||||
|
<user_constraints>
|
||||||
|
## User Constraints (from CONTEXT.md)
|
||||||
|
|
||||||
|
### Locked Decisions
|
||||||
|
|
||||||
|
**组件抽离**：
|
||||||
|
- **新建**：`components/ai-model/CredentialSlotDialog.tsx`（命名待定，见 Discretion）
|
||||||
|
- `components/ai-model/` 目录**确认不存在**，需要 mkdir
|
||||||
|
- **修改**：`app/ai-model/page.tsx`
|
||||||
|
- 删除 Phase 2 落地的占位 Dialog（确认在 L473-485）
|
||||||
|
- 用 `<CredentialSlotDialog open={isCredentialDialogOpen} onOpenChange={setIsCredentialDialogOpen} />` 替换
|
||||||
|
- 保留 Button 入口（L36-43）+ mounted 守卫（L20、L23-25）
|
||||||
|
|
||||||
|
**Dialog 接口**：
|
||||||
|
```typescript
|
||||||
|
interface CredentialSlotDialogProps {
|
||||||
|
open: boolean
|
||||||
|
onOpenChange: (open: boolean) => void
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**表单技术栈**：React Hook Form + Zod，`@hookform/resolvers/zod`（已在 deps）。
|
||||||
|
|
||||||
|
**预填态**：
|
||||||
|
- `useEffect(() => { if (open) loadData() }, [open])` 调 `getCredentialSlot()`
|
||||||
|
- `appId` field 默认值 = `slot.appId`（明文）
|
||||||
|
- `accessToken` field 默认值 = `''`（**不是** masked！）
|
||||||
|
- input placeholder = `slot.accessTokenMasked`
|
||||||
|
- 提示文字"如需更新请重新输入"
|
||||||
|
- `updated_at` 只读显示
|
||||||
|
|
||||||
|
**提交逻辑（CONTEXT 最终决策）**：
|
||||||
|
- access_token **强制输入**：`z.string().min(1, '请输入 Access Token')`
|
||||||
|
- 退化为"每次保存都要重输 access_token"，UX 略差但语义正确（不会回写脱敏掩码）
|
||||||
|
- `docs/修改记录.md` Phase 3 条目「修改原因」段必须**显式说明**这个权衡 + 候选下一步是给后端加"识别脱敏掩码保留旧值"逻辑
|
||||||
|
|
||||||
|
**Toast 通知**：
|
||||||
|
- Sonner（不要用 Radix Toast / hooks/use-toast）
|
||||||
|
- 成功：title "凭据槽位已更新" / 描述 "配置已生效"
|
||||||
|
- 失败：title "保存失败" / description = `handleApiError(e)` / variant "destructive"
|
||||||
|
|
||||||
|
**错误处理**：
|
||||||
|
- 复用 `lib/api/error-handler.ts:handleApiError`
|
||||||
|
- 失败时**不**关闭对话框、**不**清空表单值
|
||||||
|
|
||||||
|
### Claude's Discretion
|
||||||
|
|
||||||
|
- 文件命名 `CredentialSlotDialog.tsx`（PascalCase）vs `credential-slot-dialog.tsx`（kebab-case）—— researcher 看现有约定决定
|
||||||
|
- Cancel 按钮文案："取消" / "关闭"
|
||||||
|
- 提交按钮 loading 态文案："保存中..." / "处理中..." / "提交中..."
|
||||||
|
- 是否给 access_token input 加 `type="password"` —— CONTEXT 推荐**不**加
|
||||||
|
- "最后更新"时间格式：`new Date(updatedAt).toLocaleString('zh-CN')` 或 `date-fns`
|
||||||
|
|
||||||
|
### Deferred Ideas (OUT OF SCOPE)
|
||||||
|
|
||||||
|
- "留空保留旧值"语义 —— 需要后端识别脱敏掩码格式，给后端开新 phase / patch milestone
|
||||||
|
- 端到端浏览器测试（无 E2E 框架）
|
||||||
|
- token 轮换 / refresh token / DB at-rest 加密 / Vitest 体系 / ESLint bootstrap
|
||||||
|
|
||||||
|
</user_constraints>
|
||||||
|
|
||||||
|
<phase_requirements>
|
||||||
|
## Phase Requirements
|
||||||
|
|
||||||
|
| ID | Description | Research Support |
|
||||||
|
|----|-------------|------------------|
|
||||||
|
| CRED-FE-04 | 编辑对话框组件 `components/ai-model/CredentialSlotDialog.tsx`：基于 `components/ui/dialog.tsx`；表单 React Hook Form + Zod 校验；预填态显示后端返回的 app_id 明文 + access_token 末 4 位掩码 + 不可改的 updated_at；提交触发 `updateCredentialSlot()` | ✅ 1:1 模板 `components/users/user-form-dialog.tsx` 直接复用；shadcn Form wrapper `components/ui/form.tsx` 已存在；Phase 1 落地的 `getCredentialSlot()` / `updateCredentialSlot()` API 已就绪（`lib/api/credential-slot.ts`）；Phase 2 落地的页面入口 + mounted 守卫已就绪（`app/ai-model/page.tsx`） |
|
||||||
|
| CRED-FE-05 | 提交反馈：成功调 `useToast()` 弹 Sonner toast 自动关闭 + 重新 GET；失败走 `lib/api/error-handler.ts` 统一映射并 toast 提示 | ⚠️ Sonner Toaster 全局未挂载（gap，必须修复）；`handleApiError(error: unknown): string` 签名已确认；CONTEXT 锁定不重新 GET 而由打开 Dialog 时的 useEffect 自动 loadData（关闭再开自然刷新） |
|
||||||
|
|
||||||
|
</phase_requirements>
|
||||||
|
|
||||||
|
## Architectural Responsibility Map
|
||||||
|
|
||||||
|
| Capability | Primary Tier | Secondary Tier | Rationale |
|
||||||
|
|------------|-------------|----------------|-----------|
|
||||||
|
| 表单状态 + 校验 | Browser / Client (RHF + Zod) | — | 标准 RHF 受控表单，纯客户端 |
|
||||||
|
| 预填数据 GET | Browser / Client (axios) | API / Backend (Phase 2 后端 v1.0) | `apiClient.get` via Phase 1 落地的 `getCredentialSlot()` |
|
||||||
|
| 提交 PUT | Browser / Client (axios) | API / Backend (Phase 2 后端 v1.0) | `apiClient.put` via Phase 1 落地的 `updateCredentialSlot()` |
|
||||||
|
| Toast 反馈 | Browser / Client (Sonner) | — | Sonner 是纯客户端 portal，挂在 layout.tsx 的 RootLayout |
|
||||||
|
| 错误映射 | Browser / Client | — | `handleApiError` 是同步纯函数，无 IO |
|
||||||
|
| RBAC 入口可见性 | Browser / Client | — | Phase 2 已落地（`hasPermission('credential-slot')`） |
|
||||||
|
|
||||||
|
## Standard Stack
|
||||||
|
|
||||||
|
### Core（已全部在 deps，**不引入新依赖**）
|
||||||
|
|
||||||
|
| 库 | 版本（package.json） | 用途 | Why Standard |
|
||||||
|
|---------|---------|---------|--------------|
|
||||||
|
| react-hook-form | `latest` | 表单状态管理 | 仓库现有 `users/user-form-dialog.tsx` + `permissions/role-dialog.tsx` 已用 [VERIFIED: `package.json:56`] |
|
||||||
|
| @hookform/resolvers | `latest` | RHF + Zod 桥接（`zodResolver`） | 同上 [VERIFIED: `package.json:12`] |
|
||||||
|
| zod | `latest` | schema 校验 | 同上 [VERIFIED: `package.json:63`] |
|
||||||
|
| sonner | `^1.7.1` | Toast 通知 | CONTEXT 锁定 [VERIFIED: `package.json:59`] |
|
||||||
|
| lucide-react | `^0.454.0` | 图标 | `Loader2` for loading 态、`KeyRound` 已在 page.tsx import [VERIFIED: `package.json:50`] |
|
||||||
|
| @radix-ui/react-dialog | `^1.1.4` | Dialog 底层 | shadcn `components/ui/dialog.tsx` 已封装 [VERIFIED: `package.json:20`] |
|
||||||
|
|
||||||
|
### Supporting（shadcn UI 组件，全部已存在）
|
||||||
|
|
||||||
|
| 文件 | 是否存在 | 用途 |
|
||||||
|
|---------|---------|---------|
|
||||||
|
| `components/ui/dialog.tsx` | ✅ | Dialog / DialogContent / DialogHeader / DialogTitle / DialogDescription / DialogFooter |
|
||||||
|
| `components/ui/form.tsx` | ✅ | shadcn Form wrapper（Form / FormField / FormItem / FormLabel / FormControl / FormMessage / FormDescription）—— 详见下文 |
|
||||||
|
| `components/ui/input.tsx` | ✅ | Input（forwardRef，受控） |
|
||||||
|
| `components/ui/label.tsx` | ✅ | Label（基于 Radix `LabelPrimitive.Root`） |
|
||||||
|
| `components/ui/button.tsx` | ✅ | Button |
|
||||||
|
| `components/ui/sonner.tsx` | ✅ | Sonner `<Toaster />` 包装（**未在 layout 中挂载，gap**） |
|
||||||
|
|
||||||
|
### Alternatives Considered（CONTEXT 已锁定决策，仅供 plan-checker 验证）
|
||||||
|
|
||||||
|
| Instead of | Could Use | Why we don't |
|
||||||
|
|------------|-----------|----------|
|
||||||
|
| Sonner toast | `hooks/use-toast.ts`（Radix Toast） | CONTEXT 锁定 Sonner，且 Radix `<Toaster />` 同样未挂载，无优势 |
|
||||||
|
| 受控 useState（如 `add-song-dialog.tsx` / `add-outfit-dialog.tsx` 风格） | RHF + Zod | CONTEXT 锁定 RHF + Zod；现有 `user-form-dialog.tsx` / `role-dialog.tsx` 已是该风格的 in-house 模板 |
|
||||||
|
| barrel 路径 `@/lib/api` 的 `handleApiError` | `lib/api/error-handler.ts` 的版本 | CONTEXT 锁定后者；二者实现相同但显式路径避免歧义 |
|
||||||
|
|
||||||
|
**安装**：`npm install` —— 无新增依赖。
|
||||||
|
|
||||||
|
## RHF + Zod 1:1 模板（关键发现）
|
||||||
|
|
||||||
|
### 现有 RHF + Zod 用法 grep 全仓结果
|
||||||
|
|
||||||
|
仅 **2 个文件** 同时含 `useForm` + `zodResolver` + `zod`（grep `useForm.*zodResolver` head_limit：
|
||||||
|
|
||||||
|
1. **`components/users/user-form-dialog.tsx`**（289 行）—— **首选 1:1 模板**
|
||||||
|
2. **`components/permissions/role-dialog.tsx`**（425 行）—— 含动态字段，过于复杂，参考即可
|
||||||
|
|
||||||
|
### 首选模板形态：`components/users/user-form-dialog.tsx`
|
||||||
|
|
||||||
|
**关键代码区段（直接复用）**：
|
||||||
|
|
||||||
|
| 段落 | 行号 | 用途 |
|
||||||
|
|------|------|------|
|
||||||
|
| 顶部 import 块（含 `useForm` / `zodResolver` / `* as z` / `Form`...`FormMessage` / `Loader2`） | L1-22 | 复用 import 清单 |
|
||||||
|
| Zod schema 定义 | L25-45 | 改写成 `appId` + `accessToken` 两字段 |
|
||||||
|
| Component props 类型 | L47-55 | 改写成 `{ open, onOpenChange }` |
|
||||||
|
| `useForm` 初始化 | L69-80 | `resolver: zodResolver(...)`、`defaultValues` |
|
||||||
|
| `defaultValues` 改变时 `form.reset()` | L83-94 | 本 phase 不需要外部 defaultValues，但需要 GET 后 reset，**模式相同**（用 useEffect + form.reset） |
|
||||||
|
| `handleOpenChange` + `form.reset()` | L103-113 | 关闭时清表单 |
|
||||||
|
| `handleSubmit` 异步 + setIsSubmitting | L115-125 | 复用 try/finally 形态 |
|
||||||
|
| Form / FormField / FormItem / FormLabel / FormControl / Input / FormMessage 嵌套 | L146-176 | 1:1 复用模式 |
|
||||||
|
| DialogFooter + 提交按钮 + Loader2 spinner | L264-282 | 复用 |
|
||||||
|
|
||||||
|
**模板核心结构（精简后用于 plan 引用）**：
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// from components/users/user-form-dialog.tsx L20-22, 69-80, 146-176
|
||||||
|
import { useForm } from "react-hook-form"
|
||||||
|
import { zodResolver } from "@hookform/resolvers/zod"
|
||||||
|
import * as z from "zod"
|
||||||
|
|
||||||
|
const formSchema = z.object({
|
||||||
|
appId: z.string().min(1, { message: "App ID 不能为空" }),
|
||||||
|
accessToken: z.string().min(1, { message: "请输入 Access Token" }),
|
||||||
|
})
|
||||||
|
|
||||||
|
const form = useForm<z.infer<typeof formSchema>>({
|
||||||
|
resolver: zodResolver(formSchema),
|
||||||
|
defaultValues: { appId: "", accessToken: "" },
|
||||||
|
})
|
||||||
|
|
||||||
|
// 在 GET 完成后：
|
||||||
|
form.reset({ appId: slot.appId, accessToken: "" })
|
||||||
|
|
||||||
|
// JSX：
|
||||||
|
<Form {...form}>
|
||||||
|
<form onSubmit={form.handleSubmit(handleSubmit)} className="space-y-4 py-4">
|
||||||
|
<FormField
|
||||||
|
control={form.control}
|
||||||
|
name="appId"
|
||||||
|
render={({ field }) => (
|
||||||
|
<FormItem>
|
||||||
|
<FormLabel>App ID</FormLabel>
|
||||||
|
<FormControl>
|
||||||
|
<Input placeholder="输入 App ID" {...field} />
|
||||||
|
</FormControl>
|
||||||
|
<FormMessage />
|
||||||
|
</FormItem>
|
||||||
|
)}
|
||||||
|
/>
|
||||||
|
{/* ...accessToken field with placeholder={slot?.accessTokenMasked} */}
|
||||||
|
</form>
|
||||||
|
</Form>
|
||||||
|
```
|
||||||
|
|
||||||
|
### shadcn Form wrapper 用法（`components/ui/form.tsx` 已存在，179 行）
|
||||||
|
|
||||||
|
**Exported API**（L169-178）：
|
||||||
|
|
||||||
|
| 名称 | 来源 | 用途 |
|
||||||
|
|------|------|------|
|
||||||
|
| `Form` | re-export of `FormProvider` from `react-hook-form` | 包在 `<form>` 外层，传 `{...form}` |
|
||||||
|
| `FormField` | 包装 RHF `Controller` + 注入 `FormFieldContext` | 等价于 `<Controller name=... control=... render=...>` |
|
||||||
|
| `FormItem` | div + `FormItemContext`（生成唯一 id） | 字段 wrapper（`space-y-2`） |
|
||||||
|
| `FormLabel` | 基于 `<Label>` + 自动 `htmlFor={formItemId}` + error 红色 | 字段 label |
|
||||||
|
| `FormControl` | Radix `Slot` + 自动注入 `id` / `aria-describedby` / `aria-invalid` | 包在 `<Input />` 外层 |
|
||||||
|
| `FormDescription` | `<p>` 灰色小字 | 字段下方描述（如"如需更新请重新输入"可用） |
|
||||||
|
| `FormMessage` | `<p>` 红色，自动显示 `error.message` | RHF 错误信息 |
|
||||||
|
|
||||||
|
**用法范式（来自 `components/users/user-form-dialog.tsx` L149-161）**：
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<FormField
|
||||||
|
control={form.control}
|
||||||
|
name="name"
|
||||||
|
render={({ field }) => (
|
||||||
|
<FormItem>
|
||||||
|
<FormLabel>用户名</FormLabel>
|
||||||
|
<FormControl>
|
||||||
|
<Input placeholder="输入用户名" {...field} />
|
||||||
|
</FormControl>
|
||||||
|
<FormMessage />
|
||||||
|
</FormItem>
|
||||||
|
)}
|
||||||
|
/>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 本 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)
|
||||||
|
▼
|
||||||
|
┌──────────────────────────────────────────────────────────────────────┐
|
||||||
|
│ <CredentialSlotDialog open onOpenChange /> │
|
||||||
|
│ ┌──────────────────────────────────────────────────────────────────┐ │
|
||||||
|
│ │ 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: '' }) │ │
|
||||||
|
│ │ <Input placeholder={slot.accessTokenMasked} /> │ │
|
||||||
|
│ └──────────────────────────────────────────────────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
│ 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) │
|
||||||
|
│ │
|
||||||
|
└──────────────────────────────────────────────────────────────────────┘
|
||||||
|
▲
|
||||||
|
┌─────────────────────────────┴────────────────────────────────────────┐
|
||||||
|
│ <Toaster /> 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 # 修改：挂载 <Toaster />
|
||||||
|
└── 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<CredentialSlot | null>(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 `<Dialog>` (`components/ui/dialog.tsx`) | Radix 完整封装 |
|
||||||
|
| Label + input 关联（`htmlFor`） | 自己手写 id | `<FormLabel>` + `<FormControl>`（自动注入 id） | shadcn Form wrapper 已实现 |
|
||||||
|
| 错误信息红色显示 | 自己写条件 className | `<FormMessage />` | 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 `<Toaster|<Sonner` 仅命中 `components/ui/sonner.tsx` 自身定义，无任何调用方。
|
||||||
|
**How to avoid**：plan 必须包含一个 task：**在 `app/layout.tsx` `<body>` 内追加 `<Toaster />`**：
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// app/layout.tsx
|
||||||
|
import { Toaster } from "@/components/ui/sonner"
|
||||||
|
// ...
|
||||||
|
<body>
|
||||||
|
{children}
|
||||||
|
<Toaster />
|
||||||
|
</body>
|
||||||
|
```
|
||||||
|
|
||||||
|
**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 包），同时必须挂载 `<Toaster />` 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<typeof formSchema>
|
||||||
|
|
||||||
|
interface CredentialSlotDialogProps {
|
||||||
|
open: boolean
|
||||||
|
onOpenChange: (open: boolean) => void
|
||||||
|
}
|
||||||
|
|
||||||
|
export function CredentialSlotDialog({ open, onOpenChange }: CredentialSlotDialogProps) {
|
||||||
|
const [slot, setSlot] = useState<CredentialSlot | null>(null)
|
||||||
|
const [isLoading, setIsLoading] = useState(false)
|
||||||
|
const [isSubmitting, setIsSubmitting] = useState(false)
|
||||||
|
|
||||||
|
const form = useForm<FormValues>({
|
||||||
|
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 (
|
||||||
|
<Dialog open={open} onOpenChange={handleOpenChange}>
|
||||||
|
<DialogContent className="sm:max-w-[500px]">
|
||||||
|
<DialogHeader>
|
||||||
|
<DialogTitle>通用凭据槽位</DialogTitle>
|
||||||
|
<DialogDescription>
|
||||||
|
管理 APP ID 与 Access Token；提交将全字段覆写后端记录。
|
||||||
|
</DialogDescription>
|
||||||
|
</DialogHeader>
|
||||||
|
{isLoading ? (
|
||||||
|
<div className="flex items-center justify-center py-8">
|
||||||
|
<Loader2 className="h-6 w-6 animate-spin text-muted-foreground" />
|
||||||
|
</div>
|
||||||
|
) : (
|
||||||
|
<Form {...form}>
|
||||||
|
<form onSubmit={form.handleSubmit(handleSubmit)} className="space-y-4 py-2">
|
||||||
|
<FormField
|
||||||
|
control={form.control}
|
||||||
|
name="appId"
|
||||||
|
render={({ field }) => (
|
||||||
|
<FormItem>
|
||||||
|
<FormLabel>APP ID</FormLabel>
|
||||||
|
<FormControl>
|
||||||
|
<Input placeholder="输入 APP ID" {...field} />
|
||||||
|
</FormControl>
|
||||||
|
<FormMessage />
|
||||||
|
</FormItem>
|
||||||
|
)}
|
||||||
|
/>
|
||||||
|
<FormField
|
||||||
|
control={form.control}
|
||||||
|
name="accessToken"
|
||||||
|
render={({ field }) => (
|
||||||
|
<FormItem>
|
||||||
|
<FormLabel>Access Token</FormLabel>
|
||||||
|
<FormControl>
|
||||||
|
<Input
|
||||||
|
placeholder={slot?.accessTokenMasked ?? "输入 Access Token"}
|
||||||
|
{...field}
|
||||||
|
/>
|
||||||
|
</FormControl>
|
||||||
|
<FormDescription>
|
||||||
|
每次保存都需要重新输入 Access Token（不会显示原值，避免回写脱敏掩码）
|
||||||
|
</FormDescription>
|
||||||
|
<FormMessage />
|
||||||
|
</FormItem>
|
||||||
|
)}
|
||||||
|
/>
|
||||||
|
{slot && (
|
||||||
|
<p className="text-sm text-muted-foreground">
|
||||||
|
最后更新：{new Date(slot.updatedAt).toLocaleString("zh-CN")}
|
||||||
|
</p>
|
||||||
|
)}
|
||||||
|
<DialogFooter>
|
||||||
|
<Button
|
||||||
|
type="button"
|
||||||
|
variant="outline"
|
||||||
|
onClick={() => handleOpenChange(false)}
|
||||||
|
disabled={isSubmitting}
|
||||||
|
>
|
||||||
|
取消
|
||||||
|
</Button>
|
||||||
|
<Button type="submit" disabled={isSubmitting}>
|
||||||
|
{isSubmitting ? (
|
||||||
|
<>
|
||||||
|
<Loader2 className="mr-2 h-4 w-4 animate-spin" />
|
||||||
|
保存中...
|
||||||
|
</>
|
||||||
|
) : (
|
||||||
|
"保存"
|
||||||
|
)}
|
||||||
|
</Button>
|
||||||
|
</DialogFooter>
|
||||||
|
</form>
|
||||||
|
</Form>
|
||||||
|
)}
|
||||||
|
</DialogContent>
|
||||||
|
</Dialog>
|
||||||
|
)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### `app/ai-model/page.tsx` 改动定位
|
||||||
|
|
||||||
|
**Phase 2 占位 Dialog 当前位置**：
|
||||||
|
|
||||||
|
| 项 | 行号 | 内容 |
|
||||||
|
|----|------|------|
|
||||||
|
| 占位 Dialog 起始 | L473 | `<Dialog open={isCredentialDialogOpen} onOpenChange={setIsCredentialDialogOpen}>` |
|
||||||
|
| `DialogContent` | L477 | |
|
||||||
|
| `DialogTitle` | L479 | `通用凭据槽位` |
|
||||||
|
| `DialogDescription` | L480-482 | `对话框真实内容由 Phase 3 落地` |
|
||||||
|
| 占位 Dialog 结束 | L485 | `</Dialog>` |
|
||||||
|
|
||||||
|
**改动 1**：删除 L473-485（13 行）。
|
||||||
|
**改动 2**：替换为 `<CredentialSlotDialog open={isCredentialDialogOpen} onOpenChange={setIsCredentialDialogOpen} />`。
|
||||||
|
**改动 3**：删除 L9-15 的 Dialog 命名导入（`Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle`）—— 不再使用。
|
||||||
|
**改动 4**：在 import 块（L1-17 区域）新增：
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { CredentialSlotDialog } from "@/components/ai-model/credential-slot-dialog"
|
||||||
|
```
|
||||||
|
|
||||||
|
**保留**：
|
||||||
|
- L1 `"use client"` —— 不动
|
||||||
|
- L20 `useState/useEffect` —— 不动（mounted state 仍需要）
|
||||||
|
- L21 `isCredentialDialogOpen` state —— 不动
|
||||||
|
- L23-25 mounted useEffect —— 不动
|
||||||
|
- L16 `KeyRound` 已在 lucide-react import —— 仍在用（Button 图标），不动
|
||||||
|
- L35-43 凭据槽位 Button —— 不动
|
||||||
|
|
||||||
|
**Loader2 import**：是否需要 page.tsx 加？
|
||||||
|
答：**不需要**。Loader2 仅在新组件 `credential-slot-dialog.tsx` 内使用，page.tsx 不会用到。
|
||||||
|
|
||||||
|
## State of the Art
|
||||||
|
|
||||||
|
| Old Approach | Current Approach | When Changed | Impact |
|
||||||
|
|--------------|------------------|--------------|--------|
|
||||||
|
| 仓库内 useState + 手写校验（`add-song-dialog.tsx` / `add-outfit-dialog.tsx`） | RHF + Zod + shadcn Form wrapper（`user-form-dialog.tsx` / `role-dialog.tsx`） | 仓库内并存（前者更早，后者后期） | 本 phase 用后者（CONTEXT 锁定） |
|
||||||
|
| Radix Toast (`hooks/use-toast.ts`) | Sonner（`components/ui/sonner.tsx`） | 仓库内并存（Sonner 后加但未使用） | 本 phase 用 Sonner（CONTEXT 锁定） + 必须先挂载 `<Toaster />` |
|
||||||
|
|
||||||
|
**Deprecated/outdated**：
|
||||||
|
- `hooks/use-toast.ts` + `components/ui/use-toast.ts`：两份完全相同的 Radix Toast 实现（295 行 dead code，本 phase 不动它们但应该在未来 milestone 收敛）。
|
||||||
|
- `components/ui/toaster.tsx`：Radix Toast 渲染容器，**也未挂载**，全仓 grep `<Toaster` 命中 0。
|
||||||
|
- `lib/api/index.ts:191` 的 `handleApiError`：与 `lib/api/error-handler.ts:38` 重复定义，未来应收敛。
|
||||||
|
|
||||||
|
## Runtime State Inventory
|
||||||
|
|
||||||
|
> 本 phase 是新建组件 + 修改一行 import，**非** rename / refactor / migration。Skip 该 section 大部分内容。
|
||||||
|
|
||||||
|
| Category | Items Found | Action Required |
|
||||||
|
|----------|-------------|------------------|
|
||||||
|
| Stored data | None — 凭据槽位本身的存储是后端 Phase 1 已落地的 DB 单行，前端不持久化任何东西 | None |
|
||||||
|
| Live service config | None | None |
|
||||||
|
| OS-registered state | None | None |
|
||||||
|
| Secrets/env vars | `NEXT_PUBLIC_API_BASE_URL` 仍是凭据 API 的 base URL，本 phase 不改 | None |
|
||||||
|
| Build artifacts | None — 新增组件文件 + 修改 page.tsx，TS 编译产物会自动更新 | `npx tsc --noEmit` 验证 |
|
||||||
|
|
||||||
|
## Project Constraints (from CLAUDE.md)
|
||||||
|
|
||||||
|
| Constraint | Source | Apply to Phase 3 |
|
||||||
|
|-----------|--------|--------|
|
||||||
|
| 中文沟通 / 注释 / commit message / 最终回答 | `CLAUDE.md L98` | 表单文案、toast 文案、注释、commit message 全部中文（已锁定） |
|
||||||
|
| 不混用包管理器（package-lock.json + pnpm-lock.yaml + yarn.lock 并存） | `CLAUDE.md L99` | 不动 lockfile；不引入新依赖 |
|
||||||
|
| shadcn 组件可直接修改源码 | `CLAUDE.md L100` | 本 phase 不需要修改 shadcn 组件（form / dialog / input 都已成熟） |
|
||||||
|
| 修改后**必须**在同一会话追加 `docs/修改记录.md` 顶部 | `CLAUDE.md L72-82` | plan 必须包含"在 docs/修改记录.md 顶部追加 Phase 3 条目"task |
|
||||||
|
| 跨项目联动需在两端各写一条修改记录互相引用 | `CLAUDE.md L84-88` | 本 phase 是纯前端，**不**触发跨项目联动（CONTEXT.md 已说明端到端测试依赖后端 Phase 2，但前端代码层不阻塞）；修改记录条目「跨项目联动」段写「无 / 待评估」 |
|
||||||
|
| API 契约改动需双端同步 | `CLAUDE.md L65-68` | 本 phase 不改 API 契约（消费 Phase 1 已落地的 contract） |
|
||||||
|
| 业务代码 / 配置 / package.json 必须记录 | `CLAUDE.md L92-94` | 修改 `app/ai-model/page.tsx` + 新增 `components/ai-model/credential-slot-dialog.tsx` + 修改 `app/layout.tsx` 都必须记 |
|
||||||
|
|
||||||
|
## Environment Availability
|
||||||
|
|
||||||
|
> 本 phase 纯代码改动 + 类型检查，无需外部工具/服务依赖（除 Node.js + npm，已就绪）。
|
||||||
|
|
||||||
|
| Dependency | Required By | Available | Version | Fallback |
|
||||||
|
|------------|------------|-----------|---------|----------|
|
||||||
|
| Node.js + npm | npm install / npx tsc | ✓（仓库已运行 Phase 1 + 2） | — | — |
|
||||||
|
| TypeScript | `npx tsc --noEmit` 验证 | ✓ | `^5`（package.json devDep） | — |
|
||||||
|
| react-hook-form | dialog 组件 | ✓ | `latest` | — |
|
||||||
|
| @hookform/resolvers | zodResolver | ✓ | `latest` | — |
|
||||||
|
| zod | schema | ✓ | `latest` | — |
|
||||||
|
| sonner | toast | ✓ | `^1.7.1` | — |
|
||||||
|
| lucide-react | Loader2 / KeyRound | ✓ | `^0.454.0` | — |
|
||||||
|
| @radix-ui/react-dialog | Dialog | ✓ | `^1.1.4` | — |
|
||||||
|
| 后端 qy_lty Phase 2（GET/PUT `/api/v1/admin/credential-slot/`） | 端到端联调 | 🟡 看后端 milestone 状态 | — | 用 mock 或推迟到联调阶段；前端代码层 npx tsc + 单元 grep 验证不阻塞 |
|
||||||
|
|
||||||
|
**Missing dependencies with no fallback**：无。
|
||||||
|
**Missing dependencies with fallback**：后端 Phase 2 联调 —— 前端代码层用程序化验证（npx tsc + grep）通过即可，端到端测试推迟。
|
||||||
|
|
||||||
|
## Security Domain
|
||||||
|
|
||||||
|
> Phase 3 涉及凭据 (Access Token) 编辑表单 —— 必须考虑前端 ASVS。
|
||||||
|
|
||||||
|
### Applicable ASVS Categories
|
||||||
|
|
||||||
|
| ASVS Category | Applies | Standard Control |
|
||||||
|
|---------------|---------|-----------------|
|
||||||
|
| V2 Authentication | yes | Phase 2 已落地 RBAC（`hasPermission('credential-slot')`），但 CONCERNS.md 提示后端独立校验闭环 PERM-06 仍待审计 |
|
||||||
|
| V3 Session Management | no（本 phase 不动 token 存储） | — |
|
||||||
|
| V4 Access Control | yes | 入口 Button 受 `hasPermission` 收敛，未授权账户 DOM 中不渲染（Phase 2 已落地）—— 但客户端校验仅 UI 礼貌，真实安全靠后端 |
|
||||||
|
| V5 Input Validation | yes | Zod schema：`appId.min(1)` + `accessToken.min(1)` —— 仅做"非空"硬要求；其他格式（如 token 长度上下限）后端校验 |
|
||||||
|
| V6 Cryptography | no（本 phase 不加密 / 不哈希） | — |
|
||||||
|
| V8 Data Protection | yes | access_token 输入不加 `type="password"`（CONTEXT 选择，运营要看自己输入）；不打 console.log；不把真值存 localStorage / sessionStorage / cookie |
|
||||||
|
| V14 Configuration | no | — |
|
||||||
|
|
||||||
|
### Known Threat Patterns for 本 stack
|
||||||
|
|
||||||
|
| Pattern | STRIDE | Standard Mitigation |
|
||||||
|
|---------|--------|---------------------|
|
||||||
|
| 把脱敏掩码当真值回写 | Tampering（污染数据） | CONTEXT 锁定 `accessToken.min(1)` 强制重输；defaultValues.accessToken 永远空串；placeholder 仅做视觉提示 |
|
||||||
|
| Toast / 表单字段无意中泄露 access_token 真值 | Information Disclosure | toast 描述只写"配置已生效" / 错误用 `handleApiError` 中文映射，**不要** `JSON.stringify(payload)` 进 toast 或 console |
|
||||||
|
| RBAC 仅前端校验导致绕过 | Elevation of Privilege | CONCERNS.md 已记 PERM-06 候选 milestone（后端独立校验）—— 不在本 phase 范围 |
|
||||||
|
| API 401 自动跳登录 | Repudiation / Authentication | Phase 0 落地的 axios response interceptor 已处理（清空 token + 重定向 `/login`），本 phase 沿用，无需新增 |
|
||||||
|
| 表单 XSS（用户在 access_token 输了 `<script>`） | Tampering | React 默认 escape；shadcn Input 是受控的；不 dangerouslySetInnerHTML，安全 |
|
||||||
|
|
||||||
|
## Assumptions Log
|
||||||
|
|
||||||
|
| # | Claim | Section | Risk if Wrong |
|
||||||
|
|---|-------|---------|---------------|
|
||||||
|
| A1 | Sonner Toaster 全局未挂载 | Common Pitfalls / Pitfall 1 | [VERIFIED：grep `<Toaster\|<Sonner` 全仓命中 0；read `app/layout.tsx`（20 行）确认无；read `components/dashboard-shell.tsx` 确认无] —— 不是假设，已验证 |
|
||||||
|
| A2 | `accessToken.min(1)` 已是 CONTEXT.md 锁定决策 | User Constraints | [VERIFIED：CONTEXT.md L150-154] |
|
||||||
|
| A3 | `app/ai-model/page.tsx` 占位 Dialog 在 L473-485 | Code Examples | [VERIFIED：read 全文确认] |
|
||||||
|
| A4 | `components/ai-model/` 目录不存在 | Recommended Project Structure | [VERIFIED：`ls components/ai-model/` 退出码 2，明确"No such file or directory"] |
|
||||||
|
| A5 | 仓库 components 子目录命名约定为 kebab-case | RHF + Zod 模板 / 命名建议 | [VERIFIED：`ls components/songs/` + `ls components/outfits/` + 全仓 grep 现有所有业务对话框文件名] |
|
||||||
|
| A6 | `hooks/use-toast.ts` 与 `components/ui/use-toast.ts` 内容相同 | Common Pitfalls / Pitfall 2 | [VERIFIED：read 两份顶部 30 行，结构与 import 完全一致] |
|
||||||
|
| A7 | `handleApiError(error: unknown): string` 是 `lib/api/error-handler.ts:38` 的签名 | Standard Stack | [VERIFIED：read L38 确认 `export const handleApiError = (error: unknown): string =>`] |
|
||||||
|
| A8 | `lib/api/index.ts:191` 也有同名 handleApiError 但签名为 `(error: any) => string` | Anti-Patterns | [VERIFIED：read L191-196] |
|
||||||
|
| A9 | Phase 1 落地的 `getCredentialSlot()` / `updateCredentialSlot()` 类型签名 | Code Examples | [VERIFIED：read `lib/api/credential-slot.ts` 全文] |
|
||||||
|
| A10 | `useToast()` 仓库形态是 Radix 实现（非 Sonner / 非混合） | useToast/toast API | [VERIFIED：read `hooks/use-toast.ts` 全文 195 行 —— `import type { ToastActionElement, ToastProps } from "@/components/ui/toast"` L6-9 明确是 Radix Toast wrapper；无 sonner import] |
|
||||||
|
|
||||||
|
**结论**：所有关键发现都已通过 grep + read 验证，**没有 ASSUMED 类断言**。
|
||||||
|
|
||||||
|
## Open Questions
|
||||||
|
|
||||||
|
1. **PascalCase vs kebab-case 文件命名最终决定**
|
||||||
|
- What we know：仓库现有约定一致 kebab-case
|
||||||
|
- What's unclear：CONTEXT.md L32 写的是 `CredentialSlotDialog.tsx`（PascalCase）—— 这是 user 提供给 CONTEXT 时的 PascalCase 写法，但同时在 Discretion 段（L183-184）明确说"researcher 决定"
|
||||||
|
- Recommendation：**kebab-case `credential-slot-dialog.tsx`**（与 `user-form-dialog.tsx` / `role-dialog.tsx` / `add-outfit-dialog.tsx` 等 9 个现有业务对话框保持一致）
|
||||||
|
|
||||||
|
2. **Sonner Toaster 挂载位置**
|
||||||
|
- What we know：必须挂载，否则 toast 不显示
|
||||||
|
- What's unclear：挂载到 `app/layout.tsx` `<body>` 内还是 `components/dashboard-shell.tsx` 内？
|
||||||
|
- Recommendation：**挂在 `app/layout.tsx` `<body>` 末尾**（最高层、覆盖所有路由；与 next-themes ThemeProvider 同级 —— 但本仓 layout.tsx 当前就 20 行裸结构没用 ThemeProvider，可只加 Toaster）
|
||||||
|
|
||||||
|
3. **是否同时挂载 Radix Toast `<Toaster />`（来自 `components/ui/toaster`）**
|
||||||
|
- What we know：`hooks/use-toast.ts` 是 Radix Toast 实现且已被 `add-dance-dialog.tsx` 等使用（grep 命中 9 文件），但其 Toaster 也未挂载 → 这些 toast 调用本身就是 dead code
|
||||||
|
- What's unclear：本 phase 是只挂 Sonner，还是顺手把 Radix Toaster 也挂上修复其他 dead code？
|
||||||
|
- Recommendation：**只挂 Sonner**。修复 Radix Toast dead code 是范围外（CONTEXT 明确锁定本 phase 用 Sonner）。这个发现可在 CONCERNS.md 候选清单中记一笔。
|
||||||
|
|
||||||
|
4. **`updated_at` 时间格式**
|
||||||
|
- What we know：CONTEXT 提了两个选项 —— `toLocaleString('zh-CN')` 或 `date-fns`
|
||||||
|
- What's unclear：哪个更符合仓库约定？
|
||||||
|
- Recommendation：**`toLocaleString('zh-CN')`**（无新依赖、零成本；`date-fns` 虽在 deps 但本场景无需复杂格式化；如果将来需要相对时间"3 分钟前"再切 date-fns）
|
||||||
|
|
||||||
|
5. **是否做加载态骨架/spinner**
|
||||||
|
- What we know：CONTEXT 没明说
|
||||||
|
- Recommendation：**简单 `<Loader2 className="animate-spin" />`** 居中显示（已在 Code Examples 中给出）；不做骨架屏（过度工程）
|
||||||
|
|
||||||
|
## Sources
|
||||||
|
|
||||||
|
### Primary (HIGH confidence — 全部仓库内 grep + read)
|
||||||
|
|
||||||
|
- `C:\Users\admin\Desktop\Lila-Server\qy-lty-admin\components\users\user-form-dialog.tsx` —— RHF + Zod **首选 1:1 模板**（289 行）
|
||||||
|
- `C:\Users\admin\Desktop\Lila-Server\qy-lty-admin\components\permissions\role-dialog.tsx` —— RHF + Zod 第二模板（425 行，含动态字段）
|
||||||
|
- `C:\Users\admin\Desktop\Lila-Server\qy-lty-admin\components\ui\form.tsx` —— shadcn Form wrapper（179 行）
|
||||||
|
- `C:\Users\admin\Desktop\Lila-Server\qy-lty-admin\components\ui\dialog.tsx` —— Radix Dialog wrapper
|
||||||
|
- `C:\Users\admin\Desktop\Lila-Server\qy-lty-admin\components\ui\input.tsx` —— shadcn Input
|
||||||
|
- `C:\Users\admin\Desktop\Lila-Server\qy-lty-admin\components\ui\label.tsx` —— shadcn Label
|
||||||
|
- `C:\Users\admin\Desktop\Lila-Server\qy-lty-admin\components\ui\sonner.tsx` —— Sonner Toaster wrapper（**未挂载**）
|
||||||
|
- `C:\Users\admin\Desktop\Lila-Server\qy-lty-admin\hooks\use-toast.ts` —— Radix Toast hook（不用，仅作识别参考）
|
||||||
|
- `C:\Users\admin\Desktop\Lila-Server\qy-lty-admin\lib\api\error-handler.ts` —— `handleApiError` L38
|
||||||
|
- `C:\Users\admin\Desktop\Lila-Server\qy-lty-admin\lib\api\credential-slot.ts` —— Phase 1 落地的 API 客户端
|
||||||
|
- `C:\Users\admin\Desktop\Lila-Server\qy-lty-admin\lib\api\index.ts` L191 —— 重复 handleApiError 定义
|
||||||
|
- `C:\Users\admin\Desktop\Lila-Server\qy-lty-admin\app\ai-model\page.tsx` —— Phase 2 落地的页面（占位 Dialog L473-485）
|
||||||
|
- `C:\Users\admin\Desktop\Lila-Server\qy-lty-admin\app\layout.tsx` —— 20 行裸 RootLayout（**Toaster 未挂**）
|
||||||
|
- `C:\Users\admin\Desktop\Lila-Server\qy-lty-admin\package.json` —— deps 版本验证
|
||||||
|
- `C:\Users\admin\Desktop\Lila-Server\qy-lty-admin\.planning\phases\03-dialog-feedback\03-CONTEXT.md` —— 锁定决策来源
|
||||||
|
- `C:\Users\admin\Desktop\Lila-Server\qy-lty-admin\.planning\REQUIREMENTS.md` CRED-FE-04 + CRED-FE-05
|
||||||
|
- `C:\Users\admin\Desktop\Lila-Server\qy-lty-admin\.planning\ROADMAP.md` Phase 3 success criteria
|
||||||
|
- `C:\Users\admin\Desktop\Lila-Server\qy-lty-admin\CLAUDE.md` 项目宪法
|
||||||
|
|
||||||
|
### Secondary (MEDIUM confidence)
|
||||||
|
|
||||||
|
- 无 —— 全部基于本仓库代码，无外部源
|
||||||
|
|
||||||
|
### Tertiary (LOW confidence)
|
||||||
|
|
||||||
|
- 无
|
||||||
|
|
||||||
|
## Metadata
|
||||||
|
|
||||||
|
**Confidence breakdown**:
|
||||||
|
- Standard stack: HIGH —— 全部 deps 在 package.json 已验证版本
|
||||||
|
- Architecture: HIGH —— 1:1 模板 `user-form-dialog.tsx` 已存在并验证可读
|
||||||
|
- Pitfalls: HIGH —— Toaster 未挂载、双 use-toast、双 handleApiError 都是 grep + read 验证的硬事实
|
||||||
|
- Toast / Sonner gap: HIGH（这是 critical finding —— planner 必须 surface）
|
||||||
|
|
||||||
|
**Research date**：2026-05-08
|
||||||
|
**Valid until**：2026-06-07（30 天，仓库内代码稳定，外部依赖无版本变更）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Phase: 03-dialog-feedback*
|
||||||
|
*Researcher: gsd-researcher（基于 CONTEXT.md 锁定决策 + 仓库 grep + read 全验证）*
|
||||||
Loading…
x
Reference in New Issue
Block a user