root/geo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add KOL feature design spec

Browse Source 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
liangxu
2026-04-16 22:08:50 +08:00
parent ed10fd82e6
commit 33f1121633
1 changed files with 485 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/superpowers/specs/2026-04-16-kol-feature-design.md
+485
View File
@@ -0,0 +1,485 @@
# 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 测试