From 6b51bfb71c2ef04e010f857f2b3f57d30f6bbd0b Mon Sep 17 00:00:00 2001
From: Codex <codex@example.local>
Date: Mon, 24 Aug 2026 22:52:35 +0800
Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=EF=BC=9A=E5=A2=9E=E5=8A=A0?=
 =?UTF-8?q?=E6=95=B0=E6=8D=AE=E5=BA=93=E8=BF=81=E7=A7=BB=E8=B4=A6=E6=9C=AC?=
 =?UTF-8?q?=E4=B8=8E=E7=B4=A2=E5=BC=95=E4=BF=9D=E6=8A=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .codemap/codemap.html                   |   2 +-
 .codemap/codemap.md                     |  20 +-
 .codemap/modules.json                   |  36 +--
 DEVELOPMENT_LOG.md                      |  12 +
 NEXT_STEPS.md                           |   3 +-
 PROJECT_AUDIT.md                        |  33 ++-
 STABILITY_P1_DATABASE_MIGRATION_TASK.md |  87 +++++++
 app/db/database.py                      | 266 +++++++++++++++++++-
 tests/test_schema_migration_ledger.py   | 316 ++++++++++++++++++++++++
 9 files changed, 723 insertions(+), 52 deletions(-)
 create mode 100644 STABILITY_P1_DATABASE_MIGRATION_TASK.md
 create mode 100644 tests/test_schema_migration_ledger.py

diff --git a/.codemap/codemap.html b/.codemap/codemap.html
index 24e88fa..bbb7019 100644
--- a/.codemap/codemap.html
+++ b/.codemap/codemap.html
@@ -195,7 +195,7 @@ <h1 id="projTitle">Functional Architecture Map</h1>
 <div class="modal" id="stdModal"></div>
 
 <script>
-const DATA = {"meta": {"project": "NiuMa Studio", "lang": "zh", "subtitle": "牛马片场 · 本地 AI 高光生产后台工程体检", "generatedAt": "2026-08-24", "htmlPath": ".codemap/codemap.html", "mdPath": ".codemap/codemap.md", "spineDesc": "用户通过页面/API 创建素材任务，SQLite Job 驱动转写、AI 选片、审核切片和字幕，再由发送中心排期并交给 Windows Chrome Worker，所有状态与审计证据回写 SQLite。", "tracked_loc": 51786, "tracked_files": 132, "rev": "a01f103c43916d25310254f6f8389e9fc9e52521"}, "bands": [{"id": "presentation", "tier": "fe", "t": "界面 · API", "d": "浏览器页面、前端交互、FastAPI 路由与运行配置"}, {"id": "wire1", "wire": true, "t": "HTTP / JSON / 文件上传"}, {"id": "workflow", "tier": "be", "t": "业务编排", "d": "任务、流水线、发送中心和状态机"}, {"id": "processing", "tier": "be", "t": "媒体与 AI 处理", "d": "转写、AI 选片、切片和字幕"}, {"id": "execution", "tier": "be", "t": "外部执行边界", "d": "调度、Publisher 与 Windows Chrome Worker"}, {"id": "persistence", "tier": "be", "t": "持久化与运维", "d": "SQLite Schema/迁移/备份与本地交付脚本"}], "spine": ["frontend_ui", "api_runtime", "pipeline_queue", "transcription", "ai_selection", "task_review_cut", "subtitle", "publish_center", "publish_scheduler", "publisher_worker", "persistence"], "reportThemes": [["本地单体架构是当前可运行的主要原因", "FastAPI + SQLite WAL + 文件产物 + 持久化 Job + Windows Worker 与个人本机规模匹配；不需要微服务化，现有恢复骨架应保留。"], ["P0 数据一致性边界已封口，事务型旧债仍需继续", "活动库外键、测试误删、媒体删除回滚和切片批次原子提交已修复；迁移无账本与索引重建失败静默降级仍是下一阶段重点。"], ["Job、发布执行和任务状态代际已封口，下一风险转向跨进程精确续跑", "Workflow lease token、Publish execution fencing、任务状态转换、取消恢复和切片原子提交已经完成；下一阶段重点是持久化 step checkpoint 与副作用复用。"], ["可用性 fallback 正在掩盖降级结果", "AI 部分窗口、转写旧产物、损坏 JSON、封面生成、批量发布和风险字段多处静默继续，用户不一定能区分完整成功、部分成功和旧结果。"], ["发布与配置读取是主要安全边界", "Publish Center、AI Config 与 Frontend 仍存在原始 Secret 响应、可选写鉴权和 DOM XSS；Worker 路径与 journal 脱敏已收紧，但本地管理员接口门禁尚未完成。"], ["复杂度集中而非全项目平均恶化", "publish_service.py、publish-center.js、app.js、publish_scheduler.py、subtitle_data_service.py 和 transcript_service.py 是主要 God Component；应按业务边界渐进拆分。"], ["测试已与活动数据隔离，但 Coverage 与真实故障闭环仍不足", "637 项测试全部通过，Pytest 已强制使用进程级 sandbox；Coverage 尚未采集，真实平台 E2E 和故障注入仍需在不触发生产副作用的边界下补齐。"]], "standard": {"rubric": [{"grade": "A", "score": 95, "range": "90–100", "en": "clean, well-scoped, idiomatic", "zh": "干净、职责单一、地道"}, {"grade": "B", "score": 82, "range": "75–89", "en": "minor issues: a documented shim, mild bloat", "zh": "小问题：有文档的兼容、轻微臃肿"}, {"grade": "C", "score": 67, "range": "60–74", "en": "notable hacks / fallbacks / bloat / duplication", "zh": "明显的 hack / 回退 / 臃肿 / 重复"}, {"grade": "D", "score": 50, "range": "40–59", "en": "significant legacy / stubs / duplication, or a protocol violation", "zh": "严重的遗留 / 占位 / 重复，或协议违规"}, {"grade": "F", "score": 25, "range": "0–39", "en": "broken, fake output, or unfinished-but-wired", "zh": "损坏、伪造输出，或未完成却已接线"}], "severities": [{"key": "HIGH", "en": "wrong / dangerous / fake, a protocol or security issue, or a genuine maintenance hazard", "zh": "错误 / 危险 / 伪造、协议或安全问题，或真正的维护地雷"}, {"key": "MED", "en": "a real smell a maintainer should fix", "zh": "维护者该修的真坏味"}, {"key": "LOW", "en": "a documented shim, a cosmetic cast, benign bloat — worth noting, not urgent", "zh": "有文档的兼容、装饰性 cast、良性臃肿 —— 值得记、不紧急"}], "coupling": [{"key": "core", "en": "system spine — central to almost everything", "zh": "系统主线 —— 几乎牵连一切"}, {"key": "high", "en": "many connections", "zh": "连接很多"}, {"key": "med", "en": "moderate", "zh": "中等"}, {"key": "low", "en": "leaf / self-contained", "zh": "叶子 / 自洽"}], "tags": [{"id": "monkeypatch", "label": "monkeypatch", "labelZh": "猴补丁", "bad": true, "en": "runtime mutation of another module / stdlib / vendor; reflection or prototype patching", "zh": "运行时改写别的模块/标准库/依赖；反射或原型补丁"}, {"id": "fallback", "label": "fallback", "labelZh": "回退兜底", "bad": true, "en": "'try the real thing, then fake/degrade'; a||b||c chains that hide which value is real", "zh": "“先试真的再退化/造假”；a||b||c 掩盖哪个是真值"}, {"id": "silent-except", "label": "silent-except", "labelZh": "静默吞错", "bad": true, "en": "swallowed errors: empty catch / except:pass / ignored return codes", "zh": "吞掉错误：空 catch / except:pass / 忽略返回码"}, {"id": "legacy", "label": "legacy", "labelZh": "遗留", "bad": true, "en": "deprecated/back-compat shims, dead-but-shipped code, parallel old+new paths", "zh": "遗留/兼容垫片、已发布的死代码、新旧并存"}, {"id": "dual-format", "label": "dual-format", "labelZh": "双格式", "bad": true, "en": "accepting two shapes for one field (snake||camel), patched through the code", "zh": "同一字段接受两种形态（snake||camel）并散落各处"}, {"id": "stub", "label": "stub", "labelZh": "占位桩", "bad": true, "en": "NotImplemented / TODO / dead buttons / demo scripts presented as real", "zh": "未实现/TODO/死按钮/演示脚本当成品"}, {"id": "fake-output", "label": "fake-output", "labelZh": "伪造输出", "bad": true, "en": "returns random/canned/hardcoded results where real work is implied", "zh": "本应真算的地方返回随机/写死结果"}, {"id": "duplication", "label": "duplication", "labelZh": "重复", "bad": true, "en": "copy-pasted logic, or an existing shared abstraction not reused", "zh": "复制粘贴，或已有共享抽象却不复用"}, {"id": "bloat", "label": "bloat", "labelZh": "臃肿", "bad": true, "en": "oversized file / function; too many responsibilities in one unit", "zh": "超大文件/函数；单元职责过多"}, {"id": "glue", "label": "glue", "labelZh": "胶水", "bad": true, "en": "valueless pass-through: rows of thin forwarders / no-op adapters", "zh": "无价值透传：成片薄包装 / 零转换适配器"}, {"id": "any-escape", "label": "any-escape", "labelZh": "类型逃逸", "bad": true, "en": "bypassing the type system: as any / @ts-ignore / dynamic / void* / reinterpret_cast / unsafe", "zh": "绕过类型系统：as any / @ts-ignore / dynamic / void* / reinterpret_cast / unsafe"}, {"id": "over-fit", "label": "over-fit", "labelZh": "过度特化", "bad": true, "en": "hardcoded to one case where a small generalization was expected", "zh": "硬编码单一情况，本应小幅泛化"}, {"id": "god-component", "label": "god-component", "labelZh": "上帝组件", "bad": true, "en": "one component/class/file doing far too much", "zh": "一个组件/类/文件做太多事"}, {"id": "placeholder", "label": "placeholder", "labelZh": "占位", "bad": true, "en": "unfinished UI / data presented as if complete", "zh": "未完成的 UI/数据当作已完成"}, {"id": "clean", "label": "clean", "labelZh": "干净", "bad": false, "en": "no material issues — well-scoped", "zh": "无实质问题 —— 职责单一"}]}, "modules": [{"id": "frontend_ui", "label": "Frontend UI", "band": "presentation", "path": "app/templates + app/static", "desc": "用 Jinja2、原生 JavaScript 和 CSS 提供任务、审核、字幕与发送中心界面。", "coupling": "high", "deps": ["api_runtime"], "loc": 13840, "score": 65, "grade": "C", "tags": ["god-component", "bloat", "glue", "duplication", "legacy"], "findings": [{"sev": "HIGH", "loc": "app/static/js/app.js:211", "text": "多个写请求绕过统一 apiFetch；启用 LOCAL_ADMIN_TOKEN 时可能缺失 Authorization 并被 API 拒绝。"}, {"sev": "HIGH", "loc": "app/static/js/app.js:1729", "text": "接口或任务数据直接拼接到 innerHTML；publish-center.js:2152 有同类路径，存在本地 DOM XSS/页面结构破坏风险。"}, {"sev": "MED", "loc": "app/templates/system_status.html:98", "text": "配置/API Key 字段进入 DOM，base.html:11 还承载本地管理 Token；需确认全链路始终掩码。"}, {"sev": "MED", "loc": "app/static/css/styles.css:870", "text": "使用多个未在 :root 定义的 CSS 自定义属性，相关声明可能失效。"}, {"sev": "MED", "loc": "app/static/js/app.js:1", "text": "任务、转写、AI、审核、切片、字幕和配置行为集中在超大全局脚本，回归半径较大。"}, {"sev": "MED", "loc": "tests/test_publish_center_browser.py:16", "text": "Playwright 缺失时核心浏览器测试可静默跳过，字幕交互与鉴权失败路径覆盖不足。"}, {"sev": "LOW", "loc": "app/static/js/subtitle-editor.js:171", "text": "字幕编辑器已有 escapeHtml、虚拟列表、竞态 token 与自动保存版本控制，是可保留的正向实现。"}, {"sev": "LOW", "loc": "app/static/js/publish-center.js:4", "text": "前端明确只创建抖音任务，B站保留后端兼容；这是当前产品边界而非应机械删除的代码。"}]}, {"id": "api_runtime", "label": "API & Runtime", "band": "presentation", "path": "app/main.py + core/models/routers", "desc": "加载配置、初始化应用与安全中间件，并把页面/API 请求路由到业务服务。", "coupling": "core", "deps": ["media_storage", "transcription", "ai_selection", "task_review_cut", "subtitle", "pipeline_queue", "publish_center", "publish_scheduler", "persistence"], "loc": 2753, "score": 48, "grade": "D", "tags": ["fallback", "legacy", "dual-format", "bloat", "glue"], "findings": [{"sev": "HIGH", "loc": "app/routers/settings.py:10", "text": "GET /api/settings/ai 未做鉴权，返回 ai_config_service.get_ai_config_context() 中的原始 values；该上下文会从 .env/环境变量读取 API key、token 等 Secret，并同时返回 env_path。前端或本地恶意页面可直接读取凭据。"}, {"sev": "HIGH", "loc": "app/main.py:98", "text": "本地管理鉴权是可选的：只有 LOCAL_ADMIN_TOKEN 非空时才校验写请求；配置默认值为空，因此未配置 Token 时所有 POST/PUT/PATCH/DELETE API 均可被无认证调用。"}, {"sev": "HIGH", "loc": "app/routers/files.py:9", "text": "未鉴权的 /api/files/browse 调用 browse_video_directory，虽限制了根目录和路径穿越，但仍枚举 configured allowed roots 下的目录名、文件名、绝对路径、父路径和文件大小，造成本地媒体元数据泄露。"}, {"sev": "HIGH", "loc": "app/routers/tasks.py:223", "text": "async 路由直接执行同步重任务：音频处理、转写、切片和任务详情 ffprobe 可阻塞 FastAPI event loop，影响无关请求。"}, {"sev": "MED", "loc": "app/routers/tasks.py:35", "text": "大量 async 路由直接调用同步数据库、文件和服务函数；仅少数入口使用 run_in_threadpool，异步边界不一致，容易出现请求串行化和响应抖动。"}, {"sev": "MED", "loc": "app/models/task.py:7-41", "text": "TaskStatus 同时保留大写自动流水线状态和小写 legacy 状态；任意状态跳跃虽已修复，但模型、旧页面和 API 客户端仍需兼容两套值。"}, {"sev": "MED", "loc": "app/routers/tasks.py:35; app/routers/publish.py:1", "text": "tasks.py 与 publish.py 聚合大量路由、异常映射、同步/异步调度和业务编排，新增流程的 blast radius 较大。"}]}, {"id": "media_storage", "label": "Media & Storage", "band": "processing", "path": "storage/media/FFmpeg services", "desc": "管理 E 盘任务目录、路径安全、素材预检、FFmpeg/FFprobe 与受控子进程。", "coupling": "high", "deps": ["persistence"], "loc": 1614, "score": 84, "grade": "B", "tags": ["legacy", "dual-format", "glue", "fallback", "silent-except"], "findings": [{"sev": "MED", "loc": "app/services/storage_service.py:840-846", "text": "move_task_directory_to_trash 明确传入 reserve=False，仍采用查询后检查目录的非原子分配；当前无运行时调用，属于遗留兼容入口，但未来恢复调用时仍可能并发复用同一回收站目录。"}, {"sev": "MED", "loc": "app/services/storage_service.py:361-367", "text": "通用 resolve_video_file_path 对已存在路径仍原样返回。媒体 HTTP 路由已增加任务边界，但 publish/auto-publish/subtitle/task 查询等非 HTTP 调用方仍可把数据库中的现有外部路径交给后续读取或上传逻辑。"}, {"sev": "LOW", "loc": "tests/test_storage_boundaries.py:14-32", "text": "新增边界测试没有覆盖任务目录数据库读取在 sqlite3.Error、锁定或损坏数据库下显式失败的回归；代码已有保护但证据不足。"}, {"sev": "LOW", "loc": "app/services/storage_service.py:257-300", "text": "reserve=True 会在数据库任务记录写入前创建目录；进程在预占后崩溃可能留下无数据库记录的空目录，虽不会覆盖数据，但会造成孤儿目录累积。"}]}, {"id": "transcription", "label": "Transcription", "band": "processing", "path": "transcript services", "desc": "提取音频，调用火山引擎或 faster-whisper，并以分块 checkpoint 生成时间戳转写。", "coupling": "high", "deps": ["media_storage", "persistence"], "loc": 1960, "score": 59, "grade": "D", "tags": ["fallback", "silent-except", "fake-output", "duplication", "god-component", "glue", "over-fit"], "findings": [{"sev": "HIGH", "loc": "app/services/transcript_workflow_service.py:317", "text": "transcript Markdown 存在即返回 completed，未校验源指纹、Provider、进度状态或文件完整性。"}, {"sev": "HIGH", "loc": "app/services/transcript_service.py:265", "text": "JobLeaseLostError 已显式透传，但 TranscriptCancelledError 仍会被统一包装为 RuntimeError，取消可能落成 failed。"}, {"sev": "HIGH", "loc": "app/services/transcript_service.py:516", "text": "远程分块请求每次使用随机 request id，缺少持久化幂等键和超时后结果确认，重试可能重复计费。"}, {"sev": "MED", "loc": "app/services/transcript_service.py:516", "text": "HTTP 429、Retry-After、网络瞬断和可恢复服务错误缺少专门退避策略。"}, {"sev": "MED", "loc": "app/services/transcript_service.py:556", "text": "响应 result.message 可能被当作 0-1 秒转写正文写入结果。"}, {"sev": "MED", "loc": "app/services/transcript_service.py:831", "text": "进度文件 IO/JSON 损坏时静默返回空字典，可能隐藏故障并触发重复执行。"}, {"sev": "MED", "loc": "app/services/transcript_workflow_service.py:224", "text": "运行和取消状态仍是进程内 set，多进程/重启时不能可靠去重或取消。"}, {"sev": "MED", "loc": "app/services/transcript_service.py:325", "text": "本地和远程转写复制分块、checkpoint、异常和进度循环，行为容易漂移。"}, {"sev": "MED", "loc": "app/services/transcript_service.py:1088", "text": "Provider/模型/设备为模块级可变全局，并发任务可能互相覆盖运行元数据。"}, {"sev": "MED", "loc": "app/services/transcript_service.py:83", "text": "约 1300 行文件混合 FFmpeg、本地模型、远程 HTTP、checkpoint、进度和 Markdown，职责过大。"}, {"sev": "LOW", "loc": "tests/test_long_live_foundation.py:65", "text": "已覆盖失租 checkpoint 和异常透传，仍缺取消、429/坏响应、重复计费与真实 Markdown 闭环。"}]}, {"id": "ai_selection", "label": "AI Selection", "band": "processing", "path": "AI providers and analyzers", "desc": "选择 Codex/远程/本地 Provider，解析不稳定 AI 输出并生成通用、综艺或长直播候选片段。", "coupling": "core", "deps": ["transcription", "persistence"], "loc": 4420, "score": 63, "grade": "C", "tags": ["fallback", "silent-except", "legacy", "dual-format", "stub", "fake-output", "bloat", "duplication", "god-component"], "findings": [{"sev": "HIGH", "loc": "app/services/ai_config_service.py:318", "text": "get_ai_config_context 返回含 AI/ASR Key 的完整 values，GET /api/settings/ai 无读取鉴权，页面也复用该上下文。"}, {"sev": "MED", "loc": "app/services/ai/ai_clip_service.py:4", "text": "generate_candidate_clips_placeholder 返回三条硬编码 ClipCandidate；虽当前无调用方，误接线会产生 fake output。"}, {"sev": "MED", "loc": "app/services/ai/ai_clip_analyzer.py:131", "text": "分段分析失败窗口被跳过，只要其他窗口有候选便返回；通用路径缺少最低覆盖率门槛。"}, {"sev": "MED", "loc": "app/services/ai/variety_comedy_analyzer.py:513", "text": "全局评审失败时隐式降级到扩展阶段评分，Provider 失败仍可形成候选。"}, {"sev": "MED", "loc": "app/services/ai/local_model_provider.py:19", "text": "fallback_protocol 对任意 AIProviderError 都执行第二协议，未区分限流、认证和协议错误，可能重复调用与计费。"}, {"sev": "MED", "loc": "app/services/ai_analysis_workflow_service.py:738", "text": "候选事务替换、JSON 文件和 run 历史分步持久化，后续失败会形成数据库与文件/历史不一致。"}, {"sev": "MED", "loc": "app/services/ai/long_live_talk_analyzer.py:427", "text": "checkpoint 更新无 run/lease/owner fencing，并发或旧进程恢复可能互相覆盖窗口状态。"}, {"sev": "MED", "loc": "app/services/ai_analysis_workflow_service.py:71", "text": "分析元文件不存在、损坏或读取异常时静默返回空字典，无法区分未分析与产物损坏。"}, {"sev": "LOW", "loc": "app/services/ai/ai_clip_analyzer.py:456", "text": "输出归一化同时接受多组历史字段并填大量默认值，兼容有效但维护成本高。"}, {"sev": "LOW", "loc": "app/services/ai_config_service.py:55", "text": "旧 AI_REMOTE 与新分析/发布配置并存，运行时还改写全局 settings，形成双路径。"}, {"sev": "MED", "loc": "app/services/ai_analysis_workflow_service.py:685", "text": "单文件集中 profile、Provider、状态、候选、文件、历史与恢复，模块回归半径大。"}, {"sev": "MED", "loc": "app/services/ai/ai_clip_analyzer.py:252", "text": "多个分析器重复偏好摘要、时间转换、默认字段和 AI 输出解析逻辑。"}, {"sev": "MED", "loc": "tests/test_split_services.py:200", "text": "缺少真实 Provider 成功路径、文件写入失败一致性、并发运行和旧 checkpoint 覆盖测试。"}, {"sev": "MED", "loc": "tests/test_codex_cli_provider.py:12", "text": "Provider 测试主要 monkeypatch，缺少 HTTP 429/500/超时和协议 fallback 重复调用边界。"}, {"sev": "LOW", "loc": "tests/test_variety_comedy_selection.py:291", "text": "算法分支覆盖较好，但真实三阶段 Provider、资源消耗和全局评审降级未由集成测试锁定。"}]}, {"id": "task_review_cut", "label": "Task Review & Cut", "band": "workflow", "path": "task and cut workflow services", "desc": "维护任务状态与视图，保存候选审核选择，生成切片版本并同步发送中心。", "coupling": "core", "deps": ["media_storage", "ai_selection", "publish_center", "persistence"], "loc": 3036, "score": 78, "grade": "B", "tags": ["god-component", "glue", "fallback", "dual-format", "legacy", "over-fit"], "findings": [{"sev": "HIGH", "loc": "app/services/task_service.py:458-485,594-616", "text": "任务详情默认执行无 timeout 的 ffprobe，且未捕获 OSError/Path.stat 异常；NAS、损坏或卡死媒体可能阻塞详情请求或返回 500。明确延期至 P1.4。"}, {"sev": "MED", "loc": "app/services/task_lifecycle_service.py:373-401; tests/test_task_state_machine.py:69-82", "text": "公共状态转换前置条件只检查数据库字段或路径字符串，不验证源视频、候选产物和活跃 output 文件真实存在。明确延期至 P1.4。"}, {"sev": "MED", "loc": "app/services/task_service.py:1-98,1220-1273; app/services/task_query_service.py:16-24", "text": "TaskService 仍集中承担大量业务、数据库和展示职责，并与 task_query_service 互相导入、保留包装函数，维护 blast radius 较大。建议作为 P2 延后拆分。"}, {"sev": "MED", "loc": "app/services/task_service.py:717-718", "text": "候选片段列表会直接解析每条历史时间字段，单条异常格式仍可能阻断整个审核列表。"}, {"sev": "LOW", "loc": "app/services/task_lifecycle_service.py:139-225", "text": "任务目录预占后若后续数据库写入失败，仍缺少统一释放空目录的补偿路径，可能留下少量孤儿目录。"}]}, {"id": "subtitle", "label": "Subtitle", "band": "processing", "path": "subtitle services", "desc": "维护字幕轨、不可变 revision、cue、AI 建议、渲染验证与自动流水线交付决定。", "coupling": "high", "deps": ["media_storage", "task_review_cut", "ai_selection", "persistence"], "loc": 2409, "score": 70, "grade": "C", "tags": ["fallback", "silent-except", "legacy", "bloat", "god-component", "monkeypatch"], "findings": [{"sev": "MED", "loc": "app/services/subtitle_data_service.py:352", "text": "手工 revision 的 active/base 检查在事务外，并发编辑可覆盖 active 选择。"}, {"sev": "MED", "loc": "app/services/subtitle_data_service.py:489", "text": "批准 revision 在事务外校验，并发或重放旧请求可回退 active 版本。"}, {"sev": "MED", "loc": "app/services/subtitle_data_service.py:135", "text": "source/clip track 先查后插，NULL output_clip_id 约束不足，并发可能重复源轨。"}, {"sev": "MED", "loc": "app/services/subtitle_auto_workflow_service.py:87", "text": "批量批准逐 clip 独立提交，Job 后创建；中途失败会留下部分批准。"}, {"sev": "MED", "loc": "app/services/subtitle_data_service.py:168", "text": "source revision 提交后逐 clip 独立同步，异常会形成混合版本。"}, {"sev": "MED", "loc": "app/services/subtitle_workflow_service.py:475", "text": "字幕 job 完成与激活分两次写入，迟到 worker 仍可能激活旧成片。"}, {"sev": "LOW", "loc": "app/services/subtitle_auto_workflow_service.py:273", "text": "auto_config_json 损坏时静默降为空并写回，可能丢弃其他配置。"}, {"sev": "MED", "loc": "app/services/subtitle_data_service.py:1045", "text": "字幕数据服务聚合 track、revision、cue、导入导出、波形和渲染辅助，回归半径大。"}, {"sev": "LOW", "loc": "app/services/subtitle_workflow_service.py:312", "text": "统一 revision 外仍保留旧调用方适配，存在历史口径漂移成本。"}, {"sev": "MED", "loc": "tests/test_subtitle_editor.py:189", "text": "缺并发 save/approve/ensure track 与批处理中途失败测试。"}, {"sev": "LOW", "loc": "tests/test_subtitle_auto_workflow.py:172", "text": "核心真实渲染在 FFmpeg/FFprobe 缺失时会跳过，异常 Provider 证据不足。"}, {"sev": "LOW", "loc": "app/services/subtitle_data_service.py:761", "text": "波形处理把完整 PCM 捕获到内存，超长媒体存在时长线性内存峰值。"}, {"sev": "LOW", "loc": "app/services/subtitle_data_service.py:1024", "text": "单条字幕文本可接近文件上限，放大渲染、导出和 Prompt 资源消耗。"}]}, {"id": "pipeline_queue", "label": "Pipeline & Job Queue", "band": "workflow", "path": "pipeline and workflow job services", "desc": "用 SQLite Job、Lease、Heartbeat、Checkpoint 和子进程串联长任务与自动流水线。", "coupling": "core", "deps": ["transcription", "ai_selection", "task_review_cut", "subtitle", "publish_center", "persistence"], "loc": 3350, "score": 88, "grade": "B", "tags": ["god-component", "bloat", "legacy", "glue", "over-fit"], "findings": [{"sev": "LOW", "loc": "app/services/pipeline_engine.py:977-1073", "text": "PUBLISH_JOB_CREATING 尚无专用 reconcile 分支，恢复主要依赖重复创建的幂等去重。"}, {"sev": "LOW", "loc": "tests/test_pipeline_checkpoint.py:358-625; tests/test_pipeline_state_stability.py:275-313", "text": "仍缺真实进程重启、lease 过期边界及发布内容证据变更的进程级回归测试。"}]}, {"id": "publish_center", "label": "Publish Center", "band": "workflow", "path": "publish content preparation services", "desc": "准备标题、简介、话题、封面、账号和发布草稿，并保留历史兼容执行入口。", "coupling": "core", "deps": ["task_review_cut", "subtitle", "publish_scheduler", "publisher_worker", "persistence"], "loc": 5593, "score": 52, "grade": "D", "tags": ["god-component", "bloat", "legacy", "dual-format", "fallback", "silent-except", "placeholder", "duplication"], "findings": [{"sev": "HIGH", "loc": "app/services/publish_service.py:570", "text": "_normalize_config/_normalize_account 仅新增 *_masked 字段，却保留 client_secret、access_token、refresh_token 原字段；GET /api/publish/platforms、/accounts 及保存配置/账号响应直接返回这些原始密钥，存在敏感凭据泄漏风险。"}, {"sev": "MED", "loc": "app/services/publish_service.py:266", "text": "publish_service.py 当前约4750行，混合配置/账号/OAuth、文案与封面、队列同步、历史、旧 OpenCLI 脚本、API Provider 和页面上下文，形成高耦合 God Component，任一发布流程改动的 blast radius 很大。"}, {"sev": "MED", "loc": "app/services/publish_service.py:2941", "text": "历史查询 SQL 只按 PUBLISH_HISTORY_STATUSES 的大写值过滤，之后才调用 _normalize_publish_status；LEGACY_STATUS_MAP 支持旧小写状态但旧记录会在 SQL 层被提前排除，历史页可能漏数据。"}, {"sev": "MED", "loc": "app/services/publish_service.py:2144", "text": "sync_task_publish_jobs 封面生成失败时只把 {'cover_error': ...} 放入 item_covers，仍继续插入 WAITING 任务且不计入 errors；同步可能返回 ok，但生成的任务实际无法通过 local_browser readiness。"}, {"sev": "MED", "loc": "app/services/publish_service.py:2787", "text": "create_batch_publish_jobs 对不存在的 output_clip_id 直接 continue，全部无效或部分无效时仍返回 status='ok'，调用方无法区分‘创建成功’与‘输入被静默丢弃’。"}, {"sev": "MED", "loc": "app/services/publish_readiness.py:167", "text": "publish_domain/create_publish_job 仍允许 api_publish，publishers registry 也保留兼容入口，但统一 readiness 只接受 local_browser/manual_export 并将 api_publish 标记 unsupported_publish_mode，持久化任务与调度契约不一致。"}, {"sev": "MED", "loc": "app/services/publish_providers.py:117", "text": "BilibiliPublishProvider 在完成配置和 token 校验后始终抛出 bilibili_provider_pending；api_publish 模式仍可创建/注册，因此这是已接线但必然失败的 placeholder 路径。"}, {"sev": "MED", "loc": "app/services/publish_providers.py:66", "text": "旧 Douyin API Provider 将 upload 与 create 分成两个无幂等键的请求；_request_json 只包装 HTTPError/URLError，平台已接收后网络超时或连接异常可能被判失败，重试会重复上传/投稿且没有 NEED_REVIEW 不确定态。"}, {"sev": "LOW", "loc": "app/services/publish_providers.py:204", "text": "_post_multipart 先 file_path.read_bytes() 再 b''.join(chunks)，完整视频和完整 multipart body 同时驻留内存，大文件发布存在约双倍峰值。"}, {"sev": "LOW", "loc": "app/services/publish_service.py:1569", "text": "_batch_find_publish_jobs 对每条记录直接调用 _normalize_job(row)，未传入预取 accounts；_normalize_job 会逐条触发 readiness/account 查询，发布中心批量切片时形成 N+1 查询。"}, {"sev": "LOW", "loc": "tests/test_publish_history.py:111", "text": "现有定向测试未覆盖原始 Secret/Token 响应、旧小写历史状态、同步封面 partial、批量无效 ID，以及 API 超时后已接收的重复投稿边界。"}]}, {"id": "publish_scheduler", "label": "Publish Scheduler", "band": "execution", "path": "scheduler/repository/executor", "desc": "计算排期、原子领取发布任务、重试、恢复不确定执行并维护发布状态机。", "coupling": "core", "deps": ["publish_center", "publisher_worker", "persistence"], "loc": 2329, "score": 71, "grade": "C", "tags": ["god-component", "bloat", "legacy", "silent-except"], "findings": [{"sev": "MED", "loc": "app/services/publish_scheduler.py:756-785", "text": "recover_interrupted_jobs 每轮加载全部 PUBLISHING 任务，并对每个任务串行查询 Worker，没有批量上限、并发控制或退避；Worker 不可用或卡住任务较多时，单轮耗时按任务数乘以网络超时增长，会延迟后续排期处理。"}, {"sev": "MED", "loc": "app/services/publish_scheduler.py:281-302", "text": "list_due_jobs 每轮 SELECT 全部 SCHEDULED 记录，再逐条在 Python 中解析时间；虽已有状态/排期索引，但没有 SQL due 条件、分页或批量上限，排期量增长后会增加扫描内存和调度延迟。"}, {"sev": "MED", "loc": "app/services/publish_scheduler.py:133-1788", "text": "PublishScheduler 约 1891 行、42 个方法，同时承担排期计算、任务领取、执行结果写回、Worker 恢复、重试修复、人工复核、批量排期和旧版兼容；职责边界过宽，修改任一状态路径的回归半径较大。"}, {"sev": "LOW", "loc": "app/services/publish_scheduler.py:274-279", "text": "shutdown 已能追踪并等待后台 Task，但没有超时或取消兜底；若当前 run_once 被数据库锁、Worker 串行查询或文件操作长期阻塞，应用优雅停机仍可能无限等待。"}, {"sev": "LOW", "loc": "app/services/publish_scheduler.py:1807-1812", "text": "queue_snapshot 对非法 scheduled_at 捕获 ValueError 后静默 pass；损坏排期会从“今日任务”视图中消失，未产生告警或错误计数，降低数据异常可见性。"}]}, {"id": "publisher_worker", "label": "Publishers & Worker", "band": "execution", "path": "publisher registry and Windows worker", "desc": "通过 Publisher Registry 和 Windows Chrome Worker 执行抖音/B站投稿、导出与兼容模式。", "coupling": "high", "deps": ["media_storage", "persistence"], "loc": 2699, "score": 76, "grade": "B", "tags": ["legacy", "glue", "silent-except", "fallback"], "findings": [{"sev": "MED", "loc": "scripts/publish_host_worker.py:321", "text": "_prior_job_execution_requires_review 扫描旧 execution journal 时，若 journal 缺少 identity 或已损坏，直接 continue；跨 execution 无法确认其 job_id 时不会阻断新 execution。旧 Worker 在上传后崩溃并留下无身份/损坏日志时，仍存在重复投稿边界。"}, {"sev": "LOW", "loc": "app/services/publishers/page_scripts.py:14", "text": "页面脚本入口仍通过延迟导入 publish_service 私有函数来转发大量 DOM 脚本；这是有意保留的兼容层，但形成 legacy glue，脚本变更仍会牵连 4750 行 God Service。"}, {"sev": "LOW", "loc": "app/services/publishers/browser_runtime.py:315", "text": "screenshot 捕获裸 Exception 后返回空字符串，截图失败不会进入发布结果或健康信号；发布可以继续但缺少关键诊断证据。"}, {"sev": "LOW", "loc": "scripts/opencli_host_bridge.py:74", "text": "旧 OpenCLIHostBridgeHandler 的 /run 处理器本身没有 Bearer Token 校验；当前 main 已转调受保护的 publish_host_worker，默认入口不再使用它，但保留的可直接实例化旧处理器仍会造成安全边界误解。"}, {"sev": "LOW", "loc": "tests/test_publish_worker_client.py:155", "text": "当前测试已覆盖双进程锁竞争、死进程锁回收和常规 execution fencing，但仍未覆盖无身份/损坏旧 journal 被跨 execution 扫描跳过、screenshot 失败信号及旧 bridge 处理器被直接启动时的鉴权边界。"}]}, {"id": "persistence", "label": "SQLite Persistence", "band": "persistence", "path": "app/db + backup services", "desc": "创建 SQLite Schema、执行启动时兼容迁移和索引，并提供 WAL 安全备份恢复。", "coupling": "core", "deps": [], "loc": 3436, "score": 64, "grade": "C", "tags": ["silent-except", "legacy", "dual-format", "bloat", "god-component"], "findings": [{"sev": "HIGH", "loc": "app/db/database.py:628-671", "text": "_create_indexes 先删除 uq_publish_jobs_active_clip_platform_mode，随后对所有索引创建统一捕获 sqlite3.Error 并静默忽略；唯一部分索引创建失败时，旧索引已删除且无告警，活动发布任务可能失去唯一约束并产生重复记录。"}, {"sev": "MED", "loc": "app/db/database.py:31-617", "text": "数据库初始化依赖多个结构探针和缺列即 ALTER TABLE，没有 PRAGMA user_version、schema_migrations 或可追踪迁移版本；历史数据库的实际结构只能由当前代码反推。"}, {"sev": "MED", "loc": "app/db/database.py:754,1162", "text": "多个迁移函数使用 executescript，发布表迁移还会在数据规范化前提交新增列；后续失败时可能已持久化部分结构，init_db 不是原子升级。"}, {"sev": "LOW", "loc": "app/db/database.py:656-657", "text": "workflow job claim 索引未覆盖 lease_expires_at；队列规模增大或过期任务集中时可能读取更多候选行，属于性能退化而非当前正确性故障。"}]}, {"id": "ops_delivery", "label": "Ops & Delivery", "band": "persistence", "path": "Docker/PowerShell/CI", "desc": "提供 Windows/Docker 启停、诊断、CI、发布门禁、Demo 与维护脚本。", "coupling": "med", "deps": ["api_runtime", "publisher_worker", "persistence"], "loc": 4347, "score": 68, "grade": "C", "tags": ["fallback", "legacy", "dual-format", "duplication", "bloat", "glue", "silent-except", "monkeypatch"], "findings": [{"sev": "MED", "loc": ".github/workflows/ci.yml:3", "text": "CI 仅监听 master push/PR；feature/docs 直接 push 不即时验证，问题延迟到开 PR。"}, {"sev": "MED", "loc": "scripts/start_docker_opencli.ps1:24", "text": "健康检查异常只警告不返回非零，服务失败也可能被调用方视为启动成功。"}, {"sev": "MED", "loc": "scripts/start.ps1:30", "text": "Demo 覆盖生效前先对正式 E 盘配置运行 doctor，新机/迁移机的隔离 Demo 可能被旧路径阻断。"}, {"sev": "MED", "loc": "scripts/start.ps1:71", "text": "Worker 启动异常被捕获后继续并报告工作台成功，发布能力不可用时易被误判完整健康。"}, {"sev": "HIGH", "loc": "scripts/migrate_task_dirs_to_project_names.py:211", "text": "任务目录迁移用非 WAL-aware 主库 copy，先移动目录再统一更新提交，无文件补偿，异常会让路径/DB 不一致。"}, {"sev": "MED", "loc": "scripts/restore.ps1:27", "text": "恢复只以健康响应判断 App 运行，StopServices 只停 Compose；native/异常健康进程可能仍持有 DB 时执行替换。"}, {"sev": "MED", "loc": "scripts/backup.ps1:33", "text": "备份默认包含 .env 且不加密，仅显式 ExcludeEnv 才排除，包被共享时泄漏本机秘密。"}, {"sev": "MED", "loc": "tests/test_native_scripts.py:11", "text": "启停测试主要是源码字符串断言，Windows smoke 不做实际 restore/冲突/清理失败与恢复后健康验证。"}, {"sev": "MED", "loc": "scripts/seed_demo_data.py:32", "text": "缺 FFmpeg 时仍插入无媒体路径 Demo 数据并成功退出，数量检查通过但媒体 smoke 不可信。"}, {"sev": "LOW", "loc": "scripts/acceptance.ps1:115", "text": "验收递归扫描正式任务目录，媒体量大/锁文件会显著拖慢或阻断 release gate。"}, {"sev": "LOW", "loc": "scripts/backup_restore_runtime.py:142", "text": "import 时 monkeypatch backup core，全局行为依赖导入顺序。"}, {"sev": "LOW", "loc": "docs/PORTABLE_SETUP.md:127", "text": "文档描述与当前 start.ps1 实现不符，旧 Next Steps 又保留兼容入口，启动排障认知漂移。"}]}]};
+const DATA = {"meta": {"project": "NiuMa Studio", "lang": "zh", "subtitle": "牛马片场 · 本地 AI 高光生产后台工程体检", "generatedAt": "2026-08-24", "htmlPath": ".codemap/codemap.html", "mdPath": ".codemap/codemap.md", "spineDesc": "用户通过页面/API 创建素材任务，SQLite Job 驱动转写、AI 选片、审核切片和字幕，再由发送中心排期并交给 Windows Chrome Worker，所有状态与审计证据回写 SQLite。", "tracked_loc": 52028, "tracked_files": 132, "rev": "a01f103c43916d25310254f6f8389e9fc9e52521"}, "bands": [{"id": "presentation", "tier": "fe", "t": "界面 · API", "d": "浏览器页面、前端交互、FastAPI 路由与运行配置"}, {"id": "wire1", "wire": true, "t": "HTTP / JSON / 文件上传"}, {"id": "workflow", "tier": "be", "t": "业务编排", "d": "任务、流水线、发送中心和状态机"}, {"id": "processing", "tier": "be", "t": "媒体与 AI 处理", "d": "转写、AI 选片、切片和字幕"}, {"id": "execution", "tier": "be", "t": "外部执行边界", "d": "调度、Publisher 与 Windows Chrome Worker"}, {"id": "persistence", "tier": "be", "t": "持久化与运维", "d": "SQLite Schema/迁移/备份与本地交付脚本"}], "spine": ["frontend_ui", "api_runtime", "pipeline_queue", "transcription", "ai_selection", "task_review_cut", "subtitle", "publish_center", "publish_scheduler", "publisher_worker", "persistence"], "reportThemes": [["本地单体架构是当前可运行的主要原因", "FastAPI + SQLite WAL + 文件产物 + 持久化 Job + Windows Worker 与个人本机规模匹配；不需要微服务化，现有恢复骨架应保留。"], ["P0 数据一致性边界已封口，事务型旧债仍需继续", "活动库外键、测试误删、媒体删除回滚和切片批次原子提交已修复；迁移无账本与索引重建失败静默降级仍是下一阶段重点。"], ["Job、发布执行和任务状态代际已封口，下一风险转向跨进程精确续跑", "Workflow lease token、Publish execution fencing、任务状态转换、取消恢复和切片原子提交已经完成；下一阶段重点是持久化 step checkpoint 与副作用复用。"], ["可用性 fallback 正在掩盖降级结果", "AI 部分窗口、转写旧产物、损坏 JSON、封面生成、批量发布和风险字段多处静默继续，用户不一定能区分完整成功、部分成功和旧结果。"], ["发布与配置读取是主要安全边界", "Publish Center、AI Config 与 Frontend 仍存在原始 Secret 响应、可选写鉴权和 DOM XSS；Worker 路径与 journal 脱敏已收紧，但本地管理员接口门禁尚未完成。"], ["复杂度集中而非全项目平均恶化", "publish_service.py、publish-center.js、app.js、publish_scheduler.py、subtitle_data_service.py 和 transcript_service.py 是主要 God Component；应按业务边界渐进拆分。"], ["测试已与活动数据隔离，但 Coverage 与真实故障闭环仍不足", "637 项测试全部通过，Pytest 已强制使用进程级 sandbox；Coverage 尚未采集，真实平台 E2E 和故障注入仍需在不触发生产副作用的边界下补齐。"]], "standard": {"rubric": [{"grade": "A", "score": 95, "range": "90–100", "en": "clean, well-scoped, idiomatic", "zh": "干净、职责单一、地道"}, {"grade": "B", "score": 82, "range": "75–89", "en": "minor issues: a documented shim, mild bloat", "zh": "小问题：有文档的兼容、轻微臃肿"}, {"grade": "C", "score": 67, "range": "60–74", "en": "notable hacks / fallbacks / bloat / duplication", "zh": "明显的 hack / 回退 / 臃肿 / 重复"}, {"grade": "D", "score": 50, "range": "40–59", "en": "significant legacy / stubs / duplication, or a protocol violation", "zh": "严重的遗留 / 占位 / 重复，或协议违规"}, {"grade": "F", "score": 25, "range": "0–39", "en": "broken, fake output, or unfinished-but-wired", "zh": "损坏、伪造输出，或未完成却已接线"}], "severities": [{"key": "HIGH", "en": "wrong / dangerous / fake, a protocol or security issue, or a genuine maintenance hazard", "zh": "错误 / 危险 / 伪造、协议或安全问题，或真正的维护地雷"}, {"key": "MED", "en": "a real smell a maintainer should fix", "zh": "维护者该修的真坏味"}, {"key": "LOW", "en": "a documented shim, a cosmetic cast, benign bloat — worth noting, not urgent", "zh": "有文档的兼容、装饰性 cast、良性臃肿 —— 值得记、不紧急"}], "coupling": [{"key": "core", "en": "system spine — central to almost everything", "zh": "系统主线 —— 几乎牵连一切"}, {"key": "high", "en": "many connections", "zh": "连接很多"}, {"key": "med", "en": "moderate", "zh": "中等"}, {"key": "low", "en": "leaf / self-contained", "zh": "叶子 / 自洽"}], "tags": [{"id": "monkeypatch", "label": "monkeypatch", "labelZh": "猴补丁", "bad": true, "en": "runtime mutation of another module / stdlib / vendor; reflection or prototype patching", "zh": "运行时改写别的模块/标准库/依赖；反射或原型补丁"}, {"id": "fallback", "label": "fallback", "labelZh": "回退兜底", "bad": true, "en": "'try the real thing, then fake/degrade'; a||b||c chains that hide which value is real", "zh": "“先试真的再退化/造假”；a||b||c 掩盖哪个是真值"}, {"id": "silent-except", "label": "silent-except", "labelZh": "静默吞错", "bad": true, "en": "swallowed errors: empty catch / except:pass / ignored return codes", "zh": "吞掉错误：空 catch / except:pass / 忽略返回码"}, {"id": "legacy", "label": "legacy", "labelZh": "遗留", "bad": true, "en": "deprecated/back-compat shims, dead-but-shipped code, parallel old+new paths", "zh": "遗留/兼容垫片、已发布的死代码、新旧并存"}, {"id": "dual-format", "label": "dual-format", "labelZh": "双格式", "bad": true, "en": "accepting two shapes for one field (snake||camel), patched through the code", "zh": "同一字段接受两种形态（snake||camel）并散落各处"}, {"id": "stub", "label": "stub", "labelZh": "占位桩", "bad": true, "en": "NotImplemented / TODO / dead buttons / demo scripts presented as real", "zh": "未实现/TODO/死按钮/演示脚本当成品"}, {"id": "fake-output", "label": "fake-output", "labelZh": "伪造输出", "bad": true, "en": "returns random/canned/hardcoded results where real work is implied", "zh": "本应真算的地方返回随机/写死结果"}, {"id": "duplication", "label": "duplication", "labelZh": "重复", "bad": true, "en": "copy-pasted logic, or an existing shared abstraction not reused", "zh": "复制粘贴，或已有共享抽象却不复用"}, {"id": "bloat", "label": "bloat", "labelZh": "臃肿", "bad": true, "en": "oversized file / function; too many responsibilities in one unit", "zh": "超大文件/函数；单元职责过多"}, {"id": "glue", "label": "glue", "labelZh": "胶水", "bad": true, "en": "valueless pass-through: rows of thin forwarders / no-op adapters", "zh": "无价值透传：成片薄包装 / 零转换适配器"}, {"id": "any-escape", "label": "any-escape", "labelZh": "类型逃逸", "bad": true, "en": "bypassing the type system: as any / @ts-ignore / dynamic / void* / reinterpret_cast / unsafe", "zh": "绕过类型系统：as any / @ts-ignore / dynamic / void* / reinterpret_cast / unsafe"}, {"id": "over-fit", "label": "over-fit", "labelZh": "过度特化", "bad": true, "en": "hardcoded to one case where a small generalization was expected", "zh": "硬编码单一情况，本应小幅泛化"}, {"id": "god-component", "label": "god-component", "labelZh": "上帝组件", "bad": true, "en": "one component/class/file doing far too much", "zh": "一个组件/类/文件做太多事"}, {"id": "placeholder", "label": "placeholder", "labelZh": "占位", "bad": true, "en": "unfinished UI / data presented as if complete", "zh": "未完成的 UI/数据当作已完成"}, {"id": "clean", "label": "clean", "labelZh": "干净", "bad": false, "en": "no material issues — well-scoped", "zh": "无实质问题 —— 职责单一"}]}, "modules": [{"id": "frontend_ui", "label": "Frontend UI", "band": "presentation", "path": "app/templates + app/static", "desc": "用 Jinja2、原生 JavaScript 和 CSS 提供任务、审核、字幕与发送中心界面。", "coupling": "high", "deps": ["api_runtime"], "loc": 13840, "score": 65, "grade": "C", "tags": ["god-component", "bloat", "glue", "duplication", "legacy"], "findings": [{"sev": "HIGH", "loc": "app/static/js/app.js:211", "text": "多个写请求绕过统一 apiFetch；启用 LOCAL_ADMIN_TOKEN 时可能缺失 Authorization 并被 API 拒绝。"}, {"sev": "HIGH", "loc": "app/static/js/app.js:1729", "text": "接口或任务数据直接拼接到 innerHTML；publish-center.js:2152 有同类路径，存在本地 DOM XSS/页面结构破坏风险。"}, {"sev": "MED", "loc": "app/templates/system_status.html:98", "text": "配置/API Key 字段进入 DOM，base.html:11 还承载本地管理 Token；需确认全链路始终掩码。"}, {"sev": "MED", "loc": "app/static/css/styles.css:870", "text": "使用多个未在 :root 定义的 CSS 自定义属性，相关声明可能失效。"}, {"sev": "MED", "loc": "app/static/js/app.js:1", "text": "任务、转写、AI、审核、切片、字幕和配置行为集中在超大全局脚本，回归半径较大。"}, {"sev": "MED", "loc": "tests/test_publish_center_browser.py:16", "text": "Playwright 缺失时核心浏览器测试可静默跳过，字幕交互与鉴权失败路径覆盖不足。"}, {"sev": "LOW", "loc": "app/static/js/subtitle-editor.js:171", "text": "字幕编辑器已有 escapeHtml、虚拟列表、竞态 token 与自动保存版本控制，是可保留的正向实现。"}, {"sev": "LOW", "loc": "app/static/js/publish-center.js:4", "text": "前端明确只创建抖音任务，B站保留后端兼容；这是当前产品边界而非应机械删除的代码。"}]}, {"id": "api_runtime", "label": "API & Runtime", "band": "presentation", "path": "app/main.py + core/models/routers", "desc": "加载配置、初始化应用与安全中间件，并把页面/API 请求路由到业务服务。", "coupling": "core", "deps": ["media_storage", "transcription", "ai_selection", "task_review_cut", "subtitle", "pipeline_queue", "publish_center", "publish_scheduler", "persistence"], "loc": 2753, "score": 48, "grade": "D", "tags": ["fallback", "legacy", "dual-format", "bloat", "glue"], "findings": [{"sev": "HIGH", "loc": "app/routers/settings.py:10", "text": "GET /api/settings/ai 未做鉴权，返回 ai_config_service.get_ai_config_context() 中的原始 values；该上下文会从 .env/环境变量读取 API key、token 等 Secret，并同时返回 env_path。前端或本地恶意页面可直接读取凭据。"}, {"sev": "HIGH", "loc": "app/main.py:98", "text": "本地管理鉴权是可选的：只有 LOCAL_ADMIN_TOKEN 非空时才校验写请求；配置默认值为空，因此未配置 Token 时所有 POST/PUT/PATCH/DELETE API 均可被无认证调用。"}, {"sev": "HIGH", "loc": "app/routers/files.py:9", "text": "未鉴权的 /api/files/browse 调用 browse_video_directory，虽限制了根目录和路径穿越，但仍枚举 configured allowed roots 下的目录名、文件名、绝对路径、父路径和文件大小，造成本地媒体元数据泄露。"}, {"sev": "HIGH", "loc": "app/routers/tasks.py:223", "text": "async 路由直接执行同步重任务：音频处理、转写、切片和任务详情 ffprobe 可阻塞 FastAPI event loop，影响无关请求。"}, {"sev": "MED", "loc": "app/routers/tasks.py:35", "text": "大量 async 路由直接调用同步数据库、文件和服务函数；仅少数入口使用 run_in_threadpool，异步边界不一致，容易出现请求串行化和响应抖动。"}, {"sev": "MED", "loc": "app/models/task.py:7-41", "text": "TaskStatus 同时保留大写自动流水线状态和小写 legacy 状态；任意状态跳跃虽已修复，但模型、旧页面和 API 客户端仍需兼容两套值。"}, {"sev": "MED", "loc": "app/routers/tasks.py:35; app/routers/publish.py:1", "text": "tasks.py 与 publish.py 聚合大量路由、异常映射、同步/异步调度和业务编排，新增流程的 blast radius 较大。"}]}, {"id": "media_storage", "label": "Media & Storage", "band": "processing", "path": "storage/media/FFmpeg services", "desc": "管理 E 盘任务目录、路径安全、素材预检、FFmpeg/FFprobe 与受控子进程。", "coupling": "high", "deps": ["persistence"], "loc": 1614, "score": 84, "grade": "B", "tags": ["legacy", "dual-format", "glue", "fallback", "silent-except"], "findings": [{"sev": "MED", "loc": "app/services/storage_service.py:840-846", "text": "move_task_directory_to_trash 明确传入 reserve=False，仍采用查询后检查目录的非原子分配；当前无运行时调用，属于遗留兼容入口，但未来恢复调用时仍可能并发复用同一回收站目录。"}, {"sev": "MED", "loc": "app/services/storage_service.py:361-367", "text": "通用 resolve_video_file_path 对已存在路径仍原样返回。媒体 HTTP 路由已增加任务边界，但 publish/auto-publish/subtitle/task 查询等非 HTTP 调用方仍可把数据库中的现有外部路径交给后续读取或上传逻辑。"}, {"sev": "LOW", "loc": "tests/test_storage_boundaries.py:14-32", "text": "新增边界测试没有覆盖任务目录数据库读取在 sqlite3.Error、锁定或损坏数据库下显式失败的回归；代码已有保护但证据不足。"}, {"sev": "LOW", "loc": "app/services/storage_service.py:257-300", "text": "reserve=True 会在数据库任务记录写入前创建目录；进程在预占后崩溃可能留下无数据库记录的空目录，虽不会覆盖数据，但会造成孤儿目录累积。"}]}, {"id": "transcription", "label": "Transcription", "band": "processing", "path": "transcript services", "desc": "提取音频，调用火山引擎或 faster-whisper，并以分块 checkpoint 生成时间戳转写。", "coupling": "high", "deps": ["media_storage", "persistence"], "loc": 1960, "score": 59, "grade": "D", "tags": ["fallback", "silent-except", "fake-output", "duplication", "god-component", "glue", "over-fit"], "findings": [{"sev": "HIGH", "loc": "app/services/transcript_workflow_service.py:317", "text": "transcript Markdown 存在即返回 completed，未校验源指纹、Provider、进度状态或文件完整性。"}, {"sev": "HIGH", "loc": "app/services/transcript_service.py:265", "text": "JobLeaseLostError 已显式透传，但 TranscriptCancelledError 仍会被统一包装为 RuntimeError，取消可能落成 failed。"}, {"sev": "HIGH", "loc": "app/services/transcript_service.py:516", "text": "远程分块请求每次使用随机 request id，缺少持久化幂等键和超时后结果确认，重试可能重复计费。"}, {"sev": "MED", "loc": "app/services/transcript_service.py:516", "text": "HTTP 429、Retry-After、网络瞬断和可恢复服务错误缺少专门退避策略。"}, {"sev": "MED", "loc": "app/services/transcript_service.py:556", "text": "响应 result.message 可能被当作 0-1 秒转写正文写入结果。"}, {"sev": "MED", "loc": "app/services/transcript_service.py:831", "text": "进度文件 IO/JSON 损坏时静默返回空字典，可能隐藏故障并触发重复执行。"}, {"sev": "MED", "loc": "app/services/transcript_workflow_service.py:224", "text": "运行和取消状态仍是进程内 set，多进程/重启时不能可靠去重或取消。"}, {"sev": "MED", "loc": "app/services/transcript_service.py:325", "text": "本地和远程转写复制分块、checkpoint、异常和进度循环，行为容易漂移。"}, {"sev": "MED", "loc": "app/services/transcript_service.py:1088", "text": "Provider/模型/设备为模块级可变全局，并发任务可能互相覆盖运行元数据。"}, {"sev": "MED", "loc": "app/services/transcript_service.py:83", "text": "约 1300 行文件混合 FFmpeg、本地模型、远程 HTTP、checkpoint、进度和 Markdown，职责过大。"}, {"sev": "LOW", "loc": "tests/test_long_live_foundation.py:65", "text": "已覆盖失租 checkpoint 和异常透传，仍缺取消、429/坏响应、重复计费与真实 Markdown 闭环。"}]}, {"id": "ai_selection", "label": "AI Selection", "band": "processing", "path": "AI providers and analyzers", "desc": "选择 Codex/远程/本地 Provider，解析不稳定 AI 输出并生成通用、综艺或长直播候选片段。", "coupling": "core", "deps": ["transcription", "persistence"], "loc": 4420, "score": 63, "grade": "C", "tags": ["fallback", "silent-except", "legacy", "dual-format", "stub", "fake-output", "bloat", "duplication", "god-component"], "findings": [{"sev": "HIGH", "loc": "app/services/ai_config_service.py:318", "text": "get_ai_config_context 返回含 AI/ASR Key 的完整 values，GET /api/settings/ai 无读取鉴权，页面也复用该上下文。"}, {"sev": "MED", "loc": "app/services/ai/ai_clip_service.py:4", "text": "generate_candidate_clips_placeholder 返回三条硬编码 ClipCandidate；虽当前无调用方，误接线会产生 fake output。"}, {"sev": "MED", "loc": "app/services/ai/ai_clip_analyzer.py:131", "text": "分段分析失败窗口被跳过，只要其他窗口有候选便返回；通用路径缺少最低覆盖率门槛。"}, {"sev": "MED", "loc": "app/services/ai/variety_comedy_analyzer.py:513", "text": "全局评审失败时隐式降级到扩展阶段评分，Provider 失败仍可形成候选。"}, {"sev": "MED", "loc": "app/services/ai/local_model_provider.py:19", "text": "fallback_protocol 对任意 AIProviderError 都执行第二协议，未区分限流、认证和协议错误，可能重复调用与计费。"}, {"sev": "MED", "loc": "app/services/ai_analysis_workflow_service.py:738", "text": "候选事务替换、JSON 文件和 run 历史分步持久化，后续失败会形成数据库与文件/历史不一致。"}, {"sev": "MED", "loc": "app/services/ai/long_live_talk_analyzer.py:427", "text": "checkpoint 更新无 run/lease/owner fencing，并发或旧进程恢复可能互相覆盖窗口状态。"}, {"sev": "MED", "loc": "app/services/ai_analysis_workflow_service.py:71", "text": "分析元文件不存在、损坏或读取异常时静默返回空字典，无法区分未分析与产物损坏。"}, {"sev": "LOW", "loc": "app/services/ai/ai_clip_analyzer.py:456", "text": "输出归一化同时接受多组历史字段并填大量默认值，兼容有效但维护成本高。"}, {"sev": "LOW", "loc": "app/services/ai_config_service.py:55", "text": "旧 AI_REMOTE 与新分析/发布配置并存，运行时还改写全局 settings，形成双路径。"}, {"sev": "MED", "loc": "app/services/ai_analysis_workflow_service.py:685", "text": "单文件集中 profile、Provider、状态、候选、文件、历史与恢复，模块回归半径大。"}, {"sev": "MED", "loc": "app/services/ai/ai_clip_analyzer.py:252", "text": "多个分析器重复偏好摘要、时间转换、默认字段和 AI 输出解析逻辑。"}, {"sev": "MED", "loc": "tests/test_split_services.py:200", "text": "缺少真实 Provider 成功路径、文件写入失败一致性、并发运行和旧 checkpoint 覆盖测试。"}, {"sev": "MED", "loc": "tests/test_codex_cli_provider.py:12", "text": "Provider 测试主要 monkeypatch，缺少 HTTP 429/500/超时和协议 fallback 重复调用边界。"}, {"sev": "LOW", "loc": "tests/test_variety_comedy_selection.py:291", "text": "算法分支覆盖较好，但真实三阶段 Provider、资源消耗和全局评审降级未由集成测试锁定。"}]}, {"id": "task_review_cut", "label": "Task Review & Cut", "band": "workflow", "path": "task and cut workflow services", "desc": "维护任务状态与视图，保存候选审核选择，生成切片版本并同步发送中心。", "coupling": "core", "deps": ["media_storage", "ai_selection", "publish_center", "persistence"], "loc": 3036, "score": 78, "grade": "B", "tags": ["god-component", "glue", "fallback", "dual-format", "legacy", "over-fit"], "findings": [{"sev": "HIGH", "loc": "app/services/task_service.py:458-485,594-616", "text": "任务详情默认执行无 timeout 的 ffprobe，且未捕获 OSError/Path.stat 异常；NAS、损坏或卡死媒体可能阻塞详情请求或返回 500。明确延期至 P1.4。"}, {"sev": "MED", "loc": "app/services/task_lifecycle_service.py:373-401; tests/test_task_state_machine.py:69-82", "text": "公共状态转换前置条件只检查数据库字段或路径字符串，不验证源视频、候选产物和活跃 output 文件真实存在。明确延期至 P1.4。"}, {"sev": "MED", "loc": "app/services/task_service.py:1-98,1220-1273; app/services/task_query_service.py:16-24", "text": "TaskService 仍集中承担大量业务、数据库和展示职责，并与 task_query_service 互相导入、保留包装函数，维护 blast radius 较大。建议作为 P2 延后拆分。"}, {"sev": "MED", "loc": "app/services/task_service.py:717-718", "text": "候选片段列表会直接解析每条历史时间字段，单条异常格式仍可能阻断整个审核列表。"}, {"sev": "LOW", "loc": "app/services/task_lifecycle_service.py:139-225", "text": "任务目录预占后若后续数据库写入失败，仍缺少统一释放空目录的补偿路径，可能留下少量孤儿目录。"}]}, {"id": "subtitle", "label": "Subtitle", "band": "processing", "path": "subtitle services", "desc": "维护字幕轨、不可变 revision、cue、AI 建议、渲染验证与自动流水线交付决定。", "coupling": "high", "deps": ["media_storage", "task_review_cut", "ai_selection", "persistence"], "loc": 2409, "score": 70, "grade": "C", "tags": ["fallback", "silent-except", "legacy", "bloat", "god-component", "monkeypatch"], "findings": [{"sev": "MED", "loc": "app/services/subtitle_data_service.py:352", "text": "手工 revision 的 active/base 检查在事务外，并发编辑可覆盖 active 选择。"}, {"sev": "MED", "loc": "app/services/subtitle_data_service.py:489", "text": "批准 revision 在事务外校验，并发或重放旧请求可回退 active 版本。"}, {"sev": "MED", "loc": "app/services/subtitle_data_service.py:135", "text": "source/clip track 先查后插，NULL output_clip_id 约束不足，并发可能重复源轨。"}, {"sev": "MED", "loc": "app/services/subtitle_auto_workflow_service.py:87", "text": "批量批准逐 clip 独立提交，Job 后创建；中途失败会留下部分批准。"}, {"sev": "MED", "loc": "app/services/subtitle_data_service.py:168", "text": "source revision 提交后逐 clip 独立同步，异常会形成混合版本。"}, {"sev": "MED", "loc": "app/services/subtitle_workflow_service.py:475", "text": "字幕 job 完成与激活分两次写入，迟到 worker 仍可能激活旧成片。"}, {"sev": "LOW", "loc": "app/services/subtitle_auto_workflow_service.py:273", "text": "auto_config_json 损坏时静默降为空并写回，可能丢弃其他配置。"}, {"sev": "MED", "loc": "app/services/subtitle_data_service.py:1045", "text": "字幕数据服务聚合 track、revision、cue、导入导出、波形和渲染辅助，回归半径大。"}, {"sev": "LOW", "loc": "app/services/subtitle_workflow_service.py:312", "text": "统一 revision 外仍保留旧调用方适配，存在历史口径漂移成本。"}, {"sev": "MED", "loc": "tests/test_subtitle_editor.py:189", "text": "缺并发 save/approve/ensure track 与批处理中途失败测试。"}, {"sev": "LOW", "loc": "tests/test_subtitle_auto_workflow.py:172", "text": "核心真实渲染在 FFmpeg/FFprobe 缺失时会跳过，异常 Provider 证据不足。"}, {"sev": "LOW", "loc": "app/services/subtitle_data_service.py:761", "text": "波形处理把完整 PCM 捕获到内存，超长媒体存在时长线性内存峰值。"}, {"sev": "LOW", "loc": "app/services/subtitle_data_service.py:1024", "text": "单条字幕文本可接近文件上限，放大渲染、导出和 Prompt 资源消耗。"}]}, {"id": "pipeline_queue", "label": "Pipeline & Job Queue", "band": "workflow", "path": "pipeline and workflow job services", "desc": "用 SQLite Job、Lease、Heartbeat、Checkpoint 和子进程串联长任务与自动流水线。", "coupling": "core", "deps": ["transcription", "ai_selection", "task_review_cut", "subtitle", "publish_center", "persistence"], "loc": 3350, "score": 88, "grade": "B", "tags": ["god-component", "bloat", "legacy", "glue", "over-fit"], "findings": [{"sev": "LOW", "loc": "app/services/pipeline_engine.py:977-1073", "text": "PUBLISH_JOB_CREATING 尚无专用 reconcile 分支，恢复主要依赖重复创建的幂等去重。"}, {"sev": "LOW", "loc": "tests/test_pipeline_checkpoint.py:358-625; tests/test_pipeline_state_stability.py:275-313", "text": "仍缺真实进程重启、lease 过期边界及发布内容证据变更的进程级回归测试。"}]}, {"id": "publish_center", "label": "Publish Center", "band": "workflow", "path": "publish content preparation services", "desc": "准备标题、简介、话题、封面、账号和发布草稿，并保留历史兼容执行入口。", "coupling": "core", "deps": ["task_review_cut", "subtitle", "publish_scheduler", "publisher_worker", "persistence"], "loc": 5593, "score": 52, "grade": "D", "tags": ["god-component", "bloat", "legacy", "dual-format", "fallback", "silent-except", "placeholder", "duplication"], "findings": [{"sev": "HIGH", "loc": "app/services/publish_service.py:570", "text": "_normalize_config/_normalize_account 仅新增 *_masked 字段，却保留 client_secret、access_token、refresh_token 原字段；GET /api/publish/platforms、/accounts 及保存配置/账号响应直接返回这些原始密钥，存在敏感凭据泄漏风险。"}, {"sev": "MED", "loc": "app/services/publish_service.py:266", "text": "publish_service.py 当前约4750行，混合配置/账号/OAuth、文案与封面、队列同步、历史、旧 OpenCLI 脚本、API Provider 和页面上下文，形成高耦合 God Component，任一发布流程改动的 blast radius 很大。"}, {"sev": "MED", "loc": "app/services/publish_service.py:2941", "text": "历史查询 SQL 只按 PUBLISH_HISTORY_STATUSES 的大写值过滤，之后才调用 _normalize_publish_status；LEGACY_STATUS_MAP 支持旧小写状态但旧记录会在 SQL 层被提前排除，历史页可能漏数据。"}, {"sev": "MED", "loc": "app/services/publish_service.py:2144", "text": "sync_task_publish_jobs 封面生成失败时只把 {'cover_error': ...} 放入 item_covers，仍继续插入 WAITING 任务且不计入 errors；同步可能返回 ok，但生成的任务实际无法通过 local_browser readiness。"}, {"sev": "MED", "loc": "app/services/publish_service.py:2787", "text": "create_batch_publish_jobs 对不存在的 output_clip_id 直接 continue，全部无效或部分无效时仍返回 status='ok'，调用方无法区分‘创建成功’与‘输入被静默丢弃’。"}, {"sev": "MED", "loc": "app/services/publish_readiness.py:167", "text": "publish_domain/create_publish_job 仍允许 api_publish，publishers registry 也保留兼容入口，但统一 readiness 只接受 local_browser/manual_export 并将 api_publish 标记 unsupported_publish_mode，持久化任务与调度契约不一致。"}, {"sev": "MED", "loc": "app/services/publish_providers.py:117", "text": "BilibiliPublishProvider 在完成配置和 token 校验后始终抛出 bilibili_provider_pending；api_publish 模式仍可创建/注册，因此这是已接线但必然失败的 placeholder 路径。"}, {"sev": "MED", "loc": "app/services/publish_providers.py:66", "text": "旧 Douyin API Provider 将 upload 与 create 分成两个无幂等键的请求；_request_json 只包装 HTTPError/URLError，平台已接收后网络超时或连接异常可能被判失败，重试会重复上传/投稿且没有 NEED_REVIEW 不确定态。"}, {"sev": "LOW", "loc": "app/services/publish_providers.py:204", "text": "_post_multipart 先 file_path.read_bytes() 再 b''.join(chunks)，完整视频和完整 multipart body 同时驻留内存，大文件发布存在约双倍峰值。"}, {"sev": "LOW", "loc": "app/services/publish_service.py:1569", "text": "_batch_find_publish_jobs 对每条记录直接调用 _normalize_job(row)，未传入预取 accounts；_normalize_job 会逐条触发 readiness/account 查询，发布中心批量切片时形成 N+1 查询。"}, {"sev": "LOW", "loc": "tests/test_publish_history.py:111", "text": "现有定向测试未覆盖原始 Secret/Token 响应、旧小写历史状态、同步封面 partial、批量无效 ID，以及 API 超时后已接收的重复投稿边界。"}]}, {"id": "publish_scheduler", "label": "Publish Scheduler", "band": "execution", "path": "scheduler/repository/executor", "desc": "计算排期、原子领取发布任务、重试、恢复不确定执行并维护发布状态机。", "coupling": "core", "deps": ["publish_center", "publisher_worker", "persistence"], "loc": 2329, "score": 71, "grade": "C", "tags": ["god-component", "bloat", "legacy", "silent-except"], "findings": [{"sev": "MED", "loc": "app/services/publish_scheduler.py:756-785", "text": "recover_interrupted_jobs 每轮加载全部 PUBLISHING 任务，并对每个任务串行查询 Worker，没有批量上限、并发控制或退避；Worker 不可用或卡住任务较多时，单轮耗时按任务数乘以网络超时增长，会延迟后续排期处理。"}, {"sev": "MED", "loc": "app/services/publish_scheduler.py:281-302", "text": "list_due_jobs 每轮 SELECT 全部 SCHEDULED 记录，再逐条在 Python 中解析时间；虽已有状态/排期索引，但没有 SQL due 条件、分页或批量上限，排期量增长后会增加扫描内存和调度延迟。"}, {"sev": "MED", "loc": "app/services/publish_scheduler.py:133-1788", "text": "PublishScheduler 约 1891 行、42 个方法，同时承担排期计算、任务领取、执行结果写回、Worker 恢复、重试修复、人工复核、批量排期和旧版兼容；职责边界过宽，修改任一状态路径的回归半径较大。"}, {"sev": "LOW", "loc": "app/services/publish_scheduler.py:274-279", "text": "shutdown 已能追踪并等待后台 Task，但没有超时或取消兜底；若当前 run_once 被数据库锁、Worker 串行查询或文件操作长期阻塞，应用优雅停机仍可能无限等待。"}, {"sev": "LOW", "loc": "app/services/publish_scheduler.py:1807-1812", "text": "queue_snapshot 对非法 scheduled_at 捕获 ValueError 后静默 pass；损坏排期会从“今日任务”视图中消失，未产生告警或错误计数，降低数据异常可见性。"}]}, {"id": "publisher_worker", "label": "Publishers & Worker", "band": "execution", "path": "publisher registry and Windows worker", "desc": "通过 Publisher Registry 和 Windows Chrome Worker 执行抖音/B站投稿、导出与兼容模式。", "coupling": "high", "deps": ["media_storage", "persistence"], "loc": 2699, "score": 76, "grade": "B", "tags": ["legacy", "glue", "silent-except", "fallback"], "findings": [{"sev": "MED", "loc": "scripts/publish_host_worker.py:321", "text": "_prior_job_execution_requires_review 扫描旧 execution journal 时，若 journal 缺少 identity 或已损坏，直接 continue；跨 execution 无法确认其 job_id 时不会阻断新 execution。旧 Worker 在上传后崩溃并留下无身份/损坏日志时，仍存在重复投稿边界。"}, {"sev": "LOW", "loc": "app/services/publishers/page_scripts.py:14", "text": "页面脚本入口仍通过延迟导入 publish_service 私有函数来转发大量 DOM 脚本；这是有意保留的兼容层，但形成 legacy glue，脚本变更仍会牵连 4750 行 God Service。"}, {"sev": "LOW", "loc": "app/services/publishers/browser_runtime.py:315", "text": "screenshot 捕获裸 Exception 后返回空字符串，截图失败不会进入发布结果或健康信号；发布可以继续但缺少关键诊断证据。"}, {"sev": "LOW", "loc": "scripts/opencli_host_bridge.py:74", "text": "旧 OpenCLIHostBridgeHandler 的 /run 处理器本身没有 Bearer Token 校验；当前 main 已转调受保护的 publish_host_worker，默认入口不再使用它，但保留的可直接实例化旧处理器仍会造成安全边界误解。"}, {"sev": "LOW", "loc": "tests/test_publish_worker_client.py:155", "text": "当前测试已覆盖双进程锁竞争、死进程锁回收和常规 execution fencing，但仍未覆盖无身份/损坏旧 journal 被跨 execution 扫描跳过、screenshot 失败信号及旧 bridge 处理器被直接启动时的鉴权边界。"}]}, {"id": "persistence", "label": "SQLite Persistence", "band": "persistence", "path": "app/db + backup services", "desc": "创建 SQLite Schema、执行启动时兼容迁移和索引，并提供 WAL 安全备份恢复。", "coupling": "core", "deps": [], "loc": 3678, "score": 73, "grade": "C", "tags": ["legacy", "dual-format", "bloat", "god-component", "glue"], "findings": [{"sev": "MED", "loc": "app/db/database.py:607-608", "text": "schema_migrations 账本迁移在旧版兼容迁移和多处 executescript（996、1071、1155、1231、1754、1780）完成并提交后才执行；若历史 helper 或账本迁移失败，前面的 Schema/DML 已持久化而账本事务回滚，init_db 仍存在可重试但非原子的半迁移边界。"}, {"sev": "MED", "loc": "scripts/backup_restore.py:305-383", "text": "备份包验证只检查 manifest、哈希、quick_check 和表计数，没有验证 PRAGMA foreign_key_check、schema_migrations 记录或关键 v2 唯一索引定义；结构上可读但业务约束不完整的备份仍可能被接受，恢复后才在启动阶段失败或触发迁移。"}, {"sev": "MED", "loc": "scripts/backup_restore.py:529-634", "text": "restore_backup_bundle 在替换 SQLite 文件前没有应用进程锁或活动连接闸门；服务仍运行时可原子替换数据库路径，现有连接可能继续指向旧 inode，而新连接指向恢复文件，形成恢复期间的双数据库视图。"}, {"sev": "LOW", "loc": "app/db/database.py:758", "text": "workflow_jobs 认领索引仍只有 status、next_attempt_at、created_at，没有包含 lease_expires_at；过期接管查询在队列增长或大量过期任务时可能扫描更多候选行，属于性能退化而非当前正确性故障。"}]}, {"id": "ops_delivery", "label": "Ops & Delivery", "band": "persistence", "path": "Docker/PowerShell/CI", "desc": "提供 Windows/Docker 启停、诊断、CI、发布门禁、Demo 与维护脚本。", "coupling": "med", "deps": ["api_runtime", "publisher_worker", "persistence"], "loc": 4347, "score": 68, "grade": "C", "tags": ["fallback", "legacy", "dual-format", "duplication", "bloat", "glue", "silent-except", "monkeypatch"], "findings": [{"sev": "MED", "loc": ".github/workflows/ci.yml:3", "text": "CI 仅监听 master push/PR；feature/docs 直接 push 不即时验证，问题延迟到开 PR。"}, {"sev": "MED", "loc": "scripts/start_docker_opencli.ps1:24", "text": "健康检查异常只警告不返回非零，服务失败也可能被调用方视为启动成功。"}, {"sev": "MED", "loc": "scripts/start.ps1:30", "text": "Demo 覆盖生效前先对正式 E 盘配置运行 doctor，新机/迁移机的隔离 Demo 可能被旧路径阻断。"}, {"sev": "MED", "loc": "scripts/start.ps1:71", "text": "Worker 启动异常被捕获后继续并报告工作台成功，发布能力不可用时易被误判完整健康。"}, {"sev": "HIGH", "loc": "scripts/migrate_task_dirs_to_project_names.py:211", "text": "任务目录迁移用非 WAL-aware 主库 copy，先移动目录再统一更新提交，无文件补偿，异常会让路径/DB 不一致。"}, {"sev": "MED", "loc": "scripts/restore.ps1:27", "text": "恢复只以健康响应判断 App 运行，StopServices 只停 Compose；native/异常健康进程可能仍持有 DB 时执行替换。"}, {"sev": "MED", "loc": "scripts/backup.ps1:33", "text": "备份默认包含 .env 且不加密，仅显式 ExcludeEnv 才排除，包被共享时泄漏本机秘密。"}, {"sev": "MED", "loc": "tests/test_native_scripts.py:11", "text": "启停测试主要是源码字符串断言，Windows smoke 不做实际 restore/冲突/清理失败与恢复后健康验证。"}, {"sev": "MED", "loc": "scripts/seed_demo_data.py:32", "text": "缺 FFmpeg 时仍插入无媒体路径 Demo 数据并成功退出，数量检查通过但媒体 smoke 不可信。"}, {"sev": "LOW", "loc": "scripts/acceptance.ps1:115", "text": "验收递归扫描正式任务目录，媒体量大/锁文件会显著拖慢或阻断 release gate。"}, {"sev": "LOW", "loc": "scripts/backup_restore_runtime.py:142", "text": "import 时 monkeypatch backup core，全局行为依赖导入顺序。"}, {"sev": "LOW", "loc": "docs/PORTABLE_SETUP.md:127", "text": "文档描述与当前 start.ps1 实现不符，旧 Next Steps 又保留兼容入口，启动排障认知漂移。"}]}]};
 const M = DATA.modules || [];
 const BANDS = DATA.bands || [];
 const SPINE = DATA.spine || [];
diff --git a/.codemap/codemap.md b/.codemap/codemap.md
index 4fd130d..b271bbc 100644
--- a/.codemap/codemap.md
+++ b/.codemap/codemap.md
@@ -7,7 +7,7 @@
 
 > **Interactive view:** [`.codemap/codemap.html`](codemap.html) — per-module scores, findings, LoC, and the dependency graph. This file is the written report.
 
-**Generated:** 2026-08-24 · **Modules:** 13 · **Size:** 51786 tracked LoC across 132 files
+**Generated:** 2026-08-24 · **Modules:** 13 · **Size:** 52028 tracked LoC across 132 files
 
 ## Health by layer
 
@@ -17,7 +17,7 @@
 | 业务编排 | 3 | 73 |
 | 媒体与 AI 处理 | 4 | 69 |
 | 外部执行边界 | 2 | 74 |
-| 持久化与运维 | 2 | 66 |
+| 持久化与运维 | 2 | 70 |
 
 ## Per-module lines of code & score
 
@@ -59,7 +59,7 @@ _LoC is the representative file/folder per module; folder-level modules overlap
 | Module | LoC | Score | Tags |
 |---|--:|:--|:--|
 | Ops & Delivery | 4,347 | 68 C | fallback, legacy, dual-format, duplication, bloat, glue, silent-except, monkeypatch |
-| SQLite Persistence | 3,436 | 64 C | silent-except, legacy, dual-format, bloat, god-component |
+| SQLite Persistence | 3,678 | 73 C | legacy, dual-format, bloat, god-component, glue |
 
 ## Worst offenders
 
@@ -67,16 +67,16 @@ _LoC is the representative file/folder per module; folder-level modules overlap
 - **Publish Center (52/D)** — app/services/publish_service.py:570: _normalize_config/_normalize_account 仅新增 *_masked 字段，却保留 client_secret、access_token、refresh_token 原字段；GET /api/publish/platforms、/accounts 及保存配置/账号响应直接返回这些原始密钥，存在敏感凭据泄漏风险。
 - **Transcription (59/D)** — app/services/transcript_workflow_service.py:317: transcript Markdown 存在即返回 completed，未校验源指纹、Provider、进度状态或文件完整性。
 - **AI Selection (63/C)** — app/services/ai_config_service.py:318: get_ai_config_context 返回含 AI/ASR Key 的完整 values，GET /api/settings/ai 无读取鉴权，页面也复用该上下文。
-- **SQLite Persistence (64/C)** — app/db/database.py:628-671: _create_indexes 先删除 uq_publish_jobs_active_clip_platform_mode，随后对所有索引创建统一捕获 sqlite3.Error 并静默忽略；唯一部分索引创建失败时，旧索引已删除且无告警，活动发布任务可能失去唯一约束并产生重复记录。
 - **Frontend UI (65/C)** — app/static/js/app.js:211: 多个写请求绕过统一 apiFetch；启用 LOCAL_ADMIN_TOKEN 时可能缺失 Authorization 并被 API 拒绝。
 - **Ops & Delivery (68/C)** — scripts/migrate_task_dirs_to_project_names.py:211: 任务目录迁移用非 WAL-aware 主库 copy，先移动目录再统一更新提交，无文件补偿，异常会让路径/DB 不一致。
 - **Subtitle (70/C)** — app/services/subtitle_data_service.py:352: 手工 revision 的 active/base 检查在事务外，并发编辑可覆盖 active 选择。
 - **Publish Scheduler (71/C)** — app/services/publish_scheduler.py:756-785: recover_interrupted_jobs 每轮加载全部 PUBLISHING 任务，并对每个任务串行查询 Worker，没有批量上限、并发控制或退避；Worker 不可用或卡住任务较多时，单轮耗时按任务数乘以网络超时增长，会延迟后续排期处理。
+- **SQLite Persistence (73/C)** — app/db/database.py:607-608: schema_migrations 账本迁移在旧版兼容迁移和多处 executescript（996、1071、1155、1231、1754、1780）完成并提交后才执行；若历史 helper 或账本迁移失败，前面的 Schema/DML 已持久化而账本事务回滚，init_db 仍存在可重试但非原子的半迁移边界。
 - **Publishers & Worker (76/B)** — scripts/publish_host_worker.py:321: _prior_job_execution_requires_review 扫描旧 execution journal 时，若 journal 缺少 identity 或已损坏，直接 continue；跨 execution 无法确认其 job_id 时不会阻断新 execution。旧 Worker 在上传后崩溃并留下无身份/损坏日志时，仍存在重复投稿边界。
 
 ## All findings
 
-### HIGH (14)
+### HIGH (13)
 
 - **Frontend UI** · `app/static/js/app.js:211` — 多个写请求绕过统一 apiFetch；启用 LOCAL_ADMIN_TOKEN 时可能缺失 Authorization 并被 API 拒绝。
 - **Frontend UI** · `app/static/js/app.js:1729` — 接口或任务数据直接拼接到 innerHTML；publish-center.js:2152 有同类路径，存在本地 DOM XSS/页面结构破坏风险。
@@ -90,10 +90,9 @@ _LoC is the representative file/folder per module; folder-level modules overlap
 - **AI Selection** · `app/services/ai_config_service.py:318` — get_ai_config_context 返回含 AI/ASR Key 的完整 values，GET /api/settings/ai 无读取鉴权，页面也复用该上下文。
 - **Task Review & Cut** · `app/services/task_service.py:458-485,594-616` — 任务详情默认执行无 timeout 的 ffprobe，且未捕获 OSError/Path.stat 异常；NAS、损坏或卡死媒体可能阻塞详情请求或返回 500。明确延期至 P1.4。
 - **Publish Center** · `app/services/publish_service.py:570` — _normalize_config/_normalize_account 仅新增 *_masked 字段，却保留 client_secret、access_token、refresh_token 原字段；GET /api/publish/platforms、/accounts 及保存配置/账号响应直接返回这些原始密钥，存在敏感凭据泄漏风险。
-- **SQLite Persistence** · `app/db/database.py:628-671` — _create_indexes 先删除 uq_publish_jobs_active_clip_platform_mode，随后对所有索引创建统一捕获 sqlite3.Error 并静默忽略；唯一部分索引创建失败时，旧索引已删除且无告警，活动发布任务可能失去唯一约束并产生重复记录。
 - **Ops & Delivery** · `scripts/migrate_task_dirs_to_project_names.py:211` — 任务目录迁移用非 WAL-aware 主库 copy，先移动目录再统一更新提交，无文件补偿，异常会让路径/DB 不一致。
 
-### MED (59)
+### MED (60)
 
 - **Frontend UI** · `app/templates/system_status.html:98` — 配置/API Key 字段进入 DOM，base.html:11 还承载本地管理 Token；需确认全链路始终掩码。
 - **Frontend UI** · `app/static/css/styles.css:870` — 使用多个未在 :root 定义的 CSS 自定义属性，相关声明可能失效。
@@ -144,8 +143,9 @@ _LoC is the representative file/folder per module; folder-level modules overlap
 - **Publish Scheduler** · `app/services/publish_scheduler.py:281-302` — list_due_jobs 每轮 SELECT 全部 SCHEDULED 记录，再逐条在 Python 中解析时间；虽已有状态/排期索引，但没有 SQL due 条件、分页或批量上限，排期量增长后会增加扫描内存和调度延迟。
 - **Publish Scheduler** · `app/services/publish_scheduler.py:133-1788` — PublishScheduler 约 1891 行、42 个方法，同时承担排期计算、任务领取、执行结果写回、Worker 恢复、重试修复、人工复核、批量排期和旧版兼容；职责边界过宽，修改任一状态路径的回归半径较大。
 - **Publishers & Worker** · `scripts/publish_host_worker.py:321` — _prior_job_execution_requires_review 扫描旧 execution journal 时，若 journal 缺少 identity 或已损坏，直接 continue；跨 execution 无法确认其 job_id 时不会阻断新 execution。旧 Worker 在上传后崩溃并留下无身份/损坏日志时，仍存在重复投稿边界。
-- **SQLite Persistence** · `app/db/database.py:31-617` — 数据库初始化依赖多个结构探针和缺列即 ALTER TABLE，没有 PRAGMA user_version、schema_migrations 或可追踪迁移版本；历史数据库的实际结构只能由当前代码反推。
-- **SQLite Persistence** · `app/db/database.py:754,1162` — 多个迁移函数使用 executescript，发布表迁移还会在数据规范化前提交新增列；后续失败时可能已持久化部分结构，init_db 不是原子升级。
+- **SQLite Persistence** · `app/db/database.py:607-608` — schema_migrations 账本迁移在旧版兼容迁移和多处 executescript（996、1071、1155、1231、1754、1780）完成并提交后才执行；若历史 helper 或账本迁移失败，前面的 Schema/DML 已持久化而账本事务回滚，init_db 仍存在可重试但非原子的半迁移边界。
+- **SQLite Persistence** · `scripts/backup_restore.py:305-383` — 备份包验证只检查 manifest、哈希、quick_check 和表计数，没有验证 PRAGMA foreign_key_check、schema_migrations 记录或关键 v2 唯一索引定义；结构上可读但业务约束不完整的备份仍可能被接受，恢复后才在启动阶段失败或触发迁移。
+- **SQLite Persistence** · `scripts/backup_restore.py:529-634` — restore_backup_bundle 在替换 SQLite 文件前没有应用进程锁或活动连接闸门；服务仍运行时可原子替换数据库路径，现有连接可能继续指向旧 inode，而新连接指向恢复文件，形成恢复期间的双数据库视图。
 - **Ops & Delivery** · `.github/workflows/ci.yml:3` — CI 仅监听 master push/PR；feature/docs 直接 push 不即时验证，问题延迟到开 PR。
 - **Ops & Delivery** · `scripts/start_docker_opencli.ps1:24` — 健康检查异常只警告不返回非零，服务失败也可能被调用方视为启动成功。
 - **Ops & Delivery** · `scripts/start.ps1:30` — Demo 覆盖生效前先对正式 E 盘配置运行 doctor，新机/迁移机的隔离 Demo 可能被旧路径阻断。
@@ -182,7 +182,7 @@ _LoC is the representative file/folder per module; folder-level modules overlap
 - **Publishers & Worker** · `app/services/publishers/browser_runtime.py:315` — screenshot 捕获裸 Exception 后返回空字符串，截图失败不会进入发布结果或健康信号；发布可以继续但缺少关键诊断证据。
 - **Publishers & Worker** · `scripts/opencli_host_bridge.py:74` — 旧 OpenCLIHostBridgeHandler 的 /run 处理器本身没有 Bearer Token 校验；当前 main 已转调受保护的 publish_host_worker，默认入口不再使用它，但保留的可直接实例化旧处理器仍会造成安全边界误解。
 - **Publishers & Worker** · `tests/test_publish_worker_client.py:155` — 当前测试已覆盖双进程锁竞争、死进程锁回收和常规 execution fencing，但仍未覆盖无身份/损坏旧 journal 被跨 execution 扫描跳过、screenshot 失败信号及旧 bridge 处理器被直接启动时的鉴权边界。
-- **SQLite Persistence** · `app/db/database.py:656-657` — workflow job claim 索引未覆盖 lease_expires_at；队列规模增大或过期任务集中时可能读取更多候选行，属于性能退化而非当前正确性故障。
+- **SQLite Persistence** · `app/db/database.py:758` — workflow_jobs 认领索引仍只有 status、next_attempt_at、created_at，没有包含 lease_expires_at；过期接管查询在队列增长或大量过期任务时可能扫描更多候选行，属于性能退化而非当前正确性故障。
 - **Ops & Delivery** · `scripts/acceptance.ps1:115` — 验收递归扫描正式任务目录，媒体量大/锁文件会显著拖慢或阻断 release gate。
 - **Ops & Delivery** · `scripts/backup_restore_runtime.py:142` — import 时 monkeypatch backup core，全局行为依赖导入顺序。
 - **Ops & Delivery** · `docs/PORTABLE_SETUP.md:127` — 文档描述与当前 start.ps1 实现不符，旧 Next Steps 又保留兼容入口，启动排障认知漂移。
diff --git a/.codemap/modules.json b/.codemap/modules.json
index 36c1902..da5c3d5 100644
--- a/.codemap/modules.json
+++ b/.codemap/modules.json
@@ -7,9 +7,9 @@
   "htmlPath": ".codemap/codemap.html",
   "mdPath": ".codemap/codemap.md",
   "spineDesc": "用户通过页面/API 创建素材任务，SQLite Job 驱动转写、AI 选片、审核切片和字幕，再由发送中心排期并交给 Windows Chrome Worker，所有状态与审计证据回写 SQLite。",
-  "tracked_loc": 51786,
+  "tracked_loc": 52028,
   "tracked_files": 132,
-  "rev": "a01f103c43916d25310254f6f8389e9fc9e52521"
+  "rev": "1689d59b1a28ea86a53aad31598bd5c5a213b95e"
  },
  "excludes": [
   ".venv/",
@@ -1022,42 +1022,42 @@
     "tests/test_database_backup_service.py",
     "tests/test_p1_1_db_performance.py"
    ],
-   "loc": 3436,
-   "contentHash": "11881e23de872fd56070da719c9ca72f8e8f23e1dead1b32b099f7a56adfbdcf",
-   "score": 64,
+   "loc": 3678,
+   "contentHash": "a287698b7e6863a8ed1ac68f163cb1dd8cf2969fb12d571b336fd39ca194e7ce",
+   "score": 73,
    "grade": "C",
    "tags": [
-    "silent-except",
     "legacy",
     "dual-format",
     "bloat",
-    "god-component"
+    "god-component",
+    "glue"
    ],
    "findings": [
     {
-     "sev": "HIGH",
-     "loc": "app/db/database.py:628-671",
-     "text": "_create_indexes 先删除 uq_publish_jobs_active_clip_platform_mode，随后对所有索引创建统一捕获 sqlite3.Error 并静默忽略；唯一部分索引创建失败时，旧索引已删除且无告警，活动发布任务可能失去唯一约束并产生重复记录。"
+     "sev": "MED",
+     "loc": "app/db/database.py:607-608",
+     "text": "schema_migrations 账本迁移在旧版兼容迁移和多处 executescript（996、1071、1155、1231、1754、1780）完成并提交后才执行；若历史 helper 或账本迁移失败，前面的 Schema/DML 已持久化而账本事务回滚，init_db 仍存在可重试但非原子的半迁移边界。"
     },
     {
      "sev": "MED",
-     "loc": "app/db/database.py:31-617",
-     "text": "数据库初始化依赖多个结构探针和缺列即 ALTER TABLE，没有 PRAGMA user_version、schema_migrations 或可追踪迁移版本；历史数据库的实际结构只能由当前代码反推。"
+     "loc": "scripts/backup_restore.py:305-383",
+     "text": "备份包验证只检查 manifest、哈希、quick_check 和表计数，没有验证 PRAGMA foreign_key_check、schema_migrations 记录或关键 v2 唯一索引定义；结构上可读但业务约束不完整的备份仍可能被接受，恢复后才在启动阶段失败或触发迁移。"
     },
     {
      "sev": "MED",
-     "loc": "app/db/database.py:754,1162",
-     "text": "多个迁移函数使用 executescript，发布表迁移还会在数据规范化前提交新增列；后续失败时可能已持久化部分结构，init_db 不是原子升级。"
+     "loc": "scripts/backup_restore.py:529-634",
+     "text": "restore_backup_bundle 在替换 SQLite 文件前没有应用进程锁或活动连接闸门；服务仍运行时可原子替换数据库路径，现有连接可能继续指向旧 inode，而新连接指向恢复文件，形成恢复期间的双数据库视图。"
     },
     {
      "sev": "LOW",
-     "loc": "app/db/database.py:656-657",
-     "text": "workflow job claim 索引未覆盖 lease_expires_at；队列规模增大或过期任务集中时可能读取更多候选行，属于性能退化而非当前正确性故障。"
+     "loc": "app/db/database.py:758",
+     "text": "workflow_jobs 认领索引仍只有 status、next_attempt_at、created_at，没有包含 lease_expires_at；过期接管查询在队列增长或大量过期任务时可能扫描更多候选行，属于性能退化而非当前正确性故障。"
     }
    ],
-   "auditedHash": "11881e23de872fd56070da719c9ca72f8e8f23e1dead1b32b099f7a56adfbdcf",
+   "auditedHash": "a287698b7e6863a8ed1ac68f163cb1dd8cf2969fb12d571b336fd39ca194e7ce",
    "auditedAt": "2026-08-24",
-   "auditedRev": ""
+   "auditedRev": "1689d59b1a28ea86a53aad31598bd5c5a213b95e"
   },
   {
    "id": "ops_delivery",
diff --git a/DEVELOPMENT_LOG.md b/DEVELOPMENT_LOG.md
index db15f37..3554d4b 100644
--- a/DEVELOPMENT_LOG.md
+++ b/DEVELOPMENT_LOG.md
@@ -1,5 +1,17 @@
 # Development Log
 
+## 2026-08-24 稳定 V1 P1.3c 数据库迁移账本与唯一索引 Fail-Closed
+
+- 新增 `schema_migrations` 账本；每条正式新迁移记录稳定 version、name、checksum 和完成时间，同版本定义漂移时拒绝启动。
+- 迁移执行使用 `BEGIN IMMEDIATE`，Schema 修改、不变量验证和账本写入同事务提交；失败会回滚且不会伪造成功记录，两个初始化进程共享一条迁移记录。
+- 发布活动任务唯一约束迁移到版本化 `uq_publish_jobs_active_clip_platform_mode_v2`；先检查 `DRAFT/WAITING/SCHEDULED/PUBLISHING/NEED_REVIEW` 重复组，再创建并验证新版索引，最后才删除旧索引。
+- 唯一索引缺失、定义漂移、旧索引残留、重复活动记录或 SQLite 索引错误均明确阻止启动；不再执行 `except sqlite3.Error: pass` 后继续无约束运行。
+- 历史库执行 P1.3c 写入前先使用 SQLite Online Backup 创建可移植快照；异常/缺列账本也先进入备份路径，再由账本结构验证拒绝迁移。
+- 新增 12 个隔离回归，覆盖重复初始化、并发迁移、checksum/Schema 漂移、异常账本、备份、失败历史兼容、活动重复数据、旧索引回滚保护和普通索引错误传播。
+- 正式 `workflow.sqlite3` 本轮只读预检：尚无 ledger、旧唯一索引仍存在、活动重复组为 0；未重启服务、未写入正式库，也未调用 AI、FFmpeg、Chrome、抖音或 B站。
+- 最终完整隔离测试 `663 passed`，Ruff、Python Compileall 与 `git diff --check` 全部通过。Codemap 独立复评将 `SQLite Persistence` 从 `64/C` 提升到 `73/C`，原 HIGH fail-open 与无账本 finding 已移除。
+- 诚实边界：启动期旧版列探测/`executescript` 仍是 pre-ledger compatibility，不能把全部历史迁移宣称为原子；备份恢复包的 FK/ledger/关键索引校验和运行中恢复闸门留待独立后续轮次。
+
 ## 2026-08-24 稳定 V1 P1.3b 自动流水线断点恢复
 
 - 新增 `auto_pipeline_step_v1` 版本化 checkpoint；每一步记录 `running/succeeded/failed`、连续完成前缀、输入基线和紧凑产物证据，不保存 Secret、Prompt、完整 AI payload 或大对象。
diff --git a/NEXT_STEPS.md b/NEXT_STEPS.md
index e849d5e..8a7e097 100644
--- a/NEXT_STEPS.md
+++ b/NEXT_STEPS.md
@@ -11,7 +11,7 @@
 - [x] P1.2b：Publish Job 使用现有 `execution_id` 完成所有写回 fencing，并让 Windows Publish Worker 对重复 execution 幂等；跨进程锁、恢复 fail-closed 和 Scheduler 优雅停机已覆盖。
 - [x] P1.3a：任务状态接口受控转换；Task/Job lease 代际一致；自动流水线取消恢复、READY 终态和关联发布清理明确；切片批次编号、输出目录、Task 终态和数据库激活原子化。
 - [x] P1.3b：自动流水线已增加版本化步骤 checkpoint、输入/产物证据、旧 Job 原位重试和重领恢复；已覆盖 AI、转写、切片、文案、排期与发布草稿的失效边界。
-- [ ] P1.3c：修复数据库唯一索引重建失败被静默吞掉的问题，并为幂等迁移增加可追踪版本与失败证据；不在本轮直接迁移活动库。
+- [x] P1.3c：已增加 `schema_migrations` 版本/checksum 账本、迁移前 Online Backup 和 fail-closed v2 活动发布唯一索引；重复数据、索引漂移或账本异常都会拒绝启动。本轮未直接迁移活动库。
 - [ ] P1.3d：处理字幕批准批次原子性、字幕/切片中断目录清理和剩余跨进程恢复边界。
 - [ ] P1.4：统一第三方 AI/FFmpeg 超时、错误 JSON、429/5xx 与重试幂等边界，并避免重复计费。
 - [ ] P1.5：在不扩大个人本地项目范围的前提下处理密钥日志、输入校验和本地管理员接口门禁。
@@ -25,6 +25,7 @@
 4. 修复前数据库备份位于 `data/backups/workflow-before-foreign-key-repair-20260824-130321-535723-35a0f972.sqlite3`，只有活动库无法通过完整性检查时才考虑恢复，不要直接覆盖当前数据库。
 5. P1B.1/P1B.2、P1.3a 与 P1.3b 代码及隔离测试均已完成；活动库尚未增加 `workflow_jobs.lease_token`，本轮也未重启正式服务。下一独立轮先确认没有活动 Workflow Job，再做在线备份、幂等迁移和正式重启烟测。
 6. P1.3b 不增加数据库列。合并并完成正式迁移/重启后，可用一条低风险测试任务在 AI 或切片完成后重启 Worker，确认同一 Job 从 checkpoint 续跑；不要点击真实发布，也不要用重要待发布素材做故障演练。
+7. P1.3c 对正式库只做了只读预检：当前无活动发布重复组，旧唯一索引仍在，尚未写入 `schema_migrations`。合并后的首次正式重启会先创建迁移备份再切换 v2 索引；应与尚未部署的 Workflow fencing Schema 一起安排受控迁移和重启验收，不要在服务运行中手工改索引。
 
 ## 2026-08-24 工程体检确认的原始整改顺序
 
diff --git a/PROJECT_AUDIT.md b/PROJECT_AUDIT.md
index d4a3210..cd19321 100644
--- a/PROJECT_AUDIT.md
+++ b/PROJECT_AUDIT.md
@@ -96,6 +96,19 @@ Codemap 独立复评结果：`Publish Scheduler 62→71（C）`、`Publishers &
 
 本轮没有新增数据库列、没有迁移活动库，也没有调用真实 AI、FFmpeg、Chrome、抖音或 B站。恢复语义是“有可验证证据时尽量避免重复”，不是跨 SQLite 与外部服务的严格 exactly-once：若 Provider 已计费但进程在任何 run/文件落盘前崩溃，系统无法证明该次结果，重试仍可能再次调用。数据库迁移 fail-open、第三方超时/429/错误 JSON、字幕批准批次和 Secret/本地管理接口仍属于 P1.3c～P1.5，因此项目成熟度继续维持 **可用 V1**，尚不提前改判为“稳定 V1”。
 
+## 0.6 P1.3c 数据库迁移可靠性状态（2026-08-24）
+
+| P1.3c 项目 | 结果 | 验证证据 |
+| --- | --- | --- |
+| 迁移账本 | 已封口 | `schema_migrations` 保存 version/name/checksum/applied_at；同版本 checksum 漂移、缺列或 version 非主键均拒绝继续。 |
+| 迁移事务 | 已封口（新迁移） | P1.3c 起每条注册迁移使用 `BEGIN IMMEDIATE`，Schema、验证和账本同事务提交；并发 runner 最终只有一条记录。 |
+| 唯一索引切换 | 已封口 | 先创建并验证 `_v2` 索引，再删除旧索引；失败回滚后旧索引仍在，不再出现无约束继续启动。 |
+| 重复与漂移 | 已封口 | 活动状态含 `NEED_REVIEW`；重复组不自动改写而是明确阻止迁移；索引缺失、错误定义和旧索引残留同样 fail closed。 |
+| 迁移前备份 | 已封口 | 已有数据库缺 ledger/v2 索引时，任何写入前先用 SQLite Online Backup 生成可移植快照；异常 ledger 也先备份再拒绝。 |
+| 活动库边界 | 未执行写入 | 只读预检显示 ledger 尚未落地、旧索引存在、活动重复组为 0；本轮没有重启正式服务或迁移正式库。 |
+
+Codemap 独立复评将 `SQLite Persistence` 从 **64/C 提升到 73/C**，原 HIGH“先删索引、重建失败静默吞掉”和 MED“没有迁移账本”均已移除。模块仍为 C：历史列探测和多处 `executescript` 继续属于 pre-ledger compatibility，不能保证整个旧库升级原子；备份恢复工具还缺 FK/ledger/关键索引验证与运行中服务闸门。P1.3c 已完成有限范围目标，但项目整体仍维持 **可用 V1**，下一轮按路线处理 P1.3d，而不是借机全面重写数据库层。
+
 ## 1. Executive Summary
 
 ### 结论
@@ -204,7 +217,7 @@ flowchart LR
 | Publish Center | 5,561 | Core | 52 | D | Secret 泄漏 + 最大 God Service + 多种隐式 partial |
 | Publish Scheduler | 1,754 | Core | 62 | C | 发布安全思想正确；execution fencing、后台 Task 和恢复竞态不足 |
 | Publisher Worker | 2,116 | High | 62 | C | 真实边界清楚；execution id 幂等/路径和 journal 脱敏不足 |
-| Persistence | 3,023 | Core | 63 | C | WAL/备份是优点；真实 FK 违规、迁移账本和索引错误处理是核心债 |
+| Persistence | 3,678 | Core | 73 | C | WAL/备份、迁移账本与关键索引 fail-closed 已具备；旧兼容迁移和恢复闸门仍是债务 |
 | Ops / Delivery | 4,347 | Medium | 68 | C | CI/脚本较完整；恢复、Demo fail-open、默认含 `.env` 和文档漂移 |
 
 Codemap 分数高于总健康度 59 分，是因为总健康度额外纳入了“活动数据库已经发生 FK 违规”和“测试误指真实库可整表删除”这两项运行态 P0 证据，而模块评分主要评价对应代码边界。
@@ -517,19 +530,19 @@ Sonar 官方说明：Python Coverage 需要先由外部测试工具生成报告
 | Blast Radius | 任务详情、审核、字幕和发送中心页面。 |
 | 推荐方案 | 动态文本统一 `textContent/createElement`；需要 HTML 的内容只接受白名单模板；所有 API 请求走同一封装并加超时/错误规范化。 |
 
-#### P1-10 启动迁移无版本账本，唯一索引创建失败被静默吞掉
+#### P1-10 启动迁移核心 fail-open（P1.3c 已完成，保留历史兼容边界）
 
 | 字段 | 内容 |
 | --- | --- |
-| 文件 / 位置 | `app/db/database.py:31-532,601-648,654-965` |
+| 文件 / 位置 | `app/db/database.py`；`scripts/backup_restore.py:305-383,529-634` |
 | 模块 | Persistence |
 | 来源 | Code Overhaul + Codemap |
-| 原因 | 启动时通过表/列探测执行迁移，没有 `user_version`/ledger；部分 `executescript` 会改变事务语义；活动发布唯一索引先删除再创建，所有 `sqlite3.Error` 被 `pass`。 |
-| 实际影响 | 升级失败可留下半迁移；重复历史数据导致唯一索引重建失败时，应用仍启动且不告警，后续可继续产生重复活动发布任务。 |
-| 发生概率 | 新库低；历史库/异常数据升级时中等。 |
-| 修改收益 / 成本 / 风险 | 收益高；成本中到高；风险高，不能直接改生产 Schema。 |
-| Blast Radius | 整个数据库和应用启动。 |
-| 推荐方案 | 先只增加可审计 migration ledger 和 preflight；每个版本独立 backup/verify；索引失败必须阻止相关功能或显式 degraded，不能静默继续。 |
+| 原因 | P1.3c 已建立 ledger、备份和 v2 索引 fail-closed；剩余问题是早期列探测/`executescript` 仍先于账本迁移执行，恢复包也未验证 FK/ledger/关键索引或阻止运行中替换。 |
+| 实际影响 | 新迁移不会再静默丢唯一约束；但非常旧的 Schema 在兼容 helper 中途失败仍可能留下可重试的部分结构，运行中恢复还可能形成新旧连接视图分离。 |
+| 发生概率 | 正常新库低；跨多个历史版本升级或运行中恢复时低到中。 |
+| 修改收益 / 成本 / 风险 | 核心收益已取得；剩余改造收益中高、成本高、风险高，应拆成独立恢复/legacy migration 轮次。 |
+| Blast Radius | 历史数据库升级与整库恢复，不影响正常业务请求路径。 |
+| 推荐方案 | 后续新 Schema 全部走现有 ledger；独立增加 restore 离线闸门和 FK/ledger/index 校验，再按版本逐步收编旧 helper，不做一次性全面重写。 |
 
 ### P2：有限范围逐步偿还
 
@@ -803,7 +816,7 @@ Sonar 没有发现原始 Token 响应、DOM XSS 和目录拼接，说明静态
 | P1.5 Task/Cut/Subtitle 状态与批次原子性 | 先合法转移表，再切片 run 和字幕批准批次；不改 UI 主流程 | 非法跳跃拒绝、并发 run、批次中途失败、旧 active 保留 | 每项独立提交；特性开关保留旧入口短期回退 |
 | P1.6 Transcription 正确性 | run/source 绑定、取消透传、损坏产物显式状态 | 大文件中部变化、旧文件、取消、进度 JSON 损坏、重启测试 | 旧 transcript 只降为历史，不删除 |
 | P1.7 AI 质量与成本门禁 | profile 覆盖率、partial 状态、错误分类、有限退避 | 429/500/超时/坏 JSON/部分窗口/重复调用次数测试 | 配置化门槛，可回滚到旧行为但保留日志 |
-| P1.8 Migration ledger 与索引不变量 | 只为未来迁移加版本账本/preflight；当前 Schema 不大改 | 旧库升级、半迁移、重复数据、索引失败应明确阻断 | 每版前备份；一个 migration 一次提交 |
+| P1.8 Migration ledger 与索引不变量（P1.3c 核心已完成） | 已为未来迁移增加版本/checksum 账本、备份和 v2 索引 preflight；旧 helper 暂留 | 重复数据、checksum/索引漂移、并发 runner 和失败回滚已覆盖 | 每版前备份；一个 migration 一次提交；旧 helper 后续逐条收编 |
 | P2.1 覆盖率与真实故障测试 | 加 Coverage；先锁 P0/P1 核心模块，不追漂亮总百分比 | CI 产 `coverage.xml`，Sonar 能导入；核心门槛不得下降 | 移除阈值不影响生产代码 |
 | P2.2 可观测性 | readiness、Job/Worker 错误码、受控 stderr、fallback 日志 | DB/Worker/FFmpeg 故障时状态明确且不泄密 | 回滚观测层，无数据迁移 |
 | P2.3 Publish Service 渐进拆分 | 先 Secret DTO/query，再内容准备，再 job，最后 legacy adapter | 每轮 API contract、发布状态机和浏览器测试全过 | 一轮一个提交，旧 facade 保持接口 |
diff --git a/STABILITY_P1_DATABASE_MIGRATION_TASK.md b/STABILITY_P1_DATABASE_MIGRATION_TASK.md
new file mode 100644
index 0000000..c74d339
--- /dev/null
+++ b/STABILITY_P1_DATABASE_MIGRATION_TASK.md
@@ -0,0 +1,87 @@
+# P1.3c 数据库迁移账本与唯一索引 Fail-Closed
+
+## 背景
+
+当前 `init_db()` 通过表结构探测、`ALTER TABLE` 和 `executescript()` 兼容历史数据库，但没有可查询的迁移版本账本。更高风险的是 `_create_indexes()` 会先删除发布任务的活动唯一索引，再静默吞掉所有索引创建异常；一旦重建失败，应用仍会启动并允许重复活动发布任务进入数据库。
+
+## 本轮目标
+
+1. 建立最小、可扩展的 `schema_migrations` 迁移账本。
+2. 每条新迁移记录稳定版本、名称、校验和与完成时间。
+3. 版本相同但校验和变化时拒绝启动，避免迁移定义被静默改写。
+4. 发布活动任务唯一索引采用“先建立并验证新版索引，再删除旧索引”的顺序。
+5. 索引缺失、定义漂移、重复数据或 SQLite 异常时明确失败，不再静默继续运行。
+6. 迁移执行与账本写入位于同一 SQLite 事务中；失败不写成功记录。
+7. 已有数据库在 P1.3c 首次写入前创建 SQLite Online Backup；备份失败则不开始迁移。
+
+## 允许修改
+
+- `app/db/database.py`
+- 新增与本轮直接相关的隔离数据库测试
+- `DEVELOPMENT_LOG.md`
+- `NEXT_STEPS.md`
+- `PROJECT_AUDIT.md`
+- `.codemap/*`
+- 本任务说明
+
+## 禁止修改
+
+- 不直接运行或迁移正式 `workflow.sqlite3`。
+- 不删除、合并或自动修复正式库中的历史发布记录。
+- 不修改业务状态机、发布调度、Provider、Worker 或页面逻辑。
+- 不引入 Alembic 或其他新依赖，不重写全部历史兼容迁移。
+- 不处理 P1.4 Provider 超时或 P1.5 Secret/Auth。
+
+## 已确定实现要求
+
+### 迁移账本
+
+- `schema_migrations.version` 为主键，并保存 `name`、`checksum`、`applied_at`。
+- P1.3c 及后续正式 Schema 变更必须通过有序迁移注册表执行。
+- 已应用迁移必须校验 checksum 和数据库不变量；不能只看到版本号就假定成功。
+- 账本只记录完整成功的迁移，不把失败尝试伪装成已应用。
+- 旧的列探测兼容逻辑本轮保留，并明确视为 pre-ledger compatibility，不宣称已经完成全面 Alembic 化。
+
+### 唯一索引
+
+- 新版索引使用独立版本化名称，约束同一 `output_clip_id + platform + publish_mode` 只能存在一条活动发布任务。
+- 活动状态继续包括 `DRAFT`、`WAITING`、`SCHEDULED`、`PUBLISHING`、`NEED_REVIEW`。
+- 新索引创建和定义验证成功前，不删除旧版保护索引。
+- 发现活动重复数据时拒绝迁移，并返回不包含 Secret 的诊断信息；不擅自决定保留或取消哪条发布记录。
+- 已应用迁移启动时仍验证索引存在、唯一性和定义，防止手工删索引或 Schema 漂移后继续运行。
+
+### 事务与并发
+
+- 每条账本迁移通过 `BEGIN IMMEDIATE` 串行化。
+- Schema 修改、验证和账本写入同事务提交；任一步失败全部回滚。
+- 两个本地进程同时初始化同一库时，后到进程应读取已完成账本，而不是重复写入或吞掉锁错误。
+
+## 验收标准
+
+1. 新建隔离库初始化后恰有一条 P1.3c 迁移记录，重复初始化不新增记录。
+2. 新版唯一索引存在且旧版索引已在成功后移除。
+3. 迁移 checksum 漂移时明确拒绝启动。
+4. 已应用迁移的索引缺失或定义错误时明确拒绝启动。
+5. 活动重复数据导致索引无法建立时，启动失败、迁移不入账、数据不被自动改写。
+6. 模拟新版索引验证失败时，旧版索引仍存在，证明切换顺序和回滚有效。
+7. 索引列表中的其他 SQLite 异常不再被静默吞掉。
+8. 定向测试、完整 Pytest、Ruff、Compileall 通过；测试只使用临时数据库。
+9. 正式数据库文件的大小、mtime、hash 均不因本轮验证改变。
+
+## 测试命令
+
+```powershell
+.\.venv\Scripts\python.exe -m pytest -q tests/test_schema_migration_ledger.py tests/test_database_backup_service.py tests/test_publish_scheduler_state_machine.py tests/test_job_fencing.py tests/test_long_live_foundation.py
+.\.venv\Scripts\python.exe -m pytest -q
+.\.venv\Scripts\python.exe -m ruff check app tests
+.\.venv\Scripts\python.exe -m compileall -q app tests scripts
+```
+
+## 返回格式
+
+- 迁移账本与唯一索引切换方式。
+- 失败/漂移/重复数据的 fail-closed 证据。
+- 正式数据库未被修改的证据。
+- 定向与全量验证结果。
+- 仍保留的 pre-ledger 历史迁移边界。
+- Commit、分支、PR 与下一独立轮次。
diff --git a/app/db/database.py b/app/db/database.py
index 85e04d8..1d85095 100644
--- a/app/db/database.py
+++ b/app/db/database.py
@@ -1,8 +1,10 @@
+import hashlib
 import json
 import sqlite3
 from datetime import datetime
-from collections.abc import Iterator
+from collections.abc import Callable, Iterator
 from contextlib import contextmanager
+from dataclasses import dataclass
 
 from app.core.config import settings
 from app.services.database_backup_service import create_publish_migration_backup, create_schema_migration_backup
@@ -13,6 +15,46 @@
 VARIETY_AI_PROMPT_PATH = settings.project_root / "prompts" / "variety_interview_prompt_preset_002.txt"
 COMEDY_V2_AI_PROMPT_PATH = settings.project_root / "prompts" / "variety_comedy_v2_prompt.txt"
 
+PUBLISH_ACTIVE_UNIQUE_INDEX_LEGACY_NAME = "uq_publish_jobs_active_clip_platform_mode"
+PUBLISH_ACTIVE_UNIQUE_INDEX_NAME = "uq_publish_jobs_active_clip_platform_mode_v2"
+PUBLISH_UNIQUE_ACTIVE_STATUSES = (
+    "DRAFT",
+    "WAITING",
+    "SCHEDULED",
+    "PUBLISHING",
+    "NEED_REVIEW",
+)
+PUBLISH_UNIQUE_ACTIVE_STATUS_SQL = ", ".join(f"'{status}'" for status in PUBLISH_UNIQUE_ACTIVE_STATUSES)
+PUBLISH_ACTIVE_UNIQUE_INDEX_SQL = f"""
+CREATE UNIQUE INDEX IF NOT EXISTS {PUBLISH_ACTIVE_UNIQUE_INDEX_NAME}
+ON publish_jobs(output_clip_id, platform, publish_mode)
+WHERE status IN ({PUBLISH_UNIQUE_ACTIVE_STATUS_SQL})
+  AND output_clip_id IS NOT NULL AND output_clip_id <> ''
+""".strip()
+PUBLISH_ACTIVE_INDEX_MIGRATION_VERSION = "20260824_01_publish_active_unique_index_v2"
+PUBLISH_ACTIVE_INDEX_MIGRATION_NAME = "发布活动任务唯一索引安全切换"
+PUBLISH_ACTIVE_INDEX_MIGRATION_CHECKSUM = hashlib.sha256(
+    (
+        f"{PUBLISH_ACTIVE_INDEX_MIGRATION_VERSION}\n"
+        f"{PUBLISH_ACTIVE_INDEX_MIGRATION_NAME}\n"
+        f"{PUBLISH_ACTIVE_UNIQUE_INDEX_SQL}\n"
+        f"DROP INDEX {PUBLISH_ACTIVE_UNIQUE_INDEX_LEGACY_NAME}"
+    ).encode("utf-8")
+).hexdigest()
+
+
+class SchemaMigrationError(RuntimeError):
+    """数据库结构迁移或不变量验证失败。"""
+
+
+@dataclass(frozen=True)
+class SchemaMigration:
+    version: str
+    name: str
+    checksum: str
+    apply: Callable[[sqlite3.Connection], None]
+    verify: Callable[[sqlite3.Connection], None]
+
 
 @contextmanager
 def get_connection() -> Iterator[sqlite3.Connection]:
@@ -34,6 +76,9 @@ def init_db() -> None:
 
     needs_long_live_backup = _requires_long_live_schema_migration(settings.database_path)
     needs_workflow_fencing_backup = _requires_workflow_job_fencing_migration(settings.database_path)
+    needs_subtitle_editor_backup = _requires_subtitle_editor_schema_migration(settings.database_path)
+    needs_subtitle_auto_backup = _requires_subtitle_auto_schema_migration(settings.database_path)
+    needs_publish_index_backup = _requires_publish_active_index_migration(settings.database_path)
     if needs_long_live_backup:
         create_schema_migration_backup(
             settings.database_path,
@@ -46,18 +91,31 @@ def init_db() -> None:
             settings.data_dir / "backups",
             "workflow-job-fencing",
         )
-    if _requires_subtitle_editor_schema_migration(settings.database_path):
+    if needs_subtitle_editor_backup:
         create_schema_migration_backup(
             settings.database_path,
             settings.data_dir / "backups",
             "subtitle-editor-rebuild",
         )
-    if _requires_subtitle_auto_schema_migration(settings.database_path):
+    if needs_subtitle_auto_backup:
         create_schema_migration_backup(
             settings.database_path,
             settings.data_dir / "backups",
             "subtitle-auto-workflow",
         )
+    if needs_publish_index_backup and not any(
+        (
+            needs_long_live_backup,
+            needs_workflow_fencing_backup,
+            needs_subtitle_editor_backup,
+            needs_subtitle_auto_backup,
+        )
+    ):
+        create_schema_migration_backup(
+            settings.database_path,
+            settings.data_dir / "backups",
+            "publish-active-unique-index-v2",
+        )
 
     with get_connection() as connection:
         connection.executescript(
@@ -90,6 +148,13 @@ def init_db() -> None:
                 updated_at TEXT NOT NULL
             );
 
+            CREATE TABLE IF NOT EXISTS schema_migrations (
+                version TEXT PRIMARY KEY,
+                name TEXT NOT NULL,
+                checksum TEXT NOT NULL,
+                applied_at TEXT NOT NULL
+            );
+
             CREATE TABLE IF NOT EXISTS clip_candidates (
                 id TEXT PRIMARY KEY,
                 task_id TEXT NOT NULL,
@@ -540,6 +605,7 @@ def init_db() -> None:
         _seed_publish_platform_configs(connection)
         _create_indexes(connection)
         connection.commit()
+        _run_schema_migrations(connection)
 
 
 def _requires_long_live_schema_migration(database_path) -> bool:
@@ -617,6 +683,44 @@ def _requires_subtitle_auto_schema_migration(database_path) -> bool:
     } <= columns
 
 
+def _requires_publish_active_index_migration(database_path) -> bool:
+    """已有发布表尚未完成 P1.3c 迁移时，启动写入前先做可移植备份。"""
+    if not database_path.exists() or database_path.stat().st_size == 0:
+        return False
+    connection = None
+    try:
+        connection = sqlite3.connect(f"{database_path.resolve().as_uri()}?mode=ro", uri=True, timeout=10)
+        publish_table = connection.execute(
+            "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'publish_jobs'"
+        ).fetchone()
+        if publish_table is None:
+            return False
+        index_row = connection.execute(
+            "SELECT 1 FROM sqlite_master WHERE type = 'index' AND name = ?",
+            (PUBLISH_ACTIVE_UNIQUE_INDEX_NAME,),
+        ).fetchone()
+        ledger_table = connection.execute(
+            "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'schema_migrations'"
+        ).fetchone()
+        ledger_row = None
+        if ledger_table is not None:
+            try:
+                ledger_row = connection.execute(
+                    "SELECT 1 FROM schema_migrations WHERE version = ? AND checksum = ?",
+                    (
+                        PUBLISH_ACTIVE_INDEX_MIGRATION_VERSION,
+                        PUBLISH_ACTIVE_INDEX_MIGRATION_CHECKSUM,
+                    ),
+                ).fetchone()
+            except sqlite3.Error:
+                # 异常账本同样属于迁移风险：先要求备份，后续由结构验证给出明确错误。
+                return True
+        return index_row is None or ledger_row is None
+    finally:
+        if connection is not None:
+            connection.close()
+
+
 def _get_table_columns(connection: sqlite3.Connection, table_name: str) -> set[str]:
     rows = connection.execute(f"PRAGMA table_info({table_name})").fetchall()
     return {row["name"] for row in rows}
@@ -624,8 +728,6 @@ def _get_table_columns(connection: sqlite3.Connection, table_name: str) -> set[s
 
 def _create_indexes(connection: sqlite3.Connection) -> None:
     """创建常用查询索引（IF NOT EXISTS 语法兼容 SQLite 3.27+）。"""
-    # v1.4 的索引把 FAILED 也视为活动任务，导致无法为失败记录创建新的重试任务。
-    connection.execute("DROP INDEX IF EXISTS uq_publish_jobs_active_clip_platform_mode")
     indexes = [
         # 任务列表与状态筛选
         "CREATE INDEX IF NOT EXISTS idx_tasks_status_created ON tasks(status, created_at)",
@@ -658,18 +760,158 @@ def _create_indexes(connection: sqlite3.Connection) -> None:
         "CREATE INDEX IF NOT EXISTS idx_transcription_runs_task_active ON transcription_runs(task_id, is_active, updated_at)",
         "CREATE INDEX IF NOT EXISTS idx_transcription_chunks_run_status ON transcription_chunks(run_id, status, chunk_index)",
         "CREATE INDEX IF NOT EXISTS idx_ai_analysis_windows_resume ON ai_analysis_windows(task_id, transcript_fingerprint, provider, model, status, window_index)",
-        """CREATE UNIQUE INDEX IF NOT EXISTS uq_publish_jobs_active_clip_platform_mode
-           ON publish_jobs(output_clip_id, platform, publish_mode)
-           WHERE status IN ('DRAFT', 'WAITING', 'SCHEDULED', 'PUBLISHING', 'NEED_REVIEW')
-             AND output_clip_id IS NOT NULL AND output_clip_id <> ''""",
         # OAuth state 过期清理
         "CREATE INDEX IF NOT EXISTS idx_oauth_states_expires ON oauth_states(expires_at)",
     ]
     for sql in indexes:
+        connection.execute(sql)
+
+
+def _normalize_schema_sql(sql: str | None) -> str:
+    normalized = " ".join(str(sql or "").strip().rstrip(";").lower().split())
+    return normalized.replace(" if not exists ", " ")
+
+
+def _ensure_schema_migrations_table(connection: sqlite3.Connection) -> None:
+    connection.execute(
+        """
+        CREATE TABLE IF NOT EXISTS schema_migrations (
+            version TEXT PRIMARY KEY,
+            name TEXT NOT NULL,
+            checksum TEXT NOT NULL,
+            applied_at TEXT NOT NULL
+        )
+        """
+    )
+    table_info = connection.execute("PRAGMA table_info(schema_migrations)").fetchall()
+    columns = {row[1] for row in table_info}
+    required_columns = {"version", "name", "checksum", "applied_at"}
+    missing_columns = sorted(required_columns - columns)
+    if missing_columns:
+        raise SchemaMigrationError(
+            "schema_migrations 账本结构不完整，缺少字段：" + ", ".join(missing_columns)
+        )
+    version_column = next(row for row in table_info if row[1] == "version")
+    if version_column[5] != 1:
+        raise SchemaMigrationError("schema_migrations.version 不是主键，已拒绝继续迁移")
+
+
+def _assert_no_duplicate_active_publish_jobs(connection: sqlite3.Connection) -> None:
+    rows = connection.execute(
+        f"""
+        SELECT output_clip_id, platform, publish_mode, COUNT(*) AS duplicate_count
+        FROM publish_jobs
+        WHERE status IN ({PUBLISH_UNIQUE_ACTIVE_STATUS_SQL})
+          AND output_clip_id IS NOT NULL AND output_clip_id <> ''
+        GROUP BY output_clip_id, platform, publish_mode
+        HAVING COUNT(*) > 1
+        ORDER BY output_clip_id, platform, publish_mode
+        LIMIT 5
+        """
+    ).fetchall()
+    if not rows:
+        return
+    samples = "; ".join(
+        f"{row['output_clip_id']}/{row['platform']}/{row['publish_mode']} x{row['duplicate_count']}"
+        for row in rows
+    )
+    raise SchemaMigrationError(
+        "检测到重复的活动发布任务，拒绝建立唯一索引；请先人工核对后再迁移。示例：" + samples
+    )
+
+
+def _verify_publish_active_unique_index(connection: sqlite3.Connection) -> None:
+    row = connection.execute(
+        "SELECT sql FROM sqlite_master WHERE type = 'index' AND name = ?",
+        (PUBLISH_ACTIVE_UNIQUE_INDEX_NAME,),
+    ).fetchone()
+    if row is None:
+        raise SchemaMigrationError(
+            f"关键唯一索引 {PUBLISH_ACTIVE_UNIQUE_INDEX_NAME} 不存在，已拒绝启动"
+        )
+    actual_sql = row["sql"] if isinstance(row, sqlite3.Row) else row[0]
+    if _normalize_schema_sql(actual_sql) != _normalize_schema_sql(PUBLISH_ACTIVE_UNIQUE_INDEX_SQL):
+        raise SchemaMigrationError(
+            f"关键唯一索引 {PUBLISH_ACTIVE_UNIQUE_INDEX_NAME} 定义发生漂移，已拒绝启动"
+        )
+
+
+def _verify_publish_active_unique_index_migration(connection: sqlite3.Connection) -> None:
+    _verify_publish_active_unique_index(connection)
+    legacy_row = connection.execute(
+        "SELECT 1 FROM sqlite_master WHERE type = 'index' AND name = ?",
+        (PUBLISH_ACTIVE_UNIQUE_INDEX_LEGACY_NAME,),
+    ).fetchone()
+    if legacy_row is not None:
+        raise SchemaMigrationError(
+            f"旧版唯一索引 {PUBLISH_ACTIVE_UNIQUE_INDEX_LEGACY_NAME} 仍存在，迁移未完整完成"
+        )
+
+
+def _apply_publish_active_unique_index_migration(connection: sqlite3.Connection) -> None:
+    # 先建立和验证新版索引；任一步失败时旧版索引仍保留在同一事务中。
+    _assert_no_duplicate_active_publish_jobs(connection)
+    connection.execute(PUBLISH_ACTIVE_UNIQUE_INDEX_SQL)
+    _verify_publish_active_unique_index(connection)
+    connection.execute(f"DROP INDEX IF EXISTS {PUBLISH_ACTIVE_UNIQUE_INDEX_LEGACY_NAME}")
+
+
+def _registered_schema_migrations() -> tuple[SchemaMigration, ...]:
+    return (
+        SchemaMigration(
+            version=PUBLISH_ACTIVE_INDEX_MIGRATION_VERSION,
+            name=PUBLISH_ACTIVE_INDEX_MIGRATION_NAME,
+            checksum=PUBLISH_ACTIVE_INDEX_MIGRATION_CHECKSUM,
+            apply=_apply_publish_active_unique_index_migration,
+            verify=_verify_publish_active_unique_index_migration,
+        ),
+    )
+
+
+def _run_schema_migrations(connection: sqlite3.Connection) -> None:
+    """串行执行有账本的新迁移；历史列探测迁移继续作为兼容层保留。"""
+    if connection.in_transaction:
+        raise SchemaMigrationError("执行账本迁移前存在未提交事务，已拒绝继续")
+
+    for migration in _registered_schema_migrations():
+        version = migration.version
         try:
-            connection.execute(sql)
-        except sqlite3.Error:
-            pass
+            connection.execute("BEGIN IMMEDIATE")
+            _ensure_schema_migrations_table(connection)
+            applied = connection.execute(
+                "SELECT name, checksum FROM schema_migrations WHERE version = ?",
+                (version,),
+            ).fetchone()
+            if applied is not None:
+                applied_checksum = applied["checksum"] if isinstance(applied, sqlite3.Row) else applied[1]
+                if applied_checksum != migration.checksum:
+                    raise SchemaMigrationError(
+                        f"迁移 {version} 的 checksum 与账本不一致，已拒绝启动"
+                    )
+                migration.verify(connection)
+                connection.commit()
+                continue
+
+            migration.apply(connection)
+            migration.verify(connection)
+            connection.execute(
+                """
+                INSERT INTO schema_migrations (version, name, checksum, applied_at)
+                VALUES (?, ?, ?, ?)
+                """,
+                (
+                    version,
+                    migration.name,
+                    migration.checksum,
+                    datetime.now().astimezone().isoformat(timespec="seconds"),
+                ),
+            )
+            connection.commit()
+        except Exception as exc:
+            connection.rollback()
+            if isinstance(exc, SchemaMigrationError):
+                raise
+            raise SchemaMigrationError(f"数据库迁移 {version} 执行失败：{exc}") from exc
 
 
 def _migrate_tasks_table(connection: sqlite3.Connection) -> None:
diff --git a/tests/test_schema_migration_ledger.py b/tests/test_schema_migration_ledger.py
new file mode 100644
index 0000000..acbec93
--- /dev/null
+++ b/tests/test_schema_migration_ledger.py
@@ -0,0 +1,316 @@
+import sqlite3
+from concurrent.futures import ThreadPoolExecutor
+from types import SimpleNamespace
+
+import pytest
+
+from app.db import database as database_module
+
+
+@pytest.fixture
+def isolated_database(monkeypatch, tmp_path):
+    data_dir = tmp_path / "data"
+    database_path = data_dir / "migration-ledger.sqlite3"
+    tasks_dir = tmp_path / "tasks"
+    test_settings = SimpleNamespace(
+        data_dir=data_dir,
+        database_path=database_path,
+        tasks_dir=tasks_dir,
+        publish_default_mode="local_browser",
+    )
+    monkeypatch.setattr(database_module, "settings", test_settings)
+    return database_path
+
+
+def _connect(database_path):
+    connection = sqlite3.connect(database_path, timeout=10)
+    connection.row_factory = sqlite3.Row
+    connection.execute("PRAGMA busy_timeout = 10000")
+    return connection
+
+
+def _index_names(connection):
+    return {
+        row["name"]
+        for row in connection.execute(
+            "SELECT name FROM sqlite_master WHERE type = 'index'"
+        ).fetchall()
+    }
+
+
+def test_init_records_migration_once_and_switches_unique_index(isolated_database):
+    database_module.init_db()
+    database_module.init_db()
+
+    with _connect(isolated_database) as connection:
+        migrations = connection.execute(
+            "SELECT version, name, checksum, applied_at FROM schema_migrations"
+        ).fetchall()
+        indexes = _index_names(connection)
+
+    assert len(migrations) == 1
+    assert migrations[0]["version"] == database_module.PUBLISH_ACTIVE_INDEX_MIGRATION_VERSION
+    assert migrations[0]["name"] == database_module.PUBLISH_ACTIVE_INDEX_MIGRATION_NAME
+    assert migrations[0]["checksum"] == database_module.PUBLISH_ACTIVE_INDEX_MIGRATION_CHECKSUM
+    assert migrations[0]["applied_at"]
+    assert database_module.PUBLISH_ACTIVE_UNIQUE_INDEX_NAME in indexes
+    assert database_module.PUBLISH_ACTIVE_UNIQUE_INDEX_LEGACY_NAME not in indexes
+
+
+def test_checksum_drift_refuses_startup(isolated_database):
+    database_module.init_db()
+    with _connect(isolated_database) as connection:
+        connection.execute(
+            "UPDATE schema_migrations SET checksum = 'tampered' WHERE version = ?",
+            (database_module.PUBLISH_ACTIVE_INDEX_MIGRATION_VERSION,),
+        )
+        connection.commit()
+
+    with pytest.raises(database_module.SchemaMigrationError, match="checksum"):
+        database_module.init_db()
+
+
+def test_existing_database_is_backed_up_before_publish_index_migration(isolated_database):
+    database_module.init_db()
+    with _connect(isolated_database) as connection:
+        connection.execute(
+            "DELETE FROM schema_migrations WHERE version = ?",
+            (database_module.PUBLISH_ACTIVE_INDEX_MIGRATION_VERSION,),
+        )
+        connection.execute(
+            f"DROP INDEX {database_module.PUBLISH_ACTIVE_UNIQUE_INDEX_NAME}"
+        )
+        connection.commit()
+
+    database_module.init_db()
+
+    backups = list(
+        (isolated_database.parent / "backups").glob(
+            "workflow-before-publish-active-unique-index-v2-*.sqlite3"
+        )
+    )
+    assert len(backups) == 1
+
+
+def test_applied_migration_with_drifted_index_refuses_startup(isolated_database):
+    database_module.init_db()
+    with _connect(isolated_database) as connection:
+        connection.execute(
+            f"DROP INDEX {database_module.PUBLISH_ACTIVE_UNIQUE_INDEX_NAME}"
+        )
+        connection.execute(
+            f"CREATE UNIQUE INDEX {database_module.PUBLISH_ACTIVE_UNIQUE_INDEX_NAME} "
+            "ON publish_jobs(id)"
+        )
+        connection.commit()
+
+    with pytest.raises(database_module.SchemaMigrationError, match="定义发生漂移"):
+        database_module.init_db()
+
+
+def test_applied_migration_with_missing_index_refuses_startup(isolated_database):
+    database_module.init_db()
+    with _connect(isolated_database) as connection:
+        connection.execute(
+            f"DROP INDEX {database_module.PUBLISH_ACTIVE_UNIQUE_INDEX_NAME}"
+        )
+        connection.commit()
+
+    with pytest.raises(database_module.SchemaMigrationError, match="不存在"):
+        database_module.init_db()
+
+
+def test_applied_migration_with_legacy_index_refuses_startup(isolated_database):
+    database_module.init_db()
+    with _connect(isolated_database) as connection:
+        connection.execute(
+            f"""
+            CREATE UNIQUE INDEX {database_module.PUBLISH_ACTIVE_UNIQUE_INDEX_LEGACY_NAME}
+            ON publish_jobs(output_clip_id, platform, publish_mode)
+            WHERE status NOT IN ('PUBLISHED', 'EXPORTED', 'CANCELLED')
+              AND output_clip_id IS NOT NULL AND output_clip_id <> ''
+            """
+        )
+        connection.commit()
+
+    with pytest.raises(database_module.SchemaMigrationError, match="仍存在"):
+        database_module.init_db()
+
+
+def test_malformed_ledger_is_backed_up_then_rejected(isolated_database):
+    database_module.init_db()
+    with _connect(isolated_database) as connection:
+        connection.execute("DROP TABLE schema_migrations")
+        connection.execute("CREATE TABLE schema_migrations (version TEXT, name TEXT)")
+        connection.commit()
+
+    with pytest.raises(database_module.SchemaMigrationError, match="账本结构不完整"):
+        database_module.init_db()
+
+    backups = list(
+        (isolated_database.parent / "backups").glob(
+            "workflow-before-publish-active-unique-index-v2-*.sqlite3"
+        )
+    )
+    assert len(backups) == 1
+
+
+def test_unique_index_allows_failed_history_but_rejects_two_active_jobs(isolated_database):
+    database_module.init_db()
+    with _connect(isolated_database) as connection:
+        connection.executemany(
+            """
+            INSERT INTO publish_jobs (
+                id, task_id, output_clip_id, platform, publish_mode,
+                status, created_at, updated_at
+            ) VALUES (?, 'task-1', 'clip-1', 'douyin', 'local_browser', ?, ?, ?)
+            """,
+            [
+                ("failed-1", "FAILED", "2026-08-24T00:00:00+08:00", "2026-08-24T00:00:00+08:00"),
+                ("failed-2", "FAILED", "2026-08-24T00:01:00+08:00", "2026-08-24T00:01:00+08:00"),
+                ("active-1", "WAITING", "2026-08-24T00:02:00+08:00", "2026-08-24T00:02:00+08:00"),
+            ],
+        )
+        with pytest.raises(sqlite3.IntegrityError, match="UNIQUE constraint failed"):
+            connection.execute(
+                """
+                INSERT INTO publish_jobs (
+                    id, task_id, output_clip_id, platform, publish_mode,
+                    status, created_at, updated_at
+                ) VALUES (
+                    'active-2', 'task-1', 'clip-1', 'douyin', 'local_browser',
+                    'NEED_REVIEW', '2026-08-24T00:03:00+08:00', '2026-08-24T00:03:00+08:00'
+                )
+                """
+            )
+
+
+def test_duplicate_active_jobs_fail_without_data_rewrite_or_ledger_entry(isolated_database):
+    database_module.init_db()
+    with _connect(isolated_database) as connection:
+        connection.execute(
+            "DELETE FROM schema_migrations WHERE version = ?",
+            (database_module.PUBLISH_ACTIVE_INDEX_MIGRATION_VERSION,),
+        )
+        connection.execute(
+            f"DROP INDEX {database_module.PUBLISH_ACTIVE_UNIQUE_INDEX_NAME}"
+        )
+        connection.executemany(
+            """
+            INSERT INTO publish_jobs (
+                id, task_id, output_clip_id, platform, publish_mode,
+                status, created_at, updated_at
+            ) VALUES (?, 'task-1', 'clip-1', 'douyin', 'local_browser', ?, ?, ?)
+            """,
+            [
+                ("job-waiting", "WAITING", "2026-08-24T00:00:00+08:00", "2026-08-24T00:00:00+08:00"),
+                ("job-review", "NEED_REVIEW", "2026-08-24T00:01:00+08:00", "2026-08-24T00:01:00+08:00"),
+            ],
+        )
+        connection.commit()
+
+    with pytest.raises(database_module.SchemaMigrationError, match="重复的活动发布任务"):
+        database_module.init_db()
+
+    with _connect(isolated_database) as connection:
+        statuses = dict(
+            connection.execute(
+                "SELECT id, status FROM publish_jobs WHERE id IN ('job-waiting', 'job-review')"
+            ).fetchall()
+        )
+        ledger_count = connection.execute(
+            "SELECT COUNT(*) FROM schema_migrations WHERE version = ?",
+            (database_module.PUBLISH_ACTIVE_INDEX_MIGRATION_VERSION,),
+        ).fetchone()[0]
+        indexes = _index_names(connection)
+
+    assert statuses == {"job-waiting": "WAITING", "job-review": "NEED_REVIEW"}
+    assert ledger_count == 0
+    assert database_module.PUBLISH_ACTIVE_UNIQUE_INDEX_NAME not in indexes
+
+
+def test_new_index_verification_failure_preserves_legacy_index(
+    isolated_database,
+    monkeypatch,
+):
+    database_module.init_db()
+    with _connect(isolated_database) as connection:
+        connection.execute(
+            "DELETE FROM schema_migrations WHERE version = ?",
+            (database_module.PUBLISH_ACTIVE_INDEX_MIGRATION_VERSION,),
+        )
+        connection.execute(
+            f"DROP INDEX {database_module.PUBLISH_ACTIVE_UNIQUE_INDEX_NAME}"
+        )
+        connection.execute(
+            f"""
+            CREATE UNIQUE INDEX {database_module.PUBLISH_ACTIVE_UNIQUE_INDEX_LEGACY_NAME}
+            ON publish_jobs(output_clip_id, platform, publish_mode)
+            WHERE status NOT IN ('PUBLISHED', 'EXPORTED', 'CANCELLED')
+              AND output_clip_id IS NOT NULL AND output_clip_id <> ''
+            """
+        )
+        connection.commit()
+
+    def fail_verification(_connection):
+        raise database_module.SchemaMigrationError("simulated index verification failure")
+
+    monkeypatch.setattr(
+        database_module,
+        "_verify_publish_active_unique_index",
+        fail_verification,
+    )
+
+    with _connect(isolated_database) as connection:
+        with pytest.raises(database_module.SchemaMigrationError, match="simulated"):
+            database_module._run_schema_migrations(connection)
+
+    with _connect(isolated_database) as connection:
+        indexes = _index_names(connection)
+        ledger_count = connection.execute(
+            "SELECT COUNT(*) FROM schema_migrations WHERE version = ?",
+            (database_module.PUBLISH_ACTIVE_INDEX_MIGRATION_VERSION,),
+        ).fetchone()[0]
+
+    assert database_module.PUBLISH_ACTIVE_UNIQUE_INDEX_LEGACY_NAME in indexes
+    assert database_module.PUBLISH_ACTIVE_UNIQUE_INDEX_NAME not in indexes
+    assert ledger_count == 0
+
+
+def test_concurrent_migration_runners_share_one_ledger_entry(isolated_database):
+    database_module.init_db()
+    with _connect(isolated_database) as connection:
+        connection.execute(
+            "DELETE FROM schema_migrations WHERE version = ?",
+            (database_module.PUBLISH_ACTIVE_INDEX_MIGRATION_VERSION,),
+        )
+        connection.execute(
+            f"DROP INDEX {database_module.PUBLISH_ACTIVE_UNIQUE_INDEX_NAME}"
+        )
+        connection.commit()
+
+    def run_migration():
+        with _connect(isolated_database) as connection:
+            database_module._run_schema_migrations(connection)
+
+    with ThreadPoolExecutor(max_workers=2) as executor:
+        list(executor.map(lambda _: run_migration(), range(2)))
+
+    with _connect(isolated_database) as connection:
+        ledger_count = connection.execute(
+            "SELECT COUNT(*) FROM schema_migrations WHERE version = ?",
+            (database_module.PUBLISH_ACTIVE_INDEX_MIGRATION_VERSION,),
+        ).fetchone()[0]
+        indexes = _index_names(connection)
+
+    assert ledger_count == 1
+    assert database_module.PUBLISH_ACTIVE_UNIQUE_INDEX_NAME in indexes
+
+
+def test_noncritical_index_errors_are_not_silenced():
+    class FailingConnection:
+        def execute(self, _sql):
+            raise sqlite3.OperationalError("simulated index failure")
+
+    with pytest.raises(sqlite3.OperationalError, match="simulated index failure"):
+        database_module._create_indexes(FailingConnection())