# 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 填实 |