feat(ai-edit): 开发 AI 填报功能

docs/project/HANDOFF.md

@@ -1,24 +1,24 @@
 # Atlas Seller Kit 交接说明
 
-> 更新：2026-09-10。此文是新 AI 对话、架构讨论与开发工作的首读入口。开始开发前，必须先阅读并遵守 [`development-collaboration-contract.md`](./development-collaboration-contract.md)。
+> 更新：2026-09-23。此文是新 AI 对话、架构讨论与开发工作的首读入口。开始开发前，必须先阅读并遵守 [`development-collaboration-contract.md`](./development-collaboration-contract.md) 和仓库 `AGENTS.md`。下方按日期记录的旧方案仅供追溯；当前状态以本节及 [1.39](#139-开发进度与交接2026-09-23商品-ai-填报与编辑页收口) 为准。
 
 ## 1. 项目定位
 
 这是一个全新的云端产品，不是 `ozon-seller-kit` 的本地版重构。目标用户可拥有多个门店，每个门店只能绑定一个平台；平台自身可支持多个市场、国家、语言和币种。因此语言、币种、类目和发布规则不能写死为 Ozon 或中文/俄文。
 
-当前已完成 pnpm monorepo 初始化：包含 Web、NestJS API、BullMQ Worker、WXT 浏览器扩展、共享 API 契约、数据库包、本地基础设施 Compose 与依赖锁文件。API 已实现健康/readiness、集中配置与安全基础、认证、个人工作空间上下文、平台目录/上下文、门店、水印/素材、采集箱与扩展采集入库；Worker 已具备 Ozon 凭据验证、采集记录清理和按需来源素材转存消费链路，仓库同步尚未接入。Web 已具备完整前端框架（布局、路由、主题）、登录/注册页、页头平台选择器、店铺管理、水印管理、真实采集箱页面和采集数据测试页；浏览器扩展已提供毛子 ERP 风格的网页登录态同步、悬浮窗及 Ozon/1688/淘宝/天猫首版页面状态解析。不要从旧项目复制 SQLite 模型、无鉴权 API、旧 `/trial/:id` 或商品编辑页组件。可选择性复用已经验证过的纯计价公式、采集扩展思路和 AI 任务经验，但必须先适配多租户和云端边界。
+pnpm monorepo 包含 Web、NestJS API、BullMQ Worker、WXT 浏览器扩展、共享契约、数据库包和本地基础设施。认证、工作空间隔离、门店/素材、采集箱、商品编辑草稿、平台级商品参考目录、发布预检和商品 AI 填报已有实现；真正的 Ozon 首次发布、在线商品同步和定价确认仍未形成完整闭环。不要从旧项目复制 SQLite 模型、无鉴权 API、旧 `/trial/:id` 或商品编辑页组件；复用纯规则前须适配多租户和云端边界。
 
 当前运行时基线：Node 24.20.0、pnpm 11.25.0、PostgreSQL 18.6、Redis 7.4.11、MinIO `RELEASE.2025-09-07T16-13-09Z`；Web 默认端口为 `8100`，API 默认端口为 `8200`，扩展 dev server 默认端口为 `8110`（仅本地开发用），Worker 无 HTTP 端口。完整目录、依赖边界与版本表见 [`architecture/project-structure.md`](../architecture/project-structure.md) 和 [`architecture/technology-and-deployment.md`](../architecture/technology-and-deployment.md)。
 
 ## 0. 交接结论（先看这里）
 
-当前已经完成的是“采集 → 采集箱 → 商品编辑草稿”的主要数据闭环，以及 M3.0–M3.4 商品领域基础、编辑器核心、AI 来源素材字段级合并、动态属性和缓存同步基础。数据库迁移、工作空间隔离、同商品归属外键、幂等键和 product/profile 双乐观锁已经落地。
+已完成“采集 → 采集箱 → 商品编辑草稿”的主要数据闭环、平台级类目/属性/字典目录与发布预检。编辑页已接入异步「AI 填报」：基于来源资料与 Atlas 类目树生成类目建议、型号/SKU 货号、证据充分的包装建议及 SPU 中俄文案；单 SKU 文案由用户单独生成并确认应用。AI 结果只回填未保存表单，保存草稿仍是持久化边界。Ozon 动态类目属性可按已选类目加载并手工填写，**当前不由 AI 自动填报**。
 
-当前没有完成的是“可直接用于发布”的闭环：候选素材已经可以选择、转存并保存为 SKU 的平台素材，但定价确认、AI 任务与候选结果、Ozon 首次发布、在线商品同步仍未开发。真实站点回归也尚未由本项目完成；用户已确认此前提出的首次回归项基本满足采集箱和商品编辑需求，但仍建议在最终发布前保留一轮样本验收。
+尚未完成可直接发布的闭环：定价确认、真正的 Ozon 发布 job/import 及结果轮询、在线商品同步仍待开发。AI 类目推荐和文案已能运行，但不能等同于跨来源样本验收；尤其应继续用 1688/淘宝/天猫样本核验 Atlas 类目候选质量，以及俄文文案、包装证据和 SKU 继承行为。AI 生图仍是占位入口。
 
-当前最高优先级是以真实来源样本回归素材转存与选择，然后进入定价确认能力。类目树改造已落地：Worker 使用显式指定的 Ozon 缓存源预热共享树，编辑器直接读取 Cascader 树，并会在空类目时按 Ozon 来源层级回填；详见 [1.28](#128-开发进度2026-09-10类目树预热与来源回填)。
+当前优先事项：用真实来源样本回归 AI 类目推荐、文案与候选素材；完成定价确认；让首次发布 job 复用既有发布预检，再实现 Ozon import 与结果轮询。平台参考目录目前由平台级参考源和同步任务维护，不能把 9 月 10 日的门店级缓存描述当作现行架构。
 
-接手前请先阅读 `git status --short`；当前 M3 商品编辑和 M3.4/M3.5 缓存改动均已提交。不要用 `git reset --hard` 或批量清理未跟踪文件。共享 contracts 类型需先构建，再执行 Web/API/Worker 检查。
+接手前请先阅读 `git status --short`；截至本次更新，AI 填报涉及 API、Worker、Web、contracts、迁移和文档的改动仍在工作区，其中若干文件未跟踪，不能当作已提交。不要用 `git reset --hard` 或批量清理未跟踪文件。共享 contracts 类型需先构建，再执行 Web/API/Worker 检查。开发验证需要时可按 `AGENTS.md` 先确认进程与端口，再启动或重启 API/Worker；下方旧章节中的“不可重启”说法已失效。
 
 ### 1.1 开发进度（2026-09-02）
 
@@ -427,6 +427,25 @@ BullMQ Worker（最多 5 次，5 秒起指数退避）
 - 管理页面的缓存新鲜度设置由按钮打开弹窗；最近任务手动刷新有 loading 及成功/失败 message，5 秒自动轮询静默执行。
 - 旧门店目录章节保留为带日期的历史实现记录，不代表当前读写路径。当前未完成重点是真正的 Ozon 发布 job、树级发布新鲜度边界、大字典续传以及平台目录 PostgreSQL 集成测试。
 
+### 1.39 开发进度与交接（2026-09-23）：商品 AI 填报与编辑页收口
+
+**已实现的链路**
+
+- `029_product_ai_autofill.sql` 定义 AI 任务、中俄对照与 SKU 可空发布标题；API 提供全局填报、单 SKU 文案任务和任务状态读取。API 在工作空间事务内固化输入快照、写任务与 Outbox；Worker 从 `DEEPSEEK_API_KEY`、`DEEPSEEK_MODEL_NAME` 读取配置调用 DeepSeek。任务不直接写商品草稿，页面在完成后核对商品、profile 和来源快照版本，再把合格结果填入未保存表单。API、Worker、Web 与共享类型均有对应代码；迁移是否已应用到当前目标数据库，本次文档更新未核验。
+- 全局填报读取 Atlas 平台级活动类目树，按层向模型提供有限候选；对大分支分段初选、再决选，只接受给定选项。明确结果可回填类目，有多个命中则在「确认 AI 推荐类目」弹窗中由用户选择。已有类目不被覆盖；未确认类目时不能生成依赖它的型号和货号。型号是 SPU 共用稳定码，未导入 SKU 的货号分别生成并检查长度、连接符及冲突。
+- 全局文案只生成 SPU 的俄文标题、主题标签、产品描述及逐项中文对照；描述要求概述与「Характеристики:」分段、项目符号。SKU 默认继承 SPU 三项文案；用户可打开当前 SKU 的 AI 弹窗，预览后明确点击应用，才写入该 SKU 的未保存表单。SPU/SKU 都有中俄对照查看入口，俄文被手工修改后旧中文对照标为待更新。
+- 包装重量和尺寸仅在来源有可逐字核对的证据时建议；缺证据则留空。原计划的「AI 填写 Ozon 类目属性」已撤回：当前只在类目确定后按 schema 动态加载商品/SKU 属性，用户自行填写。`030_product_ai_attribute_fill.sql` 与历史 `attribute_fill` 类型保留兼容，不代表当前仍会创建或执行该任务。
+- 编辑页已把「内部商品名」文案改为「中文商品名」，「俄文发布标题」在表单与发布就绪校验中必填；SPU 标题有加号入口开启 SKU 标题覆盖。SKU 的 Ozon 变体字段已并入「SKU 信息」，不另设「Ozon 变体属性」标题。底部 `editor-footer` 固定在视口底部；AI 类目候选弹窗已调整为说明、单选候选和明确确认操作。类目输入框清除时的空值处理已修正。
+- 最新俄文文案规则同时作用于 SPU 与 SKU Prompt：`title.ru`、`tags[].ru`、`description.ru` 不得出现汉字；来源中文事实应翻译为自然俄文，只有有依据的拉丁品牌/型号及阿拉伯数字可保留。Worker 结果校验会丢弃仍含汉字的对应字段，中文对照与包装原文证据不受此限制。旧已保存文案不会自动改写，需重新生成或手工修订。
+
+**验证状态与下一步**
+
+- 最近一轮俄文禁汉字改动已通过 Worker `product-ai.test.mjs` 7 项测试、Worker TypeScript 检查和 `git diff --check`；本次交接文档更新未再发起真实 DeepSeek 请求。其他页面/API 变更有此前的构建及集成测试记录，但不能视为本次对整个脏工作区的重新验收。
+- 下一步先核对目标环境的 `029`/`030` 迁移与 API/Worker 当前进程版本，再使用 Ozon、1688、淘宝、天猫各类样本回归：类目候选准确性与确认、中文来源到纯俄文输出、无包装证据、多个 SKU 的共用型号与独立货号、SPU/SKU 文案继承和保存后中文对照。重点复查此前 1688 类目不足提示与 DeepSeek 失败场景；不能仅以单元测试认定质量已稳定。
+- 之后继续定价确认、素材按需物化回归、平台目录大字典续传与管理员回归，并将真正的首次发布 job 接到现有发布预检。发布预检 `ready` 不是已上架；在线商品同步也尚未实现。
+
+详细字段规则与任务接口见 [`ai-autofill-plan.md`](../product/ai-autofill-plan.md) 和 [`product-editor-and-publishing.md`](../api/product-editor-and-publishing.md)。
+
 ## 2. 已确认产品决策
 
 | 主题 | 决策 |
@@ -435,7 +454,7 @@ BullMQ Worker（最多 5 次，5 秒起指数退避）
 | 平台可售单元 | 一个 SKU 对应一个独立平台 offer；Ozon 首个平台中对应 `/v3/product/import.items[]` 的一项和独立 `offer_id`。 |
 | 通用属性 | 标题、品牌、型号、主题标签、简介、条形码、采买地址、货源备注及未来商品级属性；类目和平台属性属于独立的平台发布配置。首期不做富内容。 |
 | SKU 属性 | SKU 名称、图片、货号、采购价、售价、划线价、包装重量和尺寸、商品重量和尺寸、商品颜色、颜色名称等。首期不支持视频。 |
-| 型号/货号 | 型号（`model`）是父商品通用字段；`offer_id` 是当前平台下的每个 SKU 字段。采集时两者可为空；首次上架前必须由用户填写，系统不从标题、规格或来源 SKU 自动生成。被成功导入的 `offer_id` 作为历史事实锁定。 |
+| 型号/货号 | 型号（`model`）是父商品通用字段；`offer_id` 是当前平台下的每个 SKU 字段。采集入箱时两者可为空；编辑页可手填，也可在用户主动点击“AI 填报”后生成并填入表单，保存和发布时仍校验唯一性。被成功导入的 `offer_id` 作为历史事实锁定。详见[AI 填报方案](../product/ai-autofill-plan.md)。 |
 | 规格 | 实物规格与包装物流规格严格分离；尺寸图只读取实物规格，计价/物流/发布只读取包装规格。 |
 | 继承 | 可继承字段的 `null` 表示该字段没有覆盖父商品默认值，不表示 SKU 不存在、名称为空或商品为单规格。 |
 | 尺寸图 | 必须逐 SKU 生成，任务保存 SKU ID 和实物规格快照。 |
@@ -474,13 +493,13 @@ User → Workspace → Membership / Role
 
 ## 5. 已冻结的第一阶段 API 契约
 
-第一阶段 HTTP API 的接口范围已讨论完成，当前状态为**设计冻结、部分业务接口已实现**。认证、平台目录/上下文、创建/查询/编辑/默认/删除门店、异步操作读取及仓库摘要读取已有实现与集成测试；门店凭据验证、仓库同步的实际平台调用仍待 Worker 消费 Outbox 后完成。后续编码以 [`docs/api/`](../api/README.md) 为唯一 HTTP 契约来源；旧 [`product/api.md`](../product/api.md) 仅作历史背景，不能作为实现依据。
+第一阶段 HTTP API 的接口范围已讨论完成，当前状态为**设计冻结、分模块实施**。认证、门店、采集、商品编辑、平台参考目录、发布预检与 AI 任务已有接口和实现；定价、真正的商品发布及在线商品同步仍未形成完整接口/Worker 闭环。后续编码以 [`docs/api/`](../api/README.md) 为唯一 HTTP 契约来源；旧 [`product/api.md`](../product/api.md) 仅作历史背景，不能作为实现依据。
 
 - 覆盖账户认证、平台/门店、水印与素材、定价、浏览器采集/采集箱、商品编辑/首次发布、在线商品读取与同步。
 - 所有接口遵循统一鉴权、工作空间隔离、页头平台上下文、金额字符串、错误格式、`Idempotency-Key`、`If-Match` 和异步 `operation` 约定。
 - **响应信封是强制契约：** 成功单资源或同步动作返回 `{ "data": T }`，列表返回 `{ "data": T[], "meta": PaginationMeta }`，失败返回 `{ "error": ApiError }`，`204 No Content` 不返回响应体。项目不采用完整 JSON:API；任何调用方不得自行增加嵌套 `data` 或以 `data: null` 表示错误。完整规则见 [`api/conventions.md`](../api/conventions.md)。
 - 关键异步动作必须在同一事务写入业务记录、`operations`（如需用户可见进度）和 `outbox_events`；Dispatcher 至少一次投递 BullMQ，Worker 必须幂等。
-- DDL 已通过本地隔离 PostgreSQL 执行验证；迁移执行器、认证/工作空间基础、幂等与 Outbox 写入闭环、Outbox Dispatcher、Ozon 凭据验证 Worker、上传意图清理 Worker、采集记录清理 Worker 与来源素材转存 Worker 均已实现。仓库同步、发布和在线商品同步 Worker 仍待实现。
+- 早期 DDL 已通过本地隔离 PostgreSQL 验证；迁移执行器、认证/工作空间基础、幂等与 Outbox 写入闭环、Outbox Dispatcher、Ozon 凭据验证、采集清理、来源素材转存及商品 AI Worker 已有实现。新近 `029`/`030` 迁移在目标环境中的应用状态需单独核对；商品发布和在线商品同步 Worker 仍待实现。
 
 仍需在对应模块开始编码前完成的 P1/P2 决策和数据模型补丁，集中记录在 [`reviews/implementation-readiness-open-items.md`](../reviews/implementation-readiness-open-items.md)。
 
@@ -490,11 +509,11 @@ User → Workspace → Membership / Role
 
 > 注意：下面的清单不能覆盖 2026-09-18 的 [Ozon 参考目录决策](../architecture/platform-product-reference-catalog.md)。平台目录、后台、同步基础链路和商品编辑器迁移已经实现；旧门店目录只作为兼容/回滚数据保留。
 
-当前执行顺序：
+当前执行顺序（2026-09-23）：
 
-1. 将真正的 `publish-jobs` 创建事务接入已经完成的发布预检服务，固化发布快照后再实现 Ozon `/v3/product/import` 与结果轮询；不得重新实现另一套目录判断。
-2. 完成平台目录首次预热并修正大字典续传；补系统管理员浏览器回归。旧门店目录继续保留，暂不清理。
-3. 在真实采集来源中继续回归候选媒体按需物化，然后完成定价、AI 任务、首次发布和在线商品同步的剩余纵向闭环。
+1. 核对 AI 任务迁移、运行进程版本和四类来源的真实样本；回归类目选择、中俄文案（俄文字段不含汉字）、包装证据、SKU 文案继承及候选媒体按需物化。
+2. 完成定价确认、平台目录大字典续传与管理员浏览器回归；旧门店目录继续保留，暂不清理。
+3. 将真正的 `publish-jobs` 创建事务接入已完成的发布预检，固化发布快照后实现 Ozon `/v3/product/import` 与结果轮询，再推进在线商品同步；不得重新实现另一套目录判断。
 
 ### 历史计划（仅供追溯）