Add AI SQL generation and update project docs

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

feasibility_analysis.md

@@ -4,7 +4,7 @@
 
 可行性分析用于判断 HyperSql 在当前技术条件、开发时间、经济成本和实际使用场景下是否能够顺利完成。
 
-HyperSql 是一个基于 Java 24、JavaFX、Maven 和 SQLite 的轻量级数据库图形化管理工具，主要面向学生和 SQLite 初学者。目前项目已经完成了核心数据库浏览、表管理、数据行编辑和 SQLite 支持范围内的表结构编辑功能，后续将继续扩展备份恢复和 AI 辅助 SQL 生成。
+HyperSql 是一个基于 Java 24、JavaFX、Maven 和 SQLite 的轻量级数据库图形化管理工具，主要面向学生和 SQLite 初学者。目前项目已经完成了核心数据库浏览、表管理、数据行编辑、SQLite 支持范围内的表结构编辑、数据库备份恢复和 AI 辅助 SQL 生成功能。
 
 本项目从以下四个方面进行分析：
 
@@ -20,11 +20,13 @@ HyperSql 采用以下技术栈：
 | 技术 | 作用 | 当前使用情况 |
 |---|---|---|
 | Java 24 | 主要开发语言 | 已用于项目主要代码开发 |
-| JavaFX | 构建图形化用户界面 | 已实现主界面、表格、菜单、工具栏、创建表对话框、数据行编辑和结构编辑操作入口 |
-| Maven | 项目构建与依赖管理 | 已完成项目构建配置 |
+| JavaFX | 构建图形化用户界面 | 已实现主界面、表格、菜单、工具栏、创建表对话框、数据行编辑、结构编辑、备份恢复入口和 AI 设置/生成入口 |
+| Maven | 项目构建与依赖管理 | 已完成项目构建配置，并管理 JavaFX、SQLite JDBC、Jackson 等依赖 |
 | SQLite | 本地轻量级数据库 | 作为系统管理对象，并通过原生 ALTER TABLE 支持部分表结构编辑 |
-| SQLite JDBC | Java 程序访问 SQLite 数据库 | 已实现数据库连接、元数据读取、SQL 执行、数据行写入和表结构变更 |
-| AI API | 根据表结构和用户需求生成 SQL | 作为后续扩展功能，当前尚未实现 |
+| SQLite JDBC | Java 程序访问 SQLite 数据库 | 已实现数据库连接、元数据读取、SQL 执行、数据行写入、表结构变更、备份前检查点等操作 |
+| JDK HttpClient | 调用 AI API | 已用于请求 OpenAI 兼容接口和 Anthropic Claude Messages API |
+| Jackson | JSON 构造与解析 | 已用于构造 AI 请求体和解析 AI 返回结果 |
+| AI API | 根据表结构和用户需求生成 SQL | 已支持 OpenAI 兼容接口和 Anthropic Claude，API Key 由用户在 UI 中输入并仅保存在本次运行内存中 |
 
 ### 技术可行性说明
 
@@ -33,16 +35,16 @@ HyperSql 采用以下技术栈：
    - 当前项目已经通过 Maven 编译验证，说明技术环境可正常运行。
 
 2. **JavaFX 能满足 GUI 需求**
-   - JavaFX 提供菜单栏、按钮、标签、文本框、表格、分页按钮、弹窗和 FXML 等组件。
-   - 当前项目已经实现左侧表/视图列表，右侧表数据、表结构和 SQL 执行区域，并提供数据行新增/删除按钮、可编辑单元格和表结构编辑按钮，能够满足数据库管理工具的基本界面需求。
+   - JavaFX 提供菜单栏、按钮、标签、文本框、密码输入框、下拉框、表格、分页按钮、弹窗和 FXML 等组件。
+   - 当前项目已经实现左侧表/视图列表，右侧表数据、表结构和 SQL 执行区域，并提供数据行新增/删除按钮、可编辑单元格、表结构编辑按钮、备份恢复菜单和 AI SQL 生成入口。
 
 3. **SQLite 集成难度低**
    - SQLite 是文件型数据库，不需要单独部署数据库服务器，适合课程项目和本地数据库管理。
-   - 当前项目已经支持打开、新建、关闭和删除 SQLite 数据库文件。
+   - 当前项目已经支持打开、新建、关闭、删除、备份和恢复 SQLite 数据库文件。
 
 4. **SQLite JDBC 访问方式成熟**
    - 通过 JDBC 可以完成数据库连接、查询、执行 SQL、读取表结构等操作。
-   - 当前项目已经实现表/视图列表读取、字段信息读取、表数据分页查询、SQL 执行、数据行插入/更新/删除和部分表结构变更。
+   - 当前项目已经实现表/视图列表读取、字段信息读取、表数据分页查询、SQL 执行、数据行插入/更新/删除、部分表结构变更和备份恢复前后的连接管理。
 
 5. **表管理和结构编辑功能可以通过 SQL 和 JavaFX UI 实现**
    - 当前项目已经通过独立创建表对话框实现了表名输入、字段定义、字段类型选择、主键/非空设置、默认值填写和 SQL 预览。
@@ -53,20 +55,26 @@ HyperSql 采用以下技术栈：
    - 当前项目已经通过主键或 SQLite `rowid` 定位数据行，使用参数化 SQL 完成新增、修改和删除。
    - SQL 返回结果只对可识别的单表查询启用编辑，复杂查询保持只读，降低误操作风险。
 
-7. **AI SQL 生成功能技术上可行，但需要控制范围**
-   - 后续可以读取当前数据库表结构，结合用户自然语言描述构造提示词，然后调用 AI API 生成 SQL。
-   - 该功能涉及 API Key 管理、网络请求、调用成本和生成结果校验，因此适合作为扩展功能。
+7. **数据库备份恢复功能技术上可行**
+   - SQLite 数据库本质上是本地文件，因此可以通过文件复制完成备份。
+   - 当前项目在备份前执行检查点操作，并在恢复前关闭数据库连接，使用临时文件替换目标数据库，恢复后重新打开数据库并刷新界面。
+   - 恢复操作前会弹出确认提示，避免误覆盖当前数据库。
+
+8. **AI SQL 生成功能技术上可行**
+   - 当前项目已经能够读取数据库表和视图结构，并将结构信息与用户自然语言需求组合成提示词。
+   - 系统通过 JDK HttpClient 调用 OpenAI 兼容接口或 Anthropic Claude Messages API，并用 Jackson 处理 JSON 请求和响应。
+   - API Key 只保存在运行内存中，不写入本地文件；AI 生成的 SQL 只填入 SQL 输入框，不自动执行，降低安全风险。
 
 ### 技术可行性结论
 
-HyperSql 所采用的核心技术已经在当前项目中得到验证。数据库连接、表结构读取、表数据分页显示、SQL 执行、数据库文件管理、表管理、数据行编辑和 SQLite 安全结构编辑功能均已实现，因此项目核心功能在技术上可行。AI SQL 生成属于后续扩展，技术上可实现，但需要在安全性和调用成本方面进行控制。
+HyperSql 所采用的核心技术已经在当前项目中得到验证。数据库连接、表结构读取、表数据分页显示、SQL 执行、数据库文件管理、表管理、数据行编辑、SQLite 安全结构编辑、备份恢复和 AI SQL 生成均已实现，因此项目核心功能和主要扩展功能在技术上可行。
 
 ## 3. 经济可行性
 
 HyperSql 的开发成本较低，主要体现在以下方面：
 
 1. **开发工具成本低**
-   - Java、JavaFX、Maven、SQLite 和 SQLite JDBC 均可免费使用。
+   - Java、JavaFX、Maven、SQLite、SQLite JDBC 和 Jackson 均可免费使用。
    - 可使用 IntelliJ IDEA Community、VS Code 等免费开发工具。
 
 2. **运行环境成本低**
@@ -78,12 +86,13 @@ HyperSql 的开发成本较低，主要体现在以下方面：
    - 当前已完成的功能不涉及商业授权费用。
 
 4. **AI API 成本可控**
-   - AI SQL 生成尚未实现，可以作为后续扩展功能。
-   - 若后续实现，可限制调用次数，或只在演示场景使用少量 API 调用，避免高额费用。
+   - AI SQL 生成功能由用户自行输入 API Key，系统本身不内置付费密钥。
+   - 该功能只在用户主动点击生成时调用 API，不会自动后台调用。
+   - 生成 SQL 时只发送数据库结构和用户需求，不发送表数据，减少请求内容规模。
 
 ### 经济可行性结论
 
-HyperSql 不需要额外硬件和商业软件投入，当前已实现功能均基于免费技术完成，整体开发与运行成本较低，经济上可行。
+HyperSql 不需要额外硬件和商业软件投入，当前主要功能均基于免费技术完成。AI 功能可能产生的调用费用由用户配置的 API 服务决定，并且只在用户主动使用时发生，因此整体开发与运行成本较低，经济上可行。
 
 ## 4. 时间可行性
 
@@ -104,21 +113,22 @@ HyperSql 采用增量迭代模型，可以按照功能优先级逐步完成，
 | 交互修复 | 修复选择表不同步、刷新表列表保留当前表、SQL 结果区启动空状态 | 已完成 |
 | 数据行编辑 | 表数据界面新增、修改、删除数据行；可编辑单表 SQL 结果 | 已完成 |
 | 表结构安全编辑 | 重命名表、新增字段、重命名字段 | 已完成 |
-| 备份恢复 | 数据库备份和恢复 | 待实现 |
-| AI SQL 生成 | 根据表结构和自然语言生成 SQL | 待实现 |
+| 备份恢复 | 数据库备份和从备份恢复 | 已完成 |
+| 界面优化 | 整理菜单和工具栏，降低界面拥挤程度 | 已完成 |
+| AI SQL 生成 | 根据表结构和自然语言生成 SQL，支持 OpenAI 兼容接口和 Anthropic Claude | 已完成 |
 | 测试优化 | 功能测试、界面优化、最终演示准备 | 持续进行 |
 
 ### 时间可行性说明
 
 1. 当前项目已经完成数据库管理工具的核心可运行版本，可以满足基本演示要求。
 2. 数据行编辑和 SQLite 支持范围内的表结构编辑已经完成，软件实用性进一步提高。
-3. 后续开发可以优先完成备份恢复，因为它与数据库管理工具的数据安全性直接相关。
-4. AI SQL 生成可以作为亮点功能，根据剩余时间决定实现深度。
-5. 采用增量迭代方式后，即使扩展功能未全部完成，系统仍然具备可运行、可演示的核心功能。
+3. 备份恢复功能已经完成，增强了数据库文件管理和数据安全能力。
+4. AI SQL 生成功能已经完成基础版本，可以作为课程项目亮点功能展示。
+5. 后续主要工作集中在测试、演示数据准备、界面细节优化和文档完善，风险相对较低。
 
 ### 时间可行性结论
 
-从当前进展看，HyperSql 的核心功能和主要编辑功能已经完成，课程周期内完成一个可演示版本具有较高可行性。后续需要合理控制扩展功能范围，避免 AI 调用和复杂数据库结构重建功能占用过多开发时间。
+从当前进展看，HyperSql 的核心功能和主要扩展功能已经完成，课程周期内形成可运行、可演示版本具有较高可行性。后续只需继续进行测试和演示准备即可。
 
 ## 5. 操作可行性
 
@@ -139,34 +149,41 @@ HyperSql 面向学生和 SQLite 初学者，软件操作流程较为简单。
         ↓
 在 SQLite 支持范围内编辑表结构
         ↓
-在 SQL 执行区输入并执行 SQL
+根据需要备份或恢复数据库
         ↓
-根据需要创建表、删除表或刷新表列表
+在 SQL 执行区输入 SQL 或使用 AI 生成 SQL
+        ↓
+检查 SQL 后手动执行
 ```
 
 ### 操作可行性说明
 
 1. **界面符合用户习惯**
    - 采用类似数据库管理工具的布局：左侧显示表/视图列表，右侧显示表数据、表结构和 SQL 执行区域。
+   - 菜单和工具栏经过整理，高频操作更明显，危险或低频操作放在菜单中，界面更清晰。
 
 2. **降低数据库操作门槛**
-   - 用户可以通过图形界面打开数据库、浏览表结构、查看表数据、新增修改删除数据行、创建表、删除表和进行部分表结构编辑，不必完全依赖命令行工具。
+   - 用户可以通过图形界面打开数据库、浏览表结构、查看表数据、新增修改删除数据行、创建表、删除表、进行部分表结构编辑、备份恢复数据库，不必完全依赖命令行工具。
 
 3. **分页降低操作压力**
    - 表数据和 SQL 查询结果都使用分页显示，每页 100 行，避免一次显示大量数据导致界面卡顿或不便查看。
 
 4. **错误提示清晰**
-   - 当未连接数据库、数据库连接失败、SQL 执行错误、创建表失败或删除表失败时，系统会给出提示信息。
+   - 当未连接数据库、数据库连接失败、SQL 执行错误、创建表失败、删除表失败、备份恢复失败或 AI 调用失败时，系统会给出提示信息。
 
 5. **危险操作有确认流程**
-   - 删除数据库文件、删除表和删除数据行都属于破坏性操作，系统在执行前会弹出确认提示。
+   - 删除数据库文件、删除表、删除数据行、恢复数据库和结构变更等操作都属于破坏性操作，系统在执行前会弹出确认提示。
 
-6. **当前限制清晰**
-   - 当前版本已经支持创建表、删除普通表、数据行编辑和 SQLite 原生支持的部分结构编辑，但尚未实现数据库备份恢复和 AI SQL 生成。
+6. **AI 生成 SQL 使用方式安全**
+   - 用户在 UI 中设置 API Key、Base URL 和模型。
+   - API Key 只在本次运行中保存。
+   - 系统只将数据库结构和用户需求发送给 AI，不发送表数据。
+   - AI 生成的 SQL 只填入 SQL 输入框，不自动执行，用户可以检查后再手动运行。
+   - 如果生成内容包含可能修改数据或结构的关键词，系统会提示用户谨慎检查。
 
 ### 操作可行性结论
 
-HyperSql 当前功能界面直观，基本操作流程清晰，已经支持常见数据浏览、数据编辑和部分结构编辑操作，适合学生和 SQLite 初学者使用。随着后续备份恢复功能完善，软件的数据安全性会进一步提高。
+HyperSql 当前功能界面直观，基本操作流程清晰，已经支持常见数据浏览、数据编辑、部分结构编辑、备份恢复和 AI 辅助 SQL 生成操作，适合学生和 SQLite 初学者使用。
 
 ## 6. 可行性分析总结
 
@@ -174,11 +191,11 @@ HyperSql 当前功能界面直观，基本操作流程清晰，已经支持常
 
 | 分析方面 | 结论 |
 |---|---|
-| 技术可行性 | JavaFX、SQLite JDBC 和 Maven 已经支撑当前核心功能、数据编辑和结构编辑实现，AI API 可作为后续扩展 |
-| 经济可行性 | 开发工具和数据库免费，当前功能无额外运行成本 |
-| 时间可行性 | 核心功能和主要编辑功能已经完成，后续扩展可按优先级继续迭代 |
-| 操作可行性 | 面向学生和初学者，界面简单直观，危险操作有确认提示 |
+| 技术可行性 | JavaFX、SQLite JDBC、Maven、JDK HttpClient 和 Jackson 已经支撑当前核心功能、数据编辑、结构编辑、备份恢复和 AI SQL 生成实现 |
+| 经济可行性 | 开发工具和数据库免费，当前功能无额外固定运行成本，AI 调用成本由用户自行配置和控制 |
+| 时间可行性 | 核心功能和主要扩展功能已经完成，后续重点是测试和演示准备 |
+| 操作可行性 | 面向学生和初学者，界面简单直观，危险操作有确认提示，AI 生成 SQL 不自动执行 |
 
 ### 总体结论
 
-HyperSql 的技术方案成熟，开发成本低，核心功能和主要编辑功能已经形成可运行版本，适合作为软件工程课程大作业项目继续完善。后续应优先补充数据库备份恢复功能，再根据时间实现 AI 辅助 SQL 生成。
+HyperSql 的技术方案成熟，开发成本低，核心功能和主要扩展功能已经形成可运行版本，适合作为软件工程课程大作业项目继续完善和演示。当前项目已经具备数据库浏览、SQL 执行、数据编辑、结构编辑、备份恢复和 AI 辅助 SQL 生成等功能，整体可行性较高。