feat(gateway): include production Telegram user gateway

Version the NestJS TDLib gateway with Docker deployment, migrations, automated tests and platform integration documentation while excluding all account sessions, credentials, runtime databases and backups.
2026-08-01 18:38:20 +08:00
parent af49d22ca7
commit 06112602ec
142 changed files with 23107 additions and 7 deletions
@@ -0,0 +1,112 @@
+# Telegram User Account Gateway
+
+A production-grade REST API + Webhook gateway for managing Telegram user accounts via TDLib (not Bot API). Supports multi-tenant, multi-account management with independent proxies, message queue, rate limiting, and audit logging.
+
+## Architecture
+
+- **Runtime**: Node.js 20+ with TypeScript
+- **Framework**: NestJS 11.x
+- **Database**: PostgreSQL 16 (TypeORM)
+- **Cache/Queue**: Redis 7 + BullMQ
+- **TDLib**: tdjson via worker_threads
+- **Auth**: JWT (Bearer tokens)
+- **API Docs**: Swagger at `/api/docs`
+
+## Quick Start
+
+```bash
+# Copy environment config
+cp .env.example .env
+
+# Start infrastructure
+docker-compose -f docker/docker-compose.yml up -d postgres redis
+
+# Install dependencies
+npm install
+
+# Run migrations
+npm run migration:run
+
+# Start development server
+npm run start:dev
+```
+
+## Docker Compose
+
+```bash
+# Start all services
+docker compose --env-file .env -f docker/docker-compose.yml up -d --build
+```
+
+See [DEPLOYMENT.md](./DEPLOYMENT.md) for production setup, readiness checks,
+persistent data, and Windows WSL requirements.
+
+When used by 灵犀跨境, also read the repository-level
+[integration guide](../docs/TELEGRAM-GATEWAY.md).
+
+## API Endpoints
+
+### Admin
+- `GET /api/admin/health` - Health check (public)
+- `GET /api/admin/metrics` - Application metrics
+- `GET /api/admin/status` - TDLib client status
+
+### Auth
+- `POST /api/auth/register` - Register user (public)
+- `POST /api/auth/login` - Login (public)
+
+### Tenants
+- `POST /api/tenants` - Create tenant
+- `GET /api/tenants` - List tenants
+- `GET /api/tenants/:id` - Get tenant
+- `PUT /api/tenants/:id` - Update tenant
+- `DELETE /api/tenants/:id` - Delete tenant
+
+### TG Accounts
+- `POST /api/tg-accounts` - Create Telegram account
+- `GET /api/tg-accounts` - List accounts
+- `GET /api/tg-accounts/:id` - Get account
+- `DELETE /api/tg-accounts/:id` - Remove account
+
+### TG Account Authorization
+- `POST /api/tg-accounts/:id/auth/phone` - Set phone number
+- `POST /api/tg-accounts/:id/auth/code` - Submit verification code
+- `POST /api/tg-accounts/:id/auth/password` - Submit 2FA password
+- `POST /api/tg-accounts/:id/auth/logout` - Logout
+
+### Chats & Messages
+- `GET /api/tg-accounts/:id/chats` - List chats
+- `GET /api/tg-accounts/:id/chats/:chatId/history` - Chat history
+- `POST /api/tg-accounts/:id/messages/send` - Send message (queued)
+- `POST /api/tg-accounts/:id/messages/send-direct` - Send message (direct)
+- `POST /api/tg-accounts/:id/messages/pin` - Pin a message
+- `POST /api/tg-accounts/:id/messages/unpin` - Unpin a message
+- `POST /api/tg-accounts/:id/messages/action` - Send typing/chat action
+- `GET /api/tg-accounts/:id/messages/:chatId/:messageId/link` - Get message link
+
+### Contacts, Sessions & Groups
+- `GET /api/tg-accounts/:id/contacts/search?q=...` - Search by phone, username, or general query
+- `GET /api/tg-accounts/:id/dialogs/sessions` - List active Telegram sessions
+- `POST /api/tg-accounts/:id/dialogs/sessions/:sessionId/terminate` - Terminate session
+- `POST /api/tg-accounts/:id/dialogs/users/:userId/block` - Block user
+- `POST /api/tg-accounts/:id/dialogs/users/:userId/unblock` - Unblock user
+- `POST /api/tg-accounts/:id/groups/join-by-invite-link` - Join via invite link
+- `PUT /api/tg-accounts/:id/groups/:chatId/title` - Change group title
+- `PUT /api/tg-accounts/:id/groups/:chatId/photo` - Change/remove group photo
+
+### Webhooks
+- `POST /api/tg-accounts/:id/webhooks` - Create webhook
+- `GET /api/tg-accounts/:id/webhooks` - List webhooks
+
+### Operations
+- `GET /api/admin/audit-logs` - Query tenant-scoped audit logs
+- `GET /api/admin/audit-logs/accounts/:accountId` - Query account audit logs
+- `GET /api/admin/rate-limits/:accountId` - Get account rate-limit statistics
+
+## Environment Variables
+
+See `.env.example` for all available configuration options.
+
+## License
+
+MIT