first commit

docs/operations.md

@@ -0,0 +1,81 @@
+# 运维与排障手册（业务视角）
+
+本文档聚焦两件事：
+- 出错时先看哪里。
+- 日志里的状态到底代表什么业务问题。
+
+## 1. 先看什么（快速定位）
+
+1. 看运行日志（`sync_log`）：
+	 - 重点关注 `状态机流转`、`reason=`、`depends=[...]`。
+2. 看持久化数据库：
+	 - 重点字段：`binding_status`、`action`、`status`、`error`。
+3. 对照状态机文档：
+	 - `docs/state_machine.md`
+	 - `docs/node_state_definition.md`
+
+## 2. 阶段化排障
+
+### 2.1 bind 阶段
+
+常见表现：节点停在 `S03/S04/S05/S13`。
+
+- `S03(ABNORMAL)`：节点数据损坏或核心绑定异常。
+- `S04(WARNING)`：自动绑定关闭、键缺失、歧义等不可自动处理情况。
+- `S05(DEPENDENCY_ERROR)`：依赖节点不存在或依赖状态不正常。
+- `S13(PEER_CREATING)`：对侧创建进行中，尚未提交完成。
+
+典型日志：
+- `reason=依赖项不满足 | depends=[company_id status=peer_creating -> not_normal]`
+
+业务解释：
+- 上游依赖还没进入 `NORMAL`，下游业务会被严格阻断。
+
+### 2.2 create 阶段
+
+常见表现：节点长时间停在 `S13` 或 `S10C`。
+
+- `S13`：已判定需要创建，但创建提交未完成。
+- `S10C`：CREATE 异步执行中。
+- `S12C`：CREATE 失败。
+
+优先检查：
+- API 侧是否返回任务 ID 与成功回执。
+- 轮询参数（`poll_max_retries` / `poll_interval`）是否过小。
+
+### 2.3 update 阶段
+
+常见表现：节点进入 `S08` 或 `S12U`。
+
+- `S08(PRECONDITION_FAILED)`：前置条件失败（如缺 data_id、依赖 ID 解析失败）。
+- `S12U`：UPDATE 调用失败。
+- `S14`：UPDATE 被 handler 降级为 NONE 并跳过。
+
+优先检查：
+- `update_direction` 是否符合预期。
+- 目标节点是否具备 `data_id`。
+
+## 3. 常见配置误区与症状
+
+- `auto_bind=false`
+	- 症状：MISSING 节点更容易进入 `WARNING`，不会走自动创建识别。
+- `skip_sync=true`
+	- 症状：该类型只加载不执行 bind/create/update，常被误以为“没生效”。
+- `load_mode=persisted_only`
+	- 症状：数据只来自持久化，不主动拉取新数据。
+- `update_direction=none`
+	- 症状：不做 update，即使有差异也不会提交更新。
+
+## 4. 推荐操作顺序
+
+1. 先用 `run_profiles/preset/jsonl_to_jsonl.default.yaml` 跑通基线。
+2. 再切到 `run_profiles/*.local.yaml` 做最小覆盖。
+3. 每次只改一类字段（比如只改 `project` 的依赖策略）。
+4. 改完看一次 `sync_log`，确认状态流转与预期一致。
+
+## 5. UI 排障（可选）
+
+1. 启动：`python -m ui.main --host 127.0.0.1 --port 8765`
+2. 打开：`http://127.0.0.1:8765`
+3. 在“运行与日志”查看实时状态变化。
+4. 在“记录与数据库”检查节点状态与绑定记录。