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` 表中