beige/Clover架构方案.md

Clover 🍀 · 统一产品技术架构方案

项目代号：Clover（三叶草） —— 取"种草"之意，接小红书业务 + 倩倩姐设计稿的小草视觉。 对外正式品牌名待定，开发期用此代号。 版本：v0.3（7洞对齐版，2026-06-04） —— 经9-agent团队5轮审核(R1多维独立+R2挑刺+R3交叉验证+R4一致性+R5汇总)，对齐06-04的7洞决策，修复13处脱节/漏洞 受众：产品负责人（可读）+ 开发团队（可落地） 关联：[../banana复用评估.md] [../产品架构蓝图.md] [../前端交互设计.md] [../采集框架.md] [test/各洞验证落盘.md]

v0.3修订摘要：M1标杆采集定性(对外截图手填) / M2 Celery不传key(修安全矛盾) / M3去水印+达人素材交付包 / M4文案双轨+可调prompt / M5 delivery_packages表 / M6 token-url收口自家站 / M7软件MVP免费 / M8违禁词三级处理+banned_words表 / M9飞轮权重填定 / M10偏好表data_ownership字段 / M11 JWT表述工程化 / M12-13可选优化

---

〇、一句话定性

一座"小红书内容工厂"：北哥是第一个车间，将来郑州客户来了直接开新车间，互不干扰。 核心差异化 = 偏好飞轮（越用越懂你的"老师傅"）。技术底座复用 banana 半成品，但新建干净仓库抽离。

---

〇.5、基石约束（不可动摇，违反即返工）

经两轮外部AI审核 + 两轮自校验，沉淀出以下铁律。任何代码/设计违反这些 = 必须返工。

A. "凡业务参数，一律不写死"（最高原则）

• 品类不写死：预置素颜霜/精华/面膜 + 客户自助上传新品类(source区分)，代码和prompt禁止出现品类枚举
• 生成数量不写死：文案出几条、图出几张，由用户自己设定。飞轮信号强弱随用户设定走(设10选3=强信号，设3选1=弱信号)，系统不锁死
• 文案角度不写死：痛点/成分/场景等角度跟着产品走，或引导客户自己输入，落进产品档案当可配置项
• 判断标准：任何"看起来像枚举/常量"的业务概念，先问"客户会不会想改？"会→做成数据不做成代码

B. 安全铁律（API Key）

• 明文key绝不进Celery参数(Redis broker会存)。Celery只传task_id，worker内部查库→解密→调模型，明文只在函数局部变量
• key用Fernet加密存MySQL；解密用的FERNET_KEY走环境变量/密钥管理，绝不进代码库(锁和钥匙不放一起)
• key解密不落盘、不打日志
• 每账号自录自用，按key各算各的，禁止合并站级key混算

C. 多租户隔离

• workspace_id 逻辑隔离(同一MySQL用workspace_id强制过滤)，不是物理隔离(暂不做每客户独立DB)
• JWT放user_id/current_workspace_id/role当加速字段，但所有写操作+切换workspace必须查 workspace_members 校验当前权限(读操作可信JWT加速)

D. 采集↔生产接缝不能断（漏洞C）

• 采集框架里北哥团队填的"好图标准/好坏样本/质检标准"等人工判断标准，必须在Clover里有落点：进系统→帮组长审核→最终蒸馏成AI审核员
• 这是采集层和生产层的接缝，设计时必须打通，不能让采集成果悬空

E. 飞轮验收必须可测（不靠"感觉更准"）

• events正确写入 ✓ / aggregator返回明确prompt片段 ✓ / 下次Gemini prompt trace含该片段 ✓ / UI显示"本次已注入:最近偏好/打回原因" ✓
• 四点全过才算飞轮MVP达标

F. 文档诚实

• 不放"N个agent生成"这类AI背书；用工程化表述(JWT签名防篡改/短期有效/关键接口查membership)，不用"写死不可伪造"这种话

---

一、整体架构总览

分层（从上到下）

浏览器(Next.js)
  熟手：选题→看生成→8选3文案→挑图→提审
  组长：看审核队列→通过/打回(写原因)
  管理员：维护品牌库/标杆/成员
        │ HTTPS/SSE(流式推进度)
FastAPI(API层)
  认证：JWT(含workspace_id+role，HS256签名防篡改、每请求验签)
  权限：读操作凭JWT加速；写操作+切换workspace必须查workspace_members校验权限(逻辑隔离)
  Key解密：Fernet解密，只在worker内存活，不落盘
        │ 同步↓        异步↓(推Celery队列)
业务应用层            Celery Worker(后台)
  品牌库管理           ①分析标杆笔记
  飞轮信号采集         ②批量生成文案(一次出5角度)
  审核流转             ③并发生成图片(asyncio.gather)
  偏好上下文组装       ④偏好重算(第二期激活)
        │                  │
数据层(双引擎)
  MySQL(主存储,一期14表)    MongoDB(只写AI debug trace)
  业务全量数据/账号/权限     AI调用过程快照，出错排查用
  品牌库/候选/飞轮信号       业务逻辑不依赖它
  API Key(Fernet加密)       Redis(Celery队列+SSE推送通道)

一次任务的数据流转

1.管理员预置品牌库(产品档案+标杆笔记)
2.熟手发起任务：选产品+选标杆 → 后端检查有没有配key(没有→引导去配)
  → **只把task_id推入Celery队列(绝不推key，遵基石B)**
3.Worker异步：①分析标杆提8特征 ②生成5角度文案(动态注入卖点+违禁词+风格+偏好)
  ③并发生图A/B/C → 每步推SSE，前端实时看进度
4.熟手8选3文案 → 飞轮信号入口1；挑图 → 入口2
5.提交审核 → 组长看队列
6.组长通过(+5分,最重)/打回(写原因,下次自动注入prompt提醒AI别再犯)
7.归档(永久保留)

偏好飞轮怎么转（产品的魂）

【采信号】选文案+3 / 选图+3 / 审核通过+5(最重) / 打回写原因-3 / 重新生成-1 → 全进 preference_events 表
         (此为开发起步默认权重，北哥调教后可配置校准)
【聚合】  下次生成查最近50条 → 哪个角度被选最多(L3个人) + 打回原因最近3条原文拼进prompt
         不足5条信号 → 用产品档案冷启动
【三层继承】L1公司品牌基线 > L2矩阵号人设 > L3个人手感(运行时叠加，有L3用L3，没有往上兜底)
         ⚠️ 按产品维度分开学：素颜霜偏好不串到精华/面膜
【越用越准】1次=全靠静态基线均匀分布；10次=知道你爱"痛点切入"；30次=措辞从"供参考"升为明确指令
【诚实克制】banana的假评分(88分)MVP彻底不接，eval_score留NULL，等真评分(组长标准蒸馏)再装

---

二、核心设计决策（已拍板）

开发期不得推翻，变更需产品负责人重新确认。

决策项	结论
主存储	MySQL存所有业务数据(飞轮聚合要JOIN)，MongoDB只存AI debug trace
API Key	每账号自录自用、Fernet加密、不同workspace各自独立，禁止混算；token站url统一收口=自家站endpoint，账号表只存encrypted_key不存url字段(06-04洞4，旧"兼容任意中转站url"已废止)
软件费	MVP阶段免费，不做计费墙(06-04洞4)；token耗材费走自家站按key隔离，不在产品层计费；收费逻辑产品成熟后单独议
Key解密位置	只在Celery worker内存局部变量，不落盘不打日志
多租户隔离	workspace_id写进JWT，所有查询强制带此条件(安全红线)
任务主键	MySQL自增BIGINT + mongo_trace_id VARCHAR(24)，飞轮JOIN性能好
文案生成	双轨(06-04洞2)：轨A=自带强模型一次返5角度JSON(不串行不并发5次)；轨B=客户导入外部文案(豆包等)直接进候选池跳过AI；客户可在产品档案配自调prompt
图片生成	asyncio.gather并发，一次A/B/C三策略各一张(复用banana)
加密算法	cryptography.fernet.Fernet，环境变量FERNET_KEY，全仓统一
策略命名	对外API用A/B/C，内部method用minimal_edit系，建中心常量文件消除三套打架
审核记录	不建独立notes表，审核字段平铺generation_tasks，打回原因存preference_events
偏好快照	preference_profile表预建结构，MVP不写入，实时查events，第二期开物化缓存
品类动态	products.category是纯数据字段，代码和prompt禁止出现任何品类枚举
审核演进	先组长人工审为主→积累"过/不过+理由"蒸馏人工标准→生图够好+标准清晰后，AI当审核员接班(第三期)

---

三、数据模型全览（16张表 = 一期14张 + 二期预留2张）

14张=banana搬3 + 多租户基础3(不含matrix_accounts) + 业务主体7 + 飞轮1。matrix_accounts、preference_profile 二期预留，一期不建。 06-04增补：业务主体从5张增至7张(加 delivery_packages 素材交付包 + banned_words 违禁词库)。

Alembic 001 — 从banana搬3张(改造)
  users            用户账号(删credits字段)
  login_records    登录记录(无改)
  user_preferences UI设置偏好(无改，API Key另建表)

Alembic 002 — 多租户基础(全新)
  workspaces       租户/公司(北哥=1个)
  workspace_members 用户↔workspace+角色
  user_api_keys    个人API Key(Fernet加密)
  [matrix_accounts] 矩阵号 —— 二期预留，一期不建(矩阵号一期不做)

Alembic 003 — 业务主体7张(全新)
  products         产品档案(卖点/违禁词/风格/调性/标签/文案角度/可调prompt/source/workspace_id)
  benchmark_notes  标杆笔记(爆款链接/图/亮点说明，一对多挂product)
  generation_tasks 生产任务(状态机+审核字段平铺)
  text_candidates  文案候选(角度数量用户设定，MySQL主存储；source=ai/import区分双轨)
  image_candidates 图片候选(数量用户设定)
  delivery_packages 达人素材交付包(洞6)：id/workspace_id/product_id/theme/status(pending/ready/downloaded)/package_path/created_at
  banned_words     违禁词库(洞5)：word/level(auto_fix自动改/soft_warn软提示/hard_block硬拦截)/replacement/updatable/workspace_id(可覆盖)

Alembic 004 — 飞轮信号(全新)
  preference_events  飞轮信号日志(所有信号全在此；含data_ownership字段=client_data/platform_asset，洞7分层归属)
  [preference_profile] 偏好快照 —— 二期预留，一期不建(一期实时查events；二期同步加data_ownership标记)

关键字段

任务状态机：pending→generating→pending_selection→pending_review→approved/rejected→archived （打回后回到pending_selection；修订轮次靠查events统计）

generation_tasks 审核字段(平铺，需明确定义)： review_status / reviewer_id / reviewed_at / reject_reason / approved_at / archived_at

preference_events：

• signal_type: text_select | image_select | approve | reject_with_reason | regenerate
• signal_weight(已定初始默认值，北哥调教后可校准)：选文案+3 / 选图+3 / 审核通过+5(最重) / 打回-3 / 重新生成-1
• angle_label: 跟着产品的"文案角度"配置走，不写死
• reason: 打回原因原文（不做AI归纳）
• data_ownership: client_data(原始输入产出，客户可导出) | platform_asset(飞轮蒸馏成果，归平台) —— 洞7分层归属技术口子
• workspace_id + product_id: 都必须有（跨公司隔离 + 按产品分开学）

user_api_keys：UNIQUE(user_id, workspace_id, provider)

usage记录(一期必做，否则计费/排障断档)：每次AI调用记 usage(谁/用了多少token)，存 ai_call_logs 或 mongo debug trace 的 usage 字段；token站查询失败要有兜底；调用失败归因到个人key

---

四、复用 / 复活 / 新造清单

开发第一步先看这张表：哪些直接搬、哪些改造、哪些新写。

🟢 直接复用（复制基本不改）

banana模块	改动量
gemini_service.py 核心AI方法	只改__init__ 4行，AI调用方法一行不动
json_stream_extractor.py 流式解析	加variants到watched_keys
constants SCHEMA_METHODS	扩展补全
orchestrator analyze流程	数据源从Mongo改读MySQL products/benchmark_notes
celery_tasks 任务框架	task_id改BIGINT，只传task_id(绝不传key，遵基石B)，worker内部查库取encrypted_key→FERNET_KEY解密，加第4任务壳
api/stream.py SSE框架	补发历史事件(修漏洞)，结构不变
prompt_composer.py	新增compose_variants方法，原方法保留
docker-compose	直接复用，调环境变量名

🟡 复活（banana写好但没接线的死代码）

死代码	怎么复活
task_skills.py Invariants 8特征	analyze后把8特征写入events.signal_meta，飞轮统计维度从单一angle扩到8维(第三期)
loader.py PromptLoader版本alias	新建variants模板走版本机制，未来改prompt只改模板不改代码
gemini_service evaluate_schema	MVP彻底不搬，eval_score留NULL，第二/三期接真评分(避免假信号污染飞轮)

🔴 完全新造（banana没有，灵魂部件）

新造模块	作用
gemini_factory.py + Fernet解密	解决全局单例，每任务用自己的key构建实例
preference_collector.py	飞轮3信号入口(选文案/选图/审核)写入events
preference_aggregator.py	实时聚合events→prompt片段，三层继承叠加
api/products + benchmark_notes	品牌库CRUD，含source=preset预置品类
api/matrix_accounts	矩阵号CRUD(MVP前端可后做，库和接口先建)
api/api_keys	录入/删除/查询(只显后4位)，首登强制引导
middleware/workspace_guard	所有接口强制注入workspace_id，防串数据
api/review	组长待审列表/通过/打回
generate_text_variants	一次调用5角度JSON，替代banana单条循环
text_import_handler	轨B：导入外部文案(豆包等)直接进候选池，跳过AI生成(洞2文案双轨)
banned_word_checker	违禁词三级扫描:🟢自动改写/🟡软提示给建议词/🔴硬拦截，词库可配置(洞5)
image_postprocessor	出图后处理:重编码去C2PA元数据+转JPG/轻重采样削像素水印+压缩(洞3去水印)
package_exporter	生成达人素材交付包:按笔记分文件夹+图(01/02命名)+文案.txt+发布清单+合规说明(洞6)
_combine_benchmarks	1-5篇标杆合并成综合reference
base_workspace_repo	所有workspace相关Repo继承，强制过滤
Alembic 001-004	按序建14张表(一期)
constants/strategies.py	统一命名中心文件，消除三套打架

---

五、构建顺序（三期，一期拆1A/1B）

修正：原"一期3-4周"塞太满。拆成 1A生产链闭环 + 1B飞轮闭环，先证明能产出，再证明会学习。

一期·1A：生产链闭环（先让北哥能产出内容）

手动建北哥账号(不接短信)、手动/截图录标杆、产品库、按用户设定数量出文案(双轨)、出图去水印、选择、审核、打包交付。

1. 基础设施：建仓库+6容器；Alembic 001-002(不含matrix_accounts)；手动初始化北哥workspace+管理员
2. 品牌库：Alembic 003；产品档案CRUD(含文案角度+可调prompt可配置)；标杆笔记CRUD；预置素颜霜1条；初始化banned_words(MVP起步5词:美白/祛斑/速效/医用/药妆，updatable，北哥合规标准来了批量导入)
   • ⚠️ 标杆录入主通道=截图+手填亮点(洞1实测确定可行)；登录态采集=北哥内部插件，二期可选
3. API Key录入：user_api_keys+Fernet+录入界面；FERNET_KEY走环境变量；token站url固定自家站；没配key时按钮置灰引导
4. 核心生产链：中心常量文件；GeminiService改造+gemini_factory(key只在worker内解密)；analyze搬入；文案双轨(轨A生成5角度/轨B导入外部文案)；违禁词三级扫描；并发生图(数量用户设定)；Celery只传task_id；SSE推送
5. 选择+审核+交付包：选文案/选图/提审/审核队列/通过打回(审核字段明确定义)；出图后处理(去水印)→生成达人素材交付包
   • 出图后处理(洞3)：图像库重编码去C2PA元数据 + 转JPG/轻重采样削像素水印 + 压缩瘦身，对客户透明
   • 交付包结构(洞6)：按笔记分文件夹，每夹含图(01/02/03命名防传错序)+文案.txt(标题+正文+标签)，附📋发布清单.txt + ✅合规说明.txt(违禁词已过/已去水印)
   • 验收：北哥1名熟手不靠开发，从选产品→生成→选择→组长审→下载达人能直接发的素材包，全程跑通

一期·1B：飞轮闭环（让产出会学习）

1. Alembic 004(只建preference_events，不建preference_profile)
2. 三信号入口接线(选文案/选图/审核)
3. compose_preference_context 实时聚合(最近50条，workspace_id硬过滤)
4. 偏好+打回原因注入prompt
   • 验收(四点全过)：events正确写入 / aggregator返回明确片段 / 下次prompt trace含该片段 / UI显示"本次已注入"

一期整体验收：北哥熟手独立跑完生产链；飞轮选过3次后下次生成能看到偏好摘要并验证注入。

二期：多团队+对外销售（再2-3周）

留口子已在地基，二期只"打开注册开关"，不回头改表。

1. 手机号+验证码自助注册(选短信服务商) + workspace创建 + 邀请成员
2. matrix_accounts建表+矩阵号管理UI；L2人设层激活
3. preference_profile物化(events满10条触发重算，加载<50ms)
4. 管理后台：各workspace用量统计+飞轮健康度

三期：效果回流+AI审核员（看业务）

1. 发布效果回填(赞/收藏/评论→outcome_score加权)
2. L3 vs L1偏差检测(个人偏好偏离品牌基线>60%提示，防学坏)
3. Invariants 8维特征接线(飞轮统计从单一angle扩到8维)
4. AI审核员：用积累的"组长过不过+理由"蒸馏人工标准，训练AI审核员逐步接班(补banana假评分窟窿，呼应基石D)

---

六、待拍板判断点

已拍板（2026-06-03）

• ✅ 项目代号：Clover，文件夹建在 北哥小红书产品/Clover/
• ✅ 先做北哥单车间，但地基留口子，其他车间可快速打通
• ✅ 审核：先组长人工审为主 → 蒸馏人工标准 → 后期AI审核员接班
• ✅ 注册方式：手机号+验证码（对标小红书，已查证小红书就是手机号注册）。需接短信验证码服务商(阿里云/腾讯云SMS)
• ✅ 矩阵号：一期不做。L2人设层一期不激活，飞轮一期只跑"L1品牌基线+L3个人手感"两层；matrix_accounts表仍建好留口子，二期补L2
• ✅ 排版：不做独立排版环，第7环并入第6环——AI生图时直接把文字/版式排在图上(出成品图)
• ✅ 标杆采集通道（06-04洞1已拍板，实测3条真链接裸抓全返回风控假页）：
  • 对外SaaS一期主通道=截图+手填亮点（客户自己截图，零平台风险）
  • 链接自动读取=登录态采集方案（本地已有跑通代码：n8n-nodes-xiaohongshu + xhs-sign-server，Playwright跑小红书自家JS算签名），但"系统替客户取数据"=违规+封号风险，只作北哥内部自用插件、二期可选模块，不进对外标配
  • 官方蒲公英/聚光接口=二期看北哥企业资质再议
• ✅ 软件收费（06-04洞4已拍板）：MVP阶段软件免费，不做计费墙；token耗材费走自家token站、按账号key隔离，不在产品层计费。收费逻辑(底层麻烦)产品成熟后单独讨论

待拍板

• P1 短信服务商：用阿里云短信还是腾讯云短信？(影响成本和接入，都需企业实名)（注：仅二期自助注册才需要，一期手动建北哥账号不阻塞）
• P2 标杆链接读不到时的兜底 → 已由06-04洞1解决：对外=截图手填(主通道)，登录态采集作内部插件，不再是待拍板项
• P2 北哥账号开通：一期北哥账号由我们手动建(已定，不接短信)；自助注册留二期