@genduo/desk 0.0.0-stage → 0.4.0

package/README.md

@@ -1,3 +1,187 @@
-# Temporary Holding Version
+# 店铺采集 Agent（CLI）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**状态** 门店 CLI 登录授权已落地；**采集循环已落地**（`run.py` 0.4.0）｜ **下一店** 5RT2 ｜ **中心** `https://dataanalyst.jp` ｜ **POC** 7RT2 已绿
+
+## 目标 UX
+
+1. **超管先备齐**：每店 Agent token + R-Login 两组密码。
+2. **门店只拿到本 CLI**：运行 `login` 完成登录授权（写入 Keychain、心跳、可选装 LaunchAgent）。
+3. 不再以「每店手写 plist / 手工 security 命令」作为主路径。
+
+### 安装（门店主路径：npm）
+
+前置：macOS、Node ≥ 18、`python3`（`brew install python`）。  
+`--verify-rms` 另需：`pip3 install playwright && python3 -m playwright install chromium`。
+
+```bash
+npm i -g @genduo/desk
+genduo-desk login --shop 5RT2 --verify-rms --install-service
+genduo-desk status
+```
+
+包名 `@genduo/desk`（全局命令 `genduo-desk`）；版本见 `package.json` / `local_config.VERSION`（0.4.0）。  
+**Keychain service 名未改**（仍为 `dataanalyst-agent-token` / `dataanalyst/rms/...`），换包名不影响已写入的凭据。
+
+### 开发 / monorepo 路径（次要）
+
+```bash
+# 仓库内直接跑，或 symlink 到 PATH（shim 命令名仍是 dataanalyst-agent）
+ln -sf "$(pwd)/tools/collector-agent/dataanalyst-agent" /usr/local/bin/dataanalyst-agent
+# 或：cd tools/collector-agent && npm link   # → 全局命令 genduo-desk
+
+genduo-desk login --shop 5RT2 --verify-rms --install-service
+genduo-desk status
+```
+
+## 命令一览
+
+| 命令 | 谁用 | 作用 |
+|---|---|---|
+| `login` | 门店 | 粘贴 token + 输入 R-Login 两组 → Keychain；可选心跳 / RMS 校验 / LaunchAgent |
+| `status` | 门店 | Keychain 是否齐全、LaunchAgent、打一次心跳 |
+| `heartbeat` | 门店 / 调试 | `POST /api/agent/heartbeat` + 拉 jobs |
+| `install-service` | 门店 | 装 Agent + **caffeinate** LaunchAgent（默认） |
+| `prevent-sleep` | 门店 / 超管 | 只装 `jp.dataanalyst.caffeinate`（`caffeinate -dims`），并打印 `pmset` 说明 |
+| `uninstall-service` | 门店 | 卸 Agent **与** caffeinate LaunchAgent |
+| `admin checklist` | 超管 | 打印某店开店清单（含签发 token 命令） |
+| `admin set-rms` | 超管 | 交互写入本机 `dataanalyst/rms/<SHOP>-rlogin` / `-ai` |
+| `admin write-bootstrap` | 超管 | 把 token 写成 600 一次性 JSON，供门店 `login --bootstrap` |
+
+常驻进程入口是 `run.py`（LaunchAgent 调用）：进程内 sleep 循环，心跳 + 日次访问 + 月度 RPP → ingest。
+
+
+
+## 采集循环（run.py）
+
+调度（日历日用本机 `date.today()`；`daemon_state` 时间戳为 JST +09:00）：
+
+| 任务 | 间隔 | 说明 |
+|---|---|---|
+| 心跳 | ~12 分钟 | `POST /api/agent/heartbeat`；带上 `last_error` |
+| 访问人数 | ~20 小时 | 近 14 天日次 → `POST /api/ingest/rms_access` |
+| RPP 广告 | ~每天检查 | 当月（月初 1–3 日兼上月）→ `POST /api/ingest/rms_ads` |
+
+```bash
+# 冒烟（一轮心跳+采集后退出）
+python3 tools/collector-agent/run.py --once
+# 只用仓库 .venv（含 playwright）：
+/Users/gd/workspace/dataanalyst/.venv/bin/python tools/collector-agent/run.py --once
+
+# 常驻（前台调试；生产用 install-service）
+python3 tools/collector-agent/run.py
+
+# 只心跳 / ingest dry-run
+python3 tools/collector-agent/run.py --once --skip-collect
+python3 tools/collector-agent/run.py --once --dry-run-ingest
+```
+
+状态：`state/daemon_state.json`（`last_heartbeat` / `last_access_ok` / `last_ads_ok` / `last_error`，无密钥）。  
+失败 payload 进 `state/buffer/`，下轮自动重试。日志：`logs/agent.log`（轮转）。
+
+**LaunchAgent**：`KeepAlive` = 崩溃重启（配 `ThrottleInterval=30`），**不是**短周期拉起短命进程。`run.py` 必须进程内 sleep；装服务前请先 `--once` 验过。
+
+依赖：本机 Playwright Chromium + 本地代理（默认 `http://127.0.0.1:7897`，可用 `HTTPS_PROXY` / `DATAANALYST_PROXY` 覆盖）；会话 `state/<SHOP>.json`。广告解析需 monorepo `pipeline.rms_ads.parse`。
+
+## 防休眠（重要）
+
+店铺常开 Mac 若进入睡眠/关机，采集会中断。CLI 分两层：
+
+| 层级 | 谁做 | 做什么 |
+|---|---|---|
+| **用户级（CLI 自动）** | 门店跑 `login --install-service` / `install-service` / `prevent-sleep` | 安装 KeepAlive LaunchAgent `jp.dataanalyst.caffeinate` → `/usr/bin/caffeinate -dims`（防 display/idle/disk/system 休眠；登录会话内，重启后随用户登录再拉起） |
+| **系统级（需 sudo）** | 超管或有管理员权限的门店同事 | CLI **不会静默 sudo**。需人工执行：`sudo pmset -a sleep 0 disksleep 0 displaysleep 0`；可选 `sudo systemsetup -setrestartpowerfailure on` |
+
+```bash
+# 只要防休眠、暂不装 Agent 常驻：
+genduo-desk prevent-sleep
+
+# 开店主路径（装 Agent + caffeinate）：
+genduo-desk login --shop 5RT2 --verify-rms --install-service
+
+# 只要 Agent、不要 caffeinate（不推荐）：
+genduo-desk install-service --skip-caffeinate
+```
+
+`status` 会显示 `caffeinate` plist 是否已装、进程是否在跑。
+合盖笔记本另议；常开台式 + 登录用户是推荐形态。
+
+
+## Keychain 约定（勿改名）
+
+| 用途 | service | account |
+|---|---|---|
+| Agent token | `dataanalyst-agent-token` | `$USER` |
+| R-Login 第一组 | `dataanalyst/rms/<SHOP>-rlogin` | R-Login ID |
+| Rakuten SSO 第二组 | `dataanalyst/rms/<SHOP>-ai` | 邮箱 |
+
+与包内 vendored `rms_browser_login.py --from-keychain`（源真相仍是 monorepo `tools/rms_browser_login.py`）、7RT2 POC 一致。  
+本机非机密配置：`~/.config/dataanalyst-agent/config.json`（仅 `shop` / `base`）。
+
+## 中心契约
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| POST | `/api/ingest/rms_access` | 日次访问人数 |
+| POST | `/api/ingest/rms_ads` | RPP/TDA 期间报表 |
+| POST | `/api/agent/heartbeat` | 心跳 / 版本 / 错误 |
+| GET | `/api/agent/jobs?shop=` | 领取补历史/重跑 |
+| POST | `/api/agent/jobs/{id}/ack` | 回报任务结果 |
+
+鉴权：`Authorization: Bearer da_...`。每店 token：`name=agent-<SHOP>`，
+`shops` 只勾本店，`scopes=collect:view,collect:edit`。明文只创建时显示一次。
+
+## 超管流程（先）
+
+```bash
+# 1) 看清单
+genduo-desk admin checklist --shop 5RT2
+
+# 2) 中心签发 token（Web 或 VPS python -m app.tokens …）；明文不要进 git/聊天
+# 3) 可选：在店里 Mac 上预写 RMS
+genduo-desk admin set-rms --shop 5RT2
+
+# 4) 可选：做一次性 bootstrap 交给门店
+genduo-desk admin write-bootstrap --shop 5RT2 --out /tmp/5RT2.boot.json
+```
+
+## 门店流程（后）
+
+```bash
+# 交互粘贴 token + 输入两组密码
+genduo-desk login --shop 5RT2 --verify-rms --install-service
+
+# 或用超管 bootstrap（读完可删）
+genduo-desk login --shop 5RT2 \
+  --bootstrap /tmp/5RT2.boot.json --consume-bootstrap \
+  --keep-rms --verify-rms --install-service
+
+genduo-desk status
+```
+
+`--keep-token` / `--keep-rms`：Keychain 已有则跳过对应提示（7RT2 POC 复用时有用）。
+
+## 5RT2 下一店清单
+
+1. 超管：签发 `agent-5RT2`（scopes/shops 如上）；备齐 R-Login 两组。
+2. 门店 Mac：装 Playwright Chromium（若要 `--verify-rms`）。
+3. 门店：`login --shop 5RT2 --verify-rms --install-service`。
+4. 先只推最近 7 天 `rms_access`；连续 7 天正常后再接 RPP。
+5. `/sources` / `GET /api/agent/status` 可见 online；重复推送不双计。
+
+7RT2 POC 状态见 `state/POC_STATUS.md`（ingest+心跳已绿）。规划细节见
+`docs/collector-agent.md`。
+
+## 安全
+
+- 不打印 token / 密码；bootstrap 文件 mode 600，`--consume-bootstrap` 用后删除。
+- 中心**不保存** R-Login 密码；只收出站 HTTPS ingest / 心跳。
+- RMS 登录阶段禁止 accessibility snapshot / 把密码写入日志；需要人工 2FA 时本机接管。
+- 本 CLI **不会**自行向生产签发新 token。
+
+## 本地冒烟
+
+```bash
+python tests/test_collector_agent.py
+python3 tools/collector-agent/cli.py status --shop 7RT2 --offline
+python3 tools/collector-agent/cli.py admin checklist --shop 5RT2
+```

package/api_client.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""中心 HTTPS 客户端（出站）。不记录 Authorization / token。"""
+from __future__ import annotations
+
+import json
+import socket
+import urllib.error
+import urllib.request
+from typing import Any
+from urllib.parse import urlencode
+
+
+class ApiError(RuntimeError):
+    def __init__(self, method: str, path: str, code: int, detail: str):
+        self.method = method
+        self.path = path
+        self.code = code
+        self.detail = detail
+        # 截断，避免意外带出敏感体
+        super().__init__(f"{method} {path} → {code}: {detail[:300]}")
+
+
+def call(base: str, method: str, path: str, token: str,
+         body: dict | None = None, timeout: int = 60) -> dict:
+    data = None if body is None else json.dumps(body).encode()
+    req = urllib.request.Request(
+        f"{base.rstrip('/')}{path}", data=data, method=method,
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            raw = resp.read().decode()
+            return json.loads(raw) if raw else {}
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode(errors="replace")
+        raise ApiError(method, path, exc.code, detail) from exc
+
+
+def heartbeat(base: str, token: str, shop: str, version: str,
+              capabilities: list[str] | None = None,
+              last_error: str | None = None) -> dict:
+    return call(base, "POST", "/api/agent/heartbeat", token, {
+        "shop": shop,
+        "agent_version": version,
+        "capabilities": capabilities or ["rms_access", "rms_ads", "heartbeat"],
+        "hostname": socket.gethostname(),
+        "last_error": last_error,
+    })
+
+
+def jobs(base: str, token: str, shop: str, limit: int = 5) -> Any:
+    return call(base, "GET", f"/api/agent/jobs?shop={shop}&limit={limit}", token)
+
+
+def ingest(base: str, token: str, source: str, body: dict,
+           dry_run: bool = False, timeout: int = 120) -> dict:
+    """POST /api/ingest/{rms_access|rms_ads}. body: batch_id/collected_at/rows."""
+    q = urlencode({"dry_run": "1"}) if dry_run else ""
+    path = f"/api/ingest/{source}" + (f"?{q}" if q else "")
+    return call(base, "POST", path, token, body, timeout=timeout)

package/bin/genduo-desk.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * genduo-desk — Node bin → python3 cli.py
+ * 包根 = bin/ 的上一级（npm 安装后为 node_modules/@genduo/desk）。
+ */
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const pkgRoot = path.resolve(__dirname, '..');
+const cliPy = path.join(pkgRoot, 'cli.py');
+
+function findPython3() {
+  const pathEnv = process.env.PATH || '';
+  const sep = path.delimiter;
+  const names = process.platform === 'win32' ? ['python3.exe', 'python.exe'] : ['python3'];
+  for (const dir of pathEnv.split(sep)) {
+    if (!dir) continue;
+    for (const name of names) {
+      const full = path.join(dir, name);
+      try {
+        fs.accessSync(full, fs.constants.X_OK);
+        return full;
+      } catch {
+        /* try next */
+      }
+    }
+  }
+  return null;
+}
+
+if (!fs.existsSync(cliPy)) {
+  console.error(`找不到 cli.py: ${cliPy}`);
+  process.exit(1);
+}
+
+const python = findPython3();
+if (!python) {
+  console.error('需要 python3，可用 brew install python');
+  process.exit(1);
+}
+
+const result = spawnSync(python, [cliPy, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+  env: process.env,
+});
+
+if (result.error) {
+  console.error(result.error.message);
+  process.exit(1);
+}
+process.exit(result.status == null ? 1 : result.status);