# PCIe 真卡联调与冒烟检查清单

## 1. 前置条件

- 部署环境为目标架构（与生产一致的 CPU/OS/libc）。
- 已安装厂商 `.so`，并可被进程访问。
- 服务配置为 JNA 真卡模式：
  - `tms.crypto-card.enabled=true`
  - `tms.crypto-card.mode=JNA`
  - `tms.crypto-card.vendor-lib-path` 或 `tms.crypto-card.vendor-lib-name` 正确
  - `tms.crypto-card.strict-alg-id-validation=true`（若厂商扩展算法可临时关闭）
- 已知内部接口鉴权令牌 `X-Internal-Token`。

## 2. 核心检查项（必须通过）

1. 设备与会话
   - `GET /api/v1/device/crypto/device-count`
   - `GET /api/v1/device/crypto/device-info`
   - `POST /api/v1/device/crypto/self-test`
2. 基础密码能力
   - 随机数：`GET /api/v1/device/crypto/random?length=16`
   - 摘要：`POST /api/v1/device/crypto/digest`
   - HMAC：`POST /api/v1/device/crypto/hmac`
3. 对称能力
   - 明文密钥加解密：`/encrypt/plain` + `/decrypt/plain`
   - KEK 生成与状态：`/kek/generate` + `/kek/status`
4. 主密钥状态
   - `GET /api/v1/device/crypto/lmk/seed-mac`

验收标准：

- `ApiResponse.success == true`
- `ApiResponse.code == 200`
- 返回长度字段与 Base64 解码长度一致
- 错误日志中无 native 崩溃/段错误

## 3. 高风险专项

### 3.1 `SDFE_ImportEncKeyPair_ECC`（结构体直传）

- 用最小可用样本执行导入流程。
- 成功后立即查询相关密钥状态接口验证导入结果。
- 若出现参数错误，优先检查结构体字段对齐与 `unsigned long` 位宽。

### 3.2 `ECCCipher` 变长字段边界

- 对不同明文长度执行 ECC 加密路径。
- 记录返回 `ECCCipher.l` 的最大值。
- 若接近当前上限（`C_MAX_LEN`），必须提升上限并复测。

### 3.3 算法标识白名单

- 对业务实际用到的所有 `algId` 跑一遍。
- 若被严格校验拦截，补充到 `Gm0018AlgorithmIds` 后再回归。

## 4. 失败排查顺序

1. 配置错误：库路径、库名、鉴权 token。
2. 运行时依赖：`ldd`/动态库缺失。
3. 参数编码：Base64 入参、长度字段、结构体大小。
4. 算法标识：`algId` 是否在白名单。
5. 厂商错误码：结合 `PcieErrorMapper` 与厂商文档定位。

## 5. 回归策略

- 每次升级以下任一项，都执行本清单：
  - JDK 版本
  - 厂商 `.so` 版本
  - JNA 结构体定义
  - `JnaPcieCryptoService` 参数转换逻辑

## 6. 自动化模板

- 使用脚本：`scripts/pcie_realcard_smoke.sh`
- 建议在联调机和预生产各执行一次，并保留日志归档。