# 需求文档：前后端分离 — 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 返回不带该条件过滤的完整数据集