# 开发说明

## 模块边界

| 目录 | 职责 |
| --- | --- |
| `paper_atlas/cli.py` | 注册命令并延迟加载对应模块，统一参数入口 |
| `paper_atlas/collectors/` | 各来源的发现、解析与清单输出，不直接写论文主库 |
| `paper_atlas/io/` | 公共 HTTP、原始快照、HTML 树与受限 Git 元数据读取 |
| `paper_atlas/ingestion/` | 核对清单、事务导入、维护锁和来源身份回填 |
| `paper_atlas/db/` | 论文与投稿身份解析、来源保留、合并审计和 schema |
| `paper_atlas/audits/` | 入库前来源对照及全部目标的覆盖报告 |
| `paper_atlas/querying.py` | 一致性只读快照上的查询 |
| `paper_atlas/resources/` | 随安装包提供的候选会议目录 |

采集器依赖公共 IO，导入器依赖存储层，查询和审计读取既有证据。不要让公共网络模块反向依赖某个采集器，也不要在 CLI 中嵌入来源解析逻辑。新增采集器需要注册命令、输出带来源/届次/track 的清单，并补充有意义的来源边界验证。

## 远程验证

所有测试、构建、打包及安装验证在确认的 `ces-control:host` 环境进行。本机只编辑源码和进行不触发构建的检查。

```sh
python3 -B -m unittest discover -s tests -t . -v
```

`.gitea/workflows/check.yml` 会运行回归测试，构建并安装 wheel，然后从源码目录之外检查 console 命令、模块入口、schema 和会议目录资源。测试中只使用独立临时库，不连接运行中的论文主库。

## 目录迁移

原根目录脚本已迁入对应模块，统一使用 `paper-atlas <command>` 或 `python -m paper_atlas <command>`。不再把脚本文件路径作为接口。SQL schema、来源 JSONL、manifest 及既有数据库结构未因这次封装改变。

部署使用固定 commit。仍在运行的旧批次继续使用已部署版本，待该批次完成后再切换后续任务；不要为了目录迁移重启已完成的全量导入。