# HyperSql 需求分析

## 1. 需求分析概述

需求分析用于明确 HyperSql 要解决什么问题、服务哪些用户，以及系统需要提供哪些功能。

HyperSql 是一个面向学生和 SQLite 初学者的轻量级数据库图形化管理工具，主要解决以下问题：

1. SQLite 数据库虽然轻量易用，但命令行操作对初学者不够直观。
2. 初学者手写 SQL 时容易出错，需要图形界面辅助查看数据库结构和数据。
3. 数据库表结构和表数据需要以更直观的方式展示。
4. 大表或较多查询结果需要分页显示，避免界面卡顿和阅读困难。
5. 创建数据库、创建表、删除表等常见操作需要简洁清晰的图形界面。
6. 删除数据库文件、删除表、删除数据行、恢复数据库等危险操作需要确认流程，降低误操作风险。
7. 表结构修改需要尊重 SQLite 原生能力，只提供安全可控的结构编辑入口。
8. 用户希望通过 AI 根据当前数据库结构和自然语言需求辅助生成 SQL，但生成结果不应自动执行。

当前版本已经完成了数据库文件管理、表/视图浏览、表结构查看、表数据分页查看、SQL 执行、SQL 结果分页、创建表、删除表、数据行编辑、SQLite 支持范围内的表结构编辑、数据库备份恢复和 AI 辅助 SQL 生成等核心与扩展功能。

## 2. 用户需求分析

### 目标用户

| 用户类型 | 说明 |
|---|---|
| 学生 | 学习数据库课程，需要查看和操作 SQLite 数据库 |
| SQLite 初学者 | 不熟悉命令行和复杂 SQL，希望通过图形界面管理数据库 |
| 开发者学习者 | 在小型项目中使用 SQLite，需要快速查看本地数据和表结构 |

### 典型使用场景

1. 用户新建一个 SQLite 数据库文件用于课程实验。
2. 用户打开一个已有的本地 SQLite 数据库文件。
3. 用户查看数据库中有哪些表或视图。
4. 用户选择某张表，查看字段结构和表数据。
5. 用户通过分页按钮浏览大表数据。
6. 用户在 SQL 执行区输入 SQL 并查看执行结果。
7. 用户通过图形界面创建新表。
8. 用户删除不需要的普通表，并在删除前进行确认。
9. 用户通过图形界面新增、修改或删除表中的数据行。
10. 用户在 SQLite 支持范围内重命名表、新增字段或重命名字段。
11. 用户刷新表列表，并希望保持当前选中的表不变。
12. 用户将当前数据库备份为另一个文件。
13. 用户从备份文件恢复当前数据库，并在恢复前得到确认提示。
14. 用户在 UI 中配置 AI Provider、API Key、Base URL 和模型。
15. 用户输入自然语言需求，由 AI 根据当前数据库结构生成 SQL。
16. 用户检查 AI 生成的 SQL，然后手动点击执行。

## 3. 功能性需求

HyperSql 的功能性需求主要包括以下模块：

| 功能模块 | 需求说明 | 当前状态 |
|---|---|---|
| 数据库文件管理 | 新建、打开、关闭和删除本地 SQLite 数据库文件 | 已实现 |
| 数据库结构浏览 | 显示数据库表/视图列表，查看字段名、字段类型、主键、默认值等信息 | 已实现 |
| 表数据查看 | 在表格中展示指定数据表内容，并按每页 100 行分页 | 已实现 |
| SQL 执行 | 支持用户输入 SQL 语句并执行，显示结果或错误 | 已实现 |
| SQL 结果分页 | 查询结果按每页 100 行分页显示 | 已实现 |
| 表管理 | 支持通过 UI 创建表，支持删除选中普通表 | 已实现 |
| 表结构安全编辑 | 支持重命名表、新增字段、重命名字段 | 已实现 |
| 状态与错误提示 | 显示连接状态、执行结果和错误信息 | 已实现 |
| 数据编辑 | 支持新增、修改、删除表数据行，并支持可识别单表 SQL 结果编辑 | 已实现 |
| 备份与恢复 | 支持数据库文件备份和从备份文件恢复 | 已实现 |
| AI SQL 生成 | 根据表结构和用户自然语言需求生成 SQL，支持 OpenAI 兼容接口和 Anthropic Claude | 已实现 |
| UI 优化 | 整理菜单、工具栏和侧边栏操作入口，降低界面拥挤程度 | 已实现 |

## 4. 核心功能需求说明

### 4.1 数据库文件管理

- 系统应支持用户选择本地 SQLite 数据库文件并建立连接。
- 系统应支持用户新建 SQLite 数据库文件。
- 系统应支持关闭当前数据库连接。
- 系统应支持删除当前连接的数据库文件，删除前必须提示用户确认。
- 系统应显示当前数据库文件路径。

当前实现状态：已实现。

### 4.2 数据库结构浏览

- 系统应显示当前数据库中的表和视图。
- 系统应支持刷新表/视图列表。
- 刷新表/视图列表时，应尽量保留当前选中的表或视图。
- 系统应支持查看字段信息。
- 字段信息包括字段名、字段类型、是否主键、是否非空、默认值等。
- 用户切换左侧表/视图时，表数据和表结构应同步更新。

当前实现状态：已实现，并已修复选择表时数据和结构不同步的问题。

### 4.3 表结构安全编辑

- 系统应支持在 SQLite 原生能力范围内编辑普通表结构。
- 系统应支持重命名普通表。
- 系统应支持新增字段。
- 系统应支持重命名字段。
- 系统不应对视图启用结构编辑。
- 系统不应实现 SQLite 不能直接安全支持的字段类型修改、非空约束修改、默认值修改、主键修改和字段顺序调整。
- 结构变更前应提示用户确认。
- 结构变更后应刷新表列表、表结构和表数据。

当前实现状态：已实现。当前版本只实现 SQLite 原生 `ALTER TABLE` 相对安全支持的重命名表、新增字段和重命名字段。

### 4.4 表数据查看

- 系统应支持点击表名后查看表数据。
- 系统应以表格形式展示数据。
- 系统应支持分页显示表数据。
- 每页默认显示 100 行。
- 当数据不足 100 行时，应只显示一页。
- 用户应能够通过“上一页”和“下一页”按钮切换页码。
- 系统应显示当前页码、总页数、总行数和当前显示范围。

当前实现状态：已实现。表数据分页采用数据库侧分页，通过 `LIMIT` 和 `OFFSET` 每次只查询当前页数据。

### 4.5 SQL 执行

- 系统应提供 SQL 输入区域。
- 系统应支持执行查询、插入、更新、删除、建表、删表等 SQL 语句。
- 系统应显示 SQL 执行结果或错误信息。
- 对于查询结果，系统应以表格形式显示。
- 查询结果应支持分页显示，每页默认 100 行。
- 对于非查询 SQL，系统应显示影响行数或执行结果信息。
- 执行可能改变数据库结构的 SQL 后，系统应刷新表/视图列表并尽量保留当前选择。

当前实现状态：已实现。SQL 结果分页采用客户端分页，即 SQL 查询结果先读取到内存中，再按页显示。

### 4.6 创建表

- 系统应提供图形化创建表界面，不能只依赖用户手写 `CREATE TABLE`。
- 创建表界面应简洁易用。
- 用户应能输入表名。
- 用户应能添加、删除字段。
- 用户应能设置字段名、字段类型、主键、非空和默认值。
- 系统应提供 SQL 预览。
- 系统应校验表名不能为空，且不能与已有表或视图重名。
- 系统应校验字段名不能为空，字段名不能重复。
- 系统应限制字段类型为常用 SQLite 类型。
- 系统应限制默认值格式，避免明显非法或危险 SQL 片段。
- 创建成功后，应刷新表列表并选中新创建的表。

当前实现状态：已实现。

### 4.7 删除表

- 系统应支持删除左侧选中的普通表。
- 系统不应通过“删除表”功能删除视图。
- 删除表前必须弹出确认提示。
- 删除成功后，应刷新表列表。
- 删除表失败时，应显示错误信息。

当前实现状态：已实现。

## 5. 扩展功能需求说明

### 5.1 数据行编辑

- 系统应支持在表数据界面新增表数据行。
- 系统应支持直接修改表格中的数据，修改后立即保存到 SQLite 数据库。
- 系统应支持删除选中的数据行，删除前必须提示确认。
- 系统应通过主键或 SQLite `rowid` 定位数据行，避免误更新。
- 系统应在可识别的单表 SQL 查询结果中支持新增、修改和删除数据行。
- JOIN、聚合、表达式、视图等无法安全反写的 SQL 查询结果应保持只读。

当前实现状态：已实现。

### 5.2 数据库备份与恢复

- 系统应支持将当前数据库复制为备份文件。
- 系统应支持用户选择备份文件进行恢复。
- 系统应在恢复前提示用户确认，避免覆盖当前数据库。
- 系统应避免将当前数据库文件本身作为备份目标或恢复来源。
- 系统应在恢复前关闭当前数据库连接，恢复后重新打开数据库并刷新界面。
- 系统应显示备份或恢复的执行结果。

当前实现状态：已实现。

### 5.3 AI 辅助 SQL 生成

- 系统应读取当前数据库的表结构和视图结构信息。
- 系统应根据表结构自动生成 AI 提示词。
- 用户可以输入自然语言需求。
- 系统支持 OpenAI 兼容接口和 Anthropic Claude。
- 用户应能在 UI 中设置 Provider、API Key、Base URL、模型和超时时间。
- API Key 只应保存在本次运行内存中，不应写入本地配置文件。
- 系统调用 AI API 生成 SQL 语句。
- 用户可以检查并确认生成的 SQL 后再执行。
- AI 生成的 SQL 不应直接自动执行，应由用户确认后手动执行。
- 系统不应向 AI 发送表数据，只发送数据库结构和用户需求。
- 若 AI 调用失败，系统应显示错误提示。
- 若生成 SQL 包含可能修改数据或结构的关键词，系统应提示用户谨慎检查。

当前实现状态：已实现。

### 5.4 界面整理优化

- 系统菜单应包含完整功能入口。
- 工具栏应保留高频操作，避免按钮过多导致界面拥挤。
- 表相关操作应放在侧边栏附近，方便用户针对当前表操作。
- 危险或低频操作应主要放在菜单中，减少误触。

当前实现状态：已实现。

## 6. 非功能性需求

| 需求类型 | 说明 | 当前体现 |
|---|---|---|
| 易用性 | 界面清晰，操作流程简单，适合初学者使用 | 已采用菜单、工具栏、侧边栏、表格、创建表对话框、数据行编辑按钮、结构编辑按钮和 AI 生成入口 |
| 可靠性 | 数据库连接、SQL 执行、数据编辑、表操作、备份恢复和 AI 调用失败时应有错误提示 | 已实现基础错误提示 |
| 安全性 | 删除数据库、删除表、删除数据行、恢复数据库和结构变更等操作前应确认；AI 生成 SQL 不自动执行 | 已实现确认流程和 AI 生成后手动执行机制 |
| 性能 | 对常见小型 SQLite 数据库能够快速打开和查询 | 表数据采用数据库侧分页，降低大表加载压力 |
| 隐私性 | AI 功能不应发送表数据，API Key 不应持久化到本地文件 | AI 提示只包含表/视图结构和用户需求，API Key 仅保存在运行内存中 |
| 可维护性 | 采用模块化设计，便于后续扩展和维护 | 已划分数据库连接、元数据读取、SQL 执行、行数据服务、结构编辑服务、备份恢复逻辑、AI 客户端和工具类 |
| 兼容性 | 支持常见 SQLite 数据库文件，适配主流桌面系统 | 基于 JavaFX 和 SQLite JDBC，具备跨平台基础 |
| 可扩展性 | 后续可扩展更多 AI Provider、SQL 历史记录和界面美化 | 已提供 AI Provider 适配层和独立 AI SQL 生成服务 |

## 7. 需求优先级

为了保证项目按时完成，HyperSql 将需求分为三个优先级。

| 优先级 | 功能 | 当前状态 |
|---|---|---|
| 高 | 新建/打开/关闭 SQLite 数据库、浏览表结构、查看表数据、执行 SQL | 已实现 |
| 高 | 表数据分页、SQL 查询结果分页、刷新表列表保留当前选择 | 已实现 |
| 中 | 创建表、删除表、删除数据库文件 | 已实现 |
| 中 | 数据行新增、修改、删除 | 已实现 |
| 中 | SQLite 支持范围内的表结构编辑 | 已实现 |
| 中 | 数据库备份与恢复 | 已实现 |
| 低 | AI 辅助 SQL 生成、界面进一步美化 | 已实现 |
| 低 | SQL 历史记录、更多数据库类型支持 | 后续可扩展 |

### 优先级说明

1. **高优先级需求**
   - 是系统最基本的功能，决定软件是否能够正常演示。
   - 当前已经完成。

2. **中优先级需求**
   - 提升软件实用性和数据安全性。
   - 当前已经完成创建表、删除表、删除数据库文件、数据行编辑、表结构安全编辑和备份恢复。

3. **低优先级需求**
   - 作为项目亮点和扩展功能。
   - 当前已经完成 AI 辅助 SQL 生成和基础界面整理，后续可继续扩展 SQL 历史记录或更多界面美化。

## 8. 当前版本限制

当前 HyperSql 仍存在以下限制：

1. SQL 查询结果分页属于客户端分页，查询结果会先全部读取到内存中，不适合特别大的查询结果。
2. SQL 结果编辑只支持可识别的单表查询，JOIN、聚合、表达式等复杂结果保持只读。
3. 表结构编辑只支持 SQLite 原生安全支持的重命名表、新增字段和重命名字段，不支持需要重建表的复杂结构修改。
4. 当前删除表功能只支持删除普通表，不支持删除视图。
5. 当前主要面向 SQLite，不支持 MySQL、PostgreSQL 等远程数据库。
6. AI 生成 SQL 的质量取决于用户配置的模型和 API 服务，生成结果仍需要用户检查后再执行。
7. API Key 只在本次运行中保存，关闭软件后需要重新输入。
8. 当前未实现 SQL 历史记录功能。

## 9. 需求分析总结

通过需求分析可以看出，HyperSql 的主要目标是为学生和 SQLite 初学者提供一个简单、直观、易用的数据库图形化管理工具。

当前系统已经重点实现：

1. SQLite 数据库文件新建、打开、关闭和删除。
2. 数据库表/视图列表展示。
3. 表结构和表数据的可视化展示。
4. 表数据分页显示。
5. SQL 语句执行和 SQL 查询结果分页显示。
6. 图形化创建表。
7. 删除普通表。
8. 数据行新增、修改和删除。
9. SQLite 支持范围内的表结构安全编辑。
10. 数据库备份和从备份恢复。
11. AI 辅助 SQL 生成。
12. 状态提示、错误提示和危险操作确认。
13. 菜单、工具栏和侧边栏入口整理。

当前 HyperSql 已经从“可浏览、可执行 SQL、可编辑数据、可管理表结构”进一步发展为“可较完整管理 SQLite 数据库，并提供 AI 辅助 SQL 生成”的轻量级数据库管理工具。后续可以围绕测试、演示体验、SQL 历史记录和更细致的界面美化继续迭代。