# 智慧停车综合管理平台（Smart Parking Platform）
> **一句话简介**：一套集园区态势感知、视频监控大屏、异常智能报警、停车运营管理与 AI 智能助手于一体的、可私有化 Docker 一键部署的智慧停车综合管理平台。
## 目录
- [一、详细功能描述](#一详细功能描述)
- [二、解决的行业痛点](#二解决的行业痛点)
- [三、核心技术优势](#三核心技术优势)
- [四、应用场景](#四应用场景)
- [五、适配目标行业与人群](#五适配目标行业与人群)
- [六、商业应用价值](#六商业应用价值)
- [七、技术架构](#七技术架构)
- [八、环境前置依赖](#八环境前置依赖)
- [九、快速开始](#九快速开始)
- [十、完整安装部署教程](#十完整安装部署教程)
- [十一、AI 对话（TokenFree）使用教程](#十一ai-对话tokenfree使用教程)
- [十二、版权与使用说明](#十二版权与使用说明)
---
## 一、详细功能描述
平台围绕“一张屏、一张图、一个大脑”设计，功能逐条对应实拍截图：
### 1. 平台登录与权限体系
- 玻璃拟态登录页、动态渐变背景、发光输入框，支持账号密码登录与 JWT 鉴权。
### 1.1 项目概述大屏
平台内置炫酷的**项目概述大屏**：顶部动态标题与实时时钟，五大核心指标卡片（摄像头总数、设备在线率、
报警事件、报警规则、系统用户），近 7 天报警趋势折线图、设备状态环形分布图及最新报警实时滚动，
全部数据来自后端实时聚合，10 秒自动刷新，适配大屏投放。
### 2. 园区态势总览
- 园区停车核心指标看板：总车位、占用/空闲、异常事件、设备在线率；
- 基于本地地图的摄像头点位分布与状态渲染，支持点位点击联动。
### 3. 视频监控大屏
- 科技感数据大屏：多路摄像头实时画面、轮播、实时指标与报警滚动；
- 支持 HLS（hls.js）低延迟直播，适配主流分辨率。
### 4. 异常报警事件管理
- 报警事件列表、级别筛选、处置状态流转，事件全程可追溯。
### 5. AI 智能对话助手
- 标准 Chat Completions 流式对话，默认接入 TokenFree 的 `kimi-k2.6` 模型；
- 支持停车运营、设备状态、异常分析等问答，接口配置抽屉内置使用教程。
### 6. 个人中心
- 用户信息维护、密码修改等自助功能。
### 7. 系统管理（管理员）
- **园区地图管理**：自定义地图数据上传、切分与点位编辑。
- **摄像头管理**：摄像头档案、RTSP/RTMP 拉流地址、点位与启用状态维护。
- **报警规则管理**：按摄像头配置检测目标、触发条件与规则启停。
- **用户管理**：账号、角色（管理员/操作员）与状态管理。
---
## 二、解决的行业痛点
1. **系统割裂、信息孤岛**：传统监控、停车、报警系统各自独立，缺乏统一态势视图，运维人员需多平台切换。
2. **依赖人工值守、响应滞后**：传统监控需人工 7×24 盯屏，异常发现晚、研判慢、上报链路长。
3. **摄像头位置不可视**：不存储园区 GIS 地图与摄像头精确位置，调取和排查效率低。
4. **部署复杂、落地成本高**：传统方案环境依赖多、部署周期长，中小企业难以私有化落地。
5. **数据不沉淀、运营无依据**：缺乏停车与设备数据沉淀，管理决策缺少数据支撑。
平台以“统一面板 + 智能检测 + 一键私有化部署”系统性解决上述问题。
## 三、核心技术优势
- **全栈现代技术架构**：Umi 4 + React 18 + Ant Design 5 前端，NestJS + TypeScript 后端，模块清晰、可维护性强。
- **智能视频分析**：基于 YOLO 深度学习的实时目标检测（监控算法端），异常自动识别并联动报警。
- **低延迟流媒体**：RTMP 收流 + Nginx-RTMP/FFmpeg 转 HLS 分发，兼顾实时性与浏览器兼容性。
- **本地地图引擎**：Leaflet + 地图瓦片本地化切分与存储，支持自定义园区地图。
- **私有化一键交付**：Docker Compose 编排前后端、数据库、媒体服务，一条命令完成部署。
- **统一暗色面板设计体系**：玻璃拟态 + 霓虹光效 + 响应式布局，视觉统一、辨识度高。
- **AI 能力可插拔**：支持标准 Chat Completions 协议，可按需切换 TokenFree 上的 Kimi / Qwen / Claude 等模型。
## 四、应用场景
- 产业园区、写字楼、商业综合体的停车场与周界监控；
- 校园、医院、政务园区的车辆与人员安全管理；
- 物流园、工厂厂区的车辆出入与作业区域异常监测；
- 物业/安保指挥中心的集中监控与接处警；
- 需要私有化部署、数据不出内网的安防与停车运营场景。
## 五、适配目标行业与人群
| 维度 | 说明 |
| --- | --- |
| 目标行业 | 智慧物业、智慧园区、智慧交通、安防安保、校园/医院后勤、工厂物流 |
| 管理决策者 | 需要全局态势、数据报表与运营决策依据的管理者 |
| 一线运维/安保 | 需要视频监控、报警处置、设备巡检与快速定位的操作人员 |
| IT/集成服务商 | 需要可快速私有化交付、二次集成与品牌化部署的集成商 |
## 六、商业应用价值
- **降本增效**：自动化异常检测替代部分人工盯屏，降低人力成本、缩短响应时间。
- **私有化资产沉淀**：数据与平台完全部署在客户侧，形成可持续运营的数字化资产。
- **快速复制交付**：标准化 Docker 交付包支持多项目快速复制，显著降低项目实施成本。
- **可扩展增值空间**：可在统一平台上扩展计费、引导、数据分析等模块，形成增值收入。
- **品牌化交付能力**：支持 Logo、品牌与主题定制，便于服务商品牌化对外输出。
## 七、技术架构
### 7.1 总体架构
平台划分为 **前端、后端、监控算法端、RTMP 媒体服务器、地图瓦片服务、关系型数据库** 六大部分：
```mermaid
flowchart LR
subgraph Client[浏览器端]
UI[Umi4 + React18 + Antd5 玻璃面板]
end
subgraph Server[服务端]
API[NestJS 后端 REST + WebSocket]
DB[(MySQL 8.0)]
RTMP[RTMP/HLS 媒体服务]
TILE[地图瓦片服务]
end
subgraph AI[监控算法端]
YOLO[YOLO 实时目标检测]
end
CAM[摄像头 RTSP/RTMP 流] --> YOLO
YOLO -->|FFmpeg 推流| RTMP
YOLO <-->|WebSocket 配置/事件上报| API
UI -->|HTTPS / HLS| API
UI -->|HLS 直播| RTMP
UI -->|瓦片请求| TILE
API --> DB
```
- **前端**：React + Umi 4，Leaflet 渲染地图，hls.js 播放直播；
- **后端**：NestJS（TypeScript），负责业务逻辑、REST API、WebSocket、数据库 IO 与算法端鉴权；
- **监控算法端**：Python + YOLO，拉流、检测、推流，并通过 WebSocket 上报事件；
- **媒体服务**：RTMP 收流并转 HLS 提供浏览器直播；
- **数据层**：MySQL 8.0 持久化用户、设备、规则、报警、地图数据。
原始架构图（项目早期版本）保留于 `docs/tech-framework.png`、`docs/deployment-framework.png`。
### 7.2 端口规划（默认）
| 服务 | 容器端口 | 宿主机默认端口 |
| --- | --- | --- |
| Web 应用（HTTP/HLS） | 80 | 4010 |
| MySQL | 3306 | 4012 |
| RTMP | 1935 | 4015 |
> 端口可通过 `.env` 文件调整，详见部署章节。
## 八、环境前置依赖
### 8.1 硬件建议
| 规模 | CPU | 内存 | 磁盘 |
| --- | --- | --- | --- |
| 测试/小规模（≤16 路） | 4 核 | 8 GB | 40 GB SSD |
| 生产/中规模（16–64 路） | 8 核+ | 16 GB+ | 100 GB+ SSD |
> 监控算法端（YOLO）建议独立部署或配备 GPU 以获得更好性能。
### 8.2 软件依赖
- **Docker Engine** 20.10+
- **Docker Compose** v2+
- 开放端口：应用端口（默认 4010）、RTMP（默认 4015）；数据库端口建议仅内网开放
- 现代浏览器：Chrome / Edge / Firefox 最新版本
- （可选）AI 对话：在 [TokenFree](https://www.tokenfree.com/) 申请 API Key
完整依赖与注意事项见交付包内「文档」目录下的《环境依赖清单》与《部署注意事项》。
## 九、快速开始
```bash
# 1. 进入项目目录
cd smart-parking-platform
# 2.（可选）按需修改端口与数据库口令
# 复制并编辑环境变量文件
cp .env.example .env # Windows: copy .env.example .env
# 3. 一键启动全部服务
docker compose up -d
# 4. 浏览器访问
# http://localhost:4010
```
默认账号（见后端初始化逻辑 `backend/src/database-seeder.ts`）：
| 角色 | 账号 | 密码 |
| --- | --- | --- |
| 管理员 | `admin` | `admin123` |
| 操作员 | `operator` | `123456` |
> 首次登录后请及时修改默认密码。
## 十、完整安装部署教程
### 10.1 Docker 一键部署（推荐）
1. 安装并启动 Docker（Windows 建议使用 Docker Desktop，Linux 使用官方源安装 Docker Engine + Compose 插件）。
2. 获取项目完整源码（含 `docker-compose.yml`、`.env.example`、`front-backend.Dockerfile`）。
3. 根据现场环境调整 `.env`，关键变量：
```bash
APP_PORT=4010 # Web 访问端口
MYSQL_PORT=4012 # MySQL 宿主机端口
RTMP_PORT=4015 # RTMP 推流端口
MYSQL_ROOT_PASSWORD=<修改为强口令>
```
4. 执行 `docker compose up -d`，首次会自动构建镜像并初始化数据库、导入示例数据。
5. 使用 `docker compose ps` 查看状态，等待应用容器变为 `healthy`。
6. 浏览器访问 `http://<服务器IP>:`，使用默认账号登录。
### 10.2 本地开发/手动部署（无 Docker 时）
**后端（NestJS）**
```bash
cd backend
npm install
# 配置数据库连接（环境变量或配置文件）
npm run start:dev
```
**前端（Umi 4）**
```bash
cd frontend
npm install
# 开发启动
npm run dev
# 生产构建（如本地 pnpm 与 lockfile 版本冲突，可直接使用 umi）
# ./node_modules/.bin/umi build
npm run build
```
**监控算法端（Python + YOLO）**
```bash
cd ai-end
pip install -r requirements.txt
# 配置后端地址、RTMP 地址、管理员账号
python main.py
```
算法端基本流程：建立 WebSocket 连接 → 后端鉴权并下发摄像头配置与拉流地址 → 每个摄像头独立进程完成 FFmpeg 推流与规则检测 → 异常实时上报。
### 10.3 运维与排障
- 查看日志：`docker compose logs -f app`
- 重启服务：`docker compose restart app`
- 停止并清理：`docker compose down`（数据保留在数据卷，加 `-v` 会同时删除数据卷，请谨慎）
- 直播无画面：检查摄像头源是否可达、RTMP 端口是否放通、浏览器是否允许混合内容（建议统一走 HTTP/HTTPS 同源）。
## 十一、AI 对话（TokenFree）使用教程
平台「AI 对话」页面默认接入 [TokenFree](https://www.tokenfree.com/)——统一 AI API 网关，支持标准 Chat Completions 协议，默认模型 `kimi-k2.6`。
| 配置项 | 默认值 |
| --- | --- |
| API Base URL | `https://www.tokenfree.com/v1` |
| 默认模型 | `kimi-k2.6` |
| 协议 | 标准 Chat Completions（流式输出 / Models 列表） |
使用步骤：
1. 打开 ，注册账号并完成邮箱验证后登录；
2. 进入控制台「令牌 / API Keys」页面，点击「添加令牌」，复制生成的 Key（`sk-` 开头）；
3. 登录本系统，进入「AI 对话」页面，点击右上角齿轮（接口配置）；
4. 将 API Key 粘贴到表单（接口地址、模型已预填，一般无需修改）；
5. 点击「测试连接」验证通过后「保存」，即可开始流式对话。
说明：
- API Key 仅保存在浏览器本地（localStorage），不会上传到本系统后端；
- 可在 Model 中填写 TokenFree 支持的其他模型（如 Qwen、Claude 等）；
- 切换服务商后本地配置会自动升级版本，旧缓存不会污染新默认值。
## 十二、版权与使用说明
- 本平台的界面设计、面板风格、部署脚本、AI 对接及项目文档由交付团队完成，其使用权与商用权以合同及授权文件为准。
- 未经书面许可，不得对本平台进行复制、反向工程、转售、再次分发或用于授权之外的用途。
- 平台所接入的第三方服务（如 TokenFree）受其各自服务条款与模型许可约束，使用时请同时遵守对应条款。
- 请在遵守适用法律法规的前提下使用本平台。
---
## 相关链接
- [开源社区 GitCC](https://www.gitcc.com/)
- [GCC AI Coding](https://www.gitvv.com/)