# 晨风书屋书目检索与智能分类规划

> 适用版本：V2.2.0 及后续版本<br>
> 日期：2026-07-12<br>
> 状态：服务器端模型代理与独立 Key 已部署；多源候选尚未实施

## 1. 要解决的问题

录入失败并不是同一种问题，需要分开处理：

1. ISBN 有效，但单一书目源没有收录或暂时不可用。
2. 能查到书名、作者和出版社，但没有可信的中图分类号。
3. 老旧书籍没有 ISBN，只能依靠题名、作者、出版社和出版年份检索。
4. 多个版本题名相同，自动选中第一条容易把版次、作者或出版社匹配错。

大模型适合解决第 2 类问题，并可辅助第 3、4 类候选排序；它不应替代权威书目源，也不能直接生成并保存事实字段。

## 2. 目标录入链路

```text
扫码枪 / 手机摄像头 / 手工题名
  -> 输入校验与标准化
  -> 服务器聚合多个书目源
  -> 返回一个或多个候选及来源
  -> 权威 CLC / 出版社规则 / 关键词规则
  -> 仍无可靠分类时调用 DeepSeek 给出建议
  -> 页面显示候选、来源和置信度
  -> 用户人工确认
  -> POST /api/home-library/books
  -> 服务器返回正式 id
  -> 页面重新读取服务器书架
```

手机、电脑和 USB 扫码枪必须共用现有 `/api/home-library/books` 写入接口和同一个 SQLite 数据库，不增加离线副本或第二套写库通道。

## 3. 三种录入模式

### 3.1 USB 扫码枪

- 保留快速连续录入。
- ISBN checksum 不通过时立即停止查询，不写库。
- 只有权威书目源同时返回书目信息和 CLC 时，才允许现有快速确认流程。
- 只有推断分类、候选冲突或信息不完整时，暂停自动录入并要求人工确认。

### 3.2 手机摄像头

- 原生 `BarcodeDetector` 优先识别 EAN-13，ISBN 必须通过 checksum 且以 978/979 开头。
- 扫码后自动查询和填表，但一律不自动保存。
- 权限拒绝、浏览器不支持、页面隐藏或关闭扫码层时立即停止摄像头轨道。

### 3.3 无 ISBN 老书

- 题名必填，作者、出版社、出版年份和版次作为缩小范围的条件。
- 搜索结果以候选列表展示，不自动采用第一条。
- 用户选择候选后再填充字段；没有可靠候选时保留人工录入。
- 后续可增加封面/版权页 OCR，但 OCR 结果也必须作为待确认文本，不能直接写库。

## 4. 数据来源与置信度

建议按以下优先级聚合，具体来源是否可长期使用需在实施时核对许可、稳定性和访问限制：

| 等级 | 结果 | 处理方式 |
|:---|:---|:---|
| A | 权威来源返回完整书目和 CLC | 可进入快速确认 |
| B | 两个独立来源的题名、作者、出版社一致 | 填充书目，分类仍单独判断 |
| C | 单一来源或规则推断 | 明确标记来源，必须人工确认 |
| D | 仅大模型建议或候选存在冲突 | 只能作为建议，不允许自动保存 |

ISBN、题名、作者、出版社属于事实字段，优先采用书目源。CLC 建议按“权威 CLC -> 出版社规则 -> 关键词规则 -> DeepSeek”的顺序产生。

## 5. DeepSeek 接入边界

### 5.1 必须放在服务器端

目标实现使用服务器环境变量，例如：

```text
HOME_LIBRARY_DEEPSEEK_API_KEY=<secret>
HOME_LIBRARY_DEEPSEEK_MODEL=deepseek-chat
```

浏览器不保存正式 Key，不把 Key 写入 Git、HTML、日志或导出备份。历史 `localStorage` 输入和浏览器直连代码已删除。

### 5.2 建议接口

```text
POST /api/home-library/classification/suggest
```

分类接口已经实现并要求管理员令牌，只接收规范化后的题名、作者、出版社和摘要，不上传数据库内容或家庭备注。后续多源候选接口计划使用 `POST /api/home-library/metadata/search`。

建议响应固定为结构化 JSON：

```json
{
  "clcMain": "I",
  "clcCode": "I247.5",
  "confidence": 0.82,
  "source": "deepseek",
  "reason": "题名和简介显示为中国当代长篇小说"
}
```

服务端必须校验代码属于允许的 CLC 集合，并设置超时、频率限制、每日调用上限和不含隐私内容的操作日志。模型失败时应降级为人工选择，不得阻断录入。

## 6. 数据正确性规则

- 模型建议不直接调用写接口。
- 页面必须展示书目信息来源、分类来源和置信度。
- 候选冲突、低置信度、无 ISBN、手机扫码均必须人工确认。
- 重复 ISBN 允许按同书多册保存，但需要提示现有书名和位置。
- `(grid, layer, position)` 由服务器唯一约束保护；冲突时客户端刷新后最多自动重试一次。
- 写入成功后以服务器返回的 `id` 为准，并重新读取服务器数据。

## 7. 实施顺序

1. V2.2.0：完成手机扫码、移动端操作、人工确认和并发位置保护。
2. 增加服务器端多源书目聚合与候选列表，先解决“查不到”和“匹配错”。
3. 已增加服务器端 DeepSeek 分类建议接口并删除浏览器 Key；调用审计仍待实施。
4. 为书籍增加 `metadata_source`、`classification_source`、`confidence`、`verified_at` 等可追溯字段，并升级备份 schema。
5. 使用脱敏样本建立回归集，分别统计 ISBN 命中率、候选正确率、CLC 大类准确率和人工修正率。

DeepSeek Key 已通过项目外一次性中转文件安装到 `/etc/chenningbo/secrets/home-library.env`，不纳入备份或普通发布。调用预算、代表性样本准确率、模型名称和后续 Key 轮换仍属于单独的生产配置决策。