486 lines
16 KiB
Markdown
486 lines
16 KiB
Markdown
# 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 测试
|