# 晨风书屋项目资料总索引

> 应用版本：V2.3.0
> 备份 schema：2.2.0
> 集成时主站版本：v1.7.2（2026-07-12 历史基线；当前主站版本见根 `VERSION`）
> 状态基准：2026-07-12
> 线上地址：<https://chenningbo.com/library/>

## 1. 项目定位

晨风书屋是面向家庭藏书的在线管理系统。访客可浏览、检索和查看统计；管理员登录后可通过 USB 扫码枪、手机摄像头或手工题名录入，完成编辑、删除、重排、分类核对、补封面及导入导出。

品牌信息：

- 名称：晨风书屋
- 品牌语：晨风入卷，满屋书香
- Meta 标题：`晨风书屋｜晨风入卷，满屋书香 - 家庭线上图书馆`
- 简介：晨风书屋，私人家庭藏书系统。收纳藏书、记录阅读，留存一家人的共读时光。

## 2. 2026-07-12 已验证事实基准

以下数据用于证明 V2.3.0 集成和迁移结果，不代表阅读本文时的实时生产状态。主站当前版本以 P09 根 `VERSION` 为准；生产藏书数量必须通过当次只读核查或受控数据操作确认。

| 项目 | 该次基线事实 |
|:---|:---|
| 唯一源码 | `P09_PersonalWebsite`，旧 `P22_HomeLibrary` 已停止维护 |
| 唯一正式数据源 | `/var/www/data/home_library.db` |
| 已验证藏书基线 | 912 本，2026-07-12 数据库完整性与位置唯一性检查通过 |
| 前端 | `src/library/index.html` + `src/library/library-data.js` |
| 后端 | `src/api/home_library_api.py`，注册到主 Flask 服务 |
| 认证 | 管理员密码只在服务器独立 Secret 中，服务端验证 |
| 智能分类 | DeepSeek Key 只在服务器独立 Secret 中，模型结果仅作建议 |
| 浏览器持久化 | `sessionStorage` 仅存当前标签页管理员会话；`localStorage` 仅存主题及一次性旧标签迁移数据 |
| 发布入口 | `bash sync-website.sh --library-only` |
| 数据保护 | 导入前快照、发布前快照、每天 22:00 有变化才备份、不可变基线 |

代码发布绝不能包含或覆盖正式数据库。页面刷新后从服务器重新加载书目；新增、编辑、删除、重排、分类修正、封面和收藏标签均直接写服务器 SQLite。

## 3. 文档阅读顺序

首次接手项目建议依次阅读：

1. [需求分析](REQUIREMENTS.md)：目标、用户、业务规则和验收标准。
2. [功能规格](PROJECT_SPEC.md)：书架、录入、管理和界面行为。
3. [方案设计](DESIGN.md)：交互流程、分配算法和错误处理。
4. [代码架构](ARCHITECTURE.md)：模块边界、调用链和持久化边界。
5. [数据管理](DATA_MANAGEMENT.md)：数据库、导入导出、备份和恢复。
6. [API 参考](API_REFERENCE.md)：接口、权限、输入输出和错误码。
7. [发布与回滚](DEPLOY.md)：隔离发布、生产保护和恢复步骤。
8. [测试与验收](TEST_REPORT.md)：自动化结果、生产抽测和实体设备缺口。
9. [版本管理](VERSION_MANAGEMENT.md)：主站、子应用和备份 schema 的版本规则。
10. [修改记录](CHANGELOG.md)：V1 至今的版本变更。
11. [工作记录](WORK_LOG.md)：迁移、部署、数据基线和运维事实。
12. [遗留问题与路线图](KNOWN_ISSUES_AND_ROADMAP.md)：未完成事项和优先级。
13. [书目检索专项规划](METADATA_CLASSIFICATION_PLAN.md)：无 ISBN、多源候选和智能分类边界。

## 4. 源码与资料地图

| 路径 | 职责 |
|:---|:---|
| `src/library/index.html` | 页面结构、主题、书架、录入、管理、API 客户端和交互逻辑 |
| `src/library/library-data.js` | CSV/JSON/IndexedDB 包装格式解析、字段归一化和备份文档生成 |
| `src/api/home_library_api.py` | 认证、SQLite、书籍 CRUD、设置、导入导出、封面与 DeepSeek 代理 |
| `src/api/nlc_api.py` | 国图、豆瓣 ISBN 与题名搜索代理 |
| `src/api/chenningbo_api.py` | 主 Flask 入口与 Blueprint 注册 |
| `src/projects/cangshuge.html` | 主站中的晨风书屋项目介绍页 |
| `.hermes/server/backup-library-if-changed.sh` | 每天 22:00 按逻辑数据变化创建一致性备份 |
| `.hermes/server/chenningbo-library-backup.cron` | 条件备份 cron 定义 |
| `src/docs/chenfengshushe/tests/` | API、兼容格式、浏览器和备份恢复测试 |
| `sync-website.sh` | 唯一允许的发布、验证和 Secret 一次性安装入口 |

## 5. 维护边界

- 所有改动先在 P09 本地完成并测试，再通过隔离发布同步。
- 晨风书屋任务不得改动聚闻、博客、导航、其他项目页或其他服务。
- 不能直接 SSH、SCP、裸 rsync 或在服务器上临时编辑网站文件。
- 不能读取、输出、提交或备份管理员密码和 DeepSeek Key。
- 不能把桌面真实备份、生产 SQLite 或用户藏书明细放入 Git。
- 全量导入和数据恢复是高风险数据操作，不属于普通代码发布。
- 修改数据模型、备份 schema 或接口契约时，必须同步更新对应文档和测试。

## 6. 文档状态说明

本目录根部只保留当前有效资料和必要的完整版本记录。早期 P22、IndexedDB、本地 DeepSeek Key、浏览器云备份等机制只作为历史里程碑记录在 `CHANGELOG.md` 与 `WORK_LOG.md`，不再保留会被误读为现行方案的独立旧说明。