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

181 lines
7.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 账号层(`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:
```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`):
```json
{ "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. 自检
```bash
# 账号层真的在库里
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
```