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.

20 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

联调阶段：

后端按RESTful列实现 → 前端正式代码按RESTful列调整调用方式 → 联调验证

前端 Mock 开发阶段：使用端点清单的 Mock URL 列（全部POST，简化开发）
前端正式联调阶段：切换到端点清单的 正式API 列（RESTful风格：PUT/DELETE + 路径参数）
后端始终按端点清单的 正式API 列 实现，不需要实现Mock风格的URL
端点清单（§3.1~3.13）中同时列出了两列URL，是唯一的接口合同

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，id在URL路径中
删除	DELETE	`/api/admin/machine/{id}`	id在URL路径中
启停	PUT	`/api/admin/machine/{id}/toggle`	id在URL路径中
批量操作	POST	`/api/admin/machine/batch-status`	Body 传 ID 数组

强制要求：

后端 API 一律使用上表的 RESTful 风格实现（PUT/DELETE + 路径参数），禁止实现Mock风格的POST路由
前端正式联调代码一律使用 RESTful 风格调用，禁止在正式环境中使用Mock风格的URL（/update、/delete、/toggle等POST路由）
前端 Mock 开发阶段可使用简化的 POST 风格（见端点清单的 Mock URL 列），联调时按正式API列切换
参数传递：RESTful 中资源 ID 通过 URL 路径传递（/{id}），不放在 request body 中

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`	管理员登录	否

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`	刷新采集配置

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`	近期采集记录

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`	标准字段列表

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

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`	可绑定机床（未绑定）

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`	导出报表

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`	批量处理告警

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`	修改密码

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`	系统运行日志（分页）

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`	设备管理

四、端点汇总

模块	端点数	数据库表
登录	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 返回的 data 内部 JSON 结构（字段名、嵌套关系、items包裹等）必须与页面文件§9（接口引用与数据结构）中定义的数据结构保持一致。Mock 文件按页面文件§9生成，后端也必须对齐§9的数据结构。
URL路径和HTTP方法按RESTful：正式 API 的 URL 路径和 HTTP 方法使用 §1.3 定义的 RESTful 风格，不必与 Mock 的 URL 路径和方法完全一致。
端点清单是路由合同：每个模块的端点清单（§3.1~3.13）同时列出了"正式API"和"Mock URL"两列，两边各自按自己的列实现/调用即可。端点清单只定义URL和方法，不定义返回数据结构。
数据结构定义在页面文件§9：每个接口的具体Request/Response数据结构由对应的页面文件§9（接口引用与数据结构）定义，这是数据结构的唯一来源。

两列URL差异说明：

写操作：Mock 用 POST /xxx/update、POST /xxx/delete，正式API 用 PUT /xxx/{id}、DELETE /xxx/{id}
详情查询：Mock 用 GET /xxx/detail?id=，正式API 用 GET /xxx/{id}
参数传递：Mock 把 id 放在 query 或 body 中，正式API 把 id 放在 URL 路径中
读取操作（GET列表）：两列URL完全一致，只有前缀不同

新增或变更接口时的流程：

先在对应模块的端点清单（§3.x）中同时新增两行：正式API列（RESTful）+ Mock URL列（POST简化）
在对应模块的页面文件§9中定义该接口的Request/Response数据结构
在对应模块的 Mock 文件（frontend/mock/*.ts）中按页面文件§9的数据结构生成 Mock 数据
后端按正式API列实现接口，返回数据结构严格对齐页面文件§9的定义
前端 Mock 开发时按 Mock URL 列调用，正式联调时切换到正式API列
禁止只新增一列而遗漏另一列——每次新增接口必须两列同时更新

20 KiB Raw Blame History Unescape Escape