beige/backend/BACKEND_MAP.md

Clover 后端接手地图

受众：守印（新接手后端，不了解北哥产品背景） 最后更新：2026-07-01 基于真实代码分析，所有文件名/类名/函数名/行号均来自实际代码，请直接跳转核实。

---

产品背景（守印必读）

Clover 是给北哥团队做的小红书种草内容生产中台，帮助运营团队批量生产高质量小红书笔记。

完整链路：

填产品卖点（产品档案）
  → 上传标杆笔记（AI拆解爆款特征）
  → 发起任务（AI生成3套文案 × A痛点先行/B场景先行/C成分背书）
  → 运营选文案 + 选配图（每步触发飞轮信号学偏好）
  → 组长审核（通过/打回带原因）
  → 打包下载 ZIP，发给达人分发
  → 爆款笔记可触发"裂变"再出N套变体

三个角色：

• operator（运营）：选文案/选图/改稿
• supervisor（组长）：审核通过/打回
• admin（管理员）：管用户/管词库/删候选

两大特色机制：

• AI评分门禁：文案必须 ≥80分才入库，低分直接过滤不展示给运营
• 飞轮：每次选择/改稿/打回都是信号，下次生成自动学偏好

---

目录

1. 整体目录结构与技术栈
2. API 路由全清单
3. 数据模型
4. AI 引擎模块清单
5. Celery 异步任务
6. 飞轮机制
7. 门禁可配置性现状
8. 鉴权与 SSE
9. 改动快速索引

---

1. 整体目录结构与技术栈

技术栈： FastAPI + Celery + PostgreSQL + Redis，Python 3.11+，Alembic 做迁移，pytest 做测试。

backend/
├── app/
│   ├── api/v1/              # 路由层（16个文件，统一前缀 /api/v1/）
│   ├── models/              # SQLAlchemy ORM 模型（6个文件）
│   ├── repositories/        # DB 查询封装（Repository 模式）
│   ├── services/            # 业务逻辑层
│   │   ├── ai_engine/       # AI 引擎（24个模块，核心）
│   │   ├── flywheel_service.py       # 飞轮信号写入
│   │   ├── fission_service.py        # 裂变任务创建
│   │   ├── fission_pipeline.py       # 裂变执行主流程
│   │   └── fission_images.py         # 裂变生图
│   ├── workers/             # Celery 任务层（5个文件）
│   ├── constants/
│   │   └── enums.py         # 枚举定义（状态机、信号类型、角色等）
│   ├── core/
│   │   ├── config.py        # 环境变量读取（Settings 类）
│   │   ├── database.py      # DB session 工厂
│   │   ├── security.py      # JWT 签发/验证 + Fernet 加解密
│   │   └── sse_ticket.py    # SSE 一次性票据（Redis 存储）
│   └── middleware/
│       └── workspace_guard.py  # 鉴权依赖注入（4个级别）
├── alembic/versions/        # 19 个数据库迁移文件
├── tests/                   # 单元测试（pytest）
├── docker-compose.yml       # 本地开发启动
└── requirements.txt         # Python 依赖

---

2. API 路由全清单

所有路由统一挂在 app/main.py，前缀 /api/v1/。路由文件在 app/api/v1/。

auth.py — 认证

方法	路径	作用
POST	/auth/login	用户名密码登录，返回 JWT access_token
POST	/auth/change-password	修改密码（首次登录强制走此端点）
GET	/auth/me	当前用户信息 + 所属 workspace + role

workspaces.py / users.py / api_keys.py

方法	路径	作用
GET/POST	/workspaces	查/建工作区
GET/POST/PUT	/users	成员管理（admin）
POST/GET/DELETE	/api-keys	API Key 录入/查看/删除（只返回 provider+last4，不返密文）

products.py — 产品档案

方法	路径	作用
POST	/products	新建产品档案
GET	/products	列出当前 workspace 产品
GET	/products/{id}	查单个产品（含参考图）
PUT	/products/{id}	更新卖点/风格/角度等
DELETE	/products/{id}	软删除（is_active=False）

product_images.py — 产品多图（R5规格）

方法	路径	作用
POST	/products/{id}/images	上传参考图，按 scene 分类（primary/scene/texture/ingredient/model）
GET	/products/{id}/images	列出所有参考图
DELETE	/products/{id}/images/{img_id}	删除某张

benchmarks.py — 标杆笔记（链路第2环）

方法	路径	作用
POST	/products/{pid}/benchmarks/upload	上传截图（10MB 限制，magic bytes 校验）
GET	/products/{pid}/benchmarks	列出该产品标杆笔记
POST	/benchmarks/{bid}/analyze	触发 AI 拆解8维爆款特征，写入 features_json
GET/POST/PUT/DELETE	/banned-words	违禁词 CRUD（写操作需 admin）
GET	/products/export	产品档案 JSON 导出
GET	/benchmarks/export	标杆笔记 JSON/CSV 导出

tasks.py — 任务查询层

方法	路径	作用
POST	/tasks	发起生成任务（校验有无 key，推入 Celery queue）
GET	/tasks	任务列表（多状态/日期/product_id 过滤 + 分页，可混入裂变条目）
GET	/tasks/{task_id}	任务详情（含所有文案候选 + 图片候选）
DELETE	/tasks/{task_id}	删除任务（admin；有成品转 archived，无成品物理删）

task_actions.py — 任务操作层（飞轮信号入口）

所有飞轮信号都在这里触发，是行为核心。

方法	路径	作用	飞轮信号
POST	/tasks/{id}/text-candidates/select	选文案（同套单选，清旧选）	text_select +3
POST	/tasks/{id}/image-candidates/select	选图（同套同角色单选）	image_select +3
POST	/tasks/{id}/import-text	导入外部文案（客户验证过的范本，最强信号）	text_import +8
POST	/tasks/{id}/generate-images	导入轨去生图（复用已导入文案，不重生文案）	无
POST	/tasks/{id}/regenerate	重生成（支持整体/单套/单张 + custom_prompt）	regenerate -1
POST	/tasks/{id}/submit-review	提交审核（至少1文案+1图才能提）	无
GET	/tasks/{id}/preference/context	查飞轮偏好上下文（前端展示"已学习N条信号"）	无
POST	/tasks/{id}/text-candidates/{cid}/edit	改稿（真改字，回写 content + edited=True）	text_edit +5
DELETE	/tasks/{id}/text-candidates/{cid}	删文案候选（admin）	无
DELETE	/tasks/{id}/image-candidates/{cid}	删图片候选（admin）	无

review.py — 审核路由（supervisor 权限）

方法	路径	作用	飞轮信号
GET	/review/queue	待审队列（pending_review，按时间升序）	无
POST	/review/{task_id}/approve	通过（状态→approved）	approve +5
POST	/review/{task_id}/reject	打回（原因原文存 preference_events.reason）	reject_with_reason -3

stream.py — SSE 实时推送（安全红线：ticket 机制）

方法	路径	作用
POST	/tasks/{id}/sse-ticket	用 JWT 换一次性 ticket（60s 有效）
GET	/tasks/{id}/stream?ticket=<ticket>	SSE 流（断线重连支持 ?last_seq=）

fission.py — 裂变（链路第11环）

方法	路径	作用
POST	/fission	触发裂变（1套爆款→N套完整笔记包）
GET	/fission/{id}	查进度（x/N 完成）
GET	/fission/{id}/notes	取 N 套完整笔记包
GET	/fission/{id}/download	下载裂变结果 zip
POST	/fission/{id}/notes/{seq}/retry-images	对某套失败分镜补图

delivery.py — 交付打包

方法	路径	作用
POST	/tasks/{id}/package	触发打包（异步 Celery）
GET	/tasks/{id}/package	查包状态 + 下载链接

---

3. 数据模型

模型文件在 app/models/，共 6 个文件。

user.py

• User：id, username(唯一), email(唯一), hashed_password, is_active, must_change_password(首登强制改密)
• LoginRecord：登录记录，user_id FK→users, ip, user_agent
• UserPreference：UI 设置，preferences_json（Text 存 JSON）

workspace.py

• Workspace：id, name, slug(唯一), is_active
• WorkspaceMember：workspace_id + user_id 联合唯一, role 枚举(admin/supervisor/operator)
• UserApiKey：user_id + workspace_id + provider 三联唯一, encrypted_key(Fernet 密文), key_last4；绝不存明文

product.py

• Product：workspace_id FK, name, category, selling_points(JSON数组), style_tone, text_angles(JSON数组), custom_prompt, image_path(主图路径兼容旧), brand_keyword, target_audience, is_active
• ProductImage（R5多图）：product_id FK, path(绝对路径), scene(primary/scene/texture/ingredient/model), is_primary, sort_order
• BenchmarkNote：workspace_id+product_id FK, screenshot_url, highlights(手填), link_url, features_json(AI解析8维), analyze_status(pending/analyzing/done/failed)
• BannedWord：workspace_id FK, word, level(auto_fix/soft_warn/hard_block), replacement, updatable

task.py

• GenerationTask：workspace_id FK, product_id FK, operator_id FK, theme, text_count(1-20), image_count(1-20), track(ai/import), need_product_image, status 7态(见下), review_status, reviewer_id, reject_reason, source_fission_id
  • 状态机：pending → generating → pending_selection → pending_review → approved/rejected；另有 archived（有成品软删）、failed（重试耗尽终态）
• TextCandidate：task_id FK, source(ai/import), angle_label, strategy(A/B/C), content(JSON含title/content/tags/imageBrief), score_json(7维评分), banned_word_status, eval_score(一期留NULL), is_selected, edited(改稿标记)
• ImageCandidate：task_id FK, role, url, strategy(A/B/C), seq(分镜序号), is_selected, is_regen, eval_score(一期留NULL), ai_visual_score(展示用不进飞轮权重)
• DeliveryPackage：task_id FK, status(pending/ready/downloaded), package_path, download_url, expires_at

flywheel.py

• PreferenceEvent（preference_events 表）：飞轮信号日志
  • 关键字段：workspace_id, product_id, task_id FK, user_id FK, signal_type, signal_weight, candidate_id, angle_label, reason(打回原因原文), signal_meta(JSON), data_ownership(固定=client_data，数据归客户)
  • 索引：(workspace_id, product_id, created_at) 三联复合索引
• AiCallLog（ai_call_logs 表）：key_id(不含明文), provider, model, call_type, prompt_tokens, completion_tokens, success, error_code, latency_ms

fission.py

• FissionTask：workspace_id FK, source_note(源笔记JSON), source_task_id FK, reference_level(low/mid/high), fanout_count(默认3), status(pending/generating/done/failed)
• FissionNote：fission_id FK, workspace_id FK, seq(第几套), note_json(含title/content/tags/imagePlan/dimension), images_json(生图结果列表), score, passed(>=80), dimension(换角度/换痛点/换人群), status

表间主要外键：

• workspace → products / generation_tasks / fission_tasks / preference_events / banned_words（workspace_id 隔离多租户）
• generation_task → text_candidates / image_candidates / delivery_packages / preference_events

---

4. AI 引擎模块清单

全部在 app/services/ai_engine/，共 24 个文件。

模块文件	一句话职责
constants.py	所有可调常量中心：违禁词默认库、评分权重、合格线(80)、叙事策略文本、图片重试参数、飞轮权重
_score_prompt.py	AI评委 prompt 模板：7维评判标准+输出格式约束（JSON），与 constants.py 三处同步
_scoring_dims.py	机械合规打分（score_compliance），用于轨B导入文案或AI评委降级兜底
llm_scorer.py	AI评委入口：调 LLM 打7维分，合规机械硬拦，两通道挂时抛 ScoringUnavailableError
text_scoring.py	文案评分聚合：整合 AI 评委分 + 机械合规分，输出 score_json
text_variants.py	按 A/B/C 三套叙事策略调 LLM 生成多条文案变体
_text_prompt.py	文案生成 prompt 模板（含叙事策略差异化段落）
prompt_composer.py	组装最终文案生成 prompt（拼飞轮片段+产品信息+标杆特征+叙事策略）
storyboard.py	按图数和叙事策略规划分镜列表，返回 storyboard + base_prompt
storyboard_templates.py	各套叙事策略的分镜模板数据
_storyboard_data.py	分镜角色的默认视觉参数
image_gen.py	生图主入口：asyncio.gather 并发多张，主备通道切换，指数退避重试3次
image_postprocessor.py	图片去AI化后处理：SynthID破除(缩2px裁1px边+亮度/饱和微调)+高保真重编码(jpeg q=100)+尺寸处理
image_scorer.py	AI评图（0-100分），ai_visual_score+ai_visual_note，仅展示不进飞轮权重
banned_word_checker.py	三级违禁词扫描（auto_fix/soft_warn/hard_block），优先 DB 词库，兜底默认词库
preference_aggregator.py	飞轮偏好聚合：取最近50条 events → 按权重统计高频角度 → 拼 prompt 片段注入文案生成
benchmark_analyzer.py	标杆笔记爆款8维特征 AI 解析（链路第2环）
_benchmark_prompt.py	标杆分析 prompt 模板
fission_prompt.py	裂变专用 prompt（一次 LLM 出 N 套笔记）
fission_fallback.py	裂变引擎降级兜底逻辑
gemini_factory.py	Gemini 客户端工厂（生图备用通道）
package_exporter.py	AI引擎层的素材包打包辅助
beige_color_grade.py	小红书米色调色滤镜（去AI化可选后处理）

评分维度详细（7维 + 合规机械）

AI评委7维，定义在 _score_prompt.py: SCORING_DIMENSIONS 字符串 + llm_scorer.py: _DIM_MAX dict + constants.py: AI_DIM_WEIGHTS dict（三处必须同步）：

维度	满分	核心判断标准
痛点人群精准	16	"说的就是我"——处境/困扰让目标用户对号入座
情绪张力	16	过去痛（后果）+ 未来好（成果）双向情绪
买点转化	16	卖点翻译成用户能感知的场景化利益（人话）
开头钩子	13	第一句直击痛处/场景，让人停下来继续读
标题点击力	13	悬念/反差/疑问钩子 + 广覆盖不锁死窄人群
真实感	11	像真人分享，前70%干货，后30%软性推荐
标签精准度	10	精准购买意向埋词，非泛流量词
合规（机械）	5	机械硬拦，不进AI评委打分
合计	100

合格线：constants.py 第47行 QUALITY_PASS_SCORE = 80，硬编码（详见第7节）。