Files
eip4-platform/platform-auth/C2实测报告.md
zhengwr c2b3c5004f docs: 技术文档随仓库——架构设计/迁移手册/C3基线/C5报告迁入 docs/
文档分层:随代码演进的技术文档入 git(团队 clone 可得、有版本与评审);
决策档案与含商务内容的治理文档留工作区 docs/(不随仓库分发,外包 clone 不携带)。
全部交叉引用已更新(README×2/实测报告×2/登记表/pom/ArchUnit 注释)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-11 11:26:44 +08:00

169 lines
12 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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.
# EIP4 M0 任务 C2 实测报告 —— 数据权限最小真实现替换桩
> 工程:eip4-platform · 环境:本地 PG 15 `localhost:5433/eip4m0`,服务 profile=local @8084
> 时间:2026-06-11 · 通过标准:**≥3 个行级过滤实体进对拍样本且通过**
## 一、结论速览
| 项 | 结果 |
|----|------|
| 三文件移植 + Jackson 1.x 依赖 + 删桩 | ✅ 全模块 `mvn clean install` 通过 |
| ArchUnit 架构纪律(保真层禁止依赖现代层) | ✅ 仍绿(1/1) |
| 单测(DataFilterHelper JSON 互转 + getWhereClause 拼接) | ✅ 9 用例全过(要求 ≥6) |
| **行级过滤对拍(3 受控实体 × 3 用户 = 9 正例)** | ✅ **9/9 逐行一致,150 行 100%** |
| 负例(无命中角色 → PrivilegeException) | ✅ 3/3 全部被拒(HTTP 500) |
| 回归(ParityCli `--all`) | ✅ **21/21 实体、1108 行 100% 逐行一致** |
对拍报告产物:`parity-reports/privilege-parity-20260611-000631.{json,md}`(正例 9/9 一致 + 负例 3/3 被拒);
回归报告:`parity-reports/parity-20260611-000638.{json,md}`(21/21)。
---
## 二、移植清单(保真层 platform-legacy-core,包名原样)
| 文件 | 来源(framework) | 目标(platform-legacy-core) | 说明 |
|------|------|------|------|
| `DataPrivilegeServiceImpl.java`(226 行) | `com.dsasp.server.privilege.service` | 同包 | `@Service("dataPrivilegeService")`,原样移植,一行未改 |
| `DataFilterHelper.java`(110 行) | `com.dsasp.server.privilege.bean` | 同包 | FILTERRULE JSON 互转,用 Jackson 1.x |
| `MethodSecurityInterceptor.java`(18 行) | `com.dsasp.server.common.privilege.bean` | 同包(原已有 Conditional/DataFilterRule/DataPrivilege) | 注解,被 Impl 引用;无处理器亦无害 |
依赖既有(legacy-core 已具备,未新增):`Conditional` / `DataFilterRule` / `DataPrivilege` bean、`DataPrivilegeService` 接口、`POJOCRUDService`、`AbstractPOJOInfo`、`SpringBeanOsgiServices`、`SysConfig`、`StringUtil`、`UserSession`、`LoggedInUser`、`PrivilegeException` / `ValidationException`。
**删桩**:删除 `platform-auth` 的 `com.eip4.platform.auth.stub.StubDataPrivilegeService`(与新 `@Service("dataPrivilegeService")` 重名,双 Bean 冲突);其余 4 个桩保留。`platform-auth/README.md` 记录 dataPrivilegeService 已由保真层接管、P2 在此模块做组织/权限整体真实现。
**组件扫描**:`Eip4PlatformApplication` 已 `scanBasePackages={"com.eip4.platform","com.dsasp"}`,移植的 `@Service` 自动被扫描;`POInfo.getDataFilterRules()` 经 `SpringBeanOsgiServices.getBeanByName("dataPrivilegeService")` 取到真实现。服务启动无 Bean 冲突,证明删桩到位。
---
## 三、Jackson 1.x 依赖决策
- `DataFilterHelper` 原版用 `org.codehaus.jackson.*`(Jackson 1.x:`ObjectMapper`/`JsonNode`/`ArrayNode`)做 `FILTERRULE`(Conditional[])的 JSON 序列化/反序列化。
- 保真层纪律「com.dsasp 旧代码一行不改」⇒ **不改写为 Jackson 2**。
- 在父 pom `dependencyManagement` 与 `platform-legacy-core` pom 显式引入 `org.codehaus.jackson:jackson-mapper-asl:1.9.13`(传递带 `jackson-core-asl`)。
- Jackson 1.x(`org.codehaus.jackson`)与现代层 Jackson 2(`com.fasterxml.jackson`)包名不同,**共存不冲突**;现代层(EntityController/对拍 CLI)序列化仍用 Jackson 2。
---
## 四、ROLES 多值落地机制(查明结论)
`SYS_FILTERRULE.ROLES` = 「一条规则关联多个角色」的多值列,引擎按 **LIST 显示类型 + 中间表(MIDTABLE)** 落地,**读路径真实走引擎**:
1. **ROLES 列元数据**:`REFERENCEID='LIST'`(⇒ displayType=LIST、ColumnClass=List.class),`REFERENCEVALUE` 指向一条 `SYS_REFERENCEVALUE`。
2. **SYS_REFERENCEVALUE 解析**(`DataDicServiceImpl.getEntityTableNameByReferenceValue` / `getColumnNameByReferenceValue` 两条 JOIN):
- `ENTITYID` → `SYS_ENTITY.TABLENAME` = **`SYS_FILTERRULEROLE`**(中间表,tabletype=2,恰 2 列)
- `ENTITYATTRIBUTEID` → `SYS_ENTITYATTRIBUTE.COLUMNNAME` = **`FILTERRULEID`**(回引 SYS_FILTERRULE 的列)
3. **加载**(`POJOServiceImpl.loadPOJO(isHierarchical=true)` → `hierarchicalQuery`,源码 1256-1262):对 LIST 列查
`SELECT * FROM SYS_FILTERRULEROLE WHERE FILTERRULEID = '<规则id>'`,把「另一列」`ROLEID` 的全部值收集成 `List<String>`,经 `updateHierarchicalValue` 设回 ROLES。
4. `DataFilterHelper.converToDataFilterRule` 的 `po.get_Value("ROLES")` 即拿到该 `List<String>`。
> 即「子表 sys_filterrulerole(filterruleid 列)」口径成立:中间表的回引列就是 `FILTERRULEID`,取值列是 `ROLEID`,引擎用回引列定位、取另一列成 List。
**自举落法**:本地用 `bootstrap-privilege.sql` **优先按引擎读路径口径直接建模 + 直插中间表行**(中间表恰 2 列、tabletype=2、SYS_REFERENCE/SYS_REFERENCEVALUE 三件套齐备),读路径完全经引擎 `loadPOJO(...,true)` 展开 List,与原版加载机制一致。DB 实证:
```
ROLES 列 : REFERENCEID=LIST, REFERENCEVALUE=d1000000-...-0001
referencevalue 解析 → midtable=SYS_FILTERRULEROLE, backref_col=FILTERRULEID
中间表行 : f1...0001|ROLE_TASK f1...0002|ROLE_PROJECT f1...0003|ROLE_CUSTOMER
```
---
## 五、自举扩展(bootstrap-privilege.sql)
位置:`platform-parity/src/main/resources/bootstrap/bootstrap-privilege.sql`(幂等,可重复执行;在 C1 的 bootstrap-sys.sql + ParitySeeder 之后追加)。
内容:
1. **物理表**:`SYS_FILTERRULE`(规则主表,FILTERRULE 用 `text` 存 JSON、ROLES 为 LIST 不落物理列)+ `SYS_FILTERRULEROLE`(中间表,恰 2 列)。
2. **自描述元数据**:两实体进 `SYS_ENTITY`(SYS_FILTERRULEROLE tabletype=2)+ 各列进 `SYS_ENTITYATTRIBUTE`;ROLES 列 LIST + REFERENCEVALUE 三件套(`SYS_REFERENCE` + `SYS_REFERENCEVALUE`)。
3. **受控实体 CREATEBY 重分区**:ParitySeeder 把 EIP4PT_TASK/PROJECT/CUSTOMER 的 50 行 CREATEBY 全置 'ADMIN';脚本按行序 %3 改成 `USER_ALICE`/`USER_BOB`/`USER_CAROL`(确定性、幂等),使 `CREATEBY = {CURRENTUSERID}` 过滤可判别。分布(每实体):ALICE 16、BOB 17、CAROL 17。
4. **过滤规则**:为 3 个实体各配 1 条 `[{"preConditional":"CREATEBY","sign":"=","backConditional":"{CURRENTUSERID}","type":"CURRENTUSERID"}]` 规则(规则 ENTITYID 动态 `SELECT FROM sys_entity`),各关联 1 个角色(ROLE_TASK/ROLE_PROJECT/ROLE_CUSTOMER,经中间表)。
> 选 CREATEBY(char(36))作过滤列:种子实体均有此列且语义贴合「只看自己创建的行」;PG bpchar 比较忽略尾空格,引擎 `P.CREATEBY='USER_ALICE'` 与基线 `WHERE createby='USER_ALICE'` 同语义。规则用 CURRENTUSERID 等值类型,不触达 SysConfig/OWNNERPROJECT 路径。
---
## 六、对拍样本与数字(--privilege 模式)
新增 `platform-parity` 的 `--privilege` 模式(`ParityCli` + `PrivilegeCheckRunner` + `EngineHttpClient` 增 asUser/roles 透传)。
驱动方式:`EntityController.list` 增可选 `asUser`/`roles` 查询参,构造**非 ADMIN** ctx(CURRENTUSER + ROLES List)触发引擎行级过滤(引擎仅 `ctx.CURRENTUSER != ADMIN` 时才调 getWhereClause)。
- **被测侧**:`GET /api/entity/{t}/list?asUser=U&roles=R` → 引擎 `POJOCRUDServiceImpl.listSelect` → `dataPrivilegeService.getWhereClause` 拼 `AND (...)` 注入 WHERE。
- **基线侧**:直连 JDBC `SELECT * FROM t WHERE createby = 'U'`(同语义 ground truth)。
- **比对**:复用 C1 的 `RowDiff` 逐行逐列(行序无关、主键配对、char 尾空格/numeric/时间戳归一)。
### 正例(3 实体 × 3 用户 = 9 例,逐行 diff)
| 实体[用户] | 引擎行数 | JDBC 行数 | 逐行一致率 | 结果 |
|---|---|---|---|---|
| EIP4PT_CUSTOMER[USER_ALICE] | 16 | 16 | 1.0000 | ✅ |
| EIP4PT_CUSTOMER[USER_BOB] | 17 | 17 | 1.0000 | ✅ |
| EIP4PT_CUSTOMER[USER_CAROL] | 17 | 17 | 1.0000 | ✅ |
| EIP4PT_PROJECT[USER_ALICE] | 16 | 16 | 1.0000 | ✅ |
| EIP4PT_PROJECT[USER_BOB] | 17 | 17 | 1.0000 | ✅ |
| EIP4PT_PROJECT[USER_CAROL] | 17 | 17 | 1.0000 | ✅ |
| EIP4PT_TASK[USER_ALICE] | 16 | 16 | 1.0000 | ✅ |
| EIP4PT_TASK[USER_BOB] | 17 | 17 | 1.0000 | ✅ |
| EIP4PT_TASK[USER_CAROL] | 17 | 17 | 1.0000 | ✅ |
**汇总**:正例 9/9 全一致,总比对 **150 行 100% 逐行一致**;实体级与单元格级零差异。
### 负例(无命中角色 → PrivilegeException)
用错误角色 `ROLE_NOBODY` 访问 3 个受控实体(规则存在但无角色命中):
| 实体 | HTTP 状态 | 期望 | 结果 |
|---|---|---|---|
| EIP4PT_CUSTOMER | 500 | 非200(PrivilegeException) | ✅ 被拒 |
| EIP4PT_PROJECT | 500 | 非200(PrivilegeException) | ✅ 被拒 |
| EIP4PT_TASK | 500 | 非200(PrivilegeException) | ✅ 被拒 |
服务端日志证据(原版语义,`getWhereClause` 的 first 分支抛出):
```
com.dsasp.server.common.exception.PrivilegeException: 没有任务数据访问权限
```
### 回归(ParityCli --all,无规则实体不受影响)
`--all` 用 ADMIN 视角读全部 21 个 EIP4PT_* 实体:**21/21 实体、1108 行 100% 逐行一致**(无规则实体不被过滤;3 个受控实体在 ADMIN 视角同样返回全量,CREATEBY 重分区不破坏与物理事实的逐行一致)。
---
## 七、单测(platform-legacy-core,9 用例)
`com.dsasp.server.privilege.DataPrivilegeTest`(+ 测试用 `FakePOInfo`,经反射注入 `AbstractPOJOInfo` 静态缓存,绕开 DB/Spring):
- JSON 互转:单条往返、多条往返(含 op=OR/AND)、null/空/`"null"`/`[]` 归零、非法 JSON 抛异常 —— 4 例。
- getWhereClause 拼接:单角色命中(`P.OWNER ='USER_ALICE'`)、多规则命中 OR 连接(CURRENTUSER + CURRENTUSERDEPART)、无角色命中抛 PrivilegeException(含表显示名)、SYS_FILTERRULE 表返回 null、无规则实体返回 null —— 5 例。
`Tests run: 9, Failures: 0, Errors: 0`。
---
## 八、与 P2 真实现的关系
- **本实现即原版语义**:行级过滤算法、ROLES 多值落地、规则装载、CURRENTUSER/DEPART/ORG/SPECIAL/OWNNERPROJECT 各分支均原样移植自 framework,语义零偏移。
- **P2 增量**:在保真层这套引擎语义之上,接入**真实组织机构数据源**(部门/机构/用户-角色关系)与**角色/过滤规则的管理 UI**,落在 `platform-auth`。P2 不改写过滤算法,只提供「规则与角色从哪来、谁来维护」。
- C2 已把 `dataPrivilegeService` 从「桩(不过滤)」升级为「真实现(原版过滤)」,P2 接手时数据权限内核已就位。
---
## 九、遇到的坑(已同步《eip4-platform/docs/迁移手册.md》§5.8/5.9/5.10)
1. **ROLES 多值列经 LIST + 中间表落地**(§5.8):多值列不落物理列,值在中间表;需 LIST + REFERENCEVALUE + SYS_REFERENCE + 中间表(恰 2 列、回引列在前)四要素齐备,且读路径走 `loadPOJO(...,isHierarchical=true)` 才展开 List。
2. **行级过滤仅在非 ADMIN 上下文触发**(§5.9):`listSelectSpecialCol` 判断 `ctx.CURRENTUSER != ADMIN` 才调过滤;ADMIN 天然看全量。验证必须构造非 ADMIN ctx(本 C2 经 EntityController 的 asUser/roles 可选参实现)。
3. **DataFilterHelper 用 Jackson 1.x**(§5.10):原版 `org.codehaus.jackson`,保真纪律不改写为 Jackson 2,显式引 `jackson-mapper-asl:1.9.13` 与 Jackson 2 共存。
4. **bootstrap 清理顺序**:首次执行 `DELETE FROM sys_filterrulerole` 会因表不存在报错;改为只 `DROP TABLE IF EXISTS ... CASCADE`(行随表清),元数据 DELETE 保留(持久表)。
---
## 附:产物清单
- 移植:`platform-legacy-core/.../privilege/service/DataPrivilegeServiceImpl.java`、`.../privilege/bean/DataFilterHelper.java`、`.../common/privilege/bean/MethodSecurityInterceptor.java`
- 依赖:父 pom + `platform-legacy-core/pom.xml` 增 `jackson-mapper-asl:1.9.13`;legacy-core 增 `spring-boot-starter-test`(test)
- 删桩 + 文档:删 `StubDataPrivilegeService.java`;新增 `platform-auth/README.md`
- 自举:`platform-parity/src/main/resources/bootstrap/bootstrap-privilege.sql`
- 对拍:`platform-parity/.../selfcheck/PrivilegeCheckRunner.java`;`ParityCli` 增 `--privilege`;`EngineHttpClient` 增 asUser/roles 透传 + statusOf
- 驱动:`platform-metadata/.../web/EntityController.java` 增 asUser/roles 可选参
- 单测:`platform-legacy-core/src/test/.../privilege/DataPrivilegeTest.java` + `FakePOInfo.java`
- 报告:本文件 + `parity-reports/privilege-parity-*.{json,md}` + `parity-reports/parity-*.{json,md}`(回归)