antissoft / HongHua-JJ

---
description: 
alwaysApply: true
---

# 项目开发规范

## 📋 目录
- [技术栈](#技术栈)
- [前端开发规范](#前端开发规范)
- [后端开发规范](#后端开发规范)
- [数据库规范](#数据库规范)
- [API接口规范](#api接口规范)
- [数据一致性规范](#数据一致性规范)
- [代码质量规范](#代码质量规范)
- [特殊要求](#特殊要求)
- [强制约束](#强制约束)

## 🛠 技术栈

### 前端技术栈
- **框架**: 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
- **按钮对齐**: 操作按钮左对齐，统计卡片内容垂直居中
- **图标显示**: 所有列表数据都要有图标，不同颜色区分类型
- **空值显示**: 没有信息的字段显示"无"
- **列表规范**: 列表数据不能换行

### 性能要求
- 启用懒加载和代码分割
- 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()
```

## 🗄️ 数据库规范

### 命名规范
- **表命名**: 业务前缀 + 功能名称
- **字段命名**: 驼峰化
- **时间字段**: 统一使用 DateTime 类型

### 查询规范
- **分页查询**: 避免全表扫描
- **索引建立**: 关键查询字段建立索引
- **删除标记**: `base_organize.DeleteMark` 为 `null` 表示未删除

### MCP MySQL 与 SQL 验证
- 使用 MCP 查库或编写/验证统计 SQL 时，遵循 skill：`mcp-mysql-and-sql-validation`。

### 数据库文档要求
- **文档维护**: 所有数据库信息记录到 `数据库说明.md`
- **表结构记录**: 表名、字段名、字段解释、字段关联
- **变更同步**: 表结构变更时同步更新文档

## 🔌 API接口规范

### 接口注释规范
- 新增或修改 API 时，接口方法的 XML 注释格式与要求见 skill：`api-xml-comments`。

### 接口测试规范
- **必须测试**：所有新开发或修改的接口都必须测试通过后再提交；具体流程、Token 获取与 curl 示例见 skill：`api-interface-testing`。

## 📊 数据一致性规范

### 统计与列表数据
- **数据一致性**: 统计接口与列表接口使用相同的过滤条件、时间范围、权限控制
- **字段命名规范**: 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. **回复前缀**: 每次回复的时候都必须用“大哥”作为前缀

### 环境要求
1. **Node.js版本**: 必须使用16.20.2版本，项目在Node 18下会失败
2. **API传参**: GET请求使用data字段传参，不使用params

### 功能要求
4. **数据一致性**: 统计数据和列表数据必须使用相同的过滤条件
5. **UI一致性**: 所有页面必须使用统一的布局和样式规范
6. **错误处理**: 统一异常处理，返回友好错误信息
7. **性能优化**: 所有列表接口支持分页，避免大数据量查询
8. **安全防护**: 使用SqlSugar ORM防止SQL注入，前端数据渲染时进行HTML转义
9. **数据库文档**: 所有数据库表结构、字段说明、关联关系必须记录到数据库说明文档中
10. **ID生成规范**: 所有实体ID的生成都必须使用 `YitIdHelper.NextId().ToString()`，禁止使用 `Guid.NewGuid().ToString()` 或其他ID生成方式
11.**说明文档规范**:没有要求生成新的md文件的时候，严禁生成新md文件。
12. **文档与产出物规范**：项目相关形成的 md、sql、excel、word、py 等文件，必须放在 `docs/` 下对应子目录（md、sql、excel、word、py），排除 .cursor、readme、第三方包内的文件。

## 📁 文档与产出物目录

项目产出物统一存放于 `docs/`，按类型分子目录：

| 子目录 | 用途 |
|--------|------|
| `docs/md/` | 接口测试说明、功能总结、修复说明等 |
| `docs/sql/` | 迁移脚本、修复脚本等 |
| `docs/excel/` | xlsx/xls 导入模板、导出示例等 |
| `docs/word/` | doc/docx 文档等 |
| `docs/py/` | Python 脚本等 |

位置：`HongHua-JJ/docs/{md|sql|excel|word|py}/`

## 📋 重要变更记录

### 已弃用的表
- 涉及人员、门店归属、业绩关联等逻辑时，必须使用当前约定表与字段；具体弃用表及替代方案见 skill：`deprecated-tables-context`。