工件API文档
概述
本文档详细记录了邮轮穿舱件管理系统后台的工件管理相关接口，包括工件基本信息管理、工件状态更新、工件信息查询等功能。系统采用FastAPI框架构建，支持JWT身份验证，并实现了完整的CRUD操作。
系统架构
整体架构图
flowchart TD
subgraph 客户端层
A[Web前端]
B[移动端]
C[第三方系统]
end
subgraph API网关层
D[FastAPI应用]
end
subgraph 业务逻辑层
E[工件路由器]
F[工件信息路由器]
G[服务层]
end
subgraph 数据访问层
H[工件模型]
I[工件信息模型]
end
subgraph 数据存储层
J[PostgreSQL]
K[MongoDB]
end
A --> D
B --> D
C --> D
D --> E
D --> F
E --> G
F --> G
G --> H
G --> I
H --> J
I --> K
核心组件关系图
classDiagram
class WorkpieceRouter {
+APIRouter workpiece_unit_router
+api_create_workpiece()
+api_get_workpiece()
+api_delete_workpiece()
+api_update_workpiece_status()
}
class WorkpieceInfoRouter {
+APIRouter workpiece_info_router
+api_create_workpiece_info()
+api_get_workpiece_info()
+api_get_all_workpiece_infos()
+api_update_workpiece_info()
+api_delete_workpiece_info()
+api_search_workpiece_infos_by_code()
}
class WorkpieceService {
+service_create_workpiece()
+service_get_workpiece_by_id()
+service_get_all_workpieces()
+service_update_workpiece()
+service_delete_workpiece()
+service_update_workpiece_status()
}
class WorkpieceInfoService {
+service_create_workpiece_info()
+service_get_workpiece_info_by_wp_id()
+service_get_all_workpiece_infos()
+service_update_workpiece_info()
+service_delete_workpiece_info()
+service_search_workpiece_infos_by_code()
}
class Workpiece {
+workpiece_id: IntField
+workpiece_status: IntField
+inspect_reference: IntField
+maintainance_reference: IntField
+created_by: IntField
+updated_by: IntField
+created_at: DatetimeField
+updated_at: DatetimeField
}
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
}
WorkpieceRouter --> WorkpieceService : 调用
WorkpieceInfoRouter --> WorkpieceInfoService : 调用
WorkpieceService --> Workpiece : 操作
WorkpieceInfoService --> WorkpieceInfo : 操作
数据模型
工件模型 (Workpiece)
工件模型用于存储工件的基本信息，采用PostgreSQL关系型数据库存储。
字段说明：
workpiece_id: 工件ID，主键workpiece_status: 工件状态，整数类型inspect_reference: 视检参考工单IDmaintainance_reference: 维护参考工单IDcreated_by: 创建人IDupdated_by: 更新人IDcreated_at: 创建时间updated_at: 更新时间
参考文件：
工件信息模型 (WorkpieceInfo)
工件信息模型用于存储工件的详细信息，采用MongoDB文档数据库存储。
字段说明：
wp_id: 工件ID，字符串类型wp_firestop_code: 防火板代号wp_matrial: 材料wp_size: 规格wp_fire_rating: 防火等级wp_watertightness: 水密等级wp_main_vertical_zone: 主竖区wp_installation_location: 安装位置wp_z_coordinate: Z坐标wp_frame_station: 肋位wp_longitudinal_stiffener: 纵桁wp_sap1: SAP1wp_sap2: SAP2wp_standard_drawing_catalogue: 图册章节wp_extra: 额外信息
参考文件：
API接口详情
工件管理接口
1. 创建工件
接口路径： POST /workpiece/
功能描述： 创建新的工件实体
请求参数： 无
响应数据：
{
"workpiece_id": 1,
"workpiece_status": 0,
"inspect_reference": 0,
"maintainance_reference": 0,
"created_by": -1,
"updated_by": -1,
"created_at": "2024-01-01T00:00:00",
"updated_at": "2024-01-01T00:00:00"
}
状态码：
- 201: 创建成功
- 400: 请求参数错误
- 500: 服务器内部错误
参考文件：
2. 获取所有工件
接口路径： GET /workpiece/all
功能描述： 获取系统中所有工件实体
请求参数： 无
响应数据：
[
{
"workpiece_id": 1,
"workpiece_status": 0,
"inspect_reference": 0,
"maintainance_reference": 0,
"created_by": -1,
"updated_by": -1,
"created_at": "2024-01-01T00:00:00",
"updated_at": "2024-01-01T00:00:00"
}
]
参考文件：
3. 删除工件
接口路径： DELETE /workpiece/{wp_id}
功能描述： 根据ID删除工件实体
请求参数：
wp_id: 工件ID（路径参数）
响应数据：
{
"message": "Workpiece deleted successfully"
}
状态码：
- 200: 删除成功
- 404: 工件不存在
- 500: 服务器内部错误
参考文件：
4. 更新工件状态
接口路径： PUT /workpiece/{wp_id}/status
功能描述： 根据ID更新工件状态
请求参数：
wp_id: 工件ID（路径参数）status: 新状态（查询参数）
响应数据：
{
"workpiece_id": 1,
"workpiece_status": 1,
"inspect_reference": 0,
"maintainance_reference": 0,
"created_by": -1,
"updated_by": -1,
"created_at": "2024-01-01T00:00:00",
"updated_at": "2024-01-01T00:00:00"
}
状态码：
- 200: 更新成功
- 404: 工件不存在
- 500: 服务器内部错误
参考文件：
工件信息管理接口
1. 创建工件信息
接口路径： POST /workpiece-info/
功能描述： 创建新的工件信息记录
请求参数：
{
"wp_id": "WP001",
"wp_firestop_code": "FS001",
"wp_matrial": "不锈钢",
"wp_size": "100x100",
"wp_fire_rating": "A级",
"wp_watertightness": "IP68",
"wp_main_vertical_zone": "MZ001",
"wp_installation_location": "甲板A区",
"wp_z_coordinate": "Z100",
"wp_frame_station": "FS001",
"wp_longitudinal_stiffener": "LS001",
"wp_sap1": "SAP001",
"wp_sap2": "SAP002",
"wp_standard_drawing_catalogue": "TD001",
"wp_extra": "额外信息"
}
响应数据：
{
"wp_id": "WP001",
"wp_firestop_code": "FS001",
"wp_matrial": "不锈钢",
"wp_size": "100x100",
"wp_fire_rating": "A级",
"wp_watertightness": "IP68",
"wp_main_vertical_zone": "MZ001",
"wp_installation_location": "甲板A区",
"wp_z_coordinate": "Z100",
"wp_frame_station": "FS001",
"wp_longitudinal_stiffener": "LS001",
"wp_sap1": "SAP001",
"wp_sap2": "SAP002",
"wp_standard_drawing_catalogue": "TD001",
"wp_extra": "额外信息"
}
参考文件：
2. 获取工件信息
接口路径： GET /workpiece-info/{wp_id}
功能描述： 根据工件wp_id获取详细信息
请求参数：
wp_id: 工件ID（路径参数）
响应数据： 同创建接口响应数据
状态码：
- 200: 获取成功
- 404: 工件信息不存在
参考文件：
3. 获取工件信息列表
接口路径： GET /workpiece-info/
功能描述： 分页获取工件信息列表
请求参数：
skip: 跳过的记录数（默认0）limit: 返回的记录数（默认100，最大1000）
响应数据：
[
{
"wp_id": "WP001",
// ... 其他字段
}
]
参考文件：
4. 更新工件信息
接口路径： PUT /workpiece-info/{wp_id}
功能描述： 根据wp_id更新工件信息
请求参数：
wp_id: 工件ID（路径参数）- 更新数据（部分字段可选）
响应数据： 更新后的工件信息
参考文件：
5. 删除工件信息
接口路径： DELETE /workpiece-info/{wp_id}
功能描述： 根据wp_id删除工件信息
请求参数：
wp_id: 工件ID（路径参数）
响应数据： 无
状态码：
- 200: 删除成功
- 404: 工件信息不存在
参考文件：
6. 搜索工件信息
接口路径： GET /workpiece-info/search/by-code
功能描述： 根据防火板代号模糊搜索工件信息
请求参数：
code: 防火板代号（查询参数）
响应数据： 匹配的工件信息列表
参考文件：
数据流图
工件创建流程
sequenceDiagram
participant Client as 客户端
participant Router as WorkpieceRouter
participant Service as WorkpieceService
participant Model as Workpiece
participant DB as PostgreSQL
Client->>Router: POST /workpiece/
Router->>Service: service_create_workpiece()
Service->>Model: Workpiece.create()
Model->>DB: INSERT INTO workpieces
DB-->>Model: 返回新记录
Model-->>Service: 返回Workpiece对象
Service-->>Router: 返回工件数据
Router-->>Client: 201 Created
工件信息查询流程
sequenceDiagram
participant Client as 客户端
participant Router as WorkpieceInfoRouter
participant Service as WorkpieceInfoService
participant Model as WorkpieceInfo
participant DB as MongoDB
Client->>Router: GET /workpiece-info/{wp_id}
Router->>Service: service_get_workpiece_info_by_wp_id(wp_id)
Service->>Model: WorkpieceInfo.find_one({"wp_id": wp_id})
Model->>DB: db.workpiece_info.findOne({wp_id: wp_id})
DB-->>Model: 返回文档
Model-->>Service: 返回WorkpieceInfo对象
Service-->>Router: 返回工件信息
Router-->>Client: 200 OK
依赖关系分析
模块依赖图
flowchart TD
A[workpiece_router.py] --> B[workpiece_service.py]
A --> C[access_log_service.py]
A --> D[authorize.py]
E[workpiece_info_router.py] --> F[workpiece_info_service.py]
E --> C
E --> D
B --> G[workpiece.py]
F --> H[mg_workpiece_info.py]
G --> I[PostgreSQL]
H --> J[MongoDB]
style A fill:#e1f5fe
style E fill:#e1f5fe
style B fill:#f3e5f5
style F fill:#f3e5f5
style G fill:#e8f5e8
style H fill:#e8f5e8
服务层依赖关系
工件服务层依赖：
- 依赖模型：Workpiece
- 依赖数据库：PostgreSQL
- 异常处理：HTTPException, DoesNotExist, IntegrityError
工件信息服务层依赖：
- 依赖模型：WorkpieceInfo
- 依赖数据库：MongoDB
- 异常处理：HTTPException, bson.ObjectId
错误处理机制
统一错误处理
系统采用统一的错误处理机制，所有接口都包含完整的异常处理：
- 业务逻辑错误：返回400状态码，包含具体错误信息
- 资源不存在：返回404状态码
- 服务器内部错误：返回500状态码，记录详细日志
- 数据库约束错误：处理唯一性约束等数据库级错误
访问日志记录
所有接口调用都会自动记录访问日志，包括：
- 操作类型和标题
- 操作用户
- 相关工件和工单
- 操作时间戳
参考文件：
安全机制
JWT身份验证
所有工件管理接口都需要JWT令牌验证，确保只有授权用户才能访问。
验证流程：
- 客户端在请求头中包含Authorization: Bearer {token}
- 系统验证token的有效性
- 验证通过后，将用户信息存储在请求上下文中
参考文件：
性能优化建议
数据库优化
-
索引优化：为常用查询字段创建索引
- Workpiece表的workpiece_id主键索引
- WorkpieceInfo表的wp_id唯一索引
- WorkpieceInfo表的wp_firestop_code搜索索引
-
查询优化：使用分页查询避免大数据量返回
-
连接池：配置数据库连接池提高并发性能
缓存策略
对于频繁查询但不经常变更的数据，可以考虑引入Redis缓存：
- 工件基本信息缓存
- 工件状态缓存
- 常用搜索条件缓存
索引
本文档详细记录了邮轮穿舱件管理系统后台的工件管理API接口，涵盖了工件基本信息管理和工件详细信息管理的完整功能。系统采用分层架构设计，实现了清晰的职责分离和完整的错误处理机制。所有接口都支持JWT身份验证和访问日志记录，确保了系统的安全性和可追溯性。
核心文件参考：
- 主应用文件：main.py
- 工件路由器：workpiece_router.py
- 工件信息路由器：workpiece_info_router.py
- 工件服务：workpiece_service.py
- 工件信息服务：workpiece_info_service.py
- 数据模型：workpiece.py, mg_workpiece_info.py
- 数据模式：workpiece_info_schema.py