# AGENTS.md

## 项目概览

这是一个食品标签管理平台仓库，包含多端实现：

- `泰额版/Food Labeling Management Platform/`：React 18 + TypeScript + Vite 6 的泰额版 Web 管理端
- `美国版/Food Labeling Management Platform/`：React 18 + TypeScript + Vite 6 的美国版 Web 管理端
- `美国版/Food Labeling Management App UniApp/`：uni-app + Vue 3 + TypeScript 的员工端/打印端
- `美国版/Food Labeling Management Code/Yi.Abp.Net8/`：.NET 8 + SqlSugar 的后端代码
- `打印机SDK/uniapp/`：打印机相关 SDK 与插件资源

详细上下文见：`.codex/project/project-context.md`

## 本仓库对 Codex 的工作约束

1. **不要修改 `.cursor/` 下任何文件**；它们是参考来源。
2. 若需使用 `.cursor` 中的规则、agents、skills，请优先读取 `.codex/` 下的镜像内容：
   - 角色：`.codex/agents/*.md`
   - 技能：`.codex/skills/*/SKILL.md`
3. 当前仓库存在用户未提交改动；修改前先查看 `git status`，避免覆盖已有工作。
4. 当 `.cursor` 中的旧规则与当前代码事实冲突时：
   - 当前项目真实技术栈优先
   - 用户明确要求优先
   - 其余再参考 `.cursor` 约束

## 任务路由建议

### 1. 后端 / API / SqlSugar / 数据库
参考：`.codex/agents/backend-developer.md`

同时按需读取：
- `.codex/skills/api-xml-comments/SKILL.md`
- `.codex/skills/api-interface-testing/SKILL.md`
- `.codex/skills/mcp-mysql-and-sql-validation/SKILL.md`
- `.codex/skills/deprecated-tables-context/SKILL.md`

### 2. Web 前端 / 页面 / 组件
参考：`.codex/agents/frontend-developer.md`

但请注意：
- `.cursor` 内前端描述偏 Vue 2 / Element UI
- 当前本仓库 Web 端实际是 React 18 + TypeScript + Vite 6
- 所以实现时要延续现有 React 目录与组件模式，不要机械套用 Vue 2 规范

### 3. 测试 / 验证
参考：
- `.codex/agents/test-engineer.md`
- `.codex/agents/verifier.md`
- `.codex/skills/api-interface-testing/SKILL.md`

## 从 `.cursor` 继承的关键约束

以下规则来自 `.cursor`，在与当前模块匹配时应优先遵守：

- 回复前缀使用“`大哥`”
- 后端 ID 使用 `YitIdHelper.NextId().ToString()`，禁止 `Guid.NewGuid()`
- 状态/类型等固定值使用 enum，避免魔法数字
- 列表接口必须分页
- 统计接口与列表接口的过滤条件、时间范围、权限控制保持一致
- 新增/修改接口后要做接口测试
- 涉及统计 SQL、真实业务数据、落库验证时，要查库核对，不要只看接口返回
- 没有明确要求时，不要随意新增说明文档；本次因用户明确要求，可新增这些迁移说明文件

## 建议的工作顺序

1. 先读 `.codex/project/project-context.md`
2. 再根据任务类型读对应 `.codex/agents/*.md`
3. 如涉及专项流程，再读对应 `.codex/skills/*/SKILL.md`
4. 动手前确认目标模块真实技术栈，避免被旧规则误导