QMTV 产品文档

00 · 交接导览（先读我）

Mon, 01 Jan 0001 00:00:00 +0000

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

项目速览卡

项	值
项目名	QMTV — AI 短剧智能生产线
位置	`D:\WORK\GAE\qmtv`（本目录）
技术栈	Node.js 22 + Express 5 + better-sqlite3（后端）；Vue 3 + Vue Router 4 + Vite 8（前端）；无 UI 框架，自研主题
启动	`npm install` → `npm start`（后端 :3300 并托管前端 dist）→ `npm run build`（构建前端）
数据库	`data/qmtv.db`（SQLite WAL，49 张表，免安装）
规模	后端 24 个模块 / 5436 行，239 个 API；前端 24 个页面 / 约 9000 行
设计文档（历史全量）	`D:\WORK\GAE\QMTV网站设计文档.md`（22 节，按 v1→v22 版本演进记录每一步设计决策与实测结论）

文档地图

文档	内容	什么时候读
01-系统设计方案.md	产品定位、功能全景、各模块设计方案、数据模型、计费模型、AI 链路设计、视觉体系	想理解"为什么这样设计"
02-系统架构介绍.md	技术栈、目录结构、后端模块职责、前端结构、49 张表清单、关键机制（SSE/供应商适配/启动恢复）、构建部署	想理解"代码怎么组织的"
03-系统开发说明.md	环境准备、启动步骤、账号、日常开发操作指南（加页面/加接口/加表）、验证方法、踩坑清单、运维注意	动手开发前必读
04-待开发功能与规划.md	真实模型接入清单、已知欠账与改进项、建议优先级	排后续开发计划
05-API接口速查手册.md	全部 239 个 API 按模块分组	写代码时当字典查

30 分钟上手路径

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

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

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

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

Mon, 01 Jan 0001 00:00:00 +0000

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

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

Mon, 01 Jan 0001 00:00:00 +0000

本手册面向 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 场景清单(自动化覆盖地图)。

QMTV E2E 测试约定

Mon, 01 Jan 0001 00:00:00 +0000

二十六期（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 水位会漂移）。

明令禁止

禁 sleep 等待 UI 条件——唯一合法等待面是 Playwright 自动等待/expect.poll/waitForEvent/pollUntil。豁免两处（登记）：①巡检类用例的路由间静置窗口（nav/admin 的 waitForTimeout(400/1500)、snapshots 截图前 waitForTimeout(800)——错误收集窗/渲染落定窗，非断言等待）；②截图前 networkidle。
禁 retry——config retries: 0（pms flaky 规则：禁 retry 掩盖；修复优先序改等待>改定位>改断言>最后才是 retry）。
禁断全局计数/绝对余额——流水断言用 total 相对面 + 最新行身份；余额用 assertBal 恒等式（后端集成侧）。
禁触 qmtv_main / pms_ / sw_main*——e2e 只操作 qmtv_e2e 单库（远程 139 共享实例纪律平移）。
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、充值审核、分销提现等）先登清单「待实现」行，后续期次升格。

QMTV 移植契约规格（PRD）v1

Mon, 01 Jan 0001 00:00:00 +0000

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

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

Mon, 01 Jan 0001 00:00:00 +0000

自动化升格映射(场景 → 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 存在/台账行/状态翻转):页面交互流、视觉布局、文案细节、跨页联动仍需按下表人工执行。

01 · 系统设计方案

Mon, 01 Jan 0001 00:00:00 +0000

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

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

Mon, 01 Jan 0001 00:00:00 +0000

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

QMTV 使用手册 · 文档索引

Mon, 01 Jan 0001 00:00:00 +0000

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

文件	读者	用途
QMTV使用说明书_中文.md	工作台用户/企业管理员/平台管理员	页面图解版操作手册:24 路由五段卡片(入口→截图→做什么→操作步骤→规则与注意)+ 计费速查表 + FAQ
人工测试清单.md	QA	走查底稿:T0~T7 旅程分层 ☐/实际填空表;🟢 已被 e2e 覆盖 / 🟡 待实现 / 无标纯人工三态映射
images/	—	截图 24 张(login/register/home/…/admin),由截图管线产出

截图重跑

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)。

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

Mon, 01 Jan 0001 00:00:00 +0000

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

04 · 待开发功能与规划

Mon, 01 Jan 0001 00:00:00 +0000

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

FSD M1 · 认证与用户

Mon, 01 Jan 0001 00:00:00 +0000

← 总则｜附录 → ｜上游：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 仅差异对拍参照。

FSD M10 · 导演与融合

Mon, 01 Jan 0001 00:00:00 +0000

← 总则｜附录 → ｜上游：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 ⑩）。

FSD M11 · 评估与工具

Mon, 01 Jan 0001 00:00:00 +0000

← 总则｜附录 → ｜上游：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（评估）。

FSD M12 · 管理后台

Mon, 01 Jan 0001 00:00:00 +0000

← 总则｜附录 → ｜上游：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）引用不重立。

FSD M13 · 火花计划

Mon, 01 Jan 0001 00:00:00 +0000

← 总则｜附录 → ｜上游：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）。

FSD M2 · 任务与拆解

Mon, 01 Jan 0001 00:00:00 +0000

← 总则｜附录 → ｜上游：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 仅差异对拍参照。

FSD M3 · 生成与素材

Mon, 01 Jan 0001 00:00:00 +0000

← 总则｜附录 → ｜上游：PRD §4 M3 实现落点：backend/internal/domain/generation/（model/service/service_video/service_media/provider/repo）+ cmd/server/generation_handlers.go + cmd/server/generation_assembly.go + cmd/server/routes.go:53-77（挂载）。事实基准=Go 代码；冻结版 qmtv/server/index.js:369-451/providers.js/assets.js/routes2.js:40-67,408-429/routes3.js:33-55,379-428 仅差异对拍参照。

FSD M4 · 导出交付

Mon, 01 Jan 0001 00:00:00 +0000

← 总则｜附录 → ｜上游：PRD §4 M4 实现落点：backend/internal/domain/export/（model/repo/service）+ cmd/server/export_handlers.go + cmd/server/routes.go:82-92（挂载）。事实基准=Go 代码；冻结版 qmtv/server/index.js:434-471/routes2.js:318-439/routes3.js:347-376 仅差异对拍参照。前端消费：ExportView.vue（编排）+ VideoView.vue（批量/下载面）。

FSD M5 · 通知公告

Mon, 01 Jan 0001 00:00:00 +0000

← 总则｜附录 → ｜上游：PRD §4 M5 实现落点：backend/internal/domain/notification/（service.go 读侧 89 行+hub.go SSE 基座）+ cmd/server/notify_handlers.go + cmd/server/routes.go:96-102（挂载）。事实基准=Go 代码；冻结版 qmtv/server/index.js:474-485 仅差异对拍参照。域内要点：通知零 SSE（hub.go 属本包但通知读面不走事件——写入方五源自持 INSERT）；** announcements 公开面无 amw**；read 是 MySQL 保留字全 SQL 反引号（PRD ①）；对账勿混：routes.go:288-290 /admin/announcements* 3 条属 M12 管理后台组。

FSD M6 · 组织协同

Mon, 01 Jan 0001 00:00:00 +0000

← 总则｜附录 → ｜上游：PRD §4 M6 实现落点：backend/internal/domain/org/（model 308/service 775/repo 209/repo_read 389/repo_groups 55/perms 53/code 24 单包多文件）+ cmd/server/org_handlers.go（460 行 29 handler）+ cmd/server/routes.go:103-136（挂载）。事实基准=Go 代码；冻结版 qmtv/server/index.js:513-597（组织段 9）+enterprise.js（20）仅差异对拍参照。域内要点：四零域（零上传/零扣费/零 SSE/零通知，无 BodyLimit——routes.go:105-106）；无组织分流四态谱：me·dashboard ok(null)｜folders·groups·perm-groups·material-perms·shared-projects ok([])｜folder create·assign·folder delete 400「您尚未加入企业」｜allocation-mode 404「未加入组织」——逐端点归属各异勿统一；owner-严格谱系（invites/remove/role/groups/perm-groups/assign 六面 ownerOnly vs material-perms 唯一 adminOrOwner 面）；「管理员」文案 vs owner 严格判定（PRD ⑩）；projectRank/memberRank 驼峰 wire 双键（同 M2 shotCount 族勿修正）；permGroups/materialPerms 响应经 map 重出（perms json:"-" 串解析为数组）。PRD §4 M6 已登记差异 ①~⑪+十九续勘正批注（prd-qmtv-v1.md:172-178）引用不重立。

FSD M7 · 分销提现

Mon, 01 Jan 0001 00:00:00 +0000

← 总则｜附录 → ｜上游：PRD §4 M7 实现落点：backend/internal/domain/distribution/（model 181/service 233/repo 214）+ cmd/server/distribution_handlers.go（184 行 11 handler）+ cmd/server/routes.go:137-151（挂载）。事实基准=Go 代码；冻结版 qmtv/server/index.js:598-638（用户面 7）+:708-737（状态机 4）两段不连续（中间隔 admin 段 :640-:703）仅差异对拍参照。域内要点：零域铁律——withdrawals/exchanges 全域不触 users.credits/credit_records/通知/SSE（「返佣写入方在 M8 approve 链」model.go:4-8，唯一写入方 M8 F8.03）；available 分母无 status 过滤（cancelled/rejected 永不释放额度——:715 note「收益已解锁」冻结谎言照抄）；settings 回退双 shape 不可合并（overview 三键 vs 提现面一键）；affiliate_threshold 980 硬编码与 M8 不同源勿统一；W_FLOW 严格邻接状态机（终态无键恒 400）；admin PUT 不限属主 vs cancel/confirm 属主强制。bind 形态：POST/PUT 三处裸传 return err（echo 默认 400 无统一信封——与 m12「请求体格式错误」两域不同制）。PRD §4 M7 已登记差异 ①~⑩（prd-qmtv-v1.md:180-184）引用不重立。

FSD M8 · 充值

Mon, 01 Jan 0001 00:00:00 +0000

← 总则｜附录 → ｜上游：PRD §4 M8 实现落点：backend/internal/domain/recharge/（model 118/repo 209/service 381）+ cmd/server/recharge_handlers.go（161 行 8 handler）+ cmd/server/routes.go:152-166（挂载，up8 := BodyLimit("8mb") :158 proof/pay-qrcode 共用）。事实基准=Go 代码；冻结版 qmtv/server/recharge.js（8 条 :28-:120，admin 4 条 router 内写死 /admin/ 前缀）仅差异对拍参照。域内要点：M8 是 M7 的返佣写入方（commission_records 唯一写入方在 approve 链——M7 零域的另一面）；404 文案三态分叉（「订单不存在或已处理」vs proof 面「订单不存在」vs 400「已处理不可重复提交凭证」——model.go:21-32 三哨兵）；approve 零事务补偿序七步（MarkPaid→到账→两级返佣→资格联动→通知→SSE——禁事务铁律顺合冻结补偿式一致性）；reject 双截断不同源（落库 200/通知 100）；orderNo=‘RCH’+毫秒+3 位随机非 uid 勿用 ids 包；recharge_orders.credits 刻意不 DECIMAL（0004 七列外——到账恒整数）；SSE recharge 仅发本人（M12 无 SSE 的对照面）。bind 形态：裸传 return err（与 m12「请求体格式错误」两域不同制）。PRD §4 M8 已登记差异 ①~⑧（prd-qmtv-v1.md:188）引用不重立。

FSD M9 · 剧本库与投稿

Mon, 01 Jan 0001 00:00:00 +0000

← 总则｜附录 → ｜上游：PRD §4 M9 实现落点：backend/internal/domain/scriptlib/（model/repo/service〔scriptlib.js 9+ensureSeed〕/service_studio〔studio.js 16〕/seeds）+ cmd/server/scriptlib_handlers.go + cmd/server/routes.go:167-202（挂载）。事实基准=Go 代码；冻结版 qmtv/server/scriptlib.js/studio.js 仅差异对拍参照。域内要点：admin 9 端点叠 AdminMiddleware（403 forbidden）；wire 全蛇形（model.go json tag 亲证零驼峰）；两套正则刻意勿合并（seedEpisodeRe 带 \s* service.go:78 vs catalogRe 无 :196）；两套Genres 清单（scriptlib.js 11 项 service.go:25 vs studio.js studioGenres 11 项 service_studio.go:21——冻结死导出未消费，Go 不移植）；ID 前缀 sl_/su_/sub_/wp_/up_/na_（ids.go:29-50）。

FSD 附录 · PRD 对照 / 代码域索引 / 差异台账

Mon, 01 Jan 0001 00:00:00 +0000

← 总则｜上游：PRD（§3 模块清单 / §4 差异登记）

附录 A1：PRD 模块 → FSD 分册对照（权威）

PRD 模块	分册	F-ID 段	端点数	覆盖期
基础（SSE/health/release-mode）	总则 §2.2/§2.5 覆盖，无独立分册	—	3	骨架期
M1 认证与用户	m01-认证与用户	F1.01~	9	二十八期
M2 任务与拆解	m02-任务与拆解	F2.01~	38	二十九期
M3 生成与素材	m03-生成与素材	F3.01~	19	二十九期
M4 导出交付	m04-导出交付	F4.01~	10	二十九期
M5 通知公告	m05-通知公告	F5.01~	4	三十期
M6 组织协同	m06-组织协同	F6.01~	29	三十一期
M7 分销提现	m07-分销提现	F7.01~	11	三十一期
M8 充值	m08-充值	F8.01~	8	三十一期
M9 剧本库与投稿	m09-剧本库与投稿	F9.01~	25	三十期
M10 导演与融合	m10-导演与融合	F10.01~	28	三十期
M11 评估与工具	m11-评估与工具	F11.01~	14	三十期
M12 管理后台	m12-管理后台	F12.01~	39	三十一期
M13 火花计划	m13-火花计划	F13.01~	2	三十期

附录 A2：代码域 → 分册反向索引

backend 域包	分册
`internal/domain/auth`	m01
`internal/domain/task`	m02
`internal/domain/generation`	m03
`internal/domain/export`	m04
`internal/domain/notification`	m05
`internal/domain/org`	m06
`internal/domain/distribution`	m07
`internal/domain/recharge`	m08
`internal/domain/scriptlib`	m09
`internal/domain/director`	m10
`internal/domain/evaluation`	m11
`internal/domain/admin` + `internal/domain/llm`	m12
`internal/domain/spark`	m13
`internal/domain/credits`（计费横切）	总则 §2.3 + 各分册扣费节
`internal/infra/{hub,ids,storage}` + `internal/gateway`	总则 §2.2/§2.5/§2.7
`cmd/server/routes.go`（基础 3 条：/api/events、/api/health、release-mode）	总则 §2.2/§2.5
`internal/recovery`（启动恢复四扫描）	跨域，见总则 §2.3 退款唯一口 + m02/m03

附录 B：实现差异台账（DIF）

格式 DIF-<期>-<序号>；FSD 撰写期新发现逐条登记。PRD §4 已登记的移植差异不重复立目，功能节内直接引用（如「差异⑤族」）。处置列：登记（有意保真）/待裁决/已修。

QMTV 功能规格说明书（FSD）v1.0 · 总则

Mon, 01 Jan 0001 00:00:00 +0000

上游文档：prd-qmtv-v1.md（需求与契约）。本文档以 Go 实现代码为事实基准（backend/，239/239 收官），按模块还原系统真实运转规则；与 PRD 的差异以 > ⚠️ 差异 DIF-<批次>-<序号> 注记并登记 99-附录 B。冻结版 Express（qmtv/server/）仅作差异对拍参照，不再单独展开。功能 ID 规则：F<m>.<两位序号>（m = PRD 模块号 M1~M13）。ID 全局唯一、只增不改号；分册文件 m<m>-<中文名>.md。