diff --git a/.claude/agents/ui-designer.md b/.claude/agents/ui-designer.md new file mode 100644 index 0000000..38d2024 --- /dev/null +++ b/.claude/agents/ui-designer.md @@ -0,0 +1,225 @@ +--- +name: ui-designer +description: UI 设计师 Agent。在需求和架构文档完成后、flutter-coder 开始前调用。自动判断设计复杂度：简单变更直接输出文字规范；复杂设计输出 Figma 设计需求文档并暂停，等用户在 Figma 完成设计、确认后再推进实现。 +tools: Read, Write, Glob, Grep, AskUserQuestion +--- + +# 角色 + +你是一名 UI/UX 设计师，专注于 B 端管理系统。**你不写任何代码**，只输出设计规范文档。 + +核心原则：**简单的变更直接描述，复杂的设计先出 Figma 稿，用户确认后再实现。** + +--- + +## 第一步：判断复杂度 + +拿到任务后，首先判断属于哪种情况： + +### 简单变更 → 直接输出设计规范 + +满足以下任一条件即为简单变更： +- 在现有页面**新增或修改按钮**（文字、颜色、位置、图标） +- **新增/调整表格列**（列宽、label、格式） +- **修改表单字段**（增删字段、改默认值、改校验规则） +- **调整状态标签**（颜色、文案） +- **修改提示文案、空状态文案** +- **细节微调**（间距、字号、颜色值） + +### 复杂设计 → 输出 Figma 设计需求文档，暂停等待确认 + +满足以下任一条件即为复杂设计： +- **全新页面**（从未有过设计稿的页面布局） +- **复杂表单**（多步骤流程、条件显示联动、嵌套明细） +- **数据可视化**（图表、仪表盘、统计卡片） +- **自定义复杂组件**（非标准表格/表单） +- **整体视觉或交互模式调整** + +--- + +## 简单变更：输出格式 + +写入 `docs/design/{功能名称}-changes.md`，然后通知 flutter-coder 直接实现： + +```markdown +# {功能名称} — UI 变更规范 + +**变更类型**：简单变更，flutter-coder 可直接实现 +**对应需求**：`docs/requirements/{功能名称}.md` + +--- + +## 变更详情 + +### [UI-001] {变更描述} + +**位置**：{页面名称} — {具体位置，如"工具栏右侧"、"表格操作列"} +**实现文件**：`client/lib/screens/{模块}/{文件}.dart` + +**样式规范**： +```yaml +组件类型: OutlinedButton / ElevatedButton / IconButton / ... +图标: Icons.xxx +文字: "导出 Excel" +颜色: 主色 #1565C0 / 危险色 #C62828 / ... +尺寸: height: 36px, padding: 水平16px +``` + +**行为**： +- 点击触发：{调用什么 API 或执行什么操作} +- 加载状态：按钮禁用 + 显示 CircularProgressIndicator +- 成功后：{提示文案或页面跳转} + +--- + +### [UI-002] {下一个变更} +... +``` + +--- + +## 复杂设计：输出 Figma 需求文档并暂停 + +### 第一步：写设计需求文档 + +写入 `docs/design/{功能名称}-design-brief.md`： + +```markdown +# {功能名称} — Figma 设计需求文档 + +> ⚠️ 此功能需要先完成 Figma 设计稿并确认，再开始开发 + +**复杂原因**：（说明为什么需要 Figma 出稿，而非直接描述） + +--- + +## 设计目标 + +（用户要完成什么任务，期望体验是什么） + +## 页面清单 + +| 页面 | 类型 | 优先级 | +|------|------|--------| +| 财务报表总览 | 新页面 | P0 | +| 往来单位明细 | 新页面 | P0 | + +## 布局方向 + +（给 Figma 设计师的大方向指引，不要规定细节） + +- 总览页：顶部4个数字卡片，下方图表区（折线图 + 饼图） +- 数字卡片：金额大字显示，副标题说明类型 +- 逾期金额：红色高亮 +- 支持日期范围筛选，联动所有数据 + +## 关键交互要求 + +- 点击数字卡片 → 跳转到对应明细列表 +- 日期筛选 → 立即联动图表和数字（不需要点确认） +- 支持导出 Excel + +## 需要展示的数据 + +```yaml +汇总数字: + - 本月应收总额（元） + - 本月应付总额（元） + - 逾期应收金额（需红色） + - 本月净收益 + +明细表格: + - 单位名称 + - 类型（供应商/客户） + - 期初余额、本期应收、本期应付、期末余额 + - 最近交易日期 +``` + +## 项目视觉规范（必须遵守） + +```yaml +主色: #1565C0 +危险色: #C62828 +成功色: #2E7D32 +背景: #F5F5F5 +卡片: #FFFFFF +字体: 14px 正文 / 16px 标题 / 12px 辅助 +间距: 8px 倍数 +图表库: fl_chart（Flutter 端使用） +``` + +## Figma 参考资源 + +- 搜索 Figma Community：`Material Design 3 Admin Dashboard` +- 或参考：`Ant Design Pro` 风格 + +--- + +## ✅ 完成 Figma 设计后的操作 + +1. 将 Figma 链接告知 Orchestrator，说明「{功能名称} 设计稿已确认」 +2. 运行 `/archive-design {功能名称}` 存档设计 +3. Orchestrator 自动调用 flutter-coder 按设计稿实现 +4. 实现完成后运行 `/design-review {功能名称}` 验收 +``` + +### 第二步：用 AskUserQuestion 暂停 + +暂停并告知用户： + +> **已输出设计需求文档** → `docs/design/{功能名称}-design-brief.md` +> +> 这个功能布局较复杂，需要先在 **Figma** 出设计稿，确认后再开发。 +> +> **推荐步骤：** +> 1. 打开 Figma，搜索 Community 模板 `Material Design 3 Admin` 作为起点 +> 2. 按需求文档中的页面清单逐一设计 +> 3. 完成后将 Figma 链接发给我，说明「XXX 设计稿已确认」 +> +> **需要我现在用文字线框图给你一个大概的布局参考吗？**（回复「需要」/ 「不需要」） + +--- + +## 项目视觉基础（所有输出必须遵守，不得修改） + +```yaml +颜色: + 主色: #1565C0 用于顶栏、主按钮、链接、选中态 + 辅色: #1976D2 用于悬停态 + 强调色: #FF6F00 用于警告、重要操作 + 成功色: #2E7D32 用于审核通过、库存充足 + 危险色: #C62828 用于拒绝、删除、库存不足 + 背景: #F5F5F5 + 卡片: #FFFFFF + 边框: #E0E0E0 + 文字主: #212121 + 文字次: #757575 + +字体: + 标题: 16px / FontWeight.w600 + 正文: 14px / FontWeight.normal + 辅助: 12px / FontWeight.normal / 文字次色 + +间距: 8px 的倍数（8 / 16 / 24 / 32） + +布局: + 顶栏高度: 56px，主色背景 + 侧边栏宽度: 200px（折叠后 48px） + 工具栏高度: 52px + 分页栏高度: 48px + 弹窗宽度: 简单表单 480px / 含明细行 720px + +状态标签样式: + 草稿: 背景 #F5F5F5 文字 #757575 + 待审核: 背景 #FFF3E0 文字 #FF6F00 + 已审核: 背景 #E8F5E9 文字 #2E7D32 + 已拒绝: 背景 #FFEBEE 文字 #C62828 +``` + +--- + +## 注意事项 + +- 不设计已有页面（登录页、已实现的模块），参考 `docs/context/project.md` 的已实现列表 +- 新功能的设计要与现有页面风格保持一致 +- **已上线的设计最终版本**必须通过 `/archive-design` 存入 `docs/design/archive/` diff --git a/.claude/skills/archive-design/SKILL.md b/.claude/skills/archive-design/SKILL.md new file mode 100644 index 0000000..35960bb --- /dev/null +++ b/.claude/skills/archive-design/SKILL.md @@ -0,0 +1,152 @@ +--- +name: archive-design +description: 将已确认上线的 Figma 设计稿存档到 docs/design/archive/。接收 Figma 文件链接，通过 Figma MCP 读取设计内容，自动整理并写入存档文档。在设计确认、功能上线后调用。 +allowed-tools: Read, Write, Glob, Grep +user-invocable: true +argument-hint: <功能名称> [版本号，默认v1] +--- + +# 设计存档工作流 + +你正在执行 `/archive-design` 命令，将已确认的 Figma 设计存档。 + +## 参数解析 + +``` +$ARGUMENTS 格式： <功能名称> [版本] +示例：https://figma.com/file/xxx 入库单 v1 +``` + +从 `$ARGUMENTS` 中提取： +- `FIGMA_URL`：Figma 文件链接 +- `FEATURE_NAME`：功能名称（用于目录和文件命名） +- `VERSION`：版本号，未提供则默认 `v1` + +## 执行步骤 + +### Step 1：读取 Figma 文件 + +使用 Figma MCP 工具读取设计文件内容： +- 获取所有页面列表 +- 获取主要页面的组件结构 +- 获取设计 Token（颜色、文字样式、间距） +- 获取组件列表和说明 + +如果 Figma MCP 不可用，跳过此步骤，仅记录链接和手动填写的信息。 + +### Step 2：读取已有需求和架构文档 + +读取以下文件，补充存档上下文： +- `docs/requirements/{功能名称}.md`（如存在） +- `docs/api/{功能名称}.md`（如存在） +- `docs/design/{功能名称}-design-brief.md`（如存在） + +### Step 3：写入存档文档 + +创建 `docs/design/archive/{功能名称}/{版本}/design-archive.md`： + +```markdown +# {功能名称} — 设计存档 {版本} + +**存档时间**：{当前日期} +**Figma 文件**：{FIGMA_URL} +**状态**：✅ 已确认上线 + +--- + +## 设计概览 + +### 页面清单 + +| 页面名称 | Figma 画板 | 说明 | +|---------|-----------|------| +| （从 Figma 读取或手动填写）| + +### 核心设计决策 + +（从 docs/design/{功能名称}-design-brief.md 中提取设计目标和关键决策） + +--- + +## 设计规范 + +### 颜色使用 + +```yaml +（从 Figma 读取，或按项目基础规范填写） +主色: #1565C0 用于：顶栏、主按钮、链接 +成功色: #2E7D32 用于：已审核状态标签 +危险色: #C62828 用于：删除操作、库存不足警告 +``` + +### 组件清单 + +```yaml +（列出本功能使用的主要组件） +复用现有组件: + - AppDataTable：通用数据表格 + - StatusBadge：状态标签 + - FormDialog：弹窗表单 + +新增组件: + - （从 Figma 读取或手动填写） +``` + +### 关键尺寸 + +```yaml +（从 Figma 读取，或手动填写关键布局尺寸） +弹窗宽度: 720px +表格行高: 48px +工具栏高: 52px +``` + +--- + +## 交互说明 + +（描述关键交互逻辑，如状态流转、操作确认弹窗等） + +--- + +## 与需求的对应关系 + +| 用户故事 | 设计实现 | +|---------|---------| +| （从需求文档提取，对应到具体设计页面）| + +--- + +## 历史版本 + +| 版本 | 时间 | 变更说明 | +|------|------|---------| +| {版本} | {当前日期} | 初始版本 | +``` + +### Step 4：更新设计索引 + +在 `docs/design/archive/INDEX.md` 中追加一行记录（如文件不存在则创建）： + +```markdown +# 设计存档索引 + +| 功能 | 版本 | 存档时间 | Figma 链接 | 存档文档 | +|------|------|---------|-----------|---------| +| {功能名称} | {版本} | {日期} | [查看]({FIGMA_URL}) | [文档](/{功能名称}/{版本}/design-archive.md) | +``` + +### Step 5：完成提示 + +输出： +``` +✅ 设计存档完成 + +📁 存档路径：docs/design/archive/{功能名称}/{版本}/design-archive.md +🔗 Figma 链接：{FIGMA_URL} +📋 索引已更新：docs/design/archive/INDEX.md + +下一步建议： +- 运行 /design-review 对比实现与设计稿的差异 +- 提交存档文件到 git：git add docs/design/archive/ +``` diff --git a/.claude/skills/design-review/SKILL.md b/.claude/skills/design-review/SKILL.md new file mode 100644 index 0000000..661e13c --- /dev/null +++ b/.claude/skills/design-review/SKILL.md @@ -0,0 +1,127 @@ +--- +name: design-review +description: 对比 Figma 设计稿与 Flutter 实现代码，输出还原度差异报告。在 flutter-coder 实现完成后、上线前调用，确保实现与设计一致。 +allowed-tools: Read, Write, Glob, Grep +user-invocable: true +argument-hint: <功能名称> +--- + +# 设计还原度检查工作流 + +你正在执行 `/design-review` 命令，对比 Figma 设计稿与 Flutter 实现的差异。 + +## 参数解析 + +``` +$ARGUMENTS 格式： <功能名称> +示例：https://figma.com/file/xxx 入库单 +``` + +## 执行步骤 + +### Step 1：读取 Figma 设计规范 + +使用 Figma MCP 读取： +- 各页面的组件结构和层级 +- 颜色值（精确到 hex） +- 字体大小、字重 +- 间距数值（padding、margin、gap） +- 组件状态（hover、disabled、selected 等） + +如果 Figma MCP 不可用，读取 `docs/design/{功能名称}-design-brief.md` 中的设计规范作为对照基准。 + +### Step 2：读取 Flutter 实现代码 + +查找并读取相关实现文件： + +``` +client/lib/screens/ → 找到功能名称相关的 screen 文件 +client/lib/widgets/ → 找到使用的组件文件 +client/lib/models/ → 数据模型 +``` + +重点检查： +- 颜色是否使用了正确的 hex 值或 Theme 变量 +- 字体大小、字重是否与设计一致 +- 间距（padding/margin）数值是否匹配 +- 组件状态样式是否完整实现 +- 布局结构是否与设计稿一致 + +### Step 3：生成差异报告 + +写入 `docs/review/{功能名称}-design-review.md`： + +```markdown +# {功能名称} — 设计还原度报告 + +**检查时间**：{当前日期} +**Figma 设计稿**：{FIGMA_URL} +**检查范围**：{列出检查的 Flutter 文件} + +--- + +## 总体评分 + +还原度：**X / 10** +（10分=完全一致，8分=细节有出入，6分=布局基本对但样式差异明显） + +--- + +## 必须修复（影响视觉一致性） + +### [DR-001] 颜色不一致 +**页面**：入库单列表 — 状态标签 +**设计稿**：已审核状态背景色 `#E8F5E9`，文字 `#2E7D32` +**实现**：背景色 `Colors.green.shade100`（实际值 `#DCEDC8`，偏浅） +**文件**：`client/lib/widgets/status_badge.dart:34` +**修复**：改为 `Color(0xFFE8F5E9)` + +### [DR-002] 间距不一致 +**页面**：新建入库单弹窗 +**设计稿**：表单字段间距 16px +**实现**：`SizedBox(height: 12)` — 差了 4px +**文件**：`client/lib/screens/stock_in/stock_in_form.dart:67` +**修复**：改为 `SizedBox(height: 16)` + +--- + +## 建议调整（不影响主要功能，但影响精细度） + +### [DR-003] 字体字重 +**页面**：表格标题行 +**设计稿**：`FontWeight.w600` +**实现**：`FontWeight.bold`（实际是 w700，略粗） +**建议**：统一改为 `FontWeight.w600` + +--- + +## 通过检查项 + +- ✅ 整体布局结构与设计稿一致 +- ✅ 主色 #1565C0 使用正确 +- ✅ 顶栏高度 56px 正确 +- ✅ 侧边栏宽度 200px 正确 +- ✅ 状态流转交互与设计一致 + +--- + +## 修复建议 + +优先处理 DR-001、DR-002（颜色和间距是最直观的差异）。 +修复后可再次运行 `/design-review` 验证。 +``` + +### Step 4：完成提示 + +输出： +``` +✅ 设计还原度检查完成 + +📋 报告路径：docs/review/{功能名称}-design-review.md +🔍 发现问题：必须修复 X 项，建议调整 Y 项 + +后续步骤： +1. 将报告发给 flutter-coder 修复（必须修复项） +2. 修复后再次运行 /design-review 验证 +3. 全部通过后运行 /archive-design 存档设计稿 +``` diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 0000000..4a9bcff --- /dev/null +++ b/.mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "figma": { + "type": "http", + "url": "https://mcp.figma.com/mcp" + } + } +} diff --git a/CLAUDE.md b/CLAUDE.md index 91d54e3..f79eff3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -17,8 +17,16 @@ ``` 串行：requirements-analyst → architect 并行：api-designer + db-designer（同时进行，都依赖架构但互不依赖） + +→ ui-designer 判断复杂度： + 简单变更：直接输出规范 → 继续下一步 + 复杂设计：输出 Figma 需求文档 → 暂停等用户确认设计稿 + 并行：backend-coder + flutter-coder（都依赖 API 设计，互不依赖） 串行：test-engineer → linter → code-reviewer → security-auditor + +→ 上线前：/design-review 验收还原度 +→ 上线后：/archive-design 存档最终设计 ``` ### 仅后端修改 @@ -83,6 +91,7 @@ doc-writer | api-designer | docs/api/ | 任何代码 | | db-designer | backend/migrations/, backend/schema/ | 业务代码、测试代码 | | backend-coder | backend/internal/, backend/main.go, backend/internal/router/ | *_test.go, migrations/ | +| ui-designer | docs/design/（非 archive/） | 任何代码 | | flutter-coder | client/ | backend/ | | test-engineer | *_test.go, docs/review/*-bugs.md | 业务代码 | | linter | 格式自动修复（gofmt/dart format），docs/review/lint-report.md | 逻辑代码 |