包月车管理 — 设计文档

日期：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 前）

2026-07-22-monthly-card-design.md 3.7 KB Permalink Verlauf Originalformat