系统基础数据与文件 API
系统基础数据与文件 API
本文归纳字典、参数配置、语言、地区、组织、币种、文件、文件夹、监控、日志、定时任务和代码生成相关接口。
使用场景
| 场景 | 主要接口 | 说明 |
|---|---|---|
| 字典和参数 | 字典类型、字典数据、参数配置 | 统一枚举、开关和业务配置 |
| 国际化和地区 | 语言、地区、币种 | 多语言、多币种和地址选择 |
| 组织资料 | 组织信息 | 平台组织、物流组织和业务归属 |
| 文件资源 | 文件、文件夹 | 图片、附件、头像、富文本资源 |
| 监控日志 | 服务器、缓存、登录日志、操作日志、在线用户 | 运维监控和审计追踪 |
| 工具能力 | 定时任务、代码生成、测试接口 | 开发、运维和内部工具 |
基础数据使用原则
| 数据 | 使用原则 |
|---|---|
| 字典 | 前后端共享状态、类型、枚举时优先用字典 |
| 参数配置 | 适合业务开关、阈值、第三方参数引用，不适合保存复杂业务规则 |
| 地区 | 地址、物流区域、仓库、配送目的地需要统一使用地区 ID |
| 币种 | 商品、订单、钱包、结算需要明确币种字段 |
| 组织 | 管理端数据归属、物流组织和仓库关联需要统一维护 |
| 文件 | 业务表保存文件 ID，展示时通过文件 URL 接口换取地址 |
后端基础能力逻辑
系统基础数据和文件能力被多个业务域复用，变更时影响面较大。
| 能力 | 后端逻辑 |
|---|---|
| 字典 | 提供状态和枚举的展示文本，部分业务仍以 Java 枚举为准 |
| 参数配置 | 提供运行期可调整参数，适合开关和阈值，不适合复杂规则 |
| 地区 | 地址、物流区域、仓库目的地和派送范围共用 |
| 组织 | 平台组织、物流组织、仓库归属和管理端数据范围使用 |
| 币种 | 商品、订单、钱包、结算、预算都需要币种一致 |
| 文件 | 文件上传后业务表保存 fileId，展示时换取 URL |
| 定时任务 | 通过任务配置调用 Spring Bean 方法，任务日志记录执行结果 |
基础数据变更建议先评估引用关系。例如删除地区可能影响收货地址、仓库、物流规则和派送目的地；删除文件可能影响商品图片、头像、评价图片和商户资质。
基础数据
| 端别 | 接口名称 | 方法 | 路径 | 权限标识 | 主要用途 | 主要调用端 | 后端 Controller |
|---|---|---|---|---|---|---|---|
| shared | 字典类型 | GET /list、GET /page、GET /{dictId}、POST、PUT、DELETE |
/api/v1/system/dict/type |
*:system:dict:type:* |
字典类型维护 | admin |
SysDictTypeController |
| shared | 字典数据 | GET /{dictCode}、GET /type/{dictType}、GET /list、GET /page、POST、PUT、DELETE |
/api/v1/system/dict/data |
*:system:dict:data:* |
字典项维护和按类型查询 | admin、client、ops |
SysDictDataController |
| shared | 参数配置 | GET /page、GET /{configId}、GET /key/{configKey}、POST、PUT、DELETE |
/api/v1/system/config |
*:system:config:* |
系统参数配置和按键查询 | admin、client |
SysConfigController |
| shared | 语言配置 | GET /page、GET /{languageId}/dept、GET /dept/page、POST、PUT、DELETE |
/api/v1/system/language |
*:system:language:* |
多语言和部门语言配置 | admin、client |
SysLanguageController |
| shared | 地区信息 | GET /list、GET /list/cache、GET /page、GET /{locationId}、GET /{locationId}/tree、GET /{locationId}/organization/list、POST、PUT、DELETE |
/api/v1/data/location |
*:data:location:* |
国家、省市区和组织关联 | admin、client、ops |
DataLocationController |
| shared | 组织信息 | GET /list、GET /page、GET /{organizationId}、POST、PUT、DELETE、PUT /{organizationId}/status |
/api/v1/data/organization |
*:data:organization:* |
组织机构管理 | admin、ops |
DataOrganizationController |
| shared | 币种信息 | GET /list、GET /page、GET /{currency}、POST、DELETE |
/api/v1/data/currency |
*:data:currency:* |
币种资料维护 | admin、client |
DataCurrencyController |
| admin | 课程结构 | GET /list、GET /page、GET /{id}、POST、PUT、DELETE |
/api/v1/data/course-structure |
admin:data:course-structure:* |
数据结构类基础资料 | admin |
DataCourseStructureController |
| shared | 业务编码 | GET /business/code/list |
/api/v1/common |
登录态 | 获取业务编码列表 | admin、client、ops |
BusinessCodeController |
文件与文件夹
| 端别 | 接口名称 | 方法 | 路径 | 权限标识 | 主要用途 | 主要调用端 | 后端 Controller |
|---|---|---|---|---|---|---|---|
| shared | 文件管理 | GET /{fileId}/url、POST /upload、POST /upload/v2、POST /upload/current-user、PUT /{fileId}/upload/v2/complete、POST /upload/by/path、POST /upload/by/path/v2、PUT /{fileId}/move、PUT /{fileId}/copy、DELETE /{fileId} |
/api/v1/file |
*:file:* |
文件上传、预签名、当前用户文件、访问 URL、移动、复制、删除 | admin、client |
FileController |
| shared | 文件夹管理 | GET /list、GET /page、GET /{folderId}/detail、POST、PUT /{folderId}、PUT /{folderId}/move、PUT /{folderId}/copy、DELETE /{folderId} |
/api/v1/folder |
*:file:folder:* |
文件夹和子文件查询 | admin |
FolderController |
文件上传流程
普通上传：
- 前端选择文件。
- 调用
POST /api/v1/file/upload或当前用户上传接口。 - 后端保存文件元数据并返回
fileId。 - 业务表保存
fileId。 - 页面展示时调用
GET /api/v1/file/{fileId}/url获取可访问地址。
预签名上传：
- 前端调用预签名上传接口获取上传信息。
- 前端直传对象存储。
- 上传完成后调用
PUT /api/v1/file/{fileId}/upload/v2/complete。 - 后端确认文件状态，业务表再保存
fileId。
预签名上传适合大文件或小程序直传场景，但业务上仍应以 fileId 为长期引用，不保存临时上传地址。
监控、日志和工具
| 端别 | 接口名称 | 方法 | 路径 | 权限标识 | 主要用途 | 主要调用端 | 后端 Controller |
|---|---|---|---|---|---|---|---|
| admin | 首页 | GET |
/ |
登录态 | 服务首页探活 | admin |
SysIndexController |
| admin | 服务器监控 | GET |
/api/v1/monitor/server |
admin:monitor:server:* |
服务器运行状态 | admin |
ServerController |
| admin | 缓存监控 | GET、DELETE |
/api/v1/monitor/cache |
admin:monitor:cache:* |
缓存查询和清理 | admin |
CacheController |
| admin | 登录日志 | GET /list、GET /page、DELETE、POST /export |
/api/v1/monitor/logininfor |
admin:monitor:logininfor:* |
登录日志查询和导出 | admin |
SysLoginInfoController |
| admin | 操作日志 | GET /list、GET /page、DELETE、POST /export |
/api/v1/monitor/operlog |
admin:monitor:operlog:* |
操作日志查询和导出 | admin |
SysOperlogController |
| admin | 在线用户 | GET /list、DELETE /{tokenId} |
/api/v1/monitor/online |
admin:monitor:online:* |
在线用户查询和强退 | admin |
SysUserOnlineController |
| admin | 定时任务 | GET /list、GET /page、GET /{jobId}、POST、PUT、DELETE、PUT /changeStatus、PUT /run |
/api/v1/monitor/job |
admin:monitor:job:* |
定时任务配置和执行 | admin |
SysJobController |
| admin | 定时任务日志 | GET /list、GET /page、GET /{jobLogId}、DELETE、POST /clean |
/api/v1/monitor/jobLog |
admin:monitor:jobLog:* |
任务日志查询和清理 | admin |
SysJobLogController |
| admin | 代码生成 | GET /list、GET /{tableId}、POST /importTable、PUT、DELETE、GET /preview/{tableId}、GET /genCode/{tableName} |
/api/v1/tool/gen |
admin:tool:gen:* |
代码生成配置和生成 | admin |
GenController |
| shared | 测试接口 | GET /list、GET /{userId}、POST /save、PUT /update、DELETE /{userId} |
/test/user |
测试 | 示例测试接口 | 开发调试 | TestController |
定时任务维护
定时任务配置通过 /api/v1/monitor/job 维护，任务方法通常是 beanName.methodName。
| 任务类型 | 维护重点 |
|---|---|
| 业务任务 | 明确任务影响的数据范围、是否可重复执行和失败重试策略 |
| 营销任务 | 卡券过期、预算预警、预算对账、成本日报要防止重复处理 |
| 日志任务 | 清理前确认保留周期和审计要求 |
| 手工执行 | 手工运行前确认参数和影响范围，避免生产数据被重复处理 |
新增任务需要同步记录：任务名称、Bean、方法、参数、cron、负责人、影响表和失败处理方式。
前端封装
admin/src/api/dictApi.ts、locationApi.ts、organizationApi.ts、fileApi.ts。client/api/index.js的data、file分组。ops/api/system.js。
维护注意事项
- 字典值变更会影响前后端状态判断，删除前需要检查业务表和前端枚举引用。
- 地区数据应避免重复名称导致的歧义，业务表优先保存地区 ID 和必要冗余名称。
- 文件删除需要确认是否被商品、头像、富文本、资质文件等业务引用。
- 操作日志和登录日志是问题追查依据，不建议随意清理。
- 定时任务变更需要记录执行频率、影响范围和失败重试策略。
- 营销、订单、物流和结算等核心任务应优先设计为幂等，避免手工补跑造成重复扣减或重复消息。
联调验收
| 场景 | 验收口径 |
|---|---|
| 字典 | 前端下拉和后端状态展示一致 |
| 地区 | 地址、物流规则、仓库和派送目的地能使用同一地区数据 |
| 文件 | 上传、获取 URL、移动、复制、删除和业务引用都正常 |
| 头像 | 小程序头像上传后用户资料刷新正常 |
| 定时任务 | 任务可启停、手工运行、记录日志，失败能查看错误 |
| 日志审计 | 登录日志和操作日志能定位用户、时间、IP 和业务动作 |