hypersql/requirements_analysis.md

# HyperSql 需求分析

## 1. 需求分析概述

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

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

1. SQLite 数据库虽然轻量易用，但命令行操作对初学者不够直观。
2. 初学者手写 SQL 时容易出错，需要图形界面辅助查看数据库结构和数据。
3. 数据库表结构和表数据需要以更直观的方式展示。
4. 大表或较多查询结果需要分页显示，避免界面卡顿和阅读困难。
5. 创建数据库、创建表、删除表等常见操作需要简洁清晰的图形界面。
6. 删除数据库文件和删除表等危险操作需要确认流程，降低误操作风险。

当前版本已经完成了数据库文件管理、表/视图浏览、表结构查看、表数据分页查看、SQL 执行、SQL 结果分页、创建表和删除表等核心功能。数据行编辑、数据库备份恢复和 AI 辅助 SQL 生成作为后续扩展功能继续开发。

## 2. 用户需求分析

### 目标用户

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

### 典型使用场景

1. 用户新建一个 SQLite 数据库文件用于课程实验。
2. 用户打开一个已有的本地 SQLite 数据库文件。
3. 用户查看数据库中有哪些表或视图。
4. 用户选择某张表，查看字段结构和表数据。
5. 用户通过分页按钮浏览大表数据。
6. 用户在 SQL 执行区输入 SQL 并查看执行结果。
7. 用户通过图形界面创建新表。
8. 用户删除不需要的普通表，并在删除前进行确认。
9. 用户刷新表列表，并希望保持当前选中的表不变。
10. 后续版本中，用户可以通过图形界面编辑数据、备份恢复数据库，或使用 AI 辅助生成 SQL。

## 3. 功能性需求

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

| 功能模块 | 需求说明 | 当前状态 |
|---|---|---|
| 数据库文件管理 | 新建、打开、关闭和删除本地 SQLite 数据库文件 | 已实现 |
| 数据库结构浏览 | 显示数据库表/视图列表，查看字段名、字段类型、主键、默认值等信息 | 已实现 |
| 表数据查看 | 在表格中展示指定数据表内容，并按每页 100 行分页 | 已实现 |
| SQL 执行 | 支持用户输入 SQL 语句并执行，显示结果或错误 | 已实现 |
| SQL 结果分页 | 查询结果按每页 100 行分页显示 | 已实现 |
| 表管理 | 支持通过 UI 创建表，支持删除选中普通表 | 已实现 |
| 状态与错误提示 | 显示连接状态、执行结果和错误信息 | 已实现 |
| 数据编辑 | 支持新增、修改、删除表数据行 | 待实现 |
| 备份与恢复 | 支持数据库文件备份和从备份文件恢复 | 待实现 |
| AI SQL 生成 | 根据表结构和用户自然语言需求生成 SQL | 待实现 |

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

### 4.1 数据库文件管理

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

当前实现状态：已实现。

### 4.2 数据库结构浏览

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

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

### 4.3 表数据查看

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

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

### 4.4 SQL 执行

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

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

### 4.5 创建表

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

当前实现状态：已实现。

### 4.6 删除表

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

当前实现状态：已实现。

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

### 5.1 数据行编辑

- 系统后续应支持在图形界面中新增表数据。
- 系统后续应支持修改表格中的数据。
- 系统后续应支持删除选中的数据行。
- 对修改和删除操作，应提供必要的确认或错误提示。
- 数据编辑应优先保证主键识别和 SQL 生成安全。

当前实现状态：待实现。

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

- 系统后续应支持将当前数据库复制为备份文件。
- 系统后续应支持用户选择备份文件进行恢复。
- 系统应在恢复前提示用户确认，避免覆盖当前数据库。
- 系统应显示备份或恢复的执行结果。

当前实现状态：待实现。

### 5.3 AI 辅助 SQL 生成

- 系统后续应读取当前数据库的表结构信息。
- 系统后续应根据表结构自动生成 AI 提示词。
- 用户可以输入自然语言需求。
- 系统调用 AI API 生成 SQL 语句。
- 用户可以检查并确认生成的 SQL 后再执行。
- 若 AI 调用失败，系统应显示错误提示。
- AI 生成的 SQL 不应直接自动执行，应由用户确认后执行。

当前实现状态：待实现。

## 6. 非功能性需求

| 需求类型 | 说明 | 当前体现 |
|---|---|---|
| 易用性 | 界面清晰，操作流程简单，适合初学者使用 | 已采用菜单、工具栏、表格和创建表对话框 |
| 可靠性 | 数据库连接、SQL 执行和表操作失败时应有错误提示 | 已实现基础错误提示 |
| 安全性 | 删除数据库、删除表等危险操作前应确认 | 已实现确认流程 |
| 性能 | 对常见小型 SQLite 数据库能够快速打开和查询 | 表数据采用数据库侧分页，降低大表加载压力 |
| 可维护性 | 采用模块化设计，便于后续扩展和维护 | 已划分数据库连接、元数据读取、SQL 执行、工具类和控制器 |
| 兼容性 | 支持常见 SQLite 数据库文件，适配主流桌面系统 | 基于 JavaFX 和 SQLite JDBC，具备跨平台基础 |
| 可扩展性 | 后续可扩展数据编辑、备份恢复和 AI SQL 生成 | 已保留 SQL 执行和元数据读取基础能力 |

## 7. 需求优先级

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

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

### 优先级说明

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

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

3. **低优先级需求**
   - 作为项目亮点和扩展功能。
   - 可根据开发进度调整实现程度。

## 8. 当前版本限制

当前 HyperSql 仍存在以下限制：

1. 还不能通过图形界面直接新增、修改或删除表中的数据行。
2. 还没有实现数据库备份与恢复功能。
3. 还没有实现 AI 辅助 SQL 生成功能。
4. SQL 查询结果分页属于客户端分页，查询结果会先全部读取到内存中，不适合特别大的查询结果。
5. 当前删除表功能只支持删除普通表，不支持删除视图。
6. 当前主要面向 SQLite，不支持 MySQL、PostgreSQL 等远程数据库。

## 9. 需求分析总结

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

当前系统已经重点实现：

1. SQLite 数据库文件新建、打开、关闭和删除。
2. 数据库表/视图列表展示。
3. 表结构和表数据的可视化展示。
4. 表数据分页显示。
5. SQL 语句执行和 SQL 查询结果分页显示。
6. 图形化创建表。
7. 删除普通表。
8. 状态提示、错误提示和危险操作确认。

后续开发应优先完成数据行增删改查和数据库备份恢复，使系统从“可浏览、可执行 SQL、可管理表结构”进一步发展为“可完整管理 SQLite 数据库”的工具。在时间允许的情况下，再实现 AI 辅助 SQL 生成作为项目亮点。