beige/HANDOVER.md

Clover 项目接手文档（守印必读第一篇）

本文是新同事接手 Clover 的总入口。先读完这一篇建立全局认知，再按“上手路径”逐步深入。 后端细节看 backend/BACKEND_MAP.md，部署看 README.md，产品全貌看 Clover架构方案.md。

---

0. 一句话说清这是什么

Clover 是给北哥团队用的小红书内容生产中台：输入产品和卖点 → AI 生成文案（3 套叙事）→ 生成配图 → 组长/管理员审核 → 打包下载给达人分发。核心链路已上线，正在两人协作迭代。

---

目录

1. 协作方式：你和倩倩姐怎么分工
2. 代码仓库与基线
3. 技术栈全景
4. 5 分钟跑起来（本地开发）
5. 核心业务链路（先懂业务再看代码）
6. 三层视角：产品要长成什么样
7. 文档地图：什么问题看哪份文档
8. 守印上手路径（按天走）
9. 当前已知问题与红线

---

1. 协作方式

这是两人协作开发，不是单向交付：

人	负责
倩倩姐	梳理业务逻辑与框架、前端（Next.js）
守印（你）	后端（FastAPI + Celery + 数据层）

分工原则：前端归倩倩姐、后端归守印，各自在自己的分支开发，通过 API 契约对接（见 启动包/API契约.md）。改动对方领域前先打招呼，避免撞车。

2. 代码仓库与基线

• 远程仓库：http://192.168.0.101:3002/qianqian/beige（公司内网 Gitea）
• 基线分支：main = 2026-07-01 今天的上线版（commit e26f536）。这是当前线上真实运行的代码，以它为准，不要参考更早的历史分支。
• 协作分支策略：
  • main：稳定基线，只合并测过的代码，不直接在上面写
  • 各自开 feat/xxx 或 fix/xxx 分支开发，完成后合回 main
  • 守印后端相关分支建议前缀 be/，倩倩姐前端 fe/，一眼区分
• 克隆命令：

  git clone http://192.168.0.101:3002/qianqian/beige.git
  cd beige
  

3. 技术栈全景

层	技术	位置
前端	Next.js 16 (App Router) + TypeScript + Tailwind + Zustand	frontend/
后端	FastAPI + SQLAlchemy	backend/app/
异步任务	Celery（生文生图等耗时任务）	backend/app/workers/
关系库	MySQL（业务数据）	alembic/ 管迁移，25 条
文档库	MongoDB（链路留痕/trace）	via Motor
缓存/队列	Redis（Celery broker + 缓存）	—
AI 引擎	生文/生图/评分/门禁	backend/app/services/ai_engine/ 约 20 模块
部署	docker-compose + nginx 反代	docker-compose.prod.yml

非 monorepo：backend/ 和 frontend/ 各自独立，没有 workspace 工具，分别装依赖、分别跑。

4. 5 分钟跑起来

目标：本地把前后端跑起来。密钥用你自己的（AI 中转 key / 本地数据库），不要用交接包里的示例值。

准备环境变量：复制 .env.example → .env，填你自己的值。三个位置：根目录、backend/.env、frontend/.env.local。关键字段 FERNET_KEY/JWT_SECRET 自己生成，数据库密码填本地库的。

后端：

cd backend
pip install -r requirements.txt        # 依赖已全部锁版本
alembic upgrade head                   # 建表（25 条迁移）
python scripts/seed_data.py            # 灌种子数据（见 启动包/种子数据.md）
uvicorn app.main:app --reload --port 8000

前端：

cd frontend
npm ci                                 # 按 package-lock 精确安装
# .env.local 里务必设 NEXT_PUBLIC_SSE_BASE_URL=http://localhost:8000
npm run dev                            # 起在 :3000

本地开发有个坑：前端 :3000、后端 :8000 跨端口，SSE（实时进度推送）不能走 Next.js dev proxy（会缓冲 EventSource 导致进度不刷新）。必须在 frontend/.env.local 显式设 NEXT_PUBLIC_SSE_BASE_URL=http://localhost:8000。这条已写进 frontend/.env.example 注释。

5. 核心业务链路

先懂业务再看代码。操作员走完整条链路是这样的：

1. 开新任务 → 选产品（新建或从产品档案选）
2. 填产品信息 → 产品名/品类/品牌词/目标人群/风格调性/核心卖点 + 上传产品图（可标主图、标使用场景：上脸/使用/成分/包装）
3. 填今日主题 → 如"黄皮提亮"
4. 生成文案 → 固定 3 套叙事：痛点先行 / 场景先行 / 成分背书，每套可选生成几条
5. 评分去重 → AI 按 7 维门禁打分，≥80 分才出现，≥90 分标绿；相似度去重
6. 挑文案 + 改稿 → 操作员选文案，可改稿；改稿动作进飞轮留痕
7. 生成配图 → 每套配几张图（默认 6 张，可调），生图走部分并发（有先后逻辑不能全并发）
8. 组长/管理员审核 → 操作员本人不能审；不通过打回、可重申（重申写原因入飞轮）
9. 打包下载 → 图+文打包，分发给达人
10. 裂变扩散 → 已通过的笔记可再生成裂变版本（1~5 套，图+文）

三种权限：管理员（管理台）/ 组长（审核）/ 操作员（生产）。

6. 三层视角

这是孙总定的产品设计准绳——产品不只是"能跑通链路"，要撑起三层视角，价值感才拉满。守印做后端时，配置项/留痕/数据接口都要往这三层靠：

视角	面向谁	要什么	后端要提供
L1 业务视角	所有人（最浅层）	生文→生图→审核→打包链路	已有
L2 中层视角	核心中层/技术把控	门禁可见可配置、飞轮可见、操作记录、素材库、看板	配置化 API、留痕查询、素材库 CRUD
L3 高管视角	高级管理层	数据/进度看板（跑了什么、ROI）	数据聚合/统计 API

关键红线（孙总原话）："门禁写死是最麻烦的"——7 维权重、80 分合格线目前是硬编码，L2 要求把它们做成可配置。详见路线图。

7. 文档地图

接手期间遇到问题，按下表找文档，不用漫无目的翻：

想知道什么	看哪份
后端代码怎么组织、我要改X动哪里	backend/BACKEND_MAP.md ⭐
怎么部署上线、docker 怎么起	README.md
前后端 API 怎么对接（契约）	启动包/API契约.md
产品整体架构设计	Clover架构方案.md
种子数据有哪些、怎么灌	启动包/种子数据.md
项目所有约束、产品红线、拍板决策	CLAUDE.md ⭐ 开工必读
交付项核销状态（哪些做了哪些没）	交付核销表.md
出线上问题怎么排	docs/ops/troubleshooting.md
FERNET_KEY 密钥托管与恢复	docs/ops/fernet.md
北哥的原始需求是什么	北哥回填解读与落点.md
现状离目标还差什么、下一步做什么	路线图.md（同目录，见第 9 节）

8. 守印上手路径

建议按这个顺序，别一上来扎进代码：

• 第 1 步（了解全貌）：读本文 + CLAUDE.md。CLAUDE.md 是项目所有约束和产品红线的落盘，里面每条 🔴 都是踩过坑或拍过板的，务必读完。
• 第 2 步（跑起来）：按第 4 节把本地环境跑通，用你自己的 key。能登录、能开一个任务、能看到生成，就算上手了。
• 第 3 步（懂后端）：读 backend/BACKEND_MAP.md，对着代码走一遍 API 路由和数据模型，重点看 task_actions.py（飞轮信号入口）、stream.py（SSE ticket 机制）、AI 引擎评分部分。
• 第 4 步（明确分工）：读 路线图.md，看后端待办里哪些是你的活，和倩倩姐对齐优先级再动手。

9. 当前已知问题与红线

几条必须知道的红线（详见 CLAUDE.md）：

• 🔴 合格线=80 分，禁止擅改（constants.py QUALITY_PASS_SCORE=80）。提质量靠优化 prompt 顶分数，绝不靠降门槛。改这个值必须倩倩姐当面拍板。
• 🔴 SSE 认证用一次性 ticket，绝不把 JWT 放进 URL。EventSource 不支持 header，SSE 连接前先用 JWT 换一张 30-60 秒的一次性 ticket。
• 🔴 系统通用化，绝不内置写死任何具体产品（素颜霜只是北哥一个客户的一个产品，产品靠上传才有）。
• 🔴 飞轮 eval_score 留 NULL 铁律：AI 评分只做展示层，不当飞轮权重。真正影响下次生成的只认真实信号（选了哪张/改了什么/过审与否）。
• 🔴 竞品数据监控 = 不做（合规反爬红线，已砍）。

当前已知待改（会议暴露，详见路线图）：

• 新建产品链路在线上跑失败（本地 OK），产品表单逻辑割裂，要梳理全。
• 文案数量配置语义待明确（"生成几条文案"是每套还是总数）。
• 门禁 7 维权重、合格线硬编码，L2 目标要求可配置化。
• 素材库、看板（业务看板 + 高管数据看板）待建。
• 裂变功能已做但缺直观感官呈现。

完整的"现状 vs 目标差距 + 开发路线图"见同目录 路线图.md。缺口清单会在倩倩姐与北哥对齐内容板块后进一步补充。