docs: 更新文档

docs/integrations/ozon-seller-api/02-category-tree.md

@@ -172,6 +172,8 @@ async def fetch_category_tree(
 
 ### TypeScript（前端选择器）
 
+> 以下嵌套 `CategoryNode` 和 `/api/categories/tree` 是早期资料中的概念示例，不是当前 Atlas 联调契约。当前商品编辑器从 `GET /api/product-platform-profiles/{profile_id}/category-options` 读取带 `parent_id` 的平台级扁平节点，再在前端重建树；请以[商品编辑与发布 API](../../api/product-editor-and-publishing.md)为准。
+
 ```typescript
 interface CategoryNode {
   description_category_id: number;
@@ -213,7 +215,7 @@ function toTreeData(nodes: CategoryNode[]): any[] {
 
 ## 缓存策略
 
-目标方案见 [`platform-product-reference-catalog.md`](../../architecture/platform-product-reference-catalog.md)：每个平台分别维护共享目录；定时自动同步与系统管理员手动触发共用异步任务、原子版本切换和失败保留旧版；前端只读 Atlas 缓存。当前运行中的门店级同步仍见下方「Atlas 当前集成」，不能把目标方案当作已经上线。
+Atlas 已按 [`platform-product-reference-catalog.md`](../../architecture/platform-product-reference-catalog.md) 为每个平台分别维护共享目录：定时自动同步与系统管理员手动触发共用异步任务，失败保留上次成功版本；商品编辑器只读 Atlas 平台缓存。同平台的门店不再各自复制类目树，本阶段也不维护门店差异层。
 
 ---
 
@@ -225,11 +227,11 @@ function toTreeData(nodes: CategoryNode[]): any[] {
 
 ### Q2: 多久更新一次？
 
-**A**: Ozon 接口未规定 Atlas 的缓存 TTL。目标架构建议由后台每日检查树，并提供管理员手动排队同步入口；间隔可按运行量调整，见[架构决策](../../architecture/platform-product-reference-catalog.md)。
+**A**: Ozon 接口未规定 Atlas 的缓存 TTL。Atlas 固定在最近一次成功后 7 天自动同步完整树，并提供系统管理员手动排队同步入口；失败不会更新成功时间或清空旧树。
 
 ### Q3: 不同语言的类目树结构一样吗？
 
-**A**: 接口支持语言参数，不应未经验证就假定各语言的 ID 和翻译映射完全相同。当前 Worker 为每个门店缓存 `ZH_HANS`；目标是由 Ozon 平台参考源统一缓存该语言，同平台所有门店共用。前端不能携带门店密钥直连 Ozon。
+**A**: 接口支持语言参数，不应未经验证就假定各语言的 ID 和翻译映射完全相同。当前 Worker 使用 Ozon 平台参考源统一缓存 `ZH_HANS`，同平台所有门店共用。前端不能携带平台或门店密钥直连 Ozon。
 
 ### Q4: `type_id=0` 是什么意思？
 
@@ -239,16 +241,18 @@ function toTreeData(nodes: CategoryNode[]): any[] {
 
 ## Atlas 当前集成
 
-- **Worker**：以门店凭证调用 Ozon，递归持久化完整 `children` 树及父子关系；缓存命中时不重复调用 Ozon。
-- **API**：按当前目标门店返回缓存的扁平节点（包含 `parent_id`）；不会将 `Client-Id` 或 `Api-Key` 返回给浏览器。
+- **Worker**：使用系统后台配置的平台参考源凭据调用 Ozon，递归持久化完整 `children` 树及父子关系；同一平台活动任务按作用域合并。
+- **API**：按当前平台返回缓存的扁平节点（包含 `parent_id`）；不会将 `Client-Id` 或 `Api-Key` 返回给浏览器。
 - **前端**：根据 `parent_id` 重建任意深度的 Cascader；目录可展开，只有可发布的叶子能写入商品草稿。
 - **调试**：若需要查看 Ozon 原始响应，应由受权限保护的服务端调试能力获取并脱敏展示；浏览器不得直接用门店密钥请求 Ozon。
-- **迁移目标**：平台级共享目录和统一异步管理同步尚未实现；本阶段不维护门店差异层，见[架构决策](../../architecture/platform-product-reference-catalog.md)。
+- **同步维护**：完整树每 7 天自动同步，也可由系统管理员手动触发；树任务不自动展开为所有类型属性或字典任务。
+- **发布边界**：当前发布预检校验所选本地类目仍活动，但尚未对树级新鲜度创建刷新任务；该边界需在真正发布 job 接入前确认或补齐。
 
 ---
 
 ## 相关文档
 
 - [03-category-attributes.md](./03-category-attributes.md) —— 获取类目属性
-- [docs/v2/database.md](../v2/database.md) §2.7 —— `category_tree` 表结构
-- [docs/v2/ozon-publish.md](../v2/ozon-publish.md) §3 —— 类目字典缓存策略
+- [平台商品参考目录](../../architecture/platform-product-reference-catalog.md) —— 平台级数据归属
+- [平台目录缓存刷新方案](../../architecture/platform-catalog-cache-refresh-plan.md) —— 每周树同步和属性/字典按需刷新
+- [商品编辑与发布 API](../../api/product-editor-and-publishing.md) —— 编辑器类目读取和发布预检

docs/integrations/ozon-seller-api/03-category-attributes.md

@@ -431,9 +431,11 @@ if missing:
 
 ## 7. 缓存策略
 
-Ozon 只定义查询参数和分页规则，不规定 Atlas 的 TTL。2026-09-18 的[架构决策](../../architecture/platform-product-reference-catalog.md)将属性定义和字典候选值设为平台级参考数据：同一平台所有门店共用，本阶段不维护门店差异层；此方案尚未实现。当前代码仍以门店、类目和类型为作用域按需同步，用户从 Atlas 本地缓存读取。
+Ozon 只定义查询参数和分页规则，不规定 Atlas 的 TTL。Atlas 已按 2026-09-18 的[架构决策](../../architecture/platform-product-reference-catalog.md)将属性定义和字典候选值迁移为平台级参考数据：同一平台所有门店共用，本阶段不维护门店差异层。商品编辑器、草稿校验和发布预检都从 Atlas 平台缓存读取，Ozon 请求统一由 Worker 使用平台参考源凭据执行。
 
-目标同步方式：对活跃 `description_category_id + type_id` 的属性定义定期后台复核；字典候选值至少以类目、类型、属性、字典 ID 和语言限定作用域。`category_dependent=false` 可以作为进一步去重的依据，但在跨账号/跨类目验证前不能只以 `dictionary_id` 合并。小字典可完整分页并标记 `complete`；大字典先保存常用页与搜索命中，并明确标记 `partial`。搜索结果不是全集，不能据此清理未命中的旧值。定时和管理员手动同步必须共用异步任务链路，成功后原子切换版本，失败保留上次成功值。
+类型属性和字典默认 14 天内 fresh，14～21 天（含 21 天）stale 时旧缓存可用并低优先级刷新，严格超过 21 天或从未同步时必须高优先级刷新成功后才能作为当前 schema、候选值或发布依据。系统不周期性扫描属性和字典；刷新由管理员批次/单字典操作、普通用户访问或发布预检触发。
+
+字典候选值至少以平台、类目类型、Atlas 属性 UUID、外部值 ID 和语言限定作用域。`category_dependent=false` 可以作为进一步去重的依据，但在跨账号/跨类目验证前不能只以 `dictionary_id` 合并。小字典可完整分页并标记 `complete`；大字典保存已同步页与搜索命中并明确标记 `partial`。搜索结果不是全集，不能据此清理未命中的旧值；partial 字典的规范化关键词有独立缓存状态。成功后原子更新缓存，失败保留上次成功值。
 
 ---
 
@@ -510,106 +512,13 @@ Ozon 只定义查询参数和分页规则，不规定 Atlas 的 TTL。2026-09-18
 
 ---
 
-## 10. V2 项目集成
+## 10. Atlas 当前集成
 
-### API 层（已实现）
-
-```python
-# server/api/categories.py
-
-@router.get("/categories/{category_id}/attributes")
-async def get_attributes(
-    category_id: int,
-    type_id: int = Query(...),
-    shop_id: str = Query(...),
-    db: AsyncSession = Depends(get_db)
-):
-    shop = await get_shop(db, shop_id)
-    attrs = await ozon_client.get_category_attributes(
-        shop.client_id_dec,
-        shop.api_key_dec,
-        category_id,
-        type_id
-    )
-    return {"result": attrs}
-
-@router.get("/categories/attribute/{attribute_id}/values")
-async def get_attribute_values(
-    attribute_id: int,
-    category_id: int = Query(...),
-    type_id: int = Query(...),
-    q: str = Query(None),  # 搜索关键词
-    shop_id: str = Query(...),
-    db: AsyncSession = Depends(get_db)
-):
-    shop = await get_shop(db, shop_id)
-    
-    if q and len(q) >= 2:
-        # 搜索接口
-        values = await ozon_client.search_attribute_values(
-            shop.client_id_dec, shop.api_key_dec,
-            attribute_id, category_id, type_id, q
-        )
-    else:
-        # 全量拉取（分页）
-        values = await ozon_client.get_attribute_values(
-            shop.client_id_dec, shop.api_key_dec,
-            attribute_id, category_id, type_id
-        )
-    
-    return {"result": values}
-```
-
-### 前端（待实现）
-
-```tsx
-// studio/src/pages/product/components/AttributeMapper.tsx
-
-import { Form, Select, Input, Tag } from 'antd';
-
-export function AttributeMapper({ categoryId, typeId, rawParams, onChange }) {
-  const [attributes, setAttributes] = useState([]);
-  
-  useEffect(() => {
-    fetch(`/api/categories/${categoryId}/attributes?type_id=${typeId}`)
-      .then(r => r.json())
-      .then(data => setAttributes(data.result));
-  }, [categoryId, typeId]);
-  
-  // 自动匹配
-  const autoMatch = () => {
-    const matched = rawParams.map(p => {
-      const attr = attributes.find(a => 
-        normalize(a.name) === normalize(p.key)
-      );
-      return attr ? { ...p, attrId: attr.id, attr } : p;
-    });
-    return matched;
-  };
-  
-  return (
-    <div>
-      {autoMatch().map((item, i) => (
-        <Form.Item
-          key={i}
-          label={item.key}
-          required={item.attr?.is_required}
-        >
-          {item.attr?.dictionary_id > 0 ? (
-            <Select
-              showSearch
-              placeholder="选择字典值"
-              onSearch={(q) => fetchValues(item.attr.id, q)}
-            />
-          ) : (
-            <Input defaultValue={item.value} />
-          )}
-        </Form.Item>
-      ))}
-    </div>
-  );
-}
-```
+- 商品编辑器通过 `GET /api/product-platform-profiles/{profile_id}/attribute-schema` 读取当前平台类型属性，响应包含 Atlas `attribute_id` 和统一 `cache` 元数据。
+- 字典通过 `GET /api/product-platform-profiles/{profile_id}/attribute-dictionaries/{attribute_id}` 读取；`attribute_id` 是平台属性 UUID，不以门店或单独 `dictionary_id` 定位。
+- fresh/stale 立即返回；expired/missing 创建或复用高优先级任务并最多等待 5 秒，仍未完成时返回 `202`。浏览器不会拿到平台凭据或未落库的 Ozon 临时结果。
+- 发布前使用 `POST /api/product-platform-profiles/{profile_id}/publish-preflights`，只刷新当前类型 schema 和所选 SKU 实际使用的字典，再执行必填、scope、字典有效性及其他首次上架校验。
+- 管理后台支持三种类型属性批次、单字典同步、缓存策略弹窗和最近任务观察；类目树固定每 7 天同步，属性与字典不做周期性全量扫描。
 
 ---
 
@@ -617,5 +526,5 @@ export function AttributeMapper({ categoryId, typeId, rawParams, onChange }) {
 
 - [02-category-tree.md](./02-category-tree.md) —— 获取类目树
 - [04-product-import.md](./04-product-import.md) —— 发布商品（使用属性）
-- [docs/v2/database.md](../v2/database.md) §2.7 —— 属性缓存表结构
-- [docs/v2/ozon-publish.md](../v2/ozon-publish.md) §3 —— 属性映射策略
+- [平台目录缓存刷新方案](../../architecture/platform-catalog-cache-refresh-plan.md) —— 属性和字典缓存状态机
+- [商品编辑与发布 API](../../api/product-editor-and-publishing.md) —— 当前 Atlas 端点与发布预检

docs/integrations/ozon-seller-api/04-product-import.md

@@ -479,9 +479,11 @@ POST /v3/product/info/list
 
 ---
 
-## 10. V2 项目集成
+## 10. 早期集成示例（当前未实现）
 
-### API 层（已实现）
+> 下方 `server/api/publish.py` 与前端组件来自早期 V2 方案，不存在于当前 NestJS/React 实现中，仅可帮助理解流程，不能作为联调契约。Atlas 目前只完成 `publish-preflights`；真正的发布 job、`/v3/product/import` 提交和结果轮询尚未实现。当前契约见[商品编辑与发布 API](../../api/product-editor-and-publishing.md)。
+
+### 历史 API 示例
 
 ```python
 # server/api/publish.py
@@ -613,4 +615,5 @@ export function PublishPanel({ productId }) {
 - [03-category-attributes.md](./03-category-attributes.md) —— 获取属性
 - [05-product-info.md](./05-product-info.md) —— 查询商品详情
 - [09-stocks.md](./09-stocks.md) —— 设置库存（必须）
-- [docs/v2/ozon-publish.md](../v2/ozon-publish.md) —— 发布集成方案
+- [商品编辑与发布 API](../../api/product-editor-and-publishing.md) —— 当前 Atlas 预检与未来发布契约
+- [平台目录缓存刷新方案](../../architecture/platform-catalog-cache-refresh-plan.md) —— 发布前属性/字典刷新边界

docs/integrations/ozon-seller-api/05-product-info.md

@@ -431,9 +431,11 @@ console.log('库存:', detail.stocks.present);
 
 ---
 
-## 9. V2 项目集成
+## 9. 早期集成示例（当前未实现）
 
-### API 层（待实现）
+> 下方 Python 示例来自早期 V2 方案，不是当前 NestJS 接口。商品详情与审核状态同步的实际实现进度以[项目交接](../../project/HANDOFF.md)和[在线商品 API](../../api/online-listings.md)为准。
+
+### 历史 API 示例
 
 ```python
 # server/api/products.py
@@ -554,4 +556,5 @@ get_product_info_cached.cache_clear()
 - [04-product-import.md](./04-product-import.md) —— 创建/更新商品
 - [06-product-list.md](./06-product-list.md) —— 商品列表分页
 - [09-stocks.md](./09-stocks.md) —— 库存管理
-- [docs/v2/ozon-publish.md](../v2/ozon-publish.md) —— 发布集成方案
+- [在线商品 API](../../api/online-listings.md) —— 当前 Atlas 在线商品契约
+- [项目交接](../../project/HANDOFF.md) —— 实施状态

docs/integrations/ozon-seller-api/06-product-list.md

@@ -323,9 +323,11 @@ async def sync_product_states():
 
 ---
 
-## 9. V2 项目集成
+## 9. 早期集成示例（当前未实现）
 
-### API 层（待实现）
+> 下方 Python 示例来自早期 V2 方案，不是当前 NestJS 接口。Ozon 仓库同步 Worker 尚未完成，当前契约与进度以[在线商品 API](../../api/online-listings.md)和[项目交接](../../project/HANDOFF.md)为准。
+
+### 历史 API 示例
 
 ```python
 # server/api/products.py
@@ -474,4 +476,5 @@ async def incremental_sync(last_sync_time: datetime):
 - [04-product-import.md](./04-product-import.md) —— 创建/更新商品
 - [05-product-info.md](./05-product-info.md) —— 查询商品详情
 - [09-stocks.md](./09-stocks.md) —— 库存管理
-- [docs/v2/database.md](../v2/database.md) —— products 表结构
+- [在线商品 API](../../api/online-listings.md) —— 当前 Atlas 在线商品契约
+- [商品域数据模型](../../architecture/product-domain-data-model.md) —— 采集箱与在线商品边界

docs/integrations/ozon-seller-api/09-stocks.md

@@ -425,9 +425,11 @@ async def sync_stocks_from_ozon():
 
 ---
 
-## 9. V2 项目集成
+## 9. 早期集成示例（当前未实现）
 
-### API 层（待实现）
+> 下方 Python 示例来自早期 V2 方案，不是当前 NestJS 接口。库存写入不属于当前平台目录与首次发布预检范围；实际状态以[项目交接](../../project/HANDOFF.md)和[在线商品 API](../../api/online-listings.md)为准。
+
+### 历史 API 示例
 
 ```python
 # server/api/products.py
@@ -595,5 +597,5 @@ async def update_large_batch(stocks: list):
 
 - [04-product-import.md](./04-product-import.md) —— 创建商品（发布前置）
 - [05-product-info.md](./05-product-info.md) —— 查询商品信息（含库存）
-- [10-prices.md](./10-prices.md) —— 价格更新
-- [docs/v2/ozon-publish.md](../v2/ozon-publish.md) §5 —— 发布链路（含库存设置）
+- [在线商品 API](../../api/online-listings.md) —— 当前 Atlas 在线商品契约
+- [项目交接](../../project/HANDOFF.md) —— 实施状态

docs/integrations/ozon-seller-api/README.md

@@ -1,6 +1,6 @@
 # Ozon Seller API 文档总览
 
-> 本目录整理 Ozon Seller API 的核心接口文档，供 ozon-seller-kit 项目集成使用。
+> 本目录整理 Ozon Seller API 的核心接口资料，并补充 Atlas 当前适配状态。Ozon 接口说明与 Atlas 实现状态必须区分：真正的 Ozon 商品导入 job 尚未实现。
 > 官方文档：https://docs.ozon.ru/api/seller/zh/
 
 ---
@@ -15,10 +15,9 @@
 | [04-product-import.md](./04-product-import.md) | 商品导入（创建/更新） |
 | [05-product-info.md](./05-product-info.md) | 商品信息查询 |
 | [06-product-list.md](./06-product-list.md) | 商品列表 |
-| [07-import-by-sku.md](./07-import-by-sku.md) | 跟卖（按 SKU 复制） |
-| [08-pictures.md](./08-pictures.md) | 图片更新 |
 | [09-stocks.md](./09-stocks.md) | 库存管理 |
-| [10-prices.md](./10-prices.md) | 价格更新 |
+
+跟卖、独立图片更新和价格批量更新尚未形成当前仓库文档，不能使用旧目录链接推断已经实现。
 
 ---
 
@@ -85,18 +84,15 @@
 
 ---
 
-## V2 项目集成清单
+## Atlas 当前集成状态
 
-| 接口 | 用途 | 实现状态 |
+| Ozon 接口 | Atlas 用途 | 当前状态 |
 |---|---|---|
-| `/v1/description-category/tree` | 类目树 | ✅ API 已建（categories.py） |
-| `/v1/description-category/attribute` | 类目属性 | ✅ API 已建 |
-| `/v1/description-category/attribute/values` | 属性值字典 | ✅ API 已建 |
-| `/v3/product/import` | 商品导入 | ✅ API 已建（publish.py） |
-| `/v1/product/import/info` | 导入状态 | ✅ API 已建 |
-| `/v3/product/list` | 商品列表 | 🟡 待建 |
-| `/v3/product/info/list` | 商品详情 | 🟡 待建 |
-| `/v1/product/import-by-sku` | 跟卖 | 🟡 待建（二期） |
-| `/v1/product/pictures/import` | 图片更新 | 🟡 待建（二期） |
-| `/v2/products/stocks` | 库存 | 🟡 待建（二期） |
-| `/v1/product/import/prices` | 价格 | 🟡 待建（二期） |
+| `/v1/description-category/tree` | 平台级类目/商品类型树 | 已实现 Worker 同步；每 7 天自动同步并支持管理员手动同步 |
+| `/v1/description-category/attribute` | 平台级类型属性 | 已实现管理员批次、用户按需刷新和发布预检刷新 |
+| `/v1/description-category/attribute/values`、`values/search` | 平台级字典候选值 | 已实现单字典同步、按需读取和关键词补齐 |
+| `/v3/product/import` | 首次商品导入 | 尚未实现；当前只完成 `publish-preflights` |
+| `/v1/product/import/info` | 导入结果轮询 | 尚未实现 |
+| 商品列表、详情、库存、价格、跟卖、图片更新 | 后续商品运营能力 | 以对应模块交接状态为准，不在平台目录第 1～4 步范围内 |
+
+Atlas 的平台目录接口、状态机和系统后台契约见[平台类目与属性管理 API](../../api/platform-catalog-admin.md)、[商品编辑与发布 API](../../api/product-editor-and-publishing.md)及[缓存刷新方案](../../architecture/platform-catalog-cache-refresh-plan.md)。

docs/integrations/ozon-seller-api/SUMMARY.md

@@ -1,143 +1,34 @@
-# Ozon Seller API 文档整理完成
+# Ozon Seller API 文档状态摘要
 
-已完成 Ozon Seller API 的核心接口文档整理，涵盖商品发布、管理的完整流程。
+> 本文件只汇总当前仓库中的 Ozon 资料和 Atlas 实施状态，不代表 Ozon 官方接口已经全部接入。官方行为以各接口文档与 Ozon 官方文档为准，Atlas 实现进度以 [`../../project/HANDOFF.md`](../../project/HANDOFF.md) 为准。
 
-## 已完成的文档
+## 已整理资料
 
-### 核心文档（9 个）
+| 文档 | 主题 | Atlas 当前状态 |
+|---|---|---|
+| [01-authentication.md](./01-authentication.md) | Client-Id、Api-Key 和错误处理 | 平台参考源凭据已由系统管理员配置并仅供 Worker 使用 |
+| [02-category-tree.md](./02-category-tree.md) | 类目/商品类型树 | 平台级共享缓存已实现；每 7 天自动同步并支持管理员手动同步 |
+| [03-category-attributes.md](./03-category-attributes.md) | 类型属性与字典值 | 平台级缓存、14/21 天状态机、管理员批次、按需刷新和发布预检已实现 |
+| [04-product-import.md](./04-product-import.md) | `/v3/product/import` | 仅作为外部接口资料；Atlas 真正的发布 job 尚未实现 |
+| [05-product-info.md](./05-product-info.md) | 商品信息查询 | 资料文档；实现状态以在线商品模块交接为准 |
+| [06-product-list.md](./06-product-list.md) | 商品列表 | 资料文档；仓库同步 Worker 尚未完成 |
+| [09-stocks.md](./09-stocks.md) | 库存管理 | 资料文档；不属于当前平台目录与首次发布预检范围 |
 
-1. **README.md** - 总览与快速索引
-2. **01-authentication.md** - 鉴权方式、Base URL、错误码、限流
-3. **02-category-tree.md** - 类目树查询（选择类目）
-4. **03-category-attributes.md** - 类目属性与字典值（属性映射）
-5. **04-product-import.md** - 商品导入/创建/更新（核心接口）
-6. **05-product-info.md** - 商品详情查询（审核状态、图片、属性）
-7. **06-product-list.md** - 商品列表分页（ID 收集、批量查询）
-8. **09-stocks.md** - 库存管理（必须设置才能上架）
+跟卖、独立图片更新和价格批量更新尚未形成当前仓库文档。
 
-### 待补充（二期）
+## Atlas 当前目录与发布边界
 
-- **07-import-by-sku.md** - 跟卖（按 SKU 复制 PDP）
-- **08-pictures.md** - 图片更新
-- **10-prices.md** - 价格批量更新
+1. 类目树、类型属性和字典候选值按 `platform_id` 维护，同平台所有门店共享；本阶段没有门店差异层。
+2. 类目树固定每 7 天自动同步。类型属性和字典不做周期性全量扫描，由管理员操作、普通用户访问或发布预检触发 Worker 任务。
+3. 类型属性和字典默认 14 天内 fresh、14～21 天（含 21 天）stale、严格超过 21 天 expired；missing/expired 使用高优先级任务，stale 使用低优先级任务。
+4. `POST /api/product-platform-profiles/{profile_id}/publish-preflights` 已实现，只刷新当前类型和所选 SKU 实际使用的字典，并执行本地发布校验。
+5. 真正的 `product_publish_job`、发布快照、Ozon `/v3/product/import` 提交和结果轮询尚未实现；预检 `ready` 不表示商品已经提交或发布。
+6. 发布预检目前只校验本地类目仍活动，尚未判断整棵类目树缓存是否过期；该边界需在真正发布 job 接入前确认或补齐。
 
----
+## 当前应阅读的实现文档
 
-## 文档特色
-
-### 1. 完整的代码示例
-- Python（服务端）示例
-- TypeScript（前端）示例
-- 实际可运行的代码片段
-
-### 2. V2 项目集成指引
-- 每个文档都包含"V2 项目集成"章节
-- API 层实现示例（对齐 server/ 结构）
-- 前端组件示例（对齐 studio/ 结构）
-
-### 3. 最佳实践与常见问题
-- 缓存策略
-- 错误处理
-- 性能优化
-- 分页/批量操作
-
-### 4. 实用场景
-- 发布流程（端到端）
-- 属性映射工作流
-- 库存同步策略
-- 审核状态检查
-
----
-
-## 核心流程速查
-
-### 完整发布流程
-
-```
-① 获取类目树 → 选择类目
-   POST /v1/description-category/tree
-
-② 获取类目属性 → 映射属性
-   POST /v1/description-category/attribute
-   POST /v1/description-category/attribute/values/search
-
-③ 组装请求体 → 发布商品
-   POST /v3/product/import → task_id
-
-④ 轮询状态 → 获取 product_id
-   POST /v1/product/import/info → status=imported
-
-⑤ 设置库存（必须）
-   POST /v2/products/stocks → 商品上架
-
-⑥ 查询详情（可选）
-   POST /v3/product/info/list → 审核状态/图片/库存
-```
-
-### 关键约束总结
-
-1. **类目**：只有末级类目（`disabled=false`）可建品
-2. **必填字段**：name/description/category/price/尺寸重量/offer_id/images
-3. **图片 URL**：必须 https 公网直链
-4. **属性**：`is_required=true` 的必须填写
-5. **异步任务**：`/import` 返回 task_id，需轮询状态
-6. **库存必须设置**：不设置库存 = 商品不可购买
-
----
-
-## 与 V2 项目的对应关系
-
-| Ozon API | V2 后端 API | V2 前端页面 | 状态 |
-|---|---|---|---|
-| `/description-category/tree` | `/api/categories/tree` | CategoryPicker | ✅ 已建 |
-| `/description-category/attribute` | `/api/categories/{id}/attributes` | AttributeMapper | ✅ 已建 |
-| `/attribute/values` | `/api/categories/attribute/{id}/values` | - | ✅ 已建 |
-| `/v3/product/import` | `/api/products/{id}/publish` | PublishPanel | ✅ 已建 |
-| `/v1/product/import/info` | (background poll) | - | ✅ 已建 |
-| `/v3/product/info/list` | `/api/products/{id}/ozon-detail` | OzonStatusBadge | 🟡 待建 |
-| `/v3/product/list` | `/api/products/sync-from-ozon` | SyncButton | 🟡 待建 |
-| `/v2/products/stocks` | `/api/products/{id}/set-stock` | StockPanel | 🟡 待建 |
-
----
-
-## 使用建议
-
-### 阅读顺序（新接入）
-
-1. **01-authentication.md** - 了解鉴权与基础
-2. **04-product-import.md** - 核心接口，先看这个
-3. **02-category-tree.md** - 类目选择
-4. **03-category-attributes.md** - 属性映射（难点）
-5. **09-stocks.md** - 库存设置（必须）
-6. 其他按需查阅
-
-### 开发时查阅
-
-- 看接口契约 → 查对应章节的"请求/响应"
-- 看错误处理 → 查"常见错误"章节
-- 看集成方式 → 查"V2 项目集成"章节
-- 看最佳实践 → 查"使用场景"或"最佳实践"章节
-
----
-
-## 下一步
-
-### 立即可用
-现有 9 个文档已覆盖 V2 项目一期的所有核心接口，可立即用于：
-- 服务端 `ozon_client.py` 开发
-- API 端点实现参考
-- 前端组件开发参考
-
-### 二期补充
-需要时再补充：
-- 跟卖（import-by-sku）
-- 图片单独更新
-- 价格批量更新
-
----
-
-## 相关文档
-
-- [docs/v2/ozon-publish.md](../v2/ozon-publish.md) - V2 发布集成方案（与本文档配套）
-- [docs/v2/api.md](../v2/api.md) - V2 后端 API 设计
-- [docs/v2/database.md](../v2/database.md) - V2 数据库设计
+- [平台商品参考目录](../../architecture/platform-product-reference-catalog.md)
+- [平台目录缓存刷新方案](../../architecture/platform-catalog-cache-refresh-plan.md)
+- [平台类目与属性管理 API](../../api/platform-catalog-admin.md)
+- [商品编辑与发布 API](../../api/product-editor-and-publishing.md)
+- [项目交接](../../project/HANDOFF.md)