# 子系统 02 — 需求与计划管理 (`planning`) v1.0

## 子系统概述

| 维度 | 说明 |
| --- | --- |
| 代号 | `planning` |
| 核心职责 | 需求触发（人工/自动）、需求评估、计划生成（推新/回评/免评）、审批工作流、ASIN 基础信息管理 |
| 数据所有权 | `demands`, `plans`, `plan_items`, `approval_records`, `asin_catalog` |
| 启动依赖 | identity（软依赖，无 identity 可操作但无法做人群匹配） |
| 外部系统依赖 | Amazon（ASIN 数据、销售数据、评价缺口） |

---

## 1. 模块划分

```
┌─────────────────────────────────────────────────────────────┐
│                    planning 子系统                           │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │ M1: 需求管理 │  │ M2: 计划引擎 │  │ M3: 审批工作 │       │
│  │  (Demand)    │→│  (Plan)      │→│    流        │       │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘       │
│         │                 │                 │                │
│         ▼                 ▼                 ▼                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │ M4: 自动触发 │  │ M5: ASIN管理 │  │ M6: 对外 API │       │
│  │    规则引擎  │  │              │  │    Gateway   │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

| # | 模块 | 代号 | 职责 |
| --- | --- | --- | --- |
| M1 | 需求管理 | `demand-mgr` | 需求创建、评估（成立/待补充/驳回）、优先级管理、需求与 ASIN 关联 |
| M2 | 计划引擎 | `plan-engine` | 从已确认需求生成计划（推新/回评/免评）、计划生命周期管理、计划项拆解 |
| M3 | 审批工作流 | `approval-workflow` | 计划审批链（Amazon 运营总监→用户负责人→渠道负责人）、审批记录 |
| M4 | 自动触发规则引擎 | `auto-trigger` | 按 ASIN 健康度、评价缺口自动触发需求；定时评估触发条件 |
| M5 | ASIN 管理 | `asin-catalog` | ASIN 基础信息、评分、评价数、Listing 健康状态维护 |
| M6 | 对外 API Gateway | `planning-api` | 向其他子系统提供计划查询、ASIN 查询、审批状态查询 API |

---

## 2. 各模块内外说明

### 2.1 M1: 需求管理

| 维度 | 说明 |
| --- | --- |
| **对内** | Amazon 运营人工提需求（选择 ASIN、指定类型：推新/回评/免评、目标数量、周期）；用户运营评估需求（查 ASIN 健康、目标数量、历史完成、当前资源）；评估结果：已确认/待补充/驳回 |
| **对外接口** | `POST /api/demands` — 创建需求；`PUT /api/demands/{id}/evaluate` — 评估需求 |
| **数据写入** | `demands` |
| **依赖** | `GET /api/identity/person` — 评估时可能需要运营人员身份 |
| **待确认** | 需求是否有优先级字段（P0/P1/P2）？驳回后是否允许重新提交？ |

### 2.2 M2: 计划引擎

| 维度 | 说明 |
| --- | --- |
| **对内** | 从已确认需求生成计划草案（类型：推新/回评/免评）；计划参数（目标 ASIN、目标数量、周期、预算、备注）；计划状态流转；计划项拆解（将计划拆成可分配给渠道的执行单元） |
| **对外接口** | `POST /api/plans` — 创建计划；`PUT /api/plans/{id}/status` — 更新状态；`GET /api/plans/{id}/items` — 获取计划项 |
| **数据写入** | `plans`, `plan_items` |
| **依赖** | `GET /api/quota/check` — 生成人群前查询额度；`GET /api/risk/check` — 计划复核时查询风险 |
| **待确认** | 计划是否可以包含多个 ASIN？推新和回评是否可以合并为一个计划？ |

### 2.3 M3: 审批工作流

| 维度 | 说明 |
| --- | --- |
| **对内** | 按计划类型路由不同审批链：（测评→Amazon运营总监 / 回评→总监或指定负责人 / 免评→总监+用户负责人 / 紧急→运营负责人+用户负责人+主管）；周/月推送计划审批（用户负责人→渠道负责人）；审批节点（通过/驳回/待补充） |
| **对外接口** | `POST /api/approvals/{plan_id}/submit` — 提交审批；`PUT /api/approvals/{plan_id}/review` — 审批决策 |
| **数据写入** | `approval_records` |
| **依赖** | `GET /api/identity/person` — 获取审批人身份 |
| **待确认** | 审批链是否可以动态配置（不同站点/国家不同审批人）？驳回后修改再提交是否需要重新走完整审批链？ |

### 2.4 M4: 自动触发规则引擎

| 维度 | 说明 |
| --- | --- |
| **对内** | 定时扫描 ASIN 健康状态（评分、评价数、差评比例）；当满足触发条件时自动创建需求（无需人工干预）；触发规则可配置 |
| **对外接口** | 内部定时任务，不对外暴露 |
| **数据写入** | `demands`（自动生成的需求） |
| **依赖** | `GET /api/reviews/asin-health` 或本地 ASIN 数据 |
| **待确认** | 自动触发后是否需要人工确认还是直接进入评估？自动触发的优先级如何设定？ |

### 2.5 M5: ASIN 管理

| 维度 | 说明 |
| --- | --- |
| **对内** | ASIN 基础信息（ASIN 码、标题、品类、站点）；评分、评价总数、差评数；Listing 健康状态（活跃/风险/下架）；与计划的关联关系 |
| **对外接口** | `GET /api/asins/{asin}` — ASIN 详情；`GET /api/asins?status=at_risk` — 需关注的 ASIN 列表 |
| **数据写入** | `asin_catalog` |
| **依赖** | Amazon 数据同步（外部系统） |
| **待确认** | ASIN 数据是否已在 JOYHUB 或其他系统中维护？是否需要新建还是复用？ |

### 2.6 M6: 对外 API Gateway

| 维度 | 说明 |
| --- | --- |
| **对内** | 统一对外 API 认证、限流、日志 |
| **对外接口** | `GET /api/plans?status=approved` — 待执行计划（outreach 消费）；`GET /api/plans/{id}` — 计划详情（review 消费）；`GET /api/asins/{asin}` — ASIN 查询 |

---

## 3. 对外 API 契约（草案）

| 接口 | 方法 | 输入 | 输出 | 消费者 |
| --- | --- | --- | --- | --- |
| 创建需求 | `POST /api/demands` | `{asin, type, target_count, period, priority}` | `{demand_id, status}` | 运营前端 |
| 评估需求 | `PUT /api/demands/{id}/evaluate` | `{decision, reason}` | `{status}` | 用户运营前端 |
| 创建计划 | `POST /api/plans` | `{demand_id, type, params}` | `{plan_id}` | 用户运营前端 |
| 待执行计划列表 | `GET /api/plans?status=approved` | 无 | `[{plan_id, type, items}]` | outreach |
| 计划详情 | `GET /api/plans/{id}` | `plan_id` | 完整计划含审批记录 | review / outreach |
| ASIN 查询 | `GET /api/asins/{asin}` | `asin` | ASIN 详情+健康状态 | 所有子系统 |

---

## 4. 数据对象

| 对象 | 核心字段 | 说明 |
| --- | --- | --- |
| `demands` | demand_id, asin, type (NEW/REVIEW/EXEMPTION), target_count, period, status (PENDING/EVALUATING/CONFIRMED/REJECTED/WAITING), priority, created_by, evaluated_by, created_at | 需求主表 |
| `plans` | plan_id, demand_id, type, status (DRAFT/REVIEW/APPROVED/EXECUTING/COMPLETED/CANCELLED), target_count, period, created_at | 计划主表 |
| `plan_items` | item_id, plan_id, asin, item_type, target_count, assigned_channel, status | 计划执行项 |
| `approval_records` | approval_id, plan_id, approver, decision, comment, decided_at, step_order | 审批记录 |
| `asin_catalog` | asin, title, category, marketplace, rating, review_count, negative_count, health_status, last_synced_at | ASIN 信息 |

---

## 5. 业务澄清问题清单 — planning

### 5.1 需求与计划模型（5 项）

| # | 问题 | 优先级 |
| --- | --- | --- |
| P-01 | 一个需求是否可以生成多个计划？（例如一个回评需求拆分到 IM 计划和 EDM 计划）还是一对一？ | **P0** |
| P-02 | 计划是否可以跨 ASIN？（一个推新计划覆盖 3 个新 ASIN）还是每个计划只针对一个 ASIN？ | **P0** |
| P-03 | 计划中的「目标数量」是指目标评价数还是目标触达用户数？（如果转化率 2%，要得到 10 个评价需触达 500 人） | **P0** |
| P-04 | 计划的「周期」是什么粒度？（周/月/自定义日期范围？）周期结束后未完成的计划如何处理？ | P1 |
| P-05 | 需求是否有优先级？（P0/P1/P2 或高/中/低？）优先级影响什么？（审批速度？资源分配？） | P1 |

### 5.2 审批流程（4 项）

| # | 问题 | 优先级 |
| --- | --- | --- |
| P-06 | 文档提到「免评计划 → Amazon 运营总监 + 用户负责人」审批——是两者都必须通过（会签）还是任一通过即可（或签）？ | **P0** |
| P-07 | 「指定负责人」的指定规则是什么？（按 ASIN 品类？按站点？按当前负载？人工指定？） | P1 |
| P-08 | 审批超时如何处理？（审批人 N 天未处理，自动通过？自动驳回？升级到上级？） | P1 |
| P-09 | 审批驳回后修改再提交，审批链是否重置还是从当前节点继续？ | P1 |

### 5.3 自动触发（3 项）

| # | 问题 | 优先级 |
| --- | --- | --- |
| P-10 | 自动触发的具体阈值是什么？（① ASIN 评分低于多少？② 差评在最近 N 天新增多少？③ 评价总数 < 目标值？） | **P0** |
| P-11 | 自动触发是每天跑一次还是实时监控？（如果是实时，高频变化的 ASIN 会不会重复触发？） | P1 |
| P-12 | 自动触发生成的需求是否自动进入评估环节还是需要人工确认后才进入？ | P2 |

### 5.4 ASIN 管理（3 项）

| # | 问题 | 优先级 |
| --- | --- | --- |
| P-13 | ASIN 数据来源和更新频率？（从 Amazon API 拉取？T+1？实时？手动导入？） | **P0** |
| P-14 | ASIN 的「Listing 健康状态」如何定义？（评分 ≥ 4.2 = 健康？差评率 < X%？）健康度是否有多个等级？ | P1 |
| P-15 | ASIN 是否有关联关系？（变体 ASIN、父 ASIN-子 ASIN）关联合并还是独立管理？ | P2 |

### 5.5 计划执行衔接（2 项）

| # | 问题 | 优先级 |
| --- | --- | --- |
| P-16 | 计划审批通过后如何流转到 outreach 子系统？（planning 主动推送？outreach 定时拉取？事件通知？） | P1 |
| P-17 | 计划执行过程中是否可以调整目标数量或周期？调整是否需要重新审批？ | P2 |

### 5.6 计划模板与复用（3 项）

| # | 问题 | 优先级 |
| --- | --- | --- |
| P-18 | 是否需要计划模板功能？（对常推的 ASIN 创建可复用的计划模板——模板包含预设的渠道/目标数/周期？） | P1 |
| P-19 | 周期性计划（如「每月 1 号自动对 ASIN X 发起回评计划」）是否支持？谁有权限创建？ | P2 |
| P-20 | 计划是否可以暂停/恢复？（执行中因库存或供应链原因需暂停——暂停期间已触达的用户如何处理？） | P1 |

### 5.7 预算与资源管理（3 项）

| # | 问题 | 优先级 |
| --- | --- | --- |
| P-21 | 计划是否有预算字段？（返款金额、Code 成本、KOC 费用——是否需要预算审批？超出预算如何处理？） | P1 |
| P-22 | 资源容量规划——同时可执行的计划数是否有上限？（受限于客服人力/EDM发送额度/IM频控？） | P1 |
| P-23 | 是否需要计划执行成本的 ROI 计算？（返款总额 / 获得的评价数 = 单评价成本——系统自动计算还是手动录入？） | P2 |

### 5.8 季节性/大促处理（3 项）

| # | 问题 | 优先级 |
| --- | --- | --- |
| P-24 | Prime Day / Black Friday 等大促期间的计划是否有特殊处理？（提前锁定额度、加大推送量、豁免某些频控规则？） | P1 |
| P-25 | 大促前的「预热计划」和大促后的「回评计划」是否需要在系统中作为计划间的依赖关系来管理？ | P2 |
| P-26 | 季节性产品（圣诞装饰、夏季用品）的计划是否有时间敏感度标记？（错过季节窗口的计划自动降级？） | P2 |

### 5.9 多站点/多市场（3 项）

| # | 问题 | 优先级 |
| --- | --- | --- |
| P-27 | 不同 Amazon 站点的计划是否可以统一管理？（同一个 ASIN 在不同站点是独立计划还是关联计划？） | P1 |
| P-28 | 多站点的审批人是否不同？（.com 的运营总监和 .co.uk 的运营总监可能是不同人） | P1 |
| P-29 | 跨站点需求的冲突检测？（.com 和 .de 同时对同一真实的同一用户做了不同计划——算不算冲突？） | P2 |

### 5.10 实施层面（3 项）

| # | 问题 | 优先级 |
| --- | --- | --- |
| P-30 | 自动触发生成的需求如果无人处理（评估超时），是否自动驳回还是升级通知？ | P1 |
| P-31 | 审批工作流引擎——是否有现成的审批引擎可复用？（还是需要从零开发状态机？） | P2 |
| P-32 | 计划执行过程中用户反馈「不想再收到」——是标记为退订（outreach 处理）还是需要回写到 planning 的计划状态中？ | P1 |
