1|# 子系统 08 — KOC/KOL 协作 (`creator`) v1.0
     2|
     3|## 子系统概述
     4|
     5|| 维度 | 说明 |
     6|| --- | --- |
     7|| 代号 | `creator` |
     8|| 核心职责 | KOC/KOL 匹配筛选、内容 Brief/Code 分配、内容发布跟踪、带货结果跟踪、JOYCOLLAB 数据同步 |
     9|| 数据所有权 | `exemption_plan_tasks`, `creator_content_records`, `creator_profiles`, `code_records` |
    10|| 启动依赖 | planning（软依赖，免评计划入口） |
    11|| 外部系统依赖 | JOYCOLLAB（KOC/KOL 数据、内容数据、Code 使用、带货订单） |
    12|
    13|---
    14|
    15|## 1. 模块划分
    16|
    17|```
    18|┌─────────────────────────────────────────────────────────────┐
    19|│                    creator 子系统                            │
    20|│                                                             │
    21|│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
    22|│  │ M1: KOC/KOL  │  │ M2: 内容/Code│  │ M3: 结果跟踪 │       │
    23|│  │   匹配筛选   │→│    管理      │→│              │       │
    24|│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘       │
    25|│         │                 │                 │                │
    26|│         ▼                 ▼                 ▼                │
    27|│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
    28|│  │ M4: JOYCOLLAB│  │ M5: IM/EDM/  │  │ M6: 对外 API │       │
    29|│  │    数据同步  │  │ APP 协同     │  │    Gateway   │       │
    30|│  └──────────────┘  └──────────────┘  └──────────────┘       │
    31|│                                                             │
    32|└─────────────────────────────────────────────────────────────┘
    33|```
    34|
    35|| # | 模块 | 职责 |
    36|| --- | --- | --- |
    37|| M1 | KOC/KOL 匹配筛选 | 按国家/平台/粉丝量/产品类目/历史效果筛选匹配合作对象；检查合作对象风险（历史纠纷/违约） |
    38|| M2 | 内容/Code 管理 | 分配内容 Brief、分配 Code、管理 Code 使用量、素材管理 |
    39|| M3 | 结果跟踪 | 跟踪内容发布状态、点击/跳转数据、Code 使用量、带货订单、转化销量、权重变化 |
    40|| M4 | JOYCOLLAB 数据同步 | 从 JOYCOLLAB 拉取 KOC/KOL 数据、内容数据、Code 使用、带货订单；同步失败告警 |
    41|| M5 | IM/EDM/APP 协同 | KOC 内容二次分发、免评 Code 触达站内用户、活动引流、结果通知 |
    42|| M6 | 对外 API Gateway | 供 planning、outreach、review 查询 |
    43|
    44|---
    45|
    46|## 2. 各模块内外说明
    47|
    48|### 2.1 M1: KOC/KOL 匹配筛选
    49|
    50|| 维度 | 说明 |
    51|| --- | --- |
    52|| **对内** | 免评计划进入后：①按国家/平台/粉丝量/历史效果筛选 KOC/KOL ②按产品类目匹配专长 ③检查合作对象风险（历史纠纷/违约）→有风险记录时提示 |
    53|| **对外接口** | `GET /api/creators/match?plan_id=` — 获取匹配推荐列表 |
    54|| **数据写入** | `creator_profiles`（从 JOYCOLLAB 同步的 KOC/KOL 画像缓存） |
    55|| **待确认** | 匹配是完全自动推荐还是运营人工选择？推荐算法依赖哪些权重？ |
    56|
    57|### 2.2 M2: 内容/Code 管理
    58|
    59|| 维度 | 说明 |
    60|| --- | --- |
    61|| **对内** | 分配内容 Brief（产品信息/要求/素材/发布时间）；Code 分配（每个 KOC 独立 Code 还是一对多？）；Code 使用量监控 |
    62|| **对外接口** | `POST /api/creators/tasks` — 创建协作任务（含 Brief + Code） |
    63|| **数据写入** | `exemption_plan_tasks`, `code_records` |
    64|| **待确认** | Code 是 JOYCOLLAB 生成还是 USER 系统生成？Code 是优惠码还是追踪码？ |
    65|
    66|### 2.3 M3: 结果跟踪
    67|
    68|| 维度 | 说明 |
    69|| --- | --- |
    70|| **对内** | 跟踪 6 组结果：①内容发布状态/链接/互动数据 ②点击/跳转量 ③Code 使用量 ④带货订单数 ⑤转化销量 ⑥Listing 权重变化；执行评估：达标→结果回流 / 未达标→调整策略（更换KOC/调整素材/追加Code） |
    71|| **对外接口** | `GET /api/creators/results/{plan_id}` — 免评计划执行结果 |
    72|| **数据写入** | `creator_content_records` |
    73|| **依赖** | JOYCOLLAB 数据同步 |
    74|
    75|### 2.4 M4: JOYCOLLAB 数据同步
    76|
    77|| 维度 | 说明 |
    78|| --- | --- |
    79|| **对内** | 从 JOYCOLLAB 同步：KOC/KOL 画像数据、内容发布数据、Code 使用数据、带货订单数据；同步记录（时间/成功/失败）；同步失败告警 |
    80|| **对外接口** | 内部定时任务 |
    81|| **数据写入** | 本地缓存表（`creator_profiles`, `creator_content_records`） |
    82|| **待确认** | 同步方向是单向（COLLAB→USER）还是双向？同步频率？ |
    83|
    84|### 2.5 M5: IM/EDM/APP 协同
    85|
    86|| 维度 | 说明 |
    87|| --- | --- |
    88|| **对内** | 4 种协同动作：①KOC 内容二次分发（IM/APP 推送优质内容）②免评 Code 触达（IM/EDM 分发 Code 给站内用户）③活动引流（APP Push 引导用户进入 KOC 内容页）④结果通知（IM/APP 通知用户 Code 到账/订单确认） |
    89|| **对外接口** | 调用 outreach API：`POST /api/outreach/im/send` 等 |
    90|| **数据写入** | 协同记录 |
    91|
    92|---
    93|
    94|## 3. 对外 API 契约（草案）
    95|
    96|| 接口 | 方法 | 输入 | 输出 | 消费者 |
    97|| --- | --- | --- | --- | --- |
    98|| KOC/KOL 匹配推荐 | `GET /api/creators/match?plan_id=` | plan_id | `[{creator_id, score, match_reason}]` | planner 前端 |
    99|| 创建协作任务 | `POST /api/creators/tasks` | `{creator_id, plan_id, brief, code, deadline}` | `{task_id}` | planner 前端 |
   100|| 免评执行结果 | `GET /api/creators/results/{plan_id}` | plan_id | `{content, clicks, codes, orders, sales, weight_change}` | review（结果回流）, planning |
   101|| KOC/KOL 画像查询 | `GET /api/creators/{creator_id}` | creator_id | KOC/KOL 完整画像 | planner 前端 |
   102|
   103|---
   104|
   105|## 4. 数据对象
   106|
   107|| 对象 | 核心字段 | 说明 |
   108|| --- | --- | --- |
   109|| `exemption_plan_tasks` | task_id, plan_id, creator_id, brief, code, status, assigned_at, deadline | 免评计划协作任务 |
   110|| `creator_content_records` | record_id, task_id, creator_id, content_url, publish_time, engagement_data, synced_at | KOC 内容发布记录 |
   111|| `creator_profiles` | creator_id, name, platform, country, follower_count, category, historical_performance, risk_notes, synced_at | KOC/KOL 画像（从 JOYCOLLAB 同步的本地缓存） |
   112|| `code_records` | code_id, task_id, code_value, code_type, usage_count, usage_limit, status | Code 记录 |
   113|
   114|---
   115|
   116|## 5. 业务澄清问题清单 — creator
   117|
   118|### 5.1 JOYCOLLAB 对接（4 项）
   119|
   120|| # | 问题 | 优先级 |
   121|| --- | --- | --- |
   122|| K-01 | JOYCOLLAB 中 KOC/KOL 的完整数据字段有哪些？（平台/粉丝量/国家/类目/历史合作效果/历史纠纷/违约——文档部分列出，需确认完整字段清单和 API 可用性） | **P0** |
   123|| K-02 | 数据同步方向是单向（COLLAB→USER）还是双向？（USER 分配的 Brief/Code 是否需要回写到 COLLAB？） | **P0** |
   124|| K-03 | 同步频率？（实时 Webhook？每小时？每天？）同步失败时谁来处理？重试策略？ | P1 |
   125|| K-04 | JOYCOLLAB 是否有现成 API？是 REST API 还是需要开发新的同步接口？ | P1 |
   126|
   127|### 5.2 KOC/KOL 匹配（3 项）
   128|
   129|| # | 问题 | 优先级 |
   130|| --- | --- | --- |
   131|| K-05 | 匹配是运营人工选择还是系统自动推荐？推荐算法的权重？（粉丝量 vs 历史效果 vs 类目匹配 vs 报价？） | P1 |
   132|| K-06 | KOC/KOL 是否有评级/分层体系？（头部/腰部/尾部？）不同层级对应的计划类型是否不同？ | P1 |
   133|| K-07 | 「合作对象风险（历史纠纷/违约）」——风险数据从哪里来？（JOYCOLLAB？人工标记？）什么程度的风险需要拦截？ | P1 |
   134|
   135|### 5.3 Code 与内容（3 项）
   136|
   137|| # | 问题 | 优先级 |
   138|| --- | --- | --- |
   139|| K-08 | Code 是 JOYCOLLAB 生成还是 USER 系统生成？Code 类型？（优惠码/追踪码/专属链接？）一对一还是可以多人共用？ | P1 |
   140|| K-09 | KOC 发布的内容是否需要审核？（Brief 交付后→KOC 创作→审核→发布？）审核流程在哪个系统？ | P2 |
   141|| K-10 | KOC 内容二次分发到 IM/APP——分发策略是什么？（所有优质内容都分发？按产品/地区筛选？） | P2 |
   142|
   143|### 5.4 财务结算（2 项）
   144|
   145|| # | 问题 | 优先级 |
   146|| --- | --- | --- |
   147|| K-11 | KOC/KOL 的提成/返点结算在哪个系统执行？（JOYCOLLAB？财务系统？还是 USER 内触发结算指令？）USER 的责任边界？ | P1 |
   148|| K-12 | 结算数据（提成计算/返点核算/提款记录）是否需要同步到 USER？权限控制（财务数据独立权限）？ | P2 |
   149|
### 5.5 KOC/KOL 分层与定价（3 项）

| # | 问题 | 优先级 |
| --- | --- | --- |
| K-13 | KOC/KOL 是否有分层体系？（头部/腰部/尾部——按粉丝量划分？按历史带货效果划分？）不同分层的合作价格和权益？ | P1 |
| K-14 | KOC/KOL 的报价/定价数据是否在系统中维护？（用于预算计算和 ROI 分析？） | P2 |
| K-15 | KOC/KOL 是否有签约/合同管理？排他性协议？（签约期内只能推广本品牌产品？）排他性信息是否需要系统记录？ | P2 |

### 5.6 内容与权益管理（3 项）

| # | 问题 | 优先级 |
| --- | --- | --- |
| K-16 | KOC/KOL 发布内容的使用权和授权期限？（品牌是否可以二次使用、广告投放、修改？授权条款在系统中管理还是走线下合同？） | P2 |
| K-17 | 内容审核流程——KOC/KOL 创作的内容是否需要品牌方审核后才能发布？（审核不通过→修改→重新审核的流程？） | P1 |
| K-18 | 内容效果评估——除了点击/Code/订单数据外，是否需要评估内容质量？（互动率、完播率、正向评论比例？） | P2 |

### 5.7 多平台 KOC/KOL 管理（3 项）

| # | 问题 | 优先级 |
| --- | --- | --- |
| K-19 | KOC/KOL 涉及哪些平台？（YouTube / TikTok / Instagram / Facebook / 博客 / Amazon 站内 Influencer Program？）每个平台的数据来源？ | P1 |
| K-20 | 同一 KOC/KOL 在多个平台有账号——是否在系统中关联为同一个人？（类似 identity 的归并逻辑？） | P2 |
| K-21 | 不同平台的内容格式和指标不同（YouTube 视频 vs Instagram 帖子 vs TikTok 短视频）——结果跟踪如何统一？ | P2 |

### 5.8 Code 管理补充（2 项）

| # | 问题 | 优先级 |
| --- | --- | --- |
| K-22 | Code 的类型？（一次性折扣码 / 多次使用码 / 追踪链接 / 专属落地页？）不同类型的生成和追踪逻辑？ | P1 |
| K-23 | Code 的有效期管理？（计划结束后 Code 自动失效？还是保留一段时间？）Code 是否可重复使用？ | P1 |

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

| # | 问题 | 优先级 |
| --- | --- | --- |
| K-24 | JOYCOLLAB 数据同步失败时的降级策略？（用本地缓存数据？标记为「数据可能过期」？暂停新的协作任务？） | P1 |
| K-25 | KOC/KOL 匹配算法的性能——如果 JOYCOLLAB 有几千个 KOC，匹配需要多少时间？是否有预筛选+精排的两阶段设计？ | P2 |
| K-26 | KOC/KOL 的任务状态如何与 planning 的计划状态联动？（协作任务完成→计划完成度增加→计划状态更新？） | P1 |