# 代码组织与演进规划

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

## 1. 当前组织方式

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

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

## 2. 新模块约定

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

```text
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. 当前关键调用关系

```text
前端/设备事件
  -> 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 层跨表直接更新会话、数字票和支付流水。
- 不为了新功能修改或删除旧数据字段；新增字段应兼容历史数据，并说明查询回退策略。