docs: migrate Business-Rules-and-Glossary to Wiki-first (#43)

Business-Rules-and-Glossary.-.md

@@ -0,0 +1,76 @@
+# 业务规则与术语
+
+## 当前范围
+
+当前 MVP 只有四个业务动作：添加 PDD 商品、创建规则、创建采集任务、在任务详情查看 Android 回传结果。顺云宝、Shopee、采购、批量任务、规则发布流程、全局停机和实时屏幕不在范围内。
+
+## PDD 商品
+
+- PDD URL 由管理员人工录入。
+- 服务端必须规范化 URL 并提取 `goods_id`；提取失败时拒绝保存。
+- `goods_id` 唯一；相同 `goods_id` 再次添加时提示“商品已存在”。
+- 已存在商品允许修改当前 URL，但不自动改变已创建任务的 URL 快照。
+
+## 采集规则
+
+- 规则创建后立即可用，不存在草稿、发布、版本或停用流程。
+- 规则允许编辑；新任务读取编辑后的当前内容。
+- 创建任务时保存完整 `rule_snapshot`，以后编辑规则不影响该任务。
+- 删除采用软删除；删除后不能创建新任务，但已有任务继续执行自身快照。
+- 商品详情步骤应声明精确 `activityName`，并与包名和唯一控件共同作为页面证据；进入 PDD 登录 Activity 必须返回 `PDD_LOGIN_REQUIRED`，不能提交采集成功。
+- 唯一文字节点不可点击时，Agent 只可点击其最近的可点击父容器；不得改点兄弟节点或相似文字。
+- v2 规则使用类型化动作和固定阶段钩子。已由 Agent 支持的选择器、别名、超时、滑动方向和有限次数可以只更新规则；新增动作类型或页面算法才需要升级 Agent。
+- v2 任务首次未进入精确商品详情页时，可以按规则显式重开同一浏览器 URL 一次；登录、验证码、风控、无效链接和详情页内采集失败不触发该恢复。
+- 假售罄恢复只使用主商品规格/购买强证据判断页面是否正常；顶部“相似商品”可以作为受控兜底证据，推荐卡片的标题、价格和销量不得冒充主商品证据。
+- 商品规格遍历必须用已识别规格节点锁定横向颜色容器和纵向面板容器；颜色按视觉行蛇形遍历，滑动完成后重新读取节点，尺码只读并允许在标题滚出后沿已锁定容器续页。
+- Agent 可扩展，但规则必须按任务类型授权：采集规则不能创建订单，采购规则未来可以使用独立的创建订单能力，任何规则都不能付款。
+
+## 采集任务
+
+- 任务与结果共用 `collection_task` 主表，不建立独立 `collection_result` 主表。
+- 创建任务时固化 `url_snapshot`、`goods_id_snapshot` 和 `rule_snapshot`。
+- 设备默认人工指定；未指定时由在线空闲设备原子领取。
+- 一台设备同时只执行一个任务。
+- 同一 PDD 商品不能同时存在多个 `pending` 或 `running` 任务。
+- 手机离线时运行中任务失败；默认不自动重试、不自动换机。
+- 失败后允许人工重置或删除后重新创建。
+- `completed`、`completed_partial`、`failed` 可以重置；`running` 禁止重置和删除。
+- 重置保留原 URL、goods_id、规则和设备快照，在一个事务中删除旧规格/SKU、清空结果和错误，并恢复为 `pending`。
+- 任务结果只在任务详情查看，不回填到 PDD 商品列表或独立结果页面。
+
+## 采集字段
+
+- PDD 标题、店铺名、销量、评价数量。
+- 通用规格维度和值，当前重点是颜色和尺码。
+- 采集时按颜色读取价格；同一颜色下不同尺码默认价格相同。
+- 存储时展开 SKU 组合，将颜色价格复制到该颜色各尺码 SKU。
+- SKU 不完整仍提交已有结果并标记 `completed_partial`。
+
+## 自动化边界
+
+- 浏览器“打开拼多多APP”和系统确认框“打开”属于允许动作。
+- 登录失效、验证码、风控、人机验证和找不到唯一控件时失败并给出具体错误。
+- 不使用 OCR/VLM 兜底，不猜测缺失数据，不保存原始控件树或截图。
+- 当前 MVP 不创建订单、不支付、不提供实时屏幕或管理端远程控制。
+- Agent 的长期能力可以扩展到采购规则中的“创建订单”，但采集规则不能调用该动作；采购必须作为独立高风险 MVP 实施。付款、免密支付及任何等价动作始终禁止。
+
+## 设备身份与认证
+
+- Android Agent 首次安装生成唯一 `install_id`；服务端收到合法设备信息即注册或更新设备，不使用硬件标识作为唯一键。
+- `install_id` 在设备表中唯一，不存在注册码、注册申请或设备审核记录。
+- Device Token 明文只返回给客户端，服务端数据库只保存不可逆摘要。
+- 设备状态只保存在线、离线或停用；是否忙碌由运行中的任务关系确定。
+- Agent 默认每 15 秒心跳一次，45 秒没有心跳即离线；离线扫描每 15 秒执行。
+- 心跳上报的 `currentTaskId` 必须与服务端该设备唯一运行任务一致，否则拒绝更新心跳。
+- 设备超时离线时，其运行任务立即以 `DEVICE_OFFLINE` 失败，清除租约且不自动重试。
+
+## 术语
+
+| 术语 | 含义 |
+|---|---|
+| 规则快照 | 创建任务时复制到任务中的完整规则内容 |
+| URL 快照 | 创建任务时复制到任务中的 PDD URL 和 goods_id |
+| 空闲领取 | 未指定设备的待执行任务由在线且无活动任务的设备原子领取 |
+| 部分完成 | 结果已提交，但一个或多个规格/SKU 缺失 |
+| 重置任务 | 保留任务输入快照，清除原结果后重新进入待执行状态 |
+| Portal/Agent | Android 端注册、保活、执行规则和提交结果的程序 |