工件服务 - 邮轮穿舱件管理系统后台
概述
本文档详细介绍了邮轮穿舱件管理系统中的工件服务核心业务逻辑，包括工件状态跟踪、验证规则、数据模型和服务架构。系统采用双数据库架构，使用PostgreSQL存储工件基础信息，MongoDB存储工件详细信息。
系统架构
整体架构图
flowchart TD
subgraph 前端层
A[Web界面]
B[移动端应用]
end
subgraph API网关层
C[工件路由]
D[工件信息路由]
end
subgraph 业务逻辑层
E[工件服务]
F[工件信息服务]
end
subgraph 数据访问层
G[PostgreSQL<br/>工件表]
H[MongoDB<br/>工件信息集合]
end
A --> C
B --> C
C --> E
D --> F
E --> G
F --> H
组件关系图
flowchart TD
subgraph 路由层
Router1[工件路由<br/>/workpiece]
Router2[工件信息路由<br/>/workpiece-info]
end
subgraph 服务层
Service1[工件服务]
Service2[工件信息服务]
end
subgraph 模型层
Model1[Workpiece<br/>PostgreSQL]
Model2[WorkpieceInfo<br/>MongoDB]
end
Router1 --> Service1
Router2 --> Service2
Service1 --> Model1
Service2 --> Model2
数据模型设计
工件实体模型 (PostgreSQL)
classDiagram
class Workpiece {
+workpiece_id: int (PK)
+workpiece_status: int
+inspect_reference: int
+maintainance_reference: int
+created_by: int
+updated_by: int
+created_at: datetime
+updated_at: datetime
}
工件实体字段说明：
workpiece_id: 工件唯一标识符，主键workpiece_status: 工件状态码，用于状态跟踪inspect_reference: 视检参考工单IDmaintainance_reference: 维护参考工单IDcreated_by/updated_by: 创建/更新人员标识created_at/updated_at: 时间戳记录
参考源文件：
工件信息模型 (MongoDB)
classDiagram
class WorkpieceInfo {
+wp_id: str
+wp_firestop_code: str
+wp_matrial: str
+wp_size: str
+wp_fire_rating: str
+wp_watertightness: str
+wp_main_vertical_zone: str
+wp_installation_location: str
+wp_z_coordinate: str
+wp_frame_station: str
+wp_longitudinal_stiffener: str
+wp_sap1: str
+wp_sap2: str
+wp_standard_drawing_catalogue: str
+wp_extra: str
}
工件信息字段映射表：
| 字段名 | 中文含义 | 数据类型 | 约束 |
|---|---|---|---|
| wp_firestop_code | 防火板代号 | str | 必填 |
| wp_matrial | 材料 | str | 必填 |
| wp_size | 规格 | str | 必填 |
| wp_fire_rating | 防火等级 | str | 必填 |
| wp_watertightness | 水密等级 | str | 必填 |
| wp_main_vertical_zone | 主竖区 | str | 必填 |
| wp_installation_location | 安装位置 | str | 必填 |
| wp_z_coordinate | Z坐标 | str | 必填 |
| wp_frame_station | 肋位 | str | 必填 |
| wp_longitudinal_stiffener | 纵桁 | str | 必填 |
| wp_sap1 | SAP1 | str | 必填 |
| wp_sap2 | SAP2 | str | 必填 |
| wp_standard_drawing_catalogue | 图册章节 | str | 必填 |
| wp_extra | 额外信息 | str | 可选 |
参考源文件：
业务逻辑服务
工件服务 (Workpiece Service)
flowchart TD
A[API请求] --> B{操作类型}
B -->|创建| C[验证参数]
B -->|查询| D[构建查询]
B -->|更新| E[检查存在性]
B -->|删除| F[验证权限]
C --> G[创建记录]
D --> H[执行查询]
E --> I[更新字段]
F --> J[删除记录]
G --> K[返回结果]
H --> K
I --> K
J --> K
核心服务方法
1. 创建工件
async def service_create_workpiece(
inspect_reference: int = 0,
maintainance_reference: int = 0,
created_by: int = -1
) -> Workpiece
- 参数验证：确保参考ID有效性
- 状态初始化：默认状态为0（新建）
- 异常处理：完整性约束检查
2. 状态更新
async def service_update_workpiece_status(
workpiece_id: int,
updated_status: int,
updated_by: int = -1
) -> Optional[Workpiece]
- 状态验证：确保状态码有效性
- 权限检查：更新人员权限验证
- 审计追踪：记录更新时间戳
参考源文件：
工件信息服务 (Workpiece Info Service)
sequenceDiagram
participant Client as 客户端
participant Router as 工件信息路由
participant Service as 工件信息服务
participant MongoDB as MongoDB
Client->>Router: POST /workpiece-info
Router->>Service: service_create_workpiece_info()
Service->>MongoDB: 检查wp_id唯一性
MongoDB-->>Service: 查询结果
alt wp_id已存在
Service-->>Router: HTTP 400错误
Router-->>Client: 错误响应
else wp_id可用
Service->>MongoDB: 插入新文档
MongoDB-->>Service: 插入结果
Service-->>Router: 成功响应
Router-->>Client: 创建成功
end
核心服务方法
1. 创建工件信息
async def service_create_workpiece_info(
workpiece_info_data: WorkpieceInfoSchemaIn
) -> WorkpieceInfo
- 唯一性验证：检查wp_id是否重复
- 数据完整性：必填字段验证
- 中文映射：字段名称自动转换
2. 搜索功能
async def service_search_workpiece_infos_by_code(
firestop_code: str
) -> List[WorkpieceInfo]
- 模糊匹配：支持部分匹配搜索
- 大小写不敏感：提升搜索体验
- 性能优化：使用MongoDB索引
参考源文件：
API接口设计
工件路由接口
flowchart LR
A[POST /workpiece] --> B[创建工件]
C[GET /workpiece/all] --> D[获取所有工件]
E[DELETE /workpiece/{wp_id}] --> F[删除工件]
G[PUT /workpiece/{wp_id}/status] --> H[更新状态]
接口详情：
- 创建工件：
POST /workpiece- 创建新的工件实体 - 获取工件：
GET /workpiece/all- 分页获取工件列表 - 删除工件：
DELETE /workpiece/{wp_id}- 根据ID删除工件 - 状态更新：
PUT /workpiece/{wp_id}/status- 更新工件状态
参考源文件：
工件信息路由接口
flowchart TB
A[POST /workpiece-info] --> B[创建工件信息]
C[GET /workpiece-info/{wp_id}] --> D[获取详细信息]
E[GET /workpiece-info/] --> F[分页列表]
G[PUT /workpiece-info/{wp_id}] --> H[更新信息]
I[DELETE /workpiece-info/{wp_id}] --> J[删除信息]
K[GET /workpiece-info/search/by-code] --> L[搜索功能]
接口详情：
- CRUD操作：完整的增删改查接口
- 搜索功能：基于防火板代号的模糊搜索
- 向后兼容：支持ObjectId查询的旧接口
参考源文件：
状态跟踪机制
工件状态流程图
stateDiagram-v2
[*] --> 新建: 创建工件
新建 --> 待检验: 分配检验任务
待检验 --> 检验中: 开始检验
检验中 --> 检验完成: 完成检验
检验完成 --> 待维护: 需要维护
检验完成 --> 已完成: 无需维护
待维护 --> 维护中: 开始维护
维护中 --> 已完成: 完成维护
已完成 --> [*]
note right of 新建
状态码: 0
初始状态
end note
note right of 检验完成
状态码: 2
检验流程结束
end note
note right of 已完成
状态码: 4
工件生命周期结束
end note
状态码定义表
| 状态码 | 状态名称 | 描述 | 允许操作 |
|---|---|---|---|
| 0 | 新建 | 工件刚创建，未分配任务 | 分配检验、更新信息 |
| 1 | 待检验 | 已分配检验任务，等待检验 | 开始检验、取消分配 |
| 2 | 检验中 | 正在进行检验操作 | 完成检验、暂停检验 |
| 3 | 检验完成 | 检验流程已完成 | 分配维护、标记完成 |
| 4 | 待维护 | 需要维护操作 | 开始维护、取消维护 |
| 5 | 维护中 | 正在进行维护 | 完成维护、暂停维护 |
| 6 | 已完成 | 工件生命周期结束 | 归档、历史查询 |
验证规则与约束
数据验证规则
工件实体验证：
- 工件ID：必须为正整数，系统自动生成
- 状态码：必须在0-6范围内
- 参考ID：必须为有效工单ID或0（无参考）
工件信息验证：
- wp_id：字符串格式，必须唯一
- 必填字段：所有技术参数必须提供
- 格式验证：坐标、代号等特殊格式验证
业务规则约束
- 状态转换约束：只能按照预定义状态流程转换
- 数据一致性：工件与工件信息必须同步更新
- 权限控制：只有授权用户才能修改关键状态
- 审计追踪：所有操作必须记录访问日志
错误处理机制
异常分类处理
flowchart TD
A[服务调用] --> B{操作类型}
B --> C[数据操作]
B --> D[业务逻辑]
B --> E[系统异常]
C --> F{异常类型}
F -->|唯一性冲突| G[返回400错误]
F -->|数据不存在| H[返回404错误]
D --> I[业务规则违反]
I --> J[返回422错误]
E --> K[系统内部错误]
K --> L[返回500错误]
错误码映射表
| HTTP状态码 | 错误类型 | 描述 | 处理建议 |
|---|---|---|---|
| 400 | 客户端错误 | 数据验证失败、唯一性冲突 | 检查输入数据 |
| 404 | 资源不存在 | 工件或工件信息不存在 | 验证ID有效性 |
| 422 | 业务规则违反 | 状态转换不允许 | 检查业务流程 |
| 500 | 服务器错误 | 系统内部异常 | 联系系统管理员 |
性能优化策略
数据库优化
-
索引策略：
- PostgreSQL：workpiece_id主键索引，status状态索引
- MongoDB：wp_id唯一索引，firestop_code搜索索引
-
查询优化：
- 分页查询：限制返回记录数量
- 懒加载：按需加载关联数据
- 缓存策略：热点数据缓存
服务层优化
- 批量操作：支持批量创建和更新
- 异步处理：使用异步IO提升并发性能
- 连接池：数据库连接复用管理
安全考虑
安全机制
- 身份认证：JWT令牌验证
- 权限控制：基于角色的访问控制
- 数据加密：敏感字段加密存储
- 输入验证：防止SQL注入和XSS攻击
审计日志
所有工件操作都会记录详细的访问日志，包括：
- 操作人员、时间戳
- 操作类型和描述
- 影响的工件ID
- 操作结果状态
索引
工件服务作为邮轮穿舱件管理系统的核心模块，提供了完整的工件生命周期管理功能。通过双数据库架构实现了基础信息与详细信息的分离存储，确保了系统的扩展性和性能。严格的状态跟踪机制和验证规则保证了业务流程的规范性和数据的一致性。
系统的设计充分考虑了实际业务需求，提供了灵活的搜索功能和完整的CRUD操作接口，同时通过完善的错误处理和安全管理机制确保了系统的稳定性和安全性。
参考源文件汇总：