docs: API接口设计文档定稿，13个模块83个端点，含Mock映射和数据库表对照

docs/03-API接口设计.md

@@ -0,0 +1,592 @@
+# 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 响应格式
+
+```json
+// 成功响应
+{ "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=`）。前端代码通过条件判断区分。