From a57582d73951987f32c834094d7bee6164ec84e3 Mon Sep 17 00:00:00 2001 From: "borja (aider)" Date: Mon, 5 May 2025 18:40:33 +0200 Subject: [PATCH] docs: update README with current project status --- README.md | 39 +++++++++++++++++++++------------------ 1 file changed, 21 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 37cf1b3..fbd97e3 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ This service provides a WhatsApp interface for task management within WhatsApp g ## ๐Ÿ” Security Model - **Internal Networking**: The webhook should ideally only accept connections from Evolution API via internal Docker networking (configuration dependent). - **Environment Variables**: Sensitive configuration (API keys, URLs) is managed through environment variables. -- **Group Restrictions**: Designed to operate within pre-approved WhatsApp groups (validation logic pending implementation). +- **Group Restrictions**: Designed to operate within pre-approved WhatsApp groups (validation logic pending integration). - **Input Validation**: Basic validation exists for webhook structure; needs enhancement for command arguments and user/group IDs. ## ๐Ÿงฑ Architecture @@ -41,22 +41,24 @@ graph TD ``` *(Diagram updated for planned flow)* -## โœ… Current Status (as of commit dd32a3d) +## โœ… Current Status (as of commit dd32a3d, reviewed against code summaries) ### Implemented - Webhook server setup (`src/server.ts`) receiving Evolution API events. - Database schema definition and initialization (`src/db.ts`). -- Group synchronization service (`src/services/group-sync.ts`) to fetch/store/cache groups. +- Group synchronization service (`src/services/group-sync.ts`) to fetch/store/cache groups. Includes active group caching. - Webhook registration and verification with Evolution API (`src/services/webhook-manager.ts`). -- Basic `/tarea` command detection and argument parsing structure (`src/server.ts`). +- WhatsApp ID normalization utility (`src/utils/whatsapp.ts`). +- User creation function (`src/db.ts::ensureUserExists`). +- Basic `/tarea` command detection (`src/server.ts`) and processing structure (`src/services/command.ts` - logic is placeholder). - Task data models (`src/tasks/model.ts`). - Basic task creation service stub (`src/tasks/service.ts` - needs `created_by` and assignment logic). - Response queue structure (`src/services/response-queue.ts` - `process` method is empty). -- Unit testing setup with in-memory database (`tests/`). +- Unit testing setup with in-memory database (`tests/`). Includes tests for normalization. - Environment variable validation (`src/server.ts`, `src/services/webhook-manager.ts`). - Health check endpoint (`/health`). ### Incomplete / Missing Core Functionality -- **User/Group Validation:** No normalization of WhatsApp IDs or checking if messages originate from active, known groups. Users are not automatically added to the DB. +- **User/Group Validation Integration:** Although normalization (`normalizeWhatsAppId`) and user creation (`ensureUserExists`) functions exist, they are **not yet integrated** into the main request handling flow in `src/server.ts` to validate senders or automatically add users on first message. Similarly, the active group cache from `group-sync.ts` is **not yet used** in `server.ts` to filter messages from inactive/unknown groups. - **Core Command Logic:** Actual processing of `/tarea nueva` (parsing args, calling `TaskService`) is missing in `CommandService`. Other commands (`mostrar`, `completar`) not implemented. - **Task Service Implementation:** `TaskService` needs updating to handle `created_by`, assignments, and potentially methods for listing/completing tasks. - **Response Sending:** `ResponseQueue` does not yet send messages back via the Evolution API. @@ -105,10 +107,10 @@ bun test ## ๐Ÿ“… Roadmap & Priorities (Plan) ### Phase 1: User & Group Foundation (Highest Priority) -- [ ] **Create WhatsApp ID Normalization Utility:** (`src/utils/whatsapp.ts`) Handle different ID formats. -- [ ] **Implement `ensureUserExists`:** (`src/db.ts`) Add users to DB on first interaction. -- [ ] **Implement `isGroupActive` Check:** (`src/services/group-sync.ts`, `src/server.ts`) Validate incoming messages are from known, active groups. -- [ ] **Integrate Validation in Server:** (`src/server.ts`) Use normalization and validation before processing commands. +- [x] **Create WhatsApp ID Normalization Utility:** (`src/utils/whatsapp.ts`) Handle different ID formats. +- [x] **Implement `ensureUserExists`:** (`src/db.ts`) Add users to DB on first interaction. +- [ ] **Implement `isGroupActive` Check:** (`src/services/group-sync.ts`, `src/server.ts`) Cache exists in `group-sync.ts`. **Needs integration** into `server.ts`. +- [ ] **Integrate Validation in Server:** (`src/server.ts`) Use normalization, `ensureUserExists`, and active group check before processing commands. ### Phase 2: Implement `/tarea nueva` Command (High Priority) - [ ] **Update `TaskService.createTask`:** (`src/tasks/service.ts`) Handle `created_by` and assignments (including adding assigned users via `ensureUserExists`). @@ -132,12 +134,12 @@ bun test - [ ] Create task history tracking. ## ๐Ÿ”‘ Key Considerations & Caveats -* **WhatsApp ID Normalization:** Crucial for consistently identifying users and groups. Needs careful implementation to handle edge cases. +* **WhatsApp ID Normalization:** Crucial for consistently identifying users and groups. Needs careful implementation to handle edge cases. (Utility function exists). * **Response Latency:** Sending responses requires an API call back to Evolution. Ensure the `ResponseQueue` processing is efficient. * **Group Sync:** The current full sync might be slow or rate-limited with many groups. Delta updates are recommended long-term. * **Error Handling:** Failures in command processing or response sending should be logged clearly and potentially reported back to the user. Database operations should use transactions for atomicity (especially task+assignment creation). * **State Management:** The current design is stateless. Complex interactions might require state persistence later. -* **Security:** Ensure group/user validation logic is robust. +* **Security:** Ensure group/user validation logic is robust once integrated. ## ๐Ÿงช Testing ### Running Tests @@ -146,12 +148,13 @@ bun test ``` ### Test Coverage -- Database initialization and basic operations. -- Webhook validation (basic). -- Command parsing (basic structure). -- Environment checks. -- Basic error handling. -- **Needed:** Tests for ID normalization, `ensureUserExists`, `isGroupActive`, `CommandService` logic, `ResponseQueue` processing (mocking API), `TaskService` operations. +- Database initialization and basic operations (`db.test.ts`). +- Webhook validation (basic) (`webhook-manager.test.ts`). +- Command parsing (basic structure) (`command.test.ts`). +- Environment checks (`server.test.ts`). +- Basic error handling (`server.test.ts`). +- WhatsApp ID normalization (`whatsapp.test.ts`). +- **Needed:** Tests for `ensureUserExists` integration, `isGroupActive` integration, `CommandService` logic, `ResponseQueue` processing (mocking API), `TaskService` operations. ## ๐Ÿง‘โ€๐Ÿ’ป Contributing 1. Fork the repository