# 绿纤美业 ERP · Claude Code 工作指引

> 本文件供 Claude Code（CLI）自动读取。原始规则与技能仍保存在 `.cursor/` 目录下，不做任何改动。
> Claude Code 专用的 agents 在 `.claude/agents/`，slash commands 在 `.claude/commands/`，MCP 配置在 `.claude/settings.json`。

---

## 强制约定

- **回复前缀**：每次回复必须以"大哥"开头。
- 未被明确要求时，不要生成新的 Markdown 文档。
- 单次改动最小化，先看上下游再改。

---

## 项目总览

| 端 | 目录 | 技术 |
|---|---|---|
| 后端 | `netcore/` | ASP.NET Core + SqlSugar + MySQL + JWT + Serilog |
| 管理后台 | `antis-ncc-admin/` | Vue 2.6 + Element UI + Vuex + Axios |
| 门店 PC | `store-pc/` | Vue 2.6 + Element UI + Axios |
| 移动端 | `绿纤uni-app/` | uni-app（微信小程序） |
| 文档/SQL/脚本 | `项目文档相关/` | Markdown + Shell + Python + SQL |

## 关键目录

- 后端主入口：`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/`
- 数据库文档：`项目文档相关/docs/数据库说明.md`

---

## 前端规范

- Node.js 必须使用 `16.20.2`
- GET 请求统一使用 `data` 传参，不使用 `params`
- 表格优先使用 `NCC-table`
- 弹窗、二级页、复杂表单必须拆为独立 `.vue` 文件（禁止在主页面 template 内直接写）
- 文件命名使用 `kebab-case`
- 操作按钮左对齐；列表内容不换行；空值显示"无"
- 卡片高度 100px、内边距 12px、圆角 12px
- 主色 `#409EFF`，辅助色 `#67C23A` / `#F56C6C` / `#909399`

## 后端规范

- 不需要在 `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`
- `base_organize.DeleteMark` 为 `null` 表示未删除

---

## Agents（子代理）

Claude Code agents 配置在 `.claude/agents/`，对应 `.cursor/agents/` 中的角色：

| Agent | 文件 | 职责 |
|---|---|---|
| orchestrator | `.claude/agents/orchestrator.md` | 任务分析与委派 |
| 后端 | `.claude/agents/backend-developer.md` | C# API / Service / DB |
| 前端 | `.claude/agents/frontend-developer.md` | Vue 2 页面 / 组件 |
| 测试 | `.claude/agents/test-engineer.md` | 接口测试与验证 |
| verifier | `.claude/agents/verifier.md` | 最终交付验收 |

**任务分级委派原则**：
- L1（解释/评估/判断）→ 直接回答
- L2（仅后端 / 仅前端）→ 启动对应 agent
- L3（跨角色）→ 并行启动多个 agent

---

## Slash Commands（技能）

Claude Code 命令配置在 `.claude/commands/`，对应 `.cursor/skills/` 中的 skill：

| 命令 | 对应 Skill | 用途 |
|---|---|---|
| `/api-interface-testing` | `api-interface-testing` | 获取 Token、curl 接口测试流程 |
| `/api-xml-comments` | `api-xml-comments` | API XML 注释格式与模板 |
| `/deprecated-tables` | `deprecated-tables-context` | 已弃用表及替代方案 |
| `/mcp-mysql` | `mcp-mysql-and-sql-validation` | MCP MySQL 查库与 SQL 验证规范 |
| `/remember` | `remember-as-rule-or-skill` | 持久化规则或 Skill |
| `/business-operation-log` | `business-operation-log` | 删/改/作废/导出记业务日志，模块与动作用中文 |
| `/ui-ux` | `ui-ux-pro-max` | UI/UX 设计系统生成 |

---

## MCP 配置

MCP servers 配置在 `.claude/settings.json`（`mcpServers` 字段），与 `.cursor/mcp.json` 保持一致：

| 服务 | 用途 |
|---|---|
| `my-sql-db` | MySQL 只读查询（lqerp_dev），使用 `@davewind/mysql-mcp-server` |
| `my-api-spec` | OpenAPI Spec 浏览与接口调用，使用 `@ivotoby/openapi-mcp-server` |
| `filesystem` | 文件系统访问，使用 `@modelcontextprotocol/server-filesystem` |
| `excel-reader` | Excel 文件读取，使用 `@negokaz/excel-mcp-server` |

> 修改 MCP 时以 `.cursor/mcp.json` 为单一事实来源，再同步到 `.claude/settings.json`。
> 同步脚本：`python3 项目文档相关/scripts/py/sync_cursor_mcp_to_codex.py`

---

## 启动命令

```bash
# 后端
cd netcore/src/Application/NCC.API && dotnet restore && dotnet run

# 管理后台
cd antis-ncc-admin && npm install && npm run dev   # http://localhost:3000

# 门店 PC
cd store-pc && npm install && npm run dev           # http://localhost:3100
```

默认账号：`admin / 123456`，后端 API：`http://localhost:5000`，Swagger：`http://localhost:5000/antis.doc`

---

## 参考资料（原始，保留在 .cursor/）

- 项目总规则：`.cursor/rules/project_rules.mdc`
- Orchestrator 优先规则：`.cursor/rules/orchestrator-first.mdc`
- 接口测试：`.cursor/skills/api-interface-testing/SKILL.md`
- API 注释：`.cursor/skills/api-xml-comments/SKILL.md`
- 查库/SQL 验证：`.cursor/skills/mcp-mysql-and-sql-validation/SKILL.md`
- 已弃用表：`.cursor/skills/deprecated-tables-context/SKILL.md`
- 历史在职（自然月）：`.cursor/skills/historical-on-job-inference/SKILL.md`
- 规则持久化：`.cursor/skills/remember-as-rule-or-skill/SKILL.md`
- UI/UX：`.cursor/skills/ui-ux-pro-max/SKILL.md`