feat: add advisor rollout gate and rollback playbook

docs/21-投顾Agent迁移TODO.md

@@ -53,7 +53,7 @@ R4=7、R5=1；资产分类成功 18 个，1 个因合同证据不足跳过。每
 R1-R5 适当性硬过滤和排除原因。权威数据验收仍保留两个限制：R1/R5 尚不足四个
 测试产品，1 个产品因合同证据不足未完成资产分类；完整推荐侧联动留待阶段十。
 阶段五测试结果：专项 `7 passed`，全量单元测试 `473 passed, 3 warnings`，Ruff 和
-MyPy 通过。阶段五提交：待提交。
+MyPy 通过。阶段五核心提交：`291cb7b`、`47a5ca4`。
 
 ### 阶段六：开户风险问卷
 
@@ -78,7 +78,7 @@ Agent 暴露客户最新的 `confirmed` 目标，未确认目标不会进入后
 目标书含收益非承诺、非交易指令披露；写操作统一使用 `Idempotency-Key` 并写入审计。
 
 阶段七测试结果：专项测试 `5 passed`，全量单元测试 `468 passed, 3 warnings`，Ruff
-通过，MyPy（122 个源文件）通过。阶段七提交：待提交。
+通过，MyPy（122 个源文件）通过。阶段七提交：`60c4a49`。
 
 ### 阶段八：持仓分析
 
@@ -90,7 +90,7 @@ Agent 暴露客户最新的 `confirmed` 目标，未确认目标不会进入后
 异常时明确降级，不影响 MySQL 数值分析。
 
 阶段八测试结果：图谱与持仓专项测试 `8 passed`，全量单元测试 `475 passed, 3 warnings`，Ruff
-通过，MyPy（127 个源文件）通过。阶段八核心提交：待提交。
+通过，MyPy（127 个源文件）通过。阶段八核心提交：`281e76e`、`8ffd08b`。
 
 阶段九已完成动态资产配置与真实历史回测：接入 C1-C5 基础权重、收益目标、最大回撤、
 流动性和投资期限约束，读取经适当性、合同证据、资产分类和数据质量门槛过滤的场内基金
@@ -165,7 +165,14 @@ Redis 不可用时实测按设计降级放行；生产装配模式因本机 Milv
 及恢复关闭，成功行情按字段精度量化后写入场内行情快照。真实独立库同步验证两源均失败时返回
 `degraded=true`、不写入伪行情并进入失败告警链路；本次无可用行情，推荐和动态配置继续失败关闭。
 专项测试 `6 passed`，全量单元测试 `499 passed，3 warnings`，契约测试 `8 passed`，Ruff 和 MyPy
-通过。实现提交：`2376585`。
+通过。实现提交：`2376585`；命令入口提交：`fbb1171`。
+
+本次继续完成灰度闸门和回滚手册：新增 `AdvisorRolloutService`，由环境变量控制投顾灰度，
+开启后管理员放行、客户按白名单放行，未命中返回 `403 AGENT_PERMISSION_DENIED` 并写入
+`advisor.rollout_denied` 审计；已接入投顾业务路由和 `advisor` Agent 运行入口。新增操作手册
+`docs/22-投顾Agent灰度与回滚操作手册.md`。专项测试 `4 passed`，全量单元测试 `505 passed，
+3 warnings`，Ruff 和 MyPy（146 个源文件）通过。实现提交：`b3a0ee7`。生产/联调环境的
+实际灰度与回滚演练仍待执行。
 
 ## 一、迁移准备
 
@@ -204,16 +211,16 @@ python -m mypy app
 
 ## 三、公共底座适配
 
-- [ ] 阅读并记录 `app/core/contracts.py` 的请求和响应契约。
-- [ ] 阅读并记录 `app/core/errors.py` 的错误码和错误信封。
-- [ ] 确认 JWT 鉴权和 RBAC 解析流程。
-- [ ] 确认 `BaseAgent` 的标准执行流程。
-- [ ] 确认 `AgentFactory` 的 Agent 注册方式。
-- [ ] 确认 `ToolExecutor` 的工具鉴权和角色限制。
-- [ ] 确认模型路由、模型降级和超时处理方式。
-- [ ] 确认 Redis、Milvus、Neo4j 的接入方式。
-- [ ] 确认记忆抽取、召回、生命周期和 Episode 聚合流程。
-- [ ] 确认 Worker 注册和事件消费方式。
+- [x] 阅读并记录 `app/core/contracts.py` 的请求和响应契约。
+- [x] 阅读并记录 `app/core/errors.py` 的错误码和错误信封。
+- [x] 确认 JWT 鉴权和 RBAC 解析流程。
+- [x] 确认 `BaseAgent` 的标准执行流程。
+- [x] 确认 `AgentFactory` 的 Agent 注册方式。
+- [x] 确认 `ToolExecutor` 的工具鉴权和角色限制。
+- [x] 确认模型路由、模型降级和超时处理方式。
+- [x] 确认 Redis、Milvus、Neo4j 的接入方式。
+- [x] 确认记忆抽取、召回、生命周期和 Episode 聚合流程。
+- [x] 确认 Worker 注册和事件消费方式。
 - [x] 适配投顾 Agent 的公共请求和响应结构。（复用 `BaseAgent` 和 `AgentRequest/CoreResult`）
 - [x] 适配投顾工具注册。（复用 `query_fund_quote` 只读工具）
 - [x] 适配投顾 Agent 的 `AgentDefinition`。（新增 `advisor`，版本 `0.1.0`）
@@ -259,7 +266,7 @@ python -m mypy app
 - [ ] 在已有测试库执行迁移。
 - [x] 执行数据库结构审计。（72 张业务表，无缺失或多余）
 - [x] 执行数据库约束审计。（唯一键与 ORM 映射通过）
-- [ ] 完成数据库迁移提交 `advisor/database-migrations`。（待提交）
+- [x] 完成数据库迁移提交 `advisor/database-migrations`。（`9ed536e`）
 
 验收命令：
 
@@ -475,7 +482,7 @@ python tools/audit_constraints.py
 
 ## 十三、全端测试
 
-- [x] 执行全部单元测试。（`491 passed, 3 warnings`，Python 3.13）
+- [x] 执行全部单元测试。（`505 passed, 3 warnings`，Python 3.13）
 - [x] 执行全部契约测试。（`8 passed`，Python 3.13）
 - [x] 执行全部集成测试。（独立迁移库 `28 passed, 1 skipped`；原 `jr_agent` 为 `25 passed, 3 failed, 1 skipped`，失败均为历史库状态）
 - [x] 执行 Ruff 检查。（通过）
@@ -516,9 +523,9 @@ python tools/audit_constraints.py
 
 ## 十四、灰度发布
 
-- [ ] 在本地测试库完成迁移。
+- [x] 在本地测试库完成迁移。（独立库 `jr_agent_qyqy_migration` 已验证）
 - [ ] 在联调库完成迁移。
-- [ ] 仅开放测试客户和管理员账号。
+- [x] 仅开放测试客户和管理员账号。（代码闸门已完成，环境实测待执行）
 - [ ] 灰度产品查询和适当性过滤。
 - [ ] 灰度风险问卷。
 - [ ] 灰度投资目标。
@@ -533,17 +540,17 @@ python tools/audit_constraints.py
 
 ## 十五、回滚准备
 
-- [ ] 保存迁移前数据库备份。
-- [ ] 保存迁移前 Git 标签。
-- [ ] 保存每个模块的提交号。
-- [ ] 保存每个模块的测试结果。
-- [ ] 保存迁移后的结构审计结果。
-- [ ] 准备关闭新投顾入口的配置开关。
-- [ ] 准备应用代码按提交回滚方案。
-- [ ] 确认数据库不执行破坏性 downgrade。
-- [ ] 确认新增表保留，不自动删除。
-- [ ] 确认失败 Outbox 可以重试或人工处理。
-- [ ] 确认原画像和原推荐结果可以保留。
+- [x] 保存迁移前数据库备份。（`.migration-backups/jr_agent-before-base-migration.sql`）
+- [x] 保存迁移前 Git 标签。（`advisor-before-base-migration`）
+- [x] 保存每个模块的提交号。（已回填阶段记录）
+- [x] 保存每个模块的测试结果。（已回填阶段记录）
+- [x] 保存迁移后的结构审计结果。（独立迁移库 72 张业务表）
+- [x] 准备关闭新投顾入口的配置开关。（`ADVISOR_ROLLOUT_ENABLED=false`）
+- [x] 准备应用代码按提交回滚方案。（见 `docs/22-投顾Agent灰度与回滚操作手册.md`）
+- [x] 确认数据库不执行破坏性 downgrade。（见回滚手册）
+- [x] 确认新增表保留，不自动删除。（见回滚手册）
+- [x] 确认失败 Outbox 可以重试或人工处理。（沿用公共 Outbox 重试/死信机制）
+- [x] 确认原画像和原推荐结果可以保留。（回滚只关闭入口，不删除业务数据）
 - [ ] 完成灰度回滚演练。
 
 ## 十六、最终完成标准

docs/22-投顾Agent灰度与回滚操作手册.md

@@ -0,0 +1,42 @@
+# 投顾 Agent 灰度与回滚操作手册
+
+## 灰度开关
+
+投顾灰度使用进程环境变量，不修改冻结的数据库基线，也不需要数据库迁移：
+
+```text
+ADVISOR_ROLLOUT_ENABLED=true
+ADVISOR_ROLLOUT_CUSTOMER_IDS=9001,9002
+```
+
+`ADVISOR_ROLLOUT_ENABLED=false` 时保持现有本地行为。开启后，`admin` 和
+`super_admin` 始终放行；客户只有在 `ADVISOR_ROLLOUT_CUSTOMER_IDS` 中才可以访问
+投顾 Agent、投资目标、持仓分析、资产配置和推荐接口。白名单为空时客户全部失败关闭，
+不会误放量。灰度拒绝统一返回 `403 AGENT_PERMISSION_DENIED`，并写入
+`interaction_audit.action_type=advisor.rollout_denied`。
+
+修改环境变量后必须重启全部 API 进程和 Worker，确保同一发布批次使用同一开关快照。
+上线前先用一名测试客户和一名管理员验证：客户白名单命中返回业务响应，未命中返回 403，
+管理员可以完成审核/发布操作；检查审计记录中没有客户数据和内部画像字段泄露。
+
+## 灰度检查
+
+1. 在独立测试库执行 `python -m alembic upgrade head`、`python tools/audit_schema.py` 和
+   `python tools/audit_constraints.py`。
+2. 启动 API 和 Worker，执行 `python tools/acceptance_check.py`，确认问卷前置、鉴权、
+   SSE、Worker 完成态、越权和数据隔离均通过。
+3. 开启白名单后，用测试客户执行问卷、投资目标、持仓分析、资产配置、推荐及画像复核；
+   推荐无有效行情时必须保持失败关闭，不得写入伪行情或产生模拟委托。
+4. 记录 API 错误数、延迟、降级次数、行情失败告警和 `advisor.rollout_denied` 审计数。
+
+## 回滚
+
+优先将 `ADVISOR_ROLLOUT_ENABLED=false` 并滚动重启 API/Worker，关闭投顾灰度入口；已落库
+的问卷、目标、画像、推荐审核记录和 Outbox 事件保留，不删除业务数据。
+
+若需应用回滚，回到本分支上一个已验收提交，并重新执行单元、契约和结构审计。数据库不执行
+破坏性 `downgrade`，新增表保留；恢复后用 `alembic current` 和结构审计确认版本与结构一致。
+失败 Outbox 事件按原有重试/死信机制处理，必要时由管理员重放，不直接删除未完成事件。
+
+回滚演练必须记录：开关关闭时间、API/Worker 重启结果、客户 403 验证、管理员可用性、
+审计记录、Outbox 未丢失以及没有产生真实交易委托。