From c7baf5cc9d940f3d9b7ed69509b2dd41318737fc Mon Sep 17 00:00:00 2001
From: seaislee1209 <seaislee@sohu.com>
Date: Wed, 24 Jun 2026 02:04:08 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E9=A1=B9=E7=9B=AE=E7=A7=BB=E4=BA=A4?=
 =?UTF-8?q?=E6=8A=A5=E5=91=8A(2026-06-24)=E2=80=94=E2=80=94=20=E6=95=B4?=
 =?UTF-8?q?=E4=BD=93=E7=8A=B6=E5=86=B5/=E6=9C=AC=E7=A8=8B=E6=94=B9?=
 =?UTF-8?q?=E5=8A=A8/=E8=A7=86=E9=A2=91=E6=B5=81=E7=A8=8B=E7=8E=B0?=
 =?UTF-8?q?=E7=8A=B6/=E5=B7=B2=E7=9F=A5=E5=BE=85=E5=8A=9E/=E5=9B=A2?=
 =?UTF-8?q?=E9=98=9F=E7=AE=A1=E7=90=86?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

给接手同学的速览:项目是什么、视频生成流程已端到端跑通、本程(06-22~06-24)做了什么、
已知小问题(admin刷新404已修/借AirDrama账号待换/视频poster/质量词半接/线上建商品复核)、
团队管理现状与缺口、风险提醒、已有文档索引、跑起来&部署速记。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 项目移交报告-2026-06-24.md | 200 +++++++++++++++++++++++++++++++++++++
 1 file changed, 200 insertions(+)
 create mode 100644 项目移交报告-2026-06-24.md

diff --git a/项目移交报告-2026-06-24.md b/项目移交报告-2026-06-24.md
new file mode 100644
index 0000000..01675ca
--- /dev/null
+++ b/项目移交报告-2026-06-24.md
@@ -0,0 +1,200 @@
+# AirShelf 项目移交报告 · 2026-06-24
+
+> 给接手的开发同学：这份是当前项目整体状况 + 我们这一程做了什么 + 还差什么的速览。
+> 配合看仓库里已有的：[CLAUDE.md](CLAUDE.md)（工程约定/铁律）、[core/ARCHITECTURE.md](core/ARCHITECTURE.md)、[PRD.md](PRD.md)、[交接-AI生成Agent化-2026-06-17.md](交接-AI生成Agent化-2026-06-17.md)。
+
+---
+
+## 0. 一句话结论
+
+**核心「商品 → 视频」生成全流程已经端到端跑通**（实测项目「电子吧唧 · 短视频 · v3」四段视频全部出片）。
+所以**视频这条线暂时不用再投入**，可以先去做别的。下面第 5、6 节列了几个**已知小问题 + 临时依赖**，不阻塞主流程，回头清。
+
+---
+
+## 1. 项目是什么
+
+- **AirShelf** —— AI 短视频带货生成平台。一条流水线把「一个商品」变成「可投放的竖屏带货短视频」。
+- **真实开发目录在 [core/](core/)**（仓库根的 `电商AI平台/` 只是 UI 设计稿/视觉标准答案，不是运行代码）：
+  - [core/frontend/](core/frontend/) —— React 19 + Vite + TS，真网站前端。
+  - [core/backend/](core/backend/) —— Django + DRF + Celery，后端 + 平台后台。
+  - [core/qa/](core/qa/) —— 截图对比测试。
+- **部署**：Gitea Actions（[.gitea/workflows/deploy.yaml](.gitea/workflows/deploy.yaml)）→ 打 Docker 镜像 → K8s。
+  - dev 分支 → **测试环境**：前端 `https://airshelf-web.test.airlabs.art`，推 dev 自动构建部署。
+  - 三个核心服务：`airshelf-core-api`（Django）、`airshelf-core-worker`（Celery）、`airshelf-core-web`（nginx 托管 SPA + 反代 /api）。
+
+### 生成流水线（5 阶段）
+```
+商品(选品) → 脚本(脚本 Agent 流式对话) → 实体提取(角色/场景) →
+基础资产(人物立绘/三视图 · 场景图 · 商品三视图) → 故事板(分镜图) → 视频(Seedance 逐段出片)
+```
+
+### AI 链路（详见 CLAUDE.md「AI 生成 Agent 化架构」）
+- **可插拔 Provider**：火山官方直连 `VolcanoArkProvider`（豆包/SeeDream/Seedance）+ 通用中转站 `OpenAICompatibleProvider`（yunqi/tokenssr）。分流在 [services.py](core/backend/apps/ai/services.py) `build_provider()`。
+- **默认模型**：图像 = `yunqi:gpt-image-2`；视频 = `doubao-seedance-2-0`；脚本/提取 = 豆包 doubao-seed-2.0-pro。
+- **火山人像合规审核**：含人脸的素材（人物立绘/三视图/分镜图）自动送火山「人像素材库」审核，拿绿/红盾。
+
+---
+
+## 2. 视频生成流程现状：✅ 顺畅，已跑通
+
+实测 `电子吧唧 v3` 四段视频提交火山全部 ACCEPTED、正常出片。让它跑通的**关键认知**（接手必懂）：
+
+> **火山 Seedance 2.0 对「写实人脸」的原始图片直链会直接 400 拒**（`InputImageSensitiveContentDetected`）。
+> 含人脸的参考图（人物立绘、分镜图）**必须走「素材库引用」`asset://asset-xxx`**，而不是原始 TOS 直链。
+> 素材库引用要求：① 资产已送审进库（有 `review_remote_id`，processing 也行，不必等 active）；② **素材库和 Seedance 必须同一个火山账号**（见第 5.2 节临时依赖）。
+
+代码位置：[services.py](core/backend/apps/ai/services.py) `_seedance_ref_url()` / `_video_reference_images()`。
+
+### 视频提示词（admin 可改）
+真正发给 Seedance 的正文长这样（admin「提示词」页的「视频」卡可改模板）：
+```
+【设定】@图1是学生女主(角色)，@图2是室友(角色)，@图3是女生宿舍书桌(场景)，@图4是商品(商品)。
+【分镜】根据@图5分镜图生成「电子吧唧」短视频。
+【脚本】画面:… / 台词:室友：… / 学生女主：…
+电商带货短视频，商品露出清晰，节奏有转化感。不要字幕，不要背景音乐，但是要有音效，逼真的音效。
+```
+- 时长/比例（duration/ratio/resolution）**是 API 参数单独传**，不写进正文。
+- 对白带说话人、照脚本原样放（不再拍扁成一行口播）。
+
+---
+
+## 3. 我们这一程做了什么（2026-06-22 ~ 06-24）
+
+按模块归类（完整见 `git log`，均带 Claude 署名）：
+
+**提取（角色/场景）**
+- 实体提取改**异步 worker + 轮询**，根治线上 502 / 刷新丢 loading / 重复扣费。
+- skills 随后端打进镜像（之前放仓库根 → 镜像里没有 → 系统提示词为空 → 提取吐散文解析失败）。
+- 锁定豆包 2.0 Pro + 写死 JSON 输出契约兜底。
+
+**视频（本程重点，让它跑通）**
+- ⭐ **真人/分镜图走素材库 `asset://` 锁脸**，根治 Seedance「人物/场景全错」。
+- 提交报错**接住返 JSON、不再 500 白屏**；分镜图 processing 态也能走 asset://。
+- 视频卡交互反馈（重跑转圈、防连点双扣）、「全部重跑」真重跑已完成段、「共 N 版」入口。
+- 视频卡用首帧当封面（`#t=0.1`），不再空白占位。
+- 视频提示词：台词带说话人、时长/比例只走参数。
+
+**故事板**
+- 整张生成时每张分镜转圈（不全屏遮挡）、未生成占位回 2:3 竖屏。
+- ⭐ 分镜图挂**火山人像审核盾** + 红盾可「重新送审」（审核超时是误判，重提即过）。
+
+**商品**
+- ⭐ 建商品改 **upload-first**（图先进桶拿 asset，创建时带 `cover_asset`+`images` 一块落库），根治「商品创建失败」。
+- 商品图删除接通（之前叉子是纯 CSS 装饰没绑事件）+ 至少保留一张。
+
+**图片比例 / admin**
+- admin「提示词」页：视频线 6 条生图/视频提示词正文 + 比例**可在后台改，不再写死**。
+- 真 16:9 支持（`1536x864`，原来误当 3:2）；人物三视图/商品三视图/场景图默认设成 16:9（分镜图/立绘/视频保持竖屏）。
+- 脚本按向导选的时长出（之前写死 60 秒）。
+
+---
+
+## 4. 怎么跑起来（接手速记）
+
+**本地后端（连真测试库，不是隔离 sqlite）**
+```bash
+cd core/backend
+DJANGO_SETTINGS_MODULE=airshelf.settings.development .venv/bin/python manage.py runserver 127.0.0.1:8010 --noreload
+```
+**本地前端**：`cd core/frontend && npm run dev`（5173，HMR；/api 走 8010）。
+
+**跑测试**（远程库无建库权限，必须 sqlite）
+```bash
+cd core/backend
+DB_ENGINE=sqlite DJANGO_SETTINGS_MODULE=airshelf.settings.test .venv/bin/python manage.py test
+```
+**部署**：推 dev → Gitea Actions 自动构建 + 跑迁移 + 滚动部署。**默认不推，改完即停，明确说推才推**（CLAUDE.md Git 铁律）。
+
+> 注：本机用的是 python-build-standalone 的 CPython 3.12（系统自带 3.9 跑不了 Django 5），venv 在 `core/backend/.venv`。
+
+---
+
+## 5. 已知问题 / 待办（不阻塞主流程，回头清）
+
+### 5.1 ⚠️ Admin 页刷新报「找不到网页」（404）—— 根因已定位，修法明确
+**现象**：在 `/admin/...`（如 `/admin/prompts`）刷新页面 → 404。点链接进去没事（前端路由），一刷新就挂。
+
+**根因**：路径冲突。
+- React 平台后台用的是客户端路由 `/admin`、`/admin/prompts`、`/admin/teams` …
+- 但 nginx（[core/frontend/nginx.conf](core/frontend/nginx.conf)）里有 `location /admin/ { proxy_pass …api }`，把 `/admin/` **反代给了 Django**；
+- Django（[core/backend/airshelf/urls.py](core/backend/airshelf/urls.py)）只有 `path("admin/", admin.site.urls)`（Django 自带后台），找不到 `/admin/prompts` → 404。
+
+**推荐修法**（把 Django 自带后台挪开，让 `/admin/*` 回落 SPA）：
+1. `urls.py`：`path("admin/", admin.site.urls)` → `path("django-admin/", admin.site.urls)`；
+2. `nginx.conf`：`location /admin/` → `location /django-admin/`。
+   这样 `/admin/*` 落到底部 `try_files $uri $uri/ /index.html`（SPA 路由），刷新就正常了。
+
+> 约 10 分钟的小改。要的话可以直接做。
+
+### 5.2 ⚠️ 临时借 AirDrama 火山账号（**待换自有，最该尽快处理的基建项**）
+- **真人素材库审核** 用的是借来的 AirDrama 账号 AK/SK（`.env` 的 `ASSETS_API_*`）。
+- **视频 Seedance** 我们临时也指到 AirDrama 账号（`.env` 的 `VIDEO_ARK_API_KEY`，仅覆盖 video 能力，见 [services.py](core/backend/apps/ai/services.py) `build_provider`）—— 因为 `asset://` 素材库引用必须和 Seedance 同账号才解析得到。
+- **终态**：等自有火山账号开通「人像素材库（Assets API）」后，把 `ASSETS_API_*` 换成自有账号 AK/SK，并删掉 `VIDEO_ARK_API_KEY` 这行（视频自动回落自有 `VOLCANO_ARK_API_KEY`）。CLAUDE.md 里记的「待张业昌换」就是这个。
+
+### 5.3 视频封面：后端抽帧没产出 poster（前端已兜底）
+- 后端 [services.py](core/backend/apps/ai/services.py) `_generate_video_poster` 本应抽视频首帧存成封面图，但当前环境**没产出 poster 文件**（大概率缺 ffmpeg/抽帧依赖）。
+- 现在靠前端 `<video src=…#t=0.1>` 让浏览器渲染首帧当封面，已经能看。要更稳/要真 poster 再补后端抽帧依赖。
+
+### 5.4 质量词页（admin）半接状态
+- admin「质量词」页目前**只喂 `model_tryon`（模特上身）**一处；人物/故事板/视频的质量词已经不接了（提示词改走「提示词」页）。
+- 现状不影响生成（质量词全空也不报错）。回头要么把它清成只留 model_tryon，要么并进「提示词」页统一管。
+
+### 5.5 线上建商品（需接手同学复核一次）
+- upload-first 修复已推 dev、线上 bundle 实测**含新代码**（旧「先建后传」drawer 已无）。
+- 之前有同事报「线上还是失败」，排查下来最可能是**测试时部署没完成 / 浏览器开着旧标签缓存**。请接手后**硬刷新**（Cmd/Ctrl+Shift+R）在 `airshelf-web.test.airlabs.art` 再建一次（记得拖图、等图转圈→完成再点创建）确认。若仍失败，开 F12 Network 看是 `/api/assets/upload/` 还是 `/api/products/` 挂、什么状态码。
+
+---
+
+## 6. 团队管理现状 + 缺什么
+
+**这个项目是按团队 + 平台超管两层来管的，地基是齐的：**
+
+已有（[apps/accounts/models.py](core/backend/apps/accounts/models.py) + [apps/billing/](core/backend/apps/billing/) + admin 后台）：
+- **Team**（团队，有 owner、状态、通知偏好）；
+- **TeamMember**（成员，角色 owner/admin/member、状态、**每人月度额度** `monthly_credit_limit`）；
+- **Invitation**（邀请码：超管发「开团码」= 新用户注册即开新团队当 owner；团队 owner 发「入团码」）；
+- **计费**：每团队一个 billing `Account`（`balance` + `reserved_balance`），生成走**预扣 → 成功扣费 / 失败释放**（`CreditReservation` + 流水）；
+- **平台超管后台**（`/admin`，分阶段已上线）：概览 / 邀请码 / 团队 / 用户 / 提示词 / 质量词 / 资产审核 / 任务监控 / 模型供应商 / 计费审计 / 额度策略 / 治理。
+
+**可能缺 / 待复核（接手可以扫一遍确认）：**
+- **团队主自助管理**：团队 owner 在「前台」自助改团队名/管成员/看本团队用量的页面是否完整（很多管理动作目前集中在平台超管后台）。
+- **充值/加额闭环**：团队余额怎么充？目前看到的是**注册发试用额度** + 超管手动调额；有没有「自助充值」入口要确认（可能本期不做）。
+- **认证**：登录/注册是「用户名 + 密码 + 邀请码」，**有意不做邮箱**（CLAUDE.md 有定调：2026 中国市场）；**手机号注册后续再做，本期未做**。
+- **5.1 的 admin 刷新 404** 也属于团队/后台体验问题，建议先修。
+
+---
+
+## 7. 其他要提醒接手同学的点 / 风险
+
+- **`.env` 进 git 且含真实密钥**：`core/backend/.env` 被**有意放行进版本库 + 打进 CI 镜像**（`.gitignore` 里 `!core/backend/.env`），里面是真密钥（火山/TOS/中转站/TTS）。这是当前团队**有意为之**（就内部几人用）。移交时**提醒新人别外传仓库**，长期建议改走 K8s Secret / CI 注入。
+- **测试环境与本地共用同一套测试 MySQL**：本地 development 设置直连真测试库；跑 Django 单测必须 `DB_ENGINE=sqlite`（远程库无建库权限）。改数据小心。
+- **skills 必须放 `core/backend/` 内**：镜像由 `./core/backend` 构建，skills 放仓库根会不在构建上下文 → 提示词加载为空。提取/脚本两套 skill 都在 [core/backend/skills/](core/backend/skills/)。
+- **设计规范铁律**：改任何页面/CSS 前先读 [电商AI平台/design.md](电商AI平台/design.md)，用现成组件、单橙锚点、8px 圆角、不写裸 hex。详见 CLAUDE.md。
+- **审核超时**：含人脸素材送审后若长时间没人轮询（之前故事板趴不轮询）会被本地超时兜底标「未过审」——这是误判，红盾点「重新送审」即可（现已加故事板趴轮询）。
+
+---
+
+## 8. 已有文档索引（别重复造轮子）
+
+| 文档 | 内容 |
+|---|---|
+| [CLAUDE.md](CLAUDE.md) | 工程约定 / 设计铁律 / AI 链路架构 / 认证定调（**接手必读**） |
+| [core/ARCHITECTURE.md](core/ARCHITECTURE.md) | 后端架构 |
+| [PRD.md](PRD.md) | 产品需求 |
+| [交接-AI生成Agent化-2026-06-17.md](交接-AI生成Agent化-2026-06-17.md) · [AI生成-Agent化落地方案.md](AI生成-Agent化落地方案.md) | AI 生成 Agent 化的设计与落地 |
+| [image调用参考.md](image调用参考.md) · [tokenssr接口文档.md](tokenssr接口文档.md) | 图像/中转站接口参考 |
+| [性能审计报告-AirShelf-2026-06-19.md](性能审计报告-AirShelf-2026-06-19.md) · [UI还原对比报告-AirShelf-2026-06-19.md](UI还原对比报告-AirShelf-2026-06-19.md) | 性能 / UI 还原审计 |
+| [电商AI平台/design.md](电商AI平台/design.md) | 设计规范 SSoT |
+
+---
+
+## 9. 给接手同学的建议优先级
+
+1. **先确认主流程**：本地（或线上硬刷新后）走一遍 商品→脚本→提取→资产→故事板→视频，确认四段出片。
+2. **修 5.1 admin 刷新 404**（10 分钟，体验问题）。
+3. **跟进 5.2 自有火山账号**（基建，影响长期；目前借号能跑，但要尽快换）。
+4. 5.3 / 5.4 / 5.5 看排期清。
+5. 视频线既然通了，可按团队安排去做**别的模块**（如团队自助管理 / 充值闭环 / 手机号注册等本期未做项）。
+
+— 本报告由本程结束时整理（2026-06-24）。有不清楚的，仓库 `git log`（带 Claude 署名的提交）每条 message 都写了「改了什么 + 根治什么」，可逐条回看。