201 lines
8.0 KiB
Markdown
201 lines
8.0 KiB
Markdown
# 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）
|
||
|
||
```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 注册后再添加账号
|
||
|
||
添加账号示例：
|
||
|
||
```bash
|
||
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`
|
||
|
||
1. `account-manager pick-web --platform amazon_sim --lease` → `profile_dir`、`url`、`lease_token`
|
||
2. `launch_browser_with_profile` + `ensure_logged_in`
|
||
3. `page.goto(REPORTS_URL)`（URL 不进 launch args）
|
||
4. 等待 `[data-testid="reports-page-root"]`
|
||
5. 切换到 **Payments** 分类（Settlement 在该 Tab；默认 Tab 为 Fulfillment）
|
||
- 优先 `[data-testid="reports-tab-payments"]`
|
||
- 若无 testid，用 `get_by_role("button", name="Payments")`
|
||
6. 点击 `[data-testid="reports-type-item-settlement"]`
|
||
7. 填写 `[data-testid="reports-form-date-from"]` / `reports-form-date-to`
|
||
8. 可选：`[data-testid="reports-form-seller-select"]`
|
||
9. 点击 `[data-testid="reports-form-submit"]`
|
||
10. 轮询 `[data-testid^="reports-jobs-status-"][data-status="DONE"]`（超时 60s，间隔 2s）
|
||
11. 点击 `[data-testid^="reports-jobs-download-"]`，`expect_download` 保存 xlsx
|
||
12. `lease release`
|
||
13. 写 `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
|
||
|
||
### 联调验收（有账号时）
|
||
|
||
```powershell
|
||
$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 填实 |
|