|
|
@@ -0,0 +1,106 @@
|
|
|
+# 包月车管理 — 设计文档
|
|
|
+
|
|
|
+> 日期：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 前） |
|
