# bj-traffic

**Repository Path**: robot1937/bj-traffic

## Basic Information

- **Project Name**: bj-traffic
- **Description**: 北京限行通 🚗 — Vue3 + Spring Boot，限行查询 + 41探头地图 + 智能避六环
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-12
- **Last Updated**: 2026-06-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 北京限行通 🚗

> 一站式查询北京尾号限行 / 探头分布 / 进京证 / 智能避六环路线规划的 Web 应用。

[![Vue](https://img.shields.io/badge/Vue-3.5-4FC08D?logo=vue.js&logoColor=white)](https://vuejs.org/)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.x-6DB33F?logo=spring&logoColor=white)](https://spring.io/projects/spring-boot)
[![Vite](https://img.shields.io/badge/Vite-5.x-646CFF?logo=vite&logoColor=white)](https://vitejs.dev/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](#)

---

## 📖 项目背景

本地的有车一族每天都要面对：
- 今天到底限不限行？尾号几和几？
- 想绕开五环、六环怎么走？
- 进京证怎么办？办多久？经常去哪些口子查得严？
- 哪些路段有违章探头，怎么避开？

市面上的限行工具多半信息分散、地图静态、缺乏路径规划。**北京限行通**把这些零散信息整合在一张地图上，开车人打开就能看：今日限号、当前位置周边探头、常见进京证办理点、智能“避六环”或“绕六环”路线、以及自己的明日限行提醒。

## ✨ 核心功能

| 模块 | 描述 |
|---|---|
| 🗺 **高德地图** | 五环 + 六环近似边界叠加，自动定位用户位置，支持 PC + 移动端 |
| 📅 **今日限行** | 实时计算今日限行尾号，支持周末 / 节假日 / 调休工作日判别 |
| 📆 **本周日历** | 一周限行日历，4 列移动端 / 7 列桌面响应式 |
| 📡 **41 个探头** | 北京市内常见违章探头位置，支持按区域 / 类型筛选 |
| 🛂 **进京证办理** | 展示线上办 / 现场办、处罚说明、最近更新时间 |
| 🚦 **智能路线规划** | 三策略：避六环 / 普通 / 先出六环再走外环 |
| 🚗 **我的车提醒** | 输入车牌尾号，快速判断今天 / 明天是否限行 |
| 🩺 **运行健康提示** | 首页显示后端端口、政策源、数据更新时间 |

## 🛠 技术栈

**前端** (`client/`)：
- Vue 3.5 + Vite 5 + 单文件组件（SFC）
- 高德地图 JSAPI 2.0（`@amap/amap-jsapi-loader`）
- Axios HTTP 客户端
- LocalStorage 本地车牌资料存储

**后端** (`server/`)：
- Spring Boot 3.x + Java 17
- Maven 构建
- 内置节假日 / 调休日历规则
- JUnit 5 回归测试

## 🚀 快速开始

### 1. 申请高德地图 Key（必需）
1. 注册 https://lbs.amap.com 账号
2. 控制台 → 应用管理 → 创建应用 → **Web 端 (JS API)**
3. 复制 **Key** 与 **安全密钥（jscode）**

### 2. 配置环境变量

复制示例文件并填入你的 Key：

```bash
cd client
cp .env.example .env.local
```

编辑 `.env.local`：

```bash
VITE_AMAP_KEY=你的高德 Web 端 Key
VITE_AMAP_SECURITY_CODE=你的高德安全密钥
VITE_API_BASE_URL=/api
# 如需把前端代理到别的端口，可额外配置：
# VITE_API_TARGET=http://localhost:8090
```

### 3. 启动后端

```bash
cd server
mvn spring-boot:run
# 默认端口 8090
```

### 4. 启动前端

```bash
cd client
npm install
npm run dev
# 默认访问 http://localhost:5180
```

### 5. 运行测试

```bash
cd server
mvn test
```

## 📂 目录结构

```text
bj-traffic/
├── client/
│   ├── src/
│   │   ├── components/
│   │   │   ├── MapView.vue
│   │   │   ├── PolicyBanner.vue
│   │   │   ├── WeekCalendar.vue
│   │   │   ├── InfoPanel.vue
│   │   │   ├── VehicleTools.vue
│   │   │   └── StatusStrip.vue
│   │   ├── api.js
│   │   ├── config.js
│   │   ├── App.vue
│   │   └── main.js
│   ├── .env.example
│   └── vite.config.js
├── server/
│   ├── src/main/java/com/bjtraffic/
│   │   ├── config/
│   │   ├── controller/
│   │   ├── dto/
│   │   ├── entity/
│   │   └── service/
│   ├── src/test/java/com/bjtraffic/service/
│   └── pom.xml
└── README.md
```

## ⚙️ 关键配置常量

| 文件 | 常量 / 配置 | 说明 |
|---|---|---|
| `client/src/components/MapView.vue` | `SIXTH_RING` | 六环近似椭圆参数：`{cx:116.405, cy:39.915, rx:0.305, ry:0.185}` |
| `client/.env.local` | `VITE_AMAP_KEY` | 高德 JSAPI Key |
| `client/.env.local` | `VITE_AMAP_SECURITY_CODE` | 高德安全密钥 |
| `client/vite.config.js` | `VITE_API_TARGET` | 前端代理目标，默认 `http://localhost:8090` |
| `server/src/main/java/com/bjtraffic/service/HolidayCalendarService.java` | `HOLIDAYS / ADJUSTED_WORKDAYS` | 节假日与调休工作日规则 |

## 📸 截图

> 当前版本已包含：地图页、进京证页、我的车提醒页、后端健康提示。浏览器验收截图见任务回执。

## 📝 限行规则参考

工作日尾号限行（含京 X 字号牌），周末与法定节假日不限行，调休工作日按工作日规则执行：

| 周几 | 限行尾号 |
|---|---|
| 周一 | 2 和 7 |
| 周二 | 3 和 8 |
| 周三 | 4 和 9 |
| 周四 | 5 和 0 |
| 周五 | 1 和 6 |

> ⚠️ 当前项目内置 2026 节假日 / 调休日历与 2026-2027 轮换周期。若官方发布临时调整，请以最新公告为准。

## 🔐 安全提示

- ❌ 不要把高德 Key / security code 提交到公开仓库
- ✅ 使用 `.env.local` 注入，已在 `.gitignore` 中排除
- ✅ 高德安全密钥应配置服务白名单
- ✅ 当前镜像仓库不包含 `.env.local`

## 📜 License

MIT