管理、RBAC 与审计¶
平台的管理面建立在四种角色、动态权限目录与哈希链审计日志之上。
四种角色¶
| 角色 | 负责什么 |
|---|---|
superadmin |
任命/撤销管理员、邀请、平台访问模式。唯一承担此职责的角色。 |
admin |
运行系统——自动解析到目录中的全部权限 |
manager |
审核并办理公民申请（gov.review） |
user |
个人区域（personal.view） |
RBAC——动态权限¶
角色与权限存放在数据库中，可在运行期变更。完整目录见功能全景。
| 方法 | 路径 | 权限 |
|---|---|---|
GET |
/api/v1/rbac/me |
需登录——查看自身权限 |
GET |
/api/v1/rbac/roles · /permissions |
roles.manage |
POST PUT DELETE |
/api/v1/rbac/roles… |
roles.manage |
PUT |
/api/v1/rbac/roles/{id}/permissions |
roles.manage |
权限校验以路由级中间件（RequirePermission）实施，而不是在每个处理器中重复，因此新端点漏掉防护的概率大为降低。routes_authz_matrix_test.go 用测试把这张矩阵钉住。
UI：/admin/roles。
管理员界面¶
| 方法 | 路径 | 权限 |
|---|---|---|
GET POST |
/api/v1/admin/users |
users.manage |
PUT |
/api/v1/admin/users/{id}/role · /active |
users.manage |
DELETE |
/api/v1/admin/users/{id} |
users.manage |
GET PUT |
/api/v1/admin/ai/prompts · /{key} |
settings.manage |
POST |
/api/v1/admin/ai/knowledge/reindex |
settings.manage |
AI 的提示词分层与知识库均从数据库配置——参见 AI 流水线。护栏层硬编码在代码中，永远不可配置。
UI：/admin/dashboard、/admin/users、/admin/settings、/admin/core。
超级管理员¶
| 方法 | 路径 | 说明 |
|---|---|---|
GET POST |
/api/v1/superadmin/admins |
列出 / 添加管理员 |
GET POST |
/api/v1/superadmin/admins/by-register |
按登记号查找 / 添加 |
PUT |
/api/v1/superadmin/admins/{id}/grant |
授予权限 |
DELETE |
/api/v1/superadmin/admins/{id} |
收回权限 |
GET POST DELETE |
/api/v1/superadmin/invites… |
管理邀请 |
GET PUT |
/api/v1/superadmin/access-mode |
平台访问模式（public / private） |
入驻与 MFA¶
成为超级管理员的路径设有多重防护：
- 邀请白名单——未受邀的邮箱无法启动入驻流程，已使用的邀请不能重复使用。
- eID 验证——
POST /api/v1/auth/superadmin/onboard/eid/start·/start-id·/poll（身份证号或二维码）。 - Google 或邮箱验证——
/onboard/google、/onboard/email/send·/verify。 - TOTP 多因素——
/onboard/totp/init·/verify，此后每次登录都需POST /api/v1/auth/superadmin/mfa。
TOTP 密钥以 AES-GCM 密文保存——明文从不落库。恢复码仅在生成时展示一次，数据库中只保存其 SHA-256 哈希，用过的码不会再次生效。
所有入驻端点都受 auth 限流器保护（5/分钟）。
UI：/superadmin/login、/superadmin/onboard、/admin/superadmin。
审计¶
审计日志以哈希链串联，且只追加。每条记录都携带上一条的哈希，因此在中间修改或删除某一行都会把链条打断。
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/api/v1/audit |
分页列表（admin） |
GET |
/api/v1/audit/verify |
链条完整性校验 |
verify 返回 { ok, broken_id }——当 ok=false 时指出第一条被破坏记录的 id。
操作者从请求的 RLS 身份中读取，request_id 从上下文中自动取得——调用方无需传入，伪造归属的空间因此很小。
微秒精度
Postgres 的 timestamptz 具有微秒精度。若进入哈希的时间戳未做相应截断，
VerifyChain 会因纳秒级偏差而误报——代码对此做了有意的处理。
UI：/admin/audit。
安全事件¶
收集客户端侧的安全信号（CSP 违规等）：
POST /api/v1/security/events——对任何已登录用户开放（RLS 固定user_id）GET /api/v1/security/events——仅限 admin
UI：/admin/security。
外观与品牌¶
颜色、字体与密度从不硬编码——统一在管理界面中设置。
| 方法 | 路径 | 权限 |
|---|---|---|
GET |
/api/v1/site/appearance |
公开（公开页面需要） |
PUT |
/api/v1/site/appearance |
settings.manage |
GET |
/api/v1/themes/active |
公开 |
GET POST PUT DELETE |
/api/v1/themes… |
admin |
PUT |
/api/v1/themes/{id}/active |
admin |
每位用户还可拥有自己的覆盖设置。UI：/admin/themes、/admin/settings。