feat: Complete API authentication system with email & Telegram support
- Add email/password registration endpoint (/api/v1/auth/register) - Add JWT token endpoints for Telegram users (/api/v1/auth/token/get, /api/v1/auth/token/refresh-telegram) - Enhance User model to support both email and Telegram authentication - Fix JWT token handling: convert sub to string (RFC compliance with PyJWT 2.10.1+) - Fix bot API calls: filter None values from query parameters - Fix JWT extraction from Redis: handle both bytes and string returns - Add public endpoints to JWT middleware: /api/v1/auth/register, /api/v1/auth/token/* - Update bot commands: /register (one-tap), /link (account linking), /start (options) - Create complete database schema migration with email auth support - Remove deprecated version attribute from docker-compose.yml - Add service dependency: bot waits for web service startup Features: - Dual authentication: email/password OR Telegram ID - JWT tokens with 15-min access + 30-day refresh lifetime - Redis-based token storage with TTL - Comprehensive API documentation and integration guides - Test scripts and Python examples - Full deployment checklist Database changes: - User model: added email, password_hash, email_verified (nullable fields) - telegram_id now nullable to support email-only users - Complete schema with families, accounts, categories, transactions, budgets, goals Status: Production-ready with all tests passing
This commit is contained in:
376
API_DOCUMENTATION_INDEX.md
Normal file
376
API_DOCUMENTATION_INDEX.md
Normal file
@@ -0,0 +1,376 @@
|
||||
# 📚 Bot API Integration - Documentation Index
|
||||
|
||||
## 🎯 Start Here
|
||||
|
||||
Выберите документ в зависимости от вашей роли:
|
||||
|
||||
### 👤 **I'm a User/Tester**
|
||||
1. Start: [`API_QUICK_START.md`](API_QUICK_START.md) - 5 минут
|
||||
2. Testing: Follow Quick Tests section
|
||||
3. Troubleshoot: See Troubleshooting section
|
||||
|
||||
### 👨💻 **I'm a Developer**
|
||||
1. Overview: [`API_CHANGES_SUMMARY.md`](API_CHANGES_SUMMARY.md)
|
||||
2. API Reference: [`docs/API_ENDPOINTS.md`](docs/API_ENDPOINTS.md)
|
||||
3. Integration: [`docs/API_INTEGRATION_GUIDE.md`](docs/API_INTEGRATION_GUIDE.md)
|
||||
4. Code Examples: [`examples/bot_api_usage.py`](examples/bot_api_usage.py)
|
||||
|
||||
### 🚀 **I'm Deploying to Production**
|
||||
1. Checklist: [`DEPLOYMENT_CHECKLIST_API.md`](DEPLOYMENT_CHECKLIST_API.md) - 13 phases
|
||||
2. Migration: Phase 1 in checklist
|
||||
3. Testing: Phase 4-7 in checklist
|
||||
4. Monitoring: Phase 10 in checklist
|
||||
|
||||
### 🔧 **I'm Maintaining/Debugging**
|
||||
1. Changes: [`API_CHANGES_SUMMARY.md`](API_CHANGES_SUMMARY.md)
|
||||
2. Endpoints: [`docs/API_ENDPOINTS.md`](docs/API_ENDPOINTS.md)
|
||||
3. Integration: [`docs/API_INTEGRATION_GUIDE.md`](docs/API_INTEGRATION_GUIDE.md)
|
||||
4. Common Commands: [`API_QUICK_START.md`](API_QUICK_START.md#-common-commands)
|
||||
|
||||
---
|
||||
|
||||
## 📖 Complete Documentation
|
||||
|
||||
### Main Documentation Files
|
||||
|
||||
| File | Purpose | Read Time |
|
||||
|------|---------|-----------|
|
||||
| [`API_CHANGES_SUMMARY.md`](API_CHANGES_SUMMARY.md) | Overview of all changes | 5 min |
|
||||
| [`API_QUICK_START.md`](API_QUICK_START.md) | Quick deployment & testing | 5 min |
|
||||
| [`DEPLOYMENT_CHECKLIST_API.md`](DEPLOYMENT_CHECKLIST_API.md) | Full deployment guide (13 phases) | 30 min |
|
||||
| [`docs/API_ENDPOINTS.md`](docs/API_ENDPOINTS.md) | Complete API reference | 15 min |
|
||||
| [`docs/API_INTEGRATION_GUIDE.md`](docs/API_INTEGRATION_GUIDE.md) | Integration guide with code | 20 min |
|
||||
| [`BOT_API_INTEGRATION_SUMMARY.md`](BOT_API_INTEGRATION_SUMMARY.md) | Detailed implementation summary | 15 min |
|
||||
|
||||
### Code & Examples
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| [`examples/bot_api_usage.py`](examples/bot_api_usage.py) | Python implementation examples |
|
||||
| [`test_api.sh`](test_api.sh) | Bash test script for all endpoints |
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Reference
|
||||
|
||||
### Most Common Tasks
|
||||
|
||||
#### 1. Deploy Everything
|
||||
```bash
|
||||
# See API_QUICK_START.md → Deploy in 5 Minutes
|
||||
docker compose down
|
||||
docker compose up -d --build
|
||||
docker exec finance_bot_migrations alembic upgrade head
|
||||
```
|
||||
|
||||
#### 2. Register a User
|
||||
```bash
|
||||
# Email registration
|
||||
curl -X POST http://localhost:8000/api/v1/auth/register \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"email":"user@example.com","password":"pass123"}'
|
||||
|
||||
# Telegram quick registration
|
||||
curl -X POST "http://localhost:8000/api/v1/auth/telegram/register" \
|
||||
-G --data-urlencode "chat_id=556399210" \
|
||||
--data-urlencode "username=john_doe"
|
||||
```
|
||||
|
||||
#### 3. Get Token
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/api/v1/auth/token/get \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"chat_id": 556399210}'
|
||||
```
|
||||
|
||||
#### 4. Make API Call
|
||||
```bash
|
||||
curl -X GET http://localhost:8000/api/v1/accounts \
|
||||
-H "Authorization: Bearer <token>"
|
||||
```
|
||||
|
||||
#### 5. Check Logs
|
||||
```bash
|
||||
docker logs -f finance_bot_web # Web service
|
||||
docker logs -f finance_bot_bot # Bot service
|
||||
docker logs -f finance_bot_postgres # Database
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 What Was Added
|
||||
|
||||
### API Endpoints
|
||||
- ✅ `POST /api/v1/auth/register` - Email registration
|
||||
- ✅ `POST /api/v1/auth/token/get` - Get token by chat_id
|
||||
- ✅ `POST /api/v1/auth/token/refresh-telegram` - Refresh token
|
||||
- ✅ `POST /api/v1/auth/telegram/register` - Quick Telegram registration
|
||||
|
||||
### Bot Commands
|
||||
- ✅ `/start` - Show registration options
|
||||
- ✅ `/register` - One-tap Telegram registration
|
||||
- ✅ `/link` - Link existing account
|
||||
- ✅ `/help` - Updated help text
|
||||
|
||||
### Database
|
||||
- ✅ `email` field (unique, nullable)
|
||||
- ✅ `password_hash` field
|
||||
- ✅ `telegram_id` made nullable
|
||||
- ✅ `email_verified` field
|
||||
|
||||
### Documentation
|
||||
- ✅ `docs/API_ENDPOINTS.md` - Full API reference
|
||||
- ✅ `docs/API_INTEGRATION_GUIDE.md` - Integration guide
|
||||
- ✅ `examples/bot_api_usage.py` - Code examples
|
||||
- ✅ This file and 5 others
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Authentication Flows
|
||||
|
||||
### Quick Registration (1 command)
|
||||
```
|
||||
User /register → Bot API call → JWT Token → Ready!
|
||||
```
|
||||
|
||||
### Email Account Link (3 steps)
|
||||
```
|
||||
User /link → Get Code → User confirms → Get JWT → Ready!
|
||||
```
|
||||
|
||||
### Email Registration
|
||||
```
|
||||
User → Web → Register → Get Tokens → Make API calls
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing Guide
|
||||
|
||||
### Phase 1: Health Check
|
||||
```bash
|
||||
curl http://localhost:8000/health
|
||||
# Expected: {"status": "ok"}
|
||||
```
|
||||
|
||||
### Phase 2: Email Registration
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/api/v1/auth/register \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"email":"test@example.com","password":"test123"}'
|
||||
# Expected: 200 with access_token
|
||||
```
|
||||
|
||||
### Phase 3: Get Token
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/api/v1/auth/token/get \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"chat_id": 556399210}'
|
||||
# Expected: 200 with access_token
|
||||
```
|
||||
|
||||
### Phase 4: Quick Telegram Registration
|
||||
```bash
|
||||
curl -X POST "http://localhost:8000/api/v1/auth/telegram/register?chat_id=556399210&username=john"
|
||||
# Expected: 200 with jwt_token
|
||||
```
|
||||
|
||||
### Phase 5: Authenticated Request
|
||||
```bash
|
||||
curl -X GET http://localhost:8000/api/v1/accounts \
|
||||
-H "Authorization: Bearer <token>"
|
||||
# Expected: 200 or empty list
|
||||
```
|
||||
|
||||
See [`DEPLOYMENT_CHECKLIST_API.md`](DEPLOYMENT_CHECKLIST_API.md) for full testing guide.
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Troubleshooting
|
||||
|
||||
### Database Migration Failed
|
||||
```bash
|
||||
# Check status
|
||||
docker exec finance_bot_migrations alembic current
|
||||
|
||||
# Rollback and retry
|
||||
docker exec finance_bot_migrations alembic downgrade -1
|
||||
docker exec finance_bot_migrations alembic upgrade head
|
||||
```
|
||||
|
||||
### Bot Can't Connect to Web
|
||||
```bash
|
||||
# Check network
|
||||
docker network ls
|
||||
docker network inspect finance_network
|
||||
|
||||
# Test connection
|
||||
docker exec finance_bot_bot curl http://web:8000/health
|
||||
```
|
||||
|
||||
### Tokens Not Stored in Redis
|
||||
```bash
|
||||
# Check Redis
|
||||
docker exec finance_bot_redis redis-cli ping
|
||||
|
||||
# List tokens
|
||||
docker exec finance_bot_redis redis-cli keys "chat_id:*:jwt"
|
||||
```
|
||||
|
||||
### API Returns 500
|
||||
```bash
|
||||
# Check logs
|
||||
docker logs finance_bot_web | grep ERROR
|
||||
|
||||
# Restart
|
||||
docker restart finance_bot_web
|
||||
```
|
||||
|
||||
See [`API_QUICK_START.md#-troubleshooting`](API_QUICK_START.md#-troubleshooting) for more.
|
||||
|
||||
---
|
||||
|
||||
## 📊 File Structure
|
||||
|
||||
```
|
||||
finance_bot/
|
||||
├── docs/
|
||||
│ ├── API_ENDPOINTS.md # Complete API reference
|
||||
│ ├── API_INTEGRATION_GUIDE.md # Integration guide
|
||||
│ └── ARCHITECTURE.md # (existing)
|
||||
├── examples/
|
||||
│ └── bot_api_usage.py # Python examples
|
||||
├── migrations/versions/
|
||||
│ └── 003_add_email_auth.py # Database migration
|
||||
├── app/
|
||||
│ ├── db/models/
|
||||
│ │ └── user.py # Updated: email + password
|
||||
│ ├── api/
|
||||
│ │ └── auth.py # Added 3 new endpoints
|
||||
│ └── bot/
|
||||
│ └── client.py # Added 2 new commands
|
||||
├── API_QUICK_START.md # Quick start (5 min)
|
||||
├── API_CHANGES_SUMMARY.md # What changed
|
||||
├── BOT_API_INTEGRATION_SUMMARY.md # Detailed summary
|
||||
├── DEPLOYMENT_CHECKLIST_API.md # 13-phase checklist
|
||||
├── test_api.sh # Test script
|
||||
└── API_DOCUMENTATION_INDEX.md # This file!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Learning Path
|
||||
|
||||
### Beginner (15 minutes)
|
||||
1. Read [`API_CHANGES_SUMMARY.md`](API_CHANGES_SUMMARY.md) - What changed
|
||||
2. Follow [`API_QUICK_START.md`](API_QUICK_START.md) - Quick start
|
||||
3. Run test script: `bash test_api.sh`
|
||||
|
||||
### Intermediate (30 minutes)
|
||||
1. Read [`docs/API_INTEGRATION_GUIDE.md`](docs/API_INTEGRATION_GUIDE.md)
|
||||
2. Study [`examples/bot_api_usage.py`](examples/bot_api_usage.py)
|
||||
3. Test each endpoint with cURL
|
||||
4. Follow [`DEPLOYMENT_CHECKLIST_API.md`](DEPLOYMENT_CHECKLIST_API.md) phase 1-3
|
||||
|
||||
### Advanced (60 minutes)
|
||||
1. Complete all phases in [`DEPLOYMENT_CHECKLIST_API.md`](DEPLOYMENT_CHECKLIST_API.md)
|
||||
2. Review database migration in `migrations/versions/003_add_email_auth.py`
|
||||
3. Implement token refresh logic in your code
|
||||
4. Set up monitoring and alerts
|
||||
|
||||
---
|
||||
|
||||
## 💼 For Teams
|
||||
|
||||
### Frontend Team
|
||||
- Read: [`docs/API_INTEGRATION_GUIDE.md`](docs/API_INTEGRATION_GUIDE.md)
|
||||
- Reference: [`docs/API_ENDPOINTS.md`](docs/API_ENDPOINTS.md)
|
||||
- Endpoints: `/api/v1/auth/register`, `/api/v1/auth/login`, `/api/v1/auth/telegram/confirm`
|
||||
|
||||
### Backend Team
|
||||
- Read: [`BOT_API_INTEGRATION_SUMMARY.md`](BOT_API_INTEGRATION_SUMMARY.md)
|
||||
- Reference: [`docs/API_ENDPOINTS.md`](docs/API_ENDPOINTS.md)
|
||||
- Files: `app/api/auth.py`, `app/db/models/user.py`, `migrations/`
|
||||
|
||||
### DevOps Team
|
||||
- Read: [`DEPLOYMENT_CHECKLIST_API.md`](DEPLOYMENT_CHECKLIST_API.md)
|
||||
- Reference: [`API_QUICK_START.md`](API_QUICK_START.md)
|
||||
- Commands: Migration, rebuild, testing phases
|
||||
|
||||
### QA Team
|
||||
- Read: [`API_QUICK_START.md`](API_QUICK_START.md)
|
||||
- Follow: Phases 4-7 in [`DEPLOYMENT_CHECKLIST_API.md`](DEPLOYMENT_CHECKLIST_API.md)
|
||||
- Use: `test_api.sh` script
|
||||
|
||||
---
|
||||
|
||||
## 🔗 External Resources
|
||||
|
||||
### JWT Authentication
|
||||
- [jwt.io](https://jwt.io) - JWT debugger and information
|
||||
- [FastAPI Security](https://fastapi.tiangolo.com/tutorial/security/)
|
||||
|
||||
### Telegram Bot
|
||||
- [aiogram documentation](https://docs.aiogram.dev)
|
||||
- [Telegram Bot API](https://core.telegram.org/bots/api)
|
||||
|
||||
### Docker & Compose
|
||||
- [Docker Compose Reference](https://docs.docker.com/compose/compose-file/)
|
||||
- [Docker Network Guide](https://docs.docker.com/network/)
|
||||
|
||||
### Database
|
||||
- [PostgreSQL Documentation](https://www.postgresql.org/docs/)
|
||||
- [Alembic Documentation](https://alembic.sqlalchemy.org/)
|
||||
|
||||
---
|
||||
|
||||
## ✅ Verification Checklist
|
||||
|
||||
Before going live:
|
||||
- [ ] All documentation read
|
||||
- [ ] Database migration applied
|
||||
- [ ] All API endpoints tested
|
||||
- [ ] Bot commands working
|
||||
- [ ] Tokens storing in Redis
|
||||
- [ ] No errors in logs
|
||||
- [ ] Load testing done
|
||||
- [ ] Security review complete
|
||||
- [ ] Monitoring configured
|
||||
- [ ] Rollback plan ready
|
||||
|
||||
---
|
||||
|
||||
## 📞 Support & Troubleshooting
|
||||
|
||||
### Getting Help
|
||||
1. Check the relevant documentation file above
|
||||
2. Search for your error in logs: `docker logs`
|
||||
3. Run test script: `bash test_api.sh`
|
||||
4. Check troubleshooting section in [`API_QUICK_START.md`](API_QUICK_START.md)
|
||||
|
||||
### Common Issues
|
||||
- **"Email already registered"** → Use different email
|
||||
- **"User not found"** → Register first, then get token
|
||||
- **"Cannot connect to host web"** → Wait for web service to start
|
||||
- **Token not in Redis** → Check Redis connection
|
||||
|
||||
---
|
||||
|
||||
## 🎉 Completion
|
||||
|
||||
You now have:
|
||||
- ✅ 6 documentation files
|
||||
- ✅ 2 code example files
|
||||
- ✅ 1 test script
|
||||
- ✅ 1 deployment checklist
|
||||
- ✅ 5 modified application files
|
||||
- ✅ 1 new database migration
|
||||
- ✅ Complete API integration
|
||||
|
||||
**Next Step**: Choose your path above and start reading!
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-12-11
|
||||
**Status**: ✅ Ready for Production
|
||||
**Version**: 1.0.0
|
||||
Reference in New Issue
Block a user