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,10 +38,42 @@ 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
+
 # ---------- 上传 ----------
-# 后端进程内读写路径(相对容器工作目录 /app)。生产部署时由 docker-compose 挂载变量覆盖:
-# 在 deploy/env.production.example 里设 UPLOAD_DIR=/opt/csctalon/uploads 等绝对路径并随 compose 挂载,
-# 这里保持默认即可。⚠️ 统一用单数 UPLOAD_DIR/BROWSER_STATE_DIR(与后端代码 settings 同名),
+# 本地开发默认值 = 容器内相对路径(配合 compose 默认挂载 ./uploads:/app/uploads)。
+# ⚠️ docker-compose.yml backend environment 已显式注入容器内路径
+#    UPLOAD_DIR=/app/uploads / BROWSER_STATE_DIR=/app/data/browser_states(覆盖 env_file 值),
+#    故 .env 里的 UPLOAD_DIR 仅作 **compose 宿主机挂载源**(生产在 env.production.example 设
+#    /opt/csctalon/uploads 等宿主绝对路径), 不再是容器内读写路径(2026-09-06 修复路径错位)。
+# ⚠️ 统一用单数 UPLOAD_DIR/BROWSER_STATE_DIR(与后端代码 settings 同名),
 # 勿再用复数 UPLOADS_DIR/BROWSER_STATES_DIR(2026-08-30 已废弃, 配错会导致路径错配)。
 UPLOAD_DIR=./uploads
 MAX_UPLOAD_SIZE_MB=200

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

@@ -0,0 +1,99 @@
+# Gitea Actions: 合并后工单状态自动流转 (G3)
+#
+# 对应锁定设计 docs/arch/A-20260903-001-issue-automation-gates.md §2.3
+# 规则:
+#   - PR 合并(closed 且 merged)后, 从标题/描述解析 #<issue号>
+#   - incident 事故单不自动关闭(必须人工结案)
+#   - 其他类型: 若无剩余未关闭子工单则置 Closed, 否则仅评论
+# 注: 内网 runner, 纯 shell + curl + Gitea API。
+
+name: issue-close-on-merge
+
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  close-issue:
+    if: github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    steps:
+      - name: 解析工单号并流转状态
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          PR_BODY: ${{ github.event.pull_request.body }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_HTML_URL: ${{ github.event.pull_request.html_url }}
+          GITEA_TOKEN: ${{ secrets.GITEATOKEN }}
+        run: |
+          set -e
+          title="${PR_TITLE:-}"
+          body="${PR_BODY:-}"
+          num="${PR_NUMBER:-}"
+          html="${PR_HTML_URL:-}"
+          api="http://127.0.0.1:3000/api/v1/repos/tanzk/csctalon"
+
+          # 从标题+描述提取所有 #数字, 取第一个作为主工单
+          issue_no=$(printf '%s\n%s\n' "$title" "$body" | grep -Eo '#[0-9]+' | head -1 | tr -d '#')
+          if [ -z "$issue_no" ]; then
+            echo "⚠️ 未解析到工单号, 跳过状态流转"
+            exit 0
+          fi
+
+          echo "== 关联工单 #${issue_no} =="
+
+          # 读取工单标签, 判断是否为 incident (单行 python, 避免 YAML block 缩进破坏)
+          labels=$(curl -s -H "Authorization: token ${GITEA_TOKEN}" "$api/issues/${issue_no}/labels" | python3 -c "import sys,json; print(','.join(x.get('name','') for x in json.load(sys.stdin)))" 2>/dev/null || true)
+          echo "labels = $labels"
+
+          comment="✅ 已由 PR #${num} 合并交付：${html}"
+
+          if echo "$labels" | grep -q 'incident'; then
+            echo "⏸ incident 事故单, 不自动关闭(需人工结案), 仅追加评论"
+            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")" \
+              "$api/issues/${issue_no}/comments" > /dev/null
+            exit 0
+          fi
+
+          # 读取当前工单状态 (单行 python)
+          state=$(curl -s -H "Authorization: token ${GITEA_TOKEN}" "$api/issues/${issue_no}" | python3 -c "import sys,json; print(json.load(sys.stdin).get('state',''))" 2>/dev/null || true)
+          echo "current state = $state"
+
+          # 若已关闭, 只追加评论
+          if [ "$state" = "closed" ]; then
+            echo "工单已关闭, 仅追加评论"
+            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")" \
+              "$api/issues/${issue_no}/comments" > /dev/null
+            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}" \
+            -H "Content-Type: application/json" \
+            -d "$(python3 -c "import json,sys; print(json.dumps({'body': sys.argv[1]}))" "$comment")" \
+            "$api/issues/${issue_no}/comments" > /dev/null
+          curl -s -X PATCH -H "Authorization: token ${GITEA_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d '{"state":"closed"}' \
+            "$api/issues/${issue_no}" > /dev/null
+          echo "done"

.gitea/workflows/issue-gate.yml

@@ -0,0 +1,64 @@
+# Gitea Actions: PR 工单号门禁 (G1)
+#
+# 对应锁定设计 docs/arch/A-20260903-001-issue-automation-gates.md §2.1
+# 规则:
+#   - PR 标题或描述必须包含 #<数字>(如 #2), 否则 CI fail
+#   - 豁免: 变更文件全部为 docs/*.md 或根 *.md 的纯文档 PR
+# 注: 本 runner 内网, 禁用 GitHub action, 纯 shell + curl 实现。
+
+name: issue-gate
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 校验 PR 关联工单号
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          PR_BODY: ${{ github.event.pull_request.body }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          GITEA_TOKEN: ${{ secrets.GITEATOKEN }}
+        run: |
+          set -e
+          title="${PR_TITLE:-}"
+          body="${PR_BODY:-}"
+          num="${PR_NUMBER:-}"
+
+          echo "== PR #${num} 标题/描述 =="
+          printf '%s\n' "$title"
+          printf '%s\n' "$body"
+
+          # 1) 标题或描述含 #数字 即通过
+          if printf '%s\n%s\n' "$title" "$body" | grep -Eq '#[0-9]+'; then
+            echo "✅ 已关联工单号, 门禁通过"
+            exit 0
+          fi
+
+          # 2) 未关联工单号 → 检查是否纯文档 PR(豁免)
+          files=$(curl -s -H "Authorization: token ${GITEA_TOKEN}" \
+            "http://127.0.0.1:3000/api/v1/repos/tanzk/csctalon/pulls/${num}/files" \
+            | python3 -c "import sys,json; print(' '.join(f.get('filename','') for f in json.load(sys.stdin)))" 2>/dev/null || true)
+
+          echo "== 变更文件 =="
+          echo "$files"
+
+          non_doc=0
+          for f in $files; do
+            case "$f" in
+              docs/*.md|*.md) ;;
+              *) non_doc=1 ;;
+            esac
+          done
+
+          if [ "$non_doc" = "0" ]; then
+            echo "✅ 纯文档 PR, 豁免工单号门禁"
+            exit 0
+          fi
+
+          echo "❌ PR 未关联工单号(标题/描述需含 #<issue号>), 且包含代码变更"
+          echo "   请在 PR 标题或描述中加入 #工单号, 例如: 修复 xxx #2"
+          exit 1

.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,23 +88,37 @@ 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
         run: |
           # 挂宿主机绝对路径 /vol2/@appcenter/gitea-runner/workspace/ci-repo/backend
           docker run --rm --network ci-net \
@@ -58,15 +133,56 @@ 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
             "
 
+      - name: 回写 CI 结果到工单 (G2)
+        if: always() && github.event_name == 'pull_request'
+        env:
+          GITEA_TOKEN: ${{ secrets.GITEATOKEN }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          PR_BODY: ${{ github.event.pull_request.body }}
+          SHA: ${{ github.sha }}
+          TEST_OUTCOME: ${{ steps.backend-test.outcome }}
+        run: |
+          # 对应锁定设计 A-20260903-001 §2.2: pytest/ruff 结果回写工单评论, 幂等去重
+          issue_no=$(printf '%s\n%s\n' "$PR_TITLE" "$PR_BODY" | grep -Eo '#[0-9]+' | head -1 | tr -d '#')
+          [ -n "$issue_no" ] || { echo "未解析到工单号, 跳过回写"; exit 0; }
+          api="http://127.0.0.1:3000/api/v1/repos/tanzk/csctalon"
+
+          # 幂等: 该工单已有同 commit 的 CI 评论则跳过
+          existing=$(curl -s -H "Authorization: token ${GITEA_TOKEN}" "$api/issues/${issue_no}/comments")
+          if echo "$existing" | grep -q "${SHA}"; then
+            echo "已存在同 commit CI 评论, 跳过(幂等)"
+            exit 0
+          fi
+
+          outcome="${TEST_OUTCOME:-unknown}"
+          body="🤖 CI 自动回写: commit \`${SHA}\` 后端测试(ruff+pytest) = **${outcome}**"
+          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]}))" "$body")" \
+            "$api/issues/${issue_no}/comments" > /dev/null
+          echo "已回写 CI 结果到工单 #${issue_no}"
+
       - 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 「界面设计纪律（强制）」）。**缺失该章节的界面类架构文档不予通过。**
+
 ## 职责
 
 你**只输出设计，不输出实现代码**。你的产出是架构文档，交人工审核锁定后，才允许进入开发阶段。
@@ -16,7 +34,7 @@ user-invocable: true
 ## 输入
 
 - 需求描述（优先使用 `docs/standards/task-work-order.md` 派工单格式）
-- 现有代码 / 表结构（`docs/数据库表结构说明.md`、`backend/app/models/`）
+- 现有代码 / 表结构（`docs/standards/数据库表结构说明.md`、`backend/app/models/`）
 - 已有架构文档（`docs/arch/`、`.trae/documents/`）
 
 ## 输出物标准（写入 docs/arch/A-YYYYMMDD-序号-简述.md）
@@ -31,7 +49,7 @@ user-invocable: true
 1. 优先复用现有模块（`backend/app/services/`、`backend/app/api/v1/`），禁止重复造轮子
 2. 接口设计必须考虑幂等性（尤其同步、导入类接口）
 3. 数据流必须标注敏感字段（PII、金额）的脱敏点
-4. 金额一律以"分"为单位（整数），时间字段遵守 `docs/数据时间字段使用规范.md`
+4. 金额一律以"分"为单位（整数），时间字段遵守 `docs/standards/数据时间字段使用规范.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 风险（前端输出是否转义）
 - [ ] 空指针 / 越界访问
@@ -23,7 +38,7 @@ user-invocable: true
 - [ ] 与架构文档的一致性（`docs/arch/` 是否擅自改接口）
 - [ ] 性能隐患（N+1 查询、循环内调接口）
 - [ ] 金额单位（是否统一"分"，无浮点）
-- [ ] 时区处理（`Asia/Shanghai`、`SYS/system` 排除，见 `docs/数据时间字段使用规范.md`）
+- [ ] 时区处理（`Asia/Shanghai`、`SYS/system` 排除，见 `docs/standards/数据时间字段使用规范.md`）
 - [ ] 表结构变更是否走 Alembic migration
 
 ## 输出格式（分级报告）

.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

@@ -87,6 +87,9 @@ backend/uploads/*
 # 根目录 uploads/ = compose 挂载的同步下载目录(运行时生成,不入库)
 uploads/
 
+# 后端运行时数据(登录态/下载/临时,含 cookie/会话凭证,严禁入库)
+backend/data/
+
 # 样本数据(真实业务数据,含退费单号/商户信息等敏感内容,不入库)
 01样本数据/
 
@@ -106,3 +109,49 @@ backend/logs/
 
 # ---------- 部署产物(本地打包/备份,勿入库) ----------
 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/数据时间字段使用规范.md` 中规定的时区换算（`AT TIME ZONE 'Asia/Shanghai'`）与 `SYS/system` 系统操作人排除标准。
+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

@@ -126,18 +126,19 @@ csctalon/
 │       ├── api/                   # API 调用封装
 │       ├── components/            # 公共组件
 │       └── store/                 # Pinia 状态管理
-├── docs/                          # 设计文档与说明
+├── docs/                          # 设计文档与说明（组织规范见 docs/README.md）
+│   ├── README.md                  # docs 目录组织与命名规范
 │   ├── 规划设计.md                 # 系统架构设计(v0.4)
-│   ├── 数据同步与加工说明.md        # BMS/SCRM 同步链路(v0.4)
-│   ├── 数据时间字段使用规范.md      # 时间字段口径
-│   ├── 人均效率算法说明.md          # 工作量分/效率分计算
-│   ├── Group-Specialty双体系设计.md # 行政分组+业务专项
+│   ├── 规划设计-v0.5.md            # 规划 v0.5 评审定稿
 │   ├── API接口文档.md              # 50+ 路由端点
-│   ├── 数据库表结构说明.md          # 86 张表
-│   ├── alembic-migration管理规范.md # 迁移管理
+│   ├── 审查行动项登记.md           # 审查/审计行动项台账
 │   ├── arch/                      # 已锁定架构文档 + _pending/ 待审核
-│   ├── standards/                 # 规范(error-code/review-checklist/派工单)
-│   └── debug/                     # 调试文档归档
+│   ├── standards/                 # 规范/清单/派工单模板
+│   ├── reports/                   # 审计/审查/审核报告
+│   ├── design/                    # 未锁定设计方案
+│   ├── ops/                       # 运维手册/SOP
+│   ├── debug/                     # 调试文档归档
+│   └── security/                  # 安全事件/凭证整改
 ├── data/                          # Docker 数据卷 (gitignore)
 ├── logs/                          # 运行时日志 (gitignore)
 ├── .env.example                   # 环境变量模板
@@ -157,11 +158,15 @@ csctalon/
 | 全局约束 | [AGENTS.md](AGENTS.md) | AI 行为铁律(禁止 console.log/拼接SQL/硬编码密钥等), 自动加载 |
 | 三阶段 Agent | `.github/agents/` | 架构师(只设计) / 开发者(实现) / 审查员(只审查) |
 | 架构锁定 | `docs/arch/` | 已锁定架构文档 + `_pending/` 待人工审核 |
-| 规范 | `docs/standards/` | 错误码 / 审查清单 / 任务派工单模板 |
+| 规范 | `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，强制) |
 
-**协作流程**: 需求 → 架构师出设计 → 人工锁定(`docs/arch/` + git tag) → 开发者实现 → 审查员审查 → 人工终审合并。测试与 lint 由 CI 机器验证, 不依赖 AI 口头声称。
+> **提交钩子（建议安装）**：`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 口头声称。
 
 ## 运行测试
 
@@ -173,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)
 ```
 
 ## 核心功能模块
@@ -210,14 +219,15 @@ ruff check app/ tests/
 | 文档 | 说明 |
 |---|---|
 | [规划设计.md](docs/规划设计.md) | 系统架构、模块设计、技术路线 |
-| [运营指标阈值化与预警通知设计.md](docs/arch/_pending/metric-alerting-notification-design.md) | 指标注册表/四级阈值/预警引擎/通知通道设计与实施状态 |
-| [数据同步与加工说明.md](docs/数据同步与加工说明.md) | BMS/SCRM 数据采集与清洗链路 |
-| [人均效率算法说明.md](docs/人均效率算法说明.md) | 工作量分/效率分计算、6专项系数、SN去重 |
-| [Group-Specialty双体系设计.md](docs/Group-Specialty双体系设计.md) | 行政分组与业务专项双维度模型 |
-| [数据时间字段使用规范.md](docs/数据时间字段使用规范.md) | 各表时间字段口径定义 |
+| [运营指标阈值化与预警通知设计.md](docs/arch/A-20260902-004-metric-alerting-notification-design.md) | 指标注册表/四级阈值/预警引擎/通知通道设计与实施状态 |
+| [数据同步与加工说明.md](docs/standards/数据同步与加工说明.md) | BMS/SCRM 数据采集与清洗链路 |
+| [数据采集运维手册.md](docs/ops/数据采集-运维手册.md) | 采集故障排查、缺口恢复、巡检 SOP |
+| [人均效率算法说明.md](docs/standards/人均效率算法说明.md) | 工作量分/效率分计算、6专项系数、SN去重 |
+| [Group-Specialty双体系设计.md](docs/design/Group-Specialty双体系设计.md) | 行政分组与业务专项双维度模型 |
+| [数据时间字段使用规范.md](docs/standards/数据时间字段使用规范.md) | 各表时间字段口径定义 |
 | [API接口文档.md](docs/API接口文档.md) | 50+ 路由端点/参数/响应 |
-| [数据库表结构说明.md](docs/数据库表结构说明.md) | 86 张表用途/关系/索引 |
-| [alembic-migration管理规范.md](docs/alembic-migration管理规范.md) | 版本链管理、merge head、幂等升级 |
+| [数据库表结构说明.md](docs/standards/数据库表结构说明.md) | 86 张表用途/关系/索引 |
+| [alembic-migration管理规范.md](docs/standards/alembic-migration管理规范.md) | 版本链管理、merge 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

@@ -0,0 +1,70 @@
+"""quality disposition rules table (A-20260909-001)
+
+Revision ID: 0f822d39bb6e
+Revises: e0f1a2b3c4d5
+Create Date: 2026-09-09 10:45:00.000000
+"""
+from typing import Sequence, Union
+
+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
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """建 quality_disposition_rules 表(质量问题治理处置规则, A-20260909-001 §2.4)"""
+    op.create_table(
+        'quality_disposition_rules',
+        sa.Column('id', sa.BigInteger(), autoincrement=True, nullable=False, comment='自增主键'),
+        sa.Column('table_code', sa.String(length=32), nullable=False,
+                  comment='作用表: refund/wallet/shanmao/manual_refund/ticket'),
+        sa.Column('trigger_category', sa.String(length=32), nullable=False,
+                  comment='触发问题分类: time_future/time_past/time_reversed/enum_dirty/amount_invalid/missing_field/e_mismatch/residual/dup/ad_overlap_dup'),
+        sa.Column('name', sa.String(length=255), nullable=False, comment='规则名(人读)'),
+        sa.Column('match_pattern', postgresql.JSONB(astext_type=sa.Text()), nullable=True,
+                  comment='特征匹配条件(表字段级, jsonb)'),
+        sa.Column('disposition', sa.String(length=24), nullable=False,
+                  comment='处置动作: fix_field/ignore/backfill_from_e/confirm_ok'),
+        sa.Column('disposition_params', postgresql.JSONB(astext_type=sa.Text()), nullable=True,
+                  comment='动作参数: 如 fix_field 的 {field, mode}; backfill_from_e 的匹配键'),
+        sa.Column('auto_level', sa.String(length=12), nullable=False, server_default='suggest',
+                  comment='自动级别: auto/suggest'),
+        sa.Column('confidence', sa.Integer(), nullable=False, server_default='60',
+                  comment='置信度 0-100(命中次数越多越高)'),
+        sa.Column('hit_count', sa.Integer(), nullable=False, server_default='0',
+                  comment='命中计数(学习信号)'),
+        sa.Column('last_hit_at', sa.DateTime(timezone=True), nullable=True, comment='最后命中时间'),
+        sa.Column('source_rule_id', sa.BigInteger(), nullable=True, comment='由哪条人工处置沉淀而来(溯源)'),
+        sa.Column('source_ref', sa.String(length=255), nullable=True,
+                  comment='沉淀来源(如 manual_refund:id=123 处置时生成)'),
+        sa.Column('note', sa.Text(), nullable=True, 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('enabled', sa.Boolean(), nullable=False, server_default=sa.text('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_quality_disposition_rules_table_code'), 'quality_disposition_rules',
+                    ['table_code'], unique=False)
+    op.create_index(op.f('ix_quality_disposition_rules_trigger_category'), 'quality_disposition_rules',
+                    ['trigger_category'], unique=False)
+    op.create_index(op.f('ix_quality_disposition_rules_disposition'), 'quality_disposition_rules',
+                    ['disposition'], unique=False)
+    op.create_index(op.f('ix_quality_disposition_rules_auto_level'), 'quality_disposition_rules',
+                    ['auto_level'], unique=False)
+
+
+def downgrade() -> None:
+    op.drop_index(op.f('ix_quality_disposition_rules_auto_level'), table_name='quality_disposition_rules')
+    op.drop_index(op.f('ix_quality_disposition_rules_disposition'), table_name='quality_disposition_rules')
+    op.drop_index(op.f('ix_quality_disposition_rules_trigger_category'), table_name='quality_disposition_rules')
+    op.drop_index(op.f('ix_quality_disposition_rules_table_code'), table_name='quality_disposition_rules')
+    op.drop_table('quality_disposition_rules')

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/47cadbf38a6f_add_doc_sync_sources.py

@@ -0,0 +1,103 @@
+"""add doc_sync_sources
+
+共享文档在线采集源配置表 doc_sync_sources (#33, A-20260907-002):
+- 每行 = 一份共享文档(腾讯 docs.qq.com / 金山 kdocs.cn)的采集配置
+- 用登录态(BROWSER_STATE_DIR/tencent_doc.json 或 kdocs.json)+ 官方 UI 导出 xlsx,
+  再复用 complaint_sync / manual_refund_sync 既有入库管线(见 shared_doc_sync_service)
+- target_type: complaint=投诉(315+卡商2 sheet) / manual_refund=商户号退款
+- sheet_rules: sheet→目标表映射, 如
+  [{'sheet':'监督局-315投诉','target':'external_complaint'},
+   {'sheet':'卡商群投诉','target':'card_complaint'}]
+- ⚠️ 不含任何登录态/凭证/敏感信息(登录态文件路径从 settings.BROWSER_STATE_DIR 读取)
+
+Revision ID: 47cadbf38a6f
+Revises: a1f0c2e4d6b8
+Create Date: 2026-09-08 12:30:00.000000
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import JSONB
+
+from alembic import op
+
+revision: str = '47cadbf38a6f'
+down_revision: Union[str, None] = 'a1f0c2e4d6b8'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+# 默认 seed 配置(幂等, INSERT ... ON CONFLICT DO NOTHING)。
+# 不含敏感信息: 仅平台/链接/文档名/目标类型/sheet 映射, 登录态文件名走默认值。
+_DEFAULT_SOURCES: list[dict] = [
+    {
+        "platform": "tencent",
+        "doc_url": "https://docs.qq.com/sheet/DZWF4WVZJcWxGVUNW",
+        "doc_name": "315投诉处理登记表新",
+        "target_type": "complaint",
+        "sheet_rules": [
+            {"sheet": "监督局-315投诉", "target": "external_complaint"},
+            {"sheet": "卡商群投诉", "target": "card_complaint"},
+        ],
+    },
+    {
+        "platform": "kdocs",
+        "doc_url": "https://www.kdocs.cn/l/cbZIHtt6obyf",
+        "doc_name": "商户号手机退款处理登记",
+        "target_type": "manual_refund",
+        "sheet_rules": [],
+    },
+]
+
+
+def upgrade() -> None:
+    op.create_table(
+        'doc_sync_sources',
+        sa.Column('id', sa.BigInteger(), autoincrement=True, nullable=False),
+        sa.Column('platform', sa.String(length=32), nullable=False, comment='平台: tencent=腾讯文档 / kdocs=金山文档'),
+        sa.Column('doc_url', sa.String(length=512), nullable=False, comment='共享文档链接'),
+        sa.Column('doc_name', sa.String(length=128), nullable=True, comment='文档名(展示)'),
+        sa.Column('target_type', sa.String(length=32), nullable=False, comment='目标业务类型: complaint=投诉(315+卡商2sheet) / manual_refund=商户号退款'),
+        sa.Column('sheet_rules', JSONB(), nullable=True, comment="sheet→data_type映射, 如 [{'sheet':'监督局-315投诉','target':'external_complaint'},{'sheet':'卡商群投诉','target':'card_complaint'}]"),
+        sa.Column('state_file', sa.String(length=128), nullable=True, comment='登录态文件名(默认 tencent_doc.json/kdocs.json)'),
+        sa.Column('enabled', sa.Boolean(), nullable=False, server_default=sa.text('true'), comment='启用; false=停用不采集'),
+        sa.Column('sync_interval_minutes', sa.Integer(), nullable=False, server_default='60', comment='轮询间隔(分钟)'),
+        sa.Column('last_sync_at', sa.DateTime(timezone=True), nullable=True, comment='最近同步时间(UTC)'),
+        sa.Column('last_sync_status', sa.String(length=32), nullable=True, comment='最近同步状态 success/partial/failed'),
+        sa.Column('last_sync_summary', JSONB(), nullable=True, comment='最近同步统计(各sheet行数/增改等)'),
+        sa.Column('last_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'),
+        sa.UniqueConstraint('platform', 'doc_url', name='uq_doc_sync_sources_platform_doc_url'),
+        comment='共享文档在线采集源配置(每行一份共享文档)',
+    )
+    op.create_index('ix_doc_sync_sources_platform', 'doc_sync_sources', ['platform'])
+    op.create_index('ix_doc_sync_sources_target_type', 'doc_sync_sources', ['target_type'])
+
+    # seed 默认配置(幂等: 同 platform+doc_url 已存在则跳过)。
+    # sheet_rules: python 对象 + bindparam(type_=JSONB) 作为绑定参数——
+    # SQLAlchemy 编译期按 jsonb 类型序列化, psycopg2 正确写入 JSONB 数组。
+    # (禁止 type_coerce 表达式对象直接作绑定参数: psycopg2 无法适配)
+    conn = op.get_bind()
+    for row in _DEFAULT_SOURCES:
+        conn.execute(
+            sa.text(
+                "INSERT INTO doc_sync_sources "
+                "(platform, doc_url, doc_name, target_type, sheet_rules, state_file, enabled, sync_interval_minutes) "
+                "VALUES (:platform, :doc_url, :doc_name, :target_type, :sheet_rules, NULL, true, 60) "
+                "ON CONFLICT (platform, doc_url) DO NOTHING"
+            ).bindparams(sa.bindparam("sheet_rules", type_=JSONB)),
+            {
+                "platform": row["platform"],
+                "doc_url": row["doc_url"],
+                "doc_name": row["doc_name"],
+                "target_type": row["target_type"],
+                "sheet_rules": row["sheet_rules"] or [],
+            },
+        )
+
+
+def downgrade() -> None:
+    op.drop_index('ix_doc_sync_sources_target_type', table_name='doc_sync_sources')
+    op.drop_index('ix_doc_sync_sources_platform', table_name='doc_sync_sources')
+    op.drop_table('doc_sync_sources')

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/8a7b6c5d4e3f_drop_refund_wide_dead_fields.py

@@ -0,0 +1,55 @@
+"""drop refund_wide mr_* & ticket_finish_time dead fields
+
+Revision ID: 8a7b6c5d4e3f
+Revises: 47cadbf38a6f
+Create Date: 2026-09-08 17:30:00.000000
+
+背景(A-20260908-001 退费宽表精简重构, LOCKED):
+全库核实 refund_wide 的 mr_*(商户退款关联)6 字段 + ticket_finish_time 零消费
+(无任何 analysis_view/规则/接口引用), 属死字段, 精简删除:
+- wx_refund_no / mr_trade_time / mr_refund_amount / mr_refund_status / mr_fee / merchant_id
+- ticket_finish_time (89% 被 BMS 批量覆盖不可靠, 已在 UI 隐藏, 见 A-20260902-005)
+同时删除唯一索引 ix_refund_wide_wx_refund_no。
+注意: 不删 merchant_refunds 表 / matcher 关联(二者与宽表物化解耦, match.py 仍用)。
+"""
+from typing import Sequence, Union
+
+from alembic import op
+
+revision: str = '8a7b6c5d4e3f'
+down_revision: Union[str, None] = '47cadbf38a6f'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+_DROP_COLS = [
+    'wx_refund_no',
+    'mr_trade_time',
+    'mr_refund_amount',
+    'mr_refund_status',
+    'mr_fee',
+    'merchant_id',
+    'ticket_finish_time',
+]
+
+
+def upgrade() -> None:
+    op.drop_index('ix_refund_wide_wx_refund_no', table_name='refund_wide')
+    for col in _DROP_COLS:
+        op.drop_column('refund_wide', col)
+
+
+def downgrade() -> None:
+    import sqlalchemy as sa
+
+    specs = {
+        'wx_refund_no': sa.Column('wx_refund_no', sa.String(length=64), nullable=True, comment='微信退款单号'),
+        'mr_trade_time': sa.Column('mr_trade_time', sa.DateTime(timezone=True), nullable=True, comment='商户退款交易时间'),
+        'mr_refund_amount': sa.Column('mr_refund_amount', sa.Numeric(precision=12, scale=2), nullable=True, comment='商户退款金额(微信侧真实退款)'),
+        'mr_refund_status': sa.Column('mr_refund_status', sa.String(length=32), nullable=True, comment='商户退款状态'),
+        'mr_fee': sa.Column('mr_fee', sa.Numeric(precision=12, scale=4), nullable=True, comment='商户退款手续费'),
+        'merchant_id': sa.Column('merchant_id', sa.String(length=64), nullable=True, comment='商户号'),
+        'ticket_finish_time': sa.Column('ticket_finish_time', sa.DateTime(timezone=True), nullable=True, comment='工单完成时间'),
+    }
+    for col in _DROP_COLS:
+        op.add_column('refund_wide', specs[col])
+    op.create_index('ix_refund_wide_wx_refund_no', 'refund_wide', ['wx_refund_no'])

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/a1b2c3d4e5f8_add_manual_refund_aux_columns.py

@@ -0,0 +1,39 @@
+"""add_manual_refund_aux_columns
+
+手动退款登记表 manual_refunds 加辅助列(#20, 现金流回填/数据修复溯源):
+- register_time_raw               登记日期原始值(纠错前保留; 正常行=NULL)
+- backfill_refund_record_report_id op_time 回填来源 refund_record_reports.id(双向溯源)
+全部可空(只增不改)。
+
+Revision ID: a1b2c3d4e5f8
+Revises: f7a8b9c0d1e2
+Create Date: 2026-09-05 22:30:00.000000
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'a1b2c3d4e5f8'
+down_revision: Union[str, None] = 'f7a8b9c0d1e2'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column('manual_refunds', sa.Column(
+        'register_time_raw', sa.DateTime(timezone=True), nullable=True,
+        comment='登记日期原始值(纠错前保留, 正常行=NULL)',
+    ))
+    op.add_column('manual_refunds', sa.Column(
+        'backfill_refund_record_report_id', sa.String(length=64), nullable=True,
+        comment='op_time 回填来源 refund_record_reports.id',
+    ))
+    op.create_index('ix_manual_refunds_backfill_rrr_id', 'manual_refunds', ['backfill_refund_record_report_id'])
+
+
+def downgrade() -> None:
+    op.drop_index('ix_manual_refunds_backfill_rrr_id', table_name='manual_refunds')
+    op.drop_column('manual_refunds', 'backfill_refund_record_report_id')
+    op.drop_column('manual_refunds', 'register_time_raw')

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/a1f0c2e4d6b8_add_ai_focus_configs.py

@@ -0,0 +1,100 @@
+"""add ai_focus_configs
+
+AI 助手关注点/分析视角配置表 ai_focus_configs (A-20260904-003 v1.2 二期切片 / #26):
+- 运营可增改/排序/启停"关注点/分析视角"(注入 AI Prompt user 段, 建议性参考)
+- scope_key 路由(global/refund/complaint/reception) + sort_order + enabled
+- seed 默认关注点(与 QUICK_QUESTIONS 对应), 保证空库也有合理默认
+
+Revision ID: a1f0c2e4d6b8
+Revises: c0a1b2c3d4e7
+Create Date: 2026-09-07 15:40:00.000000
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'a1f0c2e4d6b8'
+down_revision: Union[str, None] = 'c0a1b2c3d4e7'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def _seed_defaults() -> list[dict]:
+    """默认关注点 seed(与 QUICK_QUESTIONS / GLOSSARY_ROUTE 对应)。"""
+    return [
+        {
+            "code": "focus-refund", "scope_key": "refund", "title": "退款关注点",
+            "sort_order": 10,
+            "content": (
+                "退款分析关注点: ①四路分布(A线上直退/B钱包取现/C闪猫/D手动)看结构变化, "
+                "指出主路径与异常抬升; ②涉诉率与涉诉金额是风险信号, 涉诉抬升须提示; "
+                "③E(退款记录报表)为对账基准, 若与四路经营差异明显(偏差>5%)要说明口径原因; "
+                "④金额单位=元, 大额单笔可点名但不能编造明细。"
+            ),
+        },
+        {
+            "code": "focus-complaint", "scope_key": "complaint", "title": "投诉关注点",
+            "sort_order": 10,
+            "content": (
+                "投诉分析关注点: ①三源(内部/商户号/外部)结构, 外部平台投诉最需重视; "
+                "②登记(窗口新增)与处理(真实办结)要分开看, 处理滞后于登记说明积压恶化; "
+                "③积压(未闭环存量)是核心风险, 抬升须提示; ④措辞区分'登记量/处理量/积压', 不要混用。"
+            ),
+        },
+        {
+            "code": "focus-reception", "scope_key": "reception", "title": "接待关注点",
+            "sort_order": 10,
+            "content": (
+                "接待分析关注点: ①总体接待量与服务设备数(SN去重)看覆盖面; "
+                "②六个专项(咨询/套餐/退款处理/退款挽回/内部投诉/外部投诉)的会话与设备规模, "
+                "指出量大的专项与负责人(lead); ③环比(同比前移等长窗口)变化要解释可能原因; "
+                "④接待量含智能助手处理(cs_record), 口径与'人工工单'不同勿混。"
+            ),
+        },
+        {
+            "code": "focus-global", "scope_key": "global", "title": "通用经营视角",
+            "sort_order": 1,
+            "content": (
+                "通用经营分析视角: ①先给结论再给数据支撑, 用标题/要点/小表格组织; "
+                "②对比(同比/环比)给出升降幅与方向; ③有异常(突变/为0/负增长)优先说明; "
+                "④数字一律引用给定数据, 无数据的写'暂无'; 金额单位=元。"
+            ),
+        },
+    ]
+
+
+def upgrade() -> None:
+    op.create_table(
+        'ai_focus_configs',
+        sa.Column('id', sa.BigInteger(), autoincrement=True, nullable=False),
+        sa.Column('code', sa.String(length=32), nullable=False, comment='唯一标识(如 focus-refund-litigation)'),
+        sa.Column('scope_key', sa.String(length=16), nullable=False, server_default='global', comment='适用范围: global/refund/complaint/reception'),
+        sa.Column('title', sa.String(length=64), nullable=False, comment='标题(如 退款关注点)'),
+        sa.Column('content', sa.Text(), nullable=False, comment='关注点正文(注入 Prompt 的指导文本)'),
+        sa.Column('sort_order', sa.Integer(), nullable=False, server_default='0', comment='排序(小在前)'),
+        sa.Column('enabled', sa.Boolean(), nullable=False, server_default=sa.text('true'), comment='启用; false=停用不注入'),
+        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'),
+        sa.UniqueConstraint('code', name='uq_ai_focus_configs_code'),
+        comment='AI 助手关注点/分析视角配置(运营可增改/排序/启停)',
+    )
+    op.create_index('ix_ai_focus_configs_scope_key', 'ai_focus_configs', ['scope_key'])
+    # seed 默认关注点(幂等: 仅空表插入)
+    conn = op.get_bind()
+    existing = conn.execute(sa.text("SELECT count(*) FROM ai_focus_configs")).scalar()
+    if not existing:
+        for row in _seed_defaults():
+            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')"
+            ), row)
+
+
+def downgrade() -> None:
+    op.drop_index('ix_ai_focus_configs_scope_key', table_name='ai_focus_configs')
+    op.drop_table('ai_focus_configs')

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/a5b6c7d8e9f0_add_manual_refunds_actual_refund_time.py

@@ -0,0 +1,35 @@
+"""add manual_refunds actual_refund_time (实际扣款时间, E路回填, 对账用; 不改 op_time 口径)
+
+Revision ID: a5b6c7d8e9f0
+Revises: 0f822d39bb6e
+Create Date: 2026-09-09 15:10:00.000000
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'a5b6c7d8e9f0'
+down_revision: Union[str, None] = '0f822d39bb6e'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """manual_refunds 新增 actual_refund_time(实际扣款时间) — E(refund_record_reports.refund_time)逐单回填。
+
+    用途(2026-09-09 对账时间对齐): 对账按"实际扣款时间"逐日匹配, 消除 D 路
+    op_time(客服操作/登记时间)与 E 扣款时间的错位。op_time 保留运营口径不变。
+    """
+    op.add_column('manual_refunds', sa.Column(
+        'actual_refund_time', sa.DateTime(timezone=True), nullable=True,
+        comment='实际扣款时间(E路refund_record_reports.refund_time回填, 对账用; 客服操作时间=op_time不变)'
+    ))
+    op.create_index('ix_manual_refunds_actual_refund_time', 'manual_refunds', ['actual_refund_time'])
+
+
+def downgrade() -> None:
+    """回滚: 删列"""
+    op.drop_index('ix_manual_refunds_actual_refund_time', table_name='manual_refunds')
+    op.drop_column('manual_refunds', 'actual_refund_time')

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/a9e8d7c6b5a4_add_external_access_tokens.py

@@ -0,0 +1,49 @@
+"""add_external_access_tokens
+
+新增 external_access_tokens 表: 外部工具只读访问令牌(workbuddy 等)。
+- token 明文不落库, 仅存 SHA-256 hash + prefix; 吊销=enabled=false 软删。
+- scopes JSONB: reception/refund/complaint/brief(可扩展)。
+- rate_limit_per_min 个性化限频(Redis 固定窗口), NULL=全局默认。
+
+Revision ID: a9e8d7c6b5a4
+Revises: 73a7922ec598
+Create Date: 2026-09-02 18:30:00.000000
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+from alembic import op
+
+revision: str = 'a9e8d7c6b5a4'
+down_revision: Union[str, None] = '73a7922ec598'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table('external_access_tokens',
+        sa.Column('name', sa.String(length=64), nullable=False, comment='调用方标识(如 workbuddy-简报), 审计/管理界面显示'),
+        sa.Column('token_hash', sa.String(length=64), nullable=False, comment='SHA-256(token), 不存明文'),
+        sa.Column('token_prefix', sa.String(length=12), nullable=False, comment='明文前 8 位, 管理界面识别用'),
+        sa.Column('scopes', postgresql.JSONB(astext_type=sa.Text()), nullable=False, comment='权限范围: reception/refund/complaint/brief, 可扩展'),
+        sa.Column('rate_limit_per_min', sa.Integer(), nullable=True, comment='每 token 个性化限频(次/分钟); NULL=用全局默认'),
+        sa.Column('enabled', sa.Boolean(), nullable=False, comment='总开关: false=已吊销(软删)'),
+        sa.Column('expires_at', sa.DateTime(timezone=True), nullable=True, comment='可选过期时间'),
+        sa.Column('last_used_at', sa.DateTime(timezone=True), nullable=True, comment='最后使用时间(管理界面看活跃度)'),
+        sa.Column('created_by', sa.String(length=64), nullable=True, comment='创建人账号'),
+        sa.Column('revoked_by', sa.String(length=64), nullable=True, comment='吊销人账号'),
+        sa.Column('id', sa.BigInteger(), autoincrement=True, nullable=False),
+        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_external_access_tokens_expires_at'), 'external_access_tokens', ['expires_at'], unique=False)
+    op.create_index(op.f('ix_external_access_tokens_token_hash'), 'external_access_tokens', ['token_hash'], unique=True)
+
+
+def downgrade() -> None:
+    op.drop_index(op.f('ix_external_access_tokens_token_hash'), table_name='external_access_tokens')
+    op.drop_index(op.f('ix_external_access_tokens_expires_at'), table_name='external_access_tokens')
+    op.drop_table('external_access_tokens')

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/b1e2f3a4c5d6_add_ingest_health_metric.py

@@ -0,0 +1,106 @@
+"""add_ingest_health_metric
+
+采集数据健康告警指标种子 (工单 #5 / A-20260904-001 LOCKED):
+- metric_registry 新增 ingest_volume_cs_record(采集健康类指标, 依赖 cs_record)
+- metric_thresholds 新增默认阈值(相对近7日均值: 预警 70% / 告警 40%)
+- alert_rules 新增启用规则(metric_code 指向新指标, 供 scan_alerts 每小时扫描)
+- 修复历史缺陷: 生产 alert_rules 为空 → 指标引擎空转无告警; 本次随新指标一并补建规则
+
+Revision ID: b1e2f3a4c5d6
+Revises: a9e8d7c6b5a4
+Create Date: 2026-09-04 12:00:00.000000
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'b1e2f3a4c5d6'
+down_revision: Union[str, None] = 'a9e8d7c6b5a4'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+CODE = "ingest_volume_cs_record"
+
+
+def _metric_registry_exists(conn) -> bool:
+    return conn.execute(sa.text(
+        "SELECT count(*) FROM metric_registry WHERE code = :c"
+    ), {"c": CODE}).scalar() > 0
+
+
+def _threshold_exists(conn) -> bool:
+    return conn.execute(sa.text(
+        "SELECT count(*) FROM metric_thresholds WHERE metric_code = :c AND valid_to IS NULL"
+    ), {"c": CODE}).scalar() > 0
+
+
+def _rule_exists(conn) -> bool:
+    return conn.execute(sa.text(
+        "SELECT count(*) FROM alert_rules WHERE metric_code = :c"
+    ), {"c": CODE}).scalar() > 0
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    # 1. 指标注册(幂等)
+    if not _metric_registry_exists(conn):
+        conn.execute(sa.text(
+            """
+            INSERT INTO metric_registry (code, name_cn, direction, period, unit, data_sources, description, enabled, created_at, updated_at)
+            VALUES (:c, '智能助手记录每日入表量', 'higher_better', 'day', '%',
+                    '["cs_record","bms_sync_logs"]',
+                    '采集健康指标: cs_record 当日入表量相对近7日均值比例(采集断流/骤降告警, 非业务指标); kind=ingest_health',
+                    true, now(), now())
+            """
+        ), {"c": CODE})
+
+    # 2. 默认阈值(相对近7日均值 %): 预警 <70% / 告警 <40%(可配置)
+    if not _threshold_exists(conn):
+        conn.execute(sa.text(
+            """
+            INSERT INTO metric_thresholds (metric_code, excellent_value, warning_value, critical_value, created_at, updated_at)
+            VALUES (:c, 100.0, 70.0, 40.0, now(), now())
+            """
+        ), {"c": CODE})
+
+    # 3. 启用规则(scan_alerts 遍历 alert_rules; 缺规则则引擎空转)
+    #    同时为 5 个既有业务指标补建规则(修复历史缺陷: 生产 alert_rules 为空)
+    existing_rules = set(r[0] for r in conn.execute(sa.text(
+        "SELECT metric_code FROM alert_rules WHERE metric_code IS NOT NULL"
+    )))
+    rule_seeds = [
+        # (name, metric_code, warning, critical)
+        ("采集健康-接待入表量", CODE, 70.0, 40.0),
+        ("业务-退款挽回率", "recovery_rate", 30.0, 20.0),
+        ("业务-当日退款笔数", "refund_count", 30.0, 50.0),
+        ("业务-投诉工单积压", "ticket_backlog", 20.0, 50.0),
+        ("业务-近7天外部投诉量", "external_complaint_7d", 50.0, 70.0),
+        ("业务-当日内部投诉量", "internal_complaint_daily", 8.0, 15.0),
+    ]
+    for name, mcode, warn, crit in rule_seeds:
+        if mcode in existing_rules:
+            continue
+        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 (:name, 'metric', NULL, NULL, true,
+                    :mcode, NULL, :warn, :crit,
+                    '["inapp"]', '["admin","supervisor"]', NULL, now(), now())
+            """
+        ), {"name": name, "mcode": mcode, "warn": warn, "crit": crit})
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    # 删除规则(含本迁移新建的) + 指标阈值 + 指标注册(幂等容忍不存在)
+    conn.execute(sa.text("DELETE FROM alert_rules WHERE metric_code = :c"), {"c": CODE})
+    conn.execute(sa.text("DELETE FROM metric_thresholds WHERE metric_code = :c"), {"c": CODE})
+    conn.execute(sa.text("DELETE FROM metric_registry WHERE code = :c"), {"c": CODE})
+    # 顺带清理迁移中为历史业务指标补建的规则
+    for mcode in ("recovery_rate", "refund_count", "ticket_backlog", "external_complaint_7d", "internal_complaint_daily"):
+        conn.execute(sa.text("DELETE FROM alert_rules WHERE metric_code = :c"), {"c": mcode})

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/b6c7d8e9f0a1_add_wallet_withdrawals_actual_refund_time.py

@@ -0,0 +1,35 @@
+"""add wallet_withdrawals actual_refund_time (用户提现实际扣款时间, E路回填, 对账用)
+
+Revision ID: b6c7d8e9f0a1
+Revises: a5b6c7d8e9f0
+Create Date: 2026-09-09 15:40:00.000000
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'b6c7d8e9f0a1'
+down_revision: Union[str, None] = 'a5b6c7d8e9f0'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """wallet_withdrawals 新增 actual_refund_time(用户提现实际扣款时间)。
+
+    2026-09-09 对账时间对齐: B(用户提现)按 SN+金额+时间窗 在 E(refund_record_reports)
+    唯一匹配, 回填其 refund_time; 对账/现金流按此归日消除 op_time vs E 扣款错位。
+    """
+    op.add_column('wallet_withdrawals', sa.Column(
+        'actual_refund_time', sa.DateTime(timezone=True), nullable=True,
+        comment='实际扣款时间(E路refund_time按SN+金额+时间窗回填, 对账用; 操作时间=op_time不变)'
+    ))
+    op.create_index('ix_wallet_withdrawals_actual_refund_time', 'wallet_withdrawals', ['actual_refund_time'])
+
+
+def downgrade() -> None:
+    """回滚: 删列"""
+    op.drop_index('ix_wallet_withdrawals_actual_refund_time', table_name='wallet_withdrawals')
+    op.drop_column('wallet_withdrawals', 'actual_refund_time')

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/c0a1b2c3d4e6_create_reconcile_checks.py

@@ -0,0 +1,55 @@
+"""create reconcile_checks
+
+对账复核批次表 reconcile_checks (A-20260906-002 LOCKED / #22):
+- ABCD/E 五路手动对账复核留痕, 按时间窗批次存时点快照(JSONB)
+- 仅留痕存档, 不参与任何统计聚合
+- 唯一 check_no; reviewed_by FK users.id(可空)
+
+Revision ID: c0a1b2c3d4e6
+Revises: a1b2c3d4e5f8
+Create Date: 2026-09-06 17:30:00.000000
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+from alembic import op
+
+revision: str = 'c0a1b2c3d4e6'
+down_revision: Union[str, None] = 'a1b2c3d4e5f8'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'reconcile_checks',
+        sa.Column('id', sa.BigInteger(), autoincrement=True, nullable=False),
+        sa.Column('check_no', sa.String(length=32), nullable=False, comment='复核单号 RC+YYYYMMDD+序号'),
+        sa.Column('window_start', sa.DateTime(timezone=True), nullable=False, comment='对账时间窗开始(UTC aware 存)'),
+        sa.Column('window_end', sa.DateTime(timezone=True), nullable=False, comment='对账时间窗结束(UTC aware 存)'),
+        sa.Column('grain', sa.String(length=8), nullable=False, comment='粒度 day/week'),
+        sa.Column('route_snapshot', postgresql.JSONB(astext_type=sa.Text()), nullable=True, comment='五路合计+差异时点快照'),
+        sa.Column('by_route_of_e', postgresql.JSONB(astext_type=sa.Text()), nullable=True, comment='E 水单勾稽归属'),
+        sa.Column('dupe_detect', postgresql.JSONB(astext_type=sa.Text()), nullable=True, comment='D 路重复/脏数据检出'),
+        sa.Column('conclusion', sa.String(length=16), nullable=True, comment='结论: 一致/差异已确认/存疑待查'),
+        sa.Column('note', sa.Text(), nullable=True, comment='复核备注(差异原因等)'),
+        sa.Column('reviewed_by', sa.Integer(), nullable=True, comment='复核人 user id'),
+        sa.Column('reviewed_name', sa.String(length=64), nullable=True, comment='复核人姓名'),
+        sa.Column('reviewed_at', sa.DateTime(timezone=True), nullable=True, comment='复核时间(UTC aware 存)'),
+        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(['reviewed_by'], ['users.id'], name='fk_reconcile_checks_reviewed_by'),
+        sa.PrimaryKeyConstraint('id'),
+        sa.UniqueConstraint('check_no', name='uq_reconcile_checks_check_no'),
+        comment='对账复核批次(ABCD/E 五路, 仅留痕不参与统计)',
+    )
+    op.create_index('ix_reconcile_checks_check_no', 'reconcile_checks', ['check_no'])
+    op.create_index('ix_reconcile_checks_window_start', 'reconcile_checks', ['window_start'])
+
+
+def downgrade() -> None:
+    op.drop_index('ix_reconcile_checks_window_start', table_name='reconcile_checks')
+    op.drop_index('ix_reconcile_checks_check_no', table_name='reconcile_checks')
+    op.drop_table('reconcile_checks')

backend/alembic/versions/c0a1b2c3d4e7_create_reconcile_matches.py

@@ -0,0 +1,61 @@
+"""create reconcile_matches
+
+对账复核逐笔勾稽结果表 reconcile_matches (A-20260906-002 v1.1 LOCKED / #22):
+- E 水单(refund_record_reports)每笔 → 自动归类(auto_route) + 候选经营单(matched_ref)
+  + 人工确认状态(confirm_status), 仅留痕不改任何源表
+- check_id FK → reconcile_checks.id(批次, 可空=草稿); (check_id, report_id) 唯一
+- report_id FK → refund_record_reports.id
+
+Revision ID: c0a1b2c3d4e7
+Revises: c0a1b2c3d4e6
+Create Date: 2026-09-06 18:40:00.000000
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+from alembic import op
+
+revision: str = 'c0a1b2c3d4e7'
+down_revision: Union[str, None] = 'c0a1b2c3d4e6'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'reconcile_matches',
+        sa.Column('id', sa.BigInteger(), autoincrement=True, nullable=False),
+        sa.Column('check_id', sa.Integer(), nullable=True, comment='关联复核批次(reconcile_checks.id, 可空=草稿未成批)'),
+        sa.Column('report_id', sa.Integer(), nullable=False, comment='E 退款记录报表 id(勾稽基准)'),
+        sa.Column('platform_order_no', sa.String(length=128), nullable=True, comment='E 笔平台订单号快照'),
+        sa.Column('refund_amount', sa.Numeric(12, 2), nullable=True, comment='E 笔退款金额快照(元)'),
+        sa.Column('refund_time', sa.DateTime(timezone=True), nullable=True, comment='E 笔退款时间快照'),
+        sa.Column('auto_route', sa.String(length=16), nullable=True, comment='自动归类 A/B/C/D/unmatched(_classify_report)'),
+        sa.Column('matched_ref', postgresql.JSONB(astext_type=sa.Text()), nullable=True, comment='候选匹配经营单 [{route,source,source_id,ref_no,amount}]'),
+        sa.Column('confirm_status', sa.String(length=16), nullable=True, comment='人工确认状态: 已核对一致/差异已确认/存疑待查/已排除重复/待核对'),
+        sa.Column('confirm_note', sa.Text(), nullable=True, comment='人工备注(差异原因等)'),
+        sa.Column('confirmed_by', sa.Integer(), nullable=True, comment='确认人 user id'),
+        sa.Column('confirmed_name', sa.String(length=64), nullable=True, comment='确认人姓名'),
+        sa.Column('confirmed_at', sa.DateTime(timezone=True), nullable=True, comment='确认时间(UTC aware)'),
+        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(['check_id'], ['reconcile_checks.id'], name='fk_reconcile_matches_check'),
+        sa.ForeignKeyConstraint(['report_id'], ['refund_record_reports.id'], name='fk_reconcile_matches_report'),
+        sa.PrimaryKeyConstraint('id'),
+        sa.UniqueConstraint('check_id', 'report_id', name='uq_reconcile_matches_check_report'),
+        comment='对账复核逐笔勾稽(E→ABCD 单笔对应, 仅留痕不改源)',
+    )
+    op.create_index('ix_reconcile_matches_check_id', 'reconcile_matches', ['check_id'])
+    op.create_index('ix_reconcile_matches_report_id', 'reconcile_matches', ['report_id'])
+    op.create_index('ix_reconcile_matches_auto_route', 'reconcile_matches', ['auto_route'])
+    op.create_index('ix_reconcile_matches_confirm_status', 'reconcile_matches', ['confirm_status'])
+
+
+def downgrade() -> None:
+    op.drop_index('ix_reconcile_matches_confirm_status', table_name='reconcile_matches')
+    op.drop_index('ix_reconcile_matches_auto_route', table_name='reconcile_matches')
+    op.drop_index('ix_reconcile_matches_report_id', table_name='reconcile_matches')
+    op.drop_index('ix_reconcile_matches_check_id', table_name='reconcile_matches')
+    op.drop_table('reconcile_matches')

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/c2d3e4f5a6b7_add_data_arrival_health_metrics.py

@@ -0,0 +1,112 @@
+"""add_data_arrival_health_metrics
+
+采集健康告警 v1.2 (工单 #6 / A-20260904-001 v1.2 LOCKED):
+- 弃用 ingest_volume_cs_record(入表量比例, 接待量波动大易误报) → 停用指标与规则
+- 注册表驱动生成 data_arrival_<data_type> 指标 + 规则:
+  主动抓取源 = sync_source_configs WHERE enabled AND default_sync
+  被动推送源 = data_sources WHERE sync_source IN ('workbuddy','tencent_doc')
+              + manual_refund(手动退款推送)
+  判定 = 该源当日是否有任一渠道到达(主动抓取 success / 被动推送 / 手动导入 imported)
+
+Revision ID: c2d3e4f5a6b7
+Revises: b1e2f3a4c5d6
+Create Date: 2026-09-04 16:00:00.000000
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'c2d3e4f5a6b7'
+down_revision: Union[str, None] = 'b1e2f3a4c5d6'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+OLD_CODE = "ingest_volume_cs_record"
+
+
+def _active_fetch_sources(conn) -> list[str]:
+    """主动抓取源: sync_source_configs enabled + default_sync 且有抓取方式(fetch_mode 非空或默认).
+    取 default_sync=true 且 enabled=true 的 data_type(排除纯推送/手动域)。
+    """
+    rows = conn.execute(sa.text(
+        "SELECT data_type FROM sync_source_configs WHERE enabled = true AND default_sync = true ORDER BY sort_order"
+    )).fetchall()
+    # 排除"仅推送/手动导入"的源(它们不在 sync_source_configs 的抓取语义内; manual_refund 等不在此表)
+    skip = {"device_combo"}  # 设备套餐 default_sync=false, 实际不在; 保留防御
+    return [r[0] for r in rows if r[0] not in skip]
+
+
+def _passive_sources(conn) -> list[str]:
+    """被动推送源: data_sources.sync_source ∈ (workbuddy/tencent_doc) + manual_refund(手动退款推送)."""
+    rows = conn.execute(sa.text(
+        "SELECT code FROM data_sources WHERE sync_source IN ('workbuddy','tencent_doc') AND status='active'"
+    )).fetchall()
+    out = [r[0] for r in rows]
+    # manual_refund 由 workbuddy 推送(manual_refund_sync_logs), 若 data_sources 未标 workbuddy 则补
+    if "manual_refund" not in out:
+        exists = conn.execute(sa.text(
+            "SELECT count(*) FROM data_sources WHERE code='manual_refund' AND status='active'"
+        )).scalar()
+        if exists:
+            out.append("manual_refund")
+    return out
+
+
+def _metric_exists(conn, code: str) -> bool:
+    return conn.execute(sa.text("SELECT count(*) FROM metric_registry WHERE code=:c"), {"c": code}).scalar() > 0
+
+
+def _rule_exists(conn, code: str) -> bool:
+    return conn.execute(sa.text("SELECT count(*) FROM alert_rules WHERE metric_code=:c"), {"c": code}).scalar() > 0
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    # 1. 停用旧 ingest_volume_cs_record(防误报; 保留历史数据)
+    conn.execute(sa.text("UPDATE metric_registry SET enabled=false WHERE code=:c"), {"c": OLD_CODE})
+    conn.execute(sa.text("UPDATE alert_rules SET enabled=false WHERE metric_code=:c"), {"c": OLD_CODE})
+
+    # 2. 动态生成 data_arrival_<type> 指标(主动抓取 + 被动推送源)
+    sources = sorted(set(_active_fetch_sources(conn)) | set(_passive_sources(conn)))
+    for dt in sources:
+        code = f"data_arrival_{dt}"
+        if not _metric_exists(conn, 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, :name, 'higher_better', 'day', '',
+                        '["bms_sync_logs","upload_records","complaint_sync_logs","manual_refund_sync_logs"]',
+                        '采集健康(v1.2 注册表驱动): 该源当日是否有任一渠道(success抓取/被动推送/手动导入)到达记录; 不看业务量',
+                        true, now(), now())
+                """
+            ), {"c": code, "name": f"{dt} 数据到达健康"})
+        if not _rule_exists(conn, 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 (:name, 'metric', NULL, NULL, true,
+                        :c, NULL, NULL, NULL,
+                        '["inapp"]', '["admin","supervisor"]', NULL, now(), now())
+                """
+            ), {"name": f"数据到达-{dt}", "c": code})
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    # 重新启用旧指标/规则
+    conn.execute(sa.text("UPDATE metric_registry SET enabled=true WHERE code=:c"), {"c": OLD_CODE})
+    conn.execute(sa.text("UPDATE alert_rules SET enabled=true WHERE metric_code=:c"), {"c": OLD_CODE})
+    # 删除 data_arrival_* 指标与规则
+    rows = conn.execute(sa.text(
+        "SELECT code FROM metric_registry WHERE code LIKE 'data_arrival_%'"
+    )).fetchall()
+    for (code,) in rows:
+        conn.execute(sa.text("DELETE FROM alert_rules WHERE metric_code=:c"), {"c": code})
+        conn.execute(sa.text("DELETE FROM metric_thresholds WHERE metric_code=:c"), {"c": code})
+        conn.execute(sa.text("DELETE FROM metric_daily_snapshots WHERE metric_code=:c"), {"c": code})
+        conn.execute(sa.text("DELETE FROM metric_registry WHERE code=:c"), {"c": code})

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/c7d8e9f0a1b2_add_refunds_actual_refund_time.py

@@ -0,0 +1,35 @@
+"""add refunds actual_refund_time (A路实际扣款时间, E路回填, 对账用)
+
+Revision ID: c7d8e9f0a1b2
+Revises: b6c7d8e9f0a1
+Create Date: 2026-09-09 15:55:00.000000
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'c7d8e9f0a1b2'
+down_revision: Union[str, None] = 'b6c7d8e9f0a1'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """refunds 新增 actual_refund_time(线上直退实际扣款时间)。
+
+    2026-09-09 对账时间对齐: A(线上直退)按 platform_order_no 在 E(refund_record_reports)
+    唯一匹配回填其 refund_time; 对账/现金流按此归日消除 created_at_raw 跨日边界错位。
+    """
+    op.add_column('refunds', sa.Column(
+        'actual_refund_time', sa.DateTime(timezone=True), nullable=True,
+        comment='实际扣款时间(E路refund_time按platform_order_no回填, 对账用; 创建时间=created_at_raw不变)'
+    ))
+    op.create_index('ix_refunds_actual_refund_time', 'refunds', ['actual_refund_time'])
+
+
+def downgrade() -> None:
+    """回滚: 删列"""
+    op.drop_index('ix_refunds_actual_refund_time', table_name='refunds')
+    op.drop_column('refunds', 'actual_refund_time')

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/c9d8e7f6a5b4_create_cash_flow_wide.py

@@ -0,0 +1,67 @@
+"""create cash_flow_wide table
+
+Revision ID: c9d8e7f6a5b4
+Revises: 8a7b6c5d4e3f
+Create Date: 2026-09-08 18:50:00.000000
+
+背景(A-20260908-004 LOCKED):
+现金流水统一宽表 cash_flow_wide —— ABCD 经营四路每笔出款统一物化, 路别列 route,
+服务对账(A+B+C+D vs E)/快速响应/运营多维分析。E(refund_record_reports)不进本表。
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'c9d8e7f6a5b4'
+down_revision: Union[str, None] = '8a7b6c5d4e3f'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'cash_flow_wide',
+        sa.Column('id', sa.BigInteger(), autoincrement=True, nullable=False),
+        sa.Column('route', sa.String(length=1), nullable=False, comment='路线: A=线上直退/B=钱包提现/C=闪猫退款/D=手动退款'),
+        sa.Column('biz_no', sa.String(length=128), nullable=True, comment='业务单号(各表最强键,尽力而为)'),
+        sa.Column('src_id', sa.String(length=128), nullable=False, comment='来源表主键(精确定位回源)'),
+        sa.Column('pay_time', sa.DateTime(timezone=True), nullable=True, comment='出款时间(各路口径归一)'),
+        sa.Column('pay_amount', sa.Numeric(precision=12, scale=2), nullable=True, comment='出款金额(各路口径归一)'),
+        sa.Column('device_sn', sa.String(length=64), nullable=True, comment='设备SN'),
+        sa.Column('operator', sa.String(length=64), nullable=True, comment='操作人(归一别名)'),
+        sa.Column('e_key', sa.String(length=128), nullable=True, comment='对账键(A=platform_order_no等)'),
+        sa.Column('e_matched', sa.Boolean(), nullable=True, comment='该笔是否在E有匹配(True/False/None弱关联)'),
+        sa.Column('reason', sa.String(length=255), nullable=True, comment='退款原因'),
+        sa.Column('merchant', sa.String(length=128), nullable=True, comment='商户名称'),
+        sa.Column('package', sa.String(length=128), nullable=True, comment='套餐名称'),
+        sa.Column('has_external_complaint', sa.Boolean(), server_default=sa.text('false'), nullable=False, comment='该SN是否有外部投诉'),
+        sa.Column('auditor', sa.String(length=64), nullable=True, comment='审核人/登记人'),
+        sa.Column('matched_at', sa.DateTime(timezone=True), nullable=False, 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_cash_flow_wide_route', 'cash_flow_wide', ['route'])
+    op.create_index('ix_cash_flow_wide_pay_time', 'cash_flow_wide', ['pay_time'])
+    op.create_index('ix_cash_flow_wide_device_sn', 'cash_flow_wide', ['device_sn'])
+    op.create_index('ix_cash_flow_wide_src_id', 'cash_flow_wide', ['src_id'])
+    op.create_index('ix_cash_flow_wide_biz_no', 'cash_flow_wide', ['biz_no'])
+    op.create_index('ix_cash_flow_wide_e_key', 'cash_flow_wide', ['e_key'])
+    op.create_index('ix_cash_flow_wide_operator', 'cash_flow_wide', ['operator'])
+    op.create_index('ix_cash_flow_wide_merchant', 'cash_flow_wide', ['merchant'])
+    op.create_index('ix_cash_flow_wide_has_external_complaint', 'cash_flow_wide', ['has_external_complaint'])
+
+
+def downgrade() -> None:
+    op.drop_index('ix_cash_flow_wide_has_external_complaint', table_name='cash_flow_wide')
+    op.drop_index('ix_cash_flow_wide_merchant', table_name='cash_flow_wide')
+    op.drop_index('ix_cash_flow_wide_operator', table_name='cash_flow_wide')
+    op.drop_index('ix_cash_flow_wide_e_key', table_name='cash_flow_wide')
+    op.drop_index('ix_cash_flow_wide_biz_no', table_name='cash_flow_wide')
+    op.drop_index('ix_cash_flow_wide_src_id', table_name='cash_flow_wide')
+    op.drop_index('ix_cash_flow_wide_device_sn', table_name='cash_flow_wide')
+    op.drop_index('ix_cash_flow_wide_pay_time', table_name='cash_flow_wide')
+    op.drop_index('ix_cash_flow_wide_route', table_name='cash_flow_wide')
+    op.drop_table('cash_flow_wide')

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/d4e5f6a7b8c9_fix_data_arrival_exclude_on_demand_sources.py

@@ -0,0 +1,47 @@
+"""fix_data_arrival_exclude_on_demand_sources
+
+修正 data_arrival 源发现: 排除"按需/低频"源(shanmao_refund)。
+
+背景: c2d3e4f5a6b7 的 _active_fetch_sources 读 sync_source_configs.default_sync,
+但该字段可能被用户改(生产 shanmao_refund 被改成 true), 而代码种子
+BMS_DATA_SOURCES 中 shanmao_refund 是 default_sync=False + requires_captcha=True
+(按需手动触发, 非每日必跑)。导致 shanmao_refund 被误纳入"每日必达"监控 →
+每日 no_arrival 误报。
+
+修复: 停用 data_arrival_shanmao_refund 指标与规则(每日必达监控只覆盖代码种子
+default_sync=True 的 refund/ticket/wallet/cs_record + 被动推送源)。
+
+Revision ID: d4e5f6a7b8c9
+Revises: c2d3e4f5a6b7
+Create Date: 2026-09-04 17:30:00.000000
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'd4e5f6a7b8c9'
+down_revision: Union[str, None] = 'c2d3e4f5a6b7'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+# 按需/低频源(非每日必跑): 代码种子 BMS_DATA_SOURCES default_sync=False 或
+# requires_captcha=True 的主动抓取源, 不应纳入"每日到达"严格监控
+ON_DEMAND_FETCH_SOURCES = {"shanmao_refund"}
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    for dt in ON_DEMAND_FETCH_SOURCES:
+        code = f"data_arrival_{dt}"
+        conn.execute(sa.text("UPDATE metric_registry SET enabled=false WHERE code=:c"), {"c": code})
+        conn.execute(sa.text("UPDATE alert_rules SET enabled=false WHERE metric_code=:c"), {"c": code})
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    for dt in ON_DEMAND_FETCH_SOURCES:
+        code = f"data_arrival_{dt}"
+        conn.execute(sa.text("UPDATE metric_registry SET enabled=true WHERE code=:c"), {"c": code})
+        conn.execute(sa.text("UPDATE alert_rules SET enabled=true WHERE metric_code=:c"), {"c": code})

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/d8e9f0a1b2c3_add_quality_fields_to_complaint_tables.py

@@ -0,0 +1,104 @@
+"""add quality fields to complaint tables (#42)
+
+Revision ID: d8e9f0a1b2c3
+Revises: c7d8e9f0a1b2
+Create Date: 2026-09-10 12:25:00.000000
+
+背景(#42, 2026-09-10):
+  治理框架(A-20260908-003 拒收行 / A-20260909-001 治理闭环)覆盖了退款四路
+  (refund/shanmao_refund/ticket/wallet 继承 QualityMixin, manual_refund 内联同名字段),
+  但**投诉两表 external_complaints / card_complaints 没有质量字段** →
+  入库前校验(ingest_validator)发现的问题无处落标, 无法进入质量页治理队列。
+
+本次为两表补 QualityMixin 的 2 列(与既有表完全同口径, 不引入新语义):
+  quality_status  String(16)  索引    None=正常 / ok / auto_fixed / pending /
+                                      dup_residual / ignored
+  quality_note    String(512)          质量说明(含原始值)
+
+⚠️ 纯加列(可空, 无默认), 对既有数据与统计**零影响**:
+  - 统计排除口径 COALESCE(quality_status,'') NOT IN ('dup_residual','ignored'),
+    存量行均为 NULL → 全部保持纳入。
+  - 打标(pending 等)由后续接入(本期仅建列, 不自动打标, 避免误标)。
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'd8e9f0a1b2c3'
+down_revision: Union[str, None] = 'c7d8e9f0a1b2'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+_TABLES = ('external_complaints', 'card_complaints')
+
+
+def _column_exists(table_name: str, column_name: str) -> bool:
+    """列存在性检查(幂等升级规范, 见 alembic-migration管理规范.md §五)
+
+    已有表环境可能由 Base.metadata.create_all() 建表(含新列), 直接 add_column 会报
+    DuplicateColumn → 必须先查 information_schema。
+    限定 table_schema='public' 避免多 schema 同名表产生假阳性(审查 N-5)。
+    """
+    conn = op.get_bind()
+    return bool(conn.execute(sa.text(
+        "SELECT EXISTS(SELECT 1 FROM information_schema.columns "
+        "WHERE table_schema = 'public' AND table_name = :t AND column_name = :c)"
+    ), {"t": table_name, "c": column_name}).scalar())
+
+
+def _index_exists(index_name: str) -> bool:
+    """索引存在性检查(幂等; 限定 schemaname='public', 审查 N-5)"""
+    conn = op.get_bind()
+    return bool(conn.execute(sa.text(
+        "SELECT EXISTS(SELECT 1 FROM pg_indexes "
+        "WHERE schemaname = 'public' AND indexname = :i)"
+    ), {"i": index_name}).scalar())
+
+
+def upgrade() -> None:
+    """投诉两表补 quality_status / quality_note(幂等: 已存在则跳过)"""
+    for table in _TABLES:
+        if not _column_exists(table, 'quality_status'):
+            op.add_column(
+                table,
+                sa.Column(
+                    'quality_status',
+                    sa.String(length=16),
+                    nullable=True,
+                    comment=(
+                        '数据质量状态: None=正常 / ok=已人工确认 / auto_fixed=已自动纠错 / '
+                        'pending=待人工确认 / dup_residual=已治理重复(排除) / ignored=人工彻底忽略(排除)'
+                    ),
+                ),
+            )
+        if not _column_exists(table, 'quality_note'):
+            op.add_column(
+                table,
+                sa.Column(
+                    'quality_note',
+                    sa.String(length=512),
+                    nullable=True,
+                    comment='质量说明(自动纠错或待确认原因, 含原始值)',
+                ),
+            )
+        idx = f'ix_{table}_quality_status'
+        if not _index_exists(idx):
+            op.create_index(idx, table, ['quality_status'])
+
+
+def downgrade() -> None:
+    """回退: 删索引与两列(幂等)
+
+    ⚠️ 降级会物理删除两列 → 已写入的治理状态(pending/ok/auto_fixed 等)一并丢失且不可恢复。
+    如需降级, 请先自行导出非空 quality_status/quality_note 作为备份。
+    """
+    for table in _TABLES:
+        idx = f'ix_{table}_quality_status'
+        if _index_exists(idx):
+            op.drop_index(idx, table_name=table)
+        if _column_exists(table, 'quality_note'):
+            op.drop_column(table, 'quality_note')
+        if _column_exists(table, 'quality_status'):
+            op.drop_column(table, 'quality_status')

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/e0f1a2b3c4d5_create_ingest_rejected_rows.py

@@ -0,0 +1,55 @@
+"""create ingest_rejected_rows table
+
+Revision ID: e0f1a2b3c4d5
+Revises: c9d8e7f6a5b4
+Create Date: 2026-09-08 19:15:00.000000
+
+背景(A-20260908-003 LOCKED):
+外部数据统一质量治理 —— 承接所有入口"从未进业务表"的未采纳行,
+按行显示 + 人工判定(open/keep/discard), 未判定/不处理默认不纳入统计。
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = 'e0f1a2b3c4d5'
+down_revision: Union[str, None] = 'c9d8e7f6a5b4'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'ingest_rejected_rows',
+        sa.Column('id', sa.BigInteger(), autoincrement=True, nullable=False),
+        sa.Column('data_type', sa.String(length=64), nullable=False, comment='目标业务表类型'),
+        sa.Column('source', sa.String(length=32), nullable=False, comment='入口标识'),
+        sa.Column('source_ref', sa.String(length=128), nullable=True, comment='溯源'),
+        sa.Column('source_row_no', sa.Integer(), nullable=True, comment='源文件/批次内行号'),
+        sa.Column('reject_category', sa.String(length=32), nullable=False, comment='拒因分类'),
+        sa.Column('reject_reason', sa.Text(), nullable=True, comment='人读原因'),
+        sa.Column('raw_row', sa.dialects.postgresql.JSONB(), nullable=True, comment='原始整行'),
+        sa.Column('business_key', sa.String(length=128), nullable=True, comment='业务键'),
+        sa.Column('status', sa.String(length=16), server_default='open', nullable=False, comment='人工状态: open/keep/discard'),
+        sa.Column('reviewed_by', sa.String(length=64), nullable=True, comment='判定人'),
+        sa.Column('reviewed_at', sa.DateTime(timezone=True), 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_ingest_rejected_rows_data_type', 'ingest_rejected_rows', ['data_type'])
+    op.create_index('ix_ingest_rejected_rows_source', 'ingest_rejected_rows', ['source'])
+    op.create_index('ix_ingest_rejected_rows_reject_category', 'ingest_rejected_rows', ['reject_category'])
+    op.create_index('ix_ingest_rejected_rows_status', 'ingest_rejected_rows', ['status'])
+    op.create_index('ix_ingest_rejected_rows_business_key', 'ingest_rejected_rows', ['business_key'])
+
+
+def downgrade() -> None:
+    op.drop_index('ix_ingest_rejected_rows_business_key', table_name='ingest_rejected_rows')
+    op.drop_index('ix_ingest_rejected_rows_status', table_name='ingest_rejected_rows')
+    op.drop_index('ix_ingest_rejected_rows_reject_category', table_name='ingest_rejected_rows')
+    op.drop_index('ix_ingest_rejected_rows_source', table_name='ingest_rejected_rows')
+    op.drop_index('ix_ingest_rejected_rows_data_type', table_name='ingest_rejected_rows')
+    op.drop_table('ingest_rejected_rows')