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

docs: revise KOL spec v2 — align with existing prompt sharing architecture

Browse Source 
Addresses all critical findings from review:
- KOL identity via prompt_share_profiles, not platform_role
- Prompts stored as sealed article_templates, not parallel system
- Platform-level packages with proper API path separation
- Generation pipeline integrated with existing tx/quota/idempotency
- Variable model with immutable IDs and version snapshots
- Independent kol_assist_tasks table (decoupled from template_assist_tasks)
- Complete resource lifecycle and auth chain
- Consistent tenant-level subscription entity

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
liangxu
2026-04-16 22:24:11 +08:00
parent 33f1121633
commit 6b2810fc74
1 changed files with 385 additions and 253 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/superpowers/specs/2026-04-16-kol-feature-design.md
+385 -253
View File
@@ -1,20 +1,34 @@
# KOL 功能设计文档
# KOL 功能设计文档（v2 — 对齐既有架构）
> **本文档是对 `geo-platform-ops-admin-tech-architecture-v1.md` §6.2.4 / §13.11.2 既有 KOL/Prompt 分享架构的补全**，在其基础上新增"市场浏览 → 订阅 → 生成"用户流程、KOL 提示词管理工作台、数据看板三层能力。不取代也不重复既有模型。
## 概述
为 GEO 工具平台新增 KOL（Key Opinion Leader）功能模块。KOL 是平台中的超级用户角色——拥有普通用户的全部功能，同时可以创建、管理精调 prompt 订阅包，供其他用户付费订阅使用。平台记录订阅和使用数据，后续用于给 KOL 结算。
为 GEO 工具平台新增 KOL 功能模块。KOL 是平台中的超级用户——拥有普通用户的全部功能，同时可以创建、管理精调 prompt 订阅包，供其他租户订阅使用。平台记录订阅和使用数据，后续用于给 KOL 结算。
### 核心概念
- **KOL 用户**：拥有 `platform_role = "kol"` 的用户，具备普通用户全部权限 + 提示词管理 + 数据看板
- **订阅包（Package）**：KOL 发布的一组精调 prompt 的集合，面向某个行业/场景（如"家具行业精调包"）
- **Prompt**：包内的具体提示词，适配不同平台或版本（如"豆包版友好"、"DeepSeek版"、"精调2025.4.16版"）
- **动态表单**：每个 prompt 由 KOL 定义用户需要填写的变量（公司名、竞品等），prompt 内容对用户不可见
- **订阅**：用户通过申请订阅获取 KOL 包的使用权，管理员审批或手动绑定开通，第一版不做支付
- **KOL 身份**：通过既有 `prompt_share_profiles` 建模（`kol_profile`），**不是 RBAC 权限角色**，不参与 `platform_role` 鉴权（参见架构文档 §6.2.4）
- **订阅包（Package）**：KOL 发布的一组 sealed prompt 的集合，面向某个行业/场景（如"家具行业精调包"）
- **Prompt**：包内的具体提示词，存储为 `article_templates`（`scope='kol_package'`, `prompt_visibility='sealed'`, `origin_type='kol_authored'`），通过 `protected_prompt_asset_key` 保护原文
- **动态表单**：每个 prompt 由 KOL 定义变量槽位（`schema_json`），用户填写后替换生成，prompt 内容对用户不可见
- **订阅**：租户级别（tenant）订阅 KOL 包，第一版通过申请 + 管理员审批/手动绑定，不做支付
- **导入物化**：租户订阅后，包内 prompt 通过 `prompt_share_codes` 机制物化为租户自己的 `article_templates`（`origin_type='kol_share'`, `share_code_id` 关联），与既有分享码导入流程一致
### 实现策略
采用**渐进式集成**方案：KOL 作为现有系统的扩展层，复用已有的 article、generation_tasks 基础设施，新增 KOL 相关数据表和页面。改动最小，风险最低。
在既有 `prompt_share_profiles` → `prompt_share_codes` → `article_templates` 体系上扩展，新增"订阅包"聚合层和"市场/看板"展示层。生成链路完全复用现有事务/幂等/额度闭环。
### 与既有架构的关系
| 既有概念 | 本次扩展 |
|---------|---------|
| `prompt_share_profiles` — KOL 身份 | 复用，新增 `share_enabled` 条件控制市场可见性 |
| `prompt_share_codes` — 分享码 | 复用，订阅激活后自动为包内每个 prompt 生成分享码 |
| `article_templates`（sealed prompt） | 复用，KOL 原始 prompt 存储为 `scope='kol_package'` 的模板 |
| `article_templates`（导入后物化） | 复用，订阅方租户内物化为 `origin_type='kol_share'` 的模板 |
| 生成链路（事务/额度/幂等） | 完全复用，`source_type='kol'` 走同一管道 |
| `template_assist_tasks` | **不复用**，新建 `kol_assist_tasks` 表，解耦 `template_id` 强依赖 |
---
@@ -22,81 +36,50 @@
### 1.1 新增表
#### kol_packages — 订阅包
#### 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
id BIGSERIAL PRIMARY KEY,
profile_id BIGINT NOT NULL REFERENCES prompt_share_profiles(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_profile ON kol_packages(profile_id) WHERE deleted_at IS NULL;
CREATE INDEX idx_kol_packages_status ON kol_packages(status) WHERE deleted_at IS NULL;
```
#### kol_prompts — KOL 提示词
**设计要点**：
- `profile_id` 关联 `prompt_share_profiles`（KOL 身份），不直接关联 `users.id`
- **无 `tenant_id`**：订阅包是平台级资源，不属于任何租户。API 走 `/api/platform/kol/*` 路径（KOL 身份鉴权），不走 `/api/tenant/*`
#### kol_package_templates — 包与模板关联
```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 TABLE kol_package_templates (
id BIGSERIAL PRIMARY KEY,
package_id BIGINT NOT NULL REFERENCES kol_packages(id),
template_id BIGINT NOT NULL REFERENCES article_templates(id),
sort_order INT NOT NULL DEFAULT 0,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE INDEX idx_kol_prompts_package ON kol_prompts(package_id);
CREATE UNIQUE INDEX uk_kol_pkg_tpl ON kol_package_templates(package_id, template_id);
```
**variables_schema 格式**（变量 key 默认中文，也支持英文）：
**设计要点**：
- KOL 的 prompt 存储在既有 `article_templates` 表中（`scope='kol_package'`, `prompt_visibility='sealed'`, `origin_type='kol_authored'`）
- 本表只做包→模板的聚合关联，一个包包含多个 sealed template
- `schema_json` 中的变量槽位定义直接复用 `article_templates.schema_json`
```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 — 订阅关系
#### kol_subscriptions — 租户级订阅关系
```sql
CREATE TABLE kol_subscriptions (
@@ -110,63 +93,200 @@ CREATE TABLE kol_subscriptions (
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');
CREATE UNIQUE INDEX uk_kol_sub_active ON kol_subscriptions(tenant_id, package_id)
WHERE status IN ('pending', 'active');
```
**设计要点**：
- 订阅主体是 **tenant**，不是 user。文案、审批、权限、结算全部以 tenant 为口径
- 订阅激活（`pending → active`）时，自动为包内每个 active template 生成 `prompt_share_codes` 记录，并物化为订阅方租户的 `article_templates`（`origin_type='kol_share'`, `share_code_id` 关联）
#### 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()
id BIGSERIAL PRIMARY KEY,
package_id BIGINT NOT NULL REFERENCES kol_packages(id),
source_template_id BIGINT NOT NULL REFERENCES article_templates(id),
tenant_id BIGINT NOT NULL REFERENCES tenants(id),
article_id BIGINT REFERENCES articles(id),
generation_task_id BIGINT REFERENCES generation_tasks(id),
template_version_no INT NOT NULL,
variables_snapshot JSONB,
schema_snapshot JSONB,
rendered_prompt_hash VARCHAR(64),
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);
```
**设计要点**：
- `source_template_id` 指向 KOL 原始 template（`scope='kol_package'`），不是订阅方物化的副本
- `template_version_no`：记录使用时的模板版本号，确保历史可复现
- `schema_snapshot`：记录使用时的 `schema_json` 快照，KOL 后续修改不影响历史记录
- `rendered_prompt_hash`：变量替换后的最终 prompt 的 SHA-256，用于幂等去重和结算审计
- `generation_task_id`：关联到 `generation_tasks`，闭合与额度系统的追溯链
#### kol_assist_tasks — KOL AI 辅助任务
```sql
CREATE TABLE kol_assist_tasks (
id VARCHAR(64) PRIMARY KEY,
profile_id BIGINT NOT NULL REFERENCES prompt_share_profiles(id),
tenant_id BIGINT NOT NULL REFERENCES tenants(id),
task_type VARCHAR(50) NOT NULL, -- ai_generate / ai_optimize
template_id BIGINT REFERENCES article_templates(id),
status VARCHAR(20) NOT NULL DEFAULT 'queued',
request_json JSONB NOT NULL DEFAULT '{}'::jsonb,
result_json JSONB,
error_message TEXT,
started_at TIMESTAMPTZ,
completed_at TIMESTAMPTZ,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE INDEX idx_kol_assist_profile ON kol_assist_tasks(profile_id, created_at DESC);
CREATE INDEX idx_kol_assist_status ON kol_assist_tasks(status, created_at DESC);
```
**设计要点**：
- 独立于 `template_assist_tasks`，解耦 `template_id` 强依赖（`template_id` 此处可为 NULL，AI 生成新 prompt 时还没有 template）
- `tenant_id` 用于 AI 模型费用归属（结算记到 KOL 所在的 tenant）
- `profile_id` 关联 KOL 身份，鉴权走 KOL 身份校验
### 1.2 现有表变更
#### article_templates 表
新增字段值（不改表结构）：
- `scope = 'kol_package'`：KOL 原始 prompt 模板
- `origin_type = 'kol_authored'`：KOL 创作的原始模板
- `origin_type = 'kol_share'`：订阅方物化的副本（已有设计，参见架构文档 §13.11.2 line 1330）
- `prompt_visibility = 'sealed'`：prompt 正文服务端只读，前端不返回（已有设计）
#### articles 表
新增字段：
- `kol_prompt_id BIGINT REFERENCES kol_prompts(id)` — 关联使用的 KOL prompt
新增 `source_type` 值：`"kol"`
（`template_id` 字段已存在，指向订阅方物化后的 article_template）
#### generation_tasks 表
新增 `task_type` 值：`"kol"`
`input_params_json` 存储用户填入的变量值：
`input_params_json` 存储：
```json
{
"kol_prompt_id": 42,
"source_template_id": 42,
"template_version_no": 3,
"variables": {
"公司名称": "宜家家居",
"行业": "家具",
"主要竞品": "全友、顾家",
"月预算": 50
}
},
"schema_snapshot": [...],
"rendered_prompt_hash": "a1b2c3d4..."
}
```
#### platform_user_roles 表
新增 `platform_role` 值：`"kol"`
**幂等键**：`tenant_id + source_type('kol') + request_hash(rendered_prompt_hash) + schedule_slot(null)`，与既有幂等体系一致。
---
## 2. 页面结构与路由
## 2. 生成链路（对齐既有事务/额度闭环）
### 2.1 侧边栏导航变更
严格遵循架构文档 §10.1 和 §13.7.3 的事务边界：
在现有 `navSections`（AppShell.vue）中新增两个分组：
### 2.1 提交路径（单 PostgreSQL 事务）
1. 校验租户身份、订阅有效性（package active + subscription active + 有效期内 + prompt active + package published）
2. 从 KOL 原始 template 读取 `prompt_content`（`protected_prompt_asset_key` 解密）
3. 变量替换，计算 `rendered_prompt_hash`
4. **单事务内**：
- 额度预扣（`quota_reservations`）
- 创建 `generation_tasks`（`task_type='kol'`, `request_hash=rendered_prompt_hash`）
- 创建 `articles` 占位记录（`source_type='kol'`, `template_id` 指向物化副本）
- 写入 `kol_usage_logs`（`status` 为 pending，关联 `generation_task_id`）
5. 事务提交后写入 RabbitMQ
### 2.2 成功路径（单 PostgreSQL 事务）
- 写入 `article_versions`
- 更新 `articles.generate_status = 'completed'`
- 确认额度消耗
- 更新 `kol_usage_logs`（关联 `article_id`）
### 2.3 失败路径（单 PostgreSQL 事务）
- 更新 `generation_tasks.status = 'failed'`
- 额度退还/释放
- 不写入 `kol_usage_logs`（或标记为 failed）
---
## 3. 变量模型（不可变 ID + 版本快照）
### 3.1 schema_json 格式
复用 `article_templates.schema_json`，变量 key 默认中文，也支持英文：
```json
{
"variables": [
{
"id": "var_a1b2c3",
"key": "公司名称",
"label": "公司名称",
"type": "input",
"required": true,
"placeholder": "请输入您的公司名"
},
{
"id": "var_d4e5f6",
"key": "行业",
"label": "行业",
"type": "select",
"options": ["家具", "建材", "家电"],
"required": true
},
{
"id": "var_g7h8i9",
"key": "主要竞品",
"label": "主要竞品",
"type": "textarea",
"required": false
},
{
"id": "var_j0k1l2",
"key": "月预算",
"label": "月预算(万)",
"type": "number",
"required": false
}
]
}
```
**设计要点**：
- 每个变量有**不可变 `id`**（`var_` + nanoid），KOL 修改 key/label 时 id 不变
- prompt 模板内部按 `{{id}}` 引用（如 `{{var_a1b2c3}}`），编辑器显示为 `{{公司名称}}`
- 用户表单根据 `label` 显示，提交时按 `id` 映射值
- 修改 key/label 不会导致旧 prompt 失效
- 支持的 type 值：`input`、`textarea`、`select`、`number`、`checkbox`
### 3.2 版本快照策略
- `article_templates.version_no` 每次 KOL 保存时递增
- 生成时记录 `template_version_no` + `schema_snapshot` 到 `generation_tasks.input_params_json` 和 `kol_usage_logs`
- 历史生成任务可完整复现：哪个版本的 prompt + 哪个版本的 schema + 什么变量值 → 什么 hash
---
## 4. 页面结构与路由
### 4.1 侧边栏导航变更
```
现有导航:
@@ -178,68 +298,143 @@ CREATE INDEX idx_kol_usage_tenant ON kol_usage_logs(tenant_id, created_at DESC);
新增:
KOL 市场: 模版市场 ← 所有用户可见
KOL 工作台: 提示词管理 | 数据看板 ← 仅 KOL 角色可见
KOL 工作台: 提示词管理 | 数据看板 ← 仅 kol_profile.share_enabled=true 的用户可见
```
"KOL 工作台" 分组根据用户 permissions 或 platform_role 动态显示/隐藏。
"KOL 工作台" 根据 `prompt_share_profiles.share_enabled` 动态显示/隐藏，不走 RBAC。
### 2.2 新增路由
### 4.2 新增路由
| 路由 | 组件 | 角色 | 说明 |
|------|------|------|------|
| `/kol/marketplace` | KolMarketplaceView | 所有用户 | 浏览/筛选/订阅 KOL 包 |
| `/kol/packages/:id` | KolPackageDetailView | 所有用户 | 包详情 → prompt 列表 → 选择 prompt |
| `/kol/generate/:promptId` | KolGenerateView | 已订阅用户 | 动态表单（填变量）→ 提交生成 |
| `/kol/generate/:promptId` | KolGenerateView | 已订阅租户 | 动态表单（填变量）→ 提交生成 |
| `/kol/manage` | KolManageView | 仅 KOL | 管理订阅包 + AI 辅助编写 prompt |
| `/kol/dashboard` | KolDashboardView | 仅 KOL | 订阅数据统计看板 |
### 2.3 用户入口（3个）
### 4.3 用户入口（3个）
1. **侧边栏「模版市场」**→ 浏览/筛选 → 订阅 → 选 prompt → 表单 → 生成
2. **Workspace 卡片区**：已订阅的包显示为卡片 → 点击 → 选 prompt → 表单 → 生成
3. **模版生成页面**：已订阅的 KOL 包也出现在模版选择器 modal 中
2. **Workspace 卡片区**：已订阅且物化的 KOL 模板显示为卡片 → 点击 → 表单 → 生成
3. **模版生成页面**：物化的 KOL 模板出现在模版选择器 modal 中（`origin_type='kol_share'`）
---
## 3. 普通用户流程
## 5. API 设计
### 3.1 模版市场（KolMarketplaceView）
### 5.1 KOL 市场（所有登录用户，走 tenant API）
- 卡片网格展示所有已发布的 KOL 订阅包
- 筛选：按行业、标签、KOL 名称
- 每张卡片展示：封面、包名、KOL 名称、行业标签、prompt 数量、订阅人数
- 卡片操作：点击进入包详情
```
GET /api/tenant/kol/marketplace/packages -- 市场列表（筛选：industry, tags, keyword）
GET /api/tenant/kol/marketplace/packages/:id -- 包详情（含 prompt 名称列表，不含 prompt_content）
POST /api/tenant/kol/marketplace/packages/:id/subscribe -- 申请订阅（tenant 级）
GET /api/tenant/kol/subscriptions -- 当前租户的订阅列表
```
### 3.2 包详情（KolPackageDetailView）
### 5.2 KOL 生成（已订阅租户，走 tenant API）
- 头部：包名、描述、KOL 信息、行业标签
- 订阅状态区：
- 未订阅 → 显示「申请订阅」按钮（状态变为 pending）
- 待审批 → 显示「审核中」状态
- 已订阅 → 显示有效期
- Prompt 列表：展示包内所有 active prompt，每个显示名称 + 平台标识
- 点击某个 prompt → 跳转到生成页面（需已订阅）
```
GET /api/tenant/kol/prompts/:id/schema -- 获取物化模板的 schema_json（不含 prompt_content）
POST /api/tenant/kol/prompts/:id/generate -- 提交生成（body: variables 对象）
```
### 3.3 动态表单生成（KolGenerateView）
生成接口内部走 §2 的完整事务链路。
- 根据 `kol_prompts.variables_schema` 动态渲染表单
- 支持的字段类型：input、textarea、select、number、checkbox
- 用户填写变量 → 点击「生成文章」
- 后端：变量值替换 prompt 模板中的 `{{key}}` → 调用 LLM → 生成文章
- 生成的文章 `source_type = "kol"`，`kol_prompt_id` 关联对应 prompt
- 同时写入 `kol_usage_logs` 记录
### 5.3 KOL 管理（走 platform API，KOL 身份鉴权）
```
GET /api/platform/kol/packages -- 我的包列表
POST /api/platform/kol/packages -- 创建包
PUT /api/platform/kol/packages/:id -- 更新包
DELETE /api/platform/kol/packages/:id -- 删除包（软删除）
PUT /api/platform/kol/packages/:id/publish -- 发布包
PUT /api/platform/kol/packages/:id/archive -- 下架包
POST /api/platform/kol/packages/:id/templates -- 创建 prompt（创建 sealed article_template + 关联）
PUT /api/platform/kol/templates/:id -- 更新 prompt（递增 version_no）
DELETE /api/platform/kol/templates/:id -- 删除 prompt（软删除 article_template + 移除关联）
POST /api/platform/kol/assist/generate -- AI 辅助生成 prompt
POST /api/platform/kol/assist/optimize -- AI 辅助优化 prompt
```
**鉴权**：中间件校验请求者有 active 的 `prompt_share_profile`，且 `share_enabled=true`。
**资源归属**：管理接口以 `profile_id` 过滤，KOL 只能操作自己的包和 prompt。
**AI 费用**：assist 任务的 `tenant_id` 取 KOL 用户所在租户，费用记到该 tenant。
### 5.4 KOL 看板（走 platform API，KOL 身份鉴权）
```
GET /api/platform/kol/dashboard/overview -- 总体指标
GET /api/platform/kol/dashboard/packages -- 按包维度统计
GET /api/platform/kol/dashboard/trend -- 趋势数据（query: period=7d/30d/90d）
```
### 5.5 管理员操作（走 platform API，platform_role 鉴权）
```
PUT /api/platform/admin/kol/subscriptions/:id/approve -- 审批订阅
POST /api/platform/admin/kol/subscriptions -- 手动绑定开通
PUT /api/platform/admin/kol/subscriptions/:id/revoke -- 撤销订阅
```
### 5.6 Workspace 集成
```
GET /api/tenant/workspace/template-cards -- 现有接口，扩展返回 origin_type='kol_share' 的模板卡片
```
---
## 4. KOL 提示词编辑器（KolManageView）
## 6. 订阅激活流程
### 4.1 包管理
当管理员审批或手动绑定（`status: pending → active`）时：
- 列表展示 KOL 自己创建的所有订阅包
1. 查找 package 内所有 `status='active'` 的 `article_templates`
2. 为每个 template 生成 `prompt_share_codes` 记录（`snapshot_json` 含卡片信息 + 变量槽位，`protected_prompt_asset_key` 引用原始 prompt）
3. 将每个 share_code 物化为订阅方租户的 `article_templates`（`scope='tenant'`, `origin_type='kol_share'`, `share_code_id` 关联, `prompt_visibility='sealed'`）
4. 物化后的模板出现在订阅方的 Workspace 和模版选择器中
KOL 后续新增 prompt 到已发布包时，自动为所有 active 订阅方同步物化。
---
## 7. 资源生命周期
### 7.1 删除策略
| 资源 | 软删除字段 | 删除行为 |
|------|-----------|---------|
| `kol_packages` | `deleted_at` | 软删除，级联将包内所有 template 标记 `status='archived'` |
| `article_templates`（KOL authored） | `deleted_at` | 软删除，同时移除 `kol_package_templates` 关联 |
| `kol_subscriptions` | 无（状态机） | `active → revoked`，不物理删除 |
| `kol_usage_logs` | 无 | 审计数据，不删除 |
### 7.2 生成鉴权完整校验链
用户访问 `/kol/generate/:promptId` 时，后端必须逐项校验：
1. 物化 template 存在且 `deleted_at IS NULL`
2. 物化 template 的 `share_code_id` 关联的 `prompt_share_codes.status = 'active'`
3. 对应的 `kol_packages.status = 'published'` 且 `deleted_at IS NULL`
4. 租户有该 package 的 `kol_subscriptions.status = 'active'`
5. 订阅在有效期内（`start_at <= now() <= end_at`）
6. 原始 template `status = 'active'`
任一不满足返回 403。
---
## 8. KOL 提示词编辑器（KolManageView）
### 8.1 包管理
- 列表展示 KOL 自己创建的所有订阅包（按 `profile_id` 过滤）
- 创建/编辑包：名称、描述、封面、行业、标签、定价说明
- 包状态管理：草稿 → 发布 → 下架
- 包状态管理：draft → published → archived
### 4.2 Prompt 编辑器（核心组件）
### 8.2 Prompt 编辑器（核心组件）
**三栏布局：**
@@ -251,134 +446,87 @@ CREATE INDEX idx_kol_usage_tenant ON kol_usage_logs(tenant_id, created_at DESC);
- 顶部 AI 辅助栏：
- AI 生成：KOL 描述需求 → AI 生成完整 prompt 模板（含变量）
- AI 优化：选中现有 prompt → AI 优化措辞/结构
- 复用现有 `template_assist_tasks` 异步任务机制
- 编辑区：支持富文本编辑，变量以彩色标签形式内联展示（如 `{{公司名称}}`）
- 操作栏：预览表单、保存草稿、发布
- 通过 `kol_assist_tasks` 异步执行
- 编辑区：变量以彩色标签形式内联展示（显示 `{{公司名称}}`，内部存储 `{{var_a1b2c3}}`）
- 操作栏：预览表单、保存草稿（递增 `version_no`）、发布
- **右栏 — 变量配置面板（260px）**：
- 展示所有已添加的变量卡片
- 点击可编辑：key、显示名（label）、类型、是否必填、提示语、选项列表
- 变量 key 默认 = 显示名（中文），也支持手动改为英文
- 可编辑：key（默认中文）、显示名（label）、类型、必填、提示语、选项列表
- 修改 key/label 不影响 `id`，不会破坏已有 prompt 引用
### 4.3 拖拽交互流程
### 8.3 拖拽交互流程
1. KOL 从左侧面板拖一个组件到编辑区光标位置
2. 弹出配置弹窗：填写变量 key（默认中文）、显示名、必填、提示语/选项
3. 确认后：编辑区插入 `{{key}}` 占位符标签 + 右侧面板出现配置卡片
4. 后续可在右侧面板修改配置，编辑区标签同步更新
2. 弹出配置弹窗：填写显示名（默认中文，自动同步为 key）、必填、提示语/选项
3. 确认后：系统分配不可变 `id`（`var_` + nanoid），编辑区插入 `{{显示名}}` 标签（内部 `{{id}}`），右侧出现配置卡片
4. 后续修改 key/label 时，编辑区标签同步更新显示，但底层 `{{id}}` 不变
### 4.4 Prompt 内容保护
### 8.4 Prompt 内容保护
- `prompt_content` 只存储在服务端
- 原始 prompt 通过 `protected_prompt_asset_key` 存储为受保护资产（与既有 sealed prompt 机制一致）
- 面向普通用户的 API 永远不返回 prompt 原文
- 用户端只获取 `variables_schema`（表单定义）用于渲染表单
- 用户端只获取 `schema_json`（变量槽位定义）用于渲染表单
- KOL 管理 API（`/api/platform/kol/*`）可读取原文，仅限 KOL 本人
---
## 5. KOL 数据看板（KolDashboardView）
## 9. KOL 数据看板（KolDashboardView）
### 5.1 数据指标
### 9.1 数据指标
- **总订阅数**：所有包的 active 订阅总数
- **总订阅租户数**：所有包的 active 订阅租户总数（去重）
- **本月新增订阅**：当月新增 active 订阅
- **总使用次数**：所有 prompt 被使用生成文章的总次数
- **本月使用次数**：当月使用次数
### 5.2 按包维度
### 9.2 按包维度
- 每个包的订阅用户数、使用次数
- 每个包的订阅租户数、使用次数
- 包内各 prompt 的使用次数排行
### 5.3 趋势图
### 9.3 趋势图
- 订阅数随时间变化趋势
- 使用次数随时间变化趋势
### 5.4 数据来源
### 9.4 数据来源
- 订阅数据：查询 `kol_subscriptions` 表
- 订阅数据：查询 `kol_subscriptions` 表（以 tenant 为统计口径）
- 使用数据：查询 `kol_usage_logs` 表
- 后续扩展：收益计算、结算报表
- 后续扩展：收益计算、结算报表（基于 `rendered_prompt_hash` 做结算审计）
---
## 6. 订阅管理
## 10. 普通用户流程
### 6.1 用户申请订阅
### 10.1 模版市场（KolMarketplaceView）
- 用户在包详情页点击「申请订阅」
- 创建 `kol_subscriptions` 记录，`status = 'pending'`
- 后续管理员审批
- 卡片网格展示所有 `status='published'` 的 KOL 订阅包
- 筛选：按行业、标签、KOL 名称
- 每张卡片展示：封面、包名、KOL 显示名、行业标签、prompt 数量、订阅租户数
- 卡片操作：点击进入包详情
### 6.2 管理员操作
### 10.2 包详情（KolPackageDetailView）
第一版通过现有平台管理机制处理：
- 审批待处理的订阅申请（pending → active）
- 手动绑定开通：管理员直接创建 `status = 'active'` 的订阅记录
- 撤销订阅（active → revoked）
- 头部：包名、描述、KOL 信息、行业标签
- 订阅状态区：
- 未订阅 → 显示「申请订阅」按钮（tenant 级，状态变为 pending）
- 待审批 → 显示「审核中」状态
- 已订阅 → 显示有效期
- Prompt 列表：展示包内所有 active prompt 的名称 + 平台标识（不含 prompt 内容）
- 点击某个 prompt → 跳转到生成页面（需已订阅）
### 6.3 订阅鉴权
### 10.3 动态表单生成（KolGenerateView）
- 用户访问 `/kol/generate/:promptId` 时，后端检查：
1. prompt 所属 package 是否存在
2. 用户 tenant 是否有该 package 的 active 订阅
3. 订阅是否在有效期内
- 不满足则返回 403
- 根据物化模板的 `schema_json.variables` 动态渲染表单
- 支持的字段类型：input、textarea、select、number、checkbox
- 用户填写变量 → 点击「生成文章」
- 走 §2 的完整事务链路
---
## 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. 前端关键组件
## 11. 前端关键组件
| 组件 | 说明 |
|------|------|
@@ -389,34 +537,35 @@ GET /api/tenant/workspace/template-cards -- 现有接口，扩展返回
| `KolPromptEditor.vue` | 核心组件：三栏 prompt 编辑器 |
| `KolVariablePanel.vue` | 左侧变量组件拖拽面板 |
| `KolVariableConfig.vue` | 右侧变量配置面板 |
| `KolDynamicForm.vue` | 根据 variables_schema 渲染动态表单（用户端 + 预览） |
| `KolDynamicForm.vue` | 根据 schema_json 渲染动态表单（用户端 + 预览） |
| `KolDashboardView.vue` | KOL 数据看板 |
| `KolPackageCard.vue` | 市场/Workspace 中的订阅包卡片组件 |
---
## 9. 权限与角色
## 12. 权限与鉴权
### 9.1 角色判断
### 12.1 KOL 身份判断
- `platform_user_roles` 表中 `platform_role = 'kol'` 标识 KOL 用户
- 前端通过 `userInfo.permissions` 或单独 API 判断当前用户是否为 KOL
- KOL 工作台导航分组根据角色动态显示/隐藏
- 通过 `prompt_share_profiles` 表判断，`share_enabled = true` 且 `status = 'active'`
- **不走 RBAC**，不在 `platform_user_roles` 中添加 KOL 角色
- 前端通过 user info API 返回的 `kol_profile` 字段判断是否展示工作台
### 9.2 路由守卫
### 12.2 API 路径分离
- `/kol/manage` 和 `/kol/dashboard`：前端路由守卫 + 后端 API 鉴权，仅 KOL 可访问
- `/kol/generate/:promptId`：后端校验订阅状态
| 路径前缀 | 鉴权方式 | 适用场景 |
|---------|---------|---------|
| `/api/tenant/kol/*` | 标准 tenant 身份 | 市场浏览、订阅、生成（带 tenant scope） |
| `/api/platform/kol/*` | KOL profile 身份 | 包管理、prompt 编辑、AI 辅助、看板 |
| `/api/platform/admin/kol/*` | platform_role 鉴权 | 管理员审批/绑定订阅 |
### 9.3 API 鉴权
### 12.3 生成鉴权
- `/api/tenant/kol/manage/*`：中间件校验 KOL 角色
- `/api/tenant/kol/prompts/:id/generate`：校验订阅有效性
- `/api/tenant/kol/dashboard/*`：校验 KOL 角色
见 §7.2 完整校验链。
---
## 10. i18n
## 13. i18n
在 `zh-CN.ts` 和 `en-US.ts` 中新增 `kol` 命名空间：
@@ -432,7 +581,7 @@ kol.manage.title -- 提示词管理
kol.manage.createPackage -- 创建订阅包
kol.manage.editor.* -- 编辑器相关
kol.dashboard.title -- 数据看板
kol.dashboard.totalSubs -- 总订阅数
kol.dashboard.totalSubs -- 总订阅租户数
kol.dashboard.monthSubs -- 本月新增
kol.dashboard.totalUsage -- 总使用次数
kol.dashboard.monthUsage -- 本月使用
@@ -444,42 +593,25 @@ 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. 第一版范围与不做的事
## 14. 第一版范围与不做的事
### 第一版做
- KOL 角色标识
- KOL 身份（复用 `prompt_share_profiles`）
- 订阅包 CRUD + 发布/下架
- Prompt 编辑器（变量拖拽 + AI 辅助）
- Prompt 编辑器（变量拖拽 + 不可变 ID + AI 辅助）
- 模版市场浏览/筛选
- 申请订阅 + 管理员手动绑定开通
- 动态表单 → 文章生成
- KOL 数据看板（基础指标 + 趋势）
- 租户级申请订阅 + 管理员审批/手动绑定 + 物化到订阅方
- 动态表单 → 文章生成（完整事务/额度/幂等闭环）
- 使用记录含版本快照 + prompt hash
- KOL 数据看板（基础指标 + 趋势，以 tenant 为统计口径）
- Workspace 和模版选择器集成
- i18n 中英文支持
### 第一版不做
- 在线支付（用申请 + 管理员审批代替）
- 收益计算和提现
- Prompt 版本历史管理
- KOL 申请入驻流程（由管理员手动分配角色）
- 收益计算和提现（数据已埋点，后续可扩展）
- KOL 申请入驻流程（由管理员手动创建 `prompt_share_profiles`）
- 订阅包评价/评分系统
- Prompt A/B 测试