jcl
/
haoliang-net
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
main
feat/windows-service-status-auto
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '9bb4b8246d'
${ noResults }
haoliang-net/docs/03-API接口设计.md

24 KiB
Raw Blame History Unescape Escape

CNC机床数据采集系统 - API接口设计文档

最后更新：2026-04-28 状态：定稿 前置依赖：前端界面设计已确认、数据库设计已定稿

一、设计原则

1.1 变更流程（强制遵守）

功能需求变更描述 → 前端界面+Mock数据先改 → API接口跟着Mock改 → 数据库最后改
  • 所有改动先落实到前端 Mock 文件（frontend/mock/*.ts）
  • Mock URL 格式：/mock-api/admin/xxx
  • 正式 API 格式：/api/admin/xxx
  • Mock 模式下前端 baseURL 自动切换为 /mock-api，正式部署切回 /api

1.2 URL映射规则

场景 Mock URL 正式 API URL
管理后台 /mock-api/admin/xxx /api/admin/xxx
大屏看板 /mock-api/screen/xxx /api/screen/xxx
采集服务 - http://localhost:{port}/api/collector/xxx

1.3 RESTful 规范

操作 Method URL示例 说明
查列表 GET /api/admin/machine 分页用 query params
查详情 GET /api/admin/machine/{id} 路径参数
新增 POST /api/admin/machine Body 传 JSON
修改 PUT /api/admin/machine/{id} Body 传 JSON
删除 DELETE /api/admin/machine/{id} -
启停 PUT /api/admin/machine/{id}/toggle -
批量操作 POST /api/admin/machine/batch-status Body 传 ID 数组

注意：Mock 中部分接口用 POST 替代 PUT/DELETE（如 update/delete），这是 Mock 阶段的简化。正式 API 全部使用标准 RESTful 语义，前端 request.ts 中的方法调用需同步调整。

1.4 认证机制

接口类型 认证方式 说明
管理后台 /api/admin/** Bearer Token（Header） 登录获取 token，30天/8小时过期
大屏看板 /api/screen/** 无需认证 公开展示，直接访问
采集服务 /api/collector/** API Key（Header） 服务间通信，配置文件中写死

二、全局规范

2.1 响应格式

// 成功响应
{ "code": 0, "message": "success", "data": { ... } }

// 分页列表
{ "code": 0, "data": { "items": [], "total": 160, "page": 1, "pageSize": 20 } }

// 失败响应
{ "code": 40001, "message": "具体错误信息", "data": null }

2.2 错误码

错误码 含义 前端处理
0 成功 正常处理 data
40001 参数校验失败/业务错误 el-message error 显示 message
40002 资源不存在 el-message warning + 刷新列表
40003 资源已存在（唯一性冲突） el-message error + 聚焦冲突字段
40101 Token 无效/过期 清除 Token → 跳转 /login
50001 服务器内部错误 el-message error 服务器错误
50002 采集服务不可达 el-message warning 采集服务未响应

2.3 分页参数

参数 类型 默认值 说明
page int 1 当前页码
pageSize int 20 每页条数，可选 [20, 50, 100]

2.4 通用查询参数

参数 类型 说明
keyword string 关键字搜索（名称/编码模糊匹配）

三、模块端点清单

3.1 登录模块

调用页面：LoginPage Mock文件：frontend/mock/login.ts 数据库表：cnc_sys_config（admin_username / admin_password_hash）

# 正式API Method Mock URL 说明 认证
1 /api/admin/login POST /mock-api/admin/login 管理员登录 否

POST /api/admin/login

Request:
{ "username": "admin", "password": "admin123", "rememberMe": true }

Response 200:
{ "code": 0, "data": { "token": "eyJhbGciOiJIUzI1NiJ9...", "expiresIn": 604800 } }

Response 400:
{ "code": 40001, "message": "用户名或密码错误", "data": null }

3.2 仪表盘模块

调用页面：DashboardPage Mock文件：frontend/mock/dashboard.ts 数据库表：cnc_machine、cnc_daily_production、cnc_worker_daily_summary、cnc_production_segment、cnc_workshop、cnc_alert、cnc_collect_address、log_collector_heartbeat

# 正式API Method Mock URL 说明
1 /api/admin/dashboard/summary GET /mock-api/admin/dashboard/summary 8个统计卡片数据
2 /api/admin/collector/status GET /mock-api/admin/collector/status 采集服务状态
3 /api/admin/dashboard/machine-rank GET /mock-api/admin/dashboard/machine-rank 机床产量排行TOP10
4 /api/admin/dashboard/worker-rank GET /mock-api/admin/dashboard/worker-rank 工人产量排行TOP10
5 /api/admin/dashboard/trend GET /mock-api/admin/dashboard/trend 产量趋势（近7天）
6 /api/admin/dashboard/workshop-production GET /mock-api/admin/dashboard/workshop-production 车间平均单机产量
7 /api/admin/dashboard/machine-status-distribution GET /mock-api/admin/dashboard/machine-status-distribution 机床状态分布
8 /api/admin/dashboard/recent-alerts GET /mock-api/admin/dashboard/recent-alerts 最新5条告警
9 /api/admin/collector/start POST /mock-api/admin/collector/start 启动采集服务
10 /api/admin/collector/stop POST /mock-api/admin/collector/stop 停止采集服务
11 /api/admin/collector/refresh POST /mock-api/admin/collector/refresh 刷新采集配置

GET /api/admin/dashboard/summary

Query: 无
Response:
{ "code": 0, "data": {
  "onlineCount": 142, "totalMachines": 160,
  "todayProduction": 2847, "activeAlerts": 3,
  "collectSuccessRate": 99.2, "todayCuttingTime": 580,
  "runningMachines": 128, "dataMissingMachines": 3
}}

GET /api/admin/dashboard/workshop-production

Query: startDate=2026-04-28&endDate=2026-04-28
Response:
{ "code": 0, "data": { "items": [
  { "workshopName": "A栋", "quantity": 1280, "machineCount": 80, "avgQuantity": 16.0 },
  { "workshopName": "B栋", "quantity": 860, "machineCount": 45, "avgQuantity": 19.1 }
]}}
说明：多天范围时 avgQuantity = 总产量÷天数÷机床数（日均单机产量）

GET /api/admin/dashboard/machine-rank

Query: startDate=2026-04-28&endDate=2026-04-28
Response:
{ "code": 0, "data": { "items": [
  { "rank": 1, "machineId": 1, "machineName": "西-1.8", "program": "1566.NC", "quantity": 580, "status": 1 }
]}}

GET /api/admin/dashboard/worker-rank

Query: startDate=2026-04-28&endDate=2026-04-28
Response:
{ "code": 0, "data": { "items": [
  { "rank": 1, "workerId": 1, "workerName": "张三", "machineCount": 3, "totalQuantity": 1240 }
]}}

3.3 设备管理模块

调用页面：MachineListPage、MachineDetailPage Mock文件：frontend/mock/machine.ts 数据库表：cnc_machine、cnc_worker_machine、cnc_collect_record、cnc_daily_production

# 正式API Method Mock URL 说明
1 /api/admin/machine GET /mock-api/admin/machine 机床列表（分页）
2 /api/admin/machine/{id} GET /mock-api/admin/machine/detail?id= 机床详情
3 /api/admin/machine POST /mock-api/admin/machine 新增机床
4 /api/admin/machine/{id} PUT /mock-api/admin/machine/update 编辑机床
5 /api/admin/machine/{id} DELETE /mock-api/admin/machine/delete 删除机床
6 /api/admin/machine/{id}/toggle PUT /mock-api/admin/machine/batch-status 启停机床
7 /api/admin/machine/{id}/status GET /mock-api/admin/machine/status 实时采集状态
8 /api/admin/machine/{id}/production/today GET /mock-api/admin/machine/production/today 今日产量明细
9 /api/admin/machine/{id}/production/trend GET /mock-api/admin/machine/production/trend 产量趋势
10 /api/admin/machine/{id}/collect-records GET /mock-api/admin/machine/collect-records 近期采集记录

GET /api/admin/machine

Query: page=1&pageSize=20&keyword=&workshopId=1&isOnline=&brandId=1
Response:
{ "code": 0, "data": { "items": [
  { "id": 1, "deviceCode": "fanake_1.8", "name": "西-1.8",
    "workshopId": 1, "workshopName": "A栋",
    "collectAddressId": 1, "brandId": 1, "brandName": "FANUC",
    "ipAddress": "10.1.1.8", "isEnabled": 1, "isOnline": 1,
    "workerId": 1, "workerName": "张三",
    "lastProgramName": "1566.NC", "lastCollectTime": "2026-04-28T10:30:00" }
], "total": 160, "page": 1, "pageSize": 20 }}

POST /api/admin/machine

Request:
{ "deviceCode": "fanake_1.8", "name": "西-1.8", "workshopId": 1,
  "collectAddressId": 1, "ipAddress": "10.1.1.8", "brandId": 1 }

Response 200:
{ "code": 0, "data": { "id": 161 } }

Response 400:
{ "code": 40003, "message": "设备编码已存在", "data": null }

3.4 品牌模板模块

调用页面：BrandListPage、BrandEditPage Mock文件：frontend/mock/brand.ts 数据库表：cnc_brand、cnc_brand_field_mapping

# 正式API Method Mock URL 说明
1 /api/admin/brand GET /mock-api/admin/brand 品牌列表
2 /api/admin/brand/{id} GET /mock-api/admin/brand/detail?id= 品牌详情（含字段映射）
3 /api/admin/brand POST /mock-api/admin/brand 新增品牌
4 /api/admin/brand/{id} PUT /mock-api/admin/brand/update 编辑品牌
5 /api/admin/brand/{id} DELETE /mock-api/admin/brand/delete 删除品牌
6 /api/admin/brand/{id}/copy POST /mock-api/admin/brand/copy 复制品牌
7 /api/admin/brand/{id}/toggle PUT /mock-api/admin/brand/toggle 启停品牌
8 /api/admin/brand/standard-fields GET /mock-api/admin/brand/standard-fields 标准字段列表

GET /api/admin/brand

Response:
{ "code": 0, "data": { "items": [
  { "id": 1, "brandName": "FANUC", "deviceField": "device", "tagsPath": "tags",
    "isEnabled": 1, "fieldCount": 16 }
]}}

GET /api/admin/brand/{id}

Response:
{ "code": 0, "data": {
  "id": 1, "brandName": "FANUC", "deviceField": "device", "tagsPath": "tags",
  "isEnabled": 1, "fieldCount": 16,
  "mappings": [
    { "id": 1, "standardField": "program_name", "fieldName": "Tag5",
      "matchBy": "id", "dataType": "string", "isRequired": 1 }
  ]
}}

3.5 采集地址模块

调用页面：CollectAddressListPage、CollectAddressDetailPage Mock文件：frontend/mock/collect-address.ts 数据库表：cnc_collect_address、cnc_machine、log_collect_raw

# 正式API Method Mock URL 说明
1 /api/admin/collect-address GET /mock-api/admin/collect-address 地址列表
2 /api/admin/collect-address/{id} GET /mock-api/admin/collect-address/detail?id= 地址详情
3 /api/admin/collect-address POST /mock-api/admin/collect-address 新增地址
4 /api/admin/collect-address/{id} PUT /mock-api/admin/collect-address/update 编辑地址
5 /api/admin/collect-address/{id} DELETE /mock-api/admin/collect-address/delete 删除地址
6 /api/admin/collect-address/{id}/toggle PUT /mock-api/admin/collect-address/toggle 启停地址
7 /api/admin/collect-address/{id}/machines GET /mock-api/admin/collect-address/machines 地址下机床列表
8 /api/admin/collect-address/{id}/collect-records GET /mock-api/admin/collect-address/collect-records 近期采集记录
9 /api/admin/collect-address/{id}/raw-json GET /mock-api/admin/collect-address/raw-json 最新原始JSON

GET /api/admin/collect-address

Response:
{ "code": 0, "data": { "items": [
  { "id": 1, "name": "FANUC-A栋", "url": "http://10.1.1.1/",
    "brandId": 1, "brandName": "FANUC", "collectInterval": 30,
    "isEnabled": 1, "lastCollectTime": "2026-04-28T10:30:00",
    "failCount": 0, "machineCount": 32 }
]}}

3.6 员工管理模块

调用页面：WorkerListPage、WorkerDetailPage Mock文件：frontend/mock/worker.ts 数据库表：cnc_worker、cnc_worker_machine、cnc_machine、cnc_daily_production

# 正式API Method Mock URL 说明
1 /api/admin/worker GET /mock-api/admin/worker 工人列表（分页）
2 /api/admin/worker/{id} GET /mock-api/admin/worker/detail?id= 工人详情
3 /api/admin/worker POST /mock-api/admin/worker 新增工人
4 /api/admin/worker/{id} PUT /mock-api/admin/worker/update 编辑工人
5 /api/admin/worker/{id} DELETE /mock-api/admin/worker/delete 删除工人
6 /api/admin/worker/{id}/toggle PUT /mock-api/admin/worker/batch-status 启停工人
7 /api/admin/worker/{id}/machines GET /mock-api/admin/worker/machines 绑定机床列表
8 /api/admin/worker/{id}/production/today GET /mock-api/admin/worker/production/today 今日产量明细
9 /api/admin/worker/{id}/production/trend GET /mock-api/admin/worker/production/trend 产量趋势
10 /api/admin/worker/available-machines GET /mock-api/admin/worker/available-machines 可绑定机床（未绑定）

GET /api/admin/worker

Query: page=1&pageSize=20&keyword=&isEnabled=
Response:
{ "code": 0, "data": { "items": [
  { "id": 1, "code": "W001", "name": "张三", "isEnabled": 1,
    "machineCount": 2, "machineNames": "西-1.8,西-2.0" }
], "total": 50, "page": 1, "pageSize": 20 }}

3.7 产量报表模块

调用页面：ProductionPage Mock文件：frontend/mock/production.ts 数据库表：cnc_daily_production、cnc_machine、cnc_production_adjustment

# 正式API Method Mock URL 说明
1 /api/admin/production/daily-summary GET /mock-api/admin/production/daily-summary 日汇总统计
2 /api/admin/production/daily GET /mock-api/admin/production/daily 日产量列表（分页）
3 /api/admin/production/adjust POST /mock-api/admin/production/adjust 修正产量
4 /api/admin/production/{recordId}/adjustment-history GET /mock-api/admin/production/adjustment-history 修正历史
5 /api/admin/production/export GET /mock-api/admin/production/export 导出报表

GET /api/admin/production/daily

Query: page=1&pageSize=20&date=2026-04-28&workshopId=&machineId=&workerId=&dataStatus=
Response:
{ "code": 0, "data": { "items": [
  { "id": 1, "date": "2026-04-28", "machineName": "西-1.8", "programName": "1566.NC",
    "quantity": 580, "runTime": "4h20m", "cuttingTime": "3h50m",
    "dataStatus": "normal", "isAdjusted": 0, "adjustedQuantity": null }
], "total": 1200, "page": 1, "pageSize": 20 }}

POST /api/admin/production/adjust

Request:
{ "targetTable": "daily_production", "targetId": 3,
  "fieldName": "total_quantity", "newValue": 320, "reason": "传感器计数偏差，手工校准" }

Response 200:
{ "code": 0, "message": "success", "data": null }

3.8 告警中心模块

调用页面：AlertPage Mock文件：frontend/mock/alert.ts 数据库表：cnc_alert

# 正式API Method Mock URL 说明
1 /api/admin/alert/statistics GET /mock-api/admin/alert/statistics 告警统计
2 /api/admin/alert GET /mock-api/admin/alert 告警列表（分页）
3 /api/admin/alert/{id}/resolve PUT /mock-api/admin/alert/resolve 处理单条告警
4 /api/admin/alert/batch-resolve POST /mock-api/admin/alert/batch-resolve 批量处理告警

GET /api/admin/alert

Query: page=1&pageSize=20&alertType=&isResolved=&machineId=&startDate=&endDate=
Response:
{ "code": 0, "data": { "items": [
  { "id": 1, "createdAt": "2026-04-28T17:30:00", "alertType": "collect_fail",
    "title": "采集请求失败", "machineName": "西-1.8",
    "detail": "HTTP超时(30s)，连续失败3次", "isResolved": 0, "resolvedAt": null }
], "total": 320, "page": 1, "pageSize": 20 }}

GET /api/admin/alert/statistics

Response:
{ "code": 0, "data": {
  "unresolved": 15, "collectFail": 5, "deviceOffline": 6,
  "productionAnomaly": 2, "unknownDevice": 2, "serviceError": 0 }}

3.9 系统设置模块

调用页面：SettingsPage Mock文件：frontend/mock/settings.ts 数据库表：cnc_sys_config、cnc_workshop

# 正式API Method Mock URL 说明
1 /api/admin/sys-config GET /mock-api/admin/sys-config 配置项列表
2 /api/admin/sys-config/{id} PUT /mock-api/admin/sys-config/update 编辑配置项
3 /api/admin/sys-config/reset-token POST /mock-api/admin/sys-config/reset-token 重置Token
4 /api/admin/workshop GET /mock-api/admin/workshop 车间列表
5 /api/admin/workshop POST /mock-api/admin/workshop 新增车间
6 /api/admin/workshop/{id} PUT /mock-api/admin/workshop/update 编辑车间
7 /api/admin/workshop/{id} DELETE /mock-api/admin/workshop/delete 删除车间
8 /api/admin/workshop/{id}/toggle PUT /mock-api/admin/workshop/toggle 启停车间
9 /api/admin/change-password POST /mock-api/admin/change-password 修改密码

GET /api/admin/sys-config

Query: keyword=
Response:
{ "code": 0, "data": { "items": [
  { "id": 1, "configKey": "ping_interval", "configValue": "60",
    "valueType": "number", "description": "Ping检测间隔(秒)" },
  { "id": 8, "configKey": "api_token", "configValue": "********",
    "valueType": "string", "description": "前端API Token" }
]}}
说明：敏感字段（api_token/collector_api_key）返回时值显示为 "********"

GET /api/admin/workshop

Response:
{ "code": 0, "data": { "items": [
  { "id": 1, "name": "A栋", "sortOrder": 1, "isEnabled": 1, "machineCount": 32 }
]}}

3.10 操作日志模块

调用页面：LogPage Mock文件：frontend/mock/log.ts 数据库表：cnc_production_adjustment、log_system

# 正式API Method Mock URL 说明
1 /api/admin/log/adjustment GET /mock-api/admin/log/adjustment 产量修正日志（分页）
2 /api/admin/log/adjustment/export GET /mock-api/admin/log/adjustment/export 导出修正日志
3 /api/admin/log/system GET /mock-api/admin/log/system 系统运行日志（分页）

GET /api/admin/log/adjustment

Query: page=1&pageSize=20&startDate=&endDate=&targetTable=&keyword=
Response:
{ "code": 0, "data": { "items": [
  { "id": 1, "createdAt": "2026-04-28T15:30:00", "targetTable": "daily_production",
    "targetId": 3, "oldValue": 310, "newValue": 320,
    "reason": "传感器计数偏差，手工校准", "operatorIp": "192.168.1.5" }
], "total": 80, "page": 1, "pageSize": 20 }}

GET /api/admin/log/system

Query: page=1&pageSize=20&startDate=&endDate=&logLevel=&source=&keyword=
Response:
{ "code": 0, "data": { "items": [
  { "id": 1, "createdAt": "2026-04-28T17:36:38", "logLevel": "INFO",
    "source": "CncCollector", "message": "采集完成: 32台成功, 0台失败",
    "stackTrace": null, "extraData": null }
], "total": 5600, "page": 1, "pageSize": 20 }}

3.11 大屏配置模块

调用页面：ScreenConfigPage Mock文件：frontend/mock/screen-config.ts 数据库表：cnc_screen_config、cnc_screen_filter

# 正式API Method Mock URL 说明
1 /api/admin/screen-config GET /mock-api/admin/screen-config 卡片配置列表
2 /api/admin/screen-config POST /mock-api/admin/screen-config 新增卡片
3 /api/admin/screen-config/{id} PUT /mock-api/admin/screen-config/update 编辑卡片
4 /api/admin/screen-config/{id} DELETE /mock-api/admin/screen-config/delete 删除卡片
5 /api/admin/screen-config/{id}/toggle PUT /mock-api/admin/screen-config/toggle 启停卡片
6 /api/admin/screen-filter GET /mock-api/admin/screen-filter 筛选配置列表
7 /api/admin/screen-filter POST /mock-api/admin/screen-filter 新增筛选项
8 /api/admin/screen-filter/{id} PUT /mock-api/admin/screen-filter/update 编辑筛选项
9 /api/admin/screen-filter/{id} DELETE /mock-api/admin/screen-filter/delete 删除筛选项

3.12 大屏看板模块

调用页面：ScreenPage Mock文件：frontend/mock/screen.ts 数据库表：cnc_machine、cnc_daily_production、cnc_worker_daily_summary、cnc_screen_config、cnc_screen_filter 认证：无需 Token

# 正式API Method Mock URL 说明
1 /api/screen/summary GET /mock-api/screen/summary 大屏汇总统计
2 /api/screen/collector-status GET /mock-api/screen/collector-status 采集服务状态
3 /api/screen/workshop-production GET /mock-api/screen/workshop-production 各车间产量
4 /api/screen/production-trend GET /mock-api/screen/production-trend 7天产量趋势
5 /api/screen/machine-rank GET /mock-api/screen/machine-rank 机床产量排行
6 /api/screen/worker-rank GET /mock-api/screen/worker-rank 工人产量排行
7 /api/screen/machine-status GET /mock-api/screen/machine-status 机床状态总览
8 /api/screen/filters GET /mock-api/screen/filters 大屏筛选条件
9 /api/screen/refresh-interval GET /mock-api/screen/refresh-interval 刷新间隔配置

3.13 公共下拉接口

以下接口被多个模块共用（下拉选择框数据源），统一在此定义：

# 正式API Method Mock URL 被调用页面
1 /api/admin/workshop/list GET /mock-api/admin/workshop/list 设备管理、产量报表、大屏
2 /api/admin/brand/list GET /mock-api/admin/brand/list 设备管理、采集地址
3 /api/admin/machine/list GET /mock-api/admin/machine/list 采集地址、产量报表、告警
4 /api/admin/worker/list GET /mock-api/admin/worker/list 设备管理、产量报表
5 /api/admin/collect-address/list GET /mock-api/admin/collect-address/list 设备管理

返回格式统一为 { "code": 0, "data": { "items": [...] } }，只包含 id 和名称字段，不含分页。

四、端点汇总

模块 端点数 数据库表
登录 1 cnc_sys_config
仪表盘 11 cnc_machine, cnc_daily_production, cnc_worker_daily_summary, cnc_workshop, cnc_alert, log_collector_heartbeat
设备管理 10 cnc_machine, cnc_worker_machine, cnc_collect_record, cnc_daily_production
品牌模板 8 cnc_brand, cnc_brand_field_mapping
采集地址 9 cnc_collect_address, cnc_machine, log_collect_raw
员工管理 10 cnc_worker, cnc_worker_machine, cnc_machine, cnc_daily_production
产量报表 5 cnc_daily_production, cnc_machine, cnc_production_adjustment
告警中心 4 cnc_alert
系统设置 9 cnc_sys_config, cnc_workshop
操作日志 3 cnc_production_adjustment, log_system
大屏配置 9 cnc_screen_config, cnc_screen_filter
大屏看板 9 cnc_machine, cnc_daily_production, cnc_worker_daily_summary, cnc_screen_config, cnc_screen_filter
公共下拉 5 各主表
合计 83（含重复共享，去重后 70）

五、Mock ↔ 正式API 对照表

前端 request.ts 中 Mock 模式 baseURL 为 /mock-api，正式模式为 /api。映射关系：

正式 API 前缀 Mock API 前缀 说明
/api/admin/ /mock-api/admin/ 管理后台所有接口
/api/screen/ /mock-api/screen/ 大屏看板接口

Mock 不动规则：正式 API 的 URL 路径（去掉前缀后）与 Mock 保持一致。如正式 GET /api/admin/machine 对应 Mock GET /mock-api/admin/machine。

例外：正式 API 中使用路径参数的接口（如 /api/admin/machine/{id}），Mock 中用 query 参数（如 /mock-api/admin/machine/detail?id=）。前端代码通过条件判断区分。