docs(#366): document initial editor readiness diagnostics

docs/06-troubleshooting.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Troubleshooting
 wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Troubleshooting
-wiki_revision: ac3a0b74704f398cec54149267089c87c8375a3e
-synchronized_at: 2026-10-06T09:50:33Z
+wiki_revision: b0fe084161a10102af6c16068f6e7a627d37d9db
+synchronized_at: 2026-10-08T02:38:08Z
 <!-- gitea-wiki-mirror:end -->
 
 # 故障排查
@@ -114,3 +114,14 @@ adb -s <serial> shell run-as cn.ilapage.goauto.agent sqlite3 -readonly databases
 - 保留现有加载、错误提示、取消和旧请求隔离逻辑，不增加自动重试。慢请求在 10～60 秒间完成时不再被原 10 秒客户端预算提前中止；超过 60 秒仍会超时，上游更短的超时也可能先终止请求。
 - 此调整不优化后端执行速度。处理阶段筛选当前先加载候选并计算阶段、后分页；不选店铺且采购类型为全部时，候选可能很大。遇到持续慢查询，应另行分析候选预筛选与数据库执行计划，不能据此认为延长前端预算已解决后端性能问题。
 - 只需发布包含该提交的 Web 资源即可生效，不要求数据库迁移、Android 安装或后端参数变更；发布仍需人工授权。
+
+## Android 地址编辑页控件就绪等待（#366，环节②）
+
+实现绑定 `650f3a6ba115bd22cdefef705eeab4535487cccd`，位于独立工单分支，未合并 main、未装机或发布；已通过目标类 62 项及完整 Debug 514 项合成单元测试；Release 测试与 APK 构建结果以工单最终记录为准，不代表真机采购验收。只修改点击“修改”后等待详细地址输入框就绪的环节；地址列表识别（①）仍缺真实单/多地址列表证据，保存退出（③）、返回与最终复核（④）不改。
+
+- 标题出现不再立即触发输入框缺失失败。在“详细地址”标签的既有同排区域，统计可见 EditText 的 structural 数量（包括空值/禁用）及其 enabled、非空子集 ready 数量。只有 structural=1 且 ready=1 才继续，读取的地址与就绪判定来自同一帧；后续 inputFresh 仍重新定位且只尝试一次。
+- 沿用单轮最多 50 次采样、原 200ms 暂停及点击后的既有暂停。不再叠加标题等待与控件等待，不设置“三次多候选即失败”；采样与解析另有耗时，不能将其表述为严格 10 秒墙钟超时。既有安全异常仍可提前终止。
+- 等待超时使用现有错误码：从未观察到详细地址标题为 PURCHASE_ADDRESS_EDIT_TIMEOUT；曾见标题但候选未就绪/不唯一为 PURCHASE_ADDRESS_UPDATE_FAILED。titleSeen 跨帧保留，因此最后一帧空树不会抹掉此前的标题证据。
+- 诊断仅含固定 stage=address_editor_ready、reason 分类以及 titleSeen、structural、ready 标量，不含地址、收货人、电话或节点文本。具体原因以实现和测试中的固定分类为准；这不是新增 SQLite 字段或上传接口。
+- 收货人/电话不能作为备用目标；区域重叠造成歧义时不输入、不保存。无额外点击、滑动、返回、保存或下单重试，正常单次动作路径保持。
+- 此修复不能证明历史失败均因慢加载，也不解决保存地址后返回超时。识别①不能仅凭“不是规格面板＋无提交按钮”推断已进入地址列表：两项都依赖同一个面板解析结果。

docs/08-agent-api-contract.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Android-Agent-API-Contract
 wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Android-Agent-API-Contract.-
-wiki_revision: 640da0a86bf1057d418dbeb062c07a84cb5b1d8e
-synchronized_at: 2026-10-08T01:42:56Z
+wiki_revision: b044dd31ab7920706599f73a5143cced5ab90605
+synchronized_at: 2026-10-08T02:38:12Z
 <!-- gitea-wiki-mirror:end -->
 
 <!-- gitea-wiki-mirror:start -->
@@ -641,6 +641,16 @@ Agent 主动提交 `order_result_unknown` 时保持订单号和下单时间为
 | `PURCHASE_ORDER_RESULT_UNKNOWN` | 无法确认订单是否创建，请人工检查 |
 | `PURCHASE_PAYMENT_FORBIDDEN` | 系统禁止自动付款 |
 
+### 地址编辑页初始等待诊断（#366，环节②）
+
+实现绑定 `650f3a6ba115bd22cdefef705eeab4535487cccd`（工单分支，尚未合并 main 或发布）。本修订只细化 Android 点击“修改”后的输入框等待及错误说明，不增加 HTTP 字段、数据库字段或错误码，不改变任务结果提交、设备/任务/规则关联和保存后的最终复核。
+
+- 一个现有 50 次采样预算内，只有详细地址区域可见 EditText 的结构候选数为 1，且其中 enabled、非空的就绪候选数也为 1，才允许后续既有单次输入；结构计数包括空值和禁用候选。
+- 超时从未观察到“详细地址”标题时沿用 `PURCHASE_ADDRESS_EDIT_TIMEOUT`；曾见标题但输入框缺失、为空、禁用或存在歧义时沿用 `PURCHASE_ADDRESS_UPDATE_FAILED`。
+- 此等待失败的 `errorMessage` 可附固定诊断 `stage=address_editor_ready;reason=<固定分类>;titleSeen=<布尔>;structural=<数量>;ready=<数量>`。reason 为 `title_missing`、`editor_missing`、`editor_ambiguous`、`editor_disabled` 或 `editor_empty`；titleSeen 累计保留，数量取最后采样帧，不包含地址值、收货人、电话及节点文本。
+- 既有页面安全异常优先失败，不必耗尽预算；`inputFresh` 失败仍不重试。其它使用 `PURCHASE_ADDRESS_UPDATE_FAILED` 的路径保持原义，不要求它们附本段诊断。
+- ①地址列表识别仍待真实场景证据，③保存退出、④返回与最终复核不改；本段不代表整单完成或真机验收。
+
 ## Agent 当前设备任务历史（#90）
 
 四个只读接口统一使用设备注册所得的 Device Token，只返回该 Token 对应设备最近 30 天内的任务；设备 A 查询设备 B 的任务时按不存在处理，不泄露任务是否存在。