finance_bot/DEPLOYMENT_CHECKLIST_API.md

# Bot API Integration - Deployment Checklist

## Phase 1: Database Migration ✅

- [ ] **Back up database** (if production)
  ```bash
  docker exec finance_bot_postgres pg_dump -U finance_user finance_db > backup.sql
  ```

- [ ] **Apply migration**
  ```bash
  docker exec finance_bot_migrations alembic upgrade head
  ```

- [ ] **Verify migration**
  ```bash
  docker exec finance_bot_migrations alembic current
  ```

- [ ] **Check tables**
  ```bash
  docker exec finance_bot_postgres psql -U finance_user -d finance_db -c "\d users"
  ```

---

## Phase 2: Code Updates ✅

- [ ] **User model updated** (`app/db/models/user.py`)
  - [x] Added `email` field
  - [x] Added `password_hash` field
  - [x] Made `telegram_id` nullable
  - [x] Added `email_verified` field

- [ ] **API endpoints added** (`app/api/auth.py`)
  - [x] `/auth/register` - Email registration
  - [x] `/auth/token/get` - Get token by chat_id
  - [x] `/auth/token/refresh-telegram` - Refresh token

- [ ] **Bot commands added** (`app/bot/client.py`)
  - [x] `/register` - Quick registration
  - [x] `/link` - Link existing account
  - [x] `/start` - Updated flow
  - [x] `/help` - Updated help text

- [ ] **Docker fixes** (`docker-compose.yml`)
  - [x] Removed deprecated `version` attribute
  - [x] Added `web` dependency for bot

---

## Phase 3: Container Rebuild

- [ ] **Rebuild containers**
  ```bash
  docker compose down
  docker compose up -d --build
  ```

- [ ] **Wait for services to start**
  ```bash
  docker compose ps
  ```

- [ ] **Check health**
  ```bash
  curl http://localhost:8000/health
  ```

---

## Phase 4: API Testing

### Test 1: Register with Email
```bash
curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "TestPass123",
    "first_name": "Test"
  }'
```
- [ ] Returns 200 with `access_token`
- [ ] Check logs: `docker logs finance_bot_web | tail -20`

### Test 2: Quick Telegram Registration
```bash
curl -X POST "http://localhost:8000/api/v1/auth/telegram/register?chat_id=556399210&username=john&first_name=John"
```
- [ ] Returns 200 with `jwt_token`
- [ ] Check database:
  ```bash
  docker exec finance_bot_postgres psql -U finance_user -d finance_db \
    -c "SELECT id, email, telegram_id FROM users WHERE telegram_id = 556399210"
  ```

### Test 3: Get Token
```bash
curl -X POST http://localhost:8000/api/v1/auth/token/get \
  -H "Content-Type: application/json" \
  -d '{"chat_id": 556399210}'
```
- [ ] Returns 200 with `access_token`
- [ ] Token format: `eyJ...`

---

## Phase 5: Bot Testing

- [ ] **Check bot is running**
  ```bash
  docker logs finance_bot_bot | tail -10
  ```

- [ ] **Send /start to bot**
  - [ ] Should see: "Welcome to Finance Bot!"
  - [ ] Should see: "/register" and "/link" options

- [ ] **Send /register to bot**
  - [ ] Should see: "Registration successful!"
  - [ ] User ID should be returned
  - [ ] Check Redis: `docker exec finance_bot_redis redis-cli get "chat_id:YOURIDEHERE:jwt"`

- [ ] **Send /help to bot**
  - [ ] Should show account commands
  - [ ] Should show transaction commands

---

## Phase 6: Token Storage Verification

- [ ] **Check Redis connection**
  ```bash
  docker exec finance_bot_redis redis-cli ping
  ```
  Expected: `PONG`

- [ ] **Check token storage**
  ```bash
  docker exec finance_bot_redis redis-cli keys "chat_id:*:jwt"
  ```
  Should list keys

- [ ] **Get stored token**
  ```bash
  docker exec finance_bot_redis redis-cli get "chat_id:556399210:jwt"
  ```
  Should return JWT token

---

## Phase 7: API Authenticated Calls

- [ ] **Get token from registration**
  ```bash
  TOKEN=$(curl -s -X POST http://localhost:8000/api/v1/auth/register \
    -H "Content-Type: application/json" \
    -d '{"email":"test@example.com","password":"test123"}' | jq -r '.access_token')
  ```

- [ ] **Make authenticated request**
  ```bash
  curl -X GET http://localhost:8000/api/v1/accounts \
    -H "Authorization: Bearer $TOKEN"
  ```
  Should return 200

- [ ] **Test with expired token**
  ```bash
  curl -X GET http://localhost:8000/api/v1/accounts \
    -H "Authorization: Bearer invalid_token"
  ```
  Should return 401

---

## Phase 8: Error Handling

- [ ] **Register with existing email**
  ```bash
  curl -X POST http://localhost:8000/api/v1/auth/register \
    -H "Content-Type: application/json" \
    -d '{"email":"test@example.com","password":"test123"}'
  ```
  Should return 400 with "Email already registered"

- [ ] **Get token for non-existent user**
  ```bash
  curl -X POST http://localhost:8000/api/v1/auth/token/get \
    -H "Content-Type: application/json" \
    -d '{"chat_id": 999999999}'
  ```
  Should return 404 with "User not found"

- [ ] **Missing required fields**
  ```bash
  curl -X POST http://localhost:8000/api/v1/auth/register \
    -H "Content-Type: application/json" \
    -d '{"email":"test@example.com"}'
  ```
  Should return 422 with validation error

---

## Phase 9: Database State

- [ ] **Check users table structure**
  ```bash
  docker exec finance_bot_postgres psql -U finance_user -d finance_db -c "\d users"
  ```
  Should show:
  - `email` (character varying, nullable)
  - `password_hash` (character varying, nullable)
  - `telegram_id` (integer, nullable)
  - `email_verified` (boolean)

- [ ] **Count users**
  ```bash
  docker exec finance_bot_postgres psql -U finance_user -d finance_db \
    -c "SELECT COUNT(*) as total_users FROM users"
  ```

- [ ] **Check recent registration**
  ```bash
  docker exec finance_bot_postgres psql -U finance_user -d finance_db \
    -c "SELECT id, email, telegram_id, created_at FROM users ORDER BY created_at DESC LIMIT 5"
  ```

---

## Phase 10: Log Monitoring

- [ ] **Monitor web service**
  ```bash
  docker logs -f finance_bot_web
  ```
  Watch for: `POST /api/v1/auth/register`, no errors

- [ ] **Monitor bot service**
  ```bash
  docker logs -f finance_bot_bot
  ```
  Watch for: `/register` command handling, token storage

- [ ] **Monitor database**
  ```bash
  docker logs finance_bot_postgres | tail -20
  ```
  Check for connection errors

---

## Phase 11: Documentation Check

- [ ] **API Integration Guide exists**
  - [x] `docs/API_INTEGRATION_GUIDE.md`

- [ ] **API Endpoints Reference exists**
  - [x] `docs/API_ENDPOINTS.md`

- [ ] **Summary Document exists**
  - [x] `BOT_API_INTEGRATION_SUMMARY.md`

- [ ] **Bot API Usage Example exists**
  - [x] `examples/bot_api_usage.py`

---

## Phase 12: Production Readiness

- [ ] **Security Review**
  - [ ] Password hashing uses strong algorithm (update if using default)
  - [ ] JWT tokens are short-lived
  - [ ] Tokens not logged or exposed
  - [ ] CORS properly configured

- [ ] **Environment Variables**
  ```bash
  docker compose config | grep -E "BOT_TOKEN|DATABASE_URL|REDIS_URL"
  ```
  Should all be set

- [ ] **Database Backups**
  ```bash
  ls -la backups/
  ```
  Recent backup exists

- [ ] **Monitoring Alerts**
  - [ ] Log rotation configured
  - [ ] Error monitoring enabled
  - [ ] Health checks working

---

## Phase 13: Rollback Plan

If issues occur, rollback steps:

```bash
# 1. Stop containers
docker compose down

# 2. Rollback database
docker compose up -d
docker exec finance_bot_migrations alembic downgrade -1

# 3. Rebuild with old code
docker compose down
git checkout previous-commit
docker compose up -d --build
```

---

## Completion Checklist

- [ ] All 13 phases completed
- [ ] No errors in logs
- [ ] All endpoints tested
- [ ] Bot commands work
- [ ] Tokens stored in Redis
- [ ] Database migrated
- [ ] Documentation updated
- [ ] Ready for production

---

## Support Resources

1. **API Documentation**: `docs/API_ENDPOINTS.md`
2. **Integration Guide**: `docs/API_INTEGRATION_GUIDE.md`
3. **Summary**: `BOT_API_INTEGRATION_SUMMARY.md`
4. **Examples**: `examples/bot_api_usage.py`
5. **Test Script**: `test_api.sh`

---

## Post-Deployment

- [ ] Monitor bot for 24 hours
- [ ] Check error logs daily
- [ ] Test /register and /link commands weekly
- [ ] Review token refresh rates
- [ ] Monitor Redis memory usage

---

**Status**: Ready for deployment ✅

Last Updated: 2025-12-11