antissoft / lvqianmeiye_ERP

Commit 2bea36e275b950fb49d9a1ca0e000ea78c3f0698

Authored by “wangming”
1 parent 28b8ebfb

docs: add project rules documentation

Inline Side-by-side
Showing 1 changed file with 206 additions and 0 deletions
PROJECT_RULES.md 0 → 100644
  View file @2bea36e
  1 +# 绿纤美业ERP系统 - 项目开发规范
  2 +
  3 +## 🛠 技术栈
  4 +
  5 +### 前端技术栈
  6 +- **框架**: Vue 2.6 + Element UI
  7 +- **样式**: SCSS (scoped)
  8 +- **HTTP客户端**: Axios
  9 +- **状态管理**: Vuex
  10 +- **构建工具**: Webpack
  11 +
  12 +### 后端技术栈
  13 +- **框架**: ASP.NET Core
  14 +- **ORM**: SqlSugar
  15 +- **认证**: JWT Token
  16 +- **日志**: Serilog
  17 +- **架构**: 分层架构 (Entitys/Interfaces/Services)
  18 +
  19 +## 🎨 前端开发规范
  20 +
  21 +### 组件开发规范
  22 +- ✅ **模块化**: views 与 components 分离
  23 +- ✅ **文件命名**: 使用 kebab-case (如: user-dialog.vue)
  24 +- ✅ **组件封装**: 弹窗、二级页面必须单独创建 Vue 文件
  25 +- ❌ **禁止**: 在主页面 template 中直接编写弹窗内容
  26 +
  27 +### UI/UX 规范
  28 +- **表格组件**: 统一使用 NCC-table
  29 +- **表单组件**: Element UI 表单，标签右对齐
  30 +- **色彩规范**:
  31 + - 主色: `#409EFF`
  32 + - 辅助色: `#67C23A` / `#F56C6C` / `#909399`
  33 +- **卡片规范**: 高度 100px，内边距 12px，圆角 12px
  34 +- **按钮对齐**: 操作按钮左对齐，统计卡片内容垂直居中
  35 +- **图标显示**: 所有列表数据都要有图标，不同颜色区分类型
  36 +- **空值显示**: 没有信息的字段显示"无"
  37 +- **列表规范**: 列表数据不能换行
  38 +
  39 +### 性能要求
  40 +- 启用懒加载和代码分割
  41 +- Vuex 仅缓存必要数据
  42 +- 页面加载时间 < 3s
  43 +
  44 +## ⚙️ 后端开发规范
  45 +
  46 +### 架构规范
  47 +- **分层架构**: Entitys → Interfaces → Services
  48 +- **依赖注入**: 使用 ASP.NET Core DI 容器
  49 +- **异常处理**: 全局捕获，统一 JSON 格式返回
  50 +
  51 +### 数据访问规范
  52 +- **分页查询**: 所有列表接口必须分页
  53 +- **索引优化**: 关键字段建立索引
  54 +- **SQL安全**: 使用 WhereIF 条件查询避免 SQL 注入
  55 +- **查询优化**: 避免 N+1 查询，使用 JOIN 优化
  56 +
  57 +### 代码规范
  58 +- **XML注释**: 关键方法必须添加 XML 注释
  59 +- **异常处理**: 统一异常处理，返回友好错误信息
  60 +- **枚举使用**: 状态、类型等固定值必须使用枚举，禁止魔法数字
  61 +
  62 +### ID生成规范
  63 +```csharp
  64 +// ✅ 正确：必须使用YitIdHelper
  65 +Id = YitIdHelper.NextId().ToString()
  66 +
  67 +// ❌ 错误：禁止使用Guid
  68 +Id = Guid.NewGuid().ToString()
  69 +```
  70 +
  71 +## 🗄️ 数据库规范
  72 +
  73 +### 命名规范
  74 +- **表命名**: 业务前缀 + 功能名称 (如: lq_)
  75 +- **字段命名**: 驼峰化
  76 +- **时间字段**: 统一使用 DateTime 类型
  77 +
  78 +### 查询规范
  79 +- **分页查询**: 避免全表扫描
  80 +- **索引建立**: 关键查询字段建立索引
  81 +- **删除标记**: `base_organize.DeleteMark` 为 `null` 表示未删除
  82 +
  83 +### MCP MySQL 使用规范
  84 +- **只支持**: SELECT 语句
  85 +- **查看表结构**:
  86 + ```sql
  87 + SELECT COLUMN_NAME, DATA_TYPE, IS_NULLABLE, COLUMN_KEY, COLUMN_DEFAULT, EXTRA, COLUMN_COMMENT
  88 + FROM INFORMATION_SCHEMA.COLUMNS
  89 + WHERE TABLE_NAME = '<表名>';
  90 + ```
  91 +
  92 +### 数据库文档要求
  93 +- **文档维护**: 所有数据库信息记录到 `数据库说明.md`
  94 +- **表结构记录**: 表名、字段名、字段解释、字段关联
  95 +- **变更同步**: 表结构变更时同步更新文档
  96 +
  97 +### SQL查询验证规范
  98 +- **统计SQL验证**: 对于统计类型的SQL查询，在提交代码前必须先使用MCP MySQL工具执行验证
  99 +- **验证要求**:
  100 + - 确保SQL语法正确
  101 + - 验证字段存在且类型匹配
  102 + - 检查JOIN关系正确
  103 + - 确认统计逻辑准确
  104 + - 使用实际数据测试返回结果
  105 +- **验证通过**: 只有验证通过的SQL才能提交到代码中
  106 +
  107 +## 🔌 API接口规范
  108 +
  109 +### 接口注释规范
  110 +所有API接口方法必须按照以下标准格式编写XML注释：
  111 +
  112 +```csharp
  113 +/// <summary>
  114 +/// 接口功能描述（简洁明了的一句话）
  115 +/// </summary>
  116 +/// <remarks>
  117 +/// 详细功能说明和使用场景
  118 +///
  119 +/// 示例请求：
  120 +/// ```json
  121 +/// {
  122 +/// "参数名": "参数值",
  123 +/// "参数名2": "参数值2"
  124 +/// }
  125 +/// ```
  126 +///
  127 +/// 参数说明：
  128 +/// - 参数名: 参数描述
  129 +/// - 参数名2: 参数描述
  130 +/// </remarks>
  131 +/// <param name="参数名">参数描述</param>
  132 +/// <returns>返回值描述</returns>
  133 +/// <response code="200">成功响应描述</response>
  134 +/// <response code="400">错误响应描述</response>
  135 +/// <response code="500">服务器错误描述</response>
  136 +```
  137 +
  138 +### 注释要求
  139 +- `<summary>` 必须简洁明了，一句话概括功能
  140 +- `<remarks>` 包含详细说明、示例请求、参数说明
  141 +- 示例请求使用JSON格式，参数说明使用列表格式
  142 +- 必须包含所有可能的HTTP状态码响应说明
  143 +- 复杂接口必须提供完整的请求示例
  144 +
  145 +## 📊 数据一致性规范
  146 +
  147 +### 统计与列表数据
  148 +- **数据一致性**: 统计接口与列表接口使用相同的过滤条件、时间范围、权限控制
  149 +- **字段命名规范**: DTO字段名称、大小写必须完全一致
  150 +- **计算逻辑统一**: 统计数据计算逻辑与列表数据筛选逻辑保持一致
  151 +- **权限过滤**: 所有数据查询必须添加相同的园区权限过滤条件
  152 +- **分页一致性**: 统计接口和列表接口的分页参数和逻辑必须保持一致
  153 +
  154 +## 📝 代码质量规范
  155 +
  156 +### 代码风格
  157 +- **缩进**: 2 空格
  158 +- **行长度**: 单行 <= 120 字符
  159 +- **注释**: 关键逻辑必须添加注释
  160 +
  161 +### 代码审查
  162 +- **自检**: 提交前进行自检
  163 +- **审查**: 重要功能需代码审查
  164 +
  165 +## ⚠️ 特殊要求
  166 +
  167 +### 前端特殊要求
  168 +- 操作按钮必须左对齐，不要居中
  169 +- 统计卡片内容必须垂直居中
  170 +- 所有列表数据都要有图标显示，不同类型的图标需要有不同的颜色，但是颜色不能太多
  171 +- 没有信息的字段显示"无"
  172 +- 卡片高度统一为100px，内边距12px，圆角12px
  173 +- 弹窗、二级页面、复杂表单等必须单独创建 Vue 文件或封装成组件
  174 +- 禁止在主页面的 template 中直接编写弹窗内容或复杂交互逻辑
  175 +- 组件文件命名使用 kebab-case，如：user-dialog.vue、edit-form.vue
  176 +- 列表数据不能换行
  177 +
  178 +### 后端特殊要求
  179 +- 使用 WhereIF 条件查询避免 SQL 注入
  180 +- 关键方法必须添加 XML 注释
  181 +- 统一异常处理，返回友好错误信息
  182 +- 系统内涉及状态、类型等固定值的字段必须使用枚举类型（enum）定义，禁止使用魔法数字或硬编码字符串；同时需为枚举成员添加 XML 注释，保证可读性与可维护性
  183 +- 不需要在NCC.API创建controller，因为Extend里面的service都是可以直接使用的
  184 +
  185 +## 🚨 强制约束
  186 +
  187 +### 环境要求
  188 +1. **Node.js版本**: 必须使用16.20.2版本，项目在Node 18下会失败
  189 +2. **API传参**: GET请求使用data字段传参，不使用params
  190 +
  191 +### 功能要求
  192 +3. **权限控制**: 所有数据查询必须添加园区权限过滤
  193 +4. **数据一致性**: 统计数据和列表数据必须使用相同的过滤条件
  194 +5. **UI一致性**: 所有页面必须使用统一的布局和样式规范
  195 +6. **错误处理**: 统一异常处理，返回友好错误信息
  196 +7. **性能优化**: 所有列表接口支持分页，避免大数据量查询
  197 +8. **安全防护**: 使用SqlSugar ORM防止SQL注入，前端数据渲染时进行HTML转义
  198 +9. **数据库文档**: 所有数据库表结构、字段说明、关联关系必须记录到数据库说明文档中
  199 +10. **ID生成规范**: 所有实体ID的生成都必须使用 `YitIdHelper.NextId().ToString()`，禁止使用 `Guid.NewGuid().ToString()` 或其他ID生成方式
  200 +11.**说明文档规范**:没有要求生成新的md文件的时候，严禁生成新md文件。
  201 +
  202 +## 📋 重要变更记录
  203 +
  204 +### 已弃用的表
  205 +- **lq_ryzl (人员资料表) 已弃用**: 人员信息现在统一使用系统用户表 `BASE_USER` 管理
  206 +- **lq_mdxx_mdgs (门店归属表) 已弃用**: 门店归属信息已整合到 `lq_mdxx` 表中
... ...