feat: complete tOS project with HR, LEAN, Dashboard and Integrations modules

Full enterprise web operating system including: - Next.js 14 frontend with App Router, i18n (DE/EN), shadcn/ui - NestJS 10 backend with Prisma, JWT auth, Swagger docs - Keycloak 24 SSO with role-based access control - HR module (employees, time tracking, absences, org chart) - LEAN module (3S planning, morning meeting SQCDM, skill matrix) - Integrations module (PlentyONE, Zulip, Todoist, FreeScout, Nextcloud, ecoDMS, GembaDocs) - Dashboard with customizable drag & drop widget grid - Docker Compose infrastructure (PostgreSQL 16, Redis 7, Keycloak 24) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-06 19:37:55 +01:00
parent a2b6612e9e
commit fe305f6fc8
509 changed files with 81111 additions and 1 deletions
--- a/.claude/agent-memory/integration-specialist/MEMORY.md
+++ b/.claude/agent-memory/integration-specialist/MEMORY.md
@@ -0,0 +1,169 @@
+# Integration Specialist Memory - tOS Project
+
+## Project Structure
+- **API Location**: `/apps/api/src/`
+- **Integrations Module**: `/apps/api/src/modules/integrations/`
+- **Connectors**: `/apps/api/src/modules/integrations/connectors/`
+
+## Phase 3 Connector Implementation (Completed)
+
+### Base Infrastructure
+- `base-connector.ts`: Abstract base class with axios, retry logic, rate limiting
+- `errors/integration.errors.ts`: Custom error classes (Auth, Connection, RateLimit, API, Config, Validation)
+
+### Implemented Connectors
+
+#### PlentyONE (`/connectors/plentyone/`)
+- **Auth**: OAuth2 Client Credentials flow
+- **Token Management**: Auto-refresh with 5-minute buffer
+- **Endpoints**: Orders, Stock, Statistics/Revenue
+- **Rate Limiting**: 60s timeout (PlentyONE can be slow)
+- **API Base**: `{baseUrl}/rest`
+
+#### ZULIP (`/connectors/zulip/`)
+- **Auth**: Basic Auth (email + API key)
+- **Endpoints**: Messages, Streams, Users
+- **API Base**: `{baseUrl}/api/v1`
+- **Note**: Form-encoded POST requests for some endpoints
+
+#### Todoist (`/connectors/todoist/`)
+- **Auth**: Bearer Token
+- **Endpoints**: Tasks, Projects, Sections, Labels
+- **API Base**: `https://api.todoist.com/rest/v2`
+- **Note**: Uses X-Request-Id header for idempotency
+
+#### FreeScout (`/connectors/freescout/`)
+- **Auth**: API Key via `X-FreeScout-API-Key` header
+- **Endpoints**: Conversations, Mailboxes, Customers, Tags
+- **API Base**: `{baseUrl}/api`
+- **API Docs**: https://github.com/freescout-helpdesk/freescout/wiki/API
+
+#### Nextcloud (`/connectors/nextcloud/`)
+- **Auth**: Basic Auth (username + app-password)
+- **Endpoints**: WebDAV Files, OCS Share API, CalDAV Calendar (basic)
+- **API Bases**: `{baseUrl}/remote.php/dav/files/{user}` (WebDAV), `{baseUrl}/ocs/v2.php` (OCS)
+- **Note**: WebDAV uses PROPFIND/MKCOL/MOVE/COPY; OCS needs `OCS-APIRequest: true` header
+
+#### ecoDMS (`/connectors/ecodms/`)
+- **Auth**: Session-based (login returns session ID, use `X-Session-Id` header)
+- **Endpoints**: Documents, Folders, Classifications, Search
+- **API Base**: `{baseUrl}/api/v1`
+- **Note**: Session auto-refresh before expiry; supports file upload with FormData
+
+## Environment Variables
+
+```bash
+# PlentyONE
+PLENTYONE_BASE_URL=
+PLENTYONE_CLIENT_ID=
+PLENTYONE_CLIENT_SECRET=
+
+# ZULIP
+ZULIP_BASE_URL=
+ZULIP_EMAIL=
+ZULIP_API_KEY=
+
+# Todoist
+TODOIST_API_TOKEN=
+
+# FreeScout
+FREESCOUT_API_URL=
+FREESCOUT_API_KEY=
+
+# Nextcloud
+NEXTCLOUD_URL=
+NEXTCLOUD_USERNAME=
+NEXTCLOUD_PASSWORD=
+
+# ecoDMS
+ECODMS_API_URL=
+ECODMS_USERNAME=
+ECODMS_PASSWORD=
+ECODMS_API_VERSION=v1
+```
+
+## Key Patterns
+
+### Retry Logic
+- Exponential backoff with jitter (0.5-1.5x multiplier)
+- Default: 3 retries, 1s initial delay, 30s max delay
+- Retry on: 429, 500, 502, 503, 504
+
+### Error Handling
+- `IntegrationConnectionError`: Network issues (retryable)
+- `IntegrationAuthError`: 401 responses (not retryable)
+- `IntegrationRateLimitError`: 429 responses (retryable after delay)
+- `IntegrationApiError`: Other API errors (retryable if 5xx)
+
+### Module Structure
+Each connector follows pattern:
+1. `{name}.types.ts` - TypeScript interfaces
+2. `{name}.connector.ts` - Low-level API client
+3. `{name}.service.ts` - Business logic layer
+4. `{name}.controller.ts` - HTTP endpoints
+5. `{name}.module.ts` - NestJS module
+6. `dto/*.dto.ts` - Request/Response DTOs
+
+## API Endpoints
+
+```
+GET  /integrations - Overview all integrations
+GET  /integrations/:type/status - Integration status
+GET  /integrations/:type/health - Health check
+
+POST /integrations/plentyone/test
+GET  /integrations/plentyone/orders
+GET  /integrations/plentyone/orders/:id
+GET  /integrations/plentyone/stock
+GET  /integrations/plentyone/stats
+
+POST /integrations/zulip/test
+GET  /integrations/zulip/messages
+POST /integrations/zulip/messages
+GET  /integrations/zulip/streams
+GET  /integrations/zulip/users
+
+POST /integrations/todoist/test
+GET  /integrations/todoist/tasks
+POST /integrations/todoist/tasks
+PUT  /integrations/todoist/tasks/:id
+DELETE /integrations/todoist/tasks/:id
+GET  /integrations/todoist/projects
+
+# FreeScout
+POST /integrations/freescout/test
+GET  /integrations/freescout/conversations
+GET  /integrations/freescout/conversations/:id
+POST /integrations/freescout/conversations
+POST /integrations/freescout/conversations/:id/reply
+GET  /integrations/freescout/mailboxes
+GET  /integrations/freescout/customers
+GET  /integrations/freescout/tags
+
+# Nextcloud
+POST /integrations/nextcloud/test
+GET  /integrations/nextcloud/files
+GET  /integrations/nextcloud/files/*path
+POST /integrations/nextcloud/files/upload
+DELETE /integrations/nextcloud/files/*path
+GET  /integrations/nextcloud/calendar/events
+
+# ecoDMS
+POST /integrations/ecodms/test
+GET  /integrations/ecodms/documents
+GET  /integrations/ecodms/documents/:id
+POST /integrations/ecodms/documents/search
+GET  /integrations/ecodms/documents/:id/download
+GET  /integrations/ecodms/folders
+GET  /integrations/ecodms/classifications
+```
+
+## Dependencies
+- `axios`: ^1.6.0 (HTTP client)
+- axios types included in axios package
+
+## Notes
+- All connectors check `isConfigured()` before operations
+- `getMissingConfig()` returns list of missing env vars
+- Logging in development mode by default
+- All API responses transformed to DTOs