QMTV 产品文档

• 1: 产品
  • 1.1: 00 · 交接导览（先读我）
  • 1.2: QMTV 移植契约规格（PRD）v1
  • 1.3: 01 · 系统设计方案
  • 1.4: 前端技术对比：qmtv（Vue3）vs pms web（React18+AntD5）
  • 1.5: 04 · 待开发功能与规划
• 2: 使用手册
  • 2.1: QMTV 使用说明书(页面图解版)
  • 2.2: 人工测试清单(QMTV QA 走查底稿)
  • 2.3: QMTV 使用手册 · 文档索引
• 3: 测试
  • 3.1: QMTV 测试规划（Go 版，P0 底册）
  • 3.2: QMTV E2E 测试约定
  • 3.3: QMTV E2E 场景清单（覆盖地图）
• 4: 功能规格（FSD）
  • 4.1: FSD M1 · 认证与用户
  • 4.2: FSD M10 · 导演与融合
  • 4.3: FSD M11 · 评估与工具
  • 4.4: FSD M12 · 管理后台
  • 4.5: FSD M13 · 火花计划
  • 4.6: FSD M2 · 任务与拆解
  • 4.7: FSD M3 · 生成与素材
  • 4.8: FSD M4 · 导出交付
  • 4.9: FSD M5 · 通知公告
  • 4.10: FSD M6 · 组织协同
  • 4.11: FSD M7 · 分销提现
  • 4.12: FSD M8 · 充值
  • 4.13: FSD M9 · 剧本库与投稿
  • 4.14: FSD 附录 · PRD 对照 / 代码域索引 / 差异台账
  • 4.15: QMTV 功能规格说明书（FSD）v1.0 · 总则

1 - 产品

• 项目导览——第一页：QMTV 是什么、能做什么，速览与文档地图
• PRD（v1）——生产工具+内容社区+商业化三合一的产品需求：用户旅程、积分体系与模块清单
• 系统设计方案（01）——三合一定位、积分体系、AI 链路与核心模块设计
• 前端技术对比（v1）——前端技术选型评估与结论
• 待开发功能与规划（04）——功能补强与演进规划

1.1 - 00 · 交接导览（先读我）

本目录是 QMTV 项目开发文档集，面向开发/运维的同事。建议按顺序阅读，全程约 30 分钟即可建立完整认知并跑起项目。

项目速览卡

文档地图

30 分钟上手路径

1. （5 分钟）读本文档 + 02-系统架构介绍.md 的目录结构一节
2. （5 分钟）npm install，两个终端分别 npm start 和 npm run dev（前端热更 :5173，代理到 :3300）
3. （5 分钟）用制片账号登录 producer@xingmang.cn / demo123456，把主导航每一页点一遍；再用管理员 admin@qmtv.com / admin123456 看管理后台
4. （10 分钟）读 03-系统交接说明.md 的「常见开发任务怎么做」与「踩坑清单」
5. （5 分钟）浏览 04-待开发功能与规划.md，确定你的第一个任务

三条最重要的经验（先记住再说）

1. 发中文请求调试一律写 Node 脚本（仓库里有大量 verify_*.js 可参照），不要用 curl/heredoc——Git Bash 下中文会 GBK 损坏，曾数次被误判为 bug。
2. 数据库是SQLite 单文件，改表结构统一走 server/db.js 的 migrations 数组（ALTER TABLE ... ADD COLUMN，try/catch 幂等），不要手改已有 CREATE TABLE。
3. 所有生成动作都走积分：先 tryDeduct 再调 providers.imageSmart/videoSmart，失败退款由 providers 内部统一负责，调用方不要重复退款。生成类入口只此一个约定，接手时务必遵守。

1.2 - QMTV 移植契约规格（PRD）v1

文档定位：本文是 qmtv 后端 Go+MySQL 移植的需求契约唯一权威——以冻结版 Node 实现（qmtv/server/，2026-10-17）的实际行为为基准逐条登记，外加已裁决的修正项。Go 版若与本文不符，以本文为准；本文与冻结代码不符处=修正项章节。上游设计参照：qmtv/docs/01-系统设计方案.md（冻结）。

后续 FSD 以 Go 实现代码为事实基准反向对账本文；本文修订走版本记录（§0.1）。

0.1 修订记录

1. 系统概览

AI 短剧内容生产线（拆解-出图-成片）+ 内容社区 + 积分商业化。单体后端，角色三档：游客（公开面）/ 用户（user）/ 管理员（admin）。

模块编号 M1M13（v1.14 起含 M13 火花计划——原 M1M12 对齐冻结代码 12 个路由文件，spark 2 条系漏登第八例补入，全文引用）。「端点数」列 = 冻结目标口径（v1.3 W10 校准：M2/M3 的 P0 统计残留已按冻结实存改；v1.7 十五续：M12 36→39 亲数勘误——冻结三文件 41 条物理 admin 路由，withdrawals 2 条归 M7；v1.8 十六续：M7 12→11 亲数勘误——P0 统计残留第四例；v1.9 十七续：M8 5→8 亲数勘误——P0 统计残留第五例，§4 清单自列 8 而标题/本表少算，与 M7 同型反向；v1.10 十八续：M6 38→29 亲数勘误——P0 统计残留第六例，冻结 index.js 组织段 9+enterprise.js 20=29、§4 清单自列即 29 而标题/本表多算 9，与 M7 同型「标题多算」；v1.12 二十续：M11 12→14 亲数勘误——P0 统计残留第七例，viral-analysis 2 条（index.js:490-513）物理夹在 M5 通知段与 M6 组织段之间不属于任何模块行、§4 M11 清单自列 6+6+2=14——与 M8 同型反向；v1.14 二十六期：新增 M13 火花计划 2 条——e2e 全站巡检抓获 Go 零 spark 路由回溯冻结源码，index.js:739-766「火花计划」段 2 条端点从未入任何模块行亦未计入历史合计（P0 统计残留第八例，与第七例同型「无模块行认领」）；「Go 已实现」列 = backend/cmd/server/routes.go 实装口径（2026-10-19 亲数）：

2. 全局契约（Go 版逐字节兼容面）

2.1 鉴权矩阵

2.2 uid 前缀常量表（infra/ids 集中定义）

u_ 用户、t_ 任务、shot_ 分镜、as_ 资产、img_ 图片、si_ 分镜图槽（index.js:249/:289）、v_ 视频、vid_ Mock 视频落盘文件名（assets.js:39，与行 id v_ 解耦）、cr_ 积分流水、nt_ 通知、rt_ 刷新令牌、e_ 导出（v1.5 勘误：原写 ex_，冻结 index.js:458 实证）、wb_ 工作台任务（workbench.js:55）、ev_ 评估项目（evaluation.js:248）、dpr_ 导演项目（v1.5 勘误：原写 dp_，冻结 director.js:274 + fusion.js:230 实证；含 dir_+projectId 伪外键挂 assets.task_id）、dsh_ 导演分镜（director.js:68）、dep_ 导演分集（director.js:99 + fusion.js:235）、ih_ 图片历史（index.js:324/:356 + director.js:214）、sl_ 剧本库（v1.5 勘误：原写 lib_，冻结 scriptlib.js:131/:222/:247 + studio.js:146 实证）、su_ 剧本使用记录（scriptlib.js:206）、sub_ 投稿（studio.js:53）、wp_ 写手档案（studio.js:90/:143）、na_ 解说任务（v1.5 勘误：原写 nar_，冻结 studio.js:167 实证）、ro_ 充值单（v1.5 勘误：原写 rch_，冻结 recharge.js:40 实证）、up_ 上传文件、fu_ 融合项（fusion.js:160）、rv_ 参考视频（fusion.js:210 + workbench.js:193）、au_ 音频（v1.3 勘误：P0 误写 aud_，冻结 routes3.js:391 实证）、vo_ 配音、tts_ TTS（assets.js:65）、wk_ 作品（v1.5 勘误：原写 w_，冻结 enterprise.js:69 works 实证）、cm_ 佣金（v1.5 勘误：原写 rc_，冻结 recharge.js:72 实证）、w_ 提现（v1.5 勘误：原写 wd_，冻结 index.js:621 实证——w_/wk_ 曾错位）、ex_ 佣金兑换（index.js:634）、va_ 爆款分析（index.js:507）、org_ 组织、pg_ 权限组、pt_ 提示词模板（promptCenter.js:36 冻结实证；Go prompts 内置不读表，存储面见 prompt_templates 补种注记——十四续 B1 补登）、mg_ 成员组、fd_ 素材夹（v1.5 勘误：原写 af_，冻结 enterprise.js:93 实证）、al_ 资产库（routes3.js:75）、an_ 公告（seed.js:24 + index.js:678）、inv_ 组织邀请（index.js:539）、me_ 自定义模型（models.js:19/:61）、oa_ 组织申请（index.js:516）、om_ 组织成员（index.js:547/:698）、st_ 风格（静态 id）、rr_ 审片报告（与 referral_relations 共用前缀——冻结两表均 uid('rr_')，UUID 空间无冲突，v1.2 注记）。

v1.5 已按 grep -ohE "uid\('[a-z_0-9]+'\)" qmtv/server/*.js | sort -u 全量复核回填（冻结 47 前缀亲数），Go 侧 51 常量（含基建 4）以 backend/internal/infra/ids/ids_test.go 全量对拍守卫钉死（TestPrefixes_FrozenContract）。

3. 修正项（冻结行为 → Go 行为）

4. 端点契约清单（M1~M13 + 基础）

表列：方法 路径｜鉴权（默认 Bearer，🔒=admin，公开面标注 ○）｜一句话契约。请求/响应字段以冻结代码为准，FSD 阶段逐模块细化（含字段表/校验规则/错误码）。

基础

M1 认证与用户（9，v1.2 清点修正）

M2 任务与拆解（38，v1.3 W10 校准：标题「66」系 P0 统计残留）

端点实装清单见 docs/API-增量.md M2 节（38 条逐条）。归组注记（v1.3 W10）：POST /api/images/storyboard/generate 物理位于冻结 index.js 生成段，routes.go 沿冻结分组归 M2 组（:141）——本节正文按实装口径收录。

CRUD：GET/POST /api/tasks、GET/PUT(title)/DELETE /api/tasks/:id、POST /api/tasks/:id/duplicate。 拆解双引擎：POST /api/tasks/v2（llm.isAvailable→异步 LLM 拆解/Mock 同步，split_status 状态机 idle/processing/done/failed/fallback——注〔三十期〕：idle/fallback 两态冻结与 Go 均无写入点，实现差异见 FSD m02 F2.03 §6；实际三态 done/processing/failed，DDL 默认 done）、POST /api/tasks/:id/resplit（20 积分）、POST /api/tasks/:id/restart、POST /api/tasks/:id/continue（对缺图镜头按 image_cost 补扣）、POST /api/tasks/:id/mark-failed 🔒、POST /api/tasks/:id/scenes/auto-generate(+ /cancel)。 资产：POST /api/tasks/:id/assets/extract 与 /extract2（2K，image_cost×N）、PUT /api/tasks/:id/extract-settings、POST /api/assets/:id/image/upload、POST /api/assets/:id/regenerate、POST /api/assets/:id/derive（衍生变体，parent_id）。 分镜：GET /api/tasks/:id/full 与 /full2（尾帧参考版）、GET /api/tasks/:id/scenes2、PUT/DELETE /api/tasks/:id/scenes/:groupNo、PUT /api/shots/:id、DELETE /api/shots/:id、POST /api/shots/:id/slots、DELETE /api/shot-images/:slotId、GET /api/shots/:id/histories、PUT /api/shots2/:id/params、POST /api/tasks/:id/storyboard-batch（批量补图）、POST /api/images/storyboard/generate（单镜补图，v1.3 W10 归组注记见上）。 资产库联动：GET/POST /api/asset-library、POST /api/asset-library/:id/share、DELETE /api/asset-library/:id、POST /api/tasks/:id/library-apply/:libId。 积分明细：GET /api/tasks/:id/credit-records。

M3 生成与素材（19，v1.3 W10 校准：标题「38」系 P0 统计残留——render-all 实属 M4、retry 无用户端点）

端点实装清单见 docs/API-增量.md M3 节（19 条逐条）。POST /api/images/storyboard/generate 归 M2 组（见 M2 归组注记）。

图片：POST /api/images/generate（COSTS.image，失败 providers 内部退款）、GET/DELETE /api/images/:id、GET /api/images、POST /api/images/upload。 视频：POST /api/videos/generate（COSTS.video）、POST /api/videos/generate-v2（videoCost(secs)=video_pull+per_second×secs，secs 1-15，reso 720p/1080p）、POST /api/videos/:id/cancel（cancelled 不退款）、POST /api/videos/tag（10×镜数）、GET /api/videos、GET /api/standalone-videos。 音频：GET/POST /api/audios、DELETE /api/audios/:id、POST/GET /api/videos/:id/voiceover（Mock WAV 字节级兼容）。 公开/辅助面：GET /api/style-presets ○（19 种风格预设）、GET /api/support/faq ○（静态 6 条）、GET /api/models/active（getBilling 投影——v1.3 W10 补登，PRD 原文全篇未列该端点；消费方 DashboardView/VideoView/Director3DView 三处〔三十期勘正，Director3DView 系 M10 落地后新增〕）。 异步契约：有 Key 时 video 提交→轮询（8s 首查/10s 步进/90 次上限）→SSE video 事件（done/progress/failed）；失败 refunded=1 防重退款。

实现差异（v1.3 W10 入正文，Go 实装 vs 冻结行为，全部显式登记）：①expires_at=C7 例外全达成（冻结 toISOString() 入库透传；Go ISOTime 响应 ISO、落库仍 DATETIME(3)）；②SmartVideo ⑩ 分辨率白名单外值（如 480p）冻结原样透传 vs Go 归一 1080p、ratio null 冻结传 null vs Go 归一 16:9（Go 收紧向，安全）；③SSE progress 冻结每次 fetch 前发 vs Go fetch 后发（tries 命中集合相同）；④tag 打标价冻结固定 COSTS.image=10 vs Go 随 F6 settings 覆盖价。

M4 导出交付（10）

POST /api/export（2 积分×完成段数，shot_count）、GET /api/export/:id（导出任务轮询面）、GET /api/export/task/:taskId（查重防重复扣费）、GET /api/tasks/:id/export/assets-deliver（2K 资产 ZIP）、GET /api/tasks/:id/export/deliver（全量 ZIP）、POST /api/tasks/:id/export/tag-all、POST /api/tasks/:id/export/render-all（Σ videoCost 批量渲染）、GET /api/tasks/:id/export/history、PUT /api/tasks/:id/export/scenes/:sid、GET /api/tasks/:id/jianying-draft（剪映草稿 JSON）。

实现差异（v1.3 W10 入正文）：①history 响应 v.* 列序——冻结 created_at 在 error 之后（db.js CREATE 后 ALTER 折叠序）vs Go DDL/struct 排末位：键集一致、前端按键取值无感，严格逐字节对拍不齐；②assets-deliver 条目名 index_no=0——冻结 JS truthy→asset_ vs Go != nil && != 0→shot000_（W6 期已修对齐冻结 truthy 语义）；③export repo 接口实为 16 方法（W5 基线「17」系计数漂移）；④F3 修正兑现——冻结 export_tasks 无 shot_count 列而 INSERT 显式引用（导出必报错存量 bug），Go DDL 含该列按修后语义（P0 裁决）。勘误（v1.3 W10）：本节原列「GET /api/export」系 P0 清单误计——冻结实存的是 GET /api/export/:id 轮询端点，无列表端点。

M5 通知公告（4）

GET /api/notifications、GET /api/notifications/unread-count、POST /api/notifications/read、GET /api/announcements/active（○；前端 localStorage qmtv_dismissed 由前端自理）。

✅ M5 落地（2026-10-19 W20，internal/domain/notification 读侧——hub 同包零新建）：App.vue 铃铛三面/AccountView 摘要 404 转绿（前端零改动）。实现差异登记：①read MySQL 保留字全 SQL 反引号（auth/repo.go:130 先例同制）；②POST read 无 id=整用户全标已读+恒 ok(true) 无 404 面（id 不属于自己也静默——冻结 :480-483 quirk 照抄）；③announcements/active 公开端点无 amw（冻结 :485 无 authRequired）；④通知零 SSE（前端 60s 轮询 unread-count）+读侧行形态兼容五源写入（auth/admin/recharge/seed/evaluation 自持 INSERT）。 | Claude |

M6 组织协同（29，v1.10 十八续勘误：标题「38」系 P0 统计残留——冻结亲数恰 29 条〔index.js 组织段 9 + enterprise.js 20〕，下清单即全量；与 M7 12→11 同型「标题多算清单对」第六例）

组织：POST /api/organizations/applications、GET /api/organizations/me、PUT /api/organizations/me/credit-allocation-mode（pooled/independent）、POST /api/organizations/me/invites、POST /api/organizations/join、DELETE /api/organizations/me/members/:memberId、PUT /api/organizations/me/members/:memberId/role（非 owner 拒，文案含「所有者」）、POST /api/director3d/:id/share、GET /api/organizations/shared-projects。 企业：GET /api/organizations/me/dashboard（冻结积分+14 天趋势+双排行）、GET/POST /api/showcase、DELETE /api/showcase/:id、素材库目录树 GET/POST /api/organizations/me/material/folders(+DELETE :id)、GET /api/organizations/me/materials、POST /api/organizations/me/material/assign、成员组 GET/POST /api/organizations/me/groups(+DELETE)、权限组 GET/POST/PUT/DELETE /api/organizations/me/perm-groups*、PUT /api/organizations/me/members/:memberId/assign、GET/PUT /api/organizations/me/material-perms*、GET /api/search（全站搜索）。 容量：素材 10GB 配额（images.file_size/audios.size 聚合）。

✅ M6 落地（2026-10-19，backend/internal/domain/org 单包多文件七件 29 端点全量）：integration 第九链 OrgChain（M12 approve 建组织→invite/join 全链→角色面三哨兵→dashboard available==balance 钉死→material-perms 联动端到端→showcase 恒 ok→share/search/401 面）。实现差异登记：①credit-allocation-mode 死端点照抄（前端零消费方，mode 非 independent 一律 pooled）；②dashboard available 恒=balance 无任何过滤+frozen 仅 eval_projects status=‘running’（M11 未落地恒 0）+projectRank dir_ 前缀死分支（实产 dpr_ 永不命中且 slice(4) 偏移亦错）——三处冻结谎言/死分支照抄不修，集成链钉死；③works.cover_path/asset_folders.org_id/member_groups.leader_id 等 Go DDL NOT NULL DEFAULT ’’ vs 冻结可空——读侧 NULLIF 还原 null（recharge ⑦ 先例）；④素材 10GB 配额系估算法非真 SUM（images.sum(file_size)+NULL 数×80KB+audios.sum(size)+videos 数×2MB 系数硬编码，plan 恒「基础档」，percent toFixed(1) 等价 Round(pct×10)/10）；⑤org_applications company/contact/reason 冻结不 slice 不 trim——Go VARCHAR(128) strict 溢出报错（SQLite 动态类型照收），超长输入行为差异；⑥invite code 冻结 Math.random base36 截 8 位大写 vs Go crypto/rand 同字母表（形态等价 ^[A-Z0-9]{8}$，值域随机性不属契约面）；⑦organizations.credits/org_members.quota/credit_allocation_mode 三列冻结无读写消费方（pooled/independent 分账完全未接线）——空转照抄；⑧DELETE /showcase/:id 与 DELETE /organizations/me/groups/:id 不查行数恒 ok:true（删他人/不存在均静默）；groups DELETE 无 404 面（403 后恒 ok）；⑨members target 不存在与 target 是 owner 合并同一 400「无法移除」（非 404 quirk）；⑩invites 文案「仅组织管理员可邀请」而判定 role=‘owner’ 严格（quirk 照抄，:553 移除面同款）；⑪PUT members/:memberId/assign 响应 group_id/perm_group_id 缺省时冻结回 null vs Go 回 ""（响应面未走读侧 NULLIF 还原——前端 assign 后重拉列表非回归，十九续 B3 登记）。十九续勘正（2026-10-19）：dashboard projectRank 谓词十八续误加 task_id != '' 曾把空串消耗聚合行（冻结 :37 IS NOT NULL 放行，以缺省名「独立生成 / 工具」kind=工具 GROUP BY 上榜）整行挡掉——已还原逐字+集成钉守（A4）；shared-projects video_id 谓词同批还原 IS NOT NULL（MySQL NOT NULL 列上即冻结字面）；shared-projects 投影补 script_text（冻结 dp.* 全列，组织共享面下发全剧本即冻结语义，用户裁决补齐）；projectRank wire 键 json:"amount-kind" 勘误 kind（A1，前端 OrganizationView 「类型」列曾恒空白——wire 键集断言守卫自此入惯例）。 | Claude |

M7 分销提现（11，v1.8 十六续勘误：标题「12」系 P0 统计残留——冻结亲数恰 11 条〔下清单即全量〕，与 M2 66→38/M3 38→19/M12 36→39 同型第四例）

GET /api/distribution/overview、GET /api/distribution/downlines、GET /api/distribution/records、GET/POST /api/distribution/withdrawals（状态机 pending→reviewing→topay→paid→done / rejected / cancelled）、POST /api/distribution/withdrawals/:id/cancel、POST /api/distribution/withdrawals/:id/confirm、GET/POST /api/distribution/exchanges、PUT /api/admin/withdrawals/:id 🔒、GET /api/admin/withdrawals 🔒。返佣：充值到账两级返佣（commission_rate/level2_rate 可配，默认 8%/2%）；满 980 元自动开 affiliate_enabled。

✅ M7 落地（2026-10-19，backend/internal/domain/distribution 单包多文件 11 端点全量）：integration 第七链 DistributionChain（seed 对拍 40 佣金/0.08-0.02-100/状态机全迁移/cancelled·rejected 不释放额度端到端钉死/exchanges 占扣/403/404 面）。实现差异登记：①withdrawals/exchanges 冻结的是佣金台账而非 users.credits——POST 两写面不触 credits/credit_records/通知/SSE，域零 credits 依赖（返佣写入方在 M8 approve 链，未落地前仅 seed 行可达）；②available 分母 SUM(withdrawals.credits) 无 status 过滤——cancelled/rejected 工单永不释放额度，:715 note「收益已解锁」与行为相悖系冻结谎言照抄不修（集成链 ⑨⑩ 双断言钉死）；③overview pending_withdraw 冻结双 IN 冗余（四态 AND 三态）→ Go 等价单 IN 三态（结果逐位一致，repo 注释钉行号）；④settings 回退三体 quirk：overview 无行回退 {0.2,0.05,100}（无 id 键）与 POST 提现面回退仅 {min_withdraw:100} 各自独立（Go 两 shape 不共用），种子行 0.08/0.02/100 覆盖表默认；⑤affiliate_threshold 硬编码 980（非 system_settings affiliate_threshold_cny，与 recharge.js:25 不同源）照抄；⑥credits 请求绑定 float64（冻结 +req.body.credits 强转）入库 int64（MySQL BIGINT 舍入 vs SQLite 动态类型可存小数——前端常态整数无差）——二十一期⑥ DECIMAL(12,2) 收口（0004）：withdrawals/exchanges credits 原值入库，差异终结；⑦reviewed_at 冻结 now()=UTC ‘YYYY-MM-DD HH:MM:SS’ 字符串 → Go time.Now().UTC() 显式（与 auth LocalTime 本地时先例刻意不同源）；⑧admin PUT 状态机 W_FLOW 严格邻接校验禁跳转（终态无键恒 400），动态文案 不允许从「X」流转到「Y」 W_ZH miss 原样回显英文态；⑨exchanges.status 恒 ‘pending’（全冻结无 UPDATE，死态照抄）；⑩withdrawals 2 条 admin 端点在本域（M12 裁决归 M7），AdminView 提现 tab 404 面转绿。

M8 充值（8，v1.9 十七续勘误：标题「5」系 P0 统计残留第五例——清单自列恰 8 条而标题少算，与 M7「标题多算」同型反向）

✅ M8 落地（2026-10-19，backend/internal/domain/recharge 单包多文件 8 端点全量）：integration 第八链 RechargeChain（config 对拍/下单 rate 换算/凭证真 multipart 落盘/approve 到账对账+两级返佣 8·2/资格联动 ≥980 自动开通+已开不重复/reject 双截断/admin list status 过滤/403/404 面）；integCleanup 扩 distribution 四表+recharge_orders（十七续 B2 收口，M8 链起共享清尾）。前端零改动（RechargeView/AdminView 充值面 404 转绿）。实现差异登记：①commission_records 唯一写入方在本域 approve 链（M7 差异①就此收口），order_amount/commission 绑定 float64→MySQL BIGINT round——冻结 SQLite INTEGER 列收 REAL 靠亲和性存原值（如 33 元二级佣金冻结存 0.66 并入账 0.66）——二十一期⑥ DECIMAL(12,2) 全链收口（0004）：pay 佣金原值入台账亦入余额，差异终结；②reviewed_at/reviewed_by——冻结 now()=UTC ‘YYYY-MM-DD HH:MM:SS’（recharge.js:93 与 M7 同源）→Go time.Now().UTC() 显式（M7 差异⑦同制）；③credits.Add ErrNoUser 显式 vs 冻结 addCredits 静默（util.js:66）——approve 链容错对齐（返佣 inviter 不存在冻结照写台账继续），其余 DB 错误照冻结 throw 传播；④settings 值非数字冻结 NaN→JSON null，Go 回退默认（settings 经 admin 白名单管理常态数字串不可达）；⑤affiliate_threshold 读 system_settings affiliate_threshold_cny 默认 980——与 M7 overview 硬编码 980 两处刻意不同源（M7 差异⑤），勿统一；⑥approveOrder 冻结导出「供重启复用」系死代码零消费方——Go 不建恢复链；⑦proof_path Go DDL NOT NULL DEFAULT ’’ vs 冻结可空——读侧 NULLIF 还原 null 透传（export normalizeExportTask 先例同制）；⑧二级返佣 from_user_id 恒=充值人（冻结 :78/:80 两级 pay 均传 o.user_id，非链上级）。

GET /api/recharge/config（1 元=N 积分 settings 面+收款码+推广阈值 980 默认）、GET/POST /api/recharge/orders（金额两位舍入/≥1 元/≤10 万；orderNo=‘RCH’+毫秒+3 位随机）、POST /api/recharge/orders/:id/proof（凭证上传 8MB，multer 两路由共用限额）、POST /api/admin/recharge-orders/:id/approve 🔒（到账+两级返佣+SSE recharge 事件+单笔达标自动开推广资格）、POST /api/admin/recharge-orders/:id/reject 🔒（note 落库截 200/通知截 100 缺省「凭证有误」两处不同源）、GET /api/admin/recharge-orders 🔒（status 过滤，‘全部’ 或空=不过滤，LIMIT 200）、POST /api/admin/pay-qrcode 🔒。

M9 剧本库与投稿（25）

Go 实现现状（v1.3 W10 盘点，P2 排期范围外）：M9 全部 25 端点 Go 零实现——前端剧本库弹窗/市集对 Go 后端 404 系排期现状非回归（迁移前后行为一致）。归属亲数勘误：scriptlib.js 9（genres/list/:id/use 四件 + admin script-library GET/POST/PUT/DELETE 四件 + upload 一件）+ studio.js 16（market/scripts 二件、投稿 submissions 四件、编剧 writer-profile 二件、writers 二件、admin/submissions 审核二件、admin cover+rating 二件、tools/narrations 二件）= 25。

✅ W13 落地（2026-10-18，backend/internal/domain/scriptlib 25 端点全量）：routes.go M9 组恰 25 条亲数；AdminMiddleware 接线 9 admin 端点（403 forbidden；十四续 B3 勘误「8」=scriptlib 5+studio 4 亲数）；integration 第五链 ScriptlibChain（ensureSeed 首触/submissions 全链/admin review publish 多表写/narrations 扣费 30 对账恒等式）；前端消费面 URL 不变零改动（Dashboard 弹窗/ScriptLibraryView/StudioView/WritersView/AdminView/IndependentToolsView 404 面转绿）。实现差异登记：①admin upload 修后语义——冻结 scriptlib.js:248 run 传 16 参数对 9 占位符，better-sqlite3 绑定超占位恒 throw RangeError（已实测坐实），冻结版 upload 端点从未可用，Go 按 9 列 INSERT 修后实现（F3 同制）；②cover_path 落库走 F8 口径（MinIO 绝对 URL/local /files/ 相对），冻结恒 /files/ 相对；③upload GBK 回退用 GB18030 解码（WHATWG TextDecoder(‘gbk’) label 实走 gb18030 算法）；④upload/cover 限额=路由级 BodyLimit（45mb/10mb）+handler 单文件校验（2MB/超 20 文件按 multer 语义 500），冻结 multer fileSize 单文件限制；⑤length()→CHAR_LENGTH（MySQL length 为字节数）；⑥char_count/preview/catalog 截断按 rune（JS UTF-16 BMP 等价，gateway.Err 300 rune 先例同制）；⑦go.mod 无新增依赖（golang.org/x/text 已在 indirect 转直接）；⑧writers 列表 search Go 侧 TrimSpace 后 LIKE（冻结 studio.js:105 直用原值不 trim）——用户裁决保持+登记（检索体验更稳；market 端点 search 与冻结一致不 trim，两处刻意不同源，repo.go 注释在）；⑨narrations 扣费台账 task_id 落 '' 而非冻结 null（credits.Record.TaskID 为 string 非 *string，沿既有 credits 模型形态——二十一期⑤已收口：0003 列 NULL 化+域内 ''→NULL 绑定；冻结 studio.js:158 tryDeduct 第 4 参 null）——credit-records 响应形态微差，待 credits 模型指针化时一并（十四续 B7 正文差异清单补登，v1.5 修订行已有同义注记）。

市集：GET /api/script-library/genres（含 markets/audiences/forms 配置）、GET /api/script-library（五维筛选/排序）、GET /api/script-library/:id（目录+试读）、POST /api/script-library/:id/use（7 日热度）、GET /api/market/scripts、GET /api/market/scripts/:id。种子幂等回填逻辑（ensureSeed）保留。 投稿：GET/POST /api/studio/submissions、PUT /api/studio/submissions/:id、POST /api/studio/submissions/:id/submit（draft→pending）、编剧档案 GET/POST /api/studio/writer-profile、GET /api/writers、GET /api/writers/:id。 管理：GET/POST /api/admin/script-library、POST /api/admin/script-library/upload（20 文件×2MB）、PUT/DELETE /api/admin/script-library/:id、POST /api/admin/script-library/:id/cover、PUT /api/admin/script-library/:id/rating、GET /api/admin/submissions、POST /api/admin/submissions/:id/review 🔒（needs_change/rejected/published；publish 自动建档+入库）。 解说：POST/GET /api/tools/narrations（30 积分，Mock WAV）。

M10 导演与融合（28）

导演：GET/POST /api/director3d、DELETE /api/director3d/:id、GET /api/director3d/:id、POST /api/director3d/:id/resplit、GET /api/director3d/episodes/:eid、POST /api/director3d/:id/episodes/:eid/extract-assets、POST /api/director3d/:id/episodes/:eid/shots（确定性 9 字段分镜）、PUT /api/director3d/shots/:id、POST /api/director3d/shots/:id/generate-image(-video)、GET /api/director3d/:id/export（ZIP）、POST /api/director3d/import。双表通路：director_shots 与 shots 并存，providers 按 shot._tbl 路由（Go 版以表名字段显式传递）。 融合：GET/POST /api/director3d/:id/assets、POST /api/director3d/assets/:id/generate（3 积分）、POST /api/director3d/:id/assets/batch-generate、POST/DELETE /api/director3d/assets/:id/queue*、GET /api/director3d/:id/queue（持久化队列 recoverQueue）、POST /api/director3d/:id/assets/import、POST/GET /api/director3d/:id/fusion*（融合生图）、POST /api/director3d/:id/remix（30 积分一键转剧）、GET/POST /api/director3d/:id/ref-videos*、DELETE /api/director3d/ref-videos/:id、POST /api/director3d/:id/convert/:eid（30 积分一键转剧——v1.11 勘正补列，原清单文字漏列而合计 28 自洽）。

✅ M10 落地（2026-10-19，backend/internal/domain/director 单包多文件 28 端点全量〔director.js 11+fusion.js 17——亲数 11+17=28 清点清白〕）：integration 第十链 DirectorChain（建项目→分集→分镜→分镜图/视频扣费对账恒等式贯穿→资产提取/生成/队列→融合/改创→参考视频→export ZIP 魔数→import ZIP→一键转剧→resplit→属主 404/401）。实现差异登记：①splitEpisodes 双阈值（resplit 1200/fusion CreateProject 800）刻意不同源勿统一（合参参数化）；②splitScenes 锚点前残余段亦成场景（「第一集 开端」头成 scene 目标——冻结 lookahead split 语义照抄，集成实测 5 目标坐实）；③「道具：」的「道具」二字亦命中 character 正则（冻结 :140 quirk 照抄）；④InsertShot 冻结字面 0 错位（:179 列 15 VALUES 16——字面 0 落 resolution、attempts 落 resolution 字符串，SQLite 动态类型容忍的存量 bug；F3 同族）——MySQL strict 恒 1265，Go 按修后语义 15 列 15 ?（resolution=草稿值/attempts=0）登记；⑤videoSmart Mock 分支 UPDATE shots 硬编码（providers.js:91 真实分支才按 tbl 路由）——导演分镜 Mock 生成后分镜行不回填（0 行静默），Go 按 tbl 意图语义打 director_shots（ShotView.Tbl 显式传递——PRD 双表通路约定落地）；⑥episodes 面 eid↔project 无关联校验（ep 按 eid 查活、project 按属主查——跨项目 eid 可达 quirk 照抄）；convert 例外（:256 WHERE id AND project_id 关联逐字）；⑦fusion cost=3 / convert flat=30 硬编码（非 ImageCost 面）+convert taskId=裸 p.id（非 dir 前缀，:259 照抄）；⑧convert 空场次：冻结 scene.split TypeError 恒 500（fallback 对象调 split）——Go 按意图语义以 ep.title 单场生成登记；⑨extract-assets 逐张生成失败 continue 不中断（冻结 providers.imageSmart 内部退款等价形态——域内 Refund 唯一口退单价 nil claim，调用方不重复退）；⑩assets/images 行 task_id=‘dir’+project_id 约定（M6 projectRank 聚合面依赖）；⑪promptcenter 模板查库面沿 M2 同源不查 prompt_templates（内置默认渲染——getShotImagePrompt 冻结有 getActive 查库，M2 起未接线，差异沿袭）——二十一期⑦已接线收口（shot_image/shot_video/asset_*×3 单级查库+内置默认回退，split 三级沿 SplitTemplate）；⑫buildShotFields JSON 键序 Go map 字典序 vs JS 插入序（JSON 对象语义等价，前端按键取）；⑬AssetJoined 等 JOIN 投影不选无字段列（gorp 反射报错——M6 GetWriterJoinedAt 同族教训，集成链抓获实修）；⑭multipart 两面 import 20MB/ref-videos 60MB（up60 新档位；upload 处理器内单文件上限双保险）；⑮空串形态与 Mock 台账 desc 两处漏登补记（二十续 B4）：assets/ref_videos 的 description/note 空串冻结恒写 ‘’（fusion.js:41/:212）vs Go 落 NULL（wire null vs “"——前端 ||'' 消费无感）；videoSmart Mock 失败退款台账 desc 参数化「导演分镜视频失败自动退回」vs 冻结硬编码「视频生成失败自动退回」（providers.js Mock catch——⑤只登记了 UPDATE 表名面）；冒烟面 404 属主过滤（英文短文案）+403 episodes/extract 属主面逐字。 | Claude |

M11 评估与工具（14——v1.12 勘正：evaluation.js 6+workbench.js 6+index.js viral 2；原清单 :208 自列 6+6+2=14 而标题少算，P0 统计残留第七例与 M8 同型反向）

评估：GET /api/evaluations/config、POST /api/evaluations/upload（txt/md/docx，UTF-8/GBK 自动识别，10MB）、GET /api/evaluations、GET /api/evaluations/:id、POST /api/evaluations（quick 100/deep 300 可配，8 角色×3 阶段流水线，冻结 cost 语义）、GET /api/evaluations/:id/report（txt 下载）；SSE eval 事件（stage/done/failed）；失败全额退款。 工作台：POST /api/workbench/tasks（转绘 20/去字幕 10/转高清 15）、GET /api/workbench/tasks（recoverWorkbench）、POST/GET /api/tasks/:id/review*、POST/GET /api/director3d/:id/review*（审片 10 积分，双入口共用 review_reports，scope classic/director）。 爆款分析：GET/POST /api/viral-analysis（COSTS.viral=5）。

✅ M11 落地（2026-10-19 W20，internal/domain/evaluation 单包多文件 14 端点全量〔workbench 6+eval 6+viral 2——v1.12 第七例勘正〕）：integration 第十一链 EvaluationChain（config 对拍→upload 真上传→扣 100 台账逐字+taskID=ev id→Mock 异步收口 waitFor done 不退款→report 下载头+体→列表定列/详情全列→404 双哨兵）+第十二链 WorkbenchNotifyChain（workbench 守卫三面→video_id 引用 done 成片 Mock done 扣 20 对账→审片双入口 404 两文案分叉+扣 10 台账+空分镜先退对冲→viral 扣 5→M5 四端点 unread-count 联动+read 单条/全标+announcements 公开/401）。实现差异登记：①costOf settings 值为 0 也回退默认 quirk 照抄（冻结 +r.value||def）；②engine 两字面不同源勿统一（config『规则(Mock)』vs POST『规则』）；③mode 非法静默归 quick 无 400；④runEval finished_at UTC 形态照抄（冻结 :181 toISOString 变形——与 created_at localtime 分裂同源）+Mock 节奏 sleep 1100/1500/900 照抄（mockSleep 可注入）；⑤LLM 通道 evalLLM 接线（modelCfg 三元+llm.Client.Chat——M12 反引号修复后已生效），模板查库不接线沿差异⑪先例（EVAL_PROMPT 兜底）——二十一期⑦已接线（eval_deep/eval_quick active 查库，content 空回退 EVAL_PROMPT；写侧 CATEGORIES 八键无此二键入口=冻结同 quirk 照抄）；⑥workbench watchVideo 状态丢失/tries>180 不 emit SSE 照抄（冻结 :84 无 bus.emit）+超时不退款照抄（providers 已退语义——与 generation PollTimeout 先例不同源勿统一）；⑦审片零 SSE 零通知+reviewShots target/scope 死变量不建+classic ’task not found’ vs director ’not found’ 404 文案分叉照抄+空分镜先退台账「审片退回：无分镜（+10）」逐字；⑧viral Math.random→math/rand+五列 INSERT（Go DDL status/version 惯例列默认）+title slice255 防御截断（冻结 SQLite VARCHAR 无约束存全量——MySQL strict 1406 防护，方言适配，二十一期 B2 补登）；⑨recoverWorkbench 整体迁移 evaluation.RecoverStuck（recovery/repo.go 预定注释兑现——四方法+BenchRef/BenchFailedErrorText 移除、WorkbenchRecoverer 窄接口注入；装配序教训：deps.eval 必须先于 recovery 建立的首跑 nil panic 被集成 RecoveryChain 抓获）；⑩workbench POST 双载荷形态（multipart 80MB up80 新档/JSON——WorkbenchView :131/:133 两形态）+taskId 无=空串（冻结 undefined——narrations ⑥ 同族沿袭）；⑪审片跨域共表读 COALESCE(image_prompt,’’)（冻结 ||'' 消费语义——集成链 NULL 直插行抓获存量炸点：gorp Scan NULL→string 恒错，shots 表真实 NULL 行同炸）；⑫workbench_tasks 可空列裁决=不收紧（source_path/video_id 二选一语义可空；DDL NOT NULL DEFAULT ’’ 即冻结 NULL 形态——wire null vs "” 随 M10 ⑮ 口径），delta 无 0003 维持；⑬GET /workbench/tasks out_url 双条件冗余+...w 展开 JOIN 伴列（out_path/video_status）照抄；⑭LLM 边缘面两处微差（二十一期核查 B4 登记）：parseEval 重复 dims key 累加 vs 冻结 find 首个（evaluation.js:125——仅 LLM 畸形输出可达）；报告模板缺失键 %v→<nil> vs 冻结 ||''（:271——Mock 全键不达）。 | Claude |

M12 管理后台（39）

用户与积分：GET /api/admin/summary、GET /api/admin/users、PUT /api/admin/users/:id、POST /api/admin/users/:id/password、GET /api/admin/credit-grant-records、POST /api/admin/credit-grant-records、GET /api/admin/credit-records/export（CSV）、GET /api/admin/runtime/tasks（运行时任务观测）。 生成审计：GET /api/admin/generation-audit/failures、POST /api/admin/generation-audit/videos/:id/release（人工退款，校验 refunded 防重）、POST /api/admin/generation-audit/tasks/:id/retry-split。 公告：GET/POST /api/admin/announcements、PUT /api/admin/announcements/:id。 组织审批：GET /api/admin/organization-applications、POST /api/admin/organization-applications/:id/approve(-reject)。 计费配置：GET/PUT /api/admin/credit-settings（白名单键，见 F6）、GET/PUT /api/admin/model-settings。 模型接入：GET/POST /api/admin/model-endpoints、PUT/DELETE /api/admin/model-endpoints/:id、POST /api/admin/model-endpoints/:id/activate、POST /api/admin/model-endpoints/:id/test（text→chat 8 token/image→红圆真生成/video→可达性，45s 超时；api_key 列表掩码前 6 位）。 提示词中心：GET/POST /api/admin/prompts、POST /api/admin/prompts/upload、PUT/DELETE /api/admin/prompts/:id、POST /api/admin/prompts/:id/activate（互斥生效版）；指令版本 GET/POST /api/admin/instruction-versions、PUT/DELETE /api/admin/instruction-versions/:id、GET /api/admin/instruction-versions/active、POST /api/admin/instruction-versions/:id/activate（v1.7 通配展开补登 PUT/DELETE :id 两条；DELETE 404 not found 与 prompts DELETE 的 版本不存在 刻意不同源照抄）。

Go 实现差异登记（v1.7 W14，internal/domain/admin 单包多文件沿 M9 先例）：①withdrawals 2 端点（GET/PUT /api/admin/withdrawals）随 M7 期落地，本期 404 系排期现状非回归；②死端点照抄：GET/PUT /admin/model-settings、GET /admin/instruction-versions/active 前端零调用（契约对齐，防演进踩空）；③ErrNoUser 吞形：grant/release 传不存在用户冻结 addCredits 静默 no-op 通知照发——Go credits.Add 显式 ErrNoUser 由管理台吞掉保冻结信封；④api_key 列表明文回显照抄（冻结 models.js:36 含原文+掩码双键）——管理台泄漏面，沿 C2 先例登记安全注记，未来收敛另立修正项（二十一期②已收敛：EndpointRow.APIKey 改 json:"-" 仅下发 api_key_masked/has_key——前端 AdminView.vue:206 只消费 masked 零消费实证，wire 与冻结分叉一处）；⑤instruction-versions DELETE 按修后语义打 prompt_templates（404 not found/400 文案逐字保持）——冻结查删 instruction_versions 死表（迁移后恒空→恒 404），F3 同制；⑥跨域共表写归表主域：retry-split 经 task.AdminRetrySplit（不删根资产=冻结原样，重复重拆根资产重复系冻结行为）、release 认领经 generation.ClaimManualRelease（CAS refunded=0+CONCAT(COALESCE(error,’’)) 追加一步，修冻结先查后改的并发窗，F9 同向）；⑦读侧衔接零失效逻辑与冻结同构，但 P0 起 modelCfg.setting() key 未反引号恒 1064——读侧配置链全哑的存量真 bug 由本期集成断言抓获并修复（见 v1.7 修订行④）；⑧prompt_templates 面不做 in-band ensureSeed（冻结 promptCenter.ensureSeed legacy 迁移在 Go 无源库）：cmd/seed 表级哨兵启动补种 5 行已覆盖，管理台 CRUD 纯存储面；⑨providers/publish 反向死调用不实现=echo 404 兜底即冻结形态（AdminView 对应调用在冻结版同样无后端端点，前端零改动面）。

M13 火花计划（2——v1.14 补登：index.js:739-766「火花计划」段；P0 统计残留第八例，与第七例同型「无模块行认领」——二十六期 e2e 全站巡检抓获 Go 零 spark 路由后回溯冻结源码定界）

报名激励：POST /api/spark/join（joined 守卫 400「您已加入火花计划」逐字 → users.spark_joined 置位 → 台账 kind=‘spark’ desc「加入火花计划奖励（+100）」→ 通知「火花计划报名成功」→ {joined:true,bonus:100}）；GET /api/spark/me（submissions 三计数：total 系 status!=‘draft’ / published / pending；三阶梯投影 min-max-per-name-perk〔星火 1-2 部 100/炬火 3-5 部 150/燎原 6+ 部 200〕+ reward_earned=published×per + next_tier 环形取下一档——燎原的下一档回星火）。

Go 实现（v1.14 W26，internal/domain/spark 单包三件）：逐字对齐无差异；errRespond 哨兵 ErrAlreadyJoined→400；集成第十六链 SparkChain（初态星火回退→join 三动作对账→重复 400→阶梯联动 submissions 直插→401 面）。

5. 数据模型概览

52 表终态（qmtv_main 单库）——分类/逐表裁决/视图清单见 docs/数据库表设计-qmtv.md（W9）；DDL 权威 = backend/migrations/full/qmtv_main_full.sql。状态表 22 张（version 乐观锁+entity_lifecycle_event 载体）、日志台账 4、字典配置 6、技术 1（refresh_tokens 重构）、资源明细 15、新增基建 4、裁剪 1（providers）。

P2 DDL 收紧（delta/0002，2026-10-18 落地）：tasks 5 可空 TEXT 列+shots 2 prompt 列 UPDATE 回填后 MODIFY NOT NULL（MySQL TEXT 无字面 DEFAULT——漏写列 strict mode 显式红=守卫语义）；seed.go tasks INSERT 全列写恒 ''；C7 例外不动（videos.prompt/error 保持 *string NULL 透传冻结语义）；director_shots（M10）/workbench_tasks（M11）待域落地随域裁决。seed Go 版一步到位差异：producer@xingmang.cn 独立演示账号（referral_code=QMXINGMANG01，与 demo 并存）+台账单笔 init（沿 SQL seed 惯例；冻结 demo 为 0 元 register 标记行形态）+prompt_templates 表级 COUNT 哨兵补种 5 行模板（Go prompts 内置不读表，纯存储面对齐产物无差）。恢复扫描窄投影：task 恢复 SELECT * 遇可空列 NULL 整段静默 no-op 已修（SplitRecoverRow 5 列窄投影，语义等价）——W8 集成抽样抓获。

6. 非功能约束

• 性能：SSE 心跳 25s；视频轮询 8s 首查/10s 步进/15min 上限；workbench 轮询 3s/5s/180 次；LLM timeout 240s；图片供应商 180s；模型测试 45s。
• 启动恢复四扫描：videos.processing→failed+退款、tasks.split_status=processing→Mock 回退、workbench_tasks.processing→按 video 状态收口、assets.queue_status=generating→回 queued。v1.3 P2 范围注记（W10 更新：四扫描已全部落地）：Go P2 W6 已内联实现全部四处（退款走 F9 唯一口 ClaimVideoRefund 认领置位）+幂等可重复启动——原注记「workbench_tasks 随 M11」已过时。实现差异登记（v1.3 W10 入正文）：①逐段容错——冻结 videos 段无 catch（异常即崩启动，SQLite 同步 API 副作用非设计）vs Go 统一逐段容错不挡启动；②workbench finished_at 冻结 datetime('now','localtime') vs Go NOW(3)（方言惯例）；③恢复扫描用 SplitRecoverRow 窄投影（§5，W8 集成抽样抓获后修）。
• 跨聚合扣款时序（v1.3 定稿，取代 TECH.md §5 actor+outbox 草案原则）：对齐冻结同步流——handler 内 credits.TryDeduct（CAS）→ 业务落库（videos/images 行）→ providers 调用 → 失败 → credits.Refund（F9 唯一口）；异步轮询 goroutine 持 ctx，重启丢轮询由启动恢复兜底（与冻结 setTimeout 语义等价）。不引 user actor 串行与 outbox 补偿：CAS 行锁已防超扣（冻结单进程无跨进程面）；RunWithRetry/isConflict 无生产原型（qmtv/pms 双侧零调用）。internal/actor、internal/event（outbox relay）维持 P0 骨架预留不强接。
• Mock 保真：SVG 渐变图/动画 SVG 视频/手写 WAV（16kHz/16bit/mono，voice 基频 female 523/male 330/child 659/narrator 392Hz）/19 种风格缩略图幂等文件名——Go 版产物对前端不可区分。
• 种子：admin@qmtv.com/admin123456（10 万积分）、demo@qmtv.com/demo123456（1335 积分+示例任务）、distribution_settings(0.08/0.02/100)、2 公告；幂等（有 admin 即跳过）。

7. 前端项目与演进轨道（v1.1 立项）

裁决（2026-10-17）：推翻「前端零改动、直接用 qmtv/ 冻结前端」口径——新建 frontend/ 独立前端项目。选型依据与优劣对比见 prd/前端技术对比-qmtv-v1.md（§2.3 可迁移经验与 §5 钉子表继续有效）。

7.1 项目形态（初始 = 复制，行为对等）

7.2 演进三件（后续期渐进落地，吸收 pms 模式而非换框架）

7.3 什么是 TS（TypeScript）

TypeScript = JavaScript 超集 + 静态类型系统（微软 2012 年发布）。所有合法 JS 都是合法 TS；它在 JS 基础上加了「编译期类型检查」这一层：

• 错误发现时机前移：纯 JS 的类型错误运行时才爆（用户点按钮才发现 undefined）；TS 在编辑器/编译期立刻红线。
• 运行时零开销：类型只是标注，编译（tsc / vite 内置 esbuild）时全部擦除，产出纯 JS——浏览器不认识也不需要认识 TS。
• 契约代码化：接口形状写成类型，传错即编译失败，无需等运行时验证。

interface User { id: string; credits: number }        // API 契约的类型化

function deduct(u: User, n: number): boolean {
  return u.credits >= n;   // 若误写 u.cridets：TS 编译期报错；纯 JS 要等运行时 undefined 比较才出错
}

deduct("不是User对象", 5);  // ❌ TS 编译期拒绝；纯 JS 静默放行，线上才炸

• 渐进迁移：allowJs 允许 .js/.ts 混用，可按文件逐个改后缀，不必 big-bang——对 qmtv 前端 9668 行 JS 的存量是唯一现实路径。
• 对本项目的意义：PRD 里 242 端点的请求/响应契约目前只存在于本文档文字；E3 落地后变成代码里的编译期断言（api 函数返回类型显式收敛），契约漂移在 CI 就被拦下。

7.4 约束

• §2 全局契约 C1~C12 对 frontend/ 全部继续有效——前端演进的是内部形态，不改后端兼容面。
• 端口：dev :5173 与冻结版同端口（同一时刻只跑一个；需要并行时 vite 自动 +1）；生产终态 Go :3300 托管 frontend/dist。
• 演进不反向解冻 qmtv/：冻结区保持对照基准原样。

1.3 - 01 · 系统设计方案

本文说明 QMTV 的产品定位、功能全景与各模块的设计方案。历史设计决策的完整推导过程见 D:\WORK\GAE\QMTV网站设计文档.md（22 节版本史）。

1. 产品定位

QMTV 是面向短剧/漫剧制作方的一站式 AI 内容生产平台，覆盖「剧本 → 资产 → 分镜 → 视频 → 成片 → 交付」完整链路，并配套内容生态（剧本库/评估/编剧激励）、企业协同（团队/权限/素材库）与商业闭环（积分/充值/返佣）三大体系。

设计原则：

• 生产工具 + 内容社区 + 商业化三合一：既做工具（对标巨日禄的项目内八类资源中心、工作台工具集），也做生态（对标新版 GAE 的剧本评估/剧本库/编剧广场），还做生意（积分计费/充值返佣/团队管理）。
• 积分是唯一硬通货：所有 AI 消耗统一折算积分，任务级流水可查，失败自动退款。商业模块（充值/返佣/提现）全部围绕积分展开。
• 功能零缺失复刻：以行业头部平台（manjuchuhai.cn 旧版/新版、video.jurilu.com）为参照逐项对齐，允许布局不同、不允许功能缺失。

2. 功能全景

QMTV
├── 创作生产
│   ├── 剧本拆解台        剧本→场次/分镜/资产，四种故事板生成方式，18 种视觉风格
│   ├── 导演工作台        项目→分集→分镜(9字段导演指令)→逐镜出图出片，八类资源 Tab
│   ├── 剧本视频生成      分镜→视频：一键下载/串行打标/全自动渲染/剪映包，智能审片
│   └── AI 工具集         独立生图/生视频/爆款分析；一键转绘/去字幕/转高清；本入剧出
├── 内容生态
│   ├── 剧本库市集        多维筛选+详情五区块(亮点/试读/人物/世界观/目录)+导入拆解台
│   ├── 剧本评估中心      8 AI 角色 × 3 阶段流水线，七维评分，逐集证据，深度/快速两档
│   ├── 编剧广场+投稿中心 编剧档案/主页，投稿状态流，过审上架剧本超市
│   ├── 火花计划          阶梯积分激励 + 现金奖池赛事页
│   ├── 作品展示          成片作品墙，发布/撤下/站内播放
│   └── 全站搜索          Ctrl K 同时搜剧本与编剧
├── 企业协同
│   ├── 企业管理台        数据看板(趋势+双排行榜)/成员角色/成员组/权限组/素材权限矩阵
│   ├── 企业素材库        目录树+10GB容量展示+共享素材跨成员可见
│   └── 项目共享          导演项目一键共享到企业
├── 商业闭环
│   ├── 积分体系          生成按量计费/任务级流水/失败退款/冻结-结算-退回
│   ├── 充值返佣          凭证审核入账、两级返佣(8%/2%)、满980自动开通推广资格
│   └── 管理后台          14 板块：用户/积分/公告/企业/提现状态机/模型接入/计费/剧本/提示词/指令/充值审核/投稿审核/任务审计
└── 平台基础
    ├── 模型接入注册表    文本/图片/视频三类，每条独立接口地址+密钥+模型名
    ├── 提示词中心        8 分类版本管理，占位符引擎
    └── 实时推送          SSE 事件流（视频进度/拆解完成/充值到账/审片报告）

3. 核心模块设计方案

3.1 剧本拆解（双引擎）

• 提交：POST /api/tasks/v2 接收剧本+配置（剧本类型/脸型/风格/时长区间/提取范围/自定义指令）。
• 引擎 A（规则拆解）：preprocess.js 正则识别场次/分镜/角色，确定性输出，秒级完成，永远可用。
• 引擎 B（LLM 拆解）：tasks/v2 走异步任务——取提示词中心生效的拆解指令（带输出合同：[CHARACTERS]/[SCENES]/[PROPS]/[SCRIPT]/[SHOT]/[IMG]/[VID] 段落标记），llm.js 调用注册表当前文本模型，parser.js 状态机解析回填。失败自动回退引擎 A 并站内通知。
• 设计要点：输出合同用段落标记而非纯 JSON——大模型对分段文本的遵循度比严格 JSON 高得多；解析器按行状态机容错，允许模型输出多余空行/前后缀。

3.2 资产一致性与融合生图

• 角色/场景/物品在项目内统一建档（assets 表），生成图后 image_id 回填，形成"资产卡"。
• 提示词组装：promptCenter.buildAssetPrompt(type, 描述, 脸型) 拼接资产类别模板 + 占位符替换，保证同角色跨镜头提示词同源——这是一致性的第一保障。
• 融合生图（3 积分/张）：组合角色/场景/物品卡描述 + 姿态/特效 + 画面描述 → 单张图，明确写入"保持所选资产外观一致性"指令。
• 图片改创：以项目内任意图为底图，原文提示词 + [改创要求] 后缀重新生成。
• 待生成队列：资产先入队（queue_status: idle/queued/generating/done）不扣费，生成时才计费；失败回 queued 不丢队列；重启时 recoverQueue() 把 generating 回退 queued（持久化挂起）。

3.3 分镜与视频渲染

• 分镜支持 9 字段导演指令（环境状态/叙事任务/世界空间锁/位置锁/轴线锁/投影/群像锁/逐秒动作/转场点，JSON 存 director_shots.shot_fields）。
• 视频/图片生成统一走 providers.imageSmart / videoSmart（见架构文档 §5）；批量渲染逐笔容错——单笔失败退款继续，返回 failed 计数。
• 智能审片（10 积分）：五维评分（主体一致性/画面美感/动作连贯/字幕与口型/穿帮检测）+ 分级问题清单 + 修复建议；LLM 可用时走结构化 JSON 审片，否则规则引擎，engine 字段标注来源。经典工作台与导演工作台双入口，报告存 review_reports。

3.4 剧本评估（多智能体流水线）

• 快速 100 / 深度 300 积分，提交冻结、完成结算、失败退回（tryDeduct type=‘reserve’）。
• 8 角色 × 3 阶段：一级 交付规范主审+交叉核验 → 二级 全剧主审+前十精读+情绪人物+海外市场 → 三级 证据复核+评分审定。阶段落库 eval_projects.stage，前端轮询渲染流水线动画。
• 七维评分（合计 100）：交付规范10 / 内容基础20 / 前10集转化20 / 人物情绪15 / 结构兑现15 / 海外适配10 / AI漫剧可视化10。
• 深度评估附逐集证据（按「第X集」切分，Mock 引擎与 LLM 提示词都要求按集给证据）。

3.5 剧本库市集与生态

• script_library（官方库）与 submissions（用户投稿）两源：官方库管理端维护；投稿过审后上架。字段完全市集化：题材/市场/受众/形式/标签/亮点/试读/人物小传/世界观/梗概/设定/集数/策划字数/编剧署名/评分/封面。
• 详情目录自动从正文解析「第X集」生成；导入使用记 script_uses（近 7 天热度驱动排序与 🔥 角标）。
• 火花计划：spark_joined 报名送 100 积分；阶梯 = 星火(1-2部过审,100/部) → 炬火(3-5部,150/部) → 燎原(6+部,200/部)；页面叠加现金赛事卡（奖池/奖项表/投稿入口）。

3.6 企业协同

• 组织/成员/邀请码；owner→admin→member 三级角色。
• 成员组（member_groups）与权限组（perm_groups：查看/编辑/删除/下载四权限 JSON）挂在 org_members 上；素材权限五项矩阵（查看/上传/下载/编辑/删除，org_members.material_perms）带联动规则：授上传/下载/编辑/删除自动含查看，授删除自动含编辑，取消查看清空全部——与行业对标产品一致。
• 数据看板：组织成员聚合的积分概览（可用+冻结）、近 14 天消耗趋势、项目消耗榜（credit_records.task_id 反查任务/项目名）、人员消耗榜。
• 素材库：asset_folders 目录树 + asset_library.folder_id 归属 + 容量估算（图片/音频真实大小、缺失按 80KB/2MB 估算，配额 10GB）。

3.7 商业闭环

• 计费：util.COSTS 基础价 + 管理端计费配置（视频=拉取5+每秒5，图片10，2K预览15，拆解20，爆款5，评估100/300，审片10，转绘20/去字幕10/转高清15，融合3，一键转剧30/集，导出2/段）。计费参数存 system_settings，管理端可改。
• 充值：创建订单→上传凭证→管理审核→approve 入账 + 两级返佣（一级 8%、二级 2%，从 distribution_settings 读）→ 单笔满 980 元自动 affiliate_enabled 开通推广资格。
• 提现状态机：pending→reviewing→topay→paid→(用户确认)done；任意审核阶段可驳回；pending/reviewing 可用户撤回解锁收益。非法流转被 W_FLOW 矩阵拒绝。
• 安全：JWT 密钥持久化 data/.jwt_secret（支持 QMTV_JWT_SECRET 覆盖）；登录 20 次/分/IP、注册 5 次/时/IP 限流；密码 hash 存储；管理端接口全部 adminRequired。

4. 数据模型设计要点

49 张表见架构文档 §6。关键设计决策：

• 多态引用：images.task_id 既存拆解任务 id（t_）也存导演项目前缀 id（dir_）；videos.shot_id 配合 shots._tbl 约定（providers 内部判断 director_shots/shots）指向不同表——避免为两套工作台建两套生成表。
• 积分流水即账本：credit_records(task_id) 使任意消耗可追溯到项目，管理端审计、项目积分记录、企业看板共用这一张表。
• 轻量迁移：所有列变更走 migrations 数组幂等 ALTER，历史兼容靠 COALESCE/DEFAULT 占位值（注意：迁移 DEFAULT 值会挡住后续数据回填，需显式覆盖，见交接文档踩坑 §7.4）。
• 种子数据幂等：剧本库种子按标题匹配回填，且只覆盖"默认占位值"（market=‘中国内地’ 等），不覆盖人工修改。

5. AI 链路设计

页面动作 → routes(校验+tryDeduct) → promptCenter 组提示词
  → providers.imageSmart / videoSmart
      ├─ 注册表有启用接入（base_url+api_key+model）→ 真实供应商
      │    图片：OpenAI 兼容 /images/generations（同步，比例→尺寸映射）
      │    视频：异步任务 提交→轮询(10s×90次)→下载回填→SSE通知；失败自动退款
      └─ 无接入 → 本地 Mock（SVG 占位图/动画视频/WAV 配音），同步返回
  → 结果落 images/videos 表 → bus.emit → SSE → 前端 toast + 刷新

• 模型接入注册表（model_endpoints）：purpose ∈ text/image/video，每条独立 base_url/api_key/model/enabled，active_model_<purpose> 指定当前使用；管理端可测试连通。
• 提示词中心（prompt_templates）：8 分类（split/shot_image/shot_video/asset_character/asset_scene/asset_prop/video_tag/viral+eval_quick/eval_deep）版本管理，单分类单生效；占位符 {描述}{脸型}{场次}{景别}{转场}{风格基调} 生成时替换。
• 失败语义统一：providers 内部退款并抛 {status, message}，全局错误中间件透传；调用方不得重复退款。

6. 视觉设计体系

• 三主题 CSS 变量切换（html[data-theme] = dark/light/gae + localStorage），深色为主品牌（深空蓝 #04060e 底 + #2f6bff→#22d3ee 电光蓝渐变），玻璃拟态面板（backdrop-blur + 半透明边框光晕）。
• 登录页左右分屏品牌大图；分镜卡 v-tilt 自定义指令 3D 悬浮倾斜（触屏禁用）。
• 导航为分组下拉（工作台/创作工具/内容生态），菜单文字固定浅色（浅色主题下 var(–text) 会在深色菜单底上不可读——历史踩坑）。
• 移动端断点：1100px 导航换行、900px 网格降列。

7. 兼容对标对照

1.4 - 前端技术对比：qmtv（Vue3）vs pms web（React18+AntD5）

文档定位：回答"前端不改写是确定的，但两套前端技术各有什么优劣"。结论前置：qmtv 前端零改动（已裁决）；本文是选型对比存档 + 为 Go 移植钉住前端兼容面 + 沉淀"若未来前端演进，哪些 pms 经验值得吸收"。事实基线：2026-10-17 双仓库实测。

修订（2026-10-17，PRD v1.1）：§3 结论「前端不动」已被新裁决取代——新建 frontend/ 独立前端项目（初始复制 qmtv 前端）+ 演进三件（@tanstack/vue-query / vitest+vue / TS 渐进），详见 prd-qmtv-v1.md §7。本文 §1/§2 事实对照、§2.3 可迁移经验（vue-query 等价获得、测试文化、类型收敛纪律）与 §5 钉子表全部继续有效；原文保留存档不改。

1. 两套技术栈事实对照

2. 优劣分析

qmtv Vue3 的优势（在它的场景里）

1. 极简依赖、零构建心智：6 个运行时依赖，13 行 vite 配置，单人可全栈维护；对 AI 辅助开发极友好（上下文小）。
2. 前端对后端零耦合：相对路径 + 单一 fetch 封装，后端换语言零改动（本次移植的前提，已验证成立）。
3. 产品形态匹配：C 端气质的创意工具（3D 分镜/主题切换/悬浮客服），手写组件的自由度比 AntD 中后台模板更贴合；AntD 反而会给它套上管理后台的壳。
4. vue-router 的 meta 守卫与 SFC 单文件组织，样板代码比 React 集中路由少。

qmtv 的劣势（真实欠账）

1. 无类型：9082 行 JS，接口契约只存在于约定；AdminView 14 个 Tab 1371 行单文件，回归靠人肉。
2. 无服务端状态层：缓存/失效/重试每页手写——Dashboard/Workbench 类多数据源页面复杂度爆炸的根因。
3. 零测试：239 个后端契约没有任何前端侧断言。
4. 无 i18n：纯中文硬编码，产品出海需全量改造。

pms web 的优势（可迁移的经验）

1. React Query 服务端状态模式是 pms 最值得移植的工程习惯——loading/缓存/失效全部声明式，191 处 useQuery 换来的是每个页面只剩"数据+渲染"。qmtv 若演进，@tanstack/vue-query 可等价获得，不必换 React。
2. 测试文化：页面测试近 1:1、Playwright 断言册与截图册物理隔离、i18n coverage 双重防护——这些约定与框架无关，可原样移植到 vitest+vue。
3. 类型收敛纪律：api 函数返回类型显式收敛、禁止 as any 兜底（注释溯源）——qmtv 若加 TS，这条是第一规则。
4. AntD5 中后台生态确实是复制式开发效率的根源；但注意 pms 实际只用了 ProLayout，ProTable/ProForm 红利并未吃到——“上了 AntD 就高效"要打折扣。

pms web 的劣势（对比中看到的税）

1. axios 运行时解包与 TS 方法签名的断裂需要 UnwrappedClient 类型修补层持续还债；Row 接口仍带 [k:string]:any 兜底。
2. 110 条路由零懒加载，bundle 全量；qmtv 反而做了按页面 code-split。
3. ProComponents 引入而未深度使用，依赖面大于收益面。

3. 结论

4. 迁移成本对照（假设反向迁移，仅作存档论证）

qmtv→pms 栈重写 ≈ 24 页面×(组件重写+React Query 接线+测试补齐) ≈ 与后端 Go 移植同量级的工程；而它解决的三个痛点（类型/服务端状态/测试）都能在 Vue 生态内补齐。重写框架 = 高成本解决低价值问题，此结论与"后端为何值得重写”（生产化运营的并发/部署/一致性硬需求）不同质。

5. Go 侧 8 条逐字节兼容约束（钉子表，PRD §2 已契约化）

1.5 - 04 · 待开发功能与规划

本文供排期参考。分四类：A 真实模型接入（最高价值）、B 产品功能补强、C 生产化改造、D 技术债与优化。每项标注预估规模（S≤1天 / M≤3天 / L>3天）与前置依赖。

A. 真实 AI 能力接入（拿到 Key 后第一优先）

验收清单（A1-A3 通用）：拆解→出图→渲染→导出全链路真实素材走通；失败退款正确（故意填错 Key 验证）；SSE 通知到达；项目积分记录与账实一致。

B. 产品功能补强（对标差距已清零后的深化）

C. 生产化改造（上生产环境前必做）

D. 技术债与优化

建议节奏

1. 第一周：A1+A2+A3（真实接入验证）+ C8 备份 —— 把"演示态"变"真实态"
2. 第二周：A4 审片 Vision + A5 成本核账 + D1 拆 index.js
3. 之后按业务方向二选一：To B 深耕 → B3/B4/C6（权限落地+独立配额+在线支付）；To C 生态 → B1/B2/B7（市集与社区）
4. 上生产前：C1-C5 按 C3（单机 pm2 + SQLite 维持）或 C1（多实例）两条路线二选一

已知问题（截至交接）

• 无 P0/P1 级 bug；以下为已记录的低优先观察项：
  • 提交拆解无 Key 时同步返回（量大会占连接），有 Key 后自然变为异步
  • 限流内存桶重启清零（C3 一并解决）
  • 作品墙/共享项目列表分页上限 60/默认（量大需翻页）
  • 移动端仅断点兜底（B9）

2 - 使用手册

• QMTV 使用说明书——页面图解版操作手册：24 页五段卡片（做什么/操作步骤/规则与注意）+ 计费速查表
• 人工测试清单——功能走查清单：T0~T7 旅程分层，覆盖登录、创作、生成、导出全流程
• README——手册目录与截图说明

2.1 - QMTV 使用说明书(页面图解版)

本手册面向 QMTV 平台的三类用户:工作台用户(拆解-出图-成片创作者)、企业管理员(组织与分销)、平台管理员(/admin 运营方)。 演示环境:http://localhost:3300(启动见 docs/DEPLOY.md §2.5);演示账号 admin@qmtv.com / admin123456(管理员)、demo@qmtv.com / demo123456、producer@xingmang.cn / demo123456。 截图来自 Playwright 截图管线(frontend/e2e/snapshots.spec.ts,重跑 cd frontend && npm run test:snapshots);Mock 模式下素材图为占位 SVG,真实供应商接入后为实际生成结果。 配套文档:人工测试清单(QA 走查底稿)· e2e 场景清单(自动化覆盖地图)。

测试旅程总览

flowchart LR
  A[第1章 快速上手] --> B[第2章 创作主链]
  B --> C[第3章 创作工具]
  A --> D[第4章 内容生态]
  A --> E[第5章 积分与账户]
  D --> F[第6章 企业与分销]
  G[第7章 管理后台]

第1章 快速上手

1.1 登录(/login)

入口:未登录访问任意页面自动跳转;路由 /login。

做什么:登录 QMTV 账号,进入工作台。

操作步骤:

1. 输入「邮箱」与「密码」(可点「显示」核对明文);
2. 点「登 录」(请求中显示「登录中…」),成功后进入首页 /。

规则与注意:

• 登录失败为原生弹窗提示(如「邮箱或密码错误」),非 toast;
• 页面不显示演示账号——演示账号见本手册头部;
• 左侧为产品流程卡:「01 剧本拆解 → 02 智能出图 → 03 成片合成」。

1.2 注册(/register)

入口:登录页「还没有账号?立即注册」;路由 /register。

做什么:注册新账号,注册即赠体验积分。

操作步骤:

1. 填「用户名」「邮箱」「密码(至少 8 位)」;
2. 有企业邀请码则填「企业邀请码(可选,注册即加入企业)」,没有留空;
3. 点「注册」,成功后自动登录进入首页。

规则与注意:

• 注册赠送 200 体验积分(台账「注册赠送 200 积分(初始)」,后台「计费配置」可调);
• 填了有效邀请码→邀请人得 50 积分;无效邀请码静默忽略;
• 昵称留空取邮箱 @ 前缀;密码后端强校验 ≥8 位。

1.3 申请企业入驻(/enterprise-apply)

入口:登录页「企业客户?申请企业入驻」;路由 /enterprise-apply,无需登录。

做什么:企业客户提交入驻申请,平台审核通过后自动创建企业组织并任命申请人为负责人。

操作步骤:

1. 填「企业名称」「联系人」「申请说明」;
2. 点「提交申请」→ 页面显示「申请已提交,等待审核。可在登录后于「企业管理」中查看进度。」。

规则与注意:审核动作在管理后台「企业审核」tab(§7.5);审核结果以站内通知告知。

1.4 首页(/)

入口:登录后默认落点;顶栏「首页」。

做什么:内容门户——查看积分余额、从四张入口卡进入核心功能。

操作步骤:整卡点击跳转:「01 剧本拆解台」→ /dashboard;「02 剧本视频生成」→ /video;「03 独立生成工具」→ /independent-tools;「04 爆款分析」→ /viral-analysis。

规则与注意:右上统计块实时显示「积分余额」与「当前账号」。

1.5 顶栏与全局功能

做什么:全局导航、搜索、主题、通知与账号入口。

操作步骤与规则:

• 导航下拉:「工作台」(拆解台/视频生成/导演工作台)、「创作工具」(独立生成/工作台工具集/本入剧出/作品展示/爆款分析)、「内容生态」(评估中心/剧本库/投稿中心/编剧广场/火花计划);「企业管理」「推广与收益」仅企业成员可见;「管理后台」仅管理员可见;
• 全站搜索(Ctrl/Cmd+K):搜「📚 剧本」与「✍️ 编剧」,回车跳首个结果;
• 主题切换:深色→浅色→雅致三态循环,记忆在浏览器本地;
• 工作台切换:「原始工作台」/「导演工作台」两版,切换即跳对应工作台;
• 🔔 通知:点开面板(60 秒轮询),支持单条/全部已读;业务完成另有实时推送 toast(视频/拆解/充值/工具四类);
• 积分胶囊:「昵称 · 可用 N 积分」,点击进账号中心;
• 右侧按钮:「充值」「积分记录」「修改密码」「退出」;
• 公告横幅:管理员发布的活跃公告显示在顶栏下,点「我知道了」不再显示。

第2章 创作主链(拆解 → 出图 → 成片 → 导出)

2.1 剧本拆解台(/dashboard)

入口:顶栏「工作台」→「🧩 剧本拆解台」;首页入口卡 01。

做什么:粘贴剧本文本,AI 拆解为场次/分镜/资产,再故事板抽卡生成分镜图——全链路的起点。

操作步骤:

1. 左栏「任务配置」:上传 .txt 或点「📚 剧本库导入」选现成剧本,或直接粘贴「剧本文本」(提示:「强烈建议一集一集放入剧本,拆解效果更佳」);
2. 填「任务名称」、选「剧本类型」(国内短剧/海外短剧)、「人物脸型风格」(亚洲中国/非亚洲)、缩略图墙选「视觉风格」(真人短剧/3D 动画/2D 插画三组共 19 种)、「成片时长(分钟)」范围与「特殊要求」;
3. 点「立即合并放入后台拆分」→ toast「拆解完成:X 场 Y 镜,消耗 Z 积分」(异步路径为「已提交后台 AI 拆解」,完成后实时通知);
4. 「智能资产提取」卡勾选「人物/场景/道具」范围点「开始提取」→「已提取 N 个资产图,消耗 N×单价 积分」;
5. 右栏故事板:逐镜「📝 编辑提示词并生成」(10 积分/张)或用「流程控制」的「一键全自动串联生成」;「🔍 预览2K」可看 15 积分/次的高清预览;
6. 「执行记录」中任务卡显示状态(完成/失败/处理中)与「N 镜头」,支持打开/复制/重命名/删除。

规则与注意(计费详见附录 A):

• AI 拆解按 token 计费:每积分 ≈ 1000 tokens(「文本拆解按 token 计费」提示行实时显示当前模型与换算);「🤖 AI 重新拆解」固定 20 积分(弹层确认「将清空现有分镜与资产并重新拆解」);
• 分镜图 10 积分/张、2K 预览 15 积分、资产提取按张数×10;
• 「图片规则说明」:自定义图需去独立生成工具页生成再上传;独立生成结果仅保存 72 小时;
• 「💰 项目积分」弹层可查本项目全部消耗明细;积分不足统一 toast「积分不足」。

2.2 剧本视频生成(/video)

入口:顶栏「工作台」→「🎬 剧本视频生成」;首页入口卡 02。

做什么:接续拆解产物,逐镜生成视频、串行打标、审片、配音,一键打包交付(图片包/视频包/剪映包)。

操作步骤:

1. 顶部「选择任务」选拆解任务(选项格式「任务名(N镜)」);
2. 逐镜填「视频提示词」(可粘贴「参考图槽位」的 @图片N 引用)、「时长(秒) 1~15」「构图」(9:16/16:9/1:1)「分辨率」(1080p/720p),点生成;
3. 批量动作:「🏷️ 一键串行打标签」(确认「消耗 N×10 积分」)、「⚡ 一键全自动串行渲染全案视频」(确认「估算消耗 X 积分(拉取5 + 每秒5×时长)」)、「🕵️ 智能审片」(确认「消耗 10 积分」→ 报告含综合分与五维:主体一致性/画面美感/动作连贯/字幕与口型/穿帮检测);
4. 「🎙 配音」:选音色(旁白解说/女声/男声/童声)生成旁白(免费);
5. 交付:「📥 一键下载图片+提示词」「📦 打包下载已完成视频」「✂️ 剪映导入包」(解压到剪映草稿目录即可打开)、「进入导出」→ 导出成片页。

规则与注意:

• 视频计费 = 拉取 5 + 每秒 5×时长(「计费说明」行实时显示当前单价);打标 10/镜;审片 10/次;配音免费;
• 「取消生成」提示「供应商已产生费用,取消不退积分」;
• 左栏可上传音频素材(「音频将自动进入剪映导入包与成片混音流程」);
• 生成完成/失败有实时 toast 推送,失败自动退积分。

2.3 导出成片(/export/:taskId)

入口:视频页工具条「进入导出」;路由 /export/:taskId(无顶栏入口)。

做什么:对已渲染分镜发起成片导出编排,显示进度与段数。

操作步骤:进入页面自动执行——已有导出则显示进度,否则自动新建并 toast「已开始导出,共 N 段」;2 秒轮询至终态 toast「导出完成」/「导出失败」。

规则与注意:每段消耗 2 积分;本页无 ZIP 下载按钮——产物下载在视频页的三个打包按钮;失败且积分不足显示「积分不足,无法导出」。

第3章 创作工具

3.1 独立生成工具(/independent-tools)

入口:顶栏「创作工具」→「🖼 独立生成工具」。

做什么:不依赖剧本项目,独立生成图片/视频素材,或一键生成解说成片。

操作步骤:

1. 「图片生成」:填提示词、选比例(9:16/16:9/1:1)、可加最多 9 张参考图,点「生成图片(10 积分)」;
2. 「视频生成」:填提示词选比例,点「生成视频(50 积分)」;
3. 「🎬 一键成片」:填标题与解说剧本(≥50 字),点「开始生成」→「成片完成:N 个解说段落」;
4. 「生成记录」中可下载原图/重用提示词/删除(删除确认「取消已开跑任务不退积分」)。

规则与注意:顶部规则「结果仅保存 72 小时,请及时下载;参考图最多 9 张」;一键成片 30 积分;视频时长滑杆仅展示不参与计费(扁价 50)。

3.2 本入剧出(/oneclick)

入口:顶栏「创作工具」→「📖 本入剧出」。

做什么:粘贴小说或剧本,自动识别分集、生成分镜并逐集渲染成片。

操作步骤:

1. 「＋ 新建转剧项目」:填项目名称、粘贴文本(支持「第X集」划分,无集名按段落切分)→「已识别 N 集」;
2. 项目卡上「🚀 一键转剧」→ 确认「将自动生成分镜并逐镜渲染视频(每集 30 积分)」→ 逐集进度,结束「转剧完成」(单集失败自动退款继续其余)。

规则与注意:每集 30 积分扁价;删除项目会「分集与成片素材一并删除」。

3.3 工作台工具集(/workbench)

入口:顶栏「创作工具」→「🛠 工作台工具集」。

做什么:成片后处理三件套——转绘/去字幕/转高清。

操作步骤:

1. 选工具卡:🎨「一键转绘」(20 积分/次,填风格描述如「赛博朋克霓虹风」)、🧽「去字幕」(10 积分/次)、💎「转高清」(15 积分/次,选目标 2K/4K);
2. 「上传视频(mp4/webm/mov)」或「引用已有成片」下拉选择;
3. 点「开始{工具名}(N 积分)」→ 完成 toast「{工具名}完成」。

规则与注意:「生成失败自动全额退回积分,可放心提交」;转绘未填描述确认「将使用默认「电影级写实质感」」。

3.4 导演工作台(/director3d)

入口:顶栏「工作台」→「🎯 导演工作台」(或顶栏工作台版本切换)。

做什么:项目制三级工作台——剧本自动分集 → 资产提取 → 9 字段导演指令分镜 → 逐镜出图出片 → 导出交付包。

操作步骤:

1. L1 项目列表:「＋ 新建项目」(名称/脸型/视觉风格/剧本文本)→「项目已创建,识别出 N 集」;支持「📥 导入项目」(.zip)与「导出 ZIP」;
2. L2 项目详情(八 tab):「🎞 片段管理」进分集工作台;「👤 角色 / 📍 场景 / 🎒 物品」资产三 tab 可「加入待生成队列」(不扣费)再「⚡ 批量生成」(按张×10,失败部分自动退款)或「📦 公共池导入」;「🖼 融合生图」选角色/场景/物品+画面描述生成一致性图(3 积分);「✨ 图片改创」以已有图为底图改创(10 积分);「🎬 参考视频」「🎵 参考音频」上传素材;项目头可「🏢 共享到企业」「🕵️ 智能审片(10 积分)」;
3. L3 分集工作台:勾选范围「🎭 提取资产」;「🎬 生成分镜」(确认「按场次生成 3~6 镜/场」);每镜卡内编辑「导演指令(9 字段)」(格式「每行一条 键:值」)、「图片提示词」「视频参数」「视频提示词」,逐镜「🖼 生成图片」「🎥 生成视频」。

规则与注意:分镜/资产图按图片单价(默认 10);融合 3 积分;「待生成资产不会消耗积分,生成时才扣」。

第4章 内容生态

4.1 剧本库(/library)

入口:顶栏「内容生态」→「📚 剧本库」。

做什么:官方剧本市集——多维筛选找剧本,看详情(项目亮点/前三集试读/人物小传/世界观/故事目录),一键导入拆解台开拍。

操作步骤:

1. 筛选:题材 chip(带 🔥 近 7 天热度)、「全部市场/受众/形式」下拉、搜索框(防抖)、排序(近期火爆/评分最高/最新上架);
2. 点卡片开详情弹层,按锚点浏览各区块;点「📥 导入到拆解台使用」→ 自动跳拆解台并载入剧本。

规则与注意:浏览与导入免费(导入记录使用热度);完整剧本在导入后才载入拆解台。

4.2 投稿中心(/studio)

入口:顶栏「内容生态」→「📮 投稿中心」。

做什么:提交原创剧本投稿(过审上架剧本库),维护编剧档案。

操作步骤:

1. 「＋ 新建剧本投稿」:填「标题*」「分类」「目标市场」「制作形式(短剧/网剧)」「目标受众」「简介」「剧本内容*」;
2. 「存草稿」或「提交审核」→「已提交审核,审核结果将在通知中告知」;
3. 状态流转:草稿→待审核→已发布/需修改/已驳回;「需修改」可「查看意见」后「重新编辑提交」;
4. 「编剧档案」:填笔名*/擅长题材/简介/代表作创建资料,资料展示在编剧广场。

规则与注意:投稿免费;过审后上架剧本库(§4.1)供全网使用;审核动作在管理后台「投稿审核」tab(§7.12)。

4.3 编剧广场(/writers)

入口:顶栏「内容生态」→「✍️ 编剧广场」。

做什么:发现编剧——按题材/排序浏览,看主页(入驻时间/在库剧本/代表作)。

操作步骤:搜索(回车)或点题材 chip;点卡片「查看主页」;主页内点在库剧本跳剧本库详情。

规则与注意:展示数据来源即投稿中心的「编剧档案」。

4.4 作品展示(/showcase)

入口:顶栏「创作工具」→「🎬 作品展示」。

做什么:平台成片作品墙——发布已完成成片让全平台看见。

操作步骤:「📤 发布作品」→ 选成片(仅已完成)+ 填「作品名称」→「发布到作品墙」;自己的卡片可「撤下」。

规则与注意:「发布不消耗积分」;发布后全平台可见。

4.5 火花计划(/spark)

入口:顶栏「内容生态」→「🔥 火花计划」。

做什么:创作者激励计划——加入即奖积分,投稿过审按阶梯持续奖励。

操作步骤:

1. 点「🔥 立即加入(赠 100 积分)」→ toast「已加入火花计划,100 积分已到账」,数据卡开始实时展示投稿量/过审率/累计激励;
2. 按本期赛事卡指引「立即投稿」(经投稿中心提交,过审自动进入评选);
3. 阶梯:🪵 星火(过审 1-2 部,100 积分/部)→ 🔥 炬火(3-5 部,150 积分/部+首页推荐位)→ 🏆 燎原(6+ 部,200 积分/部+专属流量扶持+实物周边)。

规则与注意:重复加入提示「您已加入火花计划」;「怎么玩」三步:写剧本并投稿→过审即发布→按阶梯拿激励;FAQ 见页面底部四条。

4.6 爆款分析(/viral-analysis)

入口:顶栏「创作工具」→「📈 爆款分析」。

做什么:粘贴爆款链接或文案,AI 从四维打分并给改写钩子。

操作步骤:填「任务名(可选)」与「链接或文案」→「开始分析(5 积分)」→ 结果卡显示环形总分(60-94)+ 四维条(钩子强度/情绪共鸣/节奏密度/转化引导)+ 改写钩子(可复制);历史记录可回看。

规则与注意:每次 5 积分;空内容提示「请输入待分析内容」。

4.7 剧本评估中心(/evaluation)

入口:顶栏「内容生态」→「🔬 剧本评估中心」。

做什么:七维评分体系的剧本评估,快速(100 积分)/深度(300 积分)两档,产出结构化评估报告。

操作步骤:

1. 「新建评估」:填项目名(选填)、选「评估方式」卡片(⚡ 快速—评分/结论/最多 3 项风险;🔬 深度—完整报告含逐集证据与海外适配)、可选填题材/市场/形式三下拉;
2. 粘贴剧本文本(≥100 字,建议含人物小传/大纲/分集正文)或上传 .txt/.md/.docx(≤10MB);
3. 点「开始评估」→ toast「已提交,冻结 N 积分,完成后结算(失败自动退回)」;
4. 流水线三阶段八角色实时推进(交付规范审计→全剧主审/前 10 集精读→证据复核/首席评分),3 秒轮询;
5. 完成后查看报告:总分/等级/七维评分(交付规范 10+内容基础 20+前 10 集转化 20+人物情绪 15+结构兑现 15+海外适配 10+AI 漫剧可视化 10)/故事亮点/逐集证据/重点风险/推进建议,可「📥 下载报告」(.txt)。

规则与注意:提交冻结、完成结算、失败全额退回(「评估失败,冻结积分已自动退回」);字数不足提示「剧本内容至少 100 字」。

第5章 积分与账户

5.1 个人积分流水(/credits)

入口:账号中心「积分明细页」;顶栏「积分记录」为弹层版。

做什么:查看积分充值/消费/余额明细。

操作步骤:四格汇总(可用积分/累计增加/累计消费/当前余额)+ 流水表(时间/类型「增加|扣费」/事项/积分「+N|-N」/余额);「上一页/下一页」翻页(每页 20 条)。

规则与注意:「累计增加/累计消费/当前余额」三格基于当前页聚合,非全量统计。

5.2 充值(/recharge)

入口:顶栏「充值」;账号中心「充值」。

做什么:扫码转账充值积分,上传凭证待审核到账。

操作步骤:

1. 左栏看「充值金额(元)」输入(≥1),页面实时预览「按当前汇率 1 元 = N 积分,预计获得 N 积分」;
2. 按收款码转账(备注订单号)→「创建充值订单」→ toast「充值订单 xxx 已创建(N 积分),请转账后上传支付凭证」;
3. 「我的订单」中对该单「上传凭证」(图片)→ 状态「待审核」;
4. 管理员审核通过 → 状态「已到账」+ 实时 toast「💰 充值已到账」。

规则与注意:

• 汇率默认 1 元 = 10 积分(后台可调);无收款码时提示线下联系管理员;
• 「单笔充值满 980 元自动开通推广资格」(可在后台调整);
• 到账同时自动结算两级返佣(§6.2)。

5.3 账号中心(/account)

入口:顶栏积分胶囊点击。

做什么:个人资料/登录设置/积分/通知集中管理。

操作步骤:

• 修改密码:填原密码+新密码(≥8 位)+确认 →「密码已修改」;
• 修改登录邮箱:填新邮箱+当前密码 → 成功后强制登出跳登录页;
• 查看邀请码/注册时间/推广资格 tag/通知(最近 4 条)。

规则与注意:改密成功后端撤销全部登录状态(refreshToken 全失效),其他已登录设备需重登;手机号绑定暂未接入。

第6章 企业与分销(企业成员可见)

6.1 企业管理(/organization)

入口:顶栏「企业管理」(有 org_id 时显示;未加入企业时此页提供「提交入驻申请」与「使用邀请码加入」两个入口)。

做什么:企业组织管理——数据看板/成员角色/分组权限/素材权限/企业素材库/共享项目/积分流水。

操作步骤(已加入企业,7 个 tab 全员可见,管理动作按角色收敛):

1. 📊 数据看板:积分余额(可用/冻结)/累计充值/累计消耗/近 14 天趋势与项目、人员消耗榜;
2. 👥 成员与角色:所有者可「生成邀请码」邀新(对方邮箱→邀请码→对方在「使用邀请码加入」处兑换)、调整角色(成员/管理员)、移除;
3. 🧩 成员组·权限组:所有者创建成员组(指定组长)与权限组(查看/上传/下载/编辑/删除组合);
4. 🔐 素材权限:五项独立权限勾选(「授予下载/编辑/删除会自动授予查看;授予删除自动含编辑;取消查看会取消其余全部权限」);
5. 🗄 企业素材库:目录树/类型筛选/文件夹管理;素材来自成员在拆解台「资产库」的企业共享;
6. 🎬 共享项目:导演工作台开了「共享到企业」的项目在此汇集,可跳转查看;
7. 💰 积分流水:组织维度台账。

规则与注意:角色三层——所有者(全部管理)/管理员(素材权限+看板+共享项目)/成员(按权限组访问)。

6.2 推广与收益(/distribution)

入口:顶栏「推广与收益」(企业成员可见;推广资格满 980 元充值自动开通)。

做什么:分销推广——分享推广码拿两级返佣,收益可提现或 1:1 兑换生产积分。

操作步骤:

1. 概览卡复制「我的推广码」分享;好友注册时填入即绑定为下线;
2. 下线充值即按比例返佣(到账自动结算):一级 8% / 二级 2%(后台可调);
3. 「提现」tab:收益满 100 积分申请提现 → 状态机 待审核→审核中→待打款→已打款(平台打款后)→ 你点「确认到账」→已完成;待审核/审核中可「撤回」;
4. 「兑换」tab:收益 1:1 兑换生产积分(最少 10)。

规则与注意:提现最低 100 积分(「最低提现 N 积分」);可提额度=累计佣金−全部提现申请(已驳回/撤回不释放额度);兑换与提现额度相互独立。

第7章 管理后台(/admin,管理员)

入口:顶栏「管理后台」(仅 admin);非管理员访问被顶回首页。左侧 tab 栏共 14 个 tab,30s 自动刷新概览。

做什么:平台运营全功能——用户/积分/内容/审核/计费/模型/提示词。

各 tab 速览:

规则与注意:

• 「模型配置」是全站 AI 能力开关:接入真实供应商后自动切换,失败自动回退 Mock;配置零环境变量;
• 「计费配置」改动全站即时生效(对照附录 A 各「可调」项);
• 充值「通过」即触发到账+两级返佣联动,不可逆。

附录 A 计费速查表

单价经源码核对(backend/internal/domain/credits/billing.go 及各域);标「可调」者经管理后台「计费配置」或 settings 即时生效。

附录 B 常见问题

• 登录掉线/全员掉线:JWT 密钥文件(data/.jwt_secret)丢失或更换所致——迁移必须随 data/ 整目录带走(见 DEPLOY.md §5.1);
• 页面白屏:先查前端 dist 是否构建成功(:3300 托管的就是 dist/),再清浏览器缓存;
• 生成一直排队:未配置模型接入时全站走内置 Mock(秒级同步完成);若配置了真实供应商,排队属正常,完成/失败均有实时 toast;
• 生成失败积分去哪了:自动原路退回(台账可见「+N」退回行),工作台工具/评估/转剧等失败面全覆盖;
• 独立生成的图片不见了:独立生成结果仅保存 72 小时,请及时下载;
• 改密后被登出:改密撤销全部登录状态(安全设计),用新密码重登即可;
• 充值为 0 积分:订单需管理员审核到账,状态在「我的订单」可见;到账后有实时通知;
• 提现被驳回:看提现记录「备注」列的管理员原因;驳回/撤回的额度立即解锁可重新申请。

2.2 - 人工测试清单(QMTV QA 走查底稿)

自动化升格映射(场景 → E2E/人工三向归类)见 docs/test/e2e-qmtv-场景清单.md;操作说明见 QMTV使用说明书_中文.md。

用法:按 T0→T7 顺序执行,每步 ☐ 打勾,实际:____ 填真实观察值/截图编号。失败即记 bug 编号。 测试数据:seed 三账号 admin@qmtv.com / admin123456(管理员,10 万积分)、demo@qmtv.com / demo123456(1335 积分,seed 含欢迎通知+admin→demo 分销关系)、producer@xingmang.cn / demo123456(制片视角);计费走内置 Mock(未配置 model_endpoints 时全站同步 Mock,生成图/视频为占位素材)。 前置:环境已起——生产形态 bash scripts/dev-up.sh(:3300)或 e2e 形态 bash scripts/dev/e2e/e2e-up.sh(:3301,独立库,推荐——每次 up 全量重建,水位确定);登录 admin。 图例:🟢E2E-XX-NN=该用例主链路已被 Playwright 断言用例覆盖(frontend/e2e/assertion/);🟡待实现·E2E-XX-NN=场景已登记场景清单、用例待写;无标=纯人工。 ⚠️ E2E 只断 API 链路与关键业务结果(toast 存在/台账行/状态翻转):页面交互流、视觉布局、文案细节、跨页联动仍需按下表人工执行。

测试旅程总览

flowchart LR
  A[T0 种子与环境] --> B[T1 创作主链闭环]
  B --> C[T2 创作工具]
  A --> D[T3 内容生态]
  B --> E[T4 积分与充值]
  D --> F[T5 企业与分销]
  A --> G[T6 管理后台]
  A --> H[T7 权限与边界]

T0 · 种子与环境确认

目的:确认环境就绪、种子账号/数据在位、计费走 Mock 同步面。对照 e2e-verify 六项自检。

T1 · 创作主链闭环(拆解 → 出图 → 成片 → 导出)

核心旅程:一笔剧本从拆解到导出全通,扣费流水逐笔可对。建议用 demo 账号(低水位,扣费可见)。

T2 · 创作工具

T3 · 内容生态

T4 · 积分与充值闭环

T5 · 企业与分销

T6 · 管理后台(14 tab 人工走查)

🟢E2E-ADM-01 已覆盖概览/用户/任务审计/剧本四 tab 的只读巡检;本层走查写动作与其余 tab。

T7 · 权限与边界

对账与回归锁说明

• 🟢 九场景:AUTH-01/DASH-01/GEN-01/GEN-02/CRD-01/ADM-01/NAV-01/SPK-01/SNAP-01——与本清单条目一一对应( grep 🟢 对账);断言面详见 docs/test/e2e-qmtv-场景清单.md。
• 🟡 五场景(SUB-01/RCH-01/EXP-01/WD-01/DIR-01):写链自动化待升格——本清单 T3.6/T4.7/T1.13/T5.11/T2.17 的人工步骤即其未来断言主干。
• 计费数字以 使用说明书 附录 A 为准(源码核对口径);测试中发现的流水金额不符直接记 bug(标注条目号)。
• e2e 环境纪律(隔离/造数/禁 retry)见 docs/test/e2e-测试约定.md。
• FSD 分册对账(三十一期回填)——人工条目↔功能规格区间映射(规格原文 prd/fsd-qmtv/00-总则,13 册全量):T0→总则横切(T0.2→m01/T0.3→m12)|T1→m02 F2.01F2.13(T1.13→F4.01 导出编排/T1.14→总则 §2.3)|T2→m03 F3.01F3.09(T2.72.9→m11 F11.01F11.02/T2.102.11 一键转剧→F10.15/T2.122.17→m10)|T3→m09 F9.01F9.08(T3.113.12→m13 F13.01/T3.133.15→m11 F11.06F11.08)|T4→m08 F8.01F8.03(T4.94.10→m01)|T5→m06 F6.01F6.14(T5.75.11→m07 F7.01F7.06)|T6→m12 F12.01F12.13|T7→m01 F1.01~F1.09(T7.5 边界→m06/T7.12→m05 F5.01)。纯前端/视觉条(T0.6/T0.8/T7.11 等)无 F-ID 可挂。

2.3 - QMTV 使用手册 · 文档索引

本目录面向最终用户与 QA;与开发面文档(DEPLOY.md/测试规划)互补。发布视图见 my-docs Hugo 站「QMTV 文档」分区。

截图重跑

bash scripts/dev/e2e/e2e-up.sh          # 起 e2e 环境(:3301/qmtv_e2e,强制重建 frontend/dist)
cd frontend && npm run test:snapshots   # 24 图全量刷新 → docs/manual/images/
bash scripts/dev/e2e/e2e-down.sh        # 停环境

截图纪律:纯只读遍历+截图(dashboard 仅填表单文本不提交,零造数);信号驱动 settle(innerText>80)。

构建发布

改本目录任何 .md 后:python3 docs/sync_docs.py --build——同步进 Hugo 站(qmtv/manual/ 分区)并过静态链接死链对拍;手册图片随 ASSET_RULES 一并复制。

关联文档

• e2e 场景清单——自动化覆盖地图(🟢🟡 对账权威)
• e2e 测试约定——初始世界/隔离/明令禁止/负样本纪律
• DEPLOY.md——环境启动与部署(运行口径权威)

3 - 测试

• 测试规划——测试分层与环境约定
• e2e 测试约定——初始世界/隔离/纪律
• e2e 场景清单——自动化覆盖地图

3.1 - QMTV 测试规划（Go 版，P0 底册）

回答移植需求②"基于现有项目先写单元测试——移植现有测试（如果有），或另写"。现状实测：冻结版零单测，仅 4 个 API 冒烟脚本（verify_*.js）覆盖 60/239 端点。结论：以 TDD 另写为主（pms 范式），verify 断言移植为集成冒烟底册，e2e 骨架按 pms 约定立。

1. 分层测试范式（对齐 pms backend）

2. 分域单测规划（先红后绿，TDD 顺序=P 期次）

3. verify_*.js 断言移植矩阵（约 60 端点 → Go 集成冒烟）

现有脚本逐断言移植为 Go 集成测试（integration 标签，dev-up 环境执行；脚本本身保留在冻结区不动）。「可测期次」= 该端点 Go 实现落地期。端点数为约数（唯一路径口径）：分项 ~28+~20+~6+~9 含同端点多场景重复计数，去重后约 60。

4. E2E 约定骨架（正式版 P5，按 pms docs/test 三文档体系）

• 初始世界：独立库 qmtv_e2e（dev-up 变体建库导 full+seed）；账号矩阵=seed 三账号+按需 API 注册；业务单据不进种子，一律 API 造数（防绕过状态机）。
• 外部 API 零真实调用（用户指令 2026-10-17，instructions.txt）：e2e/集成测试局限在本系统内，外部 API 调用会引起费用——全部 mock。LLM/图像/视频供应商一律走 Mock 通道（测试环境不配 model_endpoints 的 api_key，或显式 provider_routing=mock）；网络出口断言（providers 适配层的真实 HTTP 调用）用 httptest 本地假服务器验证协议形状，绝不打真实供应商；CI 环境保持零 Key（llm.isAvailable()==false 全站 Mock 路径），真实供应商连通性只允许人工在管理后台用「测试连接」单次验证。
• 确定性：时间用相对量；金额固定值；禁按自增 id 断言（qmtv 全字符串 ID 天然满足）。
• 隔离：e2e-reset（DROP/CREATE+导入）/e2e-seed（快恢复）；失败不自愈必须 reset；连跑两轮间隔 reset。
• 明令禁止：禁 sleep 等事件链（一律 pollUntil，超时 20s——评估 stage 推进/视频轮询场景）；禁 retry；5xx 直接抛响应体。
• 场景登记：docs/test/e2e-qmtv-场景清单.md 行格式对齐 pms（场景ID E2E-XXX-NN｜FSD 功能 ID｜主干路径｜关键断言｜现状）；缺陷修复覆盖优先并入现有场景加断言。
• Playwright 引入与否：P5 决策——前端冻结的前提下，API-first 断言册已覆盖回归需求；截图册（操作手册配图）可单独用 Playwright 走真 UI，不与断言册共用一行代码。（二十六期已落地：前端演进后 Playwright 双配置入位——断言册 11 用例〔auth 4/dashboard/generation 2/credits/admin/nav/spark；含 setup 册 14〕 + 截图管线，约定见 docs/test/e2e-测试约定.md；本条 P5「前端冻结」前提已随 TS 演进裁决失效，双配置即终态。二十七期勘误：二十五/二十六期宣称「13 用例」系计数漂移，11 为亲数权威口径。）

5. CI 闸门（scripts/ci.sh，已落地）

JUnit 双断言（场景总数≠期望也阻断）随 P5 e2e 落地引入。

3.2 - QMTV E2E 测试约定

二十六期（2026-10-19）立册。对齐 pms e2e 约定骨架，按 QMTV 单库场景裁剪。 场景覆盖地图见 e2e-qmtv-场景清单.md。

§1 初始世界

• 环境：bash scripts/dev/e2e/e2e-up.sh 一键起——独立库 qmtv_e2e（DROP/CREATE 即全量 reset）+ 端口 :3301（与 dev :3300 三隔离：库/端口/产物文件名，可共存）+ 托管 frontend/dist（每次 up 强制重建，永测当前 src）。停环境 e2e-down.sh；快恢复（不重建库）e2e-seed.sh。
• 种子自检：e2e-verify.sh 六项（healthz / admin·demo·producer 三账号登录 / models-active / style-presets）——绿才能跑用例。
• 账号矩阵：admin@qmtv.com（管理员，credits 100000）/ demo@qmtv.com / producer@xingmang.cn——密码=seed 公开演示值，不入新密。API 造数的辅助账号一律 e2e- 前缀 email；storageState 册（.auth/{admin,demo}.json）由 setup 项目真实 UI 登录一次产出，用例零登录（对抗 login 20/min 限流）。
• 确定性规则：未配置 model_endpoints → 生成类全走内置 Mock 同步 done（无轮询等待、无外部超时）；Mock 图像/视频字节含随机源——只断结构确定（卡片存在/URL 可达/台账行），绝不断素材内容。
• 预置种子：SQL seed（admin/demo+分销配置+计费 KV）+ Go seed（producer+示例任务链）。业务单据不进种子，一律 API 造数。
• 隔离与清理：用例各自造数各自收尾（集成侧 integCleanup 同纪律）；失败不自愈——重跑前 e2e-up；连跑两轮必须间隔 reset（credits 水位会漂移）。

明令禁止

1. 禁 sleep 等待 UI 条件——唯一合法等待面是 Playwright 自动等待/expect.poll/waitForEvent/pollUntil。豁免两处（登记）：①巡检类用例的路由间静置窗口（nav/admin 的 waitForTimeout(400/1500)、snapshots 截图前 waitForTimeout(800)——错误收集窗/渲染落定窗，非断言等待）；②截图前 networkidle。
2. 禁 retry——config retries: 0（pms flaky 规则：禁 retry 掩盖；修复优先序 改等待>改定位>改断言>最后才是 retry）。
3. 禁断全局计数/绝对余额——流水断言用 total 相对面 + 最新行身份；余额用 assertBal 恒等式（后端集成侧）。
4. 禁触 qmtv_main / pms_ / sw_main*——e2e 只操作 qmtv_e2e 单库（远程 139 共享实例纪律平移）。
5. SSE 面禁 networkidle——EventSource 长连接使 networkidle 永不触发；巡检用 load+双 rAF+静置窗口。

§2 可测性硬规则

• 断业务结果，不断文案细节：toast 只断关键短语（「拆解完成」「去字幕完成」）；选择器优先 role/placeholder/既有稳定 class，不批量加 testid（触碰面爆炸）；高频锚点按需单点补并在此登记。
• 失败留证：trace retain-on-failure + screenshot only-on-failure → e2e/.artifacts/（gitignore）。
• 断言/截图分文件一行不共用（pms 硬规则）：断言册 playwright.e2e.config.ts（testDir e2e，smoke 项目收 assertion/*.spec.ts）；截图册 playwright.config.ts（只收 snapshots.spec.ts）。
• API 侧错误信封直接抛（e2e/lib/client.ts apiReq）：非 2xx 抛响应体——静默吞错=测试说谎。
• 对话框断言用 waitForEvent('dialog')（once+变体捕获有竞态——auth.spec 负样本抓获）；LoginView 错误走原生 alert，业务 confirm 各页分散（WorkbenchView 仅 repaint 空描述分支）——用例写前先读该页 submit 源码，勿凭笔记推 dialogs。

§3 运行手册

bash scripts/dev/e2e/e2e-up.sh          # 起环境+种子自检（首次/失败后/连跑第二轮前必跑）
cd frontend
npm run test:e2e                        # 断言册（smoke，:3301）
npm run test:e2e:headed                 # 有头观察
npm run test:snapshots                  # 截图管线（二十七期手册出图）
npx playwright show-trace <trace.zip>   # 失败取证
bash scripts/dev/e2e/e2e-down.sh        # 停环境
bash scripts/ci.sh --e2e                # 全栈验收档（=--with-env 全部 + e2e 册）

§4 flaky 处理规则

• 72h 内同一用例红 ≥2 次 → 摘出开单，不得带红合入；
• 7 天未修 → 删用例（场景清单「自动化?」列同步回落「待实现」）；
• 关键用例落地必配负样本演练（涉及金额/回归锁/A1 教训面——改断言键名/路径必红才转正；A1 fixture 死键教训：键名错→锚死力失效）。巡检类（nav/admin 只读遍历）可豁免——harness 判死力由其它用例的有机红佐证（二十六期如实报告：admin.spec 无单独负样本，nav/auth/credits/dashboard/generation 五处有机红已证）。

§5 场景登记与回归锁

• 场景 ID 唯一（E2E-<模块>-<序号>），ID 标注于 spec 文件头注释（用例名可不带前缀）——清单与 spec 双侧 grep 对账按场景 ID 级（「自动化?=是」的行必须有对应 ID 的 spec 文件，清单「现状」列登记 ✅ 文件名）。〔二十七期勘误：原「用例同名对账」与实际不符——ID 在头注释非用例名，对账实为场景 ID 级 9=9+文件级 ✅ 列。〕
• 缺陷修复优先「并入现有场景加断言」（回归锁），不新开用例——本仓 /review-plan A 类「验收锚点」判死力机制直接挂此。
• 写链场景（导出 ZIP、充值审核、分销提现等）先登清单「待实现」行，后续期次升格。

3.3 - QMTV E2E 场景清单（覆盖地图）

行格式：场景 ID 唯一；「自动化?=是」行与 frontend/e2e/assertion/*.spec.ts 按场景 ID 级对账（清单 ID ↔ spec 文件头注释 ID+「现状」列 ✅ 文件名，与测试约定 §5 同口径；二十七期勘误：原「用例同名」与实情不符——用例 ID 在文件头注释非用例名）。 「FSD 功能 ID」列=场景↔功能规格双向对账锚（三十一期回填）——指向 prd/fsd-qmtv/ 各册 F<m>.<nn> 节；横切场景（积分/导航/截图）无单册归属标「横切」。 二十六期首批冒烟 8 场景全走 Mock 同步面（避开 SSE 依赖与长轮询）；写链场景登「待实现」后续升格。

4 - 功能规格（FSD）

从 00-总则 进入（横切约定与分册地图）；99-附录 是与六册的漂移差异台账；m01~m13 按模块分册（认证/任务/生成/导出/通知/组织/分销/充值/剧本库/导演/评估/管理后台/火花）。

4.1 - FSD M1 · 认证与用户

← 总则 ｜ 附录 → ｜ 上游：PRD §4 M1 实现落点：backend/internal/domain/auth/（service.go/model.go/repo.go）+ cmd/server/auth_handlers.go（handlers）+ cmd/server/routes.go:34-51（挂载）。事实基准=Go 代码；冻结版 qmtv/server/index.js:73-230 仅差异对拍参照。

M1 认证与用户

9 端点全量（基础信封见总则 §2.2：成功 {"ok":true,"data":…} / 失败 <码> {"error":"文案"}）。本域零扣费、零 SSE、零素材上传；台账/通知为写入副作用（register/改邮箱两处）。

F1.01 注册

对应 PRD：§4 M1 · POST /api/auth/register（限流 5/h）｜ 状态：实现 ｜ 实现落点：auth/service.go:68-140、auth_handlers.go:173-188 ｜ UI：/register（RegisterView）｜ 场景挂钩：无（e2e 未覆盖注册链，人工清单 T0 具名账号由 seed 产出）

1 功能定义

创建用户账号并签发首个会话（access + refresh 双令牌）：初始积分发放、邀请码建分销关系、欢迎通知三件副作用一次完成。

2 触发条件与前置状态

• 未登录访问 /register 提交表单 → POST /api/auth/register（公开面，WindowRateLimit("register", 5, time.Hour)——同 IP 每小时 5 次，超出 429）。
• 前置：邮箱未被注册；降级模式（无 DSN）下 503「数据库未配置」。

3 输入与校验

4 处理流程

flowchart TD
  A["POST /auth/register"] --> B["四关校验"]
  B --> C["invite_code 查询邀人<br/>（不命中静默）"]
  C --> D["建 users 行<br/>role=user / status=active / workspace_version=classic<br/>referral_code=QM+6位base36大写（crypto/rand）"]
  D --> E{"有邀人?"}
  E -->|是| F["INSERT referral_relations"]
  E -->|否| G["跳过"]
  F --> G
  G --> H["台账 amount=0 / balance_after=初始积分<br/>type=register 描述「注册赠送 200 积分（初始）」"]
  H --> I["欢迎通知（积分数字跟随 trial 实际值）"]
  I --> J{"有邀人?"}
  J -->|是| K["邀人台账 +50 type=referral"]
  J -->|否| L["跳过"]
  K --> L
  L --> M["issueSession → 200 {ok,data:{token,refreshToken,user}}"]

5 输出与结果状态

• 200 {"ok":true,"data":{"token","refreshToken","user":PublicUser}}（AuthSession 统一会话体，model.go:78-82）。
• user 投影字段集（冻结 publicUser 逐字节，model.go:33-44）：id/email/nickname/role/credits/org_id/workspace_version/referral_code/affiliate_enabled/created_at；org_id 空串与 referral_code NULL 均→JSON null。

6 状态流转

无状态机。用户初始 status='active'；workspace_version='classic'（后续 F1.09 可改）。

7 边界与异常

8 权限与数据规则

• 权限：公开面（限流替代鉴权）；写入 users/referral_relations/credit_records/notifications 四表。
• 数据规则：users.email UNIQUE；referral_code UNIQUE（碰撞时 INSERT 报错与冻结一致，crypto/rand 36^6 空间）；invited_by 哨兵空串（冻结写 null，DDL NOT NULL 差异已登记）；credits 初始 = trial_credits settings 值（F6 Billing.TrialCredits——冻结硬编码 200 属刻意差异）。

F1.02 登录

对应 PRD：§4 M1 · POST /api/auth/login（限流 20/min）｜ 状态：实现 ｜ 实现落点：auth/service.go:143-156、auth_handlers.go:195-208 ｜ UI：/login（LoginView——错密码 alert「邮箱或密码错误」，登录成功跳 /）｜ 场景挂钩：E2E-AUTH-01（断言册 auth.spec.ts）

1 功能定义

邮箱+密码换取会话双令牌；不存在与密码错合并同一 401（不暴露账号存在性），停用账号 403。

2 触发条件与前置状态

• 未登录（或会话过期）提交登录表单 → POST /api/auth/login（公开面，限流 20/min）。
• 前置：用户存在且 status='active'。

3 输入与校验

4 处理流程

flowchart TD
  A["POST /auth/login"] --> B["ByEmail 查用户"]
  B -->|不存在| C["401 邮箱或密码错误"]
  B -->|存在| D["VerifyPassword"]
  D -->|不符| C
  D -->|符合| E{"status=active?"}
  E -->|否| F["403 账号已被停用"]
  E -->|是| G["issueSession<br/>access JWT（claims 携 rol）+ rt_ 刷新令牌<br/>原文返回前端 / SHA-256 落库 refresh_tokens"]
  G --> H["200 {ok,data:AuthSession}"]

5 输出与结果状态

同 F1.01（AuthSession）。JWT claims 含 rol（AdminMiddleware 零查库鉴权——角色变更需重登生效，PRD §3 登记）；access TTL 72h。

6 状态流转

无状态机；refresh_tokens 表新增一行（revoked_at NULL / replaced_by 空）。

7 边界与异常

8 权限与数据规则

• 权限：公开面；读 users、写 refresh_tokens。
• 数据规则：refresh token 原文不落库（SHA-256 token_hash + expires_at LocalTime）；每次登录新增一行（不清理旧行，过期行由 ValidByHash 谓词自然失效）。

F1.03 令牌刷新（F1 真轮换）

对应 PRD：§4 M1 · POST /api/auth/refresh ｜ 状态：实现 ｜ 实现落点：auth/service.go:159-179、auth_handlers.go:214-227 ｜ UI：前端 api 层 401 自动触发（frontend/src/api.ts:36-44）｜ 场景挂钩：ci –with-env refresh 轮换断言（新旧 RT 不同/旧复刷 401）

1 功能定义

用 refreshToken 换新会话：旧令牌撤销、新令牌串链（replaced_by）——同一 refreshToken 只能用一次；与冻结版差异（冻结 refresh 恒 401 无新字段），属 PRD F1 刻意差异。

2 触发条件与前置状态

• 前端任何 API 401 → 自动 POST /api/auth/refresh 重试一次；或手动调用于 POST /api/auth/refresh（公开面无限流）。
• 前置：refreshToken 未撤销、未过期、属主 status='active'。

3 输入与校验

4 处理流程

flowchart TD
  A["POST /auth/refresh"] --> B["SHA-256 查 ValidByHash"]
  B -->|无效| C["401 invalid refresh token"]
  B -->|有效| D["查属主 + 停用校验"]
  D -->|停用/不存在| C
  D -->|active| E["issueSession 签新对"]
  E --> F["撤旧行：revoked_at 置位 + replaced_by=新 RT"]
  F --> G["200 {ok,data:AuthSession}"]

5 输出与结果状态

200 {"ok":true,"data":AuthSession}——refreshToken 字段含新令牌（冻结版响应只有 {token,user}，无此字段——前端 W9a 同期消费）。旧令牌自此 401。

6 状态流转

refresh_tokens 行级状态机：active（revoked_at NULL）→ rotated（revoked_at 置位+replaced_by 串链）；无单向状态图面，串链即审计线索。

7 边界与异常

8 权限与数据规则

• 权限：公开面；读 refresh_tokens/users、写 refresh_tokens（撤旧）。
• 数据规则：原文仅存在响应体，库中只存 SHA-256（泄库不可逆推）；replaced_by 构成轮换链。

F1.04 登出

对应 PRD：§4 M1 · POST /api/auth/logout ｜ 状态：实现 ｜ 实现落点：auth/service.go:258-260、auth_handlers.go:240-248 ｜ UI：顶栏退出按钮（LoginView 登出回 /login）｜ 场景挂钩：E2E-AUTH-01（admin 可达 /admin 并登出回 /login）

1 功能定义

撤销当前用户全部 refreshToken（F1 增强；冻结版无服务端动作，PRD v1.2 补登差异）——改密/登出后所有已发刷新令牌一并失效。

2 触发条件与前置状态

• 已登录点击退出 → POST /api/auth/logout（Bearer）。
• 前置：Bearer 有效；降级模式 503。

3 输入与校验

无 body。身份取自 JWT claims user_id。

4 处理流程

POST /auth/logout → RevokeAllForUser(userID)（UPDATE refresh_tokens SET revoked_at=NOW() WHERE user_id=? AND revoked_at IS NULL）→ 200 {"ok":true,"data":true}。

5 输出与结果状态

200 {"ok":true,"data":true}；该用户全部未撤销 refresh_tokens 行 revoked_at 置位。

6 状态流转

同 F1.03 行级状态：active → rotated（批量）。

7 边界与异常

8 权限与数据规则

• 权限：登录态（amw）；只写 refresh_tokens 自己的行（user_id 来自 claims，非入参——不可越权撤他人）。

F1.05 当前用户信息（me）

对应 PRD：§4 M1 · GET /api/auth/me ｜ 状态：实现 ｜ 实现落点：auth/service.go:182-191、auth_handlers.go:229-238 ｜ UI：顶栏积分胶囊/角色菜单数据源｜ 场景挂钩：E2E-AUTH-01（间接：全站登录态面）

1 功能定义

返回当前登录用户公开投影（PublicUser）；已登录态遇停用账号返回 401（P2 期首核查 A1 恢复冻结 util.js:53 全 authed 拦截语义，触发前端登出链路）。

2 触发条件与前置状态

• 前端挂载/刷新/积分变动后拉取 → GET /api/auth/me（Bearer）。
• 另有 query token 兜底形态 GET /api/auth/me?token=（ci 冒烟 C3 裁决面——与 SSE/images 同族，仅此三处）。

3 输入与校验

无参数。身份取自 claims。中间件层已验签（JWTAuth.AuthMiddleware）；service 层仅补停用校验。

4 处理流程

GET /auth/me → ByID(userID) → 停用? →401 : →u.Public() 投影 → 200 {"ok":true,"data":PublicUser}。

5 输出与结果状态

字段集同 F1.01 §5。credits 为当前实时余额（DECIMAL 读侧 float64）。

6 状态流转

无。

7 边界与异常

8 权限与数据规则

• 权限：登录态；只读自己一行（claims 绑定）。

F1.06 积分流水分页

对应 PRD：§4 M1 · GET /api/auth/credit-records ｜ 状态：实现 ｜ 实现落点：auth_handlers.go:309-324（委托 credits.Records）｜ UI：/credits（CreditsView）/ 顶栏积分弹层｜ 场景挂钩：E2E-CRD-01

1 功能定义

当前用户全局积分台账分页读（每页 20，created_at DESC,id DESC）——所有域的扣费/退款/充值/佣金行共用此读面。

2 触发条件与前置状态

• 进入积分流水页/翻页 → GET /api/auth/credit-records?page=N（Bearer）。

3 输入与校验

4 处理流程

GET /auth/credit-records → page 归一 → credits.Records(userID, page) → 200 {"ok":true,"data":{"list":[…],"total":N,"page":N}}。

5 输出与结果状态

• list 行字段：台账行投影（type/desc/amount/balance_after/created_at/task_id 等，credits 域读侧投影）。
• total 全量行数（非当前页）；page 回显归一后值。

6 状态流转

无（纯读）。

7 边界与异常

8 权限与数据规则

• 权限：登录态；WHERE user_id=claims 绑定（看不到他人流水）。
• 数据规则：排序 created_at DESC,id DESC（同秒稳定序）；分页 size 固定 20。

F1.07 修改密码

对应 PRD：§4 M1 · POST /api/auth/change-password ｜ 状态：实现 ｜ 实现落点：auth/service.go:194-217、auth_handlers.go:255-267 ｜ UI：/account（AccountView 安全区）｜ 场景挂钩：无独立 e2e（人工清单 T7 掉线重登路径）

1 功能定义

验原密码后更新密码哈希，并撤销全部 refreshToken（F1：改密后所有已登录会话的刷新能力失效，access 令牌存续至 72h 自然过期）。

2 触发条件与前置状态

• 账号设置页提交改密表单 → POST /api/auth/change-password（Bearer）。
• 前置：status=‘active’（停用 401，A1 拦截——本就查库零成本恢复冻结语义）。

3 输入与校验

校验序：查用户→停用拦→验原密码→验新密码（十六续 A1 修序先例在 M12 admin 域；本域顺序冻结逐字）。

4 处理流程

POST /auth/change-password → 停用?→401 : 验旧密码→验新密码→UpdatePassword（新 bcrypt 哈希）→RevokeAllForUser→200 {"ok":true,"data":true}。

5 输出与结果状态

200 {"ok":true,"data":true}；users.password_hash 更新；该用户全部 refresh_tokens 撤销（前端引导重登）。

6 状态流转

无用户级状态机；refresh_tokens 批量 active→rotated。

7 边界与异常

8 权限与数据规则

• 权限：登录态；只改自己（claims 绑定）。

F1.08 修改邮箱

对应 PRD：§4 M1 · PUT /api/auth/email ｜ 状态：实现 ｜ 实现落点：auth/service.go:220-244、auth_handlers.go:274-287 ｜ UI：/account（AccountView 安全区）｜ 场景挂钩：无独立 e2e（FAQ「改密登出」同族人工面）

1 功能定义

需当前密码确认的邮箱变更；成功后发站内通知（冻结 index.js:127-136 文案）。登出不联动（改邮箱不清会话，与改密不同——冻结语义保真）。

2 触发条件与前置状态

• 账号设置页提交改邮箱表单 → PUT /api/auth/email（Bearer）。
• 前置：新邮箱未被任何账号占用。

3 输入与校验

4 处理流程

PUT /auth/email → 停用拦 → 验当前密码 → 验新邮箱格式 → 唯一性 → UpdateEmail → 通知「登录邮箱已变更／登录邮箱已变更为 X，请使用新邮箱登录。」→ 200 {"ok":true,"data":{"email":"<新邮箱>"}}。

5 输出与结果状态

data.email = 新邮箱；users.email 更新；notifications 新增一行（标题+文案冻结逐字）。

6 状态流转

无。

7 边界与异常

8 权限与数据规则

• 权限：登录态；只改自己。
• 数据规则：users.email UNIQUE 兜底；通知文案与新邮箱值拼接（无模板）。

F1.09 工作台版本状态

对应 PRD：§4 M1 · PUT /api/auth/workspace-state ｜ 状态：实现 ｜ 实现落点：auth/service.go:247-255、auth_handlers.go:289-306 ｜ UI：工作台切换入口（双工作台 shot._tbl 通路的选择器）｜ 场景挂钩：无（M2 拆解域间接消费）

1 功能定义

保存用户工作台版本偏好（users.workspace_version）；非 'legacy' 值一律折 'classic'（白名单外静默归一，冻结 index.js:215 逐字）。

2 触发条件与前置状态

• 前端切换工作台版本 → PUT /api/auth/workspace-state（Bearer）。

3 输入与校验

4 处理流程

PUT /auth/workspace-state → 归一（≠legacy→classic）→ UpdateWorkspaceVersion → 200 {"ok":true,"data":{"workspace_version":"<归一值>"}}。

5 输出与结果状态

data.workspace_version 为归一后值（传 bogus 得 "classic"）；users.workspace_version 持久化。

6 状态流转

classic ⇄ legacy 二值域，无第三态。

7 边界与异常

8 权限与数据规则

• 权限：登录态；只改自己。
• 数据规则：M2 拆解域读此列决定 shots/director_shots 双表通路归属（shot._tbl 约定——见总则 §1 术语）。

M1 端点覆盖对账

9/9 对账 PRD §4 M1（DIF 新发现：DIF-28-1 注册台账描述硬编码——见 99-附录 B）。

4.2 - FSD M10 · 导演与融合

← 总则 ｜ 附录 → ｜ 上游：PRD §4 M10 实现落点：backend/internal/domain/director/（model/split/repo/service/service_assets/export 单包多文件）+ cmd/server/director_handlers.go（28 handler）+ generation 侧双表通路三锚点（model.go:56-69 ShotView.Tbl / service_video.go:191-229 DirectorShotVideo / repo.go:261-283 LinkShotVideo）+ cmd/server/routes.go:203-238（挂载）。事实基准=Go 代码；冻结版 qmtv/server/director.js（11）/fusion.js（17）仅差异对拍参照。 域内要点：双表通路——本域写 director_shots（M2 拆解台是 shots 表勿混），生成链经 ShotView.Tbl 显式表名打回；扣费面六处（三处硬编码照抄）；ZIP 导入导出；wire 全蛇形+派生视图尾插键；对账口径：routes.go:209/:223 注释「11+17」系冻结源文件口径（#1/#2 冻结在 fusion.js:221/:227 却排导演注释块），物理分组=导演 13+融合 15；PRD §4 M10 已登记差异 ①~⑮（prd-qmtv-v1.md:208）+v1.12 变更行三件（二十续 A1 form-tag/A2 空数组/A3 episodes 404 文案）引用不重立。ID 前缀 dpr_/dep_/dir_（tasks 侧 task_id=‘dir_’+project_id 约定=PRD ⑩）。

M10 导演与融合

28 端点全量。四零域反转：本域扣费面六处为全站最密（extract 总额扣+单价退/generate-image/fusion 硬编码 3/convert 硬编码 30/remix/资产生成）；split 双阈值 1200·800 合参（PRD ①）；审片入口在 M11（:266-267）share 在 M6 组（:115，冻结 index.js:574）——同前缀勿误收。

F10.01 项目列表与创建（director3d GET/POST）

对应 PRD：§4 M10 · GET/POST /api/director3d ｜ 状态：实现 ｜ 实现落点：director_handlers.go:21-52、service.go:110-137、repo.go（projects 段）｜ UI：Director3DView 项目列表 ｜ 场景挂钩：E2E-DIR-01（待实现，清单 :21——建项目→拆分集→分镜图生成）

1 功能定义

导演工作台项目面：列表（带分集预览）与创建（即时双阈值拆分集）。

2 触发条件与前置状态

登录态；create 前置 script_text 必填 400「剧本文本必填」（model.go:161，fusion.js:229——创建端点落在 fusion.js 冻结源，对账口径注记见册尾）。

3 输入与校验

{name, style_id, face_style, script_text, kind}（handlers :36-42；style_id 非空透传无白名单——vs face_style 白名单 service.go:130-132，quirk）；name/style_id 截断照冻结 fusion.js:232。

4 处理流程

create：INSERT dpr_ 行 → SplitEpisodes(script, 800)（fusion 阈值；director resplit 用 1200——两处刻意不同源勿统一，split.go:98-111 合参）逐集 INSERT dep_（标题缺省「第N集」）。

5 输出与结果状态

列表=ProjectRow+episodes 尾插（service.go:110-113）；create 返回 {id, episodes: n} 形态（照冻结 :227-236）。

6 状态流转

director_projects 无状态列；分集数创建即定（resplit 才重切）。

7 边界与异常

8 权限与数据规则

authed + amw；列表按 user_id 属主过滤；org_shared 列随行下发（M6 共享面消费）。

F10.02 项目详情/删除/重切分（:id GET/DELETE、resplit POST）

对应 PRD：§4 M10 · GET/DELETE /api/director3d/:id、POST /api/director3d/:id/resplit ｜ 状态：实现 ｜ 实现落点：director_handlers.go:80-112、service.go:139-183、repo.go:158-184 ｜ UI：Director3DView ｜ 场景挂钩：E2E-DIR-01（拆分集段）

1 功能定义

项目详情（含分集树）、删除（级联两删序）、重切分（1200 阈值重跑）。

2 触发条件与前置状态

属主校验：非本人 403「forbidden」（model.go:146）；不存在 404「not found」（:145）——文案分叉：『episode not found』系 extract/shots/convert 三处共享哨兵默认值（model.go:147），本面经 A3 重映射不直出。

3 输入与校验

resplit 前置项目存在+属主；script_text 不接受（重切用库内原 script——冻结同形）。

4 处理流程

• 详情：项目+分集树（episodes 尾插）+style_name JOIN（projectWithStyle service.go:212-215）。
• 删除：按 episode IN 子查询级联删 shots→episodes→项目（repo.go:158-166）——与 resplit 两删序不同（resplit 按 project_id 直删 :182-184），quirk 照抄冻结 :85-88 vs :95-96。
• resplit：删旧分集+分镜（按 project 直删）→ SplitEpisodes(script, 1200) 重插（service.go:165-176；1200 阈值——PRD ①）。

5 输出与结果状态

详情=ProjectWithEpisodes；删除/重切恒 true（无 404 面——quirk：删除查在先恒 ok service.go:149-157）。

6 状态流转

分集/分镜随 resplit 整体重建（旧 shots 含 video_id 一并清除——重建语义照冻结）。

7 边界与异常

8 权限与数据规则

authed + amw 属主面；级联删除顺序固定禁事务（中途失败半态=冻结同形）。

F10.03 分集详情（episodes/:eid GET）

对应 PRD：§4 M10 · GET /api/director3d/episodes/:eid ｜ 状态：实现 ｜ 实现落点：director_handlers.go:113-123、service.go:186-232、repo.go（episode JOIN 段）｜ UI：Director3DView L3 分集工作台 ｜ 场景挂钩：E2E-DIR-01（工作台装载）

1 功能定义

分集工作台装载面：分集行+全部分镜（含图/视频产物 URL）+资产三组，一响应全量。

2 触发条件与前置状态

URL 无 :id 项目段——属主按 ep.project_id → projects.user_id JOIN 判：非本人 403「forbidden」（service.go:231；冻结 director.js:117 逐字）；不存在 404「not found」（:222-226 本路由将共享哨兵 ErrEpisodeNotFound 重映射为 ErrNotFound——二十续 A3：冻结 :116 此面专属 ’not found’；’episode not found’ 仅 extract/shots/convert 三处直出）。

3 输入与校验

路径 :eid 无格式校验；无分页（全量分镜一次下发）。

4 处理流程

episodes 行 → shots 按 slot_no 序（每镜 slots 槽位组 service.go:267-278）→ assets 按 kind 三组 characters/scenes/props（:280-285）→ 图/视频经 imageFilePath/videoFilePath 解析 URL（export.go:137-152，store.Read 存在性守卫）。

5 输出与结果状态

{episode, shots:[{...shot, fields, slots, image_url?, video_url?}], assets:{characters, scenes, props}} 键形全蛇形。

6 状态流转

零写面；shot.status 消费面（processing/video_done 等由 F10.06/07 写入）。

7 边界与异常

8 权限与数据规则

authed + amw；assets 三组按 kind 聚合（本域 task_id=‘dir_’+project_id 约定隔离——PRD ⑩，M6 projectRank 依赖此形态）。

F10.04 资产提取（extract-assets POST）

对应 PRD：§4 M10 · POST /api/director3d/:id/episodes/:eid/extract-assets ｜ 状态：实现 ｜ 实现落点：director_handlers.go:124-140、service.go:453-490、repo.go（assets 段）｜ UI：Director3DView「提取资产」｜ 场景挂钩：E2E-DIR-01（集成实测 5 目标——含锚点前残余段 quirk）

1 功能定义

从分集文本提取角色/场景/道具三组资产并逐张生成立绘占位图：总额一次扣+逐张失败退单价 continue（PRD ⑨）。

2 触发条件与前置状态

属主双校验：项目+分集（eid↔project 无关联校验例外面——本端点校验关联，PRD ⑥ 注convert 例外）；无可提取资产 400「没有可提取的资产」（model.go:148）。

3 输入与校验

无 body；目标数由 splitScenes 解析决定。

4 处理流程

DeleteAssetsByTask 先清后插（service.go:468——重提取抹掉含导入的全部项目资产，quirk 照抄冻结 :153）→ 总额 ImageCost×N 一次 TryDeduct「导演工作台资产提取 ×N（-M）」（:461-464，taskKey=‘dir_’+pid）→ 逐张 Generate 失败：域内 Refund 唯一口退单价（nil claim 无防重面）+continue（:474-480，文案「资产图提取失败自动退回（+单价）：{err≤80}」）→ 风格前缀拼接 prompt（service.go:466，vs 资产生成后缀拼接——两源刻意不同，service_assets.go:109-117 注）。

5 输出与结果状态

{created: n, assets:{characters, scenes, props}}（同 F10.03 三组形态）。

6 状态流转

assets 行即插即生成（无队列）——与 F10.11 队列制不同源。

7 边界与异常

8 权限与数据规则

authed + amw 属主面；退款唯一口在域内 Refund（nil claim——extract 无认领制，与视频 ClaimVideoRefund 不同制）。

F10.05 分镜生成与编辑（shots POST、shots/:id PUT）

对应 PRD：§4 M10 · POST /api/director3d/:id/episodes/:eid/shots、PUT /api/director3d/shots/:id ｜ 状态：实现 ｜ 实现落点：director_handlers.go:141-166、service.go:235-405、repo.go:235-244 ｜ UI：Director3DView L3 分镜卡 ｜ 场景挂钩：E2E-DIR-01（分镜编辑段）

1 功能定义

分镜批量生成（从场景草稿落 director_shots）与单镜编辑（image_prompt/duration 等槽位）。

2 触发条件与前置状态

生成前置：eid↔project 无关联校验（service.go:309 注「逐字」PRD ⑥——仅校验各自存在+项目属主）；编辑前置：分镜属主（经 JOIN director_projects）。

3 输入与校验

生成 body {scope:[]} 按场景 no 过滤（handlers :128-131；空=全部）；编辑 body ShotInput 蛇形（service.go:392-400）；duration clamp 1-15s（videoCost 同参）。

4 处理流程

生成：SplitScenes 草稿（有标记 title=首行 slice40；无标记 rune>10 空行块+「第N场：未命名场景」，split.go:113-137）→ InsertShot 15 列 15?（repo.go:235-244——冻结字面 0 错位修后语义，PRD ④：resolution=草稿值、attempts=0）→ 分镜槽位组插入。 编辑：COALESCE 部分更新+video_id 不动（video 产物编辑不清）。

5 输出与结果状态

生成 {created: n}；编辑恒 true；响应行键形蛇形（ShotRow model.go）。

6 状态流转

status 初始 ‘draft’（InsertShot 修后语义）→ F10.06 图生成 ‘processing’→（图成）→ F10.07 视频链 ‘video_done’。

7 边界与异常

8 权限与数据规则

authed + amw 属主面；本域写 director_shots（M2 拆解台写 shots——双表通路归属标注，总则 §1 词条）。

F10.06 分镜图生成（generate-image POST）

对应 PRD：§4 M10 · POST /api/director3d/shots/:id/generate-image ｜ 状态：实现 ｜ 实现落点：director_handlers.go:167-181、service.go:407-425 ｜ UI：Director3DView 分镜卡「生成图」｜ 场景挂钩：E2E-DIR-01（分镜图生成段）

1 功能定义

单镜立绘/Storyboard 图生成：ImageCost 动态价扣费→generation.Generate（Mock SVG 或真实供应商）→images(kind=storyboard)+image_histories 落链。

2 触发条件与前置状态

分镜属主（DirectorShotForUser JOIN——ShotView.Tbl=‘director_shots’ 显式表名，generation/repo.go:261-275）；余额不足 402。

3 输入与校验

无 body（prompt 由分镜 image_prompt 组装+风格前缀）；provider 侧 size 白名单/4000 截断（generation/provider.go 通用守卫）。

4 处理流程

TryDeduct ImageCost「导演分镜图生成（-{cost}）」（service.go:410-413）→ gen.Generate → 成功：images 行+InsertImageHistory（ih_ 前缀——ids.PrefixImageHistory director/repo.go:319 消费，与 task 域 si_ 双轨并存，DIF-29-4 三十期勘正口径）+分镜回填 image_id；失败：RefundGenError 502 信封+域内退款（:418-420，「导演分镜图生成失败自动退回（+{cost}）：{err}」）。

5 输出与结果状态

{image_id, url, cost}（url=PathOf 落库口径）。

6 状态流转

shot.status=‘processing’（图链）→ 成功后回可生成视频态；重复生成追加 image_histories（历史链不截断）。

7 边界与异常

8 权限与数据规则

authed + amw 属主面；扣费 type=‘image’；images.kind=‘storyboard’ 与 M2 拆解图同表隔离（task_id 前缀 dir_）。

F10.07 分镜视频生成（generate-video POST）——双表通路

对应 PRD：§4 M10 · POST /api/director3d/shots/:id/generate-video ｜ 状态：实现 ｜ 实现落点：director_handlers.go:182-201、generation/service_video.go:191-229（DirectorShotVideo）、repo.go:274-283（LinkShotVideo）｜ UI：Director3DView 分镜卡「生成视频」｜ 场景挂钩：E2E-DIR-01（video_id 回填断言面）

1 功能定义

单镜视频生成（V2 动态价形态）：经 generation 域双表通路打 director_shots——ShotView.Tbl 显式字段是冻结 pseudoShot._tbl 鸭子字段的 Go 显式化（PRD ⑤）。

2 触发条件与前置状态

分镜属主（DirectorShotForUser JOIN director_projects，Tbl=‘director_shots’ generation/repo.go:273）；余额不足 402。

3 输入与校验

无 body；duration/ratio/resolution 取自分镜行（resolution 空回「1080p」COALESCE，repo.go:266）；videoCost(secs) clamp 1-15s（service_video.go:201-213）。

4 处理流程

TryDeduct videoCost「导演分镜视频 {secs}s（-{cost}）」（V2 计费形态）→ SmartVideo 编排（poll/SSE video 事件照 M3 四帧）→ 成功 LinkShotVideo(tbl='director_shots',…)：UPDATE video_id+status=‘video_done’+attempts+1（repo.go:274-283 按 Tbl 动态表名）；失败退款「导演分镜视频失败自动退回（+{cost}）」（Mock desc 参数化——PRD ⑮ 后半）。

5 输出与结果状态

{video_id, url, cost}；分镜 video_url 随 F10.03 详情解析。

6 状态流转

status→‘video_done’（终态；取消走 M3 cancel 面 taskId=‘dir_’+pid 隔离）。

7 边界与异常

8 权限与数据规则

authed + amw 属主面；台账 type=‘video’；本节是全站唯一跨域写表通路（generation 域函数写 director 域表——经 Tbl 参数化而非 import，域边界守卫形态）。

F10.08 项目 ZIP 导出（:id/export GET）

对应 PRD：§4 M10 · GET /api/director3d/:id/export ｜ 状态：实现 ｜ 实现落点：director_handlers.go:202-213、export.go:26-162 ｜ UI：Director3DView「导出项目」｜ 场景挂钩：无（E2E-EXP-01 为 M4 面）

1 功能定义

项目全量打包下载：六段 zip（project.json/episodes/*.txt/shots/EPxx.json/shots_all.json/images/EP{i}_shot{j}.png/videos/…svg）。

2 触发条件与前置状态

项目属主（403/404 同 F10.02）；素材缺失静默跳过（store.Read 失败=冻结 fs.existsSync 守卫，export.go:118-133）。

3 输入与校验

无 body；文件名净化 [\\/:*?"<>|]→_（export.go:22）+slice20。

4 处理流程

zip.NewWriter 逐段 addZipEntry（:153-161）：project.json（style 尾插+style_id 键保留 :38-49）→ episodes 文本 → shots 两形态 JSON → appendShotMedia 逐镜产物（store.Read，:118-133）→ 文件名 director-{pid前8}.zip（:86）→ zipRespond 二进制直出（application/zip+Content-Disposition）。

5 输出与结果状态

zip 字节流（PK 魔数——集成锚 integration_director_test.go:204-210 断言 :204 前缀）。

6 状态流转

零写面。

7 边界与异常

8 权限与数据规则

authed + amw 属主面；导出含全部素材字节（无脱敏）。

F10.09 项目 ZIP 导入（director3d/import POST）

对应 PRD：§4 M10 · POST /api/director3d/import（up20）｜ 状态：实现 ｜ 实现落点：director_handlers.go:53-79、export.go:164-234 ｜ UI：Director3DView「导入项目」｜ 场景挂钩：无

1 功能定义

v1 格式 ZIP 导入（project.json+episodes/*.txt）重建项目。

2 触发条件与前置状态

缺 ZIP 400「缺少 ZIP 文件」（model.go:158）；解析失败 400「ZIP 解析失败：{e.message}」（:159，前缀拼接）；限额 20MB（importZipLimit handlers :18+路由 up20，PRD ⑭）。

3 输入与校验

multipart file 字段；meta 必需 project.json（缺省兜底形态 export.go:192-234）；episodes 字典序排列。

4 处理流程

zip.NewReader（内存）→ project.json 解析（meta 缺省兜底）→ episodes/*.txt 按文件名字典序重建（标题「{原名}（导入）」后缀）→ SplitEpisodes 文本再切（1200 阈值——director.js:268 导入源）。

5 输出与结果状态

{id, episodes: n}（同 create 形态）。

6 状态流转

新项目 enabled 语义同 create；旧项目不受扰。

7 边界与异常

8 权限与数据规则

authed + amw；导入产物属主=当前用户；不导入素材字节（v1 仅文本结构——images/videos 不在包规格）。

F10.10 资产 CRUD 与公共池导入（assets 四件）

对应 PRD：§4 M10 · GET/POST /api/director3d/:id/assets、DELETE /api/director3d/assets/:id、POST /api/director3d/:id/assets/import ｜ 状态：实现 ｜ 实现落点：director_handlers.go:214-243/:300-327、service_assets.go:44-118/:417-435 ｜ UI：Director3DView L1 资产面（公共池 ['asset-library'] 同 key）｜ 场景挂钩：无

1 功能定义

项目资产三组读写+资产库（asset_library 公共池）导入。

2 触发条件与前置状态

GET/POST 前置项目属主；DELETE 查在先恒 ok（service_assets.go:74-82）；import 前置库资产存在 400「资产库资产不存在」（model.go:152）。

3 输入与校验

POST {name, style_id, face_style, script_text, kind}（handlers :36-42 复用）——name/kind 必填 400「名称与类型必填」（model.go:149）；风格后缀拼接（service_assets.go:109-117 注「与 extract 前缀两源刻意不同」）。

4 处理流程

import：asset_library 行复制为项目 assets（task_id=‘dir_’+pid，公共池隔离靠前缀）；DELETE 单行（级联 image 引用不动——image_id 保留孤儿兼容）。

5 输出与结果状态

列表=AssetRow+groups 三组尾插（service_assets.go:48-51 status 派生）；AssetRow.StyleID/FaceStyle json:"-" 不出 wire（model.go:81-82）。

6 状态流转

queue_status 由 F10.12 写；status 派生（image_id 有无）。

7 边界与异常

8 权限与数据规则

authed + amw 属主面；公共池 asset_library 全站共享读（导入才落项目域）。

F10.11 资产生成（generate + batch-generate POST）

对应 PRD：§4 M10 · POST /api/director3d/assets/:id/generate、POST /api/director3d/:id/assets/batch-generate ｜ 状态：实现 ｜ 实现落点：director_handlers.go:244-271、service_assets.go:120-198 ｜ UI：Director3DView 资产卡「生成」｜ 场景挂钩：无

1 功能定义

单个/批量资产立绘生成（ImageCost 计价）；批量逐笔容错（失败回 queued 不整单失败）。

2 触发条件与前置状态

已生成资产入队 400「该资产已生成，无需入队」（model.go:150）；batch：无 ids 且无待生成 400「没有待生成的资产」（:151）/有 ids 但全已生成 400「所选资产均已生成」（:150——双哨兵分叉 service_assets.go:163-167，二十续 A2 空数组方言收口）。

3 输入与校验

generate 无 body；batch {ids?:[]}——空数组=全量待生成（A2：MySQL IN () 500→Go 收口语义）。

4 处理流程

单发：TryDeduct「资产生成：{name}（-{cost}）」→Generate→回填；失败退「资产生成：{name}失败自动退回（+{cost}）：{err}」。批量：逐笔同上+失败 queue_status 回 queued 继续（:185-198）。

5 输出与结果状态

generate {image_id, url, cost}；batch {generated: n, failed: m}（failed=剩余数语义）。

6 状态流转

queued→生成中→done（image_id 回填）/失败回 queued（可重试）。

7 边界与异常

8 权限与数据规则

authed + amw 属主面（batch ids 逐个校验属主）；扣费 type=‘image’。

F10.12 待生成队列（queue 二件）

对应 PRD：§4 M10 · POST /api/director3d/assets/:id/queue、GET /api/director3d/:id/queue ｜ 状态：实现 ｜ 实现落点：director_handlers.go:272-299、service_assets.go:200-246、repo.go:18-26/:451 ｜ UI：Director3DView 队列面板 ｜ 场景挂钩：无

1 功能定义

资产入队/队列视图（持久化 queue_status）——批量排程前置面。

2 触发条件与前置状态

入队前置：已生成 400「该资产已生成，无需入队」；action 归一（非 unqueue 一律按 queue，service_assets.go:223-225 quirk 照抄 fusion.js:105）。

3 输入与校验

{action} 任意字符串（归一语义）；视图无分页。

4 处理流程

入队：queue_status=‘queued’；出队：=’’/置空；视图：QueueItemRow 七键投影（repo.go:18-26）双键排序。启动恢复由 recovery.requeueAssets 承接（service_assets.go:211-212 注——重启丢队列态回补）。

5 输出与结果状态

入队/出队恒 true；视图 queued 列表。

6 状态流转

queued ⇄ 空（unqueue）；done 由 F10.11 写。

7 边界与异常

8 权限与数据规则

authed + amw 属主面；零扣费（入队不扣，生成才扣）。

F10.13 融合生图与图片改创（fusion 二件 + remix）

对应 PRD：§4 M10 · POST/GET /api/director3d/:id/fusion、POST /api/director3d/:id/remix ｜ 状态：实现 ｜ 实现落点：director_handlers.go:328-371、service_assets.go:249-383 ｜ UI：Director3DView 融合 tab ｜ 场景挂钩：无

1 功能定义

双图融合生图（cost=3 硬编码）+融合历史列表+单图改创（remix，ImageCost 计价）。

2 触发条件与前置状态

fusion：画面描述必填 400「请填写画面描述」（model.go:154）；remix：原图存在 400「原图不存在」（:156）+改创说明必填「请填写改创说明」（:157）。

3 输入与校验

fusion {image_id_a, image_id_b, description, scene_id?}——scene_id 空串→NULL 指针（sceneIDPtr service_assets.go:509-514，scene_id || null 冻结同形）；remix {image_id, instructions}。

4 处理流程

fusion：const cost = 3 TryDeduct「融合生图（-3）」（service_assets.go:260 注「非 ImageCost——差异登记 PRD ⑦」）→ 双图 prompt 组合 → images(kind=fusion) → fusion_items 行（响应带 cost :310）。remix：ImageCost「图片改创（-{cost}）」（:366-369）→ images(kind=remix)。

5 输出与结果状态

fusion create {id, url, cost}；list=融合历史（LIMIT 面）；remix {image_id, url, cost}。

6 状态流转

零状态列（同步完成）。

7 边界与异常

8 权限与数据规则

authed + amw 属主面（image_id 引用校验属主）；fusion_items.scene_id 可空外键语义（NULL=非场景绑定）。

F10.14 参考视频（ref-videos 三件）

对应 PRD：§4 M10 · GET/POST /api/director3d/:id/ref-videos、DELETE /api/director3d/ref-videos/:id ｜ 状态：实现 ｜ 实现落点：director_handlers.go:372-425、service_assets.go:385-435 ｜ UI：Director3DView 参考视频区 ｜ 场景挂钩：无

1 功能定义

项目参考视频上传（60MB 新档位）/列表/删除。

2 触发条件与前置状态

上传前置文件存在 400「缺少视频文件」（model.go:158 族）+扩展名白名单 400「仅支持 mp4/webm/mov」（:159）；限额 60MB（refVideoLimit handlers :19+路由 up60 routes.go:208 新档位——PRD ⑭；handler 单文件双保险 500「File too large」:391-393）。

3 输入与校验

multipart file+name/note form tag（handlers :403-407——json tag 恒不命中，二十续 A1 修复锚）；name/note 可空。

4 处理流程

store.Put 大文件流 → ref_videos 行（rv_ 族）→ 列表蛇形投影；DELETE 恒 ok 不查行数（service_assets.go:430-435 quirk 照抄 fusion.js:215-218）。

5 输出与结果状态

上传 {id, url, name}；列表 rv 行数组；删除恒 true。

6 状态流转

零状态（上传即可用）。

7 边界与异常

8 权限与数据规则

authed + amw 属主面；素材字节落 MinIO/local（files 目录），wire 出 url=PathOf 口径。

F10.15 一键转剧（convert/:eid POST）

对应 PRD：§4 M10 · POST /api/director3d/:id/convert/:eid ｜ 状态：实现 ｜ 实现落点：director_handlers.go:426-436、service_assets.go:440-481 ｜ UI：Director3DView「一键转剧」｜ 场景挂钩：无

1 功能定义

分集文本一键转剧：flat=30 硬编码扣费→Mock 视频即弃（不落 videos 表）。

2 触发条件与前置状态

eid↔project 有关联校验（WHERE id AND project_id，service_assets.go:451-453——PRD ⑥ 的 convert 例外面：convert 是唯一校验关联的端点）；余额不足 402。

3 输入与校验

无 body；空场次→意图语义：ep.title 单场（:471-481——冻结 :262-267 fallback 对象调 .split 恒 TypeError 500，Go 按意图修，PRD ⑧ 登记）。

4 处理流程

const flat = 30 TryDeduct type='video'「一键转剧《{ep.title}》（-30）」taskID=裸 p.ID（:454-456——无 dir_ 前缀，PRD ⑦；集成断言 integration_director_test.go:229/:235 钉死）→ MakeVideo 占位 SVG 落盘 → 不落 videos 表（service_assets.go:440-441 注——与 M3 视频链不同源，产物一次性）。

5 输出与结果状态

{url, cost}（url 一次性产物链接）。

6 状态流转

无任务行无轮询（同步伪完成形态——M4 同款语义，status 无从查证）。

7 边界与异常

8 权限与数据规则

authed + amw 属主面；台账 type=‘video’ task_id=裸 pid（credit-records 按 taskId 聚合时与 M3 视频同族——m04 对账注记关联面）。

册尾端点覆盖对账（28/28）

对账 backend/cmd/server/routes.go:203-238 亲数 28 条 ↔ 本册 F10.01~F10.15。口径脚注：routes.go:209/:223 注释「导演面 11（director.js）/融合面 17（fusion.js）」系冻结源文件归属计数（#1/#2 冻结在 fusion.js:221/:227 却排导演注释块内）；物理分组=导演功能 13+融合功能 15，28 总数自洽。非本域同前缀：share（M6 组 :115，冻结 index.js:574——m06 F6.05）/review（M11 :266-267）勿误收。

差异纪律：PRD §4 M10 ①~⑮ 全引用不重立；二十续 A1/A2/A3 引 PRD v1.12 变更行；quirk（双方一致 as-is）节内登记不立 DIF——本册零新立 DIF（差异面全在 PRD 已登记集合；image_id=’’ 谓词引 ⑮ 族）。

4.3 - FSD M11 · 评估与工具

← 总则 ｜ 附录 → ｜ 上游：PRD §4 M11 实现落点：backend/internal/domain/evaluation/（model/service〔workbench+watchVideo〕/service_eval〔评估流水线〕/service_review〔审片双入口〕/service_viral/repo）+ cmd/server/workbench_handlers.go + cmd/server/evaluation_handlers.go + cmd/server/routes.go:239-267（挂载，审片 4 条 :264-267 物理居中）。事实基准=Go 代码；冻结版 qmtv/server/workbench.js/evaluation.js/index.js:490-513（viral）仅差异对拍参照。 域内要点：评估冻结-结算是全站唯一 TypeReserve 台账面（总则 §1 词条的展开落点）；审片双入口 404 文案分叉（classic ’task not found’ vs director ’not found’）；审片面零 SSE 零通知；watchVideo 状态丢失不 emit；wire 全蛇形；PRD §4 M11 已登记差异 ①~⑭（prd-qmtv-v1.md:216）引用不重立。上传档位 up80（工作台）/up10（评估）。

M11 评估与工具

14 端点全量（workbench 2+审片 4+eval 6+viral 2）。三扣费面三制式：工作台 TOOLS 固定价、审片 10（空分镜先退后拒）、评估 TypeReserve 冻结-结算、viral 5——四制式互不同源（quirk 富矿域）。

F11.01 工作台工具提交（workbench/tasks POST）

对应 PRD：§4 M11 · POST /api/workbench/tasks ｜ 状态：实现 ｜ 实现落点：workbench_handlers.go:18-54、service.go:141-221 ｜ UI：WorkbenchView（E2E-GEN-02 已实现——toast「去字幕完成」；confirm 仅 repaint 空描述分支）

1 功能定义

视频工作台三工具（一键转绘 20/去字幕 10/转高清 15）提交：扣费→异步处理→SSE workbench done。

2 触发条件与前置状态

登录态；tool key 白名单（TOOLS map）；余额不足 402；双载荷（multipart 视频/JSON 文本，PRD ⑩）。

3 输入与校验

{tool, video_id?/描述}——repaint 需描述（前端 confirm 分支对应）；taskId 无=空串（台账「工作台·X（-N）」service.go:176-178 逐字，冻结 workbench.js:52）。

4 处理流程

TryDeduct（固定价，settings 无此键）→ INSERT workbench_tasks（status=‘processing’）→ 异步 goroutine（提交段同步返回）→ watchVideo 编排（F11.02）。

5 输出与结果状态

{id, status:'processing'}（wb_ 行投影）；列表窄投影不含 params 全文（model.go json:"-" 面：OutPath/VideoStatus JOIN 伴列）。

6 状态流转

processing→done（SSE workbench done 帧）/failed（视频链失败联动）；「任务状态丢失」为终态旁支（不 emit，F11.02 §7）。

7 边界与异常

8 权限与数据规则

authed + amw 属主面；up80 档（workbench.js:12 multer 80MB 对齐，handler 单文件双保险 500「File too large」:35-37）。

F11.02 工作台列表/轮询/启动恢复（workbench/tasks GET）

对应 PRD：§4 M11 · GET /api/workbench/tasks ｜ 状态：实现 ｜ 实现落点：workbench_handlers.go:57-66、service.go:225-304 ｜ UI：WorkbenchView 列表+轮询 ｜ 场景挂钩：E2E-GEN-02（间接）

1 功能定义

本人工作台任务列表 + watchVideo 轮询状态机 + 服务重启悬挂恢复。

2 触发条件与前置状态

列表登录态（按 user_id）；watchVideo 由 F11.01 提交后 goroutine 内启动（非 HTTP 端点）。

3 输入与校验

无参数（全量本人任务，无分页——照冻结 :78-123）。

4 处理流程

watchVideo（service.go:228-260）：首 tick 3s/步进 5s/上限 180 次（model.go:117-122 可注入常量）→ VideoStatusOf 查 M3 videos 行 → done：SetWorkbenchDone+hub.Emit workbench done；视频 failed：SetWorkbenchWatchFailed 联动；状态丢失（!found 或超次）：置失败后直接 return 不 emit（:238-241——PRD ⑥：冻结 :84 同分支无 bus.emit）。 RecoverStuck：启动扫 processing 悬挂行→重挂 watchVideo（PRD ⑨，二十续迁移面）。

5 输出与结果状态

列表行+status（含 done/failed/「任务状态丢失」文案面）。

6 状态流转

与 F11.01 §6 同一张状态机（本节是驱动器）。

7 边界与异常

8 权限与数据规则

authed + amw；轮询消费 M3 videos 表跨域读（VideoStatusOf 窄投影三列）。

F11.03 智能审片·写（review 双入口 POST）

对应 PRD：§4 M11 · POST /api/tasks/:id/review、POST /api/director3d/:id/review ｜ 状态：实现 ｜ 实现落点：workbench_handlers.go:69-92、service_review.go:21-73 ｜ UI：DashboardView/VideoView 审片（classic）+ Director3DView 审片（director）｜ 场景挂钩：无

1 功能定义

智能审片提交：按 scope 拉分镜→LLM/Mock 逐镜评审→review_reports 落行。双入口同表同逻辑、404 文案分叉。

2 触发条件与前置状态

classic：task 存在+属主，404「task not found」（service_review.go:24）；director：404「not found」（:34）——两哨兵不同字（model.go:224/:227，PRD ⑦）；空分镜：先退台账再 400「审片退回：无分镜（+10）」（:52-58，Refund 唯一口 nil claim）。

3 输入与校验

无 body（scope 由服务端定）；审片费 10 固定（402 走统一信封）。

4 处理流程

TryDeduct「智能审片（-10）」→ 拉分镜（classic 走 shots/director 走 director_shots——跨域共表 COALESCE 可空列读，PRD ⑪ 炸点修复面）→ LLM 截 40 条（firstN :95）→ mockReview：阈值 0.22/0.5/0.7 三档 issue（high/mid/low，:140-146）+维度分 78+rand20，主体一致性 −6，clamp [55,98]（:157-161）→ review_reports 落行（scope/target_id 归属）。

5 输出与结果状态

{id}（report 行 id）；详情走 F11.04。

6 状态流转

同步完成（review_reports 一次落定，无 processing 态）。

7 边界与异常

8 权限与数据规则

authed + amw 属主面；零 SSE 零通知（全文件 grep Emit/InsertNotification 零命中——PRD ⑦，唯一不发通知的写路径）；扣费 type=‘review’。

F11.04 智能审片·读（review 双入口 GET）

对应 PRD：§4 M11 · GET /api/tasks/:id/review、GET /api/director3d/:id/review ｜ 状态：实现 ｜ 实现落点：workbench_handlers.go:81-116、service_review.go:76-88 ｜ UI：同 F11.03 读侧 ｜ 场景挂钩：无

1 功能定义

审片报告读取：按 target 取最新报告（含逐镜 issues/维度分/总分）。

2 触发条件与前置状态

属主校验同写侧（双 404 文案分叉同 F11.03 §2）；无报告返回 null 形态（非 404——照冻结 :198-203/:220-225）。

3 输入与校验

路径 :id（classic=task id / director=project id）。

4 处理流程

review_reports 按 target_id DESC 取首行 → report JSON 反序列化下发。

5 输出与结果状态

{report: {...}|null}；issues 数组键形照 mockReview 产出（shot_no/level/message）。

6 状态流转

零写面。

7 边界与异常

8 权限与数据规则

authed + amw 属主面；报告 JSON 全文下发（无脱敏）。

F11.05 评估配置与上传（evaluations/config + upload）

对应 PRD：§4 M11 · GET /api/evaluations/config、POST /api/evaluations/upload（up10）｜ 状态：实现 ｜ 实现落点：evaluation_handlers.go:17-53、service_eval.go:28-43/:47-90/:521-590 ｜ UI：EvaluationView 配置区+上传 ｜ 场景挂钩：无

1 功能定义

评估价目配置读面（quick/deep 双价）+ 剧本文件上传解析（txt/docx、GBK 回退）。

2 触发条件与前置状态

config 登录态；upload up10 档（原 studio cover 档复用）。

3 输入与校验

config 无参；upload multipart file——.txt/.docx 白名单；costOf settings 0 值回退默认（service_eval.go:38-42 err != nil || n == 0 → def，PRD ①；quick 默认 100/deep 300）。

4 处理流程

• config：两价+引擎名——engine『规则(Mock)』字面（:48-51，与 F11.06 POST 面『规则』两字面不同源，PRD ②）。
• upload：GBK 判定（ToValidUTF8→U+FFFD 计数>max(2, 0.2%)→GB18030 解码 :521-534，M9 同族）→ .docx 走 zip 解包+XML 五实体反转义（&/</>/"/&#N;，:537-590）→ 纯文本回传。

5 输出与结果状态

config {quick: n, deep: n, engine: str}；upload {text, name, chars} 形态（rune 计数）。

6 状态流转

零写面（upload 不落库——解析产物仅回显，落库在 F11.06 create）。

7 边界与异常

8 权限与数据规则

authed + amw；价键 eval_cost_quick/eval_cost_deep（管理台计费配置可调——标「可调」族）。

F11.06 评估项目与流水线（evaluations 三件+runEval）

对应 PRD：§4 M11 · POST/GET /api/evaluations、GET /api/evaluations/:id ｜ 状态：实现 ｜ 实现落点：evaluation_handlers.go:54-101、service_eval.go:93-153/:226-321 ｜ UI：EvaluationView 列表+进度轮询 ｜ 场景挂钩：无（SSE eval 三态帧：stage/done/failed）

1 功能定义

评估项目创建（TypeReserve 冻结扣费）→ 异步流水线（五 stage 推进+SSE）→ 终态结算。

2 触发条件与前置状态

create：script_text 必填；mode ∑ {quick, deep}——非法值静默归 quick 无 400（service_eval.go:97-100，PRD ③）；余额不足 402。

3 输入与校验

{name, script_text, mode}——name 缺省「未命名评估」族；script_text 落库截断（与 upload 解析面衔接）。

4 处理流程

TryDeduct type='reserve'「剧本快速/深度评估冻结（-N，完成后结算）」taskID=id（:104-106 冻结 :252-253 逐字）→ INSERT eval_projects（status=‘running’）→ 异步 goRun（:226 起，注入点便于测试）：五 stage 推进（解析/拆解/维度打分/汇总/出报告，SSE eval stage 帧逐发）→ Mock 确定性打分 (v*7919)%40（:398，冻结 :56 镜像）→ done：SetEvalDone（无台账动作——冻结即终态；TypeReserve 台账仅失败面全额退款消化）+SSE done；失败：全额退款「评估失败自动退回（+N）」+SSE failed+通知「评估失败：《name》…N 积分已退回」（evalFail :311-321，错误截 100）。

5 输出与结果状态

create {id}；list=EvalListRow 定列七投影（model.go:173-181，Report json:"-" 不入列表）；:id=全行+report（终态才有）。

6 状态流转

running→done/failed（SSE eval 帧+前端 3s 轮询双通道——E1 轮询机保留手管先例）；finished_at UTC 形态（PRD ④）。

7 边界与异常

8 权限与数据规则

authed + amw 属主面；TypeReserve 是全站唯一冻结-结算制（先冻结后按结果结算/失败全退——总则 §1 词条展开）；evalLLM 通道已接线（PRD ⑤，二十一期⑦）。

F11.07 评估报告下载（evaluations/:id/report GET）

对应 PRD：§4 M11 · GET /api/evaluations/:id/report ｜ 状态：实现 ｜ 实现落点：evaluation_handlers.go:102-114、service_eval.go:156-222 ｜ UI：EvaluationView「下载报告」｜ 场景挂钩：无

1 功能定义

评估报告 GAE 模板渲染下载（docx 兼容 HTML 容器）。

2 触发条件与前置状态

项目存在+属主；status 非 done 时 report 缺失→按冻结形态返回空/错误面。

3 输入与校验

路径 :id；无 body。

4 处理流程

report JSON → GAE 模板变量填充（七维表/总分/建议段）→ HTML 全文响应（前端 blob 下载——E1 保留 fetch+blob 先例）。

5 输出与结果状态

text/html 全文（非 JSON 信封——下载面直出）；engine 字面「规则」（POST 面字面——PRD ② 双字面对照 F11.05）。

6 状态流转

零写面。

7 边界与异常

8 权限与数据规则

authed + amw 属主面；报告含全维度明文。

F11.08 爆款分析（viral-analysis 二件）

对应 PRD：§4 M11 · GET/POST /api/viral-analysis ｜ 状态：实现 ｜ 实现落点：evaluation_handlers.go:115-138、service_viral.go:16-67、repo.go:397 ｜ UI：ViralAnalysisView ｜ 场景挂钩：无

1 功能定义

爆款标题/文案四维建议生成（math/rand Mock）：单次扣 5 积分，历史保留最近 20 条。

2 触发条件与前置状态

create：title 必填（空→400 族）；余额不足 402。

3 输入与校验

{title}；title 截 255（slice :56，PRD ⑧ 二十一期 B2 补登）。

4 处理流程

TryDeduct CostViral=5（billing.go:15）→ math/rand 四维 advice（score=60+Intn(35)、comment/emoji/duty 三键随机池，service_viral.go:44-50——math/rand 非确定性 Mock，PRD ⑧；与 eval 7919 确定性不同制）→ viral_analyses 落行（五列 INSERT）→ 响应。

5 输出与结果状态

create {id, advice:{score, comment, emoji, duty}}；list=本人最近 LIMIT 20（repo.go:397），Result/Status json:"-"（model.go json:"-" 面）。

6 状态流转

零状态（同步完成落行）。

7 边界与异常

8 权限与数据规则

authed + amw 属主面；扣费 type=‘viral’（TypeViral 独立常量——credit-records 单列归组）。

册尾端点覆盖对账（14/14）

对账 backend/cmd/server/routes.go:239-267 亲数 14 条 ↔ 本册 F11.01~F11.08（审片 4 条 :264-267 物理居 M11 段，:259-262 为 M13 spark 段——紧邻勿混）：

（:249/:256/:259-263 为注释/空行/M13 spark 段邻接行，非端点。）

差异纪律：PRD §4 M11 ①~⑭ 全引用不重立；本册零新立 DIF（goroutine recover/三注入点系测试基建形态非行为差异，节内注记）；集成锚第十一链 EvaluationChain/第十二链 WorkbenchNotifyChain 在位（backend/integration_test.go）。

4.4 - FSD M12 · 管理后台

← 总则 ｜ 附录 → ｜ 上游：PRD §4 M12 实现落点：backend/internal/domain/admin/（model 276/repo 476/service 332/service_billing 416/service_prompts 250 单包多文件+三测试件）+ cmd/server/admin_handlers.go（562 行 39 handler）+ cmd/server/routes.go:268-318（挂载）。事实基准=Go 代码；冻结版 qmtv/server/index.js（admin 段 app.* 直挂非 router，19−withdrawals 2=17）+llmroutes.js（18）+routes2.js（admin 4）仅差异对拍参照。 域内要点：39 条全部 amw+adminMw 双挂（403 forbidden，gateway/auth.go:133-141=冻结 adminRequired 逐字）；前端消费面≠端点族——AdminView 14 tab（AdminView.vue:667-682）中 submissions/withdrawals/scripts 三 tab 消费 M9/M7 域端点，本册 39 条按后端功能族 AH 组聚合；404 八态八哨兵刻意不同源（model.go:16-36：用户调整英文 “not found”/密码重置中文「用户不存在」/org approve 英文/指令 DELETE 英文/提示词删「版本不存在」/接入「接入不存在」/release「任务不存在或不是失败态」/重拆「任务不存在」）；bind 失败统一 400「请求体格式错误」（与 m08 裸传 return err 两域不同制）；api_key json:"-" masked-only（二十一期②收敛，PRD ④）；GetActivePrompt（整行+split 三级）↔activePromptContent（content-only 单级）两份同语义并存（二十二期 C1 裁决 a，task_assembly.go:188-189 注释「两处改动须同步对拍」）。PRD §4 M12 已登记差异 ①⑨（prd-qmtv-v1.md:222）引用不重立。

M12 管理后台

39 端点全量（冻结三文件 41 物理 − withdrawals 2 归 M7；对账脚注见册尾）。静态段优先三处：credit-records/export、instruction-versions/active、prompts/upload 与 :id 参数段并存——echo radix 静态子节点恒先匹配（routes.go:270-272 注）。

F12.01 概览与运行时观测（summary/runtime）

对应 PRD：§4 M12 · GET /api/admin/summary、GET /api/admin/runtime/tasks ｜ 状态：实现 ｜ 实现落点：admin_handlers.go:19-35/:127-135、service.go:63-65/:236-246、repo.go:91-109/:215-229 ｜ UI：AdminView.vue（概览 tab+运行时面板 30s 轮询）｜ 场景挂钩：E2E-ADM-01（✅ 只读巡检断言 .stat≥5）；AdminChain 集成锚

1 功能定义

全站六计数概览+运行中视频/拆解双列表观测（前端 30s 轮询面）。

2 触发条件与前置状态

双挂+requireDB；零参数零 body（无 bind 路径）。

3 输入与校验

无输入。

4 处理流程

summary：六条独立 SELECT 顺序执行无事务（repo.go:91-109=冻结同形）。runtime：ListRuntimeVideos（status IN ('processing') LIMIT 50）+ListRuntimeSplits（split_status='processing' LIMIT 50）。

5 输出与结果状态

summary 顶层键序 users,tasks,images,videos,credits_granted,credits_consumed（model.go:63-70=冻结 :641-648 展开序）；runtime 键序 videos,splits，videos 行键 id,status,seconds,resolution,created_at,email,title（title *string 可空）、splits 行键 id,title,created_at,email。

6 状态流转

只读；不订阅 SSE（M12 全程无 bus.emit——repo.go:252-253 注，与 m08 recharge SSE 对照面）。

7 边界与异常

无哨兵路径；DB 错误 → errRespond default 500。

8 权限与数据规则

quirk：六计数非事务一致性（计数间可撕裂，冻结同形照抄）；credits_granted/consumed 以 amount>0/amount<0 符号二分而非 type 字段。

F12.02 用户列表与合并 mutation（users GET/PUT）

对应 PRD：§4 M12 · GET、PUT /api/admin/users(/:id) ｜ 状态：实现 ｜ 实现落点：admin_handlers.go:30-58、service.go:67-98、repo.go:113-153 ｜ UI：AdminView.vue（用户管理 tab——adjustCredits/toggleUserStatus/setAdmin 合并 mutation）｜ 场景挂钩：AdminChain；E2E-ADM-01（用户行≥3）

1 功能定义

8 列投影全量用户列表+credits 差额调整/status/role 更新的合并 mutation。

2 触发条件与前置状态

双挂+requireDB；PUT 经 GetUserCredits 无行 → 404 英文 “not found”（ErrAdjustNotFound——与 F12.03 中文 404 刻意不同源）。

3 输入与校验

GET 零参数。PUT body credits *int64（指针透传=冻结 credits != null 判空）+status/role string（空串跳过 truthy 才更新）；bind 失败 → 400「请求体格式错误」。

4 处理流程

AdjustUser（service.go:74-98）：①GetUserCredits ErrNoRows→404；②delta != nil → credits.Add(u.ID, float64(*delta)-u.Credits, admin_adjust, "管理员调整积分", "")——Δ=req.credits−u.credits 现值差；③status/role 各自独立 UPDATE 无事务（users 无 updated_at 列不写=冻结同形）。ErrNoUser 吞掉（PRD ③——冻结 addCredits 静默 no-op）。

5 输出与结果状态

GET 行键序 id,email,nickname,role,credits,status,referral_code,created_at（referral_code *string NULL→null）；PUT data:true。无分页无搜索（前端 filteredUsers 客户端过滤，repo.go:113）。

6 状态流转

users.status/role 直改；credits 经 credits.Add 唯一口落 credit_records（type=admin_adjust）。

7 边界与异常

8 权限与数据规则

quirk：差额调整语义（前端传绝对值后端算 Δ）；跨域共表 users 本域持有写。

F12.03 密码重置（users/:id/password POST）

对应 PRD：§4 M12 · POST /api/admin/users/:id/password ｜ 状态：实现 ｜ 实现落点：admin_handlers.go:60-76、service.go:100-119、repo.go:131-159 ｜ UI：AdminView.vue（用户管理 tab resetPassword）｜ 场景挂钩：AdminChain

1 功能定义

管理员重置用户密码（校验序 404→400 十六续 A1 修序）。

2 触发条件与前置状态

双挂+requireDB；UserExists 不存在 → 中文 404「用户不存在」（ErrUserNotFoundCN——八态之二）。

3 输入与校验

body password string；bind 失败 → 400「请求体格式错误」；len(password) < 8 → 400「密码至少 8 位」（冻结 index.js:143 逐字）。先存在后长度（顺序对齐冻结 :140-142，service.go:100-102 注「十六续 A1 修序」）。

4 处理流程

UserExists → 长度校验 → crypto.HashPassword → UpdateUserPassword 单列覆盖（repo.go:156-159）。

5 输出与结果状态

data:true。

6 状态流转

users.password_hash 覆写；refresh_tokens 不动（不撤销 refreshToken=冻结语义 quirk，repo.go:155-156）。

7 边界与异常

8 权限与数据规则

quirk：len() 字节序无 trim（冻结 String(req.body.password||'') 空串→len 0→400 同效）；旧 refreshToken 仍有效。

F12.04 发放流水与发放（credit-grant-records GET/POST）

对应 PRD：§4 M12 · GET、POST /api/admin/credit-grant-records ｜ 状态：实现 ｜ 实现落点：admin_handlers.go:79-109、service.go:126-141、repo.go:162-175 ｜ UI：AdminView.vue（积分 tab doGrant——全页唯一跨分区联动 grantRecords+users 双刷）｜ 场景挂钩：AdminChain

1 功能定义

发放流水列表（amount>0 跨分区联动）+向用户发放积分+通知。

2 触发条件与前置状态

双挂+requireDB；POST userID=="" || amount==0 → 400「参数错误」（冻结 :667 !user_id || !amount）。

3 输入与校验

POST body user_id/amount int64/description（缺省「管理员发放积分」）；bind 失败 → 400「请求体格式错误」。

4 处理流程

credits.Add(userID, amount, admin_grant, desc, "")——task_id 空（冻结 4 参调用 :668），ErrNoUser 吞掉（冻结静默但通知照发 service.go:126-127 注）→ InsertNotification：title「积分到账」+content 管理员为您发放 %d 积分：%s（冻结 :669 逐字）。

5 输出与结果状态

GET 行键序 id,user_id,task_id,amount,balance_after,type,description,created_at,email,nickname（task_id *string NULL 透传、amount float64——0004 DECIMAL）；LIMIT 200；无 type 过滤仅 amount>0（quirk：充值 credit/admin_grant/admin_adjust/release 退款全部入「发放流水」列表——跨分区联动面）。POST data:true。

6 状态流转

credit_records 新行 type=admin_grant + notifications 新行。

7 边界与异常

8 权限与数据规则

quirk：用户不存在仍 ok:true 通知照发（通知 userId 为不存在 id=冻结 :669 无条件执行同形）。

F12.05 流水导出 CSV（credit-records/export GET）

对应 PRD：§4 M12 · GET /api/admin/credit-records/export ｜ 状态：实现 ｜ 实现落点：admin_handlers.go:111-124、service.go:202-233、repo.go:178-182 ｜ UI：AdminView.vue（积分 tab 导出按钮 fetch+blob）｜ 场景挂钩：无专项 e2e（AdminChain）；静态段优先第一处（routes.go:270-272 注）

1 功能定义

全量流水 CSV 直出（Excel 可开）——非 JSON 信封端点。

2 触发条件与前置状态

双挂+requireDB；零参数零 body。

3 输入与校验

无输入。

4 处理流程

ListExportRows（7 列 JOIN DESC LIMIT 10000）→ "" BOM → 头行 时间,用户邮箱,昵称,类型,事项,积分,余额 → 每行 7 字段全量引号包裹（"→"" 转义）+CRLF 分隔 → 时间 2006-01-02 15:04:05、数值 FormatFloat。handler：Content-Type text/csv; charset=utf-8 + Content-Disposition attachment + WriteHeader(200) 直写。

5 输出与结果状态

CSV 文本流（列序 created_at,email,nickname,type,description,amount,balance_after）；LIMIT 10000 静默截断无溢出标记。

6 状态流转

只读。

7 边界与异常

8 权限与数据规则

quirk：全字段强制双引号包裹（冻结 :196-197 同形）；BOM+CRLF；10000 截断静默。

F12.06 生成审计与人工释放（failures/release）

对应 PRD：§4 M12 · GET /api/admin/generation-audit/failures、POST …/videos/:id/release ｜ 状态：实现 ｜ 实现落点：admin_handlers.go:140-159、service.go:146-184、repo.go:187-212+generation/repo.go:214-222 ｜ UI：AdminView.vue（任务审计 tab）｜ 场景挂钩：AdminChain（47=7+5×8 videoCost 联动断言）

1 功能定义

失败视频+失败拆解双列表观测+失败视频人工退款释放（CAS 认领制）。

2 触发条件与前置状态

双挂+requireDB；release 仅路径 :id 零 body；FailedVideoByID（窄投影 5 列——error TEXT NULL 不进投影防 scan 坑，repo.go:203-204 注）ErrNoRows → 404。

3 输入与校验

GET 零参数；release 无 body 无 bind。

4 处理流程

failures：ListFailedVideos（status='failed' LIMIT 100，LEFT JOIN tasks）+ListFailedSplits（status='failed' OR split_status='failed' LIMIT 100）。release：①查行 404 → ②ClaimManualRelease（UPDATE videos SET refunded=1, error=CONCAT(COALESCE(error,''),'（已人工退款）') WHERE id=? AND refunded=0——CAS 认领+error 追加一步）affected=0 → 400「该任务已自动退款」 → ③cost=billing.VideoCost(secs)（secs<=0 归 5=冻结 seconds||5） → ④credits.Refund type=release desc「人工释放：失败视频退款（+%d）」。冻结序「查→检查 refunded→加币→置位」有并发双退窗，Go 认领前置收口（service.go:158-160 注，PRD ⑥）。

5 输出与结果状态

failures 键序 videos,splits；videos 行键 id,error,seconds,resolution,attempts,refunded,created_at,email,task_title,user_id（error/task_title *string NULL→null）；splits 行键 id,title,error,created_at,email（tasks.error 已 0002 收紧 NOT NULL）。release {"refunded": cost}。

6 状态流转

videos：failed → refunded=1 + error 尾缀追加；credit_records type=release 行；无通知。

7 边界与异常

8 权限与数据规则

跨域共表——videos 写归 generation（ClaimManualRelease 窄接口 service.go:40-42）；退款额随 credit-settings 写侧联动（改 video_pull 后生效——集成断言 47=7+5×8）。

F12.07 重拆（retry-split POST）

对应 PRD：§4 M12 · POST /api/admin/generation-audit/tasks/:id/retry-split ｜ 状态：实现 ｜ 实现落点：admin_handlers.go:162-169、service.go:188-197、task/service.go:469-485 ｜ UI：AdminView.vue（任务审计 tab）｜ 场景挂钩：AdminChain

1 功能定义

任务清分镜后 Mock 重拆（跨域共表写归 task 域 AdminRetrySplit）。

2 触发条件与前置状态

双挂+requireDB；仅路径 :id 零 body；AdminTaskByID ErrNoRows → 404。

3 输入与校验

无 body 无 bind。

4 处理流程

AdminRetrySplit（task/service.go:469-485）：①AdminTaskByID → ②ClearShotImagesByTask（不删根资产=冻结无此步，重复重拆根资产重复系冻结原样，PRD ⑥）→ ③DeleteShotsByTask → ④fillWithMock 直插 → ⑤RecoverSplitDone（status='complete', split_status='done'=冻结 :187）。

5 输出与结果状态

data:true。

6 状态流转

tasks 任意态 → complete/done；shots+shot_images 销毁重建；assets 根资产不动。

7 边界与异常

8 权限与数据规则

tasks/shots/shot_images 共表写归 task 域（SplitRefiller 窄接口，TECH.md §2.1 共表登记）；无用户属主校验（admin 全权=冻结）。

F12.08 公告管理（announcements 三件）

对应 PRD：§4 M12 · GET、POST /api/admin/announcements、PUT /api/admin/announcements/:id ｜ 状态：实现 ｜ 实现落点：admin_handlers.go:174-220、service.go:257-281+325-332、repo.go:234-257 ｜ UI：AdminView.vue（公告 tab createAnn——busy quirk 同步复位照抄勿修）｜ 场景挂钩：AdminChain（扇出区间断言抗并发）

1 功能定义

公告 CRUD 面（读/建+全量扇出/toggle 置位——无 title/content 编辑端点，冻结同构）。

2 触发条件与前置状态

三处双挂+requireDB；POST title=="" || content=="" → 400「标题和内容必填」；PUT 无存在性校验（不存在 id 也 ok:true）。

3 输入与校验

POST body title/content（bind 失败 → 400「请求体格式错误」）；PUT body active bool。

4 处理流程

CreateAnnouncement：an_ id → InsertAnnouncement 三列（active 落 DDL 默认 1）→ ListUserIDs 全量 → 逐用户 INSERT notification 扇出：title「新公告：」+title、content truncateRunes(content, 100)（rune 截断=冻结 content.slice(0,100) 等价）——循环内任一失败即中断返回 err（部分扇出无回滚=冻结 forEach 同形）。ToggleAnnouncement：单列 UPDATE 恒 ok（repo.go:246 注）。

5 输出与结果状态

GET 行键序 id,title,content,active,created_at；POST {"id"}；PUT true。无 LIMIT。

6 状态流转

announcements.active 布尔位；notifications 全量扇出行。

7 边界与异常

8 权限与数据规则

quirk：content 截 100 rune 只作用于通知、公告正文存全量；active wire bool（vs 冻结 1/0——DIF-31-3）；公开读镜像归 M5（routes.go:102 pub 无 amw）。

F12.09 组织审批（organization-applications 三件）

对应 PRD：§4 M12 · GET、POST /api/admin/organization-applications(/:id/approve|/:id/reject) ｜ 状态：实现 ｜ 实现落点：admin_handlers.go:222-254、service.go:292-323、repo.go:262-301 ｜ UI：AdminView.vue（orgAppReview tab——approve/reject 合并 mutation）｜ 场景挂钩：AdminChain（reject 幽灵 id 恒 ok 断言）

1 功能定义

组织入驻申请列表+审批（approve 建 org 四写+通知）+驳回（无条件恒 ok）。

2 触发条件与前置状态

三处双挂+requireDB；三端点均仅路径 :id 零 body 无 bind；approve 仅 pending 命中否则英文 404（WHERE id=? AND status='pending' 窄投影 3 列——reason TEXT NULL 不进投影）。

3 输入与校验

无输入。

4 处理流程

approve 四写+通知零事务（service.go:292-318=冻结 :692-702 逐条直译）：UpdateOrgAppStatus ‘approved’ → InsertOrganization（org_，credits=0）→ InsertOrgMember（om_ role=‘owner’）→ SetUserOrg（users.org_id 回填）→ 通知「企业入驻审核通过」+组织「%s」已创建，您是管理员。（冻结 :700 逐字）。reject：无条件 UPDATE ‘rejected’，不存在也 ok:true（service.go:321-323——与 approve 严格不对称）。

5 输出与结果状态

GET 行键序 id,user_id,company,contact,reason,status,created_at,email——version int64 json:"-" 不进 JSON（model.go:177-187）；reason *string NULL→null。approve {"org_id"}（冻结 :701）；reject true。无 LIMIT。

6 状态流转

org_applications：pending→approved（仅此路径有守卫）；pending/任意态→rejected（无守卫）。

7 边界与异常

8 权限与数据规则

quirk：四写零事务（中途失败留半态=冻结逐条 run 同形）；organizations/org_members/org_applications/users.org_id 跨 M6 共表但本域直写（model.go:3-5 自持表登记）。

F12.10 计费配置（credit-settings/model-settings 四件）

对应 PRD：§4 M12 · GET、PUT /api/admin/credit-settings、GET、PUT /api/admin/model-settings ｜ 状态：实现 ｜ 实现落点：admin_handlers.go:256-287、service_billing.go:3-109、repo.go:307-326 ｜ UI：AdminView.vue（计费 tab saveBilling——只写局部零刷新三零刷新面之一）｜ 场景挂钩：无专项 e2e（AdminChain）

1 功能定义

system_settings KV 配置读写（五键积分+四键模型名；GET/PUT 两面共用全量十键白名单）。

2 触发条件与前置状态

四处双挂+requireDB；PUT 任意 JSON 对象——白名单外键静默忽略恒 ok（service_billing.go:80-90）。

3 输入与校验

PUT body map[string]any（bind 失败 → 400「请求体格式错误」）；无键校验。

4 处理流程

GET：逐键 settingOrDefault（无行回退 defaultSettings 十键=冻结 routes2.js:26-37 DEFAULT_SETTINGS）。PUT：遍历 body → 白名单键 UpsertSetting(k, jsString(v))（ON DUPLICATE KEY upsert；值恒字符串 jsString：null→“null”/bool→“true”）。读侧零失效：genBilling/modelCfg 每请求现查 DB，UPSERT 后下一请求即生效（service_billing.go:3-5 注）。

5 输出与结果状态

credit-settings 键序 trial_credits,text_tokens_per_credit,image_generation,video_pull,video_per_second；model-settings 键序 text_model,image_model,image_model_fallback,video_model——值恒字符串；冻结键名 image_model_fallback（PRD 曾误写 image_fallback_model 勿跟）。PUT data:true。

6 状态流转

system_settings KV upsert；provider_routing 在白名单内但两 GET 均不回显（冻结 :36 同形）。

7 边界与异常

8 权限与数据规则

quirk：PUT /credit-settings 可写 text_model 等、PUT /model-settings 可写 trial_credits 等（同一全量十键白名单——冻结 :74-79/:84-88 同一循环同形照抄勿"修复"）；死端点：model-settings GET/PUT 前端零调用（PRD ②）。

F12.11 模型接入（model-endpoints 六件）

对应 PRD：§4 M12 · GET、POST /api/admin/model-endpoints、PUT、DELETE …/:id、POST …/:id/activate、POST …/:id/test ｜ 状态：实现 ｜ 实现落点：admin_handlers.go:289-370、service_billing.go:114-162/:182-300/:306-416、repo.go:331-386 ｜ UI：AdminView.vue（模型接入 tab+meTest .catch(()=>{}) 防御死代码注）｜ 场景挂钩：无专项 e2e（AdminChain；api_key 不回显断言）

1 功能定义

模型接入注册表全生命周期（列表+建+改+删+激活+三分支连通测试）。

2 触发条件与前置状态

六处双挂+requireDB；PUT/DELETE/activate/test 经 GetEndpointByID 404 前置 → 「接入不存在」（八态之六，四路同源）。

3 输入与校验

POST body purpose/name/base_url/api_key/model（purpose ∉ {text,image,video} → 400「未知模型用途」；name/base_url/model 任一空 → 400「显示名、接口地址、模型名必填」；name 截 60 rune、base_url/api_key/model TrimSpace）；PUT body 五指针（nil 即未传）。bind 失败 → 400「请求体格式错误」。

4 处理流程

List：ensureEndpointSeed（表空且三 KV 全非空 → 插「文本接入（迁移）」+置 active=冻结 models.js:12-24）→ 全量列表 → maskEndpoint（api_key 非空 → 前 6 rune+******；has_key=api_key!=""）→ active 三键（KV active_model_<p> → 行按 id+purpose 不查 enabled）。Create：me_ 行 enabled=1 → 该用途首个接入自动置 active（冻结 models.js:64）。Update：api_key 空串=保留旧值 SQL CASE（repo.go:374-380 CASE WHEN ? IS NULL OR ?='' THEN api_key ELSE ? END；其余 COALESCE）。Remove：删行 → 删的是 active 则 DeleteSetting(active_model_)。Activate：UpsertSetting → 返回 purpose。Test：三分支（text→chat/completions max_tokens 8 reply 截 30/image→images/generations 红圆判 has/video→GET base 可达）；超时 45s → TestError{504「连接超时」}/502（err 截 300）。

5 输出与结果状态

GET 键序 purposes,endpoints,active（purposes 各 {name,usage} 文案=冻结 models.js:6-10 逐字）；endpoints 行键序 id,purpose,name,base_url,model,enabled,created_at,api_key_masked,has_key——api_key json:"-" 不回显（二十一期②收敛，PRD ④——wire 与冻结分叉一处）；active 三 *string（id‖null）。POST {"id"}；PUT/DELETE true；activate {"purpose"}；test {ok, reply? omitempty, note}。

6 状态流转

model_endpoints 行 + system_settings active_model_<purpose> KV；enabled 位由 PUT 任意翻转不联动 active KV（展示面 getActiveRaw 不查 enabled vs 启用面 getActive 才查——冻结两函数分工同构）。

7 边界与异常

8 权限与数据规则

quirk：ensureSeed 每次 GET 触发（表非空即短路）；api_key 明文仍入库仅 wire 隐藏（AdminView 只消费 masked 零消费实证）；测试直连用户提供的 base_url（SSRF 面与冻结同构）；video 探测无鉴权头纯 GET 可达性。

F12.12 提示词中心（prompts 六件）

对应 PRD：§4 M12 · GET、POST /api/admin/prompts、POST /api/admin/prompts/upload、PUT、POST …/:id/activate、DELETE …/:id ｜ 状态：实现 ｜ 实现落点：admin_handlers.go:372-537、service_prompts.go:29-44/:82-175/:244-250、repo.go:393-473 ｜ UI：AdminView.vue（prompts tab——草稿保护 dataUpdatedAt 守卫面）｜ 场景挂钩：无专项 e2e（集成第十五链 PromptTemplateWiring 覆盖配置即生效）

1 功能定义

八分类提示词版本管理（分类元数据+建/传/改/激活/删；POST 缺省激活、upload 恒激活）。

2 触发条件与前置状态

六处双挂（:309 upload 额外挂 up2 2mb——全域唯一三中间件端点，对齐冻结 multer fileSize）；PUT/activate/DELETE 经 GetPromptByID → 404「版本不存在」（八态之七，三路共用）。

3 输入与校验

POST body category/name/script_type/content/activate *bool（activate !== false 缺省激活）；upload multipart 单文件 file（FormFile 失败 → 400「缺少文件」；超 2MB → 500「File too large」multer LIMIT_FILE_SIZE 信封——状态码 500 非 400；扩展名 ∈ {.txt,.md,.markdown} 否则 400「仅支持 .txt / .md 文件」）；PUT body 三 *string COALESCE；service 校验 category 八键白名单 → 400「未知的提示词分类」、content trim 空 → 400「提示词内容不能为空」。

4 处理流程

GET：ListPromptsAll（ORDER BY category, is_active DESC, created_at DESC）→ 遍历八分类（CATEGORIES=冻结 promptCenter.js:7-16 逐字）→ GetActivePrompt(key, "")（scriptType 空直落单级——三级逻辑只在 split+scriptType!="" 触发）→ count 循环。createPromptVersion 共核：name 空 → <分类名> 新版本、截 60 rune、script_type 白名单 {all,domestic,overseas} 仅 split 生效否则 ‘all’ → InsertPrompt is_active=0 → activate 则 ActivatePrompt（先全类清 0 再置 1 互斥两步，repo.go:461-467）。upload：name 缺省 regexpStripExt(originalName)（=冻结 replace(/.[^.]+$/,'')）→ 恒激活。DELETE：row.IsActive → 400「生效中的版本不可删除，请先切换其他版本」→ 删。

5 输出与结果状态

GET 键序 categories,versions；categories 元素键 key,name,desc,placeholders,scriptScoped,active,count——scriptScoped 驼峰 *bool omitempty 仅 split 有键（=JS {...c} 展开只带既有键）；versions 行键 id,name,category,script_type,content,is_active,created_at。POST {"id","activated"}；upload {"id","name"}（fixFilename 后全名含扩展名）；PUT/activate/DELETE true。无 LIMIT。

6 状态流转

prompt_templates.is_active 互斥位（每分类至多一行 1）；激活即切、旧版静默下线无确认。

7 边界与异常

8 权限与数据规则

quirk：POST 缺省激活 vs instruction POST 不激活相反默认（F12.13 交叉）；upload 恒激活（不同入口同效）；不做 in-band ensureSeed（cmd/seed 表级哨兵补种 5 行——PRD ⑧）；upload 文件全量进内存（2MB 双保险）；C1 裁决注记：本域 GetActivePrompt（整行+split 三级 repo.go:413-434）↔ 生成链 activePromptContent（content 单级+content 空视同缺失 task_assembly.go:185-200）两份刻意并存不收敛（返回形态不同+domain 不可导入 package main），两处改动须同步对拍。

F12.13 指令版本（instruction-versions 六件）

对应 PRD：§4 M12 · GET、GET /api/admin/instruction-versions/active、POST、PUT、POST …/:id/activate、DELETE …/:id ｜ 状态：实现 ｜ 实现落点：admin_handlers.go:375-451、service_prompts.go:4-77/:216-231 ｜ UI：AdminView.vue（指令版本 tab——十一续④拆解模板级联消费面）｜ 场景挂钩：无专项 e2e（集成第十五链覆盖）

1 功能定义

split 分类指令版本管理（prompt_templates category=‘split’ 薄委托——instruction_versions 死表不接线）+当前生效指令读取（三级+内置兜底）。

2 触发条件与前置状态

六处双挂+requireDB（:314 active 为静态段优先第三处）；PUT/activate 404「版本不存在」（与 prompts 同源）；DELETE 404 英文 “not found”（ErrVersionNotFoundEN——八态之八，与 prompts DELETE 的「版本不存在」刻意不同源照抄）。

3 输入与校验

GET active query script_type（缺省归 ‘all’=冻结 ||'all'）；POST body name/script_type/content（content trim 空 → 400「指令内容不能为空」）；PUT body 三 *string（无 script_type 白名单直写任意值=冻结 promptCenter.js:101 原样——与 POST 白名单不对称）。

4 处理流程

versions=ListPromptsByCategory(‘split’)；active=GetActivePrompt('split', scriptType) 三级（split+script_type → split+‘all’ → category 单级）→ ErrNoRows 兜底 {name:"内置默认", content: DefaultInstruction}（两形态响应：命中行=PromptRow 全键 / 未命中=两键）；CreateInstruction → createPromptVersion(…, false) 不激活（与 prompts POST 相反默认）；Update/Activate 与 F12.12 完全共用；DeleteInstruction 按修后语义打 prompt_templates（冻结查删 instruction_versions 死表恒 404——Go 修后：404 → IsActive 400 同文案 → 删，PRD ⑤）。

5 输出与结果状态

versions=PromptRow 数组（同 F12.12 键序）；active 两形态（行全键 ‖ {name,content} 两键）；POST {"id"}；PUT/activate/DELETE true。

6 状态流转

prompt_templates（category=‘split’）is_active 互斥位；instruction_versions 死表（service_prompts.go:4-5 注）。

7 边界与异常

8 权限与数据规则

quirk 汇总：①POST 不激活 vs prompts POST 缺省激活相反默认；②DELETE 双 404 文案分叉（EN）+400 中文保持（PRD ⑤）；③active 死端点照抄（PRD ② 前端零调用）；④PUT 无 script_type 白名单与 POST 不对称；⑤CRUD 纯存储面不接生成链（生成链内置读侧照旧——改动即生效经 GetActivePrompt 查库，service_prompts.go:6 注）。

册尾端点覆盖对账（39/39）

对账 backend/cmd/server/routes.go:275-318 亲数 39 条 ↔ 本册 F12.01~F12.13。口径脚注：M12 组注释「41 物理 admin 路由 − withdrawals 2 条归 M7」（routes.go:268-270）——冻结三文件口径 index.js admin 段 17（app.* 直挂非 router）+ llmroutes.js 18 + routes2.js 4 = 39，冻结-Go 计数自洽无 m10 式错位；withdrawals 2 条（routes.go:150-151）与 submissions 2 条（:199-200）物理不在本段，归 M7/M9。

差异纪律：PRD §4 M12 ①~⑨ 全引用不重立（含二十一期② api_key 收敛/⑥ release 认领前置+retry-split 修后/⑤ DELETE 修后语义/③ ErrNoUser 吞形/② 死端点/⑧ ensureSeed 缺位）；本册新立 DIF-31-3（布尔 wire 型 enabled/active/is_active/refunded Go true/false vs 冻结 SQLite 0/1——方言级六节波及）/DIF-31-4（bind 严格性：冻结 +credits/+amount/truthy 宽收数值字符串 vs Go int64 bind 400「请求体格式错误」——F12.02/04，m08 下单 amount_cny 同型扩域）/DIF-31-5（PUT settings 非标量值字符串化 fmt.Sprint(map) vs JS "[object Object]"）/DIF-31-6（upload 点文件名 .md 形态 regexpStripExt 保留 vs JS 正则清空走缺省名）入 99-附录 B。

4.5 - FSD M13 · 火花计划

← 总则 ｜ 附录 → ｜ 上游：PRD §4 M13 实现落点：backend/internal/domain/spark/（model/service/repo_gorp 三件）+ cmd/server/spark_handlers.go（34 行）+ cmd/server/routes.go:259-262（挂载——物理嵌在 M11 段 :258 与 :263 之间）。事实基准=Go 代码；冻结版 qmtv/server/index.js:739-766 仅差异对拍参照。 域内要点：二十六期补登域（P0 统计残留第八例——冻结 index.js:739-766 两条端点从未入任何模块行）；三阶梯 tier 表单数据源（per 系）；PRD §4 M13「逐字对齐无差异」——三十期新立 DIF-30（见 m09 册/99-附录 B）。E2E-SPK-01 已实现（spark.spec.ts，清单 :15）。

M13 火花计划

2 端点全量（join+me）。零 provider 零 SSE；通知一发（join 成功）；扣费面为零（唯一 Add 奖励面——反向 credits 流转）。

F13.01 火花计划（spark/join + spark/me）

对应 PRD：§4 M13 · POST /api/spark/join、GET /api/spark/me ｜ 状态：实现 ｜ 实现落点：spark_handlers.go:13-34、service.go:33-86、model.go:13-46、repo_gorp.go ｜ UI：SparkView（三阶梯卡片+加入按钮）｜ 场景挂钩：E2E-SPK-01（已实现——重跑容错：残留轮直断投影面）

1 功能定义

编剧激励计划：一次性加入（+100 奖励）与个人阶梯投影（按 published 过审数定档）。

2 触发条件与前置状态

join：未加入前置——重复 400「您已加入火花计划」（ErrAlreadyJoined model.go:10，errRespond 400 映射，冻结 :749 同形）；me：零前置（joined=false 也给完整阶梯投影，quirk）。

3 输入与校验

两端点无 body/参数（全按 token user_id）。

4 处理流程（join 四动作禁事务）

置位 users.spark_joined → credits.Add(+100, type='spark', 「加入火花计划奖励（+100）」)（service.go:44，冻结 :751 同形）→ INSERT notifications「火花计划报名成功」→ 响应 {joined: true, bonus: 100}——四动作逐序无事务（:33-53，中途失败留半态=冻结无事务同形）。 me：total=submissions 非 draft 计数（repo_gorp.go:50-56）/published/pending 双计数 → tierOf(published) 定档（0 部无命中回退首档星火，model.go:51-58）→ next_tier 环形取下一档（tierTable[(idx+1)%len]，service.go:84——燎原下一档回星火，冻结 :766 同式）。

5 输出与结果状态

me 键序逐字（model.go:34-46，冻结 :762-766）：joined/total/published/pending/tier/tier_perk/tier_rate/reward_earned/next_tier/tiers——reward_earned=published×per 即时计算（非累计流水）；tiers=三档全量数组（min/max/per/name/perk，max *int null=无上限）。

6 状态流转

spark_joined 0→1 单向（无退出机制）；阶梯随 published 增长单向升级（E2E-SUB-01 投稿过审联动）。

7 边界与异常

8 权限与数据规则

authed + amw；Add 奖励走 credits 唯一入账口（ErrNoUser 容错装配侧）；零扣费零退款（全站唯一纯奖励域）；wire 全蛇形零驼峰（model.go 亲证）。

册尾端点覆盖对账（2/2）

对账 backend/cmd/server/routes.go:259-262 亲数 2 条 ↔ 本册 F13.01：

差异纪律：PRD §4 M13「逐字对齐无差异」——本册零差异零新立 DIF（bonus/per 不同源与 0 部回退均系双方一致 quirk，节内登记）；集成锚 SparkChain 第十六链（me 初态→join 对账→重复 400→submissions 直插阶梯联动→401）在位。

4.6 - FSD M2 · 任务与拆解

← 总则 ｜ 附录 → ｜ 上游：PRD §4 M2 实现落点：backend/internal/domain/task/（model/repo/service/service_gen）+ cmd/server/task_handlers.go（38 handlers 全集）+ cmd/server/task_assembly.go（LLM/模板装配）+ cmd/server/routes.go:324-361（挂载）。事实基准=Go 代码；冻结版 qmtv/server/index.js:228-366/routes2.js/routes3.js 仅差异对拍参照。

M2 任务与拆解

38 端点全量（基础信封见总则 §2.2）。本域是创作主链的起点：剧本 → 拆解（规则/LLM 双引擎）→ 场景/分镜 → 资产提取与生图。计费面集中在拆解（token 制/按次 20）与图片生成（动态价）；SSE 仅 split 一类事件；上传面 2 条（slots/assets，20MB）。属主判定全 SQL 谓词，命中失败一律 404 不用 403。分镜双表通路中本域只写 shots（director_shots 归 M10，零触及）。

F2.01 任务列表

对应 PRD：§4 M2 · GET /api/tasks ｜ 状态：实现 ｜ 实现落点：task_handlers.go:51-56、task/repo.go:120-125 ｜ UI：/dashboard（DashboardView 任务列表）｜ 场景挂钩：E2E-DASH-01（A1 回归锁：wire=驼峰 shotCount）/E2E-NAV-01

1 功能定义

当前用户任务列表倒序读，每行附镜数（shotCount 驼峰 wire——二十六期 A1 回归根因，e2e 回归锁钉死）。

2 触发条件与前置状态

• 进入拆解台/任务列表刷新 → GET /api/tasks（Bearer）；降级模式 503。

3 输入与校验

无参数。身份取自 JWT claims。

4 处理流程

SELECT t.*, (子查询 COUNT shots) AS shot_count … WHERE t.user_id=? ORDER BY t.created_at DESC → TaskWithCount 数组。宽扫描 t.* 依赖 0002 DDL 收紧（W8b 守卫 integration_test.go:461-484）。

5 输出与结果状态

200 {"ok":true,"data":[TaskWithCount…]}。行 wire：id/user_id/title/status/error/script_type/face_style/min_duration/max_duration/notes/extract_status/assets_data/split_status/style_id/extract_scope/extract_notes/created_at/updated_at（蛇形）+ shotCount（驼峰，model.go:60-63）；script_text 指针 nil→JSON null。空列表 data:null（gorp nil slice——冻结恒 []，DIF-29-1）。

6 状态流转

无（纯读）。status 取值域见 F2.03 §6。

7 边界与异常

8 权限与数据规则

• 权限：登录态；WHERE user_id=? 谓词内联。
• 数据规则：倒序 created_at DESC（无次级排序键，同秒行序可能抖动——冻结同构）。

F2.02 剧本拆解·旧版同步

对应 PRD：§4 M2 · POST /api/tasks ｜ 状态：实现 ｜ 实现落点：task_handlers.go:62-82、task/service.go:148-167/301-327 ｜ UI：拆解台旧版提交入口｜ 场景挂钩：无（V2 为主链，本端点为冻结 legacy 保真）

1 功能定义

同步规则拆解：扣固定 20 积分 → 确定性 preprocess 切分场次/分镜/资产 → 立即返回统计。无 LLM、无异步。

2 触发条件与前置状态

• 拆解台提交（legacy 形态）→ POST /api/tasks（Bearer）。

3 输入与校验

4 处理流程

flowchart TD
  A["POST /tasks"] --> B["剧本非空校验"]
  B --> C["TryDeduct 20<br/>type=preprocess<br/>「剧本拆解：<title>（-20）」"]
  C -->|不足| D["402 积分不足"]
  C --> E["INSERT tasks status=complete"]
  E --> F["fillWithMock：preprocess 确定性切分"]
  F --> G["InsertAssets + InsertShots + 每镜 slot1 故事板"]
  G --> H["200 {id,sceneCount,shotCount}"]

扣费在插任务前，Insert 失败不退（service.go:159-163，冻结同序）。三次 Insert 均 _ = 吞错（service.go:314/318/324）。INSERT 显式写 18 列零值（script_type:''/min_duration:0/split_status:'' 等覆盖 DDL 默认——冻结走 SQLite DEFAULT，DIF-29-5）。

5 输出与结果状态

200 {"ok":true,"data":{"id","sceneCount","shotCount"}}（sceneCount/shotCount 驼峰，task_handlers.go:77-81；冻结 index.js:252 同）。

6 状态流转

tasks.status：插入即 'complete'（无 processing 中间态）；split_status：INSERT 显式写 ''（18 列零值，DIF-29-5——非 DDL 默认 'done'）；本端点不消费该列。

7 边界与异常

8 权限与数据规则

• 权限：登录态；创建即本人（user_id 取 claims）。
• 数据规则：写 tasks/shots/assets/shot_images/credit_records 五表。

F2.03 剧本拆解·V2 双引擎

对应 PRD：§4 M2 · POST /api/tasks/v2 ｜ 状态：实现 ｜ 实现落点：task_handlers.go:140-160、task/service.go:241-299/330-366 ｜ UI：拆解台主提交（DashboardView）｜ 场景挂钩：E2E-DASH-01（Mock 同步分支：toast「拆解完成」+镜数>0）

1 功能定义

token 制计费的剧本拆分：LLM 可用走异步拆解（SSE split 事件+站内通知，失败回退规则拆解）；LLM 不可用走规则拆解同步返回。计费 ceil(tokens/1000) 上限 1。

2 触发条件与前置状态

• 拆解台提交（主链）→ POST /api/tasks/v2（Bearer）。
• LLM 可用判定 llm.Config.Available()（三元全非空，llm.go:24）；配置三级链 active_model_text→model_endpoints→KV llm_*（task_assembly.go:49-59）。

3 输入与校验

4 处理流程

flowchart TD
  A["POST /tasks/v2"] --> B["剧本非空校验"]
  B --> C["token 估算：max(1000, ceil(rune数×1.6))<br/>cost=ceil(est/tokensPerCredit) <1 归 1"]
  C --> D["TryDeduct type=preprocess task_id=id<br/>「剧本拆分（约N tokens / 模型名，-cost）」"]
  D --> E["INSERT tasks status=processing<br/>split_status= llm可用?processing:done"]
  E --> F{"llm.Available()?"}
  F -->|否| G["fillWithMock + status=complete<br/>同步返回 sceneCount/shotCount"]
  F -->|是| H["go runLLMSplit（异步）<br/>响应 {id,async:true,engine,cost,tokens_estimated}"]
  H --> I["SplitTemplate 三级 → LLM Chat 240s → ParseSplit"]
  I -->|成功| J["三删重建 shots/assets + slot1<br/>SetSplitDone + 通知「剧本拆解完成」+ SSE split done"]
  I -->|失败| K["fallbackMock：三删+fillWithMock+SetSplitDone+complete<br/>通知「AI 拆解失败，已回退规则拆解」+ SSE split fallback"]
  K -->|回退也失败| L["status=failed + split_status=failed"]

runLLMSplit 后台 goroutine defer recover() 兜底（service.go:332）；重建三删序 ClearShotImages→DeleteShotsByTask→DeleteRootAssetsByTask（service.go:411-419）。

5 输出与结果状态

V2Result 键序 id, sceneCount(omitempty), shotCount(omitempty), async, engine, cost, tokens_estimated（service.go:243-251）：LLM 分支无 sceneCount/shotCount 键（冻结同）；Mock 分支 async:false + 两计数。

6 状态流转

• tasks.status：processing（仅本端点插入）→ complete（Mock/LLM 完成/回退成功/restart/启动恢复）｜failed（LLM 双重失败、mark-failed）。
• tasks.split_status：DDL 默认 'done'｜'processing'（LLM 可用）→ 'done'（完成/回退）｜'failed'（双重失败）。代码无 'idle'/'fallback' 写入点（PRD :142 状态机表含此二态——PRD 该行已加注「冻结与 Go 均无写入点」，用户裁决〔三十期〕判定非系统需要不实现：前端零消费〔DashboardView 仅认 processing/failed〕+fallback 系同步内联回退无可观察窗口，勿照抄亦勿实现）。
• 服务重启悬挂行：RecoverProcessingSplits（service.go:444-463）扫 split_status='processing' → fillWithMock 直插不删基座 → 恢复完成，通知「拆解已回退完成」，无 SSE 帧。

7 边界与异常

8 权限与数据规则

• 权限：登录态；写 tasks/shots/assets/shot_images/credit_records/notifications。
• 数据规则：TryDeduct 带 task_id=id（冻结 routes2.js:158 同）；通知两文案冻结逐字（service.go:352-353/359-361）。

F2.04 任务详情读取（:id / full / full2）

对应 PRD：§4 M2 · GET /api/tasks/:id、GET /api/tasks/:id/full、GET /api/tasks/:id/full2 ｜ 状态：实现 ｜ 实现落点：task_handlers.go:84-97/275-297、service_gen.go:300-427 ｜ UI：VideoView/DashboardView 任务详情｜ 场景挂钩：E2E-NAV-01（读面巡检）

1 功能定义

任务详情三形态：基础（shots+原始 assets）、full（assets 带图 URL+assets_data 缓存）、full2（variants 衍生体+风格名/缩略图+组间尾帧衔接）。

2 触发条件与前置状态

• 详情页/分镜工作台加载 → 三端点（Bearer）；任务不存在或非本人 → 404。

3 输入与校验

路径 :id。无 body。

4 处理流程

• :id：ByID（WHERE id=? AND user_id=?）→ ShotsWithSlots（shots ORDER index_no + 槽位按 shot 分组 ORDER slot_no + refAssetCount=COUNT assets）→ 原始 assets（无 image_url，task_handlers.go:95——冻结 index.js:261 同 quirk）。
• full：ByID → ShotsWithSlots → AssetsByTask（LEFT JOIN images 取 image_url）→ assets_data=缓存优先（坏 JSON 宽容 nil）否则从根资产现拼（5 键 item：id/name/description/image_id/image_url——冻结塞原始全列行，DIF-29-16）。
• full2：再加 VariantsByTask（parent_id<>’’）合并进缓存/fallback；tail_by_group 组间尾帧 map（组内最后有图镜 image_id，首镜且 groupNo>1 配 prev_tail_image_id，service_gen.go:355-372）；style_name=StyleName（19 风格目录缺省「真人电影」）、style_thumb 幂等落盘 style_<id>.svg（不在目录→null）。

5 输出与结果状态

• :id → {"task","shots":[ShotView],"assets":[原始行]}；shots 空为 []（make 初始化）、slots/assets 空 null（DIF-29-1）。
• full → {"task","shots","assets","assets_data"}。
• full2 → {"task":{…Task,"style_name","style_thumb"},"shots","assets","variants","assets_data","tail_by_group"}——style_name 嵌套在 task 内（前端 curTask.style_name 消费）。

6 状态流转

无（纯读）。

7 边界与异常

8 权限与数据规则

• 权限：登录态 + 任务属主。
• 数据规则：ShotView 含 slots/refAssetCount（驼峰）/prev_tail_image_id（full2 组首镜）；variants 键映射 parent_id→item 数组。

F2.05 任务生命周期管理（title/delete/duplicate/mark-failed/restart）

对应 PRD：§4 M2 · PUT /api/tasks/:id/title、DELETE /api/tasks/:id、POST /api/tasks/:id/duplicate、POST /api/tasks/:id/mark-failed、POST /api/tasks/:id/restart ｜ 状态：实现 ｜ 实现落点：task_handlers.go:99-138、task/service.go:168-230/583-587、task/repo.go:146-175/234-248 ｜ UI：任务卡操作菜单｜ 场景挂钩：无独立 e2e

1 功能定义

任务五个管理动作：改名、删除（三删序+孤儿保留）、复制（含分镜/资产快照）、标记失败、重启清图。

2 触发条件与前置状态

• 任务卡操作 → 对应端点（Bearer）；title/delete/duplicate 404 面，mark-failed 无存在性检查。

3 输入与校验

4 处理流程

• title：UPDATE tasks SET title=?, updated_at=NOW(3) WHERE id=? AND user_id=?。
• delete：三删序 shots→assets→tasks（子查询属主谓词）；不删 shot_images/image_histories/images/videos（孤儿保留，repo.go:151 注释冻结 §1A）。
• duplicate：新任务 title=原题+"-副本" 截 60（DIF-29-10），status/script_text 沿源（nil 透传）；逐镜复制（image_id/video_id 清空）；仅复制源镜存在 slot_no=1 的槽位（service.go:200-204，冻结每镜无条件插——DIF-29-10）；assets 全复制但 parent_id 不带（衍生变根资产，冻结 index.js:290-292 同 quirk）。
• mark-failed：UPDATE tasks SET status='failed'；不触 split_status。
• restart：RestartClears 四步——shots.image_id=’’+status=‘idle’、shot_images.image_id=’’、tasks status=‘complete’+extract_status=’’+assets_data=’’、assets.image_id=’’；保留 shots/assets/槽位行（NULL 语义翻译 ‘’，model.go:4-5）。

5 输出与结果状态

五者均 {"ok":true,"data":true}；duplicate 另返 {"id":"<新任务>"}。

6 状态流转

• delete：行删除（级联仅 shots/assets 两层）。
• mark-failed：complete|processing → failed。
• restart：任意 → complete；shots done → idle；extract_status → ''。

7 边界与异常

8 权限与数据规则

• 权限：登录态；delete/duplicate/restart 谓词内联属主。
• 数据规则：restart 是「清成果不删结构」语义——与 delete（删结构留孤儿）互补。

F2.06 智能资产提取（extract / extract2 / extract-settings）

对应 PRD：§4 M2 · POST /api/tasks/:id/assets/extract、POST /api/tasks/:id/assets/extract2、PUT /api/tasks/:id/extract-settings ｜ 状态：实现 ｜ 实现落点：task_handlers.go:174-208、service_gen.go:34-159 ｜ UI：拆解台资产区「智能提取」｜ 场景挂钩：无 e2e（人工清单 T2 族）

1 功能定义

对拆解产出的角色/场景/道具资产批量生图：v1 按资产类型模板出图并写 assets_data 缓存；v2 支持 scope 范围+自定义要求+风格前缀；extract-settings 持久化提取范围与要求。

2 触发条件与前置状态

• 资产区按钮 → extract/extract2（Bearer）；设置面板保存 → extract-settings。前置：任务已有资产行。

3 输入与校验

4 处理流程

flowchart TD
  A["POST /assets/extract(2)"] --> B["ByID 属主 404 面"]
  B --> C{"有资产?"}
  C -->|否| D["400"]
  C --> E["先 UpdateExtractResult done,''"]
  E --> F["逐资产：AssetPrompt 模板+风格前缀（v2）"]
  F --> G["images.Generate（Mock SVG/真实通道）"]
  G -->|单张失败| H["退单价 + 502 文案"]
  G -->|成功| I["InsertImage kind=asset + UpdateAssetImage"]
  I --> J["UpdateExtractResult done, assets_data JSON"]

• 计费：unit=ImageCost（settings image_generation 默认 10）；v1 cost=unit×资产数（含衍生体），desc 智能资产提取（N 个资产 × 10，-<cost>）；v2 cost 同式，desc 智能资产提取 ×N（风格：<风格名>，-<cost>）；type=image。
• v2 prompt=「视觉风格：<风格名>。」+AssetPrompt+（ExtractNotes?\n[生成要求] <notes>）。
• v1 失败 502 文案金额用总额（冻结 v1 用单价——退款金额本身正确，DIF-29-2）；v2 失败退全额（冻结 v2 传总额笔误的保真对齐，service_gen.go:121-123 注释）。

5 输出与结果状态

{"extract_status":"done","assets_data":{"characters":[],"scenes":[],"props":[]}}；item 键 id/name/description/image_id/image_url/prompt——v2 冻结显式带 variants:[]，Go omitempty 键缺失（DIF-29-3）。

6 状态流转

tasks.extract_status：'' → 'done'（成功路径先行置位，失败不回滚——下次重试覆盖）；assets_data 缓存同步覆盖。

7 边界与异常

8 权限与数据规则

• 权限：登录态+任务属主；写 images/assets/tasks/credit_records。
• 数据规则：v2 targets=根资产（parent_id=’’）∩scope；衍生体在 v1 中也计费（含衍生体）。

F2.07 AI 重新拆解（resplit）

对应 PRD：§4 M2 · POST /api/tasks/:id/resplit ｜ 状态：实现 ｜ 实现落点：task_handlers.go:514-533、service.go:488-573 ｜ UI：分镜区「AI 重新拆解」｜ 场景挂钩：无 e2e

1 功能定义

按自然语言指令对已有分镜做密度调整重切：更多/细致/丰富→每场 5 镜、精简/减少/合并→每场 2 镜、缺省 3~4；固定扣 20 积分。

2 触发条件与前置状态

• 分镜区操作 → POST /api/tasks/:id/resplit（Bearer）；前置：任务存在（不要求 complete）。

3 输入与校验

4 处理流程

ByID → 扣 20（desc AI 重新拆解（<instruction截16>）（-20），空指令 AI 重新拆解（-20），type=preprocess）→ 三删重建（同 F2.03）→ preprocess 密度调参重切 → 重插 shots（每组首镜 independent 余 anchor_prev）+slot1 → SetSplitInstruction（存 trim 值）。

5 输出与结果状态

{"instruction","sceneCount","shotCount"}——instruction 回显的是请求原始值非 trim 值（task_handlers.go:524-532；冻结回显 trim 后值，DIF-29-8）。

6 状态流转

shots 全量重建（id 全新）；split_instruction 列更新；status/split_status 不变。

7 边界与异常

8 权限与数据规则

• 权限：登录态+属主；写 shots/shot_images/tasks/credit_records。

F2.08 分镜图批量与续生成（continue / auto-generate / cancel / storyboard-batch）

对应 PRD：§4 M2 · POST /api/tasks/:id/continue、POST /api/tasks/:id/scenes/auto-generate、POST /api/tasks/:id/scenes/auto-generate/cancel、POST /api/tasks/:id/storyboard-batch ｜ 状态：实现 ｜ 实现落点：task_handlers.go:299-334/346-357/535-553、service.go:590-703、service_gen.go:634-695 ｜ UI：分镜区批量操作｜ 场景挂钩：无 e2e（人工清单 T2/T3 族）

1 功能定义

四个批量/续生成入口：continue 补缺图镜、auto-generate 带连续性提示词串联生成、cancel 纯 stub 停止提示、storyboard-batch 按模式（全部/补缺/选中）批量生图。

2 触发条件与前置状态

• 分镜区批量按钮 → 对应端点（Bearer）。

3 输入与校验

4 处理流程

• continue：pending=缺图镜（image_id=’’/NULL）→ cost=unit×len（desc 继续生成未完成分镜 ×N（-<cost>））→ 逐镜 Generate(“16:9”,“分镜<index_no>”) → settleShotImage（InsertImage kind=storyboard+SetShotImage done+slot1 回填+InsertHistory）。
• auto-generate：list=pending 空则全量镜；prompt 追加连续性段——非首镜 \n[连续性] 与上一镜头（<prevURL||前帧>）保持人物/光影/机位连续。、首镜 \n[起始镜头] 由智能体判断开场构图。；desc 故事板全自动串联生成 ×N（-<cost>）。
• cancel：{"cancelled":true,"note":"已停止后续镜头的排队（已产生的费用不退）"}，不写任何表。
• storyboard-batch：desc 批量生图（全部|仅补缺失|选中 ×N，-<cost>）；连续性措辞与 auto-generate 不同源（「与上一镜（<prevURL||前帧>）保持一致。」/首镜「智能体判断开场构图」）；失败退单价（冻结传总额系笔误，Go 统一单价——PRD v1.3 已登记，service_gen.go:632-633）。

settle 失败（DB 错）时该张已生成不退费、仅 failed++（service.go:616-619/689-694，冻结同）。

5 输出与结果状态

continue/auto-generate/storyboard-batch → {"generated":N,"failed":N}；cancel → 上述 stub 体。

6 状态流转

成功镜：shots.status idle → done（SetShotImage）；失败镜 status 不动（仅计数）。

7 边界与异常

8 权限与数据规则

• 权限：登录态+属主；写 images/shots/shot_images/image_histories/credit_records。
• 数据规则：三批量端点计价均为动态 unit（settings 可调）——与 F2.09 的静态价不同源。

F2.09 单镜故事板生成（images/storyboard/generate）

对应 PRD：§4 M2 · POST /api/images/storyboard/generate（v1.3 W10 归组 M2——物理在冻结 index.js 生成段）｜ 状态：实现 ｜ 实现落点：task_handlers.go:420-441、service_gen.go:581-623 ｜ UI：分镜卡「生成」/「2K 预览」｜ 场景挂钩：间接 E2E-NAV-01

1 功能定义

单镜故事板图/2K 预览生成：静态价（图 10/预览 15，无 settings 键），可选关联 shot 回填。

2 触发条件与前置状态

• 分镜卡生成按钮 → POST /api/images/storyboard/generate（Bearer）。

3 输入与校验

4 处理流程

计费 cost=10（COSTS.image）/15（COSTS.image_2k 恒定无 settings 键，billing.go:72-73）；kind=‘storyboard’/‘preview_2k’；desc 分镜图生成（-10）／2K预览（-15）（冻结「2K预览生成（-15）」缺「生成」二字，DIF-29-9）；task_id=shot 有则其 task 否则 ‘’。Generate → 失败退同额+502；成功 InsertImage（prompt=请求原值非解析值）→ sh != nil && !preview 才回填 shots/slot1/histories（linkShotImage 不重复插 images——W3 冒烟双插主键冲突修，service_gen.go:615-621 注释）。

5 输出与结果状态

{"id","url"}。

6 状态流转

关联 shot 非预览时：shots.status → done、slot1 回填、histories +1。

7 边界与异常

8 权限与数据规则

• 权限：登录态；shot 关联时校验属主。
• 数据规则：静态价与 F2.08 动态价刻意不同源（billing.go:72-73 注释）；Mock label=desc 全串（冻结 label「分镜图」/「2K预览」——影响 Mock SVG 文件名，DIF-29-9）。

F2.10 场景分组管理（scenes2 / rename / delete）

对应 PRD：§4 M2 · GET /api/tasks/:id/scenes2、PUT /api/tasks/:id/scenes/:groupNo、DELETE /api/tasks/:id/scenes/:groupNo ｜ 状态：实现 ｜ 实现落点：task_handlers.go:472-512、repo.go:356-371 ｜ UI：分镜区场景分组栏｜ 场景挂钩：无 e2e

1 功能定义

场景分组聚合读与改名/删除：scenes2 按 group_no 聚合统计，rename/delete 按 group_no 批量作用。

2 触发条件与前置状态

• 分镜区场景栏 → 三端点（Bearer）。

3 输入与校验

4 处理流程

• scenes2：SELECT group_no, MIN(scene_title), COUNT(*) shot_count, MIN(index_no) first_index … GROUP BY group_no ORDER BY group_no（MIN(scene_title) 字典序最小而非首镜标题——冻结同 SQL quirk 保真）。
• rename：UPDATE shots SET scene_title=? WHERE task_id=? AND group_no=?。
• delete：DELETE FROM shots WHERE task_id=? AND group_no=?。

5 输出与结果状态

scenes2 → [{"group_no","scene_title","shot_count","first_index"}]（全蛇形，空→null DIF-29-1）；rename/delete → data true。

6 状态流转

delete 组删除后 shots 行消失（槽位/histories 孤儿保留）。

7 边界与异常

8 权限与数据规则

• 权限：登录态+属主（task_id 谓词）。

F2.11 分镜编辑与槽位（shots / slots / shot-images / histories / shots2）

对应 PRD：§4 M2 · PUT /api/shots/:id、DELETE /api/shots/:id、POST /api/shots/:id/slots、DELETE /api/shot-images/:slotId、GET /api/shots/:id/histories、PUT /api/shots2/:id/params ｜ 状态：实现 ｜ 实现落点：task_handlers.go:359-470、service.go:492-501/570-578、service_gen.go:504-559、repo.go:322-354/408-437/465-470 ｜ UI：分镜卡编辑器｜ 场景挂钩：无独立 e2e

1 功能定义

单镜六动作：三提示词编辑、删除、参考槽位添加（上传或生图）、槽位删除（slot1 保护）、历史读、分辨率参数。

2 触发条件与前置状态

• 分镜卡操作 → 六端点（Bearer）；slots 上传限额 20MB（up20）。

3 输入与校验

4 处理流程

• slots 双路：有文件→images.Upload 零费；无文件→静态价 10（desc 镜头图片生成（-10），task_id=’’）→Generate→失败退+502。成功：slotNo=MAX(slot_no)+1、InsertImage(kind=orDefault(kind,“anchor”))、InsertShotImages(label=orDefault(label,“参考图”))；生成路另 SetShotImage(done)+InsertHistory（_ = 吞错）。
• shotOwned（service.go:492-501）：ShotByID err→ErrShotNotFound；task 属主 err→同——两步均 404 shot not found。

5 输出与结果状态

• slots → {"slot_no":int,"image_id","url"}；histories → [{"id","shot_id","image_id","prompt","created_at","file_path"}]（空→null DIF-29-1）；其余 data true。

6 状态流转

• 生图路 slots/SetShotImage：shots.status → done。
• params：resolution 列更新（白名单内才生效）。

7 边界与异常

8 权限与数据规则

• 权限：登录态+shot→task 属主链。
• 数据规则：本域写 images 表为跨域共表直插（10 列形态，repo.go:551-556，主归属 generation——总则 §1 术语）；histories 行 id 前缀 si_（冻结 ih_；ids.PrefixImageHistory=“ih_” 仅 director 域消费（repo.go:319 InsertImageHistory），前缀双轨并存——DIF-29-4，99-附录:57）。

F2.12 资产图编辑与衍生（assets upload / regenerate / derive）

对应 PRD：§4 M2 · POST /api/assets/:id/image/upload、POST /api/assets/:id/regenerate、POST /api/assets/:id/derive ｜ 状态：实现 ｜ 实现落点：task_handlers.go:213-272、service_gen.go:162-276 ｜ UI：资产卡操作｜ 场景挂钩：无 e2e

1 功能定义

资产图三动作：手动上传替换（同步 assets_data 缓存）、局部修改生图、衍生变体（新建子资产行）。

2 触发条件与前置状态

• 资产卡操作 → 三端点（Bearer）；upload 限额 20MB。

3 输入与校验

4 处理流程

• upload：AssetByID（JOIN tasks 属主）→ Upload（FixFilename）→ InsertImage(kind=‘asset’) → UpdateAssetImage → 同步 assets_data 缓存（读改写 JSON 三组逐项改 image_id/image_url，坏 JSON 静默跳过）。
• regenerate：扣 unit（desc 资产图局部编辑：<名>（-<unit>））→ prompt=AssetPrompt+\n[局部修改] <ins>（其余部分保持原图不变） → Generate → 失败退+502 → InsertImage(kind=‘asset_edit’) → UpdateAssetImage（不写缓存，冻结同）。
• derive：扣 unit（desc 角色衍生：<名>·<variant截12>（-<unit>））→ 先插子资产行（name=<名>_衍生<N>，parent_id=源）→ prompt=AssetPrompt+\n[衍生变体] <v>。保持角色五官与身份一致，仅按描述改变形态。视觉风格：<风格名>。 → Generate → 失败退+502（子资产行残留无回滚——冻结同序 routes3.js:170-172）→ InsertImage(kind=‘asset_variant’) → UpdateAssetImage(子)。

5 输出与结果状态

upload/regenerate → {"image_id","url"}；derive → {"asset_id","image_id","url","name"}。

6 状态流转

• derive：assets 树新增子节点（parent_id 链）。
• upload：assets.image_id 替换+缓存同步；regenerate 仅替换 image_id。

7 边界与异常

8 权限与数据规则

• 权限：登录态+资产→任务属主链（AssetByID JOIN tasks）。
• 数据规则：FixFilename 处理中文文件名（总则坑表）；缓存同步只覆盖命中的 name 项。

F2.13 任务台账与资产库（credit-records / library-apply / asset-library）

对应 PRD：§4 M2 · GET /api/tasks/:id/credit-records、POST /api/tasks/:id/library-apply/:libId、GET/POST /api/asset-library、POST /api/asset-library/:id/share、DELETE /api/asset-library/:id ｜ 状态：实现 ｜ 实现落点：task_handlers.go:555-631、service_gen.go:705-764、repo.go:569-605 ｜ UI：任务详情台账页/素材库页｜ 场景挂钩：E2E-CRD-01（台账键形同源 credits.Record）

1 功能定义

任务维度台账对账读（LIMIT 200+汇总）、资产库条目应用到任务、素材库个人/组织共享 CRUD。

2 触发条件与前置状态

• 任务详情台账 tab → credit-records；素材库页 → asset-library 四动作；「应用到任务」→ library-apply。

3 输入与校验

4 处理流程

• credit-records：credits.RecordsByTask（LIMIT 200 ORDER created_at DESC,id DESC）+ 汇总（负额和+by_type 分组，service.go:79-93）。
• library-apply：双 404 面 → InsertAssets（desc=lib.Description+（来自资产库），image_id 沿库）。
• asset-library 列表：(l.user_id=? OR (org_shared=1 AND l.user_id IN (SELECT id FROM users WHERE org_id=?))) ORDER created_at DESC LIMIT 200 JOIN users 取 owner_email（共享子查询走 users.org_id 单组织模型——冻结 org_members 双向 JOIN，语义等价登记 repo.go:574）。
• share：翻转 org_shared → 返回 {"org_shared":0|1}（整数）。

5 输出与结果状态

• credit-records → {"list":[Record…],"summary":{"total_spent","by_type"},"task_title"}；Record wire id,user_id,task_id,amount,balance_after,type,description,created_at（task_id NULL 行 wire “"）。
• asset-library → [LibraryView…]（+owner_email，空→null DIF-29-1）；add → {"id"}；apply → {"asset_id"}。

6 状态流转

• library-apply：assets 表新增行（任务下）。
• share：org_shared 0⇄1 翻转。

7 边界与异常

8 权限与数据规则

• 权限：登录态；asset-library 写面全部 user_id=? 谓词（share 的组织可见性靠 org_shared 列+列表子查询）。
• 数据规则：台账读面与 M1 F1.06 全局流水同源 credits 域；LIMIT 200。

M2 端点覆盖对账