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

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

---

## 0. 一句话说清这是什么

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

---

## 目录

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

---

## 1. 协作方式

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

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

分工原则：**前端归倩倩姐、后端归守印**，各自在自己的分支开发，通过 API 契约对接（见 [`启动包/API契约.md`](启动包/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/`，一眼区分
- **克隆命令**：
  ```bash
  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` 自己生成，数据库密码填本地库的。

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

**前端**：
```bash
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`](backend/BACKEND_MAP.md) ⭐ |
| 怎么部署上线、docker 怎么起 | [`README.md`](README.md) |
| 前后端 API 怎么对接（契约） | [`启动包/API契约.md`](启动包/API契约.md) |
| 产品整体架构设计 | [`Clover架构方案.md`](Clover架构方案.md) |
| 种子数据有哪些、怎么灌 | [`启动包/种子数据.md`](启动包/种子数据.md) |
| 项目所有约束、产品红线、拍板决策 | [`CLAUDE.md`](CLAUDE.md) ⭐ 开工必读 |
| 交付项核销状态（哪些做了哪些没） | [`交付核销表.md`](交付核销表.md) |
| 出线上问题怎么排 | [`docs/ops/troubleshooting.md`](docs/ops/troubleshooting.md) |
| FERNET_KEY 密钥托管与恢复 | [`docs/ops/fernet.md`](docs/ops/fernet.md) |
| 北哥的原始需求是什么 | [`北哥回填解读与落点.md`](北哥回填解读与落点.md) |
| 现状离目标还差什么、下一步做什么 | `路线图.md`（同目录，见第 9 节） |

## 8. 守印上手路径

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

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

## 9. 当前已知问题与红线

**几条必须知道的红线（详见 [`CLAUDE.md`](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`。缺口清单会在倩倩姐与北哥对齐内容板块后进一步补充。