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

2026-06-04 19:43:15 +08:00
commit 87fabc49c1
99 changed files with 13000 additions and 0 deletions
@@ -0,0 +1,280 @@
+# yx-platform-prototype — 项目开发指南
+
+## 项目定位
+
+智养餐饮平台V3项目的**高保真交互原型工程**，采用 **Vue 3 + Vite + Ant Design Vue + Vant** 半工程化方案。
+
+**核心目标**：让产品经理画的原型 = 开发要写的代码骨架，AI 还原代码时几乎零创造性工作。
+
+---
+
+## 四个终端
+
+| 终端 | key | UI 库 | 主要用户 | 业务定位 |
+|------|-----|-------|---------|---------|
+| 综合管理后台 | `admin-portal` | Ant Design Vue | 平台管理员 | 平台级管理（系统设置/运营中心/设备中心 等独立应用） |
+| 租户运营后台 | `tenant-portal` | Ant Design Vue | 租户运营人员 | **17 个独立可部署应用的统一入口**（营养管理/健康监测/...） |
+| C 端微信小程序 | `miniprogram` | Vant 4（375×812） | 终端用户 | 用户自助查询、上报、咨询 |
+| 硬件终端屏 | `hardware` | 自定义（动态 viewport） | 现场操作员 | 净菜柜屏 / 自助查询屏 / 大屏 等 |
+
+> **重要架构说明**（对齐生产 vue 项目 `D:\Work\platform-vue-tenant` 的 qiankun 微前端形态）：
+> - `admin-portal` / `tenant-portal` 只是登录门户外壳。下挂多个**独立可部署的应用（NavApp）**，每个应用对应生产 vue 项目中的一个 `subXxx` 子应用。
+> - 进入某个应用后，顶部显示**该应用内的一级菜单 tabs**（NavSection），左侧显示**当前一级菜单下的二/三级菜单**（NavGroup → NavLeaf）。
+> - URL 结构：`/<portal>/<app>/<section>/<page>`，例：`/tenant-portal/nutrition/nutrition-farm/monitor/crop`
+> - 应用首页（`/<portal>`）：展示应用网格卡片（参考 vue 项目 main 的 `home.vue`）。
+
+> 详细业务边界与各应用模块清单见 **`src/docs/business-architecture.md`**。AI 在生成原型前**必须先读这份文档**。
+
+---
+
+## 技术栈
+
+| 类别 | 选型 |
+|------|------|
+| 框架 | 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（降级） |
+
+---
+
+## 启动命令
+
+```bash
+npm install       # 一次性安装
+npm run dev       # 启动（端口 5180）
+npm run build     # 构建产物到 dist/
+npm run preview   # 预览构建产物
+```
+
+**门禁密码**（`.env`）：
+
+- 设计：`design2026`（可见全部）
+- 研发：`dev2026`（看不见 draft / designer-only 页面）
+
+登录后 7 天有效；过期自动重新登录。
+
+---
+
+## 详细目录说明（重要）
+
+```
+yx-platform-prototype/
+├── package.json                 npm 配置 + 依赖列表 + 脚本命令
+├── vite.config.ts               Vite 构建配置：端口 5180、路径别名、自动导入插件
+├── tsconfig.json                TS 项目根配置（references → tsconfig.app + node）
+├── tsconfig.app.json            前端代码的 TS 编译配置（vue/dom）
+├── tsconfig.node.json           Vite 配置自身的 TS 编译配置（node 环境）
+├── index.html                   Vite 入口 HTML，挂载 #app
+├── .env                         环境变量（门禁密码；可提交 git）
+│
+├── public/                      静态资源（不参与构建处理，直接拷到 dist 根）
+│
+├── CLAUDE.md                    本文件 —— 项目开发指南（AI 必读）
+│
+├── .claude/
+│   ├── skills/                  项目专属技能（slash command 可触发）
+│   │   ├── new-page.md          新建原型页骨架（init 三件套）
+│   │   ├── gen-fields.md        单页字段清单（给后端/测试）
+│   │   ├── gen-prd.md           生成 PRD 文档 + 截图（严格控制尺寸/体积）
+│   │   ├── design-overview.md   设计总览：小程序/硬件版块平铺（含拼图）
+│   │   ├── sync-nav.md          菜单与 pages/ 一致性检查
+│   │   └── prototype-lint.md    代码规范检查
+│   ├── agents/                  项目专属代理
+│   │   ├── prototype-reviewer.md       PR / 变更综合评审（只读）
+│   │   └── cross-role-doc-builder.md   模块级跨岗位文档包
+│   └── memory/                  会话间持久化记忆
+│       ├── MEMORY.md            索引
+│       ├── decisions.md         关键决策
+│       ├── feedback.md          协作规范
+│       ├── project_overview.md  技术栈与架构
+│       ├── project_progress.md  阶段进度
+│       └── user_profile.md      用户画像
+│
+└── src/
+    ├── main.ts                  应用入口：创建 Vue 实例、挂载 router
+    ├── App.vue                  根组件，仅 <router-view />
+    ├── style.css                全局设计令牌（CSS 变量）+ reset
+    │
+    ├── router/
+    │   ├── index.ts             创建 router 实例 + 守卫（门禁 + designerOnly）
+    │   └── routes.ts            路由表：由 nav.ts 自动派生 + 4 个工具路由（gate/console/prd/overview）
+    │
+    ├── meta/
+    │   └── nav.ts               🌟 菜单数据单一来源
+    │                            - 4 端类型定义（NavApp / NavSection / NavGroup / NavLeaf / NavMiniprogramTab / NavHardwareDevice）
+    │                            - 后台层级：NavApp → NavSection → (NavGroup | NavLeaf) → NavLeaf
+    │                            - admin: adminApps；tenant: tenantApps（含 nutrition / monitor 完整三层菜单）
+    │                            - status + audience 字段控制可见性
+    │
+    ├── composables/             复用逻辑
+    │   └── useVisibility.ts     可见性核心：角色、过滤、覆写存取
+    │
+    ├── layouts/                 共享布局（菜单只写一次）
+    │   ├── PortalLayout.vue     后台门户（admin/tenant 共用，按 route.meta.isAppGrid 切换"应用网格首页"/"应用内三层菜单"）
+    │   ├── MiniprogramLayout.vue  小程序手机壳（375×812）
+    │   ├── HardwareLayout.vue   硬件外壳（按 viewport 动态尺寸）
+    │   └── components/
+    │       ├── TopBar.vue       后台顶部（Logo + 应用名▾下拉切换 + 一级菜单 tabs + 返回首页 + 应用首页 + 用户区）
+    │       ├── Sidebar.vue      后台侧边栏（二/三级菜单，支持 SubMenu 嵌套）
+    │       ├── AppTabBar.vue    移动端底部 Tab（Vant Tabbar）
+    │       └── RoleBadge.vue    顶部角色徽章 + PRD/总览快捷入口 + 登出
+    │
+    ├── components/              公共业务组件（被自动注册到 AntDV 风格）
+    │   ├── StatCard.vue         统计卡（4 色配色）
+    │   ├── FilterBar.vue        配置驱动搜索栏（5 种字段类型）
+    │   ├── TableCard.vue        表格卡（无 title；#toolbar 左上、#extra 右上、a-table 全部透传）
+    │   ├── PageHeader.vue       页头（保留供详情页用，列表页不应使用）
+    │   ├── PlaceholderPage.vue  后台占位页（接 title/name）
+    │   └── AppPlaceholder.vue   移动端占位页（接 title/name）
+    │
+    ├── pages/                   原型页面（按端 + 应用 + 一级菜单 分目录）
+    │   ├── home/Home.vue        🏠 全局导航首页（四端 Tab + 卡片网格）
+    │   ├── gate/Gate.vue        🔒 门禁页（密码登录 → 设置角色 + 7 天 TTL）
+    │   ├── console/
+    │   │   └── VisibilityConsole.vue   🎛 设计完成度控制台（仅 designer）
+    │   ├── prd/
+    │   │   └── PrdViewer.vue    📄 PRD 在线查看（markdown-it 渲染 src/prd/**.md）
+    │   ├── overview/
+    │   │   └── DesignOverview.vue 🖼 设计总览（小程序/硬件页面平铺）
+    │   │
+    │   ├── admin-portal/        综合管理后台业务页面
+    │   │   ├── system-settings/Overview.vue
+    │   │   ├── operation-center/Overview.vue
+    │   │   └── device-center/Overview.vue
+    │   ├── tenant-portal/       租户运营后台业务页面（按 <app>/<section>/<page> 组织）
+    │   │   ├── home/
+    │   │   │   └── AppGrid.vue          🌟 租户应用网格首页（卡片入口）
+    │   │   ├── nutrition/                营养管理应用
+    │   │   │   ├── arc/                  档案（一级菜单）
+    │   │   │   │   ├── arcEmployee/      ⭐ 标准列表页样板（六文件）
+    │   │   │   │   └── ArcUnit.vue
+    │   │   │   └── farm/                 绿色种采（一级菜单）
+    │   │   │       └── FarmLand.vue
+    │   │   └── monitor/                  健康监测应用（菜单结构占位，页面待开发）
+    │   ├── miniprogram/         小程序业务页面
+    │   │   ├── home/Home.vue
+    │   │   └── profile/Profile.vue
+    │   └── hardware/            硬件业务页面
+    │       └── cabinet/Home.vue
+    │
+    ├── prd/                     PRD markdown 文档（自动由 /gen-prd 维护）
+    │   └── tenant-portal/nutrition/
+    │       ├── arc-employee.md
+    │       └── screenshots/<页面>/<状态>.jpg  截图（≤60KB）
+    │
+    ├── docs/                    业务文档
+    │   └── business-architecture.md   🌟 业务架构（AI 必读）
+    │
+    └── types/                   全局类型声明（自动生成 + 手写 shims）
+        ├── auto-imports.d.ts    unplugin-auto-import 生成
+        ├── components.d.ts      unplugin-vue-components 生成
+        └── shims-vue.d.ts       .vue 文件类型声明
+```
+
+---
+
+## 路径别名
+
+| 别名 | 指向 |
+|------|------|
+| `@`            | `src/` |
+| `@meta`        | `src/meta/` |
+| `@layouts`     | `src/layouts/` |
+| `@components`  | `src/components/` |
+| `@composables` | `src/composables/` |
+| `@pages`       | `src/pages/` |
+| `@router`      | `src/router/` |
+
+---
+
+## 工具路由（带 `__` 前缀，不在 nav 菜单中）
+
+| 路由 | 说明 |
+|------|------|
+| `/gate` | 门禁登录页 |
+| `/__console` | 设计完成度控制台（仅 designer） |
+| `/__prd` | PRD 文档在线查看 |
+| `/__overview` | 设计总览（小程序 / 硬件） |
+
+---
+
+## 关键约定
+
+1. **菜单单一来源**：所有菜单结构集中在 `src/meta/nav.ts`
+2. **三层菜单结构**：每个应用（NavApp） → 一级菜单（NavSection） → 二/三级菜单（NavGroup → NavLeaf）
+3. **URL 规范**：`/<portal>/<app>/<section>/<page>`，例：`/tenant-portal/nutrition/nutrition-farm/monitor/crop`
+4. **列表页 UI 规范（重要）**：
+   - **不渲染 PageHeader**（菜单 + 顶部历史栏已经表达所在位置）
+   - **TableCard 不显示 title**
+   - **主操作按钮**（导出/新增/批量等）放在 `TableCard #toolbar` 左上方
+   - **次要操作**放在 `TableCard #extra` 右上方
+   - **统计卡**放在 `FilterBar` 上方（可选）
+5. **图标规范（强制）**：
+   - 所有菜单图标 / 操作按钮图标必须取自 `@ant-design/icons-vue` 4.x，**禁止使用 emoji / 自定义 svg**
+   - NavSection / NavGroup：必填 `icon: 'XxxOutlined'`
+   - NavLeaf：可选；layouts 渲染时未指定则二级用 FileOutlined / 三级用 MinusOutlined 兜底
+   - 操作按钮标准映射：查询=SearchOutlined / 重置=RedoOutlined / 新增=PlusOutlined / 编辑=EditOutlined / 删除=DeleteOutlined / 导入=UploadOutlined / 导出=DownloadOutlined / 查看详情=EyeOutlined / 查看任务=UnorderedListOutlined
+   - 应用图标（NavApp.icon）允许 emoji（仅在应用网格首页 + 左上角应用切换器显示）
+5. **端隔离**：4 端不允许互相 import；共享仅通过 `@components` / `@layouts` / `@meta` / `@composables`
+6. **应用隔离**：同一 portal 下不同应用之间也不应相互 import（对齐 vue 项目"子应用独立部署"）；共享只能走 nav.ts 的公共抽象
+7. **列表页固定 6 文件结构**：`<页面>.vue + types + api + init/(usePage + useSearch + useTable)`
+8. **Mock 数据**：写在 `init/useTable.ts` 的 dataList
+9. **公共组件优先**：StatCard / FilterBar / TableCard / PlaceholderPage
+10. **TS 严格**：禁止 any
+11. **中文注释**
+12. **可见性**：每个 NavLeaf 有 `status`（draft/review/ready）+ `audience`（designer/all），dev 角色看不到 draft 或 designer-only 的页面
+13. **PRD 截图体积**：Web ≤ 60KB、小程序 ≤ 60KB、硬件 ≤ 80KB；优先 puppeteer，失真时降级 chrome-devtools MCP
+
+---
+
+## 项目专属 Skills / Agents
+
+| 触发场景 | 调用 |
+|---------|------|
+| 新增原型页面 | `/new-page` skill |
+| 生成 PRD（含截图） | `/gen-prd` skill |
+| 生成单页字段清单 | `/gen-fields` skill |
+| 设计总览（小程序/硬件） | `/design-overview` skill |
+| 菜单同步检查 | `/sync-nav` skill |
+| 代码规范检查 | `/prototype-lint` skill |
+| PR 综合评审 | `prototype-reviewer` agent |
+| 模块级跨岗位文档包 | `cross-role-doc-builder` agent |
+
+详见 `.claude/skills/` 与 `.claude/agents/` 下的 frontmatter description。
+
+---
+
+## 记忆体系（会话启动必读）
+
+每次新会话启动时，必须先读取记忆体系索引（`.claude/memory/MEMORY.md`），再按需加载关键记忆文件。
+
+必读：`decisions.md` / `feedback.md` / `project_progress.md`
+按需：`project_overview.md` / `user_profile.md`
+
+---
+
+## 禁止事项
+
+- 禁止跨页面修改其他模块的代码
+- 禁止在 .vue 的 setup 里直接写表格 columns 数组、mock 数据数组
+- 禁止跨端引用页面（admin ↛ tenant ↛ miniprogram ↛ hardware）
+- 禁止跨应用引用页面（不同 NavApp 之间不能互相 import，模拟独立部署）
+- 禁止修改 `src/components/` 的公共组件（除非走 PR 评审）
+- 禁止省略 init 三件套（即使只有 1 列表格也要独立 useTable.ts）
+- 禁止把业务逻辑写在模板（所有逻辑通过 usePage 等 hook 暴露）
+- 禁止使用 `any` 类型
+- 禁止在列表页渲染 PageHeader（含面包屑/标题/副标题）
+- 禁止给 TableCard 传 title（菜单已表达所在位置）
+- 禁止把主操作按钮放在页面顶部独立位置（必须放 TableCard #toolbar）
+- 禁止使用 emoji / 自定义 svg 作为菜单或按钮图标（必须用 @ant-design/icons-vue）
+- 禁止把 Vant 组件用在后台页面（admin/tenant），反之亦然
+- 禁止把截图存到 PRD 目录之外（如 public/）
+- 禁止生成 > 60KB 的单张 Web/小程序截图
+- 禁止在 Web 后台调用 `/design-overview` skill（仅支持小程序/硬件）