### Build and Run Development Server

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/superpowers/plans/2026-05-25-terminal-continent-grouping-plan.md

Commands to build the project and start the development server for verification.

```bash
cd frontend && npm run build
```

```bash
cd frontend && npm run dev
```

--------------------------------

### GET /api/ops/payments/incidents

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/API_ZH.md

Retrieve payment incidents.

```APIDOC
## GET /api/ops/payments/incidents

### Description
Retrieve payment incidents, specifically those with status payment_intent_failed. Used for troubleshooting payment issues.

### Method
GET

### Endpoint
/api/ops/payments/incidents

### Parameters
#### Query Parameters
- **reason** (string) - Optional - Filter by reason: receiver_mismatch, sender_mismatch, event_mismatch, or tx_reverted.
```

--------------------------------

### GET /api/cities

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/frontend/README.md

Retrieves a list of available cities.

```APIDOC
## GET /api/cities

### Description
Retrieves a list of available cities for weather data.

### Method
GET

### Endpoint
/api/cities
```

--------------------------------

### Run Frontend Business and Build Checks

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/superpowers/plans/2026-05-27-redis-stream-realtime-event-architecture.md

Execute frontend business logic tests, type checking, and build processes.

```bash
cd frontend
npm run test:business
npm run typecheck
npm run build
```

--------------------------------

### GET /api/ops/leaderboard/weekly

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/API_ZH.md

Retrieve the weekly points leaderboard.

```APIDOC
## GET /api/ops/leaderboard/weekly

### Description
Fetch the current weekly points leaderboard.

### Method
GET

### Endpoint
/api/ops/leaderboard/weekly
```

--------------------------------

### Run backend linting and testing

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/superpowers/plans/2026-06-23-deb-training-settlement-worker.md

Execute static analysis and unit tests to ensure service integrity before deployment.

```bash
python -m ruff check .
```

```bash
python -m pytest tests/test_training_settlement_service.py tests/test_deployment_runtime_config.py tests/test_web_observability.py -q
```

--------------------------------

### GET /api/payments/config

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/SUPABASE_SETUP_ZH.md

Checks the payment configuration status.

```APIDOC
## GET /api/payments/config

### Description
Confirms if payments are enabled and configured.

### Method
GET

### Endpoint
/api/payments/config
```

--------------------------------

### 配置运行态环境变量

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/README_ZH.md

建议将运行数据目录配置在仓库外，以避免 Git 操作冲突。

```env
POLYWEATHER_RUNTIME_DATA_DIR=/var/lib/polyweather
POLYWEATHER_DB_PATH=/var/lib/polyweather/polyweather.db
POLYWEATHER_STATE_STORAGE_MODE=sqlite
POLYWEATHER_EVENT_STORE=redis
POLYWEATHER_REDIS_URL=redis://polyweather_redis:6379/0
POLYWEATHER_REDIS_STREAM_MAXLEN=50000
POLYWEATHER_REDIS_REQUIRED=true
```

--------------------------------

### GET /healthz

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/MONITORING_ZH.md

Returns the liveness status of the service.

```APIDOC
## GET /healthz

### Description
Returns the liveness status of the service.

### Method
GET

### Endpoint
/healthz

### Response
#### Success Response (200)
- **status** (string) - The status of the service, returns "ok".
```

--------------------------------

### Run SSE Replay and Factory Tests

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/superpowers/plans/2026-05-27-redis-stream-realtime-event-architecture.md

Execute tests verifying the store factory selection and SSE replay functionality.

```bash
python -m pytest tests/test_sse_replay.py tests/test_realtime_event_store_factory.py -q
```

--------------------------------

### GET /api/city/[name]

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/frontend/README.md

Retrieves information for a specific city.

```APIDOC
## GET /api/city/[name]

### Description
Retrieves detailed information for a specific city by name.

### Method
GET

### Endpoint
/api/city/[name]

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the city.
```

--------------------------------

### 执行运行时配置校验

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/CONFIGURATION_ZH.md

在不启动服务的情况下，使用脚本检查指定组件的配置有效性。

```bash
python scripts/validate_runtime_env.py --component web
python scripts/validate_runtime_env.py --component bot
```

--------------------------------

### GET /api/ops/memberships

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/API_ZH.md

Retrieve a list of currently active memberships.

```APIDOC
## GET /api/ops/memberships

### Description
Get a list of currently active memberships, deduplicated by user with the latest expiration date retained.

### Method
GET

### Endpoint
/api/ops/memberships
```

--------------------------------

### Implement Responsive Main Layout

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/superpowers/plans/2026-05-25-terminal-continent-grouping-plan.md

Wrap the main content in a responsive container that switches between mobile tabs/cards and desktop grid layouts.

```tsx
<main className="min-h-0 flex-1 overflow-auto p-2">
  {/* Mobile layout */}
  <div className="flex flex-col gap-2 lg:hidden">
    <MobileRegionTabs
      activeTab={mobileTab}
      groups={continentGroups}
      isEn={isEn}
      onSelectTab={setMobileTab}
    />
    <div className="space-y-2 px-1">
      {mobileActiveGroup?.rows.map((row) => (
        <MobileCityCard
          key={row.id}
          row={row}
          isEn={isEn}
          onClick={setSelectedRow}
        />
      ))}
    </div>
  </div>

  {/* Desktop layout (existing 3-column grid) */}
  <div className="hidden min-h-full grid-cols-1 gap-2 lg:grid xl:grid-cols-[1.12fr_1.6fr_1.1fr]">
    {/* ... existing 3 columns unchanged ... */}
  </div>
</main>
```

--------------------------------

### GET /healthz

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/API_ZH.md

Performs a basic health check of the system.

```APIDOC
## GET /healthz

### Description
Performs a basic health check of the system.

### Method
GET

### Endpoint
/healthz
```

--------------------------------

### Project Operational Commands

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/CLAUDE.md

Standard commands for managing the frontend, backend, testing, and deployment processes.

```bash
# Frontend
cd frontend
npm run dev          # dev server :3000
npm run build        # production build
npm run typecheck    # tsc --noEmit
npm run test:business  # 19 business state tests

# Backend
uvicorn web.app:app --reload --host 0.0.0.0 --port 8000
python bot_listener.py   # Telegram bot

# Python tests
python -m pytest tests/
python -m pytest tests/test_supabase_entitlement.py

# Lint
ruff check .
ruff format .

# Docker (VPS)
docker compose down && docker compose up -d --build
```

--------------------------------

### GET /api/payments/intents/{id}

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/SUPABASE_SETUP_ZH.md

Retrieves the status of a payment intent.

```APIDOC
## GET /api/payments/intents/{id}

### Description
Polls the status of a payment intent.

### Method
GET

### Endpoint
/api/payments/intents/{id}
```

--------------------------------

### 启动服务与监控端点测试

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/MONITORING_ZH.md

使用 docker compose 启动服务，并通过 curl 测试内置的监控与状态端点。

```bash
docker compose up -d
```

```bash
curl http://127.0.0.1:8000/healthz
curl http://127.0.0.1:8000/api/system/status
curl http://127.0.0.1:8000/api/system/cache-status
curl http://127.0.0.1:8000/metrics
```

--------------------------------

### 使用脚本升级版本号

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/RELEASE.md

通过脚本自动更新版本号，支持指定版本类型或具体版本号。

```bash
python scripts/bump_version.py patch
```

```bash
python scripts/bump_version.py minor
python scripts/bump_version.py major
python scripts/bump_version.py 1.8.0
```

--------------------------------

### GET /api/auth/me

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/frontend/README.md

Retrieves the current authenticated user's information.

```APIDOC
## GET /api/auth/me

### Description
Retrieves the current authenticated user's profile information.

### Method
GET

### Endpoint
/api/auth/me
```

--------------------------------

### Frontend Minimal Configuration

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/CONFIGURATION_ZH.md

Essential environment variables required for the frontend application to connect to backend and Supabase services.

```env
POLYWEATHER_API_BASE_URL=https://your-backend.example.com
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
POLYWEATHER_AUTH_ENABLED=true
POLYWEATHER_AUTH_REQUIRED=true
NEXT_PUBLIC_POLYWEATHER_APP_ANALYTICS=false
NEXT_PUBLIC_POLYWEATHER_WEB_VITALS=false
NEXT_PUBLIC_POLYWEATHER_EAGER_CITY_SUMMARIES=false
```

--------------------------------

### GET /api/city/[name]/summary

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/frontend/README.md

Retrieves a summary for a specific city.

```APIDOC
## GET /api/city/[name]/summary

### Description
Retrieves a summary for a specific city.

### Method
GET

### Endpoint
/api/city/[name]/summary

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the city.
```

--------------------------------

### 配置 WeatherNext 2 环境变量

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/weathernext2-integration.md

设置 WeatherNext 2 的启用状态、数据路径及 GCS 访问凭据。需确保相关路径可写且 GCP 凭据具备访问权限。

```bash
WEATHERNEXT2_ENABLED=1
WEATHERNEXT2_BACKEND=gcs_zarr
WEATHERNEXT2_DATA_ROOT=/app/data/weathernext2
WEATHERNEXT2_CITY_HIGHS_PATH=/app/data/weathernext2_city_highs.json
WEATHERNEXT2_MODEL_DIR=/app/data/models/weathernext2_calibrator
WEATHERNEXT2_WORKER_INTERVAL_SEC=21600
WEATHERNEXT2_CACHE_TTL_SEC=21600
WEATHERNEXT2_GCS_ZARR_URI=gs://weathernext/weathernext_2_0_0/zarr
WEATHERNEXT2_MEAN_GCS_ZARR_URI=gs://weathernext/weathernext_2_0_0_mean/zarr
GOOGLE_APPLICATION_CREDENTIALS=/app/secrets/gcp-sa.json
```

--------------------------------

### GET /api/ops/users

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/API_ZH.md

Retrieve user information by Telegram ID, username, or email.

```APIDOC
## GET /api/ops/users

### Description
Search for users based on their Telegram ID, username, or email address.

### Method
GET

### Endpoint
/api/ops/users
```

--------------------------------

### GET /api/city/[name]/detail

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/frontend/README.md

Retrieves detailed weather data for a specific city.

```APIDOC
## GET /api/city/[name]/detail

### Description
Retrieves detailed weather data for a specific city.

### Method
GET

### Endpoint
/api/city/[name]/detail

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the city.
```

--------------------------------

### 前端环境变量配置

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/SUPABASE_SETUP_ZH.md

配置前端 Docker 容器或 .env.local 文件以连接 Supabase 并启用支付相关功能。

```env
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
POLYWEATHER_AUTH_ENABLED=true
POLYWEATHER_AUTH_REQUIRED=false
POLYWEATHER_API_BASE_URL=http://<backend-host>:8000
POLYWEATHER_BACKEND_ENTITLEMENT_TOKEN=

# WalletConnect（支持手机钱包扫码）
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=
NEXT_PUBLIC_WALLETCONNECT_POLYGON_RPC_URL=https://polygon-bor-rpc.publicnode.com

# Overlay 跳转
NEXT_PUBLIC_TELEGRAM_GROUP_URL=https://t.me/<your_group>
```

--------------------------------

### GET /api/auth/me

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/SUPABASE_SETUP_ZH.md

Retrieves the current authenticated user's profile and subscription status.

```APIDOC
## GET /api/auth/me

### Description
Retrieves the current user's authentication state and subscription status.

### Method
GET

### Endpoint
/api/auth/me
```

--------------------------------

### Development and Operational Commands

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/AGENTS.md

Commonly used commands for backend, frontend, and Docker management.

```bash
# 后端
ruff check .                    # lint
ruff format .                   # 格式化
python -m pytest                # 跑全部测试
python -m pytest tests/test_xxx.py  # 单个测试文件
uvicorn web.app:app --reload --host 0.0.0.0 --port 8000  # 开发服务器
python bot_listener.py          # Telegram 机器人

# 前端 (cd frontend)
npm run dev                     # 开发服务器 :3000 (含 sync server chunks)
npm run build                   # 生产构建
npm run typecheck               # tsc --noEmit
npm run test:business           # Playwright 业务状态测试 (19 个)
npm run lint                    # next lint

# Docker
docker compose down && docker compose up -d --build
```

--------------------------------

### GET /metrics

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/MONITORING_ZH.md

Returns system metrics in Prometheus text format. Requires operational authentication.

```APIDOC
## GET /metrics

### Description
Returns system metrics in Prometheus text format. Requires operational authentication.

### Method
GET

### Endpoint
/metrics
```

--------------------------------

### Redis Server Configuration

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/superpowers/specs/2026-05-27-redis-stream-realtime-event-architecture-design.md

Recommended Redis server settings for local VPS deployment to ensure data persistence and memory management.

```text
bind 127.0.0.1
protected-mode yes
appendonly yes
appendfsync everysec
maxmemory 512mb
maxmemory-policy noeviction
```

--------------------------------

### 执行订阅恢复脚本

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/OPS_ADMIN_ZH.md

当支付异常导致订阅未开通时，可使用此脚本根据用户邮箱进行自动对账与恢复。

```bash
python scripts/reconcile_subscription_by_email.py --email <user_email>
```

--------------------------------

### GET /api/system/cache-status

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/MONITORING_ZH.md

Lists the existence, freshness, and TTL of various cache kinds per city.

```APIDOC
## GET /api/system/cache-status

### Description
Lists the existence, freshness, and TTL of various cache kinds per city.

### Method
GET

### Endpoint
/api/system/cache-status
```

--------------------------------

### 查看支付补单日志

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/README_ZH.md

通过 Docker 日志过滤支付相关的事件循环信息。

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

--------------------------------

### GET /api/events

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/API_ZH.md

Provides a real-time event stream for weather observations using server-sent events (SSE).

```APIDOC
## GET /api/events

### Description
Browser entry point for real-time charts using text/event-stream.

### Method
GET

### Endpoint
/api/events

### Parameters
#### Query Parameters
- **cities** (string) - Optional - Comma-separated list of cities; empty means subscribe to all.
- **since_revision** (int) - Optional - Revision number for reconnection replay.
- **replay_limit** (int) - Optional - Default 500, backend-enforced limit.

### Response
#### Success Response (200)
- **connected** - Connection established, includes latest_revision.
- **city_observation_patch.v1** - Standard real-time observation patch.
- **resync_required** - Frontend should rebuild from HTTP snapshot.
- **heartbeat** - Keep-alive signal.
```

--------------------------------

### 检查版本同步结果

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/RELEASE.md

执行同步脚本并查看变更差异。

```bash
python scripts/sync_version.py
git diff
```

--------------------------------

### 检查系统健康状态

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/README_ZH.md

通过 API 接口验证系统健康、状态及指标。

```bash
curl http://127.0.0.1:8000/healthz
curl http://127.0.0.1:8000/api/system/status
curl http://127.0.0.1:8000/metrics
```

--------------------------------

### GET /api/system/status

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/MONITORING_ZH.md

Provides a summary of the system status, including database, feature flags, and event storage.

```APIDOC
## GET /api/system/status

### Description
Provides a summary of the system status, including database, feature flags, and event storage.

### Method
GET

### Endpoint
/api/system/status
```

--------------------------------

### 配置 Cloudflare 缓存规则脚本

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/CLOUDFLARE_FREE_CACHE_ZH.md

设置环境变量并运行 Python 脚本以同步或应用 Cloudflare 缓存规则。

```powershell
$env:CLOUDFLARE_API_TOKEN="<具有 Cache Settings Edit 权限的 token>"
$env:CLOUDFLARE_ZONE_ID="<polyweather.top 的 Zone ID>"
python scripts/configure_cloudflare_free.py
python scripts/configure_cloudflare_free.py --apply
```

--------------------------------

### Feedback API Response JSON

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/superpowers/specs/2026-06-08-feedback-reward-account-detail-design.md

The expected JSON structure for the GET /api/feedback endpoint, including new reward-related fields.

```json
{
  "feedback": [
    {
      "id": 123,
      "status": "resolved",
      "message": "Hong Kong COWIN reading looked stale",
      "reward_points": 300,
      "reward_reason": "Valid data freshness report",
      "rewarded_at": "2026-06-08T12:00:00",
      "reward_status": "granted"
    }
  ]
}
```

--------------------------------

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

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/API_ZH.md

Retrieves aggregated weather details for a specific city, including market scan data and meteorological analysis.

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

### Description
Provides aggregated weather details including market scan, probability distributions, and intraday meteorological signals.

### Method
GET

### Endpoint
/api/city/{name}/detail

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the city.

#### Query Parameters
- **force_refresh** (boolean) - Optional - Force refresh flag.
- **market_slug** (string) - Optional - Specific market slug.
- **target_date** (string) - Optional - Date in YYYY-MM-DD format.

### Response
#### Success Response (200)
- **market_scan** (object) - Market availability and signal data.
- **probabilities** (object) - DEB engine probability distributions.
- **intraday_meteorology** (object) - Professional meteorological analysis.
- **deb.hourly_consensus** (object) - Hourly path consensus.
- **peak** (object) - Peak window status.
- **vertical_profile_signal** (object) - Upper-air structure signals.
- **taf.signal** (object) - TAF signal analysis (non-HK airports).
```

--------------------------------

### 执行数据归档脚本

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/CONFIGURATION_ZH.md

使用 Python 脚本将实时事件归档至 Cloudflare R2。支持通过 --dry-run 参数进行试运行。

```bash
python scripts/archive_realtime_events_to_r2.py --date 2026-06-16 --dry-run
python scripts/archive_realtime_events_to_r2.py --date 2026-06-16
```

--------------------------------

### Realtime Health Monitoring JSON Schema

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/superpowers/specs/2026-05-27-redis-stream-realtime-event-architecture-design.md

Example JSON structure for exposing realtime system health metrics via the health endpoint.

```json
{
  "realtime": {
    "store": "redis",
    "redis_connected": true,
    "stream_len": 43210,
    "latest_revision": 123456,
    "oldest_revision": 80200,
    "subscriber_connected": true,
    "sse_connections": 9
  }
}
```

--------------------------------

### Backend Minimal Configuration

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/CONFIGURATION_ZH.md

Core environment variables for backend runtime, database, Redis event store, and administrative settings.

```env
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=sqlite
POLYWEATHER_EVENT_STORE=redis
POLYWEATHER_REDIS_URL=redis://polyweather_redis:6379/0
POLYWEATHER_REDIS_STREAM_MAXLEN=50000
POLYWEATHER_REDIS_REQUIRED=true
UID=1000
GID=1000
POLYWEATHER_AUTH_ENABLED=true
POLYWEATHER_AUTH_REQUIRED=false
POLYWEATHER_OPS_ADMIN_EMAILS=yhrsc30@gmail.com
TAF_CACHE_TTL_SEC=900
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=...
SUPABASE_SERVICE_ROLE_KEY=...
POLYWEATHER_BACKEND_ENTITLEMENT_TOKEN=...
POLYWEATHER_BACKEND_URL=http://polyweather_web:8000
```

--------------------------------

### Configure Wallet Payment Integration

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/FRONTEND_DEPLOYMENT_ZH.md

Build-time variables required to enable wallet payment features.

```text
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=
NEXT_PUBLIC_WALLETCONNECT_POLYGON_RPC_URL=https://polygon-bor-rpc.publicnode.com
NEXT_PUBLIC_PAYMENT_ALLOWED_HOSTS=polyweather.top,www.polyweather.top
```

--------------------------------

### 查询支付运行态

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/README_ZH.md

获取支付系统的当前运行状态。

```bash
curl http://127.0.0.1:8000/api/payments/runtime
```

--------------------------------

### 配置支付 RPC 节点

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/payments/PAYMENT_AUDIT_ZH.md

通过环境变量配置默认及多链 RPC 节点，支持多节点容灾切换。

```env
POLYWEATHER_PAYMENT_RPC_URLS=https://polygon-rpc.com,https://polygon-bor-rpc.publicnode.com
POLYWEATHER_PAYMENT_RPC_URLS_BY_CHAIN_JSON={"137":["https://polygon-rpc.com","https://polygon-bor-rpc.publicnode.com"],"1":["https://ethereum-rpc.example"]}
```

--------------------------------

### Project Directory Structure

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/AGENTS.md

Overview of the file system layout for the PolyWeather project.

```text
E:\web\PolyWeather
├── web/                 # FastAPI 后端 (app.py → create_app)
├── src/                 # Python 核心库 (analysis, data_collection, bot, database, payments)
├── tests/               # pytest (85 个文件)
├── frontend/            # Next.js 15 + React 19 + TypeScript
├── scripts/             # 运维/工具脚本 (Python)
├── deploy.sh            # VPS 部署脚本
├── docker-compose.yml   # 6+ 服务: web, frontend, bot, collector, warmer, training, weathernext2
├── bot_listener.py      # Telegram 机器人入口
├── run.py               # 机器人启动脚本 (调用 bot_listener.py)
├── pyproject.toml       # ruff 配置: E/F rules, line-length=88, py311
├── pytest.ini           # testpaths = tests
└── .github/workflows/ci.yml
```

--------------------------------

### Run Backend Verification Tests

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/docs/superpowers/plans/2026-06-08-feedback-reward-account-detail.md

Execute the backend test suite for user feedback.

```python
python -m pytest tests/test_user_feedback.py -q
```

--------------------------------

### 最小部署环境变量配置

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/frontend/README.md

运行看板和基础鉴权功能所需的必要环境变量。

```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
```

--------------------------------

### 提交代码并打标签

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/RELEASE.md

在工作区干净的状态下提交变更并创建版本标签。

```bash
git add .
git commit -m "release: v1.7.1"
git tag v1.7.1
```

--------------------------------

### 推送发布内容

Source: https://github.com/yangyuan-zhen/polyweather/blob/main/RELEASE.md

将代码及标签推送到远程仓库。

```bash
git push
git push origin v1.7.1
```