功能全景¶
本页汇总代码中真实存在的每一项功能——模块、API 前缀、UI 界面与所需权限。详情请沿链接深入。
代码在哪里？
后端的全部基础能力位于 Go 模块 platform-core（v0.3.4）。本仓库的
backend/cmd/api/main.go 加载该基础并将其命名为 ServiceName = "gerege-pos"
——这是一个没有自有路由的参考部署。前端（Next.js BFF）则完整地位于本仓库中。
模块全景¶
| 模块 | 作用 | API 前缀 | UI 界面 | 权限 |
|---|---|---|---|---|
| 身份认证 | eID（二维码 · App2App · 身份证号推送）、Google 绑定、Gerege SSO | /api/v1/auth/*、/api/v1/sso/* |
/login、/auth/eid/callback |
公开 |
| OIDC 提供方 | 平台自身即身份提供方 | /.well-known/*、/oauth2/*、/userinfo |
/oauth/login、/oauth/consent |
公开（客户端认证） |
| eID PKI 档案 | 组织、证书、设备、活动记录 | /api/v1/users/me/eid/* |
/me/eid/* |
需登录 |
| eID 服务代理 | 应用通过代理调用 eID 服务 | /api/v1/eid/*、/api/v1/eid-org/* |
—（m2m） | svc:* 授权 |
| 组织 | 创建、查询、成员与角色 | /api/v1/org/* |
/me/organizations |
需登录 |
| 公民服务 | 申请、证明、通知、缴费、预约 | /api/v1/gov/* |
/me/services、/me/applications |
需登录 |
| 经办队列 | 分配与办理申请 | /api/v1/gov/officer/* |
/manager/requests |
gov.review |
| 服务登记 | 服务护照、版本、证明材料、once-only | /api/v1/registry/* |
/admin/registry/* |
registry.view · registry.manage |
| 公开目录 | 无需登录的服务清单 | /api/v1/catalog/* |
首页 | 公开 |
| Relay | 平台之间的请求转发 | /api/v1/relay/* |
/admin/relay/* |
relay.view · relay.manage |
| API 网关 | 服务目录 + 请求遥测 | /api/v1/gateway/* |
/admin/gateway/* |
gateway.manage |
| 应用注册 | 创建 OAuth 客户端、轮换密钥 | /api/v1/applications/* |
/admin/applications |
gateway.manage |
| 电子签名 | PAdES PDF 签名（eID /v3） |
/api/v1/sign/*、/rp/sign/* |
/me/eid/sign |
需登录 |
| 个人素材 | 签名图片、拉丁文姓名、公章 | /api/v1/me/* |
/me/profile |
需登录 |
| Gerege Space | 平台自有的 SFTP 存储 | /api/v1/gspace/* |
/me/integrations |
需登录 |
| 第三方集成 | Google Drive/Meet、Dropbox OAuth 绑定 | /api/v1/integrations/* |
/me/integrations |
需登录 |
| AI 助手 | 聊天、语音转文字、文字转语音、翻译 | /api/v1/ai/* |
/me/ai、/me/translate |
需登录 |
| 公开 AI | 免登录聊天 + 流式回复 | /api/v1/public/ai/* |
首页助手 | 公开（有限流） |
| RBAC | 动态角色与权限目录 | /api/v1/rbac/* |
/admin/roles |
roles.manage |
| 管理 | 用户、AI 提示词、知识库 | /api/v1/admin/* |
/admin/* |
users.manage · settings.manage |
| 超级管理员 | 任命管理员、邀请、访问模式 | /api/v1/superadmin/* |
/admin/superadmin |
superadmin |
| 外观 | 全站强调色/字体/密度/主题 | /api/v1/site/*、/api/v1/themes/* |
/admin/themes |
settings.manage |
| 审计 | 哈希链日志 + 完整性校验 | /api/v1/audit/* |
/admin/audit |
admin |
| 安全事件 | 收集客户端安全信号 | /api/v1/security/events |
/admin/security |
需登录（列表：admin） |
权限目录¶
domain_rbac.go 中定义的 13 项权限：
| 权限 | 含义 |
|---|---|
dashboard.view |
查看管理员/经理仪表板 |
settings.manage |
管理系统设置、AI 提示词、外观 |
users.manage |
列出用户、变更角色、启用/停用 |
roles.manage |
RBAC——管理角色与权限 |
personal.view |
用户个人区域 |
manager.view |
经理区域 |
gateway.manage |
管理网关服务与应用注册 |
relay.view |
查看 relay 面板 |
relay.manage |
管理 relay 平台与路由 |
gov.review |
审核并办理公民申请 |
gov.catalog |
管理公共服务目录 |
registry.view |
查看服务登记与 once-only 面板 |
registry.manage |
管理服务护照、证明材料、版本 |
四个基础角色：superadmin → admin → manager → user。admin 会自动解析到目录中的所有权限，无需逐项授予。
速率限制¶
代码中固定的取值（cmd/api/server/server.go）：
| 限流器 | 速率 | Burst | 范围 |
|---|---|---|---|
authRateLimiter |
5/分钟 | 5 | /auth/eid/start、/auth/google、/auth/refresh、/auth/logout、超级管理员入驻 |
pollRateLimiter |
1/秒 | 30 | eID 长轮询（/auth/eid/poll、/auth/status/{sid}） |
aiRateLimiter |
20/分钟 | 10 | /ai/chat、/ai/stt、/ai/tts、/ai/translate |
publicAIRateLimiter |
6/分钟 | 3 | /public/ai/chat、/public/ai/chat/stream |
publicTTSRateLimiter |
20/分钟 | 8 | /public/ai/tts |
govWriteRateLimiter |
30/分钟 | 15 | gov 写操作、eID 档案写操作、素材、gspace |
TRUSTED_PROXIES
限流按客户端 IP 计算。在 nginx → BFF → api 的拓扑中，api 只能看到 BFF 的
IP，因此若不设置 TRUSTED_PROXIES，所有流量都会落进同一个桶。留空时
api 会在启动日志中给出警告——参见配置。
各项功能的启用条件¶
大多数能力遵循 fail-closed：没有凭据就关闭，而不是假装能用。
| 功能 | 启用条件 | 否则 |
|---|---|---|
| eID 登录 | EID_RP_UUID + EID_RP_SECRET |
按钮隐藏 |
| Google 绑定 | GOOGLE_CLIENT_ID + SECRET |
按钮隐藏 |
| Gerege SSO（RP） | SSO_ISSUER + SSO_CLIENT_ID + SECRET |
SSO 流程停用 |
| OIDC 提供方 | OAUTH_ISSUER + SSO_STATE_KEY |
Discovery 返回 404 |
| AI 助手 | GEMINI_API_KEY |
AI 端点返回 500 |
| 知识库语义检索 | pgvector + 向量模型 | 回退到 ILIKE |
| Gerege Space | GSPACE_HOST + 凭据 |
卡片停用 |
| eID 服务代理 | SSO 代理配置 | 路由不挂载 |
/metrics、/swagger |
OBSERVABILITY_TOKEN |
production 下返回 404 |