client-commons/skill-template

Fork 0

Files

chendelian 4a0be93b4a

技能自动化发布 / release (push) Successful in 5s

Details

chore: auto release commit (2026-07-03 12:09:55)

2026-07-03 12:09:55 +08:00

8.0 KiB

Raw Blame History

REQUIREMENTS

0. 技能标识（复制 REQUIREMENTS 时必填）

项	值
slug	`download-settlement-report-amazon`
中文 name	Amazon 结算报表自动下载
中文 description	在 Amazon 卖家中心自动请求并下载结算报表（Settlement）
account-manager platform_key	`amazon_sim`（若尚未注册，见 README / 本文 §7）
命名形态	标准型（verb-noun-platform）

1. 文档目标

本文档用于明确 download-settlement-report-amazon 的研发范围、交付标准、依赖关系和验收要求。
技术人员应以本文件作为开发范围依据，以避免实现偏差、范围蔓延或理解不一致。
本文档同时作为老师/实训样板：学员可复制本技能结构开发同类 Amazon / 跨境报表技能。

2. 业务背景

跨境财务实训需定期从 Amazon 下载结算报表（Settlement），用于对账、利润分析与凭证附件。
人工操作路径：登录卖家中心 → Reports → Payments 分类 → 选择 Settlement → 填写日期 → 请求 → 等待生成 → 下载 xlsx。
本技能用 Playwright RPA 在仿真环境 https://sandbox.jc2009.com/industries/ecommerce/amazon 自动完成上述流程，产出 xlsx 并写入 task_logs（task_type=download_settlement）。
禁止调用 GET/POST /api/ecommerce/amazon/reports 等 REST API 下载；必须走浏览器页面操作。

3. 开发目标

提供标准 CLI：health、version、run、logs、log-get
实现四档 adapter 中的 mock（CI 默认）与 simulator_rpa（联调）
集成 account-manager：pick-web --platform amazon_sim --lease 获取 profile_dir 与租约
登录：launch_browser_with_profile + ensure_logged_in（account-manager rpa_helpers）
下载文件保存至 {skill_data_dir}/downloads/；失败截图至 {skill_data_dir}/rpa-artifacts/{batch_id}/
可选 RpaVideoSession 录屏（中文步骤标题）

4. 功能范围

必须实现

python scripts/main.py health
python scripts/main.py version
python scripts/main.py run --date-from YYYY-MM-DD --date-to YYYY-MM-DD [--seller-code CODE]
Playwright RPA（OPENCLAW_TEST_TARGET=simulator_rpa）
mock adapter（CI 默认，OPENCLAW_TEST_TARGET=mock）
写入 task_logs（task_type=download_settlement）
下载文件保存到 {skill_data_dir}/downloads/
失败截图到 rpa-artifacts/

第一版不做

解析 xlsx 内容
多店铺批量下载
直接调 /api/ecommerce/amazon/reports API
real_rpa 真实 Amazon 生产站点

5. 非功能要求

目录结构符合 skill-template 规范；入口 scripts/main.py
Playwright 由宿主共享 runtime 提供；技能侧不要 playwright install
URL 不要放进 launch_persistent_context(args=[...])；Reports 页通过 page.goto(REPORTS_URL) 打开
元素定位优先 data-testid（F12 原则）
步骤间 random_delay；禁止 el.value=、JS 跳转
Windows UTF-8 输出；错误前缀 ERROR:

6. 输入输出要求

输入

参数	必填	默认	说明
`--date-from`	是*	`2025-12-01`	报表起始日期
`--date-to`	是*	`2025-12-31`	报表结束日期
`--seller-code`	否	页面第一个 seller	店铺代码，如 `AMA1OF6T`

* CLI 提供默认值，业务上仍须为合法 YYYY-MM-DD。

环境变量见 .env.example：AMAZON_SIM_BASE_URL、AMAZON_SIM_REPORTS_URL、OPENCLAW_TEST_TARGET 等。

成功输出（stdout JSON）

{
  "ok": true,
  "job_id": "...",
  "file_path": "...",
  "filename": "settlement_....xlsx",
  "date_from": "2025-12-01",
  "date_to": "2025-12-31"
}

失败输出

退出码非 0
stdout JSON 中 ok: false 或前置 ERROR: 行（如 ERROR:INVALID_ARGS）
task_logs.status=failed，error_msg 含原因
可选：rpa-artifacts/ 下 PNG 截图

7. 依赖的兄弟技能或外部系统

兄弟技能

account-manager：platform_key=amazon_sim；提供 profile_dir、租约、get-credential --reveal
若 amazon_sim 平台不存在，需运维在 account-manager 注册后再添加账号

添加账号示例：

python D:\OpenClaw\client-commons\account-manager\scripts\main.py account add-web \
  --platform amazon_sim \
  --login-id <邮箱> \
  --url https://sandbox.jc2009.com/industries/ecommerce/amazon/login \
  --environment simulator \
  --auth-strategy password_auto

extra_json 建议：{"logged_in_url_pattern": "/seller"}

Amazon 仿真登录：登录页为邮箱 + Continue，无复杂验证码。

外部系统

页面	URL
卖家首页	`https://sandbox.jc2009.com/industries/ecommerce/amazon/seller`
登录页	`https://sandbox.jc2009.com/industries/ecommerce/amazon/login`
Reports	`https://sandbox.jc2009.com/industries/ecommerce/amazon/seller/reports`

禁止使用 localhost:5173。

8. 不在本次范围内的内容

不解析 xlsx、不入账 Kingdee / 星航
不实现多店铺批跑
不修改 client-sandbox 源码
不修改 skill-template 源仓库
不实现 real_api / 生产 Amazon real_rpa

9. 验收标准与 RPA 步骤

RPA 步骤（与 sandbox 联调文档一致）

参考：client-sandbox/sandbox-docs/migration/from-monolith-docs/skill-integration-guide.md

account-manager pick-web --platform amazon_sim --lease → profile_dir、url、lease_token
launch_browser_with_profile + ensure_logged_in
page.goto(REPORTS_URL)（URL 不进 launch args）
等待 [data-testid="reports-page-root"]
切换到 Payments 分类（Settlement 在该 Tab；默认 Tab 为 Fulfillment）
- 优先 [data-testid="reports-tab-payments"]
- 若无 testid，用 get_by_role("button", name="Payments")
点击 [data-testid="reports-type-item-settlement"]
填写 [data-testid="reports-form-date-from"] / reports-form-date-to
可选：[data-testid="reports-form-seller-select"]
点击 [data-testid="reports-form-submit"]
轮询 [data-testid^="reports-jobs-status-"][data-status="DONE"]（超时 60s，间隔 2s）
点击 [data-testid^="reports-jobs-download-"]，expect_download 保存 xlsx
lease release
写 task_logs + 返回 JSON

仿真环境已知依赖（Payments Tab）

截至开发时，sim-ecommerce-amazon/frontend/pages/ReportsPage.jsx 中：

已定义 REPORT_TABS（含 Payments），且 settlement 类型挂载在 payments Tab 下
但页面未渲染 Tab 切换按钮（无 reports-tab-payments DOM），默认 activeTab=fulfillment，页面上仅显示 Orders 类型

因此 线上仿真 联调时，RPA 可能在步骤 5 失败（Payments Tab 不可见）。处理方式：

mock 测试必须全部通过（CI 不依赖 Tab UI）
simulator_rpa 代码已实现 Tab 切换逻辑，待 sandbox 前端补充 Tab UI 后即可联调
联调前可请 sandbox 团队在 Reports 页渲染 Tab 并添加 data-testid="reports-tab-payments"

命令验收

python tests/run_tests.py -v 全部通过
python scripts/main.py health 退出码 0
OPENCLAW_TEST_TARGET=mock python scripts/main.py run --date-from 2025-12-01 --date-to 2025-12-31 退出码 0 且产出 mock xlsx

联调验收（有账号时）

$env:OPENCLAW_TEST_TARGET="simulator_rpa"
$env:JIANGCHANG_DATA_ROOT="D:\claw-data"
$env:JIANGCHANG_USER_ID="10032"
python scripts/main.py run --date-from 2025-12-01 --date-to 2025-12-31

成功：产出 xlsx + task_logs 有 download_settlement 记录 + 退出码 0。

10. 开发注意事项

只修改本 skill 仓库；不改动其他 61 个空目录
adapter 目录：scripts/service/amazon_report_adapter/
真实浏览器联调样例：tests/integration/test_simulator_rpa_contract.py.sample（不进默认套件）

11. 变更记录

日期	版本	变更人	变更内容
2026-07-03	v1.0.0	样板实现	初版：mock + simulator_rpa + REQUIREMENTS 填实

8.0 KiB Raw Blame History Unescape Escape