CCU621M/app/pos_vtk

CCU–POS VTK 串口结算功能设计说明（草案）

版本：v0.1
协议参考：vtk-protocol-en-1.23.pdf（VTK protocol 1.23）

---

1. 应用场景概述

• 角色

  • VMC（Vending Machine Controller）：本项目中的 CCU 主控，负责充电控制、计量和向 POS 发起扣款 / 结算请求。
  • POS 终端：支持 VTK 协议的支付终端，完成银行卡 / 钱包扣款，并把结果回传给 CCU。

• 业务流程（高层逻辑）

  1. 车主在充电桩侧操作“启动充电”（扫码 / 刷卡 / 远程指令等），CCU 准备启动充电流程。
  2. CCU 根据配置计算 预扣款金额（例如 50 元，可配置）。
  3. CCU 通过 串口上的 VTK 协议 向 POS 发送“预扣款请求”消息，请求冻结该金额。
  4. POS 完成预扣并返回“通过 / 拒绝 / 超时”等结果：
     • 通过：CCU 进入正常充电流程。
     • 拒绝：CCU 不启动充电，向用户提示相应原因。
  5. 充电完成（正常结束 / 故障结束 / 用户中止）后，CCU 计算 最终充电金额（按电量 / 时间 / 固定服务费等计费规则）。
  6. CCU 再次通过 VTK 协议向 POS 发送“结算请求”，携带最终金额以及会话标识。
  7. POS 根据最终金额完成扣款 / 退款（与预扣差额），返回结算结果。
  8. CCU 记录最终结算结果到本地订单 / 日志系统，并更新 UI / 平台状态。

• 通信方式

  • 物理层：串口（UART），波特率等推荐按 VTK 文档默认值：115200 8N1，无流控。
  • 链路层：可选择直接使用原始串口帧结构（1F 起始 + 长度 + 协议号 + TLV + CRC16）。
  • 应用层：严格遵循 VTK base protocol（0x96FB/0x97FB）的 TLV 编码要求。

---

2. VTK 协议要点（与本项目相关部分）

2.1 基本帧格式（串口模式）

参考文档第 2 章，串口下消息帧结构：

• Start：1 字节，固定 0x1F
• Length：2 字节，大端，表示“后续所有数据长度（不含 CRC16）”
• Protocol discriminator：2 字节，大端
  • 0x96FB：VMC → POS
  • 0x97FB：POS → VMC
• Application message：0..65533 字节，BER TLV（ISO/IEC 8825-1）
• CRC16：2 字节，大端，CRC16-CCITT（初始值 0xFFFF），从 Start 到 TLV 最后一字节

2.2 TLV 参数

VTK base protocol 中应用消息是多个 TLV 参数的组合：

• Tag：1~3 字节（此协议中基本为单字节 Tag，例如 0x01 Message name、0x04 Amount 等）
• Length：1~3 字节
• Value：具体值（ASCII / Binary / UTF-8）

本项目中 优先使用的 Tag（参考文档 3.1）：

• 0x01：Message name（ASCII 3）—— 如 "CDP", "CRD", "INF", "PRS" 等。
• 0x03：Operation number（ASCII 数字，8 位）—— 可做一次充电会话的 ID。
• 0x04：Amount in minor currency unit（ASCII，金额的“最小货币单位”，例如分）。
• 0x11：Local time（可选，用于时钟同步）。
• 0x12：System information（可选，用于 POS 侧展示桩信息）。

后续业务实现只需先支持必要的 Tag，留出扩展空间即可。

---

3. 业务消息与状态机设计（草案）

3.1 关键业务实体

• ChargeSession（充电会话）

  • sessionId：对应 VTK 的 Operation number（Tag 0x03）。
  • gunNo：枪号（0/1/...）。
  • preAuthAmount：预扣款金额（单位：分）。
  • finalAmount：最终金额（单位：分）。
  • state：Idle / PreAuthPending / PreAuthOk / Charging / SettlePending / Settled / Failed。

• VTKOperation

  • messageName（Tag 0x01）：例如 "CDP"（预扣款）、"CRD"（结算）等。
  • direction：VMC→POS 或 POS→VMC。
  • tlvList：一个 TLV 参数列表。

3.2 建议消息映射（可根据实际对接调整）

• 预扣款请求（CCU→POS）

  • Message name (0x01)："CDP"（或自定义，如 "CHP"：Charge PreAuth）
  • Operation number (0x03)：本次充电会话 ID（ASCII 数字）
  • Amount (0x04)：预扣款金额，单位“分”，例如 5000 表示 50.00 元

• 预扣款响应（POS→CCU）

  • Message name (0x01)："CDP"（同请求）
  • Operation number (0x03)：与请求一致
  • Amount (0x04)：实际冻结金额（可与请求相同）
  • 结果参数：可以使用 System information 或自定义扩展的 Simple data block（0x0D）中定义结果码，例如：
    • 0：Approved
    • 1：Declined
    • 2：Timeout

• 结算请求（CCU→POS）

  • Message name (0x01)："CRD"（Charge Debit / Refund）
  • Operation number (0x03)：与本会话相同
  • Amount (0x04)：实际消费总金额（分）

• 结算响应（POS→CCU）

  • Message name (0x01)："CRD"
  • Operation number (0x03)：同请求
  • Amount (0x04)：最终扣款金额
  • 结果码（同上）

3.3 CCU 侧状态机（简化）

1. Idle

   • 等待用户操作（插枪、刷卡、平台下发启动命令）。

2. PreAuthPending

   • 组包 VTK CDP 预扣款请求，通过串口发给 POS。
   • 等待响应（配置超时，例如 15s），期间可处理心跳 / 重发。

3. PreAuthOk

   • 收到 POS 批准预扣款，更新内部状态，允许充电流程进入 Charging。

4. Charging

   • 现有充电流程不变（BMS/流控/计量）。

5. SettlePending

   • 充电结束，计算 finalAmount，组包 VTK CRD 结算请求，发送给 POS。
   • 等待响应；失败可重试若干次或降级处理（仅记录本地订单，提示用户到平台查询）。

6. Settled / Failed

   • Settled：记录成功订单，通知平台/界面。
   • Failed：记录失败原因（网络/卡拒绝/超时），可与平台对账或人工处理。

---

4. 模块划分与文件结构建议

在 CCU601E_RUN/app/pos_vtk 目录下建议创建如下模块（后续实现时使用）：

1. 基础协议层

   • vtk_frame.c / vtk_frame.h
     • 串口帧封装 / 解封装（1F 起始、长度、协议号、CRC16）。
     • CRC16-CCITT 实现（参考文档第 5 章）。
   • vtk_tlv.c / vtk_tlv.h
     • TLV 编码 / 解码（Tag/Length/Value）。
     • 提供便捷接口：addAsciiParam(tag, QString), getAsciiParam(tag, ...) 等。

2. 业务协议层

   • vtk_pos_protocol.c / vtk_pos_protocol.h
     • 构造/解析 预扣款请求/响应、结算请求/响应、系统信息 等应用消息：
       • buildPreAuthRequest(session, preAuthAmount, QByteArray &outFrame)
       • parsePreAuthResponse(const QByteArray &frame, VtkResult &out)
       • buildSettleRequest(...) / parseSettleResponse(...)

3. 会话与状态机层

   • pos_vtk_service.c / pos_vtk_service.h
     • 维护每把枪的 ChargeSession 状态：
       • posVtk_startPreAuth(gunNo, amount)
       • posVtk_onFrameReceived(frame) —— 调用基础解析，然后驱动状态机
       • posVtk_notifyChargeEnd(gunNo, finalAmount) —— 进入结算流程
     • 与现有 flowctrl_task/collect_task/meter_calculate/plat_comm_task 对接。

4. 串口接入层

   • 若已有串口任务（如 uart_task），只需在串口接收回调中把 VTK 帧交给 vtk_frame 层解析。
   • 若没有，可在 app_init 或 plat_comm_task 下新增 POS 串口任务：
     • 周期读取串口缓存、拼帧、调用 posVtk_onFrameReceived。

---

5. 与现有 CCU 模块的集成点

• 启动充电：在当前启动充电逻辑中（flowctrl / bms / collect），增加“调用 posVtk_startPreAuth”步骤，并根据其结果决定是否允许进入充电状态。
• 停止充电：在充电任务或计量模块中，当确定实际消费金额后，调用 posVtk_notifyChargeEnd 进入结算流程。
• 告警与 UI 提示：
  • 预扣款失败：在 UI 或平台上显示“支付预授权失败，请重试或更换支付方式”。
  • 结算失败：记录订单异常状态，提示用户可联系运营方处理。

---

6. 后续实施步骤建议

1. 确认业务映射：与 POS 提供方确认使用的 Message name（CDP/CRD/INF 等）、结果码格式以及参数集合。
2. 实现基础协议层：vtk_frame + vtk_tlv，并通过单元测试校验：
   • CRC 计算正确。
   • TLV 编解码对齐文档。
3. 实现预扣款 / 结算消息构造与解析：vtk_pos_protocol。
4. 实现 POS 会话状态机：pos_vtk_service，并与现有充电流程打通（只改入口/出口逻辑，尽量不动核心 BMS/MDU 代码）。
5. 集成串口任务：选定 UART 口，完成收发调试（先用日志工具验证 VTK 帧格式）。
6. 与实际 POS 联调：根据联调结果调整错误码处理、超时重试策略等。

---

7. 示例报文

以下示例仅展示 TLV 内容和串口帧结构，CRC16 按实现自动计算，示例中不逐字列出。

7.1 预扣款请求（CDP）

• 业务参数：

  • Message name："CDP"（Tag 0x01）
  • Operation number："12345"（Tag 0x03，十进制 ASCII）
  • Amount："5000"（Tag 0x04，表示 50.00 元）

• TLV 区段（十六进制）：

  • 01 03 43 44 50
    • Tag=0x01，Len=0x03，Value="CDP"
  • 03 05 31 32 33 34 35
    • Tag=0x03，Len=0x05，Value="12345"
  • 04 04 35 30 30 30
    • Tag=0x04，Len=0x04，Value="5000"

• 串口帧结构：

  • 1F 起始字节
  • 00 LL Length（2 字节，大端，= ProtocolDisc + TLV 长度）
  • 96 FB Protocol discriminator（VMC→POS）
  • 01 03 43 44 50 03 05 31 32 33 34 35 04 04 35 30 30 30 TLV 数据
  • CC CC CRC16-CCITT（由代码计算）

7.2 结算请求（CRD）

• 参数示意：
  • Message name："CRD"（0x01）
  • Operation number：与预扣款相同 "12345"（0x03）
  • Amount：最终金额 "4200"（0x04，表示 42.00 元）

TLV 结构与上例相同，仅值不同。

7.3 响应报文（POS→CCU）

• 假设 POS 对预扣款返回：
  • Message name："CDP"
  • Operation number："12345"
  • Amount："5000"
  • Result：Tag 0x0D，Length=1，Value=0x00（Approved）

TLV 区段：

• 01 03 43 44 50 （CDP）
• 03 05 31 32 33 34 35 （Operation number）
• 04 04 35 30 30 30 （Amount）
• 0D 01 00 （Simple data block，结果码=0）

串口帧中的 Protocol discriminator 为 0x97FB（POS→VMC）。

---

说明：本文件为第一版设计草案和实现说明，后续在实际联调和业务确认过程中，可根据需要继续细化：

• 完善错误码与 POS 侧状态码的映射
• 增加更多业务消息（如 INF、PRS 等）
• 完善异常流程（网络断开、POS 重启、CRC 错误等）的处理策略。