Add under-anything knowledge dashboard

2026-05-27 15:40:32 +08:00
commit e31a75d2bb
565 changed files with 143063 additions and 0 deletions
--- a/wishfulfilled-wiki/05_需求文档/08-子系统-KOC-KOL协作.md
+++ b/wishfulfilled-wiki/05_需求文档/08-子系统-KOC-KOL协作.md
@@ -0,0 +1,187 @@
+     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 |