cisd/README.md

# 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
```

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
```

- 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.
>>>>>>> aeb6a4d (初始化项目)