- 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>
13 KiB
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 按优先级解析为实体表名——
- view_template_id(转换器产物主路径,覆盖全部存量 source)→ 读其
xml::text根@entityid→DataDicService.getSYSEntity(entityId).getPo().get_Value("TABLENAME"); - SYS_REFERENCE_ID(兼容旧引擎引用语义)→
getReferenceEntityTableName反解; - 实体表名(直接以实体作数据源)→ 直接命中。
与转换器产物对得上:转换器 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_SEARCH500——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.javaplatform-metadata/src/main/java/com/eip4/platform/metadata/web/PageSchemaController.javaplatform-metadata/src/main/java/com/eip4/platform/metadata/schema/SchemaImportCli.javaplatform-metadata/src/main/resources/bootstrap/bootstrap-page-schema.sqlplatform-metadata/src/test/java/com/eip4/platform/metadata/web/PickerControllerTest.javaplatform-metadata/src/test/java/com/eip4/platform/metadata/web/PageSchemaControllerTest.javaplatform-metadata/src/test/java/com/eip4/platform/metadata/schema/SchemaImportCliTest.javadocs/sql/SYS_PAGE_SCHEMA.sqldocs/迁移手册.md(§8.7/8.8/8.9 新坑)platform-metadata/P4衔接-picker与schema接口报告.md+platform-metadata/P4衔接证据/schema-backend-render.png
七、坑列表(详见迁移手册 §8.7–8.9)
- SelectDialog 的 dialogid = view_template_id(非 SYS_REFERENCE_ID)——弹窗数据源实体取被引用模板根
@entityid(手册 §8.7)。 - 引擎 GeneralPO 对 String 查询条件裸拼
col like '%值%'(GeneralPO.java:1940 无参数绑定)——picker/entity 搜索值侧是注入面,须转义(手册 §8.8)。 - SYS_PAGE_SCHEMA 本期 bootstrap+生产脚本落地,Flyway 引入列 P5(架构条款平台表 Flyway 管,但工程未引 Flyway)(手册 §8.9)。
- 本地 M0 库
view_template是裁剪 stub(无xml列)——picker 模板路径对DataAccessException兜底返回 null 走退化路径,不崩;客户库view_template.xml是 PGxml物理类型,须xml::text取出再 dom4j 解析(手册 §5.33)。 - 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 触发。