API 参考¶
后端的全部 HTTP 面汇于一处。业务端点以 /api/v1/* 为前缀；OIDC 提供方与基础设施端点位于根路径。
浏览器不会直接调用这些端点
前端采用 BFF 模型：浏览器只与同源的 /api/* Next.js 路由通信，由后者在服务端代理到后端。令牌绝不会进入客户端 JS。下列路径是后端的路径。
Swagger：GET /swagger/doc.json（生产环境需要 bearer 令牌）。
基础设施¶
| 方法 | 路径 | 访问 |
|---|---|---|
GET |
/health |
公开 |
GET |
/ready |
公开 |
GET |
/metrics |
生产环境需 OBSERVABILITY_TOKEN（否则 404） |
GET |
/swagger/doc.json |
同上 |
OIDC 提供方¶
在配置了 OAUTH_ISSUER + SSO_STATE_KEY 后启用。路径由 OIDC 规范固定。
| 方法 | 路径 |
|---|---|
GET |
/.well-known/openid-configuration |
GET |
/.well-known/jwks.json |
GET |
/oauth2/auth |
POST |
/oauth2/token |
POST |
/oauth2/introspect |
POST |
/oauth2/revoke |
GET |
/oauth2/sessions/logout |
GET POST |
/userinfo |
登录/授权流程的内部 API：/api/v1/provider/login · /consent ·
/login/accept · /login/reject · /consent/accept · /consent/reject ·
/logout/accept。
身份认证 — /api/v1/auth¶
| 方法 | 路径 | 限流 |
|---|---|---|
POST |
/eid/start |
auth（5/分钟） |
POST |
/eid/start-id |
auth |
POST |
/eid/poll |
poll（1/秒，burst 30） |
POST |
/google |
auth |
DELETE |
/google/link |
需登录 |
POST |
/refresh · /logout |
auth |
POST |
/initiate |
auth（移动端） |
GET |
/status/{sid} |
poll（移动端） |
超级管理员：/api/v1/auth/superadmin/mfa ·
/onboard/{google,eid/start,eid/start-id,eid/poll,email/send,email/verify,totp/init,totp/verify}。
Gerege SSO（RP 侧）：/api/v1/sso/start · /callback · /native · /logout。
用户与组织¶
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/api/v1/users/me |
自身档案 |
GET |
/api/v1/users/me/eid/summary · /certificates · /devices · /activity |
eID PKI 档案 |
GET POST DELETE |
/api/v1/users/me/eid/organizations… |
关联组织 |
GET POST DELETE |
/api/v1/users/me/eid/organizations/{regNo}/signers… |
授权签署人 |
POST GET |
/api/v1/org |
创建 / 我的组织 |
GET |
/api/v1/org/lookup/{regNo} |
在国家登记库中查询 |
GET POST PUT DELETE |
/api/v1/org/{id}/members… |
成员与角色 |
GET |
/api/v1/core/users · /organizations |
管理员检索（users.manage） |
eID 服务代理¶
| 方法 | 路径 | 授权 |
|---|---|---|
GET |
/api/v1/eid/summary · /certificates · /devices · /activity |
svc:eid-proxy |
GET |
/api/v1/eid-org/organizations · /organizations/{regNo}/signers |
svc:eid-org-proxy |
* |
/rp/sign/* |
svc:eid-sign |
公民服务 — /api/v1/gov¶
完整清单见公民服务。
公开目录：/api/v1/catalog/services · /services/{id} · /life-events。
服务登记与 Relay¶
完整清单见服务登记与 Relay（/api/v1/registry/*、/api/v1/relay/*）。
网关与应用注册¶
| 方法 | 路径 | 权限 |
|---|---|---|
GET |
/api/v1/gateway/overview · /logs |
gateway.manage |
GET POST PUT DELETE |
/api/v1/gateway/services… |
gateway.manage |
GET POST |
/api/v1/applications |
gateway.manage |
GET PUT DELETE |
/api/v1/applications/{id} |
gateway.manage |
POST |
/api/v1/applications/{id}/rotate-secret |
gateway.manage |
PUT |
/api/v1/applications/{id}/secret · /services |
gateway.manage |
签名、素材与文件¶
| 方法 | 路径 |
|---|---|
POST |
/api/v1/sign/initiate · /init |
GET |
/api/v1/sign/status/{sid} · /{id} · /{id}/download |
GET PUT DELETE |
/api/v1/me/signature |
PUT |
/api/v1/me/latin-name · /org-name-latin/{regNo} |
GET PUT DELETE |
/api/v1/me/orgstamp/{regNo} |
GET POST DELETE |
/api/v1/gspace · /upload · /download |
GET POST DELETE |
/api/v1/integrations… |
详见文档、签名与文件。
AI¶
| 方法 | 路径 | 限流 |
|---|---|---|
POST |
/api/v1/ai/chat · /stt · /tts · /translate |
20/分钟，burst 10 |
POST |
/api/v1/public/ai/chat · /chat/stream |
6/分钟，burst 3 |
POST |
/api/v1/public/ai/tts |
20/分钟，burst 8 |
详见 AI 流水线。
管理、RBAC 与审计¶
| 方法 | 路径 | 权限 |
|---|---|---|
GET |
/api/v1/rbac/me |
需登录 |
GET POST PUT DELETE |
/api/v1/rbac/roles… · /permissions |
roles.manage |
GET POST PUT DELETE |
/api/v1/admin/users… |
users.manage |
GET PUT |
/api/v1/admin/ai/prompts… |
settings.manage |
POST |
/api/v1/admin/ai/knowledge/reindex |
settings.manage |
GET POST PUT DELETE |
/api/v1/superadmin/… |
superadmin |
GET |
/api/v1/audit · /audit/verify |
admin |
POST |
/api/v1/security/events |
需登录 |
GET |
/api/v1/security/events |
admin |
GET PUT |
/api/v1/site/appearance |
公开 / settings.manage |
GET POST PUT DELETE |
/api/v1/themes… |
公开（/active）/ admin |
详见管理、RBAC 与审计。
错误模型¶
处理器的形态为 func(w, r) error，由 v1.Wrap 包装。usecase 层返回
apperror.*，并在同一处映射为 HTTP 状态码。内部原因用
apperror.InternalCause 包裹，因此库层错误绝不会泄漏给客户端。