lc_garage/doc/代码规划.md

代码组织与演进规划

更新日期：2026-08-07 本文档描述当前工程边界和后续演进原则，不代表已创建的目录均已实现。

1. 当前组织方式

项目保留既有 GVA 风格目录用于稳定功能维护，同时将新增领域能力放到 internal/modules/。

internal/
├─ api/v1/               # 既有 HTTP 控制器
├─ service/              # 既有业务、设备与统一通行服务
├─ router/               # 既有路由组
├─ dao/                  # GORM 实体
├─ model/                # 请求、响应和公共模型
├─ initialize/           # GORM、路由、种子数据、设备初始化
├─ global/ core/         # 配置、数据库、日志、服务启动
└─ modules/              # 新领域模块
   ├─ parking-session/   # 停车会话
   ├─ digital-ticket/    # 数字票
   ├─ payment/           # 支付配置和支付流水
   ├─ monthly/           # 包月车
   ├─ shift/             # 交接班
   ├─ report/            # 收入报表
   └─ printer/           # 小票打印

2. 新模块约定

新增业务模块采用下列结构，按实际复杂度选择是否需要全部层次：

internal/modules/<module>/
├─ api.go
├─ service/
├─ repository/
└─ model/
   ├─ request/
   └─ response/

• api.go：HTTP Handler 和路由注册函数。
• service：事务、状态机、领域校验和跨模块编排。
• repository：GORM 查询、条件更新、分页查询。
• model：模块自身请求和响应模型；共享模型仍放在 internal/model/common。

3. 模块边界

模块	所有权	不应承担
parking-session	在场会话、身份定位、进出场事实快照、会话状态	支付网关、票据状态机
digital-ticket	票号、状态、事件日志、票据查询	通道设备事实、资金流水
payment	支付入口/方式配置、金额校验、支付流水	车辆入场、闸机控制
printer	票据版式、串口/USB 打印	创建会话或决定支付状态
service/parking	设备通道定位、统一通行、闸机动作	直接修改多个领域表绕过事务服务

4. 当前关键调用关系

前端/设备事件
  -> PassageService.HandlePassage
  -> ParkingSessionService 定位或创建会话
  -> TicketService 创建或查询数字票
  -> PaymentService 完成结算
  -> ParkingSessionService.CloseSessionTx 关闭会话
  -> TicketService 标记已离场
  -> GateController 执行开闸/关闸

跨模块协作优先通过 internal/service/enter.go 的服务注册中心或稳定接口进行，避免模块间随意相互导入形成循环依赖。

5. 后续演进

优先级	演进项	目标
P0	摄像头识别适配层	将 OCR 识别结果转换为统一通行请求，不复制进出场逻辑
P0	支付回调适配层	POS、中央缴费机、线上支付通过统一幂等回调进入支付服务
P1	异常处置模块	无票、人工抬杆、设备离线、支付不确定状态形成可审计工单
P1	设备事件和告警	统一记录设备在线、开闸失败、打印失败等事件
P2	报表查询仓储化	报表复杂查询逐步从既有 service 收敛到模块 repository

6. 禁止事项

• 不新增第二套车辆出场或支付状态机。
• 不把支付入口当作支付方式，或把纸质小票当作数字票本体。
• 不在 API 层跨表直接更新会话、数字票和支付流水。
• 不为了新功能修改或删除旧数据字段；新增字段应兼容历史数据，并说明查询回退策略。