gavindiaz/PolyWeather
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refresh docs for observability, payments, and SQLite rollout

Browse Source
This commit is contained in:
2569718930@qq.com
2026-03-21 00:03:18 +08:00
parent ddf909f690
commit e4b8d71653
7 changed files with 177 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/API_ZH.md
+43 -7
View File
@@ -1,8 +1,8 @@
# PolyWeather API 文档（v1.4.0）
最后更新：`2026-03-14`
最后更新：`2026-03-20`
本文档描述当前对外可用 API 口径（`web/app.py` + `frontend/app/api/*`）。
本文档描述当前对外可用 API 口径（`web/app.py` + `web/routes.py` + `frontend/app/api/*`）。
## 1. 基础信息
@@ -15,10 +15,11 @@
```mermaid
flowchart LR
FE["Browser / Dashboard"] --> BFF["Next.js Route Handlers (/api/*)"]
BFF --> API["FastAPI (/web/app.py)"]
BFF --> API["FastAPI (/web/app.py + /web/routes.py)"]
API --> WX["Weather Collector"]
API --> ANA["DEB + Trend + Probability + Market Scan"]
API --> PAY["Payment Intent + Event + Confirm Loops"]
API --> OBS["healthz / system status / metrics"]
```
## 3. 天气分析接口
@@ -60,11 +61,12 @@ flowchart LR
- `points`, `weekly_points`, `weekly_rank`
- `subscription_active`, `subscription_plan_code`, `subscription_expires_at`
## 5. 支付接口（P1）
## 5. 支付接口
| 接口 | 方法 | 用途 |
| :-- | :-- | :-- |
| `/api/payments/config` | GET | 支付配置、代币列表、套餐、积分抵扣规则 |
| `/api/payments/runtime` | GET | 支付运行态、RPC 状态、event loop 状态、最近审计事件 |
| `/api/payments/wallets` | GET | 当前用户已绑定钱包 |
| `/api/payments/wallets/challenge` | POST | 获取绑定签名 challenge |
| `/api/payments/wallets/verify` | POST | 提交签名并绑定钱包 |
@@ -83,13 +85,35 @@ flowchart LR
4. `POST /confirm`
5. 若 pending，轮询 `GET /intents/{id}` 直到 `confirmed`
## 6. 缓存策略（当前）
## 6. 运维与观测接口
| 接口 | 方法 | 用途 |
| :-- | :-- | :-- |
| `/healthz` | GET | 基础健康检查 |
| `/api/system/status` | GET | 系统状态、功能开关、rollout 状态、轻量指标摘要 |
| `/metrics` | GET | Prometheus 风格指标导出 |
`/api/system/status` 当前会包含：
- `features.state_storage_mode`
- `probability.decision`
- `probability.ready_for_primary`
- `metrics`
`/metrics` 当前会导出：
- `polyweather_http_requests_total`
- `polyweather_http_request_duration_ms_*`
- `polyweather_source_requests_total`
- `polyweather_source_request_duration_ms_*`
## 7. 缓存策略（当前）
- `cities` / `summary` / `history`：BFF 支持 `ETag + 304`
- `summary?force_refresh=true`：`Cache-Control: no-store`
- 详情接口与支付接口：`no-store`
## 7. 调试示例
## 8. 调试示例
### 查询未来日期 market_scan
@@ -103,13 +127,25 @@ curl -s "http://127.0.0.1:8000/api/city/ankara/detail?force_refresh=true&target_
curl -s http://127.0.0.1:8000/api/payments/config | python3 -m json.tool
```
### 查看支付运行态
```bash
curl -s http://127.0.0.1:8000/api/payments/runtime | python3 -m json.tool
```
### 查看系统状态
```bash
curl -s http://127.0.0.1:8000/api/system/status | python3 -m json.tool
```
### 观察支付自动补单
```bash
docker compose logs -f polyweather | egrep "payment event loop started|payment confirm loop started|payment auto-confirmed"
```
## 8. 开源口径说明
## 9. 开源口径说明
对外公开文档仅覆盖通用 API 契约。生产商业策略参数不在公开文档披露。
docs/CONFIGURATION_ZH.md
+10 -25
View File
@@ -78,6 +78,7 @@ PolyWeather 的环境变量很多，但不是所有变量都属于同一层级
- `TELEGRAM_CHAT_ID`
- `POLYWEATHER_RUNTIME_DATA_DIR`
- `POLYWEATHER_DB_PATH`
- `POLYWEATHER_STATE_STORAGE_MODE`
前端：
@@ -100,6 +101,7 @@ PolyWeather 的环境变量很多，但不是所有变量都属于同一层级
- `POLYWEATHER_AUTH_ENABLED`
- `POLYWEATHER_AUTH_REQUIRED`
- `POLYWEATHER_AUTH_REQUIRE_SUBSCRIPTION`
- `POLYWEATHER_STATE_STORAGE_MODE`
- `POLYWEATHER_PAYMENT_ENABLED`
- `POLYMARKET_MARKET_SCAN_ENABLED`
- `POLYGON_WALLET_WATCH_ENABLED`
@@ -115,6 +117,7 @@ PolyWeather 的环境变量很多，但不是所有变量都属于同一层级
- 各类 `*_TIMEOUT_SEC`
- 各类 `*_COOLDOWN_SEC`
- 各类 `*_INTERVAL_SEC`
- `POLYWEATHER_PAYMENT_RPC_URLS`
策略：
@@ -190,6 +193,7 @@ TELEGRAM_BOT_TOKEN=...
TELEGRAM_CHAT_ID=...
POLYWEATHER_RUNTIME_DATA_DIR=/var/lib/polyweather
POLYWEATHER_DB_PATH=/var/lib/polyweather/polyweather.db
POLYWEATHER_STATE_STORAGE_MODE=dual
UID=1000
GID=1000
POLYWEATHER_AUTH_ENABLED=true
@@ -206,6 +210,8 @@ POLYWEATHER_BACKEND_ENTITLEMENT_TOKEN=...
- Windows / macOS 一般可以直接保留默认值。
- `POLYWEATHER_RUNTIME_DATA_DIR` 建议放在仓库外，例如 `/var/lib/polyweather`。
- `docker-compose.yml` 会把这个目录同时挂载到容器内的 `/var/lib/polyweather` 和 `/app/data`，兼容现有缓存与 SQLite 路径。
- `POLYWEATHER_STATE_STORAGE_MODE` 当前推荐先用 `dual`，验证后再切 `sqlite`。
- `POLYWEATHER_PAYMENT_RPC_URLS` 支持逗号分隔多个 RPC；如果暂时只用单 RPC，也可以继续只配 `POLYWEATHER_PAYMENT_RPC_URL`。
## 7. 当前建议的运维规则
@@ -246,41 +252,20 @@ POLYWEATHER_BACKEND_ENTITLEMENT_TOKEN=...
- 使用者只需要先关心 10-20 个关键变量
- 其余变量保持默认即可
## 9. 推荐的下一步
当前已经完成：
## 9. 当前已经完成的配置治理
1. 根 `.env.example` 收口
2. `.env.secrets.example` 新增
3. 本文档新增
3. 前端 `.env.example` 收口
4. 运行时配置校验脚本新增
5. 支付运行态与多 RPC 配置支持
6. 运行态 SQLite 迁移配置支持
## 10. 配置校验命令
在不启动服务的情况下，你可以直接检查配置：
检查 Web：
```bash
python scripts/validate_runtime_env.py --component web
```
检查 Bot：
```bash
python scripts/validate_runtime_env.py --component bot
```
返回规则：
- 退出码 `0`：当前配置通过
- 退出码 `1`：当前配置存在关键缺失
如果某个功能已启用但缺关键变量，脚本会直接报错。
## 11. 推荐的下一步
后续最值得继续做的是：
1. 在 GitHub / Vercel / VPS 三侧固化同一套变量命名
2. 给生产部署增加一次性配置审计清单
docs/TECH_DEBT.md
+28 -17
View File
@@ -1,62 +1,73 @@
# 技术债与工程待办（v1.4.0）
最后更新：`2026-03-14`
最后更新：`2026-03-20`
目标：在收费上线后，优先保证支付可靠性、权限一致性和运营可追溯性。
目标：在收费上线后，优先保证状态一致性、支付可靠性、可观测性和概率引擎发布可控。
## 1. 债务快照
当前估计：**93% 稳定 / 7% 技术债**。
当前估计：**95% 稳定 / 5% 技术债**。
```mermaid
flowchart TD
A["技术债"]
subgraph P["支付与订阅"]
P1["异常交易自动重放策略"]
P1["合约 V2 升级（SafeERC20 / Pausable）"]
P2["退款与工单流程"]
P3["多链结算对账"]
P3["多 RPC 与链上对账面板"]
end
subgraph E["权限与运营"]
E1["前后端/Bot 权限矩阵回归"]
E2["积分与订阅冲突策略"]
E2["积分来源明细与补分审计"]
end
subgraph O["可观测性"]
O1["支付失败原因分层指标"]
O1["外部监控抓取与告警阈值"]
O2["业务监控看板"]
end
subgraph S["状态与概率"]
S1["SQLite dual -> sqlite 切换验收"]
S2["EMOS shadow -> primary 门禁稳定化"]
end
A --> P
A --> E
A --> O
A --> S
```
## 2. 近期已关闭
- P1 支付主链路已上线（intent -> submit -> confirm）。
- 支付主链路已上线（intent -> submit -> confirm）。
- 支付自动补单已上线（Event Loop + Confirm Loop）。
- 支付事件重放脚本已补齐。
- 支付运行态 API 与 SQLite 审计事件已补齐。
- 钱包绑定支持浏览器钱包 + WalletConnect。
- 账户中心与 Pro 权限展示链路打通。
- 钱包异动支持独立频道路由。
- 运行态状态/缓存已支持 SQLite 渐进迁移。
- 轻量可观测性已上线（`/healthz`、`/api/system/status`、`/metrics`）。
- EMOS/CRPS 校准链路已上线 shadow 模式。
## 3. 高优先级技术债
| 项目 | 影响 | 建议动作 |
| :-- | :-- | :-- |
| 支付异常重放策略标准化 | 偶发确认失败需人工介入 | 建立 tx hash 自动回放 + 降级路径 |
| SQLite 主读切换验收 | 仍处于 dual 过渡期 | 线上跑满 24-48 小时后切到 `sqlite` |
| EMOS 上线门禁 | 当前 `hold`，不能切 primary | 继续积累样本，重点压 `bucket_brier` |
| 外部监控与告警 | 只有轻量指标，无外部抓取 | 接 Prometheus/Grafana 或最小巡检 |
| 退款与售后链路 | 商业闭环不完整 | 增加退款状态机与工单系统 |
| 订阅审计可视化 | 排障效率受限 | 建立订阅事件时间线视图 |
| 多邮箱绑定同 TG 账户策略 | 积分归属易混淆 | 引入主账号绑定策略与迁移工具 |
## 4. 中优先级技术债
| 项目 | 影响 | 建议动作 |
| :-- | :-- | :-- |
| 积分发放可解释性 | 用户理解成本高 | 输出积分来源明细（发言/签到/奖励） |
| 积分发放可解释性 | 用户理解成本高 | 输出积分来源明细（发言/奖励/手动补分） |
| 支付合约 V2 升级 | 当前仍是最小可用合约 | 升级到 SafeERC20 + Pausable + plan 绑定 |
| 支付失败文案标准化 | 转化率受影响 | 建立错误码 -> 文案映射表 |
| 配置收敛 | 运维出错概率高 | 将支付/推送配置集中分组管理 |
## 5. 低优先级技术债
@@ -67,7 +78,7 @@ flowchart TD
## 6. 下阶段里程碑
1. 完成支付异常自动重放与告警分层。
2. 上线退款/售后后台最小版。
3. 建立商业化运营看板（支付、续费、留存）。
4. 完成权限矩阵自动化回归测试。
1. 完成 SQLite 从 `dual` 到 `sqlite` 的主读切换。
2. 稳定 EMOS shadow，达到 rollout `observe/promote` 条件。
3. 补外部监控抓取与告警阈值。
4. 评估并推进支付合约 V2 升级。
docs/TECH_DEBT_ZH.md
+28 -17
View File
@@ -1,62 +1,73 @@
# 技术债与工程待办（v1.4.0）
最后更新：`2026-03-14`
最后更新：`2026-03-20`
目标：在收费上线后，优先保证支付可靠性、权限一致性和运营可追溯性。
目标：在收费上线后，优先保证状态一致性、支付可靠性、可观测性和概率引擎发布可控。
## 1. 债务快照
当前估计：**93% 稳定 / 7% 技术债**。
当前估计：**95% 稳定 / 5% 技术债**。
```mermaid
flowchart TD
A["技术债"]
subgraph P["支付与订阅"]
P1["异常交易自动重放策略"]
P1["合约 V2 升级（SafeERC20 / Pausable）"]
P2["退款与工单流程"]
P3["多链结算对账"]
P3["多 RPC 与链上对账面板"]
end
subgraph E["权限与运营"]
E1["前后端/Bot 权限矩阵回归"]
E2["积分与订阅冲突策略"]
E2["积分来源明细与补分审计"]
end
subgraph O["可观测性"]
O1["支付失败原因分层指标"]
O1["外部监控抓取与告警阈值"]
O2["业务监控看板"]
end
subgraph S["状态与概率"]
S1["SQLite dual -> sqlite 切换验收"]
S2["EMOS shadow -> primary 门禁稳定化"]
end
A --> P
A --> E
A --> O
A --> S
```
## 2. 近期已关闭
- P1 支付主链路已上线（intent -> submit -> confirm）。
- 支付主链路已上线（intent -> submit -> confirm）。
- 支付自动补单已上线（Event Loop + Confirm Loop）。
- 支付事件重放脚本已补齐。
- 支付运行态 API 与 SQLite 审计事件已补齐。
- 钱包绑定支持浏览器钱包 + WalletConnect。
- 账户中心与 Pro 权限展示链路打通。
- 钱包异动支持独立频道路由。
- 运行态状态/缓存已支持 SQLite 渐进迁移。
- 轻量可观测性已上线（`/healthz`、`/api/system/status`、`/metrics`）。
- EMOS/CRPS 校准链路已上线 shadow 模式。
## 3. 高优先级技术债
| 项目 | 影响 | 建议动作 |
| :-- | :-- | :-- |
| 支付异常重放策略标准化 | 偶发确认失败需人工介入 | 建立 tx hash 自动回放 + 降级路径 |
| SQLite 主读切换验收 | 仍处于 dual 过渡期 | 线上跑满 24-48 小时后切到 `sqlite` |
| EMOS 上线门禁 | 当前 `hold`，不能切 primary | 继续积累样本，重点压 `bucket_brier` |
| 外部监控与告警 | 只有轻量指标，无外部抓取 | 接 Prometheus/Grafana 或最小巡检 |
| 退款与售后链路 | 商业闭环不完整 | 增加退款状态机与工单系统 |
| 订阅审计可视化 | 排障效率受限 | 建立订阅事件时间线视图 |
| 多邮箱绑定同 TG 账户策略 | 积分归属易混淆 | 引入主账号绑定策略与迁移工具 |
## 4. 中优先级技术债
| 项目 | 影响 | 建议动作 |
| :-- | :-- | :-- |
| 积分发放可解释性 | 用户理解成本高 | 输出积分来源明细（发言/签到/奖励） |
| 积分发放可解释性 | 用户理解成本高 | 输出积分来源明细（发言/奖励/手动补分） |
| 支付合约 V2 升级 | 当前仍是最小可用合约 | 升级到 SafeERC20 + Pausable + plan 绑定 |
| 支付失败文案标准化 | 转化率受影响 | 建立错误码 -> 文案映射表 |
| 配置收敛 | 运维出错概率高 | 将支付/推送配置集中分组管理 |
## 5. 低优先级技术债
@@ -67,7 +78,7 @@ flowchart TD
## 6. 下阶段里程碑
1. 完成支付异常自动重放与告警分层。
2. 上线退款/售后后台最小版。
3. 建立商业化运营看板（支付、续费、留存）。
4. 完成权限矩阵自动化回归测试。
1. 完成 SQLite 从 `dual` 到 `sqlite` 的主读切换。
2. 稳定 EMOS shadow，达到 rollout `observe/promote` 条件。
3. 补外部监控抓取与告警阈值。
4. 评估并推进支付合约 V2 升级。
docs/payments/POLYGONSCAN_VERIFY.md
+24 -2
View File
@@ -1,11 +1,17 @@
# PolyWeatherCheckout PolygonScan 验证（v1.4.0）
最后更新：`2026-03-14`
最后更新：`2026-03-20`
## 1. 目标
对生产收款合约完成源码验证，降低钱包风控误报并提升用户信任。
当前说明：
- **现网合约仍为 V1**：`contracts/PolyWeatherCheckout.sol`
- **V2 只是升级草案**：`contracts/PolyWeatherCheckoutV2.sol`
- 当前 PolygonScan 验证流程默认针对 V1
## 2. 当前部署参数（示例）
- 链：Polygon Mainnet（`chainId=137`）
@@ -48,7 +54,23 @@ python scripts/encode_checkout_constructor.py \
- USDC.e: `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174`
- Native USDC: `0x3c499c542cef5e3811e1192ce70d8cc03d5c3359`
## 7. 说明
## 7. V2 说明（尚未部署）
如果后续升级到 V2，请改用：
```bash
python scripts/encode_checkout_v2_constructor.py \
--owner 0xYourMultiSig \
--treasury 0xYourTreasury \
--signer 0xYourBackendSigner
```
V2 相关文档：
- [PAYMENT_UPGRADE_V2_ZH.md](/E:/web/PolyWeather/docs/payments/PAYMENT_UPGRADE_V2_ZH.md)
- [PAYMENT_AUDIT_ZH.md](/E:/web/PolyWeather/docs/payments/PAYMENT_AUDIT_ZH.md)
## 8. 说明
- 源码验证能显著降低“欺诈/不可信”误报，但钱包风险缓存更新存在延迟。
- 生产商用环境可使用私有升级版合约；公开仓库保留标准实现与验证流程。