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

190 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
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.
# 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 触发。