# 古诗词阅读网站

基于大模型分类的中国古诗词阅读管理系统

## 系统架构

```
┌─────────────────────────────────────────────────────────┐
│                    古诗词阅读网站                        │
├─────────────────────────────────────────────────────────┤
│  Frontend (原生 JS + CSS)  │  Backend (FastAPI + SQLite)│
│  - 多类别组合筛选           │  - RESTful API            │
│  - 阅读标记管理             │  - SQLite 数据库           │
│  - 标签云浏览               │  - 分类查询               │
│  - 进度统计                 │  - 批量导入               │
├─────────────────────────────────────────────────────────┤
│              classify_pois.py (LLM 分类脚本)             │
│                   - 20 维分类标签体系                     │
│                   - 繁体转简体支持                        │
│                   - 实时去重 + 持久化                     │
└─────────────────────────────────────────────────────────┘
```

## 核心功能

### 1. 20 维分类标签体系

| 维度分类 | 标签数量 | 示例 |
|---------|---------|------|
| **季节时序** | 39 | 春、夏、秋、冬、24 节气、时辰 |
| **题材类型** | 17 | 山水田园、边塞征战、咏史怀古等 |
| **情感心境** | 31 | 情感基调 11 种 + 具体情感 20 种 |
| **景物意象** | 77 | 自然、植物、动物、建筑、色彩、声音 |
| **哲理思想** | 7 | 儒家、道家、佛家、人生感悟等 |
| **艺术手法** | 18 | 写作手法、修辞手法 |
| **人物社会** | 33 | 人生阶段、社会身份、地理方位、节日 |

### 2. 繁体转简体支持

- ✅ 自动识别繁体中文诗词
- ✅ LLM 自动转换为简体中文
- ✅ 保留原始繁体版本（可选）
- ✅ 基于简体内容去重（繁简同一首诗不会重复）
- ✅ 所有分类标签统一使用简体

**输入示例（繁体）：**
```json
{
  "title": "山居秋暝",
  "author": "王維",
  "paragraphs": ["空山新雨後，天氣晚來秋。", "明月鬆間照，清泉石上流。"]
}
```

**输出示例（简体）：**
```json
{
  "title": "山居秋暝",
  "author": "王维",
  "paragraphs": ["空山新雨后，天气晚来秋。", "明月松间照，清泉石上流。"],
  "original_paragraphs": ["空山新雨後，天氣晚來秋。", "明月鬆間照，清泉石上流。"],
  "llm_classification": {
    "season": ["秋"],
    "genre": ["山水田园", "隐逸闲适"],
    ...
  }
}
```

### 3. 多类别组合筛选

支持同时选择多个分类标签进行组合筛选：
- 题材=山水田园 AND 情感=宁静淡泊
- 季节=春 AND 地点=江南 AND 情感=喜悦
- 使用 SQL 查询优化，支持复杂筛选条件

### 4. 阅读管理

- 标记诗词为已读/未读
- 阅读进度统计（百分比 + 数量）
- 阅读时间记录
- 快速切换阅读状态

### 5. 批量导入

- 支持 JSON/JSONL 格式
- 自动去重（基于内容签名 MD5）
- 实时写入数据库
- 导入结果反馈

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 使用 LLM 脚本分类诗词

```bash
# 本地模型 (Ollama 等)
python classify_pois.py ./poems ./output.jsonl --llm \
  --base-url http://localhost:11434/v1 \
  --model qwen:7b

# 远程模型 (OpenAI 等)
python classify_pois.py ./poems ./output.jsonl --llm \
  --base-url https://api.openai.com/v1 \
  --model gpt-4 \
  --api-key sk-xxx

# 繁体诗词测试
python classify_pois.py ./ ./output.jsonl --llm \
  --base-url http://localhost:11434/v1 \
  --model qwen:7b
```

### 3. 启动后端服务

```bash
cd backend
python main.py
```

服务启动后访问：http://localhost:8000

### 4. 前端页面

浏览器打开：http://localhost:8000

### 5. 上传诗词

通过前端界面的上传功能，上传分类后的 JSONL 文件到数据库。

## API 端点

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/` | 前端页面 |
| GET | `/api/categories` | 获取分类体系 |
| GET | `/api/stats` | 获取统计数据 |
| POST | `/api/poems/import` | 批量导入诗词 |
| GET | `/api/poems` | 获取诗词列表（支持分页、筛选） |
| GET | `/api/poems/{id}` | 获取诗词详情 |
| PUT | `/api/poems/{id}/read` | 切换阅读状态 |
| GET | `/api/poems/random` | 随机一首 |
| GET | `/api/tags/cloud` | 标签云数据 |

### API 使用示例

```bash
# 获取诗词列表（带多类别筛选）
GET /api/poems?page=1&page_size=20&categories=genre:山水田园,emotion_tone:宁静淡泊

# 搜索诗词
GET /api/poems?search=李白

# 获取已读诗词
GET /api/poems?is_read=true

# 获取未读诗词
GET /api/poems?is_read=false

# 标记为已读
PUT /api/poems/{id}/read?is_read=true

# 标记为未读
PUT /api/poems/{id}/read?is_read=false
```

## 数据格式

### 输入格式（JSON/JSONL）

```json
{
  "id": "poem_001",
  "title": "山居秋暝",
  "author": "王维",
  "paragraphs": [
    "空山新雨后，天气晚来秋。",
    "明月松间照，清泉石上流。",
    "竹喧归浣女，莲动下渔舟。",
    "随意春芳歇，王孙自可留。"
  ],
  "llm_classification": {
    "season": ["秋"],
    "solar_terms": ["白露"],
    "time_of_day": "黄昏",
    "genre": ["山水田园", "隐逸闲适"],
    "emotion_tone": "宁静淡泊",
    "emotions": ["静", "喜", "乐"],
    "nature_scenery": ["山", "水", "月"],
    "plants": ["松", "竹"],
    "animals": ["鸟"],
    "buildings": [],
    "imagery": ["空山", "新雨", "明月"],
    "philosophy": ["道家思想", "自然之道"],
    "life_stage": "中年",
    "social_role": "隐士",
    "technique": ["借景抒情", "动静结合"],
    "rhetoric": ["拟人"],
    "colors": ["青", "白"],
    "sounds": [],
    "location": "终南山",
    "festival": "无",
    "analysis": "这首诗描绘了秋日山居的幽静景色..."
  }
}
```

### 输出格式（API 响应）

```json
{
  "id": "poem_001",
  "title": "山居秋暝",
  "author": "王维",
  "paragraphs": ["空山新雨后，天气晚来秋。", ...],
  "original_paragraphs": null,
  "classifications": {
    "season": ["秋"],
    "genre": ["山水田园", "隐逸闲适"],
    ...
  },
  "is_read": false,
  "read_at": null,
  "created_at": "2024-01-01T00:00:00"
}
```

## 数据库结构

### poems 表
```sql
CREATE TABLE poems (
    id TEXT PRIMARY KEY,
    title TEXT NOT NULL,
    author TEXT NOT NULL,
    paragraphs TEXT,
    signature TEXT UNIQUE,
    created_at TIMESTAMP,
    updated_at TIMESTAMP
);
```

### classifications 表
```sql
CREATE TABLE classifications (
    id INTEGER PRIMARY KEY,
    poem_id TEXT,
    category TEXT,
    tags TEXT,
    FOREIGN KEY (poem_id) REFERENCES poems(id)
);
```

### reading_records 表
```sql
CREATE TABLE reading_records (
    id INTEGER PRIMARY KEY,
    poem_id TEXT UNIQUE,
    is_read BOOLEAN,
    read_at TIMESTAMP,
    FOREIGN KEY (poem_id) REFERENCES poems(id)
);
```

## 完整分类标签体系

| 维度 | 键名 | 标签数量 | 标签示例 |
|------|------|---------|---------|
| 季节 | season | 6 | 春、夏、秋、冬、四季 |
| 节气 | solar_terms | 24 | 立春、雨水、清明、谷雨 |
| 时辰 | time_of_day | 9 | 清晨、黄昏、夜晚、黎明 |
| 题材 | genre | 17 | 山水田园、边塞征战、咏史怀古 |
| 情感基调 | emotion_tone | 11 | 宁静淡泊、喜悦欢快、悲伤哀愁 |
| 具体情感 | emotions | 20 | 喜、怒、哀、乐、忧、思 |
| 自然景物 | nature_scenery | 14 | 山、水、云、雨、日、月 |
| 植物 | plants | 15 | 松、竹、梅、兰、菊、荷 |
| 动物 | animals | 14 | 鸟、雁、燕、蝉、蛙、鱼 |
| 建筑 | buildings | 15 | 楼、阁、亭、台、桥、寺 |
| 哲理 | philosophy | 7 | 儒家思想、道家思想、佛家禅理 |
| 人生阶段 | life_stage | 5 | 少年、青年、中年、老年 |
| 社会身份 | social_role | 10 | 士人、官员、隐士、游子 |
| 写作手法 | technique | 9 | 比兴、借景抒情、托物言志 |
| 修辞手法 | rhetoric | 9 | 比喻、拟人、夸张、对偶 |
| 色彩 | colors | 10 | 青、绿、红、白、黄、紫 |
| 声音 | sounds | 9 | 钟声、琴声、鸟鸣、雨声 |
| 地理 | location | 9 | 江南、塞北、巴蜀、关中 |
| 节日 | festival | 9 | 春节、中秋、重阳、端午 |

## 技术栈

- **后端**: FastAPI + SQLite + Uvicorn
- **前端**: 原生 JavaScript + CSS (无框架依赖)
- **分类**: 基于 LLM API (支持本地/远程模型)
- **简繁转换**: LLM 自动识别和转换

## 扩展开发

### 添加新的分类维度

1. 在 `backend/main.py` 的 `CATEGORY_SYSTEM` 中添加新维度
2. 在 `classify_pois.py` 的 `CLASSIFICATION_PROMPT` 中添加对应提示
3. 在前端 CSS 中添加对应标签样式

### 部署建议

```bash
# 生产环境使用
uvicorn backend.main:app --host 0.0.0.0 --port 8000 --workers 4

# 或使用 gunicorn
gunicorn backend.main:app -w 4 -k uvicorn.workers.UvicornWorker
```

### 简繁切换显示（可选）

在前端添加简繁切换功能：

```javascript
let showTraditional = false;

function toggleTraditional() {
    showTraditional = !showTraditional;
    const poem = state.currentPoem;
    const content = showTraditional && poem.original_paragraphs
        ? poem.original_paragraphs
        : poem.paragraphs;
    // 重新渲染内容
}
```

## 常见问题

**Q: 导入时提示重复？**  
A: 系统基于诗词内容签名（MD5）去重，相同内容的诗词只会保留一份。繁体和简体版本会被识别为同一首诗。

**Q: 如何重置阅读进度？**  
A: 直接修改数据库中 `reading_records` 表的 `is_read` 字段，或在前端重新标记。

**Q: 支持哪些 LLM 模型？**  
A: 任何支持 OpenAI 兼容 API 的模型，包括 Ollama、vLLM、OpenAI GPT、Anthropic Claude 等。

**Q: 繁体诗词如何处理？**  
A: 分类脚本会自动识别繁体中文，LLM 会返回简体版本。原始繁体会保存在 `original_paragraphs` 字段中。

**Q: JSONL 文件和 SQLite 数据库的关系？**  
A: JSONL 是分类脚本的输出格式（中间产物），SQLite 是网站运行的数据库（最终存储）。通过 API 导入功能将 JSONL 导入数据库。

## 项目结构

```
PoemClassify/
├── classify_pois.py          # LLM 分类脚本
├── requirements.txt          # Python 依赖
├── backend/
│   ├── main.py              # FastAPI 后端
│   └── poems.db             # SQLite 数据库（运行时生成）
├── frontend/
│   ├── index.html           # 前端页面
│   ├── script.js            # 前端逻辑
│   └── style.css            # 样式文件
├── test_traditional.json    # 繁体测试文件
└── README.md                # 本文档
```

## 数据备份

```bash
# 备份 SQLite 数据库
cp backend/poems.db backup_$(date +%Y%m%d).db

# 导出数据库为 JSONL
sqlite3 backend/poems.db "SELECT json_object('id',id,'title',title,'author',author,'paragraphs',paragraphs) FROM poems;" > export.jsonl

# 从 JSONL 恢复
curl -X POST http://localhost:8000/api/poems/import -F "file=@export.jsonl"
```

## License

MIT License