把 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]>
181 lines
7.8 KiB
Markdown
181 lines
7.8 KiB
Markdown
# 账号层(`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
|
||
```
|