Files
tdc-rs/docs/ACCOUNT-LAYER.md
T
adminandClaude Code 2e7f9b1975 feat(b5): 工程化外壳(文档层)—— 契约四件套 + 两本手册 + 第四把尺子
把 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]>
2026-10-27 00:56:09 +08:00

7.8 KiB
Raw Blame History

账号层(base_user)契约

🔴 本文件讲账号层:载体是什么、口令怎么算、管理员位怎么判、角色码怎么取。 上游对照物 = JNPF j7 的 base_user / base_role / base_role_relation 三张表

  • 上游 PasswordTokenGranter 的口令算法。 与 docs/contract.md(对外形状)/ docs/known-limitations.md L4(权限敞开)配套读。

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

🔴 三条容易踩的

  1. 改密不换 secretkey(与官方一致)⇒ reset_password 只重算 f_password (src/tdc/service/account.rs:576)。
  2. 一次性换算单向不可逆:f_password = md5(lower(旧裸 md5 hex) || lower(新 secretkey)) ⇒ 从旧的裸 md5 换到新公式,需要旧 md5(前端手里那份)+ 新 secretkey; 拿明文反推也可以,但拿旧的 f_password 反推不出来。
  3. 别把裸 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):

  1. 种三个角色(照抄上游 V1.0.1__connector_seed.sql,含固定 id): tdcProvider / tdcConsumer / user(WHERE NOT EXISTS ⇒ 幂等)。
  2. base_user 有没有存活行?有 ⇒ 不引导(幂等,不覆盖既有账号); 无 ⇒ 建一个管理员: f_account = TDC_BOOTSTRAP_ADMIN_ACCOUNT(默认 admin)、 f_is_administrator=1、f_enabled_mark=1、口令按上面公式入库。
  3. 管理员绑角色: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