# API接口文档

<cite>
**本文引用的文件**
- [AuthController.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/AuthController.java)
- [DataController.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/DataController.java)
- [FileController.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/FileController.java)
- [AuthService.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/AuthService.java)
- [DataService.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/DataService.java)
- [DataSaveService.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/DataSaveService.java)
- [FileService.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/FileService.java)
- [JwtUtils.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/utils/JwtUtils.java)
- [ApiResponse.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/utils/ApiResponse.java)
- [FileStorageProperties.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/config/FileStorageProperties.java)
</cite>

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

## 简介
本文件为FMS系统的API接口参考文档，覆盖认证、数据与文件三大类RESTful接口。文档包含：
- 每个接口的HTTP方法、URL路径、请求参数、响应格式与错误码说明
- JWT认证流程的调用示例（登录、令牌使用）
- 元数据驱动的数据接口调用方式（动态查询、分页、批量保存、自动编码生成）
- 文件上传、下载、预览等操作的完整示例
- 版本兼容性与向后兼容性说明

## 项目结构
后端采用Spring Boot分层架构：
- 控制器层：按业务域划分（认证、数据、文件）
- 服务层：封装业务逻辑（认证、数据读写、文件存取、批量保存）
- 工具与配置：统一响应体、JWT工具、文件存储配置等

```mermaid
graph TB
subgraph "控制器"
AC["AuthController"]
DC["DataController"]
FC["FileController"]
end
subgraph "服务"
AS["AuthService"]
DS["DataService"]
DSS["DataSaveService"]
FS["FileService"]
end
subgraph "工具与配置"
JWT["JwtUtils"]
RESP["ApiResponse"]
FSP["FileStorageProperties"]
end
AC --> AS
DC --> DS
DC --> DSS
FC --> FS
AS --> JWT
FS --> FSP
AC -.-> RESP
DC -.-> RESP
FC -.-> RESP
```

图表来源
- [AuthController.java:19-55](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/AuthController.java#L19-L55)
- [DataController.java:19-94](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/DataController.java#L19-L94)
- [FileController.java:28-111](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/FileController.java#L28-L111)
- [AuthService.java:19-84](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/AuthService.java#L19-L84)
- [DataService.java:17-69](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/DataService.java#L17-L69)
- [DataSaveService.java:25-58](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/DataSaveService.java#L25-L58)
- [FileService.java:34-118](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/FileService.java#L34-L118)
- [JwtUtils.java:18-57](file://fms-api/src/main/java/cn/g3soft/fmsapi/utils/JwtUtils.java#L18-L57)
- [ApiResponse.java:1-32](file://fms-api/src/main/java/cn/g3soft/fmsapi/utils/ApiResponse.java#L1-L32)
- [FileStorageProperties.java:1-69](file://fms-api/src/main/java/cn/g3soft/fmsapi/config/FileStorageProperties.java#L1-L69)

章节来源
- [AuthController.java:19-55](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/AuthController.java#L19-L55)
- [DataController.java:19-94](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/DataController.java#L19-L94)
- [FileController.java:28-111](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/FileController.java#L28-L111)

## 核心组件
- 统一响应体 ApiResponse：提供成功/失败封装及标准错误码
- JWT工具 JwtUtils：负责令牌签发与解析
- 文件存储配置 FileStorageProperties：本地/OSS模式配置
- 各控制器与服务：实现认证、数据、文件相关能力

章节来源
- [ApiResponse.java:1-32](file://fms-api/src/main/java/cn/g3soft/fmsapi/utils/ApiResponse.java#L1-L32)
- [JwtUtils.java:18-82](file://fms-api/src/main/java/cn/g3soft/fmsapi/utils/JwtUtils.java#L18-L82)
- [FileStorageProperties.java:1-69](file://fms-api/src/main/java/cn/g3soft/fmsapi/config/FileStorageProperties.java#L1-L69)

## 架构总览
下图展示典型请求在系统中的流转路径，以“登录”和“数据分页”为例。

```mermaid
sequenceDiagram
participant C as "客户端"
participant A as "AuthController"
participant S as "AuthService"
participant J as "JwtUtils"
participant R as "ApiResponse"
C->>A : POST /auth/login {orgid, userid, password}
A->>S : login(orgid, userid, password, request)
S-->>A : Optional<Map> (token, orgid, user)
A-->>C : ApiResponse{code=0, data={token,...}}
```

图表来源
- [AuthController.java:26-55](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/AuthController.java#L26-L55)
- [AuthService.java:34-84](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/AuthService.java#L34-L84)
- [JwtUtils.java:45-57](file://fms-api/src/main/java/cn/g3soft/fmsapi/utils/JwtUtils.java#L45-L57)
- [ApiResponse.java:9-30](file://fms-api/src/main/java/cn/g3soft/fmsapi/utils/ApiResponse.java#L9-L30)

## 详细组件分析

### 认证接口
- 基础信息
  - 基础路径：/auth
  - 认证方式：登录后返回JWT，后续请求需在请求头携带令牌（由前端或网关注入）
  - 统一响应：ApiResponse

- 登录
  - 方法：POST
  - 路径：/auth/login
  - 请求体字段
    - orgid：机构码（必填）
    - userid：用户ID（必填）
    - password：密码（必填）
  - 响应data
    - token：JWT字符串
    - orgid：机构码
    - user：{ id, account, name }
  - 错误码
    - 401：认证失败（机构码、账号或密码错误）
    - 1000：业务异常（如参数缺失）

- 调用示例（登录）
  - 请求
    - POST /auth/login
    - Body: { "orgid": "ORG001", "userid": "U001", "password": "xxx" }
  - 响应
    - { "code": 0, "message": "操作成功", "data": { "token": "...", "orgid": "ORG001", "user": { "id": 123, "account": "U001", "name": "张三" } } }

- 令牌刷新
  - 当前未提供独立的刷新接口；建议前端在令牌过期时重新调用登录获取新令牌

- 安全提示
  - 登录成功后服务端会记录会话并生成JWT；后续访问受保护资源需携带有效令牌

章节来源
- [AuthController.java:26-55](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/AuthController.java#L26-L55)
- [AuthService.java:34-84](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/AuthService.java#L34-L84)
- [JwtUtils.java:45-57](file://fms-api/src/main/java/cn/g3soft/fmsapi/utils/JwtUtils.java#L45-L57)
- [ApiResponse.java:9-30](file://fms-api/src/main/java/cn/g3soft/fmsapi/utils/ApiResponse.java#L9-L30)

### 数据接口（元数据驱动）
- 基础信息
  - 基础路径：/data
  - 元数据驱动：通过表/视图名与列元数据进行动态查询与保存
  - 统一响应：ApiResponse

- 动态查询
  - 方法：POST
  - 路径：/data/loaddata
  - 请求体字段
    - view_name：视图名（必填）
    - search_condition：搜索条件（可选）
    - order_by：排序（可选）
    - search_columns：搜索列（可选）
  - 响应data：List<Map<String,Object>>

- SQL直查
  - 方法：POST
  - 路径：/data/loaddatabysql
  - 请求体字段
    - sql：SQL语句（必填）
  - 响应data：List<Map<String,Object>>

- 分页查询
  - 方法：POST
  - 路径：/data/page
  - 请求体字段
    - view_name：视图名（必填）
    - search_columns：搜索列（可选）
    - search_condition：搜索条件（可选）
    - order_by：排序（必填）
    - page_no：页码（默认1）
    - page_size：每页条数（默认20）
  - 响应data
    - rows：列表
    - row_count：本页条数
    - total：总条数
    - page_no：当前页
    - page_size：每页大小

- 描述元数据
  - 方法：POST
  - 路径：/data/describe
  - 请求体字段
    - table：表名（必填）
  - 响应data：列元数据列表

- 批量保存（事务）
  - 方法：POST
  - 路径：/data/saveobjt
  - 请求体：数组，每项为一个表的保存指令
    - table：目标表名（必填）
    - key_field：主键字段名（必填）
    - deletes：删除行数组（可选）
    - updates：更新行数组（可选）
    - inserts：新增行数组（可选）
  - 行为
    - 同一请求内对多个表的操作在同一事务中执行
    - 任一失败将回滚整个请求
  - 响应data：null（成功）

- 批量保存流程图
```mermaid
flowchart TD
Start(["进入 saveobjt"]) --> Validate["校验请求体非空"]
Validate --> BeginTx["开启事务"]
BeginTx --> LoadMeta["加载表元数据(缓存)"]
LoadMeta --> ExecDelete{"是否存在deletes?"}
ExecDelete --> |是| DoDelete["执行删除"]
ExecDelete --> |否| ExecUpdate{"是否存在updates?"}
DoDelete --> ExecUpdate
ExecUpdate --> |是| DoUpdate["执行更新"]
ExecUpdate --> |否| ExecInsert{"是否存在inserts?"}
DoUpdate --> ExecInsert
ExecInsert --> |是| DoInsert["执行新增"]
ExecInsert --> |否| Commit["提交事务"]
DoInsert --> Commit
Commit --> End(["返回成功"])
```

图表来源
- [DataSaveService.java:34-58](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/DataSaveService.java#L34-L58)
- [DataSaveService.java:381-423](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/DataSaveService.java#L381-L423)

- 自动生成编号
  - 方法：POST
  - 路径：/data/nextcode
  - 请求体字段
    - moduleId：模块ID（必填）
    - count：生成数量（可选，默认1，范围1-1000）
  - 响应data：单个字符串或字符串数组

- 雪花ID生成
  - 方法：POST
  - 路径：/data/nextid
  - 请求体字段
    - count：生成数量（可选，默认1）
  - 响应data：单个Long或Long数组

章节来源
- [DataController.java:29-94](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/DataController.java#L29-L94)
- [DataService.java:26-69](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/DataService.java#L26-L69)
- [DataSaveService.java:34-58](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/DataSaveService.java#L34-L58)
- [DataSaveService.java:60-143](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/DataSaveService.java#L60-L143)
- [DataSaveService.java:381-423](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/DataSaveService.java#L381-L423)

### 文件接口
- 基础信息
  - 基础路径：/file
  - 存储模式：本地或OSS（通过配置切换）
  - 统一响应：ApiResponse

- 获取存储配置
  - 方法：POST
  - 路径：/file/config
  - 响应data
    - storageType：local 或 aliyun-oss

- 本地上传（FormData）
  - 方法：POST
  - 路径：/file/upload
  - 表单字段
    - files：文件数组（必填）
    - father：父级ID（必填）
    - moduleId：模块ID（必填）
    - cateId：分类ID（可选）
  - 响应data：文件元数据数组
    - subid：文件唯一标识
    - mx_filename：原始文件名
    - mx_filesize：文件大小
    - mx_fileext：扩展名
    - mx_mapfilename：映射路径（用于访问）
    - father：父级ID
    - mx_moduleid：模块ID
    - mx_cate_id：分类ID

- OSS上传凭证
  - 方法：POST
  - 路径：/file/upload-credential
  - 用途：前端直传OSS前获取凭证
  - 响应data：OSS上传所需凭证对象

- 保存文件记录（OSS回调）
  - 方法：POST
  - 路径：/file/save-record
  - 请求体：文件元数据（含subid、father、mx_moduleid、mx_filename、mx_filesize、mx_fileext、mx_mapfilename、mx_cate_id等）
  - 响应data：保存结果

- 删除文件
  - 方法：POST
  - 路径：/file/delete
  - 请求体
    - subid：文件ID（必填）
  - 行为：根据存储模式删除物理文件与数据库记录

- 本地文件访问/预览
  - 方法：GET
  - 路径：/file/static/{fileName:.+}
  - 说明：fileName包含子目录结构（如 {orgId}/{yyyy}/{MM}/{dd}/{file}）
  - 响应：文件流，浏览器可直接预览或下载

- 文件上传序列图（本地模式）
```mermaid
sequenceDiagram
participant C as "客户端"
participant FC as "FileController"
participant FS as "FileService"
participant DB as "数据库"
C->>FC : POST /file/upload (files, father, moduleId, cateId)
FC->>FS : localUpload(files, ...)
FS->>DB : 插入bf_files记录
FS-->>FC : List<元数据>
FC-->>C : ApiResponse{data : [...]}
```

图表来源
- [FileController.java:51-59](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/FileController.java#L51-L59)
- [FileService.java:54-96](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/FileService.java#L54-L96)
- [FileService.java:120-148](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/FileService.java#L120-L148)

章节来源
- [FileController.java:41-111](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/FileController.java#L41-L111)
- [FileService.java:54-268](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/FileService.java#L54-L268)
- [FileStorageProperties.java:1-69](file://fms-api/src/main/java/cn/g3soft/fmsapi/config/FileStorageProperties.java#L1-L69)

## 依赖关系分析
- 控制器依赖服务：认证、数据、文件各自解耦
- 服务依赖工具与配置：
  - AuthService依赖JwtUtils进行令牌签发
  - FileService依赖FileStorageProperties决定存储策略
  - DataSaveService通过DbUtils进行元数据驱动的持久化
- 统一响应体贯穿所有接口

```mermaid
graph LR
AC["AuthController"] --> AS["AuthService"]
DC["DataController"] --> DS["DataService"]
DC --> DSS["DataSaveService"]
FC["FileController"] --> FS["FileService"]
AS --> JWT["JwtUtils"]
FS --> FSP["FileStorageProperties"]
AC -.-> RESP["ApiResponse"]
DC -.-> RESP
FC -.-> RESP
```

图表来源
- [AuthController.java:19-55](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/AuthController.java#L19-L55)
- [DataController.java:19-94](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/DataController.java#L19-L94)
- [FileController.java:28-111](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/FileController.java#L28-L111)
- [AuthService.java:19-84](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/AuthService.java#L19-L84)
- [DataService.java:17-69](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/DataService.java#L17-L69)
- [DataSaveService.java:25-58](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/DataSaveService.java#L25-L58)
- [FileService.java:34-118](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/FileService.java#L34-L118)
- [JwtUtils.java:18-57](file://fms-api/src/main/java/cn/g3soft/fmsapi/utils/JwtUtils.java#L18-L57)
- [ApiResponse.java:1-32](file://fms-api/src/main/java/cn/g3soft/fmsapi/utils/ApiResponse.java#L1-L32)
- [FileStorageProperties.java:1-69](file://fms-api/src/main/java/cn/g3soft/fmsapi/config/FileStorageProperties.java#L1-L69)

## 性能考虑
- 分页查询：page接口支持分页，避免一次性拉取大量数据
- 元数据缓存：批量保存时对表元数据进行缓存，减少重复查询
- 事务控制：saveobjt在同一事务中处理多表操作，保证一致性
- 文件I/O：本地上传顺序写入磁盘后落库，避免大对象阻塞；OSS模式支持直传减轻服务器压力
- 连接管理：数据库连接通过DataSourceUtils获取与释放，防止连接泄漏

[本节为通用指导，不直接分析具体文件]

## 故障排查指南
- 常见错误码
  - 0：成功
  - 1000：业务异常（如参数校验失败）
  - 2001：保存错误（批量保存失败）
  - 401：认证失败（登录失败或令牌无效）
  - 40101：会话被替换（并发登录场景）
  - 500：系统错误

- 定位建议
  - 检查请求体字段是否齐全且类型正确
  - 查看统一响应体的message字段获取具体错误信息
  - 对于批量保存失败，关注SaveObjectException中的表名、操作与索引信息
  - 文件删除失败时确认存储模式与路径前缀配置是否正确

章节来源
- [ApiResponse.java:9-30](file://fms-api/src/main/java/cn/g3soft/fmsapi/utils/ApiResponse.java#L9-L30)
- [DataSaveService.java:445-463](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/DataSaveService.java#L445-L463)

## 结论
本API文档覆盖了FMS系统的认证、数据与文件三大核心能力，提供了完整的接口规范、调用示例与错误码说明。通过元数据驱动的数据接口与事务化的批量保存，系统具备良好的扩展性与一致性保障。文件接口同时支持本地与OSS两种存储模式，满足多样化部署需求。

[本节为总结性内容，不直接分析具体文件]

## 附录

### 统一响应体规范
- 结构
  - code：状态码
  - message：消息
  - data：业务数据
- 常用状态码
  - 0：成功
  - 1000：业务异常
  - 2001：保存错误
  - 401：认证失败
  - 40101：会话被替换
  - 500：系统错误

章节来源
- [ApiResponse.java:1-32](file://fms-api/src/main/java/cn/g3soft/fmsapi/utils/ApiResponse.java#L1-L32)

### 版本兼容性与向后兼容
- 向后兼容原则
  - 新增可选参数不影响已有调用
  - 响应体新增字段不影响解析
  - 错误码保持向下兼容，新增错误码不修改既有含义
- 建议
  - 前端对未知字段做忽略处理
  - 对关键必填参数做好校验与降级策略

[本节为通用指导，不直接分析具体文件]