191 lines
15 KiB
Markdown
191 lines
15 KiB
Markdown
# 需求文档：前后端分离 — Java API 后端与 PostgreSQL 数据库
|
||
|
||
## 简介
|
||
|
||
本项目旨在将现有的 Next.js 前端生产管理子系统进行前后端分离改造。当前前端所有页面（设备列表、板卡管理、校准管理、固件库、授权管理、配置文件管理、维修工单、报废管理、设备登记、设备型号管理）均使用硬编码的模拟数据。需要搭建 Java Spring Boot 3.3.6 后端 API 服务和 PostgreSQL 数据库，用真实的 RESTful API 接口和持久化数据替换前端模拟数据。
|
||
|
||
## 术语表
|
||
|
||
- **API_Server**：基于 Spring Boot 3.3.6 的 Java 后端 API 服务，项目路径 `apps/geo-bps-api/`
|
||
- **Database**：PostgreSQL 12.14 数据库实例，按模块使用不同 schema 隔离
|
||
- **Frontend**：现有 Next.js 前端应用，位于 `src/app/` 目录
|
||
- **Device_Module**：设备管理业务模块，包名 `com.geomative.bps.device`，数据库 schema `dev`
|
||
- **Common_Module**：公共模块，包名 `com.geomative.bps.common`，提供统一响应体、全局异常处理、工具类
|
||
- **API_Admin**：后台管理入口模块，提供需登录鉴权的 API 端点
|
||
- **DDD**：领域驱动设计分层架构（interfaces / application / domain / infrastructure）
|
||
- **DO**：数据库映射对象（Data Object）
|
||
- **VO**：视图对象（View Object），用于 API 响应
|
||
- **Query**：查询参数对象
|
||
- **Command**：命令对象，用于创建/更新操作
|
||
|
||
## 需求
|
||
|
||
### 需求 1：后端项目骨架搭建
|
||
|
||
**用户故事：** 作为开发者，我希望搭建一个符合技术规范的 Java Spring Boot 多模块 Maven 项目骨架，以便后续各业务模块可以在此基础上开发。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE API_Server SHALL 采用多模块 Maven 项目结构，父 POM 统一管理 Spring Boot 3.3.6、MyBatis-Plus、Lombok 等依赖版本
|
||
2. THE API_Server SHALL 包含以下子模块：api-admin、api-portal、business（含 device 子模块）、common
|
||
3. THE Common_Module SHALL 提供统一 JSON 响应格式，包含 code（整数）、message（字符串）、data（泛型）三个字段
|
||
4. THE Common_Module SHALL 提供全局异常处理器，捕获业务异常和参数校验异常并返回统一格式的错误响应
|
||
5. THE Common_Module SHALL 提供 MyBatis-Plus 的 MetaObjectHandler 实现，自动填充 created_at 和 updated_at 审计字段
|
||
6. THE API_Admin SHALL 配置 CORS 策略，允许前端开发服务器（localhost:3000）的跨域请求
|
||
7. THE API_Server SHALL 在 application.yml 中配置 PostgreSQL 数据源连接和 MyBatis-Plus 逻辑删除策略
|
||
|
||
### 需求 2：数据库 Schema 与表结构设计
|
||
|
||
**用户故事：** 作为开发者，我希望设计并创建 PostgreSQL 数据库表结构，以便持久化存储各业务模块的数据。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE Database SHALL 在 `dev` schema 下创建设备管理相关的数据表
|
||
2. THE Database SHALL 包含 `dev.devices` 表，存储设备信息（SN号、型号、状态、固件版本、生产日期、客户名称、批次号）
|
||
3. THE Database SHALL 包含 `dev.device_models` 表，存储设备型号信息（型号名称、型号代码、状态、描述）
|
||
4. THE Database SHALL 包含 `dev.board_types` 表，存储板卡型号信息（板卡类型、型号、固件版本、生产日期、状态）
|
||
5. THE Database SHALL 包含 `dev.firmware_versions` 表，存储固件版本信息（版本号、板卡型号、固件类型、发布日期、状态、文件大小、下载次数、硬件版本范围、升级类型、是否签名、MD5、SHA256、发布说明）
|
||
6. THE Database SHALL 包含 `dev.calibration_records` 表，存储校准记录（采集板SN号、板卡型号、校准日期、到期日期、校准人员、状态、通道数、综合偏差）
|
||
7. THE Database SHALL 包含 `dev.config_files` 表，存储配置文件信息（配置名称、适配型号、版本、状态、发射参数、采集参数、网络参数）
|
||
8. THE Database SHALL 包含 `dev.licenses` 表，存储授权信息（设备型号、授权模块列表、到期时间、状态）
|
||
9. THE Database SHALL 包含 `dev.repair_orders` 表，存储维修工单信息（工单号、设备SN、故障类型、状态、优先级、负责人、描述）
|
||
10. THE Database SHALL 包含 `dev.scrap_records` 表，存储报废记录（设备SN、型号、报废原因、申请人、状态、来源工单号、残值评估、可回收物料）
|
||
11. THE Database SHALL 包含 `dev.checklist_templates` 表和 `dev.checklist_items` 表，存储装配 Checklist 模板及其检查项
|
||
12. WHEN 创建任何业务表时，THE Database SHALL 包含 id（VARCHAR(64) 主键）、created_at、created_by、updated_at、updated_by、deleted 审计字段
|
||
|
||
### 需求 3：设备管理 API
|
||
|
||
**用户故事：** 作为前端开发者，我希望通过 API 获取和管理设备数据，以便替换设备列表页面的模拟数据。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 前端请求 GET `/api/admin/devices` 时，THE API_Server SHALL 返回分页的设备列表，支持按型号、状态、生产日期、SN号、批次号筛选
|
||
2. WHEN 前端请求 GET `/api/admin/devices/{sn}` 时，THE API_Server SHALL 返回指定设备的详细信息，包含关联的授权信息、子设备列表、固件信息
|
||
3. WHEN 前端请求 POST `/api/admin/devices` 时，THE API_Server SHALL 创建新设备记录（设备登记），包含装机信息和 BOM 清单
|
||
4. WHEN 前端请求 GET `/api/admin/devices/batches` 时，THE API_Server SHALL 返回所有生产批次列表及每个批次的设备数量
|
||
5. IF 请求参数中的 SN 号已存在，THEN THE API_Server SHALL 返回 409 冲突错误码和描述性错误消息
|
||
|
||
### 需求 4：设备型号管理 API
|
||
|
||
**用户故事：** 作为前端开发者，我希望通过 API 管理设备型号和装配 Checklist 模板，以便替换型号管理页面的模拟数据。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 前端请求 GET `/api/admin/device-models` 时，THE API_Server SHALL 返回所有设备型号列表
|
||
2. WHEN 前端请求 POST `/api/admin/device-models` 时，THE API_Server SHALL 创建新设备型号记录
|
||
3. WHEN 前端请求 GET `/api/admin/checklist-templates?modelCode={code}` 时，THE API_Server SHALL 返回指定型号的装配 Checklist 模板及其检查项列表
|
||
4. WHEN 前端请求 POST `/api/admin/checklist-templates` 时，THE API_Server SHALL 创建新的 Checklist 模板，包含检查项列表
|
||
5. IF 请求的型号代码已存在，THEN THE API_Server SHALL 返回 409 冲突错误码
|
||
|
||
### 需求 5：板卡型号管理 API
|
||
|
||
**用户故事：** 作为前端开发者，我希望通过 API 管理板卡型号数据，以便替换板卡管理页面的模拟数据。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 前端请求 GET `/api/admin/board-types` 时，THE API_Server SHALL 返回板卡型号列表，支持按板卡类型（主协板、采集板、发射板、升压板）筛选
|
||
2. WHEN 前端请求 GET `/api/admin/board-types/{id}` 时，THE API_Server SHALL 返回板卡详情，包含升级历史、校准历史、保养历史、维修历史
|
||
3. WHEN 前端请求 POST `/api/admin/board-types` 时，THE API_Server SHALL 创建新板卡型号记录
|
||
|
||
### 需求 6：固件库管理 API
|
||
|
||
**用户故事：** 作为前端开发者，我希望通过 API 管理固件版本数据，以便替换固件库页面的模拟数据。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 前端请求 GET `/api/admin/firmware` 时，THE API_Server SHALL 返回固件版本列表，支持按固件类型和板卡型号筛选
|
||
2. WHEN 前端请求 POST `/api/admin/firmware` 时，THE API_Server SHALL 创建新固件版本记录，包含版本号、硬件版本范围、升级类型、固件类型、签名状态、发布说明
|
||
3. WHEN 前端请求 GET `/api/admin/firmware/{id}/download` 时，THE API_Server SHALL 返回固件文件的下载流，并将该固件的下载次数加 1
|
||
4. IF 上传的固件版本号与同一板卡型号的已有版本重复，THEN THE API_Server SHALL 返回 409 冲突错误码
|
||
|
||
### 需求 7：校准管理 API
|
||
|
||
**用户故事：** 作为前端开发者，我希望通过 API 管理采集板校准数据，以便替换校准管理页面的模拟数据。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 前端请求 GET `/api/admin/calibrations` 时，THE API_Server SHALL 返回分页的校准记录列表，支持按采集板SN号、校准状态、校准人员筛选
|
||
2. WHEN 前端请求 GET `/api/admin/calibrations/{id}` 时，THE API_Server SHALL 返回校准详情，包含各通道的校准结果（参考值、测量值、偏差、结果）
|
||
3. WHEN 前端请求 POST `/api/admin/calibrations/import` 时，THE API_Server SHALL 支持批量导入校准记录数据
|
||
|
||
### 需求 8：配置文件管理 API
|
||
|
||
**用户故事：** 作为前端开发者，我希望通过 API 管理设备配置文件，以便替换配置文件管理页面的模拟数据。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 前端请求 GET `/api/admin/config-files` 时，THE API_Server SHALL 返回分页的配置文件列表，支持按适配型号、版本、关键字筛选
|
||
2. WHEN 前端请求 GET `/api/admin/config-files/{id}` 时，THE API_Server SHALL 返回配置文件详情，包含发射参数、采集参数、网络参数
|
||
3. WHEN 前端请求 POST `/api/admin/config-files` 时，THE API_Server SHALL 创建新配置文件记录
|
||
4. WHEN 前端请求 PUT `/api/admin/config-files/{id}` 时，THE API_Server SHALL 更新指定配置文件记录
|
||
5. WHEN 前端请求 DELETE `/api/admin/config-files/{id}` 时，THE API_Server SHALL 逻辑删除指定配置文件（设置 deleted=1）
|
||
|
||
### 需求 9：授权管理 API
|
||
|
||
**用户故事：** 作为前端开发者，我希望通过 API 管理设备授权数据，以便替换授权管理页面的模拟数据。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 前端请求 GET `/api/admin/licenses` 时，THE API_Server SHALL 返回分页的授权列表，支持按设备型号和状态筛选
|
||
2. WHEN 前端请求 POST `/api/admin/licenses` 时，THE API_Server SHALL 创建新授权记录，包含设备型号、授权模块列表、授权期限
|
||
3. WHEN 前端请求 PUT `/api/admin/licenses/{id}` 时，THE API_Server SHALL 更新指定授权记录
|
||
4. WHEN 前端请求 PUT `/api/admin/licenses/{id}/disable` 时，THE API_Server SHALL 将指定授权记录状态设置为已停用
|
||
|
||
### 需求 10：维修工单管理 API
|
||
|
||
**用户故事：** 作为前端开发者，我希望通过 API 管理维修工单数据，以便替换维修工单页面的模拟数据。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 前端请求 GET `/api/admin/repair-orders` 时，THE API_Server SHALL 返回分页的维修工单列表，支持按状态、优先级、负责人、日期范围、设备SN筛选
|
||
2. WHEN 前端请求 GET `/api/admin/repair-orders/{id}` 时，THE API_Server SHALL 返回工单详情，包含设备信息、故障信息、处理记录时间线、板卡更换记录
|
||
3. WHEN 前端请求 POST `/api/admin/repair-orders` 时，THE API_Server SHALL 创建新维修工单
|
||
4. WHEN 前端请求 PUT `/api/admin/repair-orders/{id}/process` 时，THE API_Server SHALL 更新工单处理信息（处理操作、板卡更换、授权处理、处理备注）
|
||
5. WHEN 前端请求 PUT `/api/admin/repair-orders/{id}/close` 时，THE API_Server SHALL 关闭工单并将状态设置为已处理
|
||
|
||
### 需求 11：报废管理 API
|
||
|
||
**用户故事：** 作为前端开发者，我希望通过 API 管理报废审批和物料回收数据，以便替换报废管理页面的模拟数据。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 前端请求 GET `/api/admin/scrap-records` 时，THE API_Server SHALL 返回分页的报废记录列表，支持按设备SN、状态、日期筛选
|
||
2. WHEN 前端请求 GET `/api/admin/scrap-records/{id}` 时，THE API_Server SHALL 返回报废详情，包含设备信息、审批信息、可回收物料列表、审批记录时间线
|
||
3. WHEN 前端请求 PUT `/api/admin/scrap-records/{id}/approve` 时，THE API_Server SHALL 审批通过报废申请，更新状态为已审批
|
||
4. WHEN 前端请求 PUT `/api/admin/scrap-records/{id}/reject` 时，THE API_Server SHALL 驳回报废申请，更新状态为已驳回，记录驳回意见
|
||
5. WHEN 前端请求 PUT `/api/admin/scrap-records/{id}/recover` 时，THE API_Server SHALL 完成物料回收入库，更新状态为已回收，记录回收的物料清单
|
||
6. THE API_Server SHALL 提供 GET `/api/admin/scrap-records/stats` 接口，返回报废统计数据（报废总数、待审批数、已审批待回收数、已回收数）
|
||
|
||
### 需求 12：首页 Dashboard 统计 API
|
||
|
||
**用户故事：** 作为前端开发者，我希望通过 API 获取首页仪表盘的统计数据，以便替换首页的模拟数据。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 前端请求 GET `/api/admin/dashboard/metrics` 时，THE API_Server SHALL 返回设备总数、装配中数量、已激活数量、维修中数量、报废数量、授权即将到期数量等统计指标
|
||
2. WHEN 前端请求 GET `/api/admin/dashboard/device-status` 时，THE API_Server SHALL 返回设备状态分布数据（已装配、已出厂、已激活、报废各状态的数量）
|
||
3. WHEN 前端请求 GET `/api/admin/dashboard/tasks` 时，THE API_Server SHALL 返回待处理任务列表，包含校准即将到期、维修工单、固件升级通知、授权即将到期四个分组
|
||
|
||
### 需求 13：前端 API 集成层
|
||
|
||
**用户故事：** 作为前端开发者，我希望在前端建立统一的 API 调用层，以便各页面组件可以方便地调用后端接口替换模拟数据。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE Frontend SHALL 创建统一的 API 客户端模块，配置后端 API 基础 URL、请求超时时间（5秒）、统一错误处理
|
||
2. THE Frontend SHALL 为每个业务模块创建独立的 API 服务文件（如 deviceApi.ts、boardApi.ts、firmwareApi.ts 等）
|
||
3. WHEN API 请求失败时，THE Frontend SHALL 在页面上展示友好的错误提示信息
|
||
4. WHEN API 请求正在进行时，THE Frontend SHALL 展示加载状态指示器
|
||
5. THE Frontend SHALL 将各页面组件中的硬编码模拟数据替换为 API 调用，使用 React 的 useState 和 useEffect 管理数据获取状态
|
||
|
||
### 需求 14：分页与筛选标准化
|
||
|
||
**用户故事：** 作为前端开发者，我希望前后端采用统一的分页和筛选参数规范，以便各列表页面的数据交互保持一致。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE API_Server SHALL 对所有列表接口采用统一的分页参数格式：page（页码，从1开始）、pageSize（每页条数，默认10）
|
||
2. THE API_Server SHALL 对所有列表接口返回统一的分页响应格式，包含 total（总记录数）、page（当前页码）、pageSize（每页条数）、records（数据列表）
|
||
3. THE API_Server SHALL 对所有筛选参数进行服务端校验，无效参数返回 400 错误码和描述性错误消息
|
||
4. WHEN 筛选条件为空或为"全部"时，THE API_Server SHALL 返回不带该条件过滤的完整数据集
|