From 6b37cb5ccd9c3b22d2316ad4a8bb204e44e86645 Mon Sep 17 00:00:00 2001 From: "hongyuan.zhang" Date: Tue, 11 Aug 2026 22:58:30 +0800 Subject: [PATCH] docs(readme): refresh module documentation --- dc3-api/README.md | 36 ++ dc3-api/dc3-api-auth/README.md | 213 ++------- dc3-api/dc3-api-data/README.md | 281 +----------- dc3-api/dc3-api-driver/README.md | 415 ++---------------- dc3-api/dc3-api-manager/README.md | 196 ++------- dc3-center/README.md | 53 +++ dc3-center/dc3-center-agentic/README.md | 24 +- dc3-center/dc3-center-auth/README.md | 35 +- dc3-center/dc3-center-data/README.md | 50 ++- dc3-center/dc3-center-manager/README.md | 43 +- dc3-center/dc3-center-single/README.md | 29 +- dc3-common/README.md | 60 +++ dc3-common/dc3-common-agentic/README.md | 17 +- dc3-common/dc3-common-api/README.md | 19 +- dc3-common/dc3-common-auth/README.md | 36 +- dc3-common/dc3-common-constant/README.md | 58 +-- dc3-common/dc3-common-dal/README.md | 19 +- dc3-common/dc3-common-data/README.md | 53 ++- dc3-common/dc3-common-driver/README.md | 37 +- dc3-common/dc3-common-exception/README.md | 28 +- dc3-common/dc3-common-facade/README.md | 29 ++ .../dc3-common-facade-api/README.md | 18 +- .../dc3-common-facade-grpc/README.md | 18 +- .../dc3-common-facade-local-auth/README.md | 17 +- .../dc3-common-facade-local-data/README.md | 17 +- .../dc3-common-facade-local-manager/README.md | 17 +- .../dc3-common-facade-local/README.md | 30 ++ dc3-common/dc3-common-gateway/README.md | 21 +- dc3-common/dc3-common-log/README.md | 52 +-- dc3-common/dc3-common-manager/README.md | 20 +- dc3-common/dc3-common-model/README.md | 46 +- dc3-common/dc3-common-mqtt/README.md | 20 +- dc3-common/dc3-common-postgres/README.md | 17 +- dc3-common/dc3-common-public/README.md | 29 +- dc3-common/dc3-common-quartz/README.md | 17 +- dc3-common/dc3-common-rabbitmq/README.md | 54 ++- dc3-common/dc3-common-repository/README.md | 19 +- .../dc3-common-resource-registrar/README.md | 17 +- dc3-common/dc3-common-sql/README.md | 17 +- dc3-common/dc3-common-test/README.md | 20 +- dc3-common/dc3-common-thread/README.md | 22 +- dc3-common/dc3-common-web/README.md | 31 +- dc3-coverage/README.md | 38 ++ dc3-driver/README.md | 47 ++ dc3-driver/dc3-driver-bacnet-ip/README.md | 24 +- dc3-driver/dc3-driver-ble/README.md | 24 +- dc3-driver/dc3-driver-can/README.md | 24 +- dc3-driver/dc3-driver-coap/README.md | 24 +- dc3-driver/dc3-driver-dlms/README.md | 24 +- dc3-driver/dc3-driver-ethernet-ip/README.md | 24 +- dc3-driver/dc3-driver-fins/README.md | 24 +- dc3-driver/dc3-driver-http/README.md | 24 +- dc3-driver/dc3-driver-iec104/README.md | 24 +- .../dc3-driver-listening-virtual/README.md | 24 +- dc3-driver/dc3-driver-lwm2m/README.md | 24 +- dc3-driver/dc3-driver-melsec/README.md | 24 +- dc3-driver/dc3-driver-modbus-rtu/README.md | 24 +- dc3-driver/dc3-driver-modbus-tcp/README.md | 24 +- dc3-driver/dc3-driver-mqtt/README.md | 26 +- dc3-driver/dc3-driver-mysql/README.md | 24 +- dc3-driver/dc3-driver-opc-da/README.md | 28 +- dc3-driver/dc3-driver-opc-ua/README.md | 24 +- dc3-driver/dc3-driver-oracle/README.md | 24 +- dc3-driver/dc3-driver-plcs7/README.md | 24 +- dc3-driver/dc3-driver-postgresql/README.md | 24 +- dc3-driver/dc3-driver-serial/README.md | 24 +- dc3-driver/dc3-driver-sl651/README.md | 24 +- dc3-driver/dc3-driver-snmp/README.md | 24 +- dc3-driver/dc3-driver-sqlserver/README.md | 24 +- dc3-driver/dc3-driver-tcp-udp/README.md | 24 +- dc3-driver/dc3-driver-virtual/README.md | 24 +- dc3-driver/dc3-driver-zigbee/README.md | 24 +- dc3-e2e/README.md | 10 +- dc3-gateway/README.md | 22 +- dc3-web/README.md | 59 ++- 75 files changed, 1360 insertions(+), 1744 deletions(-) create mode 100644 dc3-api/README.md create mode 100644 dc3-center/README.md create mode 100644 dc3-common/README.md create mode 100644 dc3-common/dc3-common-facade/README.md create mode 100644 dc3-common/dc3-common-facade/dc3-common-facade-local/README.md create mode 100644 dc3-coverage/README.md create mode 100644 dc3-driver/README.md diff --git a/dc3-api/README.md b/dc3-api/README.md new file mode 100644 index 000000000..a1261a32f --- /dev/null +++ b/dc3-api/README.md @@ -0,0 +1,36 @@ +# DC3 API + +`dc3-api` owns the protobuf contracts shared between IoT DC3 processes. It contains generated-contract modules only; +business logic belongs in `dc3-common-*` implementations. + +## Modules + +| Module | Contract surface | Primary consumers | +|---|---|---| +| `dc3-api-auth` | tenant, user, token, permission, resource registry, MCP runtime | gateway and center services | +| `dc3-api-data` | point values, command history, event history | manager, drivers, and data clients | +| `dc3-api-driver` | driver registration and driver-scoped device/point metadata | protocol drivers | +| `dc3-api-manager` | manager-scoped driver, device, profile, point, command, and event metadata | data and other centers | + +Proto sources live under each module's `src/main/protobuf/` directory. Generated Java sources are build artifacts and +must not be edited directly. + +## Contract changes + +1. Update the affected `.proto` files. +2. Preserve field numbers and RPC compatibility where practical. +3. Compile the affected module to regenerate Java sources. +4. Update server implementations, builders, and clients together. +5. Verify tenant propagation, `GrpcR` error handling, and single/list cardinality naming. + +```bash +mvn -s .mvn/settings.xml -q -f dc3-api/pom.xml compile +``` + +Use `GetXxx` for single results and `ListXxx` for collections, pages, or maps. Do not reintroduce legacy `SelectXxx` +RPC names. + +## Documentation ownership + +Each child README documents its current services and messages. The `.proto` files remain the authoritative source for +method names, request/response types, and field definitions. diff --git a/dc3-api/dc3-api-auth/README.md b/dc3-api/dc3-api-auth/README.md index e16cbc0e0..e132ba0b9 100644 --- a/dc3-api/dc3-api-auth/README.md +++ b/dc3-api/dc3-api-auth/README.md @@ -1,202 +1,41 @@ # DC3 API Auth -## Overview +`dc3-api-auth` defines the authentication and authorization gRPC contracts. Generated Java types use the +`io.github.pnoker.api.center.auth` package; proto sources live under `src/main/protobuf/api/common/auth/`. -`dc3-api-auth` provides gRPC service definitions for authentication and authorization in the IoT DC3 platform. It -defines the interfaces for tenant management, user authentication, token validation, and local credential lookup. +## Services -## Module Information +| Service | RPCs | Purpose | +|---|---|---| +| `TenantApi` | `GetByCode` | resolve tenant metadata | +| `UserApi` | `GetById`, `GetByPrincipalId` | resolve user identity | +| `TokenApi` | `CheckValid` | validate login/token material | +| `LocalCredentialApi` | `GetByLoginName` | resolve local credentials | +| `PermissionApi` | `ListPermissionCodes` | resolve effective permission codes | +| `ResourceRegistryApi` | `Sync` | synchronize annotated API/menu resources | +| `McpRuntimeApi` | `Introspect`, `ListTools`, `ResolveTool`, `AuthorizeToolCall`, `Audit` | authorize and audit MCP tools | -- **Group ID**: io.github.pnoker -- **Artifact ID**: dc3-api-auth -- **Version**: 2026.5.22 -- **Package**: `io.github.pnoker.api.center.auth` +Every response uses a contract-specific wrapper containing `GrpcR`. Callers must inspect the result envelope before +reading response data. -## Proto Definitions +## Consumers and implementation -### tenant.proto +- `dc3-common-auth` implements the servers as Spring `@Service` beans extending generated `*ImplBase` classes. +- `dc3-common-facade-grpc` creates shared blocking stubs and exposes transport-independent auth facades. +- `dc3-gateway` uses auth facades for ingress authentication and authorization. -Defines tenant-related RPC calls and data structures. +Business code should depend on facade interfaces instead of generated stubs unless it is itself a transport adapter. -**Service**: `TenantApi` +## Build and Verification -- `GetByCode` - Query tenant information by tenant code - -**Key Messages**: - -- `GrpcCodeQuery` - Request wrapper for tenant code queries -- `GrpcRTenantDTO` - Response wrapper containing tenant information -- `GrpcTenantDTO` - Tenant data structure (name, code, enable flag) - -### token.proto - -Defines token validation RPC calls and data structures. - -**Service**: `TokenApi` - -- `CheckValid` - Validate authentication tokens - -**Key Messages**: - -- `GrpcLoginQuery` - Request wrapper with login credentials (tenant, name, password, token) -- `GrpcRTokenDTO` - Response wrapper with validation result - -### user.proto - -Defines user-related RPC calls and data structures. - -**Service**: `UserApi` - -- `GetById` - Query user information by user ID -- `GetByPrincipalId` - Query user information by principal ID - -**Key Messages**: - -- `GrpcIdQuery` - Request wrapper for user ID queries -- `GrpcRUserDTO` - Response wrapper containing user information -- `GrpcUserDTO` - User data structure (nickname, username, phone, email) - -### local_credential.proto - -Defines local credential lookup RPC calls and data structures. - -**Service**: `LocalCredentialApi` - -- `GetByLoginName` - Query local credential information by login name - -**Key Messages**: - -- `GrpcLoginNameQuery` - Request wrapper for login-name queries -- `GrpcRLocalCredentialDTO` - Response wrapper containing local credential information -- `GrpcLocalCredentialDTO` - Local credential data structure (login name, principal ID) - -### permission.proto - -Defines permission lookup RPC calls for RBAC. - -**Service**: `PermissionApi` - -- `ListPermissionCodes` - List the permission codes granted to a principal - -### resource_registry.proto - -Defines resource registry synchronization RPC calls. - -**Service**: `ResourceRegistryApi` - -- `Sync` - Synchronize API/menu resource definitions into the registry - -### mcp_runtime.proto - -Defines MCP (Model Context Protocol) runtime RPC calls for AI tool integration. - -**Service**: `McpRuntimeApi` - -- `Introspect` - Introspect an MCP connection -- `ListTools` - List the tools exposed by an MCP connection -- `ResolveTool` - Resolve a tool definition by name -- `AuthorizeToolCall` - Authorize an MCP tool invocation -- `Audit` - Record an MCP tool-call audit entry - -## Dependencies - -This module depends on common proto definitions: - -- `api/common/base.proto` - Base entity fields (ID, timestamps) -- `api/common/r.proto` - Common response wrapper - -## Usage - -### 1. Add Dependency - -```xml - - - io.github.pnoker - dc3-api-auth - 2026.5.22 - -``` - -### 2. Import Proto Files - -```protobuf -import "api/center/auth/tenant.proto"; -import "api/center/auth/token.proto"; -import "api/center/auth/user.proto"; -import "api/center/auth/local_credential.proto"; -``` - -### 3. Implement Service - -```java -public class TenantServiceImpl extends TenantApiGrpc.TenantApiImplBase { - @Override - public void getByCode(GrpcCodeQuery request, - StreamObserver responseObserver) { - // Implementation - } -} -``` - -## API Features - -### Multi-Tenancy Support - -- Tenant isolation through tenant codes -- Tenant-scoped user management -- Cross-tenant operations support - -### Authentication Flow - -1. Client queries tenant by code -2. Local credential lookup via `LocalCredentialApi` -3. Token validation via `TokenApi` -4. User information retrieval by principal via `UserApi` - -### Security Features - -- Server-side password hashing -- Token-based authentication -- User credential management -- Login tracking with principal IDs - -## Data Models - -### Tenant Model - -- **tenant_name**: Display name of the tenant -- **tenant_code**: Unique tenant identifier -- **enable_flag**: Active/inactive status (1=enabled, 0=disabled) - -### User Model - -- **nick_name**: Display name -- **user_name**: Unique username -- **phone**: Contact phone number -- **email**: Email address -- **social_ext**: Encrypted social account information -- **identity_ext**: Encrypted identity verification data - -### Login Lookup Model - -- **login_name**: Username for authentication -- **user_id**: Reference to user entity -- **principal_id**: Reference to unified auth principal -- **enable_flag**: Account status - -## Build Instructions +Run from the repository root: ```bash -# Build the module -mvn -s ../../.mvn/settings.xml clean package - -# Install to local repository -mvn -s ../../.mvn/settings.xml clean install +mvn -s .mvn/settings.xml -q -pl dc3-api/dc3-api-auth -am compile ``` -## License +This module has no handwritten runtime code or module-specific tests. A successful compile verifies proto syntax and +generated Java sources; server/facade behaviour is tested in the implementing modules. -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) +When changing the contract, preserve field numbers, update implementations and clients together, and verify that +tenant and authorization context remain explicit. diff --git a/dc3-api/dc3-api-data/README.md b/dc3-api/dc3-api-data/README.md index 5f7b42761..619f058bd 100644 --- a/dc3-api/dc3-api-data/README.md +++ b/dc3-api/dc3-api-data/README.md @@ -1,273 +1,34 @@ # DC3 API Data -## Overview +`dc3-api-data` defines gRPC contracts for values, commands, events, status, and system-health queries. Generated Java +types use `io.github.pnoker.api.center.data`; proto sources live under `src/main/protobuf/api/common/data/`. -`dc3-api-data` provides gRPC service definitions for device data collection and management in the IoT DC3 platform. It -defines interfaces for querying real-time device point values and historical data retrieval. +## Services -## Module Information +| Service | RPCs | Purpose | +|---|---|---| +| `PointValueApi` | `GetLastValue`, `ListHistoryValues` | query point values | +| `PointValueApi` | `ReadCommand`, `WriteCommand` | submit point read/write commands | +| `CommandHistoryApi` | `CallCommand`, `GetByRecordId`, `ListByPage` | dispatch and query command history | +| `EventHistoryApi` | `ReportEvent`, `GetByRecordId`, `ListByPage` | report and query event history | +| `StatusHealthApi` | device/driver status and system-health RPCs | expose status snapshots and summaries | -- **Group ID**: io.github.pnoker -- **Artifact ID**: dc3-api-data -- **Version**: 2026.5.22 -- **Package**: `io.github.pnoker.api.center.data` +Single-result RPCs use `GetXxx`; collection/page results use `ListXxx` or an explicitly named status aggregation. Do +not reintroduce legacy `SelectXxx` names. -## Proto Definitions +## Consumers and implementation -### point_value.proto +- `dc3-common-data` implements the data-side servers. +- `dc3-common-facade-grpc` wraps generated stubs in transport-independent facades. +- Manager and other business modules should call the facade API rather than construct channels directly. -Defines point value query RPC calls and data structures for device data collection. +All write/report requests must carry tenant context through the transport and into the business layer. -**Service**: `PointValueApi` - -- `GetLastValue` - Query the latest collected value of a device point -- `ListHistoryValues` - Query historical values of a device point -- `ReadCommand` - Trigger a read command for a device point -- `WriteCommand` - Trigger a write command for a device point - -**Key Messages**: - -- `GrpcPointValueQuery` - Request wrapper for point value queries (device_id, point_id, tenant_id) -- `GrpcRPointValueDTO` - Response wrapper containing point value information -- `GrpcPointValueDTO` - Point value data structure - -### event_history.proto - -Defines device event history RPC calls. - -**Service**: `EventHistoryApi` - -- `ReportEvent` - Report a device event -- `GetByRecordId` - Query an event history record by record ID -- `ListByPage` - Query event history with pagination support - -### command_history.proto - -Defines device command history RPC calls. - -**Service**: `CommandHistoryApi` - -- `CallCommand` - Issue a command to a device -- `GetByRecordId` - Query a command history record by record ID -- `ListByPage` - Query command history with pagination support - -### status_health.proto - -Defines device/driver status and system health RPC calls. - -**Service**: `StatusHealthApi` - -- `DeviceStatusesByIds` - Query device statuses by device IDs -- `DeviceStatusesByProfileId` - Query device statuses by profile ID -- `DriverStatusesByIds` - Query driver statuses by driver IDs -- `DriverDeviceStatusSummary` - Summarize device statuses under a driver -- `SystemHealth` - Query overall system health - -## Data Models - -### Point Value Model - -The `GrpcPointValueDTO` represents collected data from device points: - -```protobuf -message GrpcPointValueDTO { - int64 id = 1; // Point value record ID - int64 device_id = 2; // Source device identifier - int64 point_id = 3; // Point identifier - string value = 4; // Processed/converted value - string raw_value = 5; // Raw value from device - int64 create_time = 6; // Storage timestamp -} -``` - -### Field Descriptions - -| Field | Type | Description | -|---------------|--------|------------------------------------------------------| -| `id` | int64 | Unique identifier for the point value record | -| `device_id` | int64 | ID of the device that generated the data | -| `point_id` | int64 | ID of the point (tag) within the device | -| `value` | string | Processed value after data conversion and formatting | -| `raw_value` | string | Original raw value collected from the device | -| `create_time` | int64 | Unix timestamp when data was stored (milliseconds) | - -## Dependencies - -This module depends on common proto definitions: - -- `api/common/r.proto` - Common response wrapper (GrpcR) - -## Usage - -### 1. Add Dependency - -```xml - - - io.github.pnoker - dc3-api-data - 2026.5.22 - -``` - -### 2. Import Proto Files - -```protobuf -import "api/center/data/point_value.proto"; -``` - -### 3. Implement Service - -```java -public class PointValueServiceImpl extends PointValueApiGrpc.PointValueApiImplBase { - @Override - public void getLastValue(GrpcPointValueQuery request, - StreamObserver responseObserver) { - // Query latest point value from database - // Return GrpcRPointValueDTO with point value data - } -} -``` - -### 4. Query Example - -```java -// Build query request -GrpcPointValueQuery query = GrpcPointValueQuery.newBuilder() - .setDeviceId(12345L) - .setPointId(67890L) - .setTenantId(1L) - .build(); - -// Call service -GrpcRPointValueDTO response = pointValueApi.getLastValue(query); - -// Extract data -if(response. - -getResult(). - -getOk()){ -GrpcPointValueDTO pointValue = response.getData(); -String value = pointValue.getValue(); -String rawValue = pointValue.getRawValue(); -long timestamp = pointValue.getCreateTime(); -} -``` - -## API Features - -### Real-Time Data Access - -- Query latest point values by device and point IDs -- Support for both raw and processed values -- Tenant-scoped data access - -### Data Processing - -- **Raw Value**: Original data read from the device without processing -- **Processed Value**: Converted and formatted value after applying: - - Unit conversion - - Scale factors - - Precision formatting - - Data type conversion - -### Data Flow - -``` -Device → Driver → Data Collection → Time Series DB → PointValueApi -``` - -## Use Cases - -### 1. Real-Time Monitoring - -```java -// Monitor device point value in real-time -GrpcPointValueDTO latestValue = getLastValue(deviceId, pointId); - -displayValue(latestValue.getValue()); -``` - -### 2. Data Analysis - -```java -// Compare raw vs processed values -String raw = pointValue.getRawValue(); -String processed = pointValue.getValue(); - -analyzeConversion(raw, processed); -``` - -### 3. Time Series Operations - -```java -// Use timestamp for time-based queries -long timestamp = pointValue.getCreateTime(); -Date collectionTime = new Date(timestamp); -``` - -## Performance Considerations - -- **Query Optimization**: Always include tenant_id for proper data isolation -- **Caching**: Consider caching recent point values for high-frequency queries -- **Time Series Store**: This API queries the time-series store through `dc3-common-repository` (PostgreSQL with the - TimescaleDB extension) -- **Data Volume**: Point value queries can generate high traffic in large-scale deployments - -## Integration Points - -### Driver Services - -Drivers write point values to the data layer: - -``` -Driver Service → Device SDK → Point Collection → Data Store -``` - -### Manager Service - -Manager service provides device/point metadata: - -``` -PointValueApi → ManagerApi (get point info) → Return value with metadata -``` - -### Application Layer - -Upper applications consume point value data for: - -- Real-time dashboards -- Data analytics -- Alarm monitoring -- Historical data queries - -## Data Retention - -Point values are typically stored in time-series databases with: - -- **High-frequency data**: Raw values for immediate processing -- **Aggregated data**: Processed values for long-term storage -- **Retention policies**: Configurable by tenant or device type - -## Build Instructions +## Build and Verification ```bash -# Build the module -mvn -s ../../.mvn/settings.xml clean package - -# Install to local repository -mvn -s ../../.mvn/settings.xml clean install +mvn -s .mvn/settings.xml -q -pl dc3-api/dc3-api-data -am compile ``` -## Related Modules - -- `dc3-api-driver` - Driver interface for point data collection -- `dc3-api-manager` - Device and point metadata management -- `dc3-common-data` - Data models and DTOs - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) +This contract module has no module-specific tests. Compile it after proto changes, then run the matching server and +facade tests in `dc3-common-data` and `dc3-common-facade-grpc`. diff --git a/dc3-api/dc3-api-driver/README.md b/dc3-api/dc3-api-driver/README.md index 0c20e535d..a3bc59303 100644 --- a/dc3-api/dc3-api-driver/README.md +++ b/dc3-api/dc3-api-driver/README.md @@ -1,400 +1,55 @@ # DC3 API Driver -## Overview +`dc3-api-driver` defines the gRPC contract used by protocol drivers to register with the Manager Center and retrieve +driver-scoped device and point configuration. Generated Java types use `io.github.pnoker.api.common.driver`. -`dc3-api-driver` provides gRPC service definitions for driver services in the IoT DC3 platform. It defines the -communication interface between device drivers and the platform's manager service, enabling device registration, -metadata synchronization, and point value collection. +## Services -## Module Information +| Service | RPC | Response | Purpose | +|---|---|---|---| +| `DriverApi` | `DriverRegister` | `GrpcRDriverRegisterDTO` | register metadata and receive assigned configuration | +| `DriverApi` | `GetById` | `GrpcRDriverRegisterDTO` | reload registered driver metadata | +| `DeviceApi` | `ListByPage` | `GrpcRPageDeviceDTO` | page through driver-owned devices | +| `DeviceApi` | `GetById` | `GrpcRDeviceDTO` | get one device with attached attribute configuration | +| `PointApi` | `ListByPage` | `GrpcRPagePointDTO` | page through driver-visible points | +| `PointApi` | `GetById` | `GrpcRPointDTO` | get one point with attached configuration | -- **Group ID**: io.github.pnoker -- **Artifact ID**: dc3-api-driver -- **Version**: 2026.5.22 -- **Package**: `io.github.pnoker.api.common.driver` +Proto sources live under `src/main/protobuf/api/common/driver/`. The `.proto` files are authoritative for fields and +wrapper shapes. -## Proto Definitions +## Registration flow -### driver_driver.proto +1. `dc3-common-driver` builds `GrpcDriverRegisterDTO` from the driver's `application.yml` metadata. +2. The driver calls `DriverApi.DriverRegister` on the Manager Center. +3. The response supplies driver metadata, device IDs, and supported driver/point/command/event attributes. +4. `DeviceClient` and `PointClient` load attached configuration with `GetById` or `ListByPage`. +5. The SDK initializes protocol scheduling, metadata subscriptions, commands, and value dispatch. -Defines driver registration RPC calls and data structures. - -**Service**: `DriverApi` - -- `DriverRegister` - Register a driver instance with the platform (used by drivers on startup) -- `GetById` - Query driver registration information by driver ID - -**Key Messages**: - -- `GrpcDriverRegisterDTO` - Driver registration request information -- `GrpcRDriverRegisterDTO` - Driver registration response with configuration data - -### driver_device.proto - -Defines device-related RPC calls for driver services. - -**Service**: `DeviceApi` - -- `ListByPage` - Query devices with pagination support -- `GetById` - Query device by device ID - -**Key Messages**: - -- `GrpcPageDeviceQuery` - Paginated device query request -- `GrpcDeviceQuery` - Single device query request -- `GrpcRPageDeviceDTO` - Paginated device list response -- `GrpcRDeviceDTO` - Single device response -- `GrpcRDeviceAttachDTO` - Device with full configuration (device + points + attributes) - -### driver_point.proto - -Defines point-related RPC calls for driver services. - -**Service**: `PointApi` - -- `ListByPage` - Query points with pagination support -- `GetById` - Query point by point ID - -**Key Messages**: - -- `GrpcPagePointQuery` - Paginated point query request -- `GrpcPointQuery` - Single point query request -- `GrpcRPagePointDTO` - Paginated point list response -- `GrpcRPointDTO` - Single point response - -### driver_entity.proto - -Defines driver entity structures used during registration. - -**Key Messages**: - -- `GrpcDriverRegisterDTO` - Complete driver registration information including: - - Tenant identification - - Driver client name (service instance identifier) - - Driver metadata (GrpcDriverDTO) - - Driver attribute definitions - - Point attribute definitions - -### driver_query.proto - -Defines query structures for driver services. - -**Key Messages**: - -- `GrpcDriverQuery` - Driver query by driver_id -- `GrpcDeviceQuery` - Device query by driver_id and device_id -- `GrpcPointQuery` - Point query by driver_id and point_id - -### driver_query_page.proto - -Defines paginated query structures for driver services. - -**Key Messages**: - -- `GrpcPageDeviceQuery` - Paginated device query with filters (tenant, driver, device) -- `GrpcPagePointQuery` - Paginated point query with filters (tenant, driver, device, profile) - -## Dependencies - -This module depends on common proto definitions: - -- `api/common/entity.proto` - Common entity definitions (Driver, Device, Point, Attributes) -- `api/common/page.proto` - Pagination support -- `api/common/r.proto` - Common response wrapper - -## Usage - -### 1. Add Dependency - -```xml - - - io.github.pnoker - dc3-api-driver - 2026.5.22 - -``` - -### 2. Driver Registration Flow - -```protobuf -// 1. Driver builds registration request - GrpcDriverRegisterDTO registerRequest = GrpcDriverRegisterDTO.newBuilder() - .setTenant("default") - .setClient("modbus-tcp-driver-001") - .setDriver(driverInfo) - .addAllDriverAttributes(driverAttributes) - .addAllPointAttributes(pointAttributes) - .build(); - -// 2. Call registration service - GrpcRDriverRegisterDTO response = driverApi.driverRegister(registerRequest); - -// 3. Extract configuration from response - GrpcDriverDTO driver = response.getDriver(); - List deviceIds = response.getDeviceIdsList(); - List driverAttrs = response.getDriverAttributesList(); - List pointAttrs = response.getPointAttributesList(); - -// 4. Load device configurations - for (Long deviceId : deviceIds) { -GrpcDeviceQuery query = GrpcDeviceQuery.newBuilder() - .setDriverId(driver.getId()) - .setDeviceId(deviceId) - .build(); - GrpcRDeviceDTO deviceResponse = deviceApi.getById(query); -// Process device configuration - } -``` - -### 3. Query Device Configuration +## Response handling example ```java -// Query device with full configuration -GrpcRDeviceAttachDTO deviceAttach = deviceApi.getById(deviceQuery); - -// Extract device information -GrpcDeviceDTO device = deviceAttach.getDevice(); -List pointIds = deviceAttach.getPointIdsList(); -List driverConfigs = deviceAttach.getDriverConfigsList(); -List pointConfigs = deviceAttach.getPointConfigsList(); - -// Initialize device connection -initializeDevice(device, driverConfigs, pointConfigs); -``` - -### 4. Query Point Configuration - -```java -// Query point by ID -GrpcPointQuery pointQuery = GrpcPointQuery.newBuilder() - .setDriverId(driverId) - .setPointId(pointId) - .build(); - -GrpcRPointDTO pointResponse = pointApi.getById(pointQuery); -GrpcPointDTO point = pointResponse.getData(); - -// Configure point reading -configurePoint(point); -``` - -## Driver Service Lifecycle - -### 1. Startup Phase - -``` -Driver Service Start - ↓ -Build GrpcDriverRegisterDTO - ↓ -Call DriverApi.driverRegister() - ↓ -Receive Driver Configuration - ↓ -Load Device Configurations - ↓ -Load Point Configurations - ↓ -Initialize Device Connections - ↓ -Ready for Data Collection -``` - -### 2. Runtime Phase - -``` -Periodic Data Collection - ↓ -Read Point Values from Device - ↓ -Convert and Format Values - ↓ -Send to Data Center - ↓ -Repeat -``` - -### 3. Shutdown Phase - -``` -Driver Service Stop - ↓ -Close Device Connections - ↓ -Unregister from Manager - ↓ -Cleanup Resources -``` - -## Data Models - -### Driver Metadata (GrpcDriverDTO) - -- **driver_name**: Display name -- **driver_code**: Unique identifier -- **service_name**: Driver service type -- **service_host**: Deployment location -- **driver_type_flag**: Driver type (e.g., virtual, modbus, opc-ua) -- **driver_ext**: Extended configuration (JSON) -- **enable_flag**: Active status -- **signature**: Driver signature for validation -- **version**: Configuration version - -### Device Metadata (GrpcDeviceDTO) - -- **device_name**: Display name -- **device_code**: Unique identifier -- **driver_id**: Associated driver -- **device_ext**: Extended configuration (JSON) -- **enable_flag**: Active status -- **signature**: Device signature -- **version**: Configuration version - -### Point Metadata (GrpcPointDTO) - -- **point_name**: Display name -- **point_code**: Unique identifier -- **point_type_flag**: Data type (digital, analog, string) -- **rw_flag**: Read/write permission -- **base_value**: Base value for conversion -- **multiple**: Scale factor -- **value_decimal**: Precision -- **unit**: Measurement unit -- **profile_id**: Associated profile template - -### Attribute Configuration - -Drivers and points can have configurable attributes: - -- **Driver Attributes**: Driver-level configuration (e.g., connection settings) -- **Point Attributes**: Point-level configuration (e.g., register address) - -Attributes support: - -- Type specification (string, number, boolean) -- Default values -- Per-device configuration overrides -- Dynamic configuration updates - -## API Features - -### Multi-Tenancy Support - -- Tenant-scoped driver registration -- Tenant-isolated device and point queries -- Cross-tenant operation prevention - -### Configuration Synchronization - -- Automatic configuration distribution on registration -- Version-based configuration updates -- Signature-based change detection - -### Extensibility - -- Custom driver types via driver_type_flag -- Extended configuration via *_ext fields -- Custom attribute definitions - -### Query Optimization - -- Pagination support for large device/point lists -- Driver-scoped queries for performance -- Profile-based filtering for template queries - -## Integration Points - -### Driver Implementation - -```java -// Driver service implements DriverApi for registration -public class ModbusTcpDriverService { - private final DriverApiGrpc.DriverApiBlockingStub driverApi; - private final DeviceApiGrpc.DeviceApiBlockingStub deviceApi; - private final PointApiGrpc.PointApiBlockingStub pointApi; - - public void start() { - // Register driver - registerDriver(); - - // Load configurations - loadDeviceConfigurations(); - - // Start data collection - startDataCollection(); - } +GrpcRDeviceDTO response = deviceApiBlockingStub.getById(deviceQuery); +if (!response.getResult().getOk()) { + throw new IllegalStateException(response.getResult().getMessage()); } +GrpcRDeviceAttachDTO attachment = response.getData(); +GrpcDeviceDTO device = attachment.getDevice(); ``` -### Manager Service +`DeviceApi.GetById` returns `GrpcRDeviceDTO`; `GrpcRDeviceAttachDTO` is its `data` field, not the RPC's top-level return +type. -Manager service implements these APIs to provide: +## Implementation -- Driver registration handling -- Device metadata management -- Point metadata management -- Configuration distribution +The Manager Center implements these services. Drivers are clients; they do not implement `DriverApi` themselves. +`dc3-common-driver` creates shared stubs through `DriverClientStubConfig` and exposes higher-level clients to driver +implementations. -### Data Collection - -``` -Driver Device SDK → Read Device → Convert Data → Send to Data Center -``` - -## Communication Pattern - -### Synchronous Queries - -- Configuration queries (device, point) -- Registration operations - -### Asynchronous Events - -- Device connection status updates -- Point value changes (via message queue) -- Configuration change notifications - -## Error Handling - -### Registration Failures - -- Invalid tenant -- Duplicate driver instance -- Missing required attributes - -### Query Failures - -- Device not found -- Point not found -- Permission denied -- Driver not registered - -## Performance Considerations - -- **Connection Pooling**: Reuse gRPC channels for manager communication -- **Configuration Caching**: Cache device/point configurations locally -- **Batch Queries**: Use pagination queries for loading multiple devices/points -- **Lazy Loading**: Load device configurations on-demand - -## Build Instructions +## Build and Verification ```bash -# Build the module -mvn -s ../../.mvn/settings.xml clean package - -# Install to local repository -mvn -s ../../.mvn/settings.xml clean install +mvn -s .mvn/settings.xml -q -pl dc3-api/dc3-api-driver -am compile ``` -## Related Modules - -- `dc3-api-manager` - Manager service API for device/driver/point management -- `dc3-api-data` - Data service API for point value storage -- `dc3-common-driver` - Driver framework SDK - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) +After a contract change, run the matching gRPC server/client tests in `dc3-common-manager` and `dc3-common-driver`. +Preserve field numbers and tenant context when evolving registration or query messages. diff --git a/dc3-api/dc3-api-manager/README.md b/dc3-api/dc3-api-manager/README.md index 65f1ba4f3..7bc2f4513 100644 --- a/dc3-api/dc3-api-manager/README.md +++ b/dc3-api/dc3-api-manager/README.md @@ -1,186 +1,50 @@ # DC3 API Manager -## Overview +`dc3-api-manager` defines Manager Center gRPC contracts for metadata lookups used by distributed facades and other +services. Generated Java types use `io.github.pnoker.api.center.manager`. -`dc3-api-manager` provides gRPC service definitions for the Manager Center in the IoT DC3 platform. It defines the -interfaces used by the Data service and other consumers to query driver, device, point, profile, command, and event -metadata from the Manager Center. +## Services -## Module Information +| Service | Single-result RPCs | Collection/page RPCs | +|---|---|---| +| `DriverApi` | `GetByDriverId`, `GetByDeviceId` | `ListByPage`, `ListByDriverIds` | +| `DeviceApi` | `GetByDeviceId` | `ListByPage`, `ListByProfileId`, `ListByDriverId`, `ListByDeviceIds` | +| `PointApi` | `GetById` | `ListByPage`, `ListByIds` | +| `ProfileApi` | `GetByProfileId` | `ListByPage`, `ListByProfileIds`, `ListByDeviceId` | +| `CommandApi` | `GetById` | `ListByPage`, `ListByIds` | +| `EventApi` | `GetById` | `ListByPage`, `ListByIds` | -- **Group ID**: io.github.pnoker -- **Artifact ID**: dc3-api-manager -- **Version**: 2026.5.22 -- **Package**: `io.github.pnoker.api.center.manager` +Proto sources live under `src/main/protobuf/api/common/manager/`. Shared query and page messages are defined in +`manager_query.proto` and `manager_query_page.proto`. -## Proto Definitions +## Usage boundary -### manager_driver.proto +Business services should inject facade interfaces such as `DriverFacade`, `DeviceFacade`, or `PointFacade` from +`dc3-common-facade-api`. The distributed implementation in `dc3-common-facade-grpc` owns generated blocking stubs, +channel selection, error-envelope handling, and BO conversion. -Defines driver-related RPC calls from the manager perspective. - -**Service**: `DriverApi` - -- `ListByPage` - Query drivers with pagination support -- `GetByDriverId` - Query driver information by driver ID -- `ListByDriverIds` - Query drivers by a list of driver IDs -- `GetByDeviceId` - Query driver information by device ID - -**Key Messages**: - -- `GrpcPageDriverQuery` - Paginated driver query request -- `GrpcDriverQuery` - Driver query by driver ID / device ID -- `GrpcDriverIdsQuery` - Driver query by a list of driver IDs -- `GrpcRDriverDTO` - Response wrapper containing driver information -- `GrpcRPageDriverDTO` / `GrpcRDriverListDTO` - Paginated / list responses -- `GrpcDriverDTO` - Driver data structure (service name, driver type, host, etc.) - -### manager_device.proto - -Defines device-related RPC calls from the manager perspective. - -**Service**: `DeviceApi` - -- `ListByPage` - Query devices with pagination support -- `ListByProfileId` - Query devices by profile ID -- `ListByDriverId` - Query devices by driver ID -- `GetByDeviceId` - Query device information by device ID -- `ListByDeviceIds` - Query devices by a list of device IDs - -**Key Messages**: - -- `GrpcPageDeviceQuery` - Paginated device query request -- `GrpcDeviceQuery` - Single device query -- `GrpcDeviceIdsQuery` - Device query by a list of device IDs -- `GrpcRDeviceDTO` / `GrpcRPageDeviceDTO` / `GrpcRDeviceListDTO` - Single / paginated / list responses - -### manager_point.proto - -Defines point-related RPC calls from the manager perspective. - -**Service**: `PointApi` - -- `ListByPage` - Query points with pagination support -- `GetById` - Query point information by point ID -- `ListByIds` - Query points by a list of point IDs - -**Key Messages**: - -- `GrpcPagePointQuery` - Paginated point query request -- `GrpcPointQuery` - Single point query -- `GrpcPointIdsQuery` - Point query by a list of point IDs -- `GrpcRPointDTO` / `GrpcRPagePointDTO` / `GrpcRPointListDTO` - Single / paginated / list responses - -### manager_command.proto - -Defines command-related RPC calls from the manager perspective. - -**Service**: `CommandApi` - -- `ListByPage` - Query commands with pagination support -- `GetById` - Query command information by command ID -- `ListByIds` - Query commands by a list of command IDs - -### manager_event.proto - -Defines event-related RPC calls from the manager perspective. - -**Service**: `EventApi` - -- `ListByPage` - Query events with pagination support -- `GetById` - Query event information by event ID -- `ListByIds` - Query events by a list of event IDs - -### manager_profile.proto - -Defines profile-related RPC calls from the manager perspective. - -**Service**: `ProfileApi` - -- `ListByPage` - Query profiles with pagination support -- `GetByProfileId` - Query profile information by profile ID -- `ListByProfileIds` - Query profiles by a list of profile IDs -- `ListByDeviceId` - Query profiles bound to a device - -### manager_query.proto / manager_query_page.proto - -Shared query and paginated query structures for manager RPC calls. - -## Dependencies - -This module depends on common proto definitions: - -- `api/common/entity.proto` - Common entity definitions -- `api/common/page.proto` - Pagination support -- `api/common/r.proto` - Common response wrapper - -## Usage - -### 1. Add Dependency - -```xml - - - io.github.pnoker - dc3-api-manager - 2026.5.22 - -``` - -### 2. Inject gRPC Client +A transport adapter that needs the generated API calls the current cardinality-matching methods, for example: ```java - -@GrpcClient(ManagerConstant.SERVICE_NAME) -private DriverApiGrpc.DriverApiBlockingStub driverApiBlockingStub; - -@GrpcClient(ManagerConstant.SERVICE_NAME) -private PointApiGrpc.PointApiBlockingStub pointApiBlockingStub; -``` - -### 3. Query Driver by Device - -```java -GrpcDeviceQuery query = GrpcDeviceQuery.newBuilder() +GrpcDeviceQuery request = GrpcDeviceQuery.newBuilder() .setDeviceId(deviceId) + .setTenantId(tenantId) .build(); -GrpcRDriverDTO response = driverApiBlockingStub.getByDeviceId(query); -if(response. - -getResult(). - -getOk()){ -String serviceName = response.getData().getServiceName(); -} +GrpcRDriverDTO response = driverApiBlockingStub.getByDeviceId(request); ``` -## Integration Points +Do not use removed `SelectXxx` RPC names or ad hoc channel construction in business code. -- Used by `dc3-common-data` to resolve the target driver service name before publishing RabbitMQ commands -- Used by `dc3-common-data` to look up point metadata for data queries +## Implementation -## Build Instructions +`dc3-common-manager` implements the services as Spring `@Service` beans extending generated `*ImplBase` classes. +`dc3-common-facade-grpc` consumes them through stubs created by `GrpcStubConfig`. + +## Build and Verification ```bash -# Build the module (run from repo root) -mvn -s .mvn/settings.xml clean package - -# Install to local repository -mvn -s .mvn/settings.xml clean install - -# Build this module only -mvn -s ../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -q -pl dc3-api/dc3-api-manager -am compile ``` -## Related Modules - -- `dc3-api-driver` - Driver-side gRPC API for driver registration and config sync -- `dc3-common-data` - Consumes this API to resolve driver/point metadata -- `dc3-common-manager` - Implements this API as `@GrpcService` server - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) - +After proto changes, run the Manager gRPC server tests and facade contract tests. Verify tenant propagation and update +the corresponding server, builder, facade, and caller in the same change. diff --git a/dc3-center/README.md b/dc3-center/README.md new file mode 100644 index 000000000..95e251f0f --- /dev/null +++ b/dc3-center/README.md @@ -0,0 +1,53 @@ +# DC3 Center + +`dc3-center` contains the deployable backend applications. Most business logic lives in matching `dc3-common-*` +modules; center modules assemble dependencies, configuration, and process boundaries. + +## Applications + +| Module | HTTP | gRPC | Base path | Purpose | +|---|---:|---:|---|---| +| `dc3-center-single` | 8100 | 9100 | `/single` | auth, manager, and data in one JVM | +| `dc3-center-auth` | 8300 | 9300 | `/auth` | identity, authorization, OAuth2, and MCP authorization | +| `dc3-center-manager` | 8400 | 9400 | `/manager` | device and metadata management | +| `dc3-center-data` | 8500 | 9500 | `/data` | values, commands, events, and status | +| `dc3-center-agentic` | 8600 | n/a | `/agentic` | AI-assisted operations | + +Ports are defaults; environment variables in each `application.yml` are authoritative. The distributed applications use +static, environment-overridable gRPC addresses. They do not depend on Nacos service discovery. + +## Run locally + +From the repository root: + +```bash +make up-db +make up-dev GROUP=core +``` + +To run source processes instead, start one command per terminal: + +```bash +make run SERVICE=auth +make run SERVICE=manager +make run SERVICE=data +make run SERVICE=agentic +``` + +Run the all-in-one process directly because the root Makefile does not define a `single` service alias: + +```bash +mvn -s .mvn/settings.xml -pl dc3-center/dc3-center-single -am spring-boot:run +``` + +Start the gateway separately when testing public HTTP routes. + +## Verification + +```bash +mvn -s .mvn/settings.xml -q -f dc3-center/pom.xml -DskipTests compile +mvn -s .mvn/settings.xml -f dc3-center/pom.xml test +``` + +For runtime configuration, read the affected module's `application.yml` plus its active profile file. Do not duplicate +profile-specific host or port values in new documentation. diff --git a/dc3-center/dc3-center-agentic/README.md b/dc3-center/dc3-center-agentic/README.md index a53ceab3a..40db77c96 100644 --- a/dc3-center/dc3-center-agentic/README.md +++ b/dc3-center/dc3-center-agentic/README.md @@ -11,7 +11,6 @@ shell; the agentic logic lives in `dc3-common-agentic`. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-center-agentic -- **Version**: 2026.5.22 - **Package**: `io.github.pnoker.center.agentic` ## Service Ports @@ -44,25 +43,30 @@ The WebFlux base path is `/agentic`; through the gateway the service is reached ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev SERVICES="auth manager data" ``` +The agentic service has gRPC facade channels for Auth, Manager, and Data centers. Start all three before exercising +platform tools; the gateway is optional when calling the agentic service directly. + ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-center/dc3-center-agentic -am package java -jar dc3-center/dc3-center-agentic/target/dc3-center-agentic.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-center/dc3-center-agentic -am test +``` + ## Related Modules - `dc3-common-agentic` — agentic SDK: Spring AI chat client, platform tools, conversation memory, model management - `dc3-common-facade-grpc` — gRPC facade for cross-service access - `dc3-common-resource-registrar` — registers this service's API / menu resources - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-center/dc3-center-auth/README.md b/dc3-center/dc3-center-auth/README.md index ccea70855..3cc965014 100644 --- a/dc3-center/dc3-center-auth/README.md +++ b/dc3-center/dc3-center-auth/README.md @@ -10,15 +10,14 @@ control. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-center-auth -- **Version**: 2026.5.22 - **Package**: `io.github.pnoker.center.auth` ## Service Ports -| Protocol | Port | -|-----------|------------------------------------------------------| -| HTTP REST | `8300` (default, overridable via `SERVER_PORT`) | -| gRPC | `9300` (default, overridable via `GRPC_SERVER_PORT`) | +| Protocol | Port | Configuration variable | +|-----------|--------|------------------------| +| HTTP REST | `8300` | `DC3_AUTH_PORT` | +| gRPC | `9300` | `DC3_AUTH_GRPC_PORT` | ## Key Responsibilities @@ -26,8 +25,8 @@ control. - **Tenant Management**: Multi-tenant registration, lookup by tenant code - **User Authentication**: Local credential validation with server-side password hashing - **Dictionary Services**: Provide lookup dictionaries for auth-scoped data -- **gRPC Server**: Exposes `TenantApi`, `UserApi`, `LocalCredentialApi`, `TokenApi` for inter-service consumption (e.g., - Gateway) +- **gRPC Server**: Exposes tenant, user, credential, token, permission, resource-registry, and MCP-runtime APIs for + facade-backed inter-service consumption ## REST Endpoints (via Gateway) @@ -56,21 +55,21 @@ This service wires `dc3-common-auth` which contains all business logic controlle - `application.yml` — base port and profile config - `application-dev.yml` — dev env: Postgres connection via `${ENV:default}` vars -- `application-pre.yml` — pre-release: Nacos-based service discovery -- `application-pro.yml` — production: Nacos-based service discovery +- `application-pre.yml` — pre-release datasource and runtime overrides +- `application-pro.yml` — production datasource and runtime overrides ## Running Locally ### 1. Start Infrastructure ```bash -podman compose -f dc3/docker-compose-db.yml up -d +make up-db ``` ### 2. Build ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-center/dc3-center-auth -am package ``` ### 3. Run @@ -79,14 +78,16 @@ mvn -s .mvn/settings.xml clean package java -jar dc3-center/dc3-center-auth/target/dc3-center-auth.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-center/dc3-center-auth -am test +``` + ## Related Modules - `dc3-api-auth` - gRPC API contracts for auth service - `dc3-common-auth` - Business logic implementation - `dc3-gateway` - Consumes token validation via gRPC - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-center/dc3-center-data/README.md b/dc3-center/dc3-center-data/README.md index 81fdd05d2..5a652fb83 100644 --- a/dc3-center/dc3-center-data/README.md +++ b/dc3-center/dc3-center-data/README.md @@ -10,24 +10,24 @@ exposing data query APIs. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-center-data -- **Version**: 2026.5.22 - **Package**: `io.github.pnoker.center.data` ## Service Ports -| Protocol | Port | -|-----------|------------------------------------------------------| -| HTTP REST | `8500` (default, overridable via `SERVER_PORT`) | -| gRPC | `9500` (default, overridable via `GRPC_SERVER_PORT`) | +| Protocol | Port | Configuration variable | +|-----------|--------|------------------------| +| HTTP REST | `8500` | `DC3_DATA_PORT` | +| gRPC | `9500` | `DC3_DATA_GRPC_PORT` | ## Key Responsibilities - **Point Value Ingestion**: Receives point values from drivers via RabbitMQ (`dc3.e.value` exchange, `dc3.q.value.point` queue) and persists them to the time-series storage - **Point Value Query**: Exposes REST and gRPC APIs to query the latest and historical point values -- **Device Command Dispatch**: Receives read/write commands, resolves the target driver via Manager gRPC ( - `ManagerConstant.SERVICE_NAME`), and publishes to `dc3.e.command` -- **Driver Status**: Tracks driver online/offline status events +- **Point Command Dispatch**: Resolves the target driver through `DriverFacade` and publishes point read/write commands + to `dc3.e.point_command` +- **Custom Command Dispatch**: Publishes custom device commands to `dc3.e.command` +- **Driver and Device Status**: Tracks state, timeout, and alarm events - **Data Query**: Supports pagination query, real-time telemetry, and historical data retrieval ## REST Endpoints (via Gateway) @@ -36,11 +36,13 @@ Accessible through the gateway at `/api/v3/data/**` (authentication required). ## Messaging Topics -| Exchange | Direction | Purpose | -|-----------------|-----------|-----------------------------------------| -| `dc3.e.value` | Inbound | Receive point values from drivers | -| `dc3.e.command` | Outbound | Dispatch read/write commands to drivers | -| `dc3.e.event` | Inbound | Receive driver/device status events | +| Exchange | Direction | Purpose | +|-----------------------|-----------|-----------------------------------------| +| `dc3.e.value` | Inbound | Receive point values from drivers | +| `dc3.e.point_command` | Outbound | Dispatch point read/write commands | +| `dc3.e.command` | Outbound | Dispatch custom device commands | +| `dc3.e.state` | Inbound | Receive driver/device state events | +| `dc3.e.event` | Inbound | Receive reported domain events | ## Dependencies @@ -58,21 +60,21 @@ This service wires `dc3-common-data` which contains all business logic. - `application.yml` — base port and profile config - `application-dev.yml` — dev env: Postgres, RabbitMQ, gRPC client addresses -- `application-pre.yml` — pre-release: Nacos-based service discovery -- `application-pro.yml` — production: Nacos-based service discovery +- `application-pre.yml` — pre-release datasource, messaging, and static gRPC client addresses +- `application-pro.yml` — production datasource, messaging, and static gRPC client addresses ## Running Locally ### 1. Start Infrastructure ```bash -podman compose -f dc3/docker-compose-db.yml up -d +make up-db ``` ### 2. Build ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-center/dc3-center-data -am package ``` ### 3. Run (after auth and manager are up) @@ -81,15 +83,17 @@ mvn -s .mvn/settings.xml clean package java -jar dc3-center/dc3-center-data/target/dc3-center-data.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-center/dc3-center-data -am test +``` + ## Related Modules - `dc3-api-data` - gRPC API contracts for point value queries - `dc3-api-manager` - gRPC API for resolving driver/point metadata - `dc3-common-data` - Business logic implementation - `dc3-common-repository` - Pluggable time-series storage adapter - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-center/dc3-center-manager/README.md b/dc3-center/dc3-center-manager/README.md index 41862d956..e2bffdc67 100644 --- a/dc3-center/dc3-center-manager/README.md +++ b/dc3-center/dc3-center-manager/README.md @@ -10,15 +10,14 @@ management, and command interfaces. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-center-manager -- **Version**: 2026.5.22 - **Package**: `io.github.pnoker.center.manager` ## Service Ports -| Protocol | Port | -|-----------|------------------------------------------------------| -| HTTP REST | `8400` (default, overridable via `SERVER_PORT`) | -| gRPC | `9400` (default, overridable via `GRPC_SERVER_PORT`) | +| Protocol | Port | Configuration variable | +|-----------|--------|------------------------| +| HTTP REST | `8400` | `DC3_MANAGER_PORT` | +| gRPC | `9400` | `DC3_MANAGER_GRPC_PORT` | ## Key Responsibilities @@ -49,12 +48,12 @@ Key endpoint prefixes (defined in `ManagerConstant`): ## gRPC Services (consumed by drivers and data service) -| Service | Used By | -|------------------------------|----------------------------------| -| `DriverApi.driverRegister` | Drivers on startup | -| `DeviceApi.selectById` | Drivers fetching device config | -| `PointApi.selectById` | Drivers and data service | -| `DriverApi.selectByDeviceId` | Data service for command routing | +| Service | Used by | +|----------------------------|-------------------------------------------------| +| `DriverApi.DriverRegister` | Drivers registering on startup | +| `DeviceApi.GetById` | Drivers fetching device configuration | +| `PointApi.GetById` | Drivers fetching point configuration | +| `DriverApi.GetByDeviceId` | Distributed facades resolving command routing | ## Dependencies @@ -72,21 +71,21 @@ This service wires `dc3-common-manager` which contains all business logic. - `application.yml` — base port and profile config - `application-dev.yml` — dev env: Postgres, RabbitMQ, gRPC client addresses -- `application-pre.yml` — pre-release: Nacos-based service discovery -- `application-pro.yml` — production: Nacos-based service discovery +- `application-pre.yml` — pre-release datasource, messaging, and static gRPC client addresses +- `application-pro.yml` — production datasource, messaging, and static gRPC client addresses ## Running Locally ### 1. Start Infrastructure ```bash -podman compose -f dc3/docker-compose-db.yml up -d +make up-db ``` ### 2. Build ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-center/dc3-center-manager -am package ``` ### 3. Run (after auth is up) @@ -95,14 +94,16 @@ mvn -s .mvn/settings.xml clean package java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-center/dc3-center-manager -am test +``` + ## Related Modules - `dc3-api-driver` - Driver-side gRPC API implemented by this service - `dc3-api-manager` - Manager-side gRPC API implemented by this service - `dc3-common-manager` - Business logic implementation - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-center/dc3-center-single/README.md b/dc3-center/dc3-center-single/README.md index b7d8a3f37..5ff4f2ff7 100644 --- a/dc3-center/dc3-center-single/README.md +++ b/dc3-center/dc3-center-single/README.md @@ -9,15 +9,14 @@ management services into a single deployable module for simplified single-node o - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-center-single -- **Version**: 2026.5.22 - **Package**: `io.github.pnoker.center.single` ## Service Ports -| Protocol | Port | -|-----------|------------------------------------------------------| -| HTTP REST | `8100` (default, overridable via `SERVER_PORT`) | -| gRPC | `9100` (default, overridable via `GRPC_SERVER_PORT`) | +| Protocol | Port | Configuration variable | +|-----------|--------|------------------------| +| HTTP REST | `8100` | `DC3_SINGLE_PORT` | +| gRPC | `9100` | `DC3_SINGLE_GRPC_PORT` | ## Key Responsibilities @@ -57,7 +56,7 @@ Wires all three common service modules: - `application.yml` — base port and profile config - `application-dev.yml` — dev env: single Postgres/RabbitMQ config -- `application-pre.yml` — pre-release: Nacos-based service discovery +- `application-pre.yml` — pre-release runtime overrides for the all-in-one process - `application-pro.yml` — production target config ## Running Locally @@ -65,13 +64,13 @@ Wires all three common service modules: ### 1. Start Infrastructure ```bash -podman compose -f dc3/docker-compose-db.yml up -d +make up-db ``` ### 2. Build ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-center/dc3-center-single -am package ``` ### 3. Run @@ -80,15 +79,17 @@ mvn -s .mvn/settings.xml clean package java -jar dc3-center/dc3-center-single/target/dc3-center-single.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-center/dc3-center-single -am test +``` + ## Related Modules - `dc3-center-auth` — Standalone auth service - `dc3-center-data` — Standalone data service - `dc3-center-manager` — Standalone manager service - `dc3-common-auth` / `dc3-common-data` / `dc3-common-manager` — Shared business logic - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-common/README.md b/dc3-common/README.md new file mode 100644 index 000000000..7de6d49a9 --- /dev/null +++ b/dc3-common/README.md @@ -0,0 +1,60 @@ +# DC3 Common + +`dc3-common` contains reusable backend libraries and the shared business implementations assembled by the deployable +center and driver applications. + +## Domain modules + +| Module | Responsibility | +|---|---| +| `dc3-common-auth` | authentication, authorization, identity, OAuth2, and auth gRPC servers | +| `dc3-common-manager` | driver/device/profile/point metadata and manager APIs | +| `dc3-common-data` | values, commands, events, status, and data APIs | +| `dc3-common-agentic` | AI models, sessions, tools, and assisted operations | +| `dc3-common-driver` | driver SDK, registration, scheduling, metadata, command, and value runtime | +| `dc3-common-gateway` | gateway routes, authentication filter, and ingress support | + +## Contracts and models + +| Module | Responsibility | +|---|---| +| `dc3-common-model` | shared BO/VO/DTO bases, builders, extension models, validation groups, and domain enums | +| `dc3-common-public` | response envelope, `BaseService`, shared entities/utilities, and tenant markers | +| `dc3-common-api` | shared gRPC conversion helpers | +| `dc3-common-facade` | cross-service facade contracts and implementations | +| `dc3-common-constant` | stable shared constants | +| `dc3-common-exception` | shared exception hierarchy | + +## Infrastructure modules + +| Module | Responsibility | +|---|---| +| `dc3-common-dal` | shared label/group persistence | +| `dc3-common-postgres` | datasource and MyBatis-Plus configuration | +| `dc3-common-repository` | point-value storage abstraction | +| `dc3-common-rabbitmq` | shared exchanges, connection configuration, and message conversion | +| `dc3-common-mqtt` | MQTT client configuration | +| `dc3-common-quartz` | scheduling infrastructure | +| `dc3-common-thread` | managed executors | +| `dc3-common-web` | WebFlux, springdoc, security, and controller support | +| `dc3-common-log` | logging defaults | +| `dc3-common-sql` | SQL utilities | +| `dc3-common-resource-registrar` | API/resource annotation discovery and synchronization | +| `dc3-common-test` | shared tests, harnesses, and Testcontainers | + +## Architecture rules + +- Preserve `Controller -> Service -> Manager -> Mapper` layering. +- Keep tenant scope in queries, cache keys, gRPC calls, and cross-service lookups. +- Use BOs in persistent business services and builders for VO/BO/DO conversion. +- Use facade interfaces for cross-service business calls. +- Add dependencies to the narrowest module that owns the required capability. + +## Verification + +```bash +mvn -s .mvn/settings.xml -q -f dc3-common/pom.xml -DskipTests compile +mvn -s .mvn/settings.xml -f dc3-common/pom.xml test +``` + +Use the child README for module-specific configuration and tests. diff --git a/dc3-common/dc3-common-agentic/README.md b/dc3-common/dc3-common-agentic/README.md index 5dd01683d..1fe86862d 100644 --- a/dc3-common/dc3-common-agentic/README.md +++ b/dc3-common/dc3-common-agentic/README.md @@ -10,7 +10,6 @@ model uses to read and operate platform resources. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-agentic -- **Version**: 2026.5.22 ## Key Components @@ -37,16 +36,18 @@ model uses to read and operate platform resources. ## Build Instructions ```bash -mvn -s ../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-agentic -am package +``` + +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-agentic -am test ``` ## Related Modules - `dc3-center-agentic` — the service shell that exposes this SDK over HTTP (`/api/v3/agentic/**`) - `dc3-common-facade-*` — facades the platform tools call to reach other services - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-common/dc3-common-api/README.md b/dc3-common/dc3-common-api/README.md index be4fd45c1..f09f7f3fb 100644 --- a/dc3-common/dc3-common-api/README.md +++ b/dc3-common/dc3-common-api/README.md @@ -9,7 +9,6 @@ builder utilities for constructing gRPC request/response objects from domain mod - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-api -- **Version**: 2026.5.22 ## Key Components @@ -24,16 +23,18 @@ protobuf classes. ## Build Instructions ```bash -mvn -s ../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-api -am package +``` + +## Testing + +This module currently has no module-specific automated tests. Verify generated or production sources by compiling the +affected reactor from the repository root: + +```bash +mvn -s .mvn/settings.xml -q -pl dc3-common/dc3-common-api -am -DskipTests compile ``` ## Related Modules - `dc3-api-auth` / `dc3-api-data` / `dc3-api-driver` / `dc3-api-manager` — gRPC API contracts that use these utilities - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) - diff --git a/dc3-common/dc3-common-auth/README.md b/dc3-common/dc3-common-auth/README.md index 70a7cc256..c897d9446 100644 --- a/dc3-common/dc3-common-auth/README.md +++ b/dc3-common/dc3-common-auth/README.md @@ -10,7 +10,6 @@ functionality. It is wired directly into `dc3-center-auth`. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-auth -- **Version**: 2026.5.22 ## Key Components @@ -18,22 +17,36 @@ functionality. It is wired directly into `dc3-center-auth`. |--------------|----------------------------------------------------------------------------| | Controllers | REST controllers for user, tenant, token, dictionary endpoints | | Services | `TokenService`, `UserService`, `TenantService`, `DictionaryForAuthService` | -| gRPC Servers | `TenantServer`, `UserServer`, `TokenServer` (`@GrpcService`) | +| gRPC Servers | Spring `@Service` beans extending generated `*ImplBase` server classes | | DAL | MyBatis-Plus mappers and DAL managers for auth tables | | Init | `AuthInitRunner` for startup checks | ## gRPC Services Exposed -| Service | Consumed By | -|-------------|------------------------------| -| `TokenApi` | Gateway (`Authentic` filter) | -| `TenantApi` | Gateway, other services | -| `UserApi` | Gateway, other services | +| Service | Purpose | +|---|---| +| `TokenApi` | Validate login and token material for gateway authentication | +| `TenantApi` | Resolve tenant metadata by code | +| `UserApi` | Resolve users by ID or principal ID | +| `LocalCredentialApi` | Resolve local credentials by login name | +| `PermissionApi` | List effective permission codes | +| `ResourceRegistryApi` | Synchronize discovered API and menu resources | +| `McpRuntimeApi` | Introspect, authorize, resolve, and audit MCP tool calls | + +Distributed callers use the corresponding facade interfaces; they should not construct gRPC channels in business code. ## Build Instructions ```bash -mvn -s ../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-auth -am package +``` + +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-auth -am test ``` ## Related Modules @@ -41,10 +54,3 @@ mvn -s ../../.mvn/settings.xml clean package - `dc3-center-auth` — Bootstraps this module as a Spring Boot service - `dc3-api-auth` — gRPC contract implemented by this module - `dc3-common-model` — Entity, BO, VO, DTO definitions - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) - diff --git a/dc3-common/dc3-common-constant/README.md b/dc3-common/dc3-common-constant/README.md index 5f043e9b9..d886f1da2 100644 --- a/dc3-common/dc3-common-constant/README.md +++ b/dc3-common/dc3-common-constant/README.md @@ -10,7 +10,6 @@ and common modules. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-constant -- **Version**: 2026.5.22 ## Key Components @@ -27,18 +26,22 @@ and common modules. `RabbitConstant` defines all exchange names, queue name prefixes, and routing key prefixes: -| Constant | Value | -|----------------------------------|--------------------------| -| `TOPIC_EXCHANGE_COMMAND` | `dc3.e.command` | -| `TOPIC_EXCHANGE_METADATA` | `dc3.e.metadata` | -| `TOPIC_EXCHANGE_VALUE` | `dc3.e.value` | -| `TOPIC_EXCHANGE_EVENT` | `dc3.e.event` | -| `ROUTING_DEVICE_COMMAND_PREFIX` | `dc3.r.command.device.` | -| `ROUTING_DRIVER_METADATA_PREFIX` | `dc3.r.metadata.driver.` | -| `ROUTING_POINT_VALUE_PREFIX` | `dc3.r.value.point.` | +| Constant | Base value | +|----------------------------------|--------------------------------| +| `TOPIC_EXCHANGE_POINT_COMMAND` | `dc3.e.point_command` | +| `TOPIC_EXCHANGE_COMMAND` | `dc3.e.command` | +| `TOPIC_EXCHANGE_METADATA` | `dc3.e.metadata` | +| `TOPIC_EXCHANGE_VALUE` | `dc3.e.value` | +| `TOPIC_EXCHANGE_EVENT` | `dc3.e.event` | +| `ROUTING_POINT_COMMAND_PREFIX` | `dc3.r.point_command.` | +| `ROUTING_COMMAND_PREFIX` | `dc3.r.command.` | +| `ROUTING_DRIVER_METADATA_PREFIX` | `dc3.r.metadata.driver.` | +| `ROUTING_POINT_VALUE_PREFIX` | `dc3.r.value.point.` | -> **Important**: RabbitMQ routing keys are suffixed with the driver's service name. These constants must not be renamed -> without updating all consumers. +The runtime may prepend the `dc3.rabbit.tag` system-property value to exchange, queue, and selected routing constants. +Point read/write operations use the point-command constants; `TOPIC_EXCHANGE_COMMAND` is reserved for custom commands. +Routing keys are suffixed with the driver's service name. Do not rename them without updating every producer, binding, +consumer, and deployed queue migration. ### Common Constants @@ -53,26 +56,29 @@ and common modules. Located in `io.github.pnoker.common.enums`: -- `EnableFlagEnum` — Entity enable/disable status -- `DriverStatusEnum` — Driver online/offline/fault states -- `DriverTypeFlagEnum` — Driver protocol type classification -- `PointTypeFlagEnum` — Point value type (int, float, bool, string, etc.) -- `MetadataOperateTypeEnum` — Metadata operation (add/update/delete) -- `DeviceCommandTypeEnum` — Device command type (READ/WRITE) -- And many others (`AttributeTypeFlagEnum`, `ProfileShareFlagEnum`, etc.) +- `EnableFlagEnum` — Boolean-like enable/disable state +- `EntityStatusEnum` — Online, offline, maintenance, and fault states +- `DriverTypeEnum` — Driver client/server, gateway, and connection classifications +- `PointTypeEnum` — Point value types such as string, numeric, and boolean +- `MetadataOperateTypeEnum` — Metadata add/delete/update operations +- `PointCommandTypeEnum` — Point read, batch-read, write, batch-write, and configuration commands +- `AttributeTypeEnum` — Attribute value types +- `ProfileShareTypeEnum` — Tenant-, driver-, and user-scoped profile sharing ## Build Instructions ```bash -mvn -s ../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-constant -am package +``` + +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-constant -am test ``` ## Related Modules Used as a dependency by virtually all other `dc3-common-*` and `dc3-center-*` modules. - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-common/dc3-common-dal/README.md b/dc3-common/dc3-common-dal/README.md index 0ca5e4890..589262d06 100644 --- a/dc3-common/dc3-common-dal/README.md +++ b/dc3-common/dc3-common-dal/README.md @@ -9,7 +9,6 @@ manager implementations, and shared data structures used across multiple service - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-dal -- **Version**: 2026.5.22 ## Key Components @@ -20,7 +19,16 @@ manager implementations, and shared data structures used across multiple service ## Build Instructions ```bash -mvn -s ../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-dal -am package +``` + +## Testing + +This module currently has no module-specific automated tests. Verify generated or production sources by compiling the +affected reactor from the repository root: + +```bash +mvn -s .mvn/settings.xml -q -pl dc3-common/dc3-common-dal -am -DskipTests compile ``` ## Related Modules @@ -28,10 +36,3 @@ mvn -s ../../.mvn/settings.xml clean package - `dc3-common-postgres` — PostgreSQL and MyBatis-Plus base configuration - `dc3-common-model` — Base BO/VO/DTO model definitions - `dc3-common-manager` / `dc3-common-auth` / `dc3-common-data` — Consumers of this DAL layer - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) - diff --git a/dc3-common/dc3-common-data/README.md b/dc3-common/dc3-common-data/README.md index c49f009e3..fc3fae900 100644 --- a/dc3-common/dc3-common-data/README.md +++ b/dc3-common/dc3-common-data/README.md @@ -10,40 +10,54 @@ into `dc3-center-data`. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-data -- **Version**: 2026.5.22 ## Key Components -| Layer | Contents | -|--------------|------------------------------------------------------------------------------------------| -| Controllers | REST controllers for point value read/write, query, status | -| Services | `PointCommandService`, `PointValueService`, `DriverStatusService`, `DeviceStatusService` | -| gRPC Clients | `@GrpcClient(ManagerConstant.SERVICE_NAME)` stubs for `DriverApi`, `PointApi` | -| RabbitMQ | Producer for `dc3.e.command`; Consumer for `dc3.e.value`, `dc3.e.event` | -| Init | `DataInitRunner` for startup preparation | +| Layer | Contents | +|--------------|---------------------------------------------------------------------------------------------------| +| Controllers | REST controllers for point values, point/custom commands, events, status, and health | +| Services | Point value, point command, command history, event history, driver status, and device status | +| Facades | `DriverFacade`, `PointFacade`, and related transport-independent cross-service APIs | +| RabbitMQ | Point/custom-command producers plus value, state, alarm, event, and result consumers | +| Init | `DataInitRunner` for startup preparation | ## Command Dispatch Flow ``` REST /api/v3/data/point_value/read → PointCommandServiceImpl - → gRPC: driverApiBlockingStub.selectByDeviceId() - → RabbitMQ: dc3.e.command / dc3.r.command.device.{serviceName} + → DriverFacade.getByDeviceId(tenantId, deviceId) + → RabbitMQ: dc3.e.point_command / dc3.r.point_command.{serviceName} → Driver receives and acts ``` +Custom device commands follow the parallel `dc3.e.command` / `dc3.r.command.{serviceName}` route through +`CommandHistoryServiceImpl`. + ## MQ Topics -| Exchange | Queue | Direction | -|-----------------|---------------------------------------------|-------------------------| -| `dc3.e.value` | `dc3.q.value.point` | Inbound (from drivers) | -| `dc3.e.command` | `dc3.q.command.device.{service}` | Outbound (to drivers) | -| `dc3.e.event` | `dc3.q.event.driver` / `dc3.q.event.device` | Inbound (status events) | +| Exchange | Queue or routing key | Direction | +|-----------------------|-------------------------------------|-----------------------------| +| `dc3.e.value` | `dc3.q.value.point` | Inbound point values | +| `dc3.e.point_command` | `dc3.r.point_command.{service}` | Outbound point read/write | +| `dc3.e.command` | `dc3.r.command.{service}` | Outbound custom commands | +| `dc3.e.state` | `dc3.q.state.driver` / `dc3.q.state.device` | Inbound driver/device state | +| `dc3.e.event` | `dc3.q.event.report` | Inbound reported events | + +The optional `dc3.rabbit.tag` system property prefixes runtime names; `RabbitConstant` remains authoritative. ## Build Instructions ```bash -mvn -s ../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-data -am package +``` + +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-data -am test ``` ## Related Modules @@ -52,10 +66,3 @@ mvn -s ../../.mvn/settings.xml clean package - `dc3-api-manager` — gRPC API consumed by this module for driver/point resolution - `dc3-common-repository` — Storage adapter for persisting point values - `dc3-common-rabbitmq` — RabbitMQ exchange/queue configuration - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) - diff --git a/dc3-common/dc3-common-driver/README.md b/dc3-common/dc3-common-driver/README.md index 90e661e25..1705b1384 100644 --- a/dc3-common/dc3-common-driver/README.md +++ b/dc3-common/dc3-common-driver/README.md @@ -10,7 +10,6 @@ scheduled data collection. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-driver -- **Version**: 2026.5.22 ## Key Components @@ -28,24 +27,37 @@ scheduled data collection. ``` Driver startup → DriverInitRunner - → gRPC: dc3-center-manager / DriverApi.driverRegister() + → gRPC: dc3-center-manager / DriverApi.DriverRegister ← Returns: driver ID, driver attributes, point attributes, device IDs → Subscribe to metadata queue: dc3.q.metadata.driver.{serviceName} - → Subscribe to command queue: dc3.q.command.driver.{serviceName} + → Subscribe to point-command queue: dc3.q.point_command.{serviceName} + → Subscribe to custom-command queue: dc3.q.command.{serviceName} ``` ## RabbitMQ Integration -| Exchange | Queue | Purpose | -|------------------|-----------------------------------|-------------------------------------| -| `dc3.e.metadata` | `dc3.q.metadata.driver.{service}` | Receive config change events | -| `dc3.e.command` | `dc3.q.command.driver.{service}` | Receive READ/WRITE commands | -| `dc3.e.value` | — | Publish point values to data center | +| Exchange | Queue | Purpose | +|-----------------------|-------------------------------------|--------------------------------------| +| `dc3.e.metadata` | `dc3.q.metadata.driver.{service}` | Receive configuration changes | +| `dc3.e.point_command` | `dc3.q.point_command.{service}` | Receive point read/write commands | +| `dc3.e.command` | `dc3.q.command.{service}` | Receive custom device commands | +| `dc3.e.value` | — | Publish point values to Data Center | + +The optional `dc3.rabbit.tag` system property prefixes runtime names; use `RabbitConstant` and `DriverTopicConfig` as +the authoritative definitions. ## Build Instructions ```bash -mvn -s ../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-driver -am package +``` + +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-driver -am test ``` ## Related Modules @@ -54,10 +66,3 @@ mvn -s ../../.mvn/settings.xml clean package - `dc3-api-driver` — gRPC contracts consumed by this SDK - `dc3-common-rabbitmq` — RabbitMQ exchange configuration - `dc3-common-constant` — `RabbitConstant` routing key prefixes - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) - diff --git a/dc3-common/dc3-common-exception/README.md b/dc3-common/dc3-common-exception/README.md index 145bccc55..db9b06ac5 100644 --- a/dc3-common/dc3-common-exception/README.md +++ b/dc3-common/dc3-common-exception/README.md @@ -9,7 +9,6 @@ services and modules use these exceptions to signal business errors consistently - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-exception -- **Version**: 2026.5.22 ## Key Components @@ -23,13 +22,17 @@ services and modules use these exceptions to signal business errors consistently | `DeleteException` | Entity delete failure | | `NotFoundException` | Entity or resource not found | | `JsonException` | JSON serialization/deserialization error | -| `AuthException` | Authentication/authorization failure | +| `SecurityException` | General security policy violation | +| `UnAuthorizedException` | Missing or invalid authentication | +| `AccessDeniedException` | Authenticated principal lacks access | | `DuplicateException` | Duplicate entity conflict | ### Utilities -- **`ExceptionUtil`** — Helper methods for wrapping and rethrowing exceptions with context -- **`ExceptionConstant`** — Standard exception message strings (e.g., `UTILITY_CLASS`) +- **`ExceptionUtil`** — Builds shared service-unavailable messages +- **`ExceptionMessageFormatter`** — Internal `{}` placeholder and trailing-cause formatter used by business exceptions + +Shared message constants such as `ExceptionConstant` belong to `dc3-common-constant`. ## Usage @@ -41,16 +44,17 @@ throw new AddException("Failed to add driver: " + entityBO.getServiceName()); ## Build Instructions ```bash -mvn -s ../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-exception -am package +``` + +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-exception -am test ``` ## Related Modules Used by all `dc3-common-*` service modules and `dc3-center-*` services. - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) - diff --git a/dc3-common/dc3-common-facade/README.md b/dc3-common/dc3-common-facade/README.md new file mode 100644 index 000000000..704fe8607 --- /dev/null +++ b/dc3-common/dc3-common-facade/README.md @@ -0,0 +1,29 @@ +# DC3 Common Facade + +The facade modules define and implement cross-service business boundaries without binding callers directly to gRPC or +in-process service classes. + +## Modules + +| Module | Role | +|---|---| +| `dc3-common-facade-api` | transport-independent facade interfaces and request/result contracts | +| `dc3-common-facade-grpc` | distributed implementations backed by shared gRPC stubs | +| `dc3-common-facade-local-auth` | in-process auth facade implementation | +| `dc3-common-facade-local-data` | in-process data facade implementation | +| `dc3-common-facade-local-manager` | in-process manager facade implementation | +| `dc3-common-facade-local` | convenience POM aggregating all local implementations | + +## Selection + +- Distributed center applications normally use `dc3-common-facade-grpc`. +- Single-process applications use the required domain-specific local modules. +- Depend on `dc3-common-facade-local` only when the application intentionally needs every local facade. +- Business code imports interfaces from `dc3-common-facade-api`; transport selection belongs in assembly/configuration. + +## Verification + +```bash +mvn -s .mvn/settings.xml -q -f dc3-common/dc3-common-facade/pom.xml -DskipTests compile +mvn -s .mvn/settings.xml -f dc3-common/dc3-common-facade/pom.xml test +``` diff --git a/dc3-common/dc3-common-facade/dc3-common-facade-api/README.md b/dc3-common/dc3-common-facade/dc3-common-facade-api/README.md index 4bbab384c..ab3faa0e1 100644 --- a/dc3-common/dc3-common-facade/dc3-common-facade-api/README.md +++ b/dc3-common/dc3-common-facade/dc3-common-facade-api/README.md @@ -17,7 +17,6 @@ services never depend on transport details. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-facade-api -- **Version**: 2026.5.22 ## Facade Contracts @@ -42,16 +41,19 @@ auto-configuration. ## Build Instructions ```bash -mvn -s ../../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-facade/dc3-common-facade-api -am package +``` + +## Testing + +This module currently has no module-specific automated tests. Verify generated or production sources by compiling the +affected reactor from the repository root: + +```bash +mvn -s .mvn/settings.xml -q -pl dc3-common/dc3-common-facade/dc3-common-facade-api -am -DskipTests compile ``` ## Related Modules - `dc3-common-facade-grpc` — gRPC-backed implementation - `dc3-common-facade-local-auth` / `-data` / `-manager` — in-process implementations - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-common/dc3-common-facade/dc3-common-facade-grpc/README.md b/dc3-common/dc3-common-facade/dc3-common-facade-grpc/README.md index 1761979a3..4b97f2870 100644 --- a/dc3-common/dc3-common-facade/dc3-common-facade-grpc/README.md +++ b/dc3-common/dc3-common-facade/dc3-common-facade-grpc/README.md @@ -11,7 +11,6 @@ is the default implementation for the distributed (multi-service) deployment. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-facade-grpc -- **Version**: 2026.5.22 ## Implementations @@ -35,16 +34,19 @@ auth channel points at `dc3-center-auth:9300`). ## Build Instructions ```bash -mvn -s ../../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-facade/dc3-common-facade-grpc -am package +``` + +## Testing + +This module currently has no module-specific automated tests. Verify generated or production sources by compiling the +affected reactor from the repository root: + +```bash +mvn -s .mvn/settings.xml -q -pl dc3-common/dc3-common-facade/dc3-common-facade-grpc -am -DskipTests compile ``` ## Related Modules - `dc3-common-facade-api` — facade contracts - `dc3-common-facade-local-*` — in-process alternative used by `dc3-center-single` - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-common/dc3-common-facade/dc3-common-facade-local-auth/README.md b/dc3-common/dc3-common-facade/dc3-common-facade-local-auth/README.md index e95bf6e24..562db8988 100644 --- a/dc3-common/dc3-common-facade/dc3-common-facade-local-auth/README.md +++ b/dc3-common/dc3-common-facade/dc3-common-facade-local-auth/README.md @@ -10,7 +10,6 @@ local classpath — used inside the `dc3-center-single` monolith where auth, man - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-facade-local-auth -- **Version**: 2026.5.22 ## Implementations @@ -30,16 +29,18 @@ Active when the in-process facade mode is selected (`dc3.facade.mode=local`) and ## Build Instructions ```bash -mvn -s ../../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-facade/dc3-common-facade-local-auth -am package +``` + +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-facade/dc3-common-facade-local-auth -am test ``` ## Related Modules - `dc3-common-facade-grpc` — gRPC alternative for distributed deployments - `dc3-common-facade-local-data` / `-manager` — sibling in-process facades - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-common/dc3-common-facade/dc3-common-facade-local-data/README.md b/dc3-common/dc3-common-facade/dc3-common-facade-local-data/README.md index f6183d2ca..3af5bcbd8 100644 --- a/dc3-common/dc3-common-facade/dc3-common-facade-local-data/README.md +++ b/dc3-common/dc3-common-facade/dc3-common-facade-local-data/README.md @@ -10,7 +10,6 @@ issuing gRPC calls — used inside the `dc3-center-single` monolith. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-facade-local-data -- **Version**: 2026.5.22 ## Implementations @@ -30,16 +29,18 @@ Active when the in-process facade mode is selected (`dc3.facade.mode=local`) and ## Build Instructions ```bash -mvn -s ../../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-facade/dc3-common-facade-local-data -am package +``` + +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-facade/dc3-common-facade-local-data -am test ``` ## Related Modules - `dc3-common-facade-grpc` — gRPC alternative for distributed deployments - `dc3-common-facade-local-auth` / `-manager` — sibling in-process facades - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-common/dc3-common-facade/dc3-common-facade-local-manager/README.md b/dc3-common/dc3-common-facade/dc3-common-facade-local-manager/README.md index e35b2dc31..d3cf46779 100644 --- a/dc3-common/dc3-common-facade/dc3-common-facade-local-manager/README.md +++ b/dc3-common/dc3-common-facade/dc3-common-facade-local-manager/README.md @@ -10,7 +10,6 @@ issuing gRPC calls — used inside the `dc3-center-single` monolith. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-facade-local-manager -- **Version**: 2026.5.22 ## Implementations @@ -31,16 +30,18 @@ classpath. ## Build Instructions ```bash -mvn -s ../../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-facade/dc3-common-facade-local-manager -am package +``` + +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-facade/dc3-common-facade-local-manager -am test ``` ## Related Modules - `dc3-common-facade-grpc` — gRPC alternative for distributed deployments - `dc3-common-facade-local-auth` / `-data` — sibling in-process facades - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-common/dc3-common-facade/dc3-common-facade-local/README.md b/dc3-common/dc3-common-facade/dc3-common-facade-local/README.md new file mode 100644 index 000000000..2c368264c --- /dev/null +++ b/dc3-common/dc3-common-facade/dc3-common-facade-local/README.md @@ -0,0 +1,30 @@ +# DC3 Common Facade Local + +`dc3-common-facade-local` is a dependency-only POM that aggregates every in-process facade implementation: + +- `dc3-common-facade-local-auth` +- `dc3-common-facade-local-data` +- `dc3-common-facade-local-manager` + +It contains no Java implementation sources. Use it for an all-in-one process that deliberately needs the complete local +surface. Other applications should depend on the narrowest domain-specific local facade to avoid unrelated transitive +dependencies. + +## Usage + +```xml + + io.github.pnoker + dc3-common-facade-local + +``` + +## Verification + +Verify the aggregate and its dependencies from the repository root: + +```bash +mvn -s .mvn/settings.xml -q \ + -pl dc3-common/dc3-common-facade/dc3-common-facade-local -am \ + -DskipTests compile +``` diff --git a/dc3-common/dc3-common-gateway/README.md b/dc3-common/dc3-common-gateway/README.md index 4d307dbd1..68599acf2 100644 --- a/dc3-common/dc3-common-gateway/README.md +++ b/dc3-common/dc3-common-gateway/README.md @@ -10,7 +10,6 @@ factory and supporting services that validate tokens with the Auth Center before - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-gateway -- **Version**: 2026.5.22 ## Key Components @@ -26,7 +25,9 @@ factory and supporting services that validate tokens with the Auth Center before ``` Incoming HTTP request with Authorization: Bearer {token} → AuthenticGatewayFilter - → gRPC: dc3-center-auth / TokenApi.checkTokenValid() + → FilterServiceImpl + → TokenFacade.checkValid() + → distributed mode: gRPC TokenApi.CheckValid ← token valid: inject signed X-Auth-Principal header ← token invalid: return 401 Unauthorized → Forward to backend service @@ -35,7 +36,15 @@ Incoming HTTP request with Authorization: Bearer {token} ## Build Instructions ```bash -mvn -s ../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-gateway -am package +``` + +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-gateway -am test ``` ## Related Modules @@ -43,9 +52,3 @@ mvn -s ../../.mvn/settings.xml clean package - `dc3-gateway` — Bootstraps this module - `dc3-api-auth` — gRPC contract for token validation - `dc3-center-auth` — Token validation backend - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-common/dc3-common-log/README.md b/dc3-common/dc3-common-log/README.md index d0ed74855..70596ffe0 100644 --- a/dc3-common/dc3-common-log/README.md +++ b/dc3-common/dc3-common-log/README.md @@ -2,46 +2,46 @@ ## Overview -`dc3-common-log` is the shared logging aspect module of the IoT DC3 platform. It provides a custom AOP-based `@Logs` -annotation for declarative method-level logging across all services. +`dc3-common-log` provides the shared Logback configuration used by IoT DC3 applications. It contributes console and +rolling JSON file appenders plus the Logstash Logback encoder dependency. + +The former annotation/aspect logging implementation was removed. This module does not currently register Spring +auto-configuration or provide `@Logs`, `LogsType`, or `LogsAspect` APIs. ## Module Information - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-log -- **Version**: 2026.5.22 -## Key Components +## Resources -| Component | Purpose | -|--------------|-------------------------------------------------------------------------------| -| `@Logs` | Method annotation to enable structured logging for controller/service methods | -| `LogsType` | Enum defining log types (e.g., `SysLog`, `OpLog`) | -| `LogsAspect` | Spring AOP aspect that intercepts annotated methods and records log entries | +| Resource | Purpose | +|---|---| +| `logback.xml` | Runtime console logging and size/time-based rolling JSON files | +| `logback-test.xml` | Test logging defaults | +| `AutoConfiguration.imports` | Intentionally empty; documents that no logging aspect is registered | -## Usage +Spring Boot discovers the shared `logback.xml` from the dependency classpath. Applications normally set +`logging.file.name` in their own `application.yml`; important overrides include `DC3_LOG_LEVEL`, `LOG_FILE`, +`FILE_LOG_THRESHOLD`, and the standard `LOGBACK_ROLLINGPOLICY_*` properties. -```java -@Logs(title = "Add Driver", type = LogsType.OpLog) -@PostMapping("/add") -public Mono> add(@Validated(Add.class) @RequestBody DriverVO entityVO) { - // method body -} -``` +Keep log messages in English, use parameterized placeholders, and never log credentials, tokens, passwords, or raw +private payloads. ## Build Instructions ```bash -mvn -s ../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-log -am package +``` + +## Testing + +This module has no Java implementation classes or module-specific tests. Verify packaging from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-log -am package ``` ## Related Modules -Used by controller layers in `dc3-common-auth`, `dc3-common-data`, `dc3-common-manager`. - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) - +Center, gateway, and driver applications consume the shared Logback resources through their module dependencies. diff --git a/dc3-common/dc3-common-manager/README.md b/dc3-common/dc3-common-manager/README.md index 491a14d4d..499485282 100644 --- a/dc3-common/dc3-common-manager/README.md +++ b/dc3-common/dc3-common-manager/README.md @@ -10,7 +10,6 @@ Center. It is wired into `dc3-center-manager`. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-manager -- **Version**: 2026.5.22 ## Key Components @@ -18,7 +17,7 @@ Center. It is wired into `dc3-center-manager`. |-------------------------------|-----------------------------------------------------------------------------------------------------| | Controllers | REST controllers for driver, device, profile, point, group, label, topic, etc. | | Services | `DriverService`, `DeviceService`, `ProfileService`, `PointService`, `DriverRegisterService` | -| gRPC Servers (`@GrpcService`) | `DriverDriverServer`, `DriverDeviceServer`, `DriverPointServer`, `ManagerPointServer` | +| gRPC Servers (Spring `@Service`) | `DriverDriverServer`, `DriverDeviceServer`, `DriverPointServer`, `ManagerPointServer` | | DAL Managers | `DriverManager`, `DeviceManager`, `ProfileManager`, `PointManager` (MyBatis-Plus `IService`) | | Metadata Events | `MetadataEventPublisher`, `MetadataEventListener` — async metadata change notification via RabbitMQ | | Scheduled Jobs | `ScheduleForManagerServiceImpl` — Quartz-based hourly statistics | @@ -47,7 +46,15 @@ REST: update device/point ## Build Instructions ```bash -mvn -s ../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-manager -am package +``` + +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-manager -am test ``` ## Related Modules @@ -56,10 +63,3 @@ mvn -s ../../.mvn/settings.xml clean package - `dc3-api-driver` — gRPC contracts implemented by this module - `dc3-api-manager` — Manager-side gRPC contracts implemented by this module - `dc3-common-model` — BO/VO/DTO/DO entities - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) - diff --git a/dc3-common/dc3-common-model/README.md b/dc3-common/dc3-common-model/README.md index 75c6aff35..1a553df80 100644 --- a/dc3-common/dc3-common-model/README.md +++ b/dc3-common/dc3-common-model/README.md @@ -2,24 +2,26 @@ ## Overview -`dc3-common-model` is the shared domain model module of the IoT DC3 platform. It defines all base classes, domain -entities (BO/VO/DTO/DO), validation group interfaces, and query objects used across all services and drivers. +`dc3-common-model` is the shared domain model module of the IoT DC3 platform. It defines the base BO/VO/DTO classes, +MapStruct builder contracts, JSON extension models, domain enums, validation groups, and shared transport DTOs used +across services and drivers. Persistence DO classes remain in the modules that own their database tables. ## Module Information - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-model -- **Version**: 2026.5.22 ## Key Components ### Base Classes -| Class | Purpose | -|----------|--------------------------------------------------------------------------------------------| -| `BaseBO` | Base business object — `id`, audit fields (creatorId, createTime, operatorId, operateTime) | -| `BaseDO` | Base database object (MyBatis-Plus entity with `@TableId`) | -| `BaseVO` | Base view object for REST request/response | +| Class | Purpose | +|---------------|---------------------------------------------------------------------------------------------| +| `BaseBO` | Base business object with ID, remark, and creator/operator audit fields | +| `BaseVO` | Base web view object with ID, remark, and creator/operator audit fields | +| `BaseDTO` | Base cross-process DTO with ID and audit timestamps | +| `BaseBuilder` | MapStruct conversion contract for `VO <-> BO <-> DTO` | +| `BaseExt` | Base JSON extension model used by domain-specific `*Ext` classes | ### Validation Groups @@ -32,11 +34,14 @@ Used with `@Validated(...)` in controllers: | `Select` | Marks fields for query operations | | `Read` / `Auth` | Specialized validation groups | -### Common Entities +### Shared DTOs and Extensions -- `RequestHeader.PrincipalHeader` — Carries tenant/user ID extracted from gateway-injected headers -- `Pages` — Pagination parameters (current page, page size) -- `TreeNode` — Generic tree structure for hierarchical data +- `MetadataEventDTO` — Metadata-change event transferred to driver listeners +- `PointCommandDTO` / `PointCommandResultDTO` — Point command request/result payloads +- `CommandCallDTO` / `CommandCallResultDTO` — Custom command request/result payloads +- Domain-specific `*Ext` classes — JSON extension-column shapes + +`RequestHeader`, `Pages`, `TreeNode`, `R`, and `TenantOwned` belong to `dc3-common-public`, not this module. ## Usage Example @@ -52,16 +57,17 @@ public Mono> update(@Validated(Update.class) @RequestBody DriverVO ent ## Build Instructions ```bash -mvn -s ../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-model -am package +``` + +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-model -am test ``` ## Related Modules Foundation for all `dc3-common-*`, `dc3-center-*`, and `dc3-driver-*` modules. - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) - diff --git a/dc3-common/dc3-common-mqtt/README.md b/dc3-common/dc3-common-mqtt/README.md index 92ed2d8db..33e8541ab 100644 --- a/dc3-common/dc3-common-mqtt/README.md +++ b/dc3-common/dc3-common-mqtt/README.md @@ -10,7 +10,6 @@ the MQTT driver and any service requiring MQTT connectivity. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-mqtt -- **Version**: 2026.5.22 ## Key Components @@ -49,18 +48,19 @@ MQTT driver (`dc3-driver-mqtt`) depends on this module as its primary integratio ## Build Instructions ```bash -mvn -s ../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-mqtt -am package +``` + +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-mqtt -am test ``` ## Related Modules - `dc3-driver-mqtt` — Primary consumer of this module - MQTT broker: the dev profile points at the RabbitMQ MQTT plugin (`dc3-rabbitmq:2883`); EMQX is also available via the - optional stack (`podman compose -f dc3/docker-compose-optional.yml up -d`, port `31883`) - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) - + optional stack (`make up-optional`, port `31883`) diff --git a/dc3-common/dc3-common-postgres/README.md b/dc3-common/dc3-common-postgres/README.md index 74b57bb92..c5ce0c60f 100644 --- a/dc3-common/dc3-common-postgres/README.md +++ b/dc3-common/dc3-common-postgres/README.md @@ -10,7 +10,6 @@ their primary storage. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-postgres -- **Version**: 2026.5.22 ## Key Components @@ -52,16 +51,18 @@ Each center service uses a separate Postgres schema via `currentSchema` in the J ## Build Instructions ```bash -mvn -s ../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-postgres -am package +``` + +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-postgres -am test ``` ## Related Modules - `dc3-common-manager`, `dc3-common-auth`, `dc3-common-data` — Include this as a dependency for Postgres access - `dc3-common-dal` — Builds on top of this for shared DAL entities - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-common/dc3-common-public/README.md b/dc3-common/dc3-common-public/README.md index 2a46f5fa6..34afc1f37 100644 --- a/dc3-common/dc3-common-public/README.md +++ b/dc3-common/dc3-common-public/README.md @@ -2,15 +2,14 @@ ## Overview -`dc3-common-public` is the foundational common utilities module of the IoT DC3 platform. It provides the universal -response wrapper (`R`), base entity classes, JWT key management, HTTP client configuration, and shared utility -functions used across all platform modules. +`dc3-common-public` is the foundational public contracts and utilities module of the IoT DC3 platform. It provides the +universal response wrapper (`R`), `BaseService`, shared request/pagination/tree entities, tenant markers, HTTP client +configuration, HMAC signing, and framework-neutral utility functions. ## Module Information - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-public -- **Version**: 2026.5.22 ## Key Components @@ -45,9 +44,11 @@ Fields: `ok` (boolean), `code` (String), `message` (String), `data` (T) | Utility | Purpose | |-----------------------|----------------------------------------------------------| | `JsonUtil` | Jackson JSON serialization/deserialization helpers | -| `PrincipalHeaderUtil` | Extracts `PrincipalHeader` from reactive WebFlux context | | `HostUtil` | Resolves host/IP information | -| `ResponseUtil` | Writes HTTP responses in WebFlux context | +| `PageUtil` | Converts and normalizes pagination objects | +| `HmacAuthSigner` | Signs and verifies trusted gateway principal headers | + +WebFlux-specific `BaseController`, `PrincipalHeaderUtil`, and `ResponseUtil` belong to `dc3-common-web`. ### HTTP Client @@ -79,15 +80,17 @@ Secret lookup order: ## Build Instructions ```bash -mvn -s ../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-public -am package +``` + +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-public -am test ``` ## Related Modules Foundation for all `dc3-common-*`, `dc3-center-*`, and `dc3-driver-*` modules. - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-common/dc3-common-quartz/README.md b/dc3-common/dc3-common-quartz/README.md index ae0923b97..54965e812 100644 --- a/dc3-common/dc3-common-quartz/README.md +++ b/dc3-common/dc3-common-quartz/README.md @@ -10,7 +10,6 @@ and Driver modules for periodic tasks. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-quartz -- **Version**: 2026.5.22 ## Key Components @@ -35,15 +34,17 @@ quartzService.startScheduler(); ## Build Instructions ```bash -mvn -s ../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-quartz -am package +``` + +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-quartz -am test ``` ## Related Modules - `dc3-common-manager` — Uses `QuartzService` for hourly data-volume statistics jobs - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-common/dc3-common-rabbitmq/README.md b/dc3-common/dc3-common-rabbitmq/README.md index 5116fb7ab..08df4ef3f 100644 --- a/dc3-common/dc3-common-rabbitmq/README.md +++ b/dc3-common/dc3-common-rabbitmq/README.md @@ -2,34 +2,40 @@ ## Overview -`dc3-common-rabbitmq` is the shared RabbitMQ configuration module of the IoT DC3 platform. It defines all topic -exchanges, queue bindings, and connection configuration used for asynchronous communication between services and -drivers. +`dc3-common-rabbitmq` is the shared RabbitMQ infrastructure module of the IoT DC3 platform. It defines the durable +platform exchanges, connection factory, message conversion, and profile activation used by services and drivers. +Domain modules own their queues and bindings. ## Module Information - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-rabbitmq -- **Version**: 2026.5.22 ## Key Components | Component | Purpose | |-----------------------------|----------------------------------------------------------------------| -| `ExchangeConfig` | Declares all 5 topic exchanges as persistent Spring beans | +| `ExchangeConfig` | Declares the shared durable topic exchanges | | `RabbitConfig` | Connection factory and Jackson-based message converter configuration | -| `RabbitmqEnvironmentConfig` | Binds RabbitMQ connection properties from environment variables | -| `ActiveRabbitProfileConfig` | Profile-conditional activation | +| `RabbitmqEnvironmentConfig` | Loads RabbitMQ environment defaults | +| `ActiveRabbitProfileConfig` | Activates the `rabbit` profile unless explicitly disabled | ## Topic Exchanges -| Exchange Bean | Exchange Name | Purpose | -|--------------------|------------------|---------------------------------------------| -| `eventExchange` | `dc3.e.event` | Driver/device status events (load-balanced) | -| `metadataExchange` | `dc3.e.metadata` | Metadata change broadcast to drivers | -| `commandExchange` | `dc3.e.command` | Commands from data service to drivers | -| `valueExchange` | `dc3.e.value` | Point values from drivers to data center | -| `mqttExchange` | `dc3.e.mqtt` | MQTT-to-platform message bridging | +| Exchange bean(s) | Base exchange name(s) | Purpose | +|---|---|---| +| `stateExchange`, `alarmExchange` | `dc3.e.state`, `dc3.e.alarm` | Driver/device state and alarm processing | +| `metadataExchange` | `dc3.e.metadata` | Metadata change broadcast to drivers | +| `pointCommandExchange` | `dc3.e.point_command` | Point read/write commands | +| `valueExchange` | `dc3.e.value` | Point values from drivers to Data Center | +| `mqttExchange` | `dc3.e.mqtt` | MQTT-to-platform message bridging | +| `stateTimeoutDelayExchange`, `stateTimeoutCheckExchange` | `dc3.e.state_timeout_delay`, `dc3.e.state_timeout_check` | Delayed state-timeout checks | +| `commandExchange`, `commandResultExchange`, `commandDeadExchange` | `dc3.e.command`, `dc3.e.command_result`, `dc3.e.command_dead` | Custom commands, results, and dead letters | +| `eventExchange` | `dc3.e.event` | Reported domain events | + +`ExchangeConfig` currently declares 12 shared exchanges. Data and driver modules add queues, bindings, and specialized +dead-letter/result exchanges. The optional `dc3.rabbit.tag` system property prefixes runtime names, so use +`RabbitConstant` rather than duplicating literal names in code. ## Configuration Properties @@ -56,18 +62,20 @@ and set Spring Boot's native `spring.rabbitmq.ssl.trust-store`, `trust-store-typ ## Build Instructions ```bash -mvn -s ../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-rabbitmq -am package +``` + +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-rabbitmq -am test ``` ## Related Modules - `dc3-common-constant` / `RabbitConstant` — All exchange/queue/routing key names -- `dc3-common-data` — Consumes `dc3.e.value`, publishes to `dc3.e.command` +- `dc3-common-data` — Consumes values/state/events and publishes point/custom commands - `dc3-common-manager` — Publishes to `dc3.e.metadata` -- `dc3-common-driver` — Consumes from `dc3.e.metadata`, `dc3.e.command`; publishes to `dc3.e.value` - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) +- `dc3-common-driver` — Consumes metadata and point/custom commands; publishes values and command results diff --git a/dc3-common/dc3-common-repository/README.md b/dc3-common/dc3-common-repository/README.md index 870a12a2f..88415dc71 100644 --- a/dc3-common/dc3-common-repository/README.md +++ b/dc3-common/dc3-common-repository/README.md @@ -10,7 +10,6 @@ backends without coupling business logic to a specific storage implementation. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-repository -- **Version**: 2026.5.22 ## Key Components @@ -51,16 +50,18 @@ Set `dc3.repository.auto-profile=false` to opt out of automatic `repository` pro ## Build Instructions ```bash -mvn -s ../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-repository -am package +``` + +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-repository -am test ``` ## Related Modules - `dc3-common-data` — Uses `RepositoryStrategyFactory` to route point-value persistence operations -- `dc3-common-data` — Caches latest point values with in-process `LocalCacheService` alongside repository storage - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) +- `dc3-common-data` — Caches latest point values with `PointValueLocalCache` alongside repository storage diff --git a/dc3-common/dc3-common-resource-registrar/README.md b/dc3-common/dc3-common-resource-registrar/README.md index 1029c0d75..1dbcd0de1 100644 --- a/dc3-common/dc3-common-resource-registrar/README.md +++ b/dc3-common/dc3-common-resource-registrar/README.md @@ -10,7 +10,6 @@ deployed, so permissions can be granted against real endpoints. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-resource-registrar -- **Version**: 2026.5.22 ## Key Components @@ -34,16 +33,18 @@ gRPC or in-process facade transport. ## Build Instructions ```bash -mvn -s ../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-resource-registrar -am package +``` + +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-resource-registrar -am test ``` ## Related Modules - `dc3-center-*` — include this module to register their API resources - `dc3-common-auth` — owns the resource registry on the receiving side - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-common/dc3-common-sql/README.md b/dc3-common/dc3-common-sql/README.md index abfa048b0..8bbf29ae7 100644 --- a/dc3-common/dc3-common-sql/README.md +++ b/dc3-common/dc3-common-sql/README.md @@ -10,7 +10,6 @@ and query execution, so each database driver only supplies its dialect/connectio - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-sql -- **Version**: 2026.5.22 ## Key Components @@ -26,16 +25,18 @@ and query execution, so each database driver only supplies its dialect/connectio ## Build Instructions ```bash -mvn -s ../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-sql -am package +``` + +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-sql -am test ``` ## Related Modules - `dc3-driver-mysql`, `dc3-driver-oracle`, `dc3-driver-postgresql`, `dc3-driver-sqlserver` — JDBC drivers that extend `AbstractJdbcDriverCustomService` - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-common/dc3-common-test/README.md b/dc3-common/dc3-common-test/README.md index 4cacb8cba..1101b5392 100644 --- a/dc3-common/dc3-common-test/README.md +++ b/dc3-common/dc3-common-test/README.md @@ -10,7 +10,6 @@ fixtures. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-test -- **Version**: 2026.5.22 ## Key Components @@ -27,21 +26,24 @@ fixtures. ## Usage Add as a `test`-scoped dependency. Integration tests requiring real infrastructure use the Testcontainers helpers -(PostgreSQL + TimescaleDB, RabbitMQ, MQTT), which need a running container runtime (`podman`). +(PostgreSQL + TimescaleDB, RabbitMQ, MQTT), which need a Docker-compatible container runtime. ## Build Instructions ```bash -mvn -s ../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-test -am package +``` + +## Testing + +This module currently has no module-specific automated tests. Verify generated or production sources by compiling the +affected reactor from the repository root: + +```bash +mvn -s .mvn/settings.xml -q -pl dc3-common/dc3-common-test -am -DskipTests compile ``` ## Related Modules - `dc3-e2e` — backend end-to-end suite built on these helpers - Consumed test-scoped by `dc3-common-*` and `dc3-center-*` modules - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-common/dc3-common-thread/README.md b/dc3-common/dc3-common-thread/README.md index 6ec106221..71b5c68ce 100644 --- a/dc3-common/dc3-common-thread/README.md +++ b/dc3-common/dc3-common-thread/README.md @@ -10,7 +10,6 @@ concurrent point reads and batch message handling. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-thread -- **Version**: 2026.5.22 ## Key Components @@ -33,8 +32,8 @@ dc3: ## Usage -Inject the executor you need, e.g. `private final ExecutorService virtualThreadExecutor;` in `PointValueJob` / -`MqttScheduleJob`, or `private final ThreadPoolExecutor threadPoolExecutor;` in `DriverReadScheduleJob`. +Inject the executor you need, for example `virtualThreadExecutor` in `MqttScheduleJob`, or `threadPoolExecutor` in +`DriverReadScheduleJob`. Data services also inject the shared executors for concurrent persistence and message work. > Note: Spring's `@Async` does **not** use these beans — it runs on Spring Boot's default `applicationTaskExecutor`. > These executors are obtained by explicit constructor injection, not via `@Async`. @@ -42,7 +41,15 @@ Inject the executor you need, e.g. `private final ExecutorService virtualThreadE ## Build Instructions ```bash -mvn -s ../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-thread -am package +``` + +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-thread -am test ``` ## Related Modules @@ -50,10 +57,3 @@ mvn -s ../../.mvn/settings.xml clean package - `dc3-common-data` / `dc3-common-mqtt` — inject `virtualThreadExecutor` for batch persistence / message handling - `dc3-common-driver` — injects `threadPoolExecutor` for concurrent device reads - `dc3-driver-opc-da` — injects `scheduledThreadPoolExecutor` - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) - diff --git a/dc3-common/dc3-common-web/README.md b/dc3-common/dc3-common-web/README.md index b2182b627..70486a1fa 100644 --- a/dc3-common/dc3-common-web/README.md +++ b/dc3-common/dc3-common-web/README.md @@ -10,16 +10,16 @@ REST-based center services. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-common-web -- **Version**: 2026.5.22 ## Key Components -| Component | Purpose | -|-------------------|--------------------------------------------------------------------------------------| -| `WebFluxConfig` | Global WebFlux configuration (codecs, CORS, message converters) | -| `ExceptionConfig` | `@ControllerAdvice` global exception handler mapping exceptions to `R` responses | -| `WebFilterConfig` | Registers global web filters (e.g., request logging, context enrichment) | -| `ResponseUtil` | Utilities for writing non-controller `ServerHttpResponse` bodies in reactive context | +| Component | Purpose | +|-------------------------|--------------------------------------------------------------------------------------| +| `WebFluxConfig` | Global WebFlux configuration (codecs, CORS, message converters) | +| `WebFluxSecurityConfig` | Security chain, public-path rules, and facade-backed authorization | +| `RequestIdWebFilter` | Adds and propagates request IDs for tracing | +| `ExceptionConfig` | `@ControllerAdvice` global exception handler mapping exceptions to `R` responses | +| `ResponseUtil` | Utilities for writing non-controller `ServerHttpResponse` bodies in reactive context | ## Exception Handling @@ -36,17 +36,18 @@ All exceptions thrown by controllers are caught by `ExceptionConfig` and mapped ## Build Instructions ```bash -mvn -s ../../.mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-web -am package +``` + +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-web -am test ``` ## Related Modules - `dc3-common-auth`, `dc3-common-data`, `dc3-common-manager` — All include this for reactive web support - `dc3-common-public` — Provides `R` response wrapper - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) - diff --git a/dc3-coverage/README.md b/dc3-coverage/README.md new file mode 100644 index 000000000..6ecf273b9 --- /dev/null +++ b/dc3-coverage/README.md @@ -0,0 +1,38 @@ +# DC3 Coverage + +`dc3-coverage` is a report-only Maven module. It aggregates JaCoCo execution data from the covered handwritten-code +modules and applies the repository's absolute coverage gate. + +## Generate and Verify the Report + +From the repository root: + +```bash +make coverage +``` + +Equivalent Maven command: + +```bash +mvn -s .mvn/settings.xml -B -Dmaven.test.skip=false -pl dc3-coverage -am verify +``` + +Outputs: + +- HTML: `dc3-coverage/target/site/jacoco-aggregate/index.html` +- XML: `dc3-coverage/target/site/jacoco-aggregate/jacoco.xml` + +## Gate + +The minimum line and branch ratios are configured in this module's `pom.xml`. The verify phase passes the aggregate XML +to `scripts/check_coverage.py`, which checks those absolute thresholds. + +There is currently no baseline-relative regression calculation. Do not describe the build as enforcing a percentage +drop against a previous commit unless such a comparison is implemented. + +Use `-Dcoverage.check.skip=true` only for local diagnosis; do not disable the gate in normal CI or release validation. + +## Adding covered modules + +Add a dependency in `pom.xml` only for a module whose handwritten classes should contribute to the aggregate. Generated +API artifacts and deployment-only wrappers should remain excluded unless the coverage policy changes deliberately. diff --git a/dc3-driver/README.md b/dc3-driver/README.md new file mode 100644 index 000000000..0bc28149c --- /dev/null +++ b/dc3-driver/README.md @@ -0,0 +1,47 @@ +# DC3 Drivers + +`dc3-driver` contains protocol adapters built on `dc3-common-driver`. Each driver owns protocol I/O and user-facing +attribute metadata; the SDK owns registration, scheduling, metadata refresh, health integration, commands, and value +dispatch. + +## Modules + +| Family | Modules | +|---|---| +| Industrial protocols | `bacnet-ip`, `can`, `dlms`, `ethernet-ip`, `fins`, `iec104`, `melsec`, `modbus-rtu`, `modbus-tcp`, `opc-da`, `opc-ua`, `plcs7`, `sl651`, `snmp` | +| Messaging/network | `coap`, `http`, `lwm2m`, `mqtt`, `tcp-udp` | +| Databases | `mysql`, `oracle`, `postgresql`, `sqlserver` | +| Local/device buses | `ble`, `serial`, `zigbee` | +| Simulation | `virtual`, `listening-virtual` | + +The following drivers currently declare incomplete protocol I/O and must be treated as work in progress: `can`, `dlms`, +`ethernet-ip`, `iec104`, `lwm2m`, `mqtt`, `opc-da`, and `zigbee`. Check the child README and implementation before +production use. + +## Driver metadata + +`src/main/resources/application.yml` is authoritative for: + +- stable driver `code` and client/server `type`; +- driver, point, command, and event attribute codes/types/defaults; +- scheduling and health defaults; +- local buffering configuration. + +Changing a driver code requires a metadata and RabbitMQ routing migration. Keep display names and remarks in English. + +## Build and run + +```bash +mvn -s .mvn/settings.xml -q -f dc3-driver/pom.xml -DskipTests compile +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-modbus-tcp -am test +make run SERVICE=modbus-tcp +``` + +Replace `modbus-tcp` with the desired driver service. A runnable driver also needs database/messaging infrastructure and +the required center services; use the root Makefile to start the appropriate stack. + +## Child README requirements + +Every driver README should document readiness, prerequisites, the supported attribute surface, read/write operations, +a focused test command, limitations, and any host/container device requirements. Include exact codes/defaults when they +help operators, but treat `application.yml` as the authoritative metadata definition. diff --git a/dc3-driver/dc3-driver-bacnet-ip/README.md b/dc3-driver/dc3-driver-bacnet-ip/README.md index c468aa290..7572c8967 100644 --- a/dc3-driver/dc3-driver-bacnet-ip/README.md +++ b/dc3-driver/dc3-driver-bacnet-ip/README.md @@ -10,7 +10,6 @@ number, object type, object instance, and property identifier. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-bacnet-ip -- **Version**: 2026.5.22 - **Driver Name**: BACnet IP Driver ## Driver Attributes (Device-level) @@ -41,6 +40,9 @@ number, object type, object instance, and property identifier. | Object Instance | Object instance number | | Property ID | Property identifier | +The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and +local buffering. Keep this README aligned when those user-facing settings change. + ## Prerequisites A reachable BACnet/IP device (or simulator) on the network. Communication uses UDP, typically on port 47808. @@ -50,23 +52,25 @@ A reachable BACnet/IP device (or simulator) on the network. Communication uses U ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-bacnet-ip -am package java -jar dc3-driver/dc3-driver-bacnet-ip/target/dc3-driver-bacnet-ip.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-bacnet-ip -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-driver/dc3-driver-ble/README.md b/dc3-driver/dc3-driver-ble/README.md index f34e5b9d0..14f09e531 100644 --- a/dc3-driver/dc3-driver-ble/README.md +++ b/dc3-driver/dc3-driver-ble/README.md @@ -10,7 +10,6 @@ characteristics. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-ble -- **Version**: 2026.5.22 - **Driver Name**: Bluetooth LE Driver ## Driver Attributes (Device-level) @@ -37,6 +36,9 @@ characteristics. | Service UUID | GATT Service UUID | | Characteristic UUID | GATT Characteristic UUID for writing | +The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and +local buffering. Keep this README aligned when those user-facing settings change. + ## Prerequisites A host with a Bluetooth adapter and the TinyB native library available, plus a reachable BLE peripheral exposing the @@ -47,23 +49,25 @@ configured GATT service and characteristics. ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-ble -am package java -jar dc3-driver/dc3-driver-ble/target/dc3-driver-ble.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-ble -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-driver/dc3-driver-can/README.md b/dc3-driver/dc3-driver-can/README.md index 2271480d5..af6a5a03c 100644 --- a/dc3-driver/dc3-driver-can/README.md +++ b/dc3-driver/dc3-driver-can/README.md @@ -15,7 +15,6 @@ SocketCAN interface, parsing frame payloads into device point values and sending - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-can -- **Version**: 2026.5.22 - **Driver Name**: CAN Bus Driver ## Driver Attributes (Device-level) @@ -45,6 +44,9 @@ SocketCAN interface, parsing frame payloads into device point values and sending | CAN ID | CAN identifier to write to | | Data | Frame data (supports `${value}`) | +The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and +local buffering. Keep this README aligned when those user-facing settings change. + ## Prerequisites A Linux host with an available SocketCAN interface (e.g. `can0`) and the `can-utils` package installed (`candump`, @@ -55,23 +57,25 @@ A Linux host with an available SocketCAN interface (e.g. `can0`) and the `can-ut ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-can -am package java -jar dc3-driver/dc3-driver-can/target/dc3-driver-can.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-can -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-driver/dc3-driver-coap/README.md b/dc3-driver/dc3-driver-coap/README.md index acc09a1f1..edb7bbf20 100644 --- a/dc3-driver/dc3-driver-coap/README.md +++ b/dc3-driver/dc3-driver-coap/README.md @@ -10,7 +10,6 @@ resource path and the write path performs CoAP PUT requests. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-coap -- **Version**: 2026.5.22 - **Driver Name**: CoAP Driver ## Driver Attributes (Device-level) @@ -28,6 +27,9 @@ resource path and the write path performs CoAP PUT requests. | Write Path | CoAP resource path for writing point data | | Content Format | Content format: json, text, cbor, octet-stream | +The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and +local buffering. Keep this README aligned when those user-facing settings change. + ## Prerequisites A reachable CoAP device (or simulator) exposing the configured resource paths. CoAP commonly uses UDP port 5683. @@ -37,23 +39,25 @@ A reachable CoAP device (or simulator) exposing the configured resource paths. C ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-coap -am package java -jar dc3-driver/dc3-driver-coap/target/dc3-driver-coap.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-coap -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-driver/dc3-driver-dlms/README.md b/dc3-driver/dc3-driver-dlms/README.md index 0d0fe5521..e4bfba6dc 100644 --- a/dc3-driver/dc3-driver-dlms/README.md +++ b/dc3-driver/dc3-driver-dlms/README.md @@ -17,7 +17,6 @@ and decode DLMS frames. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-dlms -- **Version**: 2026.5.22 - **Driver Name**: DLMS/COSEM Driver ## Driver Attributes (Device-level) @@ -42,6 +41,9 @@ and decode DLMS frames. | Logical Name | Object logical name / OBIS code (e.g. 1.0.1.8.0.255) | | Attribute ID | Attribute ID (2 = Present Value) | +The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and +local buffering. Keep this README aligned when those user-facing settings change. + ## Prerequisites A reachable DLMS/COSEM device (or simulator) over TCP (default port 4059) or serial, plus the matching client/ server @@ -52,23 +54,25 @@ addresses and authentication settings. ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-dlms -am package java -jar dc3-driver/dc3-driver-dlms/target/dc3-driver-dlms.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-dlms -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-driver/dc3-driver-ethernet-ip/README.md b/dc3-driver/dc3-driver-ethernet-ip/README.md index 947e8980e..1f10c45cb 100644 --- a/dc3-driver/dc3-driver-ethernet-ip/README.md +++ b/dc3-driver/dc3-driver-ethernet-ip/README.md @@ -17,7 +17,6 @@ services. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-ethernet-ip -- **Version**: 2026.5.22 - **Driver Name**: EtherNet/IP Driver ## Driver Attributes (Device-level) @@ -43,6 +42,9 @@ services. |--------------|--------------------------------------| | Send Command | Value to write (supports `${value}`) | +The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and +local buffering. Keep this README aligned when those user-facing settings change. + ## Prerequisites A reachable Rockwell Allen-Bradley (or compatible) EtherNet/IP PLC, typically on TCP port 44818. @@ -52,23 +54,25 @@ A reachable Rockwell Allen-Bradley (or compatible) EtherNet/IP PLC, typically on ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-ethernet-ip -am package java -jar dc3-driver/dc3-driver-ethernet-ip/target/dc3-driver-ethernet-ip.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-ethernet-ip -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-driver/dc3-driver-fins/README.md b/dc3-driver/dc3-driver-fins/README.md index 6cbbeb40d..b2985c8b0 100644 --- a/dc3-driver/dc3-driver-fins/README.md +++ b/dc3-driver/dc3-driver-fins/README.md @@ -10,7 +10,6 @@ supports the D, W, H, and C memory areas. No external protocol library is used. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-fins -- **Version**: 2026.5.22 - **Driver Name**: Omron FINS Driver ## Driver Attributes (Device-level) @@ -43,6 +42,9 @@ supports the D, W, H, and C memory areas. No external protocol library is used. | Address | Word address within the area | | Data Type | Value data type | +The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and +local buffering. Keep this README aligned when those user-facing settings change. + ## Prerequisites A reachable Omron PLC speaking FINS over TCP, typically on port 9600. @@ -52,23 +54,25 @@ A reachable Omron PLC speaking FINS over TCP, typically on port 9600. ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-fins -am package java -jar dc3-driver/dc3-driver-fins/target/dc3-driver-fins.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-fins -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-driver/dc3-driver-http/README.md b/dc3-driver/dc3-driver-http/README.md index 2ee730b25..de0a2eaef 100644 --- a/dc3-driver/dc3-driver-http/README.md +++ b/dc3-driver/dc3-driver-http/README.md @@ -10,7 +10,6 @@ via request body templates containing a `${value}` placeholder. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-http -- **Version**: 2026.5.22 - **Driver Name**: HTTP REST Client Driver ## Driver Attributes (Device-level) @@ -38,6 +37,9 @@ via request body templates containing a `${value}` placeholder. | Path | API path for command | | Method | HTTP method for command | +The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and +local buffering. Keep this README aligned when those user-facing settings change. + ## Prerequisites A reachable HTTP/REST endpoint that the driver can call as configured via the device's Base URL and point paths. @@ -47,23 +49,25 @@ A reachable HTTP/REST endpoint that the driver can call as configured via the de ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-http -am package java -jar dc3-driver/dc3-driver-http/target/dc3-driver-http.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-http -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-driver/dc3-driver-iec104/README.md b/dc3-driver/dc3-driver-iec104/README.md index de21bb40f..1b1eb25cc 100644 --- a/dc3-driver/dc3-driver-iec104/README.md +++ b/dc3-driver/dc3-driver-iec104/README.md @@ -16,7 +16,6 @@ polling for IEC 104 client connections. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-iec104 -- **Version**: 2026.5.22 - **Driver Name**: IEC 104 Driver ## Driver Attributes (Device-level) @@ -44,6 +43,9 @@ polling for IEC 104 client connections. |--------------|-------------| | Send Command | | +The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and +local buffering. Keep this README aligned when those user-facing settings change. + ## Prerequisites A reachable IEC 60870-5-104 server (substation/telecontrol device or simulator) addressable by the configured host and @@ -54,23 +56,25 @@ port. ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-iec104 -am package java -jar dc3-driver/dc3-driver-iec104/target/dc3-driver-iec104.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-iec104 -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-driver/dc3-driver-listening-virtual/README.md b/dc3-driver/dc3-driver-listening-virtual/README.md index f8c1a2260..33203f507 100644 --- a/dc3-driver/dc3-driver-listening-virtual/README.md +++ b/dc3-driver/dc3-driver-listening-virtual/README.md @@ -10,7 +10,6 @@ patterns supporting both TCP and UDP transports. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-listening-virtual -- **Version**: 2026.5.22 - **Driver Name**: Listening Virtual TCP/UDP Driver ## Service Ports @@ -31,28 +30,33 @@ patterns supporting both TCP and UDP transports. This driver declares no device-level driver attributes; all configuration is per-point. +The module `application.yml` and its profile-specific variants are authoritative for attribute codes, types, default +values, scheduling, health, and local buffering. Keep this README aligned when that metadata changes. + ## Running Locally ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-listening-virtual -am package java -jar dc3-driver/dc3-driver-listening-virtual/target/dc3-driver-listening-virtual.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-listening-virtual -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration and RabbitMQ integration - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-driver/dc3-driver-lwm2m/README.md b/dc3-driver/dc3-driver-lwm2m/README.md index b1d3e09fd..7a81f6600 100644 --- a/dc3-driver/dc3-driver-lwm2m/README.md +++ b/dc3-driver/dc3-driver-lwm2m/README.md @@ -14,7 +14,6 @@ Instance / Resource ID. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-lwm2m -- **Version**: 2026.5.22 - **Driver Name**: LwM2M Driver ## Driver Attributes (Device-level) @@ -38,6 +37,9 @@ Instance / Resource ID. | Resource ID | LwM2M Resource ID (e.g. 5700=Sensor Value) | | Observe | Enable LwM2M Observe: true, false | +The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and +local buffering. Keep this README aligned when those user-facing settings change. + ## Prerequisites LwM2M client devices that register with the embedded Leshan server. The server binds to the configured `Server Host` / @@ -48,23 +50,25 @@ LwM2M client devices that register with the embedded Leshan server. The server b ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-lwm2m -am package java -jar dc3-driver/dc3-driver-lwm2m/target/dc3-driver-lwm2m.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-lwm2m -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-driver/dc3-driver-melsec/README.md b/dc3-driver/dc3-driver-melsec/README.md index 93ca761cc..00db51f48 100644 --- a/dc3-driver/dc3-driver-melsec/README.md +++ b/dc3-driver/dc3-driver-melsec/README.md @@ -10,7 +10,6 @@ the MC protocol using the `iot-communication` library, reading and writing devic - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-melsec -- **Version**: 2026.5.22 - **Driver Name**: Mitsubishi Melsec Driver ## Driver Attributes (Device-level) @@ -28,6 +27,9 @@ the MC protocol using the `iot-communication` library, reading and writing devic | Device Address | Device memory address (D100, M0, X10, W200 etc.) | | String Length | String read length (0 for non-string types) | +The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and +local buffering. Keep this README aligned when those user-facing settings change. + ## Prerequisites A reachable Mitsubishi Melsec PLC (or simulator) exposing the MC protocol over TCP, addressable by the configured host @@ -38,23 +40,25 @@ and port. ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-melsec -am package java -jar dc3-driver/dc3-driver-melsec/target/dc3-driver-melsec.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-melsec -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-driver/dc3-driver-modbus-rtu/README.md b/dc3-driver/dc3-driver-modbus-rtu/README.md index 4e251b62f..a1b133320 100644 --- a/dc3-driver/dc3-driver-modbus-rtu/README.md +++ b/dc3-driver/dc3-driver-modbus-rtu/README.md @@ -10,7 +10,6 @@ values to coils and holding registers. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-modbus-rtu -- **Version**: 2026.5.22 - **Driver Name**: Modbus RTU Driver ## Driver Attributes (Device-level) @@ -40,6 +39,9 @@ values to coils and holding registers. | Offset | Register or coil address offset | | Value Template | Value template rendered with command params | +The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and +local buffering. Keep this README aligned when those user-facing settings change. + ## Prerequisites A Modbus RTU slave device connected to an accessible serial port (e.g. `/dev/ttyUSB0`, `COM3`) on the host running the @@ -50,23 +52,25 @@ driver. ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-modbus-rtu -am package java -jar dc3-driver/dc3-driver-modbus-rtu/target/dc3-driver-modbus-rtu.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-modbus-rtu -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-driver/dc3-driver-modbus-tcp/README.md b/dc3-driver/dc3-driver-modbus-tcp/README.md index 889b83d63..6049e738d 100644 --- a/dc3-driver/dc3-driver-modbus-tcp/README.md +++ b/dc3-driver/dc3-driver-modbus-tcp/README.md @@ -9,7 +9,6 @@ devices, reads coil/register values periodically, and supports write commands fo - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-modbus-tcp -- **Version**: 2026.5.22 - **Driver Name**: Modbus TCP Driver ## Driver Attributes (Device-level) @@ -36,6 +35,9 @@ devices, reads coil/register values periodically, and supports write commands fo | Offset | Register/coil address offset | | Value Template | Template for the value to write | +The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and +local buffering. Keep this README aligned when those user-facing settings change. + ## Prerequisites A running Modbus TCP slave device or simulator accessible on the network. @@ -45,23 +47,25 @@ A running Modbus TCP slave device or simulator accessible on the network. ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-modbus-tcp -am package java -jar dc3-driver/dc3-driver-modbus-tcp/target/dc3-driver-modbus-tcp.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-modbus-tcp -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-driver/dc3-driver-mqtt/README.md b/dc3-driver/dc3-driver-mqtt/README.md index 85cd6c414..076aad156 100644 --- a/dc3-driver/dc3-driver-mqtt/README.md +++ b/dc3-driver/dc3-driver-mqtt/README.md @@ -13,7 +13,6 @@ topics, parse incoming payloads as device point values, and forward commands to - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-mqtt -- **Version**: 2026.5.22 - **Driver Name**: MQTT Driver ## Point Attributes @@ -39,13 +38,16 @@ topics, parse incoming payloads as device point values, and forward commands to | Event Code Path | Path to the event code in payload | | Payload Path | Path to the event payload | +The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and +local buffering. Keep this README aligned when those user-facing settings change. + ## Prerequisites An MQTT broker must be running. The dev profile connects to the RabbitMQ MQTT plugin (`dc3-rabbitmq:2883`), which ships with the base stack: ```bash -podman compose -f dc3/docker-compose-db.yml up -d +make up-db ``` EMQX is available as an alternative via the optional stack (`docker-compose-optional.yml`, port `31883`); point @@ -56,24 +58,26 @@ EMQX is available as an alternative via the optional stack (`docker-compose-opti ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-mqtt -am package java -jar dc3-driver/dc3-driver-mqtt/target/dc3-driver-mqtt.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-mqtt -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration and RabbitMQ integration - `dc3-common-mqtt` — MQTT client configuration and utilities - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-driver/dc3-driver-mysql/README.md b/dc3-driver/dc3-driver-mysql/README.md index eddbcd254..e36b4852b 100644 --- a/dc3-driver/dc3-driver-mysql/README.md +++ b/dc3-driver/dc3-driver-mysql/README.md @@ -10,7 +10,6 @@ - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-mysql -- **Version**: 2026.5.22 - **Driver Name**: MySQL Driver ## Driver Attributes (Device-level) @@ -37,6 +36,9 @@ |---------------|----------------------------------| | Execute Query | SQL query to execute for command | +The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and +local buffering. Keep this README aligned when those user-facing settings change. + ## Prerequisites A reachable MySQL database addressable by the configured host, port, and credentials. @@ -46,24 +48,26 @@ A reachable MySQL database addressable by the configured host, port, and credent ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-mysql -am package java -jar dc3-driver/dc3-driver-mysql/target/dc3-driver-mysql.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-mysql -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration - `dc3-common-sql` — Abstract JDBC driver service (connection pooling, read/write query execution) - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-driver/dc3-driver-opc-da/README.md b/dc3-driver/dc3-driver-opc-da/README.md index 2f2829e79..27a95258b 100644 --- a/dc3-driver/dc3-driver-opc-da/README.md +++ b/dc3-driver/dc3-driver-opc-da/README.md @@ -5,11 +5,14 @@ `dc3-driver-opc-da` is the OPC DA (Data Access) protocol driver of the IoT DC3 platform. It connects to OPC DA servers using DCOM/J-Interop to read real-time process data from OPC-compliant industrial devices and SCADA systems. +> **Work in progress.** Protocol-level I/O is not fully implemented in `OpcDaDriverCustomServiceImpl`. Treat this +> module as an integration skeleton, not a production-ready OPC DA driver, until its read/write TODOs are completed and +> verified against a real server. + ## Module Information - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-opc-da -- **Version**: 2026.5.22 - **Driver Name**: OPC DA Driver ## Driver Attributes (Device-level) @@ -28,6 +31,9 @@ using DCOM/J-Interop to read real-time process data from OPC-compliant industria | Group | OPC DA item group name | | Tag | OPC DA item tag name | +The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and +local buffering. Keep this README aligned when those user-facing settings change. + ## Prerequisites - An OPC DA server running on a Windows host accessible via DCOM @@ -39,23 +45,25 @@ using DCOM/J-Interop to read real-time process data from OPC-compliant industria ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-opc-da -am package java -jar dc3-driver/dc3-driver-opc-da/target/dc3-driver-opc-da.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-opc-da -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-driver/dc3-driver-opc-ua/README.md b/dc3-driver/dc3-driver-opc-ua/README.md index ad82bffe7..5ff5f4e4e 100644 --- a/dc3-driver/dc3-driver-opc-ua/README.md +++ b/dc3-driver/dc3-driver-opc-ua/README.md @@ -9,7 +9,6 @@ servers to read and write node values from industrial automation systems using t - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-opc-ua -- **Version**: 2026.5.22 - **Driver Name**: OPC UA Driver ## Driver Attributes (Device-level) @@ -27,6 +26,9 @@ servers to read and write node values from industrial automation systems using t | Namespace | OPC UA node namespace index | | Tag | OPC UA node identifier | +The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and +local buffering. Keep this README aligned when those user-facing settings change. + ## Prerequisites An OPC UA server (e.g., Milo server, Prosys OPC UA Simulation Server) accessible on the network. @@ -36,23 +38,25 @@ An OPC UA server (e.g., Milo server, Prosys OPC UA Simulation Server) accessible ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-opc-ua -am package java -jar dc3-driver/dc3-driver-opc-ua/target/dc3-driver-opc-ua.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-opc-ua -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-driver/dc3-driver-oracle/README.md b/dc3-driver/dc3-driver-oracle/README.md index 7c4eace47..a21d780d9 100644 --- a/dc3-driver/dc3-driver-oracle/README.md +++ b/dc3-driver/dc3-driver-oracle/README.md @@ -11,7 +11,6 @@ queries and writes through configured `UPDATE`/`INSERT` queries. JDBC connection - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-oracle -- **Version**: 2026.5.22 - **Driver Name**: Oracle Driver ## Driver Attributes (Device-level) @@ -41,6 +40,9 @@ queries and writes through configured `UPDATE`/`INSERT` queries. JDBC connection |---------------|----------------------------------| | Execute Query | SQL query to execute for command | +The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and +local buffering. Keep this README aligned when those user-facing settings change. + ## Prerequisites A reachable Oracle database addressable by the configured host, port, credentials, and connection type (SID or Service @@ -51,24 +53,26 @@ Name). ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-oracle -am package java -jar dc3-driver/dc3-driver-oracle/target/dc3-driver-oracle.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-oracle -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration - `dc3-common-sql` — Abstract JDBC driver service (connection pooling, read/write query execution) - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-driver/dc3-driver-plcs7/README.md b/dc3-driver/dc3-driver-plcs7/README.md index 1b8f383c5..e5d20ac76 100644 --- a/dc3-driver/dc3-driver-plcs7/README.md +++ b/dc3-driver/dc3-driver-plcs7/README.md @@ -9,7 +9,6 @@ - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-plcs7 -- **Version**: 2026.5.22 - **Driver Name**: PLC S7 Driver ## Driver Attributes (Device-level) @@ -28,6 +27,9 @@ | Byte Offset | Byte offset within the data block | | Bit Offset | Bit offset within the byte (for boolean points) | +The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and +local buffering. Keep this README aligned when those user-facing settings change. + ## Prerequisites - Siemens S7 PLC (S7-200 Smart, S7-1200, S7-1500 or compatible) @@ -39,23 +41,25 @@ ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-plcs7 -am package java -jar dc3-driver/dc3-driver-plcs7/target/dc3-driver-plcs7.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-plcs7 -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-driver/dc3-driver-postgresql/README.md b/dc3-driver/dc3-driver-postgresql/README.md index 9b08b7feb..6087ed636 100644 --- a/dc3-driver/dc3-driver-postgresql/README.md +++ b/dc3-driver/dc3-driver-postgresql/README.md @@ -11,7 +11,6 @@ JDBC URL `jdbc:postgresql://:/` using the `org.postgresql. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-postgresql -- **Version**: 2026.5.22 - **Driver Name**: PostgreSQL Driver ## Driver Attributes (Device-level) @@ -38,6 +37,9 @@ JDBC URL `jdbc:postgresql://:/` using the `org.postgresql. |---------------|--------------|--------|----------------------------------| | Execute Query | executeQuery | STRING | SQL query to execute for command | +The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and +local buffering. Keep this README aligned when those user-facing settings change. + ## Prerequisites A reachable PostgreSQL database. The connection URL, credentials, and the SQL queries to run are all supplied through @@ -48,24 +50,26 @@ the driver and point attributes above — nothing is hardcoded. ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-postgresql -am package java -jar dc3-driver/dc3-driver-postgresql/target/dc3-driver-postgresql.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-postgresql -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration - `dc3-common-sql` — `AbstractJdbcDriverCustomService` base class providing JDBC read/write logic - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-driver/dc3-driver-serial/README.md b/dc3-driver/dc3-driver-serial/README.md index f23188541..fd8d9adf6 100644 --- a/dc3-driver/dc3-driver-serial/README.md +++ b/dc3-driver/dc3-driver-serial/README.md @@ -12,7 +12,6 @@ with the `${value}` placeholder substituted. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-serial -- **Version**: 2026.5.22 - **Driver Name**: Serial Port Driver ## Driver Attributes (Device-level) @@ -47,6 +46,9 @@ with the `${value}` placeholder substituted. | Send Command | sendCommand | STRING | ${value} | HEX command template with ${value} placeholder | | Byte Order | byteOrder | STRING | BIG | Byte order for encoding value: BIG, LITTLE | +The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and +local buffering. Keep this README aligned when those user-facing settings change. + ## Prerequisites A serial device connected to a serial port reachable from the host running the driver (e.g. `/dev/ttyUSB0`). The port @@ -57,23 +59,25 @@ path and line parameters (baud rate, data/stop bits, parity, timeout) are suppli ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-serial -am package java -jar dc3-driver/dc3-driver-serial/target/dc3-driver-serial.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-serial -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-driver/dc3-driver-sl651/README.md b/dc3-driver/dc3-driver-sl651/README.md index d71052ffa..8f95891d3 100644 --- a/dc3-driver/dc3-driver-sl651/README.md +++ b/dc3-driver/dc3-driver-sl651/README.md @@ -17,7 +17,6 @@ false`); only the custom schedule and device health check are enabled. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-sl651 -- **Version**: 2026.5.22 - **Driver Name**: SL651 Hydrological Telemetry Driver ## Service Ports @@ -41,6 +40,9 @@ The listen port is exposed as a driver attribute (see below) and read at startup |---------------|-------|------|---------|-------------------------------------------------------| | Element Index | index | INT | 0 | Zero-based index into the telemetry body element list | +The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and +local buffering. Keep this README aligned when those user-facing settings change. + ## Prerequisites SL651-2014 remote stations configured to report to this driver's listen port (default 5001). The `iot-communication` @@ -52,23 +54,25 @@ the SL651 API is unavailable. ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-sl651 -am package java -jar dc3-driver/dc3-driver-sl651/target/dc3-driver-sl651.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-sl651 -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-driver/dc3-driver-snmp/README.md b/dc3-driver/dc3-driver-snmp/README.md index 3da1658db..d4a4ba3de 100644 --- a/dc3-driver/dc3-driver-snmp/README.md +++ b/dc3-driver/dc3-driver-snmp/README.md @@ -10,7 +10,6 @@ issue an SNMP SET, with one SNMP session cached per device. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-snmp -- **Version**: 2026.5.22 - **Driver Name**: SNMP Driver ## Driver Attributes (Device-level) @@ -41,6 +40,9 @@ issue an SNMP SET, with one SNMP session cached per device. | OID | oid | STRING | | | | SNMP Type | snmpType | STRING | OCTET_STRING | | +The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and +local buffering. Keep this README aligned when those user-facing settings change. + ## Prerequisites A reachable SNMP agent. The agent host/port, SNMP version, community string, and per-point OIDs are supplied through the @@ -52,23 +54,25 @@ supports SNMP v1 and v2c. ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-snmp -am package java -jar dc3-driver/dc3-driver-snmp/target/dc3-driver-snmp.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-snmp -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-driver/dc3-driver-sqlserver/README.md b/dc3-driver/dc3-driver-sqlserver/README.md index 71b8328e9..70cca0071 100644 --- a/dc3-driver/dc3-driver-sqlserver/README.md +++ b/dc3-driver/dc3-driver-sqlserver/README.md @@ -13,7 +13,6 @@ using the `com.microsoft.sqlserver.jdbc.SQLServerDriver`. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-sqlserver -- **Version**: 2026.5.22 - **Driver Name**: SQL Server Driver ## Driver Attributes (Device-level) @@ -42,6 +41,9 @@ using the `com.microsoft.sqlserver.jdbc.SQLServerDriver`. |---------------|--------------|--------|----------------------------------| | Execute Query | executeQuery | STRING | SQL query to execute for command | +The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and +local buffering. Keep this README aligned when those user-facing settings change. + ## Prerequisites A reachable Microsoft SQL Server instance. The connection URL, credentials, encryption flags, and the SQL queries to run @@ -52,24 +54,26 @@ are all supplied through the driver and point attributes above — nothing is ha ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-sqlserver -am package java -jar dc3-driver/dc3-driver-sqlserver/target/dc3-driver-sqlserver.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-sqlserver -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration - `dc3-common-sql` — `AbstractJdbcDriverCustomService` base class providing JDBC read/write logic - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-driver/dc3-driver-tcp-udp/README.md b/dc3-driver/dc3-driver-tcp-udp/README.md index 7d7afee38..1b06c0b84 100644 --- a/dc3-driver/dc3-driver-tcp-udp/README.md +++ b/dc3-driver/dc3-driver-tcp-udp/README.md @@ -14,7 +14,6 @@ directly. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-tcp-udp -- **Version**: 2026.5.22 - **Driver Name**: TCP/UDP Raw Driver ## Driver Attributes (Device-level) @@ -47,6 +46,9 @@ directly. |--------------|-------------|--------|----------|-------------| | Send Command | sendCommand | STRING | ${value} | | +The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and +local buffering. Keep this README aligned when those user-facing settings change. + ## Prerequisites A reachable TCP or UDP endpoint. The protocol selection, host/port, timeouts, and per-point HEX commands are supplied @@ -57,23 +59,25 @@ through the driver and point attributes above. ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-tcp-udp -am package java -jar dc3-driver/dc3-driver-tcp-udp/target/dc3-driver-tcp-udp.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-tcp-udp -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-driver/dc3-driver-virtual/README.md b/dc3-driver/dc3-driver-virtual/README.md index 3863d77c0..3fc17e0af 100644 --- a/dc3-driver/dc3-driver-virtual/README.md +++ b/dc3-driver/dc3-driver-virtual/README.md @@ -10,7 +10,6 @@ hardware. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-virtual -- **Version**: 2026.5.22 - **Driver Name**: Virtual Driver ## Driver Attributes @@ -42,6 +41,9 @@ hardware. ## Data Collection Schedule +The module `application.yml` and its profile-specific variants are authoritative for attribute codes, types, default +values, scheduling, health, and local buffering. Keep this README aligned when that metadata changes. + Configured in `application-dev.yml`: ```yaml @@ -57,14 +59,14 @@ dc3: ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-virtual -am package java -jar dc3-driver/dc3-driver-virtual/target/dc3-driver-virtual.jar ``` @@ -76,12 +78,14 @@ The driver logs show gRPC registration with Manager Center on startup: Driver register success, service name: dc3-driver-virtual ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-virtual -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-driver/dc3-driver-zigbee/README.md b/dc3-driver/dc3-driver-zigbee/README.md index 8e73478c5..f95541aaa 100644 --- a/dc3-driver/dc3-driver-zigbee/README.md +++ b/dc3-driver/dc3-driver-zigbee/README.md @@ -17,7 +17,6 @@ attributes addressed by node IEEE address / endpoint / cluster / attribute, and - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-driver-zigbee -- **Version**: 2026.5.22 - **Driver Name**: Zigbee Driver ## Driver Attributes (Device-level) @@ -48,6 +47,9 @@ attributes addressed by node IEEE address / endpoint / cluster / attribute, and | Cluster ID | clusterId | INT | 0 | Cluster ID for writing | | Attribute ID | attributeId | INT | 0 | Attribute ID for writing | +The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and +local buffering. Keep this README aligned when those user-facing settings change. + ## Prerequisites A Zigbee coordinator dongle connected to a serial port on the host running the driver. The dependencies bundle the @@ -59,23 +61,25 @@ the driver attributes above (see the work-in-progress warning). ### 1. Start Infrastructure and Center Services ```bash -podman compose -f dc3/docker-compose-db.yml up -d -java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar +make up-db +make up-dev GROUP=core ``` ### 2. Build and Run ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-zigbee -am package java -jar dc3-driver/dc3-driver-zigbee/target/dc3-driver-zigbee.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-zigbee -am test +``` + ## Related Modules - `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-e2e/README.md b/dc3-e2e/README.md index 48192a108..cda13495b 100644 --- a/dc3-e2e/README.md +++ b/dc3-e2e/README.md @@ -10,7 +10,6 @@ storage, RabbitMQ delivery, and TimescaleDB hypertables. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-e2e -- **Version**: 2026.5.22 - **Packaging**: jar (test sources only) ## Test Suites @@ -34,16 +33,11 @@ make test-e2e # = DC3_E2E=true mvn -s .mvn/settings.xml -B -Dmaven.test.skip=false -Dskip.unit.tests=true -pl dc3-e2e -am -Pe2e verify ``` -Requires a container runtime (`podman`) for the Testcontainers-backed dependencies provided by `dc3-common-test`. +Requires a Docker-compatible container runtime for the Testcontainers-backed dependencies provided by +`dc3-common-test`. ## Dependencies - `dc3-common-test` — Testcontainers and test harnesses - `dc3-common-model` — domain models - `rest-assured` — HTTP assertions - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) diff --git a/dc3-gateway/README.md b/dc3-gateway/README.md index 848d6c4d8..39a166a74 100644 --- a/dc3-gateway/README.md +++ b/dc3-gateway/README.md @@ -10,7 +10,6 @@ routing, and reverse proxying. - **Group ID**: io.github.pnoker - **Artifact ID**: dc3-gateway -- **Version**: 2026.5.22 - **Package**: `io.github.pnoker.gateway` ## Service Ports @@ -73,30 +72,31 @@ Route definitions and the auth gRPC channel are shared in `dc3-common-gateway`'s ### 1. Start Infrastructure ```bash -podman compose -f dc3/docker-compose-db.yml up -d +make up-db ``` ### 2. Build ```bash -mvn -s .mvn/settings.xml clean package +mvn -s .mvn/settings.xml -pl dc3-gateway -am package ``` -### 3. Run (start first before any center service) +### 3. Run after the required center services are available ```bash java -jar dc3-gateway/target/dc3-gateway.jar ``` +## Testing + +Run the module tests from the repository root: + +```bash +mvn -s .mvn/settings.xml -pl dc3-gateway -am test +``` + ## Related Modules - `dc3-common-gateway` — `Authentic` filter implementation and gateway utilities - `dc3-api-auth` — gRPC API contracts for token validation - `dc3-center-auth` — Token validation backend - -## License - -Copyright 2016-present the IoT DC3 original author or authors. - -Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0) - diff --git a/dc3-web/README.md b/dc3-web/README.md index b7a519146..94304d021 100644 --- a/dc3-web/README.md +++ b/dc3-web/README.md @@ -1,34 +1,51 @@ -## 1. Prepare +# DC3 Web -- `git` -- `Visual Studio Code` -- `nodejs` >= 22 (enforced by `engines` in `package.json`) -- `pnpm` 11.3.0 (pinned via `packageManager`), install using - `corepack enable && corepack prepare pnpm@11.3.0 --activate` +`dc3-web` is the Vue and TypeScript management frontend for IoT DC3. It communicates with the backend exclusively +through `dc3-gateway`. -## 2. Source code +## Prerequisites + +- Node.js 22 or newer, as declared by `engines` in `package.json`. +- Corepack enabled. +- The pnpm version declared by `packageManager` in `package.json`. ```bash -git clone https://github.com/pnoker/iot-dc3.git +corepack enable +pnpm install ``` -## 3. Develop +Use pnpm only. Do not generate npm or Yarn lockfiles. When changing the package-manager version, keep `package.json` and +the Dockerfile toolchain pin aligned. + +## Develop ```bash -cd iot-dc3/dc3-web - -# install -pnpm install - -# run pnpm dev ``` -The dev server runs on `http://localhost:8080` and proxies API calls to the backend gateway (`http://localhost:8000`), -so start the backend stack first. +The development server uses the port and API proxy configured by `vite.config.ts` and `src/config/env/`. Its defaults +are `http://localhost:8080` for the UI and `http://localhost:8000` for the gateway. The UI can start without the backend, +but login and data requests require a running gateway and center services. -## 4. More +## Build and verify -For the full command surface (build, type-check, lint, unit/component/E2E tests), the tech stack, environment -configuration (`src/config/env/`), and project conventions, see -[`AGENTS.md`](./AGENTS.md). +```bash +pnpm check +pnpm lint:check +pnpm test:guard +pnpm test:ci +pnpm build +``` + +Run focused suites with `pnpm test:unit`, `pnpm test:api`, `pnpm test:component`, or `pnpm test:views`. Browser workflows +use `pnpm test:e2e`; see [tests/README.md](./tests/README.md) for the test layers and fixture policy. + +## Project conventions + +- Vite environment files live under `src/config/env/` and use the `APP_` prefix. +- Java 64-bit IDs are represented as strings and decoded with the existing JSONBigInt support. +- Type-only imports must use `import type` because `verbatimModuleSyntax` is enabled. +- API wrapper names mirror backend cardinality: `getXxx` for one result and `listXxx` for collections/pages/maps. +- Every router-guard branch must settle navigation. + +Repository-wide architecture, commit, and verification rules are in [../AGENTS.md](../AGENTS.md).