256 lines
7.8 KiB
Markdown
256 lines
7.8 KiB
Markdown
|
|
# TMS Framework
|
|
|
|
Single-process TMS monolith scaffold built with:
|
|
- JDK 17
|
|
- Spring Boot 3.5.x
|
|
- MyBatis-Plus
|
|
- TiDB (MySQL driver)
|
|
- Swagger (springdoc-openapi)
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
cd tms-framework
|
|
mvn spring-boot:run
|
|
```
|
|
|
|
## Jar Deployment (External Config)
|
|
|
|
1. Build jar:
|
|
|
|
```bash
|
|
cd tms-framework
|
|
mvn -q -DskipTests package
|
|
cp target/tms-framework-*.jar /home/tms/tms-framework.jar
|
|
```
|
|
|
|
2. Prepare deployment directory on CentOS:
|
|
|
|
```bash
|
|
sudo mkdir -p /home/tms/{config,scripts,logs,run}
|
|
sudo chown -R "$(whoami)":"$(whoami)" /home/tms
|
|
cp scripts/tms.sh /home/tms/scripts/tms.sh
|
|
cp config/application.yml.example /home/tms/config/application.yml
|
|
chmod +x /home/tms/scripts/tms.sh
|
|
```
|
|
|
|
3. Start/Stop/Status:
|
|
|
|
```bash
|
|
/home/tms/scripts/tms.sh start
|
|
/home/tms/scripts/tms.sh status
|
|
/home/tms/scripts/tms.sh stop
|
|
```
|
|
|
|
Notes:
|
|
- Script default `APP_HOME=/home/tms`, and loads external config from `/home/tms/config/` via `--spring.config.additional-location=optional:file:<app_home>/config/`.
|
|
- `/home/tms/config/application.yml` is required by default.
|
|
- Default profile is `prod`; override with `SPRING_PROFILES_ACTIVE=dev /home/tms/scripts/tms.sh start`.
|
|
- Override jar path with `JAR_PATH=/home/tms/tms-framework.jar`.
|
|
- If deployment path is not `/home/tms`, use `APP_HOME=/your/path /your/path/scripts/tms.sh start`.
|
|
|
|
Runtime recommendation:
|
|
- Use JDK 17 for local build/test to match project and CI runtime.
|
|
|
|
Open:
|
|
- Swagger UI: http://localhost:8080/swagger-ui.html
|
|
- Internal health API: `GET /api/v1/device/status`
|
|
- Internal sign preview API: `POST /api/v1/sign/preview`
|
|
- External sign API: `POST /openapi/v1/sign/signature`
|
|
- Init template API: `GET /api/v1/init/template`
|
|
- Init preview API: `POST /api/v1/init/preview`
|
|
- Auth login API: `POST /api/v1/auth/login`
|
|
- Device info API: `GET /api/v1/device/info`
|
|
- PCIe crypto count API: `GET /api/v1/device/crypto/device-count`
|
|
- PCIe crypto HMAC API: `POST /api/v1/device/crypto/hmac`
|
|
|
|
## Architecture (Monolith + Modular)
|
|
|
|
- One deployable Spring Boot application.
|
|
- Module-first packaging under `modules/*`.
|
|
- Default module layout: `controller/internal + service + repository + entity + dto`.
|
|
- `sign` module has extra `controller/openapi`, `dto/openapi`, and `support`.
|
|
- Cross-cutting concerns moved to top-level `security` and `integration`.
|
|
|
|
## Project Structure
|
|
|
|
```text
|
|
src/main/java/com/cisd/tms
|
|
├── TmsApplication.java
|
|
├── common
|
|
│ ├── api
|
|
│ ├── config
|
|
│ │ └── properties
|
|
│ ├── constant
|
|
│ ├── enums
|
|
│ ├── exception
|
|
│ └── util
|
|
├── infrastructure
|
|
│ └── persistence
|
|
│ ├── entity
|
|
│ ├── mapper
|
|
│ └── mybatis
|
|
├── integration
|
|
│ ├── cips
|
|
│ ├── mq
|
|
│ ├── crypto
|
|
│ └── file
|
|
├── security
|
|
│ ├── internal
|
|
│ └── openapi
|
|
└── modules
|
|
├── system
|
|
│ ├── controller/internal
|
|
│ ├── service
|
|
│ └── dto
|
|
├── sign
|
|
│ ├── controller/internal
|
|
│ ├── controller/openapi
|
|
│ ├── service
|
|
│ ├── dto/internal
|
|
│ ├── dto/openapi
|
|
│ ├── support
|
|
│ ├── repository
|
|
│ └── entity
|
|
├── init
|
|
├── auth
|
|
├── device
|
|
├── upgrade
|
|
├── cert
|
|
├── key
|
|
├── audit
|
|
├── backup
|
|
└── activation
|
|
```
|
|
|
|
```text
|
|
src/main/resources
|
|
├── application.yml
|
|
├── application-dev.yml
|
|
├── application-prod.yml
|
|
├── mapper
|
|
│ ├── init/InitTaskMapper.xml
|
|
│ ├── auth/AuthUserMapper.xml
|
|
│ └── device/DeviceNodeMapper.xml
|
|
└── db/migration
|
|
└── V1__init_auth_device_tables.sql
|
|
```
|
|
|
|
## API Boundary Rules
|
|
|
|
- Internal API controllers only in `*/controller/internal`, path prefix `/api/**`.
|
|
- External API controllers only in `*/controller/openapi`, path prefix `/openapi/**`.
|
|
- Internal and external DTOs are separated.
|
|
- Cross-module calls must go through `service`, not `repository`.
|
|
- Internal token interceptor exclusions: `/api/v1/device/status`, `/api/v1/auth/login`.
|
|
|
|
## Auth Configuration
|
|
|
|
```yaml
|
|
tms:
|
|
security:
|
|
internal-token: ${TMS_INTERNAL_TOKEN:change-me-internal-token}
|
|
openapi:
|
|
timestamp-skew-seconds: 300
|
|
clients:
|
|
demo-app: ${TMS_OPENAPI_DEMO_SECRET:change-me-openapi-secret}
|
|
```
|
|
|
|
## Crypto Card Configuration
|
|
|
|
```yaml
|
|
tms:
|
|
crypto-card:
|
|
enabled: ${TMS_CRYPTO_CARD_ENABLED:false}
|
|
mode: ${TMS_CRYPTO_CARD_MODE:MOCK} # MOCK / JNA
|
|
vendor-lib-path: ${TMS_CRYPTO_VENDOR_LIB_PATH:}
|
|
vendor-lib-name: ${TMS_CRYPTO_VENDOR_LIB_NAME:swsdsdf}
|
|
```
|
|
|
|
- Internal PCIe debug APIs (strong-typed service):
|
|
- `GET /api/v1/device/crypto/device-count`
|
|
- `GET /api/v1/device/crypto/device-conf`
|
|
- `GET /api/v1/device/crypto/device-info`
|
|
- `GET /api/v1/device/crypto/random?length=16`
|
|
- `POST /api/v1/device/crypto/self-test`
|
|
- `POST /api/v1/device/crypto/hmac`
|
|
- `POST /api/v1/device/crypto/digest`
|
|
- `POST /api/v1/device/crypto/encrypt/plain`
|
|
- `POST /api/v1/device/crypto/decrypt/plain`
|
|
- `POST /api/v1/device/crypto/encrypt/kek`
|
|
- `POST /api/v1/device/crypto/decrypt/kek`
|
|
- `POST /api/v1/device/crypto/mac/plain`
|
|
- `POST /api/v1/device/crypto/file/create`
|
|
- `POST /api/v1/device/crypto/file/write`
|
|
- `POST /api/v1/device/crypto/file/read`
|
|
- `POST /api/v1/device/crypto/file/delete`
|
|
- `POST /api/v1/device/crypto/kek/generate`
|
|
- `GET /api/v1/device/crypto/kek/status?keyIndex=1`
|
|
- `GET /api/v1/device/crypto/lmk/seed-mac`
|
|
- `POST /api/v1/device/crypto/std/keypair/rsa`
|
|
- `POST /api/v1/device/crypto/std/keypair/ecc`
|
|
- `POST /api/v1/device/crypto/envelope/exchange/rsa`
|
|
- `POST /api/v1/device/crypto/envelope/exchange/ecc`
|
|
- `POST /api/v1/device/crypto/agreement/data-key/ecc`
|
|
- `POST /api/v1/device/crypto/agreement/session-key/ecc`
|
|
|
|
## PCIe Crypto Unified Wrapper (JNA)
|
|
|
|
The project keeps JNA native mappings for PCIe card `SDF/SDFE` interfaces from
|
|
`PCIE密码卡应用接口说明书 V1.02`, and provides strong-typed service APIs via
|
|
`com.cisd.tms.integration.crypto.pcie.service.PcieCryptoService`.
|
|
|
|
```yaml
|
|
tms:
|
|
crypto-card:
|
|
enabled: ${TMS_CRYPTO_CARD_ENABLED:false}
|
|
mode: ${TMS_CRYPTO_CARD_MODE:JNA} # MOCK / JNA
|
|
vendor-lib-path: ${TMS_CRYPTO_VENDOR_LIB_PATH:}
|
|
vendor-lib-name: ${TMS_CRYPTO_VENDOR_LIB_NAME:swsdsdf}
|
|
```
|
|
|
|
- JNA native mapping: `com.cisd.tms.integration.crypto.pcie.jna.PcieNativeLibrary`
|
|
- JNA implementation: `com.cisd.tms.integration.crypto.pcie.service.JnaPcieCryptoService`
|
|
- Mock fallback: `com.cisd.tms.integration.crypto.pcie.service.MockPcieCryptoService`
|
|
|
|
### OpenAPI Signature Rules
|
|
|
|
- Headers: `X-App-Id`, `X-Timestamp`, `X-Nonce`, `X-Signature`
|
|
- Canonical string: `appId + "\\n" + timestamp + "\\n" + nonce`
|
|
- Signature algorithm: `HMAC-SHA256` with app secret, lowercase hex
|
|
- Replay protection: nonce one-time in time window
|
|
|
|
## Build And Test
|
|
|
|
```bash
|
|
mvn -q -DskipTests compile
|
|
mvn -q test
|
|
```
|
|
|
|
## PCIe Real-Card Smoke
|
|
|
|
- Checklist: `docs/plans/2026-02-28-pcie-realcard-smoke-checklist.md`
|
|
- Script template: `scripts/pcie_realcard_smoke.sh`
|
|
|
|
Example:
|
|
|
|
```bash
|
|
export BASE_URL=http://127.0.0.1:8080
|
|
export INTERNAL_TOKEN=change-me-internal-token
|
|
export ALG_SM3=1
|
|
export ALG_SM4_ECB=1025
|
|
./scripts/pcie_realcard_smoke.sh
|
|
```
|
|
|
|
- CI is pinned to JDK 17 via `.github/workflows/ci.yml`.
|
|
- Maven Surefire preloads Mockito javaagent to avoid dynamic self-attach failures on newer JDKs.
|
|
|
|
## Current Status
|
|
|
|
- Structure refactored to lightweight monolith modules.
|
|
- Internal and external API entry points separated.
|
|
- Basic auth interceptors for internal/openapi are in place.
|
|
- `init/auth/device/sign/system` modules have runnable skeleton controllers and services.
|
|
- `init/auth/device` modules include mapper+xml+repository-impl+DDL skeleton for TiDB.
|