docs/API_ZH.md

# PolyWeather API 文档（v1.4.0）

最后更新：`2026-03-14`

本文档描述当前对外可用 API 口径（`web/app.py` + `frontend/app/api/*`）。

## 1. 基础信息

- 后端直连：`http://127.0.0.1:8000`
- 前端 BFF：`https://polyweather-pro.vercel.app/api/*`
- 返回格式：`application/json`

## 2. 请求链路

```mermaid
flowchart LR
    FE["Browser / Dashboard"] --> BFF["Next.js Route Handlers (/api/*)"]
    BFF --> API["FastAPI (/web/app.py)"]
    API --> WX["Weather Collector"]
    API --> ANA["DEB + Trend + Probability + Market Scan"]
    API --> PAY["Payment Intent + Event + Confirm Loops"]
```

## 3. 天气分析接口

| 接口 | 方法 | 用途 |
| :-- | :-- | :-- |
| `/api/cities` | GET | 监控城市列表 |
| `/api/city/{name}` | GET | 城市主分析 |
| `/api/city/{name}/summary` | GET | 轻量摘要 |
| `/api/city/{name}/detail` | GET | 聚合详情（含 market_scan） |
| `/api/history/{name}` | GET | 历史对账 |

### `GET /api/city/{name}/detail`

可选参数：

- `force_refresh=true|false`
- `market_slug=<slug>`
- `target_date=YYYY-MM-DD`

重点字段：

- `market_scan.available`
- `market_scan.signal_label`
- `market_scan.anchor_model / anchor_high / anchor_settlement`
- `market_scan.yes_buy / no_buy`
- `market_scan.primary_market.tradable`

## 4. 鉴权与账户接口

| 接口 | 方法 | 用途 |
| :-- | :-- | :-- |
| `/api/auth/me` | GET | 当前登录态、积分、订阅状态 |

`/api/auth/me` 关键字段：

- `authenticated`
- `user_id`, `email`
- `points`, `weekly_points`, `weekly_rank`
- `subscription_active`, `subscription_plan_code`, `subscription_expires_at`

## 5. 支付接口（P1）

| 接口 | 方法 | 用途 |
| :-- | :-- | :-- |
| `/api/payments/config` | GET | 支付配置、代币列表、套餐、积分抵扣规则 |
| `/api/payments/wallets` | GET | 当前用户已绑定钱包 |
| `/api/payments/wallets/challenge` | POST | 获取绑定签名 challenge |
| `/api/payments/wallets/verify` | POST | 提交签名并绑定钱包 |
| `/api/payments/intents` | POST | 创建支付意图（intent） |
| `/api/payments/intents/{intent_id}` | GET | 查询 intent 最新状态 |
| `/api/payments/intents/{intent_id}/submit` | POST | 提交交易哈希 |
| `/api/payments/intents/{intent_id}/confirm` | POST | 手动触发确认 |

### 支付状态建议

前端流程建议：

1. `POST /intents`
2. 钱包发链上交易
3. `POST /submit`
4. `POST /confirm`
5. 若 pending，轮询 `GET /intents/{id}` 直到 `confirmed`

## 6. 缓存策略（当前）

- `cities` / `summary` / `history`：BFF 支持 `ETag + 304`
- `summary?force_refresh=true`：`Cache-Control: no-store`
- 详情接口与支付接口：`no-store`

## 7. 调试示例

### 查询未来日期 market_scan

```bash
curl -s "http://127.0.0.1:8000/api/city/ankara/detail?force_refresh=true&target_date=2026-03-12"
```

### 校验支付配置

```bash
curl -s http://127.0.0.1:8000/api/payments/config | python3 -m json.tool
```

### 观察支付自动补单

```bash
docker compose logs -f polyweather | egrep "payment event loop started|payment confirm loop started|payment auto-confirmed"
```

## 8. 开源口径说明

对外公开文档仅覆盖通用 API 契约。生产商业策略参数不在公开文档披露。

详见：[Open-Core 与商用边界](OPEN_CORE_POLICY.md)
-											release: v1.4.0
										
										
											2026-03-20 19:13:14 +08:00
+								# PolyWeather API 文档（v1.4.0）
-											feat: Implement multi-source weather data collection from OpenWeatherMap, Visual Crossing, and NOAA METAR sources.
										
										
											2026-03-08 09:57:08 +08:00
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								最后更新：`2026-03-14`
-											feat: Implement multi-source weather data collection from OpenWeatherMap, Visual Crossing, and NOAA METAR sources.
										
										
											2026-03-08 09:57:08 +08:00
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								本文档描述当前对外可用 API 口径（`web/app.py` + `frontend/app/api/*`）。
-											feat: Implement multi-source weather data collection from OpenWeatherMap, Visual Crossing, and NOAA METAR sources.
										
										
											2026-03-08 09:57:08 +08:00
 								## 1. 基础信息
-											docs: Add commercialization, technical debt, and frontend documentation, and update project READMEs.
										
										
											2026-03-12 12:01:29 +08:00
+								- 后端直连：`http://127.0.0.1:8000`
 								- 前端 BFF：`https://polyweather-pro.vercel.app/api/*`
-											docs: Add comprehensive documentation for commercialization and technical debt, and streamline the main README.
										
										
											2026-03-11 11:18:48 +08:00
+								- 返回格式：`application/json`
-											feat: Implement multi-source weather data collection from OpenWeatherMap, Visual Crossing, and NOAA METAR sources.
										
										
											2026-03-08 09:57:08 +08:00
-											docs: Add commercialization, technical debt, and frontend documentation, and update project READMEs.
										
										
											2026-03-12 12:01:29 +08:00
+								## 2. 请求链路
-											docs: Add comprehensive documentation for commercialization and technical debt, and streamline the main README.
										
										
											2026-03-11 11:18:48 +08:00
 								```mermaid
-											docs: Add commercialization, technical debt, and frontend documentation, and update project READMEs.
										
										
											2026-03-12 12:01:29 +08:00
+								flowchart LR
 								    FE["Browser / Dashboard"] --> BFF["Next.js Route Handlers (/api/*)"]
 								    BFF --> API["FastAPI (/web/app.py)"]
 								    API --> WX["Weather Collector"]
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								    API --> ANA["DEB + Trend + Probability + Market Scan"]
 								    API --> PAY["Payment Intent + Event + Confirm Loops"]
-											docs: Add comprehensive documentation for commercialization and technical debt, and streamline the main README.
										
										
											2026-03-11 11:18:48 +08:00
+								```
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								## 3. 天气分析接口
-											docs: Add comprehensive documentation for commercialization and technical debt, and streamline the main README.
										
										
											2026-03-11 11:18:48 +08:00
-											docs: Add commercialization, technical debt, and frontend documentation, and update project READMEs.
										
										
											2026-03-12 12:01:29 +08:00
+								| 接口 | 方法 | 用途 |
 								| :-- | :-- | :-- |
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								| `/api/cities` | GET | 监控城市列表 |
 								| `/api/city/{name}` | GET | 城市主分析 |
 								| `/api/city/{name}/summary` | GET | 轻量摘要 |
 								| `/api/city/{name}/detail` | GET | 聚合详情（含 market_scan） |
 								| `/api/history/{name}` | GET | 历史对账 |
-											feat: introduce PolyWeather web map API and frontend with integrated weather data collection and analysis.
										
										
											2026-03-09 04:41:24 +08:00
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								### `GET /api/city/{name}/detail`
-											feat: introduce PolyWeather web map API and frontend with integrated weather data collection and analysis.
										
										
											2026-03-09 04:41:24 +08:00
-											docs: Add comprehensive documentation for commercialization and technical debt, and streamline the main README.
										
										
											2026-03-11 11:18:48 +08:00
+								可选参数：
 								- `force_refresh=true|false`
-											docs: Add commercialization, technical debt, and frontend documentation, and update project READMEs.
										
										
											2026-03-12 12:01:29 +08:00
+								- `market_slug=<slug>`
 								- `target_date=YYYY-MM-DD`
-											docs: Add comprehensive documentation for commercialization and technical debt, and streamline the main README.
										
										
											2026-03-11 11:18:48 +08:00
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								重点字段：
-											docs: Add commercialization, technical debt, and frontend documentation, and update project READMEs.
										
										
											2026-03-12 12:01:29 +08:00
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								- `market_scan.available`
 								- `market_scan.signal_label`
 								- `market_scan.anchor_model / anchor_high / anchor_settlement`
 								- `market_scan.yes_buy / no_buy`
 								- `market_scan.primary_market.tradable`
-											feat: Implement multi-source weather data collection from OpenWeatherMap, Visual Crossing, and NOAA METAR sources.
										
										
											2026-03-08 09:57:08 +08:00
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								## 4. 鉴权与账户接口
-											feat: Implement multi-source weather data collection from OpenWeatherMap, Visual Crossing, and NOAA METAR sources.
										
										
											2026-03-08 09:57:08 +08:00
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								| 接口 | 方法 | 用途 |
 								| :-- | :-- | :-- |
 								| `/api/auth/me` | GET | 当前登录态、积分、订阅状态 |
-											feat: introduce PolyWeather web map API and frontend with integrated weather data collection and analysis.
										
										
											2026-03-09 04:41:24 +08:00
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								`/api/auth/me` 关键字段：
-											feat: Implement multi-source weather data collection from OpenWeatherMap, Visual Crossing, and NOAA METAR sources.
										
										
											2026-03-08 09:57:08 +08:00
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								- `authenticated`
 								- `user_id`, `email`
 								- `points`, `weekly_points`, `weekly_rank`
 								- `subscription_active`, `subscription_plan_code`, `subscription_expires_at`
-											feat: Implement multi-source weather data collection from OpenWeatherMap, Visual Crossing, and NOAA METAR sources.
										
										
											2026-03-08 09:57:08 +08:00
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								## 5. 支付接口（P1）
-											feat: Implement multi-source weather data collection from OpenWeatherMap, Visual Crossing, and NOAA METAR sources.
										
										
											2026-03-08 09:57:08 +08:00
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								| 接口 | 方法 | 用途 |
 								| :-- | :-- | :-- |
 								| `/api/payments/config` | GET | 支付配置、代币列表、套餐、积分抵扣规则 |
 								| `/api/payments/wallets` | GET | 当前用户已绑定钱包 |
 								| `/api/payments/wallets/challenge` | POST | 获取绑定签名 challenge |
 								| `/api/payments/wallets/verify` | POST | 提交签名并绑定钱包 |
 								| `/api/payments/intents` | POST | 创建支付意图（intent） |
 								| `/api/payments/intents/{intent_id}` | GET | 查询 intent 最新状态 |
 								| `/api/payments/intents/{intent_id}/submit` | POST | 提交交易哈希 |
 								| `/api/payments/intents/{intent_id}/confirm` | POST | 手动触发确认 |
-											feat: Implement multi-source weather data collection from OpenWeatherMap, Visual Crossing, and NOAA METAR sources.
										
										
											2026-03-08 09:57:08 +08:00
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								### 支付状态建议
-											feat: Implement multi-source weather data collection from OpenWeatherMap, Visual Crossing, and NOAA METAR sources.
										
										
											2026-03-08 09:57:08 +08:00
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								前端流程建议：
-											feat: Implement multi-source weather data collection from OpenWeatherMap, Visual Crossing, and NOAA METAR sources.
										
										
											2026-03-08 09:57:08 +08:00
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+. `POST /intents`
 . 钱包发链上交易
 . `POST /submit`
 . `POST /confirm`
 . 若 pending，轮询 `GET /intents/{id}` 直到 `confirmed`
-											feat: Implement multi-source weather data collection from OpenWeatherMap, Visual Crossing, and NOAA METAR sources.
										
										
											2026-03-08 09:57:08 +08:00
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								## 6. 缓存策略（当前）
-											feat: introduce PolyWeather web map API and frontend with integrated weather data collection and analysis.
										
										
											2026-03-09 04:41:24 +08:00
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								- `cities` / `summary` / `history`：BFF 支持 `ETag + 304`
 								- `summary?force_refresh=true`：`Cache-Control: no-store`
 								- 详情接口与支付接口：`no-store`
-											feat: Implement multi-source weather data collection from OpenWeatherMap, Visual Crossing, and NOAA METAR sources.
										
										
											2026-03-08 09:57:08 +08:00
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								## 7. 调试示例
-											feat: Implement multi-source weather data collection from OpenWeatherMap, Visual Crossing, and NOAA METAR sources.
										
										
											2026-03-08 09:57:08 +08:00
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								### 查询未来日期 market_scan
-											docs: Add comprehensive documentation for commercialization and technical debt, and streamline the main README.
										
										
											2026-03-11 11:18:48 +08:00
-											docs: Add commercialization, technical debt, and frontend documentation, and update project READMEs.
										
										
											2026-03-12 12:01:29 +08:00
+								```bash
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								curl -s "http://127.0.0.1:8000/api/city/ankara/detail?force_refresh=true&target_date=2026-03-12"
-											docs: Add commercialization, technical debt, and frontend documentation, and update project READMEs.
										
										
											2026-03-12 12:01:29 +08:00
+								```
-											docs: Add comprehensive documentation for commercialization and technical debt, and streamline the main README.
										
										
											2026-03-11 11:18:48 +08:00
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								### 校验支付配置
-											feat: introduce PolyWeather web map API and frontend with integrated weather data collection and analysis.
										
										
											2026-03-09 04:41:24 +08:00
-											docs: Add commercialization, technical debt, and frontend documentation, and update project READMEs.
										
										
											2026-03-12 12:01:29 +08:00
+								```bash
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								curl -s http://127.0.0.1:8000/api/payments/config | python3 -m json.tool
-											docs: Add commercialization, technical debt, and frontend documentation, and update project READMEs.
										
										
											2026-03-12 12:01:29 +08:00
+								```
-											feat: introduce PolyWeather web map API and frontend with integrated weather data collection and analysis.
										
										
											2026-03-09 04:41:24 +08:00
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								### 观察支付自动补单
-											feat: introduce PolyWeather web map API and frontend with integrated weather data collection and analysis.
										
										
											2026-03-09 04:41:24 +08:00
-											docs: Add commercialization, technical debt, and frontend documentation, and update project READMEs.
										
										
											2026-03-12 12:01:29 +08:00
+								```bash
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								docker compose logs -f polyweather | egrep "payment event loop started|payment confirm loop started|payment auto-confirmed"
-											docs: Add commercialization, technical debt, and frontend documentation, and update project READMEs.
										
										
											2026-03-12 12:01:29 +08:00
+								```
-											feat: introduce PolyWeather web map API and frontend with integrated weather data collection and analysis.
										
										
											2026-03-09 04:41:24 +08:00
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								## 8. 开源口径说明
-											feat: Introduce API and technical debt documentation, and enhance frontend caching, mispricing radar, and AI decision logic.
										
										
											2026-03-12 10:43:31 +08:00
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								对外公开文档仅覆盖通用 API 契约。生产商业策略参数不在公开文档披露。
-											feat: Implement multi-source weather data collection from OpenWeatherMap, Visual Crossing, and NOAA METAR sources.
										
										
											2026-03-08 09:57:08 +08:00
-											feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.
										
										
											2026-03-14 10:53:53 +08:00
+								详见：[Open-Core 与商用边界](OPEN_CORE_POLICY.md)