# parking_system

**Repository Path**: olddove/parking_system

## Basic Information

- **Project Name**: parking_system
- **Description**: 团队协作大作业
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: html
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-11
- **Last Updated**: 2026-07-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智慧停车共享系统

这是一个大作业版本的智慧停车共享系统。项目采用 **Python 后端 + 静态内存数据 + 原生 HTML/CSS/JavaScript 前端** 实现，当前不接数据库，重点展示用户、车位主、车主、管理员和核心订单流程。

## 1. 项目特点

- 后端使用 Python 标准库 `http.server` 提供 HTTP API，不依赖 Flask/FastAPI。
- 数据存储使用内存静态数据，重启后端会恢复初始状态。
- 前端使用原生 HTML/CSS/JavaScript，不需要构建工具。
- 已接入高德地图 Web JS API，用于地图展示、选点和标记车位组。
- 支持多浏览器/多设备同时登录，每个浏览器使用独立 token。
- 支持同一局域网手机访问页面。
- 支持二维码图片预览、下载、扫码到达的模拟流程。

## 2. 项目结构与文件作用

```text
park_system/
├─ README.md                         # 项目说明、运行方式、接口说明
├─ frontend_server.py                # 前端静态服务启动脚本，会输出本机和局域网访问地址
├─ backend/
│  ├─ __init__.py
│  ├─ api_server.py                  # 后端 HTTP API 入口，负责路由、JSON 响应、CORS、token 会话
│  ├─ errors.py                      # BusinessError 业务异常，统一返回错误码和错误信息
│  ├─ models.py                      # 数据模型和枚举定义，例如 User、ParkingGroup、Order、Transaction
│  ├─ demo_module1.py                # 用户模块演示脚本
│  ├─ demo_module2.py                # 车位主模块演示脚本
│  ├─ demo_module3.py                # 车主订单模块演示脚本
│  ├─ demo_module4.py                # 管理员模块演示脚本
│  ├─ demo_module5.py                # 核心业务逻辑演示脚本
│  ├─ data/
│  │  ├─ __init__.py
│  │  └─ store.py                    # 静态内存数据仓库，保存用户、车位组、车位、订单、交易等数据
│  └─ services/
│     ├─ __init__.py
│     ├─ user_service.py             # 模块一：注册登录、角色申请、个人信息、钱包、交易明细
│     ├─ parking_owner_service.py    # 模块二：车位组申请、开放时段、我的车位、收益统计
│     ├─ driver_service.py           # 模块三：车主搜索、预约、扫码到达、订单管理、历史记录
│     ├─ admin_service.py            # 模块四：用户管理、车位审核、二维码、订单争议处理
│     └─ core_service.py             # 模块五：时段冲突、余额扣款、状态联动、超时取消、订单结算
├─ frontend/
│  ├─ index.html                     # 前端页面结构，高德地图和二维码库引入位置
│  ├─ styles.css                     # 页面样式
│  └─ app.js                         # 前端交互逻辑，调用后端 API、渲染地图、订单、二维码等
└─ docs/
   └─ development.md                 # 开发文档，说明模块逻辑、流程和后续数据库迁移设计
```

## 3. 环境要求

- Python 3.10 或更高版本。
- 浏览器建议使用 Chrome、Edge。
- 手机访问时，手机和电脑需要连接同一个 Wi-Fi。
- 不需要安装数据库。
- 不需要安装 Node.js 运行项目，Node.js 只在开发时用于语法检查。

## 4. 运行方式

### 4.1 启动后端

打开 PowerShell：

```powershell
cd D:\C_data\park_system
$env:PYTHONPATH="D:\C_data\park_system"
python backend\api_server.py
```

启动后终端会输出类似内容：

```text
智慧停车系统后端已启动
本机 API: http://127.0.0.1:8000
局域网 API: http://192.168.1.23:8000
健康检查: http://192.168.1.23:8000/api/health
手机前端访问地址通常为: http://192.168.1.23:5173
```

健康检查：

```text
http://127.0.0.1:8000/api/health
```

### 4.2 启动前端

再打开一个 PowerShell：

```powershell
cd D:\C_data\park_system
python frontend_server.py
```

启动后终端会输出类似内容：

```text
智慧停车系统前端已启动
本机访问: http://127.0.0.1:5173
手机/局域网访问: http://192.168.1.23:5173
请确保后端也已启动，并允许 Python 通过 Windows 防火墙。
```

电脑浏览器访问：

```text
http://127.0.0.1:5173
```

手机浏览器访问终端输出的局域网地址，例如：

```text
http://192.168.1.23:5173
```

## 5. 演示账号

| 角色 | 手机号 | 登录密码 | 支付密码 |
|---|---|---|---|
| 车主 | `13800000001` | `abc12345` | `123456` |
| 车位主 | `13800000002` | `abc12345` | `123456` |
| 管理员 | `13800000003` | `abc12345` | `123456` |

说明：

- 普通车主默认拥有 `driver` 角色。
- 车位主账号拥有 `driver` 和 `owner` 角色。
- 管理员账号拥有 `driver` 和 `admin` 角色。
- 登录后前端会把后端返回的 token 保存在浏览器 `localStorage` 中，不同设备可同时登录不同账号。

## 6. 主要业务流程

### 6.1 车位主发布车位组

1. 登录车位主账号。
2. 进入“车位主”页面。
3. 填写车位组名称、地址、经纬度、车位数量、小时单价和开放时段。
4. 可以点击“地图选点”选择位置。
5. 点击“提交车位组”。
6. 车位组进入 `pending` 待审核状态。
7. 管理员审核通过后，系统自动生成该车位组下的单个车位和二维码内容。

### 6.2 管理员审核车位组

1. 登录管理员账号。
2. 进入“管理员”页面。
3. 在“车位组审核”中查看申请。
4. 点击“通过”或“驳回”。
5. 通过后可以点击“二维码”查看并下载二维码 PNG。

### 6.3 车主预约和支付

1. 登录车主账号。
2. 进入“钱包”，如余额不足先模拟充值。
3. 进入“地图找车位”。
4. 选择位置、半径、预约开始时间和结束时间。
5. 点击“搜索车位”。
6. 选择车位组点击“预约”。
7. 系统创建 `pending_payment` 待支付订单。
8. 自动跳转到“我的订单”。
9. 点击“支付”，输入支付密码 `123456`。
10. 支付成功后订单变为 `paid` 已支付。

### 6.4 车主扫码到达

当前业务规则是：**车主预约的是车位组容量，到达后可以扫描该车位组内任意一个未占用车位二维码**。

1. 车主到达现场。
2. 在“我的订单”页面选择已支付订单。
3. 使用摄像头扫码、上传二维码图片，或手动输入二维码内容。
4. 后端校验该二维码车位是否属于订单车位组。
5. 如果该车位未被占用，订单变为 `arrived` 已到达，车位变为 `occupied` 占用中。
6. 如果该车位已被占用，扫码失败，需要换同车位组内其他空闲车位。

### 6.5 订单完成与收益

1. 车主在“我的订单”点击“完成”。
2. 订单状态变为 `completed`。
3. 车位状态恢复为空闲。
4. 车位主余额增加订单收入。
5. 车位主可以在“收益统计”中查看完成订单、总收益、日均收益和车位利用率。

## 7. 订单状态说明

| 状态值 | 中文 | 说明 |
|---|---|---|
| `pending_payment` | 待支付 | 已创建预约订单，但还没有输入支付密码扣款 |
| `paid` | 已支付 | 已扣款，等待车主扫码到达 |
| `arrived` | 已到达 | 车主已扫码，订单绑定具体车位，车位占用中 |
| `completed` | 已完成 | 停车结束，车位恢复空闲，车位主获得收入 |
| `cancelled` | 已取消 | 用户主动取消或管理员争议退款取消 |
| `timeout_cancelled` | 超时取消 | 超过预约开始 30 分钟未扫码到��，系统自动取消 |

## 8. 车位状态说明

| 状态值 | 中文 | 说明 |
|---|---|---|
| `free` | 空闲 | 当前可用 |
| `reserved` | 已预约 | 保留状态，当前主要用于兼容旧逻辑 |
| `occupied` | 占用中 | 已有车主扫码到达并占用 |
| `disabled` | 停用 | 车位主手动停用，不可预约或扫码占用 |

## 9. 金额和时间规则

- 后端金额统一使用“分”为单位的整数。
- 前端展示时转换为“元”。
- 预约最小时长为 30 分钟。
- 当前不支持跨天预约。
- 预约必须完全落在车位组开放时段内。
- 同一车主不能预约时间重合的有效订单。
- 端点重叠也视为冲突，例如 `10:00-11:00` 和 `11:00-12:00` 算重合。
- 超过预约开始时间 30 分钟仍未扫码到达，会自动超时取消。
- 超时取消扣除订单金额 10% 作为违约金，退还 90%。

## 10. 后端接口说明

所有接口返回格式：

成功：

```json
{
  "success": true,
  "data": {}
}
```

失败：

```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "错误说明"
  }
}
```

除登录接口外，前端会在请求头中携带：

```text
X-Session-Token: 登录后返回的 token
```

### 10.1 健康检查

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/health` | 检查后端是否启动 |

### 10.2 用户与登录

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/api/auth/login` | 登录，返回 token 和用户信息 |
| GET | `/api/auth/current-user` | 获取当前 token 对应用户 |
| GET | `/api/auth/users` | 获取用户列表，演示用 |

登录请求示例：

```json
{
  "phone": "13800000001",
  "password": "abc12345"
}
```

### 10.3 钱包与交易

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/api/wallet/recharge` | 模拟充值 |
| POST | `/api/wallet/withdraw` | 提交提现申请 |
| GET | `/api/wallet/transactions` | 查看交易明细 |

充值请求示例：

```json
{
  "amount": 10000
}
```

其中 `10000` 表示 100 元。

### 10.4 车位主接口

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/api/owner/apply` | 普通车主申请成为车位主 |
| GET | `/api/owner/groups` | 查看我的车位组申请 |
| POST | `/api/owner/groups` | 提交车位组申请 |
| GET | `/api/owner/spaces` | 查看我的车位 |
| GET | `/api/owner/income` | 查看收益统计 |
| POST | `/api/owner/spaces/{space_id}/disable` | 停用车位 |
| POST | `/api/owner/spaces/{space_id}/enable` | 启用车位 |

提交车位组请求示例：

```json
{
  "name": "小区北门共享车位",
  "address": "某小区北门",
  "longitude": 116.397,
  "latitude": 39.908,
  "total_spaces": 3,
  "price_per_hour": 800,
  "open_rules": [
    {
      "weekday": 0,
      "start_time": "08:00",
      "end_time": "22:00"
    }
  ],
  "photos": []
}
```

### 10.5 车主接口

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/parking/search` | 搜索可用车位组 |
| GET | `/api/parking/space-group?space_id=xxx` | 查询车位所属车位组 |
| POST | `/api/orders` | 创建待支付预约订单 |
| POST | `/api/orders/{order_id}/pay` | 输入支付密码支付订单 |
| GET | `/api/orders` | 查看我的订单 |
| GET | `/api/orders/history` | 查看历史订单统计 |
| POST | `/api/orders/{order_id}/arrive` | 扫码到达 |
| POST | `/api/orders/{order_id}/finish` | 完成订单 |
| POST | `/api/orders/{order_id}/cancel` | 取消订单 |
| POST | `/api/orders/scan-timeout` | 扫描超时订单 |

搜索车位请求示例：

```text
GET /api/parking/search?longitude=116.397&latitude=39.908&start_time=2026-07-09T10:00:00&end_time=2026-07-09T12:00:00&radius_km=3&sort_by=distance
```

创建订单请求示例：

```json
{
  "group_id": "parking_group_xxx",
  "start_time": "2026-07-09T10:00:00",
  "end_time": "2026-07-09T12:00:00"
}
```

支付订单请求示例：

```json
{
  "pay_password": "123456"
}
```

扫码到达请求示例：

```json
{
  "qr_code": "PARKING_SPACE:parking_space_xxx:timestamp"
}
```

### 10.6 管理员接口

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/admin/users` | 用户列表，支持角色、状态、关键词筛选 |
| POST | `/api/admin/users/{user_id}/freeze` | 冻结用户 |
| POST | `/api/admin/users/{user_id}/unfreeze` | 解冻用户 |
| GET | `/api/admin/owner-applications` | 查看车位主申请 |
| POST | `/api/admin/owner-applications/{application_id}/approve` | 通过车位主申请 |
| POST | `/api/admin/owner-applications/{application_id}/reject` | 驳回车位主申请 |
| GET | `/api/admin/parking-groups` | 查看车位组申请 |
| POST | `/api/admin/parking-groups/{group_id}/approve` | 通过车位组申请并生成车位二维码 |
| POST | `/api/admin/parking-groups/{group_id}/reject` | 驳回车位组申请 |
| GET | `/api/admin/parking-groups/{group_id}/qrcodes` | 导出车位组二维码数据 |
| POST | `/api/admin/spaces/{space_id}/regenerate-qrcode` | 重新生成车位二维码 |
| GET | `/api/admin/orders` | 查看全平台订单 |
| POST | `/api/admin/orders/{order_id}/refund` | 争议订单退款取消 |

## 11. 高德地图与手机访问说明

- 前端已接入高德地图 Web JS API。
- 电脑端可以使用地图展示和地图选点。
- 手机访问局域网 HTTP 页面时，浏览器可能禁止定位和摄像头权限。
- 手机端定位失败时，可以使用“地图选点”。
- 手机端摄像头不可用时，可以上传二维码图片或手动输入二维码内容。
- 这是浏览器安全策略限制，不是后端接口问题。

## 12. 当前简化点

- 当前数据只保存在内存中，重启后端会清空车位组、车位、订单和交易等运行时数据。
- 当前支付、充值、提现均为静态模拟，不接真实支付渠道。
- 当前没有数据库事务，但核心服务按“先校验、后统一修改状态”的事务思路组织。
- 当前二维码主要由前端渲染为图片，后端保存二维码内容字符串。
- 当前安全策略适合大作业演示，不是生产级系统。

## 13. 后续可扩展方向

- 接入数据库，拆分 `users`、`parking_groups`、`parking_spaces`、`orders`、`transactions` 等表。
- 使用 Flask/FastAPI 替换当前标准库 HTTP 服务。
- 登录 token 持久化到数据库或 Redis。
- 二维码加入签名，防止伪造。
- 收益、交易、历史订单支持 CSV/PDF 导出。
- 增加站内消息、审核日志、操作日志展示。
- 支持真实短信、真实支付和 HTTPS 部署。