# 云图报告自动创建 PRD

## 一、项目基本信息

- 项目路径：`/Users/wxs/projects/browser_script/scriptCat/yuntu/yuntuReportFilling`
- 项目类型：ScriptCat 浏览器脚本 + Node.js 后端服务 + PostgreSQL
- 业务目标：在云图页面中复用最近一次成功创建报告的请求参数，自动创建一份同比报告，并将关键数据持久化到数据库
- 核心价值：
  - 降低人工重复创建报告的成本
  - 自动将时间范围回退一年，方便做同比分析
  - 为后续追溯和排查保留完整 payload 与 report_id

## 二、业务背景

当前用户在云图页面手动创建报告后，还需要再次输入或复制相同配置，才能创建同比报告。该过程重复且容易出错。

本项目通过监听用户首次手动创建报告时的请求与响应，缓存最近一次成功的 payload；当用户点击右侧按钮后，脚本自动将顶层 `startTime` 与 `endTime` 各回退一年，并再次调用云图创建接口完成报告复制。

## 三、范围说明

### 本期范围

- 监听并识别云图“创建报告”接口
- 记录最近一次成功创建报告的完整 payload
- 在页面右侧提供“一键复制同比报告”按钮
- 自动回退顶层 `startTime` / `endTime` 一年
- 调用后端 API 持久化成功创建的报告数据
- 将手动创建报告和脚本自动创建报告统一写入 PostgreSQL

### 本期不做

- 不从数据库反向同步最新 payload 到浏览器本地
- 不支持多条历史 payload 管理
- 不支持用户手动编辑复制前的字段
- 不修改除顶层 `startTime` / `endTime` 外的其他字段

## 四、目标页面与第三方接口

### 4.1 目标页面

- 页面域名：`https://yuntu.oceanengine.com`
- 目标页面路径：`/yuntu_brand/ecom/product/segmentedMarketcreation`
- 页面示例：`https://yuntu.oceanengine.com/yuntu_brand/ecom/product/segmentedMarketcreation?aadvid=1648829117232140`

### 4.2 需监听与复用的云图接口

- 请求方法：`POST`
- 接口路径：`/product_node/v2/api/segmentedMarket/createSegmentedMarket`
- 完整示例：
  - `https://yuntu.oceanengine.com/product_node/v2/api/segmentedMarket/createSegmentedMarket?aadvid=1648829117232140`
- 关键识别条件：
  - 请求方法必须为 `POST`
  - 路径必须匹配 `createSegmentedMarket`
  - 查询参数中包含 `aadvid`

### 4.3 第三方接口约束

- 浏览器脚本调用该接口时，必须复用当前用户浏览器会话中的登录态
- 不允许在脚本或后端中硬编码 Cookie、CSRF Token 等敏感信息
- 只允许浏览器脚本直接调用云图接口；后端不直接代调云图接口
- 接口成功后，从响应体 `data.reportId` 中提取业务 `report_id`

## 五、核心流程

### 5.1 手动创建报告并记录

触发时机：用户在页面中手动点击“创建报告”并且云图接口返回成功。

执行流程：

1. 监听 `createSegmentedMarket` 请求与响应。
2. 提取请求 payload 与请求 URL 中的 `aadvid`。
3. 校验响应成功，且响应体存在 `data.reportId`。
4. 将以下内容写入浏览器本地：
   - `lastReportPayload`：最近一次成功创建报告的完整 payload
   - `lastReportMeta`：最近一次成功创建报告的元信息，至少包含 `reportId`、`aadvid`、`sourceType`、`capturedAt`
5. 如果本地写入失败，立即报错，并保持按钮不可用状态；本次不调用后端持久化接口。
6. 如果本地写入成功，调用后端 API 将本次手动创建报告写入数据库。

### 5.2 一键复制同比报告

触发时机：用户点击页面右侧“一键复制同比报告”按钮。

执行流程：

1. 读取 `lastReportPayload` 与 `lastReportMeta`。
2. 若本地不存在有效 payload，则按钮保持置灰，不允许点击。
3. 深拷贝 payload，仅修改顶层 `startTime` 和 `endTime`。
4. 使用修改后的 payload 调用云图创建接口。
5. 接口成功后，从响应体中读取新的 `data.reportId`。
6. 先将新的 payload 和元信息覆盖写入本地存储。
7. 本地写入成功后，调用后端 API 持久化本次自动复制创建的报告数据。
8. 持久化成功后，给出成功提示，并显示新的 `report_id`。

失败处理：

- 云图接口调用失败：提示“同比报告创建失败”，保留旧的本地 payload，不调用后端 API。
- 本地覆盖写入失败：提示“本地缓存更新失败”，不调用后端 API，按钮恢复可点击。
- 后端持久化失败：提示“报告已创建成功，但数据库记录失败”，保留新的本地 payload，按钮恢复可点击。

## 六、时间处理规则

### 6.1 处理目标

将顶层 `startTime` 与 `endTime` 各回退一个自然年，用于生成同比报告。

### 6.2 处理原则

- 只处理 payload 顶层字段：
  - `startTime`
  - `endTime`
- 其他字段保持原值不变
- 日期格式统一为 `YYYY-MM-DD`
- 使用“自然年回退”规则，而不是简单减去 365 天

### 6.3 具体算法

1. 将 `startTime`、`endTime` 解析为日期对象。
2. 分别将年份减 1，尽量保持原始月与日不变。
3. 如果目标年份不存在该日期，则回退到目标月份最后一天。

示例：

```javascript
// 正常日期
2025-03-01 -> 2024-03-01
2026-02-28 -> 2025-02-28

// 闰年特殊情况
2024-02-29 -> 2023-02-28
```

该规则可以最大限度保持同比区间的自然日语义。

## 七、页面交互设计

### 7.1 按钮位置

- 按钮固定显示在页面右侧中部
- 文案建议：`一键复制同比报告`

### 7.2 按钮状态

- 默认状态：
  - 当本地存在有效 `lastReportPayload` 时可点击
  - 当本地不存在有效 `lastReportPayload` 时置灰且不可点击
- 加载状态：
  - 点击后立即进入 loading
  - loading 期间禁止再次点击，防止重复创建
- 完成状态：
  - 成功后 toast 提示创建成功，并展示新 `report_id`
  - 成功后不自动跳转页面，保持用户留在当前页面，避免打断连续操作

### 7.3 状态恢复规则

- 用户再次手动成功创建报告后，按钮状态根据本地缓存重新计算
- 任何失败场景都需要正确退出 loading 状态

## 八、浏览器本地存储设计

### 8.1 存储方式

- 使用 `GM_setValue` / `GM_getValue`

### 8.2 存储键

- `lastReportPayload`
- `lastReportMeta`

### 8.3 存储内容

`lastReportPayload`：

```json
{
  "endTime": "2026-02-28",
  "name": "测试",
  "periodType": "MONTH",
  "startTime": "2025-03-01"
}
```

`lastReportMeta`：

```json
{
  "reportId": "123456789",
  "aadvid": "1648829117232140",
  "sourceType": "MANUAL_CAPTURE",
  "capturedAt": "2026-03-31T15:00:00+08:00"
}
```

### 8.4 更新规则

- 每次成功创建报告后覆盖写入
- 始终只保留最近一次成功创建报告的数据
- 脚本启动时不从数据库同步数据

## 九、后端 API 设计

后端职责仅为持久化成功创建的报告数据，不直接调用云图接口。

### 9.1 保存报告记录

- 方法：`POST`
- 路径：`/api/reports`
- 用途：保存一条已创建成功的报告记录

请求体：

```json
{
  "reportId": "123456789",
  "sourceType": "AUTO_COPY",
  "sourceReportId": "987654321",
  "aadvid": "1648829117232140",
  "name": "测试",
  "price": ["1,100", "101,100000"],
  "rules": [
    {
      "keywords": ["奶粉"],
      "op": "INCLUDE"
    }
  ],
  "analysisDims": [
    "MARKETOVERVIEW",
    "PRODUCTINSIGHT",
    "MARKETCOMPOSING",
    "CONSUMERINSIGHT"
  ],
  "categories": [],
  "channels": ["ALL"],
  "startTime": "2024-03-01",
  "endTime": "2025-02-28",
  "periodType": "MONTH",
  "userName": "qichumiaosi@163.com",
  "payload": {}
}
```

字段说明：

- `reportId`：云图响应中的 `data.reportId`
- `sourceType`：取值为 `MANUAL_CAPTURE` 或 `AUTO_COPY`
- `sourceReportId`：
  - `MANUAL_CAPTURE` 时可为空
  - `AUTO_COPY` 时必填，表示复制来源报告 ID
- `aadvid`：从页面 URL 或请求 URL 中提取
- `payload`：完整请求体，原样保存

成功响应：

```json
{
  "success": true,
  "data": {
    "id": 1,
    "reportId": "123456789"
  }
}
```

失败响应：

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "sourceReportId is required when sourceType is AUTO_COPY"
  }
}
```

### 9.2 后端校验规则

- `reportId` 必填
- `sourceType` 必须为 `MANUAL_CAPTURE` 或 `AUTO_COPY`
- `AUTO_COPY` 场景下 `sourceReportId` 必填
- `payload` 必须为合法 JSON
- `startTime`、`endTime` 必须符合 `YYYY-MM-DD`
- 数据库以 `report_id` 做唯一约束，重复写入时返回成功并提示已存在，保证接口幂等

## 十、数据库设计

### 10.1 表设计说明

表名：`public.yuntu_report_info`

字段设计目标：

- 记录云图返回的业务 `report_id`
- 区分手动创建和自动复制
- 能追溯自动复制来源
- 保存结构化字段与完整 payload

### 10.2 建表 SQL

```sql
DROP TABLE IF EXISTS public.yuntu_report_info;

CREATE TABLE public.yuntu_report_info (
    id BIGSERIAL PRIMARY KEY,
    report_id VARCHAR(64) NOT NULL,
    source_type VARCHAR(32) NOT NULL,
    source_report_id VARCHAR(64) NULL,
    aadvid VARCHAR(32) NOT NULL,
    name TEXT NOT NULL,
    price JSONB NOT NULL DEFAULT '[]'::jsonb,
    rules JSONB NOT NULL DEFAULT '[]'::jsonb,
    analysis_dims JSONB NOT NULL DEFAULT '[]'::jsonb,
    categories JSONB NOT NULL DEFAULT '[]'::jsonb,
    transaction_channels JSONB NOT NULL DEFAULT '[]'::jsonb,
    start_time DATE NOT NULL,
    end_time DATE NOT NULL,
    period_type VARCHAR(32) NULL,
    user_name TEXT NULL,
    payload JSONB NOT NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    CONSTRAINT uq_yuntu_report_info_report_id UNIQUE (report_id),
    CONSTRAINT chk_yuntu_report_info_source_type
        CHECK (source_type IN ('MANUAL_CAPTURE', 'AUTO_COPY')),
    CONSTRAINT chk_yuntu_report_info_copy_source
        CHECK (
            (source_type = 'MANUAL_CAPTURE' AND source_report_id IS NULL)
            OR
            (source_type = 'AUTO_COPY' AND source_report_id IS NOT NULL)
        )
);

CREATE INDEX idx_yuntu_report_info_source_report_id
    ON public.yuntu_report_info (source_report_id);

CREATE INDEX idx_yuntu_report_info_created_at
    ON public.yuntu_report_info (created_at DESC);

CREATE INDEX idx_yuntu_report_info_aadvid_created_at
    ON public.yuntu_report_info (aadvid, created_at DESC);

CREATE OR REPLACE FUNCTION public.set_yuntu_report_info_updated_at()
RETURNS TRIGGER AS $$
BEGIN
    NEW.updated_at = NOW();
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

DROP TRIGGER IF EXISTS trg_yuntu_report_info_updated_at ON public.yuntu_report_info;

CREATE TRIGGER trg_yuntu_report_info_updated_at
BEFORE UPDATE ON public.yuntu_report_info
FOR EACH ROW
EXECUTE FUNCTION public.set_yuntu_report_info_updated_at();
```

### 10.3 字段映射

| 数据库字段 | 来源字段 | 说明 |
| --- | --- | --- |
| `report_id` | `response.data.reportId` | 云图报告 ID |
| `source_type` | 脚本内部标记 | 手动捕获或自动复制 |
| `source_report_id` | `lastReportMeta.reportId` | 自动复制来源报告 ID |
| `aadvid` | query 参数 `aadvid` | 广告主 ID |
| `name` | `payload.name` | 报告名称 |
| `price` | `payload.price` | 价格区间 |
| `rules` | `payload.rules` | 规则配置 |
| `analysis_dims` | `payload.analysisDims` | 分析维度 |
| `categories` | `payload.categories` | 类目树 |
| `transaction_channels` | `payload.channels` | 渠道信息 |
| `start_time` | `payload.startTime` | 报告开始日期 |
| `end_time` | `payload.endTime` | 报告结束日期 |
| `period_type` | `payload.periodType` | 周期类型 |
| `user_name` | `payload.userName` | 用户名 |
| `payload` | 完整 payload | 原始请求体 |

## 十一、错误处理

### 11.1 浏览器脚本侧

- 拦截不到目标接口：不报错，不显示成功态
- 响应中缺少 `data.reportId`：提示“未获取到 report_id，无法记录”
- 本地存储失败：立即报错，并终止当前脚本链路
- 用户重复点击：忽略后续点击并保持 loading
- 请求超时：提示失败并恢复按钮

### 11.2 后端侧

- 参数校验失败：返回 4xx 与明确错误信息
- 数据库写入失败：返回 5xx 与错误码
- 重复 `report_id` 写入：按幂等成功处理，不重复插入

## 十二、验收标准

1. 用户在目标页面手动成功创建报告后，脚本能够识别目标接口，并从响应体中正确提取 `data.reportId`。
2. 手动创建成功后，本地必须成功写入 `lastReportPayload` 和 `lastReportMeta`；若写入失败，页面明确报错且按钮不可点击。
3. 手动创建成功且本地写入成功后，后端数据库新增一条 `source_type = 'MANUAL_CAPTURE'` 的记录，且 `report_id` 与云图响应一致。
4. 当本地不存在有效 payload 时，右侧按钮必须置灰且无法点击。
5. 点击“一键复制同比报告”后，脚本只能修改顶层 `startTime` 和 `endTime`，其他字段与来源 payload 保持一致。
6. 自动复制成功后，新报告的时间范围必须按自然年回退一年的规则生成；闰年日期按目标月最后一天处理。
7. 自动复制成功后，本地缓存必须被新 payload 和新 `reportId` 覆盖；数据库新增一条 `source_type = 'AUTO_COPY'` 的记录，且 `source_report_id` 正确指向来源报告。
8. 点击按钮进入 loading 后，用户无法重复触发创建；无论成功还是失败，流程结束后按钮状态必须恢复正确。
9. 后端接口重复接收同一个 `report_id` 时，不得插入重复数据。
10. 整个方案不得在代码或配置中硬编码用户 Cookie、Token 等敏感登录信息。