docs: 交接文档三件套(接手总览+后端地图+差距路线图)+补全env模板

- HANDOVER.md: 守印接手第一入口,全景+上手路径+文档地图 - backend/BACKEND_MAP.md: 后端接手地图(路由/模型/AI引擎/评分维度) - 路线图.md: 现状vs目标差距(三视角×双目标矩阵+7/15倒排冲刺) - .env.example x3: 补全 MODEL_VISION/CLAUDE_API_URL 及本地SSE示例 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-01 18:49:51 +08:00
parent e26f53608b
commit de6466737b
6 changed files with 576 additions and 0 deletions
--- a/HANDOVER.md
+++ b/HANDOVER.md
@@ -0,0 +1,165 @@
+# 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`。缺口清单会在倩倩姐与北哥对齐内容板块后进一步补充。