# 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 全验证）*