# 业务模块API
**本文引用的文件**
- [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)
## 目录
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
路由与聚合"] --> CRM["CRM 服务"]
GW --> ERP["ERP 服务"]
GW --> MALL["商城服务"]
GW --> PAY["支付服务"]
subgraph "接口规范"
REST["RESTful 规范
统一响应体"]
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["校验参数
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)