# 项目开发规范（Codex 可读版）

本文件是 `.cursor/rules/project_rules.mdc` 的项目级镜像，方便非 Cursor 工具直接阅读；如有差异，以 `.cursor/` 下原始规则与技能说明为准。

## 技术栈

- 后端：ASP.NET Core + SqlSugar + JWT + Serilog
- 管理后台 / 门店 PC：Vue 2 + Element UI + Axios + Vuex
- 移动端：uni-app

## 前端规范

- Node.js 固定使用 `16.20.2`
- GET 请求使用 `data`，不要使用 `params`
- 表格统一优先 `NCC-table`
- 弹窗、二级页面、复杂表单必须拆分为独立组件
- 组件文件名使用 `kebab-case`
- 操作按钮左对齐；列表不换行；空值显示“无”
- 卡片高度 100px、内边距 12px、圆角 12px

## 后端规范

- 分层固定：`Entitys -> Interfaces -> Services`
- `Extend` 里的 Service 可直接暴露，不需要额外建 Controller
- 新增 ID 必须用 `YitIdHelper.NextId().ToString()`
- 固定值必须使用 `enum`，并补 XML 注释
- 列表接口必须分页
- 查询优先 `WhereIF`，避免 SQL 注入
- 关键方法与 API 要补 XML 注释
- 统一异常处理，返回友好错误

## 数据与统计规范

- 统计接口和列表接口必须保持相同筛选条件、时间范围、权限控制
- DTO 字段名、大小写、分页逻辑必须保持一致
- 人员相关优先使用 `BASE_USER`
- 门店归属按月份使用 `lq_md_target`
- 数据库说明文档位于：`项目文档相关/docs/数据库说明.md`

## MCP / 技能参考

- 项目规则原文：`.cursor/rules/project_rules.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`

## MCP 同步

Cursor MCP 源配置在 `.cursor/mcp.json`，Codex 可执行：

```bash
python3 项目文档相关/scripts/py/sync_cursor_mcp_to_codex.py
```

如需只预览将要写入的配置：

```bash
python3 项目文档相关/scripts/py/sync_cursor_mcp_to_codex.py --dry-run
```