# CNC机床数据采集分析系统 - OpenCode Agent Instructions

## Project Overview

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

## Tech Stack

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

## Project Structure

```
src/
├── Haoliang.Api/               # .NET 8.0 API接口层
│   ├── Controllers/           # API控制器
│   ├── Hubs/                   # SignalR Hub
│   ├── Middleware/             # 中间件
│   └── Filters/                # 过滤器
├── Haoliang.Core/              # .NET 8.0 核心业务逻辑
│   └── Services/               # 业务服务
├── Haoliang.Data/              # .NET 8.0 数据访问层
│   └── Repositories/           # 数据仓储
├── Haoliang.Models/            # .NET 8.0 数据模型层
├── frontend/
│   ├── admin/                  # Vue.js 管理后台
│   └── dashboard/              # Vue.js BI大屏
├── database/
│   ├── cnc_business.sql        # 业务库建表脚本
│   └── cnc_log.sql             # 日志库建表脚本
└── docs/                       # 文档
```

## Key Commands

### Backend Development
```bash
# 构建后端项目
dotnet build Haoliang.sln

# 运行后端
dotnet run --project Haoliang.Api
```

### Frontend Development
```bash
# 管理后台 (默认端口8080，代理到后端)
cd src/frontend/admin && npm install && npm run serve

# BI大屏 (默认端口8081，代理到后端)
cd src/frontend/dashboard && npm install && npm run serve

# 前端构建
npm run build
```

### Testing
```bash
# 运行所有测试 (Haoliang.Tests项目已删除)
./test.sh
```

## Critical Constraints

### Database Architecture
- **业务库 (cnc_business)**: 设备、员工、模板、产量、配置、告警
- **日志库 (cnc_log)**: 原始采集JSON、系统日志、异常日志
- 两个数据库在同一MariaDB实例，严格分离

### CNC Data Format (发那科标准)
- 接口返回JSON数组，每台设备包含 `device`、`desc`、`tags` 数组
- 每个tag: `id`、`desc`、`quality`、`value`、`time`
- 关键字段通过 `id` 匹配：
  - `_io_status` → 设备状态
  - `Tag5` → NC程序名
  - `Tag8` → 当前加工累计数量
  - `Tag9` → 运行状态
  - `Tag11` → 操作模式
  - `Tag14` → 主轴倍率
  - `Tag17`-`Tag21` → 速度/负载
  - `Tag22`-`Tag25` → 时间统计
  - `Tag26` → 加工状态
- 数值自动去除 `.00000` 尾缀，转换为数值/字符串
- 示例数据见 `发那科系统采集示例.txt`

### 产量统计核心逻辑 (差分计算)
- CNC接口仅返回实时累计值，无历史数据
- 同一程序连续加工：产量 = MAX(0, 当前累计数 - 上次累计数)
- 程序切换(A→B)：A产量锁定，B以当前累计数为新起点
- 切回历史程序(B→A)：视为A重新开始，增量累加到当日产量
- 跨天处理：0点自动重置，新日期以首次采集累计值为起点
- 异常值保护：跳变、负数、突变过大时忽略并告警

### 采集机制
- 设备必须Ping通 + 状态可用 才执行采集
- 采集失败重试3次，间隔30秒
- 连续5次失败记录异常日志，不改变在线状态
- 网络恢复后自动恢复采集
- 在线/离线仅由Ping判断，与HTTP采集成功与否无关

### API Design
- 统一响应格式：`{ success, data, message, timestamp }`
- API版本化前缀：`/api/v1/`
- 模板和统计数据使用内存缓存，写操作需清除缓存

## Module References

### 1. CNC品牌模板配置
- 多品牌统一接入（发那科、三菱、西门子、新代、广数等）
- JSON字段映射模板，将原始字段映射为系统标准字段
- 可视化配置tags数组路径、id匹配规则
- 模板增删改查、启用/禁用，修改实时生效无需重编译

### 2. 分布式设备采集
- 每台CNC独立配置：IP、HTTP采集地址、采集间隔、绑定模板、可用状态
- 定时轮询采集，原始JSON存日志库，解析后存业务库

### 3. 零件产量统计
- 以NC程序名(Tag5.value)作为零件唯一识别
- 按自然日00:00-23:59统计，支持跨天加班归属配置
- 差分统计逻辑（见上方核心逻辑）

### 4. 统计规则动态配置
- 自定义统计指标、计算公式、分组维度（设备/员工/日期/NC程序）
- 配置实时生效

### 5. 设备状态监控
- 在线/离线(Ping)、可用/不可用(人工)、运行状态(_io_status/Tag9/Tag11/Tag26)

### 6. 后台管理系统
- 设备管理、模板管理、员工与设备分配、统计规则配置、系统全局配置、数据查询导出、告警管理

### 7. BI数据大屏
- 实时可视化，支持折线图/柱状图/饼图/设备状态卡片
- 刷新频率可配置，支持全屏和按车间/班组筛选

## Performance Requirements
- 单服务器支持 ≥ 100台CNC同时采集
- 采集响应延迟 < 3秒
- API响应 < 500ms
- 7×24小时稳定运行

## Code Style
- 遵循各子项目现有代码规范
- 后端C#遵循.NET 8.0规范
- 前端Vue.js遵循组件化开发规范
- 所有配置页面化，无需改代码即可调整
- 日志清晰，便于排查