ui-generator

从 PRD 直接生成可运行的 ToB 高保真原型页面。

这项技能的核心价值：让产品经理跳过传统的 Axure 画图阶段，直接从 PRD 文字描述生成可交互的前端原型。这不是简陋的线框图，而是可以直接向客户或老板演示的 Premium 级 Demo。

输入

• PRD 文档（或其中的功能模块描述）
• ToB 设计规范：设计令牌 templates/tob_design_tokens.css；UI/UX 规则读取宿主契约（宿主根目录 cookbook.config.json 的 host.specMap）中 ui-ux 角色登记的 spec，调用方另给了规则位置的以调用方为准
• 宿主没有声明 ui-ux 角色、调用方也没给规则时，不停下：先告诉用户「将按默认的通用 UI/UX 规则生成，如已有自己的规则请给出位置」；用户没有另外指定，就按 默认 UI/UX 规则 与设计令牌继续，并在交付说明里写明本次用的是默认规则及该文件的位置，供下游审计把它作为 UI/UX 规则使用；取不到默认规则文件时，按设计令牌与本文的设计原则生成，并在交付说明里注明未套用默认规则

调用方随调用给出的参数，优先作为输入源。

前置准备

1. 运行 scripts/scaffold_app.py 初始化符合 ToB 规范的前端脚手架（如果项目尚未初始化）。
2. 加载设计规范：设计令牌，加上宿主的 UI/UX 规则或默认 UI/UX 规则（见「输入」），确保所有视觉元素有据可依。

设计原则

企业级 Premium 视觉

不是简陋的 MVP，而是可以直接向客户演示的高端 Demo。之所以强调"Premium"，是因为 ToB 产品的第一印象直接影响客户的付费决策——一个看起来"糙"的原型会让客户怀疑产品的专业度。

T 型布局

左侧固定导航栏 + 顶部标题栏 + 右侧内容区。这是 ToB 产品的事实标准布局（参考 Salesforce、飞书管理后台、用友 U8），用户零学习成本。

信息密度优先

ToB 用户追求效率，合理利用空间，而非大面积留白。一个财务总监不需要看到"欢迎使用本系统"的大标语，他需要一眼看到今天要处理的审批单。

交互真实感

按钮有 hover/active 反馈，表格有排序/筛选的视觉暗示。交互反馈让用户确信"系统在响应我"，减少误操作和焦虑。

严格角色隔离（Role Isolation）

这是 ToB 产品的铁律：不同角色看到的界面必须是物理隔离的，严禁使用 Tab/Toggle 来切换角色视图。原因很简单——在真实企业环境中，一个一线专员永远不需要看到"总监审批"的界面，把它们堆在一起只会造成困惑和权限泄露风险。

具体约束：

• 使用全局 RoleContext 管理当前角色状态
• 顶栏 Dropdown 模拟身份切换（仅用于演示，生产环境由认证系统控制）
• 不同角色的专属功能必须拆分为独立的页面组件

技术栈要求

• 框架：React + TypeScript（Vite 构建）
• 样式：Tailwind CSS
• 图标：Lucide React
• 组件复用：使用统一的 Common 组件库

数据访问层架构（生产可对接性）

原型若追求"能经改造对接真实后端",业务模块从第一天就按三层生成,禁止把业务逻辑、持久化、UI 状态揉进同一个 Context:

• 异步契约先行:mock 同步也保持 Promise 形状——同步改异步是侵入式改造,原型期不做,对接后端时所有页面都要返工。
• 对接后端 = 只替换 Service 实现,页面与 Provider 零改动。
• mock 实现以 storage 为唯一事实源(无状态仓储,不做模块级单例内存缓存),并注入 dev 延迟(测试环境为 0)使 loading/pending 态可见可测。
• 守卫类命令以返回值报错(不在状态层弹任何 UI),页面按反馈规范呈现;成功提示只在命令真正成功后触发。
• 金额运算一律经以整数分计算的金额工具(解析、加、减都在整数分上进行),禁裸浮点加减(多级汇总时浮点误差会逐笔放大);对应数据模型的 Decimal(18,2) 口径。

页面生成规范

对每个页面，必须包含以下结构：

// 1. 页面头部：标题 + 操作按钮区
// 2. 筛选/搜索区域（如适用）
// 3. 核心内容区（表格/表单/看板）
// 4. 分页器（如适用）
// 5. 弹窗/抽屉（操作类功能）

视觉规范

引用 templates/tob_design_tokens.css 中定义的（取不到设计令牌时，按下列各项与所用的 UI/UX 规则自行定义一组令牌，并在交付说明中注明未套用设计令牌）：

• 色彩系统（品牌色、状态色、中性色）
• 间距系统（4px 基准网格）
• 圆角规范（卡片 8px，按钮 6px，输入框 6px）
• 阴影层级（卡片 shadow-sm，弹窗 shadow-lg）
• 字体层级（页面标题 24px/700，正文 14px/400，紧凑表格 13px，辅助 12px/400）

Mock 数据要求

之所以要求 Mock 数据必须"真实感"，是因为抽象的占位符（如 User1、Item A）会让评审者无法代入真实使用场景，导致很多交互问题在演示阶段才暴露。

• 所有列表必须填充 ≥ 5 条 真实感的 Mock 数据
• 姓名使用中文（如：张伟、李娜、王芳）
• 金额使用人民币格式（¥1,234.56）
• 日期使用 yyyy-MM-dd 格式
• 状态字段使用带颜色的 Badge 组件

交互要求

质量自检

完成原型后，用以下问题自查：

• 页面是否使用了 T 型布局？
• 色彩是否严格来源于 Design Tokens？
• 表格是否有 ≥ 5 条 Mock 数据？
• 所有按钮是否有 hover 反馈？
• 是否使用了 Common 组件库中的标准组件？
• 页面加载时是否有淡入动画？
• 页面是否严格遵循了单一角色视角，没有出现跨角色越权的功能堆砌？
• RoleContext 是否正确实现，顶栏身份切换是否正常工作？
• 脚手架是否通过 scripts/scaffold_app.py 初始化？脚手架组件是否与所用的 UI/UX 规则一致（不一致时按规则替换）？
• 交付说明是否写明所用 UI/UX 规则的来源（宿主规则、调用方给出的规则，或默认规则）？

停机条件

同时满足才算完成：

1. 质量自检各项都有结论
2. 已做代码缺陷自查并修复，见 代码缺陷自查。这是作者自己的质量动作：发现即修，向用户简述修了什么，不出报告。
3. 项目能构建，页面能打开；用户明确不要求初始化或构建时，不自建工程、不安装依赖，改为在交付说明里写明未构建，并给出初始化与运行步骤

停下交用户：需求文档缺页面字段或交互规则，无法落地为界面；同一处构建错误修两次仍失败。

不宣告"原型完成、可评审"之外的结论；是否进入下一阶段由用户决定。