diff --git a/README.md b/README.md index 8186925..036d9e5 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,18 @@ -# STA - Smart Temperature & Appliance Control +

STA

+
+ + Smart Temperature & Appliance Control + +
+
+ +
+ + Coding Time Badge + + +
+
> **🤖 AI-Assisted Development Notice**: This project uses Claude Code as a development assistant for task planning, code organization, and workflow management. However, all code is human-written, reviewed, and validated by the project maintainer. AI is used as a productivity tool, not as the author of the implementation. @@ -62,33 +76,59 @@ STA will provide a modern web interface for controlling Modbus-compatible relay - RelayController and RelayLabelRepository trait definitions - Complete separation from infrastructure concerns (hexagonal architecture) -### Planned - Phases 3-8 -- 📋 Modbus TCP client with tokio-modbus (Phase 3) -- 📋 Mock controller for testing (Phase 3) -- 📋 Health monitoring service (Phase 3) +### Phase 3 Complete - Infrastructure Layer +- ✅ T028-T029: MockRelayController tests and implementation +- ✅ T030: RelayController trait with async methods (read_state, write_state, read_all, write_all) +- ✅ 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>` 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>>` 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) - 📋 US2: Bulk relay controls (Phase 5) - 📋 US3: Health status display (Phase 6) - 📋 US4: Relay labeling (Phase 7) - 📋 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 **Current:** -- **Backend**: Rust 2024 with Poem web framework +- **Backend**: Rust 2024 with Poem web framework (hexagonal architecture) - **Configuration**: YAML-based with environment variable overrides - **API**: RESTful HTTP with OpenAPI documentation - **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:** -- **Modbus Integration**: tokio-modbus for Modbus TCP communication - **Frontend**: Vue 3 with TypeScript - **Deployment**: Backend on Raspberry Pi, frontend on Cloudflare Pages - **Access**: Traefik reverse proxy with Authelia authentication -- **Persistence**: SQLite for relay labels and configuration ## Quick Start @@ -205,48 +245,65 @@ sta/ # Repository root │ │ ├── lib.rs - Library entry point │ │ ├── main.rs - Binary entry point │ │ ├── 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 -│ │ ├── 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 -│ │ │ │ ├── entity.rs - Relay aggregate -│ │ │ │ ├── controller.rs - RelayController trait -│ │ │ │ └── repository.rs - RelayLabelRepository trait +│ │ │ │ ├── entity.rs - Relay aggregate with state control +│ │ │ │ ├── controller.rs - RelayController trait & ControllerError +│ │ │ │ └── repository/ - RelayLabelRepository trait │ │ │ ├── modbus.rs - ModbusAddress type with conversion │ │ │ └── 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) -│ │ │ └── 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) +│ │ ├── settings/ - Configuration module +│ │ │ ├── mod.rs - Settings aggregation +│ │ │ └── cors.rs - CORS configuration │ │ ├── route/ - HTTP endpoint handlers │ │ │ ├── health.rs - Health check endpoints │ │ │ └── meta.rs - Application metadata │ │ └── middleware/ - Custom middleware │ │ └── rate_limit.rs +│ │ │ ├── settings/ - YAML configuration files │ │ ├── base.yaml - Base configuration -│ │ ├── development.yaml - Development overrides (NEW in Phase 0.5) -│ │ └── production.yaml - Production overrides (NEW in Phase 0.5) +│ │ ├── development.yaml - Development overrides +│ │ └── production.yaml - Production overrides │ └── 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) │ └── api/ - Type-safe API client ├── docs/ # Project documentation │ ├── 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 ├── specs/ # Feature specifications │ ├── constitution.md - Architectural principles │ └── 001-modbus-relay-control/ │ ├── spec.md - Feature specification │ ├── plan.md - Implementation plan -│ ├── tasks.md - Task breakdown (102 tasks) -│ ├── domain-layer-architecture.md - Domain layer docs (NEW in Phase 2) -│ ├── lessons-learned.md - Phase 2 insights (NEW in Phase 2) -│ └── research-cors.md - CORS configuration research +│ ├── tasks.org - Task breakdown (org-mode format) +│ ├── data-model.md - Data model specification +│ ├── types-design.md - Domain types design +│ ├── domain-layer-architecture.md - Domain layer docs +│ └── lessons-learned.md - Phase 2/3 insights ├── package.json - Frontend dependencies ├── vite.config.ts - Vite build configuration └── justfile - Build commands @@ -258,17 +315,15 @@ sta/ # Repository root - Rust 2024 edition - Poem 3.1 (web framework with OpenAPI support) - 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) - tracing + tracing-subscriber (structured logging) - governor (rate limiting) - thiserror (error handling) - 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): - Vue 3 + TypeScript - Vite build tool @@ -306,6 +361,26 @@ sta/ # Repository root **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 ### Configuration Guides