# P22 藏书阁 — 详细设计文档

> 版本：V1.2.1 | 日期：2026-05-29

---

## 一、系统架构

```
┌─────────────────────────────────────────────────┐
│                   浏览器                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────────┐  │
│  │ ISBN扫描  │  │ 书架渲染  │  │  搜索/详情   │  │
│  │ (键盘输入) │  │ (CSS Grid)│  │  (DOM事件)   │  │
│  └────┬─────┘  └────┬─────┘  └──────┬───────┘  │
│       │             │               │          │
│  ┌────┴─────────────┴───────────────┴──────┐   │
│  │           IndexedDB (books)             │   │
│  │   id|isbn|title|author|publisher|       │   │
│  │   clcMain|grid|layer|position|location  │   │
│  └─────────────────────────────────────────┘   │
│                       │                         │
│  ┌────────────────────┴────────────────────┐   │
│  │   CLC引擎        │   布局引擎           │   │
│  │  - 22大类配色    │  - 150层预分配       │   │
│  │  - 200+关键词    │  - 动态重排          │   │
│  │  - 智能推荐      │  - 全局fallback      │   │
│  └──────────────────┴──────────────────────┘   │
│                       │                         │
│  ┌────────────────────┴────────────────────┐   │
│  │         ISBN API (联网)                 │   │
│  │  OpenLibrary → Google Books (回退)      │   │
│  └─────────────────────────────────────────┘   │
└─────────────────────────────────────────────────┘
```

## 二、书架布局方案

### 2.1 物理映射

15 格 × 10 层 = 150 个书格层单元，每层容量 20 本，总容量 3000 本。

位置编号格式：`G{格}-L{层}-P{位置}`，如 `G03-L05-12` = 第3格第5层第12本。

### 2.2 CLC 预分配

| CLC | 类别 | 占比 | 层数 | 书架区域 |
|:---|:---|:---|:---|:---|
| I | 文学（小说/散文/杂文） | 35% | 52 | G1～G5 |
| F | 经济/管理 | 12% | 18 | G6～G7 |
| K | 历史/地理 | 10% | 15 | G8～G9 |
| B | 哲学/宗教 | 8% | 12 | G9～G10 |
| T | 工业技术 | 7% | 10 | G10～G11 |
| G | 文化/教育 | 5% | 8 | G11～G12 |
| H | 语言/文字 | 5% | 7 | G12～G13 |
| J | 艺术 | 4% | 6 | G13 |
| R | 医药/卫生 | 3% | 4 | G13～G14 |
| O | 数理化 | 2% | 3 | G14 |
| D | 政治/法律 | 2% | 3 | G14 |
| C | 社科总论 | 2% | 2 | G14 |
| Z | 综合/百科 | 1% | 2 | G15 |
| N | 自然科学 | 1% | 2 | G15 |
| — | 其他小类(A/E/P/Q/S/U/V/X) | 3% | 6 | G15 |

### 2.3 位置分配算法

```
allocateLocation(clcMain):
  1. 查找该CLC的预分配区域
  2. 在区域内找第一个有空位的层（<20本）
  3. 如果区域满了 → 全局扫描找空位
  4. 如果全局满了 → 返回null（提示用户重排）
```

### 2.4 动态重排算法

```
rebuildLayout():
  1. 统计每个CLC大类的实际藏书数
  2. 计算各类需要的层数 = ceil(藏书数/20)
  3. 按原顺序重新分配150层
  4. 逐类重新放置所有书籍到新位置
  5. 更新IndexedDB和内存缓存
```

## 三、CLC 分类引擎

### 3.1 22 大类配色

```
A=#D32F2F B=#7B1FA2 C=#E64A19 D=#455A64 E=#5D4037
F=#F9A825 G=#388E3C H=#0288D1 I=#C62828 J=#E91E63
K=#795548 N=#00897B O=#1565C0 P=#00ACC1 Q=#43A047
R=#EC407A S=#827717 T=#1E88E5 U=#6D4C41 V=#3949AB
X=#2E7D32 Z=#757575
```

### 3.2 关键词推荐（离线）

11 个分类规则，200+ 关键词，覆盖常见中文书籍：

- **I 文学**：小说/散文/诗歌/四大名著/百年孤独/活着/三体...
- **K 历史**：历史/朝代/明朝/唐朝/史记/资治通鉴...
- **B 哲学**：哲学/论语/孟子/庄子/道德经/禅...
- **F 经济**：经济/管理/金融/投资/理财/营销...
- **T 技术**：编程/Python/Java/算法/AI/计算机...
- **其他**：G教育/H语言/J艺术/R医药/O数理化/D法律

## 四、数据模型

### 4.1 书籍对象

```javascript
{
  id: Number,        // 自增主键
  isbn: String,      // ISBN
  title: String,     // 书名
  author: String,    // 作者
  publisher: String, // 出版社
  clcMain: String,   // CLC大类（A-Z）
  clcCode: String,   // 完整分类号
  grid: Number,      // 格子 1-15
  layer: Number,     // 层 1-10
  position: Number,  // 该层中位置 1-20
  location: String,  // 位置编号 "G03-L05-12"
  addedAt: String,   // 录入日期
  note: String       // 备注
}
```

### 4.2 IndexedDB

- 数据库：HomeLibrary
- 对象存储：books（keyPath: id, autoIncrement）
- 索引：isbn, title, clcMain, location, grid, layer

## 五、ISBN 查询流程

```
扫描/输入ISBN
    │
    ├─ [联网] OpenLibrary API (5s超时)
    │     ├─ 成功 → 填充书名/作者/出版社 + 推荐CLC
    │     └─ 失败 ↓
    │
    ├─ [联网] Google Books API (3s超时)
    │     ├─ 成功 → 填充书名/作者/出版社 + 推荐CLC
    │     └─ 失败 ↓
    │
    └─ [离线] 手动填写书名 → 关键词引擎推荐CLC
```

### 快速模式

当"快速模式"勾选时：
1. API 成功返回 + CLC推荐成功 → 0.6s后自动入库
2. 入库后清空表单，ISBN重新聚焦
3. 继续扫下一本...

## 六、交互设计

### 6.1 书架浏览

| 操作 | 方式 |
|:---|:---|
| 平移 | 鼠标拖拽空白区 / 键盘方向键(80px/次) |
| 缩放 | Ctrl + 滚轮 |
| 3D透视 | 点击"3D"按钮切换 |
| 归位 | 点击"⊡"或按Home键 |

### 6.2 书籍交互

| 操作 | 结果 |
|:---|:---|
| 悬停书脊 | 浮层显示书名/作者/位置 |
| 点击书脊 | 弹详情窗口（可编辑/删除） |
| 点击格子(多书) | 弹出该格10层放大视图 |
| 点击格子(单书) | 直接弹详情 |
| 点击空格子 | 无操作（通过按钮录入） |

### 6.3 搜索

- Ctrl+F 聚焦搜索框
- 支持书名/作者/ISBN/出版社模糊搜索
- 结果下拉列表，点击直接定位+弹详情
- Escape 关闭搜索

## 七、数据安全

- **导出**：JSON格式备份，包含所有书籍数据
- **导入**：清空现有数据后导入，id重新分配
- **浏览器缓存**：清除IndexedDB会丢失数据 → 定期导出备份
- **重排安全**：重排只修改位置字段，不丢失数据