OnecardDemo 本地消费与服务器单点功能设计
目标与范围
在现有 Java Android Demo 中补齐 CPU 用户卡本地消费，以及一卡通 WebService 连接、查询和消费记录上传。各能力独立操作、独立显示；本阶段不串成正式业务流程。
硬件与协议证据
| 项目 | 结论 | 状态 |
|---|---|---|
| 用户卡/控制/PSAM | HID 通道 1/2/3 | 抓包确认 |
| 现金/补助钱包 | EC11/EC12 | 现金扣款已验证；补助扣款待验证 |
| 消费链路 | 80 50 → PSAM 80 70 → 80 54 → PSAM 80 72 | Windows 1 分消费确认 |
| HID 长请求 | 每片最多 24 字节 | 抓包确认 |
样本余额 604→603 分，计数 43→44；PSAM 卡号 000621000206，PSAM 序号 62，TAC A4441B33。
本地消费
账号、消费额、钱包策略和消费时间毫秒值全部必填。钱包策略支持补贴优先自动分账、主钱包 0、补助钱包 1。时间转换为 yyyy-MM-dd HH:mm:ss，APDU 使用 7 字节 BCD。
- 读取并校验卡片、账号、状态和余额。
- 激活控制与 PSAM 通道，读取 PSAM 信息。
- 卡片消费初始化。
- PSAM 计算交易序号与 MAC1。
- 卡片扣款并返回 TAC/MAC2。
- PSAM 确认。
防重复扣款：
80 54 已发送但结果不可信时禁止自动重试；应先重新读卡核账。PSAM 确认失败不代表卡片未扣款。补贴优先
- 补助足够：一笔补助交易。
- 补助不足：先补助、再现金，返回两笔结果。
- 总余额不足：写卡前拒绝。
- 第一笔成功、第二笔失败：返回部分成功，不回滚、不重试第一笔。
WebService 单点功能
服务器地址和应用 ID 均必填；SOAP 1.1 命名空间为 http://NewCap.com/NewCapecWebService/。
| 功能 | SOAP 操作 | 附加必填 |
|---|---|---|
| 单个用户 | GetInfoByCustID | 账号 |
| 部分用户 | GetCustomerByNum | 起始账号、数量 |
| 全部/总数 | GetCustomerCount、分段 GetCustomerByNum | 无 |
| 黑名单 | GetBLLTCount、GetBLLTAll | 无 |
| 部门 | GetCustDeptCount、GetCustDeptInfo | 无 |
| 上传 | UploadBusinessRec | 上传结构全部字段 |
上传字段
UPLOADINFO 的 16 个输入字段全部需要提供：termID、custID、cardNO、cardSn、cardClass、cardASN、sumFare、mngFare、objNo、opFare、oddFare、opCount、jyDT、psamID、psamJyNo、tac。数值可为 0 但不得留空；rtn 是输出。
页面与验收
主页面增加本地消费区域和服务器功能入口；服务器单点页面集中提供连接、查询、上传和可复制结果区。现金消费需 Android 1 分真机验收；补助钱包需有补助余额卡；SOAP 与上传需真实服务器。构建或单元测试通过不能替代这些现场门禁。
不在本阶段范围
不实现自动上传、失败补传、消费流水数据库、注册码/混淆 key 生成、M1/NFC 复合卡或其他项目 PSAM 的兼容性承诺。