Files
eip4-platform/platform-metadata/P4衔接-picker与schema接口报告.md
zhengwr e49b39f0cf P4-4: picker 选择窗数据源 + page schema 服务化两端点
- PickerController GET /api/picker/{entityOrRef}/list?q&page&perPage:
  契约定稿——dialogid 实为 view_template_id(侦察客户库纠偏,非 SYS_REFERENCE_ID),
  按 view_template根@entityid → ref → 直连实体表名三级解析;全入参过 P1-3 白名单,
  搜索值转义防 LIKE 裸拼注入,行级权限 ctx 三级优先(与 EntityController 同口径);
  返回 amis options/CRUD 双格式。转换器 source 生成零改动(契约对接落后端解析)。
- PageSchemaController GET /api/page/schema/{templateId}:带 ETag/304,404/503;
  与 eip4-web VITE_SCHEMA_SOURCE=backend 联调渲染通过。
- SYS_PAGE_SCHEMA 平台表(bootstrap SQL + 生产 DDL 落 docs,Flyway 引入列 P5);
  SchemaImportCli 把 1489 个转换产物幂等入库(etag=sha-256)。
- 单测 +19(picker 9/schema 7/导入 3),全模块 mvn install + ArchUnit 绿。
- 新坑进迁移手册 §8.7(dialogid=view_template_id)/§8.8(GeneralPO LIKE 裸拼)/§8.9(SYS_PAGE_SCHEMA)。

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

13 KiB
Raw Permalink Blame History

P4 衔接:选择窗数据源(picker)与页面 schema 接口报告

日期:2026-06-11 | 作者:platform-metadata 工作线(P4-4) 工程:eip4-platform/platform-metadata(JDK17) 数据源:本地 M0 库 localhost:5433/eip4m0(可写,平台表落地);客户库 192.168.20.68:5435/postgres?currentSchema=eip3(ceshi/ceshi,只读,侦察 picker 契约用) 前序:platform-converter/P4批量转换报告.md(937+138+50=1125 个模板的 SelectDialog→select+source「待联动」,等本端点)


一、一句话结论

两个切流前公共端点落地并实测通过:

  • 选择窗数据源 GET /api/picker/{entityOrRef}/list?q=&page=&perPage=:解析弹窗数据源实体 → amis options/CRUD 双格式下发,全入参过白名单、搜索转义、行级权限 ctx 生效。
  • 页面 schema GET /api/page/schema/{templateId}:转换产物 1489 个入库 SYS_PAGE_SCHEMA 后服务化下发,带 ETag/304;前端 VITE_SCHEMA_SOURCE=backend 切到接口模式渲染成功(playwright 截图)。

单测新增 19 个(picker 9 + schema 7 + 导入 CLI 3),全模块 mvn install + ArchUnit 绿(8 模块 BUILD SUCCESS,78 个 metadata 测试通过)。


二、契约定稿(关键:与转换器产物对得上)

2.1 picker 契约 —— dialogid 实为 view_template_id(侦察纠偏)

转换器 UiTypeMapper(123/131 行)把 SelectDialog/MultiSelectDialog 的 source 生成为 /api/picker/{dialogid}/list,其中 dialogid = <field> 的 dialogid 属性原样值。

初判 dialogid 是 SYS_REFERENCE_ID(转换器注释如此写),侦察客户库实测推翻:

侦察项 结论
提取转换产物全部 picker source 的 dialogid 244 个唯一 dialogid(覆盖 1125 个待联动模板的弹窗字段)
在 sys_reference.sys_reference_id 反解 0 命中(全部未解析)
在 view_template.view_template_id 命中 命中——dialogid 是被引用的列表模板 id
被引用模板 XML 根元素 <crud ... entityid="...">,根 @entityid 才是弹窗数据源实体
高频 5 个 dialogid 经「模板根 @entityid → SYS_ENTITY」解析 PM_PROJECT / SYS_ORG / VIEW_SYS_USER(真实实体,全部解析成功)

定稿口径:path 变量 entityOrRef 按优先级解析为实体表名——

  1. view_template_id(转换器产物主路径,覆盖全部存量 source)→ 读其 xml::text 根 @entityid → DataDicService.getSYSEntity(entityId).getPo().get_Value("TABLENAME");
  2. SYS_REFERENCE_ID(兼容旧引擎引用语义)→ getReferenceEntityTableName 反解;
  3. 实体表名(直接以实体作数据源)→ 直接命中。

与转换器产物对得上:转换器 source 生成零改动(dialogid 即模板里原样属性值,端点带 /list 后缀与全部存量 source 对齐)。无需小改转换器、无需重跑模板闸一抽验——契约对接点全部落在后端解析路径,是更小的改动面。

2.2 picker 响应格式(amis options/CRUD 双兼容)

{ "status":0, "msg":"", "data": {
    "options": [ {"label":"系统管理员组","value":"b0000000-...001"}, ... ],  // amis select 的 source 直接消费
    "items":   [ {"_id":"b0000000-...001","NAME":"系统管理员组", ...}, ... ], // amis crud/picker 内嵌 CRUD 消费
    "total":   3
} }
  • value = 实体主键(_id);label = 标识列(isidentifier)→ 显示列(getDisplayIndex)→ 首个非主键 String 列,三级回退;都没有则 label 回落主键值。
  • 入参:q(按标识列模糊搜索,转义后下推)、page/perPage(分页)、asUser/roles/asDepart/asOrg(行级权限测试通道,与 EntityController 同口径)。

2.3 schema 契约(与 eip4-web/src/api/schema.ts 对齐)

GET /api/page/schema/{templateId}
  200  直接返回 amis 页面 schema(JSON,顶层 type:page),带强 ETag
  304  If-None-Match 命中当前 ETag(空体,省重复下发)
  404  模板不存在(SYS_PAGE_SCHEMA 无该 templateId)
  503  schema 存储不可用(SYS_PAGE_SCHEMA 表缺失/库异常 ≈「转换器/产物不可用」)
  鉴权:带 Bearer(非 prod profile 不强制)

ETag = schema_json 的 sha-256 hex(入库时算,与导入 CLI 同源)。


三、SYS_PAGE_SCHEMA 平台表与导入

3.1 建表(架构条款:平台表 Flyway 管,业务表引擎管)

本工程尚未引入 Flyway。本期按「bootstrap SQL + 生产建表脚本落 docs」落地,Flyway 引入列 P5 待办:

产物 路径 用途
本地/CI 自举建表 platform-metadata/src/main/resources/bootstrap/bootstrap-page-schema.sql CREATE TABLE IF NOT EXISTS,幂等,psql 灌
生产建表脚本 docs/sql/SYS_PAGE_SCHEMA.sql 注释写明 P5 引 Flyway 时原样改名 V{n}__create_sys_page_schema.sql
CLI 自举兜底 SchemaImportCli.CREATE_DDL 导入时 CREATE TABLE IF NOT EXISTS 兜底(本地/CI 库未跑 bootstrap 也能用)

表结构:template_id(PK) / name / schema_json(jsonb) / schema_etag(sha-256) / version / update_time(epoch ms)。

3.2 导入数量

SchemaImportCli 把 platform-converter/转换产物/schema/*.json(1489 个)批量入库:

SchemaImportCli 导入汇总: 扫描 1489 个产物, 入库/更新 1489 个, 内容未变跳过 0 个
(幂等复跑:扫描 1489 个产物, 入库/更新 0 个, 内容未变跳过 1489 个)
  • 入库 1489 个(= 闸一通过的全部转换产物),全部带名称(取自 分级清单.csv 的 view_template_id→name)。
  • 幂等:ON CONFLICT (template_id) DO UPDATE ... WHERE etag 不同——内容未变 0 行影响(不膨胀版本)。

四、验证证据

4.1 picker 端点(8086 本地库 eip4m0)

用例 请求 结果
直接实体表名 GET /api/picker/SYS_USERGROUP/list?perPage=3 200,3 options(系统管理员组/项目管理组/审批归档组)+ items + total=3
view_template_id 主路径 seed 测试模板(root @entityid→SYS_USERGROUP)GET /api/picker/{tid}/list 200,解析到 SYS_USERGROUP,3 options
ref→entity 解析 seed 测试 reference(→SYS_USERGROUP)GET /api/picker/{refid}/list 200,3 options(证 SYS_REFERENCE_ID 退化路径可用)
搜索 ?q=系统 total=1,仅「系统管理员组」(LIKE 标识列下推)
分页 ?page=2&perPage=2 total=3,第 2 页 1 条(审批归档组)
白名单负例 GET /api/picker/NOPE_INJECT' OR 1=1--/list HTTP 400 {status:1,msg:...}(不回显载荷)
无主键引用实体 ref→SYS_FILTERRULEROLE(MIDTABLE 无 PK) HTTP 400「引用实体不可作选择窗数据源(无主键)」
搜索注入负例 ?q=' OR 1=1-- HTTP 200 空结果(转义生效,非 500/注入)
行级权限 ctx ?asUser=alice&roles=r1 200(非 ADMIN 视角传引擎,触发行级过滤路径)

客户库(只读)侦察 ≥3 个真实引用实体:5 个高频 dialogid 经「view_template 根 @entityid」解析到 PM_PROJECT / SYS_ORG / VIEW_SYS_USER(真实实体),契约口径在客户库实数据上成立。

4.2 schema 端点 + 前端联调

用例 请求 结果
命中 200 GET /api/page/schema/d33af663-...(角色维护) 200,顶层 type:page,带强 ETag "7c226f99..."
304 同上带 If-None-Match: "7c226f99..." HTTP 304 空体
404 GET /api/page/schema/not-a-real-template-id HTTP 404「模板不存在」

前端切换联调(eip4-web):

  • 起 dev server:VITE_SCHEMA_SOURCE=backend VITE_BACKEND_TARGET=http://localhost:8086 npm run dev -- --port 5174;
  • 注入 JWT(app 密钥 HS256 自签,已实测被 JwtAuthFilter 接受)过路由守卫;
  • 导航 /page/d33af663-...(角色维护,真实转换产物 templateId,不在 mock MAP,只能来自后端);
  • 结果:amis 渲染成功——52 个 amis DOM 节点,可见「测试/查询/角色名称/描述/搜索」表单+表格,0 schema 加载错误;
  • 经 PerformanceResourceTiming 确认请求落在 /api/page/schema/d33af663-...(XHR,backend 模式),非 /schemas/*.json 静态 mock;
  • 截图:platform-metadata/P4衔接证据/schema-backend-render.png。
  • (页面内 2 个 console error 是 amis CRUD 数据拉取 /api/flow/SYS_ROLE_SEARCH 500——M0 库未种该服务流,属数据缺失,与 schema 接口无关;schema 已正确下发并渲染。)

4.3 单测 + 全模块绿

[INFO] PickerControllerTest      Tests run: 9, Failures: 0, Errors: 0
[INFO] PageSchemaControllerTest  Tests run: 7, Failures: 0, Errors: 0
[INFO] SchemaImportCliTest       Tests run: 3, Failures: 0, Errors: 0
[INFO] platform-metadata 全模块   Tests run: 78, Failures: 0, Errors: 0
[INFO] ArchitectureRulesTest     Tests run: 1, Failures: 0, Errors: 0   (保真层禁依赖现代层)
[INFO] Reactor: legacy-core/converter/metadata/auth/flow-gateway/ai/parity/app 全 BUILD SUCCESS

五、安全落地(全入参过白名单 + 搜索参数化 + 行级权限)

关注点 落地
标识符白名单(P1-3) 解析出的表名经 IdentifierWhitelist.requireLegalTable;非法实体 → 400(不进引擎拼接)
搜索参数化 q 经 escapeLikeValue(单引号双写防注入、%/_/\ 剔除防通配符逃逸)才进引擎 LIKE 裸拼点(GeneralPO.java:1940 String 条件无参数绑定,见手册 §8.8)
排序/分页 分页用引擎 PAGE_START/PAGE_SIZE 数值键,无标识符拼接面
行级权限 ctx 三级优先(asUser 测试通道 → JWT 绑定的请求级上下文 → ADMIN 默认),与 EntityController 同 buildCtx 口径,非 ADMIN 触发引擎行级过滤
不回显载荷 白名单异常文案只报「哪类参数+哪个实体」,表名回显只放行 [A-Z0-9_](IllegalIdentifierException + Handler 既有设施)

六、git 提交

只 add 本线自有文件(不碰 converter 脚本挂回线、flow-gateway 领地;本次未改 converter source 生成):

  • platform-metadata/src/main/java/com/eip4/platform/metadata/web/PickerController.java
  • platform-metadata/src/main/java/com/eip4/platform/metadata/web/PageSchemaController.java
  • platform-metadata/src/main/java/com/eip4/platform/metadata/schema/SchemaImportCli.java
  • platform-metadata/src/main/resources/bootstrap/bootstrap-page-schema.sql
  • platform-metadata/src/test/java/com/eip4/platform/metadata/web/PickerControllerTest.java
  • platform-metadata/src/test/java/com/eip4/platform/metadata/web/PageSchemaControllerTest.java
  • platform-metadata/src/test/java/com/eip4/platform/metadata/schema/SchemaImportCliTest.java
  • docs/sql/SYS_PAGE_SCHEMA.sql
  • docs/迁移手册.md(§8.7/8.8/8.9 新坑)
  • platform-metadata/P4衔接-picker与schema接口报告.md + platform-metadata/P4衔接证据/schema-backend-render.png

七、坑列表(详见迁移手册 §8.7–8.9)

  1. SelectDialog 的 dialogid = view_template_id(非 SYS_REFERENCE_ID)——弹窗数据源实体取被引用模板根 @entityid(手册 §8.7)。
  2. 引擎 GeneralPO 对 String 查询条件裸拼 col like '%值%'(GeneralPO.java:1940 无参数绑定)——picker/entity 搜索值侧是注入面,须转义(手册 §8.8)。
  3. SYS_PAGE_SCHEMA 本期 bootstrap+生产脚本落地,Flyway 引入列 P5(架构条款平台表 Flyway 管,但工程未引 Flyway)(手册 §8.9)。
  4. 本地 M0 库 view_template 是裁剪 stub(无 xml 列)——picker 模板路径对 DataAccessException 兜底返回 null 走退化路径,不崩;客户库 view_template.xml 是 PG xml 物理类型,须 xml::text 取出再 dom4j 解析(手册 §5.33)。
  5. M0 库 alice 登录依赖完整 auth 自举(含 parity 种子表 eip4pt_*),本端点验证经 app 密钥自签 JWT 过守卫绕开——非本线缺陷,记录供后续联调注意。

八、P5 待办

  • 引入 Flyway:把 docs/sql/SYS_PAGE_SCHEMA.sql 收编为 db/migration/V{n}__*.sql,确立平台表迁移基线(业务表仍引擎动态建、不进 Flyway)。
  • 统一值侧转义:EntityController 的 amis filter 值透传与 picker 同 sink(GeneralPO LIKE 裸拼),P5 可在引擎外包一层统一值转义工具。
  • picker 性能:高频 dialogid(如 PM_PROJECT 出现 306 次)可加 view_template_id→tablename 解析缓存(现走 POInfo 缓存 + 每次查 view_template,量大时优化)。
  • schema 增量重导:转换器重跑后经 SchemaImportCli 幂等重导(etag 变才升版本),可接 CI 触发。