Explorar el Código

feat(agent): list_tables 纳入 wa_mforensics_ 电子数据取证表

- WorkspaceSchemaCatalog 注入 WaForensicsSchemaCatalog,allTables() 追加取证表,
  与模板库同一份「已登记才可查」口径(仍不扫描 DuckDB 系统表)
- 只取 usable():wa_mforensics_ext_* 在结构文件里标 vectorize=false(展示未使用),
  与向量索引保持一致,不进 Agent 选表
- 取证列类型用原始 SQL 类型(BIGINT/DECIMAL(18,2)/TIMESTAMP),
  缺 sqlType 退回 fieldType,再缺省 TEXT;比 NUMBER 更利于生成类型安全的 SQL
- 同名表仍以模板库优先(putIfAbsent,取证表最后写入);文件缺失时该部分为空,不影响模板表
- 同步 list_tables 工具描述、SqlAnalysisTool/InsightAgentFactory javadoc、AI_AGENT.md
- 补 includesForensicsTables 契约测试(类型映射、usable 口径、同名优先)
cc hace 2 semanas
padre
commit
4cfb8cfa6d

+ 1 - 1
AI_AGENT.md

@@ -190,7 +190,7 @@ entity/       AgentChatSession、AgentMessage、AgentModel、AgentModelProvider
 | 工具 | 说明 |
 |---|---|
 | `execute_sql` | 在当前工作空间 DuckDB 上执行**只读** SQL,返回 resultId + 列定义 + 当前页 + 总行数 |
-| `list_tables` | 列出**模板库元数据里登记的可查表**(`table_info` + `ai_clean_template`,含 AI 动态表):物理表名/中文名/字段(物理列名、类型、中文注释、必填)。不扫描 DuckDB(业务约定:先登记元数据才可查) |
+| `list_tables` | 列出**已登记的可查表**(`table_info` + `ai_clean_template` 含 AI 动态表 + `wa_mforensics_` 取证表结构文件):物理表名/中文名/字段(物理列名、类型、中文注释、必填)。不扫描 DuckDB(业务约定:先登记元数据才可查);取证表只含 `vectorize=true` 的表,`wa_mforensics_ext_*` 不进清单 |
 | `search_table_schema` | 基于 pgvector 的模板元数据语义检索(`AiCleanTemplateVectorIndex`):返回物理表名 + 字段,供生成 SQL;同一份向量索引也用于 AI 模板匹配召回 |
 | `render_chart` | 校验并返回 ECharts 图表配置(**禁止**用于关系图) |
 | `execute_python` | 在沙箱中执行 Python 脚本分析,产出图片经 `/py/files/**` 访问;任意表/字段的关系图用沙箱内置 `emit_relation_graph(nodes, edges, title)` 输出 `relation_graph.json`,后端转成 `relationGraph` 交给前端通用关系图组件 |

+ 1 - 1
ai-server/src/main/java/com/zsjz/ai/module/agent/insight/agent/InsightAgentFactory.java

@@ -93,7 +93,7 @@ public class InsightAgentFactory {
     private final TableFieldMapper tableFieldMapper;
     /** 案件名称(动态公告用,只读一次) */
     private final CaseInfoMapper caseInfoMapper;
-    /** 案件 DuckDB 表目录(list_tables 的唯一事实来源,含 AI 动态表) */
+    /** 案件 DuckDB 表目录(list_tables 的唯一事实来源,含 AI 动态表与 wa_mforensics_ 取证表) */
     private final WorkspaceSchemaCatalog schemaCatalog;
     private final PythonExecutor pythonExecutor;
     private final AgentToolRegistry agentToolRegistry;

+ 70 - 9
ai-server/src/main/java/com/zsjz/ai/module/agent/rag/WorkspaceSchemaCatalog.java

@@ -21,14 +21,16 @@ import java.util.List;
 import java.util.Map;
 
 /**
- * 可查表目录:<b>只来自模板库元数据</b>,不扫描案件 DuckDB。
+ * 可查表目录:<b>只来自已登记的元数据 / 结构文件</b>,不扫描案件 DuckDB。
  *
- * <h3>事实来源(且仅此两个)</h3>
+ * <h3>事实来源(且仅此三个)</h3>
  * <ul>
  *   <li>既有模板库:{@code table_info} + {@code table_field};</li>
- *   <li>AI 模板库:{@code ai_clean_template} + {@code ai_clean_field}(AI 智能清洗出口 B 新建的动态表)。</li>
+ *   <li>AI 模板库:{@code ai_clean_template} + {@code ai_clean_field}(AI 智能清洗出口 B 新建的动态表);</li>
+ *   <li>电子数据取证表:{@link WaForensicsSchemaCatalog} 读取的 {@code schema/wa_mforensics_duckdb.json}
+ *       ({@code wa_mforensics_*} 有 100+ 张、不落模板库,理由见该类说明)。</li>
  * </ul>
- * 业务约定:<b>不读取 DuckDB 系统表 / 不做任何表扫描</b>。DuckDB 里的表必须先在两套元数据里登记,
+ * 业务约定:<b>不读取 DuckDB 系统表 / 不做任何表扫描</b>。DuckDB 里的表必须先在这三套元数据里登记,
  * 才算「可被 Agent 使用的表」——这样表清单与模板库、治理树、AI 模板匹配保持同一口径,
  * 也不会把 {@code govern_tree}/{@code raw_*} 之类的内部表暴露给模型。
  *
@@ -40,6 +42,7 @@ import java.util.Map;
  *       AI 模板取 {@code ai_clean_field.column_name}(AI 动态表的物理列是 c0..cN,
  *       语义英文名只在模板匹配/展示里用);</li>
  *   <li>{@code type} 取元数据 {@code field_type}(如 MONEY/DATE_TIME,缺省 TEXT);
+ *       取证表取<b>原始 SQL 类型</b>(VARCHAR/BIGINT/DECIMAL(18,2)),与语义检索的 DDL 文档同口径;
  *       {@code comment} 取 {@code field_name_cn};{@code required} 取 {@code required==1}。</li>
  * </ul>
  *
@@ -47,8 +50,11 @@ import java.util.Map;
  * <ul>
  *   <li>没有字段的表跳过:无字段既不能打分也不能清洗,列进目录只会让模型去查一张空表;</li>
  *   <li>物理列名为空的字段跳过(历史脏数据):它无法出现在 SQL 里,输出只会误导模型;</li>
- *   <li>输出按物理表名排序,列严格按元数据顺序({@code field_sort} → {@code id});</li>
- *   <li>两套元数据理论上不会重名;真出现同名时以 {@code table_info} 为准(先把既有模板写进结果)。</li>
+ *   <li>取证表只取 {@code vectorize=true} 的({@code wa_mforensics_ext_*} 是「展示未使用」的扩展表,
+ *       与向量索引同一口径,不进 Agent 选表);</li>
+ *   <li>输出按物理表名排序,列严格按元数据顺序({@code field_sort} → {@code id};取证表按 DDL 顺序);</li>
+ *   <li>三套元数据理论上不会重名;真出现同名时按 {@code table_info} → {@code ai_clean_template}
+ *       → 取证表 的顺序先到先得(模板库口径优先)。</li>
  * </ul>
  *
  * <h3>失败语义</h3>
@@ -83,15 +89,19 @@ public class WorkspaceSchemaCatalog {
     private final TableFieldMapper tableFieldMapper;
     private final AiCleanTemplateMapper aiCleanTemplateMapper;
     private final AiCleanFieldMapper aiCleanFieldMapper;
+    /** 取证数据表结构(文件驱动):{@code wa_mforensics_*} 的唯一事实来源 */
+    private final WaForensicsSchemaCatalog waForensicsSchemaCatalog;
 
     public WorkspaceSchemaCatalog(TableInfoMapper tableInfoMapper,
                                   TableFieldMapper tableFieldMapper,
                                   AiCleanTemplateMapper aiCleanTemplateMapper,
-                                  AiCleanFieldMapper aiCleanFieldMapper) {
+                                  AiCleanFieldMapper aiCleanFieldMapper,
+                                  WaForensicsSchemaCatalog waForensicsSchemaCatalog) {
         this.tableInfoMapper = tableInfoMapper;
         this.tableFieldMapper = tableFieldMapper;
         this.aiCleanTemplateMapper = aiCleanTemplateMapper;
         this.aiCleanFieldMapper = aiCleanFieldMapper;
+        this.waForensicsSchemaCatalog = waForensicsSchemaCatalog;
     }
 
     /**
@@ -107,7 +117,7 @@ public class WorkspaceSchemaCatalog {
     }
 
     /**
-     * 全部可查表(既有模板库 + AI 模板库),按物理表名排序、列按字段顺序排列。
+     * 全部可查表(既有模板库 + AI 模板库 + 电子数据取证表),按物理表名排序、列按字段顺序排列。
      *
      * @throws org.springframework.dao.DataAccessException 元数据查询失败时直接上抛,不降级为空列表
      */
@@ -119,10 +129,11 @@ public class WorkspaceSchemaCatalog {
         List<AiCleanTemplate> aiTemplates = nullSafe(aiCleanTemplateMapper.selectList(Wrappers.emptyWrapper()));
         List<AiCleanField> aiFields = nullSafe(aiCleanFieldMapper.selectList(Wrappers.emptyWrapper()));
 
-        // LinkedHashMap 用于「先到先得」:既有模板先写入,AI 模板 putIfAbsent,天然实现同名以 table_info 优先
+        // LinkedHashMap 用于「先到先得」:模板库先写入,后面的 putIfAbsent 不覆盖,天然实现同名优先模板库口径
         Map<String, TableSchema> byTableName = new LinkedHashMap<>();
         appendTemplateTables(byTableName, tables, tableFields);
         appendAiTemplateTables(byTableName, aiTemplates, aiFields);
+        appendForensicsTables(byTableName);
 
         List<TableSchema> result = new ArrayList<>(byTableName.values());
         result.sort(Comparator.comparing(TableSchema::tableName,
@@ -226,6 +237,56 @@ public class WorkspaceSchemaCatalog {
         }
     }
 
+    // ==================== 电子数据取证表:wa_mforensics_*(文件驱动) ====================
+
+    /**
+     * 装配电子数据取证表({@code wa_mforensics_*})。
+     *
+     * <p>这些表<b>不在</b> {@code table_info}/{@code table_field} 里:100+ 张 DDL 表落模板库会稀释
+     * 模板匹配候选池、污染模板库页面,所以由 {@link WaForensicsSchemaCatalog} 直接读
+     * {@code schema/wa_mforensics_duckdb.json}(与语义检索索引同一份事实来源)。
+     *
+     * <p><b>只取 {@link WaForensicsSchemaCatalog#usable()}</b>:{@code wa_mforensics_ext_*} 在文件里标了
+     * {@code vectorize=false}(展示未使用),与向量索引保持同一口径,不进 Agent 选表。
+     *
+     * <p>类型用<b>原始 SQL 类型</b>而不是平台枚举:取证表由模型直接查 DuckDB,
+     * {@code DECIMAL(18,2)} / {@code BIGINT} 比 NUMBER 更能防止把数值列当字符串处理
+     * (与 {@code AiCleanTemplateVectorIndex#buildDdlDoc} 的 DDL 文档同口径)。
+     *
+     * <p>文件缺失 / 解析失败时 {@code usable()} 返回空列表(catalog 内部 fail-open),
+     * 不影响模板表清单。
+     */
+    private void appendForensicsTables(Map<String, TableSchema> target) {
+        for (WaForensicsSchemaCatalog.TableSchema table : waForensicsSchemaCatalog.usable()) {
+            if (table == null || !StringUtils.hasText(table.tableNameEn())) {
+                continue;
+            }
+            List<WaForensicsSchemaCatalog.ColumnSchema> forensicsColumns =
+                    table.columns() == null ? List.of() : table.columns();
+            List<ColumnSchema> columns = forensicsColumns.stream()
+                    .filter(column -> column != null && StringUtils.hasText(column.name()))
+                    .map(column -> new ColumnSchema(
+                            column.name(),
+                            forensicsType(column),
+                            column.comment(),
+                            column.required()))
+                    .toList();
+            if (columns.isEmpty()) {
+                continue;
+            }
+            target.putIfAbsent(table.tableNameEn(),
+                    new TableSchema(table.tableNameEn(), table.tableNameCn(), columns));
+        }
+    }
+
+    /** 取证列类型:优先原始 SQL 类型,缺失时退回平台元数据类型,再缺省 TEXT。 */
+    private static String forensicsType(WaForensicsSchemaCatalog.ColumnSchema column) {
+        if (StringUtils.hasText(column.sqlType())) {
+            return column.sqlType();
+        }
+        return StringUtils.hasText(column.fieldType()) ? column.fieldType() : DEFAULT_TYPE;
+    }
+
     // ==================== 测试辅助 ====================
 
     private static <T> List<T> nullSafe(List<T> list) {

+ 13 - 10
ai-server/src/main/java/com/zsjz/ai/module/agent/tools/SqlAnalysisTool.java

@@ -36,8 +36,9 @@ import java.util.stream.Collectors;
  * {@code ETL_DB_PATH} 快照完成查询、统计与建模。本工具集只保留两个基础能力:
  * <ul>
  *   <li>{@code list_tables}:走<b>模板库元数据目录</b>({@link WorkspaceSchemaCatalog}:
- *       {@code table_info}/{@code table_field} + {@code ai_clean_template}/{@code ai_clean_field}),
- *       <b>不扫描 DuckDB 系统表</b> —— 只有登记进模板库的表才算「可被 Agent 使用的表」;</li>
+ *       {@code table_info}/{@code table_field} + {@code ai_clean_template}/{@code ai_clean_field}
+ *       + {@code wa_mforensics_*} 取证表结构文件),<b>不扫描 DuckDB 系统表</b> ——
+ *       只有登记进这三套元数据的表才算「可被 Agent 使用的表」;</li>
  *   <li>{@code render_chart}:校验并把 ECharts option 原样交还给前端渲染。</li>
  * </ul>
  *
@@ -67,13 +68,13 @@ public class SqlAnalysisTool {
     }
 
     /**
-     * 列出模板库中已登记的可查表(既有模板 + AI 智能清洗动态表)
+     * 列出已登记的可查表(既有模板 + AI 智能清洗动态表 + 电子数据取证表)
      *
-     * <p>表清单来源只有两套模板元数据(table_info + ai_clean_template),<b>不扫描 DuckDB</b>;
-     * 物理表名/物理列名见 {@link #loadMetadataTableCatalog()}。
+     * <p>表清单来源只有三套元数据(table_info + ai_clean_template + wa_mforensics 结构文件),
+     * <b>不扫描 DuckDB</b>;物理表名/物理列名见 {@link #loadMetadataTableCatalog()}。
      */
     @Tool(name = "list_tables",
-          description = "列出模板库已登记的可查表及字段(模板表 + ai_clean_ 动态表);取证表/语义检索用当前工具列表中的表结构检索工具(RAG 可用时)。",
+          description = "列出可查表及字段(模板表 + ai_clean_ 动态表 + wa_mforensics_ 取证表);已知表名看字段也用它,按语义找表用表结构检索工具(RAG 可用时)。",
           readOnly = true)
     public ToolResultBlock listTables() {
         try {
@@ -284,11 +285,12 @@ public class SqlAnalysisTool {
     // 与各业务分析工具(CallAnalysisTool 等)共用同一份实现,保证前端表格契约只有一处。
 
     /**
-     * 模板库元数据目录 → list_tables 的 JSON 形状。
+     * 元数据目录 → list_tables 的 JSON 形状。
      *
-     * <p><b>为什么只认模板库:</b>业务约定「DuckDB 里的表必须先登记进模板库元数据才算可被 Agent 使用的表」——
+     * <p><b>为什么只认元数据:</b>业务约定「DuckDB 里的表必须先登记进元数据才算可被 Agent 使用的表」——
      * 既有模板在 {@code table_info}/{@code table_field},AI 智能清洗出口 B 新建的动态表在
-     * {@code ai_clean_template}/{@code ai_clean_field}。这里<b>不扫描 DuckDB 系统表</b>,
+     * {@code ai_clean_template}/{@code ai_clean_field},电子数据取证表在
+     * {@code schema/wa_mforensics_duckdb.json}({@code wa_mforensics_*})。这里<b>不扫描 DuckDB 系统表</b>,
      * 也不把 {@code govern_tree}/{@code raw_*} 之类的内部表暴露给模型;表清单与模板库、治理树、AI 模板匹配保持同一口径。
      *
      * <p><b>列名用物理列名:</b>既有模板取 {@code field_name_en};AI 动态表的物理列是 {@code c0..cN},
@@ -344,7 +346,8 @@ public class SqlAnalysisTool {
      * 兜底链路:模板库元数据三表(meta_raw_sheet → table_info → table_field)。
      *
      * <p>仅在元数据目录查询异常时使用,字段口径与历史实现完全一致;
-     * 不覆盖 AI 智能清洗动态表({@code ai_clean_template}),所以不能作为常态表目录。
+     * 不覆盖 AI 智能清洗动态表({@code ai_clean_template})与取证表({@code wa_mforensics_*}),
+     * 所以不能作为常态表目录。
      */
     private List<Map<String, Object>> loadWorkspaceTableMeta() {
         Map<Integer, TableInfo> infoById = tableInfoMapper.selectList(Wrappers.<TableInfo>lambdaQuery().eq(TableInfo::getHasTable, HasInnerEnum.YES)).stream()

+ 55 - 2
ai-server/src/test/java/com/zsjz/ai/module/agent/rag/WorkspaceSchemaCatalogTest.java

@@ -30,12 +30,13 @@ import static org.mockito.Mockito.when;
  * {@link WorkspaceSchemaCatalog} 的离线契约测试:<b>不连真 PG / 不连 DuckDB</b>。
  *
  * <p>目录是 Agent {@code list_tables} 与 {@code search_table_schema} 的唯一事实来源,
- * 事实来源只有两套模板元数据。这里钉住五件事:
+ * 事实来源是三套元数据(两套模板库 + 取证表结构文件)。这里钉住六件事:
  * <ol>
  *   <li>既有模板({@code table_info}/{@code table_field})与 AI 模板({@code ai_clean_template}/{@code ai_clean_field})
  *       都在清单里,<b>AI 模板不按 status 过滤</b>;</li>
  *   <li>列名用<b>物理列名</b>:既有模板取 {@code field_name_en},AI 动态表取 {@code column_name}(c0..cN);</li>
  *   <li>type / comment / required 的映射口径(类型空则 TEXT、必填按 required==1);</li>
+ *   <li>取证表来自 {@link WaForensicsSchemaCatalog#usable()},类型用原始 SQL 类型;</li>
  *   <li>无字段的表跳过、输出按表名排序、列按 {@code field_sort} 稳定排序;</li>
  *   <li>元数据查询失败直接上抛,不静默返回空列表(空列表会被误读成「模板库里没有表」)。</li>
  * </ol>
@@ -49,6 +50,7 @@ class WorkspaceSchemaCatalogTest {
     private TableFieldMapper tableFieldMapper;
     private AiCleanTemplateMapper aiCleanTemplateMapper;
     private AiCleanFieldMapper aiCleanFieldMapper;
+    private WaForensicsSchemaCatalog waForensicsSchemaCatalog;
     private WorkspaceSchemaCatalog catalog;
 
     @BeforeEach
@@ -57,8 +59,11 @@ class WorkspaceSchemaCatalogTest {
         tableFieldMapper = mock(TableFieldMapper.class);
         aiCleanTemplateMapper = mock(AiCleanTemplateMapper.class);
         aiCleanFieldMapper = mock(AiCleanFieldMapper.class);
+        waForensicsSchemaCatalog = mock(WaForensicsSchemaCatalog.class);
+        // 默认无取证表:不关心取证目录的用例保持原有断言
+        when(waForensicsSchemaCatalog.usable()).thenReturn(List.of());
         catalog = new WorkspaceSchemaCatalog(tableInfoMapper, tableFieldMapper,
-                aiCleanTemplateMapper, aiCleanFieldMapper);
+                aiCleanTemplateMapper, aiCleanFieldMapper, waForensicsSchemaCatalog);
     }
 
     @Test
@@ -180,6 +185,43 @@ class WorkspaceSchemaCatalogTest {
         assertEquals(List.of("field_en"), tables.get(0).columns().stream().map(ColumnSchema::name).toList());
     }
 
+    @Test
+    @DisplayName("取证表也在清单里:类型用原始 SQL 类型、只认 usable()(ext 表不进)、同名以模板库为准")
+    void includesForensicsTables() {
+        when(tableInfoMapper.selectList(any())).thenReturn(List.of(
+                tableInfo(1, "call_record", "通话记录")));
+        when(tableFieldMapper.selectList(any())).thenReturn(List.of(
+                tableField(1, "call_time", "通话时间", FieldTypeEnum.TEXT, 1, 0)));
+        when(aiCleanTemplateMapper.selectList(any())).thenReturn(List.of());
+        when(aiCleanFieldMapper.selectList(any())).thenReturn(List.of());
+        // ext 表(vectorize=false)由 WaForensicsSchemaCatalog 在 usable() 里排除,本类只消费 usable();
+        // 这里再放一张与模板同名的取证表,验证「模板库优先」
+        when(waForensicsSchemaCatalog.usable()).thenReturn(List.of(
+                forensicsTable("wa_mforensics_010100", "基本信息",
+                        forensicsColumn("id", "id", "BIGINT", "NUMBER", true),
+                        forensicsColumn("amount", "交易金额", "DECIMAL(18,2)", "NUMBER", false),
+                        forensicsColumn("remark", "备注", null, "TEXT", false)),
+                forensicsTable("call_record", "取证同名表",
+                        forensicsColumn("x", "x", "VARCHAR", "TEXT", false))));
+
+        List<TableSchema> tables = catalog.allTables();
+
+        assertEquals(List.of("call_record", "wa_mforensics_010100"),
+                tables.stream().map(TableSchema::tableName).toList());
+        assertEquals("通话记录", tables.get(0).tableComment(), "同名表以模板库为准");
+
+        TableSchema forensics = tables.get(1);
+        assertEquals("基本信息", forensics.tableComment());
+        assertEquals(List.of("id", "amount", "remark"),
+                forensics.columns().stream().map(ColumnSchema::name).toList());
+        assertEquals("BIGINT", column(forensics, "id").type(), "取证表类型用原始 SQL 类型而不是 NUMBER");
+        assertEquals("DECIMAL(18,2)", column(forensics, "amount").type());
+        assertEquals("TEXT", column(forensics, "remark").type(), "sqlType 缺失时退回平台类型");
+        assertEquals("交易金额", column(forensics, "amount").comment());
+        assertTrue(column(forensics, "id").required());
+        assertFalse(column(forensics, "amount").required());
+    }
+
     @Test
     @DisplayName("查询失败直接上抛:不静默返回空列表(空列表会被当成「模板库里没有表」)")
     void queryFailurePropagates() {
@@ -253,4 +295,15 @@ class WorkspaceSchemaCatalogTest {
         field.setRequired(required);
         return field;
     }
+
+    private static WaForensicsSchemaCatalog.TableSchema forensicsTable(
+            String nameEn, String nameCn, WaForensicsSchemaCatalog.ColumnSchema... columns) {
+        return new WaForensicsSchemaCatalog.TableSchema(
+                nameEn, nameCn, "取证数据库", "", true, List.of(columns));
+    }
+
+    private static WaForensicsSchemaCatalog.ColumnSchema forensicsColumn(
+            String name, String comment, String sqlType, String fieldType, boolean required) {
+        return new WaForensicsSchemaCatalog.ColumnSchema(name, comment, sqlType, fieldType, required);
+    }
 }