# 投顾 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 未丢失以及没有产生真实交易委托。