# 浩瀚诗库

**Repository Path**: deepin20/Poetry-Hub

## Basic Information

- **Project Name**: 浩瀚诗库
- **Description**: 浩瀚诗库 (Poetry Hub)：一个基于 Python 的诗词检索与阅读桌面应用，支持海量诗词数据导入、全文搜索、多维度筛选、收藏与导出。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-18
- **Last Updated**: 2026-08-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 浩瀚诗库 (Poetry Hub)

一个基于 Python 的诗词检索与阅读桌面应用，支持海量诗词数据导入、全文搜索、多维度筛选、收藏与导出。

---

## ✨ 功能特性

- **📚 海量诗词检索**：支持按关键词、作者、朝代、标签全文搜索，结果实时分页展示。
- **🎨 优雅图形界面**：基于 PySide6 打造，仿古书排版，支持夜间模式、字体缩放。
- **⚙️ 数据导入工具**：自动识别多种 JSON 格式（全唐诗、宋词、纳兰性德等），批量导入 MySQL，支持去重与事务回滚。
- **📊 数据统计**：内置作者、朝代、标签统计，快速了解数据分布。
- **⭐ 收藏与导出**：可收藏心仪诗词，导出为 CSV / JSON / Markdown。
- **🌐 简繁转换**：自动将繁体内容转换为简体，方便阅读。
- **🔄 后端 API**：基于 Flask 提供 RESTful 接口，便于二次开发或 Web 端集成。

---

## 🛠️ 技术栈

| 组件          | 技术                         |
|---------------|------------------------------|
| 前端          | PySide6 (Qt for Python)      |
| 后端          | Flask + SQLAlchemy           |
| 数据库        | MySQL (支持 FULLTEXT 索引)   |
| 数据导入      | 独立 CLI 工具 (mysql.connector) |
| 缓存          | Flask-Caching (可选)         |
| 环境管理      | venv + pip                   |

---

## 📦 安装与配置

### 1. 克隆项目

```bash
git clone https://github.com/yourname/poetry-hub.git
cd poetry-hub
```

### 2. 创建虚拟环境并安装依赖

```bash
python3 -m venv venv
source venv/bin/activate          # Linux/Mac
# 或 venv\Scripts\activate       # Windows
pip install -r requirements.txt
```

### 3. 配置数据库

- 安装 MySQL 并启动服务。
- 创建数据库（默认 `poetry_db`）和用户（默认 `poetry_user` / `poetry123`）：
  ```sql
  CREATE DATABASE poetry_db CHARACTER SET utf8mb4;
  CREATE USER 'poetry_user'@'localhost' IDENTIFIED BY 'poetry123';
  GRANT ALL ON poetry_db.* TO 'poetry_user'@'localhost';
  FLUSH PRIVILEGES;
  ```
- 如需修改连接信息，编辑 `.env` 文件（参考 `.env.example`）。

### 4. 导入诗词数据

将原始 JSON 数据（如 [chinese-poetry](https://github.com/chinese-poetry/chinese-poetry) 的 JSON 文件）放入 `data/` 目录（可含子目录）。

运行导入工具：

```bash
python tools/import_poetry.py --data-dir ./data
```

可选参数：
- `--dirs 全唐诗 宋词`：只处理指定目录。
- `--batch-size 500`：批量插入大小。
- `--dry-run`：预览导入结果，不写入数据库。
- `--db-host 127.0.0.1`：指定数据库主机。

导入完成后，数据库中将自动创建 `poems` 表及索引。

---

## 🚀 启动应用

### 一键启动（推荐）

```bash
chmod +x start.sh
./start.sh
```

脚本会自动：
- 检测并启动 MySQL（若未运行）。
- 启动 Flask 后端（监听 `0.0.0.0:5000`）。
- 启动 PySide6 图形界面。

### 单独启动

- **后端**：
  ```bash
  export FLASK_APP=backend/app.py
  python -m flask run --host=0.0.0.0 --port=5000
  ```
- **GUI**：
  ```bash
  python gui/main.py
  ```

---

## 📂 目录结构

```
.
├── backend/                # Flask 后端
│   ├── api/                # API 蓝图
│   ├── services/           # 业务逻辑
│   ├── utils/              # 工具函数
│   ├── models.py           # SQLAlchemy 模型
│   ├── extensions.py       # 扩展实例 (db, cache)
│   └── config.py           # 配置类
├── gui/                    # PySide6 图形界面
│   ├── widgets/            # 自定义控件
│   ├── threads/            # 异步线程
│   ├── dialogs/            # 对话框
│   ├── resources/          # 图标、样式、字体
│   ├── main.py             # 入口
│   └── main_window.py      # 主窗口
├── tools/                  # 命令行工具
│   ├── import_poetry.py    # 统一导入工具
│   ├── clean_data.py       # 数据清洗
│   └── export.py           # 数据导出
├── scripts/                # 启动/部署脚本
│   ├── start.sh
│   ├── stop.sh
│   ├── systemd/            # systemd 服务文件
│   └── docker/             # Docker 配置
├── data/                   # 原始 JSON 数据（用户放置）
├── logs/                   # 日志文件（自动生成）
├── tests/                  # 单元测试
├── requirements.txt        # 生产依赖
├── requirements-dev.txt    # 开发依赖
└── README.md               # 本文件
```

---

## 🔧 常用命令

| 操作 | 命令 |
|------|------|
| 导入全部数据 | `python tools/import_poetry.py --data-dir ./data` |
| 仅导入指定目录 | `python tools/import_poetry.py --dirs 纳兰性德` |
| 预览导入（不写入） | `python tools/import_poetry.py --data-dir ./data --dry-run` |
| 启动服务与 GUI | `./start.sh` |
| 停止 Flask | `./stop.sh` |
| 数据清洗（补全标题/作者） | `python tools/clean_data.py titles` |
| 运行单元测试 | `pytest tests/` |

---

## 🐳 Docker 部署（可选）

```bash
cd scripts/docker
docker-compose up -d
```

服务将运行在 `http://localhost:5000`，数据库容器自动初始化。

---

## 🤝 贡献指南

1. Fork 本仓库。
2. 创建新分支 (`git checkout -b feature/your-feature`)。
3. 提交更改 (`git commit -m 'Add some feature'`)。
4. 推送到分支 (`git push origin feature/your-feature`)。
5. 提交 Pull Request。

请确保代码通过 `flake8` 检查并包含适当的单元测试。

---

## 📄 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。

---

## 📖 致谢

- 诗词数据来源于 [chinese-poetry](https://github.com/chinese-poetry/chinese-poetry) 项目。
- 使用 [PySide6](https://doc.qt.io/qtforpython/) 构建图形界面。

---

## 📧 联系方式

如有问题或建议，请提交 Issue 或发送邮件至 `poetry-hub@example.com`。