服务登记与 Relay

这两个模块处理的是机构主数据（而非按公民划分的数据），因此不启用 RLS——保护在 HTTP 层按权限施加。

Ring System · R1 — 服务登记

服务登记回答的是一个管理问题：公共服务清单有多完整、数字化到什么程度、离 once-only 还有多远？ 每一份服务护照都符合 CPSV-AP 词汇表。

护照状态

状态	含义
draft	草稿——不出现在公开目录
published	已发布——通过 /api/v1/catalog/* 对外提供
archived	已归档

主动性等级

沿用爱沙尼亚模型——从仅有信息到全自动服务：

等级	含义
information	仅发布信息
online	在线受理申请
once_only	不再重复索取已有数据
proactive	无需公民申请即主动提供

概览面板会统计各等级的服务数量，并计算平均法定办理时限。

证明材料与 once-only

registry_evidences 是证明材料目录。每条记录带有 in_khur 标志：该信息是否已存在于国家数据交换之中。

护照 ↔ 证明材料的关联上带有 from_citizen 标志：该材料是向公民索取的，还是由机构自行从系统调取的。

once-only 违规

凡是 in_khur = true 且 from_citizen = true 的情形，都是一次 once-only 违规——向公民索取国家已经掌握的信息。 GET /api/v1/registry/once-only 会列出这些情形，并按年度发生频次估算它给公民带来的负担。

版本与 delta

每次发布都会生成一个护照版本（registry_service_versions）。Delta* 字段保存的是与再造前基线的差值——负值代表改进（步骤更少、耗时更短）。

端点

registry.view 负责读取，registry.manage 负责写入。admin 同时满足两者。

方法	路径	权限
GET	/api/v1/registry/overview	view
GET	/api/v1/registry/catalog	view
GET	/api/v1/registry/once-only	view
GET	/api/v1/registry/services · /{id}	view
GET	/api/v1/registry/services/{id}/versions	view
GET	/api/v1/registry/services/{id}/once-only	view
GET	/api/v1/registry/evidences · /life-events	view
POST PUT DELETE	/api/v1/registry/services…	manage
POST	/api/v1/registry/services/{id}/publish · /archive	manage
PUT	/api/v1/registry/services/{id}/evidences	manage
POST PUT DELETE	/api/v1/registry/evidences…	manage
POST DELETE	/api/v1/registry/life-events…	manage

UI：Admin → Registry（/admin/registry、/admin/registry/services、/admin/registry/evidences）。

Relay — 平台之间的请求转发

Relay 接收上游平台发来的带时限请求，分派给下游平台，跟踪 SLA，并汇总回复。

flowchart LR
    U[Upstream platform] -->|POST /relay/requests| R[(Relay)]
    R -->|assignment| D1[Downstream A]
    R -->|assignment| D2[Downstream B]
    D1 -->|respond| R
    D2 -->|respond| R
    R -->|forward-up webhook| U

状态

请求： received → dispatched → in_progress → fulfilled （或 overdue、rejected）。

分派任务： pending → acknowledged → in_progress → done （或 overdue、rejected）。

SLA 跟踪

机制	行为
提醒	在 SLA 窗口的 75% 与 90% 处向下游发送催办
升级	任务逾期后再经过一段宽限期，自动升级至上级
时间线	received · dispatched · reminded · escalated · responded · fulfilled · overdue · breach_notified · forwarded_up

升级宽限期

核心模块中 RelayEscalateGrace 为 2 分钟——这是模板默认值。生产部署会按真实 SLA 调长。

端点

方法	路径	权限
POST	/api/v1/relay/webhook	—（对端平台调用）
POST	/api/v1/relay/requests	manage
POST	/api/v1/relay/assignments/{id}/respond	manage
POST	/api/v1/relay/requests/{id}/forward	manage
GET	/api/v1/relay/overview · /requests · /requests/{id}	view
GET POST DELETE	/api/v1/relay/platforms…	view / manage
GET POST DELETE	/api/v1/relay/routes…	view / manage

RelayRoute 是 service_code → platform 的路由规则，每个目标各有自己的 SLA。

UI：Admin → Relay（/admin/relay、/admin/relay/config、/admin/relay/{id}）。

ingest/respond 的保护方式

在本参考实现中，requests 与 assignments 的写操作由 JWT + relay.manage 保护。在生产环境中，正确的形态是上下游平台通过网关（m2m OAuth）调用它们。