# KOL 功能设计文档

## 概述

为 GEO 工具平台新增 KOL（Key Opinion Leader）功能模块。KOL 是平台中的超级用户角色——拥有普通用户的全部功能，同时可以创建、管理精调 prompt 订阅包，供其他用户付费订阅使用。平台记录订阅和使用数据，后续用于给 KOL 结算。

### 核心概念

- **KOL 用户**：拥有 `platform_role = "kol"` 的用户，具备普通用户全部权限 + 提示词管理 + 数据看板
- **订阅包（Package）**：KOL 发布的一组精调 prompt 的集合，面向某个行业/场景（如"家具行业精调包"）
- **Prompt**：包内的具体提示词，适配不同平台或版本（如"豆包版友好"、"DeepSeek版"、"精调2025.4.16版"）
- **动态表单**：每个 prompt 由 KOL 定义用户需要填写的变量（公司名、竞品等），prompt 内容对用户不可见
- **订阅**：用户通过申请订阅获取 KOL 包的使用权，管理员审批或手动绑定开通，第一版不做支付

### 实现策略

采用**渐进式集成**方案：KOL 作为现有系统的扩展层，复用已有的 article、generation_tasks 基础设施，新增 KOL 相关数据表和页面。改动最小，风险最低。

---

## 1. 数据模型

### 1.1 新增表

#### kol_packages — 订阅包

```sql
CREATE TABLE kol_packages (
    id          BIGSERIAL PRIMARY KEY,
    kol_user_id BIGINT NOT NULL REFERENCES users(id),
    name        VARCHAR(200) NOT NULL,
    description TEXT,
    cover_url   TEXT,
    industry    VARCHAR(100),
    tags        JSONB NOT NULL DEFAULT '[]',
    price_note  VARCHAR(200),
    status      VARCHAR(20) NOT NULL DEFAULT 'draft',  -- draft / published / archived
    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    deleted_at  TIMESTAMPTZ
);
CREATE INDEX idx_kol_packages_kol_user ON kol_packages(kol_user_id) WHERE deleted_at IS NULL;
CREATE INDEX idx_kol_packages_status ON kol_packages(status) WHERE deleted_at IS NULL;
```

#### kol_prompts — KOL 提示词

```sql
CREATE TABLE kol_prompts (
    id               BIGSERIAL PRIMARY KEY,
    package_id       BIGINT NOT NULL REFERENCES kol_packages(id),
    name             VARCHAR(200) NOT NULL,
    platform_hint    VARCHAR(100),        -- doubao / deepseek / chatgpt / 通用 等
    prompt_content   TEXT NOT NULL,        -- prompt 模板内容，含 {{变量}} 占位符，用户不可见
    variables_schema JSONB NOT NULL DEFAULT '[]',  -- 动态表单定义
    sort_order       INT NOT NULL DEFAULT 0,
    status           VARCHAR(20) NOT NULL DEFAULT 'draft',  -- draft / active / archived
    created_at       TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at       TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE INDEX idx_kol_prompts_package ON kol_prompts(package_id);
```

**variables_schema 格式**（变量 key 默认中文，也支持英文）：

```json
[
  {
    "key": "公司名称",
    "label": "公司名称",
    "type": "input",
    "required": true,
    "placeholder": "请输入您的公司名"
  },
  {
    "key": "行业",
    "label": "行业",
    "type": "select",
    "options": ["家具", "建材", "家电"],
    "required": true
  },
  {
    "key": "主要竞品",
    "label": "主要竞品",
    "type": "textarea",
    "required": false
  },
  {
    "key": "月预算",
    "label": "月预算(万)",
    "type": "number",
    "required": false
  }
]
```

支持的 type 值：`input`（单行文本）、`textarea`（多行文本）、`select`（下拉选择）、`number`（数字）、`checkbox`（多选标签）。

#### kol_subscriptions — 订阅关系

```sql
CREATE TABLE kol_subscriptions (
    id          BIGSERIAL PRIMARY KEY,
    tenant_id   BIGINT NOT NULL REFERENCES tenants(id),
    package_id  BIGINT NOT NULL REFERENCES kol_packages(id),
    status      VARCHAR(20) NOT NULL DEFAULT 'pending',  -- pending / active / expired / revoked
    approved_by BIGINT REFERENCES users(id),
    start_at    TIMESTAMPTZ,
    end_at      TIMESTAMPTZ,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE UNIQUE INDEX uk_kol_subscription_active ON kol_subscriptions(tenant_id, package_id) WHERE status IN ('pending', 'active');
```

#### kol_usage_logs — 使用记录

```sql
CREATE TABLE kol_usage_logs (
    id                 BIGSERIAL PRIMARY KEY,
    package_id         BIGINT NOT NULL REFERENCES kol_packages(id),
    prompt_id          BIGINT NOT NULL REFERENCES kol_prompts(id),
    tenant_id          BIGINT NOT NULL REFERENCES tenants(id),
    article_id         BIGINT REFERENCES articles(id),
    variables_snapshot JSONB,
    created_at         TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE INDEX idx_kol_usage_package ON kol_usage_logs(package_id, created_at DESC);
CREATE INDEX idx_kol_usage_tenant ON kol_usage_logs(tenant_id, created_at DESC);
```

### 1.2 现有表变更

#### articles 表

新增字段：
- `kol_prompt_id BIGINT REFERENCES kol_prompts(id)` — 关联使用的 KOL prompt

新增 `source_type` 值：`"kol"`

#### generation_tasks 表

新增 `task_type` 值：`"kol"`

`input_params_json` 存储用户填入的变量值：

```json
{
  "kol_prompt_id": 42,
  "variables": {
    "公司名称": "宜家家居",
    "行业": "家具",
    "主要竞品": "全友、顾家",
    "月预算": 50
  }
}
```

#### platform_user_roles 表

新增 `platform_role` 值：`"kol"`

---

## 2. 页面结构与路由

### 2.1 侧边栏导航变更

在现有 `navSections`（AppShell.vue）中新增两个分组：

```
现有导航:
  Workspace
  文章创作: 模版生成 | 自定义生成 | 自由创作 | 发布管理
  品牌管理: 品牌库
  品牌追踪: 追踪详情
  内容管理: 知识库 | 图片库

新增:
  KOL 市场: 模版市场                    ← 所有用户可见
  KOL 工作台: 提示词管理 | 数据看板      ← 仅 KOL 角色可见
```

"KOL 工作台" 分组根据用户 permissions 或 platform_role 动态显示/隐藏。

### 2.2 新增路由

| 路由 | 组件 | 角色 | 说明 |
|------|------|------|------|
| `/kol/marketplace` | KolMarketplaceView | 所有用户 | 浏览/筛选/订阅 KOL 包 |
| `/kol/packages/:id` | KolPackageDetailView | 所有用户 | 包详情 → prompt 列表 → 选择 prompt |
| `/kol/generate/:promptId` | KolGenerateView | 已订阅用户 | 动态表单（填变量）→ 提交生成 |
| `/kol/manage` | KolManageView | 仅 KOL | 管理订阅包 + AI 辅助编写 prompt |
| `/kol/dashboard` | KolDashboardView | 仅 KOL | 订阅数据统计看板 |

### 2.3 用户入口（3个）

1. **侧边栏「模版市场」**→ 浏览/筛选 → 订阅 → 选 prompt → 表单 → 生成
2. **Workspace 卡片区**：已订阅的包显示为卡片 → 点击 → 选 prompt → 表单 → 生成
3. **模版生成页面**：已订阅的 KOL 包也出现在模版选择器 modal 中

---

## 3. 普通用户流程

### 3.1 模版市场（KolMarketplaceView）

- 卡片网格展示所有已发布的 KOL 订阅包
- 筛选：按行业、标签、KOL 名称
- 每张卡片展示：封面、包名、KOL 名称、行业标签、prompt 数量、订阅人数
- 卡片操作：点击进入包详情

### 3.2 包详情（KolPackageDetailView）

- 头部：包名、描述、KOL 信息、行业标签
- 订阅状态区：
  - 未订阅 → 显示「申请订阅」按钮（状态变为 pending）
  - 待审批 → 显示「审核中」状态
  - 已订阅 → 显示有效期
- Prompt 列表：展示包内所有 active prompt，每个显示名称 + 平台标识
- 点击某个 prompt → 跳转到生成页面（需已订阅）

### 3.3 动态表单生成（KolGenerateView）

- 根据 `kol_prompts.variables_schema` 动态渲染表单
- 支持的字段类型：input、textarea、select、number、checkbox
- 用户填写变量 → 点击「生成文章」
- 后端：变量值替换 prompt 模板中的 `{{key}}` → 调用 LLM → 生成文章
- 生成的文章 `source_type = "kol"`，`kol_prompt_id` 关联对应 prompt
- 同时写入 `kol_usage_logs` 记录

---

## 4. KOL 提示词编辑器（KolManageView）

### 4.1 包管理

- 列表展示 KOL 自己创建的所有订阅包
- 创建/编辑包：名称、描述、封面、行业、标签、定价说明
- 包状态管理：草稿 → 发布 → 下架

### 4.2 Prompt 编辑器（核心组件）

**三栏布局：**

- **左栏 — 变量组件面板（200px）**：
  - 5 种可拖拽组件：输入框、多行文本、选择框、数字框、多选框
  - 拖入编辑区光标位置触发配置

- **中栏 — Prompt 编辑区**：
  - 顶部 AI 辅助栏：
    - AI 生成：KOL 描述需求 → AI 生成完整 prompt 模板（含变量）
    - AI 优化：选中现有 prompt → AI 优化措辞/结构
    - 复用现有 `template_assist_tasks` 异步任务机制
  - 编辑区：支持富文本编辑，变量以彩色标签形式内联展示（如 `{{公司名称}}`）
  - 操作栏：预览表单、保存草稿、发布

- **右栏 — 变量配置面板（260px）**：
  - 展示所有已添加的变量卡片
  - 点击可编辑：key、显示名（label）、类型、是否必填、提示语、选项列表
  - 变量 key 默认 = 显示名（中文），也支持手动改为英文

### 4.3 拖拽交互流程

1. KOL 从左侧面板拖一个组件到编辑区光标位置
2. 弹出配置弹窗：填写变量 key（默认中文）、显示名、必填、提示语/选项
3. 确认后：编辑区插入 `{{key}}` 占位符标签 + 右侧面板出现配置卡片
4. 后续可在右侧面板修改配置，编辑区标签同步更新

### 4.4 Prompt 内容保护

- `prompt_content` 只存储在服务端
- 面向普通用户的 API 永远不返回 prompt 原文
- 用户端只获取 `variables_schema`（表单定义）用于渲染表单

---

## 5. KOL 数据看板（KolDashboardView）

### 5.1 数据指标

- **总订阅数**：所有包的 active 订阅总数
- **本月新增订阅**：当月新增 active 订阅
- **总使用次数**：所有 prompt 被使用生成文章的总次数
- **本月使用次数**：当月使用次数

### 5.2 按包维度

- 每个包的订阅用户数、使用次数
- 包内各 prompt 的使用次数排行

### 5.3 趋势图

- 订阅数随时间变化趋势
- 使用次数随时间变化趋势

### 5.4 数据来源

- 订阅数据：查询 `kol_subscriptions` 表
- 使用数据：查询 `kol_usage_logs` 表
- 后续扩展：收益计算、结算报表

---

## 6. 订阅管理

### 6.1 用户申请订阅

- 用户在包详情页点击「申请订阅」
- 创建 `kol_subscriptions` 记录，`status = 'pending'`
- 后续管理员审批

### 6.2 管理员操作

第一版通过现有平台管理机制处理：
- 审批待处理的订阅申请（pending → active）
- 手动绑定开通：管理员直接创建 `status = 'active'` 的订阅记录
- 撤销订阅（active → revoked）

### 6.3 订阅鉴权

- 用户访问 `/kol/generate/:promptId` 时，后端检查：
  1. prompt 所属 package 是否存在
  2. 用户 tenant 是否有该 package 的 active 订阅
  3. 订阅是否在有效期内
- 不满足则返回 403

---

## 7. API 设计

### 7.1 KOL 市场（所有用户）

```
GET    /api/tenant/kol/packages                  -- 市场列表（筛选：industry, tags, keyword）
GET    /api/tenant/kol/packages/:id              -- 包详情（含 prompt 列表，不含 prompt_content）
POST   /api/tenant/kol/packages/:id/subscribe    -- 申请订阅
GET    /api/tenant/kol/subscriptions             -- 我的订阅列表
```

### 7.2 KOL 生成（已订阅用户）

```
GET    /api/tenant/kol/prompts/:id/schema        -- 获取 prompt 的 variables_schema（不含 prompt_content）
POST   /api/tenant/kol/prompts/:id/generate      -- 提交生成（body: variables 对象）
```

### 7.3 KOL 管理（仅 KOL 角色）

```
GET    /api/tenant/kol/manage/packages           -- 我的包列表
POST   /api/tenant/kol/manage/packages           -- 创建包
PUT    /api/tenant/kol/manage/packages/:id       -- 更新包
DELETE /api/tenant/kol/manage/packages/:id       -- 删除包（软删除）

GET    /api/tenant/kol/manage/packages/:id/prompts       -- 包内 prompt 列表（含 prompt_content）
POST   /api/tenant/kol/manage/packages/:id/prompts       -- 创建 prompt
PUT    /api/tenant/kol/manage/prompts/:id                -- 更新 prompt
DELETE /api/tenant/kol/manage/prompts/:id                -- 删除 prompt

POST   /api/tenant/kol/manage/prompts/ai-generate        -- AI 辅助生成 prompt
POST   /api/tenant/kol/manage/prompts/ai-optimize        -- AI 辅助优化 prompt
```

### 7.4 KOL 看板（仅 KOL 角色）

```
GET    /api/tenant/kol/dashboard/overview        -- 总体指标
GET    /api/tenant/kol/dashboard/packages        -- 按包维度统计
GET    /api/tenant/kol/dashboard/trend           -- 趋势数据（query: period=7d/30d/90d）
```

### 7.5 Workspace 集成

```
GET    /api/tenant/workspace/template-cards      -- 现有接口，扩展返回已订阅的 KOL 包卡片
```

---

## 8. 前端关键组件

| 组件 | 说明 |
|------|------|
| `KolMarketplaceView.vue` | 模版市场页面，卡片网格 + 筛选 |
| `KolPackageDetailView.vue` | 包详情，prompt 列表 + 订阅操作 |
| `KolGenerateView.vue` | 动态表单生成页面 |
| `KolManageView.vue` | KOL 包和 prompt 管理 |
| `KolPromptEditor.vue` | 核心组件：三栏 prompt 编辑器 |
| `KolVariablePanel.vue` | 左侧变量组件拖拽面板 |
| `KolVariableConfig.vue` | 右侧变量配置面板 |
| `KolDynamicForm.vue` | 根据 variables_schema 渲染动态表单（用户端 + 预览） |
| `KolDashboardView.vue` | KOL 数据看板 |
| `KolPackageCard.vue` | 市场/Workspace 中的订阅包卡片组件 |

---

## 9. 权限与角色

### 9.1 角色判断

- `platform_user_roles` 表中 `platform_role = 'kol'` 标识 KOL 用户
- 前端通过 `userInfo.permissions` 或单独 API 判断当前用户是否为 KOL
- KOL 工作台导航分组根据角色动态显示/隐藏

### 9.2 路由守卫

- `/kol/manage` 和 `/kol/dashboard`：前端路由守卫 + 后端 API 鉴权，仅 KOL 可访问
- `/kol/generate/:promptId`：后端校验订阅状态

### 9.3 API 鉴权

- `/api/tenant/kol/manage/*`：中间件校验 KOL 角色
- `/api/tenant/kol/prompts/:id/generate`：校验订阅有效性
- `/api/tenant/kol/dashboard/*`：校验 KOL 角色

---

## 10. i18n

在 `zh-CN.ts` 和 `en-US.ts` 中新增 `kol` 命名空间：

```
kol.marketplace.title          -- 模版市场 / KOL Marketplace
kol.marketplace.filter.*       -- 筛选相关
kol.package.subscribe          -- 申请订阅
kol.package.subscribed         -- 已订阅
kol.package.pending            -- 审核中
kol.generate.title             -- 生成文章
kol.generate.submit            -- 提交生成
kol.manage.title               -- 提示词管理
kol.manage.createPackage       -- 创建订阅包
kol.manage.editor.*            -- 编辑器相关
kol.dashboard.title            -- 数据看板
kol.dashboard.totalSubs        -- 总订阅数
kol.dashboard.monthSubs        -- 本月新增
kol.dashboard.totalUsage       -- 总使用次数
kol.dashboard.monthUsage       -- 本月使用
nav.kolMarketplace             -- 模版市场
nav.kolManage                  -- 提示词管理
nav.kolDashboard               -- 数据看板
status.sourceType.kol          -- KOL 生成
```

---

## 11. 与现有系统的集成点

| 现有模块 | 集成方式 |
|---------|---------|
| articles 表 | 新增 `source_type = "kol"` + `kol_prompt_id` 字段 |
| generation_tasks 表 | 新增 `task_type = "kol"` |
| 文章生成管道 | 复用 generation_tasks → worker → article_versions 流程 |
| platform_user_roles | 新增 `platform_role = "kol"` |
| template_assist_tasks | AI 辅助编写 prompt 复用此异步任务机制 |
| AppShell.vue navSections | 新增 2 个导航分组 |
| WorkspaceView.vue | 卡片区扩展显示已订阅 KOL 包 |
| TemplatesView.vue picker | 模版选择器 modal 中可展示已订阅 KOL 包 |
| display.ts getSourceTypeLabel | 新增 `"kol"` 分支 |
| shared-types | 新增 KOL 相关 TypeScript 接口 |

---

## 12. 第一版范围与不做的事

### 第一版做

- KOL 角色标识
- 订阅包 CRUD + 发布/下架
- Prompt 编辑器（变量拖拽 + AI 辅助）
- 模版市场浏览/筛选
- 申请订阅 + 管理员手动绑定开通
- 动态表单 → 文章生成
- KOL 数据看板（基础指标 + 趋势）
- Workspace 和模版选择器集成
- i18n 中英文支持

### 第一版不做

- 在线支付（用申请 + 管理员审批代替）
- 收益计算和提现
- Prompt 版本历史管理
- KOL 申请入驻流程（由管理员手动分配角色）
- 订阅包评价/评分系统
- Prompt A/B 测试