haoliang-net/docs/03-API接口设计.md

# 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=`）。前端代码通过条件判断区分。