#服务端 API

AppKernia 使用 OpenAPI 3.1 描述服务端契约。本文档提供最常用路径、示例和安全约束；字段、枚举、响应码与 Schema 的最终事实源始终是当前仓库的 server/openapi/openapi.yaml。

下载当前 OpenAPI YAML

使用 Admin 在线 OpenAPI 文档

#API 面

Admin 与 Mobile Token 不能互换。X-AppID 只选择一个公开、启用的 App；租户和用户范围必须来自已验证 Session，不能由该 Header 越权指定。

#认证流程

Admin 与 Mobile 使用不同入口和 Audience；刷新是受控的单次会话轮换，不是对任意失败请求的自动重放。

Admin 和 Mobile 使用不同入口与 Audience。客户端不能把一次失败写请求盲目重放；只有接口明确具备幂等语义并满足幂等约定时才可自动重试。

#API 家族

#所有客户端都应发送

Accept: application/json
Accept-Language: zh-CN
X-Request-ID: 019…

App 相关接口还需要：

X-AppID: 01900000-0000-7000-8000-000000000001

受保护的 Mobile 请求：

Authorization: Bearer YOUR_ACCESS_TOKEN

#第一个无需登录的请求

在本机 API 已启动后，用仓库清单里的 App ID 请求公共配置：

curl --fail-with-body \
  -H 'Accept: application/json' \
  -H 'Accept-Language: zh-CN' \
  -H 'X-AppID: 00000000-0000-4000-8000-000000000001' \
  http://127.0.0.1:8080/api/v1/public/config

成功响应应同时满足 HTTP 2xx、稳定 code、与请求语言匹配的 Content-Language，并且不包含任何服务器 Secret。

#集成检查表

• 从 OpenAPI 生成 Client，并在 CI 中校验 Schema Hash。
• Mobile 只调用 /api/v1，Admin 只调用 /admin-api/v1。
• 每个请求传递 Accept-Language；日志保留 Request ID，但不记录 Token。
• 用后端权限测试覆盖拒绝路径，不把菜单或按钮当授权证据。
• 写请求明确幂等键、重试边界和审计行为。
• 多租户接口用两个 Tenant 的集成数据验证 SQL 隔离。

#从哪里开始

• 在线 OpenAPI 文档与系统菜单
• 响应、错误与幂等
• Mobile 认证 API
• Mobile 用户与公共资源
• Admin 认证 API
• Admin 核心资源 API