Imported from uuo00n/elderly-care (AGENTS.md). Install upstream with npx skills add uuo00n/elderly-care. Copyright stays with the author.

AGENTS.md — 智慧颐养系统前端项目规则

本文档是 Codex 在本仓库工作时必须遵守的强约束。读完再动手。

1. 设计稿优先（最高优先级）

所有页面必须严格按 Sketch 原型图像素级复刻，不允许凭文档/经验/组件默认样式自行发挥。

1.1 工作流程（每个页面/组件落地前的必经步骤）

1. 取截图：调用 mcp__sketch__run_code 选中目标画板，再调用 mcp__sketch__get_selection_as_image 拿到画板视觉截图。未取得截图前不得编写该页代码。
2. 逐区拆解：把截图划分为顶部/筛选区/统计区/表格区/弹窗等区块，逐区列出宽高、间距、颜色、字号、按钮位置。
3. 结构对齐：用 mcp__sketch__run_code 进一步读取关键 group 的 frame 和 style，确认像素级数值与命名（如"任务类型备份 3"通常是筛选 chip，不是表格列）。
4. 实现并比对：写完后用 mcp__chrome-devtools__navigate_page + take_screenshot 把页面截图，与 Sketch 截图并排比对；Sketch 截图是唯一视觉验收基准，仅允许浏览器字体渲染、抗锯齿等不可控细微差异，布局、尺寸、颜色、间距、层级、文本位置明显不一致即视为不达标，必须重做。
5. 冲突时：Sketch 与文档 (docs/FRONTEND_LAYOUT_PROTOTYPE_REDESIGN_BRIEF.md) 不一致时，以 Sketch 为准；文档仅作为字段/字段含义的补充。

1.2 Sketch 画板 ID 速查

无 Sketch 画板的路由（/basic/staff-management、设备 4 子页、设置 5 页、分析 2 页）才允许参考"同模块画板 + 文档"推断。

1.3 不允许的事

• ❌ 仅凭 FRONTEND_LAYOUT_PROTOTYPE_REDESIGN_BRIEF.md 文字描述写页面（文档不带视觉细节）
• ❌ 把 Sketch 画板里的"任务类型备份"理解为表格列（它通常是筛选/Tag chip）
• ❌ 把工作台的"老人实时告警"做成左右分栏的卡片网格（Sketch 里它是横向滚动条带状区域）
• ❌ 自行发明配色、卡片圆角、按钮位置；色值与圆角必须取自 Sketch
• ❌ Subagent 启动后不读 Sketch 就开始写代码
• ❌ 为了迁就 Element Plus 默认样式而放弃 Sketch 尺寸、间距、颜色、状态或交互布局

2. 技术栈与目录约定

• Vue 3 + Vite + JavaScript（不引 TypeScript）+ SCSS（不引 Tailwind）
• UI：Element Plus + unplugin-vue-components 自动按需引入；图标 @element-plus/icons-vue
• 允许引入必要的 Vue 3 三方包，但必须解决真实问题、与现有栈兼容，并先按第 5 节使用 Context7 MCP 查明用法
• 路由：vue-router 4，createWebHistory
• 状态：Pinia + pinia-plugin-persistedstate@^3.2.3（4.x 与 pinia 2 不兼容，固定 3.x）
• 网络：axios，统一通过 @/api/request 调用；mock 由 VITE_USE_MOCK=true 控制
• 时间：dayjs；图表：echarts + vue-echarts；通用工具：@vueuse/core

目录树以现状为准，新增模块按 views/{module}/、api/{module}.js、mock/{module}.mock.js 三件套放置。

3. 代码风格

• 单文件组件统一 <script setup>；不使用 Options API
• 模板里 Element Plus 组件直接用（已自动注册），但 ElMessage / ElMessageBox 这类函数式调用要 import { ElMessage } from 'element-plus'
• 错误提示交给 @/api/request 的响应拦截器统一 toast，不要在业务页 catch 里再 ElMessage.error
• 字典（楼栋/楼层/部门/职位/护理等级）一律走 @/api/dict，禁止页面本地写死
• 颜色、间距、圆角从 src/styles/variables.scss 取，不硬编码
• 不写大段注释解释 WHAT；只在 WHY 不显而易见时加一行注释

4. Subagent 并行开发约束

• 多页面/多模块开发必须使用 subagent 并行拆分；主会话负责共享上下文、任务边界、最终集成和验收
• Subagent 启动前，主会话必须明确：路由、Sketch 画板 ID、目标文件、API/mock 边界、可写范围、验收标准
• Subagent 只写自己负责的 view + api + mock 三件套，不修改 router/stores/layout/共享组件/全局样式等共享代码
• Subagent 启动后第一步必须用 Sketch MCP 取目标画板截图，并读取关键图层 frame/style/text（见第 1 节）
• Subagent 交付时必须说明：使用的 Sketch 画板 ID、读取的关键视觉数据、修改文件范围、是否需要共享代码支持
• 如 Subagent 发现需要扩展共享组件或改共享代码，必须挂起该部分改动、交回主会话处理

5. Context7 MCP 强制约束

• 遇到 Vue、Vite、Element Plus、Pinia、axios、echarts、vue-echarts 或任何新增三方包的开发问题时，必须使用 Context7 MCP 查询官方用法
• Context7 可用时，先解析目标库，再读取对应文档；不得仅凭记忆、旧经验或博客内容处理框架/三方包问题
• 如果当前环境没有可调用的 Context7 MCP，相关框架/三方包问题必须标记为阻塞并上报，不允许改用官方文档、本地源码或经验兜底绕过
• 不涉及框架/三方包用法的问题，可继续按仓库现有代码和 Sketch 原型推进

6. 验收要求

每次交付必须满足：

1. npm run build 通过，控制台无报错
2. 用 mcp__chrome-devtools__navigate_page 遍历所有新增/修改路由
3. 与对应 Sketch 截图并排比对，视觉不一致需修改到一致
4. mcp__chrome-devtools__list_console_messages 返回 0 个 error
5. 关键交互（搜索/分页/新增/编辑/删除/弹窗）至少手测一次