# 前期业务与 ToC 功能架构规格书 (V30.0)

## 1. 核心目标
- **快速上线**：在 AGI 完全体演化完成前，提供高可用的 ToC 贸易加速基础。
- **数据积累**：通过基础订单流积累 AGI 策略演化所需的先验数据。

## 2. 核心功能
- **多平台连接器**：实现 Amazon/AliExpress 的基础订单与商品同步。
- **ConsumerOrderService**：支持 TOC 订单的归集、分润与基础状态流转。
- **基础选品雷达**：基于热销榜单的初级趋势分析。

## 3. 模块详细设计

### 3.1 多平台连接器 (Multi-Platform Connector)
| 模块 | 功能描述 | 状态 |
|------|----------|------|
| Amazon Connector | OAuth2 授权、订单拉取、ASIN 映射 | 待开发 |
| AliExpress Connector | 开放平台 API、SKU 同步 | 待开发 |
| 统一适配层 | 抽象 PlatformInterface，统一订单/商品模型 | 规划中 |

### 3.2 订单归集服务 (ConsumerOrderService)
- **订单归集**：跨平台订单统一归集，按 tenantId 隔离
- **分润计算**：基于订单利润的自动分润比例计算
- **状态流转**：`PENDING` -> `CONFIRMED` -> `SHIPPED` -> `DELIVERED` -> `COMPLETED`

### 3.3 选品雷达 (Product Radar)
- **热销榜单抓取**：Amazon Best Sellers、AliExpress 热销榜
- **品类趋势分析**：基于销量增长率的品类热度计算
- **价格带分析**：目标价格区间的竞品分布

## 4. API 端点设计
| 方法 | 路径 | 功能 |
|------|------|------|
| GET | /api/v1/connector/platforms | 获取支持的平台列表 |
| POST | /api/v1/connector/sync/:platform | 触发平台数据同步 |
| GET | /api/v1/orders | 获取归集订单列表 |
| GET | /api/v1/orders/:id | 获取订单详情 |
| GET | /api/v1/radar/trending | 获取热销趋势 |

## 5. 数据库设计
- `cf_platform_connection`: 平台连接配置 (platform, credentials, status)
- `cf_consumer_order`: 归集订单表 (platform, platform_order_id, amount, status)
- `cf_product_trend`: 选品趋势数据 (platform, category, trend_score)

## 6. 依赖关系
- **前置依赖**：Knex.js, Redis (缓存), 平台 OAuth 凭证
- **后续演进**：AGI 策略引擎接入、自动化采购路由

---
**负责人**: AI-3 (Biz) | **看板索引**: [collaboration-board.md](../governance/collaboration-board.md)
**更新日志**: [AI-3 @ 2026-03-15] 补充模块详细设计与 API 端点