diff --git a/开发文档/1、需求/修改/工作手机_进行中_20260613.md b/开发文档/1、需求/修改/工作手机_进行中_20260613.md index 358b8d2acb..381f605a43 100644 --- a/开发文档/1、需求/修改/工作手机_进行中_20260613.md +++ b/开发文档/1、需求/修改/工作手机_进行中_20260613.md @@ -295,3 +295,14 @@ - [ ] 当前 ADB 设备 0 台;手机回连后覆盖安装并补扫码页截图、引擎运行状态和 Hook 回读。 - 正式包:`sdk/releases/20260724/workphone-agent-v5.0.10-release.apk` - SHA-256:`64afcbe4e02c70de965a33bb9eeab80cc35d6345625a8457a021e179b5bd4a9c` + +## 十、2026-07-26 微信智能追问二轮收敛 + +- [x] 补齐5个核心用户故事,明确管理员、运营和负责人三类使用目标。 +- [x] 补齐设备、Hook、任务、消息四类状态机,统一`queued/unknown/succeeded`边界。 +- [x] 定义9张最小核心数据表及关键索引。 +- [x] 明确设备中心、聊天中心、任务中心、风险日志四个管理端页面规格。 +- [x] 固定Sprint 0~3执行顺序、核心指标和本期不做范围。 +- [ ] 待确认首个聊天中心承载端、消息保存期限、专用测试对象和批量暂停阈值。 + +详细定义:`开发文档/1、需求/工作手机微信产品需求_20260726.md`。 diff --git a/开发文档/1、需求/工作手机微信产品需求_20260726.md b/开发文档/1、需求/工作手机微信产品需求_20260726.md index 7e49f7ce93..3cfe794ea5 100644 --- a/开发文档/1、需求/工作手机微信产品需求_20260726.md +++ b/开发文档/1、需求/工作手机微信产品需求_20260726.md @@ -142,3 +142,184 @@ 4. 写动作只在测试账号、测试群、测试朋友圈和专用对象执行。 5. P0六项全部通过后,才扩大好友、群发和朋友圈批量规模。 + +## 八、二轮智能追问:把方向收敛为开发决策 + +| 智能追问 | 默认答案 | 对研发的约束 | +|---|---|---| +| 第一使用者是谁? | 运营人员执行,管理员处理设备与异常,负责人看结果 | 权限最少分为运营、管理员、负责人三类 | +| 用户最怕什么? | 页面显示成功,微信里却没有结果 | `false_success_rate`必须为0,未知状态不得包装成成功 | +| 出错后先让用户做什么? | 系统先自愈并解释,再给人工动作 | 每个错误必须带层级、原因、自动处理、下一步 | +| 能否连续点击重复执行? | 不能 | 写动作必须有`idempotency_key`和内容指纹 | +| 批量任务如何避免误操作? | 预检、预览、确认、小批执行、失败暂停 | 默认批次10,失败率达到阈值自动暂停 | +| 谁能看到敏感正文? | 仅有权限的业务人员 | 列表脱敏、详情按权限解密、查询留审计记录 | +| 离线时任务怎么办? | 不直接失败,也不盲目执行 | 进入`blocked`并显示阻塞原因;恢复后按策略继续或重新确认 | +| 历史记录保存什么? | 保存能复现一次执行的完整证据 | 请求摘要、trace、通道、原始回执、回读、操作者、时间均保留 | +| 今天先看哪个指标? | 闭环成功率,不看接口调用量 | 北极星指标为“真实动作闭环成功率” | + +## 九、核心用户故事 + +### US-01 管理员绑定并确认真实在线 + +作为管理员,我扫码绑定手机后,要在一个页面看到设备身份、非回环连接、微信进程、Hook四层状态和最近异常,从而确认设备能否承接业务任务。 + +**完成条件**:同一设备只出现一次;拔USB后仍在线;状态更新时间不超过60秒;异常可一键查看trace。 + +### US-02 运营发送消息并得到微信回读 + +作为运营,我选择客户、编辑内容并确认发送后,要看到排队、执行、微信回执和最终回读,而不是只看到HTTP成功。 + +**完成条件**:消息正文幂等落库;页面显示最终状态;失败可按原任务重试;重复点击不产生第二条消息。 + +### US-03 管理员定位并恢复Hook故障 + +作为管理员,当Hook不可用时,我要明确知道故障在Frida、微信进程、attach还是RPC,并看到系统已采取的自愈动作。 + +**完成条件**:四层状态独立;60秒内自动恢复或给出唯一人工动作;恢复前写任务保持阻塞。 + +### US-04 运营安全执行批量任务 + +作为运营,我执行好友、群发或朋友圈任务前,要先看到对象数、去重数、风险项和预计批次,确认后再执行。 + +**完成条件**:支持dry-run;高风险项默认剔除;部分失败可导出;失败率达到20%时暂停后续批次。 + +### US-05 负责人查看结果而非技术日志 + +作为负责人,我只需要看到今天成功多少、失败多少、主要原因、影响账号和待人工事项,并可下钻到证据。 + +**完成条件**:业务结果与trace关联;指标不把queued/unknown计入成功。 + +## 十、统一状态机 + +### 10.1 设备状态 + +`unbound → binding → online → degraded → recovering → online` + +任何状态均可进入`offline`;只有当非回环WSS会话、鉴权和心跳均有效时才进入`online`。Hook异常但连接正常时为`degraded`,不能把整台设备误报离线。 + +### 10.2 Hook状态 + +`service_unavailable → service_ready → process_found → attached → rpc_ready` + +- `rpc_ready`才允许写动作。 +- 任一层失败进入`degraded`并记录`failed_layer`。 +- 状态必须有`checked_at/expires_at`,过期结果不得继续展示为可用。 + +### 10.3 任务状态 + +`draft → prechecking → awaiting_confirm → queued → running → readback → succeeded` + +异常分支:`blocked / partial_failed / failed / unknown / cancelled`。 + +- `queued`仅表示接收任务。 +- 无原始回执进入`unknown`。 +- 有回执但回读不一致进入`failed`或`partial_failed`。 +- 只有回读对象、内容指纹和目标一致才进入`succeeded`。 + +### 10.4 消息状态 + +`queued → sent → delivered`,失败分支为`failed / unknown / recalled`。 + +发送接口成功最多推进到`sent`;取得微信服务端ID或等价业务回读后才进入`delivered`。 + +## 十一、最小数据模型 + +| 集合/表 | 必填核心字段 | 作用 | +|---|---|---| +| `devices` | `device_id, serial_aliases, model, bind_status, owner, created_at` | 唯一设备身份 | +| `connections` | `session_id, device_id, channel, source_ip, server, auth_status, heartbeat_at, closed_reason` | 真实连接单一真源 | +| `hook_status` | `device_id, service, process, attached, rpc_ready, failed_layer, checked_at, expires_at` | Hook四层真值 | +| `wechat_accounts` | `wxid, device_id, nickname, account_status, last_active_at` | 微信号与设备映射 | +| `conversations` | `conversation_id, wxid, talker, type, last_message_at, unread_count` | 会话索引 | +| `messages` | `msg_svr_id, local_id, conversation_id, direction, type, content, status, sent_at, delivered_at` | 正式聊天记录 | +| `tasks` | `task_id, idempotency_key, action, operator_id, targets, status, risk_level, created_at` | 所有写任务主表 | +| `action_receipts` | `trace_id, task_id, channel_used, raw_receipt, readback, error_code, started_at, finished_at` | 执行与回读证据 | +| `audit_events` | `actor, role, action, object_type, object_id, result, trace_id, created_at` | 权限与审计 | + +**索引要求**:`device_id`、`wxid`、`trace_id`、`idempotency_key`唯一或高选择性索引;消息以`conversation_id + sent_at`分页;原始回执大字段可转对象存储但必须保留摘要和引用。 + +## 十二、管理端页面规格 + +### 12.1 设备中心 + +- 列表:设备名、微信号、连接、Hook、心跳、待处理异常。 +- 详情:设备身份、连接会话、Hook四层、最近10次恢复事件、能力清单。 +- 操作:重新探测、恢复Hook、暂停接单、查看trace。 + +### 12.2 聊天中心 + +- 左侧会话,中间消息流,右侧客户信息与执行证据。 +- 消息气泡显示发送中、已发送、已送达、失败、未知、已撤回。 +- 空态说明未同步原因;加载态用骨架屏;错误态保留已加载记录并允许重试。 + +### 12.3 任务中心 + +- 新建任务采用“选择对象→风险预检→内容预览→确认→执行”五步。 +- 任务列表显示总数、成功、失败、未知、暂停原因和预计完成时间。 +- 任务详情按对象展示独立状态,不用一个总成功掩盖部分失败。 + +### 12.4 风险与日志 + +- 风险页只呈现需决策事项:离线、Hook异常、频控、失败聚类、账号异常。 +- 技术日志默认折叠,业务人员看到大白话原因和下一步;管理员可查看原始回执。 + +## 十三、统一接口回执 + +```json +{ + "trace_id": "TRACE_ID", + "task_id": "TASK_ID", + "device_id": "DEVICE_ID", + "wxid": "WXID", + "action": "send_message", + "status": "readback", + "channel_used": "wss_frida", + "error": null, + "raw_rpc_receipt": {}, + "readback": {}, + "timestamps": { + "accepted_at": "ISO_TIME", + "executed_at": "ISO_TIME", + "verified_at": "ISO_TIME" + } +} +``` + +错误码固定五层前缀:`AUTH_* / CONNECTION_* / CAPABILITY_* / EXECUTION_* / READBACK_*`。前端不得自行把错误改写成成功。 + +## 十四、迭代顺序与上线门禁 + +| 迭代 | 范围 | 出口条件 | +|---|---|---| +| Sprint 0 | 真实连接、唯一设备映射、统一错误模型 | 伪在线为0;三端设备状态一致 | +| Sprint 1 | Hook四层、自愈、任务状态机 | 三类故障各3轮恢复;写动作可阻塞和恢复 | +| Sprint 2 | 消息落库、聊天中心、发送回读 | 收发20条全部可查;重复入库为0 | +| Sprint 3 | 好友/群发/朋友圈小批闭环 | dry-run、确认、执行、回读、审计全链路通过 | + +### 核心指标 + +- 真实在线率 ≥ 99%。 +- 动作闭环成功率 ≥ 95%(测试环境首阶段目标)。 +- 假成功率 = 0。 +- 消息幂等落库率 = 100%。 +- Hook自动恢复率 ≥ 90%,平均恢复时间 ≤ 60秒。 +- `unknown`任务必须在10分钟内被回查或转人工。 + +## 十五、本期明确不做 + +1. 不在APK新增聊天、好友、群发、朋友圈详情页。 +2. 不把ADB reverse、127回环或USB在线作为生产在线证据。 +3. 不把accepted、queued、HTTP 200当作业务成功。 +4. P0未全绿前,不开放大规模好友、群发和朋友圈任务。 +5. 不为追求“接口数量”继续增加没有真实RPC与回读的空动作。 + +## 十六、下一次智能追问输入 + +下一轮只追问四个能改变开发结果的问题: + +1. 当前管理端实际由存客宝还是触客宝承载首个聊天中心? +2. 消息正文默认保存期限和可见角色是什么? +3. 首批专用测试微信号、测试群和测试朋友圈对象分别是哪组? +4. 批量失败暂停阈值是否接受默认20%? + +在答案缺失时,研发按本文默认决策推进,不阻塞Sprint 0~2。 diff --git a/开发文档/功能迭代记录.md b/开发文档/功能迭代记录.md index 4c574d3f9b..f159715678 100644 --- a/开发文档/功能迭代记录.md +++ b/开发文档/功能迭代记录.md @@ -1375,3 +1375,11 @@ flowchart LR - P0:WX-P0-01~WX-P0-06,共6项。 - P1:WX-P1-01~WX-P1-04,共4项。 - 详细需求:`开发文档/1、需求/工作手机微信产品需求_20260726.md`。 + +## 2026-07-26|微信智能追问二轮开发级收敛 + +- 将首版功能清单深化为5个用户故事、4类状态机、9张核心数据表和4类管理端页面。 +- 统一设备在线、Hook可用、任务成功和消息送达的状态边界,明确假成功率必须为0。 +- 排定Sprint 0~3:连接与映射→Hook与任务→消息落库→业务小批闭环。 +- 增加真实在线率、闭环成功率、消息幂等率、Hook自愈率和未知任务处理时限指标。 +- 详细需求:`开发文档/1、需求/工作手机微信产品需求_20260726.md`。