API 约定

每个 StackRivet 端点——包括代码生成器产出的——都遵守同一套约定，base path 为 /api/v1。详尽的端点目录是 live OpenAPI 3.1 文档；本页是这些端点共享的契约。

# 永远最新的完整目录：
open http://127.0.0.1:8080/swagger-ui.html      # 交互式
curl http://127.0.0.1:8080/v3/api-docs           # 原始 OpenAPI JSON

响应信封

每个响应都被包装，并带一个可与服务端日志关联的 traceId：

{ "code": "0", "message": "OK", "data": {}, "traceId": "01J..." }

code: "0" 表示成功。注意 HTTP 状态码同样有意义（StackRivet 不把一切都压成 200）——code 是稳定、可被机器分支的契约，HTTP 状态是传输层信号。

分页的 data：

{ "items": [], "page": 1, "pageSize": 20, "total": 0 }

HTTP 状态码

状态	何时
200 / 201 / 202	成功 / 已创建 / 异步任务已接受
400	参数错误
401 / 403	未认证 / 无权限
404	不存在
409	状态 / 唯一键 / 版本冲突
413 / 415	上传过大 / 类型不支持
429	限流
500	系统错误

错误码

错误 code 是稳定、永不本地化的契约——客户端按它分支。传输格式为 {前缀}_{原因}_{HTTP}：

{ "code": "SYSTEM_USER_DUPLICATED_409", "message": "...", "details": [], "traceId": "01J..." }

前缀包括 AUTH、PERM、VALIDATION、SYSTEM、ASSET、SIGNED_URL、GENERATOR、TASK。所有码来自 stackrivet-common 的 ErrorCode 注册表；message 按 Accept-Language 本地化（回退英文），但 code 不。构建期门禁保证每个码的中英文案齐备。

分页与排序

参数	默认	说明
`page`	1	从 1 开始
`pageSize`	20	最大 200
`sort`	—	如 `createdAt,desc`；仅白名单字段

sort 只接受白名单字段——任意 SQL 列绝不透传。

类型

时间是 ISO 8601 字符串。
精度敏感值（金额、比例）用字符串或整数最小单位——绝不用浮点。
枚举是小写字符串；布尔是 JSON boolean；ID 是字符串。

请求头

Authorization: Bearer <access_token>
X-Request-Id: 可选的客户端请求 ID
Idempotency-Key: 可选——仅用于明确声明支持幂等的接口

Token 短期有效且可撤销；强制下线使旧 token 失效。Token 绝不进日志。
只有接口明确声明支持幂等时才发送 Idempotency-Key。StackRivet 在异步任务提交中使用它，避免重试导致重任务重复执行。
重操作（导入、导出、大批生成写入）返回 202 和任务 ID，而非占着请求线程——通过任务追踪。

API 分组

OpenAPI tag 映射到路径前缀：Auth（/auth）、Me（/me）、Users、Departments、Posts、Roles、Menus、Dictionaries、Params、Audit、Assets、Generator、Tasks、System——全部在 /api/v1 下。