frontend/README.md

# PolyWeather 前端

PolyWeather Pro 的生产前端工程。

线上地址：
- [https://polyweather-pro.vercel.app/](https://polyweather-pro.vercel.app/)

## 技术栈

- Next.js App Router
- React + Tailwind
- Leaflet + Chart.js
- Supabase Auth
- WalletConnect + 浏览器 EVM 钱包

## 运行模型

1. 浏览器 -> Next 应用（`frontend`）
2. Next Route Handlers（`/api/*`）-> FastAPI 后端
3. FastAPI -> 分析服务 / 支付服务

## 本地开发

```bash
cd frontend
cp .env.example .env.local
npm install
npm run dev
```

## Vercel 最小部署配置

只跑看板和基础鉴权时，先填这 4 项：

```env
POLYWEATHER_API_BASE_URL=https://<your-fastapi-host>
NEXT_PUBLIC_SUPABASE_URL=https://<your-supabase-project>.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=<your-anon-key>
POLYWEATHER_AUTH_ENABLED=true
```

建议显式补：

```env
POLYWEATHER_AUTH_REQUIRED=true
```

如果你只是开放游客浏览，可改成：

```env
POLYWEATHER_AUTH_ENABLED=false
POLYWEATHER_AUTH_REQUIRED=false
```

## 可选环境变量

仅在对应功能启用时填写：

```env
# 看板分享令牌
POLYWEATHER_DASHBOARD_ACCESS_TOKEN=

# 前端 API 转发到后端时使用的共享令牌
POLYWEATHER_BACKEND_ENTITLEMENT_TOKEN=

# 钱包支付
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=
NEXT_PUBLIC_WALLETCONNECT_POLYGON_RPC_URL=https://polygon-bor-rpc.publicnode.com

# 社群入口
NEXT_PUBLIC_TELEGRAM_GROUP_URL=https://t.me/<your_group>
NEXT_PUBLIC_TELEGRAM_BOT_URL=https://t.me/WeatherQuant_bot
```

更完整的 Vercel 配置说明见：
- [docs/FRONTEND_DEPLOYMENT_ZH.md](/E:/web/PolyWeather/docs/FRONTEND_DEPLOYMENT_ZH.md)

## 路由处理器

天气：

- `GET /api/cities`
- `GET /api/city/[name]`
- `GET /api/city/[name]/summary`
- `GET /api/city/[name]/detail`
- `GET /api/history/[name]`

鉴权：

- `GET /api/auth/me`

支付：

- `GET /api/payments/config`
- `GET /api/payments/wallets`
- `POST /api/payments/wallets/challenge`
- `POST /api/payments/wallets/verify`
- `POST /api/payments/intents`
- `GET /api/payments/intents/[intentId]`
- `POST /api/payments/intents/[intentId]/submit`
- `POST /api/payments/intents/[intentId]/confirm`

Ops：

- `GET /ops`
- `GET /api/ops/users`
- `GET /api/ops/leaderboard/weekly`
- `GET /api/ops/memberships`
- `GET /api/ops/payments/incidents`
- `POST /api/ops/users/grant-points`
- `POST /api/ops/payments/incidents/[eventId]/resolve`

## Ops 管理后台

当前前端已内置轻量管理页：

- [https://polyweather-pro.vercel.app/ops](https://polyweather-pro.vercel.app/ops)

页面当前支持：

- 系统状态
- SQLite / rollout / 支付运行态
- 用户查询
- 当前会员
- 本周积分榜
- 手动补分
- 支付异常单筛选与标记已处理

注意：

- `/ops` 页面是否可写，取决于后端 `POLYWEATHER_OPS_ADMIN_EMAILS`
- 前端登录邮箱本身不会自动获得管理员权限

## 支付安全补充

为降低“旧页面/旧配置导致打到旧收款地址”的风险，支付区现在会：

1. 点击支付前重新请求 `/api/payments/config`
2. 若 `receiver_contract` 已更新，先切到最新地址
3. 若后端返回的 `tx_payload.to` 与最新地址不一致，直接阻断支付

这意味着：

- 旧标签页风险已明显降低
- 但支付地址变更后，仍建议在 Vercel 上 redeploy 当前 production，并清理明显过期 deployment

## 缓存行为

- `cities` / `summary` / `history`：`ETag + Cache-Control`
- `summary?force_refresh=true`：`no-store`
- 支付相关路由：`no-store`

## 开源边界说明

此前端仓库包含通用产品界面和标准支付体验。
商业策略调优、私有运营流程和敏感生产参数不在公开文档范围内。

详见根目录策略文档：`docs/OPEN_CORE_POLICY.md`

最后更新：`2026-03-21`
-											docs: Add new READMEs for extension and frontend, create tech debt document, and update Chinese README.
										
										
											2026-03-20 19:07:11 +08:00
+								# PolyWeather 前端
-											chore: install project dependencies and generate build artifacts.
										
										
											2026-03-06 08:41:19 +08:00
-											docs: Add new READMEs for extension and frontend, create tech debt document, and update Chinese README.
										
										
											2026-03-20 19:07:11 +08:00
+								PolyWeather Pro 的生产前端工程。
-											feat: Add database-backed user and subscription management, update project architecture documentation, and outline technical debt.
										
										
											2026-03-06 19:10:05 +08:00
-											docs: Add new READMEs for extension and frontend, create tech debt document, and update Chinese README.
										
										
											2026-03-20 19:07:11 +08:00
+								线上地址：
 								- [https://polyweather-pro.vercel.app/](https://polyweather-pro.vercel.app/)
-											chore: install project dependencies and generate build artifacts.
										
										
											2026-03-06 08:41:19 +08:00
-											docs: Add new READMEs for extension and frontend, create tech debt document, and update Chinese README.
										
										
											2026-03-20 19:07:11 +08:00
+								## 技术栈
-											chore: install project dependencies and generate build artifacts.
										
										
											2026-03-06 08:41:19 +08:00
-											feat: Add database-backed user and subscription management, update project architecture documentation, and outline technical debt.
										
										
											2026-03-06 19:10:05 +08:00
+								- Next.js App Router
-											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
+								- React + Tailwind
 								- Leaflet + Chart.js
 								- Supabase Auth
-											docs: Add new READMEs for extension and frontend, create tech debt document, and update Chinese README.
										
										
											2026-03-20 19:07:11 +08:00
+								- WalletConnect + 浏览器 EVM 钱包
-											feat: Add database-backed user and subscription management, update project architecture documentation, and outline technical debt.
										
										
											2026-03-06 19:10:05 +08:00
-											docs: Add new READMEs for extension and frontend, create tech debt document, and update Chinese README.
										
										
											2026-03-20 19:07:11 +08:00
+								## 运行模型
-											feat: Add database-backed user and subscription management, update project architecture documentation, and outline technical debt.
										
										
											2026-03-06 19:10:05 +08:00
-											docs: Add new READMEs for extension and frontend, create tech debt document, and update Chinese README.
										
										
											2026-03-20 19:07:11 +08:00
+. 浏览器 -> Next 应用（`frontend`）
 . Next Route Handlers（`/api/*`）-> FastAPI 后端
 . FastAPI -> 分析服务 / 支付服务
-											chore: install project dependencies and generate build artifacts.
										
										
											2026-03-06 08:41:19 +08:00
-											docs: Add new READMEs for extension and frontend, create tech debt document, and update Chinese README.
										
										
											2026-03-20 19:07:11 +08:00
+								## 本地开发
-											chore: install project dependencies and generate build artifacts.
										
										
											2026-03-06 08:41:19 +08:00
 								```bash
 								cd frontend
 								cp .env.example .env.local
 								npm install
 								npm run dev
 								```
-											Add config validation and deployment docs
										
										
											2026-03-20 22:00:02 +08:00
+								## Vercel 最小部署配置
 								只跑看板和基础鉴权时，先填这 4 项：
-											chore: install project dependencies and generate build artifacts.
										
										
											2026-03-06 08:41:19 +08:00
-											feat: Add database-backed user and subscription management, update project architecture documentation, and outline technical debt.
										
										
											2026-03-06 19:10:05 +08:00
+								```env
 								POLYWEATHER_API_BASE_URL=https://<your-fastapi-host>
-											Add config validation and deployment docs
										
										
											2026-03-20 22:00:02 +08:00
+								NEXT_PUBLIC_SUPABASE_URL=https://<your-supabase-project>.supabase.co
 								NEXT_PUBLIC_SUPABASE_ANON_KEY=<your-anon-key>
-											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
+								POLYWEATHER_AUTH_ENABLED=true
-											chore: install project dependencies and generate build artifacts.
										
										
											2026-03-06 08:41:19 +08:00
+								```
-											Add config validation and deployment docs
										
										
											2026-03-20 22:00:02 +08:00
+								建议显式补：
-											docs: Add commercialization, technical debt, and frontend documentation, and update project READMEs.
										
										
											2026-03-12 12:01:29 +08:00
 								```env
-											Add config validation and deployment docs
										
										
											2026-03-20 22:00:02 +08:00
+								POLYWEATHER_AUTH_REQUIRED=true
 								```
 								如果你只是开放游客浏览，可改成：
 								```env
 								POLYWEATHER_AUTH_ENABLED=false
 								POLYWEATHER_AUTH_REQUIRED=false
-											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
+								```
-											Add config validation and deployment docs
										
										
											2026-03-20 22:00:02 +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
 								```env
-											Add config validation and deployment docs
										
										
											2026-03-20 22:00:02 +08:00
+								# 看板分享令牌
 								POLYWEATHER_DASHBOARD_ACCESS_TOKEN=
 								# 前端 API 转发到后端时使用的共享令牌
 								POLYWEATHER_BACKEND_ENTITLEMENT_TOKEN=
 								# 钱包支付
 								NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=
 								NEXT_PUBLIC_WALLETCONNECT_POLYGON_RPC_URL=https://polygon-bor-rpc.publicnode.com
 								# 社群入口
-											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
+								NEXT_PUBLIC_TELEGRAM_GROUP_URL=https://t.me/<your_group>
-											Add config validation and deployment docs
										
										
											2026-03-20 22:00:02 +08:00
+								NEXT_PUBLIC_TELEGRAM_BOT_URL=https://t.me/WeatherQuant_bot
-											docs: Add commercialization, technical debt, and frontend documentation, and update project READMEs.
										
										
											2026-03-12 12:01:29 +08:00
+								```
-											chore: install project dependencies and generate build artifacts.
										
										
											2026-03-06 08:41:19 +08:00
-											Add config validation and deployment docs
										
										
											2026-03-20 22:00:02 +08:00
+								更完整的 Vercel 配置说明见：
 								- [docs/FRONTEND_DEPLOYMENT_ZH.md](/E:/web/PolyWeather/docs/FRONTEND_DEPLOYMENT_ZH.md)
-											docs: Add new READMEs for extension and frontend, create tech debt document, and update Chinese README.
										
										
											2026-03-20 19:07:11 +08:00
+								## 路由处理器
-											feat: Add database-backed user and subscription management, update project architecture documentation, and outline technical debt.
										
										
											2026-03-06 19:10:05 +08:00
-											docs: Add new READMEs for extension and frontend, create tech debt document, and update Chinese README.
										
										
											2026-03-20 19:07:11 +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
-											chore: install project dependencies and generate build artifacts.
										
										
											2026-03-06 08:41:19 +08:00
+								- `GET /api/cities`
-											feat: Add database-backed user and subscription management, update project architecture documentation, and outline technical debt.
										
										
											2026-03-06 19:10:05 +08:00
+								- `GET /api/city/[name]`
-											feat: fully migrate frontend to a React component-driven architecture and expand project documentation.
										
										
											2026-03-09 10:53:23 +08:00
+								- `GET /api/city/[name]/summary`
-											docs: Add commercialization, technical debt, and frontend documentation, and update project READMEs.
										
										
											2026-03-12 12:01:29 +08:00
+								- `GET /api/city/[name]/detail`
-											feat: Add database-backed user and subscription management, update project architecture documentation, and outline technical debt.
										
										
											2026-03-06 19:10:05 +08:00
+								- `GET /api/history/[name]`
-											chore: install project dependencies and generate build artifacts.
										
										
											2026-03-06 08:41:19 +08:00
-											docs: Add new READMEs for extension and frontend, create tech debt document, and update Chinese README.
										
										
											2026-03-20 19:07:11 +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
+								- `GET /api/auth/me`
-											docs: Add commercialization, technical debt, and frontend documentation, and update project READMEs.
										
										
											2026-03-12 12:01:29 +08:00
-											docs: Add new READMEs for extension and frontend, create tech debt document, and update Chinese README.
										
										
											2026-03-20 19:07:11 +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
+								- `GET /api/payments/config`
 								- `GET /api/payments/wallets`
 								- `POST /api/payments/wallets/challenge`
 								- `POST /api/payments/wallets/verify`
 								- `POST /api/payments/intents`
 								- `GET /api/payments/intents/[intentId]`
 								- `POST /api/payments/intents/[intentId]/submit`
 								- `POST /api/payments/intents/[intentId]/confirm`
-											docs: Add commercialization, technical debt, and frontend documentation, and update project READMEs.
										
										
											2026-03-12 12:01:29 +08:00
-											Update docs for ops, payments, and deployment guidance
										
										
											2026-03-21 14:52:25 +08:00
+								Ops：
 								- `GET /ops`
 								- `GET /api/ops/users`
 								- `GET /api/ops/leaderboard/weekly`
 								- `GET /api/ops/memberships`
 								- `GET /api/ops/payments/incidents`
 								- `POST /api/ops/users/grant-points`
 								- `POST /api/ops/payments/incidents/[eventId]/resolve`
 								## Ops 管理后台
 								当前前端已内置轻量管理页：
 								- [https://polyweather-pro.vercel.app/ops](https://polyweather-pro.vercel.app/ops)
 								页面当前支持：
 								- 系统状态
 								- SQLite / rollout / 支付运行态
 								- 用户查询
 								- 当前会员
 								- 本周积分榜
 								- 手动补分
 								- 支付异常单筛选与标记已处理
 								注意：
 								- `/ops` 页面是否可写，取决于后端 `POLYWEATHER_OPS_ADMIN_EMAILS`
 								- 前端登录邮箱本身不会自动获得管理员权限
 								## 支付安全补充
 								为降低“旧页面/旧配置导致打到旧收款地址”的风险，支付区现在会：
 . 点击支付前重新请求 `/api/payments/config`
 . 若 `receiver_contract` 已更新，先切到最新地址
 . 若后端返回的 `tx_payload.to` 与最新地址不一致，直接阻断支付
 								这意味着：
 								- 旧标签页风险已明显降低
 								- 但支付地址变更后，仍建议在 Vercel 上 redeploy 当前 production，并清理明显过期 deployment
-											docs: Add new READMEs for extension and frontend, create tech debt document, and update Chinese README.
										
										
											2026-03-20 19:07:11 +08:00
+								## 缓存行为
-											docs: Add commercialization, technical debt, and frontend documentation, and update project READMEs.
										
										
											2026-03-12 12:01:29 +08:00
-											docs: Add new READMEs for extension and frontend, create tech debt document, and update Chinese README.
										
										
											2026-03-20 19:07:11 +08:00
+								- `cities` / `summary` / `history`：`ETag + Cache-Control`
 								- `summary?force_refresh=true`：`no-store`
 								- 支付相关路由：`no-store`
-											docs: Add commercialization, technical debt, and frontend documentation, and update project READMEs.
										
										
											2026-03-12 12:01:29 +08:00
-											docs: Add new READMEs for extension and frontend, create tech debt document, and update Chinese README.
										
										
											2026-03-20 19:07:11 +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 new READMEs for extension and frontend, create tech debt document, and update Chinese README.
										
										
											2026-03-20 19:07:11 +08:00
+								此前端仓库包含通用产品界面和标准支付体验。
 								商业策略调优、私有运营流程和敏感生产参数不在公开文档范围内。
-											chore: install project dependencies and generate build artifacts.
										
										
											2026-03-06 08:41:19 +08:00
-											docs: Add new READMEs for extension and frontend, create tech debt document, and update Chinese README.
										
										
											2026-03-20 19:07:11 +08:00
+								详见根目录策略文档：`docs/OPEN_CORE_POLICY.md`
-											feat: Add database-backed user and subscription management, update project architecture documentation, and outline technical debt.
										
										
											2026-03-06 19:10:05 +08:00
-											Update docs for ops, payments, and deployment guidance
										
										
											2026-03-21 14:52:25 +08:00
+								最后更新：`2026-03-21`