From 1d688269da8aae647c63282a510702e1854cc899 Mon Sep 17 00:00:00 2001 From: seaislee1209 Date: Wed, 24 Jun 2026 02:31:18 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E7=A7=BB=E4=BA=A4=E6=8A=A5=E5=91=8A?= =?UTF-8?q?=E8=A1=A5=E5=85=85=20=E2=80=94=E2=80=94=20=E7=B3=BB=E7=BB=9F?= =?UTF-8?q?=E6=9E=B6=E6=9E=84=E5=9B=BE=20+=20=E6=8F=90=E7=A4=BA=E8=AF=8D?= =?UTF-8?q?=E4=BD=93=E7=B3=BB(6=E6=A8=A1=E6=9D=BF+=E6=95=B0=E6=8D=AE?= =?UTF-8?q?=E7=BB=93=E6=9E=84/=E6=95=B0=E7=BB=84)=20+=20=E6=BE=84=E6=B8=85?= =?UTF-8?q?=E8=BF=9C=E7=A8=8B=E5=BA=93/=E6=B5=8B=E8=AF=95=E6=9D=83?= =?UTF-8?q?=E9=99=90=20+=20=E5=9B=A2=E9=98=9F=E7=AE=A1=E7=90=86=E5=8F=82?= =?UTF-8?q?=E8=80=83=20AirDrama?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 加系统架构图(nginx/api/worker/MySQL/TOS/火山·中转站 + 后端 apps/前端结构) - 加「提示词体系」:6 条 admin 模板(正文+占位符+比例尺寸)+ 背后的数据结构/数组 (script_entities / entity_refs / dialogue / 视频 reference_images 的 asset:// vs 直链) - 澄清:应用直连远程测试库读写现有库没问题(真实验证就这么做的);只是 manage.py test 要建一次性 测试库需 CREATE 权限、该账号没有 → 单测走 sqlite。远程库连接是前一位同学搭的 - 团队管理可直接参考现有 AirDrama 项目(成熟,照补即可) Co-Authored-By: Claude Opus 4.8 (1M context) --- 项目移交报告-2026-06-24.md | 84 +++++++++++++++++++++++++++++++++++++- 1 file changed, 83 insertions(+), 1 deletion(-) diff --git a/项目移交报告-2026-06-24.md b/项目移交报告-2026-06-24.md index 01675ca..0bd73cf 100644 --- a/项目移交报告-2026-06-24.md +++ b/项目移交报告-2026-06-24.md @@ -34,6 +34,43 @@ - **默认模型**：图像 = `yunqi:gpt-image-2`；视频 = `doubao-seedance-2-0`；脚本/提取 = 豆包 doubao-seed-2.0-pro。 - **火山人像合规审核**：含人脸的素材（人物立绘/三视图/分镜图）自动送火山「人像素材库」审核，拿绿/红盾。 +### 系统架构图 + +``` + 浏览器(SPA) + │ https + ┌─────────────▼──────────────┐ + │ airshelf-core-web (nginx) │ ← 托管打包好的 React 静态资源 + │ ├─ /assets,/ → SPA(index.html, try_files 回落=客户端路由) + │ ├─ /api/ → 反代 Django + │ └─ /django-admin/,/static/ → 反代 Django(自带后台) + └───────┬──────────────┬──────┘ + /api │ │ /api(异步任务也读写同库) + ┌────────────────▼───┐ ┌──────▼─────────────────┐ + │ airshelf-core-api │ │ airshelf-core-worker │ + │ Django + DRF │ │ Celery(出图/出片/审核轮询)│ + │ (gunicorn) │ │ │ + └──┬────┬────┬───┬───┘ └──┬─────┬────────┬───────┘ + │ │ │ │ │ │ │ + MySQL │ TOS│ 火山│中转站 Redis MySQL 火山/中转站 + (远程 │(对象│ ARK │(yunqi/ (broker)(同一库) (同上) + 测试库)│存储)│直连 │ tokenssr) + │ │(豆包/ │ + │ │ SeeDream/ │ + │ │ Seedance) │ + │ └─ 人像素材库 Assets API(审核 + asset:// 引用,与 Seedance 需同账号) +``` + +**后端 Django apps（[core/backend/apps/](core/backend/apps/)）**： +`accounts`(团队/成员/邀请码/认证) · `products`(商品+商品图) · `projects`(项目/脚本/故事板/视频段/时间轴) · +`assets`(资产+文件+模特库+审核) · `ai`(Provider/模型配置/AI任务/提示词模板/质量词/脚本Agent/各生成 service) · +`billing`(团队账户余额/预扣/流水) · `adminpanel`(平台超管后台 API) · `common`(团队作用域 mixin/健康检查)。 + +**前端（[core/frontend/src/](core/frontend/src/)）**：`App.tsx`(壳+路由) · `routes/pipeline.tsx`(5 阶段流水线主页，最大的文件) · +`routes/admin/*`(平台后台) · `routes/products/projects/library`(商品/项目/成品库) · `components/`(共享组件) · `design-restraint.css`(设计 token/组件)。 + +> 数据/计费动作统一走「团队作用域」(`TeamScopedViewSetMixin`)；生成统一「预扣额度 → 成功扣费 / 失败释放」。 + --- ## 2. 视频生成流程现状：✅ 顺畅，已跑通 @@ -59,6 +96,46 @@ --- +## 2.5 提示词体系（admin 6 条模板 + 数据结构/数组） + +提示词**不再写死**：admin「提示词」页存「一段固定模板 + 几个 `{占位符}`」，生成时把角色/场景/商品/脚本等**自动塞进占位符**，拼成最终发给模型的正文。代码在 [services.py](core/backend/apps/ai/services.py) `render_prompt()` / `prompt_ratio_size()`（DB 模板覆盖代码写死默认；模板删了/停用就回落默认，零回归）。比例靠模板的 `ratio` 字段 → gpt-image 尺寸（`_RATIO_TO_SIZE`）。 + +### 6 条模板（DB 当前值） +| key | 名称 | 比例→尺寸 | 占位符 | 模板正文 | +|---|---|---|---|---| +| `person_portrait` | 人物立绘 | 竖2:3→1024×1536 | `{描述}` | 电商真人模特，氛围正面全身照，**{描述}**，自然妆容，柔和影棚光，真实质感，单人，纯色背景 | +| `person_triview` | 人物三视图 | 16:9→1536×864 | （无，靠参考图1） | 参考图1角色，生成角色三视图：胸像特写/全身正面/侧面/背面，白色背景 | +| `product_triview` | 商品三视图 | 16:9→1536×864 | `{商品}` `{补充}` | 参考图1是「**{商品}**」真实主图。严格参照生成三视图：正面/侧面/背面，纯白背景，**{补充}** | +| `scene` | 场景图 | 16:9→1536×864 | `{场景描述}` | **{场景描述}**（外层风格可在 admin 包） | +| `storyboard_frame` | 分镜图 | 竖2:3→1024×1536 | `{设定}{场景上下文}{时长}{脚本}{补充}` | **{设定}**根据脚本生成导演故事板…（保持各参考图同一张脸/同一商品）；竖屏 9:16 | +| `video_segment` | 视频 | 竖屏(参数) | `{设定}{分镜}{脚本}{时长}` | **{设定}{分镜}**【脚本】**{脚本}**\n电商带货短视频…不要字幕/背景音乐，要逼真音效 | + +> ⚠️ 占位符是「调用字段」，**改模板时别删它们**（删了运行时原样保留、不会崩，但就拼不进内容了）。视频的时长/比例是 **API 参数**(duration/ratio)，不在正文。 + +### 关键数据结构（占位符背后的「数组」） +脚本 Agent 产出结构化 `ScriptDraft`，落 `ScriptVersion.metadata` + 逐镜 `ScriptSegment`，并回填 `project.metadata` 供下游： + +- **`project.metadata.script_entities`** —— 提取出的角色/场景/商品实体数组（占位符 `{设定}`/参考图来源）： + ```json + [{"id":"c1","type":"character","name":"学生女主"}, + {"id":"c2","type":"character","name":"室友"}, + {"id":"p1","type":"product","name":"电子吧唧"}, + {"id":"s1","type":"scene","name":"女生宿舍书桌"}] + ``` +- **`ScriptSegment.entity_refs`** —— 本镜引用的实体 id 数组：`["c1","c2","p1","s1"]`（决定本镜带哪些参考图）。 +- **`ScriptSegment.dialogue`** —— 结构化对白数组（视频 `{脚本}` 的台词，照原样带说话人）： + ```json + [{"speaker":"c2","line":"你偷偷跟谁聊天呢？老实交代！"}, + {"speaker":"c1","line":"哎呀你别瞎想！"}] + ``` + （`speaker` 是实体 id，渲染时用 `script_entities` 解析成名字；另有扁平 `narration` 兜底。） +- **`ScriptSegment`** 其它：`visual_prompt`(画面)、`product_exposure`(商品露出)、`duration_seconds`、`sort_order`。 +- **视频 `reference_images` 数组**（传给 Seedance，与提示词 `@图N` 顺序严格对齐）： + `["asset://asset-…(角色)", "asset://asset-…(角色)", "https://…(场景)", "https://…(商品)", "asset://asset-…(分镜图)"]` + —— **含人脸的(角色/分镜图)走 `asset://` 素材库引用，无脸的(场景/商品)走原始直链**（见第 2 节）。 + +--- + ## 3. 我们这一程做了什么（2026-06-22 ~ 06-24） 按模块归类（完整见 `git log`，均带 Claude 署名）： @@ -157,6 +234,8 @@ DB_ENGINE=sqlite DJANGO_SETTINGS_MODULE=airshelf.settings.test .venv/bin/python - **计费**：每团队一个 billing `Account`（`balance` + `reserved_balance`），生成走**预扣 → 成功扣费 / 失败释放**（`CreditReservation` + 流水）； - **平台超管后台**（`/admin`，分阶段已上线）：概览 / 邀请码 / 团队 / 用户 / 提示词 / 质量词 / 资产审核 / 任务监控 / 模型供应商 / 计费审计 / 额度策略 / 治理。 +> 💡 **团队管理这块可直接参考现有的 AirDrama 项目** —— 它的团队/成员/额度/计费这套已经成熟，照着补我们缺的部分即可，不用从零设计。 + **可能缺 / 待复核（接手可以扫一遍确认）：** - **团队主自助管理**：团队 owner 在「前台」自助改团队名/管成员/看本团队用量的页面是否完整（很多管理动作目前集中在平台超管后台）。 - **充值/加额闭环**：团队余额怎么充？目前看到的是**注册发试用额度** + 超管手动调额；有没有「自助充值」入口要确认（可能本期不做）。 @@ -168,7 +247,10 @@ DB_ENGINE=sqlite DJANGO_SETTINGS_MODULE=airshelf.settings.test .venv/bin/python ## 7. 其他要提醒接手同学的点 / 风险 - **`.env` 进 git 且含真实密钥**：`core/backend/.env` 被**有意放行进版本库 + 打进 CI 镜像**（`.gitignore` 里 `!core/backend/.env`），里面是真密钥（火山/TOS/中转站/TTS）。这是当前团队**有意为之**（就内部几人用）。移交时**提醒新人别外传仓库**，长期建议改走 K8s Secret / CI 注入。 -- **测试环境与本地共用同一套测试 MySQL**：本地 development 设置直连真测试库；跑 Django 单测必须 `DB_ENGINE=sqlite`（远程库无建库权限）。改数据小心。 +- **关于「连远程库」和「跑测试」（澄清一个易混点）**： + - **应用本身**（本地 development / 线上）**直连远程测试 MySQL**，读写**现有库**没问题 —— 本报告里所有「真实数据验证 / 真跑 ARK·Seedance 接口」都是这么连着远程库做的。 + - **但 Django 的单元测试运行器**（`manage.py test`）会**临时 CREATE 一个一次性测试库再删掉**，这一步需要 `CREATE DATABASE` 权限，而**这个 MySQL 账号没有该权限**（不是不能读写现有库，是不能建新库）。所以**单元测试走 `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。 - **审核超时**：含人脸素材送审后若长时间没人轮询（之前故事板趴不轮询）会被本地超时兜底标「未过审」——这是误判，红盾点「重新送审」即可（现已加故事板趴轮询）。