16 KiB
16 KiB
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 — 订阅包
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 提示词
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 默认中文，也支持英文）：
[
{
"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 — 订阅关系
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 — 使用记录
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 存储用户填入的变量值：
{
"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个）
- 侧边栏「模版市场」→ 浏览/筛选 → 订阅 → 选 prompt → 表单 → 生成
- Workspace 卡片区：已订阅的包显示为卡片 → 点击 → 选 prompt → 表单 → 生成
- 模版生成页面：已订阅的 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异步任务机制
- 编辑区：支持富文本编辑，变量以彩色标签形式内联展示（如
{{公司名称}}） - 操作栏：预览表单、保存草稿、发布
- 顶部 AI 辅助栏：
-
右栏 — 变量配置面板（260px）：
- 展示所有已添加的变量卡片
- 点击可编辑：key、显示名（label）、类型、是否必填、提示语、选项列表
- 变量 key 默认 = 显示名（中文），也支持手动改为英文
4.3 拖拽交互流程
- KOL 从左侧面板拖一个组件到编辑区光标位置
- 弹出配置弹窗：填写变量 key（默认中文）、显示名、必填、提示语/选项
- 确认后：编辑区插入
{{key}}占位符标签 + 右侧面板出现配置卡片 - 后续可在右侧面板修改配置，编辑区标签同步更新
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时，后端检查：- prompt 所属 package 是否存在
- 用户 tenant 是否有该 package 的 active 订阅
- 订阅是否在有效期内
- 不满足则返回 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 测试