# Milestone: v1.3 — Path Normalization & Architecture Hardening

**Completed:** 2026-04-24
**Phases:** 11-12 (2 phases)
**Commits:** 75 commits since v1.2

---

## Summary

v1.3 是 **PaperForge** 的第三个里程碑，聚焦两大主题：
1. **路径规范化** — 修复 Zotero 附件路径解析问题，支持多附件识别和 Obsidian wikilink 生成
2. **架构清理** — 消除模块边界泄漏，将 4041 行的单体脚本拆分为 7 个专注模块

---

## Accomplishments

### Phase 11: Zotero Path Normalization (8 tasks)

**核心交付：**
- `_normalize_attachment_path()` — 统一处理 3 种 BBT 导出格式（absolute Windows, storage: prefix, bare relative）
- `_identify_main_pdf()` — 混合策略识别主 PDF vs 补充材料
- `obsidian_wikilink_for_pdf()` — 生成标准 `[[relative/path]]` wikilink
- `paperforge doctor` 增强 — 检测 junction、验证路径、推荐 mklink 命令
- `paperforge repair --fix-paths` — 自动修复路径错误
- `paperforge status` — 显示 path_error 统计

**新 frontmatter 字段：**
- `bbt_path_raw` — 原始 BBT 路径（调试）
- `zotero_storage_key` — 8 位 Zotero 存储键
- `attachment_count` — 附件总数
- `supplementary` — 补充材料 wikilink 列表
- `path_error` — 路径错误状态

**测试：** 25 个新测试方法，全部通过

**提交：** 11 个（包含测试修复）

### Phase 12: Architecture Cleanup (11 tasks)

**核心交付：**
- `paperforge/worker/sync.py` (~1440 行) — selection-sync, index-refresh, 路径工具
- `paperforge/worker/ocr.py` (~1377 行) — OCR 队列、PDF 处理、图表切割
- `paperforge/worker/repair.py` — 状态修复、路径修复
- `paperforge/worker/status.py` — doctor、status 命令
- `paperforge/worker/deep_reading.py` — 深度阅读队列
- `paperforge/worker/base_views.py` — Base 视图管理
- `paperforge/worker/update.py` — 更新系统
- `paperforge/skills/literature-qa/` — 从 skills/ 迁移

**删除：**
- `pipeline/worker/scripts/literature_pipeline.py` (4041 行)
- 整个 `pipeline/` 目录
- 整个 `skills/` 目录

**更新：**
- 40+ 处导入路径更新
- 所有测试文件适配新模块结构
- `paperforge/config.py` 更新 `ld_deep_script` 解析

**测试：** 203 passed, 2 skipped, 0 failed

**提交：** 5 个

---

## Key Decisions

| ID | Decision | Rationale |
|--|---------|-----------|
| D-01 | 统一路径转换时机（load_export_rows 阶段） | 避免下游重复处理 |
| D-02 | 混合策略识别主 PDF | title==PDF → 最大文件 → 最短标题 |
| D-03 | 代码适配所有 BBT 格式 | 不依赖用户配置 |
| D-04 | junction 在 absolutize 中解析 | 简化 wikilink 生成逻辑 |
| D-05 | 颗粒化错误状态 | path_error 字段记录 not_found/invalid/permission_denied |
| D-06 | 完全重构 pipeline → paperforge/worker/ | 与 commands/ 结构对齐 |
| D-07 | skills 保留子目录迁移 | 配套资源需要子目录结构 |
| D-08 | base_views 提取到独立模块 | 完全模块化标准 |

---

## Statistics

| Metric | Value |
|--------|-------|
| Total commits | 75 |
| Phases completed | 2 (11, 12) |
| New modules created | 7 |
| Old modules removed | 2 (pipeline, skills) |
| Lines moved | 4041 → ~2800 (across 7 files) |
| Test coverage | 203 passed, 2 skipped |
| Consistency audit | 4/4 |

---

## Breaking Changes

None.所有变更都是内部重构，用户界面保持不变：
- `paperforge sync` 行为不变
- `paperforge ocr` 行为不变
- `paperforge doctor` 输出增强（新增 Path Resolution 部分）
- Agent 命令 (`/pf-deep`, `/pf-paper`) 不变

---

## Deferred to Future

1. Repair scan O(n*m) 性能优化
2. 一致性审计 CI 集成
3. Skill 热加载机制
4. Supplementary 材料标题确定策略
5. 用户可配置路径覆盖

---

## Verification

```
pytest tests/ -v
# 203 passed, 2 skipped, 0 failed

python scripts/consistency_audit.py
# 4/4 passing
```

---

## Next Milestone Candidates

参考 ROADMAP.md:
- **v1.4** — Base 视图增强、Obsidian 插件架构准备
- **v2.0** — TypeScript Obsidian 插件、UI 界面
