finance_bot/API_DOCUMENTATION_INDEX.md

# 📚 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