fix(deploy): [skip-issue] 共享文档登录脚本迁移至 app/services/ 修复清理清单导致镜像内缺失

根因: 两脚本在 scripts/archive/ 子目录, 但 upgrade.sh 白名单 find 只保留 scripts/ 根目录
同名文件, .dockerignore 放行规则 !scripts/kdocs_login.py 也匹配不到 archive/ 路径,
导致 docker compose build 时脚本被排除, 镜像内根本没有 → 共享文档同步反复报
"未找到金山登录态"

修复:
- kdocs_login.py / tencent_doc_login.py 迁入 app/services/shared_doc_{kdocs,tencent}_cli.py
- 去掉 sys.path 注入, 直接 from app.core.config import settings
- upgrade.sh: 整个 backend/scripts/ 清空(不再需要按文件名白名单保留)
- .dockerignore: 删掉两条 scripts/ 登录脚本放行规则
- package.sh: 删掉追加登录脚本到 tar 的 staging 逻辑
- 服务层/错误提示/测试断言同步更新路径引用
- 旧文件删除

.dsh/skills/csctalon-management-effectiveness/SKILL.md

@@ -1,56 +0,0 @@
----
-name: csctalon-management-effectiveness
-description: CSCTalon 客服管理系统管理效果/管理闭环设计规范。定义例外管理、归因不归责、管理成本核算、周报自动化、预警驱动、绩效只汇总不扣分等模式,用于提升"符合管理效果"层面。发现"报表没人看/管理动作重/例外被淹没/绩效扣分争议/周报手工汇总"时使用。
-whenToUse: 设计管理看板、评审报表价值、规划绩效与预警、优化周报/复盘流程、梳理管理层体验时加载。
----
-
-# CSCTalon 管理效果/管理闭环设计规范
-
-> 定位: 系统是解决问题的, 不是制造麻烦的。管理层体验 = 看结果不翻过程、管例外不管全量、催闭环不催人。
-
-## 1. 例外管理(主管视角核心)
-
-- 主管首页只突出「需要动作」的项: 异常/超期/待回看/待审/积压, 正常数据折叠不打扰。
-- 看板默认口径: 红色=要处理, 黄色=快到期, 绿色=正常不显示。
-- 每个「例外」可一键跳转到处理页(详情/跟进/审核), 不要求主管跨页面拼信息。
-
-## 2. 归因不归责(数据真实的地基)
-
-- 投诉审计/退款挽回/绩效数据**只做分析汇总, 不做扣分依据**。
-- 审计结论用于改进流程, 不挂钩个人绩效扣罚。
-- 系统内任何"审计/评估"文案都强调改进导向, 避免逼人"优化数据"。
-
-## 3. 管理成本核算(砍掉没人看的报表)
-
-- 每张报表/看板必须回答: **谁看? 看完做什么决策?** 答不上就不上线。
-- 管理动作(登记/审计/跟进/报表)字段能简则简, 抓核心。
-- 已有报表定期审计: 使用频率低的合并/下线, 不累积僵尸页面。
-
-## 4. 周报/复盘自动化
-
-- 周报 10 项框架数据自动填充(接待/退款/投诉/措施/异常), 人只补结论。
-- 周例会只审到期措施 + 例外项, 不每周重复全量审。
-- 周报确认后固化快照, 可持续批注(活文档), 不下钻不强制派生报告。
-
-## 5. 预警驱动(让异常自己浮现)
-
-- 预警规则可配置(退款激增/工单积压/异常激增/投诉激增), 调度器定时扫描。
-- 预警进待办中心 + 通知中心, 人从"盯数据"变"确认预警"。
-- 预警幂等(同日同规则只一条), 避免刷屏。
-
-## 6. 绩效只汇总不扣分
-
-- 绩效看板呈现工作量/效率/成功率**汇总与趋势**(纵向比进步), 不排名惩罚。
-- 人效算法口径(专项难度系数/本职转接)文档化, 数据变化可追溯解释。
-- 不把投诉/异常数据直接折算进个人扣分。
-
-## 7. 管理效果评审清单(梳理管理层体验时逐项过)
-
-- [ ] 主管第一屏是否只突出例外(异常/超期/待审)?
-- [ ] 是否每个例外一键可达处理页?
-- [ ] 报表是否都能回答"谁看/看完做什么决策"?
-- [ ] 是否有没人看的僵尸报表可下线?
-- [ ] 周报是否自动填充、只补结论?
-- [ ] 预警是否驱动处理而非人工盯数据?
-- [ ] 绩效是否只汇总不扣分、口径可追溯?
-- [ ] 管理动作字段是否最简?

.dsh/skills/csctalon-ui-organization/SKILL.md

@@ -1,73 +0,0 @@
----
-name: csctalon-ui-organization
-description: CSCTalon 客服管理系统前端界面组织规范(Vue3+ElementPlus)。定义页面分层、四范式结构、菜单导航组织、状态色板、组件复用规则,用于新增页面与整体界面梳理。发现"界面组织混乱/菜单无序/风格不统一/组件重复"时使用。
-whenToUse: 新增前端页面、重构菜单导航、统一页面风格、评审界面组织合理性时加载。
----
-
-# CSCTalon 前端界面组织规范
-
-> 适用技术栈: Vue 3 + Vite + Element Plus + ECharts + Pinia。目标是"不培训就会用、新页面照模板拼装"。
-
-## 1. 页面分层(内容组织四层)
-
-任何页面按此四层组织,禁止跳层:
-
-1. **页头**: 页面标题(左) + 一句话副标题说明用途 + 主操作按钮(右, 右上角)。
-2. **筛选区**: 顶部卡片内放 FilterBar/筛选控件(状态/日期/关键词), 变更即刷新。
-3. **主体区**: 表格(列表页) 或 卡片栅格(看板页); 看板优先复用 dashboard 组件(KpiCard/ChartCard/SectionHeader)。
-4. **页脚区**: 分页 + 总数统计(列表页); 看板页可不设。
-
-## 2. 四大交互范式(页面模板)
-
-| 范式 | 结构 | 适用 |
-|------|------|------|
-| 列表页 | 页头 + 筛选 + 表格 + 分页 + 导出 + 右上主按钮 | 异常/标签/发票/政策/排班/知识库 |
-| 详情页 | 面包屑 + 元信息头(el-descriptions) + 主体 + 侧栏/底部时间线 | 异常详情/投诉审计/报告详情 |
-| 表单页 | 必填 ≤3 项置顶 + 其余折叠"更多" + 保存草稿/提交 | 所有登记 |
-| 导入页 | 模板下载 + 上传 + 预览复核 + 确认(回执成功/失败) | 标签批量/排班/发票 |
-
-## 3. 菜单与导航组织(侧边栏)
-
-- 一级菜单按角色可见性分层: 全员可见(运营看板/工作台/我的待办/数据中心/发票/知识库) → 管理层(决策看板/管理闭环) → 管理员(系统管理)。
-- 同一业务域的页面放同一子菜单(如 管理闭环: 报告/周报/措施/异常/排班/预警/跨部门), 不散落。
-- 菜单名与页面 title 一致; 命名避免歧义(如"设备专项标签"区别于"专项任务")。
-- 隐藏路由(hidden: true)用于详情页/跳转页, 不进菜单。
-
-## 4. 全局状态色板(统一语义)
-
-| 状态族 | 颜色 | 语义 |
-|--------|------|------|
-| 待处理/待审/待回看 | warning(黄) | 需要动作 |
-| 进行中/执行中 | primary(蓝) | 已启动 |
-| 已完成/生效/闭环 | success(绿) | 结束 |
-| 异常/失效/超期 | danger(红) | 需关注 |
-| 归档/废止 | info(灰) | 只读留存 |
-
-统一封装在 `web/src/utils/statusColor.js`(已存在), 页面禁止私写配色。
-
-## 5. 组件复用(禁止重复造轮子)
-
-- KPI 卡 → `KpiCard`; 图表卡 → `ChartCard` + `BaseChart`; 区块标题 → `SectionHeader`; 筛选条 → `FilterBar`; 三列队列 → `QueuePanel`。
-- 新页面先引入公共组件拼装, 禁止内联 KPI 卡/图表卡样式。
-- 需要新 props 时向后兼容扩展公共组件, 不在使用页私写覆盖类名。
-
-## 6. 角色化工作台(第一屏差异化)
-
-| 角色 | 第一屏 |
-|------|--------|
-| 系统管理员 | 全局 KPI + 系统告警 + 待审队列 |
-| 主管 | 全局 KPI + 例外清单(异常/超期/待回看) + 待审 |
-| 专项组长 | 本专项 KPI + 本专项待办 + 本组排班 |
-| 专员 | 本人待办 + 本人数据 + 被指派专项 |
-| 普通客服 | 待读政策 + 本人接待 + 提交发票入口 |
-
-## 7. 审核清单(梳理界面时逐项过)
-
-- [ ] 每个页面是否四层结构完整?
-- [ ] 是否落在四大范式之一?
-- [ ] 菜单是否按角色分层、业务归组、命名无歧义?
-- [ ] 状态色是否用统一色板?
-- [ ] 是否复用了公共组件而非内联样式?
-- [ ] 必填项是否 ≤3、其余折叠?
-- [ ] 空数据是否有 el-empty 提示?
-- [ ] 加载是否有 v-loading?

.dsh/skills/csctalon-workflow-design/SKILL.md

@@ -1,71 +0,0 @@
----
-name: csctalon-workflow-design
-description: CSCTalon 客服管理系统办公流程/工作流设计规范。定义状态机、统一待办中心、通知提醒、闭环分级、跨模块联动(异常→措施→回看)等设计模式,用于业务流程规划与评审。发现"流程断点/状态混乱/该闭环未闭环/待办分散/无提醒"时使用。
-whenToUse: 设计新业务流程、评审现有流程是否闭环、规划状态机与待办通知、梳理跨模块联动时加载。
----
-
-# CSCTalon 办公流程/工作流设计规范
-
-> 核心原则: 系统第一屏应「推着人走」而非「人到处找事」; 流程要闭环但分级, 不搞一刀切。
-
-## 1. 流程设计五问(任何新流程先回答)
-
-1. **谁发起?** 录入入口是否 ≤30 秒、能自动则自动?
-2. **谁处理?** 是否有明确负责人/接收人(缺省=进统一待办中心)?
-3. **什么状态?** 状态机是否线性可预期(待处理→处理中→已完成/闭环)?
-4. **何时提醒?** 到期/超期/新增是否有通知(站内信+角标)?
-5. **如何闭环?** 结束态是否明确(关闭/归档/回看), 结果是否可追溯?
-
-答不上的流程=不完整, 不上线。
-
-## 2. 状态机规范
-
-- 状态用 String 枚举(避免 SA Enum 迁移麻烦), Pydantic 层校验。
-- 状态流转线性的: `待处理 → 处理中 → 已完成` 为主轴; `挂起/驳回/退回` 为分支。
-- 每个状态变更落时间线记录(谁/何时/从哪到哪/备注), 复用跟进记录表。
-- 状态色统一用 `statusColor.js` 色板(黄=需动作/蓝=进行中/绿=结束/红=异常/灰=归档)。
-
-## 3. 统一待办中心(必做)
-
-- 汇聚所有「该我处理的事」: 待办事项 / 待跟进异常 / 待回看措施 / 待审发票报销 / 待读政策 / 被指派工单。
-- 每条带: 来源 + 优先级 + 截止 + 一键跳转; 按角色过滤(管理层看全部, 一线看本人)。
-- 新模块的"待处理"数据必须接入统一待办中心, 禁止散落各页面。
-
-## 4. 通知提醒(轻量站内信)
-
-- 触发点: 到期(措施回看/异常跟进)、新增(异常登记/政策发布/审计指派)、状态变化(审核通过/被驳回)。
-- 落 `notifications` 表(recipient_id/type/title/content/ref_type/ref_id/is_read), 前端角标 + 列表。
-- 局域网内站内信即可, 不做外部推送。
-
-## 5. 闭环分级(不过度管理)
-
-| 事项重要度 | 闭环要求 |
-|-----------|---------|
-| 小事/日常 | 一句跟进记录即闭环(记录>不记录) |
-| 中事/影响有限 | 跟进 + 状态流转 + 到期回看 |
-| 大事/影响大 | 完整流程: 登记 → 复盘 → 输出措施 → 到期回看 → 结论归档 |
-
-禁止对小事强制走完整流程(会逼人少登记, 数据失真)。
-
-## 6. 跨模块联动(推荐链路)
-
-```
-异常事故(登记+跟进)
-  ├─→ 转待办(todo_items)        当需要人执行
-  ├─→ 转管理措施(measures)       当需要持续改进/到期回看
-  └─→ 转跨部门派发(upstream)     当根因在上游
-投诉审计 → 审计结论 → 转管理措施
-政策发布 → 通知相关角色 + 关联知识库话术同步
-发票提交 → 主管审核 → 报销 → 导出
-```
-
-## 7. 流程评审清单(梳理流程时逐项过)
-
-- [ ] 五问是否全部可答?
-- [ ] 状态机是否线性可预期、流转落时间线?
-- [ ] 待处理项是否进统一待办中心?
-- [ ] 到期/新增是否有通知?
-- [ ] 结束态是否明确、可追溯?
-- [ ] 是否按重要度分级闭环而非一刀切?
-- [ ] 是否与异常/措施/待办/上游正确联动?
-- [ ] 录入是否 ≤30 秒、能自动则自动?

.env.example

@@ -38,6 +38,35 @@ JWT_ACCESS_TOKEN_EXPIRE_MINUTES=1440
 # 生产建议显式设置独立随机 key（先于 JWT 轮换生效），避免 JWT 轮换连带凭证失联
 CONFIG_ENCRYPTION_KEY=
 
+# ---------- 跨站免密入口：管理员 → netmgr 网络管理面板（工单 #187）----------
+# 本系统是签发方：管理员点入口 → 签 60 秒一次性 HMAC 票据 → 浏览器跳 netmgr 面板。
+# ⚠️ SSO_SHARED_SECRET 必须与 netmgr 侧 /opt/netmgr/.env 的 SSO_SHARED_SECRET 逐字符一致
+#    （openssl rand -hex 32 生成，两侧各存一份）。留空 = 免密入口关闭（不影响本系统登录）。
+SSO_SHARED_SECRET=
+# netmgr 面板对外地址；本地/ZT 调试可临时改 http://10.147.17.34:6080
+SSO_NETMGR_URL=https://panel.kimirock.top
+# 票据有效期（秒），须与 netmgr 侧 TTL 一致，勿随意调大
+SSO_TICKET_TTL_SECONDS=60
+# talon 算力通道管理台直链（仅前端放链接，走 talon 可信网段免密，不签票）
+# ⚠️ talon 没有公网入口，故给两个候选地址，前端按当前访问来源择一：
+#    从办公网打开本页 → 用 _LAN；否则（公网域名 / ZT）→ 用 _ZT
+#    两个都留空 = 不显示该入口。刻意不把它暴露到公网（见工单 #188）
+SSO_TALON_URL_LAN=http://192.168.10.21:4080
+SSO_TALON_URL_ZT=http://10.147.17.22:4080
+
+# ---------- 跨子域 SSO（反向：netmgr 面板 → 本系统）----------
+# 方向：本系统是消费方，netmgr 面板(panel.kimirock.top)是身份源。
+#   面板管理员登录后 → 面板签 60 秒 HMAC 票据 → 302 到本系统 /api/v1/auth/sso
+#   → 本系统验票 → 复用自身登录链路签 JWT → 引导页写 localStorage。
+# 与上方 SSO_SHARED_SECRET(本系统→面板方向)是两个独立密钥，不可混用。
+# ⚠️ NETMGR_SSO_SECRET 必须与 netmgr 侧 /opt/netmgr/.env 的 SSO_CSCTALON_SECRET 逐字符一致
+#    （openssl rand -hex 32 生成，两侧各存一份）。留空 = 反向 SSO 关闭(不影响本系统登录)。
+NETMGR_SSO_SECRET=
+# 面板 SSO 签票入口(无票/票据过期时回跳此地址重新签票)
+NETMGR_SSO_PANEL_URL=https://panel.kimirock.top/sso/csctalon
+# 票据 sub 映射的本系统账号(面板固定签此用户名，须与本系统已存在且 active 的账号一致)
+NETMGR_SSO_DEFAULT_USER=admin
+
 # ---------- 上传 ----------
 # 本地开发默认值 = 容器内相对路径(配合 compose 默认挂载 ./uploads:/app/uploads)。
 # ⚠️ docker-compose.yml backend environment 已显式注入容器内路径

.gitea/workflows/issue-close-on-merge.yml

@@ -71,6 +71,21 @@ jobs:
             exit 0
           fi
 
+          # ── O-11 (R-P2-15): A-20260903-001 §2.3 子工单判定 ──
+          # 父子工单在本仓库以「父单正文引用 #N」关联（见 docs/design/20260905-BMS工单草稿.md）。
+          # 规则: 父单正文引用的工单中仍有 open 者 → 仅评论不关闭; 全部 closed → 正常关闭。
+          # 实现: 独立脚本(避免 YAML block 内嵌多行 Python 的缩进陷阱), 输出逗号分隔的 open 引用号。
+          open_children=$(curl -s -H "Authorization: token ${GITEA_TOKEN}" "$api/issues/${issue_no}" \
+            | python3 scripts/ci_open_referenced_issues.py --api "$api" --exclude "${issue_no}" 2>/dev/null || true)
+          if [ -n "$open_children" ]; then
+            echo "⏸ 存在未关闭子工单/关联工单(#${open_children}), 仅评论不关闭"
+            curl -s -X POST -H "Authorization: token ${GITEA_TOKEN}" \
+              -H "Content-Type: application/json" \
+              -d "$(python3 -c "import json,sys; print(json.dumps({'body': sys.argv[1]}))" "${comment}（仍有未关闭关联工单：$(echo $open_children | sed 's/,/, #/g; s/^/#/')，暂不自动关闭）")" \
+              "$api/issues/${issue_no}/comments" > /dev/null
+            exit 0
+          fi
+
           # 关闭工单 + 评论
           echo "✅ 关闭工单 #${issue_no}"
           curl -s -X POST -H "Authorization: token ${GITEA_TOKEN}" \

.gitea/workflows/test.yml

@@ -4,7 +4,8 @@
 #    原 `uses:` 的 GitHub action(actions/checkout/setup-python/setup-node/cache)
 #    无法下载, job 卡死在 "Set up job"。改为纯本地 docker 执行:
 #    - checkout: runner(:host) 已自动 clone 代码到工作目录
-#    - 后端: docker run postgres:15(测试库) + docker run python:3.11-slim(pytest)
+#    - 后端: postgres:15 ×2(pytest 测试库 + 空库迁移门禁库) + python:3.11-slim
+#      (ruff app/+tests/ → 空库 alembic upgrade head → pytest)
 #    - 前端: docker run node:20(npm ci + lint + vitest)
 #    前提: 群晖可访问 docker hub(已验证 python:3.11-slim/gitleaks 可拉取)
 
@@ -17,6 +18,66 @@ on:
     branches: [main, master]
 
 jobs:
+  # #216/R-P2-9: 提交信息必须携带 #工单号（与本地 commit-msg 钩子共用 scripts/check-commit-issue.sh）。
+  # 纯 git 轻量门禁, 不依赖 docker; 只校验「本次新增」提交, 不追溯历史。
+  commit-message-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码 (显式 clone)
+        run: |
+          rm -rf /workspace/ci-repo
+          git clone --quiet http://127.0.0.1:3000/tanzk/csctalon.git /workspace/ci-repo
+          cd /workspace/ci-repo && git log --oneline -1
+
+      - name: 校验新增提交信息携带工单号 (#216)
+        run: |
+          set -euo pipefail
+          cd /workspace/ci-repo
+          zero=0000000000000000000000000000000000000000
+          event="${{ github.event_name }}"
+          # 默认按 push 的 before..after；PR 改用 base..head。
+          before="${{ github.event.before }}"
+          after="${{ github.event.after }}"
+          [ -z "$after" ] && after="${{ github.sha }}"
+          if [ "$event" = "pull_request" ]; then
+            before="${{ github.event.pull_request.base.sha }}"
+            after="${{ github.event.pull_request.head.sha }}"
+          fi
+          echo "event=$event before=${before:-<empty>} after=$after"
+
+          # 两端提交都本地可达且 before 非全零（非新分支首推）→ 精确校验新增区间；
+          # 新分支首推 / force-push 旧基不可达 / fork PR 等无法确定可靠区间时，
+          # 回退为仅校验 HEAD（保守: 不追溯、不误阻断; 主干最新提交本就要求带号）。
+          if [ -n "${before:-}" ] && [ "$before" != "$zero" ] \
+             && git cat-file -e "${before}^{commit}" 2>/dev/null \
+             && git cat-file -e "${after}^{commit}" 2>/dev/null; then
+            range="$before..$after"
+            echo "== 校验新增提交区间 $range =="
+            git log --oneline "$range" || true
+            bash scripts/check-commit-issue.sh --range "$range"
+          else
+            echo "== 无法确定可靠区间（新分支/force-push/fork），回退仅校验 HEAD =="
+            git log --oneline -1
+            bash scripts/check-commit-issue.sh --head-only
+          fi
+
+  # #319 契约 C2: analytics 层禁止直读 ods 源表(P2 逐域切换的棘轮门禁)。
+  # 纯 python3 静态扫描, 不依赖 docker; 只阻断「新增」违规, 存量违规入基线逐步收敛。
+  analytics-ods-isolation:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码 (显式 clone)
+        run: |
+          rm -rf /workspace/ci-repo
+          git clone --quiet http://127.0.0.1:3000/tanzk/csctalon.git /workspace/ci-repo
+          cd /workspace/ci-repo && git log --oneline -1
+
+      - name: 校验 analytics↔ods 隔离 (C2 棘轮)
+        run: |
+          set -euo pipefail
+          cd /workspace/ci-repo
+          python3 scripts/check_analytics_ods_isolation.py
+
   backend-lint-test:
     runs-on: ubuntu-latest
     steps:
@@ -27,21 +88,34 @@ jobs:
           git clone --quiet http://127.0.0.1:3000/tanzk/csctalon.git /workspace/ci-repo
           cd /workspace/ci-repo && git log --oneline -1
 
-      - name: 启动 postgres 测试库容器
+      - name: 启动 postgres 容器 (测试库 + 空库迁移门禁库)
         run: |
           # 清理残留(失败时)
-          docker rm -f ci-pg 2>/dev/null || true
+          docker rm -f ci-pg ci-pg-mig 2>/dev/null || true
           docker network create ci-net 2>/dev/null || true
           docker run -d --name ci-pg --network ci-net \
             -e POSTGRES_USER=csctalon \
             -e POSTGRES_PASSWORD=csctalon123 \
             -e POSTGRES_DB=csctalon_test \
             postgres:15
+          # 空库迁移门禁专用库(#211): POSTGRES_DB 在容器首次初始化时建成一个不含任何
+          # 表的**空库**, 专供 `alembic upgrade head` 从基线重放整条迁移链。它与 pytest 的
+          # create_all + stamp head 路径相互独立 —— 后者会掩盖"某迁移 DROP 了链上从未
+          # CREATE 的对象/迁移链断裂/多 head"。库名 _dev 后缀以通过启动期模式守卫。
+          docker run -d --name ci-pg-mig --network ci-net \
+            -e POSTGRES_USER=csctalon \
+            -e POSTGRES_PASSWORD=csctalon123 \
+            -e POSTGRES_DB=csctalon_dev \
+            postgres:15
           # 等待 PG 就绪(最多 30s)
           for i in $(seq 1 30); do
             docker exec ci-pg pg_isready -U csctalon && break
             sleep 1
           done
+          for i in $(seq 1 30); do
+            docker exec ci-pg-mig pg_isready -U csctalon && break
+            sleep 1
+          done
 
       - name: 后端测试 (docker python:3.11-slim)
         id: backend-test
@@ -59,8 +133,20 @@ jobs:
               apt-get update -qq && apt-get install -y -qq libzbar0 libpq-dev gcc >/dev/null 2>&1
               pip install -q --upgrade pip >/dev/null 2>&1
               pip install -q -e '.[dev]' >/dev/null 2>&1
-              echo '== ruff (tests/) =='
-              ruff check tests/
+              echo '== ruff (app/ + tests/) =='
+              ruff check app/ tests/
+              echo '== alembic upgrade head (空库迁移链门禁, #211) =='
+              # 命令级 env 仅作用于本条 alembic 进程(切勿 export 到全局): tests/conftest.py
+              # 用 setdefault 从 TEST_POSTGRES_* 回填 POSTGRES_*, 若全局已存在 POSTGRES_HOST
+              # 会遮蔽回填, 反令 pytest 连到空库主机上不存在的 csctalon_test。
+              # 多 head / 链断裂时 upgrade head 直接非零退出(set -e 即门禁失败)。
+              APP_MODE=dev POSTGRES_HOST=ci-pg-mig POSTGRES_PORT=5432 \
+              POSTGRES_USER=csctalon POSTGRES_PASSWORD=csctalon123 \
+              POSTGRES_DB=csctalon_dev python -m alembic upgrade head
+              echo '== alembic heads (应为单一 head) =='
+              APP_MODE=dev POSTGRES_HOST=ci-pg-mig POSTGRES_PORT=5432 \
+              POSTGRES_USER=csctalon POSTGRES_PASSWORD=csctalon123 \
+              POSTGRES_DB=csctalon_dev python -m alembic heads
               echo '== pytest =='
               pytest
             "
@@ -96,7 +182,7 @@ jobs:
 
       - name: 清理 postgres 容器
         run: |
-          docker rm -f ci-pg 2>/dev/null || true
+          docker rm -f ci-pg ci-pg-mig 2>/dev/null || true
           docker network rm ci-net 2>/dev/null || true
           echo "已清理测试容器"
 

.github/agents/architect.agent.md

@@ -9,6 +9,24 @@ user-invocable: true
 
 你是本项目的**架构师**。必须先加载并遵守仓库根目录的 `AGENTS.md`（全局行为约束）。
 
+## ⚠️ 界面设计纪律（涉前端界面时强制）
+
+若需求涉及**新增/改造任何前端界面**（页面 / 标签页 / 区块组件），架构文档**必须包含
+「界面设计说明」章节**，逐项给出：
+
+| # | 要素 | 内容 |
+|---|---|---|
+| 1 | **目的** | 替**谁**（岗位）、回答**什么决策问题**、使用频率 |
+| 2 | **逻辑** | 为何这样组织；**可控指标** vs **后果指标**的排序理由 |
+| 3 | **口径** | 数据来源与判据 + `docs/standards/` 文档指针 |
+| 4 | **取舍** | **不做什么 + 为什么**（此段必填） |
+| 5 | **工单** | issue 号 + 设计文档路径 |
+
+并明确：① 每个图表**指向哪个动作**；② 是否存在与别处的**重复展示**（谁是真身/投影）。
+
+> 依据：[docs/standards/界面设计说明规范.md](../../docs/standards/界面设计说明规范.md)
+> （AGENTS.md 「界面设计纪律（强制）」）。**缺失该章节的界面类架构文档不予通过。**
+
 ## 职责
 
 你**只输出设计，不输出实现代码**。你的产出是架构文档，交人工审核锁定后，才允许进入开发阶段。

.github/agents/developer.agent.md

@@ -9,6 +9,22 @@ user-invocable: true
 
 你是本项目的**开发者**。必须先加载并遵守仓库根目录的 `AGENTS.md`（全局行为约束）。
 
+## ⚠️ 界面设计纪律（改前端必读）
+
+改动任何界面文件（`.vue`）前，**必须**按 `docs/standards/界面设计说明规范.md`
+**三层落地**（缺一即视为未完成）：
+
+1. **代码层** —— 文件头部 `设计说明（Design Rationale）` 注释块，五要素齐全
+   （目的 / 逻辑 / 口径 / **取舍** / 工单）。
+2. **页面层** —— 使用者**可见**的 ⓘ 气泡 或「设计说明」抽屉，**必须含「取舍」段**。
+3. **审查层** —— 对应检查项可通过（`docs/standards/review-checklist.md`）。
+
+**禁止**：无意图改动（顺手加图 / 多堆 tab）；图表不指向动作；只堆后果指标；
+同一指标重复展示且未声明真身/投影。
+
+> 可参考模板：`web/src/components/dashboard/ComplaintTimeBar.vue`（工单 #67）。
+> ⚠️ **只写代码注释不算完成** —— 设计意图必须让使用者看得到。
+
 ## 职责
 
 根据**已锁定**的架构文档（`docs/arch/` 下 LOCKED 文件），实现具体功能。**禁止自行修改架构设计**；若发现架构问题，停止实现并回到 Architect 阶段。

.github/agents/reviewer.agent.md

@@ -15,6 +15,21 @@ user-invocable: true
 
 ## 检查清单（必须逐项核对）
 
+### 界面设计说明（前端改动必查 · 缺则 CRITICAL）
+
+> 依据：`docs/standards/界面设计说明规范.md`
+
+- [ ] **代码层**：界面文件头部含 `设计说明（Design Rationale）` 注释块且**五要素齐全**
+      （目的 / 逻辑 / 口径 / **取舍** / 工单）
+- [ ] **页面层**：存在使用者可见的 ⓘ 气泡 或「设计说明」抽屉，**含「取舍」段**
+- [ ] **口径出处**：设计说明中的口径标注了 `docs/standards/` 对应文档
+- [ ] **无意图改动**：无「顺手加图」「多堆 tab」；**每个图表都能指向一个动作**
+- [ ] **可控指标前置**：不是只堆后果指标（总量 / 金额）
+- [ ] **重复展示**：同指标若与其它页面重复，已声明「真身 / 投影」关系
+- [ ] **关联工单**：设计说明含 issue 号与设计文档路径
+
+### 通用
+
 - [ ] SQL 注入风险（是否参数化 / `text()` 绑定参数）
 - [ ] XSS 风险（前端输出是否转义）
 - [ ] 空指针 / 越界访问

.github/instructions/doc-class-rationale.instructions.md

@@ -0,0 +1,47 @@
+---
+applyTo: 'docs/**/*.md,AGENTS.md'
+---
+
+# 文档性质纪律（强制 · 新增/改动文档必读）
+
+> 全文见 [docs/standards/文档性质标记规范.md](../standards/文档性质标记规范.md)。
+> 核心铁律：**文档必须先说清自己是「需求」还是「需求的需求」，再谈内容。**
+
+## 为什么
+
+这两类文档**适用完全不同的规则** —— 混用会导致：
+- 用"需求"的标准审查"元需求"（要求规范写验收标准，但规范的验收标准是"能否约束住别人"）
+- 用"元需求"的稳定性要求"需求"（需求本就该随迭代演进）
+- 实现者不知道**到底该遵守哪几条**
+
+## 三分类
+
+| 性质 | 定义 | 判定判据 | 审查标准 |
+|---|---|---|---|
+| **元需求（META）** | 约束**所有**需求怎么做 | 回答"任何新增功能都必须遵守什么？"／定义口径权威含义／规定流程门禁／提供审查判据／是模板 | 能否**约束住别人** |
+| **需求（REQ）** | 做一个**具体**功能/集成 | 有功能边界 + 接口契约 + 验收标准 + 归属工单 | 验收标准是否达成 |
+| **参考（REF）** | 现状记录，**无约束** | 以代码为准的清单／已实现机制描述／台账 | 是否与代码一致 |
+
+> ★ **判据是「约束范围」，不是文件名**：
+> 名为"XX接入规范"的文档若只约束**一个集成** → 它是 **REQ** 而非 META。
+
+## 三层落地（新增/改动约束性文档时）
+
+1. **文档头部** — 标题下紧随 `**性质**：元需求（META） / 需求（REQ） / 参考（REF）`
+2. **索引登记** — 在 `docs/README.md` §六「文档性质索引」加一行
+3. **强制链** — META 且含强制条款 → **必须同步挂进 `AGENTS.md` 引用链**
+
+> ⚠️ **标记了但不挂强制链 = 只是标签，不构成约束。**（实测：11 份 META 中曾有 7 份无任何强制入口）
+
+## 三类规则差异
+
+| | META | REQ | REF |
+|---|---|---|---|
+| 变更成本 | 高（全仓影响） | 中（局部） | 低（同步即可） |
+| 走架构锁定 | ❌ | ✅ `docs/arch/` | ❌ |
+| 关联工单 | 建议 | **必须** | 建议 |
+| AI 自动加载 | 强制类必须 | 否 | 否 |
+
+## 存量策略
+
+**不追溯**（不强制给历史文档补标记）；**但谁改动、谁补齐**。

.github/instructions/ui-design-rationale.instructions.md

@@ -0,0 +1,64 @@
+---
+applyTo: '**/*.vue,web/src/**/*.js,web/src/**/*ts'
+---
+
+# 界面设计纪律（强制 · 前端改动必读）
+
+> 全文见 [docs/standards/界面设计说明规范.md](../../docs/standards/界面设计说明规范.md)。
+> 本文件是**自动加载的强制指令** —— 只要改动前端界面（页面 / 标签页 / 区块组件），
+> 以下要求立即生效，**不是建议**。
+
+## 铁律
+
+> **说不清「替谁解决什么问题」的界面，不许开工。**
+
+## 一、动手前必须先回答（五要素）
+
+在写任何界面代码之前，先明确并记录：
+
+| # | 要素 | 必须回答 |
+|---|---|---|
+| 1 | **目的** | 替**谁**（写出岗位）、回答**什么决策问题**、多久用一次 |
+| 2 | **逻辑** | **为什么**这样组织？为什么是这几个指标/这个顺序？ |
+| 3 | **口径** | 数据来自哪张表/哪个判据？口径文档路径？ |
+| 4 | **取舍** | **不做什么**？**为什么不做**？（此段强制，不得省略） |
+| 5 | **工单** | issue 号 + 设计文档路径 |
+
+## 二、三层落地，缺一即未完成
+
+1. **代码层** —— 界面文件头部必须有 `设计说明（Design Rationale）` 注释块，五要素齐全。
+2. **页面层** —— 使用者**可见**的 ⓘ 气泡 或「设计说明」抽屉，**必须含「取舍」段**。
+3. **审查层** —— `docs/standards/review-checklist.md` 的「界面设计说明」检查项通过。
+
+> ⚠️ 只写代码注释**不算完成** —— 设计意图必须让**使用者**看得到。
+
+## 三、禁止事项
+
+| 禁止 | 说明 |
+|---|---|
+| ❌ **无意图改动** | 不得「顺手加一张图」「多堆一个 tab」 |
+| ❌ **图表不指向动作** | 每个图表必须能回答"看完要做什么" |
+| ❌ **只堆后果指标** | 可控指标（如升级率）必须前置，不能只有总量/金额 |
+| ❌ **重复展示** | 同一指标全站唯一「真身」，其它位置为「投影」且需声明 |
+| ❌ **秀好看的界面** | 删掉后没有任何人的决定会改变 → 应删 |
+
+## 四、自检（开工前逐条过）
+
+- [ ] 写出这个界面**替谁**解决问题（岗位）
+- [ ] 写出使用者看完能做出**哪一个具体决定**
+- [ ] 每个图表都能**指向一个动作**
+- [ ] 已区分**可控指标**与**后果指标**，可控的在前
+- [ ] 检查是否与别处**重复展示**（谁是真身、谁是投影）
+- [ ] 已写下**不做什么 + 为什么**
+- [ ] 已在代码 / 页面 / 审查清单**三层落地**
+
+## 五、存量处理
+
+- **本次改造的界面** → 必须补齐三层设计说明（验收前置条件）
+- **存量未改造界面** → 不追溯；**谁改动、谁补齐**
+- 与已锁定架构文档冲突 → **走人工审核修订**，不得静默绕过
+
+## 参考范例
+
+`web/src/components/dashboard/ComplaintTimeBar.vue`（工单 #67）
+—— 代码层注释块 + 页面层 ⓘ 气泡 + 取舍段完整，可作为模板参考。

.gitignore

@@ -113,3 +113,45 @@ backups/
 # ---------- 本地工具凭证(勿入库,如 Gitea API token) ----------
 .gitea-token
 .gitea_token
+
+# ---------- 含 PII 的去重分析明细(勿入库, 由 scripts/export_dedup_analysis.py 生成) ----------
+# 这些 CSV 含真实用户手机号/设备SN, 仅本地人工核对用
+docs/reports/*投诉去重分析/*.csv
+/tmp/csctalon-dup-analysis/
+
+# ══════════════════════════════════════════════════════════════════
+# ★ 通用规则: 核查类导出 CSV 一律不入库
+# ══════════════════════════════════════════════════════════════════
+# 教训: 原先按目录逐条加规则(见下方历史条目), 每新增一个核查目录就要记得加一条
+#       → 遗漏时 PII 会被 `git add` 扫进去。
+#       #65 已改为**通用 glob**, 一次覆盖所有 `*-核查/`、`*-核查/` 子目录。
+#       保留下方历史条目作说明, 但与通用规则重复, 可随时清理。
+#
+# 覆盖: docs/reports/*核查*/  (对账核查 / 工信部误录核查 / 外部投诉缺口核查 / ...)
+docs/reports/*核查*/*.csv
+docs/reports/*核查*/*/*.csv
+docs/reports/*分析*/*.csv
+docs/reports/*导出*/*.csv
+
+# ── 历史条目(已被通用规则覆盖, 保留作变更溯源) ──
+# #56 外部投诉对账核查导出: 含真实手机号/设备SN(PII), 仅供本地人工核查, 严禁入库
+docs/reports/*外部投诉对账核查/*.csv
+/tmp/csctalon-recon/
+
+# #58 工信部误录核查导出: 含真实SN/手机号(PII), 仅供本地人工核查, 严禁入库
+docs/reports/*工信部误录核查/*.csv
+
+# #64 SN 清洗验证导出: 含真实SN/手机号(PII)
+docs/reports/*外部投诉缺口核查/*.csv
+
+# ---------- 仓库入库规范(见 docs/standards/仓库入库规范.md) ----------
+# C4 任务现场: 一次性脚本/冻结语料/模型raw输出/状态日志, 本机工作台不入库
+workdata/
+work-data/
+# C5 密钥凭证: 证书私钥泄露即事故
+certs/
+# C7 工具私有状态: AI 工具记忆/会话状态, 写给工具自己用的不入库
+.workbuddy/
+.trae/
+.dsh/
+

.gitleaks.toml

@@ -20,12 +20,16 @@ paths = [
     '''^\.gitleaks\.toml$''',
     '''package-lock\.json$''',
     '''yarn\.lock$''',
-    # CI 工作流: postgres service 测试密码(非业务凭证, 与 config.py 默认一致)。
-    # 仅用于 CI 隔离测试库, 生产走 .env 注入; 属于测试基础设施豁免, 不违反 OPS-11。
-    '''^\.gitea/workflows/.*\.yml$''',
-    # 后端测试: 测试用的假手机号/假数据(如 13812345678), 非真实凭证。
-    # 测试文件可能构造各种"像凭证"的样例数据, 豁免避免误报拖慢开发。
-    '''^backend/tests/.*\.py$''',
+    # CI 工作流: 仅 test.yml 含 postgres service 测试口令(非业务凭证, 与 config.py
+    # 默认一致), 只用于 CI 隔离库, 生产走 .env 注入; 属测试基础设施豁免, 不违反 OPS-11。
+    # #211 收窄: 不再用 .*\.yml 整体放行整个 workflows 目录 —— 其余 workflow 及未来
+    # 新增工作流一律纳入扫描, 防凭证借 CI 文件绕过。
+    '''^\.gitea/workflows/test\.yml$''',
+    # #211 收窄: 不再整体放行 backend/tests(原放行会让真实密钥借测试文件绕过**所有**规则)。
+    # 测试夹具天然高发的「假手机号 / 假强密码串」改在对应**规则级** allowlist 精确豁免
+    # (见文末 hardcoded-phone-number / hardcoded-strong-password 两条规则);
+    # 而 scrm-* / shanmao-* 业务凭证规则与 gitleaks 内置密钥规则(AKIA/openai/jwt/
+    # generic-api-key/private-key 等)对 backend/tests 仍全量生效。
 ]
 # 占位符/示例值不报警
 # 注意: admin123/csctalon123 已从全局 allowlist 移除(2026-08-20 审计 OPS-11):
@@ -77,6 +81,12 @@ regexes = [
     '''REPLACE_''',
     '''\$\{2:?''',
 ]
+# #211: 测试夹具的默认假密码/密文样例(如 pwd="P@ssw0rd123"、
+# "unit-test-...-secret"、"sk-...-never-leak")是本条启发式规则的高假阳性来源,
+# 故仅此一条规则对 tests 豁免; 真实密钥形态仍由 gitleaks 内置规则在 tests 中扫描。
+paths = [
+    '''^backend/tests/.*\.py$''',
+]
 tags = ["password", "hardcoded"]
 
 # 规则3: 硬编码管理员手机号(11位连续数字,出现在赋值/字典字面量中)
@@ -85,6 +95,13 @@ id = "hardcoded-phone-number"
 description = "疑似硬编码手机号(11位 1开头)"
 regex = '''["']?(1[3-9]\d{9})["']?\s*[,\)#]'''
 tags = ["phone", "pii"]
+# #211: 测试夹具大量构造 11 位手机号(连续假号 13700137xxx、号码分割逻辑样例等),
+# 是本条 PII 启发式规则的高假阳性来源, 仅此规则对 tests 豁免; 带账号登录语义的
+# SCRM 手机号仍由 scrm-baiyin-credentials 规则(对 tests 生效)兜底, 不会漏。
+[rules.allowlist]
+paths = [
+    '''^backend/tests/.*\.py$''',
+]
 
 # 规则4: 杉猫(BMS)平台凭证(2026-08-20 审计 C-1 新增)
 # 覆盖两种形态: SHANMAO_PASS = "值" 直接赋值, 与 os.environ.get("SHANMAO_PASS", "值") 回退默认值

.trae/documents/README.md

@@ -1,9 +0,0 @@
-# 说明
-
-本目录下的设计文档已迁移至仓库根目录 `docs/arch/_pending/`（保留 git 历史）。
-
-迁移目的：统一"AI 协作治理规范" 4.2 的架构文档资产化管理，设计文档进 `docs/arch/` 并接受架构锁定流程。
-
-- 迁移日期：2026-09-01
-- 迁移去向：`docs/arch/_pending/`（状态 PENDING，待人工审核锁定）
-- 原 20 份文档经 `git mv` 迁移，历史完整保留

.workbuddy/memory/2026-08-20.md

@@ -1,18 +0,0 @@
-# 2026-08-20 工作日志
-
-## 项目审计
-
-对 CSCTalon 项目进行了全面审计，覆盖五大维度：
-- **架构与配置**: Docker Compose 部署合理，.env 未入库，端口暴露受限
-- **后端代码质量**: 分层清晰但 analytics.py 8508 行严重超标；30+ 处裸 except 吞异常；零测试覆盖；死依赖 passlib
-- **前端代码质量**: Vue 3 懒加载路由 + DOMPurify XSS 防护良好；但无 TypeScript、无 ESLint；SyncDashboard.vue 2010 行超标
-- **数据库**: 56 表完整，37 个 Alembic 迁移单 head，连接池配置合理，启动咨询锁防重复迁移
-- **安全**: bcrypt + JWT token_version 吊销 + 登录限速 + SafeStaticFiles + Fernet 加密 + CSP + 操作日志，安全实现质量高
-
-审计报告已输出至 docs/audit-report-20260820.html。
-
-### 关键发现
-- P0: 零测试覆盖（tests/ 目录为空）
-- P1: 超大文件拆分、裸 except 清理、死依赖清理
-- P2: TypeScript 引入、CI/CD、限速迁移 Redis
-- P3: 加密 key 独立化、前端组件拆分、依赖精确锁定

AGENTS.md

@@ -1,7 +1,10 @@
 # 全局行为约束（00-global）
 
+**性质**：元需求（META）—— **仓库级约束源**，约束所有在本仓库内执行的 AI 任务
+
 > 本文件对应"AI 协作治理规范" 4.1 铁律与 4.2 `00-global.md`，作为仓库级指令被 AI 助手自动加载。
 > 适用范围：所有在本仓库内执行的 AI 代码生成 / 文档 / 审查任务。
+> 文档性质索引见 [docs/README.md §六](docs/README.md)。
 
 ## 身份
 
@@ -21,16 +24,83 @@
    - 唯一例外：`console.log('[TODO:...]')` 形式的显式 TODO 标记，可保留但必须带 `[TODO:` 前缀。
 2. 禁止无参数化地拼接 SQL。允许 `text()` + 绑定参数（如 `db.execute(text(...), {...})`），禁止字符串 `f"...{var}..."` 直接拼进 SQL。
 3. 禁止在代码中硬编码密码、密钥、内网 IP、数据库账号，必须走环境变量（`.env` / `settings`）。
+   **连带：禁止让"库名"的默认值指向真实库，也禁止让模式与库名可以不一致。**
+   - 库名必须与运行模式自洽（`APP_MODE=dev` → 库名以 `_dev` 结尾；`test` → `_test`；
+     `prod` → 不含 `_dev`/`_test`）。启动期会**硬校验**，不一致即拒绝启动。
+   - 破坏性操作（`DELETE`/`TRUNCATE`/`DROP`/批量 `UPDATE`）**必须**先过
+     `app.core.db_guard.assert_safe_to_destroy()`；操作真实库须**显式**传
+     `allow_real_db=True`（脚本参数为 `--allow-real-db`），**禁止**用环境变量绕过。
+   - 新写 `scripts/**` 必须经 `scripts/_bootstrap.py` 的 `bootstrap()` 进入，
+     不得自己拼 `POSTGRES_DB` 环境变量（那是两份定义，必漏）。
+   - 全文见 `docs/arch/A-20260922-001-运行模式框架与配置分离.md`。
+   > 为什么不单列一条：本条与"禁止硬编码 DB 账号"是**同一个风险面**——
+   > 把库名默认成生产库名，等价于把连接信息硬编码到代码里。
+   > 现有 13 条已足够长，另开一条会稀释权威性（参见 `docs/standards/跨项目经验迁移指南.md`
+   > "铁律只列最重要的，避免冗长失效"）。
 4. 禁止擅自修改已锁定的架构文档（`docs/arch/` 下标记为 `LOCKED` 的文件），修改必须先走人工审核流程。
 5. 禁止删除或绕过 `docs/standards/数据时间字段使用规范.md` 中规定的时区换算（`AT TIME ZONE 'Asia/Shanghai'`）与 `SYS/system` 系统操作人排除标准。
 6. 禁止绕过 Alembic 直接改表结构；表结构变更必须新增 migration 版本。
+7. **禁止「无设计说明」的界面改动**（见 `docs/standards/界面设计说明规范.md`）。
+   新增/改造任何前端界面（页面 / 标签页 / 区块），必须先写清「替谁回答什么问题、
+   为什么这样组织、不做什么及原因」，并按该规范**三层落地**（代码注释 + 页面可见说明 + 审查清单）。
+   禁止「顺手加一张图 / 多堆一个 tab」式的无意图改动。
+8. 禁止绕过后端响应格式规范（见 `docs/standards/error-code.md`）。
+   成功返回 `{code:0, data, message}`，错误一律走 `HTTPException`，禁止自定义裸 dict。
+9. 禁止绕过 `docs/standards/数据采集合并去重机制说明.md` 规定的**去重键**。
+   该规范约束**所有采集通道**（投诉指纹 / 手动退款复合键 / 各 data_type 唯一键）；
+   新增采集源必须先确认去重键，否则会产生重复入库。
+10. 禁止擅自变更 `docs/standards/投诉渠道口径与对账说明.md` 中的**渠道口径权威定义**
+    （内部 / 商户号 / 外部投诉的归类判据）。口径是统计的根，改动会影响全部投诉数字，
+    必须走人工审核 + 回归验证。
+11. 禁止绕开 `docs/standards/数据源接入与缓存加速规范.md` 的缓存铁律：
+    新增数据源 / 看板接口时，写入后必须失效对应缓存 pattern，Redis key 必须逐字符对齐。
+12. **禁止「无数据说明 / 不可下钻」的看板卡片**（见 `docs/standards/看板卡片数据说明与下钻规范.md`）。
+    任何看板卡片必须**同时**做到：① 有 ⓘ 数据说明（来源 / 口径 / 时点，并写明"空"的含义）；
+    ② 可下钻且**带时间窗口与筛选条件**。确不下钻的须在代码注释 + 页面 ⓘ 显式声明理由。
+    禁止「点了没反应」的数字，禁止跳到空白明细页让使用者自己再筛一遍。
+13. **禁止绕过 `docs/standards/数据源命名与分组规范.md`** 的数据源命名与分组元规则：
+    - **分组顺序唯一来源**是 `data_source_registry.CATEGORY_ORDER`，前端**不得**再定义一份
+      （两份定义必然漂移，同 A-20260910-004 菜单漂移）；组内顺序由服务端 `sort_order` 决定。
+    - `code` / `table_name` / `name_cn` 必须一一对应，`name_cn` **全树唯一**且必须带域前缀
+      （`前缀·中文语义`，禁止出现 code 原文）；例外须在该规范 §3.5 登记。
+    - 数据**已停用**或**口径易误用**（如 E 路对账基准）→ **必须在显示名**中标注，
+      只写 `description` 不算（树上看到名字的人不会点开描述）。
+    - **同一张表禁止注册两个 code**（统计口径分裂）；需要第二入口请用**投影**
+      （`DATA_SOURCE_PROJECTIONS`），且投影**必须**声明真身分组与名称，否则视为
+      「无声明重复展示」违规。
+14. **禁止绕过《仓库入库规范》的文件入库分类纪律**（见 `docs/standards/仓库入库规范.md`，META）：
+    - **C5 密钥凭证**（`.env` / token / 私钥 / 真实密码）与 **C6 PII/业务数据**（含真实手机号/单号/SN
+      的语料、xlsx/csv/pkl 导出、`01样本数据/`）**严禁入 git**，由 gitleaks + CI 兜底
+      （与第 3 条互补：第 3 条管"代码内不许硬编码"，本条管"什么文件根本不许入库"）。
+    - **一次性任务现场**（临时脚本 / 模型 raw 输出 / 探针 / 冻结语料）落本地 `workdata/`（gitignore），
+      不入 git；任务收尾把**结论提炼进 `docs/reports/`**，耐用脚本证明可复用后才进 `scripts/`。
+    - **点号 ≠ 不入库**：`.gitea/` 等协作配置必须入库；`__pycache__` / `.venv` / `node_modules`
+      等缓存运行时忽略。唯一判据：别人 clone 后是否需要它才能跑起来 / 理解系统。
+15. **禁止绕过《退款五路数据标准与采纳规则》的采纳口径**（见 `docs/standards/退款五路数据标准与采纳规则.md`，META）：
+    - 退款五路（A 线上直退 / B 钱包流水 / C 闪猫 / D 手动 / E 企微记录）统计**一律读 `std_*` 标准表**
+      （`std_refund_online` / `std_wallet_flow` / `std_refund_shanmao` / `std_refund_manual` / `std_refund_record`），
+      **禁止**在查询侧散落复刻采纳条件（失败/冻结关键词、质量状态过滤等已由采纳作业在表层固化）。
+    - ods 原始表**只同步不治理**：采集 upsert 不得覆盖采纳标识四列（`adopt_state` / `adopt_reason` /
+      `adopt_rule_ver` / `adopted_at`）；质量治理入口 = 人工覆盖 API（`adoption_overrides`），禁止直接改原始数据。
+    - 采纳规则变更必须**升版 `ADOPT_RULE_VER`** 并同步修订口径文档；全状态/全方式语义例外
+      （挽回漏斗、状态分布、工作量统计、导出原始明细、链路台账、设备档案、对账勾稽）
+      一律读 `std_*_all` 全量镜像视图（ods 同构透传），**业务代码禁止直读 ods**；
+      ods 仅剩采集写入、采纳作业读取、质量治理标记三个本职消费（#334）。
+    - 企业商户维度统一经 `dim_device_merchant`（as-of 分段维表）回填，禁止各处自行实现商户回落逻辑。
 
 ## 输出风格
 
 1. 代码块必须带注释说明关键逻辑（尤其涉及时间换算、金额单位、事务回滚处）。
 2. 修改现有文件时，必须先说明改动意图（涉及哪几个文件、改了什么），禁止静默大改。
 3. 遇到不确定的需求，必须停下来提问，禁止猜测实现。
-4. 金额字段一律以"分"为单位（整数），禁止浮点存储金额。
+4. 金额字段一律使用定点数（Decimal），禁止二进制浮点进入金额存储与计算。
+   **现行口径（#217 拍板方案 C′，2026-10-08）**：
+   - DB 层 `Numeric(12,2)/(12,4)`（元单位）不变；ORM 注解 `Mapped[Decimal | None]`；
+   - 采集写入经 `upsert._core._to_decimal`；计算路径用 `analytics._core.D()` 定点化；
+   - **出参边界**（JSON API / Excel 导出 / JSONB 落库）允许 `float(...)` 一次性表示层转换，
+     对外契约保持 JSON number（元）不变；
+   - **例外登记**（保留 float，非金额语义）：`merchant_refund.rate`（费率 Numeric(8,4)）、
+     `device_flow_usage.flow_gb`（流量 GB）。新增金额列必须走 Decimal，例外须在此登记。
 
 ## 工具使用
 
@@ -38,3 +108,67 @@
 2. 执行任何会改动数据的命令前，先输出将要执行的命令，等待确认。
 3. 数据库操作默认使用只读账号（如 `db` 容器内的查询），除非明确获得授权。
 4. 运行测试 / lint：优先使用项目既有命令（如 `ruff`、`pytest`），不要擅自引入新工具链。
+
+## 界面设计纪律（强制）
+
+> 全文见 `docs/standards/界面设计说明规范.md`。核心铁律：
+> **说不清「替谁解决什么问题」的界面，不许开工。**
+
+1. **五要素必填**：目的（替谁/答何决策）· 逻辑（为何这样组织）· 口径（数据判据 + 文档指针）·
+   **取舍（不做什么及原因）** · 工单（issue 号 + 设计文档）。
+2. **三层落地**，缺一即未完成：
+   - ① **代码层**：界面文件头部 `设计说明（Design Rationale）` 注释块；
+   - ② **页面层**：使用者可见的 ⓘ 气泡 或「设计说明」抽屉（**必须含「取舍」段**）；
+   - ③ **审查层**：`docs/standards/review-checklist.md` 对应检查项通过。
+3. **禁止无意图改动**：不得「顺手加一张图」「多堆一个 tab」；每个图表必须**指向一个动作**。
+4. **可控指标前置**：优先展示可控指标（如升级率），而非只有后果指标（如总量/金额）。
+5. **禁止重复展示**：同一指标全站应有唯一「真身」，其它位置为「投影」；
+   投影必须在设计说明中声明，并注明真身位置。
+6. **删掉无损判据**：若某界面被删掉后**没有任何人的任何决定会改变**，则它属于「秀好看」，应删。
+7. **存量不追溯，改动即补齐**：未改造的存量界面不强制追溯；但**谁改动、谁补齐**。
+8. **看板卡片双强制**（见 `docs/standards/看板卡片数据说明与下钻规范.md`）：
+   任何看板卡片必须**有数据说明**（来源/口径/时点 + "空"的含义）且**可下钻**
+   （带当前时间窗口与筛选条件）；不可下钻的须显式声明理由。详见该规范全文。
+9. **数据源命名与分组**（见 `docs/standards/数据源命名与分组规范.md`）：
+   数据查看树的每一项必须让人看出「这是哪一类/哪一路」；分组顺序与组内顺序均由服务端
+   单一来源决定；停用与易误用口径**必须在显示名标注**；同表第二入口只能走**投影**
+   且必须声明真身位置。详见「绝对禁止」第 13 条。
+
+## 工单纪律（强制）
+
+1. **所有任务必须先建工单，再动手**（见 `docs/standards/issue-workflow.md`）。
+2. **提交信息必须携带 `#issue号`**，否则关联不上、无法审计。
+3. **关闭工单前必须先写「关闭凭证核验」评论**：
+   - 标题固定 `## 关闭凭证核验 (YYYY-MM-DD)`
+   - 用表格**逐条对应**正文的「验收标准 / 关闭条件」，每条给出**可复现**的核验方式
+     （测试用例名 / commit sha / 实测命令），禁止写「已测试通过」这类不可验证的话
+   - 同时把正文里对应的 `- [ ]` 勾成 `- [x]`
+   - 批量关闭多张工单时，**每张各写一条**自己的凭证评论
+   - 确属降级接受的，写 `结论: 以 <理由> 降级验收`，**禁止静默关闭**
+4. **禁止无凭证关闭**。凭证缺失的历史工单**不重开**，改为补记
+   `## 关闭凭证核验（补记 · YYYY-MM-DD）` 并显式标注为事后追溯。
+
+## 文档性质纪律（强制）
+
+> 全文见 `docs/standards/文档性质标记规范.md`。核心铁律：
+> **文档必须先说清自己是「需求」还是「需求的需求」，再谈内容。**
+
+1. **两类必须区分**：
+   - **需求（REQ）** —— 做一个具体功能/集成。有功能边界、接口契约、验收标准、归属工单。
+   - **元需求（META）** —— 约束**所有**需求怎么做（规范/口径/流程/模板/审查判据）。
+     `docs/standards/` 与 `AGENTS.md` 属此类。
+   - **参考（REF）** —— 现状记录（表结构说明 / API 清单 / 台账），**无约束力**，以代码为准。
+2. **判据是「约束范围」，不是文件名**：名为"XX接入规范"的文档若只约束**一个集成**，
+   它是 **REQ** 而非 META。
+3. **三层落地**（新增/改动约束性文档时）：
+   - ① 文档头部标 `**性质**：元需求（META） / 需求（REQ） / 参考（REF）`
+   - ② 在 `docs/README.md` §六「文档性质索引」登记一行
+   - ③ META 且含强制条款 → **必须同步挂进本文件（AGENTS.md）引用链**
+4. **禁止「标记了但约束不住」**：META 不进 AGENTS 引用链 = 只是标签，不构成约束。
+5. **三类适用不同规则**（用错标准 = 审查失效）：
+   | | META | REQ | REF |
+   |---|---|---|---|
+   | 审查标准 | 能否**约束住别人** | 验收标准是否达成 | 是否与代码一致 |
+   | 变更成本 | 高（全仓影响） | 中（局部） | 低（同步即可） |
+   | 走架构锁定 | ❌ | ✅ | ❌ |
+6. **存量不追溯，改动即补齐**：未标性质的存量文档不强改；**谁改动、谁补齐**。

README.md

@@ -161,7 +161,10 @@ csctalon/
 | 规范 | `docs/standards/` | 错误码 / 审查清单 / 任务派工单模板 / 工单驱动工作流 |
 | 文档组织 | `docs/README.md` | docs 目录职责 / 文件命名规范 / 运维手册分发 |
 | 测试 | `backend/tests/` | pytest 基建, 独立 `csctalon_test` 库, 隔离开发/生产 |
-| CI | `.gitea/workflows/` | gitleaks 凭证扫描 + backend-test(ruff + pytest 强制) |
+| CI | `.gitea/workflows/` | gitleaks 凭证扫描 + backend-test(**提交信息工单号校验** · ruff `app/`+`tests/` · **空库 alembic upgrade head** · pytest，强制) |
+
+> **提交钩子（建议安装）**：`bash scripts/install-gitleaks-hook.sh`（pre-commit 扫凭证）+
+> `bash scripts/install-commit-msg-hook.sh`（commit-msg 强制提交信息带 `#工单号`，#216）。
 
 **协作流程**: 需求/事件 → **建 Gitea 工单**（见 [docs/standards/issue-workflow.md](docs/standards/issue-workflow.md)，事故拆单：incident + governance）→ 架构师出设计 → 人工锁定(`docs/arch/` + git tag) → 开发者实现（提交/PR 关联 `#issue号`）→ 审查员审查 → 人工终审合并。测试与 lint 由 CI 机器验证, 不依赖 AI 口头声称。
 
@@ -175,6 +178,10 @@ pip install -e ".[dev]"
 pytest
 # 静态检查
 ruff check app/ tests/
+# 空库迁移链自检(CI 门禁 #211; 需先建一个空库, 完整命令见
+# docs/standards/alembic-migration管理规范.md §二/§八)
+APP_MODE=dev POSTGRES_DB=<空库名_dev> python -m alembic upgrade head
+python -m alembic heads   # 必须只输出一个 (head)
 ```
 
 ## 核心功能模块

backend/.dockerignore

@@ -10,8 +10,21 @@ __pycache__/
 .env
 
 # 调试/一次性脚本(含历史凭证与嗅探器,禁止进入生产镜像,2026-08-20 审计 C-1/TST-02)
-scripts/
+# 登录脚本已于 2026-10-20 迁入 app/services/shared_doc_*_cli.py, 不再从 scripts/ 放行
+scripts/*
 tests/
+# 例外: 工单到期核验脚本 + 其运行守卫(#193 交付)。
+#   ⚠️ 仅对**直接 docker build** 生效。生产走 upgrade.sh/package.sh 时, 它们有各自的
+#      发布白名单(见 upgrade.sh), 会把 backend/scripts/* 全删,
+#      故生产需按下方配方先把两个文件 docker cp 进容器:
+#         scp backend/scripts/{check_ai_issue_gates,_bootstrap}.py <host>:/tmp/
+#         ssh <host> "docker cp /tmp/check_ai_issue_gates.py csctalon-backend:/app/scripts/ &&
+#                     docker cp /tmp/_bootstrap.py  csctalon-backend:/app/scripts/"
+#         ssh <host> "docker exec -w /app -e PYTHONPATH=/app csctalon-backend \
+#                     python /app/scripts/check_ai_issue_gates.py --issue 191 --allow-real-db"
+#       (两处白名单若口径不一致会漂移 —— 如需常态化, 应把配方收敛到只留一处)
+!scripts/check_ai_issue_gates.py
+!scripts/_bootstrap.py
 
 # 上传文件(运行时挂载)
 uploads/*

backend/.env.dev.example

@@ -0,0 +1,49 @@
+# ============================================================================
+# 开发环境配置模板（dev 模式）
+# ============================================================================
+# 用法:  cp backend/.env.dev.example backend/.env.dev
+#
+# 运行模式由 **APP_MODE=dev** 决定（见 app/core/config/profiles.py）：
+#   dev  → 库名必须以 _dev 结尾；日志 DEBUG + 详细格式；/docs 开启
+#
+# ⚠️ 为什么 dev 的库名必须带 _dev 后缀：
+#   2026-09-10 与 2026-09-22 两次同因事故的根因是**库名无区分**——
+#   本地与生产都叫 csctalon，连错库时配置/日志/界面没有任何信号。
+#   现在启动期会校验「模式 ↔ 库名」，连错库**直接拒绝启动**（见 guard.py）。
+# ============================================================================
+
+# 运行模式（唯一入口；兼容旧变量 ENV）
+# ⚠️ 容器部署时由 docker-compose 显式注入 ENV=prod；本地开发用 APP_MODE=dev
+APP_MODE=dev
+
+# 数据库（库名以 _dev 结尾是启动期的硬要求）
+POSTGRES_HOST=127.0.0.1
+POSTGRES_PORT=5432
+POSTGRES_USER=csctalon
+POSTGRES_PASSWORD=csctalon123
+POSTGRES_DB=csctalon_dev
+
+# Redis
+REDIS_HOST=127.0.0.1
+REDIS_PORT=6379
+REDIS_DB=0
+REDIS_PASSWORD=
+
+# 安全（dev 环境允许弱值；prod 会 fail-fast 拒绝）
+JWT_SECRET_KEY=dev-only-not-for-production-0123456789abcdef
+JWT_ALGORITHM=HS256
+JWT_ACCESS_TOKEN_EXPIRE_MINUTES=1440
+INIT_ADMIN_USERNAME=admin
+INIT_ADMIN_PASSWORD=admin123
+
+# 上传与目录（相对 backend/；dev 默认 ./uploads）
+UPLOAD_DIR=./uploads
+MAX_UPLOAD_SIZE_MB=200
+
+# 跨域（本地前端）
+CORS_ORIGINS=http://localhost:5173,http://localhost,http://127.0.0.1
+
+# 排障开关：需要看 SQL 时开（默认关，避免日志噪音）
+SQL_ECHO=false
+# 本地调试可关掉定时同步，避免干扰
+BMS_SCHEDULE_AUTOSTART=false

backend/.env.example

@@ -1,7 +1,30 @@
 # 客服中心管理系统 - 环境配置模板
 # 复制为 .env 后按实际环境填写,切勿将真实 .env 提交到 git
+#
+# ============================================================================
+# ⚠️ 2026-09-22 起：本项目引入**运行模式**机制（见 docs/arch/A-20260922-001）
+# ============================================================================
+# 模式由 APP_MODE 决定（兼容旧变量 ENV），分 dev / test / prod。
+# 模式**硬决定**库名、日志级别、数据目录等（单一真值来源：app/core/config/profiles.py）。
+#
+# ★ 关键规则（启动期强制校验，违反直接拒绝启动）：
+#     dev  模式 → 库名必须以 _dev  结尾
+#     test 模式 → 库名必须以 _test 结尾
+#     prod 模式 → 库名**不得**包含 _dev / _test
+#
+#   为什么要有这条：2026-09-10 与 2026-09-22 两次同因事故的根因是**库名无区分**——
+#   本地与生产都叫 csctalon，连错库时配置/日志/界面没有任何信号，
+#   只能靠"恰好有活跃连接"这类运气拦下。现在连错库会在**启动期**直接失败。
+#
+# 推荐做法：按模式使用专属文件（app/core/config/settings.py 会自动加载）
+#     cp backend/.env.dev.example   backend/.env.dev     # 本地开发
+#     生产用 deploy/env.production.example → /opt/csctalon/.env（compose 注入环境变量）
+#
+# ⚠️ 不要再用 "ENV=dev + POSTGRES_DB=csctalon" 这种组合 —— 会被守卫拒绝。
+# ============================================================================
 
-ENV=dev
+# 运行模式：dev / test / prod
+APP_MODE=dev
 DEBUG=true
 
 # ---------- 站点备案信息(登录页/全局页脚展示, 网站备案要求) ----------
@@ -19,7 +42,10 @@ SITE_SUBTITLE=专注数据分析与内部工具
 # ---------- 数据库 ----------
 POSTGRES_USER=csctalon
 POSTGRES_PASSWORD=<请修改为强密码>
-POSTGRES_DB=csctalon
+# ★ 必须与 APP_MODE 匹配（dev→_dev / test→_test / prod→无后缀）。
+#   ⚠️ 曾默认为 csctalon（真实库名），使"忘记配置"="连真实库" —— 已移除默认值，
+#      留空会启动失败（这是**有意**的：宁可启动失败，也不要静默连错库）。
+POSTGRES_DB=csctalon_dev
 # Docker Compose 部署时填 db;本机直连时填 127.0.0.1
 POSTGRES_HOST=db
 POSTGRES_PORT=5432

backend/Dockerfile

@@ -17,6 +17,9 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
     libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 \
     libgbm1 libasound2 libpangocairo-1.0-0 libpango-1.0-0 libcairo2 \
+    # 虚拟显示服务(工单 #45): 共享文档页面内扫码登录需在有头浏览器中渲染,
+    # 容器无物理显示器 → 用 Xvfb 提供虚拟 DISPLAY。xauth 供 xvfb-run 使用。
+    xvfb xauth \
     && rm -rf /var/lib/apt/lists/*
 
 # pip 使用清华源
@@ -24,19 +27,10 @@ RUN pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple \
     && pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn
 
 COPY pyproject.toml ./
-RUN pip install --no-cache-dir \
-    "fastapi>=0.110.0" "uvicorn[standard]>=0.27.0" "gunicorn>=21.2.0" \
-    "sqlalchemy>=2.0.25" "alembic>=1.13.0" "psycopg2-binary>=2.9.9" \
-    "pydantic>=2.6.0" "pydantic-settings>=2.1.0" \
-    "python-jose[cryptography]>=3.3.0" "bcrypt>=4.0.0" \
-    "python-multipart>=0.0.9" "pandas>=2.2.0" "openpyxl>=3.1.2" "python-calamine>=0.2.0" \
-    "redis>=5.0.0" "python-dotenv>=1.0.0" "orjson>=3.9.0" \
-    "pypinyin>=0.50.0" "httpx>=0.27.0" \
-    "playwright>=1.45.0" \
-    # 验证码自动识别(ddddocr + ONNX Runtime,纯 Python,无外部系统依赖)
-    "ddddocr>=1.4.11" "onnxruntime>=1.17.0" \
-    # 发票二维码图本地解码(规划设计 §4.5 全电发票识别链路)
-    "pyzbar>=0.1.9" "pillow>=10.0.0"
+COPY app ./app
+# 依赖单一来源 = pyproject.toml (#183): 安装本项目即解析全部依赖,
+# 杜绝 Dockerfile 硬编码清单与 pyproject 双定义漂移。
+RUN pip install --no-cache-dir .
 
 # 安装 Chromium 浏览器(浏览器二进制走 npmmirror 镜像,避免 cdn.playwright.dev 国内无法访问)
 ENV PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright/
@@ -50,9 +44,13 @@ RUN mkdir -p /app/uploads
 EXPOSE 8000
 
 # gunicorn + uvicorn worker
-# -w 1: 单 worker, 与 docker-compose 一致。
-#   原因: 同步任务管理器/登录限速用进程内内存互斥锁(asyncio.Lock/字典), 多 worker 下各自计数
-#   会导致重复同步与限速失效。如需多 worker 并发, 须先将这些状态迁至 Redis(M5)。
+# -w 1: 单 worker, 与 docker-compose.yml、Dockerfile.patch 三处保持一致（#212 已消除 -w 4 矛盾）。
+#   原因（下列状态均为进程内状态，多 worker 各持一份即失效）:
+#     · llm_scheduler 的进程级 threading.Condition 门闸(_gates): 保证任一时刻仅 1 个 LLM
+#       调用在飞，多 worker 会把单个 ollama 端点并发打爆；
+#     · 同步任务管理器(SyncTaskManager) / 登录限速(core.rate_limit) 的内存锁与计数:
+#       多 worker 各自计数会导致重复同步(数据重复)与限速失效。
+#   多 worker 水平扩容是 v0.7「立此存照、不做」项；如需，须先将这些状态迁至 Redis。
 # --timeout 900s: sync-all 多源抓取含 65s 间隔, 全程 5-8 分钟, 默认 120s 会被 gunicorn
 #   判超时 SIGABRT → 前端 502。
 # 日志: gunicorn/uvicorn/app 日志统一走 stdout/stderr, 由 docker json-file 轮转(10m×3)捕获,

backend/Dockerfile.patch

@@ -14,4 +14,14 @@ RUN mkdir -p /app/uploads
 
 EXPOSE 8000
 
-CMD ["gunicorn", "app.main:app", "-w", "4", "-k", "uvicorn.workers.UvicornWorker", "-b", "0.0.0.0:8000", "--timeout", "900", "--log-level", "info"]
+# ★ worker 数必须与主 Dockerfile、docker-compose.yml 三处完全一致：-w 1（#212 / R-P1-9）。
+#   本补丁镜像可能被直接 `docker run`（不经 compose 的 command 覆盖），故 CMD 不能写成 -w 4：
+#   下列进程内状态在多 worker 下会各持一份而失效——
+#     · llm_scheduler 的进程级 threading.Condition 门闸(_gates)：任一时刻仅 1 个 LLM 调用在飞，
+#       多 worker 会把单个 ollama 端点并发打爆；
+#     · SyncTaskManager 同步互斥 / core.rate_limit 登录限速的进程内锁与计数：
+#       多 worker 各自计数 → 重复提交同步任务(数据重复)、限速失效。
+#   多 worker 水平扩容是 v0.7 明确「立此存照、不做」项，须先把上述状态迁至 Redis。
+# --timeout 900s: sync-all 多源抓取含 65s 间隔，全程 5-8 分钟，默认 120s 会被 gunicorn
+#   判超时 SIGABRT → 前端 502。
+CMD ["gunicorn", "app.main:app", "-w", "1", "-k", "uvicorn.workers.UvicornWorker", "-b", "0.0.0.0:8000", "--timeout", "900", "--log-level", "info"]

backend/alembic/env.py

@@ -1,12 +1,11 @@
 """Alembic 环境配置"""
 
 import logging
-
 from logging.config import fileConfig
 
-from alembic import context
 from sqlalchemy import engine_from_config, pool
 
+from alembic import context
 from app.core.config import settings
 from app.core.database import Base
 from app.models import *  # noqa: F401,F403  # 注册所有模型
@@ -27,7 +26,12 @@ target_metadata = Base.metadata
 
 def run_migrations_offline() -> None:
     url = config.get_main_option("sqlalchemy.url")
-    context.configure(url=url, target_metadata=target_metadata, literal_binds=True, compare_type=True)
+    # #319: 模型已分布到 public/ods 两 schema, 必须 include_schemas=True,
+    # 否则 autogen 只反射 public, 会把 ods 表误判为"待新建"而生成重复建表。
+    context.configure(
+        url=url, target_metadata=target_metadata, literal_binds=True,
+        compare_type=True, include_schemas=True,
+    )
     with context.begin_transaction():
         context.run_migrations()
 
@@ -39,7 +43,10 @@ def run_migrations_online() -> None:
         poolclass=pool.NullPool,
     )
     with connectable.connect() as connection:
-        context.configure(connection=connection, target_metadata=target_metadata, compare_type=True)
+        context.configure(
+            connection=connection, target_metadata=target_metadata,
+            compare_type=True, include_schemas=True,  # #319: 同上
+        )
         with context.begin_transaction():
             context.run_migrations()
 

backend/alembic/versions/0f822d39bb6e_quality_disposition_rules_table.py

@@ -6,10 +6,11 @@ Create Date: 2026-09-09 10:45:00.000000
 """
 from typing import Sequence, Union
 
-from alembic import op
 import sqlalchemy as sa
 from sqlalchemy.dialects import postgresql
 
+from alembic import op
+
 revision: str = '0f822d39bb6e'
 down_revision: Union[str, None] = 'e0f1a2b3c4d5'
 branch_labels: Union[str, Sequence[str], None] = None

backend/alembic/versions/11bcdc63728f_add_submit_params_to_service_tickets.py

@@ -7,9 +7,9 @@ Create Date: 2026-07-26 14:50:00.000000
 """
 from typing import Sequence, Union
 
-from alembic import op
 import sqlalchemy as sa
 
+from alembic import op
 
 # revision identifiers, used by Alembic.
 revision: str = '11bcdc63728f'

backend/alembic/versions/64a584531400_reimbursement_items_invoice_unique.py

@@ -7,8 +7,6 @@ Create Date: 2026-08-20 08:56:28.292288
 from typing import Sequence, Union
 
 from alembic import op
-import sqlalchemy as sa
-
 
 revision: str = '64a584531400'
 down_revision: Union[str, None] = 'r6f7a8b9c0d1'

backend/alembic/versions/73a7922ec598_add_system_events_and_source_groups.py

@@ -6,9 +6,10 @@ Create Date: 2026-08-25 11:06:57.088116
 """
 from typing import Sequence, Union
 
-from alembic import op
 import sqlalchemy as sa
 
+from alembic import op
+
 revision: str = '73a7922ec598'
 down_revision: Union[str, None] = 'm7n8o9p0q1r2'
 branch_labels: Union[str, Sequence[str], None] = None

backend/alembic/versions/97862042a459_add_scrm_staff_profiles.py

@@ -9,10 +9,11 @@ Create Date: 2026-08-07 13:06:50.653313
 """
 from typing import Sequence, Union
 
-from alembic import op
 import sqlalchemy as sa
 from sqlalchemy.dialects import postgresql
 
+from alembic import op
+
 revision: str = '97862042a459'
 down_revision: Union[str, None] = 'c3e4f5a6b7c8'
 branch_labels: Union[str, Sequence[str], None] = None

backend/alembic/versions/a0b1c2d3e4f5_phase_a_workflow_incident_tag.py

@@ -17,10 +17,9 @@ Create Date: 2026-08-18 00:00:00.000000
 """
 from typing import Sequence, Union
 
-from alembic import op
 import sqlalchemy as sa
-from sqlalchemy.dialects import postgresql
 
+from alembic import op
 
 revision: str = 'a0b1c2d3e4f5'
 down_revision: Union[str, None] = 'p1b2c3d4e5f6'

backend/alembic/versions/a1b2c3d4e5f6_add_shanmao_phone_paid_amount.py

@@ -10,9 +10,10 @@ Create Date: 2026-08-03 21:00:00.000000
 """
 from typing import Sequence, Union
 
-from alembic import op
 import sqlalchemy as sa
 
+from alembic import op
+
 # revision identifiers, used by Alembic.
 revision: str = 'a1b2c3d4e5f6'
 down_revision: Union[str, None] = 'b8c9d0e1f2a3'

backend/alembic/versions/a1b2c3d4e5f7_add_sync_source_configs_options.py

@@ -10,10 +10,11 @@ Create Date: 2026-08-05 14:00:00.000000
 """
 from typing import Sequence, Union
 
-from alembic import op
 import sqlalchemy as sa
 from sqlalchemy.dialects import postgresql
 
+from alembic import op
+
 # revision identifiers, used by Alembic.
 revision: str = "a1b2c3d4e5f7"
 down_revision: Union[str, None] = "z9y8x7w6v5u4"

backend/alembic/versions/a1c2e3f4d5b6_cs_record_unique_nulls_not_distinct.py

@@ -0,0 +1,93 @@
+"""cs_records 唯一约束改为 NULLS NOT DISTINCT
+
+【工单】#77 cs_records 重复行止损：唯一约束因 NULL 失效
+【问题】原约束 uq_cs_record_business 含 8 列，其中 problem_create_time 大量为 NULL。
+        PostgreSQL 唯一约束默认 NULLS DISTINCT —— 任一列为 NULL 时该行不参与去重，
+        导致重复行可无限插入（实测单秒同一 SN 最多 64 行，2026-09 重复率 47%）。
+【修复】重建约束为 UNIQUE NULLS NOT DISTINCT（PG 15+ 特性），
+        使 NULL 视为相等值参与去重，从数据库层堵住重复插入。
+【依据】docs/standards/数据采集合并去重机制说明.md（去重键）
+        工单 #77 正文「根因判断」与「处理动作」
+【数据】本迁移只改约束，不动数据；重复行清理由工单 #77 单独执行并留备份。
+
+⚠️ 注意：PostgreSQL 15 起才支持 NULLS NOT DISTINCT。
+   项目 PostgreSQL 版本为 15.19，满足要求。
+
+Revision ID: a1c2e3f4d5b6
+Revises: b2c3d4e5f6a7
+Create Date: 2026-09-13 12:30:00.000000
+"""
+from typing import Sequence, Union
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = 'a1c2e3f4d5b6'
+down_revision: Union[str, None] = 'b2c3d4e5f6a7'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+# 业务唯一键（与 app/models/cs_record.py 保持一致）
+_UNIQUE_COLS = (
+    "device_sn", "operation_time", "operator",
+    "problem_category", "problem_type", "solution",
+    "consult_time", "problem_create_time",
+)
+_CONSTRAINT_NAME = "uq_cs_record_business"
+
+
+def upgrade() -> None:
+    # 0) 先清理历史重复行 —— 否则下面加唯一约束必然失败(库中已存在重复)。
+    #    去重口径与业务键一致，保留每组 id 最小的一条(最早入库的那条)。
+    #    ⚠️ 这是**幂等**操作: 无重复时不删任何行。
+    #    生产已于 2026-09-13 手工清理(备份 /tmp/cs_records_pre_dedup_*.sql)，此处兜底
+    #    其他环境(本地/测试库)；重复行是同一事件的重复写入，无业务信息损失。
+    op.execute(
+        """
+        DELETE FROM cs_records c
+        WHERE NOT EXISTS (
+            SELECT 1 FROM (
+                SELECT min(id) AS keep_id
+                FROM cs_records
+                GROUP BY device_sn, operation_time, operator, solution, consult_time
+            ) k
+            WHERE k.keep_id = c.id
+        )
+        """
+    )
+
+    # 1) 删除旧约束（NULLS DISTINCT 语义，对含 NULL 的记录不起去重作用）
+    #    ⚠️ 空库可重放（#211）：建表迁移 b4c9d1f02e5a 从未创建过该唯一约束
+    #    （旧约束历史上仅由 create_all 依模型带出，链上无独立建约束迁移）。
+    #    全新环境顺序迁移到此处时约束并不存在，无条件 drop_constraint 会以
+    #    UndefinedObject 中断整条迁移链（create_all + stamp head 的盲区）。
+    #    故先查 pg_constraint：存在（存量库）才 DROP；不存在（全新空库）跳过，
+    #    由下一步直接建立 NULLS NOT DISTINCT 约束。两种路径最终 schema 一致。
+    op.execute(
+        f"""
+        DO $do$
+        BEGIN
+            IF EXISTS (
+                SELECT 1 FROM pg_constraint
+                WHERE conrelid = 'cs_records'::regclass
+                  AND conname = '{_CONSTRAINT_NAME}'
+            ) THEN
+                ALTER TABLE cs_records DROP CONSTRAINT {_CONSTRAINT_NAME};
+            END IF;
+        END $do$;
+        """
+    )
+
+    # 2) 重建为 NULLS NOT DISTINCT：NULL 视为相等值，参与去重
+    #    这样即使 problem_create_time 为 NULL，重复行也会被数据库拒绝。
+    #    与 upsert.py 的 on_conflict_do_nothing(constraint=...) 同名，无需改业务代码。
+    op.execute(
+        f"ALTER TABLE cs_records ADD CONSTRAINT {_CONSTRAINT_NAME} "
+        f"UNIQUE NULLS NOT DISTINCT ({', '.join(_UNIQUE_COLS)})"
+    )
+
+
+def downgrade() -> None:
+    # 回滚为默认 NULLS DISTINCT（恢复原行为）
+    op.execute(f"ALTER TABLE cs_records DROP CONSTRAINT {_CONSTRAINT_NAME}")
+    op.create_unique_constraint(_CONSTRAINT_NAME, "cs_records", list(_UNIQUE_COLS))

backend/alembic/versions/a2c4e6f8b0d2_add_policies_and_dept_syncs.py

@@ -20,10 +20,11 @@ Create Date: 2026-08-09 09:00:00.000000
 
 from typing import Sequence, Union
 
-from alembic import op
 import sqlalchemy as sa
 from sqlalchemy.dialects import postgresql
 
+from alembic import op
+
 # revision identifiers, used by Alembic.
 revision: str = 'a2c4e6f8b0d2'
 down_revision: Union[str, None] = 'z9y8x7w6v5u4'

backend/alembic/versions/a332b05d6e7f_add_arbiter_pick_dim_device_merchant.py

@@ -0,0 +1,41 @@
+"""#332 T5: dim_device_merchant 加仲裁标记列 arbiter_pick
+
+背景(tasks.md T5 取舍决策): 同 SN 同时段多商户(overlap)时, 消费侧需一个
+**可仲裁标记** 决定优先展示哪家。实现时二选一(维表加列 vs 消费侧 JOIN devices
+现算)—— 选「维表加列」: 仲裁依据 devices.merchant_name 只在构建期稳定可得,
+物化后消费侧 as-of JOIN 无需再回查设备档案, 口径集中在维表一处。
+
+- arbiter_pick BOOLEAN NOT NULL DEFAULT FALSE: 仅对 conflict_flag='overlap'
+  的分段可能有意义; TRUE 表示该分段所属商户被设备档案 merchant_name 仲裁选中
+  (精确命中商户名优先, 其次命中集团名, 每 SN 至多 1 家)。
+
+Revision ID: a332b05d6e7f
+Revises: f332a01b2c3d
+Create Date: 2026-10-16 22:30:00.000000
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "a332b05d6e7f"
+down_revision: str = "f332a01b2c3d"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "dim_device_merchant",
+        sa.Column(
+            "arbiter_pick", sa.Boolean(), nullable=False, server_default=sa.text("false"),
+            comment="仲裁选中: TRUE=同 SN overlap 分段中被设备档案 merchant_name 选中的商户分段",
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("dim_device_merchant", "arbiter_pick")

backend/alembic/versions/a3b4c5d6e7f8_llm_role_members_many_to_many.py

@@ -0,0 +1,105 @@
+"""llm_role_members 关联表 —— 修复「一模型多角色」限制
+
+背景（2026-09-21，见 docs/design/20260921-模型角色分组与出域管控设计.md §3.1）:
+
+  原设计用 `llm_providers.role_scope`（单值列）表达角色归属，假设「一模型一角色」。
+  **部署后立即被实测证伪**: `qwen3-coder:30b` 需同时服务
+    - assistant  的首选（实测语义匹配 6/6 全对、快 3x）
+    - specialist 的备选（27b 失败时的降级目标）
+  单值列下相互覆盖，导致 assistant 降级为 `qwen2.5:7b`
+  —— 该模型实测语义匹配 **5/5 全错**，比源码常量更差。
+
+  本迁移建立多对多关联表，是正式修复。
+
+数据迁移策略（关键）:
+  1. 建表
+  2. 把 llm_providers 中已有的 role_scope/role_order 迁入新表（幂等）
+  3. 补充「已知的多角色归属」——即本次暴露的问题本身:
+     coder-30b 同时属于 assistant(1) 与 specialist(2)
+  4. **保留** role_scope/role_order 列一个版本（读时兜底），
+     待运行时确认只读新表后再删除
+
+Revision ID: a3b4c5d6e7f8
+Revises: e5f6a7b8c9d1
+Create Date: 2026-09-21 09:35:00.000000
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = 'a3b4c5d6e7f8'
+down_revision: Union[str, None] = 'e5f6a7b8c9d1'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "llm_role_members",
+        sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
+        sa.Column("role_key", sa.String(32), nullable=False,
+                  comment="角色键(assistant/specialist/expert)"),
+        sa.Column("provider_code", sa.String(64), nullable=False,
+                  comment="provider code(快照)"),
+        sa.Column("sort_order", sa.Integer(), nullable=False, server_default=sa.text("100"),
+                  comment="角色内兜底顺序(小=先尝试)"),
+        sa.Column("enabled", sa.Boolean(), nullable=False, server_default=sa.text("true"),
+                  comment="该成员在本角色内是否启用"),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False,
+                  server_default=sa.text("now()")),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False,
+                  server_default=sa.text("now()")),
+        sa.UniqueConstraint("role_key", "provider_code",
+                            name="uq_llm_role_members_role_provider"),
+    )
+    op.create_index("ix_llm_role_members_role_key", "llm_role_members", ["role_key"])
+    op.create_index("ix_llm_role_members_provider_code", "llm_role_members", ["provider_code"])
+
+    # 2) 迁移已有单值归属（幂等，重复执行不报错）
+    op.execute("""
+        INSERT INTO llm_role_members (role_key, provider_code, sort_order, enabled)
+        SELECT role_scope, code, role_order, true
+          FROM llm_providers
+         WHERE role_scope IS NOT NULL
+           AND role_scope <> ''
+        ON CONFLICT (role_key, provider_code) DO NOTHING
+    """)
+
+    # 3) 补充多角色归属（本次证伪的正是这一条）
+    #    coder-30b 同时服务 assistant(首选) 与 specialist(备选:
+    #    27b 失败时降级目标, 实测 coder-30b 快 3x)
+    op.execute("""
+        INSERT INTO llm_role_members (role_key, provider_code, sort_order, enabled)
+        SELECT 'assistant', code, 1, true FROM llm_providers
+         WHERE code = 'talon-gmk-qwen3-coder-30b'
+        ON CONFLICT (role_key, provider_code) DO NOTHING
+    """)
+    op.execute("""
+        INSERT INTO llm_role_members (role_key, provider_code, sort_order, enabled)
+        SELECT 'specialist', code, 2, true FROM llm_providers
+         WHERE code = 'talon-gmk-qwen3-coder-30b'
+        ON CONFLICT (role_key, provider_code) DO NOTHING
+    """)
+    # assistant 备选: 7b（降级兜底；注意它实测语义匹配会错，但作最后兜底仍优于无）
+    op.execute("""
+        INSERT INTO llm_role_members (role_key, provider_code, sort_order, enabled)
+        SELECT 'assistant', code, 2, true FROM llm_providers
+         WHERE code = 'talon-gmk-qwen2.5-7b'
+        ON CONFLICT (role_key, provider_code) DO NOTHING
+    """)
+    # expert 备选: 27b
+    op.execute("""
+        INSERT INTO llm_role_members (role_key, provider_code, sort_order, enabled)
+        SELECT 'expert', code, 2, true FROM llm_providers
+         WHERE code = 'talon-gmk-qwen3.8-27b'
+        ON CONFLICT (role_key, provider_code) DO NOTHING
+    """)
+
+
+def downgrade() -> None:
+    op.drop_index("ix_llm_role_members_provider_code", table_name="llm_role_members")
+    op.drop_index("ix_llm_role_members_role_key", table_name="llm_role_members")
+    op.drop_table("llm_role_members")

backend/alembic/versions/a3f8c2e91b4d_add_analysis_views_and_classification_rules.py

@@ -10,10 +10,11 @@ Create Date: 2026-07-26 18:00:00.000000
 """
 from typing import Sequence, Union
 
-from alembic import op
 import sqlalchemy as sa
 from sqlalchemy.dialects import postgresql
 
+from alembic import op
+
 revision: str = 'a3f8c2e91b4d'
 down_revision: Union[str, None] = 'd9b7f1b89c1d'
 branch_labels: Union[str, Sequence[str], None] = None

backend/alembic/versions/a4b5c6d7e8f0_pregen_template_realign_306.py

@@ -0,0 +1,82 @@
+"""pregen_template_realign: AI 预生成模板收敛 (#306)
+
+Revision ID: a4b5c6d7e8f0
+Revises: f299combo
+Create Date: 2026-10-12
+
+#306 AI 模板报告预生成收敛(生产 26 天命中率审计后拍板):
+
+1. 五个保留模板(daily×3 / weekly / monthly)的专用 provider 由冷备
+   talon-gmk-qwen3.8-27b 切到热驻 talon-gmk-gpt-oss-120b:
+   27b 已转冷备(preload=false), 每次预生成触发 ~80s 冷加载并与 node-4090
+   热驻 coder-30b 抢显存; 10-12 冒烟实测已全部兜底跑到 120b。
+   仅更新当前仍为 27b 的行(可重入, 不覆盖之后的人工调整)。
+2. rolling_7d_compare / rolling_30d_compare 停用(is_active=false):
+   26 天命中率 rolling_7d 1/27(3.7%)、rolling_30d 0/26, 且与自然周/月报
+   语义重叠; 停用后相关问句走实时 LLM 兜底, 历史报告保留可命中。
+
+code/provider 均为本文件内固定字面量(非外部输入), 沿用仓库数据迁移的内联写法。
+配套代码变更(同工单): worker 触发日当天漏跑当补 + settings 默认 skip 模式 off。
+"""
+from typing import Sequence, Union
+
+from alembic import op
+
+revision: str = 'a4b5c6d7e8f0'
+down_revision: Union[str, None] = 'f299combo'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # 1. 保留模板: 27b → 120b(仅当前仍指向 27b 的行, 重复执行幂等)
+    op.execute(
+        """
+        UPDATE ai_report_templates
+        SET llm_provider_code = 'talon-gmk-gpt-oss-120b'
+        WHERE code IN (
+                  'daily_general_morning',
+                  'daily_refund_brief',
+                  'daily_complaint_brief',
+                  'weekly_compare_last',
+                  'monthly_overview'
+              )
+          AND llm_provider_code = 'talon-gmk-qwen3.8-27b'
+        """
+    )
+    # 2. 滚动模板停用(幂等: 已是 false 的行不受影响; 历史 ai_reports 保留)
+    op.execute(
+        """
+        UPDATE ai_report_templates
+        SET is_active = FALSE
+        WHERE code IN ('rolling_7d_compare', 'rolling_30d_compare')
+          AND is_active = TRUE
+        """
+    )
+
+
+def downgrade() -> None:
+    # 回滚滚动模板为启用
+    op.execute(
+        """
+        UPDATE ai_report_templates
+        SET is_active = TRUE
+        WHERE code IN ('rolling_7d_compare', 'rolling_30d_compare')
+          AND is_active = FALSE
+        """
+    )
+    # 回滚 provider: 120b → 27b(仅本工单迁移覆盖的 5 个 code)
+    op.execute(
+        """
+        UPDATE ai_report_templates
+        SET llm_provider_code = 'talon-gmk-qwen3.8-27b'
+        WHERE code IN (
+                  'daily_general_morning',
+                  'daily_refund_brief',
+                  'daily_complaint_brief',
+                  'weekly_compare_last',
+                  'monthly_overview'
+              )
+          AND llm_provider_code = 'talon-gmk-gpt-oss-120b'
+        """
+    )

backend/alembic/versions/a6f7a8b9c1d0_merchant_refund_unique_time_order.py

@@ -12,7 +12,6 @@ from typing import Sequence, Union
 
 from alembic import op
 
-
 revision: str = 'a6f7a8b9c1d0'
 down_revision: Union[str, None] = 'z5e6f7a8b9c0'
 branch_labels: Union[str, Sequence[str], None] = None

backend/alembic/versions/a7b6c5d4e3f2_ai_template_detail_level_and_dimensions.py

@@ -0,0 +1,81 @@
+"""ai_report_templates 加 detail_level + required_dimensions (工单 #152)
+
+AI 回答模式分级框架(A-20260919-001)模板配置扩展:
+- detail_level: 模板期望的回答详细级别 brief/standard/deep(预生成按此组织输出密度)
+- required_dimensions: 业务维度清单(JSONB 关键词数组), 供完整性校验器检查快照维度覆盖;
+  NULL=不做完整性校验(简报类)
+
+种子回填现有 3 模板(按 code, 幂等):
+- daily_general_morning: 明细级(standard), 维度=接待/退款/四路/涉诉/挽回/投诉/结论
+- weekly_compare_last / monthly_overview: 深度级(deep), 维度同日报+趋势对比/环比/同比
+
+Revision ID: a7b6c5d4e3f2
+Revises: dc20f480c17e
+Create Date: 2026-09-19
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+from alembic import op
+
+revision: str = 'a7b6c5d4e3f2'
+down_revision: Union[str, None] = 'dc20f480c17e'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+# 种子回填: code → (detail_level, required_dimensions)
+_SEED: dict[str, tuple[str, list[str]]] = {
+    "daily_general_morning": (
+        "standard",
+        ["接待", "退款", "四路", "涉诉", "挽回", "投诉", "结论"],
+    ),
+    "weekly_compare_last": (
+        "deep",
+        ["接待", "退款", "四路", "涉诉", "挽回", "投诉", "趋势", "环比", "结论"],
+    ),
+    "monthly_overview": (
+        "deep",
+        ["接待", "退款", "四路", "涉诉", "挽回", "投诉", "趋势", "同比", "结论"],
+    ),
+}
+
+
+def upgrade() -> None:
+    op.add_column(
+        "ai_report_templates",
+        sa.Column(
+            "detail_level", sa.String(length=16), nullable=False,
+            server_default="standard",
+            comment="#152 回答详细级别: brief/standard/deep(预生成按此组织输出密度)",
+        ),
+    )
+    op.add_column(
+        "ai_report_templates",
+        sa.Column(
+            "required_dimensions", postgresql.JSONB(astext_type=sa.Text()), nullable=True,
+            comment=(
+                "#152 业务维度清单(JSONB 关键词数组, 如 [\"四路\",\"涉诉\",\"挽回\"]); "
+                "完整性校验器按此检查快照维度覆盖; NULL=不做校验"
+            ),
+        ),
+    )
+    # 种子回填(按 code 幂等更新; 用户已改过的模板会被覆盖, 属预期种子)
+    for code, (detail_level, dims) in _SEED.items():
+        op.execute(
+            sa.text(
+                "UPDATE ai_report_templates "
+                "SET detail_level = :detail, required_dimensions = :dims "
+                "WHERE code = :code"
+            ).bindparams(
+                sa.bindparam("detail", value=detail_level),
+                sa.bindparam("dims", value=dims, type_=postgresql.JSONB()),
+                sa.bindparam("code", value=code),
+            )
+        )
+
+
+def downgrade() -> None:
+    op.drop_column("ai_report_templates", "required_dimensions")
+    op.drop_column("ai_report_templates", "detail_level")

backend/alembic/versions/a7b8c9d0e1f2_add_urge_dispatch_fields_to_service_tickets.py

@@ -16,9 +16,9 @@ Create Date: 2026-08-03 11:50:00.000000
 """
 from typing import Sequence, Union
 
-from alembic import op
 import sqlalchemy as sa
 
+from alembic import op
 
 # revision identifiers, used by Alembic.
 revision: str = 'a7b8c9d0e1f2'

backend/alembic/versions/a8b9c0d1e2f3_llm_providers_and_call_logs.py

@@ -0,0 +1,168 @@
+"""llm_providers + llm_call_logs: LLM 多 Provider 框架 (工单 #108)
+
+Revision ID: a8b9c0d1e2f3
+Revises: b3c4d5e6f7a8
+Create Date: 2026-09-15 22:30:00.000000
+
+设计:
+1. llm_providers 表: 多 Provider 接入(本地 Talon 网关 / 云端 DeepSeek)
+   - API key Fernet 加密入库(同 sync_source_configs)
+   - priority 升序遍历, transient 错误降级下一个
+   - healthy/失败计数/最近失败时间: 连续失败 N 次自动降级
+2. llm_call_logs 表: 每次调用一行审计(成功/失败均记), 不打敏感数据
+3. seed 3 条默认 Provider:
+   - talon-gmk-qwen3-coder-30b (主力, priority=10): 本地 Talon 网关 qwen3-coder:30b
+   - talon-gmk-qwen2.5-7b (兜底, priority=20): 本地 Talon 网关 qwen2.5:7b
+   - deepseek-v4-flash (云端兜底, priority=30, enabled=false 默认禁用):
+     云端 DeepSeek, 防止本地节点全挂时业务中断(运维按需启用)
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'a8b9c0d1e2f3'
+down_revision: Union[str, None] = 'b3c4d5e6f7a8'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def _encrypt(plaintext: str | None) -> str | None:
+    """Fernet 加密; 失败时返回 None(等同未配 key)"""
+    if not plaintext:
+        return None
+    try:
+        from app.core.crypto import encrypt_secret
+        return encrypt_secret(plaintext)
+    except Exception:
+        return None
+
+
+def upgrade() -> None:
+    # ── llm_providers ──
+    op.create_table(
+        'llm_providers',
+        sa.Column('id', sa.BigInteger(), autoincrement=True, nullable=False),
+        sa.Column('code', sa.String(length=64), nullable=False),
+        sa.Column('name', sa.String(length=128), nullable=False),
+        sa.Column('base_url', sa.String(length=256), nullable=False),
+        sa.Column('model', sa.String(length=128), nullable=False),
+        sa.Column('api_key_cipher', sa.Text(), nullable=True),
+        sa.Column('api_key_prefix', sa.String(length=16), nullable=True),
+        sa.Column('priority', sa.Integer(), nullable=False, server_default='100'),
+        sa.Column('enabled', sa.Boolean(), nullable=False, server_default=sa.text('true')),
+        sa.Column('healthy', sa.Boolean(), nullable=False, server_default=sa.text('true')),
+        sa.Column('thinking', sa.String(length=16), nullable=False, server_default='disabled'),
+        sa.Column('timeout_s', sa.Float(), nullable=False, server_default='120.0'),
+        sa.Column('retry_max', sa.Integer(), nullable=False, server_default='2'),
+        sa.Column('fail_threshold', sa.Integer(), nullable=False, server_default='3'),
+        sa.Column('fail_count', sa.Integer(), nullable=False, server_default='0'),
+        sa.Column('last_fail_at', sa.DateTime(timezone=True), nullable=True),
+        sa.Column('last_success_at', sa.DateTime(timezone=True), nullable=True),
+        sa.Column('note', sa.String(length=255), nullable=True),
+        sa.Column('created_by', sa.String(length=64), nullable=True),
+        sa.Column('updated_by', sa.String(length=64), nullable=True),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.PrimaryKeyConstraint('id'),
+        sa.UniqueConstraint('code'),
+    )
+    op.create_index('ix_llm_providers_code', 'llm_providers', ['code'])
+    op.create_index('ix_llm_providers_priority', 'llm_providers', ['priority'])
+    op.create_index('ix_llm_providers_enabled', 'llm_providers', ['enabled'])
+    op.create_index('ix_llm_providers_healthy', 'llm_providers', ['healthy'])
+
+    # ── llm_call_logs ──
+    op.create_table(
+        'llm_call_logs',
+        sa.Column('id', sa.BigInteger(), autoincrement=True, nullable=False),
+        sa.Column('provider_id', sa.Integer(), nullable=True),
+        sa.Column('provider_code', sa.String(length=64), nullable=True),
+        sa.Column('model', sa.String(length=128), nullable=True),
+        sa.Column('status', sa.String(length=16), nullable=False),
+        sa.Column('status_code', sa.Integer(), nullable=True),
+        sa.Column('duration_ms', sa.Integer(), nullable=False),
+        sa.Column('prompt_chars', sa.Integer(), nullable=True),
+        sa.Column('out_chars', sa.Integer(), nullable=True),
+        sa.Column('error_message', sa.Text(), nullable=True),
+        sa.Column('source', sa.String(length=32), nullable=True),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.PrimaryKeyConstraint('id'),
+    )
+    op.create_index('ix_llm_call_logs_provider_id', 'llm_call_logs', ['provider_id'])
+    op.create_index('ix_llm_call_logs_status', 'llm_call_logs', ['status'])
+    op.create_index('ix_llm_call_logs_source', 'llm_call_logs', ['source'])
+    op.create_index('ix_llm_call_logs_created_at', 'llm_call_logs', ['created_at'])
+
+    # ── seed 3 条默认 Provider ──
+    # ⚠️ 安全: 不在 migration 里硬编码任何 API key(gitleaks 会拦)。
+    #    key 由运维在「LLM 模型接入」管理界面手动填(POST /llm-providers);
+    #    seed 仅写 base_url/model/priority/note, api_key_cipher 留 NULL。
+    # 注: 读取 .env 的 LLM_API_KEY/LLM_BASE_URL/LLM_MODEL 作为 DeepSeek seed 的
+    #    默认值(运维在管理界面改); 其它 Provider 的 key 一律由运维手动填。
+    bind = op.get_bind()
+    deepseek_key = ''
+    deepseek_url = 'https://api.deepseek.com'
+    deepseek_model = 'deepseek-v4-flash'
+    try:
+        from app.core.config import settings  # type: ignore
+        deepseek_key = settings.LLM_API_KEY or ''
+        if settings.LLM_BASE_URL:
+            deepseek_url = settings.LLM_BASE_URL
+        if settings.LLM_MODEL:
+            deepseek_model = settings.LLM_MODEL
+    except Exception:
+        pass
+
+    talon_url = 'http://192.168.10.21:4080/v1'
+
+    # 1) 主力: Talon gmk-evo qwen3-coder:30b
+    op.execute(sa.text(
+        "INSERT INTO llm_providers (code, name, base_url, model, api_key_cipher, api_key_prefix, "
+        "priority, enabled, healthy, thinking, timeout_s, retry_max, fail_threshold, fail_count, note, created_by, updated_by) "
+        "VALUES (:code, :name, :base_url, :model, NULL, NULL, "
+        "10, true, true, 'disabled', 120.0, 2, 3, 0, :note, 'system', 'system')"
+    ).bindparams(
+        code='talon-gmk-qwen3-coder-30b',
+        name='Talon·GMK·qwen3-coder:30b',
+        base_url=talon_url,
+        model='qwen3-coder:30b',
+        note='主力模型: Talon 网关 gmk-evo(192.168.10.21:11434) qwen3-coder:30b 17GB; Radeon 8060S 64GB; API key 需运维在管理界面填',
+    ))
+
+    # 2) 兜底: Talon qwen2.5:7b(轻量, 主力挂时降级用)
+    op.execute(sa.text(
+        "INSERT INTO llm_providers (code, name, base_url, model, api_key_cipher, api_key_prefix, "
+        "priority, enabled, healthy, thinking, timeout_s, retry_max, fail_threshold, fail_count, note, created_by, updated_by) "
+        "VALUES (:code, :name, :base_url, :model, NULL, NULL, "
+        "20, true, true, 'disabled', 90.0, 2, 3, 0, :note, 'system', 'system')"
+    ).bindparams(
+        code='talon-gmk-qwen2.5-7b',
+        name='Talon·GMK·qwen2.5:7b',
+        base_url=talon_url,
+        model='qwen2.5:7b',
+        note='兜底模型: Talon 网关 qwen2.5:7b; 主力挂或并发高时降级用; API key 需运维在管理界面填',
+    ))
+
+    # 3) 云端兜底: DeepSeek(默认禁用, 运维按需启用)
+    op.execute(sa.text(
+        "INSERT INTO llm_providers (code, name, base_url, model, api_key_cipher, api_key_prefix, "
+        "priority, enabled, healthy, thinking, timeout_s, retry_max, fail_threshold, fail_count, note, created_by, updated_by) "
+        "VALUES (:code, :name, :base_url, :model, :key_cipher, :key_prefix, "
+        "30, :enabled, true, 'disabled', 120.0, 2, 3, 0, :note, 'system', 'system')"
+    ).bindparams(
+        code='deepseek-v4-flash',
+        name='DeepSeek·v4-flash',
+        base_url=deepseek_url,
+        model=deepseek_model,
+        key_cipher=_encrypt(deepseek_key) if deepseek_key else None,
+        key_prefix=(deepseek_key[:6] or None),
+        enabled=False,  # 默认禁用; 运维按需启用
+        note='云端兜底: DeepSeek 官方 API; 默认禁用, 本地节点全挂时运维启用',
+    ))
+
+
+def downgrade() -> None:
+    op.drop_table('llm_call_logs')
+    op.drop_table('llm_providers')

backend/alembic/versions/a9b0c1d2e3f4_issue322_refund_clean_view.py

@@ -0,0 +1,50 @@
+"""#322 方案A: 新建只读精简视图 public.refund_clean (over ods.refunds)
+
+背景(#319/#322 数据分层):
+- #319 已把退款信源表移入 ods schema; C2 契约要求 services/analytics/** 不得直读 ods 源表。
+- 本迁移为 refund 域落地「方案A」: 建只读视图把 analytics 对 refunds 的读取全部切到
+  public.refund_clean。**口径不变** —— 逐列取自 ods.refunds, 不新增任何加工。
+
+暴露列(21 列, = analytics 实际消费集合):
+  refund_no, platform_order_no, third_order_no, device_sn, refund_reason, package_name,
+  merchant_name, refund_amount, actual_amount, remark, status, refund_method,
+  audit_remark, auditor, operator, created_at_raw, updated_at_raw, actual_refund_time,
+  quality_status, created_at, updated_at
+不暴露的 5 列(明确无用/内部溯源, 不为切换扩表): package_price, raw_extra, synced_at,
+  updated_by_raw, quality_note
+
+写入不受影响: upsert(_refunds.py) 与 actual_refund_time 回填仍直写 ods.refunds(经 Refund 模型),
+视图仅给 analytics 读。
+
+Revision ID: a9b0c1d2e3f4
+Revises: f8a9b0c1d2e3
+Create Date: 2026-10-14 00:30:00.000000
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "a9b0c1d2e3f4"
+down_revision: str = "f8a9b0c1d2e3"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+# 21 列 DDL 片段(与 conftest 视图重建逐字一致, 改一处须同步另一处)
+_REFUND_CLEAN_COLUMNS = (
+    "refund_no, platform_order_no, third_order_no, device_sn, refund_reason, package_name, "
+    "merchant_name, refund_amount, actual_amount, remark, status, refund_method, "
+    "audit_remark, auditor, operator, created_at_raw, updated_at_raw, actual_refund_time, "
+    "quality_status, created_at, updated_at"
+)
+
+
+def upgrade() -> None:
+    op.execute(
+        f"CREATE VIEW public.refund_clean AS SELECT {_REFUND_CLEAN_COLUMNS} FROM ods.refunds"
+    )
+
+
+def downgrade() -> None:
+    op.execute("DROP VIEW IF EXISTS public.refund_clean")

backend/alembic/versions/aa11bb22cc33_expand_ticket_short_varchars.py

@@ -15,9 +15,9 @@ Create Date: 2026-08-07 23:00:00.000000
 """
 from typing import Sequence, Union
 
-from alembic import op
 import sqlalchemy as sa
 
+from alembic import op
 
 # revision identifiers, used by Alembic.
 revision: str = 'aa11bb22cc33'

backend/alembic/versions/b0c1d2e3f4a5_phase_b_schedule_invoice_kb_alert.py

@@ -14,10 +14,10 @@ Create Date: 2026-08-18 01:00:00.000000
 """
 from typing import Sequence, Union
 
-from alembic import op
 import sqlalchemy as sa
 from sqlalchemy.dialects import postgresql
 
+from alembic import op
 
 revision: str = 'b0c1d2e3f4a5'
 down_revision: Union[str, None] = 'a0b1c2d3e4f5'

backend/alembic/versions/b1_5_1_incident_event_extension.py

@@ -0,0 +1,107 @@
+"""extend incidents with event_type / target_audience / start_at / end_at / impact_metrics
+
+B1.5-1 (#232) 经营事件时间轴标注 - 表结构变更:
+
+incidents 原表只支持「异常事故」登记(occurred_at + duration_minutes 表示点事件 +
+持续时长)。本次扩展支持两种事件类型:
+  - 异常事故 (默认, 与原语义一致): occurred_at + duration_minutes
+  - 经营事件 (新增): 推文/广告/活动/定期维护等可预期事件, 用 start_at + end_at
+    表示持续时间区间(点事件 end_at=null)
+
+新增字段:
+  - event_type       String(16) NOT NULL DEFAULT '异常事故'
+                     取值: '经营事件' / '异常事故' (用 String 而非 PG ENUM,
+                     与现有 status/severity/category 等同字段保持一致,
+                     避免 ENUM 修改成本)
+  - target_audience  Text, 推文/活动目标群体描述(经营事件用)
+  - start_at         TIMESTAMPTZ, 经营事件生效起(含)
+  - end_at           TIMESTAMPTZ, 经营事件生效止(含, NULL=点事件或无限期)
+  - impact_metrics   JSONB, 量化影响指标 {key: value} 用于事件与数据对照(进
+                     一步在 B1.5-3 趋势曲线叠加中消费)
+
+不变字段:
+  - occurred_at / duration_minutes 保留, 仅服务于「异常事故」类型; 经营事件
+    也可填 occurred_at 表示事件发生时点(用于时间轴打点), 但通常 start_at/end_at
+    更适合表达持续时间区间。
+
+Revision ID: b1_5_1_incident_event
+Revises: t0u1v2w3x4y5
+Create Date: 2026-10-08 11:50:00.000000
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+from alembic import op
+
+revision: str = 'b1_5_1_incident_event'
+down_revision: Union[str, None] = 't0u1v2w3x4y5'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # 1) 新增列(全部 nullable / 有默认值, 与历史数据兼容)
+    #    event_type 给默认值 '异常事故', 这样存量行无需回填即可读为「异常事故」
+    op.add_column(
+        'incidents',
+        sa.Column(
+            'event_type',
+            sa.String(length=16),
+            nullable=False,
+            server_default='异常事故',
+            comment='事件类型: 经营事件/异常事故(默认)',
+        ),
+    )
+    op.add_column(
+        'incidents',
+        sa.Column(
+            'target_audience',
+            sa.Text(),
+            nullable=True,
+            comment='目标群体(经营事件用: 推文/活动受众描述)',
+        ),
+    )
+    op.add_column(
+        'incidents',
+        sa.Column(
+            'start_at',
+            sa.DateTime(timezone=True),
+            nullable=True,
+            comment='经营事件生效起始(含, 与 end_at 共同表达持续时间区间)',
+        ),
+    )
+    op.add_column(
+        'incidents',
+        sa.Column(
+            'end_at',
+            sa.DateTime(timezone=True),
+            nullable=True,
+            comment='经营事件生效结束(含, NULL=点事件或无限期)',
+        ),
+    )
+    op.add_column(
+        'incidents',
+        sa.Column(
+            'impact_metrics',
+            postgresql.JSONB(astext_type=sa.Text()),
+            nullable=True,
+            comment='量化影响指标 {key: value} (用于事件与数据对照)',
+        ),
+    )
+
+    # 2) 索引: event_type 用于筛选(经营事件 vs 异常事故)
+    #    start_at 用于时间轴查询(按生效起排序)
+    op.create_index('ix_incidents_event_type', 'incidents', ['event_type'])
+    op.create_index('ix_incidents_start_at', 'incidents', ['start_at'])
+
+
+def downgrade() -> None:
+    op.drop_index('ix_incidents_start_at', table_name='incidents')
+    op.drop_index('ix_incidents_event_type', table_name='incidents')
+    op.drop_column('incidents', 'impact_metrics')
+    op.drop_column('incidents', 'end_at')
+    op.drop_column('incidents', 'start_at')
+    op.drop_column('incidents', 'target_audience')
+    op.drop_column('incidents', 'event_type')

backend/alembic/versions/b1_5_4_scheduling_suggestion.py

@@ -0,0 +1,40 @@
+"""add scheduling_suggestion to incidents for B1.5-4 排班联动
+
+B1.5-4 (#235) 事件关联排班调整建议 — 字段登记:
+
+incidents 新增 scheduling_suggestion (Text, nullable):
+  - 经营事件登记时可填排班调整建议(如"推文后加早班1人"、"活动期间增开2号位")
+  - 仅做字段登记, 排班页关联事件展示等后置于 B3-8 排班目标形态决策
+  - 异常事故通常不涉及排班调整, 该字段留空
+
+Revision ID: b1_5_4_scheduling_suggestion
+Revises: b1_5_1_incident_event
+Create Date: 2026-10-08 12:10:00.000000
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'b1_5_4_scheduling_suggestion'
+down_revision: Union[str, None] = 'b1_5_1_incident_event'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # 新增 scheduling_suggestion 字段(排班调整建议, 仅经营事件用, 可空)
+    op.add_column(
+        'incidents',
+        sa.Column(
+            'scheduling_suggestion',
+            sa.Text(),
+            nullable=True,
+            comment='排班调整建议(经营事件用, 如"推文后加早班1人")',
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column('incidents', 'scheduling_suggestion')

backend/alembic/versions/b1c2d3e4f5a6_llm_providers_add_is_cloud_role_scope_.py

@@ -0,0 +1,96 @@
+"""llm_providers 增 is_cloud/role_scope/role_order（数据出域管控 + 角色归属）
+
+背景（2026-09-21，见 docs/design/20260921-模型角色分组与出域管控设计.md）:
+
+  原实现把云端 provider(deepseek-v4-flash) 硬编码为所有能力档位的兜底项
+  （llm_tiers.CLOUD_FALLBACK）。本地模型 transient 失败时（实测 27b 曾 30% 超时）
+  会**静默把 prompt 发给 api.deepseek.com**，而 prompt 含真实客服工单数据 ——
+  与「数据不出内网」的核心定位冲突，且无开关、无审计标记。
+
+  本迁移为出域管控与角色分组提供数据基础。
+
+  数据回填策略（关键，避免改变现有行为）:
+    - 公网域名（如 api.deepseek.com）→ is_cloud=true
+    - 内网 IP / localhost / docker 内部 → is_cloud=false
+    - role_scope 不预填（留 NULL=不限角色），由管理界面配置；
+      运行时 resolve_tier() 在 DB 无角色配置时回退 llm_tiers.py 常量，行为不变。
+
+Revision ID: b1c2d3e4f5a6
+Revises: p7q8r9s0t1u2
+Create Date: 2026-09-21 09:23:22.970514
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision: str = 'b1c2d3e4f5a6'
+down_revision: Union[str, None] = 'p7q8r9s0t1u2'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # 1) is_cloud: 是否出域。默认 false（保守），随后按 base_url 回填云端标记。
+    op.add_column(
+        "llm_providers",
+        sa.Column(
+            "is_cloud", sa.Boolean(), nullable=False, server_default=sa.text("false"),
+            comment="是否出域(公网/云端); true 时受 LLM_CLOUD_POLICY 管控",
+        ),
+    )
+    op.create_index("ix_llm_providers_is_cloud", "llm_providers", ["is_cloud"])
+
+    # 2) role_scope: 角色归属; NULL = 不限角色（保持现有行为，由界面再配）
+    op.add_column(
+        "llm_providers",
+        sa.Column(
+            "role_scope", sa.String(32), nullable=True,
+            comment="角色归属(assistant/specialist/expert); NULL=不限角色",
+        ),
+    )
+    op.create_index("ix_llm_providers_role_scope", "llm_providers", ["role_scope"])
+
+    # 3) role_order: 角色内兜底顺序（小=先尝试）
+    op.add_column(
+        "llm_providers",
+        sa.Column(
+            "role_order", sa.Integer(), nullable=False, server_default=sa.text("100"),
+            comment="角色内兜底顺序(小=先尝试); 仅 role_scope 非空时有意义",
+        ),
+    )
+
+    # 4) 回填 is_cloud: 公网域名（非内网 IP / localhost）判为出域。
+    #    用 base_url 判定而非写死 code，新增云端 provider 时同样适用。
+    op.execute("""
+        UPDATE llm_providers
+           SET is_cloud = true
+         WHERE base_url NOT LIKE '%://127.0.0.1%'
+           AND base_url NOT LIKE '%://localhost%'
+           AND base_url NOT LIKE '%://host.docker.internal%'
+           AND base_url NOT LIKE '%://10.%'
+           AND base_url NOT LIKE '%://192.168.%'
+           AND base_url !~ '://172\\.(1[6-9]|2[0-9]|3[01])\\.'
+    """)
+
+    # 5) llm_call_logs 增 is_cloud: 事后审计「数据去过哪」。
+    #    快照式（调用时记录），不依赖 provider 当前配置变化。
+    op.add_column(
+        "llm_call_logs",
+        sa.Column(
+            "is_cloud", sa.Boolean(), nullable=False, server_default=sa.text("false"),
+            comment="本次调用是否出域(快照); 供事后审计数据流向",
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("llm_call_logs", "is_cloud")
+
+    op.drop_index("ix_llm_providers_role_scope", table_name="llm_providers")
+    op.drop_column("llm_providers", "role_order")
+    op.drop_column("llm_providers", "role_scope")
+
+    op.drop_index("ix_llm_providers_is_cloud", table_name="llm_providers")
+    op.drop_column("llm_providers", "is_cloud")

backend/alembic/versions/b2_5_long_report_tokens.py

@@ -0,0 +1,47 @@
+"""R-P1-4 (#240): 存量详尽长报告模板 max_tokens 兜底对齐 R3 下限 4000
+
+Revision ID: b2_5_long_report_tokens
+Revises: b1_5_4_scheduling_suggestion
+Create Date: 2026-10-09 14:00:00.000000
+
+背景:
+- R3《20260927 算力深度评估》结论: 详尽长报告经 1200→2400→4000 三轮迭代才不截断,
+  生产长报告 max_tokens 不应低于 4000。
+- 内置模板数据层已对齐(#134: weekly 4000/monthly 5000; rolling seed: rolling_7d
+  4000/rolling_30d 5000), 但历史上可能存在手动新建的周/月/滚动长报告模板仍 <4000
+  (旧创建入口统一默认 2000)。本迁移做**幂等兜底**: 仅把这些长报告模板的下限抬到
+  4000, GREATEST 保证已 ≥4000 的(如 monthly 5000)不被压低; 日报(daily)不在其列。
+
+注意:
+- 纯数据对齐, 无表结构变更(列本就无 server_default, ORM 默认由代码常量控制)。
+- downgrade 无法还原各行原值(未逐行备份), 故不做反向 UPDATE —— 把长报告下限从
+  4000 降回 2000 会重新引入截断, 没有回退价值。
+- revision id 长度受限(alembic_version.version_num varchar(32)), 故用短 id。
+"""
+from typing import Sequence, Union
+
+from sqlalchemy import text
+
+from alembic import op
+
+revision: str = 'b2_5_long_report_tokens'
+down_revision: Union[str, None] = 'b1_5_4_scheduling_suggestion'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # 详尽长报告(周/月/滚动)下限对齐 4000; GREATEST 保留已更高的设置(如 monthly 5000)。
+    op.execute(
+        text(
+            "UPDATE ai_report_templates "
+            "SET max_tokens = GREATEST(max_tokens, 4000), updated_at = NOW() "
+            "WHERE period IN ('weekly', 'monthly', 'rolling_7d', 'rolling_30d') "
+            "AND max_tokens < 4000"
+        )
+    )
+
+
+def downgrade() -> None:
+    # 见模块 docstring: 无法还原原值且回退会重新引入截断, 有意 no-op。
+    pass

backend/alembic/versions/b2_6_sync_watermark_split.py

@@ -0,0 +1,56 @@
+"""R-P1-16 (#241): 文档采集拆分「尝试心跳 last_attempt_at」与「成功水位 last_sync_at」
+
+Revision ID: b2_6_sync_watermark_split
+Revises: b2_5_long_report_tokens
+Create Date: 2026-10-09 15:00:00.000000
+
+背景:
+- doc_sync_sources / doc_sync_configs 的 last_sync_at 历史上成败都刷新, 同时充当
+  调度节流基准与看板成功水位 → 失败被当成功: 失败源静默等满整个 interval(默认 60min,
+  > 高频槽距 30min)才重试, 看板水位也被失败污染(R-P1-16)。
+- 本迁移新增 last_attempt_at(最近尝试, 无论成败); 应用层此后只在成功时刷 last_sync_at。
+
+存量回填:
+- last_attempt_at = last_sync_at(旧值本质是「最近一次记录时间」)。回填使加列后所有源
+  不会因 attempt 为 NULL 而在部署瞬间全部到期、并发触发 playwright; 未跑过的行
+  (last_sync_at IS NULL)仍保持 NULL → 首次恒到期。
+- 无法从历史数据恢复 failed 行「真正的上次成功时间」, 不做猜测; 此后新失败不再污染水位。
+
+downgrade: 纯新增列, 直接 DROP 即可安全回退(仅丢失新引入的尝试时间)。
+"""
+from typing import Sequence, Union
+
+from sqlalchemy import Column, DateTime, text
+
+from alembic import op
+
+revision: str = 'b2_6_sync_watermark_split'
+down_revision: Union[str, None] = 'b2_5_long_report_tokens'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        'doc_sync_sources',
+        # 最近一次尝试时间(调度节流心跳, 无论成败)
+        Column('last_attempt_at', DateTime(timezone=True), nullable=True),
+    )
+    op.add_column(
+        'doc_sync_configs',
+        Column('last_attempt_at', DateTime(timezone=True), nullable=True),
+    )
+    # 存量回填: 旧 last_sync_at 即最近记录时间; 仅回填非空行(空行保持 NULL=首次到期)
+    op.execute(text(
+        "UPDATE doc_sync_sources SET last_attempt_at = last_sync_at "
+        "WHERE last_attempt_at IS NULL AND last_sync_at IS NOT NULL"
+    ))
+    op.execute(text(
+        "UPDATE doc_sync_configs SET last_attempt_at = last_sync_at "
+        "WHERE last_attempt_at IS NULL AND last_sync_at IS NOT NULL"
+    ))
+
+
+def downgrade() -> None:
+    op.drop_column('doc_sync_configs', 'last_attempt_at')
+    op.drop_column('doc_sync_sources', 'last_attempt_at')

backend/alembic/versions/b2c3d4e5f6a7_add_scheduler_settings.py

@@ -0,0 +1,100 @@
+"""add scheduler_settings table (#51)
+
+Revision ID: b2c3d4e5f6a7
+Revises: f0a1b2c3d4e5
+Create Date: 2026-09-10 20:10:00.000000
+
+背景(#51, A-20260910-006 LOCKED v1.0):
+  高频采集节拍原为代码常量 `bms_scheduler.DAYTIME_HOURS = {8..23, 0}`(每小时),
+  管理员无法在界面调整。本表把「起止时段 + 间隔」DB 化, 支持页面自助修改且无需重启。
+
+新增表 `scheduler_settings`(**单行表**, id 恒为 1):
+  high_freq_start_hour       Integer  高频时段起(含), 默认 8
+  high_freq_end_hour         Integer  高频时段止(不含), 默认 24 (表示至当日 24:00)
+  high_freq_interval_minutes Integer  间隔(分钟), 默认 30
+  updated_by / created_at / updated_at
+
+默认值 = 目标态: 8:00~24:00 每 30 分钟(**32 槽/天**, 原 17 次/天)。
+
+⚠️ 纯新增表, 对既有表/接口零影响。
+⚠️ seed 幂等: 若 id=1 已存在则跳过(不覆盖用户改动, 遵循审计项 C-P2-2)。
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'b2c3d4e5f6a7'
+down_revision: Union[str, None] = 'f0a1b2c3d4e5'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+_TABLE = 'scheduler_settings'
+_SINGLETON_ID = 1
+
+
+def _table_exists(table_name: str) -> bool:
+    """表存在性检查(幂等升级规范: create_all 环境可能已建表)。"""
+    bind = op.get_bind()
+    sql = sa.text(
+        "SELECT 1 FROM information_schema.tables "
+        "WHERE table_schema='public' AND table_name=:t"
+    )
+    return bind.execute(sql, {"t": table_name}).scalar() is not None
+
+
+def upgrade() -> None:
+    if not _table_exists(_TABLE):
+        op.create_table(
+            _TABLE,
+            sa.Column('id', sa.BigInteger(), autoincrement=True, nullable=False),
+            sa.Column('high_freq_start_hour', sa.Integer(), nullable=False,
+                      server_default=sa.text('8'), comment='高频时段起(含), 北京时区小时 0~23'),
+            sa.Column('high_freq_end_hour', sa.Integer(), nullable=False,
+                      server_default=sa.text('24'), comment='高频时段止(不含), 1~24; 24 表示至当日 24:00'),
+            sa.Column('high_freq_interval_minutes', sa.Integer(), nullable=False,
+                      server_default=sa.text('30'), comment='采集间隔(分钟), 5~180'),
+            sa.Column('updated_by', sa.String(length=64), nullable=True, comment='最后修改人账号'),
+            sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+            sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+            sa.PrimaryKeyConstraint('id'),
+            # DB 层最后防线(应用层已有 400 校验, 此处防手工改库写入非法值)
+            sa.CheckConstraint(
+                "high_freq_start_hour >= 0 AND high_freq_start_hour <= 23",
+                name="ck_scheduler_settings_start_hour",
+            ),
+            sa.CheckConstraint(
+                "high_freq_end_hour >= 1 AND high_freq_end_hour <= 24",
+                name="ck_scheduler_settings_end_hour",
+            ),
+            sa.CheckConstraint(
+                "high_freq_interval_minutes >= 5 AND high_freq_interval_minutes <= 180",
+                name="ck_scheduler_settings_interval",
+            ),
+        )
+
+    _seed_default_row()
+
+
+def _seed_default_row() -> None:
+    """幂等灌入默认行(id=1): 8:00~24:00 每 30 分钟(**已存在则跳过**)。"""
+    bind = op.get_bind()
+    exists = bind.execute(
+        sa.text(f"SELECT 1 FROM {_TABLE} WHERE id = :i"), {"i": _SINGLETON_ID}
+    ).scalar()
+    if exists:
+        return
+    bind.execute(
+        sa.text(
+            f"INSERT INTO {_TABLE} "
+            "(id, high_freq_start_hour, high_freq_end_hour, high_freq_interval_minutes, updated_by) "
+            "VALUES (:i, 8, 24, 30, 'system')"
+        ),
+        {"i": _SINGLETON_ID},
+    )
+
+
+def downgrade() -> None:
+    if _table_exists(_TABLE):
+        op.drop_table(_TABLE)

backend/alembic/versions/b2d3e4f5a6b7_add_synced_at_updated_by_raw_tickets_refunds.py

@@ -14,9 +14,9 @@ Create Date: 2026-08-06 14:30:00.000000
 """
 from typing import Sequence, Union
 
-from alembic import op
 import sqlalchemy as sa
 
+from alembic import op
 
 # revision identifiers, used by Alembic.
 revision: str = 'b2d3e4f5a6b7'

backend/alembic/versions/b3_1_customer_domain.py

@@ -0,0 +1,174 @@
+"""B3-1 (#246): 客户域建表 - 四层主数据 + 设备→商户号 SCD 建链 + 设备类型维度
+
+Revision ID: b3_1_customer_domain
+Revises: b2_6_sync_watermark_split
+Create Date: 2026-10-09 16:00:00.000000
+
+依据: docs/arch/A-20261007-002-客户域主数据与设备360设计.md (LOCKED v1.0)
+     排期 docs/reports/20261009-下一步开发计划-排期规划.md §六 B3-1
+
+范围(只建结构, 不含回填/360 页面):
+1. dim_device_type 设备类型维度表 + devices.device_type_code 可空外键
+   (原始 device_type 文本保留, 只增不改不删)。
+2. merchants 演进: merchant_id 业务键部分唯一索引(空值允许); 代理键沿用 id。
+3. device_merchant_links: 设备→商户号 SCD Type2 建链(通路① 交易);
+   部分唯一 (device_sn) WHERE is_current。
+4. shops / enterprises 主数据(架构 §九-5 排期 v2 提前至 B3-1);
+   shop_enterprise_history 店铺↔企业父子 SCD;
+   device_shop_links 设备→店铺 SCD 建链(通路② 归属)。
+
+铁律:
+- 事实表不加外键、不回填历史; 原始文本列一律保留。
+- 所有新表/列向后兼容(可空、不破坏现有采集与看板)。
+
+downgrade: 全部为新表/可空新列, DROP 即安全回退, 无业务数据损失。
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'b3_1_customer_domain'
+down_revision: Union[str, None] = 'b2_6_sync_watermark_split'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ── 1. 设备类型维度 + devices.device_type_code ─────────────────────
+    op.create_table(
+        'dim_device_type',
+        sa.Column('type_code', sa.String(length=32), primary_key=True, comment='归一类型码(如 4G_CPE)'),
+        sa.Column('type_name', sa.String(length=64), nullable=False, comment='类型中文名'),
+        sa.Column('normalized_from', sa.JSON(), nullable=True, comment='归并来源原始文本列表(快照)'),
+        sa.Column('status', sa.String(length=16), nullable=False, server_default='active', comment='active/disabled'),
+    )
+    op.add_column(
+        'devices',
+        sa.Column('device_type_code', sa.String(length=32), nullable=True,
+                  comment='归一设备类型码(#246 B3-1, 原始 device_type 文本保留)'),
+    )
+    op.create_foreign_key(
+        'fk_devices_device_type_code', 'devices', 'dim_device_type',
+        ['device_type_code'], ['type_code'],
+    )
+    op.create_index('ix_devices_device_type_code', 'devices', ['device_type_code'])
+
+    # ── 2. merchants 演进: merchant_id 业务键部分唯一 ──────────────────
+    op.create_index(
+        'ix_merchants_merchant_id_unique', 'merchants', ['merchant_id'],
+        unique=True, postgresql_where=sa.text('merchant_id IS NOT NULL'),
+    )
+
+    # ── 3. 设备→商户号 SCD 建链 ───────────────────────────────────────
+    op.create_table(
+        'device_merchant_links',
+        sa.Column('id', sa.BigInteger(), primary_key=True, autoincrement=True),
+        sa.Column('device_sn', sa.String(length=64), sa.ForeignKey('devices.sn'), nullable=False, index=True),
+        sa.Column('merchant_pk', sa.BigInteger(), sa.ForeignKey('merchants.id'), nullable=False, index=True),
+        sa.Column('effective_from', sa.Date(), nullable=False),
+        sa.Column('effective_to', sa.Date(), nullable=True),
+        sa.Column('is_current', sa.Boolean(), nullable=False, server_default=sa.text('true')),
+        sa.Column('confidence', sa.Numeric(5, 4), nullable=True),
+        sa.Column('match_source', sa.String(length=16), nullable=False),
+        sa.Column('raw_merchant_name', sa.String(length=128), nullable=True),
+        sa.Column('change_reason', sa.Text(), nullable=True),
+        sa.Column('created_by', sa.String(length=64), nullable=True),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+    )
+    op.create_index(
+        'ix_dml_device_current', 'device_merchant_links', ['device_sn'],
+        unique=True, postgresql_where=sa.text('is_current'),
+    )
+    op.create_index('ix_device_merchant_links_is_current', 'device_merchant_links', ['is_current'])
+
+    # ── 4. 店铺 / 企业主数据 + 两条 SCD ────────────────────────────────
+    op.create_table(
+        'enterprises',
+        sa.Column('id', sa.BigInteger(), primary_key=True, autoincrement=True),
+        sa.Column('name', sa.String(length=128), nullable=False),
+        sa.Column('status', sa.String(length=16), nullable=False, server_default='active'),
+        sa.Column('raw_source', sa.String(length=32), nullable=True),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+    )
+    op.create_table(
+        'shops',
+        sa.Column('id', sa.BigInteger(), primary_key=True, autoincrement=True),
+        sa.Column('shop_name', sa.String(length=128), nullable=False),
+        sa.Column('enterprise_pk', sa.BigInteger(), sa.ForeignKey('enterprises.id'), nullable=True, index=True),
+        sa.Column('status', sa.String(length=16), nullable=False, server_default='active'),
+        sa.Column('raw_source', sa.String(length=32), nullable=True),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+    )
+    op.create_table(
+        'shop_enterprise_history',
+        sa.Column('id', sa.BigInteger(), primary_key=True, autoincrement=True),
+        sa.Column('shop_pk', sa.BigInteger(), sa.ForeignKey('shops.id', ondelete='CASCADE'), nullable=False, index=True),
+        sa.Column('enterprise_pk', sa.BigInteger(), sa.ForeignKey('enterprises.id'), nullable=False, index=True),
+        sa.Column('effective_from', sa.Date(), nullable=False),
+        sa.Column('effective_to', sa.Date(), nullable=True),
+        sa.Column('is_current', sa.Boolean(), nullable=False, server_default=sa.text('true')),
+        sa.Column('source', sa.String(length=32), nullable=True),
+        sa.Column('change_reason', sa.Text(), nullable=True),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+    )
+    op.create_index(
+        'ix_seh_shop_current', 'shop_enterprise_history', ['shop_pk'],
+        unique=True, postgresql_where=sa.text('is_current'),
+    )
+    op.create_table(
+        'device_shop_links',
+        sa.Column('id', sa.BigInteger(), primary_key=True, autoincrement=True),
+        sa.Column('device_sn', sa.String(length=64), sa.ForeignKey('devices.sn'), nullable=False, index=True),
+        sa.Column('shop_pk', sa.BigInteger(), sa.ForeignKey('shops.id'), nullable=False, index=True),
+        sa.Column('effective_from', sa.Date(), nullable=False),
+        sa.Column('effective_to', sa.Date(), nullable=True),
+        sa.Column('is_current', sa.Boolean(), nullable=False, server_default=sa.text('true')),
+        sa.Column('match_source', sa.String(length=16), nullable=False),
+        sa.Column('raw_source_text', sa.String(length=128), nullable=True),
+        sa.Column('change_reason', sa.Text(), nullable=True),
+        sa.Column('created_by', sa.String(length=64), nullable=True),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+    )
+    op.create_index(
+        'ix_dsl_device_current', 'device_shop_links', ['device_sn'],
+        unique=True, postgresql_where=sa.text('is_current'),
+    )
+    op.create_index('ix_device_shop_links_is_current', 'device_shop_links', ['is_current'])
+
+
+def downgrade() -> None:
+    # 全部为新表/可空新列, DROP 即安全回退
+    op.drop_index('ix_device_shop_links_is_current', table_name='device_shop_links')
+    op.drop_index('ix_device_shop_links_shop_pk', table_name='device_shop_links')
+    op.drop_index('ix_device_shop_links_device_sn', table_name='device_shop_links')
+    op.drop_index('ix_dsl_device_current', table_name='device_shop_links', postgresql_where=sa.text('is_current'))
+    op.drop_table('device_shop_links')
+
+    op.drop_index('ix_seh_shop_current', table_name='shop_enterprise_history', postgresql_where=sa.text('is_current'))
+    op.drop_table('shop_enterprise_history')
+
+    op.drop_table('shops')
+    op.drop_table('enterprises')
+
+    op.drop_index('ix_device_merchant_links_is_current', table_name='device_merchant_links')
+    op.drop_index('ix_device_merchant_links_merchant_pk', table_name='device_merchant_links')
+    op.drop_index('ix_device_merchant_links_device_sn', table_name='device_merchant_links')
+    op.drop_index('ix_dml_device_current', table_name='device_merchant_links', postgresql_where=sa.text('is_current'))
+    op.drop_table('device_merchant_links')
+
+    op.drop_index(
+        'ix_merchants_merchant_id_unique', table_name='merchants',
+        postgresql_where=sa.text('merchant_id IS NOT NULL'),
+    )
+
+    op.drop_index('ix_devices_device_type_code', table_name='devices')
+    op.drop_constraint('fk_devices_device_type_code', 'devices', type_='foreignkey')
+    op.drop_column('devices', 'device_type_code')
+    op.drop_table('dim_device_type')

backend/alembic/versions/b3_2_combo_dict.py

@@ -0,0 +1,71 @@
+"""B3-2 (#247): 套餐归一字典 - combo_dict + combo_name_alias
+
+Revision ID: b3_2_combo_dict
+Revises: b3_1_customer_domain
+Create Date: 2026-10-09 16:30:00.000000
+
+依据: docs/arch/A-20261007-002 §3.5 (LOCKED v1.0)
+     排期 §六 B3-2 (S-P1-12)
+
+范围:
+1. combo_dict 归一套餐字典(combo_code PK, canonical_name, package_type, traffic_type, status)
+2. combo_name_alias 原始名→归一码映射(SCD, 含 merchant_pk + 生效期)
+   - 部分唯一索引 (raw_package_name, merchant_pk) WHERE is_current
+   - NULLS NOT DISTINCT 使全局别名(merchant_pk NULL)同样受唯一约束
+
+downgrade: 新表 DROP 即安全回退, 无业务数据损失。
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'b3_2_combo_dict'
+down_revision: Union[str, None] = 'b3_1_customer_domain'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'combo_dict',
+        sa.Column('combo_code', sa.String(length=64), primary_key=True, comment='归一套餐码(稳定键)'),
+        sa.Column('canonical_name', sa.String(length=128), nullable=False, comment='归一标准名'),
+        sa.Column('package_type', sa.String(length=32), nullable=True, comment='套餐类型'),
+        sa.Column('traffic_type', sa.String(length=32), nullable=True, comment='流量类型'),
+        sa.Column('status', sa.String(length=16), nullable=False, server_default='active', comment='active/disabled'),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+    )
+    op.create_table(
+        'combo_name_alias',
+        sa.Column('id', sa.BigInteger(), primary_key=True, autoincrement=True),
+        sa.Column('combo_code', sa.String(length=64), sa.ForeignKey('combo_dict.combo_code'), nullable=False, index=True),
+        sa.Column('raw_package_name', sa.String(length=128), nullable=False),
+        sa.Column('merchant_pk', sa.BigInteger(), sa.ForeignKey('merchants.id'), nullable=True, index=True),
+        sa.Column('effective_from', sa.Date(), nullable=False),
+        sa.Column('effective_to', sa.Date(), nullable=True),
+        sa.Column('is_current', sa.Boolean(), nullable=False, server_default=sa.text('true')),
+        sa.Column('source', sa.String(length=32), nullable=True),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+    )
+    op.create_index(
+        'ix_cna_raw_merchant_current', 'combo_name_alias',
+        ['raw_package_name', 'merchant_pk'],
+        unique=True,
+        postgresql_where=sa.text('is_current'),
+        postgresql_nulls_not_distinct=True,
+    )
+    op.create_index('ix_combo_name_alias_is_current', 'combo_name_alias', ['is_current'])
+
+
+def downgrade() -> None:
+    op.drop_index('ix_combo_name_alias_is_current', table_name='combo_name_alias')
+    op.drop_index(
+        'ix_cna_raw_merchant_current', table_name='combo_name_alias',
+        postgresql_where=sa.text('is_current'),
+    )
+    op.drop_table('combo_name_alias')
+    op.drop_table('combo_dict')

backend/alembic/versions/b3_3_tag_rel_source.py

@@ -0,0 +1,38 @@
+"""B3-3 (#249): device_tag_rel 补业务事实来源列(source_table/source_id/reason)
+
+Revision ID: b3_3_tag_rel_source
+Revises: b3_9_upload_source_widen
+Create Date: 2026-10-09 17:30:00.000000
+
+依据: docs/arch/A-20261007-002 §3.6 (S-P1-13)
+     排期 §六 B3-3
+
+范围:
+1. device_tag_rel 补 3 列可空来源列(老批次数据为 NULL, 与 batch_id 两来源并存)
+2. 部分唯一约束: 同 device_sn+tag_id 当前有效仅一条(复合主键已约束,
+   此处不加新约束, 只补注释说明)
+
+downgrade: 纯新增列, DROP 即安全回退。
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'b3_3_tag_rel_source'
+down_revision: Union[str, None] = 'b3_9_upload_source_widen'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column('device_tag_rel', sa.Column('source_table', sa.String(length=32), nullable=True, comment='来源表名(可空)'))
+    op.add_column('device_tag_rel', sa.Column('source_id', sa.String(length=64), nullable=True, comment='来源行主键值(可空)'))
+    op.add_column('device_tag_rel', sa.Column('reason', sa.Text(), nullable=True, comment='打标原因(可空)'))
+
+
+def downgrade() -> None:
+    op.drop_column('device_tag_rel', 'reason')
+    op.drop_column('device_tag_rel', 'source_id')
+    op.drop_column('device_tag_rel', 'source_table')

backend/alembic/versions/b3_7_person_skill_tags.py

@@ -0,0 +1,48 @@
+"""B3-7 (#255): 人员技能矩阵表 person_skill_tags
+
+Revision ID: b3_7_person_skill_tags
+Revises: b3_3_tag_rel_source
+Create Date: 2026-10-09 18:30:00.000000
+
+依据: 排期 §六 B3-7 人员管理重设计(技能矩阵)
+
+范围:
+1. 新建 person_skill_tags: 人员 × 技能标签 × 熟练度(1-5)
+2. 唯一约束 (person_id, skill_tag): 同一人员同一技能仅一行, 重复打标幂等覆盖
+
+downgrade: 纯新表, DROP 即安全回退。
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'b3_7_person_skill_tags'
+down_revision: Union[str, None] = 'b3_3_tag_rel_source'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'person_skill_tags',
+        sa.Column('id', sa.BigInteger(), autoincrement=True, nullable=False),
+        sa.Column('person_id', sa.BigInteger(), nullable=False, comment='人员ID'),
+        sa.Column('skill_tag', sa.String(length=64), nullable=False, comment='技能标签(如:投诉处理/套餐咨询/外呼)'),
+        sa.Column('level', sa.Integer(), nullable=False, server_default='1', comment='熟练度 1-5'),
+        sa.Column('updated_by', sa.String(length=64), nullable=True, comment='最近操作人'),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+        sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+        sa.ForeignKeyConstraint(['person_id'], ['persons.id'], ondelete='CASCADE'),
+        sa.PrimaryKeyConstraint('id'),
+        sa.UniqueConstraint('person_id', 'skill_tag', name='uq_person_skill_tag'),
+    )
+    op.create_index('ix_person_skill_tags_person_id', 'person_skill_tags', ['person_id'])
+    op.create_index('ix_person_skill_tags_skill_tag', 'person_skill_tags', ['skill_tag'])
+
+
+def downgrade() -> None:
+    op.drop_index('ix_person_skill_tags_skill_tag', table_name='person_skill_tags')
+    op.drop_index('ix_person_skill_tags_person_id', table_name='person_skill_tags')
+    op.drop_table('person_skill_tags')

backend/alembic/versions/b3_9_upload_source_widen.py

@@ -0,0 +1,41 @@
+"""B3-9 (#248): upload_records.source 扩宽至 32 字符, 支持 shared_doc 批次台账
+
+Revision ID: b3_9_upload_source_widen
+Revises: b3_2_combo_dict
+Create Date: 2026-10-09 17:00:00.000000
+
+背景:
+- S-P1-14: shared_doc_sync_service(#33) 走 ingest_service 入库但不落 upload_records,
+  共享表格通道无批次台账/质量留痕, 可观测性与手工通道不对等。
+- 本迁移仅扩宽 source 列(16→32), 枚举值扩展 manual/bms/shared_doc。
+
+downgrade: 纯列宽回退(32→16), 无数据损失(shared_doc 值仅 10 字符)。
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'b3_9_upload_source_widen'
+down_revision: Union[str, None] = 'b3_2_combo_dict'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.alter_column(
+        'upload_records', 'source',
+        existing_type=sa.String(length=16),
+        type_=sa.String(length=32),
+        existing_nullable=True,
+    )
+
+
+def downgrade() -> None:
+    op.alter_column(
+        'upload_records', 'source',
+        existing_type=sa.String(length=32),
+        type_=sa.String(length=16),
+        existing_nullable=True,
+    )

backend/alembic/versions/b3c4d5e6f7a8_ai_feed_refactor_seeds_and_specialty_efficiency_field.py

@@ -0,0 +1,221 @@
+"""ai_feed refactor: specialty efficiency_field + ai_focus_configs new seeds
+
+AI 助手数据底座重构 (工单 #98 后续 / 2026-09-15):
+1. specialties 表加 efficiency_field 字段(替代 external._BUCKET 硬编码)
+2. 把已合并到"投诉专项"的历史专项"内部投诉"/"外部投诉" is_active 置 False
+   (代码层 _reception_specialty 只过滤 is_active=True 即可, 不再靠 LEGACY 常量名硬编码过滤)
+3. ai_focus_configs 表插入 4 条新 seed(business-benchmark / work-time-ai-assist /
+   inference-discipline / ai-incremental-analysis) — 业务判定基准/工作时间/AI 协助/
+   防主观推断指导/AI 增量分析任务全部 DB 化, 运营可通过 /ai/focus-configs REST 路由增改
+4. UPDATE 现有 focus-complaint / focus-reception seed 修正过时口径(原 focus-complaint
+   含"处理滞后于登记说明积压恶化"是错误推断; 原 focus-reception 列出六个专项但
+   内部/外部已合并到投诉专项)
+
+Revision ID: b3c4d5e6f7a8
+Revises: e5f6a7b8c9d0
+Create Date: 2026-09-15 11:00:00.000000
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'b3c4d5e6f7a8'
+down_revision: Union[str, None] = 'e5f6a7b8c9d0'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+# ── ai_focus_configs 新增 4 条 seed (业务判定基准/工作时间/防主观推断/AI 增量分析) ──
+_NEW_FOCUS_SEEDS = [
+    {
+        "code": "business-benchmark",
+        "scope_key": "global",
+        "title": "业务判定基准",
+        "sort_order": 2,
+        "content": (
+            "业务判定基准(方向性判据, 用于判定'好/坏'与'风险/机会'): "
+            "退款越少越好(金额/笔数); 均单价越低越好; 退款单数越少越好; "
+            "接待量越多越好; 接待会话数越多越好; "
+            "投诉越少越好; 投诉严重性 外部投诉 > 商户号投诉 > 内部投诉(即外部投诉 1 件 > 商户号 10 件); "
+            "投诉处理越及时越好(handle - register 间隔越短越好); "
+            "退款挽回率越高越好(挽回成功/分母); "
+            "积压投诉越低越好(窗口内登记未闭环). "
+            "陈述'环比涨跌'后必须按此基准标注'利好/利空', 不得只报数字不评判."
+        ),
+    },
+    {
+        "code": "work-time-ai-assist",
+        "scope_key": "global",
+        "title": "工作时间与 AI 协助",
+        "sort_order": 3,
+        "content": (
+            "客服工作时间 08:00~23:59; 非工作时间(00:00~07:59)由 AI 协助处理. "
+            "解读'接待量为 0 / 完工单为 0'时, 必须先核对窗口是否落在非工作时间, "
+            "不得直接判定'无人值班'或'系统故障'. "
+            "AI 接管率(ai_takeover)是可控指标前置: 接待量可升可控, AI 接管率上升=利好."
+        ),
+    },
+    {
+        "code": "inference-discipline",
+        "scope_key": "global",
+        "title": "防主观推断指导",
+        "sort_order": 4,
+        "content": (
+            "防主观推断指导: "
+            "① 不同口径的数字(如 registered=窗口内新登记 vs handled=窗口内完成含历史单)禁止直接相减或比较大小; "
+            "必须显式标注口径差异后再下结论. "
+            "② 禁止做'处理量 > 登记量 → 消化存量'这类无证据因果推断; "
+            "如需描述关系, 只能说'本期 handled 高于 registered, 差额源于窗口外登记、窗口内办结的历史单'等可验证陈述. "
+            "③ 数据未提供的归因(如'退款上升因 XX 活动')禁止编造, 一律写'原因需结合运营侧确认'. "
+            "④ yoy_value/yoy_pct 是上一等长周期汇总, 不是另一天的独立明细, 不得当独立日数据展开陈述."
+        ),
+    },
+    {
+        "code": "ai-incremental-analysis",
+        "scope_key": "global",
+        "title": "AI 增量分析任务",
+        "sort_order": 5,
+        "content": (
+            "当用户问'分析/总览/怎么看/风险/异常'类开放题时(纯取数问句跳过本段), 增量分析任务: "
+            "- 口径差异提醒: 当数据里出现 registered 与 handled 这类不同口径数字(见口径卡), 必须显式标注口径, 禁止直接相减或推断因果; "
+            "- 环比异常预警: yoy_pct 超 ±30% 的指标, 必须点名并给出可能原因方向(数据/运营/外部, 不下结论); "
+            "- 风险与机会: 按 business_benchmark 卡的方向判定(如'退款金额上升=风险'), 每类最多 1 条; "
+            "- 下钻建议: 给出'看哪个看板卡片/下钻到哪一层'的可执行建议(不重复数据)."
+        ),
+    },
+]
+
+# ── 修正现有 seed (focus-complaint / focus-reception 过时口径) ──
+_FOCUS_UPDATES = {
+    "focus-complaint": {
+        # 原: ②登记(窗口新增)与处理(真实办结)要分开看, 处理滞后于登记说明积压恶化
+        # 改: ②登记(窗口新增)与处理(真实办结)是不同口径, 禁止直接相减或推断因果;
+        #     处理>登记属正常(含历史单办结), 不必然意味'消化存量'
+        "content": (
+            "投诉分析关注点: ①三源(内部/商户号/外部)结构, 外部平台投诉最需重视; "
+            "②登记(窗口新增)与处理(真实办结)是不同口径, 禁止直接相减或推断因果; "
+            "处理>登记属正常(含历史单办结), 不必然意味'消化存量'; "
+            "③积压(未闭环存量)是核心风险, 抬升须提示; ④措辞区分'登记量/处理量/积压', 不要混用."
+        ),
+    },
+    "focus-reception": {
+        # 原: ②六个专项(咨询/套餐/退款处理/退款挽回/内部投诉/外部投诉)的会话与设备规模
+        # 改: ②五个正式专项(咨询接待/套餐专项/退款处理/退款挽回/投诉专项), 历史已合并
+        "content": (
+            "接待分析关注点: ①总体接待量与服务设备数(SN去重)看覆盖面; "
+            "②五个正式专项(咨询接待/套餐专项/退款处理/退款挽回/投诉专项)的会话与设备规模, "
+            "历史专项(内部投诉/外部投诉)已合并到投诉专项, "
+            "指出量大的专项与负责人(lead); ③环比(同比前移等长窗口)变化要解释可能原因; "
+            "④接待量含智能助手处理(cs_record), 口径与'人工工单'不同勿混。"
+        ),
+    },
+}
+
+# 6 个正式专项的 efficiency_field 填值(对应 today_staff_efficiency 的 sp_*/pp_* 字段)
+# 注: "内部投诉"/"外部投诉" 不填 efficiency_field(is_active=False 不参与)
+_SPECIALTY_EFFICIENCY_FIELDS = {
+    "咨询接待": "sp_zixun,pp_zixun",
+    "套餐专项": "sp_taocan,pp_taocan",
+    "退款挽回": "sp_recovery,pp_recovery",
+    "退款处理": "sp_processing,pp_processing",
+    "投诉专项": "sp_internal,pp_internal",  # 投诉类合并到此桶
+}
+
+
+def upgrade() -> None:
+    # ── 1. specialties 表加 efficiency_field 字段 ──
+    op.add_column(
+        'specialties',
+        sa.Column(
+            'efficiency_field',
+            sa.String(length=64),
+            nullable=True,
+            comment="对应 today_staff_efficiency 的字段名, 格式 'sp_xxx,pp_xxx'; NULL=不参与会话/设备统计",
+        ),
+    )
+
+    # ── 2. 给 5 个正式专项填 efficiency_field 值 ──
+    conn = op.get_bind()
+    for name, field in _SPECIALTY_EFFICIENCY_FIELDS.items():
+        conn.execute(
+            sa.text("UPDATE specialties SET efficiency_field = :field WHERE name = :name AND is_active = true"),
+            {"field": field, "name": name},
+        )
+
+    # ── 3. 把"内部投诉"/"外部投诉"两条历史专项的 is_active 置 False ──
+    # (已合并到"投诉专项", DB 治理后代码层 _reception_specialty 只过滤 is_active=True 即可)
+    # 注: LEGACY_COMPLAINT_SPECIALTIES 常量保留(analytics.py 用于 SCD 历史归因, 不影响)
+    conn.execute(
+        sa.text("UPDATE specialties SET is_active = false WHERE name IN ('内部投诉', '外部投诉')")
+    )
+
+    # ── 4. ai_focus_configs 插入 4 条新 seed (幂等: code 唯一, 已存在则跳过) ──
+    for seed in _NEW_FOCUS_SEEDS:
+        existing = conn.execute(
+            sa.text("SELECT id FROM ai_focus_configs WHERE code = :code"),
+            {"code": seed["code"]},
+        ).scalar()
+        if existing:
+            # 已存在(可能是历史迁移重复执行), 跳过插入
+            continue
+        conn.execute(
+            sa.text(
+                "INSERT INTO ai_focus_configs (code, scope_key, title, content, sort_order, enabled, created_by) "
+                "VALUES (:code, :scope_key, :title, :content, :sort_order, true, 'seed-b3c4d5e6f7a8')"
+            ),
+            seed,
+        )
+
+    # ── 5. UPDATE 现有 focus-complaint / focus-reception seed 修正过时口径 ──
+    for code, update_fields in _FOCUS_UPDATES.items():
+        conn.execute(
+            sa.text("UPDATE ai_focus_configs SET content = :content, updated_by = 'seed-b3c4d5e6f7a8' WHERE code = :code"),
+            {"code": code, "content": update_fields["content"]},
+        )
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+
+    # 1. 还原 focus-complaint / focus-reception seed 内容(回退到 a1f0c2e4d6b8 的原 seed)
+    conn.execute(
+        sa.text(
+            "UPDATE ai_focus_configs SET content = :content, updated_by = NULL WHERE code = 'focus-complaint'"
+        ),
+        {"content": (
+            "投诉分析关注点: ①三源(内部/商户号/外部)结构, 外部平台投诉最需重视; "
+            "②登记(窗口新增)与处理(真实办结)要分开看, 处理滞后于登记说明积压恶化; "
+            "③积压(未闭环存量)是核心风险, 抬升须提示; ④措辞区分'登记量/处理量/积压', 不要混用。"
+        )},
+    )
+    conn.execute(
+        sa.text(
+            "UPDATE ai_focus_configs SET content = :content, updated_by = NULL WHERE code = 'focus-reception'"
+        ),
+        {"content": (
+            "接待分析关注点: ①总体接待量与服务设备数(SN去重)看覆盖面; "
+            "②六个专项(咨询/套餐/退款处理/退款挽回/内部投诉/外部投诉)的会话与设备规模, "
+            "指出量大的专项与负责人(lead); ③环比(同比前移等长窗口)变化要解释可能原因; "
+            "④接待量含智能助手处理(cs_record), 口径与'人工工单'不同勿混。"
+        )},
+    )
+
+    # 2. 删除 4 条新 seed
+    for seed in _NEW_FOCUS_SEEDS:
+        conn.execute(
+            sa.text("DELETE FROM ai_focus_configs WHERE code = :code AND created_by = 'seed-b3c4d5e6f7a8'"),
+            {"code": seed["code"]},
+        )
+
+    # 3. 还原"内部投诉"/"外部投诉" is_active = True
+    conn.execute(
+        sa.text("UPDATE specialties SET is_active = true WHERE name IN ('内部投诉', '外部投诉')")
+    )
+
+    # 4. 清空 efficiency_field 值
+    conn.execute(sa.text("UPDATE specialties SET efficiency_field = NULL"))
+
+    # 5. 删除 efficiency_field 字段
+    op.drop_column('specialties', 'efficiency_field')

backend/alembic/versions/b3d4e5f6a7c8_expand_template_keywords.py

@@ -0,0 +1,60 @@
+"""expand default template question_keywords (工单 #147 A 提示词工程)
+
+Revision ID: b3d4e5f6a7c8
+Revises: c8d9e0f1a2b3
+Create Date: 2026-09-17 22:15:00.000000
+
+设计(#147 A): 只做提示词工程(不拆新模板)提升日常问法命中率。
+扩充 3 内置模板 question_keywords, 覆盖经营侧高频词(客流/营收/退款率/投诉量/
+月度复盘/KPI/目标达成/环比同比走势等), 让日常问法更易命中对应模板, 减少走实时 LLM。
+用 UPDATE ... 覆盖(不 INSERT), 因模板已存在; 幂等: 覆盖为固定「权威」关键词集,
+is_active=false 的模板不在此(仅 update 既有 3 code)。
+"""
+from typing import Sequence, Union
+
+from alembic import op
+
+revision: str = 'b3d4e5f6a7c8'
+down_revision: Union[str, None] = 'c8d9e0f1a2b3'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # 日报: 覆盖「现在/今天」时段 + 整体经营(接待/退款/投诉)高频词
+    op.execute("""
+        UPDATE ai_report_templates
+        SET question_keywords = '["今天","今日","现在","当前","今天怎么样","整体经营","经营总览","总览","晨会","日报","接待量","退款","投诉"]'::jsonb
+        WHERE code = 'daily_general_morning'
+    """)
+    # 周报: 本周 + 环比 + 趋势/进度类
+    op.execute("""
+        UPDATE ai_report_templates
+        SET question_keywords = '["本周","这周","这周吧","周报","上周","环比","对比","周趋势","周度","这周情况","本周经营","目标达成","KPI"]'::jsonb
+        WHERE code = 'weekly_compare_last'
+    """)
+    # 月报: 本月 + 同比 + 月度复盘/走势类
+    op.execute("""
+        UPDATE ai_report_templates
+        SET question_keywords = '["本月","这个月","这月","月报","上月","同比","月度","月度复盘","月度总结","月度走势","下月建议","月经营","KPI达成"]'::jsonb
+        WHERE code = 'monthly_overview'
+    """)
+
+
+def downgrade() -> None:
+    # 回滚到 #124 原始关键词集
+    op.execute("""
+        UPDATE ai_report_templates
+        SET question_keywords = '["今天","今日","整体","总览","晨会","日报"]'::jsonb
+        WHERE code = 'daily_general_morning'
+    """)
+    op.execute("""
+        UPDATE ai_report_templates
+        SET question_keywords = '["本周","这周","周报","对比","上周","环比"]'::jsonb
+        WHERE code = 'weekly_compare_last'
+    """)
+    op.execute("""
+        UPDATE ai_report_templates
+        SET question_keywords = '["本月","这个月","月报","上月","同比"]'::jsonb
+        WHERE code = 'monthly_overview'
+    """)

backend/alembic/versions/b443c1a2d3e4_add_std_all_views.py

@@ -0,0 +1,46 @@
+"""add std_*_all full-mirror views over ods refund tables
+
+Revision ID: b443c1a2d3e4
+Revises: a332b05d6e7f
+Create Date: 2026-10-19
+
+#334: 退款域业务代码零读 ods —— 全状态语义场景统一迁 std 层全量镜像视图。
+
+五个视图（public schema, SELECT * 透传 ods, 含 T1 已加的采纳四列）：
+  std_refund_online_all   → ods.refunds              (A 路全量)
+  std_wallet_flow_all     → ods.wallet_withdrawals   (B 路全量)
+  std_refund_shanmao_all  → ods.shanmao_refunds      (C 路全量)
+  std_refund_manual_all   → ods.manual_refunds       (D 路全量)
+  std_refund_record_all   → ods.refund_record_reports (E 路全量)
+
+定位：
+  - 经营统计口径仍读 std_* 采纳集物理表（不动）；
+  - 全状态语义（挽回漏斗/状态分布/工作量/导出明细/链路台账/设备档案/对账勾稽）
+    一律读本视图，业务代码不再直读 ods；
+  - ods 回归三本职：采集写入、采纳作业读取、质量治理标记。
+
+视图零存储、随 ods 实时一致，采纳作业无需改动。
+"""
+from typing import Sequence, Union
+
+from alembic import op
+from app.models.refund_standard import STD_ALL_VIEWS
+
+revision: str = "b443c1a2d3e4"
+down_revision: Union[str, None] = "a332b05d6e7f"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+# 视图名 → ods 源表: 单一来源 STD_ALL_VIEWS(代码常量白名单, 与 conftest 逐字一致)
+_VIEWS = STD_ALL_VIEWS
+
+
+def upgrade() -> None:
+    for view, src in _VIEWS.items():
+        # CREATE OR REPLACE: 幂等, 重跑安全; 显式 ods 限定不受 search_path 影响
+        op.execute(f"CREATE OR REPLACE VIEW {view} AS SELECT * FROM {src}")
+
+
+def downgrade() -> None:
+    for view in _VIEWS:
+        op.execute(f"DROP VIEW IF EXISTS {view}")

backend/alembic/versions/b4_1_metric_dictionary.py

@@ -0,0 +1,246 @@
+"""B4-1 (#257): 指标字典表 - metric_dictionary 口径单点登记 + 种子 19 条
+
+Revision ID: b4_1_metric_dictionary
+Revises: b3_7_person_skill_tags
+Create Date: 2026-10-09 00:00:00.000000
+
+依据: 排期 §七 B4-1 (S-P1-1); AGENTS 界面纪律"卡片必须有数据说明"。
+
+范围:
+1. metric_dictionary 表: code PK / name_cn 全站唯一 / definition 必填 /
+   formula(JSONB: source/aggregation/filter/window) / unit / category /
+   source_tables(JSONB) / owner / is_active / remark
+2. 种子 19 条高频核心指标, 口径**逐条对照代码现状**核对
+   (today/_kpi.py #81 v4 四路退款 / #78 接待分层 / complaint.py #81 三源合计),
+   code 命名 = 域.名, 与看板接口实现同源(见各行 definition 中的实现指针)。
+
+downgrade: 新表 DROP 即安全回退, 无业务数据损失。
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import JSONB
+
+from alembic import op
+
+revision: str = 'b4_1_metric_dictionary'
+down_revision: Union[str, None] = 'b3_7_person_skill_tags'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+# 种子指标(口径以代码现状为准; definition 里写实现指针, 谁改口径谁更新字典)
+_SEEDS = [
+    # ── 接待域 (today/_kpi.py today_kpi + reception.py) ──
+    {
+        "code": "reception.session_count", "name_cn": "会话数(次)",
+        "definition": "窗口内 cs_records 记录条数(operation_time ∈ 窗口), 含真人/AI全自动/系统/客户自助四类(各 kind 之和 == 本值, #78 分层不变式)。前端显示名 '会话数(次)'。",
+        "formula": {"source": "cs_records", "aggregation": "count(*)", "filter": "operation_time ∈ [start, end]", "window": "看板当前窗口(日/周/月)"},
+        "unit": "次", "category": "reception",
+        "source_tables": ["cs_records"],
+        "owner": "运营组", "remark": "#78 接待来源分层; 实现: today/_kpi.py today_kpi #1",
+    },
+    {
+        "code": "reception.device_count", "name_cn": "接待设备数(个)",
+        "definition": "窗口内 cs_records.device_sn 去重数(NULL/空串排除)。1台设备多次进线算1次, 体现覆盖面。AI/真人跨类重叠时按全量去重(不按 kind 拆分)。",
+        "formula": {"source": "cs_records", "aggregation": "count(distinct nullif(trim(device_sn),''))", "filter": "operation_time ∈ [start, end]", "window": "同会话数"},
+        "unit": "个", "category": "reception",
+        "source_tables": ["cs_records"],
+        "owner": "运营组", "remark": "实现: today/_kpi.py today_kpi #1b",
+    },
+    {
+        "code": "reception.staff_on_duty", "name_cn": "在岗人数(人)",
+        "definition": "窗口内 cs_records.operator 去重数(NULL 排除)。⚠️ 未排除系统/AI 账户(历史口径, 与人效表真人口径不同, 勿混用)。",
+        "formula": {"source": "cs_records", "aggregation": "count(distinct operator)", "filter": "operation_time ∈ [start, end] AND operator IS NOT NULL", "window": "同会话数"},
+        "unit": "人", "category": "reception",
+        "source_tables": ["cs_records"],
+        "owner": "运营组", "remark": "实现: today/_kpi.py today_kpi #6",
+    },
+    {
+        "code": "reception.ticket_done", "name_cn": "完工工单(单)",
+        "definition": "status='已完成' 的工单, 按**有效完工时间推算**计数: 真实完成样本(白名单) → handle_duration 秒 → handler 近30天真实平均 → 全局真实平均。finish_time 89% 被批量覆盖, 不能直接用。",
+        "formula": {"source": "service_tickets", "aggregation": "count(*)", "filter": "status='已完成' AND 有效完工时间 ∈ [start, end]", "window": "同会话数"},
+        "unit": "单", "category": "reception",
+        "source_tables": ["service_tickets"],
+        "owner": "运营组", "remark": "实现: complaint.py _ticket_effective_finish_time_where; 背景 docs/reports/20260801-数据时间审核-审计报告.md",
+    },
+    {
+        "code": "reception.ai_takeover_session_pct", "name_cn": "AI接管率(会话)",
+        "definition": "AI 全自动会话占比 = operator='wechat' 的会话数 / 会话总数 ×100%(#78 接待来源分层, 判据=operator+description 文本模式, 见 system_accounts.classify_cs_record)。",
+        "formula": {"source": "cs_records", "aggregation": "sum(kind=AI_AUTO)/count(*)", "filter": "operation_time ∈ [start, end]", "window": "同会话数"},
+        "unit": "%", "category": "reception",
+        "source_tables": ["cs_records"],
+        "owner": "运营组", "remark": "#78; 架构 docs/arch/A-20260913-001-AI接待口径分层.md",
+    },
+    {
+        "code": "reception.ai_takeover_device_pct", "name_cn": "AI接管率(设备)",
+        "definition": "AI 独有 SN 占比 = (AI 覆盖 SN − 人机共管 SN) / 接待设备数 ×100%。分母为 device_count, 共管设备归真人侧不计入 AI 接管。",
+        "formula": {"source": "cs_records", "aggregation": "(ai_sn - overlap_sn)/device_count", "filter": "operation_time ∈ [start, end]", "window": "同会话数"},
+        "unit": "%", "category": "reception",
+        "source_tables": ["cs_records"],
+        "owner": "运营组", "remark": "#78; device_shared/device_ai_total 随 KPI 透出",
+    },
+    # ── 绩效域 (today/_staff.py today_staff_efficiency) ──
+    {
+        "code": "performance.efficiency_score", "name_cn": "工作效率值",
+        "definition": "双合成指标: 工作量分 = Σ(专项会话数 × 专项难度系数 × 本职系数); 效率分 = cs_record 接待SN ∪ ServiceTicket 处理SN 跨表去重数。本职系数 1.0 / 转接固定 0.2(不叠加难度); 管理岗/专员岗跨类全豁免(三级豁免判定)。前端显示 'n次(m个)'。系统/自助/AI 虚拟账户不进真人排名。",
+        "formula": {"source": "cs_records + service_tickets", "aggregation": "工作量分=Σ(会话×难度×本职系数); 效率分=SN跨表union去重", "filter": "排除系统自动记录(system_accounts 黑名单)", "window": "同会话数"},
+        "unit": "值", "category": "performance",
+        "source_tables": ["cs_records", "service_tickets"],
+        "owner": "运营组", "remark": "v3 转接系数(2026-08-09); 权重表 TRANSFER_PENALTY=0.2; 实现: today/_staff.py today_staff_efficiency",
+    },
+    # ── 退款域 (today/_kpi.py v4 四路核算; 实现 analytics/cash.py _cash_routes_total) ──
+    {
+        "code": "refund.count", "name_cn": "退款笔数",
+        "definition": "四路经营合计 A+B+C+D(经营侧登记的所有退款出款), 各路按各自时间列 ∈ 窗口。⚠️ 与 metric_registry 的 refund_count 同名同源(#83 已修)。",
+        "formula": {"source": "A+B+C+D 四路", "aggregation": "Σcount", "filter": "各路时间列 ∈ [start, end]", "window": "同会话数"},
+        "unit": "笔", "category": "refund",
+        "source_tables": ["refunds", "wallet_withdrawals", "shanmao_refunds", "manual_refunds"],
+        "owner": "运营组", "remark": "v4 统一口径(2026-08-10); 实现: today/_kpi.py today_kpi #2/3/4",
+    },
+    {
+        "code": "refund.amount", "name_cn": "退款金额",
+        "definition": "四路经营合计金额 A+B+C+D(元), = 退款笔数同窗口的金额维度。",
+        "formula": {"source": "A+B+C+D 四路", "aggregation": "Σamount", "filter": "各路时间列 ∈ [start, end]", "window": "同会话数"},
+        "unit": "元", "category": "refund",
+        "source_tables": ["refunds", "wallet_withdrawals", "shanmao_refunds", "manual_refunds"],
+        "owner": "运营组", "remark": "金额定点数(AGENTS 铁律4); 出参 float 表示层转换",
+    },
+    {
+        "code": "refund.route_a", "name_cn": "A路·线上直退",
+        "definition": "refunds(BMS退费单)按 created_at_raw ∈ 窗口计入经营退款。补充口径 refund_done_today: status='已退款' 且 updated_at_raw(实际退款时刻) ∈ 当日, 含几天前创建今天完成的单(BMS 实际退款时间口径)。",
+        "formula": {"source": "refunds", "aggregation": "count+sum(refund_amount)", "filter": "created_at_raw ∈ 窗口(_route_a_online_refund_filter)", "window": "同会话数"},
+        "unit": "元", "category": "refund",
+        "source_tables": ["refunds"],
+        "owner": "运营组", "remark": "E路对账基准勿与A路混用(易误用口径已在数据源树标注)",
+    },
+    {
+        "code": "refund.route_b", "name_cn": "B路·用户取现",
+        "definition": "wallet_withdrawals 用户取现成功计入经营退款。",
+        "formula": {"source": "wallet_withdrawals", "aggregation": "count+sum(amount)", "filter": "_route_b_withdraw_filter", "window": "同会话数"},
+        "unit": "元", "category": "refund",
+        "source_tables": ["wallet_withdrawals"],
+        "owner": "运营组", "remark": "实现: analytics/cash.py",
+    },
+    {
+        "code": "refund.route_c", "name_cn": "C路·闪猫退款",
+        "definition": "shanmao_refunds 独立表, status='已退款' 计入经营退款。",
+        "formula": {"source": "shanmao_refunds", "aggregation": "count+sum(paid_amount)", "filter": "status='已退款' AND 时间列 ∈ 窗口", "window": "同会话数"},
+        "unit": "元", "category": "refund",
+        "source_tables": ["shanmao_refunds"],
+        "owner": "运营组", "remark": "实现: analytics/cash.py _route_c_shanmao_trend",
+    },
+    {
+        "code": "refund.route_d", "name_cn": "D路·手动退款",
+        "definition": "manual_refunds 独立业务表, is_refunded='是' 计入经营退款(去重键见数据采集合并去重机制说明)。",
+        "formula": {"source": "manual_refunds", "aggregation": "count+sum(refund_amount)", "filter": "is_refunded='是' AND 时间列 ∈ 窗口", "window": "同会话数"},
+        "unit": "元", "category": "refund",
+        "source_tables": ["manual_refunds"],
+        "owner": "运营组", "remark": "实现: analytics/cash.py _route_d_other_trend",
+    },
+    # ── 现金流域 ──
+    {
+        "code": "cash.actual_cashflow", "name_cn": "实际现金流",
+        "definition": "refund_record_reports 退款成功合计(不分 ORIGINAL/BALANCE 桶), 是**对账基准**(2026-09-05 v1.1 起替代 merchant_refunds)。商户号流水 T+1 导入, 本日可能为空。",
+        "formula": {"source": "refund_record_reports", "aggregation": "sum(退款成功金额)", "filter": "_route_e_cashflow_filter", "window": "同会话数"},
+        "unit": "元", "category": "cash",
+        "source_tables": ["refund_record_reports"],
+        "owner": "运营组", "remark": "对账基准, 勿与经营估算混淆(数据源树已标注)",
+    },
+    {
+        "code": "cash.recon_diff", "name_cn": "对账偏差",
+        "definition": "对账偏差 = 经营估算(A+B+C+D) − 实际现金流(E)。为 0 表示两套账齐平; 持续为正说明经营侧多记或 E 少导。",
+        "formula": {"source": "四路合计 vs refund_record_reports", "aggregation": "operational.amount - actual_cashflow.amount", "filter": "同窗口", "window": "同会话数"},
+        "unit": "元", "category": "cash",
+        "source_tables": ["refunds", "wallet_withdrawals", "shanmao_refunds", "manual_refunds", "refund_record_reports"],
+        "owner": "运营组", "remark": "实现: cash.py _cash_routes_total 的 diff",
+    },
+    # ── 投诉域 (#81 口径统一到唯一出口) ──
+    {
+        "code": "complaint.total", "name_cn": "投诉数",
+        "definition": "三源合计 = 内部投诉(工单投诉类) + 商户号投诉 + 外部投诉(含补充文件), **不含卡商**(#53 卡商全部单算)。判据与投诉专项四卡同源(complaint_scope 分桶), 已扣除补充表中已关联工单的重叠记录。",
+        "formula": {"source": "service_tickets + external_complaints(+补充)", "aggregation": "count(registered)", "filter": "_sources_reg_handled 判据", "window": "同会话数"},
+        "unit": "单", "category": "complaint",
+        "source_tables": ["service_tickets", "external_complaints"],
+        "owner": "运营组", "remark": "#81 口径统一(2026-09-13); 实现: complaints.py _sources_reg_handled",
+    },
+    {
+        "code": "complaint.repeat_rate", "name_cn": "重复投诉率",
+        "definition": "代理指标: 窗口内同 SN 出现 ≥2 次投诉的 SN 占比(重复投诉分布 reps>1)。⚠️ 禁止改叫「升级率」—— 这是升级的**代理信号**, 非真实升级率(真实值待升级投诉表到位)。",
+        "formula": {"source": "三源投诉(同 complaint.total)", "aggregation": "reps≥1 的 SN / 去重 SN", "filter": "同 complaint.total", "window": "同会话数"},
+        "unit": "%", "category": "complaint",
+        "source_tables": ["service_tickets", "external_complaints", "card_complaints"],
+        "owner": "运营组", "remark": "complaint.py complaint_health_metrics; 口径权威定义见投诉渠道口径与对账说明",
+    },
+    {
+        "code": "complaint.card_total", "name_cn": "(外)卡商投诉数",
+        "definition": "卡商投诉 = 工单侧真卡商 + card_complaints − 重叠(与 /summary 同公式)。⚠️ 独立统计, **不计入** complaint.total(#53 用户口径)。",
+        "formula": {"source": "service_tickets(卡商) + card_complaints", "aggregation": "count − 重叠", "filter": "#65 软纠正判据", "window": "同会话数"},
+        "unit": "单", "category": "complaint",
+        "source_tables": ["service_tickets", "card_complaints"],
+        "owner": "运营组", "remark": "#53/#65; 渠道口径权威定义见 docs/standards/投诉渠道口径与对账说明.md",
+    },
+    # ── 退款挽回 ──
+    {
+        "code": "recovery.rate", "name_cn": "退款挽回成功率",
+        "definition": "退款挽回专项同口径(refund_recovery_analysis): 挽回成功单 / 挽回跟进单。higher_better, 阈值 40/30/20(#82 准入: 口径同源 + 阈值经分布验证)。",
+        "formula": {"source": "refund_recovery_analysis", "aggregation": "recovered/followed", "filter": "专项判据", "window": "同会话数"},
+        "unit": "%", "category": "performance",
+        "source_tables": ["refunds", "manual_refunds"],
+        "owner": "运营组", "remark": "#82; 实现: metric_registry_service._eval_recovery_rate",
+    },
+]
+
+
+def upgrade() -> None:
+    op.create_table(
+        'metric_dictionary',
+        sa.Column('code', sa.String(length=64), primary_key=True, comment='指标code(域.名, 如 reception.session_count)'),
+        sa.Column('name_cn', sa.String(length=128), nullable=False, comment='显示名(全站唯一)'),
+        sa.Column('definition', sa.Text(), nullable=False, comment='口径语义: 含什么/排什么/时点'),
+        sa.Column('formula', JSONB(), nullable=True,
+                  comment='结构化公式: {source, aggregation, filter, window}'),
+        sa.Column('unit', sa.String(length=16), nullable=True, comment='单位: 个/次/人/笔/元/%/值'),
+        sa.Column('category', sa.String(length=16), nullable=False, comment='分类: reception/refund/complaint/cash/performance'),
+        sa.Column('source_tables', JSONB(), nullable=True, comment='来源表清单(供下钻/健康检查)'),
+        sa.Column('owner', sa.String(length=32), nullable=True, comment='口径负责人'),
+        sa.Column('is_active', sa.Boolean(), nullable=False, server_default=sa.text('true'),
+                  comment='是否现行口径(停用不删, 留历史引用可查)'),
+        sa.Column('remark', sa.Text(), nullable=True, comment='备注(变更背景/工单号)'),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        comment='指标字典: 口径单点登记(#257 B4-1)',
+    )
+    op.create_index('ix_metric_dictionary_category', 'metric_dictionary', ['category'])
+    op.create_index('ix_metric_dictionary_name_cn', 'metric_dictionary', ['name_cn'], unique=True)
+
+    # 种子 19 条(幂等: ON CONFLICT DO NOTHING, 重复执行不报错)
+    for s in _SEEDS:
+        op.execute(
+            sa.text("""
+                INSERT INTO metric_dictionary
+                    (code, name_cn, definition, formula, unit, category,
+                     source_tables, owner, is_active, remark)
+                VALUES (:code, :name_cn, :definition,
+                        CAST(:formula AS jsonb), :unit, :category,
+                        CAST(:source_tables AS jsonb), :owner, true, :remark)
+                ON CONFLICT (code) DO NOTHING
+            """).bindparams(
+                code=s["code"], name_cn=s["name_cn"], definition=s["definition"],
+                formula=json_dumps(s.get("formula")), unit=s.get("unit"),
+                category=s["category"], source_tables=json_dumps(s.get("source_tables")),
+                owner=s.get("owner"), remark=s.get("remark"),
+            )
+        )
+
+
+def json_dumps(v):
+    """JSONB 绑定参数序列化( None → NULL )。"""
+    import json
+    return json.dumps(v, ensure_ascii=False) if v is not None else None
+
+
+def downgrade() -> None:
+    op.drop_index('ix_metric_dictionary_name_cn', table_name='metric_dictionary')
+    op.drop_index('ix_metric_dictionary_category', table_name='metric_dictionary')
+    op.drop_table('metric_dictionary')

backend/alembic/versions/b4_2_batch_jobs.py

@@ -0,0 +1,89 @@
+"""B4-2 (#258): 夜间批处理基建 - batch_jobs 调度表 + batch_job_runs 执行日志
+
+Revision ID: b4_2_batch_jobs
+Revises: b4_1_metric_dictionary
+Create Date: 2026-10-09 01:00:00.000000
+
+依据: 排期 §七 B4-2 (S-P1-7); 机制来源 dify 调度表 + zammad daily_event_lock
+     (只抄模式, 自建不引入; 详见 app/services/batch_runner.py 模块注释)。
+
+范围:
+1. batch_jobs 调度配置(job_name PK / schedule_daily_at 北京时间 / enabled /
+   timeout_minutes / next_run_at / 留痕字段 / consecutive_failures 熔断计数)
+2. batch_job_runs 执行日志 + 两道幂等锁(部分唯一索引):
+   - ux_batch_job_runs_running: (job_name) WHERE status='running'      防重叠
+   - ux_batch_job_runs_daily:   (job_name, business_date)
+         WHERE status IN ('running','success')                          防当日重跑
+
+不 seed 调度行: runner 启动时按代码注册表 _ensure_job_rows 幂等补插(ON CONFLICT DO
+NOTHING), 新任务挂接零迁移。
+
+downgrade: 新表 DROP 即安全回退, 无业务数据损失(仅夜批日志)。
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import JSONB
+
+from alembic import op
+
+revision: str = 'b4_2_batch_jobs'
+down_revision: Union[str, None] = 'b4_1_metric_dictionary'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'batch_jobs',
+        sa.Column('job_name', sa.String(length=64), primary_key=True, comment='任务名(代码层 batch_registry 注册键)'),
+        sa.Column('schedule_daily_at', sa.String(length=5), nullable=False, comment='每日调度时刻 北京时间 HH:MM'),
+        sa.Column('enabled', sa.Boolean(), nullable=False, server_default=sa.text('true'),
+                  comment='是否启用(熔断自动关, 人工重开)'),
+        sa.Column('timeout_minutes', sa.Integer(), nullable=False, server_default='120',
+                  comment='运行超时(分钟); 超时 run 标记 timeout 并释放锁'),
+        sa.Column('next_run_at', sa.DateTime(timezone=True), nullable=True, comment='下次调度时刻(UTC tz-aware)'),
+        sa.Column('last_run_at', sa.DateTime(timezone=True), nullable=True, comment='最近一次调度时刻'),
+        sa.Column('last_status', sa.String(length=16), nullable=True, comment='最近结果: success/failed/timeout/skipped'),
+        sa.Column('last_error', sa.Text(), nullable=True, comment='最近错误摘要'),
+        sa.Column('consecutive_failures', sa.Integer(), nullable=False, server_default='0',
+                  comment='连续失败次数(成功清零; 达阈值熔断)'),
+        sa.Column('updated_by', sa.String(length=64), nullable=True, comment='最后修改人(人工启用/停用留痕)'),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+    )
+    op.create_table(
+        'batch_job_runs',
+        sa.Column('id', sa.BigInteger(), primary_key=True, autoincrement=True),
+        sa.Column('job_name', sa.String(length=64), nullable=False, index=True),
+        sa.Column('business_date', sa.String(length=10), nullable=False,
+                  comment='业务日(YYYY-MM-DD 北京时间; 夜批跑昨数但归属调度日)'),
+        sa.Column('status', sa.String(length=16), nullable=False, server_default='running',
+                  comment='running/success/failed/timeout/skipped'),
+        sa.Column('started_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column('finished_at', sa.DateTime(timezone=True), nullable=True, comment='结束时刻(运行中为 NULL)'),
+        sa.Column('detail', JSONB(), nullable=True, comment='执行明细(行数/耗时等, job 函数返回)'),
+        sa.Column('error', sa.Text(), nullable=True, comment='错误摘要(失败/超时)'),
+        sa.Column('triggered_by', sa.String(length=32), nullable=True, comment='触发来源: scheduler/manual'),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+    )
+    # 幂等锁 1: 同一 job 全局仅一个 running
+    op.create_index(
+        'ux_batch_job_runs_running', 'batch_job_runs', ['job_name'],
+        unique=True, postgresql_where=sa.text("status = 'running'"),
+    )
+    # 幂等锁 2: 同一 job 同一业务日仅一个 running/success
+    op.create_index(
+        'ux_batch_job_runs_daily', 'batch_job_runs', ['job_name', 'business_date'],
+        unique=True, postgresql_where=sa.text("status IN ('running', 'success')"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_index('ux_batch_job_runs_daily', table_name='batch_job_runs',
+                  postgresql_where=sa.text("status IN ('running', 'success')"))
+    op.drop_index('ux_batch_job_runs_running', table_name='batch_job_runs',
+                  postgresql_where=sa.text("status = 'running'"))
+    op.drop_table('batch_job_runs')
+    op.drop_table('batch_jobs')

backend/alembic/versions/b4_3_audit_changes.py

@@ -0,0 +1,59 @@
+"""B4-5 (#261): 统一变更审计表 audit_changes (S-P1-11)
+
+Revision ID: b4_3_audit_changes
+Revises: b4_2_batch_jobs
+Create Date: 2026-10-09 02:00:00.000000
+
+依据: 排期 §七 B4-5; 范式来源 zammad histories / helpdesk TicketChange
+     (统一变更模型: 实体 + 动作 + 字段级 before/after)。
+
+范围:
+1. audit_changes 统一变更审计表(entity_type/entity_id/action/actor/source/
+   changes JSONB{field:[before,after]}/summary)
+2. 索引: entity_type+entity_id 联合(实体追溯主路径) / created_at(保留期清理扫描)
+   / source(来源过滤) —— 单列 entity_type/entity_id 索引由联合索引左前缀覆盖,
+   不重复建。
+
+downgrade: 新表 DROP 即安全回退(仅审计数据, 无业务数据损失)。
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import JSONB
+
+from alembic import op
+
+revision: str = 'b4_3_audit_changes'
+down_revision: Union[str, None] = 'b4_2_batch_jobs'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'audit_changes',
+        sa.Column('id', sa.BigInteger(), primary_key=True, autoincrement=True),
+        sa.Column('entity_type', sa.String(length=64), nullable=False, comment='实体类型(表名, 如 persons/manual_refunds)'),
+        sa.Column('entity_id', sa.String(length=64), nullable=False, comment='实体主键(统一字符串)'),
+        sa.Column('action', sa.String(length=16), nullable=False, comment='动作: create/update/delete'),
+        sa.Column('actor_id', sa.Integer(), sa.ForeignKey('users.id', ondelete='SET NULL'), nullable=True, comment='操作人ID(系统触发为空)'),
+        sa.Column('actor_name', sa.String(length=64), nullable=True, comment='操作人账号(冗余,用户删除后仍可审计)'),
+        sa.Column('source', sa.String(length=16), nullable=False, comment='来源: api/night_batch/manual_import/system'),
+        sa.Column('changes', JSONB(), nullable=True, comment='字段级变更: {field: [before, after]}'),
+        sa.Column('summary', sa.Text(), nullable=True, comment='人类可读摘要'),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        comment='统一变更审计: 实体字段级 before/after(#261 B4-5)',
+    )
+    # 实体追溯主路径: 查"某实体被谁改成什么样"
+    op.create_index('ix_audit_changes_entity', 'audit_changes', ['entity_type', 'entity_id'])
+    # 保留期清理扫描 + 时间范围查询
+    op.create_index('ix_audit_changes_created_at', 'audit_changes', ['created_at'])
+    op.create_index('ix_audit_changes_source', 'audit_changes', ['source'])
+
+
+def downgrade() -> None:
+    op.drop_index('ix_audit_changes_source', table_name='audit_changes')
+    op.drop_index('ix_audit_changes_created_at', table_name='audit_changes')
+    op.drop_index('ix_audit_changes_entity', table_name='audit_changes')
+    op.drop_table('audit_changes')

backend/alembic/versions/b4c9d1f02e5a_add_cs_records_table.py

@@ -10,9 +10,9 @@ Create Date: 2026-07-26 23:00:00.000000
 """
 from typing import Sequence, Union
 
-from alembic import op
 import sqlalchemy as sa
 
+from alembic import op
 
 revision: str = 'b4c9d1f02e5a'
 down_revision: Union[str, None] = 'a3f8c2e91b4d'

backend/alembic/versions/b8c9d0e1f2a3_create_shanmao_refunds.py

@@ -27,10 +27,11 @@ Create Date: 2026-08-07 14:30:00.000000
 """
 from typing import Sequence, Union
 
-from alembic import op
 import sqlalchemy as sa
 from sqlalchemy.dialects import postgresql
 
+from alembic import op
+
 # revision identifiers, used by Alembic.
 revision: str = 'b8c9d0e1f2a3'
 down_revision: Union[str, None] = 'a7b8c9d0e1f2'

backend/alembic/versions/b9c0d1e2f3a4_ai_reports.py

@@ -0,0 +1,70 @@
+"""ai_reports: AI 分析报告历史持久化 (工单 #116)
+
+Revision ID: b9c0d1e2f3a4
+Revises: a8b9c0d1e2f3
+Create Date: 2026-09-16 00:00:00.000000
+
+设计:
+- ai_reports 表: AI 分析任务成功后落库的完整产物(question + answer_md + 窗口 + 用时 + token)
+- 仅 success 落库(失败/运行中不落库); 永久保留(用户在工单 #116 明确选永久保留)
+- 归属: user_id 隔离, 仅本人可见; admin 可查全部
+- 关联 users(id) ON DELETE CASCADE: 用户被删除时报告级联清空
+- 索引: (user_id, created_at DESC) 主查询路径; created_at 时间范围扫
+- 不 seed(用户主动使用产生)
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'b9c0d1e2f3a4'
+down_revision: Union[str, None] = 'a8b9c0d1e2f3'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'ai_reports',
+        sa.Column('id', sa.BigInteger(), autoincrement=True, nullable=False),
+        sa.Column('task_id', sa.String(length=32), nullable=True, comment='对应内存 ai_task_manager 的 task_id; 规则层秒回无 task_id 则 NULL'),
+        sa.Column('user_id', sa.BigInteger(), nullable=False, comment='归属用户 id(仅本人可见, admin 可查全部)'),
+        sa.Column('question', sa.Text(), nullable=False, comment='原问句'),
+        sa.Column('period', sa.String(length=16), nullable=True, comment='窗口周期 daily/weekly/monthly/range'),
+        sa.Column('date', sa.Date(), nullable=True, comment='显式日期(纯日期)'),
+        sa.Column('start', sa.Date(), nullable=True, comment='区间起点(纯日期)'),
+        sa.Column('end', sa.Date(), nullable=True, comment='区间终点(纯日期)'),
+        sa.Column('window_source', sa.String(length=16), nullable=True, comment='窗口判定来源: explicit_range/explicit_date/nl/nl_llm/period/rule'),
+        sa.Column('window_label', sa.String(length=64), nullable=True, comment='窗口说明(如 2026-09-15(今天))'),
+        sa.Column('answer_md', sa.Text(), nullable=False, comment='LLM 返回的 markdown 报告'),
+        sa.Column('llm_model', sa.String(length=64), nullable=True, comment='命中的 provider+model; 规则层秒回=rule-engine'),
+        sa.Column('llm_ms', sa.Integer(), nullable=False, comment='LLM 推理耗时(ms)'),
+        sa.Column('total_ms', sa.Integer(), nullable=False, comment='端到端总耗时(ms)'),
+        sa.Column('prompt_tokens', sa.Integer(), nullable=True, comment='输入 token(OpenAI usage.prompt_tokens); 服务端不返则 NULL'),
+        sa.Column('completion_tokens', sa.Integer(), nullable=True, comment='输出 token(OpenAI usage.completion_tokens); 服务端不返则 NULL'),
+        sa.Column('total_tokens', sa.Integer(), nullable=True, comment='总 token(OpenAI usage.total_tokens); 服务端不返则 NULL'),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.ForeignKeyConstraint(['user_id'], ['users.id'], ondelete='CASCADE'),
+        sa.PrimaryKeyConstraint('id'),
+        sa.UniqueConstraint('task_id', name='uq_ai_reports_task_id'),
+    )
+    # 主查询路径: 列表分页(本人最近 N 条) + 时间范围筛选
+    op.create_index(
+        'ix_ai_reports_user_created',
+        'ai_reports',
+        ['user_id', sa.text('created_at DESC')],
+    )
+    # 时间范围扫(管理员看全局时间线, 或 KPI 聚合)
+    op.create_index(
+        'ix_ai_reports_created_at',
+        'ai_reports',
+        ['created_at'],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index('ix_ai_reports_created_at', table_name='ai_reports')
+    op.drop_index('ix_ai_reports_user_created', table_name='ai_reports')
+    op.drop_table('ai_reports')

backend/alembic/versions/c0d1e2f3a4b5_phase_c_policy_audit_upstream.py

@@ -16,10 +16,10 @@ Create Date: 2026-08-18 02:00:00.000000
 """
 from typing import Sequence, Union
 
-from alembic import op
 import sqlalchemy as sa
 from sqlalchemy.dialects import postgresql
 
+from alembic import op
 
 revision: str = 'c0d1e2f3a4b5'
 down_revision: Union[str, None] = 'b0c1d2e3f4a5'

backend/alembic/versions/c1d2e3f4a5b6_ai_report_templates.py

@@ -0,0 +1,65 @@
+"""ai_report_templates: AI 报告模板配置 (工单 #119)
+
+Revision ID: c1d2e3f4a5b6
+Revises: b9c0d1e2f3a4
+Create Date: 2026-09-16 12:50:00.000000
+
+设计:
+- ai_report_templates 表: 配置化的 AI 报告模板(同源 prompt + 关键词匹配 + 调度 + 多模型分工)
+- 模板同源: 前台实时与后台预生成共用同一份 question_template prompt
+- question_keywords 用 JSONB(数组)便于匹配用户问句
+- 自引用 fallback_template_id ON DELETE SET NULL: 简版被删时降级字段置 NULL
+- 关联 users(id) ON DELETE SET NULL: 创建者被删时模板保留
+- 不 seed(留待 #124 内置默认模板工单)
+- 索引: (is_active, frequency) 调度器扫描用; code unique 唯一标识
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+from alembic import op
+
+revision: str = 'c1d2e3f4a5b6'
+down_revision: Union[str, None] = 'b9c0d1e2f3a4'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'ai_report_templates',
+        sa.Column('id', sa.BigInteger(), autoincrement=True, nullable=False),
+        sa.Column('code', sa.String(length=64), nullable=False, comment='模板编码(如 daily_general_morning), 全树唯一'),
+        sa.Column('name_cn', sa.String(length=128), nullable=False, comment='显示名(如「每日晨会·整体经营」), admin 管理界面与通知用'),
+        sa.Column('question_template', sa.Text(), nullable=False, comment='问题/prompt 模板, 可含变量 {{date}} {{period}}; 前后台同源共用'),
+        sa.Column('question_keywords', postgresql.JSONB(astext_type=sa.Text()), nullable=True, comment='关键词数组(如 ["今天","今日","整体","总览"]); 用于匹配用户问句到对应模板'),
+        sa.Column('period', sa.String(length=16), nullable=False, comment='窗口周期 daily/weekly/monthly/range'),
+        sa.Column('frequency', sa.String(length=32), nullable=False, comment='调度频率: sync-triggered(同步后触发) / daily / weekly / monthly'),
+        sa.Column('trigger_at', sa.String(length=32), nullable=True, comment='触发时刻: daily→HH:MM(如 09:00); weekly→wday:H(如 1:09=周一9点); monthly→day:H'),
+        sa.Column('sync_offset_min', sa.Integer(), nullable=False, server_default='5', comment='sync-triggered 频率下, 同步完成后延迟分钟数(避免数据未稳), 默认 5'),
+        sa.Column('priority', sa.Integer(), nullable=False, server_default='100', comment='多模板同时触发时的执行顺序(小先执行), 默认 100'),
+        sa.Column('llm_provider_code', sa.String(length=64), nullable=True, comment='指定 provider code 跑此模板; None 走多 provider 优先级遍历(默认)'),
+        sa.Column('fallback_template_id', sa.BigInteger(), nullable=True, comment='LLM 调用失败时降级到的简版模板 id; None=不降级'),
+        sa.Column('max_tokens', sa.Integer(), nullable=False, server_default='2000', comment='后台预生成 token 上限(详尽), 默认 2000; 前台实时由调用方覆盖为 800'),
+        sa.Column('is_active', sa.Boolean(), nullable=False, server_default=sa.true(), comment='启停开关; False 时调度器跳过此模板'),
+        sa.Column('visibility_scope', sa.String(length=16), nullable=False, server_default='public', comment='可见性: public(全员可看预生成报告) / admin_only(仅 admin 可看)'),
+        sa.Column('created_by', sa.BigInteger(), nullable=True, comment='创建者 user_id; 用户被删时置 NULL(模板保留)'),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.ForeignKeyConstraint(['created_by'], ['users.id'], ondelete='SET NULL'),
+        sa.ForeignKeyConstraint(['fallback_template_id'], ['ai_report_templates.id'], ondelete='SET NULL'),
+        sa.PrimaryKeyConstraint('id'),
+        sa.UniqueConstraint('code', name='uq_ai_report_templates_code'),
+    )
+    # 调度器扫描: WHERE is_active=true AND frequency=? 按时点过滤
+    op.create_index(
+        'ix_ai_report_templates_active_freq',
+        'ai_report_templates',
+        ['is_active', 'frequency'],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index('ix_ai_report_templates_active_freq', table_name='ai_report_templates')
+    op.drop_table('ai_report_templates')

backend/alembic/versions/c2_drop_unused_idx_286.py

@@ -0,0 +1,44 @@
+"""#286 删除 8 个未用索引 (约 72MB, #274 审计 C2)
+
+Revision ID: c2_drop_unused_idx_286
+Revises: o5_risk_alert_settings
+Create Date: 2026-10-09
+
+依据: pg_stat_user_indexes 统计自集群初始化从未 reset, 8 个索引 idx_scan=0
+且 >1MB; 已逐个复核列引用与去重键:
+- ticket_action_logs 3 索引: 访问均以 ticket_no(FK 索引) 为入口;
+- devices.start_iccid / service_tickets.synced_at / cash_flow_wide.biz_no:
+  只写不作为过滤条件;
+- merchant_refunds.merchant_order_no: 去重走 (trade_time, merchant_order_no)
+  部分唯一复合索引, 与本单列索引无关;
+- data_match_relations.src_table: 100% 行均为 'refund', 过滤无选择性。
+"""
+from alembic import op
+
+# revision identifiers
+revision = "c2_drop_unused_idx_286"
+down_revision = "o5_risk_alert_settings"
+branch_labels = None
+depends_on = None
+
+# (索引名, 表名, 列) — downgrade 按此重建
+_INDEXES = [
+    ("ix_ticket_action_logs_operator_action", "ticket_action_logs", ["operator"]),
+    ("ix_ticket_action_logs_action_at", "ticket_action_logs", ["action_at"]),
+    ("ix_ticket_action_logs_action_type", "ticket_action_logs", ["action_type"]),
+    ("ix_devices_start_iccid", "devices", ["start_iccid"]),
+    ("ix_service_tickets_synced_at", "service_tickets", ["synced_at"]),
+    ("ix_cash_flow_wide_biz_no", "cash_flow_wide", ["biz_no"]),
+    ("ix_merchant_refunds_merchant_order_no", "merchant_refunds", ["merchant_order_no"]),
+    ("ix_data_match_relations_src_table", "data_match_relations", ["src_table"]),
+]
+
+
+def upgrade() -> None:
+    for idx, table, _cols in _INDEXES:
+        op.drop_index(idx, table_name=table)
+
+
+def downgrade() -> None:
+    for idx, table, cols in _INDEXES:
+        op.create_index(idx, table, cols, unique=False)

backend/alembic/versions/c3d4e5f6a7b8_issue322_clean_views_batch.py

@@ -0,0 +1,49 @@
+"""#322 方案A: 批量新建 public 干净层只读视图(10 张, over ods 源表)
+
+背景(#319/#322 数据分层):
+- #319 已把 21 张信源表移入 ods schema; C2 契约要求 services/analytics/** 不得直读 ods 源表。
+- 本迁移为剩余各域落地「方案A 薄视图」: 一表一视图, **逐列取自 ods 源表, 不做任何加工**
+  (不改变任何口径/过滤/时间换算), 仅把 analytics 的「读法」从 ods 换成 public 视图。
+- refund 域的 public.refund_clean 已由上一迁移 a9b0c1d2e3f4 建好, **本迁移不重建**。
+
+单一列清单来源: app.models.ods_clean.CLEAN_VIEWS(键=视图名, 值=(源表全限定名, 列清单))。
+列清单由对应只读模型的 __table__.columns 生成, 与 conftest 视图重建共用同一来源, 保证不漂移。
+
+暴露列口径: 除内部溯源列 synced_at / raw_extra / updated_by_raw 外全部保留;
+  quality_status / quality_note 必须保留(analytics 质检清单/统计排除会读)。
+
+写入不受影响: upsert 入库 / actual_refund_time 回填等仍直写 ods 源表, 视图仅给 analytics 读。
+
+Revision ID: c3d4e5f6a7b8
+Revises: a9b0c1d2e3f4
+Create Date: 2026-10-14 01:00:00.000000
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+from app.models.ods_clean import CLEAN_VIEWS
+
+# revision identifiers, used by Alembic.
+revision: str = "c3d4e5f6a7b8"
+down_revision: str = "a9b0c1d2e3f4"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+# refund_clean 已由 a9b0c1d2e3f4 建好, 本迁移只建其余 10 张
+_NEW_VIEWS = [v for v in CLEAN_VIEWS if v != "refund_clean"]
+
+
+def upgrade() -> None:
+    for view, (src_table, cols) in CLEAN_VIEWS.items():
+        if view == "refund_clean":
+            continue  # 已存在, 不重建
+        op.execute(
+            f"CREATE VIEW public.{view} AS SELECT {cols} FROM {src_table}"
+        )
+
+
+def downgrade() -> None:
+    for view in _NEW_VIEWS:
+        op.execute(f"DROP VIEW IF EXISTS public.{view}")

backend/alembic/versions/c3e4f5a6b7c8_add_ticket_action_logs.py

@@ -22,10 +22,10 @@ Create Date: 2026-08-06 14:50:00.000000
 """
 from typing import Sequence, Union
 
-from alembic import op
 import sqlalchemy as sa
 from sqlalchemy.dialects import postgresql
 
+from alembic import op
 
 # revision identifiers, used by Alembic.
 revision: str = 'c3e4f5a6b7c8'

backend/alembic/versions/c4d5e6f7a8b9_fix_metric_thresholds_and_add_backlog_net.py

@@ -0,0 +1,206 @@
+"""fix_metric_thresholds_and_add_backlog_net
+
+#83: 指标阈值严重错配治理 + 新增「积压净增」指标
+
+## 问题（2026-09-14 生产实测，近90天分布）
+3 个 lower_better 指标的阈值比真实常态低 6.6~13.5 倍 → **每天恒报 critical**，
+告警机制对它们实际已失效（使用者会学会忽略告警 → 比没有告警更糟）：
+
+| 指标 | 近90天 p50 | 旧阈值 warn/crit | 倍数 |
+|---|---|---|---|
+| refund_count（旧口径 refunds 单表） | 673 | 30 / 50 | 13.5x |
+| internal_complaint_daily | 135 | 8 / 15 | 9.0x |
+| ticket_backlog | 330 | 20 / 50 | 6.6x |
+
+## 本迁移做三件事
+
+### 1. 重设 3 个错配阈值 → 异常检测语义（用户 2026-09-14 拍板）
+**预警 = p90，告警 = p95** —— 即「显著高于历史常态」才报。
+
+| 指标 | 新 warn / crit | 依据（近90天分布） |
+|---|---|---|
+| `refund_count` | 400 / 460 | 四路合计 p90=403 / p95=451 |
+| `internal_complaint_daily` | 220 / 290 | p90=216 / p95=282 |
+| `ticket_backlog` | 420 / 450 | p90=419 / p95=431（当前 585 超历史峰值，报 critical 正确） |
+
+⚠️ `recovery_rate`(30/20/优秀40) 与 `external_complaint_7d`(50/70) **不动** ——
+   其阈值经复核合理（前者是业务目标语义，后者与当前值 27 相符）。
+
+### 2. 新增 `ticket_backlog_net`（积压净增，滚动7天）
+用户决策：「存量指标看『是否在恶化』比看『绝对水位』有意义」。
+阈值 warn=149 / crit=180（依据 p90=149.1 / p95=180.1；当前值 32 → green）。
+
+### 3. 历史快照标注不可比
+`refund_count` 口径由「refunds 单表」改为「四路经营合计」（代码层，见
+`metric_registry_service._eval_refund_count`），**旧快照数值不可与新值比较**。
+本迁移在旧快照 detail 上追加标记，避免回溯分析误读。
+
+Revision ID: b8c9d0e1f2a3
+Revises: a1c2e3f4d5b6
+Create Date: 2026-09-14 10:00:00.000000
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'c4d5e6f7a8b9'
+down_revision: Union[str, None] = 'a1c2e3f4d5b6'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+NET_CODE = "ticket_backlog_net"
+
+# (metric_code, 新 warn, 新 crit) —— 按 p90/p95 重设
+THRESHOLD_FIXES = [
+    ("refund_count", 400.0, 460.0),
+    ("internal_complaint_daily", 220.0, 290.0),
+    ("ticket_backlog", 420.0, 450.0),
+]
+# 旧阈值（供 downgrade 还原）
+THRESHOLD_OLD = {
+    "refund_count": (30.0, 50.0),
+    "internal_complaint_daily": (8.0, 15.0),
+    "ticket_backlog": (20.0, 50.0),
+}
+
+
+def _has_metric(conn, code: str) -> bool:
+    return conn.execute(
+        sa.text("SELECT count(*) FROM metric_registry WHERE code = :c"), {"c": code}
+    ).scalar() > 0
+
+
+def _has_rule(conn, code: str) -> bool:
+    return conn.execute(
+        sa.text("SELECT count(*) FROM alert_rules WHERE metric_code = :c"), {"c": code}
+    ).scalar() > 0
+
+
+def _rethreshold(conn, code: str, warn: float, crit: float) -> None:
+    """关闭当前生效阈值(留痕 valid_to) + 插入新版本 —— 与
+    `PUT /metrics/{code}/thresholds` 的行为一致（不删历史，可回溯调参）"""
+    conn.execute(
+        sa.text(
+            "UPDATE metric_thresholds SET valid_to = now(), updated_at = now() "
+            "WHERE metric_code = :c AND valid_to IS NULL"
+        ),
+        {"c": code},
+    )
+    conn.execute(
+        sa.text(
+            "INSERT INTO metric_thresholds "
+            "(metric_code, excellent_value, warning_value, critical_value, "
+            " valid_from, created_at, updated_at) "
+            "VALUES (:c, NULL, :w, :k, now(), now(), now())"
+        ),
+        {"c": code, "w": warn, "k": crit},
+    )
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    # ── 1. 重设 3 个错配阈值 ──
+    for code, warn, crit in THRESHOLD_FIXES:
+        if _has_metric(conn, code):
+            _rethreshold(conn, code, warn, crit)
+
+    # ── 2. 新增「积压净增」指标 + 阈值 + 规则 ──
+    if not _has_metric(conn, NET_CODE):
+        conn.execute(
+            sa.text(
+                """
+                INSERT INTO metric_registry
+                (code, name_cn, direction, period, unit, data_sources, description, enabled, created_at, updated_at)
+                VALUES (:c, '投诉积压净增(7天)', 'lower_better', 'day', '个',
+                        '["service_tickets"]',
+                        '滚动 7 天 新增投诉工单 − 真实结案(finish−register≥3min)。为负=在消化(好); 为正=在累积(坏)。新增于 #83: 存量指标(ticket_backlog)只增不减, 用历史分位定阈值无意义, 故改看增量方向。',
+                        true, now(), now())
+                """
+            ),
+            {"c": NET_CODE},
+        )
+    # 阈值: p90/p95（近90天实测 149.1 / 180.1）
+    if not conn.execute(
+        sa.text(
+            "SELECT count(*) FROM metric_thresholds WHERE metric_code = :c AND valid_to IS NULL"
+        ),
+        {"c": NET_CODE},
+    ).scalar():
+        conn.execute(
+            sa.text(
+                "INSERT INTO metric_thresholds "
+                "(metric_code, excellent_value, warning_value, critical_value, "
+                " valid_from, created_at, updated_at) "
+                "VALUES (:c, -50.0, 149.0, 180.0, now(), now(), now())"
+            ),
+            {"c": NET_CODE},
+        )
+    if not _has_rule(conn, NET_CODE):
+        conn.execute(
+            sa.text(
+                """
+                INSERT INTO alert_rules
+                (name, type, condition, threshold, enabled, metric_code,
+                 excellent_value, warning_value, critical_value,
+                 channels, recipient_roles, silence_window, created_at, updated_at)
+                VALUES ('业务-投诉积压净增(7天)', 'metric', NULL, NULL, true, :c,
+                        -50.0, 149.0, 180.0,
+                        '["inapp"]', '["admin","supervisor"]', NULL, now(), now())
+                """
+            ),
+            {"c": NET_CODE},
+        )
+
+    # ── 3. 同步 alert_rules 的阈值副本（scan 时以 metric_thresholds 为准，
+    #        但规则上的副本会展示在预警中心，不同步会显示旧数字）──
+    for code, warn, crit in THRESHOLD_FIXES:
+        conn.execute(
+            sa.text(
+                "UPDATE alert_rules SET warning_value = :w, critical_value = :k, updated_at = now() "
+                "WHERE metric_code = :c"
+            ),
+            {"c": code, "w": warn, "k": crit},
+        )
+
+    # ── 4. 旧 refund_count 快照标注「不可比」（口径已改，防回溯误读）──
+    conn.execute(
+        sa.text(
+            "UPDATE metric_daily_snapshots "
+            "SET detail = COALESCE(detail, '') || ' [⚠️#83 口径已由 refunds 单表改为四路合计, 此值不可与新值比较]' "
+            "WHERE metric_code = 'refund_count' AND period_date < :d"
+        ),
+        {"d": "2026-09-14"},
+    )
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    # 还原 3 个阈值
+    for code, warn, crit in THRESHOLD_FIXES:
+        old = THRESHOLD_OLD.get(code)
+        if old and _has_metric(conn, code):
+            _rethreshold(conn, code, old[0], old[1])
+            conn.execute(
+                sa.text(
+                    "UPDATE alert_rules SET warning_value = :w, critical_value = :k, updated_at = now() "
+                    "WHERE metric_code = :c"
+                ),
+                {"c": code, "w": old[0], "k": old[1]},
+            )
+    # 删除新增指标（含阈值/规则）
+    if _has_rule(conn, NET_CODE):
+        conn.execute(sa.text("DELETE FROM alert_rules WHERE metric_code = :c"), {"c": NET_CODE})
+    conn.execute(sa.text("DELETE FROM metric_thresholds WHERE metric_code = :c"), {"c": NET_CODE})
+    conn.execute(sa.text("DELETE FROM metric_daily_snapshots WHERE metric_code = :c"), {"c": NET_CODE})
+    conn.execute(sa.text("DELETE FROM metric_registry WHERE code = :c"), {"c": NET_CODE})
+    # 撤销快照标注
+    conn.execute(
+        sa.text(
+            "UPDATE metric_daily_snapshots SET detail = REPLACE(detail, "
+            "' [⚠️#83 口径已由 refunds 单表改为四路合计, 此值不可与新值比较]', '') "
+            "WHERE metric_code = 'refund_count'"
+        )
+    )

backend/alembic/versions/c5d0e2a13f6b_add_strategy_docs.py

@@ -10,9 +10,9 @@ Create Date: 2026-07-26 23:30:00.000000
 """
 from typing import Sequence, Union
 
-from alembic import op
 import sqlalchemy as sa
 
+from alembic import op
 
 revision: str = 'c5d0e2a13f6b'
 down_revision: Union[str, None] = 'b4c9d1f02e5a'

backend/alembic/versions/c5d6e7f8a9b0_issue307_prompt_dual_version_and_focus_fix.py

@@ -0,0 +1,312 @@
+"""#307 AI 问答质量治理: 提示词双版拆分 + focus 卡口径修复
+
+取证结论(生产实测 4 样本 + 120b/27b 双模型批判, 2026-10-12):
+- 单一 gen_system v3(3892 字符) 同时服务实时问答与预生成, 目标相反导致:
+  ① 问「今日退款」输出全套 5 个 H2 锚点(含空段); ② 口径纪律原文背给用户(泄漏);
+  ③ 「≤500 字」对大模型失效; ④ verdict 全靠模型自判(无据判定)。
+- v3 §2「模板设计与匹配」/§3「依赖系统代码」~700 字符是维护者 CHANGELOG, 纯稀释;
+- 铁律 12 字段清单(prev_pct/*_prev_pct/registered_prev_pct 等)与 feed 实际下发
+  (yoy_value/yoy_pct/backlog_prev_pct/verdict 等)脱节, 模型按清单找字段找不到。
+
+本迁移:
+1. prompt_configs seed gen_system v4(预生成版, 删 §2/§3, 铁律 12 按 feed 实际字段重写,
+   保留 H2 五锚点供摘取层定位) — **不激活**(is_active=false), 发布后走金丝雀验证再激活,
+   激活前预生成链路继续用 v3(零回归);
+2. prompt_configs seed **gen_system_live v1**(实时问答精简版, is_active=true 直接生效;
+   代码兜底常量 ai_feed._SYSTEM_PROMPT_LIVE 与本版一致);
+3. ai_focus_configs 修三张卡(WHERE content=旧 seed 原文才更新, 防覆盖运营手工修改):
+   - focus-refund ② 与 gen_system 铁律 11a 冲突(「涉诉是风险信号」vs「合规体现非风险信号」);
+   - focus-global ①「用标题/小表格组织」是实时问答输出 H2 空段帮凶, 改为简短分点;
+   - ai-incremental-analysis 追加「无派生字段直接陈述绝对值, 禁系统话术」。
+
+Revision ID: c5d6e7f8a9b0
+Revises: a4b5c6d7e8f0
+Create Date: 2026-10-12 22:00:00.000000
+"""
+import logging
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# R-P2-16: 迁移内提示走 logger(AGENTS.md 铁律 1 禁裸 print)
+logger = logging.getLogger("alembic.runtime.migration")
+
+revision: str = 'c5d6e7f8a9b0'
+down_revision: Union[str, None] = 'a4b5c6d7e8f0'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+# ── gen_system v4(预生成版) ──────────────────────────────────────────────
+# 与 v3 的差异(全部有 #307 取证依据):
+#   - 删 v3 §2(模板设计与匹配)/§3(依赖系统代码): 维护者 CHANGELOG 注入生成 Prompt 纯稀释;
+#   - 铁律 3 长度约束改「预生成可详尽」: 实时问答已拆到 gen_system_live, 本版不再服务前台;
+#   - 铁律 9 加 verdict 直接引用(feed 已由代码预计算 #307 _add_verdicts);
+#   - 铁律 12 字段清单全部对齐 feed 实际下发字段名(yoy_value/yoy_pct/delta_pct_points/
+#     amount_pct/count_pct/backlog_prev_pct/recon_gap_*/complaint_breakdown.*_prev/verdict);
+#   - 铁律 11a 原文保留(涉诉率=合规体现), focus-refund 卡同步修正消除冲突。
+_GEN_SYSTEM_V4 = (
+    "# 客服/经营数据分析助手系统规则（预生成报告版）\n"
+    "\n"
+    "## 1. 数据来源与引用\n"
+    "- **铁律 1**: 所有数字必须来自【给定数据】，严禁编造、外推或臆测；数据中没有的写\"暂无/未提供\"。\n"
+    "- **铁律 2**: 严格按【业务口径】理解指标，不要自创定义。\n"
+    "- **铁律 3**: 回答中文，结论注明数据窗口。\n"
+    "  - **结构要求**: 报告按 H2 锚点结构化输出，锚点固定为 `## 接待分析` / `## 退款分析` / "
+    "`## 投诉分析` / `## 趋势对比` / `## 结论建议`（无数据的段写\"暂无\"，不要省略锚点）。"
+    "锚点行**必须以两个井号+空格(`## `)开头**，五个锚点名不得写成 `### 接待分析`(三级)或 "
+    "`## **接待分析**`(加粗)等变体 —— 下游摘取层按 `## ` 前缀精确匹配；锚点内更细的小节才可用 `### `。\n"
+    "  - **长度约束**: 本版服务后台预生成草稿，可详尽展开；若【数据窗口说明】含\"预生成\"字样不受前台 500 字限制。\n"
+    "- **铁律 4**: 只回答与经营数据相关的问题；无关问题礼貌说明无法回答（一句即可，不展开）。\n"
+    "- **铁律 5**: 金额一律以元为单位。\n"
+    "- **铁律 6**: 回答开头必须写明本次统计窗口（直接引用【数据窗口说明】的起止时间）；"
+    "用户问的时间范围与给定窗口不一致时，先指出差异再作答，不要默默按别的窗口回答。\n"
+    "- **铁律 7**: 给定数据里的 yoy_value/yoy_pct 是\"前一个等长周期\"的对比值，**不是另一天的独立明细**；"
+    "不要把它当成完整的一天数据来陈述。所有对比均为环比口径，回答中**禁止使用\"同比\"一词**；"
+    "用户问句含\"同比\"时，先说明数据仅支持环比口径，再用环比数据作答。\n"
+    "- **铁律 8**: **防主观推断**: 不同口径的数字（如 registered=窗口内新登记 vs handled=窗口内完成含历史单）"
+    "禁止直接相减或比较大小，必须显式标注口径差异后再下结论；"
+    "禁止做\"处理量 > 登记量 → 消化存量\"这类无证据因果推断；"
+    "数据未提供的归因（如\"退款上升因 XX 活动\"）禁止编造，一律写\"原因需结合运营侧确认\"。\n"
+    "- **铁律 9**: **业务判定方向**: 退款（金额/笔数/均单价）越少越好；接待量与会话数越多越好；"
+    "投诉越少越好，严重性 外部投诉 > 商户号投诉 > 内部投诉（外部 1 件 > 商户号 10 件）；"
+    "退款挽回率越高越好；积压投诉越低越好。陈述\"环比涨跌\"后必须按此基准标注\"利好/利空\"；"
+    "数据已带 verdict（利好/利空/持平）字段的指标**直接原样引用 verdict**，禁止改判或另行评判。\n"
+    "- **铁律 10**: **工作时间**: 客服工作时间 08:00~23:59；非工作时间（00:00~07:59）由 AI 协助处理。"
+    "解读\"接待量为 0 / 完工单为 0\"时必须先核对窗口是否落在非工作时间，"
+    "不得直接判定\"无人值班\"或\"系统故障\"。AI 接管率上升=利好（可控指标前置）。\n"
+    "- **铁律 11**: **指标解读基线（业务权威口径, 优先于铁律 9 的机械方向与通用常识）**:\n"
+    "  - a. 涉诉率/涉诉金额：高涉诉率 = 退款动作按规则执行、争议可查证, 属**合规体现, 非风险信号**; "
+    "仅当涉诉内容/备注指向违规操作（超期未退、错退、未按规则退款）时才提示关注。"
+    "涉诉率 ≠ 投诉率, 禁止把\"涉诉率高\"解读为\"客诉风险高\"。\n"
+    "  - b. 退款金额/笔数上升：先核对窗口口径（环比基数/等长周期）与时段异动（高峰批量操作）, 再定性; "
+    "不得仅凭升幅单方向判\"利空\"。若涉诉率同时偏高, 按 a 优先解读为合规体现。\n"
+    "  - c. 处理量 > 登记量：含窗口内办结历史单, 正常现象, 禁止\"消化存量\"类因果推断（延续铁律 8）。\n"
+    "  - d. 指标缺失：涉诉金额/涉诉率/专项负责人等未提供时写\"暂无\", 禁止按总额反推或编造（延续铁律 1）。\n"
+    "- **铁律 12**: **变化率引用纪律（派生数字只能引用系统下发的字段, 模型自算已实测出错）**:\n"
+    "  - a. 可引用的派生字段（**原样照搬**, 禁止四舍五入改约数, 如 40.15 不得写\"40% 左右\"）: "
+    "环比 `yoy_value`/`yoy_pct`（refund.total_amount、refund.total_count、reception.total、"
+    "refund.a_route.litigation_ratio）; 涉诉率百分点差 `delta_pct_points`; "
+    "四路占比 `amount_pct`/`count_pct`（各路占退款总额/总笔数）; "
+    "投诉环比 `registered_prev_pct`/`handled_prev_pct`/`backlog_prev_pct`"
+    "（complaint.total 与 complaint.by_source 各项, 基期为 0 时为 null）。"
+    "带 verdict（利好/利空/持平）的指标直接引用 verdict（含 registered_verdict/"
+    "handled_verdict/backlog_verdict）。\n"
+    "  - b. 本期与对比期绝对值都有、但没给对应派生字段时：只陈述两个绝对值"
+    "（对比期前值见 complaint_breakdown 各项的 registered_prev/handled_prev/backlog_prev）, "
+    "禁止自算百分号。\n"
+    "  - c. 派生字段为 null（系统算不出, 如基期为 0）时, 写\"基期为零, 无法计算变化率\", 禁止自行补算。\n"
+    "  - d. E 路（actual_cashflow_e）没有上期对比字段; recon_gap_amount/recon_gap_pct 是"
+    "\"四路经营 − E 真实现金流\"的**口径对账差异**, 不是环比, 禁止表述为\"E 环比上升/下降\"; "
+    "actual_cashflow_e_until 是 E 数据截止日（上游报表 T+1）, 当日 E=0 表示水单尚未发布, "
+    "应说\"E 数据截至当日尚未采集\", 不得报\"无退款/暂无\"。\n"
+    "  - e. daily_trend 逐日数组只含已列出的字段；禁止把汇总维度（投诉三源、退款四路、专项分组等）"
+    "自行拆成逐日/逐时段明细造表。\n"
+    "  - f. 段落数字专用：退款分析只能用 refund 段数字，接待分析只能用 reception 段数字，"
+    "投诉分析只能用 complaint/complaint_breakdown 段数字；不得把其它段的数字挪用充当本段缺失指标。"
+    "本段没有该指标时写\"暂无\"（延续铁律 11d）。\n"
+    "\n"
+    "## 2. 无关问题处理\n"
+    "- 无关问题统一回复: \"抱歉, 我只能回答本系统经营数据相关的问题（接待/退款/投诉/设备等）, 请换个问题试试。\"\n"
+)
+
+# ── gen_system_live v2(实时问答版) ───────────────────────────────────────
+# 与 ai_feed._SYSTEM_PROMPT_LIVE 代码兜底常量保持一致(DB 优先, 常量兜底)。
+# v2(vs v1): 铁律 1 补「禁止用两个绝对值自算百分比; null(基期为零)只报绝对值」
+#   —— 发布实测发现模型在 per-source 场景绕过引用自算 62.5%/100%(把基期 0 算成
+#   上升 100%), v1 措辞只说「直接引用」不足以抑制自算倾向。
+_GEN_SYSTEM_LIVE_V2 = (
+    "你是客服经营数据助手，基于【给定数据】用中文简洁回答实时问句。\n"
+    "铁律:\n"
+    "1. 所有数字必须来自【给定数据】，严禁编造；环比/占比等派生数字(如 yoy_pct、"
+    "*_prev_pct、amount_pct/count_pct)均已由系统算好，直接原样引用，禁止自行计算；"
+    "禁止用两个绝对值自算百分比；派生字段为 null(如基期为零)时只报绝对值，"
+    "禁止编出任何百分数。\n"
+    "2. 数据中带 verdict(利好/利空/持平)的指标直接引用该判定；无 verdict 的指标"
+    "只报数字，禁止自行评判好坏。\n"
+    "3. 某指标没有对比字段时，直接陈述本期数值即可，禁止写\"变化率未随数据下发\""
+    "\"无法计算\"等系统内部话术。\n"
+    "4. 只回答问句所问的内容：问退款就只说退款。禁止输出 \"## 章节标题\"、表格和"
+    "未问到的段落；用简短分点叙述，全文不超过 300 字。\n"
+    "5. 禁止向用户复述统计口径、系统规则、数据缺失原因；指标确实无数据时写\"暂无\"。\n"
+    "6. 回答第一行写明统计窗口(引用【数据窗口说明】起止时间，格式 YYYY-MM-DD HH:mm)；"
+    "金额一律元；所有对比均为环比(前一个等长周期)，禁止使用\"同比\"一词。\n"
+    "7. 只回答经营数据相关的问题；无关问题礼貌说明无法回答。\n"
+    "8. 若上下文给出【本次必须覆盖维度】清单，则逐维度给出数据(用 **维度**：加粗行)，"
+    "此时长度可放宽至 800 字，但仍禁止未问段落的空泛展开。\n"
+    "示例(问\"今日退款情况如何？\"):\n"
+    "统计窗口：2026-10-12 00:00 至 20:20\n"
+    "- 退款总额 26,061.70 元，环比 +2.4%（利空）；221 笔，环比持平。\n"
+    "- 四路：A 线上直退 13,926.30 元（53.4%）、B 钱包提现 6,208.30 元（23.8%）、"
+    "D 手动退款 5,927.10 元（22.7%）。\n"
+    "- 涉诉率 37.4%，环比下降（利好）。\n"
+    "- 建议：关注 A 路大额单笔。\n"
+)
+# v1 留痕(账本完整, 已被 v2 取代)
+_GEN_SYSTEM_LIVE_V1 = (
+    "你是客服经营数据助手，基于【给定数据】用中文简洁回答实时问句。\n"
+    "铁律:\n"
+    "1. 所有数字必须来自【给定数据】，严禁编造；环比(yoy_pct)、占比(amount_pct/"
+    "count_pct)等派生数字均已由系统算好，直接原样引用，禁止自行计算。\n"
+    "2. 数据中带 verdict(利好/利空/持平)的指标直接引用该判定；无 verdict 的指标"
+    "只报数字，禁止自行评判好坏。\n"
+    "3. 某指标没有对比字段时，直接陈述本期数值即可，禁止写\"变化率未随数据下发\""
+    "\"无法计算\"等系统内部话术。\n"
+    "4. 只回答问句所问的内容：问退款就只说退款。禁止输出 \"## 章节标题\"、表格和"
+    "未问到的段落；用简短分点叙述，全文不超过 300 字。\n"
+    "5. 禁止向用户复述统计口径、系统规则、数据缺失原因；指标确实无数据时写\"暂无\"。\n"
+    "6. 回答第一行写明统计窗口(引用【数据窗口说明】起止时间，格式 YYYY-MM-DD HH:mm)；"
+    "金额一律元；所有对比均为环比(前一个等长周期)，禁止使用\"同比\"一词。\n"
+    "7. 只回答经营数据相关的问题；无关问题礼貌说明无法回答。\n"
+    "8. 若上下文给出【本次必须覆盖维度】清单，则逐维度给出数据(用 **维度**：加粗行)，"
+    "此时长度可放宽至 800 字，但仍禁止未问段落的空泛展开。\n"
+    "示例(问\"今日退款情况如何？\"):\n"
+    "统计窗口：2026-10-12 00:00 至 20:20\n"
+    "- 退款总额 26,061.70 元，环比 +2.4%（利空）；221 笔，环比持平。\n"
+    "- 四路：A 线上直退 13,926.30 元（53.4%）、B 钱包提现 6,208.30 元（23.8%）、"
+    "D 手动退款 5,927.10 元（22.7%）。\n"
+    "- 涉诉率 37.4%，环比下降（利好）。\n"
+    "- 建议：关注 A 路大额单笔。\n"
+)
+
+_V4_REASON = (
+    "#307 AI 问答质量治理: 删 v3 §2/§3 维护者 CHANGELOG(纯稀释~700字符); "
+    "铁律 12 字段清单对齐 feed 实际下发(原 prev_pct/*_prev_pct 与实际 yoy_pct 等脱节); "
+    "铁律 9 加 verdict 直接引用(feed 已预计算); 保留 H2 五锚点供摘取层。"
+    "取证: 生产 4 坏例实测 + 120b/27b 双模型批判。"
+)
+
+_LIVE_V1_REASON = (
+    "#307 实时问答专用精简版: 单一 v3 同时服务两种模式导致实时问答输出 H2 空段/"
+    "口径纪律泄漏/超长。本版铁律: 只答所问/禁章节标题/verdict 直接引用/无对比字段禁系统话术/≤300字。"
+)
+
+_LIVE_V2_REASON = (
+    "#307 发布实测补刀: v1 下模型在 per-source 场景绕过引用, 用绝对值自算环比"
+    "(62.5%/把基期 0 自算成上升 100%)。v2 铁律 1 明确: 禁止两绝对值自算百分比, "
+    "派生字段 null(基期为零)只报绝对值。"
+)
+
+
+def _focus_updates() -> list[dict]:
+    """focus 卡修复(幂等: 仅当 content 仍等于旧 seed 原文时才 UPDATE, 防覆盖运营手工修改)。"""
+    return [
+        {
+            "code": "focus-refund",
+            # 旧文案(a1f0c2e4d6b8 seed 原文)
+            "old": (
+                "退款分析关注点: ①四路分布(A线上直退/B钱包取现/C闪猫/D手动)看结构变化, "
+                "指出主路径与异常抬升; ②涉诉率与涉诉金额是风险信号, 涉诉抬升须提示; "
+                "③E(退款记录报表)为对账基准, 若与四路经营差异明显(偏差>5%)要说明口径原因; "
+                "④金额单位=元, 大额单笔可点名但不能编造明细。"
+            ),
+            "new": (
+                "退款分析关注点: ①四路分布(A线上直退/B钱包取现/C闪猫/D手动)看结构变化, "
+                "指出主路径与异常抬升; ②涉诉率与涉诉金额按指标解读基线(铁律 11a)解读: "
+                "高涉诉率=退款动作按规则执行、争议可查证, 属合规体现非风险信号, "
+                "仅当涉诉内容指向违规操作(超期未退/错退/未按规则退款)才提示关注, "
+                "禁止把涉诉率高解读为客诉风险高; "
+                "③E(退款记录报表)为对账基准, 若与四路经营差异明显(偏差>5%)要说明口径原因; "
+                "④金额单位=元, 大额单笔可点名但不能编造明细。"
+            ),
+        },
+        {
+            "code": "focus-global",
+            "old": (
+                "通用经营分析视角: ①先给结论再给数据支撑, 用标题/要点/小表格组织; "
+                "②对比(同比/环比)给出升降幅与方向; ③有异常(突变/为0/负增长)优先说明; "
+                "④数字一律引用给定数据, 无数据的写'暂无'; 金额单位=元。"
+            ),
+            "new": (
+                "通用经营分析视角: ①先给结论再给数据支撑, 用简短分点组织, "
+                "不套固定章节模板(实时问答禁止 ## 标题与未问到的段落); "
+                "②对比给环比升降幅与方向, 数据带 verdict(利好/利空/持平)直接引用, 禁用'同比'一词; "
+                "③有异常(突变/为0/负增长)优先说明; "
+                "④数字一律引用给定数据, 无数据的写'暂无'; 金额单位=元。"
+            ),
+        },
+        {
+            "code": "ai-incremental-analysis",
+            # 完整 seed 原文(b3c4d5e6f7a8)做等值定位(UPDATE WHERE content=:old 是等值匹配,
+            # 不能用片段 —— 首版迁移用片段定位导致该卡漏更, 2026-10-12 修正)
+            "old": (
+                "当用户问'分析/总览/怎么看/风险/异常'类开放题时(纯取数问句跳过本段), 增量分析任务: "
+                "- 口径差异提醒: 当数据里出现 registered 与 handled 这类不同口径数字(见口径卡), 必须显式标注口径, 禁止直接相减或推断因果; "
+                "- 环比异常预警: yoy_pct 超 ±30% 的指标, 必须点名并给出可能原因方向(数据/运营/外部, 不下结论); "
+                "- 风险与机会: 按 business_benchmark 卡的方向判定(如'退款金额上升=风险'), 每类最多 1 条; "
+                "- 下钻建议: 给出'看哪个看板卡片/下钻到哪一层'的可执行建议(不重复数据)."
+            ),
+            "new": (
+                "当用户问'分析/总览/怎么看/风险/异常'类开放题时(纯取数问句跳过本段), 增量分析任务: "
+                "- 口径差异提醒: 当数据里出现 registered 与 handled 这类不同口径数字(见口径卡), 必须显式标注口径, 禁止直接相减或推断因果; "
+                "- 环比异常预警: yoy_pct 超 ±30% 的指标, 必须点名并给出可能原因方向(数据/运营/外部, 不下结论); "
+                "- 风险与机会: 按 business_benchmark 卡的方向判定(如'退款金额上升=风险'), 每类最多 1 条; "
+                "- 下钻建议: 给出'看哪个看板卡片/下钻到哪一层'的可执行建议(不重复数据); "
+                "无派生字段时: 某指标数据里没有环比(yoy_pct)/verdict 等派生字段, "
+                "直接陈述本期绝对值即可, 禁止输出'变化率未随数据下发/无法计算'类系统内部话术"
+                "(【数据省略说明】另有标注的除外)."
+            ),
+        },
+    ]
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    # 1) gen_system v4(不激活, 激活走管理界面金丝雀流程; 激活前预生成继续用 v3)
+    _v4 = conn.execute(
+        sa.text("SELECT 1 FROM prompt_configs WHERE code='gen_system' AND version=4")
+    ).scalar()
+    if not _v4:
+        conn.execute(sa.text(
+            "INSERT INTO prompt_configs (code, name_cn, content, version, is_active, change_reason) "
+            "VALUES ('gen_system', '生成侧·System 铁律', :content, 4, false, :reason)"
+        ), {"content": _GEN_SYSTEM_V4, "reason": _V4_REASON})
+    # 2) gen_system_live: v1 留痕 + v2 激活(v1 为空库 seed; 已装库 v1 已存在→去激活,
+    #    插入 v2 生效。同 code 至多一个生效(部分唯一索引), 幂等)
+    _live1 = conn.execute(
+        sa.text("SELECT 1 FROM prompt_configs WHERE code='gen_system_live' AND version=1")
+    ).scalar()
+    if not _live1:
+        conn.execute(sa.text(
+            "INSERT INTO prompt_configs (code, name_cn, content, version, is_active, change_reason) "
+            "VALUES ('gen_system_live', '生成侧·实时问答 System', :content, 1, false, :reason)"
+        ), {"content": _GEN_SYSTEM_LIVE_V1, "reason": _LIVE_V1_REASON})
+    conn.execute(sa.text(
+        "UPDATE prompt_configs SET is_active=false WHERE code='gen_system_live' AND version<2"
+    ))
+    _live2 = conn.execute(
+        sa.text("SELECT 1 FROM prompt_configs WHERE code='gen_system_live' AND version=2")
+    ).scalar()
+    if not _live2:
+        conn.execute(sa.text(
+            "INSERT INTO prompt_configs (code, name_cn, content, version, is_active, "
+            "activated_at, change_reason) "
+            "VALUES ('gen_system_live', '生成侧·实时问答 System', :content, 2, true, now(), :reason)"
+        ), {"content": _GEN_SYSTEM_LIVE_V2, "reason": _LIVE_V2_REASON})
+    # 3) focus 卡修复(仅当仍是 seed 原文时更新, 运营手工改过的不动)
+    for row in _focus_updates():
+        res = conn.execute(
+            sa.text("UPDATE ai_focus_configs SET content=:new, updated_by='issue307', "
+                    "updated_at=now() WHERE code=:code AND content=:old"),
+            {"code": row["code"], "old": row["old"], "new": row["new"]},
+        )
+        if res.rowcount:
+            logger.info("  focus card updated: %s", row["code"])
+        else:
+            logger.warning(
+                "  focus card skipped (content 不匹配旧 seed, 疑运营已手工修改): %s", row["code"]
+            )
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    conn.execute(sa.text("DELETE FROM prompt_configs WHERE code='gen_system' AND version=4"))
+    # live: 删 v2, v1 重激活(回到首发布态)
+    conn.execute(sa.text("DELETE FROM prompt_configs WHERE code='gen_system_live' AND version=2"))
+    conn.execute(sa.text(
+        "UPDATE prompt_configs SET is_active=true, activated_at=now() "
+        "WHERE code='gen_system_live' AND version=1"
+    ))
+    # focus 卡不回滚(文案修正无副作用, 且 WHERE 原文已不在)

backend/alembic/versions/c6d7e8f9a0b1_add_data_source_specs.py

@@ -0,0 +1,66 @@
+"""data_source_specs 接入声明表 (工单 #155)
+
+AI 数据接入助手「接入声明层」: 一行 = 一次数据源接入意图（AI 草稿 / 已确认 / 已落地）。
+声明主体字段对齐 data_sources（确认后可直接映射），AI 产物（field_specs /
+dedup_recommendation）与校验结果（validator_report）以 JSONB 存储，
+保证「AI 建议、规则校验、人工确认」三层可分别追责。
+
+本迁移只建表，不触碰 data_sources / data_source_fields（现有 registry 机制不变）。
+
+Revision ID: c6d7e8f9a0b1
+Revises: e4f5a6b7c8d9
+Create Date: 2026-09-19
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+from alembic import op
+
+revision: str = 'c6d7e8f9a0b1'
+down_revision: Union[str, None] = 'e4f5a6b7c8d9'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "data_source_specs",
+        sa.Column("id", sa.BigInteger(), autoincrement=True, primary_key=True),
+        sa.Column("code", sa.String(length=64), nullable=False),
+        sa.Column("table_name", sa.String(length=64), nullable=False),
+        sa.Column("name_cn", sa.String(length=64), nullable=False),
+        sa.Column("category", sa.String(length=32), nullable=True),
+        sa.Column("sort_order", sa.Integer(), nullable=False, server_default="999"),
+        sa.Column("time_field", sa.String(length=64), nullable=True),
+        sa.Column("sn_field", sa.String(length=64), nullable=True),
+        sa.Column("pk_field", sa.String(length=64), nullable=True),
+        sa.Column("pk_strategy", sa.String(length=32), nullable=False, server_default="primary_key"),
+        sa.Column("sync_source", sa.String(length=32), nullable=True),
+        sa.Column("description", sa.Text(), nullable=True),
+        sa.Column("status", sa.String(length=16), nullable=False, server_default="draft"),
+        sa.Column("issue_no", sa.String(length=16), nullable=True),
+        sa.Column("sample_summary", postgresql.JSONB(astext_type=sa.Text()), nullable=True),
+        sa.Column("field_specs", postgresql.JSONB(astext_type=sa.Text()), nullable=True),
+        sa.Column("dedup_recommendation", postgresql.JSONB(astext_type=sa.Text()), nullable=True),
+        sa.Column("validator_report", postgresql.JSONB(astext_type=sa.Text()), nullable=True),
+        sa.Column("apply_package", postgresql.JSONB(astext_type=sa.Text()), nullable=True),
+        sa.Column("created_by", sa.BigInteger(), nullable=True),
+        sa.Column("confirmed_by", sa.BigInteger(), nullable=True),
+        sa.Column("confirmed_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("applied_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.ForeignKeyConstraint(["confirmed_by"], ["users.id"], ondelete="SET NULL"),
+        sa.ForeignKeyConstraint(["created_by"], ["users.id"], ondelete="SET NULL"),
+        sa.UniqueConstraint("code", name="uq_data_source_specs_code"),
+    )
+    op.create_index("ix_data_source_specs_code", "data_source_specs", ["code"], unique=True)
+    op.create_index("ix_data_source_specs_status", "data_source_specs", ["status"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_data_source_specs_status", table_name="data_source_specs")
+    op.drop_index("ix_data_source_specs_code", table_name="data_source_specs")
+    op.drop_table("data_source_specs")

backend/alembic/versions/c8d9e0f1a2b3_add_ai_reports_hit_mode.py

@@ -0,0 +1,45 @@
+"""add ai_reports.hit_mode (工单 #147)
+
+Revision ID: c8d9e0f1a2b3
+Revises: g3h4i5j6k7l8
+Create Date: 2026-09-17 22:10:00.000000
+
+设计(#147 B): 历史记录需区分命中粒度。命中(L1/L2)与未命中(实时)统一落库后,
+用 hit_mode 标记该条报告是「完整采用预生成全文 / 摘取局部段落 / 实时生成 / 规则秒回」:
+- full:    命中·全量 —— 问句命中预生成模板且直接采用整篇报告(extract_section #144 规则短路)
+- section: 命中·局部 —— 命中预生成报告后按问句摘取相关段落(LLM 摘取)
+- live:    未命中·实时 —— 未命中预生成, 走实时 LLM 生成
+- rule:    规则层秒回 —— #98 层3 纯取数问句规则命中(非模板)
+历史存量报告该列为 NULL, 前端按「未标记」降级展示(不误标)。
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'c8d9e0f1a2b3'
+down_revision: Union[str, None] = 'g3h4i5j6k7l8'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "ai_reports",
+        sa.Column(
+            "hit_mode",
+            sa.String(length=16),
+            nullable=True,
+            comment=(
+                "#147 命中粒度: full(命中·全量=整篇采用预生成)/"
+                "section(命中·局部=摘取段落)/"
+                "live(未命中·实时=实时LLM)/"
+                "rule(规则层秒回); 历史存量 NULL=未标记"
+            ),
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("ai_reports", "hit_mode")

backend/alembic/versions/d1e2f3a4b5c6_template_refresh_on_sync.py

@@ -0,0 +1,48 @@
+"""feat: ai_report_templates 新增 refresh_on_sync 模板级随同步刷新开关 (工单 #130)
+
+Revision ID: d1e2f3a4b5c6
+Revises: f4a5b6c7d8e9
+Create Date: 2026-09-16 22:10:00.000000
+
+设计:
+- 刷新节奏模板化(用户诉求): 日报类内容时效性强, 需随高频数据同步及时预生成;
+  周报/月报每日定时一次即可。是否随同步刷新应由模板决定(可手动选择/按周期自动识别)。
+- 新列 refresh_on_sync BOOLEAN NOT NULL DEFAULT FALSE:
+  * True  = 每次高频数据同步成功后刷新(warm_on_sync_complete 候选)
+  * False = 仅按 trigger_at 定时(warm_idle; 周报/月报每日一次)
+- 数据回填(自动识别存量): frequency in (daily, sync-triggered) 或 period='daily'
+  的存量模板置 TRUE; weekly/monthly 置 FALSE(保持列默认)。
+- daily 模板仍保留 trigger_at=09:00 作每日保底首版, refresh_on_sync 是"额外"高频刷新。
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'd1e2f3a4b5c6'
+down_revision: Union[str, None] = 'f4a5b6c7d8e9'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        'ai_report_templates',
+        sa.Column(
+            'refresh_on_sync',
+            sa.Boolean(),
+            nullable=False,
+            server_default=sa.false(),
+        ),
+    )
+    # 自动识别存量: 日报类(daily 频率/周期, 或 sync-triggered)开启随同步刷新
+    op.execute("""
+        UPDATE ai_report_templates
+        SET refresh_on_sync = TRUE
+        WHERE frequency IN ('daily', 'sync-triggered') OR period = 'daily'
+    """)
+
+
+def downgrade() -> None:
+    op.drop_column('ai_report_templates', 'refresh_on_sync')

backend/alembic/versions/d2e3f4a5b6c7_ai_reports_ext.py

@@ -0,0 +1,77 @@
+"""ai_reports 扩字段: template_id/snapshot_date/snapshot_period/is_public/matched_count (工单 #121)
+
+Revision ID: d2e3f4a5b6c7
+Revises: c1d2e3f4a5b6
+Create Date: 2026-09-16 13:30:00.000000
+
+设计:
+- ai_reports 表加 5 字段, 支撑预生成报告与匹配命中复用统计
+- template_id FK ai_report_templates ON DELETE SET NULL(模板被删时报告保留)
+- snapshot_date/snapshot_period 报告数据时点(区别于 created_at 入库时点)
+- is_public 区分公共报告(预生成, 所有人可看)与私有报告(实时, 仅本人)
+- matched_count 命中 +1(用 UPDATE ... RETURNING 保证并发安全, 业务层负责)
+- 2 索引: (template_id, snapshot_date) 匹配查询用; (is_public, created_at) 公共报告列表用
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'd2e3f4a5b6c7'
+down_revision: Union[str, None] = 'c1d2e3f4a5b6'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # 5 新增字段
+    op.add_column('ai_reports', sa.Column(
+        'template_id', sa.Integer(), nullable=True,
+        comment='#121: 来自预生成则为模板 id, 实时生成则 NULL',
+    ))
+    op.add_column('ai_reports', sa.Column(
+        'snapshot_date', sa.Date(), nullable=True,
+        comment='#121: 报告数据时点(窗口起算 date, 区别于 created_at 的入库时点)',
+    ))
+    op.add_column('ai_reports', sa.Column(
+        'snapshot_period', sa.String(length=16), nullable=True,
+        comment='#121: daily/weekly/monthly/range(与模板 period 对应)',
+    ))
+    op.add_column('ai_reports', sa.Column(
+        'is_public', sa.Boolean(), nullable=False, server_default=sa.false(),
+        comment='#121: true=公共报告(所有人可看, 来自预生成); false=私有(仅本人, 来自实时)',
+    ))
+    op.add_column('ai_reports', sa.Column(
+        'matched_count', sa.Integer(), nullable=False, server_default='0',
+        comment='#121: 被命中复用次数(match_template_report 命中时 +1)',
+    ))
+
+    # FK: template_id -> ai_report_templates.id ON DELETE SET NULL
+    op.create_foreign_key(
+        'fk_ai_reports_template_id',
+        'ai_reports', 'ai_report_templates',
+        ['template_id'], ['id'],
+        ondelete='SET NULL',
+    )
+
+    # 索引
+    op.create_index(
+        'ix_ai_reports_template_snapshot',
+        'ai_reports', ['template_id', 'snapshot_date'],
+    )
+    op.create_index(
+        'ix_ai_reports_public_created',
+        'ai_reports', ['is_public', 'created_at'],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index('ix_ai_reports_public_created', table_name='ai_reports')
+    op.drop_index('ix_ai_reports_template_snapshot', table_name='ai_reports')
+    op.drop_constraint('fk_ai_reports_template_id', 'ai_reports', type_='foreignkey')
+    op.drop_column('ai_reports', 'matched_count')
+    op.drop_column('ai_reports', 'is_public')
+    op.drop_column('ai_reports', 'snapshot_period')
+    op.drop_column('ai_reports', 'snapshot_date')
+    op.drop_column('ai_reports', 'template_id')

backend/alembic/versions/d3_profile_probe_at.py

@@ -0,0 +1,45 @@
+"""add devices.profile_probe_at
+
+Revision ID: d3_profile_probe_at
+Revises: c2_drop_unused_idx_286
+Create Date: 2026-10-10
+
+加 devices.profile_probe_at 字段(档案探针时间, #293)。
+
+背景: 设备档案 SN 补全(device_profile_enrich)以「缺字段」为扫描口径,
+但两类设备永远无法出队——① BMS 查无此 SN 的 miss(短SN脏数据/已删设备,
+约占 45%); ② hit 但无套餐等设备(current_combo_name 在 BMS 本就为空)。
+miss 路径原不写任何标记 → 永久 miss 在每批堆积, 3~4 批后扫描配额被全部占满,
+回填实际停滞(2026-10-10 生产实测: 批1 hit 11018 但仅 1073 台退出缺失集)。
+
+修复: hit/miss 都写 profile_probe_at=now() 探针时间; 扫描只看
+「未探针 OR 探针超过 30 天」(30 天复探窗口给后续新买套餐设备留刷新口)。
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "d3_profile_probe_at"
+down_revision = "c2_drop_unused_idx_286"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "devices",
+        sa.Column(
+            "profile_probe_at",
+            sa.DateTime(timezone=True),
+            nullable=True,
+            comment="档案探针时间(#293): SN 补全探过的时刻, 含 miss; 扫描只看未探针或超30天",
+        ),
+    )
+    # 存量已被探过的设备(active_flag 非空 = 日批导出/补全已写入过 BMS 数据)直接打标,
+    # 避免上线后对 23 万已探设备重扫一遍; 日批导出负责其后续字段刷新
+    op.execute("UPDATE devices SET profile_probe_at = now() WHERE active_flag IS NOT NULL AND active_flag != ''")
+
+
+def downgrade() -> None:
+    op.drop_column("devices", "profile_probe_at")

backend/alembic/versions/d4e5f6a7b8c0_llm_cloud_policy_singleton.py

@@ -0,0 +1,55 @@
+"""llm_cloud_policy 单行表 —— 出域策略可从界面切换（无需改 .env 重启）
+
+背景（2026-09-21，见 docs/design/20260921-模型角色分组与出域管控设计.md §3.3）:
+
+  B1 出域管控上线时，策略取自 `settings.LLM_CLOUD_POLICY`（.env）。
+  但 .env 改动需重启服务，与「管理员界面自助调整」诉求不符 ——
+  B3 界面只能只读展示并提示"需改 .env 重启"。
+
+  本迁移照 `scheduler_settings` 的既有模式把策略 DB 化:
+    - 单行表（id 恒为 1）: 避免"多行配置哪行生效"歧义
+    - DB CHECK 约束作为最后防线（防手工改库写入非法值）
+    - **不预置行**: DB 无行时运行时回退 settings.LLM_CLOUD_POLICY，
+      保证升级后行为与 B1 完全一致（零行为变更）
+
+Revision ID: d4e5f6a7b8c0
+Revises: a3b4c5d6e7f8
+Create Date: 2026-09-21 09:40:00.000000
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = 'd4e5f6a7b8c0'
+down_revision: Union[str, None] = 'a3b4c5d6e7f8'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "llm_cloud_policy",
+        sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
+        sa.Column("policy", sa.String(16), nullable=False,
+                  server_default=sa.text("'explicit_only'"),
+                  comment="出域策略: never / explicit_only / auto"),
+        sa.Column("require_confirm", sa.Boolean(), nullable=False,
+                  server_default=sa.text("true"),
+                  comment="explicit_only 下是否需用户确认（预留）"),
+        sa.Column("updated_by", sa.String(64), nullable=True, comment="最后修改人账号"),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False,
+                  server_default=sa.text("now()")),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False,
+                  server_default=sa.text("now()")),
+        sa.CheckConstraint("policy IN ('never', 'explicit_only', 'auto')",
+                           name="ck_llm_cloud_policy_value"),
+    )
+    # 刻意**不预置行** —— 运行时回退 settings.LLM_CLOUD_POLICY（B1 行为）。
+    # 管理员首次在界面保存时才写入，届时 DB 值优先。
+
+
+def downgrade() -> None:
+    op.drop_table("llm_cloud_policy")

backend/alembic/versions/d5f6a7b8c9d0_add_doc_sync_configs.py

@@ -6,10 +6,10 @@ Create Date: 2026-08-22 12:00:00.000000
 """
 from typing import Sequence, Union
 
-from alembic import op
 import sqlalchemy as sa
 from sqlalchemy.dialects import postgresql
 
+from alembic import op
 
 revision: str = "d5f6a7b8c9d0"
 down_revision: Union[str, None] = "n9a8b7c6d5e4f"

backend/alembic/versions/d6e7f8a9b0c1_issue319_create_ods_schema.py

@@ -0,0 +1,34 @@
+"""#319 数据分层 M1: 创建 ods schema(信源表层)
+
+背景: 系统 86 张表混居 public schema, 其中 21 张是 BMS/SCRM/企微等上游信源的
+浅层拷贝(ods 性质), 与系统业务表(强逻辑/强约束)混杂, 边界不清。
+本次分层(M1 建 schema → M2 移表 → M3 autogen 适配)把信源表归入 ods schema:
+  - public = 系统业务库(宁缺毋滥, 强约束)
+  - ods    = 信源直连层(浅层拷贝, 原始留痕)
+
+裸 SQL 兼容: 不逐处改写 300+ 处历史裸 SQL, 由 database.py 连接级
+`SET search_path TO public, ods` 兜底(见 app/core/database.py 注释)。
+
+Revision ID: d6e7f8a9b0c1
+Revises: c5d6e7f8a9b0
+Create Date: 2026-10-13 10:00:00.000000
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "d6e7f8a9b0c1"
+down_revision: str = "c5d6e7f8a9b0"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute("CREATE SCHEMA IF NOT EXISTS ods")
+
+
+def downgrade() -> None:
+    # 仅当 ods 已空(M2 已回退)才允许删 schema, 防止连带丢表
+    op.execute("DROP SCHEMA IF EXISTS ods")

backend/alembic/versions/d9b7f1b89c1d_init_schema_with_data_sources_persons_.py

@@ -1,15 +1,16 @@
 """init schema with data sources persons and upload archive
 
 Revision ID: d9b7f1b89c1d
-Revises: 
+Revises:
 Create Date: 2026-07-26 17:00:28.338446
 """
 from typing import Sequence, Union
 
-from alembic import op
 import sqlalchemy as sa
 from sqlalchemy.dialects import postgresql
 
+from alembic import op
+
 revision: str = 'd9b7f1b89c1d'
 down_revision: Union[str, None] = None
 branch_labels: Union[str, Sequence[str], None] = None

backend/alembic/versions/dc20f480c17e_add_doc_sync_login_logs_工单_149.py

@@ -0,0 +1,53 @@
+"""add doc_sync_login_logs (工单 #149)
+
+登录历史表: 记录每次页面内扫码登录的最终结果(成功/失败), 供运维审计
+「谁在何时用什么账号登录」, 定位登录态被覆盖或失效的时序。
+
+Revision ID: dc20f480c17e
+Revises: x9y0z1a2b3c4
+Create Date: 2026-09-18 16:25:29.463158
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = 'dc20f480c17e'
+down_revision: Union[str, None] = 'x9y0z1a2b3c4'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # 登录历史表: 一行 = 一次登录会话的最终结果
+    op.create_table(
+        'doc_sync_login_logs',
+        sa.Column('id', sa.BigInteger(), autoincrement=True, nullable=False),
+        sa.Column(
+            'platform', sa.String(length=32), nullable=False,
+            comment='平台: tencent=腾讯 / kdocs=金山',
+        ),
+        sa.Column(
+            'source_id', sa.Integer(), nullable=True,
+            comment='触发登录的采集源 id(可为空: CLI 上传登录态)',
+        ),
+        sa.Column('uid', sa.String(length=128), nullable=True, comment='登录账号(脱敏, 取不到为空)'),
+        sa.Column(
+            'cookies_count', sa.Integer(), nullable=False,
+            comment='保存成功后的 cookie 条数(失败为 0)',
+        ),
+        sa.Column(
+            'result', sa.String(length=16), nullable=False,
+            comment='success=登录态已保存 / failed=校验或保存失败',
+        ),
+        sa.Column('error', sa.Text(), nullable=True, comment='失败原因(成功为空)'),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+        sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+        sa.PrimaryKeyConstraint('id'),
+    )
+    op.create_index(op.f('ix_doc_sync_login_logs_platform'), 'doc_sync_login_logs', ['platform'], unique=False)
+
+
+def downgrade() -> None:
+    op.drop_index(op.f('ix_doc_sync_login_logs_platform'), table_name='doc_sync_login_logs')
+    op.drop_table('doc_sync_login_logs')

backend/alembic/versions/e1_renew_probe_at.py

@@ -0,0 +1,44 @@
+"""add devices.renew_probe_at
+
+Revision ID: e1_renew_probe_at
+Revises: d3_profile_probe_at
+Create Date: 2026-10-10
+
+加 devices.renew_probe_at 字段(续费记录探针时间, #293)。
+
+背景: 续费记录套餐兜底(mode="renew")与设备列表探针共用 profile_probe_at,
+两类问题:
+1. renew 扫描无法区分「已被续费探过(含miss)」与「仅设备列表探过」——
+   miss 设备刷新 profile_probe_at 后在排序中形成「miss墙」, 挡住后续
+   未扫描设备(2026-10-10 实测: 首批零填充即误判收敛, 94,570 台漏扫);
+2. renew 写 profile_probe_at 会把设备推出设备列表 30 天扫描窗口, 两个
+   探针语义被耦合。
+
+修复: 独立 renew_probe_at; renew 扫描只取「未续费探过 OR 超30天」的
+缺套餐设备, miss 打 renew 标记后不再挡道, target=0 才是真收敛。
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "e1_renew_probe_at"
+down_revision = "d3_profile_probe_at"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "devices",
+        sa.Column(
+            "renew_probe_at",
+            sa.DateTime(timezone=True),
+            nullable=True,
+            comment="续费记录探针时间(#293): 套餐兜底查过的时刻, 含miss; renew扫描只看未探或超30天",
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("devices", "renew_probe_at")

backend/alembic/versions/e1f2a3b4c5d6_add_ingest_mode_configs.py

@@ -6,9 +6,9 @@ Create Date: 2026-08-22 13:00:00.000000
 """
 from typing import Sequence, Union
 
-from alembic import op
 import sqlalchemy as sa
 
+from alembic import op
 
 revision: str = "e1f2a3b4c5d6"
 down_revision: Union[str, None] = "d5f6a7b8c9d0"

backend/alembic/versions/e2f3a4b5c6d7_llm_provider_pregen_only.py

@@ -0,0 +1,59 @@
+"""feat: llm_providers 新增 pregen_only + 落 122b 预生成专用 provider(初始 disabled) (工单 #131)
+
+Revision ID: e2f3a4b5c6d7
+Revises: d1e2f3a4b5c6
+Create Date: 2026-09-17 00:20:00.000000
+
+设计:
+- pregen_only=true 的 provider 不进实时默认链(用户问答/时间解析), 不参与启动 warmup,
+  仅在调用方按 code 显式指定时置顶(报告预生成); 用于 qwen3.5:122b 这类慢而重的模型。
+- 同时插入 122b provider 行, **初始 enabled=false**:
+  模型 81GB 拉取约 4h, 拉取完成前 ollama 对缺失模型返 404(permanent, 不降级),
+  若启用会让每轮同步触发的预生成硬失败。拉完冒烟通过后由运维手动 enable + 绑模板。
+- base_url 走 talon-api(4080) 模型亲和调度: 122b 只装在 gmk-evo 节点, 会自动路由过去。
+- timeout_s=600(预生成放宽), retry_max=0(单次失败即降级常规链, 避免 2×10 分钟等待)。
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'e2f3a4b5c6d7'
+down_revision: Union[str, None] = 'd1e2f3a4b5c6'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        'llm_providers',
+        sa.Column(
+            'pregen_only',
+            sa.Boolean(),
+            nullable=False,
+            server_default=sa.false(),
+        ),
+    )
+    # 122b 预生成专用 provider(初始禁用, 待模型拉取验证后启用)
+    op.execute("""
+        INSERT INTO llm_providers
+            (code, name, base_url, model, priority, enabled, pregen_only, healthy,
+             thinking, timeout_s, retry_max, fail_threshold, fail_count,
+             note, created_by, updated_by, created_at, updated_at)
+        VALUES
+            ('talon-gmk-qwen3.5-122b',
+             'Talon·GMK·qwen3.5:122b(A10B/预生成专用)',
+             'http://192.168.10.21:4080/v1',
+             'qwen3.5:122b',
+             3, FALSE, TRUE, TRUE,
+             'disabled', 600.0, 0, 3, 0,
+             '#131 122B MoE A10B q4_K_M(81GB), 仅 gmk-evo 124GB 节点; 专供报告预生成, 拉取验证后启用',
+             'system', 'system', now(), now())
+        ON CONFLICT (code) DO NOTHING
+    """)
+
+
+def downgrade() -> None:
+    op.execute("DELETE FROM llm_providers WHERE code = 'talon-gmk-qwen3.5-122b'")
+    op.drop_column('llm_providers', 'pregen_only')

backend/alembic/versions/e3f4a5b6c7d8_seed_default_templates.py

@@ -0,0 +1,57 @@
+"""seed: 内置默认模板 日报/周报/月报 (工单 #124)
+
+Revision ID: e3f4a5b6c7d8
+Revises: d2e3f4a5b6c7
+Create Date: 2026-09-16 13:40:00.000000
+
+设计:
+- 3 条内置默认模板: daily_general_morning / weekly_compare_last / monthly_overview
+- 用 INSERT ... ON CONFLICT (code) DO NOTHING(幂等, 重复 upgrade 不报错)
+- is_active=true, visibility_scope=public
+- max_tokens: daily=2000, weekly=2500, monthly=3000
+- trigger_at: daily=09:00, weekly=1:09:00(周一9点), monthly=1:09:00(每月1号9点)
+- question_keywords JSONB 数组(用于 #122 匹配层关键词路由)
+"""
+from typing import Sequence, Union
+
+from alembic import op
+
+revision: str = 'e3f4a5b6c7d8'
+down_revision: Union[str, None] = 'd2e3f4a5b6c7'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # 幂等 INSERT: code 冲突时跳过(已 seed 不重置字段, 保留 admin 调整)
+    op.execute("""
+        INSERT INTO ai_report_templates
+            (code, name_cn, question_template, question_keywords,
+             period, frequency, trigger_at, sync_offset_min, priority,
+             llm_provider_code, fallback_template_id, max_tokens,
+             is_active, visibility_scope)
+        VALUES
+            ('daily_general_morning', '每日晨会·整体经营',
+             '今日经营总览, 含接待量/退款四路/投诉三源, 给出关键指标与异动提醒',
+             '["今天","今日","整体","总览","晨会","日报"]'::jsonb,
+             'daily', 'daily', '09:00', 5, 100,
+             NULL, NULL, 2000, true, 'public'),
+            ('weekly_compare_last', '周报·本周与上周对比',
+             '本周整体经营情况, 与上周对比, 给出环比变化与趋势分析',
+             '["本周","这周","周报","对比","上周","环比"]'::jsonb,
+             'weekly', 'weekly', '1:09:00', 5, 100,
+             NULL, NULL, 2500, true, 'public'),
+            ('monthly_overview', '月报·本月总览',
+             '本月经营情况总览, 含同比环比, 关键指标月度走势与下月建议',
+             '["本月","这个月","月报","上月","同比"]'::jsonb,
+             'monthly', 'monthly', '1:09:00', 5, 100,
+             NULL, NULL, 3000, true, 'public')
+        ON CONFLICT (code) DO NOTHING
+    """)
+
+
+def downgrade() -> None:
+    op.execute("""
+        DELETE FROM ai_report_templates
+        WHERE code IN ('daily_general_morning', 'weekly_compare_last', 'monthly_overview')
+    """)

backend/alembic/versions/e4f5a6b7c8d9_ai_reports_latest_missing.py

@@ -0,0 +1,42 @@
+"""ai_reports 加 latest_missing JSONB (工单 #153)
+
+AI 提示词反馈闭环「收集层」: 把 check_dimensions 的维度校验缺失清单落库,
+供周期「提示词健康报告」聚合(缺失维度 TopN → 直指 feed 供给缺口)。
+
+- latest_missing: JSONB 数组, 最近一次 standard 维度校验的缺失清单
+  (空数组 = 校验通过维度齐全; NULL = 尚未校验, 预生成快照在首次被
+  standard 校验/评审时回填)
+- 仅记录校验结果, 不覆盖 answer_md 等大字段
+
+Revision ID: e4f5a6b7c8d9
+Revises: a7b6c5d4e3f2
+Create Date: 2026-09-19
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+from alembic import op
+
+revision: str = 'e4f5a6b7c8d9'
+down_revision: Union[str, None] = 'a7b6c5d4e3f2'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "ai_reports",
+        sa.Column(
+            "latest_missing", postgresql.JSONB(astext_type=sa.Text()), nullable=True,
+            comment=(
+                "#153 最近一次 standard 维度校验的缺失清单(JSONB 数组, 空数组=维度齐全); "
+                "供提示词健康报告聚合缺失维度 TopN"
+            ),
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("ai_reports", "latest_missing")

backend/alembic/versions/e5f6a7b8c9d0_fix_specialty_lead_duplicates_and_stale_leads.py

@@ -0,0 +1,269 @@
+"""fix_specialty_lead_duplicates_and_stale_leads
+
+#90: 专项负责人硬编码遗留 + 历史表 is_current 重复 → 「唐彩慧/董梦玲 是负责人」
+
+## 问题（2026-09-14 用户反馈 + 生产实测）
+
+用户：「明明有清晰的负责人、组长划分，为什么会出现唐彩绘是负责人、
+董梦玲是负责人的说法？是不是有硬编码？」
+
+**是硬编码，且是三层叠加的缺陷**：
+
+### ① 硬编码人名（原罪）
+`scripts/init_groups_specialties.py` 把负责人**写死人名**：
+```python
+specialty_leaders = {
+    "complaint": "张蕾",
+    "refund_recovery": "唐彩慧",   # 用户已明确「他不是 lead」
+    "package": "朱海洋",
+    "consulting": "董梦玲",
+}
+```
+该脚本**无幂等守卫**，重复执行会直接覆盖 `specialties.current_lead_id`。
+
+### ② 生产指针未按用户决策收敛
+`scripts/apply_org_change_20260914.py` 的 `SPECIALTY_LEAD`（用户第三批决策
+「退款挽回 + 套餐 两专项组长都是吴晓龙」）**从未生效** —— 生产实测：
+
+| id | code | 专项 | current_lead_id | 人员 | 应有 |
+|---|---|---|---|---|---|
+| 3 | package | 套餐专项 | 151 | 朱海洋 | 吴晓龙 |
+| 4 | refund_recovery | 退款挽回 | 207 | 唐彩慧 | 吴晓龙 |
+| 1 | consulting | 咨询接待 | 146 | 董梦玲 | 保持/待确认 |
+
+### ③ 历史表 is_current 重复且无唯一约束（真正无法自愈的原因）
+```
+id | specialty | person   | is_current | source    | created
+3  | 套餐专项   | 朱海洋   | t          | migration | 08-09
+9  | 套餐专项   | 吴晓龙   | t          | manual    | 06:07
+7  | 套餐专项   | 吴晓龙   | t          | manual    | 06:40   ← 重复 2 条
+2  | 退款挽回   | 唐彩慧   | t          | migration | 08-09   ← 旧职未卸
+6  | 退款挽回   | 吴晓龙   | t          | manual    | 06:07
+8  | 退款挽回   | 吴晓龙   | t          | manual    | 06:40   ← 重复
+```
+两个独立 bug：
+- **卸任查询少维度**：`apply_org_change` 卸任时按
+  `(specialty_id, person_id, is_current)` 查 → 查「吴晓龙」查不到（他无旧岗）
+  → **旧 lead（唐彩慧/朱海洋）从未被卸任**；
+- **`__main__` 重复执行**：新任幂等守卫查 `(specialty_id, role, is_current).scalar()`
+  → 命中吴晓龙就 `continue`（正确），但因**首次执行时旧记录未被卸任**，
+  再次执行时该 query 返回**两条**(吴晓龙×2) → `scalar()` 报错或静默取一条，
+  且每次都 `db.add` 新行 → 同一 `(specialty, person, role)` 产生 multiple current。
+
+数据库**无** `UNIQUE (specialty_id, role) WHERE is_current` 部分唯一索引
+→ 重复行可静默写入（原索引 `ix_slh_spec_role_current` 是普通 btree 索引）。
+
+## 本迁移做三件事
+
+### 1. 收敛重复的 is_current（每个 (specialty_id, role) 只留一条）
+保留规则：`effective_from` 最大者；并列时取 `id` 最大者（最新创建）。
+其余置 `is_current=false` 并补 `effective_to`，同时写入 `change_reason` 以便追溯。
+
+### 2. 卸任陈旧 lead（用户已明确「不做该专项」）
+- `refund_recovery`：唐彩慧（207）卸任 —— 用户原文「唐彩绘是专职退款处理，
+  不做退款挽回，他不是 lead」
+- `package`：朱海洋（151）卸任 —— 用户第三批「套餐专项组长是吴晓龙」
+- 幂等：仅当指针**仍指向旧人**时才改，避免覆盖后续人工调整。
+
+### 3. 加部分唯一索引（防复发，本次核心）
+```sql
+CREATE UNIQUE INDEX uq_slh_spec_role_current
+  ON specialty_leadership_history (specialty_id, role) WHERE is_current;
+CREATE UNIQUE INDEX uq_glh_group_role_current
+  ON group_leadership_history (group_id, role) WHERE is_current;
+```
+此后**数据库层**拒绝第二条 current，重复行不可能再写入。
+
+⚠️ 注意：`internal_complaint`(id=2) 与 `external_complaint`(id=6) 的
+   `current_lead_id` 均为空 —— 该两专项已被 `complaint_merged` 合并，
+   空值是**正确终态**，本迁移不动。
+
+Revision ID: e5f6a7b8c9d0
+Revises: c4d5e6f7a8b9
+Create Date: 2026-09-14 18:00:00.000000
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "e5f6a7b8c9d0"
+down_revision: Union[str, None] = "c4d5e6f7a8b9"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+# 需卸任的陈旧 lead: (专项 code, 人员姓名, 卸任原因)
+STALE_LEADS = [
+    ("refund_recovery", "唐彩慧",
+     "2026-09-14 组织调整·卸任(用户: 唐彩慧是专职退款处理, 不做退款挽回, 不是 lead)"),
+    ("package", "朱海洋",
+     "2026-09-14 组织调整·卸任(用户: 套餐专项组长为吴晓龙)"),
+]
+
+# 用户决策应生效的 lead: (专项 code, 人员姓名)
+#   ⚠️ 来自 apply_org_change_20260914.py 的 SPECIALTY_LEAD（该脚本未生效）
+TARGET_LEADS = [
+    ("refund_recovery", "吴晓龙"),
+    ("package", "吴晓龙"),
+]
+
+
+def upgrade() -> None:
+    bind = op.get_bind()
+
+    # ── 1. 收敛重复 is_current ───────────────────────────────────────
+    # 每个 (specialty_id, role) 保留 effective_from 最大者（并列取 id 最大者）。
+    # 用窗口函数一次定位「应保留」的行, 其余置 false。
+    dup_rows = bind.execute(sa.text("""
+        SELECT id, specialty_id, role, person_id
+        FROM (
+            SELECT id, specialty_id, role, person_id,
+                   ROW_NUMBER() OVER (
+                       PARTITION BY specialty_id, role
+                       ORDER BY effective_from DESC, id DESC
+                   ) AS rn
+            FROM specialty_leadership_history
+            WHERE is_current
+        ) t
+        WHERE rn > 1
+    """)).fetchall()
+
+    for row in dup_rows:
+        bind.execute(sa.text("""
+            UPDATE specialty_leadership_history
+            SET is_current = false,
+                effective_to = COALESCE(effective_to, :to_date),
+                change_reason = COALESCE(change_reason, '') ||
+                    ' | #90 收敛重复 current(effective_from 非最大)'
+            WHERE id = :id
+        """), {"id": row[0], "to_date": _today(bind)})
+
+    # 行政组同表治理（同一缺陷形态）
+    dup_groups = bind.execute(sa.text("""
+        SELECT id
+        FROM (
+            SELECT id,
+                   ROW_NUMBER() OVER (
+                       PARTITION BY group_id, role
+                       ORDER BY effective_from DESC, id DESC
+                   ) AS rn
+            FROM group_leadership_history
+            WHERE is_current
+        ) t
+        WHERE rn > 1
+    """)).fetchall()
+
+    for row in dup_groups:
+        bind.execute(sa.text("""
+            UPDATE group_leadership_history
+            SET is_current = false,
+                effective_to = COALESCE(effective_to, :to_date),
+                change_reason = COALESCE(change_reason, '') ||
+                    ' | #90 收敛重复 current(effective_from 非最大)'
+            WHERE id = :id
+        """), {"id": row[0], "to_date": _today(bind)})
+
+    # ── 2. 卸任陈旧 lead + 补写应生效 lead ───────────────────────────
+    for code, pname, reason in STALE_LEADS:
+        spec = _find_specialty(bind, code)
+        person = _find_person(bind, pname)
+        if spec is None or person is None:
+            continue
+        # 幂等: 仅当指针**仍指向该旧人**时才卸任
+        cur_lead = bind.execute(sa.text(
+            "SELECT current_lead_id FROM specialties WHERE id = :sid"
+        ), {"sid": spec}).scalar()
+        if cur_lead != person:
+            continue
+        bind.execute(sa.text("""
+            UPDATE specialty_leadership_history
+            SET is_current = false,
+                effective_to = COALESCE(effective_to, :to_date),
+                change_reason = :reason
+            WHERE specialty_id = :sid AND person_id = :pid
+              AND role = 'lead' AND is_current
+        """), {"sid": spec, "pid": person, "to_date": _today(bind), "reason": reason})
+        # 指针暂置空（随后由 TARGET_LEADS 写入正确人）
+        bind.execute(sa.text(
+            "UPDATE specialties SET current_lead_id = NULL WHERE id = :sid"
+        ), {"sid": spec})
+
+    for code, pname in TARGET_LEADS:
+        spec = _find_specialty(bind, code)
+        person = _find_person(bind, pname)
+        if spec is None or person is None:
+            continue
+        cur_lead = bind.execute(sa.text(
+            "SELECT current_lead_id FROM specialties WHERE id = :sid"
+        ), {"sid": spec}).scalar()
+        if cur_lead == person:
+            continue   # 已是目标人 → 跳过（幂等）
+        # 若尚有其它 current lead, 一并卸任（保证唯一）
+        bind.execute(sa.text("""
+            UPDATE specialty_leadership_history
+            SET is_current = false,
+                effective_to = COALESCE(effective_to, :to_date),
+                change_reason = COALESCE(change_reason, '') || ' | #90 轮岗卸任'
+            WHERE specialty_id = :sid AND role = 'lead' AND is_current
+        """), {"sid": spec, "to_date": _today(bind)})
+        # 该人可能已有一条 current(=被上面的收敛保留的那条) → 复用, 避免重复
+        existing = bind.execute(sa.text("""
+            SELECT id FROM specialty_leadership_history
+            WHERE specialty_id = :sid AND person_id = :pid
+              AND role = 'lead' AND is_current
+        """), {"sid": spec, "pid": person}).scalar()
+        if existing is None:
+            bind.execute(sa.text("""
+                INSERT INTO specialty_leadership_history
+                    (specialty_id, person_id, role, effective_from, is_current,
+                     change_reason, source, created_at, updated_at)
+                VALUES (:sid, :pid, 'lead', :eff, true, :reason, 'manual',
+                        NOW(), NOW())
+            """), {"sid": spec, "pid": person, "eff": _eff_date(bind),
+                   "reason": "2026-09-14 组织架构调整（#90 补生效）"})
+        bind.execute(sa.text(
+            "UPDATE specialties SET current_lead_id = :pid WHERE id = :sid"
+        ), {"sid": spec, "pid": person})
+
+    # ── 3. 加部分唯一索引（防复发）────────────────────────────────────
+    # PostgreSQL 部分唯一索引: WHERE is_current → 每个 (spec, role) 最多一条 current
+    op.execute("""
+        CREATE UNIQUE INDEX IF NOT EXISTS uq_slh_spec_role_current
+        ON specialty_leadership_history (specialty_id, role)
+        WHERE is_current
+    """)
+    op.execute("""
+        CREATE UNIQUE INDEX IF NOT EXISTS uq_glh_group_role_current
+        ON group_leadership_history (group_id, role)
+        WHERE is_current
+    """)
+
+
+def downgrade() -> None:
+    op.execute("DROP INDEX IF EXISTS uq_glh_group_role_current")
+    op.execute("DROP INDEX IF EXISTS uq_slh_spec_role_current")
+    # 说明: 数据收敛/卸任**不自动回滚** —— 那是业务决策结果, 不是迁移副作用。
+    # 如需回退, 请走专项负责人轮岗接口人工操作, 保留完整审计轨迹。
+
+
+# ── helpers ──────────────────────────────────────────────────────────
+def _today(bind) -> str:
+    """当日日期（字符串）—— 用于 effective_to 兜底"""
+    return bind.execute(sa.text("SELECT CURRENT_DATE::text")).scalar()
+
+
+def _eff_date(bind) -> str:
+    """生效日期: 用户决策的组织调整生效日为 2026-09-01"""
+    return "2026-09-01"
+
+
+def _find_specialty(bind, code: str):
+    return bind.execute(sa.text(
+        "SELECT id FROM specialties WHERE code = :c ORDER BY id LIMIT 1"
+    ), {"c": code}).scalar()
+
+
+def _find_person(bind, name: str):
+    return bind.execute(sa.text(
+        "SELECT id FROM persons WHERE display_name = :n ORDER BY id LIMIT 1"
+    ), {"n": name}).scalar()

backend/alembic/versions/e5f6a7b8c9d1_llm_role_configs_table_seed_3_roles.py

@@ -0,0 +1,108 @@
+"""llm_role_configs 表 + seed 三角色（助理/专员/专家）
+
+背景（2026-09-21，见 docs/design/20260921-模型角色分组与出域管控设计.md §3.2）:
+
+  能力档位原先是 `llm_tiers.py` 里的 Python 常量，管理员无法在界面调整。
+  本迁移把**角色定义**落库（仅 3 行，存文案与角色级开关），
+  角色**成员**（哪些 provider 服务该角色、兜底顺序）存在 llm_providers 的
+  role_scope / role_order 两列上。
+
+  运行时选型: llm_tiers.resolve_tier() 优先读 DB；DB 无配置时回退源码常量
+  （保证首次部署即生效，见 llm_tiers.py 注释）。
+
+  为什么用「加两列 + 一张小表」而非规范化的关联表？
+    实测本集群模型能力差异明显且互斥（MoE 有数值缺陷、Dense 慢），
+    **一个模型服务多个角色的场景当前不存在**，且 provider 仅 5 个。
+    加关联表会引入 JOIN 复杂度而收益为零。若将来出现多角色需求，再迁移。
+
+seed 策略:
+  - 三角色的 display_name/description/rationale 取自 llm_tiers.py 的实测结论，
+    保证界面展示与源码一致（避免两处文案漂移）。
+  - allow_cloud 默认 **false**（保守）：角色级出域需管理员显式开启，
+    与全局 LLM_CLOUD_POLICY 形成双重管控（两者都为真才出域）。
+
+Revision ID: e5f6a7b8c9d1
+Revises: b1c2d3e4f5a6
+Create Date: 2026-09-21 09:26:00.000000
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = 'e5f6a7b8c9d1'
+down_revision: Union[str, None] = 'b1c2d3e4f5a6'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+# 三角色的文案与选型依据（与 app/services/llm_tiers.py 保持同步）
+_ROLES = [
+    {
+        "key": "assistant", "name": "助理", "order": 10,
+        "desc": "速度优先：分类打标 / 语义匹配 / 摘取排版 / 短摘要",
+        "rationale": (
+            "实测 coder-30b 语义匹配 6/6 全对、摘取数字全对，decode 78 t/s（快 3x）。"
+            "备选 7b 仅作降级 —— 注意它实测语义匹配 5/5 全错，不可作该类首选。"
+        ),
+    },
+    {
+        "key": "specialist", "name": "专员", "order": 20,
+        "desc": "平衡：实时问答 / 报告生成 / 结构化输出 / 治理研判",
+        "rationale": (
+            "实测 27b 数值聚合 4/4、语义 0.95（最稳），Dense 架构无 MoE 算术缺陷。"
+            "备选 coder-30b 快 3x，承接非数值降级场景。"
+        ),
+    },
+    {
+        "key": "expert", "name": "专家", "order": 30,
+        "desc": "质量优先：长文深度分析 / 跨数据关联 / 复杂推理 / 预生成",
+        "rationale": (
+            "实测 122b 数值 4/4、prefill 331 t/s（集群最快），长文唯一选择。"
+            "备选 27b 数值同样 4/4。"
+        ),
+    },
+]
+
+
+def upgrade() -> None:
+    op.create_table(
+        "llm_role_configs",
+        sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
+        sa.Column("role_key", sa.String(32), nullable=False,
+                  comment="角色键(assistant/specialist/expert)"),
+        sa.Column("display_name", sa.String(32), nullable=False, comment="显示名(助理/专员/专家)"),
+        sa.Column("description", sa.String(255), nullable=True, comment="用途说明(含典型任务)"),
+        sa.Column("rationale", sa.String(512), nullable=True,
+                  comment="选型依据(实测数据); 供界面展示"),
+        sa.Column("enabled", sa.Boolean(), nullable=False, server_default=sa.text("true"),
+                  comment="角色总开关; false 时该角色调用回退默认链"),
+        sa.Column("allow_cloud", sa.Boolean(), nullable=False, server_default=sa.text("false"),
+                  comment="该角色是否允许出域; 与全局 LLM_CLOUD_POLICY 双重管控"),
+        sa.Column("tier_order", sa.Integer(), nullable=False, server_default=sa.text("100"),
+                  comment="界面排序(小=前)"),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False,
+                  server_default=sa.text("now()")),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False,
+                  server_default=sa.text("now()")),
+    )
+    op.create_unique_constraint("uq_llm_role_configs_role_key", "llm_role_configs", ["role_key"])
+    op.create_index("ix_llm_role_configs_role_key", "llm_role_configs", ["role_key"])
+
+    # seed 三角色（幂等: ON CONFLICT DO NOTHING，重复执行不报错）
+    for r in _ROLES:
+        op.execute(sa.text("""
+            INSERT INTO llm_role_configs
+                (role_key, display_name, description, rationale,
+                 enabled, allow_cloud, tier_order)
+            VALUES (:k, :n, :d, :ra, true, false, :o)
+            ON CONFLICT (role_key) DO NOTHING
+        """).bindparams(k=r["key"], n=r["name"], d=r["desc"], ra=r["rationale"], o=r["order"]))
+
+
+def downgrade() -> None:
+    op.drop_index("ix_llm_role_configs_role_key", table_name="llm_role_configs")
+    op.drop_constraint("uq_llm_role_configs_role_key", "llm_role_configs", type_="unique")
+    op.drop_table("llm_role_configs")

backend/alembic/versions/e6f7a8b9c0d2_add_prompt_config_change_reason.py

@@ -0,0 +1,48 @@
+"""提示词版本补充变更依据字段 change_reason/references (工单 #178)
+
+为 prompt_configs 增加「为什么改/解决什么问题」(change_reason) 与
+「参考依据来源」(references) 两个字段，使版本账本可溯（评估中心建议/
+用户评价/意见工单/文档链接等来源），解决人工意见与版本管理做闭环时
+缺少「依据」落点的问题。
+
+幂等：列已存在（本地 create_all 环境可能已建）则跳过，不报错；
+适配 Alembic 与 Base.metadata.create_all 并存的升级规范。
+
+Revision ID: e6f7a8b9c0d2
+Revises: d4e5f6a7b8c0
+Create Date: 2026-09-23
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'e6f7a8b9c0d2'
+down_revision: Union[str, None] = 'd4e5f6a7b8c0'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def _has_column(table: str, column: str) -> bool:
+    bind = op.get_bind()
+    insp = sa.inspect(bind)
+    return any(c["name"] == column for c in insp.get_columns(table))
+
+
+def upgrade() -> None:
+    for col, comment in (
+        ("change_reason", "本版迭代依据：解决什么问题/为何改（新建版本时人工填写）"),
+        ("references", "本版参考依据：评估中心建议/用户评价/意见工单/文档链接等来源"),
+    ):
+        if not _has_column("prompt_configs", col):
+            op.add_column(
+                "prompt_configs",
+                sa.Column(col, sa.Text(), nullable=True, comment=comment),
+            )
+
+
+def downgrade() -> None:
+    for col in ("references", "change_reason"):
+        if _has_column("prompt_configs", col):
+            op.drop_column("prompt_configs", col)

backend/alembic/versions/e7a1b3c4d5e6_add_operation_logs.py

@@ -9,9 +9,9 @@ Create Date: 2026-07-26 23:50:00.000000
 """
 from typing import Sequence, Union
 
-from alembic import op
 import sqlalchemy as sa
 
+from alembic import op
 
 revision: str = 'e7a1b3c4d5e6'
 down_revision: Union[str, None] = 'c5d0e2a13f6b'

backend/alembic/versions/e7f8a9b0c1d2_issue319_move_source_tables_to_ods.py

@@ -0,0 +1,69 @@
+"""#319 数据分层 M2: 21 张信源表从 public 移入 ods schema
+
+表清单(与模型 __table_args__ {"schema": "ods"} 一一对应):
+  退款/订单:  bms_orders, refunds, manual_refunds, merchant_refunds,
+              shanmao_refunds, refund_record_reports, wallet_withdrawals
+  设备/套餐:  device_combos, device_flow_usage
+  投诉/客服:  card_complaints, external_complaints, cs_records
+  SCRM:       scrm_sessions, scrm_session_transfers, scrm_operators, scrm_staff_profiles
+  其他信源:   return_trackings, wechat_registrations, wechat_accounts,
+              dept_info_syncs, attendance
+
+实现要点:
+- ALTER TABLE ... SET SCHEMA 是目录级元数据操作, 不搬数据, 秒级完成;
+  索引/约束/序列/触发器随表一起迁移, 无需重建。
+- public.<t> 上若有视图/物化视图依赖会被 PG 拒绝 —— 经清点 21 表均无视图依赖。
+- 外键约束(含跨 schema 指向 ods 的 3 处: complaint_same_source_members.complaint_id /
+  scrm_session_transfers.session_id / reconcile_matches.report_id)在 SET SCHEMA 后
+  自动指向新位置, 无需重建。
+- downgrade 反向移回 public, 逐表对称。
+
+Revision ID: e7f8a9b0c1d2
+Revises: d6e7f8a9b0c1
+Create Date: 2026-10-13 10:05:00.000000
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "e7f8a9b0c1d2"
+down_revision: str = "d6e7f8a9b0c1"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+# 21 张信源表(顺序无关, SET SCHEMA 互不影响)
+ODS_TABLES: tuple[str, ...] = (
+    "bms_orders",
+    "device_combos",
+    "refunds",
+    "manual_refunds",
+    "merchant_refunds",
+    "shanmao_refunds",
+    "refund_record_reports",
+    "card_complaints",
+    "external_complaints",
+    "cs_records",
+    "scrm_sessions",
+    "scrm_session_transfers",
+    "scrm_operators",
+    "scrm_staff_profiles",
+    "wallet_withdrawals",
+    "device_flow_usage",
+    "return_trackings",
+    "wechat_registrations",
+    "wechat_accounts",
+    "dept_info_syncs",
+    "attendance",
+)
+
+
+def upgrade() -> None:
+    for table in ODS_TABLES:
+        op.execute(f"ALTER TABLE public.{table} SET SCHEMA ods")
+
+
+def downgrade() -> None:
+    for table in ODS_TABLES:
+        op.execute(f"ALTER TABLE ods.{table} SET SCHEMA public")

backend/alembic/versions/e8d7c6b5a4f3_add_prompt_configs.py

@@ -0,0 +1,124 @@
+"""提示词版本化配置表 prompt_configs (工单 #178)
+
+设计: #178 B（两级提示词 DB 化 + 版本化）
+
+两级提示词（生成侧 _SYSTEM_PROMPT / 摘取侧 _EXTRACT_SYSTEM）从代码常量升级为
+DB 可迭代 + 版本化：代码常量保留为兜底默认（提示词铁律），DB 行只有
+`is_active=TRUE` 时才生效。
+
+⚠️ seed 策略（零回归关键）：
+- seed 两行（gen_system / extract_system）**is_active=FALSE** —— 初始不激活，
+  加载侧「DB 无生效行 → 回退代码常量」，升级后行为与现状完全一致；
+- 管理员经版本管理激活新版本后才 DB 优先，且旧版本行保留可回滚。
+
+⚠️ revision id 说明：初版误用 a1b2c3d4e5f6（与 add_shanmao_phone_paid_amount 撞车），
+  换为 e8d7c6b5a4f3（已 grep 全 versions 确认唯一）。
+
+Revision ID: e8d7c6b5a4f3
+Revises: s9t0u1v2w3x4
+Create Date: 2026-09-21
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'e8d7c6b5a4f3'
+down_revision: Union[str, None] = 's9t0u1v2w3x4'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'prompt_configs',
+        sa.Column('id', sa.BigInteger(), autoincrement=True, nullable=False),
+        sa.Column('code', sa.String(length=64), nullable=False,
+                  comment='提示词标识（gen_system=生成侧 / extract_system=摘取侧）'),
+        sa.Column('name_cn', sa.String(length=128), nullable=False, comment='显示名'),
+        sa.Column('content', sa.Text(), nullable=False, comment='提示词正文'),
+        sa.Column('version', sa.Integer(), nullable=False, server_default='1',
+                  comment='版本号（每次迭代递增；旧版本行保留可回滚）'),
+        sa.Column('is_active', sa.Boolean(), nullable=False, server_default=sa.text('false'),
+                  comment='生效标记；TRUE=当前生效版本（每 code 至多一个），FALSE=历史/草稿版本'),
+        sa.Column('baseline', sa.String(length=255), nullable=True,
+                  comment='激活时基线指标（命中率/live 占比，金丝雀验证回填）'),
+        sa.Column('created_by', sa.Integer(), nullable=True, comment='创建人 user_id'),
+        sa.Column('activated_at', sa.DateTime(timezone=True), nullable=True, comment='激活时刻'),
+        sa.Column('activated_by', sa.Integer(), nullable=True, comment='激活人 user_id'),
+        sa.Column('created_at', sa.DateTime(timezone=True), nullable=False,
+                  server_default=sa.text('now()'), comment='创建时刻'),
+        sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False,
+                  server_default=sa.text('now()'), comment='更新时间'),
+        sa.PrimaryKeyConstraint('id'),
+        sa.Index('ix_prompt_configs_code', 'code'),
+        # 同一 code 至多一个生效版本（部分唯一索引，与模型 Index 镜像）
+        sa.Index('uq_prompt_configs_active_code', 'code', unique=True,
+                 postgresql_where=sa.text('is_active')),
+    )
+
+    # seed 初始版本（is_active=FALSE → 不生效，加载回退代码常量，零回归）
+    # 内容 = 当前代码常量快照，仅作初始版本留痕；管理员激活后才 DB 优先
+    _gen_seed = (
+        "你是本客服/经营系统的数据分析助手。你的职责是基于【给定数据】回答经营/退款/投诉/接待问题。\n"
+        "铁律:\n"
+        "1. 所有数字必须来自【给定数据】, 严禁编造、外推或臆测; 数据中没有的写\"暂无/未提供\"。\n"
+        "2. 严格按【业务口径】理解指标, 不要自创定义。\n"
+        "3. 回答中文, 结论注明数据窗口(如 今日/本周/本月 截至时间)。\n"
+        "   **结构要求**: 周报/月报**必须**按 H2 锚点结构化输出, 锚点固定为 "
+        "`## 接待分析` / `## 退款分析` / `## 投诉分析` / `## 趋势对比` / `## 结论建议`"
+        "(无数据的段写\"暂无\", 不要省略锚点); 日报保持简洁, 不强制 H2。\n"
+        "   **长度约束**: 前台实时问答 ≤500 字(突出核心结论, 不展开逐项明细; 超长会被截断); "
+        "后台预生成草稿(数据窗口说明含\"预生成\"字样时)可详尽展开, 不受此限。\n"
+        "4. 只回答与经营数据相关的问题; 无关问题礼貌说明无法回答。\n"
+        "5. 金额一律以元为单位。\n"
+        "6. **回答开头必须写明本次统计窗口**(直接引用【数据窗口说明】里的起止时间), 让用户能核对窗口"
+        "是否符合预期; 若用户问的时间范围与给定窗口不一致, 先指出差异再作答, 不要默默按别的窗口回答。\n"
+        "7. 给定数据里的 yoy_value/yoy_pct 是\"前一个等长周期\"的对比值, **不是另一天的独立明细**; "
+        "不要把它当成完整的一天数据来陈述。若用户要某天的明细而该窗口未提供, 如实说明。\n"
+        "8. **防主观推断**: 不同口径的数字(如 registered=窗口内新登记 vs handled=窗口内完成含历史单)"
+        "禁止直接相减或比较大小; 必须显式标注口径差异后再下结论。"
+        "禁止做\"处理量 > 登记量 → 消化存量\"这类无证据因果推断; "
+        "数据未提供的归因(如\"退款上升因 XX 活动\")禁止编造, 一律写\"原因需结合运营侧确认\"。\n"
+        "9. **业务判定方向**: 退款(金额/笔数/均单价)越少越好; 接待量与会话数越多越好; "
+        "投诉越少越好, 严重性 外部投诉 > 商户号投诉 > 内部投诉(外部 1 件 > 商户号 10 件); "
+        "退款挽回率越高越好; 积压投诉越低越好。陈述\"环比涨跌\"后必须按此基准标注\"利好/利空\", "
+        "不得只报数字不评判。\n"
+        "10. **工作时间**: 客服工作时间 08:00~23:59; 非工作时间(00:00~07:59)由 AI 协助处理。"
+        "解读\"接待量为 0 / 完工单为 0\"时, 必须先核对窗口是否落在非工作时间, "
+        "不得直接判定\"无人值班\"或\"系统故障\"。AI 接管率上升=利好(可控指标前置)。"
+    )
+    _extract_seed = (
+        "你是经营数据分析摘取助手。基于给定的草稿段落, 按问句摘取相关部分并排版输出。\n"
+        "铁律:\n"
+        "1. 只能从【给定段落】中摘取, 严禁编造、外推或添加未在段落中出现的数据。\n"
+        "2. 严格按问句意图排版: 简要问给简要答, 详细问给详细答(可保留段落内明细与表格)。\n"
+        "3. 段落内 `**<维度>**：` 是维度锚点行(如 `**四路分布**：A 线上直退 23 笔`); "
+        "问句指向某维度时, 优先摘取该锚点行及其后内容, 锚点行写\"暂无/未提供\"时如实保留, "
+        "不要从旁述/建议句里拼凑该维度的数据。\n"
+        "4. 回答中文, 开头注明数据窗口(直接引用段落里出现的窗口说明)。\n"
+        "5. 段落里没有的部分如实写\"未提供\", 不要从段落外内容补充。\n"
+        "6. 金额单位保持与段落一致(元/分), 不要转换。"
+    )
+    op.bulk_insert(
+        sa.table(
+            'prompt_configs',
+            sa.column('code', sa.String(64)),
+            sa.column('name_cn', sa.String(128)),
+            sa.column('content', sa.Text()),
+            sa.column('version', sa.Integer()),
+            sa.column('is_active', sa.Boolean()),
+            sa.column('created_by', sa.Integer()),
+        ),
+        [
+            {'code': 'gen_system', 'name_cn': '生成侧·System 铁律',
+             'content': _gen_seed, 'version': 1, 'is_active': False, 'created_by': None},
+            {'code': 'extract_system', 'name_cn': '摘取侧·System 提示词',
+             'content': _extract_seed, 'version': 1, 'is_active': False, 'created_by': None},
+        ],
+    )
+
+
+def downgrade() -> None:
+    op.drop_table('prompt_configs')

backend/alembic/versions/f0a1b2c3d4e5_add_integration_profiles.py

@@ -0,0 +1,116 @@
+"""add integration_profiles table (#44)
+
+Revision ID: f0a1b2c3d4e5
+Revises: e9f0a1b2c3d4
+Create Date: 2026-09-10 19:00:00.000000
+
+背景(#44, A-20260910-002 LOCKED v1.0):
+  调用方(WorkBuddy 等)接入需要「提示词 + 字段规范 + 接口说明」一整套物料,
+  此前散落在代码常量与 Markdown 文档里, 改一次要发版。
+  本表把配置包模板 DB 化, 管理员可在「接入中心」直接维护。
+
+新增表 `integration_profiles`:
+  code         String(48)  唯一   模板标识
+  name         String(64)         显示名
+  scene        String(24)  索引   场景 push/pull/manual_refund
+  content_md   Text               Markdown 模板(含 {{变量}})
+  variables    JSONB              变量声明 [{key,label,required}]
+  enabled      Boolean            停用后不在列表出现
+  sort_order   Integer            排序
+  created_by / updated_by / created_at / updated_at
+
+种子: 3 个默认场景(投诉推送/手动退款推送/经营日报拉取), 内容取
+services/integration_profile_service._SEED_PROFILES 常量(单一事实来源)。
+**已存在则跳过**, 不覆盖用户改动(遵循审计项 C-P2-2)。
+
+⚠️ 纯新增表, 对既有表/接口零影响。
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+from alembic import op
+
+revision: str = 'f0a1b2c3d4e5'
+down_revision: Union[str, None] = 'e9f0a1b2c3d4'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+_TABLE = 'integration_profiles'
+
+
+def _table_exists(table_name: str) -> bool:
+    """表存在性检查(幂等升级规范: create_all 环境可能已建表)。"""
+    bind = op.get_bind()
+    sql = sa.text(
+        "SELECT 1 FROM information_schema.tables "
+        "WHERE table_schema='public' AND table_name=:t"
+    )
+    return bind.execute(sql, {"t": table_name}).scalar() is not None
+
+
+def upgrade() -> None:
+    if not _table_exists(_TABLE):
+        op.create_table(
+            _TABLE,
+            sa.Column('id', sa.BigInteger(), autoincrement=True, nullable=False),
+            sa.Column('code', sa.String(length=48), nullable=False, comment='唯一标识(如 workbuddy-complaint-push)'),
+            sa.Column('name', sa.String(length=64), nullable=False, comment='显示名'),
+            sa.Column('scene', sa.String(length=24), nullable=False, comment='场景: push/pull/manual_refund'),
+            sa.Column('content_md', sa.Text(), nullable=False, comment='Markdown 模板(含 {{变量}})'),
+            sa.Column('variables', postgresql.JSONB(astext_type=sa.Text()), nullable=True,
+                      comment='变量声明: [{"key":"doc_url","label":"共享文档地址","required":true}]'),
+            sa.Column('enabled', sa.Boolean(), nullable=False, server_default=sa.text('true'), comment='停用后不在列表出现'),
+            sa.Column('sort_order', sa.Integer(), nullable=False, server_default=sa.text('0'), comment='排序(小在前)'),
+            sa.Column('created_by', sa.String(length=64), nullable=True, comment='创建人'),
+            sa.Column('updated_by', sa.String(length=64), nullable=True, comment='最后更新人'),
+            sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+            sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+            sa.PrimaryKeyConstraint('id'),
+        )
+        op.create_index('ix_integration_profiles_code', _TABLE, ['code'], unique=True)
+        op.create_index('ix_integration_profiles_scene', _TABLE, ['scene'], unique=False)
+
+    _seed_default_profiles()
+
+
+def _seed_default_profiles() -> None:
+    """幂等灌入默认模板(**已存在则跳过, 不覆盖用户改动**)。
+
+    内容来自服务层常量, 避免 migration 与服务层两份文本漂移。
+    """
+    try:
+        from app.services.integration_profile_service import _SEED_PROFILES
+    except Exception:  # noqa: BLE001  migration 环境无 app 包时跳过 seed
+        return
+
+    bind = op.get_bind()
+    for item in _SEED_PROFILES:
+        exists = bind.execute(
+            sa.text(f"SELECT 1 FROM {_TABLE} WHERE code = :c"), {"c": item["code"]}
+        ).scalar()
+        if exists:
+            continue
+        bind.execute(
+            sa.text(
+                f"INSERT INTO {_TABLE} "
+                "(code, name, scene, content_md, variables, enabled, sort_order, created_by, updated_by) "
+                "VALUES (:code, :name, :scene, :content_md, CAST(:variables AS jsonb), true, :sort_order, 'system', 'system')"
+            ),
+            {
+                "code": item["code"],
+                "name": item["name"],
+                "scene": item["scene"],
+                "content_md": item["content_md"],
+                "variables": __import__("json").dumps(item.get("variables") or [], ensure_ascii=False),
+                "sort_order": item.get("sort_order", 0),
+            },
+        )
+
+
+def downgrade() -> None:
+    if _table_exists(_TABLE):
+        op.drop_index('ix_integration_profiles_scene', table_name=_TABLE)
+        op.drop_index('ix_integration_profiles_code', table_name=_TABLE)
+        op.drop_table(_TABLE)

backend/alembic/versions/f0e1d2c3b4a5_create_manual_refunds.py

@@ -22,9 +22,10 @@ Create Date: 2026-08-23
 """
 from typing import Sequence, Union
 
-from alembic import op
 import sqlalchemy as sa
 
+from alembic import op
+
 # revision identifiers, used by Alembic.
 revision: str = 'f0e1d2c3b4a5'
 down_revision: Union[str, None] = 'e1f2a3b4c5d6'

backend/alembic/versions/f1e2d3c4b5a6_add_manual_refund_quality.py

@@ -10,9 +10,10 @@ Create Date: 2026-08-23
 """
 from typing import Sequence, Union
 
-from alembic import op
 import sqlalchemy as sa
 
+from alembic import op
+
 # revision identifiers, used by Alembic.
 revision: str = 'f1e2d3c4b5a6'
 down_revision: Union[str, None] = 'f0e1d2c3b4a5'

backend/alembic/versions/f1g2h3i4j5k6_add_onboarding_prompts.py

@@ -0,0 +1,101 @@
+"""onboarding_prompts 起草提示词配置表 (工单 #156)
+
+AI 数据接入助手「AI 起草层」提示词落库（#153 反馈闭环思路）：
+- 修改起草提示词不需要发版，直接改 DB 即生效；
+- code 唯一标识一份提示词（draft_system / draft_user），version 留痕便于追溯回滚；
+- 规范原文段不落库（由代码按常量生成注入），本表只存提示词骨架与铁律。
+
+本迁移建表 + 幂等 seed v1 两条提示词（重复 upgrade 不报错，不覆盖 admin 修改）。
+
+Revision ID: f1g2h3i4j5k6
+Revises: c6d7e8f9a0b1
+Create Date: 2026-09-19
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import insert
+
+from alembic import op
+
+revision: str = 'f1g2h3i4j5k6'
+down_revision: Union[str, None] = 'c6d7e8f9a0b1'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+# 起草提示词 v1 内容（含 {spec_rules}/{output_schema} 等占位符, 由起草服务格式化注入）。
+# 用 Python 参数化插入替代手写 SQL: 内容含换行与中文引号, 原样 SQL 字面量拼接易错。
+_DRAFT_SYSTEM_V1 = (
+    "你是「数据源接入助手」。用户会给你一份业务数据样例（已脱敏，含表头与若干行数据）"
+    "与业务提示，请把它翻译成符合本项目规范的「数据源接入声明」。\n"
+    "\n【项目规范原文（必须逐条遵守）】\n{spec_rules}\n"
+    "\n【输出 JSON 结构】\n{output_schema}\n"
+    "\n【铁律】\n"
+    "1. 只做语义推断，不做业务断言（禁止编造「这是对账基准」之类结论）。\n"
+    "2. 金额列一律判 semantic_role 为 amount 且 unit 为「分」；拿不准时 confidence 给小于 0.7 而非硬猜。\n"
+    "3. code 用英文蛇形命名（如 bms_order）；name_cn 用中文业务词且必须带域前缀（前缀·中文名）。\n"
+    "4. 时间列判 semantic_role 为 time 并给出 time_zone_note（默认 Asia/Shanghai）；SN 列判 sn。\n"
+    "5. dedup_recommendation 必须给出依据并置 requires_human_confirm 为 true（去重键是红线，AI 永不自决）。\n"
+    "6. 拿不准语义的列进 unknown_fields，不进 field_specs 硬猜。"
+)
+_DRAFT_USER_V1 = (
+    "【业务提示】\n"
+    "- 表名/来源提示：{table_hint}\n"
+    "- 业务背景：{business_note}\n"
+    "\n【样例数据（已脱敏，共 {row_count} 行）】\n{samples}\n"
+    "\n请按系统提示词要求，只输出 JSON 接入声明，禁止任何解释文字或 markdown 代码块标记。"
+)
+
+
+def upgrade() -> None:
+    op.create_table(
+        "onboarding_prompts",
+        sa.Column("id", sa.BigInteger(), autoincrement=True, primary_key=True),
+        sa.Column("code", sa.String(length=64), nullable=False),
+        sa.Column("name_cn", sa.String(length=128), nullable=False),
+        sa.Column("content", sa.Text(), nullable=False),
+        sa.Column("version", sa.Integer(), nullable=False, server_default="1"),
+        sa.Column("is_active", sa.Boolean(), nullable=False, server_default=sa.text("true")),
+        sa.Column("created_by", sa.BigInteger(), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.UniqueConstraint("code", name="uq_onboarding_prompts_code"),
+    )
+    op.create_index("ix_onboarding_prompts_code", "onboarding_prompts", ["code"], unique=True)
+
+    # 幂等 seed v1（ON CONFLICT DO NOTHING: 重复 upgrade 不报错, 不覆盖 admin 后续调整）
+    onboarding_prompts = sa.table(
+        "onboarding_prompts",
+        sa.column("code", sa.String),
+        sa.column("name_cn", sa.String),
+        sa.column("content", sa.Text),
+        sa.column("version", sa.Integer),
+        sa.column("is_active", sa.Boolean),
+    )
+    op.execute(
+        insert(onboarding_prompts)
+        .values(
+            [
+                {
+                    "code": "draft_system",
+                    "name_cn": "起草·系统提示（角色+铁律+输出结构）",
+                    "content": _DRAFT_SYSTEM_V1,
+                    "version": 1,
+                    "is_active": True,
+                },
+                {
+                    "code": "draft_user",
+                    "name_cn": "起草·用户提示（样例注入）",
+                    "content": _DRAFT_USER_V1,
+                    "version": 1,
+                    "is_active": True,
+                },
+            ]
+        )
+        .on_conflict_do_nothing(index_elements=["code"])
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_onboarding_prompts_code", table_name="onboarding_prompts")
+    op.drop_table("onboarding_prompts")

backend/alembic/versions/f299_combo_backfill_slices.py

@@ -0,0 +1,53 @@
+"""combo_backfill_slices: device_combo 历史回补断点台账 (#299)
+
+Revision ID: f299combo
+Revises: e1_renew_probe_at
+Create Date: 2026-10-11
+
+设备套餐历史切片回补(#299): 按北京业务日记录每个导出切片的执行状态,
+支持分夜断点续跑 / 触顶折半(split) / 失败次夜重试。纯新增台账表,
+不触碰 device_combos 业务表, 零风险。
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'f299combo'
+down_revision: Union[str, None] = 'e1_renew_probe_at'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'combo_backfill_slices',
+        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column('start_date', sa.Date(), nullable=False, comment='切片起始北京业务日'),
+        sa.Column('end_date', sa.Date(), nullable=False, comment='切片结束北京业务日(含)'),
+        sa.Column('status', sa.String(length=16), nullable=False, comment='pending/running/success/empty/failed/split'),
+        sa.Column('total_rows', sa.Integer(), nullable=True, comment='导出总行数(触顶判据)'),
+        sa.Column('inserted_rows', sa.Integer(), nullable=True, comment='upsert 新增行数'),
+        sa.Column('updated_rows', sa.Integer(), nullable=True, comment='upsert 更新行数'),
+        sa.Column('failed_rows', sa.Integer(), nullable=True, comment='解析失败行数'),
+        sa.Column('attempts', sa.Integer(), nullable=False, server_default='0', comment='累计尝试次数'),
+        sa.Column('last_error', sa.Text(), nullable=True, comment='最近一次失败原因(截断)'),
+        sa.Column('triggered_by', sa.String(length=32), nullable=True, comment='scheduled/manual'),
+        sa.Column('started_at', sa.DateTime(timezone=True), nullable=True),
+        sa.Column('finished_at', sa.DateTime(timezone=True), nullable=True),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+        sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+        sa.PrimaryKeyConstraint('id', name=op.f('combo_backfill_slices_pkey')),
+        sa.UniqueConstraint('start_date', 'end_date', name='uq_combo_backfill_slice_range'),
+    )
+    op.create_index(op.f('ix_combo_backfill_slices_start_date'), 'combo_backfill_slices', ['start_date'])
+    op.create_index(op.f('ix_combo_backfill_slices_end_date'), 'combo_backfill_slices', ['end_date'])
+    op.create_index(op.f('ix_combo_backfill_slices_status'), 'combo_backfill_slices', ['status'])
+
+
+def downgrade() -> None:
+    op.drop_index(op.f('ix_combo_backfill_slices_status'), table_name='combo_backfill_slices')
+    op.drop_index(op.f('ix_combo_backfill_slices_end_date'), table_name='combo_backfill_slices')
+    op.drop_index(op.f('ix_combo_backfill_slices_start_date'), table_name='combo_backfill_slices')
+    op.drop_table('combo_backfill_slices')

backend/alembic/versions/f2e3d4c5b6a7_switch_manual_refund_dedup_index.py

@@ -10,9 +10,10 @@ Create Date: 2026-08-23
 """
 from typing import Sequence, Union
 
-from alembic import op
 import sqlalchemy as sa
 
+from alembic import op
+
 # revision identifiers, used by Alembic.
 revision: str = 'f2e3d4c5b6a7'
 down_revision: Union[str, None] = 'f1e2d3c4b5a6'