上线版: 产品表单统一+form嵌套修复+用户管理+部署+三套叙事

- 产品编辑入口统一走 ProductFormFull(卖点/风格/人群/品牌词全字段); 修复开任务页 <form> 套 <form> 致"编辑产品"报错、改不了、跳回首个产品 - dashboard 入口卡片对齐实际路由: 系统管理(/config) 与工作配置(/settings) 分开; settings ?tab=products 直达改用挂载后读 URL, 消除 hydration mismatch - 新增用户管理(users API/admin service/改密页) + alembic 022/023/024 - 上线部署: Dockerfile / docker-compose.prod+https / nginx https / .env.example - A8 三套正交叙事(痛点/场景/成分背书) + beige 调色去AI化 + 飞轮 text_import 高权重信号 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-30 18:08:13 +08:00
parent a77212781c
commit df1856d793
150 changed files with 8616 additions and 1765 deletions
--- a/docs/ops/fernet.md
+++ b/docs/ops/fernet.md
@@ -0,0 +1,34 @@
+# FERNET_KEY 管理
+
+`FERNET_KEY` 用于加密客户在工作台录入的 API Key。它不是普通配置，必须单独备份。
+
+## 规则
+
+- 每个生产环境生成唯一 `FERNET_KEY`。
+- 不要复用本地测试环境的 key。
+- 不要提交到 git。
+- 不要发在聊天记录里。
+- 备份时和数据库备份分开放置。
+
+## 丢失后果
+
+如果 `FERNET_KEY` 丢失，数据库里的客户 API Key 密文无法解密，客户需要重新录入 key。
+
+## 生成方式
+
+```bash
+python3 - <<'PY'
+from cryptography.fernet import Fernet
+print(Fernet.generate_key().decode())
+PY
+```
+
+## 轮换方式
+
+一期不做密文在线重加密。需要轮换时：
+
+1. 通知客户暂停生成。
+2. 清空 `user_api_keys` 中旧密文，或让客户在设置页逐个覆盖录入。
+3. 更新服务器 `.env` 的 `FERNET_KEY`。
+4. 重启 api/worker。
+5. 让客户重新录入 API Key。
--- a/docs/ops/runbook.md
+++ b/docs/ops/runbook.md
@@ -0,0 +1,74 @@
+# Clover 运维手册
+
+## 部署
+
+1. 复制 `.env.example` 为 `.env`。
+2. 填写 `FERNET_KEY`、`JWT_SECRET`、数据库密码、域名、AI provider base URL。
+3. 如果前端和 API 走同一个 nginx 域名，`NEXT_PUBLIC_API_BASE_URL` 和 `NEXT_PUBLIC_SSE_BASE_URL` 保持空；如果前后端分域，填公网 API 域名，并且每次修改后必须重新 build 前端镜像。
+4. 内测 HTTP 启动：
+
+```bash
+docker compose -f docker-compose.prod.yml --env-file .env up -d --build
+```
+
+5. 正式 HTTPS 启动前置条件：
+
+- 域名已经解析到服务器公网 IP。
+- 证书文件放在 `certs/fullchain.pem` 和 `certs/privkey.pem`。
+- `.env` 的 `CORS_ALLOW_ORIGINS` 填真实 HTTPS 域名。
+
+```bash
+docker compose -f docker-compose.prod.yml -f docker-compose.https.yml --env-file .env up -d --build
+```
+
+6. 查看状态：
+
+```bash
+docker compose -f docker-compose.prod.yml ps
+curl http://127.0.0.1/health
+```
+
+HTTPS 模式验证：
+
+```bash
+docker compose -f docker-compose.prod.yml -f docker-compose.https.yml ps
+curl -I https://<domain>/health
+```
+
+## 更新
+
+```bash
+git fetch --tags
+git checkout <delivery-tag>
+docker compose -f docker-compose.prod.yml --env-file .env up -d --build
+```
+
+## 回滚
+
+```bash
+git checkout <previous-delivery-tag>
+docker compose -f docker-compose.prod.yml --env-file .env up -d --build
+```
+
+## 备份
+
+```bash
+cd backend
+MYSQL_USER=clover MYSQL_PASSWORD='<password>' MYSQL_DB=clover sh scripts/backup.sh
+```
+
+备份内容包括 MySQL、MongoDB、uploads。
+
+## 密钥
+
+- `FERNET_KEY` 必须备份，丢失后客户 API Key 需要重新录入。
+- `JWT_SECRET` 轮换会让所有登录态失效。
+- 服务器 `.env` 可放测试公共 key；客户自购 key 应在工作台由客户自己录入。
+
+## 日志
+
+```bash
+docker compose -f docker-compose.prod.yml logs -f api
+docker compose -f docker-compose.prod.yml logs -f worker
+docker compose -f docker-compose.prod.yml logs -f nginx
+```
--- a/docs/ops/troubleshooting.md
+++ b/docs/ops/troubleshooting.md
@@ -0,0 +1,52 @@
+# Clover 排障手册
+
+## 服务不可访问
+
+```bash
+docker compose -f docker-compose.prod.yml ps
+docker compose -f docker-compose.prod.yml logs --tail=100 nginx
+curl -I http://127.0.0.1/
+```
+
+## 后端异常
+
+```bash
+curl http://127.0.0.1/health
+docker compose -f docker-compose.prod.yml logs --tail=200 api
+docker compose -f docker-compose.prod.yml logs --tail=200 worker
+```
+
+## SSE 没有实时进度
+
+检查 nginx 是否关闭缓冲：
+
+```bash
+curl -N -H "Accept: text/event-stream" "http://127.0.0.1/api/v1/tasks/<task_id>/stream?ticket=<ticket>"
+```
+
+应能持续收到 named event。nginx 配置必须包含 `proxy_buffering off` 和 `X-Accel-Buffering: no`。
+
+## 图片显示 404
+
+```bash
+docker compose -f docker-compose.prod.yml exec api ls -lah /app/uploads
+docker compose -f docker-compose.prod.yml exec worker ls -lah /app/uploads
+curl -I http://127.0.0.1/uploads/<path>
+```
+
+api 和 worker 必须共享同一个 `uploads` volume。
+
+## 生成失败
+
+常见原因：
+
+- 客户未录入 API Key。
+- provider key 余额不足或无权限。
+- 上游中转站 429/503。
+- 产品入镜但未上传产品图。
+
+查看 worker 日志：
+
+```bash
+docker compose -f docker-compose.prod.yml logs --tail=200 worker
+```
--- a/docs/user/使用说明.md
+++ b/docs/user/使用说明.md
@@ -0,0 +1,197 @@
+# Clover 用户操作手册
+
+适用对象：运营、组长、管理员。  
+访问地址：由管理员提供；本机预览地址为 `http://localhost:3001`。
+
+## 1. 登录与首次改密
+
+1. 打开平台地址。
+2. 输入管理员提供的账号和初始密码。
+3. 首次登录会进入「修改密码」页面。
+4. 输入当前密码、新密码、确认新密码。
+5. 修改成功后，系统会按角色进入对应页面。
+
+角色入口：
+
+- 管理员：进入「系统管理」，可维护产品、标杆笔记、违禁词。
+- 组长：进入「审核台」，负责通过或打回内容。
+- 运营：进入「开新任务」，负责生成内容和提交审核。
+
+## 2. 录入自己的 API Key
+
+进入「工作配置」或「设置」→「API Key」。
+
+1. 选择 Provider。
+2. 粘贴自己的 API Key。
+3. 点击「测试」。
+4. 提示测试通过后，点击「保存」。
+
+Provider 说明：
+
+- 主通道 apiports：必填，用于文案和图片生成。
+- 备用通道 codeproxy：选填，主通道繁忙时自动兜底。
+- Gemini：选填，作为备用能力。
+
+注意：
+
+- 系统只显示 Key 后 4 位，不展示完整 Key。
+- 每个账号使用自己录入的 Key。
+- 后续换 Key 时，点击对应通道的「修改」，重新填写后保存即可覆盖。
+
+## 3. 新建或维护产品
+
+进入「开新任务」。
+
+1. 在产品区域选择已有产品，或点击新建产品。
+2. 填写产品名称、品牌词、卖点。
+3. 上传产品参考图。
+4. 如果要让产品出现在生成图片中，必须至少上传一张清晰产品图。
+5. 可给产品图选择场景角色，例如主图、细节、使用场景等。
+
+产品图建议：
+
+- 图片清晰，瓶身或包装完整。
+- 不要使用过度裁切、遮挡、强滤镜图片。
+- 同一个产品可上传多张图，方便系统按分镜自动选择参考图。
+
+## 4. 创建生成任务
+
+进入「开新任务」。
+
+1. 选择产品。
+2. 填写本次内容主题。
+3. 选择是否「产品入镜」。
+4. 设置每套图片数量。
+5. 点击生成。
+
+系统会生成 A/B/C 三套不同叙事：
+
+- A：痛点先行。
+- B：场景先行。
+- C：成分背书。
+
+生成过程中不要关闭页面。若页面刷新，可回到「历史归档」或当前任务继续查看。
+
+## 5. 选择文案
+
+进入文案选择页后：
+
+1. 分别查看 A/B/C 三套文案。
+2. 每套选择 1 条文案。
+3. 注意查看质量分和合规提示。
+4. 三套都选完后，进入图片选择。
+
+如果文案不满意，可以重新生成。
+
+## 6. 选择图片
+
+进入图片选择页后：
+
+1. 图片按 A/B/C 三套分组展示。
+2. 每套需要选满任务设置的图片数量。
+3. 点击图片可放大查看。
+4. 不满意的图片可重生单张或整套。
+5. 如果某批图片失败，页面会显示失败原因，可点击重试。
+
+选图完成后，进入确认预览页。
+
+## 7. 提交审核
+
+在确认预览页：
+
+1. 检查已选文案、图片、标签和标题。
+2. 确认无误后点击「提交审核」。
+3. 任务会进入「待审核」状态。
+
+被打回后：
+
+1. 在任务页查看打回原因。
+2. 按组长意见调整文案或图片。
+3. 再次提交审核。
+
+## 8. 组长审核
+
+组长或管理员进入「审核台」。
+
+1. 查看待审核任务。
+2. 检查 A/B/C 三套内容、图片和质量分。
+3. 通过：内容进入可打包状态。
+4. 打回：必须填写打回原因，运营会在任务页看到原因。
+
+## 9. 下载交付包
+
+进入「历史归档」。
+
+1. 找到已通过审核的任务。
+2. 点击生成或下载交付包。
+3. 下载 zip 文件。
+
+交付包通常包含：
+
+- 每套笔记文案。
+- 已选图片。
+- 发布清单。
+- 合规说明。
+
+下载后请抽查压缩包内容是否完整。
+
+## 10. 裂变扩散
+
+进入「裂变扩散」。
+
+1. 选择一个已经通过审核的源任务。
+2. 选择参考程度。
+3. 设置裂变套数。
+4. 点击开始裂变。
+5. 完成后进入裂变结果页查看多套笔记包。
+
+如果系统提示使用了兜底草稿，需要人工复核标题、正文和分镜后再交付。
+
+## 11. 常见问题
+
+提示未配置 API Key：
+
+- 到「设置」→「API Key」录入并测试 Key。
+
+API Key 测试失败：
+
+- 检查 Key 是否复制完整。
+- 检查中转站余额和模型权限。
+- 检查是否选择了正确 Provider。
+
+产品入镜失败：
+
+- 检查产品是否上传参考图。
+- 换更清晰、无遮挡的产品图后重试。
+
+生成进度不动：
+
+- 先刷新页面或回到「历史归档」查看任务状态。
+- 若仍无变化，联系管理员检查 worker、SSE 和上游中转站。
+
+图片不符合预期：
+
+- 优先更换更清晰的产品图。
+- 对单张图片使用重生。
+- 必要时调整主题表达后重新生成。
+
+被组长打回：
+
+- 查看打回原因。
+- 按原因修改后重新提交审核。
+
+下载包打不开或内容缺失：
+
+- 重新生成交付包。
+- 若仍失败，联系管理员检查 uploads 持久化目录和打包任务日志。
+
+## 12. 客户交付前检查
+
+正式交付客户使用前，管理员需要确认：
+
+- 客户访问域名可打开。
+- HTTPS 证书正常。
+- 三类账号可登录。
+- 首次登录会强制改密。
+- 客户账号可以录入并测试 API Key。
+- 能完整跑通一条任务：建产品 → 生成 → 选择 → 审核 → 下载交付包。