382 lines
28 KiB
Markdown
382 lines
28 KiB
Markdown
|
# 业务模块API
|
|||
|
|
|
|||
|
|
<cite>
|
|||
|
|
**本文引用的文件**
|
|||
|
|
- [docs/technical-overview/07-接口文档.md](file://docs/technical-overview/07-接口文档.md)
|
|||
|
|
- [viewsh-module-crm/viewsh-module-crm-api/src/main/java/com/viewsh/module/crm/enums/ApiConstants.java](file://viewsh-module-crm/viewsh-module-crm-api/src/main/java/com/viewsh/module/crm/enums/ApiConstants.java)
|
|||
|
|
- [viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/customer/CrmCustomerController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/customer/CrmCustomerController.java)
|
|||
|
|
- [viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/business/CrmBusinessController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/business/CrmBusinessController.java)
|
|||
|
|
- [viewsh-module-erp/viewsh-module-erp-api/src/main/java/com/viewsh/module/erp/enums/ApiConstants.java](file://viewsh-module-erp/viewsh-module-erp-api/src/main/java/com/viewsh/module/erp/enums/ApiConstants.java)
|
|||
|
|
- [viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/stock/ErpStockController.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/stock/ErpStockController.java)
|
|||
|
|
- [viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/package-info.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/package-info.java)
|
|||
|
|
- [viewsh-module-mall/viewsh-module-product-server/src/main/java/com/viewsh/module/product/controller/admin/category/ProductCategoryController.java](file://viewsh-module-mall/viewsh-module-product-server/src/main/java/com/viewsh/module/product/controller/admin/category/ProductCategoryController.java)
|
|||
|
|
- [viewsh-module-mall/viewsh-module-trade-api/src/main/java/com/viewsh/module/trade/enums/ApiConstants.java](file://viewsh-module-mall/viewsh-module-trade-api/src/main/java/com/viewsh/module/trade/enums/ApiConstants.java)
|
|||
|
|
- [viewsh-module-mall/viewsh-module-trade-server/src/main/java/com/viewsh/module/trade/controller/admin/order/TradeOrderController.java](file://viewsh-module-mall/viewsh-module-trade-server/src/main/java/com/viewsh/module/trade/controller/admin/order/TradeOrderController.java)
|
|||
|
|
- [viewsh-module-mall/viewsh-module-trade-server/src/main/java/com/viewsh/module/trade/controller/admin/brokerage/BrokerageWithdrawController.java](file://viewsh-module-mall/viewsh-module-trade-server/src/main/java/com/viewsh/module/trade/controller/admin/brokerage/BrokerageWithdrawController.java)
|
|||
|
|
- [viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/enums/ApiConstants.java](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/enums/ApiConstants.java)
|
|||
|
|
- [viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/app/PayAppController.java](file://viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/app/PayAppController.java)
|
|||
|
|
- [viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/channel/PayChannelController.java](file://viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/channel/PayChannelController.java)
|
|||
|
|
- [viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/order/PayOrderController.java](file://viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/order/PayOrderController.java)
|
|||
|
|
- [viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/notify/PayNotifyController.java](file://viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/notify/PayNotifyController.java)
|
|||
|
|
- [viewsh-server/src/main/java/com/viewsh/server/controller/DefaultController.java](file://viewsh-server/src/main/java/com/viewsh/server/controller/DefaultController.java)
|
|||
|
|
- [viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/web/core/handler/GlobalExceptionHandler.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/web/core/handler/GlobalExceptionHandler.java)
|
|||
|
|
</cite>
|
|||
|
|
|
|||
|
|
## 目录
|
|||
|
|
1. [简介](#简介)
|
|||
|
|
2. [项目结构](#项目结构)
|
|||
|
|
3. [核心组件](#核心组件)
|
|||
|
|
4. [架构总览](#架构总览)
|
|||
|
|
5. [详细组件分析](#详细组件分析)
|
|||
|
|
6. [依赖分析](#依赖分析)
|
|||
|
|
7. [性能考虑](#性能考虑)
|
|||
|
|
8. [故障排查指南](#故障排查指南)
|
|||
|
|
9. [结论](#结论)
|
|||
|
|
10. [附录](#附录)
|
|||
|
|
|
|||
|
|
## 简介
|
|||
|
|
本文件面向各业务模块的RESTful API接口文档，覆盖以下核心业务域：
|
|||
|
|
- CRM 客户关系管理：客户与商机的增删改查、成交状态变更、公海池流转、导入导出等。
|
|||
|
|
- ERP 企业资源计划：产品库存的查询、库存数量统计、导出等。
|
|||
|
|
- 商城业务：商品分类、交易订单、佣金提现等管理后台接口。
|
|||
|
|
- 支付管理：应用信息、支付渠道、支付订单、回调通知等。
|
|||
|
|
|
|||
|
|
文档说明各模块的业务对象接口、业务流程接口与状态变更接口，阐述业务数据关联关系与一致性保障机制，提供关键业务场景（如订单创建、支付处理、库存管理）的接口调用序列，并给出业务规则验证与异常处理机制，以及模块间协作规范与数据交换格式。
|
|||
|
|
|
|||
|
|
## 项目结构
|
|||
|
|
- 后端采用多模块微服务架构，各业务模块独立成服务，统一通过网关进行路由与文档聚合。
|
|||
|
|
- 接口规范遵循RESTful风格，响应体统一为业务结果包装，HTTP状态码与业务错误码分离。
|
|||
|
|
- 网关层负责将/admin-api与/app-api前缀的请求转发至对应服务；Knife4j实现接口文档的自动生成与聚合。
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
graph TB
|
|||
|
|
GW["网关 Gateway<br/>路由与聚合"] --> CRM["CRM 服务"]
|
|||
|
|
GW --> ERP["ERP 服务"]
|
|||
|
|
GW --> MALL["商城服务"]
|
|||
|
|
GW --> PAY["支付服务"]
|
|||
|
|
subgraph "接口规范"
|
|||
|
|
REST["RESTful 规范<br/>统一响应体"]
|
|||
|
|
DOC["Knife4j 聚合文档"]
|
|||
|
|
end
|
|||
|
|
GW --> REST
|
|||
|
|
GW --> DOC
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
图表来源
|
|||
|
|
- [docs/technical-overview/07-接口文档.md](file://docs/technical-overview/07-接口文档.md#L61-L73)
|
|||
|
|
- [docs/technical-overview/07-接口文档.md](file://docs/technical-overview/07-接口文档.md#L45-L58)
|
|||
|
|
|
|||
|
|
章节来源
|
|||
|
|
- [docs/technical-overview/07-接口文档.md](file://docs/technical-overview/07-接口文档.md#L5-L73)
|
|||
|
|
|
|||
|
|
## 核心组件
|
|||
|
|
- 统一响应体与错误码
|
|||
|
|
- 响应体包含业务状态码与消息，HTTP状态码仅标识网络层状态。
|
|||
|
|
- 常见错误码：成功、参数校验失败、未登录/Token过期、无权限、限流、服务器内部错误及各模块业务错误码区间。
|
|||
|
|
- 网关路由与前缀
|
|||
|
|
- /admin-api/** 路由到对应业务服务（如 /admin-api/crm/** -> crm-server）。
|
|||
|
|
- /app-api/** 路由到系统服务（移动端接口复用）。
|
|||
|
|
- 文档聚合
|
|||
|
|
- Knife4j 自动聚合各服务Swagger文档，统一入口 http://{gateway-ip}:48080/doc.html。
|
|||
|
|
|
|||
|
|
章节来源
|
|||
|
|
- [docs/technical-overview/07-接口文档.md](file://docs/technical-overview/07-接口文档.md#L17-L42)
|
|||
|
|
- [docs/technical-overview/07-接口文档.md](file://docs/technical-overview/07-接口文档.md#L61-L73)
|
|||
|
|
- [docs/technical-overview/07-接口文档.md](file://docs/technical-overview/07-接口文档.md#L45-L58)
|
|||
|
|
|
|||
|
|
## 架构总览
|
|||
|
|
- 模块命名与前缀
|
|||
|
|
- CRM/ERP/Trade/Pay 模块各自定义服务名、API前缀与版本常量，确保与服务名一致。
|
|||
|
|
- 默认路由占位
|
|||
|
|
- 当某模块未启用时，网关对相应/admin-api前缀返回“未实现”提示，便于识别模块启用状态。
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
graph TB
|
|||
|
|
AC["/admin-api/crm/**"] --> CRM["crm-server"]
|
|||
|
|
AE["/admin-api/erp/**"] --> ERP["erp-server"]
|
|||
|
|
AT["/admin-api/trade/**"] --> TRADE["trade-server"]
|
|||
|
|
AP["/admin-api/pay/**"] --> PAY["pay-server"]
|
|||
|
|
subgraph "默认占位响应"
|
|||
|
|
D404["/admin-api/product/**"] --> P404["商城模块未启用"]
|
|||
|
|
D404_2["/admin-api/report/**"] --> R404["报表模块未启用"]
|
|||
|
|
D404_3["/admin-api/pay/**"] --> Y404["支付模块未启用"]
|
|||
|
|
end
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
图表来源
|
|||
|
|
- [viewsh-module-crm/viewsh-module-crm-api/src/main/java/com/viewsh/module/crm/enums/ApiConstants.java](file://viewsh-module-crm/viewsh-module-crm-api/src/main/java/com/viewsh/module/crm/enums/ApiConstants.java#L17-L21)
|
|||
|
|
- [viewsh-module-erp/viewsh-module-erp-api/src/main/java/com/viewsh/module/erp/enums/ApiConstants.java](file://viewsh-module-erp/viewsh-module-erp-api/src/main/java/com/viewsh/module/erp/enums/ApiConstants.java#L17-L21)
|
|||
|
|
- [viewsh-module-mall/viewsh-module-trade-api/src/main/java/com/viewsh/module/trade/enums/ApiConstants.java](file://viewsh-module-mall/viewsh-module-trade-api/src/main/java/com/viewsh/module/trade/enums/ApiConstants.java#L17-L21)
|
|||
|
|
- [viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/enums/ApiConstants.java](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/enums/ApiConstants.java#L17-L21)
|
|||
|
|
- [viewsh-server/src/main/java/com/viewsh/server/controller/DefaultController.java](file://viewsh-server/src/main/java/com/viewsh/server/controller/DefaultController.java#L35-L63)
|
|||
|
|
|
|||
|
|
章节来源
|
|||
|
|
- [viewsh-module-crm/viewsh-module-crm-api/src/main/java/com/viewsh/module/crm/enums/ApiConstants.java](file://viewsh-module-crm/viewsh-module-crm-api/src/main/java/com/viewsh/module/crm/enums/ApiConstants.java#L10-L23)
|
|||
|
|
- [viewsh-module-erp/viewsh-module-erp-api/src/main/java/com/viewsh/module/erp/enums/ApiConstants.java](file://viewsh-module-erp/viewsh-module-erp-api/src/main/java/com/viewsh/module/erp/enums/ApiConstants.java#L10-L23)
|
|||
|
|
- [viewsh-module-mall/viewsh-module-trade-api/src/main/java/com/viewsh/module/trade/enums/ApiConstants.java](file://viewsh-module-mall/viewsh-module-trade-api/src/main/java/com/viewsh/module/trade/enums/ApiConstants.java#L10-L23)
|
|||
|
|
- [viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/enums/ApiConstants.java](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/enums/ApiConstants.java#L10-L23)
|
|||
|
|
- [viewsh-server/src/main/java/com/viewsh/server/controller/DefaultController.java](file://viewsh-server/src/main/java/com/viewsh/server/controller/DefaultController.java#L35-L63)
|
|||
|
|
|
|||
|
|
## 详细组件分析
|
|||
|
|
|
|||
|
|
### CRM 客户关系管理
|
|||
|
|
- 服务名与前缀
|
|||
|
|
- 服务名：crm-server
|
|||
|
|
- API 前缀：/crm
|
|||
|
|
- 版本：1.0.0
|
|||
|
|
- 核心接口
|
|||
|
|
- 客户
|
|||
|
|
- POST /crm/customer/create：创建客户
|
|||
|
|
- PUT /crm/customer/update：更新客户
|
|||
|
|
- PUT /crm/customer/update-deal-status：更新成交状态
|
|||
|
|
- DELETE /crm/customer/delete：删除客户
|
|||
|
|
- GET /crm/customer/get：获取客户详情
|
|||
|
|
- GET /crm/customer/page：客户分页
|
|||
|
|
- GET /crm/customer/simple-list：精简列表（仅含id/name）
|
|||
|
|
- GET /crm/customer/export-excel：导出客户Excel
|
|||
|
|
- POST /crm/customer/import：导入客户
|
|||
|
|
- PUT /crm/customer/transfer：客户转移
|
|||
|
|
- PUT /crm/customer/lock：锁定/解锁客户
|
|||
|
|
- PUT /crm/customer/put-pool：放入公海
|
|||
|
|
- PUT /crm/customer/receive：领取公海客户
|
|||
|
|
- PUT /crm/customer/distribute：分配公海给负责人
|
|||
|
|
- 商机
|
|||
|
|
- POST /crm/business/create：创建商机
|
|||
|
|
- PUT /crm/business/update：更新商机
|
|||
|
|
- PUT /crm/business/update-status：更新商机状态
|
|||
|
|
- DELETE /crm/business/delete：删除商机
|
|||
|
|
- GET /crm/business/get：获取商机详情
|
|||
|
|
- GET /crm/business/page：商机分页
|
|||
|
|
- GET /crm/business/page-by-customer：按客户分页
|
|||
|
|
- GET /crm/business/page-by-contact：按联系人分页
|
|||
|
|
- GET /crm/business/export-excel：导出商机Excel
|
|||
|
|
- GET /crm/business/simple-all-list：商机精简列表
|
|||
|
|
- 关联关系与一致性
|
|||
|
|
- 客户与部门、管理员用户关联，详情构建时拼接创建人、负责人及其部门名称。
|
|||
|
|
- 商机与客户、产品、状态类型/状态关联，详情构建时拼接客户名称与产品明细。
|
|||
|
|
- 公海池逻辑：当客户未成交且未锁定，依据“成交到期天数”和“最后联系到期天数”计算剩余天数，决定是否进入公海。
|
|||
|
|
- 业务流程接口序列（示例：客户导入）
|
|||
|
|
- 步骤1：上传导入模板（GET /crm/customer/get-import-template）
|
|||
|
|
- 步骤2：提交Excel导入（POST /crm/customer/import）
|
|||
|
|
- 步骤3：查看导入结果（导入返回值包含统计信息）
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
sequenceDiagram
|
|||
|
|
participant C as "客户端"
|
|||
|
|
participant G as "网关"
|
|||
|
|
participant S as "CRM 服务"
|
|||
|
|
participant U as "用户/部门服务"
|
|||
|
|
C->>G : GET /crm/customer/get-import-template
|
|||
|
|
G->>S : 转发请求
|
|||
|
|
S-->>C : 返回导入模板
|
|||
|
|
C->>G : POST /crm/customer/import {file}
|
|||
|
|
G->>S : 转发请求
|
|||
|
|
S->>U : 校验导入数据关联对象
|
|||
|
|
S-->>C : 返回导入结果统计/明细
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
图表来源
|
|||
|
|
- [viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/customer/CrmCustomerController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/customer/CrmCustomerController.java#L247-L270)
|
|||
|
|
|
|||
|
|
章节来源
|
|||
|
|
- [viewsh-module-crm/viewsh-module-crm-api/src/main/java/com/viewsh/module/crm/enums/ApiConstants.java](file://viewsh-module-crm/viewsh-module-crm-api/src/main/java/com/viewsh/module/crm/enums/ApiConstants.java#L17-L21)
|
|||
|
|
- [viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/customer/CrmCustomerController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/customer/CrmCustomerController.java#L65-L316)
|
|||
|
|
- [viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/business/CrmBusinessController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/business/CrmBusinessController.java#L72-L200)
|
|||
|
|
|
|||
|
|
### ERP 企业资源计划
|
|||
|
|
- 服务名与前缀
|
|||
|
|
- 服务名：erp-server
|
|||
|
|
- API 前缀：/erp
|
|||
|
|
- 版本：1.0.0
|
|||
|
|
- 核心接口
|
|||
|
|
- 库存
|
|||
|
|
- GET /erp/stock/get：获取产品库存（支持按id或productId+warehouseId）
|
|||
|
|
- GET /erp/stock/get-count：获取产品库存数量
|
|||
|
|
- GET /erp/stock/page：产品库存分页
|
|||
|
|
- GET /erp/stock/export-excel：导出产品库存Excel
|
|||
|
|
- 关联关系与一致性
|
|||
|
|
- 库存详情构建时，拼接产品名称、分类、单位与仓库名称，确保展示一致。
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
flowchart TD
|
|||
|
|
Start(["请求 /erp/stock/get"]) --> CheckParams["校验参数<br/>id 或 (productId, warehouseId)"]
|
|||
|
|
CheckParams --> FetchStock["查询库存记录"]
|
|||
|
|
FetchStock --> BuildVO["拼接产品/仓库信息"]
|
|||
|
|
BuildVO --> Return["返回库存视图"]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
图表来源
|
|||
|
|
- [viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/stock/ErpStockController.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/stock/ErpStockController.java#L55-L68)
|
|||
|
|
|
|||
|
|
章节来源
|
|||
|
|
- [viewsh-module-erp/viewsh-module-erp-api/src/main/java/com/viewsh/module/erp/enums/ApiConstants.java](file://viewsh-module-erp/viewsh-module-erp-api/src/main/java/com/viewsh/module/erp/enums/ApiConstants.java#L17-L21)
|
|||
|
|
- [viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/stock/ErpStockController.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/stock/ErpStockController.java#L55-L112)
|
|||
|
|
|
|||
|
|
### 商城业务
|
|||
|
|
- 商品分类
|
|||
|
|
- POST /product/category/create：创建商品分类
|
|||
|
|
- PUT /product/category/update：更新商品分类
|
|||
|
|
- DELETE /product/category/delete：删除商品分类
|
|||
|
|
- GET /product/category/get：获取商品分类
|
|||
|
|
- GET /product/category/list：获取商品分类列表
|
|||
|
|
- 交易订单
|
|||
|
|
- GET /trade/order/page：订单分页
|
|||
|
|
- GET /trade/order/summary：订单统计
|
|||
|
|
- GET /trade/order/get-detail：订单详情
|
|||
|
|
- GET /trade/order/get-express-track-list：物流轨迹
|
|||
|
|
- PUT /trade/order/delivery：订单发货
|
|||
|
|
- PUT /trade/order/update-remark：订单备注
|
|||
|
|
- PUT /trade/order/update-price：订单调价
|
|||
|
|
- PUT /trade/order/update-address：修改收货地址
|
|||
|
|
- PUT /trade/order/pick-up-by-id：核销订单（按ID）
|
|||
|
|
- PUT /trade/order/pick-up-by-verify-code：核销订单（按核销码）
|
|||
|
|
- GET /trade/order/get-by-pick-up-verify-code：按核销码查询订单
|
|||
|
|
- 佣金提现
|
|||
|
|
- PUT /trade/brokerage-withdraw/approve：通过申请
|
|||
|
|
- PUT /trade/brokerage-withdraw/reject：驳回申请
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
sequenceDiagram
|
|||
|
|
participant C as "客户端"
|
|||
|
|
participant G as "网关"
|
|||
|
|
participant T as "交易服务"
|
|||
|
|
participant M as "会员服务"
|
|||
|
|
C->>G : GET /trade/order/page {filters}
|
|||
|
|
G->>T : 转发请求
|
|||
|
|
T->>M : 按用户ID批量查询用户信息
|
|||
|
|
T-->>C : 返回订单分页含用户昵称/分销员信息
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
图表来源
|
|||
|
|
- [viewsh-module-mall/viewsh-module-trade-server/src/main/java/com/viewsh/module/trade/controller/admin/order/TradeOrderController.java](file://viewsh-module-mall/viewsh-module-trade-server/src/main/java/com/viewsh/module/trade/controller/admin/order/TradeOrderController.java#L52-L71)
|
|||
|
|
|
|||
|
|
章节来源
|
|||
|
|
- [viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/package-info.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/package-info.java)
|
|||
|
|
- [viewsh-module-mall/viewsh-module-product-server/src/main/java/com/viewsh/module/product/controller/admin/category/ProductCategoryController.java](file://viewsh-module-mall/viewsh-module-product-server/src/main/java/com/viewsh/module/product/controller/admin/category/ProductCategoryController.java#L33-L75)
|
|||
|
|
- [viewsh-module-mall/viewsh-module-trade-server/src/main/java/com/viewsh/module/trade/controller/admin/order/TradeOrderController.java](file://viewsh-module-mall/viewsh-module-trade-server/src/main/java/com/viewsh/module/trade/controller/admin/order/TradeOrderController.java#L52-L169)
|
|||
|
|
- [viewsh-module-mall/viewsh-module-trade-server/src/main/java/com/viewsh/module/trade/controller/admin/brokerage/BrokerageWithdrawController.java](file://viewsh-module-mall/viewsh-module-trade-server/src/main/java/com/viewsh/module/trade/controller/admin/brokerage/BrokerageWithdrawController.java#L45-L57)
|
|||
|
|
|
|||
|
|
### 支付管理
|
|||
|
|
- 服务名与前缀
|
|||
|
|
- 服务名：pay-server
|
|||
|
|
- API 前缀：/pay
|
|||
|
|
- 版本：1.0.0
|
|||
|
|
- 核心接口
|
|||
|
|
- 应用信息
|
|||
|
|
- POST /pay/app/create：创建支付应用信息
|
|||
|
|
- PUT /pay/app/update：更新支付应用信息
|
|||
|
|
- PUT /pay/app/update-status：更新支付应用状态
|
|||
|
|
- DELETE /pay/app/delete：删除支付应用信息
|
|||
|
|
- GET /pay/app/get：获取支付应用信息
|
|||
|
|
- GET /pay/app/page：支付应用信息分页
|
|||
|
|
- 支付渠道
|
|||
|
|
- POST /pay/channel/create：创建支付渠道
|
|||
|
|
- PUT /pay/channel/update：更新支付渠道
|
|||
|
|
- DELETE /pay/channel/delete：删除支付渠道
|
|||
|
|
- GET /pay/channel/get：获取支付渠道
|
|||
|
|
- 支付订单
|
|||
|
|
- GET /pay/order/get：获取支付订单
|
|||
|
|
- GET /pay/order/page：支付订单分页
|
|||
|
|
- GET /pay/order/export-excel：导出支付订单Excel
|
|||
|
|
- 回调通知
|
|||
|
|
- POST /pay/notify/...：第三方支付回调入口（允许匿名访问），内部路由到订单/退款/转账处理
|
|||
|
|
- 关键流程（示例：支付回调处理）
|
|||
|
|
- 第三方支付平台回调 -> 网关 -> /pay/notify -> 平台内部处理 -> 更新支付单状态
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
sequenceDiagram
|
|||
|
|
participant TP as "第三方支付平台"
|
|||
|
|
participant G as "网关"
|
|||
|
|
participant P as "支付服务"
|
|||
|
|
participant O as "支付订单服务"
|
|||
|
|
TP->>G : POST /pay/notify/{type}
|
|||
|
|
G->>P : 转发回调
|
|||
|
|
P->>O : 校验签名/幂等/状态
|
|||
|
|
O-->>P : 更新订单状态
|
|||
|
|
P-->>TP : 返回成功/失败
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
图表来源
|
|||
|
|
- [viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/notify/PayNotifyController.java](file://viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/notify/PayNotifyController.java#L43-L56)
|
|||
|
|
- [viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/order/PayOrderController.java](file://viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/order/PayOrderController.java#L59-L60)
|
|||
|
|
|
|||
|
|
章节来源
|
|||
|
|
- [viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/enums/ApiConstants.java](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/enums/ApiConstants.java#L17-L21)
|
|||
|
|
- [viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/app/PayAppController.java](file://viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/app/PayAppController.java#L40-L92)
|
|||
|
|
- [viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/channel/PayChannelController.java](file://viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/channel/PayChannelController.java#L34-L61)
|
|||
|
|
- [viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/order/PayOrderController.java](file://viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/order/PayOrderController.java#L59-L60)
|
|||
|
|
- [viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/notify/PayNotifyController.java](file://viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/notify/PayNotifyController.java#L43-L56)
|
|||
|
|
|
|||
|
|
## 依赖分析
|
|||
|
|
- 模块间耦合
|
|||
|
|
- CRM 客户详情构建依赖系统模块的用户/部门服务；商机详情构建依赖客户、产品、状态类型/状态服务。
|
|||
|
|
- ERP 库存详情构建依赖产品与仓库服务。
|
|||
|
|
- 商城订单详情构建依赖会员服务与订单项/日志服务。
|
|||
|
|
- 支付模块内部通过回调控制器路由到订单/退款/转账服务。
|
|||
|
|
- 外部依赖与集成点
|
|||
|
|
- 网关层统一路由与文档聚合。
|
|||
|
|
- Knife4j 聚合各服务接口文档。
|
|||
|
|
- 潜在循环依赖
|
|||
|
|
- 控制器依赖服务，服务依赖API接口，整体呈单向依赖，未见循环依赖迹象。
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
graph LR
|
|||
|
|
CRM_Ctrl["CRM 控制器"] --> CRM_Svc["CRM 服务"]
|
|||
|
|
CRM_Svc --> Sys_API["系统用户/部门 API"]
|
|||
|
|
ERP_Ctrl["ERP 控制器"] --> ERP_Svc["ERP 服务"]
|
|||
|
|
ERP_Svc --> Prod_API["产品/仓库 API"]
|
|||
|
|
Trade_Ctrl["交易控制器"] --> Trade_Svc["交易服务"]
|
|||
|
|
Trade_Svc --> Member_API["会员 API"]
|
|||
|
|
Pay_Notify["支付回调控制器"] --> Pay_OrderSvc["支付订单服务"]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
图表来源
|
|||
|
|
- [viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/customer/CrmCustomerController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/customer/CrmCustomerController.java#L60-L63)
|
|||
|
|
- [viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/business/CrmBusinessController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/business/CrmBusinessController.java#L67-L70)
|
|||
|
|
- [viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/stock/ErpStockController.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/stock/ErpStockController.java#L50-L53)
|
|||
|
|
- [viewsh-module-mall/viewsh-module-trade-server/src/main/java/com/viewsh/module/trade/controller/admin/order/TradeOrderController.java](file://viewsh-module-mall/viewsh-module-trade-server/src/main/java/com/viewsh/module/trade/controller/admin/order/TradeOrderController.java#L49-L50)
|
|||
|
|
- [viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/notify/PayNotifyController.java](file://viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/notify/PayNotifyController.java#L50-L55)
|
|||
|
|
|
|||
|
|
章节来源
|
|||
|
|
- [viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/customer/CrmCustomerController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/customer/CrmCustomerController.java#L60-L63)
|
|||
|
|
- [viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/business/CrmBusinessController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/business/CrmBusinessController.java#L67-L70)
|
|||
|
|
- [viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/stock/ErpStockController.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/stock/ErpStockController.java#L50-L53)
|
|||
|
|
- [viewsh-module-mall/viewsh-module-trade-server/src/main/java/com/viewsh/module/trade/controller/admin/order/TradeOrderController.java](file://viewsh-module-mall/viewsh-module-trade-server/src/main/java/com/viewsh/module/trade/controller/admin/order/TradeOrderController.java#L49-L50)
|
|||
|
|
- [viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/notify/PayNotifyController.java](file://viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/notify/PayNotifyController.java#L50-L55)
|
|||
|
|
|
|||
|
|
## 性能考虑
|
|||
|
|
- 分页与导出
|
|||
|
|
- 分页接口建议限制每页大小，避免一次性返回大量数据；导出接口建议设置最大导出条数并异步处理。
|
|||
|
|
- 关联查询
|
|||
|
|
- 控制器侧批量查询用户/部门/产品/仓库等信息，减少多次远程调用；注意批量查询的集合大小阈值。
|
|||
|
|
- 缓存与幂等
|
|||
|
|
- 支付回调需实现幂等校验，避免重复处理；可结合订单状态与外部流水号进行去重。
|
|||
|
|
- 网关与文档
|
|||
|
|
- Knife4j 聚合文档在高并发下建议开启缓存与限流，避免对网关造成压力。
|
|||
|
|
|
|||
|
|
## 故障排查指南
|
|||
|
|
- 统一异常处理
|
|||
|
|
- 全局异常处理器捕获未处理异常，记录异常日志并返回统一错误码；对特定数据库表不存在异常做特殊处理。
|
|||
|
|
- 异常日志
|
|||
|
|
- 异常日志包含异常类名、方法名、行号、根因消息与堆栈轨迹，便于快速定位问题。
|
|||
|
|
- 常见问题
|
|||
|
|
- 404/403：确认路由前缀与权限配置；模块未启用时会返回“未实现”提示。
|
|||
|
|
- 401/403：检查Token有效性与权限位；权限不足时需补充角色/菜单授权。
|
|||
|
|
- 500：查看异常日志与堆栈，定位具体业务异常原因。
|
|||
|
|
|
|||
|
|
章节来源
|
|||
|
|
- [viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/web/core/handler/GlobalExceptionHandler.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/web/core/handler/GlobalExceptionHandler.java#L320-L348)
|
|||
|
|
- [viewsh-server/src/main/java/com/viewsh/server/controller/DefaultController.java](file://viewsh-server/src/main/java/com/viewsh/server/controller/DefaultController.java#L35-L63)
|
|||
|
|
|
|||
|
|
## 结论
|
|||
|
|
本项目通过统一的RESTful接口规范、网关路由与Knife4j文档聚合，实现了跨模块的清晰协作。各业务模块围绕核心对象（客户、商机、库存、订单、应用/渠道/订单/通知）提供了完整的增删改查与状态变更接口，并在控制器层面完成必要的关联数据拼装与导出能力。异常处理与日志记录保障了线上问题的可追溯性。建议在生产环境中进一步完善分页与导出策略、幂等与缓存机制，以及权限与路由的精细化治理。
|
|||
|
|
|
|||
|
|
## 附录
|
|||
|
|
- 接口文档聚合入口
|
|||
|
|
- http://{gateway-ip}:48080/doc.html
|
|||
|
|
- 常用错误码
|
|||
|
|
- 成功、参数校验失败、未登录/Token过期、无权限、限流、服务器内部错误及各模块业务错误码区间
|
|||
|
|
|
|||
|
|
章节来源
|
|||
|
|
- [docs/technical-overview/07-接口文档.md](file://docs/technical-overview/07-接口文档.md#L45-L58)
|
|||
|
|
- [docs/technical-overview/07-接口文档.md](file://docs/technical-overview/07-接口文档.md#L31-L42)
|