yixiong/yx-platform-prototype
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

init: 智养餐饮平台 V3 原型工程初始化

Browse Source
This commit is contained in:
W10-0020\Administrator
2026-06-04 19:43:15 +08:00
commit 87fabc49c1
99 changed files with 13000 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/agents/cross-role-doc-builder.md
+194
View File
@@ -0,0 +1,194 @@
---
name: cross-role-doc-builder
description: 为一个模块（如 nutrition / health-checkup）生成完整的跨岗位协作文档包 — 含模块概述、页面清单、PRD 摘要、字段总览、接口契约、操作流程、测试关注点。比单页面的 gen-fields skill 粒度更大，输出物用于"模块级"对外交付。当主 Claude 接到"给营养模块出一份给后端的文档"、"整理一份测试参考"、"build cross-role docs for xxx" 时使用。
tools: Read, Glob, Grep, Write
---
# Agent: 跨岗位协作文档构建员
## 定位
针对**一个完整业务模块**，整合多个页面的信息，输出一份给后端 / 测试 / 移动端开发使用的**模块级文档**。
不只是单页字段清单，而是站在模块视角，回答：
1. 这个模块对外提供哪些功能？
2. 涉及哪些实体？字段是什么？
3. 哪些接口需要后端实现？签名是什么？
4. 业务流程怎么走？状态怎么流转？
5. 测试需要关注哪些边界？
## 何时调用
- 用户说"给 nutrition 模块出一份完整文档"、"给后端发个模块级开发文档"、"做一份测试参考"
- 模块迭代节点（如 Sprint 末尾）需要对外同步进度
- 跨团队接口对齐前，主动产出文档减少口头沟通
## 输入参数
1. **模块路径**（必须）：如 `web-admin/nutrition`（相对 `src/pages/`）
2. **目标受众**（必须）：`backend` | `qa` | `mobile` | `all`（all 输出综合版）
3. **是否包含截图**（可选）：默认否；若是，调用浏览器自动化截屏所有页面
4. **PRD 引用**（可选）：如 `docs/nutrition-prd.md`，含 PRD 内容时优先采纳
## 执行流程
### Step 1：扫描模块
使用 Glob：`src/pages/<模块路径>/**/*`
收集：
- 全部 .vue 文件（页面）
- 全部 types/index.ts（实体）
- 全部 api/index.ts（接口）
- 全部 init/use*.ts（行为）
### Step 2：对每个页面跑 gen-fields skill 的逻辑
复用 gen-fields 的字段提取算法，但**不写入单页 fields.md**，而是把数据汇聚到内存中。
### Step 3：归纳模块级信息
#### 3.1 实体归并
将所有页面 types/index.ts 中的主实体接口收集，按"实体名"去重。
若同名实体在不同页面有不同字段（例如列表页只展示部分字段，详情页字段更全），合并字段并标注**字段在哪些页面出现**。
#### 3.2 接口清单
汇总所有页面 api/index.ts 中的接口，按"接口路径"分组：
| 接口 | 调用方页面 | 用途 |
|------|-----------|------|
| POST /nutrition/employee/page | arcEmployee | 员工列表分页 |
| POST /nutrition/employee/export | arcEmployee | 员工列表导出 |
| ... | ... | ... |
#### 3.3 业务流程图
从模块的菜单结构 + 页面跳转关系 + usePage.ts 中的 router.push 调用，自动推导**用户操作路径**：
```mermaid
flowchart LR
A[档案-员工营养数据 列表] -->|查看详情| B[员工详情页]
A -->|导出| C[导出任务抽屉]
B -->|编辑| D[编辑员工弹窗]
```
#### 3.4 状态流转图
若发现页面中存在状态字段（如 status / orderState），生成状态机：
```mermaid
stateDiagram-v2
[*] --> 待审核
待审核 --> 已通过: 审核通过
待审核 --> 已驳回: 审核驳回
已驳回 --> 待审核: 重新提交
```
### Step 4：按受众组装文档
**Backend 视角文档** `docs/<模块>/backend.md`：
```markdown
# <模块中文名> · 后端接口文档
## 一、模块概述
（一段话 + 实体关系图）
## 二、实体定义（ER 视角）
- 实体 1：员工营养记录 EmployeeNutritionRecord
- 字段表（含类型、约束）
- 字段在哪些接口出现
## 三、接口清单
- 按接口路径排序，每个接口含：路径、方法、请求、响应、错误码
## 四、ApiResponse 约定
（统一响应包装格式说明）
## 五、字典编码
（页面用到的所有下拉选项 value，建议作为后端字典编码）
```
**QA 视角文档** `docs/<模块>/qa.md`：
```markdown
# <模块中文名> · 测试参考文档
## 一、模块功能清单
- 列出每个页面的功能点
## 二、字段校验规则
- 每个搜索 / 编辑字段的：必填、长度、格式、特殊值
## 三、状态流转
（状态机图 + 每个状态的允许操作）
## 四、关键操作流程
（含用户路径与期望结果）
## 五、边界用例
- 空数据态
- 大数据量（分页、滚动）
- 列冻结 + 横向滚动一致性
- 网络异常态（loading / error / empty）
## 六、跨页面联动
- A 页面操作后，B 页面是否同步？
```
**Mobile 视角文档** `docs/<模块>/mobile.md`：
```markdown
# <模块中文名> · 移动端开发参考
## 一、对应移动端页面映射
- Web 端 列表页 ↔ 移动端 哪些页面
## 二、字段精简建议
- Web 端 14 列 → 移动端建议保留哪 5-6 个核心字段
## 三、操作差异
- Web 端"鼠标 hover"→ 移动端"长按"
- Web 端"批量勾选"→ 移动端建议改为"多选模式切换"
## 四、共享 API
（与 Web 端共用后端接口的清单）
```
### Step 5：写入文件
落地路径：
```
src/docs/<模块路径>/
├── backend.md
├── qa.md
├── mobile.md
└── overview.md # 综合版（all 时生成）
```
写入前检查已有文件，若存在询问"是否覆盖 / 增量更新"。
## 输出物
- 1-4 个 markdown 文件（按受众）
- 终端打印文件路径与摘要
## 工具约束
`Read, Glob, Grep, Write` — 仅 Write 创建文档文件，**不可** Edit 原型代码。
禁止使用：`Edit, NotebookEdit`
## 注意事项
- 文档必须基于实际代码生成，禁止凭空构造接口或字段
- 状态流转图必须能从代码或 PRD 中找到依据
- 接口路径与 api/index.ts 中的 `@接口路径` 注释保持完全一致
- 字段类型必须使用 TypeScript 字面量（与 types/index.ts 一致），不自行翻译为 Java 类型
- 若代码与 PRD 不一致，优先采用代码并在文档末尾"差异说明"中列出
- 生成完毕提醒用户：本文档基于原型源代码，若原型迭代请重新生成
.claude/agents/prototype-reviewer.md
+165
View File
@@ -0,0 +1,165 @@
---
name: prototype-reviewer
description: 综合评审原型 PR / 一次性提交的变更。同时跑规范检查、菜单同步、字段一致性、PRD 对齐度，给出一份分级评审报告。当主 Claude 接到"评审这次原型变更"、"prototype review"、"看下这个 PR 改的怎么样" 等任务时使用。
tools: Read, Glob, Grep, Bash
---
# Agent: 原型综合评审员
## 定位
不是写代码的 Agent，是**只读评审**型 Agent。综合 `prototype-lint` / `sync-nav` / `gen-fields` 三个 skill 的能力，外加跨文件一致性与业务合理性判断，给出一份可直接用于 PR 评论的报告。
## 何时调用
主 Claude 在以下场景应优先 spawn 本 Agent，而不是自己评审：
1. 用户说"评审这次变更"、"review 一下"、"看看代码质量"
2. 用户即将提交 PR 或 git commit，希望先自检
3. 一次性新增 / 修改了 3 个以上原型页面，担心整体一致性
4. 想知道"这次改动有没有影响其他模块"
## 输入
- **评审范围**（必须）：
- `--diff` 模式：基于 `git diff` 评审本次未提交变更（默认）
- `--branch <name>` 模式：评审某个分支相对 master 的全部变更
- `--paths <glob>` 模式：评审指定路径（如 `src/pages/web-admin/nutrition/**`）
- **PRD 对照文件**（可选）：如 `docs/nutrition-prd.md`，用于检查字段是否与 PRD 一致
## 评审维度
### 1. 规范符合度（参考 prototype-lint 全部检查项）
- 目录结构、模板层、init 文件、types、api、公共组件使用
### 2. 菜单一致性（参考 sync-nav）
- 孤儿页面 / 死引用 / 命名不规范
### 3. 字段一致性
- types/index.ts 主实体字段 ↔ useTable.ts columns.dataIndex ↔ useSearch.ts filterFields.name 三者对齐
- api/index.ts 接口参数类型 ↔ types/index.ts Params 类型
### 4. 跨模块影响
- 本次变更是否动了 `src/components/`（公共组件）→ 列出受影响的页面
- 本次变更是否动了 `src/meta/nav.ts` → 列出菜单结构变化
- 本次变更是否动了 `src/layouts/` → 列出布局变化（影响所有页面）
### 5. PRD 对齐度（若提供 PRD）
- 字段名 / 中文标题 / 必填规则 / 默认值 是否与 PRD 表述一致
- 操作按钮（导出、批量操作等）是否覆盖 PRD 描述的全部操作
### 6. 经验性提示
- 列宽合计是否过宽（建议横向滚动而非压缩列宽 < 60px）
- 是否有列没有声明 `width`（会自动等分，可能不符合 PRD）
- 是否有 `fixed: 'right'` 操作列但宽度 < 90px（按钮易换行）
- 搜索字段超过 6 个时建议折叠（用户体验提示）
## 执行流程
### Step 1：确定变更范围
```bash
# 默认 diff 模式
git diff --name-only HEAD
# branch 模式
git diff --name-only master..HEAD
# paths 模式：直接 Glob
```
输出变更文件列表。
### Step 2：分类变更文件
| 文件类型 | 说明 |
|---------|------|
| 页面新增 | `src/pages/<新目录>/*` 全部新文件 |
| 页面修改 | 已有页面目录内的文件 |
| 公共变更 | `src/components/ | src/layouts/ | src/meta/nav.ts` |
| 配置变更 | `vite.config.ts / tsconfig.json / package.json` |
### Step 3：按文件类型分别评审
- **页面新增**：跑全部 lint 检查项 + 字段一致性 + PRD 对照
- **页面修改**：增量评审改动行，特别关注是否新增了反模式
- **公共变更**：分析爆炸半径，列出受影响的所有页面（Grep 引用关系）
- **配置变更**：单独 highlight，建议人工审核
### Step 4：汇总报告
```markdown
# 原型评审报告（PR / 当前未提交变更）
> 评审时间：YYYY-MM-DD HH:mm
> 变更范围：6 个文件（新增 2 个页面 + 改了 1 个公共组件 + 改了 nav.ts）
## 📊 总览评分
| 维度 | 评分 | 说明 |
|------|------|------|
| 规范符合度 | 🟢 4/5 | 仅 1 处 any 类型 |
| 菜单一致性 | 🟢 5/5 | 无孤儿 / 死引用 |
| 字段一致性 | 🟡 3/5 | 1 处 columns 字段在 types 中未声明 |
| 跨模块影响 | 🔴 需关注 | 修改了 StatCard.vue，影响 8 个页面 |
| PRD 对齐 | 🟢 5/5 | 字段命名与 PRD 一致 |
## 🔴 阻塞项（必须修复后再合并）
1. **公共组件 StatCard.vue 改动**（src/components/StatCard.vue）
- 修改了 `color` prop 的可选值，移除了 `red`
- 影响：以下页面使用了 `color="red"` 会显示异常
- pages/web-admin/health-monitor/exception/exception.vue:23
- pages/web-admin/emergency-dispatch/serious-illness/serious-illness.vue:45
- **建议**：保留 `red`，或同步修改受影响页面
## 🟡 改进项（建议修复，不阻塞）
1. **字段不一致**：arcUnit 的 columns 中 dataIndex='manager' 在 EmployeeUnitRecord 中未声明
2. **缺类型注解**：farmHarvest/init/useTable.ts:8 的 columns 缺少 TableColumnsType 注解
...
## 🟢 提示（仅供参考）
1. 列宽合计 1640px，建议横向滚动
2. 搜索字段 8 个，建议增加"高级筛选"折叠按钮
## ✅ 已通过
- 所有新增页面均符合 init 三件套结构
- 所有页面均已注册到 nav.ts
- 类型定义集中在 types/index.ts，无散落
```
### Step 5：交付给主 Claude
不直接修改任何文件，只输出报告。主 Claude 收到后可选择：
- 把报告作为最终答复返回用户
- 询问用户"是否一键修复 N 个 warning？"
- 主动调用 prototype-lint 自动修复白名单内的项
## 输出物
完整 Markdown 评审报告（建议主 Claude 直接呈现给用户）。
## 工具约束
只读：`Read / Glob / Grep / Bash (only for git diff)`
禁止使用：`Edit / Write / NotebookEdit`
理由：评审 Agent 不应直接改代码。若发现需修复的问题，由主 Claude 决定如何应对。
## 注意事项
- 评审 Agent 应**穷尽全部维度**，不要因为某个维度 OK 就跳过其他维度
- 报告要分级：阻塞 / 改进 / 提示 三档，便于决策
- 跨模块影响分析必须使用 Grep 实际查找引用，禁止凭空判断
- 不要给出主观的"代码风格建议"（如变量命名口味）；只对**有客观依据的规范**给意见
.claude/memory/MEMORY.md
+23
View File
@@ -0,0 +1,23 @@
# 记忆索引
> **单一基准**：此目录是唯一权威来源，其他位置的记忆以此为准同步。
> _Last synced: 2026-06-04 | 阶段 16 完成（智养餐饮平台V3 业务清单 + Home.vue 视觉重做）_
| 文件 | 描述 | 类型 | 更新日期 |
|------|------|------|----------|
| project_overview.md | 项目技术栈、四端架构、与正式工程关系 | project | 2026-06-04 |
| project_progress.md | 1-15 阶段完成情况、当前状态、下一步 | project | 2026-06-04 |
| decisions.md | 关键决策：Vue 工程化、菜单单源、init 三件套、四端架构、门禁、可见性、PRD、总览 | project | 2026-06-04 |
| feedback.md | 协作规范、用户偏好、已避免的反模式 | feedback | 2026-06-04 |
| user_profile.md | 用户画像（产品经理 + AI 协作） | user | 2026-06-04 |
## 必读优先级
1. `decisions.md` — 避免重新讨论已决事项
2. `feedback.md` — 避免重犯已纠正的错误
3. `project_progress.md` — 避免重复已完成工作
## 按需加载
- `project_overview.md` — 涉及架构 / 技术栈讨论时
- `user_profile.md` — 个性化回复时
.claude/memory/decisions.md
+258
View File
@@ -0,0 +1,258 @@
---
name: 关键决策与架构约定
description: 记录本原型工程的核心决策，避免跨会话重新讨论
metadata:
type: project
last_updated: 2026-06-04
---
## 1. 采用 Vue 工程化原型（替代原 HTML 自包含方案）
**结论**：原型工程采用 Vue 3 + Vite + Ant Design Vue + Vant，是真正的 SPA 工程。
**Why**：用户 2026-06-03 明确撤销了墨刀约束，技术栈与正式工程 `platform-vue-tenant` 对齐，让 AI 还原代码近乎零创造性。
---
## 2. 四个终端架构
**结论**：
| 终端 | key | UI 库 | 主要用户 |
|------|-----|-------|---------|
| 综合管理后台 | `admin-portal` | Ant Design Vue | 平台管理员 |
| 租户运营后台 | `tenant-portal` | Ant Design Vue | 租户运营 |
| C 端微信小程序 | `miniprogram` | Vant 4（375×812） | 终端用户 |
| 硬件终端屏 | `hardware` | 自定义动态 viewport | 现场操作 |
**Why**：用户 2026-06-04 明确"新项目中有四个终端"。两个后台都用 AntDV 但业务边界不同（平台层 vs 业务层）。硬件含多种设备（净菜柜屏 / 大屏 / PAD），每种 viewport 不一致 → 由 `NavHardwareDevice.viewport` 字段独立声明，HardwareLayout 动态渲染。
---
## 3. 菜单数据单一来源（src/meta/nav.ts）
**结论**：`adminPortalModules / tenantPortalModules / miniprogramTabs / hardwareDevices` 四个数组是所有路由 + 菜单的唯一数据源。
**Why**：菜单变更只改一处，路由自动派生，所有 Layout 自动重渲。
---
## 4. 列表页固定为"init 三件套"6 文件结构
**结论**：`<页面>.vue + types + api + init/(usePage + useSearch + useTable)`。
**Why**：与正式工程目录结构 100% 同构，AI 还原成本接近零。
---
## 5. Mock 数据直接写在 useTable.ts
**结论**：原型 mock 数据写 `init/useTable.ts` 的 dataList 数组，**不引入 MockJS**。
---
## 6. 不引入 Pinia
**结论**：原型阶段不引入 Pinia 等全局状态管理。
---
## 7. 双密码门禁 + 7 天有效期（阶段 11）
**结论**：
- 部署后访问需密码。两套密码：`designer` 和 `dev`（在 `.env` 中配置）
- 登录后写入 localStorage，**7 天 TTL**，过期自动跳回门禁页
- 路由守卫强制：未登录 → `/gate`；已登录 → 放行
- `/gate` 页面**简洁纯白居中**风格
**Why**：用户 2026-06-04 明确"密码要有过期机制，7 天后重新登录"、"需要做两套密码"、"简洁纯白居中"。
---
## 8. NavLeaf 加 status + audience，可见性过滤（阶段 10）
**结论**：每个 `NavLeaf` 可选字段：
- `status?: 'draft' | 'review' | 'ready'`（默认 ready）
- `audience?: 'designer' | 'all'`（默认 all）
研发角色（dev）看不到 `status='draft'` 或 `audience='designer'` 的页面。
设计师角色（designer）看到全部。
`useVisibility` composable 提供过滤函数；Sidebar / Home / Miniprogram / Hardware Layouts 都自动应用。
---
## 9. 设计完成度控制台（阶段 12，纯展示）
**结论**：`/__console` 路由，仅 designer 可访问。
- 列出全部叶子页面 + status + audience + 当前对 dev 是否可见
- 支持单页面覆写（存 localStorage `visibility.overrides`）
- **不修改 nav.ts 源代码**（用户 2026-06-04 选 A：纯展示控制台手动同步）
- 支持"清除单行覆写"和"重置全部覆写"
---
## 10. PRD 在线查看（阶段 13）
**结论**：
- 路由 `/__prd`，所有登录角色都可访问
- 自动收集 `src/prd/**/*.md` 作为目录树
- markdown-it 渲染，含表格 / 代码 / blockquote / 自动图片解析
- 截图存在 `src/prd/<端>/<模块>/screenshots/<页面>/<状态>.jpg`
---
## 11. 截图工具优先级与体积限制（阶段 14）
**结论**：
| 类别 | 视口 | DPR | 体积上限 |
|------|------|-----|---------|
| Web 后台 | 1440 × 900 | 1 | ≤ 60KB |
| 小程序 | 375 × 812 | 2 | ≤ 60KB |
| 硬件 | 按设备 viewport | 1 | ≤ 80KB |
- **优先 puppeteer**；失真或尺寸不对时降级 chrome-devtools MCP
- 输出 jpeg q=85；超限时降 quality 或缩尺寸
**Why**：用户 2026-06-04 明确"优先使用 puppeteer，puppeteer 截图失真或者尺寸不对时再用 chrome-devtools MCP"。
---
## 12. 设计总览仅小程序 / 硬件（阶段 14 + 阶段 17 重构）
**结论**：
- 路由 `/__overview` 是**截图浏览器**：把 PRD 目录中的所有截图（含弹窗、状态变体）平铺到一页，给 UI 设计岗评审
- 数据源：`src/prd/<端>/<模块>/screenshots/<页面>/<状态>.{jpg,jpeg,png}`，用 `import.meta.glob` 自动收集
- 命名解析：
- `default.*` → 默认状态（无标签）
- `modal-*` / `dialog-*` / `popup-*` → **弹窗**（橙色 tag--modal）
- `state-*` / `tab-*` / `empty` / `loading` / `error` / `expanded` / `collapsed` → **状态变体**（蓝色 tag--state）
- 视觉风格完全参考原 `platform-prototype/_templates/design-overview-template.html`：暗色背景 + sticky 顶部导航 + 横向滚动卡片 + 灯箱放大 + 模块锚点
- 仅小程序、硬件，**不做后台**（用 PRD 替代）
**Why**：用户 2026-06-04 明确"设计总览只做小程序和硬件"；阶段 17 进一步澄清"使用 PRD 文档的截图平铺到一个页面中，截图要包含所有的页面、弹窗、同页面的不同形态"。
**How to apply**：
- `/design-overview` skill 负责"截图 + 命名 + 落地到 PRD 目录"
- `/__overview` 页面负责"读取 + 分组 + 灯箱"
- 体积上限：小程序 ≤ 60KB、硬件 ≤ 80KB；优先 puppeteer 截图，失真时降级 chrome-devtools MCP
---
## 13. 业务架构文档（src/docs/business-architecture.md）
**结论**：在项目根目录建一份业务架构文档，含四端定位、用户角色映射、各端模块清单、跨端协作关系。
**Why**：用户 2026-06-04 提到"还需要在项目目录下新建一个业务架构的描述文档，方便后期在生成原型时 AI 对目录规划和业务理解"。AI 在 new-page / gen-prd / cross-role-doc-builder 等任务前必读。
---
## 14. dev server 端口 5180
避开正式工程 7000-7009 端口。
---
## 15. 主题色 #1890FF
与正式工程、原 HTML 原型一致。
---
## 16. 工具路由命名约定（带 `__` 前缀）
**结论**：所有"非业务"工具路由用 `__` 前缀，便于人眼区分、防止与业务模块 key 冲突。
清单：
- `/gate` — 门禁页（特殊：唯一无 `__` 前缀且 `meta.public: true`）
- `/__console` — 设计完成度控制台
- `/__prd` — PRD 查看
- `/__overview` — 设计总览
---
## 17. 公共组件清单（阶段三沉淀）
- `StatCard` — 统计卡（4 色配色）
- `FilterBar` — 配置驱动搜索栏
- `TableCard` — 表格卡（透传 a-table 全部 slots）
- `PageHeader` — 页头
- `RoleBadge` — 顶部角色徽章（layouts/components 下）
---
## 18. 项目专属 skills / agents 清单
| 类型 | 名称 | 用途 |
|------|------|------|
| skill | new-page | 新建原型页面脚手架 |
| skill | gen-fields | 生成单页字段清单 |
| skill | gen-prd | 生成 PRD 文档 + 截图 |
| skill | design-overview | 设计总览（仅小程序/硬件） |
| skill | sync-nav | 菜单同步检查 |
| skill | prototype-lint | 代码规范 + 截图体积检查 |
| agent | prototype-reviewer | PR / 变更综合评审（只读） |
| agent | cross-role-doc-builder | 模块级跨岗位文档包 |
---
## 19. 项目名：智养餐饮平台V3（阶段 16）
**结论**：项目正式名称为"智养餐饮平台V3"，原"健康CQ升级"是早期占位。所有 UI 文案与文档统一使用新名称。
**Why**：用户 2026-06-04 提供。
**How to apply**：CLAUDE.md / Home 标题 / Gate 标题 / 记忆文件均使用"智养餐饮平台V3"。
---
## 20. 业务清单填充（阶段 16）
**结论**：用户给出四端粗粒度功能清单：
- **综合管理后台**：系统设置、运营中心、设备中心
- **租户运营后台**（18 模块）：租户首页、控制台、系统管理、营养管理、健康体检、体重管理、运动管理、健康监测、健康评估、知识普及、健康数据、健康档案、心脑血管病预防、糖尿病预防、癌症预防、专家咨询、应急就医、一线医疗
- **微信小程序**（4 Tab）：吃、问、做、我
- **硬件终端屏**（10 类设备）：智能货柜、档口机、入库秤、营养秤、吐盘机、结算台、配比秤、带鱼屏、统计大屏、炒菜机器人
均以 `status: 'draft'` 占位接入 nav.ts；营养管理保留 arcEmployee 样板为 ready。
**How to apply**：
- 每个模块的具体二级菜单由用户规划后用 `/new-page` skill 生成
- 业务架构文档 `src/docs/business-architecture.md` 已同步此清单
- 占位页文件实际存在（不是简单的通用占位组件），便于将来直接替换内容
---
## 21. Home.vue 视觉：参考原 platform-prototype/index.html（阶段 16）
**结论**：Home.vue 视觉效果**完全参考原 HTML 原型项目的 index.html**：
- 顶部渐变 Header（紫蓝 → 蓝 → 浅蓝）
- Tab 嵌入 Header 底部（圆角胶囊式 + 玻璃态 + 计数徽章）
- 模块卡片网格：左名称 + 右状态徽章 + 底部 PRD 链接 + 页数徽章
- 卡片状态色：ready 绿色呼吸灯 / wip 黄色 / empty 灰色虚线圆形水印
- 右上角悬浮：📄 PRD / 🖼 总览 / 🎛 控制台 / 角色徽章
**Why**：用户 2026-06-04 明确"整个原型项目的引导页的布局我希望你完全参考之前的原型项目的 index 页面的布局重新设计"。
**How to apply**：禁止把首页改成 a-tabs 等 AntDV 通用风格；保持渐变 + 胶囊 Tab + 卡片视觉。
---
## 22. RoleBadge 控制台独立按钮（阶段 16）
**结论**：设计模式下，控制台入口从下拉菜单升级为顶部独立按钮 `🎛 控制台`（橙色高亮）；下拉菜单仅保留"退出登录"。
**Why**：用户 2026-06-04 明确"设计模式下右上角比之前多个控制台"。
**How to apply**：`RoleBadge.vue` 中通过 `v-if="role === 'designer'"` 渲染该按钮。研发模式下不可见。
.claude/memory/feedback.md
+187
View File
@@ -0,0 +1,187 @@
---
name: 协作规范与用户纠正
description: 记录与用户协作的偏好、风格、已纠正的反模式
metadata:
type: feedback
last_updated: 2026-06-03
---
## 1. 简体中文优先
**规则**：所有与用户对话、所有代码注释一律使用简体中文。
**Why**：用户为中文母语，团队规范要求。
**How to apply**：永远不要用英文回复（除非涉及代码标识符）；所有注释中文。
---
## 2. 分阶段执行 + 阶段汇报
**规则**：涉及多步骤任务时，先列阶段任务清单等用户确认，再分阶段执行，每个阶段完成后汇报、等待用户决定继续或验收。
**Why**：用户偏好掌握节奏；避免单次性输出过长内容难以验收。
**How to apply**：
- 大任务用 TodoWrite 拆分跟踪
- 每个阶段完成后用"汇报 + 是否继续"的格式
- 用户说"全部跑完"等明确授权时，可以一口气完成，但仍要每阶段简短汇报
---
## 3. 设计先对齐，再写代码
**规则**：涉及抽象设计 / 架构调整 / 新模块时，先用文字 + Mermaid 图给出设计方案，等用户确认后再写代码。
**Why**：来自用户全局 CLAUDE.md 的强制要求。
**How to apply**：
- 给方案优先用 Mermaid 流程图 / 类图 / 时序图
- 重大决策点用表格列出选项 + 推荐 + 权衡
- 决策项过多时用 ask_user_question 提问，不要让用户做长选择题
---
## 4. 代码风格
**规则**：
- TypeScript 严格类型，禁止 `any`
- 注释只解释 WHY、不解释 WHAT
- 函数 / 变量名小驼峰；CSS 类名 BEM
- `<script setup lang="ts">` 是 .vue 文件的唯一形式
- 列表页强制 init 三件套拆分
**Why**：与正式工程对齐 + 团队规范。
**How to apply**：见 CLAUDE.md "关键约定" 章节。
---
## 5. 公共组件优先，不重复造轮子
**规则**：列表页必须使用 4 个公共组件（StatCard / FilterBar / TableCard / PageHeader）；不允许自己写 div + CSS 模拟。
**Why**：阶段三沉淀。一致性 + 维护成本。
**How to apply**：发现公共组件不够用，**提议增强**而非在页面里 fork。
---
## 6. 用户对效率与还原度的极度敏感
**规则**：用户的核心诉求是"原型 → 正式工程"的转化效率与还原度。每次方案选择都要回答这一点。
**Why**：用户 2026-06-03 多次强调"AI 还原代码效率"、"半工程化"路线、"和 vue 开发相同的技术栈和 UI 组件库"。
**How to apply**：
- 建议方案时明确指出还原度（如"95%+"、"复制粘贴即可"）
- 设计样板时优先与正式工程目录结构同构
- 当面临"轻量 vs 工程化"的取舍，倾向工程化（用户已明确"还不如直接整一个工程化的 vue 项目"）
---
## 7. 跨岗位协作物料独立沉淀
**规则**：原型代码主要给前端 + AI 用；跨岗位协作（后端 / 测试 / 移动端）通过单独的 `fields.md` 文档传递信息，而不是让别的岗位读原型代码。
**Why**：用户 2026-06-03 讨论得出的结论 — 不同岗位关注点不同，统一文档比"让他们读代码"更友好。
**How to apply**：
- 用 `/gen-fields` skill 为单页生成 fields.md
- 用 `cross-role-doc-builder` agent 为模块生成 backend.md / qa.md / mobile.md
---
## 8. 不主动加文档 / 不主动写 README
**规则**：除非用户明确要求，不主动创建 README.md、CHANGELOG.md 等文档。
**Why**：来自全局 CLAUDE.md 默认行为约束。
**How to apply**：完成代码后口头说明 + 必要时更新 CLAUDE.md / memory，不创建零散文档。
---
## 9. 文件路径使用 Windows 绝对路径
**规则**：所有文件操作（Read / Write / Edit）使用完整 Windows 绝对路径，反斜杠或正斜杠都可（但保持一致）。
**Why**：用户全局 CLAUDE.md 中明确的工具兼容性要求。
**How to apply**：
- ✅ `D:\Work\yx-platform-prototype\src\...`
- ✅ `D:/Work/yx-platform-prototype/src/...`
- ❌ `/c/Work/...` 或 `./src/...`
---
## 10. 不要急着进入"最优解"
**规则**：用户问"有没有更好的方式"时，先把每种方式的权衡说清楚，让用户基于自己情况决策，**不要立即推一个方案就开始写代码**。
**Why**：用户作为产品经理，更关心方案合理性而非快速产出。
**How to apply**：探索性问题（"有没有什么思路"）用 2-3 句话给方向 + 主要权衡 + 询问是否继续。
---
## 11. 阶段任务连续执行授权
**规则**：当用户说"全部跑完"、"先把后面的几个阶段都跑完"等明确授权时，可以一口气连续完成多阶段任务而不需每阶段都等用户回复。但**每阶段完成后仍要简短汇报**（一句话级别），并继续下一阶段。
**Why**：用户 2026-06-04 多次提"先把所有的阶段都跑完，自己检查验证"，明示信任 AI 端到端执行。
**How to apply**：
- 阶段开始：列出本阶段任务清单
- 阶段中：使用 TodoWrite 跟踪
- 阶段结束：简短汇报（不超 3 句）+ 立即进入下一阶段
- 全部完成后：做汇总总结 + 验收清单
---
## 12. 截图工具的优先级与降级策略
**规则**：截图优先 puppeteer；puppeteer 失真或尺寸不对时再用 chrome-devtools MCP。
**Why**：用户 2026-06-04 明确说"优先使用 puppeteer，puppeteer 截图失真或者尺寸不对时再用 chrome-devtools MCP，据我之前的观察 chrome-devtools MCP 截图效果可能会更好"。即 puppeteer 是默认选择，MCP 是质量备份方案。
**How to apply**：
- 在 gen-prd / design-overview skill 文档中明确这一优先级
- 实际截图任务先用 puppeteer，输出后检查质量；不达标再降级 MCP
---
## 13. 截图体积控制（强制）
**规则**：截图体积严格控制：
- Web 后台 1440×900 @1x：≤ 60KB
- 小程序 375×812 @2x：≤ 60KB
- 硬件设备（按 viewport）：≤ 80KB
- 拼图 PNG：≤ 500KB
**Why**：用户 2026-06-04 明确"一定要注意之前 prd 文档中的截图规范（控制尺寸和体积）"。原 platform-prototype 项目曾有此规范，迁移延续。
**How to apply**：
- 截图后用 Bash check size（`stat -c %s file`）
- 超限：降 quality（85→75）；仍超用 sharp 二次压缩
- prototype-lint 会扫描整个 src/prd/**/screenshots 并报告超限文件
---
## 14. 业务架构文档作为 AI 必读
**规则**：所有 new-page / gen-prd / cross-role-doc-builder 等生成原型的任务，**必须先读 `src/docs/business-architecture.md`** 理解业务上下文，禁止跨端引用。
**Why**：用户 2026-06-04 明确"还需要在项目目录下新建一个业务架构的描述文档，方便后期在生成原型时 AI 对目录规划和业务理解"。
**How to apply**：每个 skill 描述里写明"必读 src/docs/business-architecture.md"。
.claude/memory/project_overview.md
+77
View File
@@ -0,0 +1,77 @@
---
name: 项目概览与技术栈
description: 本原型工程的技术栈、四端架构、与正式工程的关系
metadata:
type: project
last_updated: 2026-06-04
---
## 定位
`yx-platform-prototype` 是智养餐饮平台V3项目的**高保真交互原型工程**。
- **服务对象**：产品经理画原型 → AI 还原成正式 Vue 工程代码 + 跨岗位文档
- **核心 KPI**：原型 → 正式工程的"复制粘贴还原度"（目标 95%+）
## 四个终端
| 终端 | key | UI 库 | 业务定位 |
|------|-----|-------|---------|
| 综合管理后台 | admin-portal | AntDV | 平台层管理（跨租户） |
| 租户运营后台 | tenant-portal | AntDV | 单租户业务运营 |
| C 端微信小程序 | miniprogram | Vant 4 (375×812) | 终端用户自助 |
| 硬件终端屏 | hardware | 自定义动态 viewport | 现场操作 / 公共展示 |
## 技术栈
| 类别 | 选型 |
|------|------|
| 框架 | Vue 3.5 + TypeScript 5.9 |
| 构建 | Vite 8 |
| Web 端 UI | Ant Design Vue 4.2 |
| 移动端 UI | Vant 4 |
| 路由 | Vue Router 4（Hash 模式） |
| 状态管理 | 不引入 Pinia |
| 样式 | LESS + CSS 变量（设计令牌） |
| 自动导入 | unplugin-auto-import + unplugin-vue-components |
| Markdown | markdown-it（PRD 渲染） |
| 截图 | puppeteer（优先）/ chrome-devtools MCP（降级） |
## 关键架构特性
1. **菜单单源**：`src/meta/nav.ts` 是路由 + 菜单的唯一数据源
2. **端隔离**：4 端不互相 import；共享通过 @components / @layouts / @meta / @composables
3. **六文件页面结构**：列表页固定 `<页面>.vue + types + api + init/(usePage + useSearch + useTable)`
4. **可见性模型**：NavLeaf.status + audience，dev 看不到 draft / designer-only 页面
5. **门禁机制**：双密码 + 7 天 TTL，路由守卫强制
6. **工具路由**：`/gate` / `/__console` / `/__prd` / `/__overview`
## 与正式工程的对照
正式工程 `D:\Work\platform-vue-tenant`（Monorepo + Qiankun）。
| 维度 | 原型工程 | 正式工程 |
|------|---------|---------|
| 工程形态 | 单 SPA | Qiankun 微前端 + Monorepo |
| 状态管理 | 无 | Pinia + 持久化 |
| 接口 | 占位 | 真 HTTP + 拦截器 + 401/403 |
| 权限 | 角色门禁 + 可见性过滤 | 菜单权限 + 按钮权限 + 动态路由 |
| Mock 数据 | useTable.ts 写死 | 无 |
| 文件结构 | **完全一致** | **完全一致** |
| 技术栈 | **完全一致** | **完全一致** |
## 部署 / 分发
- 构建：`npm run build` → `dist/`
- 静态分发：dist/ 是纯静态文件，可部署到任何静态服务
- 门禁密码可在 `.env.production` 重新定义后构建
## 跨工程引用关系
```
yx-platform-prototype/
├─ src/pages/ 原型源
├─ src/prd/ PRD markdown + 截图
├─ src/docs/ 业务架构文档
└─ AI 还原 → platform-vue-tenant/
```
.claude/memory/project_progress.md
+75
View File
@@ -0,0 +1,75 @@
---
name: 阶段进度
description: 16 阶段重构完成情况、当前状态、下一步计划
metadata:
type: project
last_updated: 2026-06-04
---
## 总体进度
✅ **16 阶段全部完成（2026-06-04）**。原型工程从 0 到 1 搭建完毕 + 四端架构 + 门禁 + 控制台 + PRD + 总览 + 智养餐饮平台V3 业务清单与首页重做。可投入日常使用。
## 阶段一览
| 阶段 | 主题 | 状态 |
|------|------|------|
| 1 | 工程骨架（Vite + Vue 3 + TS） | ✅ |
| 2 | 路由 + 菜单数据化 + 共享布局 | ✅ |
| 3 | 公共业务组件（StatCard / FilterBar / TableCard / PageHeader） | ✅ |
| 4 | 标准列表页样板（arcEmployee 六文件结构） | ✅ |
| 5 | 导航首页（首版） | ✅ |
| 6 | 项目专属 4 skill + 2 agent（首版） | ✅ |
| 7 | CLAUDE.md + 记忆体系（首版） | ✅ |
| 8 | 四端架构重构：nav.ts + 3 个 Layout + 业务架构文档 | ✅ |
| 9 | Home.vue 改为四端 Tab | ✅ |
| 10 | NavLeaf 加 status/audience + useVisibility 过滤 | ✅ |
| 11 | 双密码门禁页 + 7 天过期 | ✅ |
| 12 | VisibilityConsole 设计完成度控制台 | ✅ |
| 13 | PRD 在线查看（PrdViewer.vue） | ✅ |
| 14 | /gen-prd skill + /design-overview skill + DesignOverview.vue | ✅ |
| 15 | CLAUDE.md 详细目录说明 + lint 体积检查 + 记忆体系同步 | ✅ |
| 16 | 智养餐饮平台V3 业务清单填充 + Home.vue 视觉重做（参考原 index.html）+ RoleBadge 控制台独立按钮 | ✅ |
| 17 | DesignOverview.vue 重做为"PRD 截图浏览器" + design-overview skill 重写（命名规范 / 弹窗与状态标签 / 灯箱） | ✅ |
## 当前状态
- **项目名**：智养餐饮平台V3（原"健康CQ升级"已替换为正式名称）
- 工程可启动：`npm run dev` → http://localhost:5180
- 门禁密码：`design2026` / `dev2026`
- **nav.ts 业务清单完成度**：
- 综合管理后台：3 个一级模块（系统设置 / 运营中心 / 设备中心），各 1 个 draft 占位页
- 租户运营后台：18 个一级模块，营养管理已有样板（arcEmployee ready + 2 个 draft），其余 17 个均 draft 占位
- 微信小程序：4 个底部 Tab（吃 / 问 / 做 / 我），均 draft 占位
- 硬件终端屏：10 类设备（智能货柜 / 档口机 / 入库秤 / 营养秤 / 吐盘机 / 结算台 / 配比秤 / 带鱼屏 / 统计大屏 / 炒菜机器人），每类独立 viewport
- **首页视觉**：完全参考原 platform-prototype/index.html — 渐变 header + 嵌入式 Tab 胶囊 + 卡片网格（状态徽章/PRD/页数）+ ready 绿色呼吸灯 / wip 黄色 / empty 灰色虚线
- **右上角入口**：📄 PRD / 🖼 总览 / 🎛 控制台（仅 designer 可见独立按钮）/ 角色徽章下拉（退出登录）
## 已验证通过的端到端流程
1. 未登录 → 自动跳 `/gate`
2. 输入密码 → 设置角色 + 7 天 TTL → 跳到原目标
3. 顶部角色徽章显示"设计模式 · 7 天" + 下拉菜单（打开控制台 / 退出）
4. 四端 Tab 切换正常（admin / tenant / 小程序 / 硬件）
5. 控制台显示全部叶子页面，可单页面切换 status / audience
6. PRD 文档树自动加载，markdown-it 渲染正常
7. 设计总览 iframe 平铺渲染（小程序 2 个手机壳并排）
8. dev / build 全链路无报错
## 已知遗留事项
1. **生产 chunk 偏大**：arcEmployee 单页 chunk ~670KB（AntDV 4 ESM 未按需拆分）。大量页面后做 manualChunks 优化
2. **小程序 iframe 总览仍显示底部"返回首页"链接**：可后续增强 `?_ov=1` 模式隐藏布局外壳
3. **PRD 截图工具未自动集成**：`gen-prd` skill 说明了 puppeteer 模板，但实际截图需要主 Claude 调用工具实现
4. **PortalLayout 没有 designerOnly 路由侧边栏隐藏样式**：从 dev 视角看 `/__console` 入口被守卫拦下（已用 `v-if="role === 'designer'"` 在 RoleBadge 处理），但若 dev 直接输 URL 会被 router 守卫重定向回 `/`
## 下一步建议
按优先级：
1. **填写 `src/docs/business-architecture.md`** — 用户填充四端模块清单，AI 在生成原型时会先读
2. **画一两个真实业务页面** — 试用 `/new-page` skill 验证体验
3. **跑一次 `/gen-prd`** — 验证给后端的物料质量与截图体积控制
4. **试用 `/__overview`** — 走通设计总览给 UI 岗评审的流程
5. **存量原 HTML 原型按需迁移** — 不强求一次性
6. **chunk 优化**（积累 20+ 页面后做）
.claude/memory/user_profile.md
+58
View File
@@ -0,0 +1,58 @@
---
name: 用户画像
description: 用户角色、协作风格、技能背景
metadata:
type: user
last_updated: 2026-06-03
---
## 角色
**产品经理**（软件公司）
## 工作流
- 通过 Claude Code 画原型 → AI 还原代码 → Vue 开发参考实现
- 经历过纯 HTML 原型阶段，已意识到"原型与正式工程脱节"的痛点
- 2026-06-03 主导了原型工程从 HTML 迁移到 Vue 工程化的决策
## 技术背景
- **熟练**：原型设计、PRD 编写、业务建模、需求拆解
- **了解**：基本前端概念（Vue / 组件 / 路由）、npm 命令
- **不熟练**：TypeScript 深度类型、Vite 内部机制、复杂工程化配置
- **不需要**：手写代码（依靠 AI 完成）
→ **协作策略**：写代码这件事完全交给 AI；用户负责设计决策、验收、走通日常使用流程。文档要避免"写完即过期"的细节，应聚焦"为什么这么做、怎么用"。
## 沟通偏好
- 简体中文
- 简洁、有结构（表格 / 列表）
- 重要决策要列表对比 + 推荐 + 权衡
- 不喜欢长篇大论的解释；喜欢"先方案后实施"的节奏
- 不喜欢被推到"二选一陷阱"；喜欢"建议 X，但你可以选 Y/Z"
## 关键工作场景
1. **画新原型**：会用 `/new-page` skill 快速生成骨架
2. **改原型字段**：直接改 useTable.ts 的 columns 与 dataList
3. **跨岗位同步**：用 `/gen-fields` 或 `cross-role-doc-builder` 生成文档分享
4. **PR 自检**：用 `prototype-reviewer` agent 做综合评审
5. **AI 还原代码**：把原型整个目录提供给前端开发的 AI
## 工作时间习惯
- 2026-06-03 16:00 左右说"快要下班了，明天再验收"
- 推测工作时间：常规上班时间（9-18 / 10-19）
## 协作中的明确表达
用户在本次会话（2026-06-03）的重要表达：
- "我感觉搞成这种了还不如直接整一个工程化的 vue 项目"（否定了 sfc-loader 中间方案）
- "如果我直接将原型的绘制方式从之前的 HTML 迁移至 vue 框架，对于服务端（java）或者是测试岗，移动端有没有什么影响"（关注跨岗位）
- "技术选型上是否考虑今天提到的原型其实可以走半工程化路线（不是强制，需要你给出最优解）"（鼓励 AI 给最优解、不必拘泥用户表面提议）
- "你先全部把后面的几个阶段跑完吧，我快要下班了"（信任 AI 端到端完成执行）
→ **判断依据**：用户**信任 AI 的工程判断**，但需要在关键决策点（选型、阶段拆分、目录结构）有清晰对齐。
.claude/skills/design-overview.md
+200
View File
@@ -0,0 +1,200 @@
---
name: design-overview
description: 把一个端 / 模块所有页面 + 弹窗 + 状态变体截图平铺到一个页面，交付给 UI 设计岗评审。截图来自 PRD 目录 src/prd/**/screenshots，按"端 → 模块 → 页面 → 状态"4 层组织，弹窗与状态变体分别用橙色 / 蓝色标签区分。在线查看页 /__overview 自动渲染。当用户说"生成 xx 的设计总览"、"截一组截图给 UI"、"design-overview xx" 时触发。
---
# Skill: 页面设计总览
## 用途定位
**交付物**：给 UI 设计岗评审用的"一页式截图墙"，包含一个模块（或一个端）下：
- 所有页面的默认状态
- 每个页面的全部弹窗（modal / dialog / popup）
- 每个页面的状态变体（empty / loading / error / tab 切换 / 展开收起 …）
UI 岗一眼能看完整模块视觉，不用切换页面。
> 与 PRD 文档的区别：PRD 关注字段/接口/操作；设计总览只关注**截图视觉**。两者共享同一 `screenshots/` 目录。
## 触发场景
- 模块原型画完，需要给 UI 评审
- 调整了视觉风格，要重新出一份总览给 UI 复检
- 弹窗 / 状态变体多，散落在 PRD 各段不便整体看
## 输入参数
1. **端**（必须）：`miniprogram` 或 `hardware`（**仅这两个端**；Web 后台用 PRD 查看代替，详见决策 22）
2. **模块**（可选）：如 `eat`（小程序）或 `smart-cabinet`（硬件）；不传 = 整个端
3. **截图状态清单**（必须）：要包含的状态，至少有 `default`，其余按页面定（如 `search-active` / `modal-confirm` / `empty`）
## 执行流程
### Step 1：读业务架构与现有 PRD
必读：
- `src/docs/business-architecture.md`（理解模块在端中的位置）
- `src/prd/<端>/<模块>/*.md`（已有页面清单与截图引用）
确认要补截图的页面集合。
### Step 2：截图（核心）
**目标路径统一**：`src/prd/<端>/<模块>/screenshots/<页面 path>/<状态>.jpg`
例如：
```
src/prd/miniprogram/eat/screenshots/home/default.jpg
src/prd/miniprogram/eat/screenshots/home/modal-confirm.jpg
src/prd/miniprogram/eat/screenshots/home/empty.jpg
src/prd/miniprogram/eat/screenshots/order/default.jpg
src/prd/miniprogram/eat/screenshots/order/state-paid.jpg
```
#### 视口规范（必须严格执行）
| 端 | 视口 | DPR | 输出 | 体积上限 |
|----|------|-----|------|---------|
| miniprogram | 375 × 812 | 2 | jpeg q=85 | **≤ 60KB** |
| hardware（按设备） | 见 `nav.ts` 的 `viewport` 字段 | 1 | jpeg q=80 | **≤ 80KB** |
#### 工具优先级
1. **puppeteer**（首选）—— 输出质量稳定
2. **chrome-devtools MCP**（降级）—— puppeteer 失真或尺寸不对时使用
#### puppeteer 截图模板
```js
import puppeteer from 'puppeteer'
const browser = await puppeteer.launch({ headless: 'new' })
const page = await browser.newPage()
// 小程序：iPhone X 规格 @2x
await page.setViewport({ width: 375, height: 812, deviceScaleFactor: 2 })
await page.goto('http://localhost:5180/#/miniprogram/eat', { waitUntil: 'networkidle0' })
// 等待小程序壳渲染完毕
await page.waitForSelector('.phone-shell__content > *')
// 仅截"内容区"（不截整个手机壳）
const content = await page.$('.phone-shell__content')
await content.screenshot({
path: 'src/prd/miniprogram/eat/screenshots/home/default.jpg',
type: 'jpeg',
quality: 85,
})
// 触发弹窗状态再截
await page.click('[data-test="confirm-btn"]')
await page.waitForSelector('.modal-confirm')
await content.screenshot({
path: 'src/prd/miniprogram/eat/screenshots/home/modal-confirm.jpg',
type: 'jpeg',
quality: 85,
})
await browser.close()
```
#### chrome-devtools MCP 降级路径
仅当 puppeteer 输出尺寸不对 / 文字模糊时切换：
```
1. mcp__chrome-devtools__resize_page → width=375 height=812
2. mcp__chrome-devtools__navigate_page → URL
3. mcp__chrome-devtools__wait_for / click → 触发状态
4. mcp__chrome-devtools__take_screenshot → format=jpeg quality=85 filePath=...
```
#### 体积控制
每张截图保存后立即检查：
```bash
stat -c %s src/prd/.../<状态>.jpg
```
- 超 60KB（小程序）/ 80KB（硬件）→ 降 quality (85→75) 重截
- 仍超 → `npx sharp -i in.jpg -o out.jpg --quality 70`
- 仍超 → 检查是否长截图溢出（应只截视口）
### Step 3：命名规范（严格）
文件名 = **状态 key**，决定视觉分类标签：
| 文件名前缀 / 关键词 | 类型 | 总览页标签颜色 |
|--------------------|------|---------------|
| `default.jpg` / 模块入口 | 默认状态 | 无标签 |
| `modal-<名>.jpg` / `dialog-<名>.jpg` / `popup-<名>.jpg` | 弹窗 | **橙色 tag--modal** |
| `state-<名>.jpg` / `tab-<名>.jpg` / `empty.jpg` / `loading.jpg` / `error.jpg` / `expanded.jpg` / `collapsed.jpg` | 状态变体 | **蓝色 tag--state** |
| 其他自定义 | 其他变体 | 蓝色 tag--state |
总览页 `/__overview` 自动按命名解析 + 渲染标签，**不需要额外配置文件**。
### Step 4：在线查看
完成截图后，访问：
```
http://localhost:5180/#/__overview?portal=<端>&module=<模块>
```
如：
```
http://localhost:5180/#/__overview?portal=miniprogram&module=eat
```
页面布局参考原 platform-prototype/_templates/design-overview-template.html：
- 暗色背景 `#1a1a2e`
- 顶部 sticky 导航 + 模块锚点
- 按"页面"分小组，每组横向滚动卡片
- 每张卡 260×564（小程序）/ 比例缩略（硬件）
- 弹窗橙标、状态变体蓝标
- 点击卡片灯箱放大
### Step 5：检查清单
交付前自检：
- [ ] 模块下每个页面**至少**有 `default.jpg`
- [ ] 重要弹窗都有截图，命名 `modal-<名>.jpg`
- [ ] 关键状态变体覆盖完整（空数据 / 加载 / 错误 / 主要 tab）
- [ ] 单图体积全部达标
- [ ] 总览页 `/__overview?portal=...&module=...` 渲染正常，无缺图占位
### Step 6：交付提示
打印：
- 截图清单（路径 + 体积）
- 总图数 / 弹窗数 / 状态变体数
- 在线查看 URL
## 输出物
- `src/prd/<端>/<模块>/screenshots/<页面 path>/<状态>.jpg` （多张）
- 终端打印检查清单
## 禁止事项
- **禁止给 Web 后台**（admin / tenant）生成设计总览（用 PRD 替代）
- 禁止超过 60KB / 80KB 体积上限
- 禁止把截图存到 `src/prd/<端>/<模块>/screenshots/` 之外
- 禁止用截图脚本控制设备屏幕外尺寸（必须严格按 viewport）
- 禁止跨模块共享同一截图（每个模块独立 screenshots 目录）
## 注意事项
- 截图前确保 dev server 运行，且**已登录 designer 模式**（否则部分 draft 页被过滤）
- 弹窗截图时点击触发后用 `waitForSelector` 等真实弹窗 DOM 出现，避免拍到过渡态
- 硬件设备视口往往超大（1080×1920 / 1920×1080 / 3840×1080），puppeteer 必须设对应 viewport
- 截图前后**不要修改**布局组件（Layout / phone-shell），否则边距错位
- 总览页是"静态截图浏览器"，不会调起业务页面 — 截图缺失就是缺失，必须先截
.claude/skills/gen-fields.md
+180
View File
@@ -0,0 +1,180 @@
---
name: gen-fields
description: 扫描指定原型页面的 useTable.ts 与 useSearch.ts，反向提取字段语义，生成跨岗位协作用的 fields.md 字段清单（含表格列字段、搜索字段、接口契约、操作流程），供后端 / 测试 / 移动端开发参考。当用户说"生成字段清单"、"gen-fields xxx"、"给 xxx 出一份接口文档" 时触发。
---
# Skill: 反向生成跨岗位字段清单
## 触发场景
原型页面已经画完，需要把"字段语义"沉淀成结构化文档，给后端写接口、测试写用例、移动端开发参考。
## 输入参数
1. **目标页面路径**：相对 `src/pages/` 的完整路径，例如 `tenant-portal/nutrition/arc/arcEmployee`（4 端 / NavApp / NavSection / 页面）
2. **是否覆盖已有 fields.md**：默认 `false`，发现冲突时询问用户
## 执行流程
### Step 1：定位页面文件
读取以下文件：
- `src/pages/<路径>/<页面key>.vue` — 模板层，提取页面标题、子组件用法
- `src/pages/<路径>/types/index.ts` — 类型定义，提取实体接口（如 EmployeeNutritionRecord）
- `src/pages/<路径>/api/index.ts` — 接口契约
- `src/pages/<路径>/init/useTable.ts` — 表格列
- `src/pages/<路径>/init/useSearch.ts` — 搜索字段
- `src/pages/<路径>/init/usePage.ts` — 页面级行为
任一文件缺失则提示用户并继续（部分页面如详情页可能没有 useTable）。
### Step 2：提取字段语义
**从 `useTable.ts` 的 columns 数组提取**：
| 提取项 | 来源 |
|--------|------|
| 字段名 | `dataIndex` |
| 中文标题 | `title` |
| 列宽 | `width` |
| 是否冻结 | `fixed: 'left'/'right'` |
| 自定义渲染 | `key` 字段（在模板 bodyCell 中找规则） |
**从 `useSearch.ts` 的 filterFields 数组提取**：
| 提取项 | 来源 |
|--------|------|
| 字段名 | `name` |
| 标签 | `label` |
| 控件类型 | `type` |
| 必填规则 | （从 placeholder 启发，原型阶段大多无强制规则） |
| 下拉选项 | `options`（从 useSearch.ts 同文件 unitOptions 等取） |
**从 `types/index.ts` 提取**：
- 主实体 interface 的全部字段类型（含 TS 类型）
- 与 columns 对齐补充字段说明
**从 `api/index.ts` 提取**：
- 接口路径、请求方法
- 请求 / 响应类型
### Step 3：生成 fields.md
写入路径：`src/docs/<portal>/<app>/<section 短名>/<页面key>.md`（镜像 pages 目录结构）
> 注意：新规范下列表页不再有 PageHeader，因此生成文档时**不要**从 vue 模板里抓取标题——以 nav.ts 中的 leaf.label 为准。
文档结构：
```markdown
# <页面中文名>
> 自动生成于 YYYY-MM-DD，对应原型路径 `src/pages/<路径>`
## 一、页面概览
- **业务定位**：<从 PRD / 页面标题推断的一段说明>
- **路由路径**：`/<端>/<模块>/<路由>`
- **页面类型**：列表页 / 详情页 / 弹窗
## 二、接口契约
| 用途 | 方法 | 路径 | 请求参数 | 响应 |
|------|------|------|---------|------|
| 分页查询 | POST | /nutrition/employee/page | EmployeeListParams | EmployeeListResponse |
| 导出 | POST | /nutrition/employee/export | EmployeeListParams | Blob |
## 三、实体字段（对照后端 DTO）
| 字段名 | TS 类型 | 中文 | 来源接口 | 必填 | 备注 |
|--------|---------|------|---------|------|------|
| id | string | 主键 | page | 是 | row-key |
| name | string | 姓名 | page | 是 | 冻结左侧 |
| ... | ... | ... | ... | ... | ... |
## 四、表格列展示规则
| 列 | 列宽 | 冻结 | 自定义渲染 |
|----|------|------|-----------|
| 姓名 | 80 | 左 | - |
| 营养达标率 | 110 | - | ≥85 绿色 / ≥70 黄 / <70 红 |
| 操作 | 100 | 右 | 「查看详情」链接 |
## 五、搜索字段
| 字段 | 控件 | 选项来源 | placeholder |
|------|------|---------|-------------|
| 姓名/工号 | 文本框 | - | 请输入姓名或工号 |
| 所属单位 | 下拉 | unitOptions（3 个值） | 全部 |
| ... | ... | ... | ... |
## 六、操作流程
> 自动从模板的 @click 与 usePage.ts 暴露的方法提取
- **查看详情**：调用 `viewDetail(record)`，期望跳转到 detail 路由（原型用 message 占位）
- **导出列表**：调用 `handleExport()`，期望调用 `exportEmployeeList` 接口下载 Blob
- **查看导出任务**：调用 `viewExportTasks()`，期望打开抽屉展示历史任务
## 七、测试关注点（供测试同事参考）
- 搜索字段重置后能否清空所有筛选条件
- 营养达标率 tag 颜色阈值（85 / 70）
- 表格横向滚动时左侧"姓名"与右侧"操作"列冻结正确
- 分页：首页禁用上一页；尾页禁用下一页；每页条数切换后回到第一页
## 八、后端接口期望（供 Java 开发参考）
接口路径：`POST /nutrition/employee/page`
请求体（JSON）：
\`\`\`json
{
"current": 1,
"pageSize": 30,
"keyword": "张",
"unit": "hq",
"dept": "rd",
"year": 2026
}
\`\`\`
响应体（JSON，符合 ApiResponse 包装）：
\`\`\`json
{
"code": "00000",
"msg": "操作成功",
"data": {
"records": [ ... ],
"total": 1280
}
}
\`\`\`
```
### Step 4：交付提示
- 打印生成的 fields.md 路径
- 提示用户可以把这份文档**分享给后端、测试、移动端**作为接口契约依据
- 提醒：如果原型 columns / filterFields 之后有变更，再次执行本 skill 会重新生成（除非配置 `--no-overwrite`）
## 输出物
`src/docs/<portal>/<app>/<section 短名>/<页面key>.md`
## 禁止事项
- 禁止主动修改原型源代码（即使发现命名不规范，仅在文档末尾"备注"中说明）
- 禁止生成不在 useTable / useSearch 中体现的字段（避免凭空构造）
- 禁止把 mock 数据复制到 fields.md（只放结构和规则）
## 注意事项
- 生成的字段类型必须与 types/index.ts 保持一致
- 接口路径采用 `api/index.ts` 注释里声明的路径
- 若 useTable 中某列用了 `key` 而非 `dataIndex`（自定义渲染列），在"表格列展示规则"中说明渲染规则，不要凭空推断字段
.claude/skills/gen-prd.md
+125
View File
@@ -0,0 +1,125 @@
---
name: gen-prd
description: 为指定原型页面生成 / 更新 PRD 文档（src/prd/<端>/<模块>/<页面>.md），并截取关键状态截图存入 screenshots/。截图严格控制尺寸（Web 1440×900 1x、移动 375×812 2x）与体积（≤ 60KB）。当用户说"生成 xx 的 PRD"、"截一组截图"、"gen-prd xx" 时触发。
---
# Skill: 生成 PRD 文档 + 截图
## 触发场景
- 完成一个页面原型后，需要把字段语义、操作流程、接口契约沉淀为可分发的 markdown
- 页面有较大改动，PRD 需重新生成
- 给后端 / 测试 / 移动端开发提交"对外可读文档 + 关键截图"
## 输入参数
1. **目标页面路径**（必须）：相对 `src/pages/`，如 `tenant-portal/nutrition/arcEmployee`
2. **状态清单**（可选）：要截图的状态，默认 `default`；常见还有 `search-active` / `empty` / `loading` / `error` / `<弹窗名>`
3. **覆盖策略**（可选）：默认增量更新（保留"页面概述"等手工编辑部分），传 `--overwrite` 全量重写
## 执行流程
### Step 1：扫描页面源
读取以下文件并提取信息：
| 文件 | 提取项 |
|------|--------|
| `<页面>.vue` | 页面标题、组件结构、@click 行为 |
| `init/usePage.ts` | 页头信息、统计卡数据、详情跳转 |
| `init/useSearch.ts` | 搜索字段配置、下拉选项 |
| `init/useTable.ts` | 表格 columns（dataIndex / title / width / fixed） |
| `types/index.ts` | 主实体接口 / 搜索参数 / 响应类型 |
| `api/index.ts` | 接口路径、方法、参数、返回 |
对照 `src/docs/business-architecture.md` 理解模块业务上下文，避免凭空生成。
### Step 2：生成 / 合并 markdown
落地路径：`src/prd/<端>/<模块>/<页面 path>.md`（与 `pages/` 路径同构，文件名使用路由 path 短横线版）
模板结构（与 `arc-employee.md` 一致）：
1. 页面概述（保留旧版手工编辑内容）
2. 页面截图（自动写入截图引用）
3. 统计区（自动从 usePage.ts stats 提取）
4. 搜索区（自动从 useSearch.ts filterFields 提取）
5. 表格字段（自动从 useTable.ts columns + types 实体对齐）
6. 操作（自动从模板 @click 与 usePage.ts 暴露的方法提取）
7. 接口契约（自动从 api/index.ts 注释提取）
8. 状态流转（如有 status 字段，输出 mermaid 状态机）
9. 测试关注点（自动 + 手工编辑保留）
10. 变更记录（追加新条目）
**保留手工编辑**：第 1、9 节若已存在内容，保留并在末尾追加自动生成部分。
### Step 3：截图
按状态清单逐张截图，存放路径：`src/prd/<端>/<模块>/screenshots/<页面 path>/<状态>.jpg`
**优先 puppeteer**；若 puppeteer 输出失真 / 尺寸不对，降级到 chrome-devtools MCP。
#### 通用截图规范（严格）
| 类别 | 视口 | DPR | 输出 | 体积上限 |
|------|------|-----|------|---------|
| Web 后台 | 1440 × 900 | 1 | jpeg q=85 | **≤ 60KB** |
| 小程序 | 375 × 812 | 2 | jpeg q=85 | **≤ 60KB** |
| 硬件 | 按设备 viewport | 1 | jpeg q=80 | **≤ 80KB**（大屏可放宽） |
#### puppeteer 代码模板（伪代码）
```js
import puppeteer from 'puppeteer'
const browser = await puppeteer.launch({ headless: 'new' })
const page = await browser.newPage()
await page.setViewport({ width: 1440, height: 900, deviceScaleFactor: 1 })
await page.goto('http://localhost:5180/#/tenant-portal/nutrition/arc-employee', { waitUntil: 'networkidle0' })
// 触发状态（如 search-active 时执行 fill + click）
await page.screenshot({ path: 'src/prd/tenant-portal/nutrition/screenshots/arc-employee/default.jpg', type: 'jpeg', quality: 85 })
await browser.close()
```
#### chrome-devtools MCP 降级路径（仅当 puppeteer 输出有问题时）
```
1. mcp__chrome-devtools__navigate_page → 目标 URL
2. mcp__chrome-devtools__resize_page → 设视口
3. （如需触发状态）mcp__chrome-devtools__fill / click
4. mcp__chrome-devtools__take_screenshot → format=jpeg quality=85 filePath=...
```
#### 体积控制
截图后立即检查文件体积：
- 若 > 60KB 且 quality > 70：降低 quality 重截
- 若 > 60KB 且尺寸过大：检查是否长截图溢出（应只截视口）
- 仍不达标：用 `sharp` 二次压缩 `npx sharp -i input.jpg -o output.jpg --quality 75`
### Step 4：交付提示
打印：
- 生成 / 更新的 md 路径
- 截图清单 + 单张体积
- PRD 在线查看 URL：`http://localhost:5180/#/__prd?path=<端>/<模块>/<页面>.md`
## 输出物
- `src/prd/<端>/<模块>/<页面>.md`
- `src/prd/<端>/<模块>/screenshots/<页面>/*.jpg`
## 禁止事项
- 禁止把截图存到其他目录（如 `public/`）
- 禁止生成超过 60KB 的单张 Web 截图（必须二次压缩或降 quality）
- 禁止把 mock 数据复制到 PRD（PRD 关注规则，不关注具体数据值）
- 禁止删除 PRD 中"页面概述"等手工编辑章节
## 注意事项
- 所有字段类型严格采用 types/index.ts 中的 TS 字面量，禁止自译为 Java 类型
- 接口路径必须与 api/index.ts 注释一致
- 写完后引导用户访问 `/__prd` 验证
- 业务架构上下文：必读 `src/docs/business-architecture.md`，禁止跨端引用
.claude/skills/new-page.md
+215
View File
@@ -0,0 +1,215 @@
---
name: new-page
description: 在原型工程中新建一个标准列表页 / 详情页 / 弹窗，按 init 三件套规范生成完整骨架（vue + types + api + 三个 init 文件），并自动注册到 src/meta/nav.ts。当用户说"新增 xxx 页面"、"加一个 xxx 列表"或"new-page" 时触发。
---
# Skill: 新建原型页面脚手架
## 图标规范（强制）
所有图标必须取自 `@ant-design/icons-vue`（4.x），**禁止使用 emoji / 自定义 svg / 第三方 icon** 作为菜单或按钮图标。
> 应用图标（NavApp.icon）可继续使用 emoji，仅用于"应用网格首页"与左上角应用切换器。
**菜单图标**（在 nav.ts 中以字符串形式声明组件名，渲染时 layouts 用 `<component :is="icon" />`）：
| 层级 | 字段 | 是否必填 | 兜底 |
|------|------|---------|------|
| NavSection（一级菜单） | `icon: 'XxxOutlined'` | 必填 | AppstoreOutlined |
| NavGroup（二级分组） | `icon: 'XxxOutlined'` | 必填 | AppstoreOutlined |
| NavLeaf（叶子页面） | `icon: 'XxxOutlined'` | 可选 | 二级叶子 FileOutlined / 三级叶子 MinusOutlined |
常用菜单图标候选（写 nav.ts 时优先复用）：
- 档案/记录：FolderOpenOutlined / FileTextOutlined / ProfileOutlined
- 监控/统计：MonitorOutlined / DashboardOutlined / BarChartOutlined / PieChartOutlined
- 设备/工具：DesktopOutlined / ToolOutlined / ApiOutlined
- 异常/告警：WarningOutlined / ExclamationCircleOutlined
- 配置/字典：SettingOutlined / DatabaseOutlined / BookOutlined
- 安全/检测：SafetyCertificateOutlined / FileSearchOutlined
- 环境/地理：EnvironmentOutlined / CloudOutlined / GlobalOutlined
**操作按钮图标**（所有页面按钮 100% 遵循，统一 antd icon）：
| 操作 | 图标 |
|------|------|
| 查询 / 搜索 | SearchOutlined |
| 重置 | RedoOutlined |
| 新增 / 添加 | PlusOutlined |
| 编辑 / 修改 | EditOutlined |
| 删除 | DeleteOutlined |
| 导入 | UploadOutlined |
| 导出 | DownloadOutlined |
| 查看详情 | EyeOutlined |
| 查看任务/列表 | UnorderedListOutlined |
| 批量操作 | AppstoreOutlined |
| 刷新 | ReloadOutlined / SyncOutlined |
| 复制 | CopyOutlined |
| 返回 | RollbackOutlined |
| 上一步/下一步 | LeftOutlined / RightOutlined |
`FilterBar` 公共组件已内置"查询/重置"按钮（带图标），新页面无需重写。
## 项目背景（必读）
本项目 4 端架构 + 后台菜单四层模型（与生产 vue 项目 `D:\Work\platform-vue-tenant` qiankun 子应用对齐）：
```
Portal（admin-portal / tenant-portal / miniprogram / hardware）
└─ NavApp (应用，独立可部署，如"营养管理"/"健康监测")
└─ NavSection (应用内一级菜单，顶部 tab，如"档案"/"绿色种采")
└─ NavGroup (二级分组，可选) | NavLeaf (二级页面)
└─ NavLeaf (三级页面)
```
URL：`/<portal>/<app>/<section>/<page>`
## 输入参数（向用户依次提问）
1. **页面类型**：`list`（列表页）| `detail`（详情页）| `modal`（弹窗）
2. **所属 Portal**：`admin-portal` | `tenant-portal` | `miniprogram` | `hardware`
3. **所属 NavApp** key：如 `nutrition`、`monitor`、`checkup`
4. **所属 NavSection** key：如 `nutrition-arc`（档案）、`nutrition-farm`（绿色种采）
5. **如有二级分组**：NavGroup key 与 label（如 `nutrition-farm-monitor` / 种养监控）
6. **页面 key**：唯一 + 小驼峰，如 `arcUnit`；nav.ts 中 leaf key 建议 `<app>-<section 简称>-<页面简称>` 风格
7. **页面中文名**：如 `单位营养报表`
8. **路由 path 片段**：短横线小写，如 `arc-unit`
9. **图标**（可选）：emoji，未指定时 Sidebar 自动用默认图标
## 执行流程
### Step 1：参数校验
- 检查 `src/pages/<portal>/<app>/<section 短名>/<页面key>/` 目录不存在
- 检查 `src/meta/nav.ts` 对应 NavSection 的 children 内不存在同名 leaf
如已存在，告知用户并中止。
### Step 2：以 arcEmployee 为蓝本生成骨架
参考路径：`src/pages/tenant-portal/nutrition/arc/arcEmployee/`
生成文件清单（list 类型）：
```
src/pages/<portal>/<app>/<section 短名>/<页面key>/
├── <页面key>.vue # 薄模板层（仅渲染，不写逻辑）
├── types/index.ts # 接口类型集中
├── api/index.ts # 接口契约占位
└── init/
├── usePage.ts # 页面级 state + 行为（无 PageHeader / 无 pageInfo）
├── useSearch.ts # 搜索字段 + 选项 + 查询/重置
└── useTable.ts # 列 + 数据 + 分页（mock 数据写这里）
```
模板差异：
| 页面类型 | 包含文件 |
|---------|---------|
| `list` | 全部 6 个文件 |
| `detail` | 5 个文件（去掉 useSearch + useTable，新增 useDetail.ts） |
| `modal` | 4 个文件（vue + usePage + types；api 视需要） |
### Step 3：填充内容（遵循新规范）
**列表页 vue 模板**：
```vue
<template>
<div class="<页面key kebab>">
<!-- 顶部统计卡（可选） -->
<a-row :gutter="16" class="<页面key kebab>__stats">
<a-col :span="6" v-for="s in stats" :key="s.label">
<StatCard :icon="s.icon" :color="s.color" :value="s.value" :label="s.label" />
</a-col>
</a-row>
<!-- 搜索栏 -->
<FilterBar
v-model="searchForm"
:fields="filterFields"
@search="handleSearch"
@reset="handleReset"
/>
<!-- 表格（无标题；主操作放 #toolbar 左上方） -->
<TableCard
:columns="columns"
:data-source="dataList"
:pagination="pagination"
row-key="id"
>
<template #toolbar>
<a-button type="primary" @click="handleExport">
<template #icon><DownloadOutlined /></template>
导出列表数据
</a-button>
<a-button @click="viewExportTasks">
<template #icon><UnorderedListOutlined /></template>
查看导出任务
</a-button>
</template>
<template #bodyCell="{ column, record }">
<!-- 业务渲染 -->
</template>
</TableCard>
</div>
</template>
```
**重要规范**：
- ❌ **禁止**渲染 `PageHeader`（标题、面包屑由顶部菜单/历史栏表达）
- ❌ **禁止**给 `TableCard` 传 `title`（菜单已经表达了所在位置）
- ✅ **必须**通过 `TableCard #toolbar` 放置主操作按钮（导出、新增等），位置在表格卡片左上方
- ✅ **可选**使用 `TableCard #extra` 放置次要操作（视图切换、批量操作等）
- ✅ **可选**统计卡片放在 `FilterBar` 之上
- ✅ 替换实体名占位：`Employee` → 用户输入的页面 key 推导
- ✅ API 接口路径占位：`POST /api/<app>/<页面key>/page`
### Step 4：注册到 nav.ts
读取 `src/meta/nav.ts`，找到目标 NavApp → NavSection 对象：
- 若指定了 `分组 key`：找到该 NavGroup（若不存在则新建），在其 children 末尾追加 NavLeaf
- 若未指定分组：直接在 NavSection.children 末尾追加 NavLeaf
- NavLeaf 模板：
```ts
{
key: '<leaf key>',
label: '<中文名>',
path: '<路由 path 片段>',
icon: '<emoji>', // 可选，省略时 Sidebar 用默认图标
status: 'draft', // 新页面默认 draft
component: () => import('@pages/<portal>/<app>/<section 短名>/<页面key>/<页面key>.vue'),
}
```
### Step 5：验证
- 打印生成清单，告知用户在浏览器访问的路由路径：`/<portal>/<app>/<section key>/<path>`
- 若 dev 已启动，提示用户直接刷新即可看到新菜单与页面
## 输出物
1. 6 个新文件（list 类型）
2. 修改后的 `src/meta/nav.ts`
3. 终端打印的访问 URL
## 禁止事项
- 禁止跨页面修改其他模块的代码
- 禁止跨应用 import（不同 NavApp 之间模拟独立部署）
- 禁止省略 `init/` 拆分；即使只有一个搜索字段或一列表格，也必须独立文件
- 禁止把 mock 数据写在 .vue 的 setup 里，必须放 useTable.ts
- 禁止修改 `src/components/` 下的公共组件，原型阶段所有定制都在页面内
- 禁止渲染 PageHeader 标题 / TableCard title（新规范）
- 禁止把导出/新增按钮放在页面顶部独立位置（必须放 TableCard #toolbar）
## 注意事项
- 所有注释使用简体中文
- TypeScript 类型必须明确声明，不允许 `any`
- 字段命名小驼峰；CSS 类名 BEM
- 生成后再次提醒用户：原型阶段 mock 数据写在 useTable.ts，工程化时只需替换为 api 调用即可
.claude/skills/prototype-lint.md
+158
View File
@@ -0,0 +1,158 @@
---
name: prototype-lint
description: 扫描原型工程的代码规范一致性。检查每个页面目录是否符合 init 三件套结构、columns 与 types 字段是否对齐、是否存在禁止的反模式（mock 写在 .vue / 业务逻辑写在模板 / 跨模块引用 / 缺类型）。当用户说"检查规范"、"prototype-lint"、"扫描代码风格" 时触发。
---
# Skill: 原型工程规范检查
## 触发场景
- PR 合并前自检
- 多人协作时确保一致性
- 周期性巡检（建议每周一次）
## 检查项
### A. 目录结构合规（关键）
对 `src/pages/**` 下的每个页面目录检查：
| 项 | 要求 | 严重度 |
|----|------|--------|
| A1 | 列表页必须含 `init/usePage.ts + init/useSearch.ts + init/useTable.ts` 三件套 | 🔴 错误 |
| A2 | 必须有 `types/index.ts` | 🔴 错误 |
| A3 | 必须有 `api/index.ts`（占位也算） | 🟡 警告 |
| A4 | 主 .vue 文件名必须与目录名一致（小驼峰） | 🔴 错误 |
| A5 | 禁止在页面目录直接放 `.css/.less` 文件，样式必须 `<style scoped>` | 🟡 警告 |
### B. 模板层 .vue 文件检查
对每个页面主 .vue 文件：
| 项 | 要求 | 严重度 |
|----|------|--------|
| B1 | `<script setup lang="ts">` 必须设置 `lang="ts"` | 🔴 错误 |
| B2 | setup 内不允许出现表格数据数组字面量（`const dataList = ref([{...},{...}])`） | 🔴 错误 |
| B3 | setup 内不允许出现 `columns` 数组字面量 | 🔴 错误 |
| B4 | 不允许直接 `import` 其他模块 / 其他端的页面文件 | 🔴 错误 |
| B5 | `<style>` 必须带 `scoped`（除非顶层 Layout） | 🟡 警告 |
| B6 | 模板中 class 命名建议使用 BEM | 🟢 提示 |
### C. init/*.ts 检查
| 项 | 要求 | 严重度 |
|----|------|--------|
| C1 | 每个 use*.ts 必须用 `export const useXxx = () => { ... }` 命名规范 | 🔴 错误 |
| C2 | useTable.ts 的 `columns` 数组应使用 `TableColumnsType` 类型注解 | 🟡 警告 |
| C3 | useSearch.ts 的 `filterFields` 应使用 `FilterField[]` 类型注解 | 🟡 警告 |
| C4 | 禁止使用 `any` 类型 | 🟡 警告 |
### D. types/index.ts 与 columns 对齐
对照 useTable.ts 的 `columns` 和 types/index.ts 中的主实体接口字段：
| 项 | 要求 | 严重度 |
|----|------|--------|
| D1 | columns.dataIndex 中出现的字段，必须在主实体 interface 中声明 | 🔴 错误 |
| D2 | 主实体的必填字段（无 `?`），应该至少出现在 columns 或 useDetail 中 | 🟢 提示 |
### E. api/index.ts 检查
| 项 | 要求 | 严重度 |
|----|------|--------|
| E1 | 接口函数必须有 `@接口路径` 注释（供后端 / 测试参考） | 🟡 警告 |
| E2 | 接口参数应使用 types/index.ts 中的 Params 类型 | 🟡 警告 |
| E3 | 原型阶段允许返回 `Promise.reject` 占位，但必须含 `[原型阶段]` 标识 | 🟢 提示 |
### F. 公共组件使用规范
| 项 | 要求 | 严重度 |
|----|------|--------|
| F1 | 列表页若有顶部统计区，应使用 `StatCard` 而非自定义 div | 🟡 警告 |
| F2 | 列表页搜索区应使用 `FilterBar` + filterFields 配置驱动 | 🟡 警告 |
| F3 | 列表页表格应使用 `TableCard` 包装 | 🟡 警告 |
| F4 | 禁止修改 `src/components/` 下的公共组件（按需扩展走"提一个 PR 评审"） | 🔴 错误 |
### G. 截图与文档体积巡检
| 项 | 要求 | 严重度 |
|----|------|--------|
| G1 | `src/prd/**/screenshots/**/*.jpg`：Web 截图体积 ≤ 60KB | 🔴 错误 |
| G2 | `src/prd/**/screenshots/**/*.jpg`：小程序截图体积 ≤ 60KB | 🔴 错误 |
| G3 | `src/prd/**/screenshots/**/*.jpg`：硬件截图体积 ≤ 80KB | 🟡 警告 |
| G4 | `src/prd/**/_overview/**/*.png`：拼图体积 ≤ 500KB | 🟡 警告 |
| G5 | 单个 PRD `.md` 体积 ≤ 200KB（防止粘贴大段截图 base64） | 🟡 警告 |
| G6 | `dist/assets/*.js`：单 chunk 体积 ≤ 700KB（信息提示，可通过 manualChunks 优化） | 🟢 提示 |
实现：用 Bash `find ... -size +60k` 找出超限文件并列出。
## 执行流程
### Step 1：枚举页面目录
使用 Glob：`src/pages/web-admin/**/*/`、`src/pages/employee-app/**/*/`、`src/pages/emergency-app/**/*/`
跳过：
- 占位页（`AppPlaceholder.vue` / `PlaceholderPage.vue`）
- `home/`
### Step 2：逐目录跑全部检查项
对每个目录，串行执行 A → F 的检查，收集问题。
### Step 3：输出报告
```markdown
# 原型规范检查报告（YYYY-MM-DD）
## 总览
- 检查页面数：12
- 🔴 错误：3
- 🟡 警告：8
- 🟢 提示：5
## 错误详情
### pages/web-admin/nutrition/arcUnit/
- [A1] 缺少 `init/useSearch.ts`
- [B2] arcUnit.vue 第 45 行：表格数据写在了 setup 里，应迁移到 init/useTable.ts
### pages/employee-app/profile/
- [B4] Profile.vue 第 12 行：import 了 web-admin 的组件，禁止跨端引用
## 警告详情
...
```
### Step 4：可选自动修复
询问用户："以下 N 个警告可以自动修复（如 missing scoped、any 类型替换、缺类型注解），是否执行？"
仅对**白名单内的可逆改动**执行自动修复：
- 给 `<style>` 加 `scoped`
- 给 `columns` 加 `TableColumnsType` 类型注解
- 给 `filterFields` 加 `FilterField[]` 类型注解
不在白名单内的（如 B2 数据搬迁），打印手工修复指引但不动代码。
## 输出物
- 终端打印的检查报告
- 可选：`.claude/memory/lint_report.md`（持久化最近一次报告）
## 禁止事项
- 禁止执行可能破坏页面渲染的"自动修复"
- 禁止跨页面/跨模块自动重构（仅同文件内的微调）
- 禁止重命名文件（命名问题只报告）
## 注意事项
- 列表页 vs 详情页 vs 弹窗的"必须文件"清单不同，按页面类型差异化检查
- 占位页（标题含 "Placeholder" 或文件名为 Placeholder*）不参与全部检查
- 检查耗时：100 个页面 < 5 秒（基于 Grep + Read，不调用任何工具子进程）
.claude/skills/sync-nav.md
+109
View File
@@ -0,0 +1,109 @@
---
name: sync-nav
description: 检查 src/meta/nav.ts 与 src/pages/ 实际文件的一致性。扫描 pages 下所有 .vue 文件，对照 nav.ts 中的 component 懒加载路径，报告：在 pages 但未注册到 nav 的孤儿页面 / 在 nav 但 pages 不存在的死引用 / 路径与目录命名不一致的问题。当用户说"检查菜单同步"、"sync-nav"、"看看哪些页面没注册到菜单" 时触发。
---
# Skill: 菜单与页面文件一致性检查
## 触发场景
- 大量新增 / 删除原型页面后，不放心 nav.ts 是否同步
- PR 评审前的快速自检
- 出现"菜单点击 404 / 页面访问 404 / 菜单没显示新页面"等异常时排查
## 执行流程
### Step 1：扫描 src/pages 下所有 .vue 文件
使用 Glob：`src/pages/**/*.vue`
排除：
- `src/pages/home/Home.vue`（导航首页，不参与菜单）
- 任何以 `_` 开头的目录（约定为草稿）
收集每个 .vue 的相对路径（相对 `src/pages/`）。
### Step 2：读取 src/meta/nav.ts 中的所有 component 路径
正则匹配：`import\('@pages/(.+?)\.vue'\)`
提取每条匹配的相对路径，建立"已注册"集合。
### Step 3：比对差异
**差异 A：孤儿页面（pages 中存在但 nav 未注册）**
```
src/pages/web-admin/nutrition/arcUnit/ArcUnit.vue
→ nav.ts 未引用，菜单不会显示，无法访问
```
**差异 B：死引用（nav 引用但 pages 不存在）**
```
nav.ts → import('@pages/web-admin/foo/Foo.vue')
→ 实际文件不存在，路由懒加载会失败（404 或 Vite 报错）
```
**差异 C：命名不规范**
检查每个 .vue 文件路径是否符合：
- 目录名小驼峰：`arcEmployee` ✅ / `ArcEmployee` ❌ / `arc-employee` ❌（路由 path 用短横线，目录不用）
- 文件名与目录名一致：`arcEmployee/arcEmployee.vue` ✅
- 不允许多层冗余：`arcEmployee/index.vue`（除非阶段一约定的占位页）
### Step 4：输出诊断报告
```markdown
# 菜单同步检查报告（YYYY-MM-DD HH:mm）
## 总览
- pages 下 .vue 文件总数：12
- nav.ts 已注册路径数：10
- 一致性：⚠️ 发现 3 处差异
## 差异 A：孤儿页面（2）
| 文件 | 建议 |
|------|------|
| pages/web-admin/nutrition/arcUnit/arcUnit.vue | 建议在 nav.ts 的 nutrition.arc 分组追加 NavLeaf |
| pages/web-admin/nutrition/farmHarvest/farmHarvest.vue | 同上 |
## 差异 B：死引用（1）
| nav 引用 | 建议 |
|---------|------|
| @pages/web-admin/foo/Foo.vue | 删除该 NavLeaf 或补齐文件 |
## 差异 C：命名不规范（0）
无
## 建议执行命令
如需自动补齐 nav，可继续调用 new-page 重新生成（仅注册步骤）。
```
### Step 5：交互处理
询问用户：
- "是否要我自动为孤儿页面在 nav.ts 中追加 NavLeaf？" → 默认放在该模块最后一个 NavGroup 末尾
- "是否要删除死引用？" → 默认不删，仅标注
## 输出物
终端打印诊断报告。若用户确认修复，直接更新 `src/meta/nav.ts`。
## 禁止事项
- 禁止主动重命名文件 / 目录（命名问题只报告，让用户决定）
- 禁止删除 .vue 文件（即使是死引用对应的孤儿目录）
- 禁止跨模块移动文件
## 注意事项
- 占位组件（`PlaceholderPage.vue` / `AppPlaceholder.vue`）属于"通用占位"，可以被多个 NavLeaf 共享引用，不算死引用
- 检测路径时区分大小写：因 Vite dev 严格区分，`ArcEmployee.vue` 与 `arcEmployee.vue` 视为不同文件
.claude/tmp/verify-arc-employee.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 145 KiB

.claude/tmp/verify-page-history-v2.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 145 KiB