# CNC机床数据采集分析系统 - 开发规范

## 🚀 项目概述

CNC机床多品牌统一化分布式数据采集分析系统，实现设备状态监控、零件产量自动统计、加工过程分析、人员与设备绑定管理，及BI大屏实时展示。

## 📋 技术栈

- **Backend**: .NET 8.0 WebApi (IIS部署)
- **Frontend**: Vue.js 管理后台 + BI大屏
- **Database**: MariaDB 10.6+ (本地部署，双库分离)
- **Real-Time**: SignalR WebSocket
- **Caching**: Memory Cache

## 🏗️ 项目结构

```
src/
├── Haoliang.Api/           # API接口层 (.NET 8.0)
│   ├── Controllers/       # API控制器
│   ├── Hubs/             # SignalR Hub
│   ├── Middleware/       # 中间件
│   └── Filters/          # 过滤器
├── Haoliang.Core/        # 业务逻辑层 (.NET 8.0)
│   └── Services/         # 业务服务
├── Haoliang.Data/        # 数据访问层 (.NET 8.0)
│   ├── Entities/         # 实体类
│   └── Repositories/     # 数据仓储
└── Haoliang.Models/      # 数据模型层 (.NET 8.0)
```

## 🔧 开发环境要求

### 必需组件
- .NET 8.0 SDK
- Visual Studio 2022 或 VS Code
- MySQL/MariaDB 10.6+
- Git

### IDE推荐配置
- C# Dev Kit 扩展
- IntelliCode C# 扩展
- GitLens 扩展
- Docker 扩展

## 📝 代码规范

### C# 代码规范
- 使用 PascalCase 命名空间和类名
- 使用 camelCase 参数和局部变量
- 使用 PascalCase 公共方法和属性
- 使用 _ 前缀表示私有字段

### API 设计规范
- RESTful API 设计
- 统一响应格式：`{ success, data, message, timestamp }`
- API 版本化：`/api/v1/`
- 状态码：200(成功), 400(客户端错误), 500(服务器错误)

### 注释规范
- 使用 XML 文档注释
- 公共接口必须注释
- 复杂业务逻辑需要注释
- 使用英文注释

## 🔄 Git 工作流

### 强制要求：每次修改必须提交到Git仓库

**仓库信息**:
- **仓库地址**: https://git.cjy.net.cn/jcl/haoliang.git
- **用户名**: 821644@qq.com
- **密码**: 123465a

### 提交规范

#### 1. 每次修改完成后必须执行以下步骤：

```bash
# 1. 查看当前状态
git status

# 2. 添加所有修改的文件
git add .

# 3. 查看即将提交的变更
git status

# 4. 创建提交（根据修改内容选择合适的类型）
git commit -m "类型: 简短描述

详细说明（可选）"

# 5. 推送到远程仓库
git push origin main
```

#### 2. 提交信息规范

**提交类型**:
- `feat`: 新功能
- `fix`: 修复bug
- `docs`: 文档更新
- `style`: 代码格式调整
- `refactor`: 代码重构
- `test`: 测试相关
- `chore`: 构建或辅助工具变动

**示例**:
```bash
git commit -m "feat: 添加生产统计功能
- 实现OEE计算
- 添加生产趋势分析
- 集成实时数据更新"

git commit -m "fix: 修复设备状态同步问题
- 解决WebSocket连接异常
- 优化状态机逻辑"
```

#### 3. 分支管理策略

**主分支**:
- `main`: 生产环境代码

**开发流程**:
```bash
# 创建功能分支
git checkout -b feature/user-management

# 开发完成后合并到main
git checkout main
git merge feature/user-management

# 删除分支
git branch -d feature/user-management
```

## 🧪 测试要求

### 单元测试
- 所有核心服务必须有单元测试
- 测试覆盖率不低于80%
- 使用 Moq 进行模拟测试
- 测试文件命名: `[ClassName]Tests.cs`

### 集成测试
- API端点必须有集成测试
- 使用 TestHost 进行测试
- 测试数据库连接和事务

### 测试命令
```bash
# 运行所有测试
dotnet test

# 运行特定测试
dotnet test --filter "ProductionServiceTests"

# 生成测试报告
dotnet test --collect:"XPlat Code Coverage"
```

## 🚀 部署要求

### 开发环境
- 使用 Docker Compose 快速启动
- 配置文件：`docker-compose.yml`
- 数据库迁移：`dotnet ef database update`

### 生产环境
- Windows Server 2019+
- IIS 10.0+
- .NET 8.0 运行时
- MariaDB 10.6+

### 性能要求
- 支持100+设备同时采集
- API响应时间 < 500ms
- WebSocket延迟 < 100ms
- 7×24小时稳定运行

## 🔒 安全要求

### 认证授权
- JWT Token 认证
- 角色基础访问控制(RBAC)
- 密码加密存储

### 数据安全
- 数据库连接字符串加密
- 敏感信息配置化
- 审计日志记录

### 网络安全
- HTTPS强制加密
- CORS跨域配置
- API限流保护

## 📊 监控和日志

### 日志级别
- **Error**: 系统错误和异常
- **Warning**: 警告和潜在问题
- **Information**: 重要业务操作
- **Debug**: 调试信息

### 性能监控
- 使用 Application Insights
- 关键指标监控
- 告警规则配置

## 🔄 代码审查流程

1. **开发完成** → 提交到Git
2. **自动构建** → CI/CD流水线
3. **自动化测试** → 单元测试+集成测试
4. **代码审查** → 团队成员Review
5. **部署上线** → 生产环境发布

## 📚 相关文档

- [API接口文档](https://git.cjy.net.cn/jcl/haoliang.git/blob/main/docs/api.md)
- [数据库设计文档](https://git.cjy.net.cn/jcl/haoliang.git/blob/main/docs/database.md)
- [部署运维文档](https://git.cjy.net.cn/jcl/haoliang.git/blob/main/docs/deployment.md)
- [用户操作手册](https://git.cjy.net.cn/jcl/haoliang.git/blob/main/docs/user-manual.md)

## 🆘 常见问题

### Git操作问题
```bash
# 解决Git认证问题
git config --global user.name "821644@qq.com"
git config --global user.password "123465a"

# 清理Git缓存
git rm -r --cached .
git add .
```

### 构建问题
```bash
# 清理解决方案
dotnet clean
dotnet restore

# 重新生成项目文件
dotnet build --force
```

### 数据库问题
```bash
# 更新数据库迁移
dotnet ef database update

# 创建新的迁移
dotnet ef migrations add MigrationName
```

---

**注意**: 本文档将随着项目发展持续更新，请定期查看最新版本。