# 晨风书舍 — 工程记录

> **稳定版 V1.12.7** | 2026-06-01

## 项目概述

单文件 HTML 家庭图书管理系统。扫描 ISBN → 自动获取书名/作者/CLC 分类号 → 自动上架。  
15 列书架，A→Z 顺序等比例排列，含预留空格缓冲。

## 技术架构

| 层 | 技术 | 说明 |
|:---|:---|:---|
| 前端 | 单文件 HTML+CSS+JS | IndexedDB 存储，零依赖 |
| API | Python Flask | NLC OPAC + 豆瓣搜索 |
| 部署 | Nginx + systemd | chenningbo.com /api/ |
| 封面 | OpenLibrary | covers.openlibrary.org |
| 云备份 | chenningbo.com | POST/GET /api/home-library/backup |
| 分类AI | DeepSeek API | NLC 无结果时自动推断中图分类 |

## 书架规则（V1.12.7 稳定版）

### 层规则
| 层 | 用途 | 状态 |
|:---|:---|:---|
| L1-L2 | 保留层（中间层 80% 后开放） | 虚线展示，不录入 |
| L3-L8 | 活跃层（普通书籍录入区） | 正常使用 |
| L9 | 底层收藏区（手办/杂志/手机盒等） | 可点击自定义文字标签 |

### 列规则
| 列 | 用途 | 状态 |
|:---|:---|:---|
| G1-G13 | CLC A→Z 编码管理 | 等比例预留 |
| G14 | 儿童书籍（不纳入编码） | 固定列，L1 显示橙色"儿童"标签 |
| G15 | 相册（不纳入编码） | 固定列，L1 显示紫色"相册"标签 |

### 容量计算
- 活跃格：13 × 6 = **78 格**
- 每格：15 本
- 活跃容量：78 × 15 = **1170 本**
- 开放顶层后：(13×8 + 2) × 15 = **1590 本**

### 比例分配算法（`proportionalAlloc`）
两步走，确保总格数恰好 = 78：
1. **保底**：每类给 `ceil(count/15)` 格（存量书能放下）→ 共 57 格
2. **缓冲**：剩余 21 格按录入量比例分配（小数部分最大者优先得余格）

结果（以 693 本为例）：
- I 类（282 本 / 40.7%）→ 27 格，容量 405，缓冲 123 本
- K 类（121 本 / 17.5%）→ 13 格，容量 195，缓冲 74 本
- Z 类（3 本 / 0.4%）→ **1 格，位于 G13 最后一格**

## 数据源策略

| 优先级 | 源 | 用途 | 状态 |
|:---|:---|:---|:---|
| 1 | 国图 OPAC（chenningbo.com/api/isbn） | CLC 分类号 + 书目 | ✅ 正常，⚠ 单IP日限 |
| 2 | 豆瓣服务端搜索（chenningbo.com/api/douban） | 书名/作者 | ✅ 正常 |
| 3 | 豆瓣 CORS 代理 | 书名/作者/简介 | ✅ 备用 |
| 4 | **DeepSeek API**（本地 Key） | NLC 无结果时推断 CLC | ✅ 按需调用 |
| 5 | OpenLibrary | 封面图 | ✅ 封面可用 |
| 6 | Google Books | 海外备用 | ❌ 国内不通 |

## 关键功能清单（V1.12.7）

### 书架展示
- [x] A→Z 从左到右严格排列，等比例预留空格
- [x] 每格只属于一个分类（不混放）
- [x] 空格显示分类名标签 + 分类色底色
- [x] G14/G15 列标识（L1 行显示"儿童"/"相册"）
- [x] L9 可点击编辑收藏标签
- [x] 书脊显示标题（≤4本→10字，≤9本→8字，≥10本→6字）
- [x] Ctrl+滚轮缩放

### 录入流程
- [x] ISBN 扫描 → 国图 API → CLC + 书目（自动保存）
- [x] 国图失败 → 豆瓣 → DeepSeek 推断 CLC → 自动保存
- [x] 无 ISBN 旧书 → 手动输书名 → 🔍 搜索补全 → DeepSeek 推断分类
- [x] DeepSeek Key 管理（顶栏 🤖 按钮，localStorage 存储）
- [x] 重复 ISBN 检测

### 数据管理
- [x] 重排（比例分配，A→Z，溢出全局兜底）
- [x] 批量修正（国图重新拉取 CLC）
- [x] 重排前混放格子检测
- [x] CSV 导入导出（UTF-8 BOM）
- [x] JSON 导入导出
- [x] 云端备份/恢复（自动 + 手动）
- [x] 补封面（OpenLibrary）
- [x] 拖拽移动书籍

### 统计面板
- [x] 甜甜圈饼图：CLC 分类分布 + 侧边图例
- [x] 作者 Top10 横条图
- [x] 出版社 Top10 横条图
- [x] KPI 卡片：总藏书、分类数、ISBN 覆盖率、书架利用率、最近录入

## 已知限制

1. **NLC 限流**：批量修正每日约 12 次/IP 上限
2. **DOM 性能**：1000+ 本时全量重建约 200ms，可优化为增量更新
3. **旧书无 ISBN**：DeepSeek 推断准确率约 90%，版权页中图号更准确

## 版本里程碑

| 版本 | 日期 | 关键变更 |
|:---|:---|:---|
| **V1.12.7** | 06-01 | 🔒 稳定版：修复 SyntaxError，比例分配完整实现 |
| V1.12.6 | 06-01 | 两步比例分配算法（proportionalAlloc），Z→G13 末位 |
| V1.12.5 | 06-01 | 修复统计 ID 冲突（statsBar 重名导致图表空白） |
| V1.12.4 | 06-01 | 比例分配初版 |
| V1.12.3 | 06-01 | 重排逻辑重写（无跳层+溢出兜底）、G14/G15 标识、L9 可编辑 |
| V1.12.2 | 06-01 | DeepSeek API 集成（NLC 失败时推断 CLC） |
| V1.12.1 | 06-01 | 手动录入 🔍 按钮、重排混放检测、区域文字去重叠 |
| V1.12.0 | 06-01 | 统计面板重设计（甜甜圈+作者+出版社） |
| V1.11.9 | 06-01 | 区域底色 + 空格分类标签 |
| V1.11.8 | 06-01 | A→Z 排序修正，严格每格独占 |
| V1.11.7 | 06-01 | 书名字数适配、统计按钮修复 |
| V1.11.6 | 06-01 | 层规则修正（L1-L2 保留、L9 杂志区、START=3、END=8） |
| V1.11.5 | 06-01 | 10 个 bug 修复（缩放/CLC 匹配/渲染/统计等） |
| V1.11.4 | 06-01 | 云备份、封面、CSV 导入导出、统计面板、9 层书架 |

## 下次迭代候选

- [ ] 增量 DOM 更新（1000+ 本性能优化）
- [ ] NLC 批量修正限速（避免触发日限）
- [ ] 无 ISBN 旧书书名搜索准确率提升