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

cd tms-framework
mvn spring-boot:run

Jar Deployment (External Config)

1. Build jar:

cd tms-framework
mvn -q -DskipTests package
cp target/tms-framework-*.jar /home/tms/tms-framework.jar

2. Prepare deployment directory on CentOS:

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:

/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

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

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

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

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.

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

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:

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.