# 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 = ` 的 `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 根元素 | ``,根 `@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 触发。