docs: update README for Phase 3 infrastructure completion
Update README to reflect completed Phase 3 infrastructure layer: - Documented ModbusRelayController, MockRelayController, SqliteRelayLabelRepository, and HealthMonitor implementations - Added testing coverage details (20+ tests across infrastructure components) - Updated architecture diagrams and project structure - Changed task reference to tasks.org format - Updated dependency list with production infrastructure dependencies Ref: Phase 3 tasks in specs/001-modbus-relay-control/tasks.org
This commit is contained in:
125
README.md
125
README.md
@@ -62,33 +62,59 @@ STA will provide a modern web interface for controlling Modbus-compatible relay
|
|||||||
- RelayController and RelayLabelRepository trait definitions
|
- RelayController and RelayLabelRepository trait definitions
|
||||||
- Complete separation from infrastructure concerns (hexagonal architecture)
|
- Complete separation from infrastructure concerns (hexagonal architecture)
|
||||||
|
|
||||||
### Planned - Phases 3-8
|
### Phase 3 Complete - Infrastructure Layer
|
||||||
- 📋 Modbus TCP client with tokio-modbus (Phase 3)
|
- ✅ T028-T029: MockRelayController tests and implementation
|
||||||
- 📋 Mock controller for testing (Phase 3)
|
- ✅ T030: RelayController trait with async methods (read_state, write_state, read_all, write_all)
|
||||||
- 📋 Health monitoring service (Phase 3)
|
- ✅ T031: ControllerError enum (ConnectionError, Timeout, ModbusException, InvalidRelayId)
|
||||||
|
- ✅ T032: MockRelayController comprehensive tests (6 tests)
|
||||||
|
- ✅ T025a-f: ModbusRelayController implementation (decomposed):
|
||||||
|
- Connection setup with tokio-modbus
|
||||||
|
- Timeout-wrapped read_coils and write_single_coil helpers
|
||||||
|
- RelayController trait implementation
|
||||||
|
- ✅ T034: Integration test with real hardware (uses #[ignore] attribute)
|
||||||
|
- ✅ T035-T036: RelayLabelRepository trait and SQLite implementation
|
||||||
|
- ✅ T037-T038: MockRelayLabelRepository for testing
|
||||||
|
- ✅ T039-T040: HealthMonitor service with state tracking
|
||||||
|
|
||||||
|
#### Key Infrastructure Features Implemented
|
||||||
|
- **ModbusRelayController**: Thread-safe Modbus TCP client with timeout handling
|
||||||
|
- Uses `Arc<Mutex<Context>>` for concurrent access
|
||||||
|
- Native Modbus TCP protocol (MBAP header, no CRC16)
|
||||||
|
- Configurable timeout with `tokio::time::timeout`
|
||||||
|
- **MockRelayController**: In-memory testing without hardware
|
||||||
|
- Uses `Arc<Mutex<HashMap<RelayId, RelayState>>>` for state
|
||||||
|
- Optional timeout simulation for error handling tests
|
||||||
|
- **SqliteRelayLabelRepository**: Compile-time verified SQL queries
|
||||||
|
- Automatic migrations via SQLx
|
||||||
|
- In-memory mode for testing
|
||||||
|
- **HealthMonitor**: State machine for health tracking
|
||||||
|
- Healthy -> Degraded -> Unhealthy transitions
|
||||||
|
- Recovery on successful operations
|
||||||
|
|
||||||
|
### Planned - Phases 4-8
|
||||||
- 📋 US1: Monitor & toggle relay states - MVP (Phase 4)
|
- 📋 US1: Monitor & toggle relay states - MVP (Phase 4)
|
||||||
- 📋 US2: Bulk relay controls (Phase 5)
|
- 📋 US2: Bulk relay controls (Phase 5)
|
||||||
- 📋 US3: Health status display (Phase 6)
|
- 📋 US3: Health status display (Phase 6)
|
||||||
- 📋 US4: Relay labeling (Phase 7)
|
- 📋 US4: Relay labeling (Phase 7)
|
||||||
- 📋 Production deployment (Phase 8)
|
- 📋 Production deployment (Phase 8)
|
||||||
|
|
||||||
See [tasks.md](specs/001-modbus-relay-control/tasks.md) for detailed implementation roadmap (102 tasks across 9 phases).
|
See [tasks.org](specs/001-modbus-relay-control/tasks.org) for detailed implementation roadmap.
|
||||||
|
|
||||||
## Architecture
|
## Architecture
|
||||||
|
|
||||||
**Current:**
|
**Current:**
|
||||||
- **Backend**: Rust 2024 with Poem web framework
|
- **Backend**: Rust 2024 with Poem web framework (hexagonal architecture)
|
||||||
- **Configuration**: YAML-based with environment variable overrides
|
- **Configuration**: YAML-based with environment variable overrides
|
||||||
- **API**: RESTful HTTP with OpenAPI documentation
|
- **API**: RESTful HTTP with OpenAPI documentation
|
||||||
- **CORS**: Production-ready configurable middleware with security validation
|
- **CORS**: Production-ready configurable middleware with security validation
|
||||||
- **Middleware Chain**: Rate Limiting → CORS → Data injection
|
- **Middleware Chain**: Rate Limiting -> CORS -> Data injection
|
||||||
|
- **Modbus Integration**: tokio-modbus for Modbus TCP communication
|
||||||
|
- **Persistence**: SQLite for relay labels with compile-time SQL verification
|
||||||
|
|
||||||
**Planned:**
|
**Planned:**
|
||||||
- **Modbus Integration**: tokio-modbus for Modbus TCP communication
|
|
||||||
- **Frontend**: Vue 3 with TypeScript
|
- **Frontend**: Vue 3 with TypeScript
|
||||||
- **Deployment**: Backend on Raspberry Pi, frontend on Cloudflare Pages
|
- **Deployment**: Backend on Raspberry Pi, frontend on Cloudflare Pages
|
||||||
- **Access**: Traefik reverse proxy with Authelia authentication
|
- **Access**: Traefik reverse proxy with Authelia authentication
|
||||||
- **Persistence**: SQLite for relay labels and configuration
|
|
||||||
|
|
||||||
## Quick Start
|
## Quick Start
|
||||||
|
|
||||||
@@ -205,48 +231,65 @@ sta/ # Repository root
|
|||||||
│ │ ├── lib.rs - Library entry point
|
│ │ ├── lib.rs - Library entry point
|
||||||
│ │ ├── main.rs - Binary entry point
|
│ │ ├── main.rs - Binary entry point
|
||||||
│ │ ├── startup.rs - Application builder and server config
|
│ │ ├── startup.rs - Application builder and server config
|
||||||
│ │ ├── settings/ - Configuration module
|
|
||||||
│ │ │ ├── mod.rs - Settings aggregation
|
|
||||||
│ │ │ └── cors.rs - CORS configuration (NEW in Phase 0.5)
|
|
||||||
│ │ ├── telemetry.rs - Logging and tracing setup
|
│ │ ├── telemetry.rs - Logging and tracing setup
|
||||||
│ │ ├── domain/ - Business logic (NEW in Phase 2)
|
│ │ │
|
||||||
│ │ │ ├── relay/ - Relay domain types, entity, and traits
|
│ │ ├── domain/ - Business logic layer (Phase 2)
|
||||||
|
│ │ │ ├── relay/ - Relay domain aggregate
|
||||||
│ │ │ │ ├── types/ - RelayId, RelayState, RelayLabel newtypes
|
│ │ │ │ ├── types/ - RelayId, RelayState, RelayLabel newtypes
|
||||||
│ │ │ │ ├── entity.rs - Relay aggregate
|
│ │ │ │ ├── entity.rs - Relay aggregate with state control
|
||||||
│ │ │ │ ├── controller.rs - RelayController trait
|
│ │ │ │ ├── controller.rs - RelayController trait & ControllerError
|
||||||
│ │ │ │ └── repository.rs - RelayLabelRepository trait
|
│ │ │ │ └── repository/ - RelayLabelRepository trait
|
||||||
│ │ │ ├── modbus.rs - ModbusAddress type with conversion
|
│ │ │ ├── modbus.rs - ModbusAddress type with conversion
|
||||||
│ │ │ └── health.rs - HealthStatus state machine
|
│ │ │ └── health.rs - HealthStatus state machine
|
||||||
│ │ ├── application/ - Use cases (planned Phase 3-4)
|
│ │ │
|
||||||
|
│ │ ├── application/ - Use cases and orchestration (Phase 3)
|
||||||
|
│ │ │ └── health/ - Health monitoring service
|
||||||
|
│ │ │ └── health_monitor.rs - HealthMonitor with state tracking
|
||||||
|
│ │ │
|
||||||
│ │ ├── infrastructure/ - External integrations (Phase 3)
|
│ │ ├── infrastructure/ - External integrations (Phase 3)
|
||||||
│ │ │ └── persistence/ - SQLite repository implementation
|
│ │ │ ├── modbus/ - Modbus TCP communication
|
||||||
|
│ │ │ │ ├── client.rs - ModbusRelayController (real hardware)
|
||||||
|
│ │ │ │ ├── client_test.rs - Hardware integration tests
|
||||||
|
│ │ │ │ └── mock_controller.rs - MockRelayController for testing
|
||||||
|
│ │ │ └── persistence/ - Database layer
|
||||||
|
│ │ │ ├── entities/ - Database record types
|
||||||
|
│ │ │ ├── sqlite_repository.rs - SqliteRelayLabelRepository
|
||||||
|
│ │ │ └── label_repository.rs - MockRelayLabelRepository
|
||||||
|
│ │ │
|
||||||
│ │ ├── presentation/ - API layer (planned Phase 4)
|
│ │ ├── presentation/ - API layer (planned Phase 4)
|
||||||
|
│ │ ├── settings/ - Configuration module
|
||||||
|
│ │ │ ├── mod.rs - Settings aggregation
|
||||||
|
│ │ │ └── cors.rs - CORS configuration
|
||||||
│ │ ├── route/ - HTTP endpoint handlers
|
│ │ ├── route/ - HTTP endpoint handlers
|
||||||
│ │ │ ├── health.rs - Health check endpoints
|
│ │ │ ├── health.rs - Health check endpoints
|
||||||
│ │ │ └── meta.rs - Application metadata
|
│ │ │ └── meta.rs - Application metadata
|
||||||
│ │ └── middleware/ - Custom middleware
|
│ │ └── middleware/ - Custom middleware
|
||||||
│ │ └── rate_limit.rs
|
│ │ └── rate_limit.rs
|
||||||
|
│ │
|
||||||
│ ├── settings/ - YAML configuration files
|
│ ├── settings/ - YAML configuration files
|
||||||
│ │ ├── base.yaml - Base configuration
|
│ │ ├── base.yaml - Base configuration
|
||||||
│ │ ├── development.yaml - Development overrides (NEW in Phase 0.5)
|
│ │ ├── development.yaml - Development overrides
|
||||||
│ │ └── production.yaml - Production overrides (NEW in Phase 0.5)
|
│ │ └── production.yaml - Production overrides
|
||||||
│ └── tests/ - Integration tests
|
│ └── tests/ - Integration tests
|
||||||
│ └── cors_test.rs - CORS integration tests (NEW in Phase 0.5)
|
│ └── cors_test.rs - CORS integration tests
|
||||||
|
│
|
||||||
|
├── migrations/ - SQLx database migrations
|
||||||
├── src/ # Frontend source (Vue/TypeScript)
|
├── src/ # Frontend source (Vue/TypeScript)
|
||||||
│ └── api/ - Type-safe API client
|
│ └── api/ - Type-safe API client
|
||||||
├── docs/ # Project documentation
|
├── docs/ # Project documentation
|
||||||
│ ├── cors-configuration.md - CORS setup guide
|
│ ├── cors-configuration.md - CORS setup guide
|
||||||
│ ├── domain-layer.md - Domain layer architecture (NEW in Phase 2)
|
│ ├── domain-layer.md - Domain layer architecture
|
||||||
│ └── Modbus_POE_ETH_Relay.md - Hardware documentation
|
│ └── Modbus_POE_ETH_Relay.md - Hardware documentation
|
||||||
├── specs/ # Feature specifications
|
├── specs/ # Feature specifications
|
||||||
│ ├── constitution.md - Architectural principles
|
│ ├── constitution.md - Architectural principles
|
||||||
│ └── 001-modbus-relay-control/
|
│ └── 001-modbus-relay-control/
|
||||||
│ ├── spec.md - Feature specification
|
│ ├── spec.md - Feature specification
|
||||||
│ ├── plan.md - Implementation plan
|
│ ├── plan.md - Implementation plan
|
||||||
│ ├── tasks.md - Task breakdown (102 tasks)
|
│ ├── tasks.org - Task breakdown (org-mode format)
|
||||||
│ ├── domain-layer-architecture.md - Domain layer docs (NEW in Phase 2)
|
│ ├── data-model.md - Data model specification
|
||||||
│ ├── lessons-learned.md - Phase 2 insights (NEW in Phase 2)
|
│ ├── types-design.md - Domain types design
|
||||||
│ └── research-cors.md - CORS configuration research
|
│ ├── domain-layer-architecture.md - Domain layer docs
|
||||||
|
│ └── lessons-learned.md - Phase 2/3 insights
|
||||||
├── package.json - Frontend dependencies
|
├── package.json - Frontend dependencies
|
||||||
├── vite.config.ts - Vite build configuration
|
├── vite.config.ts - Vite build configuration
|
||||||
└── justfile - Build commands
|
└── justfile - Build commands
|
||||||
@@ -258,17 +301,15 @@ sta/ # Repository root
|
|||||||
- Rust 2024 edition
|
- Rust 2024 edition
|
||||||
- Poem 3.1 (web framework with OpenAPI support)
|
- Poem 3.1 (web framework with OpenAPI support)
|
||||||
- Tokio 1.48 (async runtime)
|
- Tokio 1.48 (async runtime)
|
||||||
|
- tokio-modbus (Modbus TCP client for relay hardware)
|
||||||
|
- SQLx 0.8 (async SQLite with compile-time SQL verification)
|
||||||
|
- async-trait (async methods in traits)
|
||||||
- config (YAML configuration)
|
- config (YAML configuration)
|
||||||
- tracing + tracing-subscriber (structured logging)
|
- tracing + tracing-subscriber (structured logging)
|
||||||
- governor (rate limiting)
|
- governor (rate limiting)
|
||||||
- thiserror (error handling)
|
- thiserror (error handling)
|
||||||
- serde + serde_yaml (configuration deserialization)
|
- serde + serde_yaml (configuration deserialization)
|
||||||
|
|
||||||
**Planned Dependencies:**
|
|
||||||
- tokio-modbus 0.17 (Modbus TCP client)
|
|
||||||
- SQLx 0.8 (async SQLite database access)
|
|
||||||
- mockall 0.13 (mocking for tests)
|
|
||||||
|
|
||||||
**Frontend** (scaffolding complete):
|
**Frontend** (scaffolding complete):
|
||||||
- Vue 3 + TypeScript
|
- Vue 3 + TypeScript
|
||||||
- Vite build tool
|
- Vite build tool
|
||||||
@@ -306,6 +347,26 @@ sta/ # Repository root
|
|||||||
|
|
||||||
**Test Coverage Achieved**: 100% domain layer coverage with comprehensive test suites
|
**Test Coverage Achieved**: 100% domain layer coverage with comprehensive test suites
|
||||||
|
|
||||||
|
**Phase 3 Infrastructure Testing:**
|
||||||
|
- **MockRelayController Tests**: 6 tests in `mock_controller.rs`
|
||||||
|
- Read/write state operations
|
||||||
|
- Read/write all relay states
|
||||||
|
- Invalid relay ID handling
|
||||||
|
- Thread-safe concurrent access
|
||||||
|
- **ModbusRelayController Tests**: Hardware integration tests (#[ignore])
|
||||||
|
- Real hardware communication tests
|
||||||
|
- Connection timeout handling
|
||||||
|
- **SqliteRelayLabelRepository Tests**: Database layer tests
|
||||||
|
- CRUD operations on relay labels
|
||||||
|
- In-memory database for fast tests
|
||||||
|
- Compile-time SQL verification
|
||||||
|
- **HealthMonitor Tests**: 15+ tests in `health_monitor.rs`
|
||||||
|
- State transitions (Healthy -> Degraded -> Unhealthy)
|
||||||
|
- Recovery from failure states
|
||||||
|
- Concurrent access safety
|
||||||
|
|
||||||
|
**Test Coverage Achieved**: Comprehensive coverage across all layers with TDD approach
|
||||||
|
|
||||||
## Documentation
|
## Documentation
|
||||||
|
|
||||||
### Configuration Guides
|
### Configuration Guides
|
||||||
|
|||||||
Reference in New Issue
Block a user