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

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>

docs/superpowers/specs/2026-04-16-kol-feature-design.md

@@ -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,12 +36,12 @@
 
 ### 1.1 新增表
 
-#### kol_packages — 订阅包
+#### kol_packages — 订阅包（平台级资源）
 
 ```sql
 CREATE TABLE kol_packages (
     id                BIGSERIAL PRIMARY KEY,
-    kol_user_id BIGINT NOT NULL REFERENCES users(id),
+    profile_id        BIGINT NOT NULL REFERENCES prompt_share_profiles(id),
     name              VARCHAR(200) NOT NULL,
     description       TEXT,
     cover_url         TEXT,
@@ -39,64 +53,33 @@ CREATE TABLE kol_packages (
     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 (
+CREATE TABLE kol_package_templates (
     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 '[]',  -- 动态表单定义
+    template_id     BIGINT NOT NULL REFERENCES article_templates(id),
     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()
+    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),
+    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 测试