lc_garage/docs/superpowers/specs/2026-07-23-digital-ticket-design.md

数字票（Digital Ticket）— 设计文档

日期：2026-07-23 | 优先级：P0

1. 目标

引入数字票作为停车业务的统一抽象模型。所有进场方式（RFID/车牌识别/手动）最终创建数字票，以票的状态驱动计费、支付和放行。

2. 状态机

                    ┌──────────┐
               ┌──→ │  已过期   │ ←──┐
               │    └──────────┘    │
               │     超时未支付      │ 超时未离场
               │                    │
  ┌────────┐  │  ┌───────────┐  ┌──┴───┐  ┌────────┐
  │ 已创建  │─→│  │  待支付    │─→│ 已支付 │─→│ 已离场  │
  └────────┘    └───────────┘  └──────┘  └────────┘
  车辆入场      自动转换       支付成功    验证放行

状态	描述	触发条件
created	车辆入场，数字票生成	入场事件触发
pending_payment	待支付	创建完成后自动进入
paid	已支付，费用结清	支付成功回调
exited	已离场，流程结束	验证通过后开闸
expired	超时未支付或未离场	定时任务/超时逻辑

3. 数据模型

digital_ticket 表

字段	类型	说明
id	uint	主键
ticket_no	string	票号（UUID，二维码凭证）
plate_number	string	车牌
trigger_mode	string	rfid / plate_recognition / manual
state	string	created / pending_payment / paid / exited / expired
vehicle_record_id	uint	关联 vehicle_record
entry_time	datetime	入场时间
exit_time	datetime	出场时间
fee	float64	计费金额
payment_method	string	cash / free / wechat / alipay
payment_order_no	string	支付单号（关联 payment_record）
paid_at	datetime	支付时间
expire_at	datetime	超时过期时间
event_log	text(JSON)	事件日志数组

event_log 格式

[
  {"at": "2026-07-23 10:30", "event": "created", "trigger": "manual"},
  {"at": "2026-07-23 12:30", "event": "fee_calculated", "fee": 15.0},
  {"at": "2026-07-23 12:31", "event": "paid", "method": "cash", "amount": 20}
]

4. API

方法	路径	说明
POST	/digital-ticket/create	创建票（入场时）
GET	/digital-ticket/:ticketNo	查询票（扫码用）
POST	/digital-ticket/:ticketNo/calculate	计费
POST	/digital-ticket/:ticketNo/pay	支付
POST	/digital-ticket/:ticketNo/exit	离场验证
GET	/digital-ticket/list	列表

5. 与现有流程关系

任何进场方式 → DigitalTicket.Create() + VehicleEntry()
                                    │
                            状态: created → pending_payment
                                    │
                             ExitPreview / ExitConfirm
                                    │
                            状态: paid → exited

数字票作为业务状态层，位于 internal/modules/digital-ticket/，不替代 vehicle_record。

6. 文件变更

文件	操作
internal/dao/digital_ticket.go	新建
internal/modules/digital-ticket/api.go	新建
internal/modules/digital-ticket/service/service.go	新建
internal/modules/digital-ticket/repository/repo.go	新建
internal/service/vehicle/vehicle.go	修改（VehicleEntry 创建 digital_ticket）
internal/initialize/gorm.go	修改（AutoMigrate）
internal/initialize/router.go	修改（路由注册）