文档分层:随代码演进的技术文档入 git(团队 clone 可得、有版本与评审); 决策档案与含商务内容的治理文档留工作区 docs/(不随仓库分发,外包 clone 不携带)。 全部交叉引用已更新(README×2/实测报告×2/登记表/pom/ArchUnit 注释) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
12 KiB
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-corepom 显式引入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) 落地,读路径真实走引擎:
- ROLES 列元数据:
REFERENCEID='LIST'(⇒ displayType=LIST、ColumnClass=List.class),REFERENCEVALUE指向一条SYS_REFERENCEVALUE。 - SYS_REFERENCEVALUE 解析(
DataDicServiceImpl.getEntityTableNameByReferenceValue/getColumnNameByReferenceValue两条 JOIN):ENTITYID→SYS_ENTITY.TABLENAME=SYS_FILTERRULEROLE(中间表,tabletype=2,恰 2 列)ENTITYATTRIBUTEID→SYS_ENTITYATTRIBUTE.COLUMNNAME=FILTERRULEID(回引 SYS_FILTERRULE 的列)
- 加载(
POJOServiceImpl.loadPOJO(isHierarchical=true)→hierarchicalQuery,源码 1256-1262):对 LIST 列查SELECT * FROM SYS_FILTERRULEROLE WHERE FILTERRULEID = '<规则id>',把「另一列」ROLEID的全部值收集成List<String>,经updateHierarchicalValue设回 ROLES。 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 之后追加)。
内容:
- 物理表:
SYS_FILTERRULE(规则主表,FILTERRULE 用text存 JSON、ROLES 为 LIST 不落物理列)+SYS_FILTERRULEROLE(中间表,恰 2 列)。 - 自描述元数据:两实体进
SYS_ENTITY(SYS_FILTERRULEROLE tabletype=2)+ 各列进SYS_ENTITYATTRIBUTE;ROLES 列 LIST + REFERENCEVALUE 三件套(SYS_REFERENCE+SYS_REFERENCEVALUE)。 - 受控实体 CREATEBY 重分区:ParitySeeder 把 EIP4PT_TASK/PROJECT/CUSTOMER 的 50 行 CREATEBY 全置 'ADMIN';脚本按行序 %3 改成
USER_ALICE/USER_BOB/USER_CAROL(确定性、幂等),使CREATEBY = {CURRENTUSERID}过滤可判别。分布(每实体):ALICE 16、BOB 17、CAROL 17。 - 过滤规则:为 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)
- ROLES 多值列经 LIST + 中间表落地(§5.8):多值列不落物理列,值在中间表;需 LIST + REFERENCEVALUE + SYS_REFERENCE + 中间表(恰 2 列、回引列在前)四要素齐备,且读路径走
loadPOJO(...,isHierarchical=true)才展开 List。 - 行级过滤仅在非 ADMIN 上下文触发(§5.9):
listSelectSpecialCol判断ctx.CURRENTUSER != ADMIN才调过滤;ADMIN 天然看全量。验证必须构造非 ADMIN ctx(本 C2 经 EntityController 的 asUser/roles 可选参实现)。 - DataFilterHelper 用 Jackson 1.x(§5.10):原版
org.codehaus.jackson,保真纪律不改写为 Jackson 2,显式引jackson-mapper-asl:1.9.13与 Jackson 2 共存。 - 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}(回归)