把 v3 spec §11.2 要求的整套文档层补齐,并把 spec §11.1 欠下的
「浏览器验收重跑」在真实上游 SPA 上补做完(内核浏览器 aix 驱动)。
新增文档:
- `docs/contract.md`(重写):**132 端点全表** + 4 种响应形状 + 数据模型 + 时间口径,
唯一真源。端点表由 `scripts/check-contract.sh` 与源码注册路由**逐条对账**。
- `docs/decisions.md`(重写):逐条裁决 D1–D21。
- `docs/known-limitations.md`(重写):L1–L7,含 §5.4 权限敞开的显式条目(L4)。
- `docs/runbook.md`(新):怎么起 / 怎么冒烟 / 常见故障。
- `MIGRATION.md`(新):Java TDC ⇄ Rust 逐件翻译表 + 口令换算 + 数据 ETL。
- `HOWTO_ENTITY.md`(新):加一个实体(含子表挂载面)。
- `docs/ACCOUNT-LAYER.md`(新):`base_user` 账号层(官方双 md5 公式)。
- `docs/CONSOLE-ACCEPTANCE.md`(重写):**B5 重跑版**浏览器验收。
新增尺子(第四把 + 两把专项):
- `scripts/check-contract.sh`:端点表 vs 实际注册路由对账(132 == 132)。
- `scripts/check-citations.py`:文档里 `文件:行号` 引用逐条校验(139 条 0 失效)。
- `scripts/upstream-action-census.py`:上游动作端点普查(只读上游克隆,可复算)。
- `scripts/contract_probe.py`:动作端点形状探针(109 条逐条打过,零偏差)。
影响:
- **L5 数字纠正**:原先记的「111 条上游动作端点未实现」口径错了
(`grep -rhoE` 只抓带参数的映射、且跨了全部 31 个控制器)
⇒ 真实数字 **109**(122 声明 − 11 CRUD 基线 − 2 聚合详情 = 26 形态 A + 83 形态 B)。
- **L7(新增)**:**26 条**上游动作端点**不会 404** ⇒ 被通用详情路由 `/{Entity}/{id}`
吞掉(`src/tdc/controller/crud.rs:65-93`)⇒ GET 返回 **200 + `code:400`**、
POST 返回 **405** ⇒ 上游前端下拉框静默变空。**只判 HTTP 状态码会误判成成功**。
- **CONSOLE-ACCEPTANCE §4 纠正**:服务目录 / 我的账单**已实现**(P4),
失败点在**连接器身份闸门**(`f_tds_space_id` / `f_tds_connector_id` 为空 ⇒ 出向前 fail-closed),
**不是** TDS NOOP 降级、也不是代理 404。
- `CLAUDE.md` 同步:目录树、红线、坑位表(「上游动作端点不 404」新增一行)。
实测:cargo test **246** 项全绿 0 failed(1 ignored)· smoke.sh PASS=80 FAIL=0 ·
check-boundary.sh exit 0 · check-entity.sh PASS=13 FAIL=0 ·
check-contract.sh 132 条端点一致 · check-citations.py 139 条引用 0 失效 ⇒ **六把尺子全绿**。
⚠️ 口径更正:此前(B4 提交信息与记忆文件)记的「172 lib + 62 集成 = 236」是**误数**
—— `src/` 与 `tests/` 自 B4 起未变,逐二进制实测就是 246 ⇒ 从本批起统一用 246。
Co-Authored-By: Claude Code <[email protected]>
7.8 KiB
账号层(base_user)契约
🔴 本文件讲账号层:载体是什么、口令怎么算、管理员位怎么判、角色码怎么取。 上游对照物 = JNPF j7 的
base_user/base_role/base_role_relation三张表
- 上游
PasswordTokenGranter的口令算法。 与docs/contract.md(对外形状)/docs/known-limitations.mdL4(权限敞开)配套读。
1. 载体
| 表 | 用途 | 本仓位置 |
|---|---|---|
base_user |
账号(f_account / f_password / f_secretkey / f_is_administrator / f_enabled_mark / f_delete_mark …) |
schema/migrate.sql(B2 起建表,B4 起真正使用) |
base_role |
角色(f_en_code) |
同上 |
base_role_relation |
用户 ↔ 角色(f_object_type='user' + f_object_id + f_role_id) |
同上 |
🔴 数据面代码:src/tdc/service/account.rs(读写 base_*)、
src/tdc/controller/account.rs(6 个端点 + 登录)。
🔴 不建上游其余 120 张 base_*(base_module / base_authorize / base_organize …)——
上游 ssw.jnpf-permission.enabled=false ⇒ 菜单授权行是死的(见 docs/known-limitations.md L2)。
🔴 data/accounts.json 保留但后端不再读取(B4 之前它是载体)。
存量账号不导入(决策 D8)⇒ 旧 JSON 里的账号在 B4 之后登不上。
2. 口令:官方双 md5 公式
公式
f_password = md5( lower( md5(明文) ) + lower(f_secretkey) )
- 入参
md5(明文)是明文的 md5 hex(32 个小写 hex),不是明文本身。 f_secretkey是每账号随机的秘钥(UUID v4 大写,36 字符带连字符)。- 上游对照:
PasswordTokenGranter.java:186=Md5Util.getStringMd5(inputPwd + secretkey.toLowerCase())(inputPwd已经是md5_hex(明文))。
完整链路
| 环节 | 做什么 | 代码位置 |
|---|---|---|
| 浏览器加密 | md5(明文) → AES-256-ECB-PKCS7 → hex |
src/platform/cipher.rs(与上游 frontend/web/src/utils/cipher.ts 逐字对齐) |
| 服务端解密 | 密文 hex → md5(明文) |
src/platform/cipher.rs(decrypt_login_password) |
| 入库 / 比对 | md5(lower(md5(明文)) + lower(secretkey)) |
src/tdc/service/account.rs:124(official_password_hash) |
| 登录比对 | constant_time_eq(常量时间) |
src/tdc/controller/account.rs:78(login)+ src/platform/compare.rs |
🔴 三条容易踩的
- 改密不换 secretkey(与官方一致)⇒
reset_password只重算f_password(src/tdc/service/account.rs:576)。 - 一次性换算单向不可逆:
f_password = md5(lower(旧裸 md5 hex) || lower(新 secretkey))⇒ 从旧的裸 md5 换到新公式,需要旧 md5(前端手里那份)+ 新 secretkey; 拿明文反推也可以,但拿旧的f_password反推不出来。 - 别把裸 md5 当口令存:裸 md5 一旦泄漏即可直接当口令用(上游公式正是为了这个)。
自证(不是自证自洽)
src/tdc/service/account.rs 的单测 official_password_hash_matches_the_upstream_formula
用两个独立向量(用系统 md5 算出来的,不是本仓代码算的):
| secretkey | 期望 f_password |
|---|---|
A1B2C3D4 |
f5aed9cb34072037071de9e90f3ef650 |
00-11-22 |
cf1150bde4e2f01f1f0a4558a800cbb0 |
(md5("123456") = e10adc3949ba59abbe56e057f20f883e)
另有一道跨端防线:tests/account_api.rs::login_accepts_the_upstream_literal_ciphertext
拿上游的字面密文真打登录端点(改密钥它必红)。
3. 引导(幂等)
src/tdc/service/account.rs:621(bootstrap_account_layer):
- 种三个角色(照抄上游
V1.0.1__connector_seed.sql,含固定 id):tdcProvider/tdcConsumer/user(WHERE NOT EXISTS⇒ 幂等)。 base_user有没有存活行?有 ⇒ 不引导(幂等,不覆盖既有账号); 无 ⇒ 建一个管理员:f_account=TDC_BOOTSTRAP_ADMIN_ACCOUNT(默认admin)、f_is_administrator=1、f_enabled_mark=1、口令按上面公式入库。- 管理员绑角色:
base_role_relation写一行,绑user角色。
🔴 全程持 db_lock ⇒ 进程内串行(pglite 单 backend)。
🔴 默认口令是公开已知的
admin / admin ⇒ 本地调试默认值。
TDC_STRICT_SECRETS=1⇒ 启动时若管理员仍在用默认口令 ⇒ 拒绝启动 (src/main.rs+src/tdc/service/account.rs:753)。- 部署前必须改口令(走
POST /api/permission/Users/{id}/Actions/ResetPassword)。
4. 管理员位(fail-closed)
| 项 | 口径 |
|---|---|
| 判据 | base_user.f_is_administrator = 1 且 (f_delete_mark IS NULL OR f_delete_mark = 0) |
| 代码 | src/tdc/service/account.rs:289(is_administrator) |
| 异常处理 | 查询出错 ⇒ false(fail-closed)⇒ 宁可拒绝,不可误放行 |
| 用途 | 守 /api/permission/Users* 6 个端点(src/tdc/controller/account.rs:149,require_admin) |
require_admin 的放行口径:
| 主体 | 结果 |
|---|---|
连接器身份会话(Principal::Session) |
✅ 放行(上游同款:身份本身就是管理员) |
本地账号会话(Principal::Account) |
查 f_is_administrator ⇒ 1 才放行 |
内部令牌(Principal::Internal) |
❌ 403「仅管理员可管理连接器用户」(比上游严一档,刻意) |
| 无凭证 | ❌ 401「内部接口凭证无效」 |
🔴 管理员账号不可删:remove() 遇 administrator == true ⇒ 业务失败
「管理员账号不可删除」(src/tdc/service/account.rs:513)。
5. 角色码
src/tdc/service/account.rs:320(role_codes)—— 逐字照抄上游 SQL:
SELECT b.f_en_code FROM base_role b
JOIN base_role_relation r ON r.f_role_id = b.f_id
WHERE r.f_object_type = 'user' AND r.f_object_id = ?
AND (b.f_delete_mark IS NULL OR b.f_delete_mark = 0)
AND b.f_en_code IN ('tdcProvider','tdcConsumer','tdsReadOnly')
- 暴露在
GET /api/ssw/tdc/Auth/Me的roles键(上游AuthController#me:207同款) ⇒src/tdc/service/identity.rs:360(me_payload)。 - 只对账号会话算(上游只有门户登录这一路算角色)⇒ 身份会话返回空数组。
🔴 悬空码(上游自身的不一致,照抄)
tdcProvider |
tdcConsumer |
tdsReadOnly |
user |
|
|---|---|---|---|---|
判据(IN 列表) |
✅ | ✅ | ✅ | ❌ |
种子(SEED_ROLES) |
✅ | ✅ | ❌ | ✅ |
⇒ 引导管理员绑的是 user 角色 ⇒ 它的 roles 数组是空的。
这不是 bug,是上游口径(决策 D9)。
6. 出参形状(不变)
/api/permission/Users 每一行(src/tdc/controller/account.rs:127,account_view):
{ "id", "account", "realName", "gender", "mobilePhone", "enabledMark", "creatorTime", "description" }
- 🔴 不得回显
f_password/f_secretkey(出参整条删键,不是置 null)。 gender是数字(上游列是varchar(50)⇒ 存数字文本、读时解析成i64,默认 0)。mobilePhone/description空串落 SQL NULL ⇒ 出参是null不是""(src/tdc/service/account.rs:169,opt_p)。creatorTime是to_char(f_creator_time,'YYYY-MM-DD HH24:MI:SS')的字符串 (服务器本地时区,见docs/contract.md§时间口径)。
7. 自检
# 账号层真的在库里
curl -s --noproxy '*' http://127.0.0.1:30000/api/health # ⇒ baseTables = 3
# 登录(口令公式端到端)
bash scripts/smoke.sh # ⇒ PASS=80 FAIL=0
# 口令公式的两个独立向量
cargo test --lib official_password_hash