# 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 结构：`///
/`，例：`/tenant-portal/nutrition/nutrition-farm/monitor/crop` > - 应用首页（`/`）：展示应用网格卡片（参考 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 根组件，仅 ├── 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/ 租户运营后台业务页面（按 /
/ 组织） │ │ ├── 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 规范**：`///
/`，例：`/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（仅支持小程序/硬件）