# 数据规则运行时运维手册

适用范围：数据标准与数据流程的自然语言规则编写、不可变规则/标准版本发布、
数据生产线发布，以及数据工厂中的 disabled 部署、canary、激活和回滚。

## 1. 不可越过的边界

- 自然语言和模型输出只存在于设计控制面；Runner 只接受服务端发布的
  `component_binding_id`、`execution_plan_hash` 和短期任务令牌。
- 数据标准和数据流程共用 `RuleVersion`、编译器和执行证据。标准条款固定到
  `StandardVersion`，数据流程发布时再冻结为 `DataFlowVersion` 包。
- 数据工厂只能绑定和投产已发布的 `DataFlowVersion`。不得修改自然语言、
  `RuleSpec`、规则顺序或重新编译业务语义；语义变化必须回到设计态创建新版本。
- `DATA_FACTORY_ACTIVATION_ENABLED` 默认关闭。只有本手册的发布门禁通过后，
  才能在目标环境显式设为 `true`。
- 不允许内联 SQL、Python、凭据、对象存储正文或数据样本。首期仅执行封闭
  SQL/Polars 计划；生成 Python 不在激活路径内。

## 2. 依赖与健康检查

本地验收栈至少包含 PostgreSQL、Neo4j、MinIO、Kestra、Runner、Backend 和
Frontend。执行：

```bash
docker compose -f deploy/docker/docker-compose.yml ps
curl -fsS http://127.0.0.1:15500/health
curl -fsS http://127.0.0.1:15600/health
curl -fsS http://127.0.0.1:18080/api/v1/health
curl -fsS http://127.0.0.1:19000/minio/health/live
```

继续部署前应确认：

1. Alembic 已在目标 revision，且没有待执行迁移。
2. 数据源定义可解析，但日志和请求中没有凭据。
3. MinIO 规则制品桶可读写，过期清理器可运行。
4. Kestra namespace 与 DataOps 环境一致。
5. `/api/rules/capabilities` 对未通过门禁的环境仍返回
   `data_factory_activation=false`。

## 3. 识别一个生产线版本

排障和变更单必须同时记录：

- `rule_version_id`、`rule_spec_hash`、模型/Prompt/上下文/候选 Hash；
- `standard_version_id` 与固定的规则版本；
- `dataflow_version_id`、`package_hash`；
- `deployment_id`、`binding_hash`、`schema_snapshot_hash`；
- 每个 `execution_plan_hash`；
- `workflow_spec_hash`、`schedule_hash`、`engine_definition_hash`；
- correlation ID、Kestra execution ID 和 Runner rule run ID。

任一 Hash 与部署快照不一致时必须停止激活，不能现场重新生成或“修复”计划。

## 4. 受治理的发布和投产

以下命令中的令牌、ID 和幂等键均由调用方安全注入；示例不包含凭据。

```bash
# 能力检查
curl -fsS -H "Authorization: Bearer $DATAOPS_OPERATOR_TOKEN" \
  http://127.0.0.1:15500/api/rules/capabilities

# disabled 部署
curl -fsS -X POST \
  -H "Authorization: Bearer $DATAOPS_OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  http://127.0.0.1:15500/api/rules/deployments/$DEPLOYMENT_ID/deploy-disabled \
  -d '{"idempotency_key":"change-id:deploy","reason":"approved change"}'

# canary
curl -fsS -X POST \
  -H "Authorization: Bearer $DATAOPS_OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  http://127.0.0.1:15500/api/rules/deployments/$DEPLOYMENT_ID/canary \
  -d '{"idempotency_key":"change-id:canary","reason":"approved canary"}'

# 激活
curl -fsS -X POST \
  -H "Authorization: Bearer $DATAOPS_ACTIVATOR_TOKEN" \
  -H "Content-Type: application/json" \
  http://127.0.0.1:15500/api/rules/deployments/$DEPLOYMENT_ID/activate \
  -d '{"idempotency_key":"change-id:activate","reason":"canary passed"}'

# 回滚到部署快照记录的上一 active 版本
curl -fsS -X POST \
  -H "Authorization: Bearer $DATAOPS_ROLLBACK_TOKEN" \
  -H "Content-Type: application/json" \
  http://127.0.0.1:15500/api/rules/deployments/$DEPLOYMENT_ID/rollback \
  -d '{"idempotency_key":"incident-id:rollback","reason":"incident rollback"}'
```

不要复用别的操作者、动作或业务原因的幂等键。响应丢失或外部状态不明时，先调用对应
`reconcile-deploy`、`reconcile-activate` 或 `reconcile-rollback`，不得换键重试。

## 5. Canary 判定

Canary 只有同时满足下列条件才算通过：

- package、binding、schema snapshot、物理计划、工作流、调度和引擎定义 Hash
  与部署快照完全一致；
- SQL/Polars 执行成功，输入、输出、拒绝、隔离数量可对账；
- 违规样本已脱敏、数量有上限、TTL 有效；
- 写入结果为明确 `committed` 或明确 `rolled_back`，不能是 `unknown`；
- 没有计划撤销、Schema drift、过期制品、令牌重放或连接池超预算；
- canary 证据尚未过期，且由有权限的主体确认。

## 6. 证据查询与保留

- 规则版本的编译/测试证据：
  `/api/rules/rule-versions/{id}/evidence`。
- 目录资产证据：
  `/api/rules/catalog/assets/{asset_type}/{id}/evidence`。
- Runner 的 `rule_runs` 记录执行状态、计数、计划 Hash、提交结果和 correlation ID。
- `rule_violation_samples` 只保存脱敏且有界的引用，不保存秘密或完整敏感行。
- `rule_artifacts` 保存 digest、Schema、行数、大小、过期时间和 MinIO 引用。

过期清理必须同时删除目录行和服务端拥有的 MinIO 对象，并按 correlation 范围执行。
业务数据、非规则前缀对象或未过期制品不得被清理。

## 7. 故障处置

| 故障域 | 先检查 | 处置 |
|---|---|---|
| 模型 | Provider 健康、超时、模型/Prompt Hash、歧义与置信度 | 不执行未验证输出；允许有界确定性修复，仍失败则请求澄清或切换已批准模型 |
| 编译器 | 算子/方言支持、Schema Hash、计划状态 | 不允许 best-effort 改义；回到设计态修改并发布新版本 |
| Runner | 任务令牌、计划 Hash、lease/heartbeat、提交结果 | 重放令牌直接拒绝；`unknown` 先对账和 reconcile，不能盲目重跑 |
| 数据源 | 定义版本、secret reference、连接池、Schema drift | 轮换凭据只改秘密存储；重新绑定/发布，不把凭据放入请求 |
| MinIO | digest、TTL、Schema、对象所有权、大小限制 | 损坏或过期制品拒绝读取；从上游受治理节点重建 |
| Kestra | Flow Hash、execution、disabled/active 状态 | 重启后按服务端快照 reconcile；不得直接在 Kestra UI 修改业务 Flow |
| 写入 | 幂等策略、目标唯一键、commit outcome | 明确失败可按策略重试；未知提交结果先查目标与 ledger |

紧急回滚仍必须走受治理 API。若激活/回滚操作 lease 丢失，旧操作者不得补偿新 owner
的 Flow；先恢复或对账持久化 operation，再继续。

## 8. 验收命令

```bash
PYTHONPATH=. .venv/bin/pytest -q tests/core/data_rules tests/runner
PYTHONPATH=. .venv/bin/pytest -q \
  tests/integration/test_data_rule_sql_execution.py \
  tests/integration/test_data_rule_polars_execution.py \
  tests/integration/test_data_factory_postgres_lifecycle.py
PYTHONPATH=. .venv/bin/pytest -q \
  tests/e2e/test_ai_rule_to_data_product.py \
  tests/performance/test_rule_execution_capacity.py
npm --prefix frontend run build
```

容量证据位于 `docs/validation/data-rule-m5-capacity-evidence.json`，真实本地模型证据位于
`docs/acceptance/data-rule/real-qwen-authoring-evidence.json`。两者均不包含凭据、
完整 Prompt 或数据样本。