# TFDS 生成后自检 Checklist

> **作用域**：页面或组件生成完成后，按本文件逐项检查。任一项失败，先修复再交付。

---

## 1. Skill 读取链路

- 已读取 `DESIGN_PRINCIPLES.md` 判断页面气质。
- 已读取 `PAGE_ARCHETYPES.md` 判断页面范式。
- 已读取 `LAYOUT_RECIPES.md` 并选择唯一主 recipe（`base-management` / `chat-home` / `chat-conversation` / `copilot-workbench` / `im-thread`）。
- 已用 `components.summary.json` 做组件初选。
- 已对命中的组件读取 `components.index.json` 中完整 props / rules / examples。
- 自定义区块已查 `LAYOUT_RULES.md` 与 `GLOBAL_DESIGN_RULES.md`。

---

## 2. 组件调用

- `components.index.json` 里有对应组件时，已整体 import 使用。
- 命中 `page-pattern` / `page-template` 时，已优先直接 import 对应 `*Pattern` / 列表示例组件；若做业务改造，已完整复制模板源码作为起点，而不是拆模板局部 JSX 或按截图重拼。
- 没有用 `div/span` 手搓 Tag、Button、Tabs、Card、FormTitle、ChatInput、Table。
- 浏览器 Inspect/检查元素时，所有 TFDS 组件根节点或关键节点能看到 `.tfds-*` 专有类名或 `data-tfds-component` 标识；页面模板根节点能看到 `.tfds-page-*` 类名。若只看到普通 `div/span/button/input` + Tailwind class，说明该处可能是手搓组件，必须回到 `components.index.json` 选择对应 TFDS 组件。
- **Inspect 防误判总则**：复合组件 / 页面模板的子树允许出现普通 `div/span`（布局容器、插槽包裹、Portal 容器等）。验收以“组件根节点 / 关键交互节点”出现 `.tfds-*` 或 `data-tfds-component` 为准，**不要求每一层 DOM 都带标识**。
- **复合组件 Inspect**：`SplitButton` 验收组合根（`.tfds-split-button` / `data-tfds-component="SplitButton"`），内层两个 `Button` 的 `tfds-button` 属正常子节点，不算手搓。
- **AI 推荐区 Inspect**：`Input` / `Select` / `TextArea` 内嵌的 AI 推荐列表验 `.tfds-ai-suggestion-panel` 或父级 `tfds-input` / `tfds-select` / `tfds-textarea`；`AgentFamilyAvatar` 验 `.tfds-agent-family-avatar`。
- 页面级模板使用公开 Page Pattern 时，根节点已带统一 `.tfds-page-*` 类名，例如 `.tfds-page-base-frame`、`.tfds-page-customer-service-workspace`、`.tfds-page-chat-home`、`.tfds-page-im-conversation`；不要在外层再包一层无 TFDS 标识的伪页面根容器。
- 页面模板的 Header / Workspace / 主内容区 / 信息区 / 输入区或状态栏等容器顺序、间距、滚动归属、拖拽/折叠/吸底/上下文同步能力与模板源码一致，没有只保留静态外观。
- **Tabs 尺寸默认铁律**：页面内/白卡内/面板内/表单分段/筛选维度/Playground 内的 `<Tabs />` **默认一律 SM**（省略 `size` 或显式 `size="sm"`）；只有平台顶部 header / 页面级顶导 / 产品级一级导航才允许使用 `md/lg`。
- 涉及客服业务、客服工作台、客服接待、工单处理、售后处理、订单/商品上下文核对等场景时，客服工单信息、商品信息、订单信息、用户信息、客服信息、沟通记录、处理日志等辅助信息区已优先使用 `InfoDisplayPanel`，没有用多个 `Card` / `div` / 自制 tabs 拼接信息侧栏。
- 客服信息区存在多个分类时，已通过 `InfoDisplayPanel` 顶部 Tabs 切换分类；只有单一分类时才降级为标题 + 内容结构。
- 当右侧信息 tab 命中“托管助手 / 托管助理 / AI 托管 / 辅助回复 / 推荐回复 / HiAI”语义时，已默认使用客服工作台模板托管助手形态：左侧 IM 最新用户消息灰色气泡、`HiAI` 执行流、与 IM 客服回复一致的推荐文案、复制到输入框和发送给用户两个真实交互；没有写成静态 AssistantPanel 或孤立的 AI 文本。
- 工单 Agent 工作台中，底部 `AgentStatusBar` 的 `title / planSteps / summarySections / summaryTags / inputPlaceholder / primaryActionLabel` 已由上方 5 个 `AgentNodeCard` 节点真实内容派生，没有使用 `SAMPLE_*` 静态样例文案。
- 工单 Agent 工作台中，“Agent 节点总结”的 `summarySections[].key` 已统一为 4 个中文字符短标题，左侧固定宽度黑色加粗列对齐，没有直接使用过长 `statusText`。
- 页面标题、白卡标题、面板标题、section 标题全部使用 `FormTitle`。
- 状态、类型、风险、数量徽标优先使用 `Tag`。
- 所有纯图标按钮必须使用 `<Button iconOnly tooltip="操作文案" />`，不论 primary / outline / ghost / text 任一变体；禁止只放 icon 让用户猜操作含义。
- 对话、消息、输入使用 `ChatMessage` / `ChatBubble` / `ChatInput`。
- 所有人像类头像使用 `Avatar` / `AvatarGroup` 等 TFDS 组件，并默认优先使用包内本地成员头像素材；未使用 pravatar / Unsplash / placeholder 等随机外链头像。

---

## 3. 页面范式

- 页面第一屏能看出当前对象、关键状态和下一步操作。
- 页面主 recipe 与用户第一步动作一致：对象管理走 `base-management`，从 0 发起 AI 任务走 `chat-home`，持续 AI 协作走 `chat-conversation`，对象/产物主工作区 + AI 侧助走 `copilot-workbench`，单线程真人会话走 `im-thread`，客服在线处理工作台或左侧列表 + 中间聊天 + 右侧信息 Tabs 的三栏 IM 工作台走 `customer-service-workspace`。
- 页面 header 直接坐灰底，没有被错误包进白卡。
- 内容白卡只承载真实工作区：表格、列表、表单、对话、编辑器、运行结果。
- 复杂任务使用稳定分屏，而不是纵向堆叠成长页面。
- 入口页主行动居中，模板/案例卡片只做辅助路径；`ChatHomePagePattern` 右侧主内容区保持浅灰底，未用大白卡包住 Hero / ChatInput / Tabs / Card 网格。
- AI 入口页 Hero 发送或模板卡点击后，必须 handoff 到 `ChatConversationPattern`（`bootstrapSendSignal` 自动发首条消息），禁止在一级页内手写 `ChatMessage` 流（见 `PAGE_FLOW_LINKAGES.md` §1）。
- 产物预览像可交付文档，不被压缩成普通信息卡。

---

## 4. 布局与滚动

- 根容器 `h-dvh` / `h-full` 链路完整，关键层有 `min-h-0` / `min-w-0`。
- 已在常见桌面尺寸验证：宽度至少覆盖 `1920 / 1440 / 1280 / 1024`，高度至少覆盖 `900 / 768`；默认浏览器缩放下关键控件、底部操作、表格分页、输入区和结果区都可达，不依赖缩放页面才能使用。
- 页面没有横向 body 滚动；Tabs、筛选栏、表单网格、按钮组、表格工具条、InfoDisplayPanel 和右侧面板不会撑破父容器。若局部内容超宽，滚动必须发生在该组件或面板内部，而不是把整页撑宽。
- 表格、消息流、编辑器、产物区在自身容器内滚动。
- Playground、会话、多面板页没有错误地整页滚动。
- 双栏 / 三栏布局中固定侧 `shrink-0`，主内容 `flex-1 min-w-0`。
- **横向并列大卡工作区**（如双白卡 / 左筛选 + 右主表）：辅助侧默认具备外层容器级宽度拖拽（父容器维护 `width / min / max` 和拖拽事件，外层 `overflow-visible`），主卡 `flex-1 min-w-0`；`TagBar` 自身不要写 `tone / resizable / onWidthChange`；对照 `LAYOUT_RULES.md` §3.2 / `McpManagementPage`。
- 通用页面白卡距浏览器边缘约 16px；基础页面框架菜单入口按 `PAGE_FRAME_CONTENT_MARGIN = 16px 16px 16px 0`，页面示例3 按 `PAGE_FRAME_CONTENT_WITH_TOPBAR_MARGIN = 0 16px 16px 0`，NavBar 右侧不得额外加左 padding；**纵向叠放**的板块默认 16px (`gap-4`)；**横向并列**的同行多白卡分栏 / 多面板 Playground 默认 8px (`gap-2`)。
- 客服工作台框架使用 `CustomerServiceWorkspaceFramePattern` 时，除模板自身内部间距外，外层不得再套 `main p-4`、margin wrapper、白卡或灰底 wrapper；工作台顶部、底部、右侧直接贴浏览器可视区。若左侧有菜单栏，必须是 AppShell 级 `NavBar platform="bytehi"` + 右侧工作台，NavBar 与工作台之间不得额外加 gap/padding。
- 白卡内部 padding 使用 24px，未误用到页面外框。
- PageMetaBar / 白卡 Header / 筛选栏 / 卡片网格已按 `LAYOUT_RECIPES.md` 对齐：左侧标题 `min-w-0 flex-1`，右侧操作 `shrink-0 flex-wrap gap-2`；筛选栏固定宽而非全宽；卡片网格使用 `auto-fit/minmax`。
- 表单正文宽度已按 `GLOBAL_DESIGN_RULES.md` §3.1 对齐：页面主表单、白卡表单、抽屉 / 弹窗正文表单、侧栏详情表单中的 `Input` / `Select` / `TextArea` / `InputNumber` / `DatePicker` / `TimePicker` / `TagInput` 均撑满字段列，并且左右边界一致。
- 没有把筛选栏 / 工具条的固定宽 `160/200/240px` 或示意宽 `300px` 套到业务表单正文；只有筛选栏、紧凑查询区、工具条允许固定宽。
- 使用 `Form children` 或 `item.control` 自定义字段时，自定义控件外层已补 `w-full min-w-0 max-w-full`，没有绕过 `Form` 的字段宽度约束。
- AI 入口页的 Hero、`ChatInput`、Tabs、搜索和模板网格直接坐灰底；模板卡 `Card color="white"`；网格 `gap-4`；Tabs 为 `size="sm"`。
- `<Tabs />` 默认保持 `overflow="auto"`，父级具备 `min-w-0 max-w-full`；没有给 Tabs 或其父级添加 `w-fit` / `min-w-max` / 固定大宽度导致溢出。
- `ChatMessage role="user"` 默认保持 `userBubbleTone="auto"`；白色大背景 / 白色工作卡内用户气泡应自动呈现 `fill-default` 灰底，浅灰或其他非白背景上应呈现白色气泡；不要在白底上强行写 `userBubbleTone="surface"`。

---

## 5. Token 与视觉

- 无硬编码 `#000` / `#fff` / `#333` 等颜色。
- 无 Tailwind 任意值 `text-[15px]` / `p-[18px]` / `rounded-[10px]` 等。
- 须与设计一致的字重使用 `[font-weight:var(--font-semibold)]` / `[font-weight:var(--font-bold)]`，避免裸 `font-semibold` / `font-bold`（见 `GLOBAL_DESIGN_RULES.md` §2.2）。
- 最外层白卡为纯白底 + 12px 圆角 + 无 border + 无 shadow。
- 品牌青绿只用于焦点、激活、链接、品牌状态和标题竖条。
- AI 渐变只出现在明确 AI 语义面。
- 每个区域最多一个 primary 主按钮。
- 密集内容区（表格、表单、日志、配置、代码、结果、长编辑器）使用稳定白底或组件指定背景；不使用 AI 渐变、透明玻璃、弱对比背景或整卡 hover lift。
- 分隔线只用于真实结构边界：表格头、滚动区边界、弹窗头尾、分栏、工具条；没有在每个卡片 header / section / footer 上习惯性叠加横线。

---

## 6. 文本与可读性

- 核心说明、错误原因、状态说明完整可读，不被静默裁切。
- 列表预览、文件名、对象 ID 可省略，但有 Tooltip 或详情入口。
- 标题横向可读，没有一字一行、竖排、过窄标题列。
- 普通标题默认不展示 description；只有确有说明诉求才开启。

---

## 7. 工程集成

- 全局 CSS 已引入 `@import "@tfdesign/b-end/theme.css"`。
- Tailwind 已扫描 `node_modules/@tfdesign/b-end/**/*.{js,jsx}`。
- 交付前可运行：

```bash
node node_modules/@tfdesign/b-end/scripts/check-tfds-integration.mjs
node node_modules/@tfdesign/b-end/scripts/check-tfds-contract.mjs
```

---

## 8. FormTitle 真伪五件套（每个标题逐项目测）

仅"竖条 + 文字"**不算**用对 FormTitle，必须**逐项**通过；任一不中即视为伪 FormTitle，必须改：

1. **字重 = 600**（与组件一致：`[font-weight:var(--font-semibold)]`，禁止依赖裸 `font-semibold` 类）
2. **字色 = `var(--color-foreground)` 深色**（不是 secondary 灰色）
3. **竖条 = brand-500 蓝绿色 3×14/16px 圆角条**（不是品牌浅底、不是 1px border-left 直线）
4. **描述默认隐藏**：无明确说明诉求时不写 `description`；确需展示时必须写 `showDescription`
5. **描述位置正确**：`form` / `level-1` 描述在标题**下方独占一行**；`level-2` / `level-3` 描述在标题**同行右侧**；`card` 标题描述同排且**无竖条**
6. **标题横向可读**：主标题保持横排，标题区最小宽度不低于 120px，右侧操作宁可换行也不能挤压标题

**variant 选型速记**：整体页面左上角总标题 / 工作台名 → `form`；列表/管理页单张主白卡顶栏、页内一级板块标题 → `level-1`；白卡内 section 区块标题（"Prompt Workspace / System Prompt / Conversation / Tools / Run Result"等）→ `level-2`；level-2 之下子分区 → `level-3`；Card 内嵌摘要条 → `card`。

**常见伪装**（命中即必须替换为 `<FormTitle />`）：

- ❌ 手搓竖条：`<div className="flex gap-2"><div className="w-1 h-4 bg-teal-500 rounded" /><h3 className="text-base">Prompt Workspace</h3></div>`
- ❌ 错用 `variant="card"` 当面板主标题（card 是弱化标题，不能用于 Workspace / System Prompt 等面板主标题）
- ❌ `<FormTitle className="font-normal text-gray-600" />`（违反"严禁覆写"铁律）
- ❌ 用 `<p>` 代替 `description` prop
- ❌ 标题竖排/逐字换行：`writing-mode: vertical-rl` / `break-all` / 给标题列固定 12-24px 宽

**标题状态 Tag 必须用 `titleSuffix`**：标题旁的状态 / 数量 / 身份 Tag（如 `0 条消息`、`Beta`、`只读`、`推荐`）必须作为 `titleSuffix` 紧跟主标题，不能放进右侧 action 区。

✅ Good：`<FormTitle variant="level-2" title="Conversation" titleSuffix={<Tag variant="grey" size="m">0 条消息</Tag>} />`

---

## 9. 黑色边框误用 → 正确组件映射（高频）

| 误用场景                                                | 必须改成                                              |
| --------------------------------------------------- | ------------------------------------------------- |
| 数值型模型参数（Temperature/Top-P/Max Tokens/阈值/权重）         | `<InputNumber />`                                 |
| System Prompt / 模型高级参数 JSON / 请求参数 / 代码参数 / 代码输入 | `<TextArea variant="code" minRows={5} />`         |
| 模型 ID/URL 输入                                        | `<TextArea minRows={1} />`                        |
| 操作描述                                                | `<TextArea minRows={2} />`                        |
| 表单备注                                                | `<TextArea minRows={3} />`                        |
| 模型/Effort 枚举                                        | `<Select />`                                      |
| user/assistant 角色切换                                 | `<Tabs variant="segment" />`                      |
| Model List / 查看全部 文字链                               | `<Button variant="text-brand" />`                 |

---

## 10. TextArea 撑满卡片高度（卡片主编辑区标准结构）

主编辑区（System Prompt / 模型高级参数 / 代码 / JSON / 长文本）**必须**：

```jsx
<section className="flex-1 min-h-0 flex flex-col overflow-hidden">
  <header className="shrink-0 px-6 py-4">
    <FormTitle variant="level-2" title="System Prompt" />
  </header>
  <div className="flex-1 min-h-0 overflow-hidden px-6 pb-6">
    <TextArea variant="code" fillHeight resize="none" className="flex-1 min-h-0 w-full" />
  </div>
</section>
```

⛔ Bad：`<TextArea minRows={5} />` 直接放在高卡片里，导致控件不撑满、下方空白。
✅ Good：header `shrink-0` 固定，body `flex-1 min-h-0 overflow-hidden`，TextArea `fillHeight` 后内部滚动。

**code 字号铁律**：`variant="code"` 正文与行号必须保持 14px / 20px，⛔ 禁止外层套 `text-base` / `text-lg` / `leading-7` / `style={{ fontSize: 16 }}`。

---

## 11. 多面板 / Playground 嵌套结构（防整页滚）

**触发关键词**：`playground` / `调试` / `试验` / `IDE` / `多面板` / `prompt editor` / `prompt workspace` / `runtime` / `run result` / `输入区+输出区+参数区` / `A/B 对比` / `编辑器+预览`。

**必须从根到面板正文逐层匹配此骨架**：

```
h-dvh + overflow-hidden                              ← 根：永不滚
  └─ main: flex-1 min-h-0 + overflow-hidden          ← 主区：永不滚
       └─ section/aside（横向子项）
            └─ flex-1 min-h-0 min-w-0 + flex-col + overflow-hidden  （或 shrink-0 w-[Npx]）
                 ├─ header: shrink-0
                 └─ body:   flex-1 min-h-0 overflow-y-auto          ← 唯一滚动层
```

任一层 `overflow-y-auto` 写在错误位置或漏 `min-h-0`，整页就会一起滚。

仅 **Dashboard / 入口聚合首页 / KPI 看板**（纯堆叠浏览，无面板内编辑）才允许整页滚（LAYOUT_RULES § 12.4）。

---

## 12. 页面 header 灰底裸放（Bad / Good 对照）

**白卡装什么 / 灰底装什么**：

| 内容类型                                  | 装在哪    | 理由                          |
| ------------------------------------- | ------ | --------------------------- |
| 列表 / 表格 / 对话流 / 参数表单 / 运行结果 / 编辑器主体 | ✅ 白卡   | 用户在这里"做事"——这是工作区            |
| 页面标题 + 描述 + 主次操作按钮（返回/导入/导出）       | ✅ 灰底裸放 | 用户"了解 / 切换位置 / 触发动作"——页面元数据 |
| 面包屑 / 页面级 Pill Tabs（业务模块切换）        | ✅ 灰底裸放 | 页面级导航，不是卡内子页签               |
| 全局浮窗工具条（Floating Action Bar）        | ✅ 灰底裸放 | 页面级动作                       |
| 白卡内的子区块标题（FormTitle level-2/3）     | ✅ 在白卡内 | 卡内层级，不是页面级 header           |

| ❌ 误用                                                      | ✅ 必须改成                                                                                                       |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `<div bg=surface rounded-lg p-6>{标题 + 描述 + 操作按钮}</div>` | `<header className="shrink-0 px-4 pt-3 pb-2 flex justify-between">{...}</header>`（直接坐灰底，参照 LAYOUT_RULES § 1.5.2） |
| 把页面级 Pill Tabs（业务模块切换）放进白卡                                | Pill Tabs 直接坐灰底（参照 CopilotPagePattern 的 TopBarTabs）                                                          |
| "标题白卡 + Tab 白卡 + 内容白卡"三张白卡叠加                              | 顶部一行灰底裸放 + 一张内容白卡                                                                                            |

**参考样本**：`CopilotPagePattern` TopBar = 裸顶导栏标杆；`BasePageFramePattern` = 顶部灰底 PageHeader + 单白卡 / 双白卡内容区组合。

---

## 13. 全宽撑满 / 左右大空白专项

- 通用灰底页面 `main` padding 默认 `p-4`（16px）；基础页面框架 / 菜单栏入口必须使用 `PAGE_FRAME_CONTENT_MARGIN` 或 `PAGE_FRAME_CONTENT_WITH_TOPBAR_MARGIN`
- ⛔ **禁止**在 `main` 内套 `<div className="max-w-* mx-auto">` 居中容器
- 通用页面白卡 div 自身不加 `mx-` 外边距；基础页面框架只允许使用 `pageListShared.jsx` 共享 margin token，靠 `flex-1` / `shrink-0 w-[Npx]` 控制宽度
- ⛔ 禁止根容器 / `main` 加 `max-w-screen-xl` / `max-w-7xl` / `max-w-[1440px]` 等收窄值
- AI 入口页（`ChatHomePagePattern`）右侧主内容区禁止用 `bg-surface` / 白卡 wrapper 包住 Hero + ChatInput + Tabs + Card 网格；只允许模板卡自身是 `<Card color="white" />`
