一卡通 Android 对接协议

1. 对话结论摘要

本次一卡通适配从 Windows Demo 和读卡器抓包开始，最终形成 Android Java 实现。已经确认的关键结论如下：

1. Windows Demo 的业务顺序是“连接读卡器 → 寻卡 → 读卡”，读卡前需要获得当前卡片 UID。
2. Android 的 readCard() 内部会自行寻卡；已经显式执行 findCard() 时，应调用 readCard(expectedUid) 复用 UID，避免重复完整寻卡。
3. 读卡结果包含账号、卡号、持卡序号、卡状态、卡类型、现金余额、补贴余额及各钱包消费计数，金额单位均为分。
4. 本地消费只修改卡片：优先扣补贴钱包，不足部分再扣主钱包；一次跨钱包消费可能产生两笔独立卡交易。
5. 消费交易使用当前毫秒值，上传服务端时转换为 yyyy-MM-dd HH:mm:ss。
6. 自动寻卡模式在读卡器连接后持续轮询；检测到新卡时触发一次交易，卡片拿走并连续确认无卡后才恢复等待下一张卡。
7. 长时间连接后重新打开可能出现 HID 写入 -1。F700-HW 已实现只在连接初始化阶段触发一次 xHCI 重绑恢复；该能力依赖 root 和固定硬件拓扑，不能视为通用 Android 能力。
8. 一卡通 WebService 的“连接”并非保持长连接，而是使用 URL 和 AppID 调用 GetCustomerCount 做连通性及认证验证；成功后客户端保存配置供后续请求使用。
9. AppID 必须先通过 Windows 注册流程获得并在一卡通服务器完成认证配置。Android 不复制 Windows 的 systemint.dat，只保存和使用最终数字 AppID。
10. 全量人员按账号游标分段获取，当前默认每批 1000 条；每批解析后写入 SQLite，完整成功后才清理上次快照中的过期人员。
11. 日志记录读卡器连接、USB收发、寻卡、读卡、消费、人员同步和异常，时间精确到毫秒。

2. 能力与验证状态

“代码已实现”不等同于目标硬件已经验收。涉及读卡器、PSAM、补贴卡、F700 root恢复的结论均应以目标样机实测为最终依据。

3. 代码结构与复制边界

com.zhct.traybinding.onecard
├── config/      一卡通URL、AppID默认值及输入校验
├── reader/      USB HID、寻卡、读卡、本地消费、自动巡卡
├── server/      SOAP请求、响应解析、人员/黑名单/部门/上传接口
├── customer/    全量人员分页、SQLite快照、业务人员同步扩展
└── log/         毫秒级文件日志

3.1 可作为通用一卡通代码复制

• config/OnecardSettings
• reader 包中的读卡器协议、数据模型和交易执行器
• server 全包
• log 全包
• customer 中的 CustomerBatchParser、CustomerPageSource、CustomerRecord、CustomerRepository、CustomerSyncResult、CustomerSyncService、SQLiteCustomerRepository、SyncLogger、ReaderLogSyncLogger

3.2 复制到其他项目时需要调整

• ConsumptionCardSearchManager 引用了当前应用的 BuildConfig.APPLICATION_ID 生成 USB 权限 Action。复制后必须改为目标项目的 BuildConfig，或把 applicationId 作为构造参数传入。
• NetworkBusinessPersonGateway、BusinessPersonMapper、BusinessPersonSyncService、ConsumptionPersonSyncCoordinator 依赖 ZhctTrayBindingMachine 自有网络接口和人员 DTO，属于目标业务扩展，不是新开普通用协议。
• F700 控制器恢复依赖 /system/xbin/su、USB 节点 5-1 和 xhci-hcd.1.auto，复制到其他硬件前必须重新确认拓扑。

4. Android 接入前置条件

4.1 最低代码条件

• Java 8 语法支持。
• Android USB Host API。
• 后台线程：USB和HTTP接口均为同步阻塞调用，禁止直接在主线程调用底层接口。
• 若复制当前 ConsumptionCardSearchManager，目标项目需要 Android Handler、单线程 ExecutorService 和可用的 BuildConfig.APPLICATION_ID。

4.2 Manifest

<uses-permission android:name="android.permission.INTERNET" />

<uses-feature
    android:name="android.hardware.usb.host"
    android:required="true" />

当前服务地址是 HTTP。若目标项目仍使用 HTTP，需要允许明文流量，例如：

<application
    android:networkSecurityConfig="@xml/network_security_config"
    ... />

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config cleartextTrafficPermitted="true" />
</network-security-config>

当前目标项目已经具备 INTERNET 和明文网络配置，但尚未声明 android.hardware.usb.host；正式硬件交付前应补充该声明。

4.3 USB权限与自动启动

ConsumptionCardSearchManager 会动态监听：

• 自定义 USB 权限结果；
• UsbManager.ACTION_USB_DEVICE_ATTACHED；
• UsbManager.ACTION_USB_DEVICE_DETACHED。

因此正常页面内自动连接不要求静态 device_filter.xml。只有需要“插入读卡器自动拉起应用”时，才需给 Activity 配置 USB_DEVICE_ATTACHED 和设备过滤器：

<resources>
    <usb-device vendor-id="1552" product-id="8208" />
</resources>

其中十进制 1552:8208 对应十六进制 0610:2010。

Android 13及更高 targetSdk 的项目复制动态广播代码时，需要按目标SDK要求为 registerReceiver 增加导出标志，建议使用 RECEIVER_NOT_EXPORTED。

5. 服务器配置与 AppID

当前默认值定义在 OnecardSettings：

String serverUrl = OnecardSettings.DEFAULT_SERVER_URL;
long appId = OnecardSettings.DEFAULT_APP_ID;

当前默认值：

• URL：http://10.128.1.19/WebService/Newcapec.eCard.ProxyWebService.asmx
• AppID：6

这些只是当前部署默认值，正式项目必须允许配置。URL校验规则为：

• 必填；
• 使用 http 或 https；
• 路径以 .asmx 结尾。

AppID校验规则为正整数。

5.1 AppID注册边界

1. 在可连接一卡通服务端的 Windows 环境执行厂商注册流程。
2. 使用厂商注册码完成注册，并由服务端加载对应 AppID 认证配置。
3. 获取最终数字 AppID，例如当前配置为 6。
4. Android 只保存 URL 和数字 AppID，不读取或模拟 Windows 的 systemint.dat。
5. 如果服务端没有加载该 AppID 的认证配置，Android 即使网络可达也会连接验证失败。

注册码属于敏感部署材料，不应写入源码、普通日志或本文档。

6. 读卡器高层接口

6.1 基础接口

CardReader 提供：

void connect() throws ReaderException;
CardUid findCard() throws ReaderException;
CardInfo readCard() throws ReaderException;
CardInfo readCard(CardUid expectedUid) throws ReaderException;
ConsumptionResult consume(ConsumptionRequest request) throws ReaderException;
ConsumptionBatchResult consumeSubsidyFirst(long customerId, long amount,
                                            long timeMillis) throws ReaderException;
ConsumptionBatchResult consumeSubsidyFirst(CardInfo card, long amount,
                                            long timeMillis) throws ReaderException;
void disconnect();
boolean isConnected();

具体实现：

NewcapecUsbCardReader reader = new NewcapecUsbCardReader(context);

设备检查扩展：

UsbDevice device = reader.findSupportedDevice();
boolean supported = NewcapecUsbCardReader.isSupported(device);
boolean permission = reader.hasPermission(device);
boolean physicalPresent = reader.isConnectedDevicePresent();

6.2 手动连接、寻卡、读卡

以下代码必须运行在后台串行线程：

ReaderLog.initialize(context);
ReaderLog.beginSession("ONECARD_MANUAL");

NewcapecUsbCardReader reader = new NewcapecUsbCardReader(context);
try {
    reader.connect();
    CardUid uid = reader.findCard();
    CardInfo card = reader.readCard(uid);
    // 使用 card
} catch (ReaderException error) {
    ReaderError code = error.getError();
    // 分类处理
} finally {
    reader.disconnect();
}

调用约束：

• connect() 前必须已经获得 Android USB 权限。
• findCard() 只负责获取 UID，不返回余额。
• readCard() 会先自行完整寻卡。
• 已经调用 findCard() 时使用 readCard(uid)，避免重复寻卡。
• 读卡期间卡片移除或换卡分别返回 CARD_REMOVED、CARD_CHANGED。
• 同一个 CardReader 实例上的硬件命令必须串行执行。

6.3 推荐的自动连接与巡卡接口

业务页面优先使用 ConsumptionCardSearchManager，它已经封装：

• USB设备发现；
• 权限申请；
• 插拔监听；
• 自动连接；
• 500ms巡卡；
• 连续3次无卡确认移卡；
• 单线程卡交易；
• 页面生命周期释放。

生命周期接法：

private ConsumptionCardSearchManager manager;

@Override
protected void onCreate(Bundle state) {
    super.onCreate(state);
    ReaderLog.initialize(this);
    ReaderLog.beginSession("CONSUMPTION_PAGE");
    manager = new ConsumptionCardSearchManager(this, listener);
}

@Override
protected void onStart() {
    super.onStart();
    manager.start();
}

@Override
protected void onStop() {
    if (!manager.isTransactionInFlight()) {
        manager.stop();
    }
    super.onStop();
}

@Override
protected void onDestroy() {
    manager.close();
    super.onDestroy();
}

准备一笔订单：

boolean armed = manager.armConsumption(orderNo, amountInCents);

• amountInCents == 0：只读卡，不发送扣款指令。
• amountInCents > 0：执行消费前读卡、补贴优先消费、消费后复读。
• 同一时间只能武装一笔订单。
• 卡片长期放在读卡区不会重复触发新订单；拿走并确认无卡后才恢复等待。
• 交易已经开始时不得强制中断USB线程，也不得自动重复扣款。

取消尚未开始的订单：

manager.cancelPendingConsumption();

6.4 自动巡卡回调

ConsumptionCardSearchManager.Listener：

7. 卡片与消费数据模型

7.1 CardInfo

7.2 钱包

7.3 单钱包消费

ConsumptionRequest request = new ConsumptionRequest(
        card.getCustomerId(),
        amountInCents,
        WalletType.MAIN,
        System.currentTimeMillis());

ConsumptionResult result = reader.consume(request);

注意：consume(request) 内部会重新读卡。已经有完整 CardInfo 且要求补贴优先时，应调用 consumeSubsidyFirst(card, ...)。

7.4 补贴优先消费

ConsumptionBatchResult result = reader.consumeSubsidyFirst(
        card, amountInCents, System.currentTimeMillis());

分账原则：

1. 优先使用补贴余额；
2. 补贴不足时，剩余金额使用主钱包；
3. 总余额不足返回 INSUFFICIENT_BALANCE；
4. 每个钱包产生独立的 ConsumptionResult、PSAM流水号和TAC；
5. 如果第一钱包成功、第二钱包失败，返回部分成功结果，禁止直接按原总金额重试。

ConsumptionResult 关键字段：

8. 交易一致性与禁止自动重试

推荐订单流程：

检测新卡UID
  → 消费前完整读卡
  → 校验账号、卡状态和余额
  → 按补贴优先执行一笔或两笔卡交易
  → 消费后复读同一UID
  → 核对余额和计数
  → 本地落库
  → 异步上传服务端

处理原则：

• 前读失败：没有发送扣款，可提示重新放卡。
• 扣款明确失败且未写卡：根据错误类型决定是否重试。
• 发生 TRANSACTION_OUTCOME_UNKNOWN、USB超时、卡片在扣款中移除或消费后复读失败：不得自动再次扣款，应保存原始响应并进入人工核对或补偿流程。
• ConsumptionBatchResult.isComplete() 为 false 时必须查看 getCompletedTransactions() 和 getFailure()，不能只按失败处理，否则会丢失已成功的部分扣款。
• 扣款期间禁止页面退出、USB断开或并发寻卡。

9. 读卡器错误码

10. 一卡通服务端接口

10.1 客户端与连接语义

OnecardWebServiceClient client = new OnecardWebServiceClient();
int customerCount = client.connect(serverUrl, appId);

connect() 实际执行 GetCustomerCount：

• 请求成功并解析出非负人数后，客户端才保存 endpoint 和 appId；
• 失败时不进入已连接状态；
• disconnect() 只是清除本地 URL 和 AppID，不存在需要保持的长连接或Socket；
• HTTP连接超时 8 秒，读取超时 15 秒；
• 所有方法都是同步阻塞调用，应在后台线程执行。

10.2 SOAP公共约定

10.3 接口清单

单人信息可使用：

SoapResponse response = client.getCustomer(customerId);
String display = CustomerInfoFormatter.format(response);

当前格式化器识别：CUSTOMERID、NAME、OUTID、CARDNO、CARDSN、SCARDSNR、STATUS、CARDTYPE、CUSTDEPT、ODDFARE、SUBODDFARE、OPCOUNT、OPENDT、NOUSEDATE。

11. 全量人员同步与SQLite

OnecardWebServiceClient client = new OnecardWebServiceClient();
client.connect(serverUrl, appId);

SQLiteCustomerRepository repository =
        new SQLiteCustomerRepository(context);
CustomerSyncService syncService =
        new CustomerSyncService(client, repository);

CustomerSyncResult result = syncService.sync(
        (batch, batchSaved, totalSaved, expected) -> {
            // 更新进度
        });

同步规则：

1. 先获取总人数；
2. 从 startingCustomerId = 0 开始；
3. 默认每批1000条；
4. 解析 PROXY_BASE_CUSTOMERS；
5. 每条必须有合法 CUSTOMERID；
6. 同批和跨批 CUSTOMERID 不得重复；
7. 下一批游标为本批最大账号加1；
8. 每批使用SQLite事务保存；
9. 同一账号使用主键更新，保证唯一性；
10. 只有完整同步成功后才删除上次快照中不存在的人员；
11. 中途失败保留已经保存的批次和失败记录，但不会把失败快照标为成功。

数据库：onecard.db

CustomerSyncResult 返回同步ID、预期数量、保存数量、成功批次数、开始/完成时间、耗时和数据库人数。

12. 消费记录上传

12.1 字段协议

UploadRecord 构造器的16个字段均必须提供；其中 CardSN、OPDT、SAMCardNO 还有显式格式校验。

AppID 不在 UploadRecord 构造参数内，由 SoapRequestFactory.createUpload() 自动加入 dto。

12.2 时间转换

SimpleDateFormat format = new SimpleDateFormat(
        "yyyy-MM-dd HH:mm:ss", Locale.CHINA);
String consumptionTime = format.format(
        new Date(result.getTimeMillis()));

应使用设备业务时区，并保证设备时间已经校准。

12.3 上传示例

UploadRecord record = new UploadRecord(
        terminalId,
        card.getCustomerId(),
        card.getCardNumber(),
        card.getCardSerialNumber(),
        card.getCardClass(),
        card.getApplicationSerialNumber(),
        card.getTotalAmount(),
        0L,
        transaction.getWallet().getCode(),
        transaction.getAmount(),
        transaction.getBalanceAfter(),
        transaction.getOperationCountAfter(),
        consumptionTime,
        transaction.getPsamIdDecimal(),
        transaction.getPsamTransactionNumber(),
        transaction.getTac());

SoapResponse response = client.upload(record);

跨钱包消费必须遍历 ConsumptionBatchResult.getCompletedTransactions()，每个 ConsumptionResult 分别上传一条记录，因为钱包类型、余额、消费计数、PSAM交易序号和TAC都不同。

上传失败不得回滚卡片扣款。应先把完整交易信息和原始响应持久化，再通过唯一业务流水进行幂等补传；服务端幂等键需要由业务接口另行约定。

13. SOAP响应解析

SoapResponse 提供：

boolean isFault();
String getMessage();
String getResultText();
String getRawXml();
String getOperation();
int requireCount();
List<Long> getLongValues(String elementName);
Map<String, String> getFirstValues(String... elementNames);
List<Map<String, String>> getRecords(String recordElementName);

解析器兼容带命名空间和不带命名空间的XML元素，并启用了安全XML配置，拒绝外部实体。业务代码不应通过字符串截取解析SOAP XML。

14. 日志协议

初始化：

ReaderLog.initialize(context);
ReaderLog.beginSession("业务场景名称");

日志位置：

<应用内部 filesDir>/reader_logs/

规则：

• 文件名：reader-yyyy-MM-dd.log；
• 时间格式：yyyy-MM-dd HH:mm:ss.SSS；
• 单文件默认最大5MB，超出后当天按序号轮转；
• 默认保留7天；
• 每行包含 session、level、event 和 details；
• 日志写入失败不得改变读卡、消费或同步结果。

读取：

List<File> files = ReaderLog.listLogFiles();
String text = ReaderLog.readLog(files.get(0));

禁止在普通日志中记录注册码、密码、完整身份证号等敏感信息。卡号、账号、PSAM号的日志脱敏规则应由业务项目补充。

15. USB HID底层摘要

完整底层指令、抓包样本和字段偏移见：

新开普 HID RF Picc Reader 通讯协议（逆向整理）

Android实现的核心约定：

私有操作码摘要：

通道 0x01 用于卡片，0x02 用于读卡器初始化。APDU使用 ISO/IEC 14443 Type A CRC-A，初值 0x6363，低字节在前。

16. 目标项目业务扩展

ZhctTrayBindingMachine 在通用一卡通能力之上增加了人员上传到自身业务系统的流程：

连接新开普服务
  → 全量人员按1000条拉取
  → 保存SQLite成功快照
  → 按业务接口上限分批转换
  → POST /api/oneCardTerminal/syncPersons

业务人员字段：

该业务接口和 com.zhct.traybinding.network.* 不是新开普协议的一部分，其他项目复制时应替换为自己的数据目标。

17. 接入验收清单

17.1 配置

• URL可访问且以 .asmx 结尾。
• AppID已通过Windows注册并在服务端启用。
• Android设备时间和时区正确。
• HTTP明文或HTTPS证书策略符合部署环境。

17.2 USB与读卡

• 能识别 0610:2010。
• 首次USB权限允许后能连接。
• 拒绝权限、拔出、重新插入能正确恢复。
• 同一张卡连续读取20次字段稳定。
• 无卡、读卡中移卡、换卡错误分类正确。
• 32/64字节 Report Profile 与实际端点拓扑匹配。

17.3 消费

• 主钱包小额消费后余额和计数正确。
• 补贴余额足够时只扣补贴。
• 补贴不足时先补贴后现金，两笔结果均保存。
• 总余额不足不写卡。
• 扣款中移卡、USB超时不自动重扣。
• 消费前后卡号、账号和UID一致。
• 交易时间、PSAM号、PSAM流水号、TAC完整。

17.4 服务端与数据

• 连接验证返回非负人数。
• 单人、部分人员字段解析正确。
• 全量人员按1000条分页且最终数量一致。
• 同账号重复同步只更新一条数据。
• 黑名单和部门数量与列表一致。
• 每个钱包交易分别上传成功。
• 网络失败后补传不会生成重复消费记录。

17.5 稳定性

• 连接一次后循环寻卡/读卡100次，每次间隔200ms。
• 页面反复进入退出时USB资源正常释放。
• 服务器稳定性测试记录成功率、最小/最大/平均/P95耗时。
• 连续运行后关闭再打开读卡器，无需物理插拔；若触发F700恢复，日志完整。

18. 已知边界

• 当前底层协议是根据抓包、真机和现有实现逆向整理，不是厂商正式底层协议。
• M1卡、复合卡、挂失卡、过期卡、坏卡的完整错误码仍不完整。
• 补贴钱包、不同PSAM和不同卡发行批次需要更多样本验证。
• F700控制器恢复不可直接用于其他Android主控。
• 服务端上传的业务幂等规则不在当前SOAP客户端内，需要服务端明确。
• OnecardWebServiceClient 超时目前是固定值，尚未开放构造配置。
• 核心接口为同步调用；自动巡卡管理器负责线程化，但直接使用底层接口的项目必须自行管理线程和生命周期。