1 建设目标
本方案面向海外充电网络运营场景，围绕 OCPI 中 CPO（Charging Point Operator，充电点运营商）角色建设平台能力。CPO 负责充电站点、充电设备、连接器、费率、充电会话和结算明细的运营，并通过 OCPI 与 eMSP、漫游平台或 HUB 交换数据，使电动车用户能够跨网络查找充电点、发起充电、获取实时状态并完成跨网络结算。
平台建设目标如下：
建立统一的 CPO 运营域模型，管理 Location、EVSE、Connector、Tariff、Session、CDR 和 Token 等核心对象。
实现基于 HTTPS REST API 的 OCPI 2.2.1 对接，支持版本发现、凭据交换、模块路由和标准响应格式。
将自有充电桩协议或内部运营系统转换为 OCPI 对外模型，隔离设备协议差异。
支持实时状态同步、远程启停、令牌授权、充电过程同步和充电详单推送。
通过幂等、重试、审计和对账机制，保证跨平台数据交换可追踪、可恢复。
2 范围与角色边界
方案只描述 CPO 侧平台能力以及 CPO 与外部合作方之间的 OCPI 互联，不替代充电桩与设备管理平台内部使用的 OCPP、私有协议或厂商接口。OCPP 负责充电桩与充电管理系统之间的设备通信，OCPI 负责不同充电网络或服务平台之间的数据和业务互联。
角色 职责 CPO 侧关注点
CPO 运营充电站和充电设备，维护充电服务和结算数据 Locations、Tariffs、Sessions、CDRs 为主要输出；Tokens、Commands 为主要输入
eMSP 面向车主提供找桩、授权、启停和账单服务 消费 CPO 的位置、状态和费率，向 CPO 提供用户令牌并发起远程命令
HUB 连接多个 CPO 和 eMSP，承担漫游互联 识别客户端能力、路由模块请求并传递业务语义
车主与车辆 使用充电服务并产生充电会话 不直接调用 OCPI，由 eMSP 或 CPO 业务系统代为处理
3 总体架构
平台采用“设备接入层、CPO 运营域、OCPI 适配层、合作方接入层”分层设计。设备接入层接收 OCPP 或厂商协议消息；运营域维护设备和交易的权威状态；OCPI 适配层负责对象映射、版本兼容、响应封装和同步任务；合作方接入层负责外部 HTTPS 请求、令牌鉴权、限流、审计和回调。
层次 核心组件 主要职责
设备接入层 OCPP Gateway、设备会话、消息解析器 接收 BootNotification、StatusNotification、MeterValues 和交易消息，维护桩和枪的实时状态
运营域 站点、设备、连接器、订单、费率、会话、详单服务 形成统一模型，处理充电流程、计费、订单和运营规则
OCPI 适配层 版本路由、对象转换、分页、幂等、重试、回调调度 将内部模型映射为 OCPI 2.2.1 对象，处理模块同步
合作方接入层 HTTPS API、Token 校验、访问控制、审计日志 提供 CPO Sender/Receiver 接口，保护外部访问
数据与运维层 关系库、缓存、消息队列、对象存储、监控 保存业务数据、同步游标、原始报文、失败任务和指标
4 OCPI 版本发现与认证流程
OCPI 对接应先完成版本和凭据协商，再进入业务模块。双方通过版本信息确认支持的 OCPI 版本和模块入口，再通过 Credentials 模块交换后续请求使用的 Token。平台应把合作方信息、国家代码、Party ID、版本 URL、模块 URL、Token、有效期和状态作为独立的连接记录。
阶段 交互 CPO 平台处理
1 版本发现 合作方访问版本入口，获取支持的版本列表 返回 OCPI 版本号及版本详情入口
2 版本详情 合作方查询指定版本的模块入口 返回 Credentials、Locations、Sessions 等 base URL
3 凭据交换 双方交换 Token 和对方信息 安全保存 Token，校验国家代码和 Party ID，建立连接状态
4 能力确认 根据角色和模块列表确定 Sender/Receiver 方向 只开放已启用模块，拒绝未授权访问
5 业务同步 开始位置、费率、令牌、会话和详单交换 记录同步游标、版本号、时间戳和失败重试任务
认证建议采用 Authorization: Token 请求头。Token 必须以密文或密钥引用方式保存，日志中只记录脱敏值；合作方停用、Token 轮换或连续鉴权失败时，应暂停该连接的业务同步。
5 CPO 核心模块设计
5.1 Locations 位置与充电设备
Locations 是 CPO 对外提供充电资源信息的基础模块。Location 表示一个充电站点，EVSE 表示站点中的一台充电设备，Connector 表示具体插头或充电接口。平台应维护对象之间的稳定 ID 关系，并支持新增、更新、停用、状态变化和分页查询。
Location：名称、地址、经纬度、国家、城市、营业时间、可访问性和设施信息。
EVSE：EVSE UID、二维码、状态、最后更新时间、硬件信息和连接器列表。
Connector：标准、格式、最大功率、电压、电流和连接器状态。
同步策略：静态属性变更使用 PUT/版本更新，实时状态变更及时推送或按时间戳增量获取。
5.2 Tariffs 费率
Tariffs 模块用于向 eMSP 提供价格计算所需的费率结构。费率不能只保存一个展示价格，还应拆分为能源费、时间费、停车费、会话费、税费和货币等可计算组件，并通过时间段、功率、能量或会话条件表达计费规则。
费率必须绑定货币、有效期和适用范围，并明确价格单位及小数精度。
费率变更需要保留历史版本，已开始的会话按照费率快照计费。
海外部署要考虑时区、夏令时、税率、货币和本地化展示，内部统一使用 UTC 存储时间。
5.3 Tokens 令牌授权
Tokens 模块用于在 eMSP 和 CPO 之间同步授权令牌。CPO 收到充电桩侧的授权请求后，可通过本地缓存判断令牌所属合作方和授权状态，再决定是否启动会话。令牌数据应设置有效期、最后更新时间和来源标记，并支持撤销和增量更新。
5.4 Sessions 会话
Session 描述正在进行的充电过程，是设备状态、授权、计量和订单之间的连接点。CPO 侧应以内部 transaction_id 作为主键，以 OCPI session_id 作为对外标识，并建立 EVSE、Connector、Token、Tariff 和 eMSP 的关联。
开始：记录开始时间、初始电量、初始计量值、授权令牌和费率快照。
进行中：接收并聚合 MeterValues，更新当前功率、电量、持续时间和状态。
结束：记录结束时间、结束原因、最终计量值和最终状态，生成待结算数据。
同步：对外推送时使用 last_updated 时间戳和幂等键，避免重复创建或覆盖新数据。
5.5 CDRs 充电详单
CDR（Charge Detail Record）是完成充电后的结算依据，应由 CPO 在会话结束并完成计费计算后生成。CDR 必须能够回溯到 Session、Location、EVSE、Connector、Token、Tariff 和原始计量数据。
数据组 关键字段 校验要求
身份关联 CDR ID、Session ID、CPO、eMSP、Token ID 唯一，关联关系完整
时间与计量 开始/结束时间、开始/结束电量、充电时长 时间使用 UTC，结束值不得小于开始值
费用 总金额、货币、费率、税费、费用维度 金额可由费用维度复算，精度和舍入规则固定
位置 Location、EVSE、Connector、地址快照 保留会话发生时快照，避免历史失真
5.6 Commands 远程命令
Commands 模块承载跨平台远程操作，典型命令包括 START_SESSION、STOP_SESSION、RESERVE_NOW、CANCEL_RESERVATION 和 UNLOCK_CONNECTOR。OCPI 命令只表达业务意图，CPO 需要将其转换为内部订单动作或 OCPP 远程命令，并把设备侧结果异步回传给调用方。
命令接收后先校验 Location、EVSE、Connector 和 Token 的归属，再检查设备在线及当前状态。
命令应生成 command_id 并持久化状态，区分 RECEIVED、ACCEPTED、RUNNING、SUCCESS、FAILED 和 TIMEOUT。
设备未在线、枪状态不允许或交易已存在时，应返回明确失败原因，不能用通用成功响应掩盖实际结果。
6 接口与数据交换规范
所有 OCPI 接口统一使用标准 Response 格式，至少包含 status_code、status_message、timestamp 和 data。分页接口应返回协议约定的分页信息；增量同步应使用时间范围、offset、limit 或 last_updated 组合，避免合作方重复拉取全量数据。
接口类别 CPO 对外能力 数据方向
Versions 版本列表和版本详情 CPO 提供，合作方获取
Credentials Token 交换、合作方信息和连接更新 双方双向
Locations 站点、EVSE、Connector 信息和状态 CPO 提供给 eMSP/HUB
Tariffs 费率与价格组件 CPO 提供给 eMSP/HUB
Tokens 接收合作方令牌并返回授权结果 eMSP 提供，CPO 接收
Sessions 实时会话和会话状态 CPO 提供给 eMSP/HUB
CDRs 已完成充电详单 CPO 提供给 eMSP/HUB
Commands 接收远程命令并异步返回执行结果 eMSP/HUB 提供，CPO 接收
Charging Profiles 接收或提供智能充电策略 按合作方角色和协议能力启用
7 一致性与可靠性设计
海外漫游对接存在网络延迟、合作方短暂不可用、重复请求和异步回调乱序等问题，平台必须将“接口调用成功”和“业务处理成功”分开处理。
幂等：以 HTTP 方法、资源 ID、last_updated 或业务 command_id 形成幂等键；重复 PUT 不应产生重复数据。
重试：仅对连接失败、超时和可恢复的 5xx 错误重试；4xx 参数错误不应无限重试。
顺序：按合作方和资源维度保存更新时间，拒绝旧版本覆盖新版本。
补偿：同步失败进入消息队列或任务表，支持指数退避、人工重试和死信处理。
对账：按 Session、CDR、金额和货币进行日级对账，发现缺失、重复或金额不一致时生成差异单。
可观测：记录 trace_id、partner_id、module、resource_id、HTTP 状态、OCPI 状态码、耗时和重试次数。
8 安全与合规要求
传输安全：生产环境强制 HTTPS，证书和 TLS 配置按合作方要求管理。
访问控制：按 partner_id、country_code、party_id、角色和模块控制资源访问范围。
令牌安全：Token 加密存储，展示和日志脱敏，支持轮换、吊销和双 Token 过渡期。
个人信息：Token 可能关联用户或车辆，公开接口和日志只保留完成授权所需的最少信息。
审计：保留凭据变更、远程命令、费率变更、CDR 重发和人工修订记录。
数据驻留：根据海外部署国家和合作方合同要求，规划数据库、日志和备份的存储区域。
9 部署与运维方案
建议采用容器化部署，将 OCPI API、同步任务、命令服务和设备接入服务拆分为可独立扩缩容的组件。OCPI API 作为无状态服务部署在负载均衡之后；合作方连接状态、幂等记录和同步游标存储在共享数据库；异步同步与重试使用消息队列。
组件 部署建议 关键指标
OCPI API 多实例无状态部署，网关统一鉴权和限流 请求量、P95 延迟、4xx/5xx、OCPI 错误码
同步任务 按合作方和模块分片，支持暂停和重试 待处理数、成功率、重试次数、任务延迟
命令服务 持久化命令状态，异步等待设备结果 命令成功率、超时率、平均完成时间
数据存储 业务库与审计库分离，原始报文进入对象存储 连接数、慢查询、存储增长、备份状态
监控告警 日志、指标、链路追踪统一采集 合作方不可用、Token 失效、CDR 积压、对账差异
10 测试与验收标准
测试域 验收内容 通过标准
版本与认证 版本发现、版本详情、Credentials Token 交换 双方可完成认证，未授权 Token 被拒绝
位置同步 Location、EVSE、Connector 全量和增量同步 对象层级、字段、分页和更新时间正确
费率同步 Tariff 新增、修改、失效和多货币 价格组件可计算，历史会话费率不受新版本影响
授权与启停 Token 授权、START_SESSION、STOP_SESSION 命令状态可追踪，设备结果能回传
实时会话 Session 状态、电量、功率和时间更新 无重复、无倒退，断线后可补齐数据
详单结算 CDR 生成、推送、重发和对账 金额可复算，重复推送不产生重复详单
异常恢复 超时、5xx、合作方不可用、旧版本覆盖 按策略重试，失败可人工恢复，数据不丢失
安全审计 鉴权、越权、Token 脱敏和操作审计 敏感数据不泄露，关键动作可追溯
11 实施阶段建议
第一阶段：完成 CPO 内部统一模型和版本/凭据模块，打通测试合作方。
第二阶段：完成 Locations、Tariffs、Tokens、Sessions 和 CDRs 主链路，优先支持找桩、授权、充电和结算闭环。
第三阶段：接入 Commands、Charging Profiles 和 HUB 场景，增加异步回调、任务编排和多合作方路由。
第四阶段：完善跨国部署、货币税费、对账、运营监控、合规审计和合作方自助配置。
12 结论
以 CPO 为核心建设海外充电平台时，OCPI 不应被当作若干孤立 REST 接口，而应作为连接设备运营、漫游授权、实时会话和结算数据的外部业务契约。平台需要先建立稳定的内部运营模型，再通过版本发现、凭据交换、模块适配、幂等同步和对账机制向不同 eMSP 或 HUB 提供一致能力。
本方案以 OCPI 2.2.1 为接口基线，具体启用模块、字段约束、合作方认证方式和数据保存周期，应在项目实施阶段结合目标国家法规、漫游伙伴能力和现有 OCPP/运营平台接口进一步确认。
