Codex Repo Config (Nuxt Dashboard)

本文件约束 Codex 在本仓库的默认行为。所有源码、配置、脚本和文档统一使用 UTF-8。

1. 角色与目标

• 默认使用简体中文回复；代码命名沿用仓库英文风格。
• 不要假设用户清楚自己想要什么，不清晰时停下来讨论目标
• 清晰但路径不是最优时，直接建议更好的办法
• 遇到问题追根因，不打补丁，每个决策要能回答"为什么"
• 输出说重点，砍掉一切不改变决策的信息

2. 项目现状

• 项目类型：Nuxt Dashboard 前端应用。
• 技术栈：Nuxt 4、Vue 3.5、TypeScript、Composition API、<script setup lang="ts">。
• UI 与样式：Nuxt UI 4、Tailwind CSS 4、Iconify 图标。
• 工具库：VueUse、date-fns、Unovis、TanStack Table、Zod。
• 服务端接口：Nuxt Nitro server routes，模拟接口位于 server/api/。
• 包管理器：pnpm，锁文件为 pnpm-lock.yaml。
• 业务定位：Robot 装配、测试、异常、返修、完工入库全过程管理与工序级追溯系统，面向内网部署。
• MVP 边界：工单管理、SN 管理、工艺路线、工序流转、扫码开工、测试结果录入、异常/返修闭环、基础追溯查询、RBAC 权限、报表导出。
• 暂缓范围：MES/ERP/WMS 深度集成、设备自动采集、SPC、AI 分析和完整移动端，除非需求明确要求。

3. 项目目录结构

frontend/
├─ app/
│  ├─ app.vue              # 应用入口、布局和页面挂载
│  ├─ app.config.ts        # Nuxt UI 主题配置
│  ├─ error.vue            # Nuxt 错误页
│  ├─ assets/css/          # 全局样式
│  ├─ components/          # 业务组件
│  │  ├─ customers/ home/ inbox/ settings/
│  ├─ composables/         # 组合式函数
│  ├─ layouts/             # 页面布局
│  ├─ pages/               # Nuxt 文件路由页面
│  ├─ types/               # 共享业务类型
│  └─ utils/               # 通用工具函数
├─ server/api/             # Nitro API 路由与模拟数据
├─ public/                 # 静态资源
├─ nuxt.config.ts          # Nuxt 配置
├─ eslint.config.mjs       # ESLint 配置
├─ tsconfig.json           # TypeScript 配置
├─ package.json            # 脚本与依赖
├─ pnpm-lock.yaml          # pnpm 锁文件
└─ AGENTS.md               # Codex 项目规则

4. 常用命令

pnpm install      # 安装依赖
pnpm dev          # 启动开发服务器，默认 http://localhost:3000
pnpm build        # 生产构建
pnpm preview      # 本地预览生产构建
pnpm lint         # ESLint 检查
pnpm typecheck    # Nuxt / Vue 类型检查

5. 工作规则

• 修改前先阅读相关页面、组件、组合式函数、类型和 API 路由，明确数据流与交互。
• 涉及业务逻辑时同步参考 ../docs/ 下系统方案，尤其是需求建模、流程设计、前端架构、安全质量和最终架构报告。
• 小改动可以直接执行；较大改动先说明理解、假设和最小方案。
• 保持改动范围收敛，不做无关重构、不移动无关文件、不引入无关格式化。
• 非必要不新增依赖；必须新增时说明用途、替代方案和影响。
• 不改变公开路由和 API 返回结构，除非需求明确要求。
• 不删除已有错误处理、空状态、加载状态和无障碍属性。
• 涉及 useFetch、$fetch 或外部请求时，必须考虑失败、空数据和加载状态。
• 修改后优先运行最小验证命令；涉及组件、路由、类型或 API 合同时考虑 pnpm lint 和 pnpm typecheck。

6. Nuxt / Vue 约定

• 页面放在 app/pages/，布局放在 app/layouts/，复用组件放在 app/components/。
• 共享状态或跨组件交互优先放在 app/composables/。
• 服务端模拟接口放在 server/api/，使用 eventHandler 暴露 Nitro 路由。
• 类型定义集中放在 app/types/，页面和 API 返回数据尽量复用共享类型。
• 组件优先使用 Nuxt 自动导入、类型导入和现有 Nuxt UI 写法。
• 图标沿用 i-lucide-*；样式优先使用 Nuxt UI 与 Tailwind，避免全局污染。
• 修改导航、快捷键、侧边栏或通知逻辑时，重点检查 app/layouts/default.vue 与 app/composables/useDashboard.ts。

7. Review 模式

• 当用户要求 review 或代码评审时，先列问题，按严重程度从高到低排序。
• 每个问题包含文件路径、位置、原因、影响和修复建议。
• 总结放在最后；如果没有发现问题，明确说明未验证项或残留风险。

8. 功能JSON驱动开发（强制）

• 功能清单唯一来源：项目根目录 feature-plan.json。
• 后续所有实现任务必须严格按 feature-plan.json 推进，不允许脱离清单新增大功能；若需新增，先更新 JSON 再实施。
• 每次仅允许处理一个功能项（features 数组中的一项），并且优先选择状态为 待实现 或 修复中 的最靠前项，除非用户明确指定其他项。

8.1 每个功能项必填字段约束

• name：功能名称，必须唯一且可读。
• 实际需求背景：真实业务动因，描述“为什么做”。
• 验收标准：可测试、可判定通过/失败的标准列表。
• 状态：仅允许使用 待实现 | 实现中 | 测试中 | 修复中 | 测试完成 | 已完成 | 阻塞。
• 当前进行的工作：一句话说明当前进度，不允许留空。

8.2 强制执行循环

• 必须按以下循环执行，禁止跳步：
• 实现：完成当前功能最小可交付实现；进入 实现中。
• 测试：运行最小必要验证（至少包含与改动相关的 lint/typecheck/页面或接口验证）；进入 测试中。
• 修复：若测试失败，修复问题并记录修复点；进入 修复中。
• 测试完成：修复后再次测试，直到通过；进入 测试完成。
• 更新功能json：将该功能状态更新为 已完成，并更新“当前进行的工作”为完成说明与日期。
• 新会话：结束当前功能，在下一次会话开始处理下一个未完成功能。

8.3 会话输出要求

• 每次会话结束时，必须明确输出：
• 本次处理的功能 name
• 当前 状态
• 执行到循环的哪一步
• 下一步动作
• 若功能进入 阻塞，必须写明阻塞原因、影响范围、解除阻塞所需条件，并同步更新 feature-plan.json。