绿纤美业 ERP · Codex 工作指引

本文件用于把项目内原本主要写给 Cursor 的规则，整理成 Codex 更容易直接遵循的版本；.cursor/ 仍然保留为原始资料。

1. 项目总览

• 后端：netcore/，ASP.NET Core + SqlSugar + JWT + Serilog
• 管理后台：antis-ncc-admin/，Vue 2 + Element UI
• 门店 PC：store-pc/，Vue 2 + Element UI
• 移动端：绿纤uni-app/，uni-app
• 文档/脚本/SQL：项目文档相关/
• 导出目录：ExportFiles/

2. 关键目录定位

• 后端主入口：netcore/src/Application/NCC.API/
• 业务核心模块：netcore/src/Modularity/Extend/
• 后端分层：Entitys -> Interfaces -> Services
• 管理后台页面：antis-ncc-admin/src/views/
• 管理后台接口：antis-ncc-admin/src/api/
• 门店 PC 页面：store-pc/src/views/
• uni-app 页面：绿纤uni-app/pages/、绿纤uni-app/pagesA/

3. 必须遵守的硬规则

通用

• 默认回复前缀使用“大哥”。
• 未被明确要求时，不要顺手新增 Markdown 文档。
• 单次改动保持最小化，先看上下游再改。

前端

• Node.js 必须使用 16.20.2。
• Vue 侧 GET 请求统一使用 data，不要用 params。
• 表格优先使用 NCC-table。
• 弹窗、二级页、复杂表单必须拆成独立 .vue 文件。
• 文件命名使用 kebab-case。
• 操作按钮左对齐；列表内容不换行；空值显示“无”。

后端

• 不需要在 NCC.API 新建 Controller；Extend 中的 Service 会直接暴露。
• 新实体 ID 必须使用 YitIdHelper.NextId().ToString()，禁止 Guid.NewGuid()。
• 固定状态/类型必须使用 enum，并写 XML 注释。
• 列表接口必须分页。
• 查询条件优先 WhereIF，避免拼接 SQL。
• 统计接口与列表接口必须使用完全一致的筛选条件、时间范围、权限控制与字段命名。
• 关键 API / 方法需要 XML 注释。

数据口径

• 人员信息优先使用 BASE_USER，不要再依赖 lq_ryzl。
• 门店归属按月份从 lq_md_target 取，不要使用 lq_mdxx 上已弃用归属字段。
• 表结构/字段说明变更后，要同步更新 项目文档相关/docs/数据库说明.md。

4. Codex 遇到相关任务时应优先看的资料

• 项目总规则：.cursor/rules/project_rules.mdc
• API XML 注释：.cursor/skills/api-xml-comments/SKILL.md
• 接口测试流程：.cursor/skills/api-interface-testing/SKILL.md
• 查库 / SQL 验证：.cursor/skills/mcp-mysql-and-sql-validation/SKILL.md
• 已弃用表说明：.cursor/skills/deprecated-tables-context/SKILL.md
• 规则/技能持久化方式：.cursor/skills/remember-as-rule-or-skill/SKILL.md
• UI/UX 资料：.cursor/skills/ui-ux-pro-max/SKILL.md

5. MCP 约定

• Cursor 的 MCP 源配置在：.cursor/mcp.json
• Codex 同步脚本：python3 项目文档相关/scripts/py/sync_cursor_mcp_to_codex.py
• 建议把 .cursor/mcp.json 当作项目内 MCP 的单一事实来源；若修改了它，再同步到 Codex。

6. 常用启动命令

后端

cd netcore/src/Application/NCC.API
dotnet restore
dotnet run

管理后台

cd antis-ncc-admin
npm install
npm run dev

门店 PC

cd store-pc
npm install
npm run dev

7. 任务处理建议

• 后端问题优先看 netcore/src/Modularity/Extend/ 及相关 Entitys/Interfaces/Services
• 管理后台问题优先看 antis-ncc-admin/src/views、src/api
• 门店端问题优先看 store-pc/src/views
• 涉及真实业务数据、统计口径、SQL 正确性时，优先使用 MCP 查库验证