PROJECT_RULES.md

# 绿纤美业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
/// <summary>
/// 接口功能描述（简洁明了的一句话）
/// </summary>
/// <remarks>
/// 详细功能说明和使用场景
/// 
/// 示例请求：
/// ```json
/// {
///   "参数名": "参数值",
///   "参数名2": "参数值2"
/// }
/// ```
/// 
/// 参数说明：
/// - 参数名: 参数描述
/// - 参数名2: 参数描述
/// </remarks>
/// <param name="参数名">参数描述</param>
/// <returns>返回值描述</returns>
/// <response code="200">成功响应描述</response>
/// <response code="400">错误响应描述</response>
/// <response code="500">服务器错误描述</response>
```
### 注释要求
- `<summary>` 必须简洁明了，一句话概括功能
- `<remarks>` 包含详细说明、示例请求、参数说明
- 示例请求使用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` 表中