wms/.qoder/repowiki/zh/content/API接口文档/API接口文档.md

# API接口文档

<cite>
**本文引用的文件**
- [AdminApplication.java](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java)
- [AuthApplication.java](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java)
- [ApiResult.java](file://nflg-wms-common/src/main/java/com/nflg/wms/common/pojo/ApiResult.java)
- [STATE.java](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/STATE.java)
- [Constant.java](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java)
- [BaseController.java](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java)
- [application.yml（admin）](file://nflg-wms-admin/src/main/resources/application.yml)
- [application.yml（auth）](file://nflg-wms-auth/src/main/resources/application.yml)
- [ApiMark.java](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/annotation/ApiMark.java)
- [ApiStorageTest.java](file://nflg-wms-admin/src/test/java/com/nflg/wms/admin/ApiStorageTest.java)
- [ApiServiceImpl.java](file://nflg-wms-repository/src/main/java/com/nflg/wms/repository/service/impl/ApiServiceImpl.java)
- [pom.xml（根）](file://pom.xml)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件为NFLG WMS系统的完整API接口文档，覆盖仓储管理、物料管理、订单处理等业务域的RESTful接口设计与规范。文档基于仓库中的Spring Boot微服务架构与统一返回体、状态码体系进行整理，并结合注解标记与测试用例对接口进行梳理与归档。同时提供认证与授权机制说明、错误处理策略、版本与兼容性建议、客户端集成与SDK使用指引，以及Postman集合与curl示例的准备思路。

## 项目结构
系统采用多模块聚合工程，核心模块包括：
- 公共模块：统一返回体、常量、异常与工具
- 启动器模块：基础控制器基类、通用注解
- 认证模块：统一认证中心（SSO）
- 管理模块：业务管理端服务
- 仓储模块：接口清单持久化与查询
- 网关与定时任务等其他模块

```mermaid
graph TB
subgraph "公共层"
COMMON["nflg-wms-common<br/>统一返回体/常量/异常"]
STARTER["nflg-wms-starter<br/>基础控制器/注解"]
end
subgraph "服务层"
AUTH["nflg-wms-auth<br/>认证中心(SSO)"]
ADMIN["nflg-wms-admin<br/>管理服务"]
REPO["nflg-wms-repository<br/>接口清单持久化"]
end
GATEWAY["nflg-wms-gateway<br/>网关(可选)"]
ROOT["根pom<br/>多模块聚合"]
ROOT --> COMMON
ROOT --> STARTER
ROOT --> AUTH
ROOT --> ADMIN
ROOT --> REPO
ROOT --> GATEWAY
ADMIN --> COMMON
ADMIN --> STARTER
AUTH --> COMMON
AUTH --> STARTER
REPO --> COMMON
```

图表来源
- [pom.xml（根）:17-28](file://pom.xml#L17-L28)
- [AdminApplication.java:12-18](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java#L12-L18)
- [AuthApplication.java:10-14](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java#L10-L14)

章节来源
- [pom.xml（根）:17-28](file://pom.xml#L17-L28)
- [application.yml（admin）:1-48](file://nflg-wms-admin/src/main/resources/application.yml#L1-L48)
- [application.yml（auth）:1-50](file://nflg-wms-auth/src/main/resources/application.yml#L1-L50)

## 核心组件
- 统一返回体与状态码
  - 统一返回体封装了响应码、类型、消息、时间戳、追踪ID与结果数据；支持分页转换与多种错误构造方式。
  - 状态枚举覆盖系统错误、成功、参数错误、权限拒绝、业务异常、请求方式错误、库存不足等场景。
- 基础控制器
  - 提供二维码内容生成等通用能力，便于各业务控制器复用。
- 注解与接口清单
  - 使用自定义注解标记接口模块与名称，并通过测试用例扫描注册到接口清单表中，形成可维护的接口目录。

章节来源
- [ApiResult.java:16-121](file://nflg-wms-common/src/main/java/com/nflg/wms/common/pojo/ApiResult.java#L16-L121)
- [STATE.java:6-36](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/STATE.java#L6-L36)
- [BaseController.java:17-77](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java#L17-L77)
- [ApiMark.java:8-17](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/annotation/ApiMark.java#L8-L17)
- [ApiStorageTest.java:28-65](file://nflg-wms-admin/src/test/java/com/nflg/wms/admin/ApiStorageTest.java#L28-L65)
- [ApiServiceImpl.java:24-38](file://nflg-wms-repository/src/main/java/com/nflg/wms/repository/service/impl/ApiServiceImpl.java#L24-L38)

## 架构总览
系统采用Spring Cloud微服务架构，认证中心提供统一SSO认证，管理服务承载业务接口，公共模块提供统一返回与常量，启动器模块提供基础能力与注解，仓储模块用于接口清单的持久化与查询。

```mermaid
graph TB
CLIENT["客户端/第三方系统"]
GATEWAY["网关(可选)"]
AUTH["认证中心(nflg-wms-auth)<br/>端口8101"]
ADMIN["管理服务(nflg-wms-admin)<br/>端口8102"]
COMMON["公共模块(nflg-wms-common)"]
STARTER["启动器模块(nflg-wms-starter)"]
REPO["仓储模块(nflg-wms-repository)"]
CLIENT --> GATEWAY
GATEWAY --> AUTH
GATEWAY --> ADMIN
ADMIN --> COMMON
ADMIN --> STARTER
ADMIN --> REPO
AUTH --> COMMON
AUTH --> STARTER
```

图表来源
- [AdminApplication.java:12-18](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java#L12-L18)
- [AuthApplication.java:10-14](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java#L10-L14)
- [application.yml（admin）:1-48](file://nflg-wms-admin/src/main/resources/application.yml#L1-L48)
- [application.yml（auth）:1-50](file://nflg-wms-auth/src/main/resources/application.yml#L1-L50)

## 详细组件分析

### 认证与授权机制
- Token与SSO
  - 认证中心通过Sa-Token提供SSO能力，默认Token名称为authorization，超时时间为2592000秒（30天），Ticket超时为300秒。
  - 客户端在访问受保护资源时，应在请求头携带authorization字段。
- 登录扩展信息
  - 登录时会附加用户名、工号、邮箱、部门ID、角色、用户类型等扩展信息，便于前端与后端进行权限控制与个性化展示。
- 权限验证
  - 业务接口应结合角色与菜单按钮权限进行校验，具体策略由各业务模块在控制器中实现。

章节来源
- [application.yml（auth）:20-34](file://nflg-wms-auth/src/main/resources/application.yml#L20-L34)
- [Constant.java:11-22](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java#L11-L22)

### 错误处理与统一返回体
- 统一返回体字段
  - code：响应码
  - type：响应类型
  - message：提示信息
  - extras：额外信息（如错误详情）
  - time：服务器时间
  - traceId：链路追踪ID
  - result：业务结果
- 常见状态码
  - 成功：200
  - 参数错误：101
  - 信息错误：102
  - 操作失败：103
  - 没有权限：104
  - 用户校验失败：105
  - 请重新登录：106
  - 上传失败：107
  - 数据不完整无法提交或审核：108
  - 服务连接异常：109
  - 访问地址不存在：110
  - 请求服务异常：111
  - 账号异地登录：112
  - 页面跳转：113
  - 页面异常：114
  - 业务异常：115
  - 请求方式错误：116
  - 需要用户确认：117
  - 订单不存在：118
  - SAP错误：119
  - 库存不足：120

章节来源
- [ApiResult.java:16-121](file://nflg-wms-common/src/main/java/com/nflg/wms/common/pojo/ApiResult.java#L16-L121)
- [STATE.java:6-36](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/STATE.java#L6-L36)

### 接口命名与模块化
- 接口命名规范
  - 使用@ApiMark注解标注接口模块名与接口名，并声明是否公开接口。
- 接口清单管理
  - 通过测试用例扫描所有带@ApiMark的方法，自动注册或更新接口清单，便于统一管理与文档化。

章节来源
- [ApiMark.java:8-17](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/annotation/ApiMark.java#L8-L17)
- [ApiStorageTest.java:28-65](file://nflg-wms-admin/src/test/java/com/nflg/wms/admin/ApiStorageTest.java#L28-L65)
- [ApiServiceImpl.java:24-38](file://nflg-wms-repository/src/main/java/com/nflg/wms/repository/service/impl/ApiServiceImpl.java#L24-L38)

### 二维码打印与内容生成
- 通用二维码内容生成
  - 基础控制器提供二维码内容生成方法，便于在打印、扫码等环节复用。

章节来源
- [BaseController.java:30-37](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java#L30-L37)

## 依赖分析
- 模块间依赖
  - 管理服务与认证中心均依赖公共模块与启动器模块，确保统一的返回体、常量与注解能力。
  - 接口清单服务依赖公共模块的VO与实体，用于接口目录的分组与查询。
- 外部依赖
  - Sa-Token用于SSO与JWT，Actuator用于健康检查与监控，Nacos用于配置与服务发现。

```mermaid
graph LR
ADMIN["nflg-wms-admin"] --> COMMON["nflg-wms-common"]
ADMIN --> STARTER["nflg-wms-starter"]
ADMIN --> REPO["nflg-wms-repository"]
AUTH["nflg-wms-auth"] --> COMMON
AUTH --> STARTER
REPO --> COMMON
```

图表来源
- [AdminApplication.java:12-18](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java#L12-L18)
- [AuthApplication.java:10-14](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java#L10-L14)
- [ApiServiceImpl.java:24-38](file://nflg-wms-repository/src/main/java/com/nflg/wms/repository/service/impl/ApiServiceImpl.java#L24-L38)

章节来源
- [pom.xml（根）:54-192](file://pom.xml#L54-L192)

## 性能考虑
- 并发与重试
  - 管理服务启用重试与调度，有助于提升部分业务的可用性与稳定性。
- 监控与追踪
  - Actuator开启健康检查与Redis数据库健康探测，支持链路追踪与采样概率设置。
- 文件上传
  - 管理服务配置了较大的文件与请求大小限制，满足大文件导入导出场景。

章节来源
- [AdminApplication.java:16-18](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java#L16-L18)
- [application.yml（admin）:24-27](file://nflg-wms-admin/src/main/resources/application.yml#L24-L27)
- [application.yml（admin）:31-48](file://nflg-wms-admin/src/main/resources/application.yml#L31-L48)

## 故障排查指南
- 常见错误码定位
  - 参数错误、业务异常、权限不足、请求方式错误、SAP错误、库存不足等，均可通过统一返回体中的code与message快速定位。
- 追踪ID
  - 返回体包含traceId，可用于日志检索与问题定位。
- 登录与SSO
  - 若出现“用户校验失败”或“请重新登录”，检查authorization头与Token有效性；确认认证中心配置与回调地址。

章节来源
- [ApiResult.java:16-24](file://nflg-wms-common/src/main/java/com/nflg/wms/common/pojo/ApiResult.java#L16-L24)
- [STATE.java:6-36](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/STATE.java#L6-L36)
- [application.yml（auth）:20-34](file://nflg-wms-auth/src/main/resources/application.yml#L20-L34)

## 结论
本API文档基于仓库现有实现，明确了统一返回体、状态码、认证授权、错误处理与接口清单管理等关键机制。建议后续补充各业务模块的具体接口定义与示例，以完善端到端的API使用体验。

## 附录

### API版本管理与兼容性
- 版本策略
  - 建议在URL中引入版本前缀（如/v1），并在服务端通过网关或路由进行版本分流。
- 向后兼容
  - 新增字段采用可选策略，避免破坏既有调用；变更字段需通过新版本发布并提供迁移指引。

### 客户端集成与SDK使用
- SDK建议
  - 基于统一返回体与状态码，封装HTTP客户端SDK，内置Token刷新、重试与日志追踪能力。
- 集成步骤
  - 认证中心获取Token → 管理服务调用携带Authorization头 → 处理统一返回体与状态码。

### Postman集合与curl示例
- Postman集合
  - 建议将接口清单（来自接口扫描与注册）导入Postman，按模块分组，设置全局变量（如Token、环境地址）。
- curl示例
  - 登录获取Token：curl -X POST "{认证中心}/login" -H "Content-Type: application/json" -d '{"username":"...","password":"..."}'
  - 调用受保护接口：curl -X GET "{管理服务}/api/..." -H "Authorization: {token}"