antissoft / lvqianmeiye_ERP

PROJECT_RULES.md 8.82 KB

绿纤美业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 仅缓存必要数据
  • 页面加载时间

⚙️ 后端开发规范

架构规范

  • 分层架构: Entitys → Interfaces → Services
  • 依赖注入: 使用 ASP.NET Core DI 容器
  • 异常处理: 全局捕获，统一 JSON 格式返回

数据访问规范

  • 分页查询: 所有列表接口必须分页
  • 索引优化: 关键字段建立索引
  • SQL安全: 使用 WhereIF 条件查询避免 SQL 注入
  • 查询优化: 避免 N+1 查询，使用 JOIN 优化

代码规范

  • XML注释: 关键方法必须添加 XML 注释
  • 异常处理: 统一异常处理，返回友好错误信息
  • 枚举使用: 状态、类型等固定值必须使用枚举，禁止魔法数字

ID生成规范

// ✅ 正确：必须使用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注释：

/// <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 空格
  • 行长度: 单行
  • 注释: 关键逻辑必须添加注释

代码审查

  • 自检: 提交前进行自检
  • 审查: 重要功能需代码审查

⚠️ 特殊要求

前端特殊要求

  • 操作按钮必须左对齐，不要居中
  • 统计卡片内容必须垂直居中
  • 所有列表数据都要有图标显示，不同类型的图标需要有不同的颜色，但是颜色不能太多
  • 没有信息的字段显示"无"
  • 卡片高度统一为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

功能要求

  1. 权限控制: 所有数据查询必须添加园区权限过滤
  2. 数据一致性: 统计数据和列表数据必须使用相同的过滤条件
  3. UI一致性: 所有页面必须使用统一的布局和样式规范
  4. 错误处理: 统一异常处理，返回友好错误信息
  5. 性能优化: 所有列表接口支持分页，避免大数据量查询
  6. 安全防护: 使用SqlSugar ORM防止SQL注入，前端数据渲染时进行HTML转义
  7. 数据库文档: 所有数据库表结构、字段说明、关联关系必须记录到数据库说明文档中
  8. ID生成规范: 所有实体ID的生成都必须使用 YitIdHelper.NextId().ToString()，禁止使用 Guid.NewGuid().ToString() 或其他ID生成方式 11.说明文档规范:没有要求生成新的md文件的时候，严禁生成新md文件。

📋 重要变更记录

已弃用的表

  • lq_ryzl (人员资料表) 已弃用: 人员信息现在统一使用系统用户表 BASE_USER 管理
  • lq_mdxx_mdgs (门店归属表) 已弃用: 门店归属信息已整合到 lq_mdxx 表中