20260823210241

2026-08-23 21:02:41 +08:00
1 parent 5ff4583aeb
commit f4c7413dc6
@@ -0,0 +1,442 @@
+# 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)
+
+### 版本兼容性与向后兼容
+- 向后兼容原则
+  - 新增可选参数不影响已有调用
+  - 响应体新增字段不影响解析
+  - 错误码保持向下兼容，新增错误码不修改既有含义
+- 建议
+  - 前端对未知字段做忽略处理
+  - 对关键必填参数做好校验与降级策略
+
+[本节为通用指导，不直接分析具体文件]