|
|
# 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
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
**注意**: 本文档将随着项目发展持续更新，请定期查看最新版本。 |