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/：冻结区保持对照基准原样。