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

docs: Add new READMEs for extension and frontend, create tech debt document, and update Chinese README.

Browse Source
This commit is contained in:
2569718930@qq.com
2026-03-20 19:07:11 +08:00
parent 6e3bc1ce75
commit 2a19a23e4d
4 changed files with 82 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README_ZH.md
+2 -2
View File
@@ -127,8 +127,8 @@ docker compose logs -f polyweather | egrep "polymarket wallet activity watcher s
- 商业化说明：[docs/COMMERCIALIZATION.md](docs/COMMERCIALIZATION.md) - 商业化说明：[docs/COMMERCIALIZATION.md](docs/COMMERCIALIZATION.md)
- Open-Core 边界：[docs/OPEN_CORE_POLICY.md](docs/OPEN_CORE_POLICY.md) - Open-Core 边界：[docs/OPEN_CORE_POLICY.md](docs/OPEN_CORE_POLICY.md)
- Supabase 接入：[docs/SUPABASE_SETUP_ZH.md](docs/SUPABASE_SETUP_ZH.md) - Supabase 接入：[docs/SUPABASE_SETUP_ZH.md](docs/SUPABASE_SETUP_ZH.md)
- 技术债（中文）：[docs/TECH_DEBT_ZH.md](docs/TECH_DEBT_ZH.md) - 技术债（中文镜像）：[docs/TECH_DEBT_ZH.md](docs/TECH_DEBT_ZH.md)
- 技术债（英文）：[docs/TECH_DEBT.md](docs/TECH_DEBT.md) - 技术债（主文档）：[docs/TECH_DEBT.md](docs/TECH_DEBT.md)
- 支付合约验证：[docs/payments/POLYGONSCAN_VERIFY.md](docs/payments/POLYGONSCAN_VERIFY.md) - 支付合约验证：[docs/payments/POLYGONSCAN_VERIFY.md](docs/payments/POLYGONSCAN_VERIFY.md)
- 前端报告：[FRONTEND_REDESIGN_REPORT.md](FRONTEND_REDESIGN_REPORT.md) - 前端报告：[FRONTEND_REDESIGN_REPORT.md](FRONTEND_REDESIGN_REPORT.md)
docs/TECH_DEBT.md
+42 -42
View File
@@ -1,31 +1,31 @@
# Technical Debt Backlog (v1.4) # 技术债与工程待办（v1.4）
Last Updated: `2026-03-14` 最后更新：`2026-03-14`
Focus after paid launch: payment reliability, entitlement parity, and auditability. 目标：在收费上线后，优先保证支付可靠性、权限一致性和运营可追溯性。
## 1. Snapshot ## 1. 债务快照
Current estimate: **93% stable / 7% debt**. 当前估计：**93% 稳定 / 7% 技术债**。
```mermaid ```mermaid
flowchart TD flowchart TD
A["Tech Debt"] A["技术债"]
subgraph P["Payments & Subscriptions"] subgraph P["支付与订阅"]
P1["Automatic replay for failed confirmations"] P1["异常交易自动重放策略"]
P2["Refund and support workflow"] P2["退款与工单流程"]
P3["Multi-chain settlement reconciliation"] P3["多链结算对账"]
end end
subgraph E["Entitlement & Ops"] subgraph E["权限与运营"]
E1["Frontend/backend/bot entitlement regression matrix"] E1["前后端/Bot 权限矩阵回归"]
E2["Points vs subscription conflict policy"] E2["积分与订阅冲突策略"]
end end
subgraph O["Observability"] subgraph O["可观测性"]
O1["Layered metrics for payment failures"] O1["支付失败原因分层指标"]
O2["Business operations dashboards"] O2["业务监控看板"]
end end
A --> P A --> P
@@ -33,41 +33,41 @@ flowchart TD
A --> O A --> O
``` ```
## 2. Recently Closed ## 2. 近期已关闭
- P1 checkout flow live (intent -> submit -> confirm). - P1 支付主链路已上线（intent -> submit -> confirm）。
- Automatic reconciliation live (event loop + confirm loop). - 支付自动补单已上线（Event Loop + Confirm Loop）。
- Wallet binding supports extension wallets + WalletConnect. - 钱包绑定支持浏览器钱包 + WalletConnect。
- Account center entitlement rendering is wired end-to-end. - 账户中心与 Pro 权限展示链路打通。
- Wallet activity watcher supports dedicated channel routing. - 钱包异动支持独立频道路由。
## 3. High-Priority Debt ## 3. 高优先级技术债
| Item | Impact | Suggested Work | | 项目 | 影响 | 建议动作 |
| :-- | :-- | :-- | | :-- | :-- | :-- |
| Automatic replay strategy for transient tx failures | Manual intervention still needed in some edge cases | Standardize tx replay + fallback paths | | 支付异常重放策略标准化 | 偶发确认失败需人工介入 | 建立 tx hash 自动回放 + 降级路径 |
| Refund/support workflow | Commercial loop incomplete | Add refund state machine + support tooling | | 退款与售后链路 | 商业闭环不完整 | 增加退款状态机与工单系统 |
| Subscription audit visualization | Slower incident triage | Build timeline view for entitlement events | | 订阅审计可视化 | 排障效率受限 | 建立订阅事件时间线视图 |
| Multi-email same-Telegram binding policy | Points ownership confusion | Add primary-account binding and migration utilities | | 多邮箱绑定同 TG 账户策略 | 积分归属易混淆 | 引入主账号绑定策略与迁移工具 |
## 4. Medium-Priority Debt ## 4. 中优先级技术债
| Item | Impact | Suggested Work | | 项目 | 影响 | 建议动作 |
| :-- | :-- | :-- | | :-- | :-- | :-- |
| Points transparency | User confusion | Expose points breakdown by source | | 积分发放可解释性 | 用户理解成本高 | 输出积分来源明细（发言/签到/奖励） |
| Payment error copy consistency | Conversion impact | Build error-code to UX-copy mapping table | | 支付失败文案标准化 | 转化率受影响 | 建立错误码 -> 文案映射表 |
| Config sprawl | Ops mistakes | Consolidate payment/push configs into grouped schemas | | 配置收敛 | 运维出错概率高 | 将支付/推送配置集中分组管理 |
## 5. Low-Priority Debt ## 5. 低优先级技术债
| Item | Impact | Suggested Work | | 项目 | 影响 | 建议动作 |
| :-- | :-- | :-- | | :-- | :-- | :-- |
| Offline cache support | Non-core | Evaluate SW + IndexedDB | | 前端离线缓存能力 | 非核心 | 评估 Service Worker + IndexedDB |
| Cold-start variance | First-load jitter | Add route prewarming for hot cities | | 冷启动波动 | 首屏抖动 | 热点城市预热 |
## 6. Next Milestones ## 6. 下阶段里程碑
1. Ship automatic replay and alert stratification for payment anomalies. 1. 完成支付异常自动重放与告警分层。
2. Launch minimal refund/support admin flow. 2. 上线退款/售后后台最小版。
3. Add business dashboards for payments, renewals, and retention. 3. 建立商业化运营看板（支付、续费、留存）。
4. Complete entitlement parity regression suite. 4. 完成权限矩阵自动化回归测试。
extension/README.md
+11 -11
View File
@@ -1,13 +1,13 @@
# PolyWeather Side Panel Extension (MVP) # PolyWeather 侧边栏插件（MVP）
这是一个 Chrome / Edge 的侧边栏扩展 MVP，用于把 PolyWeather 右侧城市卡片移植到浏览器侧边栏中。 这是一个 Chrome / Edge 侧边栏扩展的 MVP，用于把 PolyWeather 右侧城市卡片移植到浏览器侧边栏中。
## 功能 ## 功能
- 侧边栏展示： - 侧边栏展示：
- 城市选择 - 城市选择
- 风险徽章 - 风险徽章
- 城市档案（结算源/距离/观测更新/周边站点） - 城市档案（结算源 / 距离 / 观测更新时间 / 周边站点）
- 今日日内走势（简版 Canvas） - 今日日内走势（简版 Canvas）
- 多日预报 - 多日预报
- 快捷按钮： - 快捷按钮：
@@ -18,15 +18,15 @@
- 监听当前激活标签页 URL（例如 Polymarket `.../event/highest-temperature-in-ankara-...`） - 监听当前激活标签页 URL（例如 Polymarket `.../event/highest-temperature-in-ankara-...`）
- 自动将侧边栏城市切换为 URL 对应城市 - 自动将侧边栏城市切换为 URL 对应城市
- 设置页可配置： - 设置页可配置：
- Site Base URL - 网站基础地址
- API Base URL - API 基础地址
- Bearer Token（可选） - Bearer Token（可选）
## 本地安装（开发者模式） ## 本地安装（开发者模式）
1. 打开 Chrome/Edge 扩展页面： 1. 打开 Chrome/Edge 扩展页面：
- Chrome: `chrome://extensions` - Chrome：`chrome://extensions`
- Edge: `edge://extensions` - Edge：`edge://extensions`
2. 打开“开发者模式”。 2. 打开“开发者模式”。
3. 选择“加载已解压的扩展程序”。 3. 选择“加载已解压的扩展程序”。
4. 选择目录：`extension/`。 4. 选择目录：`extension/`。
@@ -36,11 +36,11 @@
首次建议打开扩展“选项页”并确认： 首次建议打开扩展“选项页”并确认：
- `Site Base URL`：你的前端域名（例如 `https://polyweather-pro.vercel.app`） - `网站基础地址`：你的前端域名（例如 `https://polyweather-pro.vercel.app`）
- `API Base URL`：你的后端 API 域名（若同域也可填前端域名） - `API 基础地址`：你的后端 API 域名（若同域也可填前端域名）
- `Bearer Token`：后端开启鉴权时填写 - `Bearer Token`：后端开启鉴权时填写
## 说明 ## 说明
- 当前是 MVP，重点是“导流回站”，未接入支付链路。 - 当前版本是 MVP，重点是“导流回站”，未接入支付链路。
- 若你的 API 做了严格鉴权，请先在设置页填 token 再使用。 - 若你的 API 做了严格鉴权，请先在设置页填写 token 再使用。
frontend/README.md
+27 -27
View File
@@ -1,25 +1,25 @@
# PolyWeather Frontend # PolyWeather 前端
Production frontend for PolyWeather Pro. PolyWeather Pro 的生产前端工程。
Production URL: 线上地址：
- https://polyweather-pro.vercel.app/ - [https://polyweather-pro.vercel.app/](https://polyweather-pro.vercel.app/)
## Stack ## 技术栈
- Next.js App Router - Next.js App Router
- React + Tailwind - React + Tailwind
- Leaflet + Chart.js - Leaflet + Chart.js
- Supabase Auth - Supabase Auth
- WalletConnect + browser EVM wallets - WalletConnect + 浏览器 EVM 钱包
## Runtime Model ## 运行模型
1. Browser -> Next app (`frontend`) 1. 浏览器 -> Next 应用（`frontend`）
2. Next Route Handlers (`/api/*`) -> FastAPI backend 2. Next Route Handlers（`/api/*`）-> FastAPI 后端
3. FastAPI -> analysis/payment services 3. FastAPI -> 分析服务 / 支付服务
## Local Development ## 本地开发
```bash ```bash
cd frontend cd frontend
@@ -28,7 +28,7 @@ npm install
npm run dev npm run dev
``` ```
## Required Environment Variables ## 必需环境变量
```env ```env
POLYWEATHER_API_BASE_URL=https://<your-fastapi-host> POLYWEATHER_API_BASE_URL=https://<your-fastapi-host>
@@ -39,22 +39,22 @@ POLYWEATHER_AUTH_REQUIRED=false
POLYWEATHER_BACKEND_ENTITLEMENT_TOKEN= POLYWEATHER_BACKEND_ENTITLEMENT_TOKEN=
``` ```
WalletConnect: WalletConnect：
```env ```env
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID= NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=
NEXT_PUBLIC_WALLETCONNECT_POLYGON_RPC_URL=https://polygon-bor-rpc.publicnode.com NEXT_PUBLIC_WALLETCONNECT_POLYGON_RPC_URL=https://polygon-bor-rpc.publicnode.com
``` ```
Overlay links: 浮层链接：
```env ```env
NEXT_PUBLIC_TELEGRAM_GROUP_URL=https://t.me/<your_group> NEXT_PUBLIC_TELEGRAM_GROUP_URL=https://t.me/<your_group>
``` ```
## Route Handlers ## 路由处理器
Weather: 天气：
- `GET /api/cities` - `GET /api/cities`
- `GET /api/city/[name]` - `GET /api/city/[name]`
@@ -62,11 +62,11 @@ Weather:
- `GET /api/city/[name]/detail` - `GET /api/city/[name]/detail`
- `GET /api/history/[name]` - `GET /api/history/[name]`
Auth: 鉴权：
- `GET /api/auth/me` - `GET /api/auth/me`
Payments: 支付：
- `GET /api/payments/config` - `GET /api/payments/config`
- `GET /api/payments/wallets` - `GET /api/payments/wallets`
@@ -77,17 +77,17 @@ Payments:
- `POST /api/payments/intents/[intentId]/submit` - `POST /api/payments/intents/[intentId]/submit`
- `POST /api/payments/intents/[intentId]/confirm` - `POST /api/payments/intents/[intentId]/confirm`
## Cache Behavior ## 缓存行为
- `cities` / `summary` / `history`: `ETag + Cache-Control` - `cities` / `summary` / `history`：`ETag + Cache-Control`
- `summary?force_refresh=true`: `no-store` - `summary?force_refresh=true`：`no-store`
- payment routes: `no-store` - 支付相关路由：`no-store`
## Open-Core Note ## 开源边界说明
This frontend repo includes general product UI and standard payment UX. 此前端仓库包含通用产品界面和标准支付体验。
Commercial strategy tuning, private ops workflows, and sensitive production parameters are intentionally outside the public docs scope. 商业策略调优、私有运营流程和敏感生产参数不在公开文档范围内。
See root policy: `docs/OPEN_CORE_POLICY.md` 详见根目录策略文档：`docs/OPEN_CORE_POLICY.md`
Last updated: `2026-03-14` 最后更新：`2026-03-14`