From 33f1121633fb1b845057f2103b1b17e23d43b99e Mon Sep 17 00:00:00 2001 From: liangxu Date: Thu, 16 Apr 2026 22:08:50 +0800 Subject: [PATCH] docs: add KOL feature design spec Co-Authored-By: Claude Opus 4.6 (1M context) --- .../specs/2026-04-16-kol-feature-design.md | 485 ++++++++++++++++++ 1 file changed, 485 insertions(+) create mode 100644 docs/superpowers/specs/2026-04-16-kol-feature-design.md diff --git a/docs/superpowers/specs/2026-04-16-kol-feature-design.md b/docs/superpowers/specs/2026-04-16-kol-feature-design.md new file mode 100644 index 0000000..14bd95f --- /dev/null +++ b/docs/superpowers/specs/2026-04-16-kol-feature-design.md @@ -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 测试