@genduo/desk 0.0.0-stage → 0.5.0

package/README.md

@@ -1,3 +1,188 @@
-# 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.5.0）｜ **凭据** 与销量计算系统一致｜ **下一店** 5RT2 ｜ **中心** `https://dataanalyst.jp` ｜ **POC** 7RT2 已绿
+
+## 目标 UX
+
+1. **超管先备齐**：中心签发每店 Agent token；店机维护 `JDY_MCP`（与销量系统相同）；RMS 用 env-file。
+2. **门店只拿到本 CLI**：运行 `login`（token 进环境 / bootstrap）、心跳、可选装 LaunchAgent。
+3. 不再以「手工 `security` 写 dataanalyst/*」作为主路径。
+
+### 安装（门店主路径：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.5.0）。  
+**0.5.0**：凭据获取与销量计算系统一致（`JDY_MCP` → MCP → 密码表 API Key）；旧 `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` | 门店 | Agent token → 环境；可选心跳 / RMS 校验 / LaunchAgent |
+| `status` | 门店 | JDY_MCP / token 环境 / 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` | 超管 | 开店清单（与销量系统凭据说明） |
+| `admin verify-secrets` | 超管 | 探测 `JDY_MCP` → API Key（不打印） |
+| `admin set-rms` | 超管 | **已废弃**（勿写 dataanalyst/rms/*） |
+| `admin write-bootstrap` | 超管 | 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 **只**用于 MCP URL（店机维护；本开发机可以没有）：
+
+| service | account | 覆盖 |
+|---|---|---|
+| `JDY_MCP` | `服务器URL` | 环境变量 `JDY_MCP_URL` 优先 |
+
+JDY API Key：经 MCP `member_data_list` 查密码表，Title 精确匹配 **`api key 精细化运营`**（同销量系统 `config.JDY_API_KEY_TITLE`）。不硬编码、不打印。
+
+Agent token（中心 `da_…`）：环境变量 `DATAANALYST_AGENT_TOKEN`，或 `login --bootstrap`。**不写** `dataanalyst-agent-token` Keychain。
+
+RMS 两组：`RMS_<SHOP>_LOGIN_ID` / `PASSWORD` / `SHOP_USER` / `SHOP_PASSWORD`，或 `rms_browser_login --env-file`。**不写** `dataanalyst/rms/*` Keychain。
+
+本机非机密配置：`~/.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（明文勿进 git/聊天）→ 门店 DATAANALYST_AGENT_TOKEN 或 bootstrap
+# 3) 店机维护 JDY_MCP（与销量系统相同；开发机可无）
+genduo-desk admin verify-secrets --shop 5RT2
+
+# 4) 可选 bootstrap
+genduo-desk admin write-bootstrap --shop 5RT2 --out /tmp/5RT2.boot.json
+```
+
+## 门店流程（后）
+
+```bash
+genduo-desk login --shop 5RT2 --verify-rms --install-service
+
+genduo-desk status
+```
+
+`--keep-token` / `--keep-rms`：沿用已有环境变量，不重复交互。
+
+## 5RT2 下一店清单
+
+1. 超管：签发 `agent-5RT2`；门店 Mac 维护 `JDY_MCP`（与销量系统一致）；备齐 RMS env-file。
+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 / 密码；JDY 侧与销量计算系统一致（Keychain 仅 MCP URL → 密码表 API Key）。
+- Agent token / RMS 用环境变量或 bootstrap / env-file，不写 dataanalyst/* Keychain。
+- 中心**不保存** 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);