# CNC机床数据采集系统 - 需求与设计文档

> 最后更新：2026-04-23
> 状态：设计中（数据库设计已确认，API/前端/采集服务待设计）

---

## 一、项目概述

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

系统本地IIS部署，MariaDB数据库（业务库+日志库双库分离），单角色管理模式。

---

## 二、技术栈

| 层 | 技术 | 说明 |
|----|------|------|
| 前端 | Vue3 | 管理后台 + 大屏看板 |
| 后端 | ASP.NET Web API 2 (.NET Framework 4.5+) | REST API |
| 采集服务 | Windows Service (.NET Framework 4.5+) | 定时采集+数据处理 |
| 数据库 | MariaDB 10.6+ | 业务库 + 日志库 |
| 部署 | Windows Server + IIS | 局域网，同站点 |

---

## 三、系统架构

[见附图：架构图]

核心组件：
- Windows Service (CncCollector)：定时拉取HTTP数据，字段映射解析，零件数增量计算，日终汇总，心跳上报
- MariaDB：业务库(cnc_business) + 日志库(cnc_log)
- IIS Web API 2：/api/admin/** Token认证，/api/screen/** 免认证
- Vue3前端：管理后台(/) + 大屏(/screen)

---

## 四、已确认的核心需求与决策

### 4.1 采集架构

| 决策 | 结论 |
|------|------|
| 采集模式 | 系统定时从一个HTTP地址拉取JSON数据（非直连机床） |
| 采集地址 | 多个采集地址，每个地址关联品牌+选择要采的机床列表，URL和间隔配在地址级 |
| 采集间隔 | 配置在采集地址级别，同地址统一间隔 |
| 采集并发 | 地址间并行，地址内串行 |
| Ping前置 | Ping通才采集，Ping结果=在线状态 |
| 采集失败 | 自动重试3次间隔30秒，连续5次失败记告警 |
| 采集认证 | HTTP采集地址无需认证 |
| 新设备发现 | 采集到未知device时记录告警，不自动创建 |

### 4.2 数据格式

| 决策 | 结论 |
|------|------|
| 顶层结构 | 所有品牌统一：JSON数组，每台设备含device、desc、tags |
| 字段定位 | 通过tags数组中id匹配定位关键字段 |
| 字段映射 | 管理后台可视化配置品牌字段映射，实时生效不改代码 |
| device映射 | 机床表配置device_code，采集时用device值匹配 |
| 原始数据 | 存原始JSON到日志库，解析后结构化数据存业务库 |
| 时间标准 | 以服务器时间为准，机床时间仅存为参考字段 |
| 数值处理 | 自动去除.00000尾缀，转换为数值/字符串 |

### 4.3 零件产量统计

| 决策 | 结论 |
|------|------|
| 零件识别 | NC程序名（Tag5）作为零件唯一识别 |
| 计数方式 | CNC切换加工零件时NC程序名变更+零件数清零 |
| 产量计算 | 程序切换时结账上一段零件数，新程序从0开始 |
| A-B-C-A-B | 同程序名多次出现，产量分段记录，日汇总时合并 |
| 手动清零 | 同程序下part_count下降视为手动清零，结账前值后从0重计 |
| 设备重启 | 确认不清零零件数 |
| 跨天处理 | 零点后数据归属第二天，有问题后台手工调 |
| 日终汇总 | 按自然天汇总，过0点后自动汇总前一天，汇总时间后台可配 |
| 未开机机床 | 日汇总插0产量记录 |
| 采集失败机床 | Ping通但采集失败标记数据缺失，前端显示-而非0 |

### 4.4 班次与工人

| 决策 | 结论 |
|------|------|
| 班次 | v1不支持班次，按自然天+固定绑定汇总 |
| 工人-机床 | 固定绑定，一台机床只绑一个工人 |
| 工人归属 | 工人不归属车间 |

### 4.5 管理与监控

| 决策 | 结论 |
|------|------|
| 采集服务通信 | 心跳写DB + 轻量HTTP管理API（启停控制） |
| 配置热更新 | 轮询DB（每30秒）+ 管理操作后API通知，双保险 |
| 采集服务自恢复 | 每个采集地址任务独立线程，崩了不影响其他，自动重启间隔递增 |
| DB断连处理 | 本地文件缓存+自动补写 |
| 采集服务API认证 | 加服务间API Key（配置文件中写死） |
| 手工调整产量 | 管理后台修正功能+审计日志 |
| 模板修改 | 不回溯历史数据，修改时弹提醒 |

### 4.6 前端与认证

| 决策 | 结论 |
|------|------|
| API认证 | /api/admin/** Token认证，/api/screen/** 免认证 |
| 管理后台 | PC端，Vue3 |
| 大屏 | Chrome无人值守，提供全屏按钮，免认证 |
| 大屏可配置 | 固定布局+卡片指标可配+筛选可配+图表类型可选 |
| Vue3部署 | 同IIS站点，无跨域问题 |
| Excel导出 | EPPlus |

### 4.7 系统运维

| 决策 | 结论 |
|------|------|
| 日志轮转 | 按日期切割，保留天数在管理后台配置 |
| DB备份 | 每日自动全量+binlog增量，保留30天，需检查binlog是否开启 |
| 分区维护 | 按月创建新分区+删除过期分区 |
| 品牌预置 | 预置FANUC品牌模板，其他手动添加 |
| 告警通知 | v1只做管理后台内告警列表+标记已处理，不做推送 |
| 机床停用 | 软删除(is_enabled)，保留历史数据 |

---

## 五、待设计模块

> 以下模块尚未展开设计，待后续讨论确认：

- 5.1 API接口设计
- 5.2 采集服务核心逻辑设计
- 5.3 前端管理后台设计
- 5.4 大屏看板设计