antissoft / lvqianmeiye_ERP

Commit 073fdd9a9c87ffbdeaaf3c66737e44d214434958

Authored by “wangming”
1 parent 31673a02

chore: remove PROJECT_RULES.md file 

- Deleted the comprehensive project development guidelines document, which included technical stacks, development standards, and database norms.
Inline Side-by-side
Showing 1 changed file with 0 additions and 245 deletions
PROJECT_RULES.md deleted
View file @31673a0
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   -- **弹窗显示**: 弹窗需要使用圆角 12px
39   -
40   -### 性能要求
41   -- 启用懒加载和代码分割
42   -- Vuex 仅缓存必要数据
43   -- 页面加载时间 < 3s
44   -
45   -## ⚙️ 后端开发规范
46   -
47   -### 架构规范
48   -- **分层架构**: Entitys → Interfaces → Services
49   -- **依赖注入**: 使用 ASP.NET Core DI 容器
50   -- **异常处理**: 全局捕获，统一 JSON 格式返回
51   -
52   -### 数据访问规范
53   -- **分页查询**: 所有列表接口必须分页
54   -- **索引优化**: 关键字段建立索引
55   -- **SQL安全**: 使用 WhereIF 条件查询避免 SQL 注入
56   -- **查询优化**: 避免 N+1 查询，使用 JOIN 优化
57   -
58   -### 代码规范
59   -- **XML注释**: 关键方法必须添加 XML 注释
60   -- **异常处理**: 统一异常处理，返回友好错误信息
61   -- **枚举使用**: 状态、类型等固定值必须使用枚举，禁止魔法数字
62   -
63   -### ID生成规范
64   -```csharp
65   -// ✅ 正确：必须使用YitIdHelper
66   -Id = YitIdHelper.NextId().ToString()
67   -
68   -// ❌ 错误：禁止使用Guid
69   -Id = Guid.NewGuid().ToString()
70   -```
71   -
72   -## 🗄️ 数据库规范
73   -
74   -### 命名规范
75   -- **表命名**: 业务前缀 + 功能名称 (如: lq_)
76   -- **字段命名**: 驼峰化
77   -- **时间字段**: 统一使用 DateTime 类型
78   -
79   -### 查询规范
80   -- **分页查询**: 避免全表扫描
81   -- **索引建立**: 关键查询字段建立索引
82   -- **删除标记**: `base_organize.DeleteMark` 为 `null` 表示未删除
83   -
84   -### MCP MySQL 使用规范
85   -- **只支持**: SELECT 语句
86   -- **查看表结构**:
87   - ```sql
88   - SELECT COLUMN_NAME, DATA_TYPE, IS_NULLABLE, COLUMN_KEY, COLUMN_DEFAULT, EXTRA, COLUMN_COMMENT
89   - FROM INFORMATION_SCHEMA.COLUMNS
90   - WHERE TABLE_NAME = '<表名>';
91   - ```
92   -
93   -### 数据库文档要求
94   -- **文档维护**: 所有数据库信息记录到 `数据库说明.md`
95   -- **表结构记录**: 表名、字段名、字段解释、字段关联
96   -- **变更同步**: 表结构变更时同步更新文档
97   -
98   -### SQL查询验证规范
99   -- **统计SQL验证**: 对于统计类型的SQL查询，在提交代码前必须先使用MCP MySQL工具执行验证
100   -- **验证要求**:
101   - - 确保SQL语法正确
102   - - 验证字段存在且类型匹配
103   - - 检查JOIN关系正确
104   - - 确认统计逻辑准确
105   - - 使用实际数据测试返回结果
106   -- **验证通过**: 只有验证通过的SQL才能提交到代码中
107   -
108   -## 🔌 API接口规范
109   -
110   -### 接口注释规范
111   -所有API接口方法必须按照以下标准格式编写XML注释：
112   -
113   -```csharp
114   -/// <summary>
115   -/// 接口功能描述（简洁明了的一句话）
116   -/// </summary>
117   -/// <remarks>
118   -/// 详细功能说明和使用场景
119   -///
120   -/// 示例请求：
121   -/// ```json
122   -/// {
123   -/// "参数名": "参数值",
124   -/// "参数名2": "参数值2"
125   -/// }
126   -/// ```
127   -///
128   -/// 参数说明：
129   -/// - 参数名: 参数描述
130   -/// - 参数名2: 参数描述
131   -/// </remarks>
132   -/// <param name="参数名">参数描述</param>
133   -/// <returns>返回值描述</returns>
134   -/// <response code="200">成功响应描述</response>
135   -/// <response code="400">错误响应描述</response>
136   -/// <response code="500">服务器错误描述</response>
137   -```
138   -
139   -### 注释要求
140   -- `<summary>` 必须简洁明了，一句话概括功能
141   -- `<remarks>` 包含详细说明、示例请求、参数说明
142   -- 示例请求使用JSON格式，参数说明使用列表格式
143   -- 必须包含所有可能的HTTP状态码响应说明
144   -- 复杂接口必须提供完整的请求示例
145   -
146   -### 接口测试规范
147   -- **必须测试**: 所有新开发的接口或修改的接口都必须进行测试
148   -- **测试要求**:
149   - - 使用实际数据测试接口功能
150   - - 验证接口返回数据的正确性
151   - - 测试边界情况和异常情况
152   - - 验证接口性能和响应时间
153   - - 确保接口符合业务逻辑要求
154   -- **测试方式**: 可以使用 curl、Postman、Swagger 等工具进行接口测试
155   -- **测试通过**: 只有测试通过的接口才能提交代码
156   -- **测试token获取**：
157   - - **接口地址**: `/api/oauth/Login`
158   - - **请求方式**: POST
159   - - **Content-Type**: `application/x-www-form-urlencoded`
160   - - **请求参数**:
161   - - `account`: `admin`
162   - - `password`: `e10adc3949ba59abbe56e057f20f883e`
163   - - **curl示例**:
164   - ```bash
165   - curl -X POST "http://localhost:2011/api/oauth/Login" \
166   - -H "Content-Type: application/x-www-form-urlencoded" \
167   - -d "account=admin&password=e10adc3949ba59abbe56e057f20f883e"
168   - ```
169   - - **返回格式**:
170   - ```json
171   - {
172   - "code": 200,
173   - "msg": "操作成功",
174   - "data": {
175   - "theme": "functional",
176   - "token": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
177   - "user": null
178   - }
179   - }
180   - ```
181   - - **token使用**: 返回的token已包含"Bearer "前缀，可直接在请求头中使用：`Authorization: {data.token}`
182   -
183   -
184   -## 📊 数据一致性规范
185   -
186   -### 统计与列表数据
187   -- **数据一致性**: 统计接口与列表接口使用相同的过滤条件、时间范围、权限控制
188   -- **字段命名规范**: DTO字段名称、大小写必须完全一致
189   -- **计算逻辑统一**: 统计数据计算逻辑与列表数据筛选逻辑保持一致
190   -- **权限过滤**: 所有数据查询必须添加相同的园区权限过滤条件
191   -- **分页一致性**: 统计接口和列表接口的分页参数和逻辑必须保持一致
192   -
193   -## 📝 代码质量规范
194   -
195   -### 代码风格
196   -- **缩进**: 2 空格
197   -- **行长度**: 单行 <= 120 字符
198   -- **注释**: 关键逻辑必须添加注释
199   -
200   -### 代码审查
201   -- **自检**: 提交前进行自检
202   -- **审查**: 重要功能需代码审查
203   -
204   -## ⚠️ 特殊要求
205   -
206   -### 前端特殊要求
207   -- 操作按钮必须左对齐，不要居中
208   -- 统计卡片内容必须垂直居中
209   -- 所有列表数据都要有图标显示，不同类型的图标需要有不同的颜色，但是颜色不能太多
210   -- 没有信息的字段显示"无"
211   -- 卡片高度统一为100px，内边距12px，圆角12px
212   -- 弹窗、二级页面、复杂表单等必须单独创建 Vue 文件或封装成组件
213   -- 禁止在主页面的 template 中直接编写弹窗内容或复杂交互逻辑
214   -- 组件文件命名使用 kebab-case，如：user-dialog.vue、edit-form.vue
215   -- 列表数据不能换行
216   -
217   -### 后端特殊要求
218   -- 使用 WhereIF 条件查询避免 SQL 注入
219   -- 关键方法必须添加 XML 注释
220   -- 统一异常处理，返回友好错误信息
221   -- 系统内涉及状态、类型等固定值的字段必须使用枚举类型（enum）定义，禁止使用魔法数字或硬编码字符串；同时需为枚举成员添加 XML 注释，保证可读性与可维护性
222   -- 不需要在NCC.API创建controller，因为Extend里面的service都是可以直接使用的
223   -
224   -## 🚨 强制约束
225   -
226   -### 环境要求
227   -1. **Node.js版本**: 必须使用16.20.2版本，项目在Node 18下会失败
228   -2. **API传参**: GET请求使用data字段传参，不使用params
229   -
230   -### 功能要求
231   -3. **权限控制**: 所有数据查询必须添加园区权限过滤
232   -4. **数据一致性**: 统计数据和列表数据必须使用相同的过滤条件
233   -5. **UI一致性**: 所有页面必须使用统一的布局和样式规范
234   -6. **错误处理**: 统一异常处理，返回友好错误信息
235   -7. **性能优化**: 所有列表接口支持分页，避免大数据量查询
236   -8. **安全防护**: 使用SqlSugar ORM防止SQL注入，前端数据渲染时进行HTML转义
237   -9. **数据库文档**: 所有数据库表结构、字段说明、关联关系必须记录到数据库说明文档中
238   -10. **ID生成规范**: 所有实体ID的生成都必须使用 `YitIdHelper.NextId().ToString()`，禁止使用 `Guid.NewGuid().ToString()` 或其他ID生成方式
239   -11.**说明文档规范**:没有要求生成新的md文件的时候，严禁生成新md文件。
240   -
241   -## 📋 重要变更记录
242   -
243   -### 已弃用的表
244   -- **lq_ryzl (人员资料表) 已弃用**: 人员信息现在统一使用系统用户表 `BASE_USER` 管理
245   -- **lq_mdxx_mdgs (门店归属表) 已弃用**: 门店归属信息已整合到 `lq_mdxx` 表中