886 lines
32 KiB
Markdown
886 lines
32 KiB
Markdown
# 设计文档：前后端分离 — Java API 后端与前端集成
|
||
|
||
## 概述
|
||
|
||
本设计文档描述将现有 Next.js 16 前端生产管理子系统从硬编码模拟数据迁移到真实 RESTful API 的完整技术方案。涵盖 Java Spring Boot 3.3.6 后端多模块项目架构、PostgreSQL 数据库设计、DDD 分层实现，以及前端 API 集成层的构建。
|
||
|
||
系统为地球物理仪器（高密度电法仪等）的全生命周期管理平台，包含设备管理、板卡管理、固件库、校准管理、校准文件管理、授权管理、配置文件管理、维修工单、报废回收等核心业务模块。
|
||
|
||
### 设计目标
|
||
|
||
- 搭建符合 DDD 分层架构的 Spring Boot 多模块 Maven 项目
|
||
- 设计 PostgreSQL `dev` schema 下的完整数据库表结构
|
||
- 为所有前端页面提供对应的 RESTful API 端点
|
||
- 在前端建立统一的 API 调用层，替换所有硬编码模拟数据
|
||
- 前后端采用统一的分页、筛选、错误响应规范
|
||
|
||
## 架构
|
||
|
||
### 整体架构
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph Frontend["前端 Next.js 16"]
|
||
Pages["页面组件<br/>devices / boards / firmware / ..."]
|
||
ApiLayer["API 集成层<br/>src/lib/api/"]
|
||
Pages --> ApiLayer
|
||
end
|
||
|
||
subgraph Backend["后端 Spring Boot 3.3.6"]
|
||
subgraph ApiAdmin["api-admin 模块"]
|
||
Controllers["REST Controllers<br/>/api/admin/*"]
|
||
end
|
||
subgraph ApiPortal["api-portal 模块"]
|
||
PortalControllers["REST Controllers<br/>/api/portal/*<br/>（无需鉴权）"]
|
||
end
|
||
subgraph Business["business 模块"]
|
||
subgraph Device["device 子模块"]
|
||
Interfaces["interfaces 层<br/>Controller / VO / Assembler"]
|
||
Application["application 层<br/>AppService / Command / Query"]
|
||
Domain["domain 层<br/>Entity / Repository接口"]
|
||
Infrastructure["infrastructure 层<br/>Mapper / DO / Repository实现"]
|
||
end
|
||
end
|
||
subgraph Common["common 模块"]
|
||
Response["统一响应体 R<T>"]
|
||
Exception["全局异常处理"]
|
||
Audit["审计字段自动填充"]
|
||
end
|
||
end
|
||
|
||
subgraph DB["PostgreSQL 12.14"]
|
||
DevSchema["dev schema<br/>devices / device_models / board_types / board_cards / calibration_files / ..."]
|
||
end
|
||
|
||
ApiLayer -->|HTTP REST| Controllers
|
||
ApiLayer -->|HTTP REST| PortalControllers
|
||
Controllers --> Interfaces
|
||
PortalControllers --> Interfaces
|
||
Interfaces --> Application
|
||
Application --> Domain
|
||
Domain --> Infrastructure
|
||
Infrastructure -->|MyBatis-Plus| DevSchema
|
||
```
|
||
|
||
### 后端项目结构
|
||
|
||
```
|
||
apps/geo-bps-api/
|
||
├── pom.xml # 父 POM
|
||
├── api-admin/
|
||
│ ├── pom.xml
|
||
│ └── src/main/java/com/geomative/bps/admin/
|
||
│ ├── ApiAdminApplication.java
|
||
│ └── config/
|
||
│ ├── CorsConfig.java # CORS 配置
|
||
│ └── WebMvcConfig.java
|
||
├── api-portal/
|
||
│ ├── pom.xml
|
||
│ └── src/main/java/com/geomative/bps/portal/
|
||
│ ├── ApiPortalApplication.java
|
||
│ └── config/
|
||
│ ├── CorsConfig.java # CORS 配置
|
||
│ └── WebMvcConfig.java # 文件上传大小限制等
|
||
├── business/
|
||
│ ├── pom.xml # pom packaging
|
||
│ └── device/
|
||
│ ├── pom.xml
|
||
│ └── src/main/java/com/geomative/bps/device/
|
||
│ ├── interfaces/ # Controller + VO
|
||
│ ├── application/ # AppService + Command + Query
|
||
│ ├── domain/ # Entity + Repository接口
|
||
│ └── infrastructure/ # Mapper + DO + Repository实现
|
||
└── common/
|
||
├── pom.xml
|
||
└── src/main/java/com/geomative/bps/common/
|
||
├── response/
|
||
│ └── R.java # 统一响应体
|
||
├── exception/
|
||
│ ├── BizException.java
|
||
│ └── GlobalExceptionHandler.java
|
||
├── mybatis/
|
||
│ └── AuditMetaObjectHandler.java
|
||
└── page/
|
||
└── PageResult.java # 分页响应
|
||
```
|
||
|
||
### 前端 API 集成层结构
|
||
|
||
```
|
||
src/
|
||
├── lib/
|
||
│ └── api/
|
||
│ ├── client.ts # Axios 实例，统一配置
|
||
│ ├── types.ts # 通用响应/分页类型
|
||
│ ├── deviceApi.ts # 设备管理 API
|
||
│ ├── modelApi.ts # 设备型号 API
|
||
│ ├── boardApi.ts # 板卡管理 API
|
||
│ ├── firmwareApi.ts # 固件库 API
|
||
│ ├── calibrationApi.ts # 校准管理 API
|
||
│ ├── calibrationFileApi.ts # 校准文件 API
|
||
│ ├── configFileApi.ts # 配置文件 API
|
||
│ ├── licenseApi.ts # 授权管理 API
|
||
│ ├── repairApi.ts # 维修工单 API
|
||
│ ├── scrapApi.ts # 报废管理 API
|
||
│ └── dashboardApi.ts # 首页统计 API
|
||
└── hooks/
|
||
└── useApi.ts # 通用数据获取 Hook
|
||
```
|
||
|
||
## 组件与接口
|
||
|
||
### 统一响应体
|
||
|
||
```java
|
||
public class R<T> {
|
||
private int code; // 业务状态码，0=成功
|
||
private String message; // 提示信息
|
||
private T data; // 响应数据
|
||
|
||
public static <T> R<T> ok(T data) { ... }
|
||
public static <T> R<T> fail(int code, String message) { ... }
|
||
}
|
||
```
|
||
|
||
### 分页响应体
|
||
|
||
```java
|
||
public class PageResult<T> {
|
||
private long total; // 总记录数
|
||
private int page; // 当前页码
|
||
private int pageSize; // 每页条数
|
||
private List<T> records; // 数据列表
|
||
}
|
||
```
|
||
|
||
### 统一分页请求参数
|
||
|
||
所有列表接口统一使用：
|
||
- `page`：页码，从 1 开始，默认 1
|
||
- `pageSize`：每页条数，默认 10
|
||
|
||
### API 端点清单
|
||
|
||
| 模块 | 方法 | 路径 | 说明 |
|
||
|------|------|------|------|
|
||
| 设备 | GET | `/api/admin/devices` | 分页设备列表（筛选：型号/状态/日期/SN/批次） |
|
||
| 设备 | GET | `/api/admin/devices/{sn}` | 设备详情（含授权、子设备、固件） |
|
||
| 设备 | POST | `/api/admin/devices` | 创建设备（设备登记） |
|
||
| 设备 | GET | `/api/admin/devices/batches` | 生产批次列表 |
|
||
| 型号 | GET | `/api/admin/device-models` | 设备型号列表 |
|
||
| 型号 | POST | `/api/admin/device-models` | 创建设备型号 |
|
||
| 型号 | GET | `/api/admin/checklist-templates` | Checklist 模板列表 |
|
||
| 型号 | POST | `/api/admin/checklist-templates` | 创建 Checklist 模板 |
|
||
| 板卡 | GET | `/api/admin/board-types` | 板卡型号列表（筛选：类型） |
|
||
| 板卡 | GET | `/api/admin/board-types/{id}` | 板卡详情 |
|
||
| 板卡 | POST | `/api/admin/board-types` | 创建板卡型号 |
|
||
| 固件 | GET | `/api/admin/firmware` | 固件版本列表（筛选：类型/板卡型号） |
|
||
| 固件 | POST | `/api/admin/firmware` | 创建固件版本 |
|
||
| 固件 | GET | `/api/admin/firmware/{id}/download` | 下载固件文件 |
|
||
| 校准 | GET | `/api/admin/calibrations` | 校准记录列表（筛选：SN/状态/人员） |
|
||
| 校准 | GET | `/api/admin/calibrations/{id}` | 校准详情 |
|
||
| 校准 | POST | `/api/admin/calibrations/import` | 批量导入校准记录 |
|
||
| 校准文件 | POST | `/api/portal/calibration-files/upload` | 上传校准文件（无需鉴权，上位机调用） |
|
||
| 校准文件 | GET | `/api/admin/board-cards/{id}/calibration-files` | 指定采集板的校准文件列表（按上传时间倒序） |
|
||
| 校准文件 | GET | `/api/admin/calibration-files/{id}/download` | 下载校准文件 |
|
||
| 配置 | GET | `/api/admin/config-files` | 配置文件列表（筛选：型号/版本/关键字） |
|
||
| 配置 | GET | `/api/admin/config-files/{id}` | 配置文件详情 |
|
||
| 配置 | POST | `/api/admin/config-files` | 创建配置文件 |
|
||
| 配置 | PUT | `/api/admin/config-files/{id}` | 更新配置文件 |
|
||
| 配置 | DELETE | `/api/admin/config-files/{id}` | 逻辑删除配置文件 |
|
||
| 授权 | GET | `/api/admin/licenses` | 授权列表（筛选：型号/状态） |
|
||
| 授权 | POST | `/api/admin/licenses` | 创建授权记录 |
|
||
| 授权 | PUT | `/api/admin/licenses/{id}` | 更新授权记录 |
|
||
| 授权 | PUT | `/api/admin/licenses/{id}/disable` | 停用授权 |
|
||
| 维修 | GET | `/api/admin/repair-orders` | 工单列表（筛选：状态/优先级/人员/日期/SN） |
|
||
| 维修 | GET | `/api/admin/repair-orders/{id}` | 工单详情 |
|
||
| 维修 | POST | `/api/admin/repair-orders` | 创建工单 |
|
||
| 维修 | PUT | `/api/admin/repair-orders/{id}/process` | 处理工单 |
|
||
| 维修 | PUT | `/api/admin/repair-orders/{id}/close` | 关闭工单 |
|
||
| 报废 | GET | `/api/admin/scrap-records` | 报废记录列表（筛选：SN/状态/日期） |
|
||
| 报废 | GET | `/api/admin/scrap-records/{id}` | 报废详情 |
|
||
| 报废 | PUT | `/api/admin/scrap-records/{id}/approve` | 审批通过 |
|
||
| 报废 | PUT | `/api/admin/scrap-records/{id}/reject` | 驳回 |
|
||
| 报废 | PUT | `/api/admin/scrap-records/{id}/recover` | 物料回收入库 |
|
||
| 报废 | GET | `/api/admin/scrap-records/stats` | 报废统计 |
|
||
| 首页 | GET | `/api/admin/dashboard/metrics` | 统计指标 |
|
||
| 首页 | GET | `/api/admin/dashboard/device-status` | 设备状态分布 |
|
||
| 首页 | GET | `/api/admin/dashboard/tasks` | 待处理任务 |
|
||
|
||
### 前端 API 客户端
|
||
|
||
```typescript
|
||
// src/lib/api/client.ts
|
||
import axios from 'axios';
|
||
|
||
const apiClient = axios.create({
|
||
baseURL: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8080',
|
||
timeout: 5000,
|
||
headers: { 'Content-Type': 'application/json' },
|
||
});
|
||
|
||
// 响应拦截器：统一错误处理
|
||
apiClient.interceptors.response.use(
|
||
(res) => res.data,
|
||
(error) => {
|
||
const message = error.response?.data?.message || '请求失败，请稍后重试';
|
||
return Promise.reject(new Error(message));
|
||
}
|
||
);
|
||
|
||
export default apiClient;
|
||
```
|
||
|
||
### 前端通用类型
|
||
|
||
```typescript
|
||
// src/lib/api/types.ts
|
||
export interface ApiResponse<T> {
|
||
code: number;
|
||
message: string;
|
||
data: T;
|
||
}
|
||
|
||
export interface PageResult<T> {
|
||
total: number;
|
||
page: number;
|
||
pageSize: number;
|
||
records: T[];
|
||
}
|
||
|
||
export interface PageParams {
|
||
page?: number;
|
||
pageSize?: number;
|
||
}
|
||
```
|
||
|
||
|
||
## 数据模型
|
||
|
||
### ER 关系图
|
||
|
||
```mermaid
|
||
erDiagram
|
||
device_models ||--o{ devices : "型号关联"
|
||
device_models ||--o{ checklist_templates : "模板关联"
|
||
device_models ||--o{ config_files : "配置关联"
|
||
device_models ||--o{ licenses : "授权关联"
|
||
checklist_templates ||--o{ checklist_items : "包含检查项"
|
||
devices ||--o{ device_boards : "装配板卡"
|
||
devices ||--o{ repair_orders : "维修工单"
|
||
devices ||--o{ scrap_records : "报废记录"
|
||
board_types ||--o{ device_boards : "板卡实例"
|
||
board_types ||--o{ firmware_versions : "固件版本"
|
||
board_types ||--o{ calibration_records : "校准记录"
|
||
board_cards ||--o{ calibration_files : "校准文件"
|
||
|
||
device_models {
|
||
varchar(64) id PK
|
||
varchar(100) name
|
||
varchar(50) code UK
|
||
varchar(20) status
|
||
varchar(500) description
|
||
timestamp created_at
|
||
varchar(64) created_by
|
||
timestamp updated_at
|
||
varchar(64) updated_by
|
||
smallint deleted
|
||
}
|
||
|
||
devices {
|
||
varchar(64) id PK
|
||
varchar(100) sn UK
|
||
varchar(64) model_id FK
|
||
varchar(100) model_name
|
||
varchar(20) status
|
||
varchar(20) firmware_version
|
||
timestamp production_date
|
||
varchar(200) customer
|
||
varchar(20) batch
|
||
varchar(64) operator
|
||
timestamp created_at
|
||
varchar(64) created_by
|
||
timestamp updated_at
|
||
varchar(64) updated_by
|
||
smallint deleted
|
||
}
|
||
|
||
board_types {
|
||
varchar(64) id PK
|
||
varchar(50) type
|
||
varchar(50) version UK
|
||
varchar(20) latest_firmware
|
||
date production_date
|
||
varchar(20) status
|
||
timestamp created_at
|
||
varchar(64) created_by
|
||
timestamp updated_at
|
||
varchar(64) updated_by
|
||
smallint deleted
|
||
}
|
||
|
||
device_boards {
|
||
varchar(64) id PK
|
||
varchar(64) device_id FK
|
||
varchar(100) device_sn
|
||
varchar(64) board_type_id FK
|
||
varchar(100) board_sn
|
||
varchar(50) board_name
|
||
varchar(50) board_model
|
||
varchar(20) calibration_status
|
||
timestamp created_at
|
||
varchar(64) created_by
|
||
timestamp updated_at
|
||
varchar(64) updated_by
|
||
smallint deleted
|
||
}
|
||
|
||
firmware_versions {
|
||
varchar(64) id PK
|
||
varchar(20) version
|
||
varchar(64) board_type_id FK
|
||
varchar(50) board_version
|
||
varchar(50) firmware_type
|
||
date release_date
|
||
varchar(20) status
|
||
varchar(20) file_size
|
||
int download_count
|
||
varchar(200) hw_range
|
||
varchar(20) upgrade_type
|
||
boolean signed
|
||
varchar(64) md5
|
||
varchar(128) sha256
|
||
text release_notes
|
||
varchar(500) file_path
|
||
timestamp created_at
|
||
varchar(64) created_by
|
||
timestamp updated_at
|
||
varchar(64) updated_by
|
||
smallint deleted
|
||
}
|
||
|
||
calibration_records {
|
||
varchar(64) id PK
|
||
varchar(100) board_sn
|
||
varchar(64) board_type_id FK
|
||
varchar(50) board_version
|
||
date calibration_date
|
||
date expiry_date
|
||
varchar(100) calibrator
|
||
varchar(20) status
|
||
int channel_count
|
||
decimal overall_deviation
|
||
jsonb channel_results
|
||
timestamp created_at
|
||
varchar(64) created_by
|
||
timestamp updated_at
|
||
varchar(64) updated_by
|
||
smallint deleted
|
||
}
|
||
|
||
config_files {
|
||
varchar(64) id PK
|
||
varchar(100) name
|
||
varchar(64) model_id FK
|
||
varchar(100) model_name
|
||
varchar(20) version
|
||
varchar(20) status
|
||
jsonb transmission_params
|
||
jsonb acquisition_params
|
||
jsonb protection_params
|
||
jsonb network_params
|
||
timestamp created_at
|
||
varchar(64) created_by
|
||
timestamp updated_at
|
||
varchar(64) updated_by
|
||
smallint deleted
|
||
}
|
||
|
||
licenses {
|
||
varchar(64) id PK
|
||
varchar(64) model_id FK
|
||
varchar(50) model_code
|
||
jsonb modules
|
||
varchar(20) validity_type
|
||
date expiry_date
|
||
varchar(20) status
|
||
timestamp created_at
|
||
varchar(64) created_by
|
||
timestamp updated_at
|
||
varchar(64) updated_by
|
||
smallint deleted
|
||
}
|
||
|
||
repair_orders {
|
||
varchar(64) id PK
|
||
varchar(50) order_no UK
|
||
varchar(100) device_sn
|
||
varchar(50) fault_type
|
||
varchar(20) status
|
||
varchar(10) priority
|
||
varchar(100) assignee
|
||
varchar(500) description
|
||
varchar(500) phenomenon
|
||
date expected_fix_date
|
||
text note
|
||
jsonb process_records
|
||
jsonb board_replacements
|
||
timestamp created_at
|
||
varchar(64) created_by
|
||
timestamp updated_at
|
||
varchar(64) updated_by
|
||
smallint deleted
|
||
}
|
||
|
||
scrap_records {
|
||
varchar(64) id PK
|
||
varchar(100) device_sn
|
||
varchar(100) model_name
|
||
varchar(500) reason
|
||
varchar(100) applicant
|
||
varchar(20) status
|
||
varchar(50) order_id
|
||
decimal residual_value
|
||
jsonb materials
|
||
jsonb approval_timeline
|
||
text approval_note
|
||
timestamp created_at
|
||
varchar(64) created_by
|
||
timestamp updated_at
|
||
varchar(64) updated_by
|
||
smallint deleted
|
||
}
|
||
|
||
checklist_templates {
|
||
varchar(64) id PK
|
||
varchar(64) model_id FK
|
||
varchar(50) model_code
|
||
timestamp created_at
|
||
varchar(64) created_by
|
||
timestamp updated_at
|
||
varchar(64) updated_by
|
||
smallint deleted
|
||
}
|
||
|
||
checklist_items {
|
||
varchar(64) id PK
|
||
varchar(64) template_id FK
|
||
varchar(200) name
|
||
boolean required
|
||
int sort_order
|
||
timestamp created_at
|
||
varchar(64) created_by
|
||
timestamp updated_at
|
||
varchar(64) updated_by
|
||
smallint deleted
|
||
}
|
||
|
||
board_cards {
|
||
varchar(64) id PK
|
||
varchar(100) sn UK
|
||
varchar(50) type
|
||
varchar(50) version
|
||
varchar(20) firmware_version
|
||
varchar(20) status
|
||
varchar(100) device_sn
|
||
date production_date
|
||
varchar(20) calib_status
|
||
date calib_date
|
||
varchar(500) remark
|
||
timestamp created_at
|
||
varchar(64) created_by
|
||
timestamp updated_at
|
||
varchar(64) updated_by
|
||
smallint deleted
|
||
}
|
||
|
||
calibration_files {
|
||
varchar(64) id PK
|
||
varchar(100) board_sn
|
||
varchar(200) original_name
|
||
varchar(500) file_path
|
||
bigint file_size
|
||
varchar(64) md5
|
||
timestamp upload_time
|
||
timestamp created_at
|
||
varchar(64) created_by
|
||
timestamp updated_at
|
||
varchar(64) updated_by
|
||
smallint deleted
|
||
}
|
||
```
|
||
|
||
### 表结构详细说明
|
||
|
||
#### 公共审计字段（所有表必须包含）
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
|------|------|------|------|
|
||
| id | VARCHAR(64) | PK | 应用层生成（雪花算法/UUID） |
|
||
| created_at | TIMESTAMP | NOT NULL | 创建时间，INSERT 自动填充 |
|
||
| created_by | VARCHAR(64) | NULL | 创建人 |
|
||
| updated_at | TIMESTAMP | NOT NULL | 修改时间，INSERT/UPDATE 自动填充 |
|
||
| updated_by | VARCHAR(64) | NULL | 修改人 |
|
||
| deleted | SMALLINT | NOT NULL DEFAULT 0 | 逻辑删除标记 |
|
||
|
||
#### dev.devices — 设备表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| sn | VARCHAR(100) | 设备SN号，唯一索引 |
|
||
| model_id | VARCHAR(64) | 关联设备型号 |
|
||
| model_name | VARCHAR(100) | 型号名称（冗余） |
|
||
| status | VARCHAR(20) | 装配中/已出厂/已激活/报废 |
|
||
| firmware_version | VARCHAR(20) | 当前固件版本 |
|
||
| production_date | TIMESTAMP | 生产日期 |
|
||
| customer | VARCHAR(200) | 客户名称 |
|
||
| batch | VARCHAR(20) | 生产批次（YYYY-WXX） |
|
||
| operator | VARCHAR(64) | 登记人 |
|
||
|
||
#### dev.device_models — 设备型号表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| name | VARCHAR(100) | 型号名称（如 GD-30 Supreme） |
|
||
| code | VARCHAR(50) | 型号代码（如 GD30），唯一索引 |
|
||
| status | VARCHAR(20) | 在产/停产 |
|
||
| description | VARCHAR(500) | 描述 |
|
||
|
||
#### dev.board_types — 板卡型号表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| type | VARCHAR(50) | 板卡类型（主协板/采集板/发射板/升压板） |
|
||
| version | VARCHAR(50) | 版本号（如 MB-V1.8），唯一索引 |
|
||
| latest_firmware | VARCHAR(20) | 最新固件版本 |
|
||
| production_date | DATE | 生产日期 |
|
||
| status | VARCHAR(20) | 在产/停产 |
|
||
|
||
#### dev.device_boards — 设备板卡关联表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| device_id | VARCHAR(64) | 关联设备 |
|
||
| device_sn | VARCHAR(100) | 设备SN（冗余） |
|
||
| board_type_id | VARCHAR(64) | 关联板卡型号 |
|
||
| board_sn | VARCHAR(100) | 板卡SN号 |
|
||
| board_name | VARCHAR(50) | 板卡名称（主协板/采集板等） |
|
||
| board_model | VARCHAR(50) | 板卡型号 |
|
||
| calibration_status | VARCHAR(20) | 校准状态 |
|
||
|
||
#### dev.firmware_versions — 固件版本表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| version | VARCHAR(20) | 版本号 |
|
||
| board_type_id | VARCHAR(64) | 关联板卡型号 |
|
||
| board_version | VARCHAR(50) | 板卡版本（冗余） |
|
||
| firmware_type | VARCHAR(50) | 固件类型（主协板/采集板/发射板/升压板/主机固件/计算单元固件） |
|
||
| release_date | DATE | 发布日期 |
|
||
| status | VARCHAR(20) | 已发布/草稿 |
|
||
| file_size | VARCHAR(20) | 文件大小 |
|
||
| download_count | INT | 下载次数，默认 0 |
|
||
| hw_range | VARCHAR(200) | 硬件版本范围 |
|
||
| upgrade_type | VARCHAR(20) | 可选/强制 |
|
||
| signed | BOOLEAN | 是否数字签名 |
|
||
| md5 | VARCHAR(64) | MD5 校验值 |
|
||
| sha256 | VARCHAR(128) | SHA256 校验值 |
|
||
| release_notes | TEXT | 发布说明（JSON 数组） |
|
||
| file_path | VARCHAR(500) | 文件存储路径 |
|
||
|
||
#### dev.calibration_records — 校准记录表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| board_sn | VARCHAR(100) | 采集板SN号 |
|
||
| board_type_id | VARCHAR(64) | 关联板卡型号 |
|
||
| board_version | VARCHAR(50) | 板卡版本（冗余） |
|
||
| calibration_date | DATE | 校准日期 |
|
||
| expiry_date | DATE | 到期日期 |
|
||
| calibrator | VARCHAR(100) | 校准人员 |
|
||
| status | VARCHAR(20) | 合格/不合格/待校准 |
|
||
| channel_count | INT | 通道数 |
|
||
| overall_deviation | DECIMAL(10,4) | 综合偏差 |
|
||
| channel_results | JSONB | 各通道校准结果 |
|
||
|
||
#### dev.config_files — 配置文件表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| name | VARCHAR(100) | 配置文件名（如 CFG-GD30-v1.3.0） |
|
||
| model_id | VARCHAR(64) | 关联设备型号 |
|
||
| model_name | VARCHAR(100) | 型号名称（冗余） |
|
||
| version | VARCHAR(20) | 配置版本 |
|
||
| status | VARCHAR(20) | 生效/已停用 |
|
||
| transmission_params | JSONB | 发射参数 |
|
||
| acquisition_params | JSONB | 采集参数 |
|
||
| protection_params | JSONB | 保护参数 |
|
||
| network_params | JSONB | 网络参数 |
|
||
|
||
#### dev.licenses — 授权表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| model_id | VARCHAR(64) | 关联设备型号 |
|
||
| model_code | VARCHAR(50) | 型号代码（冗余） |
|
||
| modules | JSONB | 授权模块列表 |
|
||
| validity_type | VARCHAR(20) | 永久/1年/2年/自定义 |
|
||
| expiry_date | DATE | 到期日期 |
|
||
| status | VARCHAR(20) | 生效/草稿/已停用 |
|
||
|
||
#### dev.repair_orders — 维修工单表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| order_no | VARCHAR(50) | 工单号（如 WO-2024-0001），唯一索引 |
|
||
| device_sn | VARCHAR(100) | 设备SN号 |
|
||
| fault_type | VARCHAR(50) | 故障类型 |
|
||
| status | VARCHAR(20) | 待处理/处理中/已处理 |
|
||
| priority | VARCHAR(10) | 高/中/低 |
|
||
| assignee | VARCHAR(100) | 负责人 |
|
||
| description | VARCHAR(500) | 故障描述 |
|
||
| phenomenon | VARCHAR(500) | 故障现象 |
|
||
| expected_fix_date | DATE | 预计修复日期 |
|
||
| note | TEXT | 备注 |
|
||
| process_records | JSONB | 处理记录时间线 |
|
||
| board_replacements | JSONB | 板卡更换记录 |
|
||
|
||
#### dev.scrap_records — 报废记录表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| device_sn | VARCHAR(100) | 设备SN号 |
|
||
| model_name | VARCHAR(100) | 设备型号 |
|
||
| reason | VARCHAR(500) | 报废原因 |
|
||
| applicant | VARCHAR(100) | 申请人 |
|
||
| status | VARCHAR(20) | 待审批/审批中/已审批/已驳回/回收中/已回收 |
|
||
| order_id | VARCHAR(50) | 来源工单号 |
|
||
| residual_value | DECIMAL(12,2) | 残值评估 |
|
||
| materials | JSONB | 可回收物料列表 |
|
||
| approval_timeline | JSONB | 审批记录时间线 |
|
||
| approval_note | TEXT | 审批意见 |
|
||
|
||
#### dev.checklist_templates — Checklist 模板表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| model_id | VARCHAR(64) | 关联设备型号 |
|
||
| model_code | VARCHAR(50) | 型号代码（冗余） |
|
||
|
||
#### dev.checklist_items — Checklist 检查项表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| template_id | VARCHAR(64) | 关联模板 |
|
||
| name | VARCHAR(200) | 检查项名称 |
|
||
| required | BOOLEAN | 是否必填 |
|
||
| sort_order | INT | 排序序号 |
|
||
|
||
#### dev.calibration_files — 校准文件表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| board_sn | VARCHAR(100) | 采集板SN号，关联 board_cards.sn |
|
||
| original_name | VARCHAR(200) | 原始文件名 |
|
||
| file_path | VARCHAR(500) | 服务器存储路径 |
|
||
| file_size | BIGINT | 文件大小（字节） |
|
||
| md5 | VARCHAR(64) | 文件MD5校验值 |
|
||
| upload_time | TIMESTAMP | 上传时间 |
|
||
|
||
|
||
## 正确性属性
|
||
|
||
*正确性属性是在系统所有有效执行中都应成立的特征或行为——本质上是对系统应做什么的形式化陈述。属性是人类可读规范与机器可验证正确性保证之间的桥梁。*
|
||
|
||
### Property 1: 统一响应格式一致性
|
||
|
||
*For any* API 请求（无论成功或失败），响应 JSON 都应包含且仅包含 `code`（整数）、`message`（字符串）、`data`（泛型）三个顶层字段。成功时 code=0，业务异常和参数校验异常均应返回 code≠0 的统一格式响应。
|
||
|
||
**Validates: Requirements 1.3, 1.4**
|
||
|
||
### Property 2: 审计字段自动填充
|
||
|
||
*For any* 通过 MyBatis-Plus 插入的实体记录，`created_at` 和 `updated_at` 字段应非空且为合理的时间戳；*For any* 更新操作，`updated_at` 应大于等于更新前的值。*For any* `dev` schema 下的业务表，都应包含 `id`、`created_at`、`created_by`、`updated_at`、`updated_by`、`deleted` 六个审计字段。
|
||
|
||
**Validates: Requirements 1.5, 2.12**
|
||
|
||
### Property 3: CRUD 数据往返一致性
|
||
|
||
*For any* 有效的创建命令（设备、型号、板卡、固件、配置文件、授权、工单、Checklist 模板），通过 POST 创建后再通过 GET 查询，返回的数据应与创建时提交的数据一致（在服务端生成的字段如 id、审计字段除外）。
|
||
|
||
**Validates: Requirements 3.2, 3.3, 4.2, 4.4, 5.3, 6.2, 8.3, 8.4, 9.2, 9.3, 10.3**
|
||
|
||
### Property 4: 唯一性约束与冲突检测
|
||
|
||
*For any* 已存在的唯一标识（设备SN号、型号代码、同一板卡型号下的固件版本号），尝试创建具有相同唯一标识的记录时，API 应返回 HTTP 409 冲突错误码和描述性错误消息，且数据库中不应产生重复记录。
|
||
|
||
**Validates: Requirements 3.5, 4.5, 6.4**
|
||
|
||
### Property 5: 筛选条件正确性
|
||
|
||
*For any* 列表查询接口和任意有效的筛选参数组合，返回的所有记录都应满足指定的筛选条件。例如：按型号筛选时，所有返回的设备型号应与筛选值匹配；按状态筛选时，所有返回记录的状态应与筛选值匹配。
|
||
|
||
**Validates: Requirements 3.1, 5.1, 6.1, 7.1, 8.1, 9.1, 10.1, 11.1**
|
||
|
||
### Property 6: 状态转换正确性
|
||
|
||
*For any* 支持状态转换的实体（授权停用、工单关闭、报废审批/驳回/回收），执行状态转换操作后，实体的状态应更新为目标状态，且相关附加信息（如驳回意见、回收物料清单）应被正确记录。
|
||
|
||
**Validates: Requirements 9.4, 10.5, 11.3, 11.4, 11.5**
|
||
|
||
### Property 7: 逻辑删除排除性
|
||
|
||
*For any* 被逻辑删除的记录（deleted=1），该记录不应出现在任何列表查询的结果中。
|
||
|
||
**Validates: Requirements 8.5**
|
||
|
||
### Property 8: 分页一致性
|
||
|
||
*For any* 列表查询接口，响应应包含 `total`、`page`、`pageSize`、`records` 四个字段；`records` 的长度应不超过 `pageSize`；当不传筛选条件或筛选条件为空时，应返回不带过滤的完整数据集（受分页限制）。
|
||
|
||
**Validates: Requirements 14.1, 14.2, 14.4**
|
||
|
||
### Property 9: 聚合统计一致性
|
||
|
||
*For any* 统计接口返回的数据，各分类计数之和应等于总数。例如：设备状态分布中各状态数量之和应等于设备总数；报废统计中各状态数量之和应等于报废总数。
|
||
|
||
**Validates: Requirements 11.6, 12.2**
|
||
|
||
### Property 10: 参数校验防御性
|
||
|
||
*For any* 无效的筛选参数（如非法的状态值、格式错误的日期），API 应返回 HTTP 400 错误码和描述性错误消息，而非返回错误数据或抛出未处理异常。
|
||
|
||
**Validates: Requirements 14.3**
|
||
|
||
### Property 11: 校准文件上传-下载往返一致性
|
||
|
||
*For any* 有效的校准文件和已存在的采集板SN号，通过 POST `/api/portal/calibration-files/upload` 上传后，再通过 GET `/api/admin/calibration-files/{id}/download` 下载，下载的文件内容应与上传的原始文件完全一致，且 `dev.calibration_files` 表中的记录应正确关联该采集板SN号，文件大小和MD5校验值应与原始文件匹配。
|
||
|
||
**Validates: Requirements 17.2, 17.3, 17.7**
|
||
|
||
### Property 12: 校准文件列表完整性与排序
|
||
|
||
*For any* 采集板，上传 N 个校准文件后，通过 GET `/api/admin/board-cards/{id}/calibration-files` 查询应返回恰好 N 条记录，每条记录包含 id、fileName、fileSize、md5、uploadTime 字段，且结果按 uploadTime 倒序排列。
|
||
|
||
**Validates: Requirements 17.6, 17.10**
|
||
|
||
## 错误处理
|
||
|
||
### 后端错误处理策略
|
||
|
||
| 错误类型 | HTTP 状态码 | 业务码 | 处理方式 |
|
||
|----------|------------|--------|----------|
|
||
| 参数校验失败 | 400 | 40001 | `GlobalExceptionHandler` 捕获 `MethodArgumentNotValidException`，返回字段级错误信息 |
|
||
| 资源不存在 | 404 | 40401 | Service 层抛出 `BizException`，Handler 统一处理 |
|
||
| 文件不存在 | 404 | 40402 | 校准文件在存储目录中不存在时，返回描述性错误消息 |
|
||
| 唯一性冲突 | 409 | 40901 | Service 层检测重复后抛出 `BizException` |
|
||
| 文件上传失败 | 500 | 50002 | 文件写入磁盘失败时，记录日志并返回错误消息 |
|
||
| 服务器内部错误 | 500 | 50001 | `GlobalExceptionHandler` 兜底捕获，记录完整堆栈日志 |
|
||
|
||
### 自定义异常体系
|
||
|
||
```java
|
||
public class BizException extends RuntimeException {
|
||
private final int code;
|
||
private final String message;
|
||
|
||
public BizException(int code, String message) {
|
||
super(message);
|
||
this.code = code;
|
||
this.message = message;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 全局异常处理器
|
||
|
||
```java
|
||
@RestControllerAdvice
|
||
public class GlobalExceptionHandler {
|
||
|
||
@ExceptionHandler(BizException.class)
|
||
public R<Void> handleBizException(BizException e) {
|
||
return R.fail(e.getCode(), e.getMessage());
|
||
}
|
||
|
||
@ExceptionHandler(MethodArgumentNotValidException.class)
|
||
public R<Void> handleValidation(MethodArgumentNotValidException e) {
|
||
String msg = e.getBindingResult().getFieldErrors().stream()
|
||
.map(f -> f.getField() + ": " + f.getDefaultMessage())
|
||
.collect(Collectors.joining("; "));
|
||
return R.fail(40001, msg);
|
||
}
|
||
|
||
@ExceptionHandler(Exception.class)
|
||
public R<Void> handleException(Exception e) {
|
||
log.error("Unhandled exception", e);
|
||
return R.fail(50001, "服务器内部错误");
|
||
}
|
||
}
|
||
```
|
||
|
||
### 前端错误处理策略
|
||
|
||
| 场景 | 处理方式 |
|
||
|------|----------|
|
||
| 网络超时（5秒） | 显示"网络请求超时，请检查网络连接" |
|
||
| HTTP 400 | 显示后端返回的具体校验错误信息 |
|
||
| HTTP 404 | 显示"请求的资源不存在" |
|
||
| HTTP 409 | 显示后端返回的冲突描述（如"SN号已存在"） |
|
||
| HTTP 500 | 显示"服务器异常，请稍后重试" |
|
||
| 请求进行中 | 页面显示 loading 骨架屏或 spinner |
|
||
|
||
## 测试策略
|
||
|
||
### 后端测试
|
||
|
||
#### 单元测试
|
||
- 框架：JUnit 5 + Mockito
|
||
- 覆盖范围：
|
||
- Application Service 层的业务逻辑
|
||
- Domain Entity 的状态转换逻辑
|
||
- 参数校验逻辑
|
||
- 异常处理逻辑
|
||
|
||
#### 集成测试
|
||
- 框架：Spring Boot Test + TestContainers（PostgreSQL）
|
||
- 覆盖范围：
|
||
- Controller 层 API 端点的请求/响应格式
|
||
- MyBatis-Plus Mapper 的 CRUD 操作
|
||
- 审计字段自动填充
|
||
- 逻辑删除行为
|
||
- 分页查询
|
||
|
||
#### 属性测试
|
||
- 框架：jqwik（Java 属性测试库）
|
||
- 最少 100 次迭代
|
||
- 每个属性测试需引用设计文档中的属性编号
|
||
- 标签格式：`Feature: frontend-backend-separation, Property {number}: {property_text}`
|
||
- 覆盖范围：
|
||
- Property 1: 统一响应格式（生成随机数据类型，验证序列化格式）
|
||
- Property 3: CRUD 往返一致性（生成随机实体数据，验证创建-查询一致性）
|
||
- Property 4: 唯一性约束（生成随机唯一标识，验证重复创建返回 409）
|
||
- Property 5: 筛选正确性（生成随机筛选参数，验证返回结果匹配）
|
||
- Property 8: 分页一致性（生成随机 page/pageSize，验证响应格式）
|
||
- Property 10: 参数校验（生成随机无效参数，验证返回 400）
|
||
- Property 11: 校准文件上传-下载往返（生成随机文件内容和SN号，验证上传后下载内容一致、元数据正确）
|
||
- Property 12: 校准文件列表完整性（生成随机数量的校准文件上传，验证列表返回数量和排序正确）
|
||
|
||
### 前端测试
|
||
|
||
#### 单元测试
|
||
- 框架：Vitest + React Testing Library
|
||
- 覆盖范围：
|
||
- API 客户端的请求拦截和错误处理
|
||
- 各 API 服务文件的请求参数构造
|
||
- 页面组件的加载状态和错误状态渲染
|
||
- 板卡详情抽屉中校准文件列表的渲染和下载按钮交互
|
||
|
||
#### 集成测试
|
||
- 框架：Vitest + MSW（Mock Service Worker）
|
||
- 覆盖范围：
|
||
- 页面组件与 API 的完整交互流程
|
||
- 筛选、分页操作的数据刷新
|
||
- 表单提交与 API 调用
|
||
|