JavaFX Voice Query Lab

一个面向 JavaFX、语音交互和查询构造学习者的实验原型：把中文文本（可选语音转写）解析为结构化条件，预览并参数化执行 SQLite 单表或视图查询。

状态： Unreleased（目标首发 v0.1.0）· Experimental · Offline-first · Java 17

默认模式完全离线，不需要 API Key，也不会调用付费服务。它不是通用 NL2SQL 引擎，不包含生产级认证、权限、审计或多租户隔离，请勿直接连接敏感生产数据库。

为什么值得看

许多自然语言查询 Demo 只展示“模型返回一段 SQL”。本项目把中间安全边界显式拆开：数据库元数据决定可用表和列，固定 allowlist 决定操作符，用户值只进入 PreparedStatement 参数。没有云服务时，中文规则解析仍可完成可复现演示。

适合：

学习 JavaFX WebView 与 Java Bridge 协作；
理解自然语言条件如何落到可审计的查询对象；
演示 SQLite 元数据读取、动态 WHERE 与参数绑定；
为语音查询或 NL2SQL 原型准备离线测试基线。

能力与边界

能力	默认离线	显式开启云能力后
手工选择列、操作符和值	✓	✓
中文规则解析	✓	✓（云端失败自动回退）
SQLite 元数据、SQL 预览和参数化查询	✓	✓
麦克风/本地音频转写	—	可选 DashScope 或百度兼容模式
模型辅助条件解析	—	可选 DashScope Qwen

当前限制：

查询范围是一个 SQLite 表或视图；多表场景需先建立视图。
规则解析只覆盖有限中文表达，并非通用语言理解。
模型输出仍会经过列与操作符校验，不能绕过本地安全策略。
SQL 预览用于解释执行计划；实际执行始终使用参数化 SQL。
每次查询默认最多返回 200 行，可调但代码硬上限为 1000 行。
云服务可能传输文本/音频并产生费用，责任由运行者承担。

工作流

flowchart LR
    A["中文文本"] --> C["离线规则解析"]
    B["录音或音频"] -->|"显式云端 opt-in"| D["语音转写"]
    D --> E["模型解析或规则回退"]
    C --> F["结构化条件"]
    E --> F
    M["SQLite 元数据"] --> G["表与列 allowlist"]
    F --> G
    G --> H["固定操作符 + 参数绑定"]
    H --> I["查询结果"]

更详细的组件与信任边界见架构文档和安全设计。

快速开始

前置条件

64 位 JDK 17；项目会拒绝其他主版本。
首次构建需要网络下载 Maven 与依赖；应用运行的默认模式无需网络。

macOS / Linux：

./mvnw --batch-mode --no-transfer-progress verify
./mvnw --quiet compile exec:java

Windows PowerShell：

.\mvnw.cmd --batch-mode --no-transfer-progress verify
.\mvnw.cmd --quiet compile exec:java

首次启动会根据 sql/init.sql 在 data/voice_query.db 创建完全虚构的演示数据。data/ 是本地运行目录，不会进入 Git。

Windows 用户也可双击 快速启动.bat；它只是上述 Wrapper 命令的相对路径便捷入口，不是唯一启动方式。

5 分钟离线验证

保持默认表名 students，点击加载列信息。
在文本框输入：查询性别为女并且年龄小于18的学生。
点击解析，检查生成的两条结构化条件。
预览 SQL，然后执行查询。
确认结果来自本地虚构数据，整个过程不需要 Key。

可选云能力

只有同时设置开关和自己的 Key 才会调用 DashScope：

$env:VOICE_QUERY_CLOUD_ENABLED = "true"
$env:BAILIAN_API_KEY = "your-key-here"
.\mvnw.cmd --quiet compile exec:java

macOS / Linux 使用同名环境变量。不要把 Key 写入 config/application.properties、脚本、Issue 或提交历史。

环境变量	默认值	用途
`VOICE_QUERY_CLOUD_ENABLED`	`false`	云调用总开关，必须显式设为 `true`
`BAILIAN_API_KEY` / `DASHSCOPE_API_KEY`	空	DashScope 凭据，只从环境读取
`BAILIAN_BASE_URL`	官方北京端点	可选服务端点覆盖
`BAIDU_API_KEY` / `BAIDU_API_SECRET`	空	兼容语音模式凭据
`VOICE_QUERY_DB_PATH`	`data/voice_query.db`	本地数据库路径
`VOICE_QUERY_TABLE`	`students`	默认表或视图名
`VOICE_QUERY_RESULT_LIMIT`	`200`	返回行数，范围 `1..1000`，超出上限自动收敛为 1000
`VOICE_QUERY_BAIDU_ENABLED`	`false`	旧百度兼容适配器的额外 opt-in；默认弃用

云调用前请阅读服务商的数据处理条款和计费规则。启用云端模型解析时，项目会发送自然语言查询文本，以及当前目标表/视图的字段名和数据类型 schema；不会主动发送查询结果行，但 schema 本身也可能包含敏感业务信息。敏感数据库应保持 cloud=false，或先对字段名和输入内容完成脱敏。模型输入上限为 1000 字符，最大输出为 512 token，并另设响应字符上限。项目设置了连接/读取超时，并避免在日志中记录 Key、完整音频和查询正文。旧百度适配器默认关闭；启用时凭据通过 HTTPS POST body 发送，不放入 URL 查询串。第三方 SDK 的具体网络行为仍属于外部信任边界。

查询安全模型

表/视图： 名称先通过严格语法检查，再以参数查询 sqlite_schema；sqlite_* 内部对象被拒绝。
列：只能从目标表/视图的 PRAGMA table_info 元数据集合中选择。
操作符： 只允许 =, !=, <, >, <=, >=, LIKE, IS。
值：始终通过 PreparedStatement 参数绑定，不拼接到执行 SQL。
结果量： 每条 SELECT 都使用参数化 LIMIT，并受 1000 行硬上限约束。
模型输出： 与用户输入同样经过列、操作符和类型校验。

这降低了本 Demo 的 SQL 注入风险，但不替代数据库最小权限、鉴权、审计和生产安全评估。

测试

./mvnw --batch-mode --no-transfer-progress verify

测试默认强制 voicequery.cloud.enabled=false，覆盖：

操作符 allowlist 与恶意 SQL 片段拒绝；
列 allowlist、数值类型和 NOT CONTAINS 构造；
中文别名与规则解析；
内存 SQLite 中的参数绑定、视图查询、非法/内部表拒绝；
可配置查询上限及 1000 行硬上限；
云模型输入/输出预算；
即使环境存在 Key，显式关闭云能力时仍选择离线服务。

CI 使用 JDK 17 和同一 Wrapper verify，不会向付费 API 发请求。

config/                 无秘密的运行配置
docs/                   架构、安全、样例数据与发布审计
examples/               可公开、可审阅的输入示例
sql/init.sql            虚构演示库初始化
src/main/java/          JavaFX、解析、查询与可选云适配
src/main/resources/     WebView 页面、FXML 和样式
src/test/java/          离线单元与 SQLite 集成测试
data/                   本地数据库/录音（Git 忽略）

生成合成示例音频（Windows，可选）

examples/query_demo.txt 是公开文本源。运行 生成示例录音.bat 会使用 Windows SAPI 在 data/samples/ 生成本地 WAV；音频不会进入 Git。不同系统语音包的输出与许可可能不同，公开任何生成音频前请自行核对权利。

参与和报告问题

开发流程：CONTRIBUTING.md
漏洞私密报告：SECURITY.md
行为准则：CODE_OF_CONDUCT.md
版本变化：CHANGELOG.md

Roadmap 包括更多规则解析用例、可复现 UI 截图、可配置查询结果上限，以及对云适配器更细粒度的可替换测试接口。

项目来源与许可证

本项目由课程原型演化而来，当前开源价值是可审计的“文本/语音 → 条件对象 → 参数化查询”参考链路，而不是课程提交本身。

代码拟以 MIT License 发布。公开发布前，仓库所有者仍需在发布审计中确认全部源码、素材和许可证授权权利。