通用约定¶

在生态系统所有代码仓库中反复出现的事实标准。它们并非来自某份正式规范—— 而是同样的现实问题被解决过多次之后沉淀下来的规则。新平台应当从一开始就遵循它们。

Identity casing¶

规则：数据库中所有身份类文本一律以小写存储。检索不区分大小写。展示时再转换为标准形式（登记号大写，姓名用 Title Case）。

豁免字段——以下字段按原样存储：

这条规则从何而来

曾有公民以 АБ12345678 注册，之后又试图用 аб12345678 登录，系统便视其为 另一个人，从而产生重复账户。在存储层统一大小写，可以整类地消除这种缺陷。

superadmin (1) → admin (2) → manager (3) → user (4)

硬性规则：

super admin 是启用 MFA 的独立账户。 通过 onboarding 向导创建：邀请白名单 → Google → eID → 邮箱 OTP → TOTP + 恢复码。它保存在单独的表中，以 Google 身份为键。

由此带来的实际结果是：同一个人既可以是 eID 管理员，也可以是 Google super admin——两个不同账户、两条不同的登录路径。super admin 的每一次登录都受 MFA 保护。

admin 权限按登记号授予，且必须对应本地 eID 中已注册的用户。

规则：在机构中授予某人 manager 权限时，会向本人推送 eID SIGN，只有在其以 PIN2 确认之后，该权限才变为 ACTIVE。

原因：授予权限是一项具有法律后果的行为。若管理员单方面把某人设为负责人，当事人日后可以否认。PIN2 签名提供了不可否认性——堵住了「我没有同意过」这条退路。

规则：只有在同一设备（same-device）的流程中才返回回调。其他情况一律轮询会话（poll）。

原因在于：对于在另一台设备上发起的流程，回调根本不知道该返回到哪里。轮询把发起流程的浏览器确立为事实来源，使流程保持明确。

第三方 deep-link——通过回调参数传递；流程结束时把相应应用切到前台。

规则：绑定 Google 账号之前，用户必须先经 eID 核验。首次绑定把账号与真实自然人关联；此后即可直接用 Google 登录。也可以解绑。

原因：Google 账号任何人都能创建，单凭它无法作为公民身份凭证。经 eID 绑定一次之后，该 Google 账号才指向某位确定的公民。

规则：在 eID 上只注册 RP。同一个 RP 之下的多个应用或子系统，通过 rp_app / rp_app_url 字段传递。

这样，日志和用户界面上都能看出是哪个应用发起的请求——而无需为每个应用单独注册 RP，也无需把凭据四处分发。

规则：用户登出后会回到其发起时所在的域名，而不会被抛到 SSO 的 /login。

原因：用户原本身处 RP 的应用之中。登出后落到一个完全陌生域名的登录页，只会造成困惑。登出应当在它开始的那个应用内部结束。

规则：OAuth client 与 client secret 只在 SSO 中创建，也只存放在那里。任何其他系统都不创建、不保存、不展示它们。

Developer Portal 是这条规则的试金石：它提供应用注册的指引，但并不创建 client，只是深链接到 SSO 控制台。

规则：每个仓库都有自己的 docs/ 目录与 MkDocs 站点。文档与代码同处一个仓库，并在同一个 PR 中一同变更。

语言覆盖：至少 MN + EN；主要仓库另加 ZH · RU。详见多语言页面。

规则：handler → usecase → repository → domain。依赖只能单向流动。业务内核（domain、usecase）永远不会 import Web 框架。

一个简单的检查办法：如果 domain/ 下的文件里出现了 net/http 或 chi 的 import，规则就已被破坏。