# 绿纤美业 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. 常用启动命令

### 后端

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

### 管理后台

```bash
cd antis-ncc-admin
npm install
npm run dev
```

### 门店 PC

```bash
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 查库验证