# hezhou-charging

**Repository Path**: AVC_HC/hezhou-charging

## Basic Information

- **Project Name**: hezhou-charging
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-25
- **Last Updated**: 2026-09-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 贺州高速充电桩可视化系统

基于**高德地图**的广西壮族自治区**关键点位（高速出入口 + 内陆港口/码头）与充电桩**可视化平台。

## 项目目的

以"交通关键位置找充电桩"为核心：把全广西的高速收费站/出入口、内河港口/码头统一为**关键点位**，在地图上可视化展示，并围绕每个关键点位检索周边充电桩，帮助判断"高速/港口沿途哪里能充电"。

## 主要功能

- **区域两级筛选**：广西全境 → 14 个地级市 → 各区县（市/区县下拉联动，默认"全部区县"）
- **边界可视化**：全境显示全部市边界，选市显示该市全部区县边界，选区县高亮该县边界（高德行政区划数据）
- **关键点位**：高速出入口（带日均新能源数据）+ 港口码头（带"港"标识），地图标签显示**名称 + 周边充电桩数量**
- **充电桩检索**：围绕关键点位拉取周边充电桩（流式进度），支持点位详情（费用/桩数/功率/照片）
- **数量统计**：全境/市模式下标签直接显示各区县/各市的关键点位聚合数量（灰色 0 = 未拉取）
- **交互快捷键**：ESC 逐级退回（区县 → 全部区县 → 广西全境）；点击地图区域直接切换筛选；标记展示/隐藏切换
- **数据缓存**：城市/区县列表、区域边界在**后端数据库 + 前端 localStorage** 双层缓存，多用户零重复配额消耗
- **静态数据快照**：一键把已拉取的全部数据导出为 SQL，多端部署可直接初始化/重建，避免重复调用高德
- **账号系统**：邀请码注册 / 登录 / 修改密码 / 生成邀请码（左侧边栏"账号管理"）；未登录只能看到登录页
  - 首次启动自动生成初始邀请码 → `backend/data/initial_invite.txt`（注册首个账号用）
  - 实现：`backend/app/modules/auth/`（Flask Blueprint, 密码 pbkdf2 加盐哈希, 会话 token 存库）

## 技术栈

| 层 | 技术 |
|---|---|
| 前端 | React 19 + TypeScript + Vite + Ant Design 6 + SCSS |
| 地图 | 高德地图 JS API 2.0（@amap/amap-jsapi-loader） |
| 后端 | Python 3.9+ + Flask + Flask-SQLAlchemy |
| 数据库 | SQLite（默认 `backend/data/hezhou.db`，可用 `DB_PATH` 环境变量覆盖） |
| 部署 | 单进程（前端构建产物由 Flask 托管），systemd 守护 |

## 快速开始（本地开发）

环境要求：Python 3.9+、Node.js 18+。

```bash
# 1. 安装依赖并启动(开发模式)
./start.sh            # 前端 http://localhost:5180 (代理到后端)
                       # 后端 http://localhost:8090

# 或生产模式(单进程, 前端构建后由后端托管)
./start_prod.sh               # 前台 http://<本机IP>:8090
./start_prod.sh --daemon      # 后台运行(日志 prod.out / PID prod.pid)
./start_prod.sh --skip-build  # 跳过前端构建(已构建过)
```

> 端口：后端 **8090**（`PORT` 环境变量可覆盖），前端开发 **5180**。

## 首次使用

### 1. 配置高德 API Key

打开页面 → 右上角 **⚙ 设置** → 填写三个 Key（已保存会自动回填，无需重复录入）：

| 字段 | 用途 |
|---|---|
| Web服务 API Key | 后端调用高德 POI 搜索/行政区划（拉取数据、边界） |
| Web端 (JS API) Key | 前端地图展示 |
| 安全秘钥 securityJsCode | JS API 2.0 安全校验 |

> 若地图加载报错 `USERKEY_PLAT_NOMATCH` 等，请在高德控制台把访问域名/IP 加入 Web端 Key 的白名单。

### 2. 初始化数据（推荐：静态快照，零配额）

项目内置静态数据快照 `scripts/data_snapshot.sql`（含全部关键点位/充电桩/边界，拉取时间见文件头）：

- **首次启动自动初始化**：数据库为空且快照存在时，后端启动会自动导入，无需任何操作
- **手动重建**：设置 → **重建数据**（覆盖业务数据，保留高德 Key）

### 3. 拉取新数据（可选，消耗高德配额）

在具体市/区县下点击"拉取关键点位"/"拉取充电桩"（左侧日志面板实时显示进度，可取消）：

- **拉取关键点位**：关键词 收费站/高速出入口/港口/码头，自动分类入库
- **拉取充电桩**：围绕该范围全部关键点位逐个检索周边充电桩（流式）

> 拉取消耗高德 Web 服务配额（个人 Key 约 5000 次/日），建议按市/区县逐步拉取。

## 使用指南

- **选择区域**：左上角"市/区县"下拉，或直接点击地图上的市/区县边界/名称标签
- **ESC 返回**：具体区县 → 按 ESC 退回全部区县 → 再按 ESC 退回广西全境（选择区域时右侧有气泡提示）
- **查看充电桩**：点击地图出入口/港口标签 → 周边充电桩以蓝点+虚线展示，点击蓝点弹出详情
- **隐藏标记**：右上角眼睛按钮切换出入口标记显示/隐藏（仅具体区县模式可用）
- **拉取时间**：右侧列表每项显示"拉取 2026-08-23 05:30"（最近一次聚合/刷新时间）

## 数据说明

- **关键点位**（`toll_stations`）：类别 `出入口`（高速收费站/出入口）与 `港口码头`（内河港口/码头/渡口），含城市、区县、坐标、拉取时间
- **充电桩**（`charging_stations`）：名称、地址、费用、桩数、功率、营业时间、照片等
- **区域边界/区县列表**（`region_boundaries` / `city_counties`）：高德行政区划，首次拉取后落库，所有用户复用，零重复配额
- **数量统计**（`region_counts`）：各市/区县关键点位按 1km 聚类后的数量，拉取数据时自动更新

### 静态快照维护

```bash
# 全部数据拉取完成后, 重新导出快照(覆盖 scripts/data_snapshot.sql)
python3 scripts/export_snapshot_sql.py

# 全量拉取本地全部数据(14市关键点位+充电桩)
python3 scripts/full_pull_local.py    # 需要本机后端 8090 运行中
```

> 快照**不包含**高德 Key（`settings` 表），部署后需单独配置 Key。

## 生产部署（Linux + systemd）

```bash
# 1. 拉代码 + 装依赖 + 构建前端
git clone git@gitee.com:AVC_HC/hezhou-charging.git
cd hezhou-charging
./start_prod.sh --daemon        # 首次: 建venv+装依赖+构建+启动

# 2. 配置 systemd 守护(开机自启/崩溃拉起)
cat > /etc/systemd/system/hezhou-charging.service <<'EOF'
[Unit]
Description=Hezhou Charging Map
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=root
WorkingDirectory=/root/hezhou-charging/backend
Environment=PORT=8090
Environment=FLASK_DEBUG=0
ExecStart=/root/hezhou-charging/.venv/bin/python run.py
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload
systemctl enable --now hezhou-charging

# 3. 日常管理
systemctl status hezhou-charging
journalctl -u hezhou-charging -f
systemctl restart hezhou-charging
```

**更新代码**：`git pull` → （前端有改动时）`cd frontend && npm run build` → `systemctl restart hezhou-charging`

> 多端部署时：把 `backend/data/hezhou.db`（或先导出快照）拷贝到新机器，启动即可复用全部数据，无需重新拉取。

## API 概览（前缀 `/api`）

| 接口 | 说明 |
|---|---|
| `GET /cities`、`GET /cities/<city>/counties` | 城市/区县下拉选项 |
| `GET /boundaries/<region_key>?keyword=` | 区域边界（数据库缓存） |
| `GET/POST /toll-stations`、`/toll-stations/fetch-stream` | 关键点位查询/流式拉取 |
| `GET /toll-stations/counts?city=` | 数量统计（按市/按区县） |
| `GET /charging-stations`、`/charging-stations/fetch-stream` | 充电桩查询/流式拉取 |
| `POST /settings/rebuild-data` | 从静态快照重建数据 |

## 目录结构

```
backend/
  app/
    core/            # 配置/地理工具/静态托管/城市列表
    modules/
      toll_station/  # 关键点位(出入口+港口码头): 模型/服务/路由
      charging_station/  # 充电桩
      settings/      # 高德Key配置 + 重建数据
      regions/       # 城市/区县/边界(数据库缓存)
frontend/
  src/
    features/hezhou-stations/  # 地图页: 面板/地图逻辑/状态/hooks
scripts/
  data_snapshot.sql   # 静态数据快照(部署初始化/重建)
  export_snapshot_sql.py  # 导出快照
  full_pull_local.py      # 本地全量拉取
  cleanup_districts.py    # 数据清理维护
```