项目开发规范（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 可执行：

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

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

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