# 包月车管理 — 设计文档

> 日期：2026-07-22 | 优先级：P1

## 1. 目标

实现包月车（月卡/季卡/年卡）的办理、续费、到期管理。办卡自动加入白名单，到期自动移除，进出场复用现有白名单检查逻辑。

## 2. 核心设计

### 办卡 = 自动白名单

```
选车辆 → 选卡类型 → 自动计算到期日 → 确认办理
  ├── INSERT monthly_card
  ├── INSERT shortlist (白名单 + ExpirationTime)
  └── INSERT payment_record
```

### 进出场识别

复用现有白名单检查（passage.go / vehicle.go），零改动。月卡到期后短名单自动失效。

### 到期处理

车辆进出场时，若白名单 `ExpirationTime < now`，前端/后端提示已到期。

## 3. 数据模型

### 新增表：`monthly_card`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | uint | 主键 |
| vehicle_id | uint | 关联 vehicle.id |
| card_type | string | month / quarter / year |
| start_date | date | 生效日期 |
| end_date | date | 到期日期 |
| fee | float64 | 实收金额 |
| payment_status | string | paid / refunded |
| operator_id | uint | 办理人 |
| remark | string | 备注 |

### 复用表

| 表 | 用途 |
|------|------|
| shortlist | 白名单 + ExpirationTime = end_date |
| payment_record | 收银记录 |

## 4. 页面结构

新增菜单：**停车管理 → 包月车管理**

```
┌─────────────────────────────────────────┐
│ 包月车管理                              │
│                                         │
│ [办理月卡]                               │
│                                         │
│ ┌───────────────────────────────────────┐│
│ │ 列表：车牌 | 卡类型 | 生效日期 | 到期日 ││
│ │ 金额 | 状态 | 操作(续费/退卡)         ││
│ └───────────────────────────────────────┘│
└─────────────────────────────────────────┘
```

**办理弹窗**：
```
车牌号选择器 → 卡类型(月/季/年) → 自动显示到期日 → 金额输入 → 确认
```

**续费**：点击续费 → 选续费时长 → 确认（end_date 延长 + 更新 shortlist）

## 5. API

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /monthly-card/create | 办理月卡 |
| POST | /monthly-card/renew | 续费 |
| GET | /monthly-card/list | 列表（车牌/类型/状态筛选） |
| DELETE | /monthly-card/refund | 退卡 |

## 6. 文件变更

| 文件 | 操作 | 说明 |
|------|------|------|
| `internal/dao/monthly_card.go` | 新增 | DAO 实体 |
| `internal/modules/monthly/api.go` | 新增 | Handler + Router |
| `internal/modules/monthly/service/service.go` | 新增 | 办理/续费/退卡 |
| `internal/modules/monthly/repository/repo.go` | 新增 | CRUD |
| `internal/initialize/router.go` | 修改 | 注册路由 |
| `internal/initialize/gorm.go` | 修改 | AutoMigrate |
| `internal/initialize/seed.go` | 修改 | 菜单+权限 |
| `frontend/src/view/parking/monthlyCard.vue` | 新增 | 包月车管理页面 |
| `frontend/src/api/monthlyCard.js` | 新增 | API 封装 |
| `frontend/src/lang/zh-CN.js, en.js` | 修改 | 翻译键 |

## 7. 边界情况

| 场景 | 处理 |
|------|------|
| 一辆车多次办卡 | 只能有一条有效记录，续费延长到期日 |
| 到期后车辆进出 | 白名单 ExpirationTime 过期，按临时车计费 |
| 退卡 | 标记 refunded，从 shortlist 移除 |
| 月卡到期当天 | 当天仍有效（23:59:59 前） |