diff --git a/PROJECT_RULES.md b/PROJECT_RULES.md new file mode 100644 index 0000000..48c51c9 --- /dev/null +++ b/PROJECT_RULES.md @@ -0,0 +1,206 @@ +# 绿纤美业ERP系统 - 项目开发规范 + +## 🛠 技术栈 + +### 前端技术栈 +- **框架**: Vue 2.6 + Element UI +- **样式**: SCSS (scoped) +- **HTTP客户端**: Axios +- **状态管理**: Vuex +- **构建工具**: Webpack + +### 后端技术栈 +- **框架**: ASP.NET Core +- **ORM**: SqlSugar +- **认证**: JWT Token +- **日志**: Serilog +- **架构**: 分层架构 (Entitys/Interfaces/Services) + +## 🎨 前端开发规范 + +### 组件开发规范 +- ✅ **模块化**: views 与 components 分离 +- ✅ **文件命名**: 使用 kebab-case (如: user-dialog.vue) +- ✅ **组件封装**: 弹窗、二级页面必须单独创建 Vue 文件 +- ❌ **禁止**: 在主页面 template 中直接编写弹窗内容 + +### UI/UX 规范 +- **表格组件**: 统一使用 NCC-table +- **表单组件**: Element UI 表单,标签右对齐 +- **色彩规范**: + - 主色: `#409EFF` + - 辅助色: `#67C23A` / `#F56C6C` / `#909399` +- **卡片规范**: 高度 100px,内边距 12px,圆角 12px +- **按钮对齐**: 操作按钮左对齐,统计卡片内容垂直居中 +- **图标显示**: 所有列表数据都要有图标,不同颜色区分类型 +- **空值显示**: 没有信息的字段显示"无" +- **列表规范**: 列表数据不能换行 + +### 性能要求 +- 启用懒加载和代码分割 +- Vuex 仅缓存必要数据 +- 页面加载时间 < 3s + +## ⚙️ 后端开发规范 + +### 架构规范 +- **分层架构**: Entitys → Interfaces → Services +- **依赖注入**: 使用 ASP.NET Core DI 容器 +- **异常处理**: 全局捕获,统一 JSON 格式返回 + +### 数据访问规范 +- **分页查询**: 所有列表接口必须分页 +- **索引优化**: 关键字段建立索引 +- **SQL安全**: 使用 WhereIF 条件查询避免 SQL 注入 +- **查询优化**: 避免 N+1 查询,使用 JOIN 优化 + +### 代码规范 +- **XML注释**: 关键方法必须添加 XML 注释 +- **异常处理**: 统一异常处理,返回友好错误信息 +- **枚举使用**: 状态、类型等固定值必须使用枚举,禁止魔法数字 + +### ID生成规范 +```csharp +// ✅ 正确:必须使用YitIdHelper +Id = YitIdHelper.NextId().ToString() + +// ❌ 错误:禁止使用Guid +Id = Guid.NewGuid().ToString() +``` + +## 🗄️ 数据库规范 + +### 命名规范 +- **表命名**: 业务前缀 + 功能名称 (如: lq_) +- **字段命名**: 驼峰化 +- **时间字段**: 统一使用 DateTime 类型 + +### 查询规范 +- **分页查询**: 避免全表扫描 +- **索引建立**: 关键查询字段建立索引 +- **删除标记**: `base_organize.DeleteMark` 为 `null` 表示未删除 + +### MCP MySQL 使用规范 +- **只支持**: SELECT 语句 +- **查看表结构**: + ```sql + SELECT COLUMN_NAME, DATA_TYPE, IS_NULLABLE, COLUMN_KEY, COLUMN_DEFAULT, EXTRA, COLUMN_COMMENT + FROM INFORMATION_SCHEMA.COLUMNS + WHERE TABLE_NAME = '<表名>'; + ``` + +### 数据库文档要求 +- **文档维护**: 所有数据库信息记录到 `数据库说明.md` +- **表结构记录**: 表名、字段名、字段解释、字段关联 +- **变更同步**: 表结构变更时同步更新文档 + +### SQL查询验证规范 +- **统计SQL验证**: 对于统计类型的SQL查询,在提交代码前必须先使用MCP MySQL工具执行验证 +- **验证要求**: + - 确保SQL语法正确 + - 验证字段存在且类型匹配 + - 检查JOIN关系正确 + - 确认统计逻辑准确 + - 使用实际数据测试返回结果 +- **验证通过**: 只有验证通过的SQL才能提交到代码中 + +## 🔌 API接口规范 + +### 接口注释规范 +所有API接口方法必须按照以下标准格式编写XML注释: + +```csharp +/// +/// 接口功能描述(简洁明了的一句话) +/// +/// +/// 详细功能说明和使用场景 +/// +/// 示例请求: +/// ```json +/// { +/// "参数名": "参数值", +/// "参数名2": "参数值2" +/// } +/// ``` +/// +/// 参数说明: +/// - 参数名: 参数描述 +/// - 参数名2: 参数描述 +/// +/// 参数描述 +/// 返回值描述 +/// 成功响应描述 +/// 错误响应描述 +/// 服务器错误描述 +``` + +### 注释要求 +- `` 必须简洁明了,一句话概括功能 +- `` 包含详细说明、示例请求、参数说明 +- 示例请求使用JSON格式,参数说明使用列表格式 +- 必须包含所有可能的HTTP状态码响应说明 +- 复杂接口必须提供完整的请求示例 + +## 📊 数据一致性规范 + +### 统计与列表数据 +- **数据一致性**: 统计接口与列表接口使用相同的过滤条件、时间范围、权限控制 +- **字段命名规范**: DTO字段名称、大小写必须完全一致 +- **计算逻辑统一**: 统计数据计算逻辑与列表数据筛选逻辑保持一致 +- **权限过滤**: 所有数据查询必须添加相同的园区权限过滤条件 +- **分页一致性**: 统计接口和列表接口的分页参数和逻辑必须保持一致 + +## 📝 代码质量规范 + +### 代码风格 +- **缩进**: 2 空格 +- **行长度**: 单行 <= 120 字符 +- **注释**: 关键逻辑必须添加注释 + +### 代码审查 +- **自检**: 提交前进行自检 +- **审查**: 重要功能需代码审查 + +## ⚠️ 特殊要求 + +### 前端特殊要求 +- 操作按钮必须左对齐,不要居中 +- 统计卡片内容必须垂直居中 +- 所有列表数据都要有图标显示,不同类型的图标需要有不同的颜色,但是颜色不能太多 +- 没有信息的字段显示"无" +- 卡片高度统一为100px,内边距12px,圆角12px +- 弹窗、二级页面、复杂表单等必须单独创建 Vue 文件或封装成组件 +- 禁止在主页面的 template 中直接编写弹窗内容或复杂交互逻辑 +- 组件文件命名使用 kebab-case,如:user-dialog.vue、edit-form.vue +- 列表数据不能换行 + +### 后端特殊要求 +- 使用 WhereIF 条件查询避免 SQL 注入 +- 关键方法必须添加 XML 注释 +- 统一异常处理,返回友好错误信息 +- 系统内涉及状态、类型等固定值的字段必须使用枚举类型(enum)定义,禁止使用魔法数字或硬编码字符串;同时需为枚举成员添加 XML 注释,保证可读性与可维护性 +- 不需要在NCC.API创建controller,因为Extend里面的service都是可以直接使用的 + +## 🚨 强制约束 + +### 环境要求 +1. **Node.js版本**: 必须使用16.20.2版本,项目在Node 18下会失败 +2. **API传参**: GET请求使用data字段传参,不使用params + +### 功能要求 +3. **权限控制**: 所有数据查询必须添加园区权限过滤 +4. **数据一致性**: 统计数据和列表数据必须使用相同的过滤条件 +5. **UI一致性**: 所有页面必须使用统一的布局和样式规范 +6. **错误处理**: 统一异常处理,返回友好错误信息 +7. **性能优化**: 所有列表接口支持分页,避免大数据量查询 +8. **安全防护**: 使用SqlSugar ORM防止SQL注入,前端数据渲染时进行HTML转义 +9. **数据库文档**: 所有数据库表结构、字段说明、关联关系必须记录到数据库说明文档中 +10. **ID生成规范**: 所有实体ID的生成都必须使用 `YitIdHelper.NextId().ToString()`,禁止使用 `Guid.NewGuid().ToString()` 或其他ID生成方式 +11.**说明文档规范**:没有要求生成新的md文件的时候,严禁生成新md文件。 + +## 📋 重要变更记录 + +### 已弃用的表 +- **lq_ryzl (人员资料表) 已弃用**: 人员信息现在统一使用系统用户表 `BASE_USER` 管理 +- **lq_mdxx_mdgs (门店归属表) 已弃用**: 门店归属信息已整合到 `lq_mdxx` 表中