docs: 更新文档

docs/project/HANDOFF.md

@@ -281,7 +281,7 @@ M3.5 与 M3.6 均已收口。真实来源回归中若要提升 Ozon 自动类目
 - 编辑器选择类目后立即加载属性 schema。`is_required=true` 的商品级属性始终展示在「产品属性」，`is_aspect=true` 的必填属性始终展示在对应 SKU 卡片；必填状态仅使用 Label 前的红色 `*`，选填属性仍可折叠。
 - 动态属性控件已拆为独立组件，统一处理字典、布尔、数值、文本和多值字段；商品级与 SKU 级属性只负责各自的分区编排。主要信息继续保留类目、标题、型号、品牌和默认包装规格，SKU 展开区可覆盖包装及商品规格。
 - 草稿保存不会因 Ozon 必填属性或包装规格为空而失败；已提交的非空属性仍由 API 校验类型、数量、字典归属、类目归属及 `is_aspect` 对应的商品/SKU scope。
-- 新增 `GET /api/product-platform-profiles/{profile_id}/validation`，在独立校验模块中返回商品级问题和逐 SKU 问题。已导入 SKU 标为 `not_publishable_again`；必填通用属性和必填变体属性都以当前门店类目 schema 为准。
+- 新增 `GET /api/product-platform-profiles/{profile_id}/validation`，在独立校验模块中返回商品级问题和逐 SKU 问题。已导入 SKU 标为 `not_publishable_again`；该阶段的必填通用属性和必填变体属性当时以门店类目 schema 为准，现已由 1.36 的第 3 步迁移为平台 schema。
 - 类目 schema 新增 `editor_field` 语义绑定，严格按 Ozon 属性 ID 识别品牌 `85`、型号名称 `9048`、类型 `8229`、主题标签 `23171`、JSON 富内容 `11254` 和简介/产品描述 `4191`。这些字段由编辑器已有控件承载，动态属性区不再重复展示或预取字典；名称和翻译文本不参与判断。
 - Contracts、API 与 Web TypeScript 检查、Web production build 和 `git diff --check` 已通过。API 集成测试已补充通用/逐 SKU 必填缺失和 scope 伪造场景；本轮环境无法连接 PostgreSQL/Redis，因此未实际跑通该集成测试，且未按约定启动 API 或 Worker。
 
@@ -293,7 +293,7 @@ M3.5 与 M3.6 均已收口。真实来源回归中若要提升 Ozon 自动类目
 
 - 类目/商品类型树、类型属性定义和字典候选值归属 `platform_id`，同一平台的全部门店共用，不再按门店复制。Ozon 与未来 Wildberries 等平台分别使用自己的适配器和外部 ID 语义；本阶段**不创建、不读取门店差异层**。
 - 门店连接、卖家凭据、商品/SKU 已填属性、发布状态和错误仍是工作空间业务数据。平台参考目录不保存客户商品、价格、库存或发布事实。
-- 商品编辑器已由迁移 `027` 和新版 API 切到平台级类目 UUID、属性和字典缓存。`022_store_catalog_cache.sql` 的门店表与列暂时保留为兼容/回滚数据，不得在发布链路迁移完成前删除。
+- 商品编辑器和首次发布预检已由迁移 `027` 与新版 API 切到平台级类目 UUID、属性和字典缓存。`022_store_catalog_cache.sql` 的门店表与列暂时保留为兼容/回滚数据；真正的 Ozon 发布 job 复用预检服务并完成稳定性验证前不得删除。
 
 #### 1.33.2 类目树、属性和字典的标识规则
 
@@ -357,7 +357,7 @@ BullMQ Worker（最多 5 次，5 秒起指数退避）
 
 1. 调整定时调度公平性：树之后不能等待全部类型属性完成才开始字典；应在属性和字典之间设置配额/轮转，并优先近期使用或管理员选中的类型。
 2. 为超过 10000 项的大字典实现可续传游标或分片同步周期。当前任务会正确标记 `is_complete=false`，但下一次仍从头读取，不能持续推进到第 10001 项以后。
-3. ~~将商品编辑器由门店级缓存迁移到平台级目录。~~ 已由第 3 步完成；后续只在发布迁移和稳定性验证后讨论清理 `022` 表。
+3. ~~将商品编辑器由门店级缓存迁移到平台级目录。~~ 已由第 3 步完成，发布预检也已迁移；后续只在真正的 Ozon 发布 job 复用预检并完成稳定性验证后讨论清理 `022` 表。
 4. 增加平台目录 PostgreSQL 集成测试，覆盖系统管理员隔离、凭据版本替换、手动幂等复用、定时去重、失败保留旧缓存、完整字典停用旧值及跨平台 ID 拒绝。
 5. 在浏览器完成管理员菜单、直达路由、凭据弹窗、任务轮询、类目/属性/字典展示的回归，并确认 API/Worker 进程都使用迁移后的当前代码。
 
@@ -418,6 +418,14 @@ BullMQ Worker（最多 5 次，5 秒起指数退避）
 - 最终本地校验除标题、型号、品牌、必填属性、offer ID、价格、包装和图片外，新增“所用字典缓存未过期且候选 ID 仍为活动值”检查。stale 字典可以完成本次发布校验并在后台刷新；expired/missing 会返回刷新中问题。
 - 预检响应包含 schema 与每个已用字典的统一 cache 元数据，以及本次创建/复用的目录 runs。真正的 `product_publish_job`、发布快照、Ozon `/v3/product/import` 调用和轮询仍未实现；预检 ready 不能解释为已提交或已发布。
 - 代码按目录编排、最终校验、HTTP 入口拆分在独立组件中，没有把逻辑继续堆入 `product-editor.service.ts`。API 集成测试覆盖 stale 的 low publish 任务、expired 的 high 提升、只刷新已用字典和不触达未用字典。
+- 当前边界：预检只校验 profile 引用的平台类目仍存在且活动，并刷新该类型 schema/实际使用字典；尚未检查整棵类目树的缓存新鲜度，也不会因树过期创建树任务。本地类目无效时返回 Atlas 自己的 `422 CATEGORY_INVALID`，不是 Ozon 响应。真正发布 job 接入前需补齐或确认此边界。
+
+### 1.38 文档同步与当前交接结论（2026-09-20）
+
+- 已把平台级目录、第 1～4 步刷新方案、发布预检、缓存设置弹窗和最近任务刷新反馈同步到交接、架构、商品编辑、管理 API 与 Ozon 集成文档。
+- 当前事实统一为：类目树每 7 天自动同步且支持管理员手动同步；类型属性和字典不做周期性全量扫描；普通访问和发布预检按 fresh/stale/expired/missing 创建或复用 high/low Worker 任务；同平台所有门店共享一份参考目录。
+- 管理页面的缓存新鲜度设置由按钮打开弹窗；最近任务手动刷新有 loading 及成功/失败 message，5 秒自动轮询静默执行。
+- 旧门店目录章节保留为带日期的历史实现记录，不代表当前读写路径。当前未完成重点是真正的 Ozon 发布 job、树级发布新鲜度边界、大字典续传以及平台目录 PostgreSQL 集成测试。
 
 ## 2. 已确认产品决策