初始化项目
This commit is contained in:
waner
@@ -0,0 +1,48 @@
|
||||
# JDK17 + Mockito + CI Stability Implementation Plan
|
||||
|
||||
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
||||
|
||||
**Goal:** Stabilize local/CI test execution by fixing Mockito agent startup behavior and pinning CI to JDK 17.
|
||||
|
||||
**Architecture:** Configure Maven Surefire to preload Mockito as a javaagent and set required JVM flags to avoid runtime self-attach failures. Add a CI workflow that always uses JDK 17 and runs compile/test checks. Update README for explicit developer/CI runtime expectations.
|
||||
|
||||
**Tech Stack:** Maven Surefire, Mockito, GitHub Actions, JDK 17, Spring Boot 3.5
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Build/Test runtime hardening
|
||||
|
||||
**Files:**
|
||||
- Modify: `pom.xml`
|
||||
|
||||
1. Add explicit `mockito.version` property.
|
||||
2. Add `maven-surefire-plugin` with `argLine` including:
|
||||
- `-Djdk.attach.allowAttachSelf=true`
|
||||
- `-XX:+EnableDynamicAgentLoading`
|
||||
- `-javaagent:${settings.localRepository}/org/mockito/mockito-core/${mockito.version}/mockito-core-${mockito.version}.jar`
|
||||
|
||||
### Task 2: CI JDK pinning
|
||||
|
||||
**Files:**
|
||||
- Create: `.github/workflows/ci.yml`
|
||||
|
||||
1. Add workflow on `push` + `pull_request`.
|
||||
2. Use `actions/setup-java` with Temurin `17`.
|
||||
3. Run `mvn -q -DskipTests compile` then `mvn -q test`.
|
||||
|
||||
### Task 3: Documentation sync
|
||||
|
||||
**Files:**
|
||||
- Modify: `README.md`
|
||||
|
||||
1. Add explicit local recommended JDK 17 note.
|
||||
2. Add CI note: workflow runs JDK 17 and compile+test.
|
||||
3. Add troubleshooting note for Mockito agent behavior on newer JDKs.
|
||||
|
||||
### Task 4: Verification
|
||||
|
||||
**Commands:**
|
||||
1. `mvn -q -DskipTests compile`
|
||||
2. `mvn -q test` (sandbox)
|
||||
3. `mvn -q test` (escalated fallback if sandbox attach restrictions block)
|
||||
4. Key checks with `rg` for workflow and surefire config.
|
||||
@@ -0,0 +1,168 @@
|
||||
# PCIe密码卡强类型封装设计（第一期）
|
||||
|
||||
- 日期：2026-02-28
|
||||
- 范围：基于 `0018接口.pdf`（国密标准SDF）与 `PCIE密码卡应用接口说明书.docx`（SDFE扩展）
|
||||
- 目标：为上层提供强类型业务方法，屏蔽底层JNA细节
|
||||
|
||||
## 1. 设计目标与约束
|
||||
|
||||
### 1.1 目标
|
||||
|
||||
1. 提供强类型业务方法，不要求上层使用 `execute(command, params)`。
|
||||
2. 采用短连接会话模型：每个业务方法内部完成 `openDevice/openSession/call/closeSession/closeDevice`。
|
||||
3. 第一期开通核心子集接口，覆盖设备管理、会话、HMAC、LMK与常用密钥管理。
|
||||
4. 统一错误模型与错误码映射，便于上层处理与运维排障。
|
||||
|
||||
### 1.2 非目标
|
||||
|
||||
1. 不在第一期覆盖文档所有SDF/SDFE接口。
|
||||
2. 不在第一期做多设备负载均衡与高并发优化。
|
||||
3. 不在第一期实现JNI桥代码生成。
|
||||
|
||||
## 2. 方案选型
|
||||
|
||||
### 2.1 备选方案
|
||||
|
||||
1. 动态命令入口（`execute(command, params)`）+ 强类型外观。
|
||||
2. 纯强类型服务（推荐）。
|
||||
3. 从头文件自动生成绑定与服务代码。
|
||||
|
||||
### 2.2 选型结论
|
||||
|
||||
采用方案2：新增 `PcieCryptoService` 及其 `JnaPcieCryptoService` 实现，
|
||||
强类型方法直接调用JNA映射，统一通过短连接模板管理句柄生命周期。
|
||||
|
||||
## 3. 总体架构
|
||||
|
||||
### 3.1 分层
|
||||
|
||||
1. `PcieCryptoService`：面向上层的强类型业务接口。
|
||||
2. `JnaPcieCryptoService`：服务实现，调用 `PcieNativeLibrary`。
|
||||
3. `PcieSessionTemplate`：统一短连接模板。
|
||||
4. `PcieNativeLibrary`：JNA native函数映射。
|
||||
5. `PcieErrorMapper`：错误码映射（`retCode -> 业务可读信息`）。
|
||||
|
||||
### 3.2 调用路径
|
||||
|
||||
上层业务 -> `PcieCryptoService` 强类型方法 -> `PcieSessionTemplate` -> `PcieNativeLibrary` -> 厂商 `.so`
|
||||
|
||||
## 4. 第一期开通接口（核心子集）
|
||||
|
||||
### 4.1 设备与会话
|
||||
|
||||
1. `getDeviceNumber()` -> `SDFE_GetDeviceNumber`
|
||||
2. `getNormalDeviceNumber()` -> `SDFE_GetNormalDeviceNumber`
|
||||
3. `deviceSelfTest()` -> `SDFE_DeviceSelfTest`
|
||||
4. `deviceConfGet()` -> `SDFE_DeviceConfGet`
|
||||
5. `initIdentify(oldPin, newPin)` -> `SDFE_InitIdentify`
|
||||
|
||||
> 注：`open/close` 作为模板内部行为，不暴露给上层业务接口。
|
||||
|
||||
### 4.2 常用密钥管理（用户确认的8组）
|
||||
|
||||
1. `generateKeyPairEcc` / `generateKeyPairRsa`
|
||||
2. `generateKek`
|
||||
3. `backupUserKey` / `recoverUserKey`
|
||||
4. `backupKek` / `recoverKek`
|
||||
5. `deleteUserKey` / `deleteKek`
|
||||
6. `statusUserKeyEcc` / `statusUserKeyRsa`
|
||||
7. `statusKek`
|
||||
8. `changePrivateKeyAccessPassword`
|
||||
|
||||
### 4.3 HMAC
|
||||
|
||||
1. `hmac(algId, key, data)`
|
||||
2. 内部流程：`SDFE_HmacInit` -> `SDFE_HmacUpdate` -> `SDFE_HmacFinal`
|
||||
|
||||
### 4.4 LMK（核心）
|
||||
|
||||
1. `generateLmk` / `loadLmk` / `backupLmk` / `recoverLmk` / `destroyLmk`
|
||||
2. `checkLmk` / `exportLmkSeedMac`
|
||||
|
||||
## 5. 强类型模型
|
||||
|
||||
### 5.1 请求对象
|
||||
|
||||
1. `GenerateKeyRequest`：`keyIndex`, `keyBits`, `keyType`
|
||||
2. `RecoverUserKeyRequest`：`keyIndex`, `keyType`, `cipherKeyData`, `storeFlag`
|
||||
3. `RecoverKekRequest`：`keyIndex`, `cipherKeyData`
|
||||
4. `ChangePrivateKeyPasswordRequest`：`keyIndex`, `oldPassword`, `newPassword`
|
||||
5. `HmacRequest`：`algId`, `key`, `data`
|
||||
|
||||
### 5.2 响应对象
|
||||
|
||||
1. `OperationResult`：`success`, `retCode`, `message`
|
||||
2. `DeviceCountResult`：`deviceNumber`, `normalDeviceNumber`
|
||||
3. `DeviceConfResult`：映射 `SDFE_DeviceConf`
|
||||
4. `BackupUserKeyResult` / `BackupKekResult`：`data`, `length`
|
||||
5. `KeyStatusResult`：`keyState`
|
||||
6. `HmacResult`：`hmac`, `hmacLength`
|
||||
|
||||
## 6. 会话模板（短连接）
|
||||
|
||||
定义统一模板方法：
|
||||
|
||||
```text
|
||||
executeWithSession(apiName, callback):
|
||||
SDF_OpenDevice
|
||||
SDF_OpenSession
|
||||
callback(session)
|
||||
SDF_CloseSession
|
||||
SDF_CloseDevice
|
||||
```
|
||||
|
||||
约束：
|
||||
|
||||
1. 所有强类型方法必须通过模板执行。
|
||||
2. 关闭失败仅记录日志，不覆盖主调用错误。
|
||||
3. 模板保证异常场景也能回收句柄。
|
||||
|
||||
## 7. 错误处理
|
||||
|
||||
1. `retCode == 0`：成功。
|
||||
2. `retCode != 0`：抛 `PcieCryptoException(apiName, retCode, mappedMessage)`。
|
||||
3. 映射文档补充错误码：
|
||||
- `SDR_UKEYERR`
|
||||
- `SDR_GENKEYERR`
|
||||
- `SDR_STATEERR`
|
||||
- `SDR_RETRYERR`
|
||||
- `SDR_DEVICE_BUSY`
|
||||
- `SDR_RET_ERR_STATUS`
|
||||
- `SDR_RET_INIT_STATUS`
|
||||
- `SDR_RET_LOGINED`
|
||||
- `SDR_RET_GD32_TIMEOUT`
|
||||
4. 参数校验失败在服务层抛 `IllegalArgumentException`，不下发至设备。
|
||||
|
||||
## 8. 并发与安全
|
||||
|
||||
1. 第一期开启串行访问（单设备锁）避免状态错乱。
|
||||
2. PIN/口令参数不打印明文日志。
|
||||
3. 密钥备份字节在服务层保持二进制，不做文本日志输出。
|
||||
|
||||
## 9. 对上层的使用方式
|
||||
|
||||
示例：
|
||||
|
||||
1. `pcieCryptoService.generateLmk()`
|
||||
2. `pcieCryptoService.backupKek(keyIndex, outBufferSize)`
|
||||
3. `pcieCryptoService.hmac(request)`
|
||||
|
||||
上层仅依赖强类型接口与DTO，不直接依赖JNA类型和指针。
|
||||
|
||||
## 10. 验收标准
|
||||
|
||||
1. 强类型接口可完成第一期核心子集调用。
|
||||
2. 每个方法均使用短连接模板。
|
||||
3. 统一异常中包含 `apiName + retCode + mappedMessage`。
|
||||
4. `mvn -DskipTests compile` 通过。
|
||||
5. 关键路径联调用例可跑通：
|
||||
- `getDeviceNumber`
|
||||
- `deviceConfGet`
|
||||
- `hmac`
|
||||
- `generateKek + statusKek`
|
||||
|
||||
## 11. 后续扩展
|
||||
|
||||
1. 第二期覆盖U盾与内部密钥管理。
|
||||
2. 第三期覆盖全量SDF/SDFE并补充结构体严格对齐校验。
|
||||
3. 加入真实设备集成测试与回放测试。
|
||||
Reference in New Issue
Block a user