From 5d1261303436c1d76d381b860fb61f8150b7ead9 Mon Sep 17 00:00:00 2001 From: zhengwr Date: Sun, 14 Jun 2026 18:20:38 +0800 Subject: [PATCH] =?UTF-8?q?perf(WS-D=20I1):=20/api/file/list=20=E5=8E=BB?= =?UTF-8?q?=E5=87=BD=E6=95=B0=E5=8C=85=E5=88=97=20+=20sys=5Fdoc=20?= =?UTF-8?q?=E5=87=BD=E6=95=B0=E5=BC=8F=E9=83=A8=E5=88=86=E7=B4=A2=E5=BC=95?= =?UTF-8?q?=EF=BC=88=E5=85=A8=E8=A1=A8=E6=89=AB=E2=86=92Index=20Scan?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit I1 性能(必修): - 根因: GET /api/file/list 原查询 WHERE UPPER(tablename)=? AND TRIM(businesskey)=? AND isactive=1 —— 列被函数包裹(非 sargable),sys_doc 33.8 万行仅 PK 索引 → 每次附件页渲染 Parallel Seq Scan 全表(amis service 容器每渲必打本端点; EXPLAIN cost ~18572)。 - 修(FileController.list 查询): · tablename 列本就全大写(DB 实测 tablename<>upper(tablename) 计数 0),app 侧已 tableName.trim().toUpperCase() → 去 UPPER 改 tablename = ?(sargable)。 · businesskey 不能简单 = trimmed: DB 实测 13000 行存「32 位 UUID + 4 空格 padding 至 36」CHAR 补白遗留(业务 PK 为 character(36)),naive businesskey=trimmed 会 漏列这 13000 行附件 → 保留 trim 语义改 rtrim(businesskey) = ?,配函数式索引使其 sargable。全程 ? 绑定(防注入,无拼接)。 - 索引 DDL: docs/sql/SYS_DOC_INDEX.sql CREATE INDEX IF NOT EXISTS ix_sys_doc_biz ON eip3.sys_doc (tablename, rtrim(businesskey)) WHERE isactive = 1; 已应用到 eip4dev(含 COMMENT,幂等)。客户库排切流窗口执行(与现有 docs/sql/* 同放 同风格;P5 Flyway 待办同 SYS_PAGE_SCHEMA.sql)。 - 验证(eip4dev): EXPLAIN Seq Scan(cost 18572) → Index Scan using ix_sys_doc_biz (cost 8.44, exec 0.038ms); 补白键 OA_NOTICEMANAGE + 横线键 OA_NEWSMANAGE 均命中。 8093 重启含新 jar 后 /api/file/list 两种键风格均正常返附件(含 13000 行补白键场景)。 补测试: - FileControllerTest #5 注入安全(priority 契约): 恶意 tableName/businessKey 不抛、返空, ArgumentCaptor 断言走 ? 绑定(SQL 文本为静态参数化语句不含用户串,用户原串作绑定值)。 - TemplateToAmisConverterTest 新增 skip-guard: 表名 ORPHAN_*(SYS_ENTITY 解析不到)→ enrichAttachmentFields 降级守卫生效,附件字段保留原 input-file 不包 service。 - 测试全绿: FileControllerTest 5/5, TemplateToAmisConverterTest 93/93(JDK21)。 M4: buildAttachmentField 加注释说明 service.name 与内层 input-file 同名(DOCUMENT) 仅作布局归位 key,表单值由内层 input-file 绑定,amis 容忍(已浏览器验证)。 I2(已知系统级后续项,本次不修): /api/file/list 及 download 无行级数据权限——任意已认证 用户可枚举任意业务记录附件,与现有 download/flow 同 posture(生产仅认证可访问)。 TODO 注释标于 FileController.list javadoc。 Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/sql/SYS_DOC_INDEX.sql | 34 +++++++++++++++ .../converter/TemplateToAmisConverter.java | 3 ++ .../TemplateToAmisConverterTest.java | 30 ++++++++++++++ .../platform/metadata/web/FileController.java | 15 ++++++- .../metadata/web/FileControllerTest.java | 41 +++++++++++++++++++ 5 files changed, 122 insertions(+), 1 deletion(-) create mode 100644 docs/sql/SYS_DOC_INDEX.sql diff --git a/docs/sql/SYS_DOC_INDEX.sql b/docs/sql/SYS_DOC_INDEX.sql new file mode 100644 index 0000000..9842e5e --- /dev/null +++ b/docs/sql/SYS_DOC_INDEX.sql @@ -0,0 +1,34 @@ +-- ============================================================================ +-- 性能索引脚本:SYS_DOC 附件按业务实体检索(WS-D I1) +-- ---------------------------------------------------------------------------- +-- 归属:platform-metadata(GET /api/file/list,附件查看态只读下载列表)。 +-- 背景:sys_doc 33.8 万行,原仅 PK 索引(sys_doc_id)。/api/file/list 按 +-- tablename + businesskey 列附件,amis service 容器每次附件页渲染都打本端点。 +-- 原查询 WHERE UPPER(tablename)=? AND TRIM(businesskey)=? AND isactive=1 —— 列被 +-- 函数包裹(非 sargable)→ Parallel Seq Scan 全表 33.8 万行(EXPLAIN cost ~18572)。 +-- +-- 修: +-- 1) tablename 列本就全大写(DB 实测:sys_doc.tablename<>upper(tablename) 计数 0), +-- app 侧已 tableName.trim().toUpperCase(),查询去 UPPER 改 tablename = ?(sargable)。 +-- 2) businesskey 列 varchar(100) 存 CHAR(36) 补白遗留:DB 实测 13000 行为 +-- 「32 位 UUID(去横线)+ 4 空格 padding 至 36」。不能简单 businesskey = trimmed +-- (会漏这 13000 行)→ 保留 trim 语义,查询用 rtrim(businesskey) = ?,并配 +-- 函数式索引(索引 key 同为 rtrim(businesskey))使其 sargable。 +-- 3) 部分索引(WHERE isactive=1)与 list 查询条件一致,索引更小更贴。 +-- +-- 验证(eip4dev 实测,2026-06-14): +-- EXPLAIN 走 Index Scan using ix_sys_doc_biz,cost 18572 → 8.44, +-- actual Execution Time 0.038 ms(补白键 OA_NOTICEMANAGE + 横线键 OA_NEWSMANAGE 均命中)。 +-- +-- 【Flyway 待办(P5)】同 SYS_PAGE_SCHEMA.sql:本工程当前未引入 Flyway,本脚本即 +-- 「生产建表/建索引脚本」。客户库排切流窗口执行(CREATE INDEX 默认持表锁;若需在线 +-- 无锁建索引可改 CREATE INDEX CONCURRENTLY,但不能在事务/Flyway 事务内执行)。 +-- P5 引入 Flyway 时原样改名 V{n}__create_ix_sys_doc_biz.sql 纳入 db/migration 即可。 +-- ============================================================================ + +CREATE INDEX IF NOT EXISTS ix_sys_doc_biz + ON eip3.sys_doc (tablename, rtrim(businesskey)) + WHERE isactive = 1; + +COMMENT ON INDEX eip3.ix_sys_doc_biz IS + 'WS-D I1:/api/file/list 按 tablename + rtrim(businesskey) 检索附件的 sargable 函数式部分索引(isactive=1)'; diff --git a/platform-converter/src/main/java/com/eip4/platform/converter/TemplateToAmisConverter.java b/platform-converter/src/main/java/com/eip4/platform/converter/TemplateToAmisConverter.java index e1862ac..2045a84 100644 --- a/platform-converter/src/main/java/com/eip4/platform/converter/TemplateToAmisConverter.java +++ b/platform-converter/src/main/java/com/eip4/platform/converter/TemplateToAmisConverter.java @@ -1026,6 +1026,9 @@ public class TemplateToAmisConverter { service.put("type", "service"); // 业务键绑表单主键;空主键(新增态)时 list 端点返空,不误列 service.put("api", "get:/api/file/list?tableName=" + upperTable + "&businessKey=${" + pkCol + "}"); + // M4:service.name 与内层 input-file 同名(皆 DOCUMENT)。service.name 仅作布局归位 key + // (供
把本容器排到正确位置),表单实际取值由内层 input-file 绑定; + // amis 容忍二者同名(外层 service 不抢绑该字段值)——已浏览器实证(查看页附件下载列表+上传控件正常)。 service.put("name", uploadItem.get("name")); // 保
归位 service.put("label", uploadItem.get("label")); List> body = new ArrayList<>(); diff --git a/platform-converter/src/test/java/com/eip4/platform/converter/TemplateToAmisConverterTest.java b/platform-converter/src/test/java/com/eip4/platform/converter/TemplateToAmisConverterTest.java index ed49e3a..5b64996 100644 --- a/platform-converter/src/test/java/com/eip4/platform/converter/TemplateToAmisConverterTest.java +++ b/platform-converter/src/test/java/com/eip4/platform/converter/TemplateToAmisConverterTest.java @@ -688,6 +688,36 @@ class TemplateToAmisConverterTest { assertEquals("input-file", svcBody.get(1).get("type")); } + @Test + @SuppressWarnings("unchecked") + void form_附件字段_表名不可靠_不包service保留上传控件_降级守卫() { + // WS-D D.2 skip-guard:实体在 SYS_ENTITY 解析不到 → resolveTableName 返 ORPHAN_*(占位表名), + // 表名不可靠不能拼 /api/file/list?tableName=ORPHAN_*(会查无意义甚至误列)→ enrichAttachmentFields + // 诚实降级:不包 service 容器,保留原 input-file 上传控件(与老系统编辑态一致,仅缺只读下载列表)。 + JdbcTemplate jdbc = mock(JdbcTemplate.class); + // SYS_ENTITY 解析抛异常 → resolveTableName 走 catch 返 "ORPHAN_e1" + lenient().when(jdbc.queryForObject(any(String.class), eq(String.class), any(Object[].class))) + .thenThrow(new RuntimeException("SYS_ENTITY 无此实体(孤儿模板)")); + TemplateToAmisConverter orphanConverter = new TemplateToAmisConverter(jdbc); + + String pageXml = "" + + "" + + ""; + Function resolver = id -> pageXml; + String xml = "
"; + ConversionResult r = orphanConverter.convertGraded(xml, "孤儿附件表单", new ArrayList<>(), resolver); + + Map form = body(r.getSchema()); + List> items = flattenFormBody(form); + Map doc = items.get(0); + + // 表名 ORPHAN_* → 降级守卫生效:附件字段保持原 input-file(不被包成 service 容器) + assertEquals("input-file", doc.get("type"), + "表名不可靠(ORPHAN_*) → 不包 service,保留原 input-file 上传控件"); + assertEquals("DOCUMENT", doc.get("name")); + assertNull(doc.get("api"), "降级时不应配 /api/file/list(表名不可靠)"); + } + /** 从 WS-D 附件 service 容器里取内层上传控件(input-file)。 */ @SuppressWarnings("unchecked") private static Map attachmentUploadOf(Map attachmentField) { diff --git a/platform-metadata/src/main/java/com/eip4/platform/metadata/web/FileController.java b/platform-metadata/src/main/java/com/eip4/platform/metadata/web/FileController.java index 2e3c7a9..2435c9d 100644 --- a/platform-metadata/src/main/java/com/eip4/platform/metadata/web/FileController.java +++ b/platform-metadata/src/main/java/com/eip4/platform/metadata/web/FileController.java @@ -214,6 +214,10 @@ public class FileController { * 附件按 {@code sys_doc.tablename + businesskey} 关联业务记录(非物理列),查看态须列出已有附件供下载, * 而非空上传按钮。amis {@code service} 组件按本端点拉取,{@code each} 渲染「文件名 (大小KB) + 下载」列表。 * + *

TODO(I2 已知系统级后续项,本任务不修):本端点(及 {@code download} / 流式下载) + * 无行级数据权限——任意已认证用户可凭 tableName+businessKey 枚举任意业务记录附件。 + * 与现有 download/flow 同 posture(生产仅认证可访问)。行级数据权限属系统级后续项。 + * * @param tableName 业务表名(大小写不敏感,入库前已大写存储) * @param businessKey 业务记录主键(空 → 返回空列表,防全表扫) * @return amis 约定 {@code {status:0, data:{items:[{id,name,size,sizeKb,url}]}}} @@ -228,9 +232,18 @@ public class FileController { List> items = new java.util.ArrayList<>(); // 业务键缺失 → 空列表(不查库,防 businesskey 为空时全表附件扫出) if (tableName != null && !tableName.isBlank() && businessKey != null && !businessKey.isBlank()) { + // WS-D I1 性能:sys_doc 33.8 万行仅 PK 索引,原 UPPER()/TRIM() 包列 → 非 sargable + // → 每次附件页渲染 Parallel Seq Scan 全表(amis service 容器每渲必打本端点)。 + // 修:tablename 列本就全大写(DB 实测 tablename<>upper(tablename) 计数 0),故 app 侧 + // tableName.trim().toUpperCase() 后即可直接 tablename = ? 等值匹配(去 UPPER,sargable)。 + // businesskey 列存 CHAR(36) 补白遗留(DB 实测 13000 行 32 位 UUID + 4 空格 padding 至 36): + // 不能简单 businesskey = trimmed(会漏这 13000 行)→ 保留 trim 语义,用 rtrim(businesskey) + // 配套函数式部分索引 ix_sys_doc_biz (tablename, rtrim(businesskey)) WHERE isactive=1, + // 既 sargable(Index Scan,EXPLAIN cost 18572→8.44)又正确(同时命中补白/不补白键)。 + // 全程 ? 绑定(防注入,无拼接)。索引 DDL 见 docs/sql/SYS_DOC_INDEX.sql。 List> rows = jdbcTemplate.queryForList( "SELECT sys_doc_id, filename, filesize FROM sys_doc " - + "WHERE UPPER(tablename) = ? AND TRIM(businesskey) = ? AND isactive = 1 " + + "WHERE tablename = ? AND rtrim(businesskey) = ? AND isactive = 1 " + "ORDER BY createtime", tableName.trim().toUpperCase(), businessKey.trim()); for (Map r : rows) { diff --git a/platform-metadata/src/test/java/com/eip4/platform/metadata/web/FileControllerTest.java b/platform-metadata/src/test/java/com/eip4/platform/metadata/web/FileControllerTest.java index f5869b8..2952775 100644 --- a/platform-metadata/src/test/java/com/eip4/platform/metadata/web/FileControllerTest.java +++ b/platform-metadata/src/test/java/com/eip4/platform/metadata/web/FileControllerTest.java @@ -1,11 +1,13 @@ package com.eip4.platform.metadata.web; import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; import static org.junit.jupiter.api.Assertions.assertNotNull; import static org.junit.jupiter.api.Assertions.assertTrue; import static org.mockito.ArgumentMatchers.anyString; import static org.mockito.ArgumentMatchers.eq; import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.verify; import static org.mockito.Mockito.when; import java.util.LinkedHashMap; @@ -15,6 +17,7 @@ import java.util.Map; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; +import org.mockito.ArgumentCaptor; import org.springframework.http.ResponseEntity; import org.springframework.jdbc.core.JdbcOperations; @@ -101,4 +104,42 @@ class FileControllerTest { List> items = (List>) data.get("items"); assertEquals(1L, items.get(0).get("sizeKb")); } + + @Test + @DisplayName("5. 注入安全(priority 契约):恶意 tableName 不抛、不破坏,走 ? 绑定(用户串只作绑定值,不进 SQL 文本)") + void listSqlInjectionGoesThroughBindParameters() { + String evilTable = "x'; DROP TABLE sys_doc; --"; + String evilKey = "y' OR '1'='1"; + // mock 返回空——证明不抛、返空集(anyString 消歧到变长参重载,与生产 String 绑定参一致) + when(jdbc.queryForList(anyString(), anyString(), anyString())).thenReturn(List.of()); + + // 不抛异常 + ResponseEntity> resp = controller.list(evilTable, evilKey); + + // 返空 items(status=0,不破坏) + Map body = resp.getBody(); + assertNotNull(body); + assertEquals(0, body.get("status")); + Map data = (Map) body.get("data"); + assertTrue(((List) data.get("items")).isEmpty()); + + // 捕获实际传给 jdbc 的 SQL 文本 + 绑定参数,证明走 ? 绑定(非字符串拼接)。 + // 参数捕获用 String 类型(消歧到 queryForList(String, Object...) 变长参重载,与生产调用一致)。 + ArgumentCaptor sqlCaptor = ArgumentCaptor.forClass(String.class); + ArgumentCaptor argCaptor = ArgumentCaptor.forClass(String.class); + verify(jdbc).queryForList(sqlCaptor.capture(), argCaptor.capture(), argCaptor.capture()); + + String sql = sqlCaptor.getValue(); + // SQL 文本是静态参数化语句:含 ? 占位、不含任何用户串片段 + assertTrue(sql.contains("WHERE tablename = ? AND rtrim(businesskey) = ?"), + "SQL 应为静态参数化语句: " + sql); + assertFalse(sql.contains("DROP TABLE"), "SQL 文本不得含用户注入串: " + sql); + assertFalse(sql.contains("OR '1'='1"), "SQL 文本不得含用户注入串: " + sql); + assertFalse(sql.contains(evilTable), "SQL 文本不得含原始 tableName: " + sql); + + // 用户原串作为绑定参数传入(tableName 经 trim+大写归一,businessKey 经 trim) + List boundArgs = argCaptor.getAllValues(); + assertEquals(evilTable.trim().toUpperCase(), boundArgs.get(0)); + assertEquals(evilKey.trim(), boundArgs.get(1)); + } }