@ -13,7 +13,7 @@ This service provides a WhatsApp interface for task management within WhatsApp g
## 🔐 Security Model
## 🔐 Security Model
- **Internal Networking**: The webhook should ideally only accept connections from Evolution API via internal Docker networking (configuration dependent).
- **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.
- **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.
- **Input Validation**: Basic validation exists for webhook structure; needs enhancement for command arguments and user/group IDs.
## 🧱 Architecture
## 🧱 Architecture
@ -41,22 +41,24 @@ graph TD
```
```
*(Diagram updated for planned flow)*
*(Diagram updated for planned flow)*
## ✅ Current Status (as of commit dd32a3d)
## ✅ Current Status (as of commit dd32a3d, reviewed against code summaries)
### Implemented
### Implemented
- Webhook server setup (`src/server.ts`) receiving Evolution API events.
- Webhook server setup (`src/server.ts`) receiving Evolution API events.
- Database schema definition and initialization (`src/db.ts`).
- 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`).
- 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`).
- Task data models (`src/tasks/model.ts`).
- Basic task creation service stub (`src/tasks/service.ts` - needs `created_by` and assignment logic).
- 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).
- 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.
- **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.
- **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.
- **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.
- **Response Sending:**`ResponseQueue` does not yet send messages back via the Evolution API.
@ -105,10 +107,10 @@ bun test
## 📅 Roadmap & Priorities (Plan)
## 📅 Roadmap & Priorities (Plan)
### Phase 1: User & Group Foundation (Highest Priority)
### Phase 1: User & Group Foundation (Highest Priority)
- [] **Create WhatsApp ID Normalization Utility:** (`src/utils/whatsapp.ts`) Handle different ID formats.
- [x] **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.
- [x] **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.
- [ ] **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 and validation before processing commands.
- [ ] **Integrate Validation in Server:** (`src/server.ts`) Use normalization, `ensureUserExists`, and active group check before processing commands.
- [ ] **Update `TaskService.createTask`:** (`src/tasks/service.ts`) Handle `created_by` and assignments (including adding assigned users via `ensureUserExists`).
- [ ] **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.
- [ ] Create task history tracking.
## 🔑 Key Considerations & Caveats
## 🔑 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.
* **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.
* **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).
* **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.
* **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
## 🧪 Testing
### Running Tests
### Running Tests
@ -146,12 +148,13 @@ bun test
```
```
### Test Coverage
### Test Coverage
- Database initialization and basic operations.
- Database initialization and basic operations (`db.test.ts`).
