diff --git a/PROJECT_RULES.md b/PROJECT_RULES.md deleted file mode 100644 index 7e26d21..0000000 --- a/PROJECT_RULES.md +++ /dev/null @@ -1,245 +0,0 @@ -# 绿纤美业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 -- **按钮对齐**: 操作按钮左对齐,统计卡片内容垂直居中 -- **图标显示**: 所有列表数据都要有图标,不同颜色区分类型 -- **空值显示**: 没有信息的字段显示"无" -- **列表规范**: 列表数据不能换行 -- **弹窗显示**: 弹窗需要使用圆角 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状态码响应说明 -- 复杂接口必须提供完整的请求示例 - -### 接口测试规范 -- **必须测试**: 所有新开发的接口或修改的接口都必须进行测试 -- **测试要求**: - - 使用实际数据测试接口功能 - - 验证接口返回数据的正确性 - - 测试边界情况和异常情况 - - 验证接口性能和响应时间 - - 确保接口符合业务逻辑要求 -- **测试方式**: 可以使用 curl、Postman、Swagger 等工具进行接口测试 -- **测试通过**: 只有测试通过的接口才能提交代码 -- **测试token获取**: - - **接口地址**: `/api/oauth/Login` - - **请求方式**: POST - - **Content-Type**: `application/x-www-form-urlencoded` - - **请求参数**: - - `account`: `admin` - - `password`: `e10adc3949ba59abbe56e057f20f883e` - - **curl示例**: - ```bash - curl -X POST "http://localhost:2011/api/oauth/Login" \ - -H "Content-Type: application/x-www-form-urlencoded" \ - -d "account=admin&password=e10adc3949ba59abbe56e057f20f883e" - ``` - - **返回格式**: - ```json - { - "code": 200, - "msg": "操作成功", - "data": { - "theme": "functional", - "token": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", - "user": null - } - } - ``` - - **token使用**: 返回的token已包含"Bearer "前缀,可直接在请求头中使用:`Authorization: {data.token}` - - -## 📊 数据一致性规范 - -### 统计与列表数据 -- **数据一致性**: 统计接口与列表接口使用相同的过滤条件、时间范围、权限控制 -- **字段命名规范**: 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` 表中