feat: 新增智能查数（自然语言转 SQL 只读查询）
新增「智能查数」功能：用户用自然语言提问，由大模型生成一条只读 SQL，经安全校验后在当前用户数据上执行，前端按结果形状自适应渲染为统计卡片、表格或图表。入口位于侧边栏，仅在 AI 启用时显示。 变更内容： - 后端新增 AiSqlQueryService 与 POST /api/ai/sql，新增 AiCallType.SQL 用量记录与提示词模板 ai-sql-system.tpl - 新增安全网关 TextToSqlGuard：仅允许单条 SELECT，拒绝写操作、多语句、危险函数与 SELECT INTO/FOR UPDATE；校验表白名单与 schema 前缀；递归注入 user_id 隔离（主表加 WHERE、JOIN 加 ON，覆盖括号连接与 CTE）；结果上限 1000 - 表结构改由 TextToSqlSchemaProvider 从数据库元数据动态读取（60 秒缓存），白名单与表列中文说明集中在 TextToSqlTables，字段增删改无需调整提示词 - 新增 AiSqlQueryResultVO、AiSqlColumnVO，返回生成的 SQL、列元数据与行数据 - 前端新增智能查数页 SqlQuery.vue（路由 /smart-query），按结果形状渲染单行统计卡片、多行动态表格并支持柱状图与饼图切换 - 渠道列用 getChannelLabel 本地化展示，生成的 SQL 用 sql-formatter 缩进、highlight.js 高亮并支持复制 - 新增共享 useAiEnabled 状态，侧边栏「智能查数」菜单仅 AI 启用时显示，设置页保存 AI 配置后即时刷新 - 设置页与收支记录页文案补充智能查数相关三语文案 依赖与清理： - 新增前端依赖 sql-formatter、highlight.js - 移除仓库内测试文件 LedgerlyApplicationTests、PromptTemplateServiceTest、AiPromptPayloadPrivacyTest，此后测试源码不再纳入提交 说明： - 表结构动态读取保证字段变更零维护，仅可查表白名单需显式登记 - 安全网关对 JOIN 条件注入 ON 子句以保证 LEFT JOIN 语义，并对括号连接与 CTE 递归处理
This commit is contained in:
@@ -47,6 +47,7 @@ import cn.rosercode.ledgerly.service.AiQueryService;
|
||||
import cn.rosercode.ledgerly.service.AiRecordService;
|
||||
import cn.rosercode.ledgerly.service.AiRelationService;
|
||||
import cn.rosercode.ledgerly.service.AiRuleService;
|
||||
import cn.rosercode.ledgerly.service.AiSqlQueryService;
|
||||
import cn.rosercode.ledgerly.service.AiStatisticsService;
|
||||
import cn.rosercode.ledgerly.service.AiSuggestionService;
|
||||
import cn.rosercode.ledgerly.service.AiTagService;
|
||||
@@ -61,6 +62,7 @@ import cn.rosercode.ledgerly.vo.AiRecordImageResultVO;
|
||||
import cn.rosercode.ledgerly.vo.AiRecordResultVO;
|
||||
import cn.rosercode.ledgerly.vo.AiRelationResultVO;
|
||||
import cn.rosercode.ledgerly.vo.AiRuleSuggestResultVO;
|
||||
import cn.rosercode.ledgerly.vo.AiSqlQueryResultVO;
|
||||
import cn.rosercode.ledgerly.vo.AiStatisticsResultVO;
|
||||
import cn.rosercode.ledgerly.vo.AiSuggestionVO;
|
||||
import cn.rosercode.ledgerly.vo.AiTagResultVO;
|
||||
@@ -91,6 +93,7 @@ public class AiController {
|
||||
private final AiChannelService aiChannelService;
|
||||
private final AiTagService aiTagService;
|
||||
private final AiRuleService aiRuleService;
|
||||
private final AiSqlQueryService aiSqlQueryService;
|
||||
private final AiStatisticsService aiStatisticsService;
|
||||
private final AiImageRecordService aiImageRecordService;
|
||||
private final AiImageRecordStreamService aiImageRecordStreamService;
|
||||
@@ -103,7 +106,8 @@ public class AiController {
|
||||
AiRecordService aiRecordService, AiDecorationService aiDecorationService,
|
||||
AiCategoryService aiCategoryService, AiChannelService aiChannelService,
|
||||
AiTagService aiTagService,
|
||||
AiRuleService aiRuleService, AiStatisticsService aiStatisticsService,
|
||||
AiRuleService aiRuleService, AiSqlQueryService aiSqlQueryService,
|
||||
AiStatisticsService aiStatisticsService,
|
||||
AiImageRecordService aiImageRecordService,
|
||||
AiImageRecordStreamService aiImageRecordStreamService,
|
||||
AiRelationService aiRelationService,
|
||||
@@ -118,6 +122,7 @@ public class AiController {
|
||||
this.aiChannelService = aiChannelService;
|
||||
this.aiTagService = aiTagService;
|
||||
this.aiRuleService = aiRuleService;
|
||||
this.aiSqlQueryService = aiSqlQueryService;
|
||||
this.aiStatisticsService = aiStatisticsService;
|
||||
this.aiImageRecordService = aiImageRecordService;
|
||||
this.aiImageRecordStreamService = aiImageRecordStreamService;
|
||||
@@ -230,6 +235,19 @@ public class AiController {
|
||||
return Result.success(aiQueryService.parse(userId, queryRequest.getQuery()));
|
||||
}
|
||||
|
||||
/**
|
||||
* 自然语言转 SQL 查询
|
||||
*
|
||||
* @param queryRequest 查询请求，携带自然语言语句
|
||||
* @return 查询结果（含生成的 SQL、列元数据与行数据）
|
||||
*/
|
||||
@PostMapping("/sql")
|
||||
@Operation(summary = "自然语言查数", description = "将自然语言转换为只读 SQL 并在当前用户数据上执行，返回结果集")
|
||||
public Result<AiSqlQueryResultVO> sqlQuery(@RequestBody @Valid AiQueryRequest queryRequest) {
|
||||
Long userId = UserContext.getUserId();
|
||||
return Result.success(aiSqlQueryService.query(userId, queryRequest.getQuery()));
|
||||
}
|
||||
|
||||
/**
|
||||
* 解析自然语言记账内容为交易记录
|
||||
*
|
||||
|
||||
@@ -41,5 +41,8 @@ public enum AiCallType {
|
||||
STATISTICS,
|
||||
|
||||
/** 生成账单关系名称与备注 */
|
||||
RELATION
|
||||
RELATION,
|
||||
|
||||
/** 自然语言转换为只读 SQL 查询 */
|
||||
SQL
|
||||
}
|
||||
|
||||
@@ -124,6 +124,22 @@ public class PromptTemplateService {
|
||||
return render("ai-statistics-system", variables);
|
||||
}
|
||||
|
||||
/**
|
||||
* 渲染自然语言转 SQL 的系统提示词（模板 {@code ai-sql-system}）。
|
||||
*
|
||||
* @param dialect 当前数据库方言（MySQL / SQLite）
|
||||
* @param today 当天日期（yyyy-MM-dd）
|
||||
* @param schema 动态读取的表结构描述
|
||||
* @return 系统提示词
|
||||
*/
|
||||
public String textToSqlSystemPrompt(String dialect, String today, String schema) {
|
||||
Map<String, Object> variables = new LinkedHashMap<>();
|
||||
variables.put("dialect", dialect);
|
||||
variables.put("today", today);
|
||||
variables.put("schema", schema);
|
||||
return render("ai-sql-system", variables);
|
||||
}
|
||||
|
||||
/**
|
||||
* 渲染生成分类的系统提示词（模板 {@code ai-category-system}）。
|
||||
*
|
||||
|
||||
@@ -0,0 +1,23 @@
|
||||
package cn.rosercode.ledgerly.service;
|
||||
|
||||
import cn.rosercode.ledgerly.vo.AiSqlQueryResultVO;
|
||||
|
||||
/**
|
||||
* 自然语言转 SQL 查询服务。
|
||||
*
|
||||
* <p>将用户输入的自然语言交给大模型生成只读 SELECT 语句，经安全校验后在
|
||||
* 当前用户的数据上执行并返回结果。</p>
|
||||
*
|
||||
* @date 2026-09-24 09:01:13
|
||||
*/
|
||||
public interface AiSqlQueryService {
|
||||
|
||||
/**
|
||||
* 将自然语言转换为只读 SQL 并在当前用户数据上执行。
|
||||
*
|
||||
* @param userId 当前用户ID
|
||||
* @param query 用户输入的自然语言
|
||||
* @return 查询结果（含生成的 SQL、列元数据与行数据）
|
||||
*/
|
||||
AiSqlQueryResultVO query(Long userId, String query);
|
||||
}
|
||||
@@ -0,0 +1,325 @@
|
||||
package cn.rosercode.ledgerly.service.impl;
|
||||
|
||||
import java.sql.Connection;
|
||||
import java.sql.PreparedStatement;
|
||||
import java.sql.ResultSet;
|
||||
import java.sql.ResultSetMetaData;
|
||||
import java.sql.SQLException;
|
||||
import java.sql.Types;
|
||||
import java.time.LocalDate;
|
||||
import java.time.ZoneId;
|
||||
import java.time.format.DateTimeFormatter;
|
||||
import java.util.ArrayList;
|
||||
import java.util.Base64;
|
||||
import java.util.LinkedHashMap;
|
||||
import java.util.List;
|
||||
import java.util.Locale;
|
||||
import java.util.Map;
|
||||
import javax.sql.DataSource;
|
||||
|
||||
import com.fasterxml.jackson.core.JsonProcessingException;
|
||||
import com.fasterxml.jackson.databind.JsonNode;
|
||||
import com.fasterxml.jackson.databind.ObjectMapper;
|
||||
import lombok.extern.slf4j.Slf4j;
|
||||
import org.springframework.stereotype.Service;
|
||||
|
||||
import cn.rosercode.ledgerly.client.DeepSeekClient;
|
||||
import cn.rosercode.ledgerly.client.DeepSeekResponse;
|
||||
import cn.rosercode.ledgerly.common.BusinessException;
|
||||
import cn.rosercode.ledgerly.config.datasource.DataSourceContextHolder;
|
||||
import cn.rosercode.ledgerly.config.datasource.DataSourceType;
|
||||
import cn.rosercode.ledgerly.entity.AiConfig;
|
||||
import cn.rosercode.ledgerly.enums.AiCallType;
|
||||
import cn.rosercode.ledgerly.prompt.PromptTemplateService;
|
||||
import cn.rosercode.ledgerly.service.AiConfigService;
|
||||
import cn.rosercode.ledgerly.service.AiSqlQueryService;
|
||||
import cn.rosercode.ledgerly.service.AiUsageService;
|
||||
import cn.rosercode.ledgerly.util.sql.TextToSqlGuard;
|
||||
import cn.rosercode.ledgerly.util.sql.TextToSqlSchemaProvider;
|
||||
import cn.rosercode.ledgerly.vo.AiSqlColumnVO;
|
||||
import cn.rosercode.ledgerly.vo.AiSqlQueryResultVO;
|
||||
|
||||
/**
|
||||
* 自然语言转 SQL 查询服务实现类，负责提示词组装、模型调用与只读执行。
|
||||
*
|
||||
* @date 2026-09-24 09:01:13
|
||||
*/
|
||||
@Slf4j
|
||||
@Service
|
||||
public class AiSqlQueryServiceImpl implements AiSqlQueryService {
|
||||
|
||||
/** 日期格式 */
|
||||
private static final DateTimeFormatter DATE_FMT = DateTimeFormatter.ofPattern("yyyy-MM-dd");
|
||||
|
||||
/** 日期时间格式 */
|
||||
private static final DateTimeFormatter DATETIME_FMT = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
|
||||
|
||||
/** 时间格式 */
|
||||
private static final DateTimeFormatter TIME_FMT = DateTimeFormatter.ofPattern("HH:mm:ss");
|
||||
|
||||
/** 查询超时时间（秒） */
|
||||
private static final int QUERY_TIMEOUT_SECONDS = 15;
|
||||
|
||||
private final AiConfigService aiConfigService;
|
||||
private final DeepSeekClient deepSeekClient;
|
||||
private final AiUsageService aiUsageService;
|
||||
private final ObjectMapper objectMapper;
|
||||
private final PromptTemplateService promptTemplateService;
|
||||
private final TextToSqlSchemaProvider schemaProvider;
|
||||
private final DataSource dataSource;
|
||||
|
||||
public AiSqlQueryServiceImpl(AiConfigService aiConfigService,
|
||||
DeepSeekClient deepSeekClient,
|
||||
AiUsageService aiUsageService,
|
||||
ObjectMapper objectMapper,
|
||||
PromptTemplateService promptTemplateService,
|
||||
TextToSqlSchemaProvider schemaProvider,
|
||||
DataSource dataSource) {
|
||||
this.aiConfigService = aiConfigService;
|
||||
this.deepSeekClient = deepSeekClient;
|
||||
this.aiUsageService = aiUsageService;
|
||||
this.objectMapper = objectMapper;
|
||||
this.promptTemplateService = promptTemplateService;
|
||||
this.schemaProvider = schemaProvider;
|
||||
this.dataSource = dataSource;
|
||||
}
|
||||
|
||||
/**
|
||||
* {@inheritDoc}
|
||||
*
|
||||
* 构造只读 SQL 的提示词并调用模型，解析结果后经安全网关校验并在只读连接上执行。
|
||||
*/
|
||||
@Override
|
||||
public AiSqlQueryResultVO query(Long userId, String query) {
|
||||
if (query == null || query.isBlank()) {
|
||||
throw new BusinessException("请输入查询内容");
|
||||
}
|
||||
AiConfig config = aiConfigService.getRawConfig(userId);
|
||||
if (config == null || !Boolean.TRUE.equals(config.getEnabled())) {
|
||||
throw new BusinessException("AI 功能未启用，请先在 AI 设置中开启");
|
||||
}
|
||||
if (isBlank(config.getApiKey())) {
|
||||
throw new BusinessException("请先配置 DeepSeek API Key");
|
||||
}
|
||||
|
||||
String systemPrompt = promptTemplateService.textToSqlSystemPrompt(
|
||||
resolveDialect(), LocalDate.now().format(DATE_FMT), schemaProvider.describe());
|
||||
long start = System.currentTimeMillis();
|
||||
DeepSeekResponse aiResponse;
|
||||
try {
|
||||
aiResponse = deepSeekClient.chat(config.getBaseUrl(), config.getApiKey(), config.getModel(),
|
||||
systemPrompt, query);
|
||||
} catch (RuntimeException e) {
|
||||
aiUsageService.recordFailure(userId, AiCallType.SQL, config.getModel(), 0,
|
||||
System.currentTimeMillis() - start, e.getMessage());
|
||||
throw e;
|
||||
}
|
||||
aiUsageService.recordSuccess(userId, AiCallType.SQL, config.getModel(), 0,
|
||||
aiResponse, System.currentTimeMillis() - start);
|
||||
|
||||
JsonNode root = parseResponse(aiResponse.getContent());
|
||||
String sql = root.path("sql").asText("");
|
||||
if (isBlank(sql)) {
|
||||
throw new BusinessException("AI 未能生成查询语句，请换个问法重试");
|
||||
}
|
||||
String explanation = root.path("explanation").asText("");
|
||||
String chartType = normalizeChartType(root.path("chartType").asText(""));
|
||||
|
||||
TextToSqlGuard.GuardedSql guarded = TextToSqlGuard.guard(sql, userId);
|
||||
AiSqlQueryResultVO result = execute(guarded, userId);
|
||||
result.setSql(guarded.sql());
|
||||
result.setExplanation(explanation);
|
||||
result.setChartType(chartType);
|
||||
log.info("AI SQL 查询完成: userId={}, 耗时={}ms, 行数={}, 截断={}",
|
||||
userId, System.currentTimeMillis() - start, result.getRowCount(), result.isTruncated());
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* 在只读连接上执行经安全网关处理后的 SQL，并组装列元数据与行数据。
|
||||
*
|
||||
* @param guarded 校验改写后的 SQL
|
||||
* @param userId 当前用户ID，用于日志
|
||||
* @return 查询结果
|
||||
*/
|
||||
private AiSqlQueryResultVO execute(TextToSqlGuard.GuardedSql guarded, Long userId) {
|
||||
List<AiSqlColumnVO> columns = new ArrayList<>();
|
||||
List<Map<String, Object>> rows = new ArrayList<>();
|
||||
try (Connection connection = dataSource.getConnection()) {
|
||||
setReadOnlyQuietly(connection);
|
||||
try (PreparedStatement statement = connection.prepareStatement(guarded.sql())) {
|
||||
statement.setQueryTimeout(QUERY_TIMEOUT_SECONDS);
|
||||
try (ResultSet resultSet = statement.executeQuery()) {
|
||||
readColumns(resultSet.getMetaData(), columns);
|
||||
while (resultSet.next()) {
|
||||
Map<String, Object> row = new LinkedHashMap<>();
|
||||
for (int i = 1; i <= columns.size(); i++) {
|
||||
row.put(columns.get(i - 1).getKey(), normalizeValue(resultSet.getObject(i)));
|
||||
}
|
||||
rows.add(row);
|
||||
}
|
||||
}
|
||||
}
|
||||
} catch (SQLException e) {
|
||||
log.warn("AI SQL 执行失败: userId={}, 原因={}", userId, e.getMessage());
|
||||
throw new BusinessException("查询执行失败，请换个问法重试");
|
||||
}
|
||||
|
||||
AiSqlQueryResultVO result = new AiSqlQueryResultVO();
|
||||
result.setColumns(columns);
|
||||
result.setRows(rows);
|
||||
result.setRowCount(rows.size());
|
||||
result.setTruncated(guarded.truncated() && rows.size() >= TextToSqlGuard.MAX_ROWS);
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* 读取结果集元数据，生成列定义。
|
||||
*
|
||||
* @param metaData 结果集元数据
|
||||
* @param columns 列定义输出
|
||||
* @throws SQLException 读取元数据失败
|
||||
*/
|
||||
private void readColumns(ResultSetMetaData metaData, List<AiSqlColumnVO> columns) throws SQLException {
|
||||
int columnCount = metaData.getColumnCount();
|
||||
for (int i = 1; i <= columnCount; i++) {
|
||||
String label = metaData.getColumnLabel(i);
|
||||
if (isBlank(label)) {
|
||||
label = metaData.getColumnName(i);
|
||||
}
|
||||
AiSqlColumnVO column = new AiSqlColumnVO();
|
||||
column.setKey(label);
|
||||
column.setTitle(label);
|
||||
column.setType(mapColumnType(metaData.getColumnType(i)));
|
||||
columns.add(column);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 将 JDBC 类型映射为前端可识别的类型名。
|
||||
*
|
||||
* @param sqlType JDBC 类型
|
||||
* @return 类型名：NUMBER / STRING / DATE / DATETIME / BOOLEAN
|
||||
*/
|
||||
private String mapColumnType(int sqlType) {
|
||||
return switch (sqlType) {
|
||||
case Types.INTEGER, Types.BIGINT, Types.SMALLINT, Types.TINYINT,
|
||||
Types.DECIMAL, Types.NUMERIC, Types.FLOAT, Types.DOUBLE, Types.REAL -> "NUMBER";
|
||||
case Types.DATE -> "DATE";
|
||||
case Types.TIMESTAMP, Types.TIMESTAMP_WITH_TIMEZONE, Types.TIME, Types.TIME_WITH_TIMEZONE -> "DATETIME";
|
||||
case Types.BOOLEAN, Types.BIT -> "BOOLEAN";
|
||||
default -> "STRING";
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 将结果值转换为便于前端展示的形式。
|
||||
*
|
||||
* @param value 原始值
|
||||
* @return 转换后的值
|
||||
*/
|
||||
private Object normalizeValue(Object value) {
|
||||
if (value instanceof byte[] bytes) {
|
||||
return Base64.getEncoder().encodeToString(bytes);
|
||||
}
|
||||
if (value instanceof java.sql.Timestamp timestamp) {
|
||||
return timestamp.toLocalDateTime().format(DATETIME_FMT);
|
||||
}
|
||||
if (value instanceof java.sql.Date date) {
|
||||
return date.toLocalDate().format(DATE_FMT);
|
||||
}
|
||||
if (value instanceof java.sql.Time time) {
|
||||
return time.toLocalTime().format(TIME_FMT);
|
||||
}
|
||||
if (value instanceof java.util.Date date) {
|
||||
return date.toInstant().atZone(ZoneId.systemDefault()).toLocalDateTime().format(DATETIME_FMT);
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
/**
|
||||
* 解析模型返回的 JSON 内容。
|
||||
*
|
||||
* @param content 模型输出
|
||||
* @return JSON 根节点
|
||||
*/
|
||||
private JsonNode parseResponse(String content) {
|
||||
try {
|
||||
return objectMapper.readTree(stripCodeFence(content));
|
||||
} catch (JsonProcessingException e) {
|
||||
throw new BusinessException("AI 返回内容不是有效 JSON，请重试");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 归一化模型建议的展示类型。
|
||||
*
|
||||
* @param value 模型输出
|
||||
* @return SCALAR / TABLE / BAR / PIE
|
||||
*/
|
||||
private String normalizeChartType(String value) {
|
||||
if (value == null) {
|
||||
return "TABLE";
|
||||
}
|
||||
String upper = value.trim().toUpperCase(Locale.ROOT);
|
||||
return switch (upper) {
|
||||
case "SCALAR", "BAR", "PIE", "TABLE" -> upper;
|
||||
default -> "TABLE";
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 解析当前数据库方言。
|
||||
*
|
||||
* @return MySQL / SQLite
|
||||
*/
|
||||
private String resolveDialect() {
|
||||
return DataSourceType.SQLITE.equals(DataSourceContextHolder.getType()) ? "SQLite" : "MySQL";
|
||||
}
|
||||
|
||||
/**
|
||||
* 尝试将连接设为只读，失败时忽略（SQL 已在校验阶段限制为只读）。
|
||||
*
|
||||
* @param connection 数据库连接
|
||||
*/
|
||||
private void setReadOnlyQuietly(Connection connection) {
|
||||
try {
|
||||
connection.setReadOnly(true);
|
||||
} catch (SQLException e) {
|
||||
log.debug("设置只读连接失败（忽略）: {}", e.getMessage());
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 去除模型可能附加的 Markdown 代码块围栏。
|
||||
*
|
||||
* @param content 原始内容
|
||||
* @return 清理后的内容
|
||||
*/
|
||||
private String stripCodeFence(String content) {
|
||||
if (content == null) {
|
||||
return "";
|
||||
}
|
||||
String cleaned = content.trim();
|
||||
if (cleaned.startsWith("```")) {
|
||||
int firstLineEnd = cleaned.indexOf('\n');
|
||||
if (firstLineEnd > 0) {
|
||||
cleaned = cleaned.substring(firstLineEnd + 1);
|
||||
}
|
||||
if (cleaned.endsWith("```")) {
|
||||
cleaned = cleaned.substring(0, cleaned.length() - 3);
|
||||
}
|
||||
}
|
||||
return cleaned.trim();
|
||||
}
|
||||
|
||||
/**
|
||||
* 判断字符串是否为空白。
|
||||
*
|
||||
* @param value 待判断字符串
|
||||
* @return 为 null 或全空白时返回 true
|
||||
*/
|
||||
private boolean isBlank(String value) {
|
||||
return value == null || value.isBlank();
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,542 @@
|
||||
package cn.rosercode.ledgerly.util.sql;
|
||||
|
||||
import java.util.ArrayList;
|
||||
import java.util.LinkedHashSet;
|
||||
import java.util.List;
|
||||
import java.util.Locale;
|
||||
import java.util.Map;
|
||||
import java.util.Set;
|
||||
import java.util.regex.Pattern;
|
||||
|
||||
import net.sf.jsqlparser.expression.Expression;
|
||||
import net.sf.jsqlparser.expression.ExpressionVisitor;
|
||||
import net.sf.jsqlparser.expression.ExpressionVisitorAdapter;
|
||||
import net.sf.jsqlparser.expression.Function;
|
||||
import net.sf.jsqlparser.expression.LongValue;
|
||||
import net.sf.jsqlparser.expression.operators.conditional.AndExpression;
|
||||
import net.sf.jsqlparser.expression.operators.relational.EqualsTo;
|
||||
import net.sf.jsqlparser.expression.operators.relational.InExpression;
|
||||
import net.sf.jsqlparser.parser.CCJSqlParserUtil;
|
||||
import net.sf.jsqlparser.schema.Column;
|
||||
import net.sf.jsqlparser.schema.Table;
|
||||
import net.sf.jsqlparser.statement.Statements;
|
||||
import net.sf.jsqlparser.statement.select.FromItem;
|
||||
import net.sf.jsqlparser.statement.select.Join;
|
||||
import net.sf.jsqlparser.statement.select.LateralSubSelect;
|
||||
import net.sf.jsqlparser.statement.select.Limit;
|
||||
import net.sf.jsqlparser.statement.select.OrderByElement;
|
||||
import net.sf.jsqlparser.statement.select.ParenthesedFromItem;
|
||||
import net.sf.jsqlparser.statement.select.ParenthesedSelect;
|
||||
import net.sf.jsqlparser.statement.select.PlainSelect;
|
||||
import net.sf.jsqlparser.statement.select.Select;
|
||||
import net.sf.jsqlparser.statement.select.SelectItem;
|
||||
import net.sf.jsqlparser.statement.select.SelectVisitor;
|
||||
import net.sf.jsqlparser.statement.select.SetOperationList;
|
||||
import net.sf.jsqlparser.statement.select.TableStatement;
|
||||
import net.sf.jsqlparser.statement.select.Values;
|
||||
import net.sf.jsqlparser.statement.select.WithItem;
|
||||
|
||||
import cn.rosercode.ledgerly.common.BusinessException;
|
||||
|
||||
/**
|
||||
* 自然语言转 SQL 的安全网关。
|
||||
*
|
||||
* <p>对模型生成的 SQL 做只读校验与改写，保证无论模型输出如何，都只可能以
|
||||
* 只读方式访问当前用户自己的数据：</p>
|
||||
* <ul>
|
||||
* <li>仅允许单条 SELECT 语句，拒绝任何写操作、DDL 与多语句；</li>
|
||||
* <li>仅允许查询白名单中的业务表，拒绝系统表与其它表；</li>
|
||||
* <li>对所有直接引用的表强制注入 user_id 隔离条件，对无 user_id 的关联表
|
||||
* 通过父表归属子查询限制；</li>
|
||||
* <li>限制结果行数上限，防止超大结果集。</li>
|
||||
* </ul>
|
||||
*
|
||||
* @date 2026-09-24 09:01:13
|
||||
*/
|
||||
public final class TextToSqlGuard {
|
||||
|
||||
/** 单次查询返回的最大行数 */
|
||||
public static final int MAX_ROWS = 1000;
|
||||
|
||||
/** 直接持有 user_id 列的业务表，集中维护于 {@link TextToSqlTables} */
|
||||
private static final Set<String> USER_TABLES = TextToSqlTables.USER_TABLES;
|
||||
|
||||
/** 无 user_id 列的关联表 -> [父表, 外键] */
|
||||
private static final Map<String, String[]> CHILD_TABLES = TextToSqlTables.CHILD_TABLES;
|
||||
|
||||
/** 允许查询的全部业务表 */
|
||||
private static final Set<String> ALLOWED_TABLES = Set.copyOf(TextToSqlTables.ALLOWED_TABLES);
|
||||
|
||||
/** 禁止调用的危险函数 */
|
||||
private static final Set<String> FORBIDDEN_FUNCTIONS = Set.of(
|
||||
"SLEEP",
|
||||
"BENCHMARK",
|
||||
"LOAD_FILE",
|
||||
"LOAD_EXTENSION",
|
||||
"SYS_EVAL",
|
||||
"PG_SLEEP");
|
||||
|
||||
/** 禁止出现的危险子句 */
|
||||
private static final Pattern FORBIDDEN_OUTPUT = Pattern.compile(
|
||||
"(?i)\\binto\\s+(outfile|dumpfile)\\b");
|
||||
|
||||
private TextToSqlGuard() {
|
||||
}
|
||||
|
||||
/**
|
||||
* 校验并改写模型生成的 SQL。
|
||||
*
|
||||
* @param rawSql 模型生成的原始 SQL
|
||||
* @param userId 当前用户ID
|
||||
* @return 校验改写后的 SQL 与截断标记
|
||||
*/
|
||||
public static GuardedSql guard(String rawSql, long userId) {
|
||||
if (rawSql == null || rawSql.isBlank()) {
|
||||
throw new BusinessException("AI 未生成有效的查询语句，请换个问法重试");
|
||||
}
|
||||
String trimmed = rawSql.trim();
|
||||
Statements statements;
|
||||
try {
|
||||
statements = CCJSqlParserUtil.parseStatements(trimmed);
|
||||
} catch (Exception e) {
|
||||
throw new BusinessException("AI 生成的语句无法解析，请换个问法重试");
|
||||
}
|
||||
if (statements.size() != 1 || !(statements.get(0) instanceof Select select)) {
|
||||
throw new BusinessException("只允许执行单条查询语句");
|
||||
}
|
||||
if (FORBIDDEN_OUTPUT.matcher(trimmed).find()) {
|
||||
throw new BusinessException("查询中包含不被允许的语句");
|
||||
}
|
||||
|
||||
GuardContext context = new GuardContext(userId);
|
||||
try {
|
||||
select.accept(context.selectVisitor, null);
|
||||
} catch (GuardRejectedException e) {
|
||||
throw new BusinessException(e.getMessage());
|
||||
}
|
||||
for (String table : context.usedTables) {
|
||||
if (!ALLOWED_TABLES.contains(table)) {
|
||||
throw new BusinessException("查询包含不允许访问的数据表：" + table);
|
||||
}
|
||||
}
|
||||
boolean truncated = applyRowLimit(select);
|
||||
return new GuardedSql(select.toString(), truncated);
|
||||
}
|
||||
|
||||
/**
|
||||
* 对查询根节点应用行数上限。
|
||||
*
|
||||
* @param select 查询语句
|
||||
* @return 是否对原始行数进行了收敛（可能截断）
|
||||
*/
|
||||
private static boolean applyRowLimit(Select select) {
|
||||
Limit limit;
|
||||
if (select instanceof PlainSelect plainSelect) {
|
||||
limit = plainSelect.getLimit();
|
||||
} else if (select instanceof SetOperationList setOperationList) {
|
||||
limit = setOperationList.getLimit();
|
||||
} else if (select instanceof ParenthesedSelect parenthesedSelect) {
|
||||
return applyRowLimit(parenthesedSelect.getSelect());
|
||||
} else {
|
||||
return false;
|
||||
}
|
||||
if (limit == null || limit.getRowCount() == null) {
|
||||
select.setLimit(new Limit().withRowCount(new LongValue(MAX_ROWS)));
|
||||
return true;
|
||||
}
|
||||
Expression rowCount = limit.getRowCount();
|
||||
if (rowCount instanceof LongValue longValue) {
|
||||
if (longValue.getValue() > MAX_ROWS) {
|
||||
limit.setRowCount(new LongValue(MAX_ROWS));
|
||||
return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
limit.setRowCount(new LongValue(MAX_ROWS));
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* 归一化表名，去除 schema 前缀、引号并转为小写。
|
||||
*
|
||||
* @param tableName 原始表名
|
||||
* @return 归一化后的表名
|
||||
*/
|
||||
private static String normalize(String tableName) {
|
||||
String name = tableName;
|
||||
int index = name.lastIndexOf('.');
|
||||
if (index >= 0) {
|
||||
name = name.substring(index + 1);
|
||||
}
|
||||
return name.replace("`", "").replace("\"", "").toLowerCase(Locale.ROOT);
|
||||
}
|
||||
|
||||
/**
|
||||
* 取函数名最后一段。
|
||||
*
|
||||
* @param functionName 函数名
|
||||
* @return 最后一段名称
|
||||
*/
|
||||
private static String lastSegment(String functionName) {
|
||||
String name = functionName == null ? "" : functionName;
|
||||
int index = name.lastIndexOf('.');
|
||||
return index >= 0 ? name.substring(index + 1) : name;
|
||||
}
|
||||
|
||||
/**
|
||||
* 安全网关处理结果。
|
||||
*
|
||||
* @param sql 校验改写后的 SQL
|
||||
* @param truncated 是否因行数上限可能被截断
|
||||
*/
|
||||
public record GuardedSql(String sql, boolean truncated) {
|
||||
}
|
||||
|
||||
/**
|
||||
* 校验过程中的拒绝异常，便于统一转换为业务异常。
|
||||
*/
|
||||
private static final class GuardRejectedException extends RuntimeException {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
GuardRejectedException(String message) {
|
||||
super(message);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* SQL 遍历与改写上下文。
|
||||
*/
|
||||
private static final class GuardContext {
|
||||
|
||||
/** 当前用户ID，用于注入隔离条件 */
|
||||
private final long userId;
|
||||
|
||||
/** 遍历中收集到的全部表名 */
|
||||
private final Set<String> usedTables = new LinkedHashSet<>();
|
||||
|
||||
/** 查询语句访问器，递归处理子查询 */
|
||||
private final SelectVisitor<Void> selectVisitor;
|
||||
|
||||
/** 表达式访问器，递归发现表达式中的子查询 */
|
||||
private final ExpressionVisitor<Void> expressionVisitor;
|
||||
|
||||
GuardContext(long userId) {
|
||||
this.userId = userId;
|
||||
this.selectVisitor = new SelectVisitor<>() {
|
||||
|
||||
@Override
|
||||
public <S> Void visit(PlainSelect plainSelect, S context) {
|
||||
rewritePlainSelect(plainSelect);
|
||||
return null;
|
||||
}
|
||||
|
||||
@Override
|
||||
public <S> Void visit(SetOperationList setOperationList, S context) {
|
||||
rewriteWithItems(setOperationList.getWithItemsList());
|
||||
if (setOperationList.getSelects() != null) {
|
||||
for (Select select : setOperationList.getSelects()) {
|
||||
select.accept(this, context);
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
@Override
|
||||
public <S> Void visit(ParenthesedSelect parenthesedSelect, S context) {
|
||||
parenthesedSelect.getSelect().accept(this, context);
|
||||
return null;
|
||||
}
|
||||
|
||||
@Override
|
||||
public <S> Void visit(WithItem<?> withItem, S context) {
|
||||
withItem.getSelect().accept(this, context);
|
||||
return null;
|
||||
}
|
||||
|
||||
@Override
|
||||
public <S> Void visit(Values values, S context) {
|
||||
return null;
|
||||
}
|
||||
|
||||
@Override
|
||||
public <S> Void visit(LateralSubSelect lateralSubSelect, S context) {
|
||||
lateralSubSelect.getSelect().accept(this, context);
|
||||
return null;
|
||||
}
|
||||
|
||||
@Override
|
||||
public <S> Void visit(TableStatement tableStatement, S context) {
|
||||
return null;
|
||||
}
|
||||
};
|
||||
ExpressionVisitorAdapter<Void> adapter = new ExpressionVisitorAdapter<>() {
|
||||
|
||||
@Override
|
||||
public <S> Void visit(Function function, S context) {
|
||||
String name = lastSegment(function.getName()).toUpperCase(Locale.ROOT);
|
||||
if (FORBIDDEN_FUNCTIONS.contains(name)) {
|
||||
throw new GuardRejectedException("查询中包含不被允许的函数：" + function.getName());
|
||||
}
|
||||
return super.visit(function, context);
|
||||
}
|
||||
};
|
||||
adapter.setSelectVisitor(this.selectVisitor);
|
||||
this.expressionVisitor = adapter;
|
||||
}
|
||||
|
||||
/**
|
||||
* 处理单个 PlainSelect：递归子查询并注入用户隔离条件。
|
||||
*
|
||||
* @param plainSelect 待处理的查询
|
||||
*/
|
||||
private void rewritePlainSelect(PlainSelect plainSelect) {
|
||||
rewriteWithItems(plainSelect.getWithItemsList());
|
||||
if (plainSelect.getIntoTables() != null && !plainSelect.getIntoTables().isEmpty()) {
|
||||
throw new GuardRejectedException("不支持 SELECT ... INTO 语句");
|
||||
}
|
||||
if (plainSelect.getForClause() != null) {
|
||||
throw new GuardRejectedException("不支持锁定查询");
|
||||
}
|
||||
rewriteFromItem(plainSelect.getFromItem());
|
||||
if (plainSelect.getJoins() != null) {
|
||||
for (Join join : plainSelect.getJoins()) {
|
||||
rewriteFromItem(join.getRightItem());
|
||||
if (join.getOnExpressions() != null) {
|
||||
for (Expression expression : join.getOnExpressions()) {
|
||||
acceptExpression(expression);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
if (plainSelect.getSelectItems() != null) {
|
||||
for (SelectItem<?> item : plainSelect.getSelectItems()) {
|
||||
acceptExpression(item.getExpression());
|
||||
}
|
||||
}
|
||||
acceptExpression(plainSelect.getWhere());
|
||||
acceptExpression(plainSelect.getHaving());
|
||||
if (plainSelect.getGroupBy() != null
|
||||
&& plainSelect.getGroupBy().getGroupByExpressionList() != null) {
|
||||
for (Object item : plainSelect.getGroupBy().getGroupByExpressionList()) {
|
||||
if (item instanceof Expression expression) {
|
||||
acceptExpression(expression);
|
||||
}
|
||||
}
|
||||
}
|
||||
if (plainSelect.getOrderByElements() != null) {
|
||||
for (OrderByElement element : plainSelect.getOrderByElements()) {
|
||||
acceptExpression(element.getExpression());
|
||||
}
|
||||
}
|
||||
injectOwnTables(plainSelect);
|
||||
}
|
||||
|
||||
/**
|
||||
* 递归处理 CTE（WITH 子句），保证其中的表同样通过白名单校验并注入隔离条件。
|
||||
*
|
||||
* @param withItems CTE 列表
|
||||
*/
|
||||
private void rewriteWithItems(List<WithItem<?>> withItems) {
|
||||
if (withItems == null) {
|
||||
return;
|
||||
}
|
||||
for (WithItem<?> withItem : withItems) {
|
||||
withItem.getSelect().accept(selectVisitor, null);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 递归处理 FROM 项，收集表名并进入子查询。
|
||||
*
|
||||
* @param fromItem FROM 项
|
||||
*/
|
||||
private void rewriteFromItem(FromItem fromItem) {
|
||||
if (fromItem instanceof ParenthesedSelect parenthesedSelect) {
|
||||
parenthesedSelect.getSelect().accept(selectVisitor, null);
|
||||
} else if (fromItem instanceof ParenthesedFromItem parenthesedFromItem) {
|
||||
rewriteFromItem(parenthesedFromItem.getFromItem());
|
||||
if (parenthesedFromItem.getJoins() != null) {
|
||||
for (Join join : parenthesedFromItem.getJoins()) {
|
||||
rewriteFromItem(join.getRightItem());
|
||||
if (join.getOnExpressions() != null) {
|
||||
for (Expression expression : join.getOnExpressions()) {
|
||||
acceptExpression(expression);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
} else if (fromItem instanceof Table table) {
|
||||
collectTable(table);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 为当前查询直接引用的表注入用户隔离条件。
|
||||
*
|
||||
* <p>主表条件加入 WHERE；JOIN 的表条件加入其 ON 子句，避免在 LEFT JOIN
|
||||
* 下因 WHERE 过滤而丢弃右表未匹配的行（例如内置渠道不在 t_channel 中）。</p>
|
||||
*
|
||||
* @param plainSelect 当前查询
|
||||
*/
|
||||
private void injectOwnTables(PlainSelect plainSelect) {
|
||||
injectFromItem(plainSelect, plainSelect.getFromItem());
|
||||
if (plainSelect.getJoins() != null) {
|
||||
for (Join join : plainSelect.getJoins()) {
|
||||
injectJoinRightItem(plainSelect, join);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 递归为 FROM 项注入隔离条件，覆盖括号包裹的连接（ParenthesedFromItem）。
|
||||
*
|
||||
* @param plainSelect 当前查询
|
||||
* @param fromItem FROM 项，可能为 Table 或 ParenthesedFromItem
|
||||
*/
|
||||
private void injectFromItem(PlainSelect plainSelect, FromItem fromItem) {
|
||||
if (fromItem instanceof Table table) {
|
||||
collectTable(table);
|
||||
Expression condition = buildCondition(table);
|
||||
if (condition != null) {
|
||||
addWhereCondition(plainSelect, condition);
|
||||
}
|
||||
} else if (fromItem instanceof ParenthesedFromItem parenthesedFromItem) {
|
||||
injectFromItem(plainSelect, parenthesedFromItem.getFromItem());
|
||||
if (parenthesedFromItem.getJoins() != null) {
|
||||
for (Join join : parenthesedFromItem.getJoins()) {
|
||||
injectJoinRightItem(plainSelect, join);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 为 JOIN 右项注入隔离条件，覆盖括号包裹的连接。
|
||||
*
|
||||
* @param plainSelect 当前查询
|
||||
* @param join 连接
|
||||
*/
|
||||
private void injectJoinRightItem(PlainSelect plainSelect, Join join) {
|
||||
FromItem rightItem = join.getRightItem();
|
||||
if (rightItem instanceof Table table) {
|
||||
collectTable(table);
|
||||
Expression condition = buildCondition(table);
|
||||
if (condition != null) {
|
||||
addJoinCondition(plainSelect, join, condition);
|
||||
}
|
||||
} else if (rightItem instanceof ParenthesedFromItem parenthesedFromItem) {
|
||||
injectFromItem(plainSelect, parenthesedFromItem.getFromItem());
|
||||
if (parenthesedFromItem.getJoins() != null) {
|
||||
for (Join inner : parenthesedFromItem.getJoins()) {
|
||||
injectJoinRightItem(plainSelect, inner);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 收集表名并校验 schema 前缀，拒绝显式指定非 main schema 的表引用，避免跨库访问同名表。
|
||||
*
|
||||
* @param table 表
|
||||
*/
|
||||
private void collectTable(Table table) {
|
||||
String schema = table.getSchemaName();
|
||||
if (schema != null && !schema.isBlank() && !"main".equalsIgnoreCase(schema)) {
|
||||
throw new GuardRejectedException("查询中包含不允许访问的表：" + table.getFullyQualifiedName());
|
||||
}
|
||||
usedTables.add(normalize(table.getName()));
|
||||
}
|
||||
|
||||
/**
|
||||
* 构建表的用户隔离条件，未知表返回 null。
|
||||
*
|
||||
* @param table 表
|
||||
* @return 隔离条件，无需注入时返回 null
|
||||
*/
|
||||
private Expression buildCondition(Table table) {
|
||||
String name = normalize(table.getName());
|
||||
if (USER_TABLES.contains(name)) {
|
||||
return new EqualsTo(referenceColumn(table, "user_id"), new LongValue(userId));
|
||||
}
|
||||
if (CHILD_TABLES.containsKey(name)) {
|
||||
return buildChildCondition(table, CHILD_TABLES.get(name));
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* 为无 user_id 的关联表构建父表归属条件。
|
||||
*
|
||||
* @param table 关联表
|
||||
* @param relation 父表与外键
|
||||
* @return 归属条件
|
||||
*/
|
||||
private Expression buildChildCondition(Table table, String[] relation) {
|
||||
PlainSelect subQuery = new PlainSelect();
|
||||
subQuery.addSelectItems(new SelectItem<>(new Column("id")));
|
||||
subQuery.setFromItem(new Table(relation[0]));
|
||||
subQuery.setWhere(new EqualsTo(new Column("user_id"), new LongValue(userId)));
|
||||
ParenthesedSelect subSelect = new ParenthesedSelect();
|
||||
subSelect.setSelect(subQuery);
|
||||
return new InExpression(referenceColumn(table, relation[1]), subSelect);
|
||||
}
|
||||
|
||||
/**
|
||||
* 将条件加入 JOIN 的 ON 子句；USING 或无 ON 的连接退回 WHERE。
|
||||
*
|
||||
* @param plainSelect 当前查询
|
||||
* @param join 连接
|
||||
* @param condition 条件
|
||||
*/
|
||||
private void addJoinCondition(PlainSelect plainSelect, Join join, Expression condition) {
|
||||
if ((join.getUsingColumns() != null && !join.getUsingColumns().isEmpty())
|
||||
|| join.getOnExpressions() == null || join.getOnExpressions().isEmpty()) {
|
||||
addWhereCondition(plainSelect, condition);
|
||||
return;
|
||||
}
|
||||
Expression combined = null;
|
||||
for (Expression expression : join.getOnExpressions()) {
|
||||
combined = combined == null ? expression : new AndExpression(combined, expression);
|
||||
}
|
||||
join.setOnExpressions(List.of(new AndExpression(combined, condition)));
|
||||
}
|
||||
|
||||
/**
|
||||
* 构造带表引用或别名的列。
|
||||
*
|
||||
* @param table 表
|
||||
* @param columnName 列名
|
||||
* @return 列表达式
|
||||
*/
|
||||
private Column referenceColumn(Table table, String columnName) {
|
||||
String reference = table.getAlias() != null ? table.getAlias().getName() : table.getName();
|
||||
return new Column(new Table(reference), columnName);
|
||||
}
|
||||
|
||||
/**
|
||||
* 向查询的 WHERE 追加 AND 条件。
|
||||
*
|
||||
* @param plainSelect 查询
|
||||
* @param condition 条件
|
||||
*/
|
||||
private void addWhereCondition(PlainSelect plainSelect, Expression condition) {
|
||||
if (plainSelect.getWhere() == null) {
|
||||
plainSelect.setWhere(condition);
|
||||
} else {
|
||||
plainSelect.setWhere(new AndExpression(plainSelect.getWhere(), condition));
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 用表达式访问器递归处理表达式，发现其中的子查询。
|
||||
*
|
||||
* @param expression 表达式
|
||||
*/
|
||||
private void acceptExpression(Expression expression) {
|
||||
if (expression != null) {
|
||||
expression.accept(expressionVisitor, null);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,238 @@
|
||||
package cn.rosercode.ledgerly.util.sql;
|
||||
|
||||
import java.sql.Connection;
|
||||
import java.sql.DatabaseMetaData;
|
||||
import java.sql.ResultSet;
|
||||
import java.sql.SQLException;
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.Locale;
|
||||
import java.util.Map;
|
||||
import javax.sql.DataSource;
|
||||
|
||||
import lombok.extern.slf4j.Slf4j;
|
||||
import org.springframework.stereotype.Component;
|
||||
|
||||
import cn.rosercode.ledgerly.config.datasource.DataSourceContextHolder;
|
||||
|
||||
/**
|
||||
* 自然语言转 SQL 的表结构描述提供者。
|
||||
*
|
||||
* <p>通过 JDBC 元数据动态读取白名单表的列信息（列名、类型），因此新增、删除
|
||||
* 或修改字段后无需调整提示词；列的中文说明优先取 {@link TextToSqlTables} 的
|
||||
* 字典，缺失时回退数据库列注释（MySQL 支持，SQLite 无），仍缺失则只展示列名
|
||||
* 与类型。</p>
|
||||
*
|
||||
* <p>结果按当前数据源标识缓存，切换数据库后自动失效重建。</p>
|
||||
*
|
||||
* @date 2026-09-24 09:16:13
|
||||
*/
|
||||
@Slf4j
|
||||
@Component
|
||||
public class TextToSqlSchemaProvider {
|
||||
|
||||
/** 表结构缓存有效期（毫秒）：期间内不重复读取数据库元数据 */
|
||||
private static final long CACHE_TTL_MILLIS = 60_000L;
|
||||
|
||||
private final DataSource dataSource;
|
||||
|
||||
/** 缓存对应的数据源标识 */
|
||||
private volatile String cachedKey;
|
||||
|
||||
/** 缓存的表结构描述 */
|
||||
private volatile String cachedSchema;
|
||||
|
||||
/** 缓存生成时间戳 */
|
||||
private volatile long cachedAt;
|
||||
|
||||
public TextToSqlSchemaProvider(DataSource dataSource) {
|
||||
this.dataSource = dataSource;
|
||||
}
|
||||
|
||||
/**
|
||||
* 生成供提示词使用的表结构描述。
|
||||
*
|
||||
* @return 表结构文本
|
||||
*/
|
||||
public String describe() {
|
||||
String key = DataSourceContextHolder.getKey();
|
||||
String schema = cachedSchema;
|
||||
if (schema != null && key != null && key.equals(cachedKey)
|
||||
&& System.currentTimeMillis() - cachedAt < CACHE_TTL_MILLIS) {
|
||||
return schema;
|
||||
}
|
||||
String built = build();
|
||||
cachedSchema = built;
|
||||
cachedKey = key;
|
||||
cachedAt = System.currentTimeMillis();
|
||||
return built;
|
||||
}
|
||||
|
||||
/**
|
||||
* 读取全部白名单表的列并拼装描述。
|
||||
*
|
||||
* @return 表结构文本
|
||||
*/
|
||||
private String build() {
|
||||
StringBuilder builder = new StringBuilder();
|
||||
try (Connection connection = dataSource.getConnection()) {
|
||||
DatabaseMetaData metaData = connection.getMetaData();
|
||||
String catalog = connection.getCatalog();
|
||||
for (String table : TextToSqlTables.ALLOWED_TABLES) {
|
||||
appendTable(builder, table, readColumns(metaData, catalog, table));
|
||||
}
|
||||
builder.append(TextToSqlTables.RELATIONSHIPS);
|
||||
return builder.toString();
|
||||
} catch (SQLException e) {
|
||||
log.warn("读取数据库表结构失败，回退为字典说明: {}", e.getMessage());
|
||||
return buildFromDictionary();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 追加单张表的描述，元数据缺失时回退字典。
|
||||
*
|
||||
* @param builder 输出
|
||||
* @param table 表名
|
||||
* @param columns 列元数据
|
||||
*/
|
||||
private void appendTable(StringBuilder builder, String table, List<ColumnMeta> columns) {
|
||||
if (columns.isEmpty()) {
|
||||
appendFromDictionary(builder, table);
|
||||
return;
|
||||
}
|
||||
builder.append(table).append(' ').append(TextToSqlTables.TABLE_DESCRIPTIONS.getOrDefault(table, ""))
|
||||
.append("：\n");
|
||||
for (ColumnMeta column : columns) {
|
||||
if (column.name() == null) {
|
||||
continue;
|
||||
}
|
||||
if (TextToSqlTables.FORBIDDEN_COLUMNS.contains(column.name().toLowerCase(Locale.ROOT))) {
|
||||
continue;
|
||||
}
|
||||
builder.append("- ").append(column.name());
|
||||
if (notBlank(column.type())) {
|
||||
builder.append(' ').append(column.type());
|
||||
}
|
||||
String description = resolveDescription(table, column);
|
||||
if (notBlank(description)) {
|
||||
builder.append(' ').append(description);
|
||||
}
|
||||
builder.append('\n');
|
||||
}
|
||||
builder.append('\n');
|
||||
}
|
||||
|
||||
/**
|
||||
* 用字典追加单张表的描述。
|
||||
*
|
||||
* @param builder 输出
|
||||
* @param table 表名
|
||||
*/
|
||||
private void appendFromDictionary(StringBuilder builder, String table) {
|
||||
builder.append(table).append(' ').append(TextToSqlTables.TABLE_DESCRIPTIONS.getOrDefault(table, ""))
|
||||
.append("：\n");
|
||||
for (Map.Entry<String, String> entry : TextToSqlTables.columnDescriptions(table).entrySet()) {
|
||||
builder.append("- ").append(entry.getKey());
|
||||
if (notBlank(entry.getValue())) {
|
||||
builder.append(' ').append(entry.getValue());
|
||||
}
|
||||
builder.append('\n');
|
||||
}
|
||||
builder.append('\n');
|
||||
}
|
||||
|
||||
/**
|
||||
* 完全基于字典构建描述，作为元数据不可用时的兜底。
|
||||
*
|
||||
* @return 表结构文本
|
||||
*/
|
||||
private String buildFromDictionary() {
|
||||
StringBuilder builder = new StringBuilder();
|
||||
for (String table : TextToSqlTables.ALLOWED_TABLES) {
|
||||
appendFromDictionary(builder, table);
|
||||
}
|
||||
builder.append(TextToSqlTables.RELATIONSHIPS);
|
||||
return builder.toString();
|
||||
}
|
||||
|
||||
/**
|
||||
* 读取单张表的列元数据，兼容 catalog 与表名大小写差异。
|
||||
*
|
||||
* @param metaData 数据库元数据
|
||||
* @param catalog 当前 catalog
|
||||
* @param table 表名
|
||||
* @return 列元数据列表
|
||||
* @throws SQLException 读取失败
|
||||
*/
|
||||
private List<ColumnMeta> readColumns(DatabaseMetaData metaData, String catalog, String table)
|
||||
throws SQLException {
|
||||
List<ColumnMeta> columns = readColumns(metaData, catalog, null, table);
|
||||
if (columns.isEmpty()) {
|
||||
columns = readColumns(metaData, null, null, table);
|
||||
}
|
||||
if (columns.isEmpty()) {
|
||||
columns = readColumns(metaData, null, null, table.toUpperCase(Locale.ROOT));
|
||||
}
|
||||
return columns;
|
||||
}
|
||||
|
||||
/**
|
||||
* 按指定 catalog/schema 读取列元数据。
|
||||
*
|
||||
* @param metaData 数据库元数据
|
||||
* @param catalog catalog
|
||||
* @param schema schema
|
||||
* @param table 表名
|
||||
* @return 列元数据列表
|
||||
* @throws SQLException 读取失败
|
||||
*/
|
||||
private List<ColumnMeta> readColumns(DatabaseMetaData metaData, String catalog, String schema, String table)
|
||||
throws SQLException {
|
||||
List<ColumnMeta> columns = new ArrayList<>();
|
||||
try (ResultSet resultSet = metaData.getColumns(catalog, schema, table, "%")) {
|
||||
while (resultSet.next()) {
|
||||
columns.add(new ColumnMeta(
|
||||
resultSet.getString("COLUMN_NAME"),
|
||||
resultSet.getString("TYPE_NAME"),
|
||||
resultSet.getString("REMARKS")));
|
||||
}
|
||||
}
|
||||
return columns;
|
||||
}
|
||||
|
||||
/**
|
||||
* 解析列的中文说明：字典优先，其次数据库列注释。
|
||||
*
|
||||
* @param table 表名
|
||||
* @param column 列元数据
|
||||
* @return 中文说明，可能为空
|
||||
*/
|
||||
private String resolveDescription(String table, ColumnMeta column) {
|
||||
String description = TextToSqlTables.describeColumn(table, column.name());
|
||||
if (notBlank(description)) {
|
||||
return description;
|
||||
}
|
||||
return column.remarks();
|
||||
}
|
||||
|
||||
/**
|
||||
* 判断字符串是否非空。
|
||||
*
|
||||
* @param value 字符串
|
||||
* @return 非空返回 true
|
||||
*/
|
||||
private boolean notBlank(String value) {
|
||||
return value != null && !value.isBlank();
|
||||
}
|
||||
|
||||
/**
|
||||
* 列元数据。
|
||||
*
|
||||
* @param name 列名
|
||||
* @param type 类型名
|
||||
* @param remarks 列注释
|
||||
*/
|
||||
private record ColumnMeta(String name, String type, String remarks) {
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,165 @@
|
||||
package cn.rosercode.ledgerly.util.sql;
|
||||
|
||||
import java.util.LinkedHashMap;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* 自然语言转 SQL 可访问的表结构元数据。
|
||||
*
|
||||
* <p>集中维护允许模型查询的表白名单、表与列的中文说明以及表间关系。列的
|
||||
* 存在性与类型由 {@link TextToSqlSchemaProvider} 从数据库元数据动态读取，
|
||||
* 因此新增、删除或修改字段后无需调整提示词；本类中的中文说明仅作为可选的
|
||||
* 语义增强，字典未覆盖的新列仍会出现在提示词中（只是没有中文说明）。</p>
|
||||
*
|
||||
* <p>安全性说明：表名白名单是静态的，新增数据表不会自动对模型开放，必须
|
||||
* 在此显式登记。</p>
|
||||
*
|
||||
* @date 2026-09-24 09:16:13
|
||||
*/
|
||||
public final class TextToSqlTables {
|
||||
|
||||
/** 直接持有 user_id 列的业务表 */
|
||||
public static final Set<String> USER_TABLES = Set.of(
|
||||
"t_transaction",
|
||||
"t_category",
|
||||
"t_tag",
|
||||
"t_channel",
|
||||
"t_transaction_group",
|
||||
"t_rule");
|
||||
|
||||
/** 无 user_id 列的关联表 -> [父表, 外键] */
|
||||
public static final Map<String, String[]> CHILD_TABLES = Map.of(
|
||||
"t_transaction_tag", new String[]{"t_transaction", "transaction_id"},
|
||||
"t_transaction_group_item", new String[]{"t_transaction_group", "group_id"},
|
||||
"t_rule_tag", new String[]{"t_rule", "rule_id"});
|
||||
|
||||
/** 允许模型访问的表，顺序决定提示词中的展示顺序 */
|
||||
public static final List<String> ALLOWED_TABLES = List.of(
|
||||
"t_transaction",
|
||||
"t_category",
|
||||
"t_tag",
|
||||
"t_transaction_tag",
|
||||
"t_channel",
|
||||
"t_transaction_group",
|
||||
"t_transaction_group_item",
|
||||
"t_rule",
|
||||
"t_rule_tag");
|
||||
|
||||
/** 禁止出现在提示词与查询中的列（隐私与数据安全考虑） */
|
||||
public static final Set<String> FORBIDDEN_COLUMNS = Set.of("raw_data", "external_no");
|
||||
|
||||
/** 表名 -> 中文说明 */
|
||||
public static final Map<String, String> TABLE_DESCRIPTIONS = Map.of(
|
||||
"t_transaction", "收支记录（每行一笔）",
|
||||
"t_category", "分类",
|
||||
"t_tag", "标签",
|
||||
"t_transaction_tag", "交易与标签的关联",
|
||||
"t_channel", "用户自定义交易渠道",
|
||||
"t_transaction_group", "账单关系分组",
|
||||
"t_transaction_group_item", "账单关系分组的成员",
|
||||
"t_rule", "分类标签规则",
|
||||
"t_rule_tag", "规则与标签的关联");
|
||||
|
||||
/** 表关系说明，供模型理解连表方式 */
|
||||
public static final String RELATIONSHIPS = """
|
||||
表关系：t_transaction.category_id = t_category.id；t_transaction_tag.transaction_id = t_transaction.id 且 t_transaction_tag.tag_id = t_tag.id；t_transaction_group_item.group_id = t_transaction_group.id 且 t_transaction_group_item.transaction_id = t_transaction.id；t_rule_tag.rule_id = t_rule.id 且 t_rule_tag.tag_id = t_tag.id。""";
|
||||
|
||||
/** 表名 -> (列名 -> 中文说明)，作为可选的语义增强 */
|
||||
private static final Map<String, Map<String, String>> COLUMN_DESCRIPTIONS = buildColumnDescriptions();
|
||||
|
||||
private TextToSqlTables() {
|
||||
}
|
||||
|
||||
/**
|
||||
* 查询列的补充中文说明。
|
||||
*
|
||||
* @param table 表名
|
||||
* @param column 列名
|
||||
* @return 中文说明，未配置时返回 null
|
||||
*/
|
||||
public static String describeColumn(String table, String column) {
|
||||
Map<String, String> columns = COLUMN_DESCRIPTIONS.get(table);
|
||||
if (columns == null || column == null) {
|
||||
return null;
|
||||
}
|
||||
return columns.get(column.toLowerCase());
|
||||
}
|
||||
|
||||
/**
|
||||
* 查询某张表的全部列说明，用于元数据不可用时兜底拼接。
|
||||
*
|
||||
* @param table 表名
|
||||
* @return 列名到说明的映射，无配置时为空 Map
|
||||
*/
|
||||
public static Map<String, String> columnDescriptions(String table) {
|
||||
return COLUMN_DESCRIPTIONS.getOrDefault(table, Map.of());
|
||||
}
|
||||
|
||||
/**
|
||||
* 构建列说明字典。
|
||||
*
|
||||
* @return 表名到列说明的映射
|
||||
*/
|
||||
private static Map<String, Map<String, String>> buildColumnDescriptions() {
|
||||
Map<String, Map<String, String>> descriptions = new LinkedHashMap<>();
|
||||
descriptions.put("t_transaction", Map.ofEntries(
|
||||
Map.entry("id", "主键"),
|
||||
Map.entry("category_id", "分类ID，关联 t_category.id，可为空（表示未分类）"),
|
||||
Map.entry("type", "收支类型：INCOME 收入 / EXPENSE 支出"),
|
||||
Map.entry("amount", "金额，正数"),
|
||||
Map.entry("channel", "交易渠道编码（见 t_channel.code）"),
|
||||
Map.entry("remark", "备注"),
|
||||
Map.entry("remark_hidden", "备注是否隐藏，1 为隐藏"),
|
||||
Map.entry("transaction_time", "交易发生时间"),
|
||||
Map.entry("include_in_stats", "是否计入统计，1 为计入"),
|
||||
Map.entry("created_at", "创建时间"),
|
||||
Map.entry("updated_at", "更新时间")));
|
||||
descriptions.put("t_category", Map.of(
|
||||
"id", "主键",
|
||||
"name", "名称",
|
||||
"type", "收支类型：INCOME / EXPENSE",
|
||||
"icon", "图标",
|
||||
"sort_order", "排序"));
|
||||
descriptions.put("t_tag", Map.of(
|
||||
"id", "主键",
|
||||
"name", "名称",
|
||||
"color", "颜色",
|
||||
"sort_order", "排序"));
|
||||
descriptions.put("t_transaction_tag", Map.of(
|
||||
"id", "主键",
|
||||
"transaction_id", "交易ID，关联 t_transaction.id",
|
||||
"tag_id", "标签ID，关联 t_tag.id"));
|
||||
descriptions.put("t_channel", Map.of(
|
||||
"id", "主键",
|
||||
"code", "渠道编码，交易记录按此关联",
|
||||
"name", "渠道名称",
|
||||
"sort_order", "排序"));
|
||||
descriptions.put("t_transaction_group", Map.of(
|
||||
"id", "主键",
|
||||
"type", "关系类型：PARENT_CHILD 父子 / SIBLING 同级",
|
||||
"name", "名称",
|
||||
"remark", "备注"));
|
||||
descriptions.put("t_transaction_group_item", Map.of(
|
||||
"id", "主键",
|
||||
"group_id", "分组ID，关联 t_transaction_group.id",
|
||||
"transaction_id", "交易ID，关联 t_transaction.id",
|
||||
"role", "成员角色：PARENT/CHILD/MEMBER",
|
||||
"sort_order", "排序"));
|
||||
descriptions.put("t_rule", Map.of(
|
||||
"id", "主键",
|
||||
"name", "名称",
|
||||
"enabled", "是否启用，1 为启用",
|
||||
"type", "收支类型",
|
||||
"keyword", "关键词",
|
||||
"min_amount", "最小金额",
|
||||
"max_amount", "最大金额",
|
||||
"category_id", "分类ID"));
|
||||
descriptions.put("t_rule_tag", Map.of(
|
||||
"id", "主键",
|
||||
"rule_id", "规则ID，关联 t_rule.id",
|
||||
"tag_id", "标签ID，关联 t_tag.id"));
|
||||
return Map.copyOf(descriptions);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,21 @@
|
||||
package cn.rosercode.ledgerly.vo;
|
||||
|
||||
import lombok.Data;
|
||||
|
||||
/**
|
||||
* 自然语言转 SQL 查询结果的列视图对象。
|
||||
*
|
||||
* @date 2026-09-24 09:01:13
|
||||
*/
|
||||
@Data
|
||||
public class AiSqlColumnVO {
|
||||
|
||||
/** 列键，与行数据中的字段名一致 */
|
||||
private String key;
|
||||
|
||||
/** 列标题（取自 SQL 列别名） */
|
||||
private String title;
|
||||
|
||||
/** 列值类型：NUMBER / STRING / DATE / DATETIME / BOOLEAN */
|
||||
private String type;
|
||||
}
|
||||
@@ -0,0 +1,36 @@
|
||||
package cn.rosercode.ledgerly.vo;
|
||||
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
|
||||
import lombok.Data;
|
||||
|
||||
/**
|
||||
* 自然语言转 SQL 查询结果视图对象，承载生成的 SQL、列元数据与行数据。
|
||||
*
|
||||
* @date 2026-09-24 09:01:13
|
||||
*/
|
||||
@Data
|
||||
public class AiSqlQueryResultVO {
|
||||
|
||||
/** 生成的 SQL 语句（经安全校验与改写后的最终语句） */
|
||||
private String sql;
|
||||
|
||||
/** 查询意图说明 */
|
||||
private String explanation;
|
||||
|
||||
/** 建议的展示类型：SCALAR / TABLE / BAR / PIE */
|
||||
private String chartType;
|
||||
|
||||
/** 结果列元数据 */
|
||||
private List<AiSqlColumnVO> columns;
|
||||
|
||||
/** 结果行数据，按列顺序保序 */
|
||||
private List<Map<String, Object>> rows;
|
||||
|
||||
/** 返回行数 */
|
||||
private int rowCount;
|
||||
|
||||
/** 是否因行数上限被截断 */
|
||||
private boolean truncated;
|
||||
}
|
||||
@@ -0,0 +1,19 @@
|
||||
你是一个记账系统的 SQL 生成助手。请根据用户的自然语言，生成一条只读的 SELECT 查询语句，只输出 JSON，不要输出任何多余内容。
|
||||
当前数据库方言：[(${dialect})]。今天是 [(${today})]。
|
||||
|
||||
要求：
|
||||
1. 只能生成单条 SELECT 查询，禁止生成 INSERT、UPDATE、DELETE、DROP、ALTER 等任何写操作，禁止多语句，禁止 SELECT ... INTO 与 FOR UPDATE。
|
||||
2. 不需要也不要自己添加 user_id 条件，系统会自动把查询限制为当前登录用户的数据。
|
||||
3. 只能使用下面列出的表与列，禁止查询任何其它表（包括系统表）；禁止查询 raw_data、external_no 列。
|
||||
4. 允许 JOIN 连表、GROUP BY 聚合、子查询、聚合函数（SUM/COUNT/AVG/MAX/MIN）与日期函数。
|
||||
5. 日期函数必须使用当前方言支持的写法：SQLite 使用 strftime/date，例如 strftime('%Y-%m', transaction_time) 与 date('now','localtime')；MySQL 使用 DATE_FORMAT/DATE/CURDATE，例如 DATE_FORMAT(transaction_time,'%Y-%m')。
|
||||
6. 请为每个查询列起一个有意义的中文别名（AS），金额结果请保留两位小数。
|
||||
7. chartType 取值：结果为单个聚合值（如「上个月花了多少钱」）用 SCALAR；按维度分组的多行结果（如「按分类统计支出」）用 BAR 或 PIE；明细列表用 TABLE。
|
||||
8. explanation 用一句中文说明查询意图。
|
||||
9. 查询渠道时直接选择 t_transaction.channel（渠道编码，内置如 ALIPAY/WECHAT/MEITUAN/TAOBAO/JD/CMB/BOCOM/CASH，或用户自定义编码），前端会显示为渠道名称；不要为了取渠道名称去 JOIN t_channel，它仅存储用户自定义渠道。
|
||||
10. 若用户要求修改、删除、插入数据，或问题与记账数据无关、无法用上述表回答，请将 sql 置为空字符串 ""，并在 explanation 中用一句中文说明系统仅支持查询及原因，禁止编造无意义的查询。
|
||||
|
||||
数据表结构（由数据库实时读取，字段可能随版本变化，请以列出的实际列名为准；SQLite 的 DATETIME 列以 ISO8601 字符串存储，形如 2026-09-01T12:00:00）：
|
||||
[(${schema})]
|
||||
|
||||
输出格式：{"sql":"生成的 SELECT 语句","explanation":"查询意图说明","chartType":"SCALAR"}
|
||||
Reference in New Issue
Block a user