docs: capture mainland result sync prerequisite

2026-04-19 02:44:30 +08:00
parent 6c4e995f84
commit 3a55db94f8
3 changed files with 269 additions and 165 deletions
--- a/docs/ops_center_runtime/HANDOFF_20260419_0243.md
+++ b/docs/ops_center_runtime/HANDOFF_20260419_0243.md
@@ -0,0 +1,135 @@
+# HANDOFF 2026-04-19 02:43
+
+## 本轮完成了什么
+
+本轮只做了一件事：
+
+- 把 `I1-检测结果逐条回写设计批` 查到底，确认当前是否真的能做 item 级统一
+
+实际结论：
+
+- 现在还不能直接做 item 级回写
+
+## 本轮关键证据
+
+### 证据 1：`detect_result_projection` 只有聚合数据
+
+当前只包含：
+
+- `job`
+- `latest_event`
+- `queue`
+- `phase`
+
+没有：
+
+- `domain_id`
+- `job_item_id`
+- 逐条终态结果
+
+### 证据 2：中央 `detect_run_events` 的逐条结果只有海外
+
+当前中央看到的逐条事件只有：
+
+- `overseas-control-01`
+  - `domain_started`
+  - `domain_completed`
+
+中央没看到：
+
+- `mainland-controller-01`
+  - 无 `domain_*`
+- `mainland-worker-01`
+  - 无 `domain_*`
+
+### 证据 3：所以当前不能直接回写 `detect_job_items`
+
+原因不是逻辑不会写，而是中央没有大陆逐条输入。
+
+## 当前最高优先级
+
+唯一最高优先级：
+
+- `J1-大陆逐条结果同步前置批`
+
+原因：
+
+- item 级统一的真正阻塞点已经定位
+- 下一步必须先把大陆逐条结果送到中央
+
+## 当前状态结论
+
+当前可以明确说：
+
+- 检测能跑
+- 大陆节点确实参与了
+- 主统计已经统一
+- 但 item 级回写现在还做不了
+
+## 当前唯一剩余问题
+
+唯一剩余问题：
+
+- 大陆节点缺少逐条结果进入中央的最小同步通道
+
+所以当前阶段已经从：
+
+- “显示不对”
+
+进入到：
+
+- “逐条结果输入还没进中央”
+
+## 下一轮如果继续，只做什么
+
+下一轮只做这一件事：
+
+- 给大陆执行链补最小逐条结果同步输入
+
+优先原则：
+
+- 不发散
+- 不扩页面
+- 不碰发布动作
+
+## 推荐模型与推理等级
+
+继续推荐：
+
+- `GPT-5.4`
+- `high`
+
+原因：
+
+- 下一轮是同步链最小设计与落地
+- 还不必切超高
+
+## 给下一轮的任务卡
+
+```text
+任务名：J1-大陆逐条结果同步前置批
+
+目标：
+1. 让大陆节点把逐条检测终态送到中央
+2. 至少带回：
+   - job_code
+   - cycle_token
+   - domain_id 或可稳定映射的 domain
+   - result_status
+   - finished_at
+3. 只补输入通道，不做最终 item 回写
+
+范围限制：
+1. 不新增页面
+2. 不扩控制面功能
+3. 不进入发布动作
+4. 不并行做别的方向
+
+完成判定：
+1. 中央能看到 mainland 节点的 domain_* 终态事件或等价逐条投影
+2. 后续再做 detect_job_items 回写时，不再缺输入
+```
+
+## 一句话结论
+
+这轮已经把“为什么 item 级统一还做不了”彻底查清了；下一轮真正该做的，不是继续改统计，而是先把大陆逐条结果送进中央。
--- a/docs/ops_center_runtime/IMPLEMENTATION_STATUS.md
+++ b/docs/ops_center_runtime/IMPLEMENTATION_STATUS.md
@@ -1,6 +1,6 @@
 # IMPLEMENTATION_STATUS

-更新时间：2026-04-19 02:40 CST
+更新时间：2026-04-19 02:43 CST

 ## 当前真实状态

@@ -12,74 +12,50 @@

 本轮最重要的新事实：

- Detect 主统计口径已经从“双轨显示”推进到“统一后的有效账本”
- `detect/job/active` 和 `detect/queue-summary` 主字段已直接体现大陆 + 海外的统一聚合结果
- 原始中央账本仍完整保留，便于继续排障和审计
+- item 级统一当前不能继续直接推进
+- 根本原因已经查清：
+  - 大陆逐条结果目前没有进入中央

-## 本轮代码收口
+## 本轮结论收口

-本轮后端变更：
+本轮没有进入新实现扩展，而是完成了 `I1` 的证据闭环：

- `domain-api/app/services/detect_job_service.py`
+### 1. `detect_result_projection` 当前只有聚合信息

-本轮测试变更：
+当前 `projection.keys()` 为：

- `domain-api/tests/test_detect_job_service.py`
+- `job`
+- `latest_event`
+- `queue`
+- `phase`

-本轮修复方式：
+没有逐条结果：

- 保留中央 `detect_job_items` 原始值
- 引入“有效统一账本”：
-  - `node_stats`
-  - `items_pending`
-  - `items_claimed`
-  - `items_running`
-  - `items_completed`
-  - `items_failed`
-  - `items_terminal`
- 同时新增 `raw_*` 字段保留中央原始账本
+- 没有 `domain_id`
+- 没有 `job_item_id`
+- 没有终态域名列表

-## 关键验证证据
+### 2. 中央 `detect_run_events` 逐条结果只有海外节点

-接口验证：
+当前中央实际可见：

- `detect/job/active`
-  - 已统一为：
-    - `items_total = 1000`
-    - `items_pending = 931`
-    - `items_claimed = 34`
-    - `items_running = 14`
-    - `items_completed = 21`
-  - 原始账本仍可追溯：
-    - `raw_items_pending = 950`
-    - `raw_items_claimed = 25`
-    - `raw_items_running = 4`
-  - `node_stats` 已包含：
-    - `mainland-controller-01`
-    - `mainland-worker-01`
-    - `overseas-control-01`
-    - `unassigned`
- `detect/queue-summary`
-  - 已统一为：
-    - `pending = 931`
-    - `claimed = 34`
-    - `running = 14`
+- `overseas-control-01`
+  - `domain_started`
+  - `domain_completed`

-编译验证：
+当前中央不可见：

- `python3 -m py_compile domain-api/app/services/detect_job_service.py domain-api/tests/test_detect_job_service.py`
-  - 通过
+- `mainland-controller-01`
+  - 无 `domain_*`
+- `mainland-worker-01`
+  - 无 `domain_*`

-单测验证：
+### 3. 因此当前还做不了大陆 item 级回写

- `/opt/domaincheck/domainCheck/.venv/bin/python -m unittest tests.test_detect_job_service`
-  - 通过
+这不是简单 SQL 没补的问题，而是输入流还不存在：

-运行验证：
-
- `domaincheck-api`
-  - 已重启成功
- 线上接口返回统一账本字段正常
+- 中央不知道大陆到底是哪个域名完成了
+- 中央只知道大陆总体“参与了、跑了多少、当前多少 running”

 ## 当前已闭合的问题

@@ -87,44 +63,48 @@

 - 大陆 controller 无法 `pull_tasks`
 - Detect 页面误判“大陆没跑”
- Detect 节点表格只显示海外与 `unassigned`
- Detect 主统计仍依赖 display 附加字段才能看懂
+- Detect 主统计口径不一致
+- Runtime / Queue / Detect 主摘要不统一
+- item 级统一为什么做不了，这个问题现在已经查清

 ## 当前剩余问题

 当前唯一剩余问题：

- 还没有做到 item 级逐条统一回写
+- 大陆逐条结果缺少进入中央的最小同步通道

-具体来说：
+换句话说：

- 当前已做到：
-  - 主统计口径一致
-  - 节点参与口径一致
-  - Runtime / Detect 读取同一套有效聚合值
- 当前未做到：
-  - 大陆执行结果逐条回写 `detect_job_items`
+- 当前不是“不会回写”
+- 而是“没有可回写的逐条输入”

 ## 当前是否可以继续跑检测测试

 当前结论：

- 可以继续跑检测任务测试
- 而且现在 Detect 主统计和节点参与都更接近真实执行态
+- 可以继续跑检测测试
+- 主统计和节点参与已经足够可信
+- 只是不要把 `detect_job_items` 当作大陆执行结果的逐条真相来源

 ## 当前是否建议直接上线

 当前结论：

- 已经比上一轮更接近可上线状态
- 如果目标是“后台可以稳定发起检测并看懂谁在跑”，已经基本可用
- 如果目标是“中央账本逐条结果完全统一”，还差最后一层 item 级回写
+- 如果目标是：
+  - 后台稳定发起检测
+  - 看懂谁在跑
+  - 看懂整体任务推进
+  那已经基本可用
+
+- 如果目标是：
+  - 中央账本逐条反映大陆每个域名的终态
+  那还差最后一个前置批次

 ## 当前优先级判断

 最高优先级：

- 决定是否继续进入 `detect_result_projection -> detect_job_items` 的 item 级统一
+- `J1-大陆逐条结果同步前置批`

 当前不应继续推进：

@@ -132,12 +112,12 @@
 - 新模块
 - 新页面
 - 发布动作
- 与检测账本统一无关的工作
+- 与逐条结果同步无关的工作

 ## 完成下一轮后的预期

-如果下一轮把 item 级结果回写规则明确并最小落地：
+如果下一轮把大陆逐条结果输入中央这件事补上：

- Detect 不仅主统计一致
- 而且底层逐条账本也会接近最终一致
+- item 级统一才会真正可落地
+- 后续 `detect_job_items` 回写会变成纯工程实现问题
 - 整体可上线程度预计提升到 `95%~96%`
--- a/docs/ops_center_runtime/TASK_BOARD.md
+++ b/docs/ops_center_runtime/TASK_BOARD.md
@@ -1,138 +1,127 @@
 # TASK_BOARD

-更新时间：2026-04-19 02:40 CST
+更新时间：2026-04-19 02:43 CST

 ## 当前主批次

-唯一主批次：`H1-检测账本统一最小落地批`
+唯一主批次：`J1-大陆逐条结果同步前置批`

 目标：

- 不进入新功能实现
+- 不进入新页面
 - 不扩展控制面
- 只把 Detect 主账本口径从“双轨显示”收敛到“统一后的有效口径”
+- 只解决 item 级统一前的唯一前置缺口：
+  - 大陆节点当前没有把逐条检测结果同步回中央

 ## 本轮已完成

-本轮完成了最小统一落地：
+本轮完成的是结论确认，不是新功能扩展：

- `detect_job_service.py`
-  - 新增统一账本聚合逻辑：
-    - `_build_effective_node_stats`
-    - `_build_effective_summary`
-  - `active_job` 主字段已切换为统一后的有效值：
-    - `items_pending`
-    - `items_claimed`
-    - `items_running`
-    - `items_completed`
-    - `items_failed`
-    - `items_terminal`
-    - `node_stats`
- 保留中央原始账本供追溯：
-  - `raw_items_total`
-  - `raw_items_pending`
-  - `raw_items_claimed`
-  - `raw_items_running`
-  - `raw_items_completed`
-  - `raw_items_blacklisted`
-  - `raw_items_failed`
-  - `raw_items_terminal`
-  - `raw_node_stats`
- 新增单测：
-  - `domain-api/tests/test_detect_job_service.py`
+- 已核查 `detect_result_projection`
+- 已核查 `detect_run_events`
+- 已确认当前 item 级回写为什么做不了

-## 当前结果快照
+## 关键证据

-接口验证结果：
+### 证据 1：`detect_result_projection` 只有聚合数据

- `detect/job/active`
-  - 主字段已统一为：
-    - `items_total = 1000`
-    - `items_pending = 931`
-    - `items_claimed = 34`
-    - `items_running = 14`
-    - `items_completed = 21`
-  - 原始中央账本仍可追溯：
-    - `raw_items_pending = 950`
-    - `raw_items_claimed = 25`
-    - `raw_items_running = 4`
-  - `node_stats` / `distributed_node_stats` 已统一为：
-    - `mainland-controller-01`
-    - `mainland-worker-01`
-    - `overseas-control-01`
-    - `unassigned = 680`
- `detect/queue-summary`
-  - 主字段已统一为：
-    - `pending = 931`
-    - `claimed = 34`
-    - `running = 14`
+最新 `detect_result_projection` 当前只包含：

-验证结果：
+- `job`
+- `latest_event`
+- `queue`
+- `phase`

- `python3 -m py_compile`
-  - 通过
- `/opt/domaincheck/domainCheck/.venv/bin/python -m unittest tests.test_detect_job_service`
-  - 通过
- `domaincheck-api`
-  - 已重启并验证通过
+不包含：
+
+- `domain_id`
+- `job_item_id`
+- `domain`
+- `status` 的逐条结果列表
+
+### 证据 2：中央 `detect_run_events` 的逐条事件只有海外
+
+当前中央库里可见：
+
+- `overseas-control-01`
+  - `domain_started`
+  - `domain_completed`
+
+当前不可见：
+
+- `mainland-controller-01`
+  - 无逐条 `domain_*` 事件
+- `mainland-worker-01`
+  - 无逐条 `domain_*` 事件
+
+### 证据 3：大陆当前只同步了“聚合参与态”，没有同步“逐条结果”
+
+所以当前能做到：
+
+- 主统计统一
+- 节点参与统一
+
+当前还做不到：
+
+- 把大陆执行结果逐条映射回 `detect_job_items`

 ## 当前结论

-这轮已经把“中央账本原值”和“分布式 display 附加值”进一步收敛成一套主展示账本。
+`I1-检测结果逐条回写设计批` 的结论已经明确：

-现在的口径变成：
+- 现在还不能直接做 item 级回写
+- 不是逻辑没写
+- 是中央当前缺少大陆逐条结果输入

- 主字段：
-  - 直接反映当前统一后的有效检测账本
- 原始字段：
-  - 仍保留中央派发账本，供排障和审计
+## 下一步唯一主批次

-这意味着：
+唯一主批次：`J1-大陆逐条结果同步前置批`

- Detect 页面不再只是“看起来对”
- Runtime / Queue / Detect 主视图开始吃同一套有效统计
+范围：

-## 当前唯一剩余问题
+- 不做最终 item 回写
+- 先补“大陆逐条结果进入中央”的最小数据通道

-唯一剩余问题：
+本批次唯一目标：

- 这 still 是“聚合统一”，还不是“逐条 item 真正回写统一”
-
-也就是说：
-
- 当前已经解决：
-  - 主统计口径一致
-  - 节点参与显示一致
- 当前还没解决：
-  - 大陆执行结果逐条回写 `detect_job_items`
+- 让大陆节点把至少这些字段同步回来：
+  - `job_code`
+  - `cycle_token`
+  - `domain_id` 或可稳定映射的 `domain`
+  - `result_status`
+  - `finished_at`

 ## 候选批次

-### Candidate I1
+### Candidate J2

-名称：检测结果逐条回写设计批
+名称：item 级回写最小落地批

 进入条件：

- 用户确认要继续把聚合统一推进到 item 级一致
+- `J1` 完成后，中央已经能收到大陆逐条结果

 范围：

- 只设计 `detect_result_projection -> detect_job_items` 的最小映射方案
- 不直接重做整条执行链
+- 将大陆逐条结果最小映射回 `detect_job_items`
+- 只更新：
+  - `status`
+  - `finished_at`
+  - `last_error`
+  - `result_version`

-### Candidate I2
+### Candidate J3

-名称：Detect / Runtime 文案统一批
+名称：raw/effective 运营文案收口批

 进入条件：

- 如果用户只想进一步把“raw vs effective”提示写清楚
+- 如果用户只想先把页面提示再写清楚

 范围：

- 补统一文案
- 不再扩逻辑
+- 只补文案
+- 不改逻辑

 ## 暂停项

@@ -142,10 +131,10 @@
 - 新模块
 - 运维中枢增强
 - 发布动作
- 与检测账本统一无关的工作
+- 与大陆逐条结果同步无关的工作

 ## 下一轮唯一动作

 下一轮唯一应该继续做的事情：

- 明确是否要继续进入 item 级结果回写统一
+- 设计并落地“大陆逐条检测结果 -> 中央可消费事件/投影”的最小同步通道