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（降级）

启动命令

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`	设计总览（小程序 / 硬件）

关键约定

菜单单一来源：所有菜单结构集中在 src/meta/nav.ts
三层菜单结构：每个应用（NavApp） → 一级菜单（NavSection） → 二/三级菜单（NavGroup → NavLeaf）
URL 规范：/<portal>/<app>/<section>/<page>，例：/tenant-portal/nutrition/nutrition-farm/monitor/crop
列表页 UI 规范（重要）：
- 不渲染 PageHeader（菜单 + 顶部历史栏已经表达所在位置）
- TableCard 不显示 title
- 主操作按钮（导出/新增/批量等）放在 TableCard #toolbar 左上方
- 次要操作放在 TableCard #extra 右上方
- 统计卡放在 FilterBar 上方（可选）
图标规范（强制）：
- 所有菜单图标 / 操作按钮图标必须取自 @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（仅在应用网格首页 + 左上角应用切换器显示）
端隔离：4 端不允许互相 import；共享仅通过 @components / @layouts / @meta / @composables
应用隔离：同一 portal 下不同应用之间也不应相互 import（对齐 vue 项目"子应用独立部署"）；共享只能走 nav.ts 的公共抽象
列表页固定 6 文件结构：<页面>.vue + types + api + init/(usePage + useSearch + useTable)
Mock 数据：写在 init/useTable.ts 的 dataList
公共组件优先：StatCard / FilterBar / TableCard / PlaceholderPage
TS 严格：禁止 any
中文注释
可见性：每个 NavLeaf 有 status（draft/review/ready）+ audience（designer/all），dev 角色看不到 draft 或 designer-only 的页面
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（仅支持小程序/硬件）

15 KiB Raw Blame History Unescape Escape