docs: 工程骨架落地记录（架构 §13）与 AGENTS.md 工程一节

- 架构 §13：SK1–SK8，SK1（事件流用 Valkey stream）、SK2（测试不用 testcontainers）待确认
- api-design §10：接口实现进度
- openapi.yaml：ChecklistItem 的必填字段在同一层声明，生成的类型不再是可选
- AGENTS.md：目录结构、常用命令、编码约定、当前进度

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/architecture/api-design.md

@@ -179,3 +179,17 @@
 | API3 | 异地多设备并发登录怎么「提示并限制」 | **新设备登录时提示「账号已在其他设备登录」，用户确认后挤掉旧设备**。另一种做法是旧设备不退出就不让新设备登录，但用户换了电脑、忘了退出时就登不上了 |
 | API4 | 扣点说明和实际扣点不一致时 | **拒绝并刷新说明，不扣点**（§4.1）。用户看到「不扣点」，结果却扣了，这种情况必须杜绝 |
 | API5 | 报告怎么生成 | **后台生成**，完成后推送事件。用 Chromium 生成 PDF 要几秒到十几秒，不放在请求里同步做（架构：api 只做短事务） |
+
+## 10. 实现进度（工程骨架）
+
+骨架阶段只实现了「上传 → 解析 → 显示清单」这条最小链路要用的接口。`server/tests/test_contract.py` 保证已实现的接口都在契约里；契约里还没实现的，按模块列在这里，实现一个划掉一个。
+
+| 模块 | 已实现 | 还没实现 |
+|---|---|---|
+| 登录与账号 | 发验证码、注册、登录（含挤下线确认）、退出、`GET /me` | 修改显示名、在线会话列表和下线、注销账号 |
+| 额度与套餐 | `GET /plans`、`GET /quota` | 额度流水、开通申请 |
+| 项目 | 列表（不含筛选和分页）、新建、详情 | 基本信息字段修改与补遗确认、状态变更、删除、分包的增删改和选包 |
+| 上传与文档 | 分片上传全套、挂到项目、文档列表和详情、逐页摘要、一页的句子、签名下载、发起解析、解析进度、取消 | 删除文档、人工建出处 |
+| 清单 | 清单概况、清单项列表（只按区域筛选） | 修改、采纳、删除恢复、替换出处、补遗更新确认、修改记录、确认清单、版本 |
+| 检查、报告、资质 | — | 全部（查标阶段） |
+| 通知与事件 | 事件流、通知列表 | 标为已读、反馈 |

docs/architecture/architecture.md

@@ -839,4 +839,21 @@ S1–S4 风险最高，建议先做；S8（桌面外壳 PoC）等桌面版立项
 1. 做技术验证 S1–S4，结论写进本文件，并据此确定 FR-M2-05、FR-M2-06 的目标值。
 2. ~~物理数据建模~~：✅ 已完成，见 `data-model.md`、`schema-draft.sql`（DM1–DM7 已确认）。
 3. ~~定接口契约~~：✅ 已完成，见 `api-design.md`、`openapi.yaml`（API1–API5 已确认）。
-4. 搭工程骨架：仓库结构、CI、Compose 一键启动、一个贯通「上传 → 解析 → 显示清单」的最小链路。
+4. ~~搭工程骨架~~：✅ 已完成，见 §13 和 AGENTS.md「工程」一节。
+
+## 13. 工程骨架的落地记录（2026-11-03）
+
+搭骨架时按代码实际情况做了下面这些调整或补充。SK1、SK2 改了上文的写法，待确认；其余是实现细节，记在这里备查。
+
+| # | 事项 | 做法 | 状态 |
+|---|---|---|---|
+| SK1 | 进度推送（§3.4） | 用 **Valkey stream** 代替发布 / 订阅：一个结构同时解决实时推送和断线补发（按 `Last-Event-ID` 续读），多个 api 实例都能读到。Valkey 丢了也只是没有推送，前端轮询兜底 | 待确认 |
+| SK2 | 接口集成测试（§8） | 不用 testcontainers，改为连 Compose 起的 PostgreSQL，每次测试会话重建 `bid_doctor_test` 库；CI 里用 GitHub Actions 的服务容器。更快，本地和 CI 走同一套配置 | 待确认 |
+| SK3 | 建任务和入队在同一个事务里（§3.4） | Procrastinate 的 `defer` 用的是它自己的连接，进不了我们的事务，所以直接调用它的 SQL 函数 `procrastinate_defer_jobs_v1`（`core/queue.py`）；它的表放在 public schema。pyproject 锁定了大版本，升级时要核对 | 已实现 |
+| SK4 | 上传会话（§5.2 第 7 条） | 上传会话的元数据放在 Valkey（24 小时过期），分片按企业级数据密钥加密后写进对象存储；挂到项目上时换成项目密钥 | 已实现 |
+| SK5 | ORM 模型 | 表结构以迁移为准，ORM 模型只做列映射、不声明外键，所以写入顺序要自己 `flush` 保证（测试里踩到过两次） | 编码约定 |
+| SK6 | 文字层 | 有的 PDF（如 Chromium 生成的）把汉字映射成康熙部首码位（「目」成了 U+2F6C），引文校验会对不上；文字层把康熙部首和部首补充区换回常用汉字，其他字符不动 | 已实现 |
+| SK7 | 斜体下划线（07 F1） | 只有文件的「标注规则说明」声明过斜体下划线标注，才按它认定实质性条款；没声明的文件里，标题、表头也常是斜体或下划线（S02 实测踩到） | 已实现 |
+| SK8 | 登录验证码 | 登录和注册共用一个验证码；会话建好之后才作废，用户确认挤下线（API3）或发现「还没注册」时不用重新获取 | 已实现 |
+
+还没做、留了 TODO 的：转换镜像的字体包和 WPS 旧版 DOC 预处理（S1）、表格按单元格切句和页眉页脚识别（S3）、OCR（S5）、结构识别和分包识别、模型路由表和限流、PDF 阅读器、读标的修改类接口、查标全部。

docs/architecture/openapi.yaml

@@ -2524,6 +2524,12 @@ components:
         - type: object
           required: [categories, title]
           properties:
+            categories:
+              type: array
+              minItems: 1
+              uniqueItems: true
+              items: { $ref: '#/components/schemas/Category' }
+            title: { type: string, minLength: 1, maxLength: 200 }
             citation_ids:
               type: array
               items: { $ref: '#/components/schemas/Id' }
@@ -2535,6 +2541,13 @@ components:
         - type: object
           required: [id, categories, title, importance, origin, zone, citations, edited_fields, updated_at]
           properties:
+            categories:
+              type: array
+              minItems: 1
+              uniqueItems: true
+              items: { $ref: '#/components/schemas/Category' }
+            title: { type: string, minLength: 1, maxLength: 200 }
+            importance: { $ref: '#/components/schemas/Importance' }
             id: { $ref: '#/components/schemas/Id' }
             summary:
               type: [string, 'null']