From 2a19a23e4dabf4d95b9f43bea8b11fa4482cbfd1 Mon Sep 17 00:00:00 2001 From: "2569718930@qq.com" <2569718930@qq.com> Date: Fri, 20 Mar 2026 19:07:11 +0800 Subject: [PATCH] docs: Add new READMEs for extension and frontend, create tech debt document, and update Chinese README. --- README_ZH.md | 4 +-- docs/TECH_DEBT.md | 84 ++++++++++++++++++++++----------------------- extension/README.md | 22 ++++++------ frontend/README.md | 54 ++++++++++++++--------------- 4 files changed, 82 insertions(+), 82 deletions(-) diff --git a/README_ZH.md b/README_ZH.md index 35e71596..ffd05f47 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -127,8 +127,8 @@ docker compose logs -f polyweather | egrep "polymarket wallet activity watcher s - 商业化说明：[docs/COMMERCIALIZATION.md](docs/COMMERCIALIZATION.md) - Open-Core 边界：[docs/OPEN_CORE_POLICY.md](docs/OPEN_CORE_POLICY.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.md](docs/TECH_DEBT.md) +- 技术债（中文镜像）：[docs/TECH_DEBT_ZH.md](docs/TECH_DEBT_ZH.md) +- 技术债（主文档）：[docs/TECH_DEBT.md](docs/TECH_DEBT.md) - 支付合约验证：[docs/payments/POLYGONSCAN_VERIFY.md](docs/payments/POLYGONSCAN_VERIFY.md) - 前端报告：[FRONTEND_REDESIGN_REPORT.md](FRONTEND_REDESIGN_REPORT.md) diff --git a/docs/TECH_DEBT.md b/docs/TECH_DEBT.md index f12ce7f1..ba3a78ca 100644 --- a/docs/TECH_DEBT.md +++ b/docs/TECH_DEBT.md @@ -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 flowchart TD - A["Tech Debt"] + A["技术债"] - subgraph P["Payments & Subscriptions"] - P1["Automatic replay for failed confirmations"] - P2["Refund and support workflow"] - P3["Multi-chain settlement reconciliation"] + subgraph P["支付与订阅"] + P1["异常交易自动重放策略"] + P2["退款与工单流程"] + P3["多链结算对账"] end - subgraph E["Entitlement & Ops"] - E1["Frontend/backend/bot entitlement regression matrix"] - E2["Points vs subscription conflict policy"] + subgraph E["权限与运营"] + E1["前后端/Bot 权限矩阵回归"] + E2["积分与订阅冲突策略"] end - subgraph O["Observability"] - O1["Layered metrics for payment failures"] - O2["Business operations dashboards"] + subgraph O["可观测性"] + O1["支付失败原因分层指标"] + O2["业务监控看板"] end A --> P @@ -33,41 +33,41 @@ flowchart TD A --> O ``` -## 2. Recently Closed +## 2. 近期已关闭 -- P1 checkout flow live (intent -> submit -> confirm). -- Automatic reconciliation live (event loop + confirm loop). -- Wallet binding supports extension wallets + WalletConnect. -- Account center entitlement rendering is wired end-to-end. -- Wallet activity watcher supports dedicated channel routing. +- P1 支付主链路已上线（intent -> submit -> confirm）。 +- 支付自动补单已上线（Event Loop + Confirm Loop）。 +- 钱包绑定支持浏览器钱包 + WalletConnect。 +- 账户中心与 Pro 权限展示链路打通。 +- 钱包异动支持独立频道路由。 -## 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 | -| 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 | +| 支付异常重放策略标准化 | 偶发确认失败需人工介入 | 建立 tx hash 自动回放 + 降级路径 | +| 退款与售后链路 | 商业闭环不完整 | 增加退款状态机与工单系统 | +| 订阅审计可视化 | 排障效率受限 | 建立订阅事件时间线视图 | +| 多邮箱绑定同 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 | -| Cold-start variance | First-load jitter | Add route prewarming for hot cities | +| 前端离线缓存能力 | 非核心 | 评估 Service Worker + IndexedDB | +| 冷启动波动 | 首屏抖动 | 热点城市预热 | -## 6. Next Milestones +## 6. 下阶段里程碑 -1. Ship automatic replay and alert stratification for payment anomalies. -2. Launch minimal refund/support admin flow. -3. Add business dashboards for payments, renewals, and retention. -4. Complete entitlement parity regression suite. +1. 完成支付异常自动重放与告警分层。 +2. 上线退款/售后后台最小版。 +3. 建立商业化运营看板（支付、续费、留存）。 +4. 完成权限矩阵自动化回归测试。 diff --git a/extension/README.md b/extension/README.md index 285095ae..017f77b2 100644 --- a/extension/README.md +++ b/extension/README.md @@ -1,13 +1,13 @@ -# PolyWeather Side Panel Extension (MVP) +# PolyWeather 侧边栏插件（MVP） -这是一个 Chrome / Edge 的侧边栏扩展 MVP，用于把 PolyWeather 右侧城市卡片移植到浏览器侧边栏中。 +这是一个 Chrome / Edge 侧边栏扩展的 MVP，用于把 PolyWeather 右侧城市卡片移植到浏览器侧边栏中。 ## 功能 - 侧边栏展示： - 城市选择 - 风险徽章 - - 城市档案（结算源/距离/观测更新/周边站点） + - 城市档案（结算源 / 距离 / 观测更新时间 / 周边站点） - 今日日内走势（简版 Canvas） - 多日预报 - 快捷按钮： @@ -18,15 +18,15 @@ - 监听当前激活标签页 URL（例如 Polymarket `.../event/highest-temperature-in-ankara-...`） - 自动将侧边栏城市切换为 URL 对应城市 - 设置页可配置： - - Site Base URL - - API Base URL + - 网站基础地址 + - API 基础地址 - Bearer Token（可选） ## 本地安装（开发者模式） 1. 打开 Chrome/Edge 扩展页面： - - Chrome: `chrome://extensions` - - Edge: `edge://extensions` + - Chrome：`chrome://extensions` + - Edge：`edge://extensions` 2. 打开“开发者模式”。 3. 选择“加载已解压的扩展程序”。 4. 选择目录：`extension/`。 @@ -36,11 +36,11 @@ 首次建议打开扩展“选项页”并确认： -- `Site Base URL`：你的前端域名（例如 `https://polyweather-pro.vercel.app`） -- `API Base URL`：你的后端 API 域名（若同域也可填前端域名） +- `网站基础地址`：你的前端域名（例如 `https://polyweather-pro.vercel.app`） +- `API 基础地址`：你的后端 API 域名（若同域也可填前端域名） - `Bearer Token`：后端开启鉴权时填写 ## 说明 -- 当前是 MVP，重点是“导流回站”，未接入支付链路。 -- 若你的 API 做了严格鉴权，请先在设置页填 token 再使用。 +- 当前版本是 MVP，重点是“导流回站”，未接入支付链路。 +- 若你的 API 做了严格鉴权，请先在设置页填写 token 再使用。 diff --git a/frontend/README.md b/frontend/README.md index 9e53f76b..b615da02 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -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 - React + Tailwind - Leaflet + Chart.js - Supabase Auth -- WalletConnect + browser EVM wallets +- WalletConnect + 浏览器 EVM 钱包 -## Runtime Model +## 运行模型 -1. Browser -> Next app (`frontend`) -2. Next Route Handlers (`/api/*`) -> FastAPI backend -3. FastAPI -> analysis/payment services +1. 浏览器 -> Next 应用（`frontend`） +2. Next Route Handlers（`/api/*`）-> FastAPI 后端 +3. FastAPI -> 分析服务 / 支付服务 -## Local Development +## 本地开发 ```bash cd frontend @@ -28,7 +28,7 @@ npm install npm run dev ``` -## Required Environment Variables +## 必需环境变量 ```env POLYWEATHER_API_BASE_URL=https:// @@ -39,22 +39,22 @@ POLYWEATHER_AUTH_REQUIRED=false POLYWEATHER_BACKEND_ENTITLEMENT_TOKEN= ``` -WalletConnect: +WalletConnect： ```env NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID= NEXT_PUBLIC_WALLETCONNECT_POLYGON_RPC_URL=https://polygon-bor-rpc.publicnode.com ``` -Overlay links: +浮层链接： ```env NEXT_PUBLIC_TELEGRAM_GROUP_URL=https://t.me/ ``` -## Route Handlers +## 路由处理器 -Weather: +天气： - `GET /api/cities` - `GET /api/city/[name]` @@ -62,11 +62,11 @@ Weather: - `GET /api/city/[name]/detail` - `GET /api/history/[name]` -Auth: +鉴权： - `GET /api/auth/me` -Payments: +支付： - `GET /api/payments/config` - `GET /api/payments/wallets` @@ -77,17 +77,17 @@ Payments: - `POST /api/payments/intents/[intentId]/submit` - `POST /api/payments/intents/[intentId]/confirm` -## Cache Behavior +## 缓存行为 -- `cities` / `summary` / `history`: `ETag + Cache-Control` -- `summary?force_refresh=true`: `no-store` -- payment routes: `no-store` +- `cities` / `summary` / `history`：`ETag + Cache-Control` +- `summary?force_refresh=true`：`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`