feat(ops): update cleaner status and assignment logic

2026-01-19 14:56:31 +08:00
parent 73bc3b299f
commit b71558ae07
169 changed files with 57972 additions and 162 deletions
--- a/.qoder/repowiki/zh/content/API接口文档/业务模块API/ERP企业资源计划API.md
+++ b/.qoder/repowiki/zh/content/API接口文档/业务模块API/ERP企业资源计划API.md
@@ -0,0 +1,412 @@
+# ERP企业资源计划API
+
+<cite>
+**本文档引用的文件**
+- [ErpServerApplication.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/ErpServerApplication.java)
+- [application.yaml](file://viewsh-module-erp/viewsh-module-erp-server/src/main/resources/application.yaml)
+- [ApiConstants.java](file://viewsh-module-erp/viewsh-module-erp-api/src/main/java/com/viewsh/module/erp/enums/ApiConstants.java)
+- [ErrorCodeConstants.java](file://viewsh-module-erp/viewsh-module-erp-api/src/main/java/com/viewsh/module/erp/enums/ErrorCodeConstants.java)
+- [ErpAuditStatus.java](file://viewsh-module-erp/viewsh-module-erp-api/src/main/java/com/viewsh/module/erp/enums/ErpAuditStatus.java)
+- [ErpPurchaseOrderController.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/purchase/ErpPurchaseOrderController.java)
+- [ErpSaleOrderController.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/sale/ErpSaleOrderController.java)
+- [ErpStockController.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/stock/ErpStockController.java)
+- [ErpAccountController.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/finance/ErpAccountController.java)
+- [ErpPurchaseOrderServiceImpl.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/service/purchase/ErpPurchaseOrderServiceImpl.java)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+
+## 简介
+本文件为ERP企业资源计划模块的全面API接口文档，覆盖采购管理、销售管理、库存管理、财务管理等核心业务的RESTful API接口。文档详细记录了采购订单管理接口（包括采购入库、退货处理、供应商管理）、销售管理接口（销售出库、订单处理、客户管理）、库存管理接口（库存盘点、移库操作、库存调整）、财务管理系统接口（账户管理、收付款处理、财务报表），并说明业务流程接口（采购到付款、销售到收款的完整流程）。同时，文档包含数据验证规则、权限控制和业务规则约束，以及各模块间的数据流转接口和集成方案。
+
+## 项目结构
+ERP模块采用标准的分层架构，包含API定义层、服务实现层、数据访问层和控制器层。模块启动类位于server包，配置文件位于resources目录，API常量和错误码定义在api包，控制器、服务和数据对象分别位于controller、service、dal包中。
+
+```mermaid
+graph TB
+subgraph "ERP模块结构"
+A[启动类 ErpServerApplication] --> B[配置文件 application.yaml]
+C[API常量 ApiConstants] --> D[错误码定义 ErrorCodeConstants]
+E[审核状态 ErpAuditStatus] --> F[控制器层]
+G[服务实现层] --> H[数据访问层]
+F --> G
+G --> H
+end
+```
+
+**图表来源**
+- [ErpServerApplication.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/ErpServerApplication.java#L1-L31)
+- [application.yaml](file://viewsh-module-erp/viewsh-module-erp-server/src/main/resources/application.yaml#L1-L125)
+
+**章节来源**
+- [ErpServerApplication.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/ErpServerApplication.java#L1-L31)
+- [application.yaml](file://viewsh-module-erp/viewsh-module-erp-server/src/main/resources/application.yaml#L1-L125)
+
+## 核心组件
+ERP模块的核心组件包括：
+- API常量：定义服务名、API前缀和版本号
+- 错误码定义：统一管理各模块的错误码
+- 审核状态枚举：定义审核状态（未审核、已审核）
+- 控制器层：提供RESTful API接口
+- 服务实现层：处理业务逻辑和数据验证
+- 数据访问层：提供数据库操作接口
+
+**章节来源**
+- [ApiConstants.java](file://viewsh-module-erp/viewsh-module-erp-api/src/main/java/com/viewsh/module/erp/enums/ApiConstants.java#L1-L24)
+- [ErrorCodeConstants.java](file://viewsh-module-erp/viewsh-module-erp-api/src/main/java/com/viewsh/module/erp/enums/ErrorCodeConstants.java#L1-L169)
+- [ErpAuditStatus.java](file://viewsh-module-erp/viewsh-module-erp-api/src/main/java/com/viewsh/module/erp/enums/ErpAuditStatus.java#L1-L40)
+
+## 架构概览
+ERP模块采用分层架构，控制器负责接收HTTP请求，服务层处理业务逻辑，数据访问层负责数据库操作。模块通过权限注解进行权限控制，通过Swagger提供API文档。
+
+```mermaid
+graph TB
+subgraph "API层"
+A[采购订单控制器]
+B[销售订单控制器]
+C[库存控制器]
+D[账户控制器]
+end
+subgraph "服务层"
+E[采购订单服务实现]
+F[销售订单服务实现]
+G[库存服务实现]
+H[账户服务实现]
+end
+subgraph "数据访问层"
+I[采购订单Mapper]
+J[销售订单Mapper]
+K[库存Mapper]
+L[账户Mapper]
+end
+A --> E
+B --> F
+C --> G
+D --> H
+E --> I
+F --> J
+G --> K
+H --> L
+```
+
+**图表来源**
+- [ErpPurchaseOrderController.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/purchase/ErpPurchaseOrderController.java#L1-L164)
+- [ErpSaleOrderController.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/sale/ErpSaleOrderController.java#L1-L164)
+- [ErpStockController.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/stock/ErpStockController.java#L1-L112)
+- [ErpAccountController.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/finance/ErpAccountController.java#L1-L116)
+
+## 详细组件分析
+
+### 采购管理API
+
+#### 采购订单管理接口
+采购订单管理提供完整的采购订单生命周期管理，包括创建、更新、状态更新、删除、查询和导出功能。
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant Controller as "采购订单控制器"
+participant Service as "采购订单服务实现"
+participant Mapper as "采购订单Mapper"
+participant Redis as "Redis生成单号"
+Client->>Controller : POST /erp/purchase-order/create
+Controller->>Service : createPurchaseOrder(reqVO)
+Service->>Redis : generate(采购订单号前缀)
+Redis-->>Service : 返回单号
+Service->>Service : 校验供应商和结算账户
+Service->>Service : 校验订单项有效性
+Service->>Service : 计算总价
+Service->>Mapper : insert(订单)
+Service->>Mapper : insertBatch(订单项)
+Mapper-->>Service : 返回订单ID
+Service-->>Controller : 返回订单ID
+Controller-->>Client : 成功响应
+```
+
+**图表来源**
+- [ErpPurchaseOrderController.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/purchase/ErpPurchaseOrderController.java#L62-L67)
+- [ErpPurchaseOrderServiceImpl.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/service/purchase/ErpPurchaseOrderServiceImpl.java#L62-L86)
+
+主要接口包括：
+- 创建采购订单：POST /erp/purchase-order/create
+- 更新采购订单：PUT /erp/purchase-order/update
+- 更新采购订单状态：PUT /erp/purchase-order/update-status
+- 删除采购订单：DELETE /erp/purchase-order/delete
+- 获取采购订单：GET /erp/purchase-order/get
+- 采购订单分页查询：GET /erp/purchase-order/page
+- 导出采购订单：GET /erp/purchase-order/export-excel
+
+**章节来源**
+- [ErpPurchaseOrderController.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/purchase/ErpPurchaseOrderController.java#L62-L134)
+- [ErpPurchaseOrderServiceImpl.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/service/purchase/ErpPurchaseOrderServiceImpl.java#L62-L200)
+
+#### 采购入库接口
+采购入库接口用于处理采购货物的入库操作，包括入库单的创建、更新、状态管理和查询功能。
+
+```mermaid
+flowchart TD
+Start([开始入库流程]) --> ValidateOrder["校验采购订单存在性"]
+ValidateOrder --> CheckApprove{"是否已审核？"}
+CheckApprove --> |否| ErrorApprove["抛出未审核错误"]
+CheckApprove --> |是| ValidateStock["校验库存数量"]
+ValidateStock --> StockEnough{"库存是否充足？"}
+StockEnough --> |否| ErrorStock["抛出库存不足错误"]
+StockEnough --> |是| CreateInOrder["创建入库单"]
+CreateInOrder --> UpdateOrder["更新采购订单入库数量"]
+UpdateOrder --> UpdateStock["更新库存数量"]
+UpdateStock --> ApproveIn["审核入库单"]
+ApproveIn --> End([完成入库])
+ErrorApprove --> End
+ErrorStock --> End
+```
+
+**图表来源**
+- [ErpPurchaseOrderServiceImpl.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/service/purchase/ErpPurchaseOrderServiceImpl.java#L190-L296)
+
+#### 供应商管理接口
+供应商管理接口提供供应商的增删改查、状态管理和查询功能，支持供应商的启用/停用操作。
+
+**章节来源**
+- [ErrorCodeConstants.java](file://viewsh-module-erp/viewsh-module-erp-api/src/main/java/com/viewsh/module/erp/enums/ErrorCodeConstants.java#L12-L28)
+
+### 销售管理API
+
+#### 销售订单管理接口
+销售订单管理提供完整的销售订单生命周期管理，包括创建、更新、状态更新、删除、查询和导出功能。
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant Controller as "销售订单控制器"
+participant Service as "销售订单服务实现"
+participant Mapper as "销售订单Mapper"
+participant Redis as "Redis生成单号"
+Client->>Controller : POST /erp/sale-order/create
+Controller->>Service : createSaleOrder(reqVO)
+Service->>Redis : generate(销售订单号前缀)
+Redis-->>Service : 返回单号
+Service->>Service : 校验客户和结算账户
+Service->>Service : 校验订单项有效性
+Service->>Service : 计算总价
+Service->>Mapper : insert(订单)
+Service->>Mapper : insertBatch(订单项)
+Mapper-->>Service : 返回订单ID
+Service-->>Controller : 返回订单ID
+Controller-->>Client : 成功响应
+```
+
+**图表来源**
+- [ErpSaleOrderController.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/sale/ErpSaleOrderController.java#L62-L67)
+
+主要接口包括：
+- 创建销售订单：POST /erp/sale-order/create
+- 更新销售订单：PUT /erp/sale-order/update
+- 更新销售订单状态：PUT /erp/sale-order/update-status
+- 删除销售订单：DELETE /erp/sale-order/delete
+- 获取销售订单：GET /erp/sale-order/get
+- 销售订单分页查询：GET /erp/sale-order/page
+- 导出销售订单：GET /erp/sale-order/export-excel
+
+**章节来源**
+- [ErpSaleOrderController.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/sale/ErpSaleOrderController.java#L62-L134)
+
+#### 销售出库接口
+销售出库接口用于处理销售货物的出库操作，包括出库单的创建、更新、状态管理和查询功能。
+
+**章节来源**
+- [ErrorCodeConstants.java](file://viewsh-module-erp/viewsh-module-erp-api/src/main/java/com/viewsh/module/erp/enums/ErrorCodeConstants.java#L68-L78)
+
+#### 客户管理接口
+客户管理接口提供客户的增删改查、状态管理和查询功能，支持客户的启用/停用操作。
+
+**章节来源**
+- [ErrorCodeConstants.java](file://viewsh-module-erp/viewsh-module-erp-api/src/main/java/com/viewsh/module/erp/enums/ErrorCodeConstants.java#L51-L54)
+
+### 库存管理API
+
+#### 库存查询接口
+库存查询接口提供产品库存的查询和分页功能，支持按产品和仓库维度查询库存数量。
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant Controller as "库存控制器"
+participant Service as "库存服务实现"
+participant Mapper as "库存Mapper"
+Client->>Controller : GET /erp/stock/get
+Controller->>Service : getStock(productId, warehouseId)
+Service->>Mapper : selectOne(条件查询)
+Mapper-->>Service : 返回库存记录
+Service-->>Controller : 返回库存VO
+Controller-->>Client : 成功响应
+```
+
+**图表来源**
+- [ErpStockController.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/stock/ErpStockController.java#L63-L68)
+
+主要接口包括：
+- 获取产品库存：GET /erp/stock/get
+- 获取产品库存数量：GET /erp/stock/get-count
+- 产品库存分页查询：GET /erp/stock/page
+- 导出产品库存：GET /erp/stock/export-excel
+
+**章节来源**
+- [ErpStockController.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/stock/ErpStockController.java#L55-L95)
+
+#### 库存盘点接口
+库存盘点接口用于处理库存盘点操作，支持盘点单的创建、更新、状态管理和查询功能。
+
+**章节来源**
+- [ErrorCodeConstants.java](file://viewsh-module-erp/viewsh-module-erp-api/src/main/java/com/viewsh/module/erp/enums/ErrorCodeConstants.java#L118-L125)
+
+#### 库存调拨接口
+库存调拨接口用于处理库存在不同仓库间的调拨操作，支持调拨单的创建、更新、状态管理和查询功能。
+
+**章节来源**
+- [ErrorCodeConstants.java](file://viewsh-module-erp/viewsh-module-erp-api/src/main/java/com/viewsh/module/erp/enums/ErrorCodeConstants.java#L110-L117)
+
+### 财务管理API
+
+#### 账户管理接口
+账户管理接口提供结算账户的增删改查、状态管理和查询功能，支持账户的启用/停用和默认状态设置。
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant Controller as "账户控制器"
+participant Service as "账户服务实现"
+participant Mapper as "账户Mapper"
+Client->>Controller : POST /erp/account/create
+Controller->>Service : createAccount(reqVO)
+Service->>Service : 校验账户状态
+Service->>Mapper : insert(账户)
+Mapper-->>Service : 返回账户ID
+Service-->>Controller : 返回账户ID
+Controller-->>Client : 成功响应
+```
+
+**图表来源**
+- [ErpAccountController.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/finance/ErpAccountController.java#L42-L47)
+
+主要接口包括：
+- 创建结算账户：POST /erp/account/create
+- 更新结算账户：PUT /erp/account/update
+- 更新结算账户默认状态：PUT /erp/account/update-default-status
+- 删除结算账户：DELETE /erp/account/delete
+- 获取结算账户：GET /erp/account/get
+- 获取结算账户精简列表：GET /erp/account/simple-list
+- 结算账户分页查询：GET /erp/account/page
+- 导出结算账户：GET /erp/account/export-excel
+
+**章节来源**
+- [ErpAccountController.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/finance/ErpAccountController.java#L42-L116)
+
+#### 收付款处理接口
+收付款处理接口提供收款单和付款单的管理功能，支持收付款单的创建、更新、状态管理和查询功能。
+
+**章节来源**
+- [ErrorCodeConstants.java](file://viewsh-module-erp/viewsh-module-erp-api/src/main/java/com/viewsh/module/erp/enums/ErrorCodeConstants.java#L152-L167)
+
+### 业务流程接口
+
+#### 采购到付款流程
+采购到付款流程涵盖了从采购订单创建到付款完成的完整业务流程，包括采购入库、采购退货、付款处理等环节。
+
+```mermaid
+flowchart TD
+PurchaseOrder[采购订单] --> PurchaseIn[采购入库]
+PurchaseIn --> Payment[付款处理]
+PurchaseOrder --> PurchaseReturn[采购退货]
+PurchaseReturn --> Refund[退款处理]
+Payment --> FinancialReport[财务报表]
+Refund --> FinancialReport
+PurchaseIn --> Inventory[库存更新]
+PurchaseReturn --> Inventory
+```
+
+#### 销售到收款流程
+销售到收款流程涵盖了从销售订单创建到收款完成的完整业务流程，包括销售出库、销售退货、收款处理等环节。
+
+```mermaid
+flowchart TD
+SaleOrder[销售订单] --> SaleOut[销售出库]
+SaleOut --> Receipt[收款处理]
+SaleOrder --> SaleReturn[销售退货]
+SaleReturn --> Refund[退款处理]
+Receipt --> FinancialReport[财务报表]
+Refund --> FinancialReport
+SaleOut --> Inventory[库存更新]
+SaleReturn --> Inventory
+```
+
+## 依赖关系分析
+ERP模块的依赖关系清晰，控制器层依赖服务层，服务层依赖数据访问层。模块通过权限注解实现权限控制，通过Swagger提供API文档。
+
+```mermaid
+graph TB
+subgraph "外部依赖"
+A[Spring Security]
+B[Swagger/OpenAPI]
+C[MyBatis Plus]
+D[Redis]
+end
+subgraph "内部模块"
+E[控制器层]
+F[服务层]
+G[数据访问层]
+H[数据模型层]
+end
+A --> E
+B --> E
+C --> G
+D --> F
+E --> F
+F --> G
+G --> H
+```
+
+**图表来源**
+- [application.yaml](file://viewsh-module-erp/viewsh-module-erp-server/src/main/resources/application.yaml#L45-L58)
+- [application.yaml](file://viewsh-module-erp/viewsh-module-erp-server/src/main/resources/application.yaml#L61-L80)
+
+**章节来源**
+- [application.yaml](file://viewsh-module-erp/viewsh-module-erp-server/src/main/resources/application.yaml#L45-L125)
+
+## 性能考虑
+ERP模块在性能方面采用了多项优化措施：
+- 缓存策略：使用Redis缓存热点数据，提高查询性能
+- 分页查询：所有列表查询都支持分页，避免大数据量查询
+- 批量操作：订单项的增删改采用批量操作，减少数据库交互
+- 权限控制：通过注解实现细粒度的权限控制，避免不必要的数据查询
+- Swagger集成：提供API文档，便于前端开发和调试
+
+## 故障排除指南
+ERP模块的错误码定义统一规范，便于问题定位和解决：
+
+### 常见错误类型
+- 供应商相关错误：供应商不存在、供应商未启用
+- 订单相关错误：订单不存在、订单已审核无法修改、反审核失败
+- 库存相关错误：库存不足、库存数量为负数
+- 财务相关错误：账户不存在、账户未启用
+
+### 排错步骤
+1. 检查请求参数是否正确
+2. 验证用户权限是否足够
+3. 查看相关单据状态是否符合业务要求
+4. 检查库存数量是否充足
+5. 确认财务账户状态正常
+
+**章节来源**
+- [ErrorCodeConstants.java](file://viewsh-module-erp/viewsh-module-erp-api/src/main/java/com/viewsh/module/erp/enums/ErrorCodeConstants.java#L1-L169)
+
+## 结论
+ERP企业资源计划模块提供了完整的API接口体系，涵盖了采购、销售、库存、财务等核心业务领域。模块采用分层架构设计，具有良好的可扩展性和维护性。通过统一的错误码定义、权限控制和业务规则约束，确保了系统的稳定性和可靠性。建议在实际使用中结合具体业务场景，合理配置参数和权限，确保系统能够满足企业的业务需求。