docs: 添加项目说明文档

- 添加完整的readme.md文件 - 包含项目概述、技术栈、项目结构、快速开始指南 - 详细说明核心功能、API文档、开发规范 - 提供代码提交规范和故障排除指南 - 确保开发者能够快速了解项目并开始开发
4 weeks ago · 73b92d2b12
parent f90cbd7209
commit 73b92d2b12
1 changed files with 224 additions and 0 deletions
--- a/readme.md
+++ b/readme.md
@ -0,0 +1,224 @@
+# CNC机床数据采集分析系统
+
+## 项目概述
+
+CNC机床多品牌统一化分布式数据采集分析系统，实现设备状态监控、零件产量自动统计、加工过程分析、人员与设备绑定管理，及BI大屏实时展示。
+
+## 技术栈
+
+- **后端**: .NET 6 Web API
+- **数据库**: MySQL 8.0+ (使用 Pomelo.EntityFrameworkCore.MySql)
+- **ORM**: Entity Framework Core 6.0
+- **测试**: xUnit
+- **API文档**: Swagger/OpenAPI
+
+## 项目结构
+
+```
+haoliang/
+├── Haoliang.Api/           # Web API 项目
+│   ├── Controllers/       # API 控制器
+│   ├── Program.cs         # 应用程序入口
+│   └── appsettings.json   # 配置文件
+├── Haoliang.Core/         # 核心业务逻辑项目
+├── Haoliang.Data/         # 数据访问层项目
+│   ├── Entities/          # 实体类
+│   └── Repositories/      # 数据仓储
+├── Haoliang.Models/       # 数据模型项目
+├── Haoliang.Tests/        # 单元测试项目
+├── database/             # 数据库脚本
+├── src/                  # 源代码备份
+└── test-reports/         # 测试报告
+```
+
+## 快速开始
+
+### 环境要求
+
+- .NET 6.0 SDK
+- MySQL 8.0+
+- Visual Studio 2019 或更高版本
+
+### 安装步骤
+
+1. 克隆项目
+```bash
+git clone <repository-url>
+cd haoliang
+```
+
+2. 还原 NuGet 包
+```bash
+dotnet restore
+```
+
+3. 配置数据库连接
+打开 `Haoliang.Api/appsettings.json`，修改数据库连接字符串：
+```json
+{
+  "ConnectionStrings": {
+    "DefaultConnection": "Server=localhost;Database=cnc_business;Uid=root;Pwd=your_password;"
+  }
+}
+```
+
+4. 更新数据库
+```bash
+dotnet ef database update
+```
+
+5. 运行项目
+```bash
+dotnet run --project Haoliang.Api
+```
+
+### 运行测试
+
+```bash
+# 运行所有测试
+dotnet test
+
+# 运行特定项目测试
+dotnet test Haoliang.Tests
+
+# 生成测试报告
+./test.sh
+```
+
+## 核心功能
+
+### 1. 设备管理
+- CNC设备信息管理
+- 设备状态监控
+- 设备模板配置
+
+### 2. 生产统计
+- 零件产量自动统计
+- 加工过程分析
+- 程序切换处理逻辑
+
+### 3. 用户管理
+- 用户信息管理
+- 权限控制
+- 设备绑定管理
+
+### 4. 系统管理
+- 系统配置
+- 日志管理
+- 告警管理
+
+## API 文档
+
+启动项目后，访问以下地址查看 API 文档：
+- Swagger UI: `https://localhost:5001/swagger`
+
+## 开发规范
+
+### 代码提交规范
+
+**重要**: 每次代码修改，经过测试通过之后，提交到git，并写清楚修改内容
+
+#### 提交信息格式
+
+```
+<type>: <description>
+
+[optional body]
+
+[optional footer]
+```
+
+#### Type 类型说明
+
+- `feat`: 新功能
+- `fix`: 修复bug
+- `docs`: 文档更新
+- `style`: 代码格式调整
+- `refactor`: 代码重构
+- `test`: 测试相关
+- `chore`: 构建工具或依赖管理
+
+#### 提交示例
+
+```
+feat: 添加设备批量导入功能
+
+- 实现Excel文件上传和解析
+- 添加设备数据验证逻辑
+- 批量插入优化，减少数据库查询次数
+
+fix: 修复设备状态更新失败的问题
+
+- 修复并发更新时的竞态条件
+- 添加重试机制
+- 优化错误处理逻辑
+```
+
+### 测试规范
+
+- 所有新功能必须包含单元测试
+- 测试覆盖率要求达到 80% 以上
+- 测试用例需要覆盖正常和异常情况
+- 运行测试命令：`dotnet test`
+
+### 代码规范
+
+- 遵循 C# 编码规范
+- 使用异步编程模式
+- 添加适当的 XML 注释
+- 避免硬编码，使用配置文件
+
+## 数据库设计
+
+### 业务库 (cnc_business)
+存储业务数据：设备、员工、模板、产量、配置、告警等
+
+### 日志库 (cnc_log)
+存储原始采集数据、系统日志、异常日志
+
+## 部署说明
+
+### 开发环境
+- 使用 IIS 或 Kestrel 服务器
+- 配置开发数据库连接
+
+### 生产环境
+- 配置生产数据库连接
+- 设置适当的日志级别
+- 启用 HTTPS
+- 配置反向代理
+
+## 故障排除
+
+### 常见问题
+
+1. **数据库连接失败**
+   - 检查 MySQL 服务是否运行
+   - 验证连接字符串配置
+   - 确保数据库用户权限正确
+
+2. **编译错误**
+   - 确保 .NET 6.0 SDK 已安装
+   - 运行 `dotnet restore` 更新包依赖
+   - 检查项目引用是否正确
+
+3. **测试失败**
+   - 确保测试数据库配置正确
+   - 检查测试数据是否准备充分
+   - 运行 `dotnet test --verbosity detailed` 查看详细错误信息
+
+## 版本历史
+
+- v1.0.0 - 初始版本，实现基础功能模块
+
+## 贡献指南
+
+1. Fork 项目
+2. 创建功能分支
+3. 提交变更
+4. 推送到分支
+5. 创建 Pull Request
+
+## 许可证
+
+本项目采用 MIT 许可证