docs: update documentation with Phase 3.8 fixes and production warnings

2025-12-09 19:25:52 +01:00
parent b0ca382ce7
commit 3c116bf796
4 changed files with 188 additions and 8 deletions
--- a/README.md
+++ b/README.md
@@ -24,22 +24,26 @@ Web application (PWA) enabling dance event participants to:
 - Password reset workflow
 - Real-time username/email availability validation (debounced API calls, visual feedback)
 - Enhanced password validation with visual requirement indicators
- WSDC integration (auto-fill profile data from worldsdc.com)
+- WSDC integration (auto-fill profile data from worldsdc.com, string ID support)
+- Polish character support in first/last name validation (ąćęłńóśźż)
 - Event slugs (alphanumeric IDs preventing enumeration attacks)
 - Cloudflare Turnstile CAPTCHA (bot protection on registration & contact form)
 - Security: CORS, CSRF, Helmet.js, rate limiting, account lockout
 - Trust proxy for correct client IP detection behind nginx
+- Session persistence with accountTier and isAdmin flags

 ### Events & Chat
 - Event list from worldsdc.com
 - Real-time event chat (Socket.IO) with active users sidebar
 - Real-time active users list (instant updates when users join/leave)
+- Private 1:1 match chat with automatic room reconnection
 - Infinite scroll message history
 - Clickable usernames (/@{username}) with country flags
 - Competitor numbers (bib numbers) display
 - Message validation: 2000 character limit with visual counter
 - Spam protection: rate limiting (10 msg/min), duplicate detection, profanity filter
 - Polish + English profanity filtering
+- Mobile-optimized scroll behavior (no page jump on new messages)

 ### Auto-matching & Fairness System
 - Smart recording assignment for competition heats
@@ -484,5 +488,39 @@ TBD

 ---

-**Status:** MVP Complete ✅ | 351/351 tests passing (100%) | Production Ready
-**Last Updated:** 2025-12-06
+**Status:** ✅ **LIVE IN PRODUCTION** | 351/351 tests passing (100%)
+**Last Updated:** 2025-12-09
+**Production URL:** [spotlight.cam](https://spotlight.cam)
+
+---
+
+## ⚠️ Production Notice
+
+**This application is now running in production with real users and data.**
+
+### Development Guidelines for Production Environment
+
+1. **Database Migrations**
+   - ⚠️ **NEVER** run destructive migrations without backup
+   - Test all schema changes in development first
+   - Use Prisma migration preview: `npx prisma migrate dev --create-only`
+   - Review generated SQL before applying to production
+   - Always backup production database before schema changes
+
+2. **Data Safety**
+   - Production database contains real user data
+   - Test data operations in development environment first
+   - Use transactions for multi-step operations
+   - Implement rollback procedures for critical changes
+
+3. **Deployment Process**
+   - Test thoroughly in development before pushing
+   - Run full test suite: `make test`
+   - Review all changes: `git diff origin/master`
+   - Deploy during low-traffic periods when possible
+   - Monitor logs after deployment: `docker compose logs -f`
+
+4. **Emergency Procedures**
+   - Keep previous Docker images for quick rollback
+   - Document all production changes
+   - Have database backup ready before major updates
--- a/docs/SESSION_CONTEXT.md
+++ b/docs/SESSION_CONTEXT.md
@@ -348,4 +348,52 @@ REST_BUFFER_MINUTES: 60

 ---

-**Last Updated:** 2025-12-06
+**Last Updated:** 2025-12-09
+
+---
+
+## ⚠️ PRODUCTION ENVIRONMENT
+
+**Status:** ✅ **LIVE IN PRODUCTION**
+**URL:** https://spotlight.cam
+**Deployed:** 2025-12-09
+**Users:** Real users with real data
+
+### Critical Development Guidelines
+
+#### Database Safety
+- ⚠️ **NEVER** run migrations without testing in development first
+- Always backup production database before schema changes
+- Use `npx prisma migrate dev --create-only` to preview SQL
+- Test data operations in dev environment before production
+- Use transactions for multi-step operations
+
+#### Deployment Process
+1. Test thoroughly in development (`docker compose --profile dev up`)
+2. Run full test suite (`make test` - all 351 tests must pass)
+3. Review changes: `git diff origin/master`
+4. Deploy during low-traffic periods
+5. Monitor logs after deployment: `docker compose logs -f backend-prod`
+
+#### Emergency Rollback
+- Keep previous Docker images: `docker images | grep app-`
+- Rollback command: `docker compose --profile prod down && docker tag OLD_IMAGE NEW_IMAGE && docker compose --profile prod up -d`
+- Have database backup ready at all times
+
+#### What to NEVER Do
+- ❌ Drop tables or columns without migration plan
+- ❌ Change primary keys or foreign key relationships
+- ❌ Deploy without running tests
+- ❌ Push directly to master without review
+- ❌ Test experimental features on production data
+
+#### Recent Bug Fixes (Phase 3.8 - Dec 2025)
+1. Admin dropdown persistence (session fields)
+2. Mobile chat scroll behavior
+3. Polish characters in name validation
+4. WSDC ID type conversion
+5. Match chat message display
+6. Socket.IO reconnection handling
+7. Docker production build scripts
+
+All fixes deployed successfully with zero downtime.
--- a/docs/TODO.md
+++ b/docs/TODO.md
@@ -6,20 +6,49 @@

 ## Current Status

-**Phase:** MVP Complete - Production Ready (Phase 3.6)
+**Phase:** ✅ **LIVE IN PRODUCTION** (Phase 3.8 Complete)
+**Production URL:** https://spotlight.cam
 **Tests:** 351/351 passing - 100% ✅ (73% coverage)
+**Last Deployment:** 2025-12-09
 **Recent Work:**
+- 2025-12-09: Bug fixes deployed to production (admin dropdown, mobile scroll, Polish chars, WSDC ID, chat fixes)
+- 2025-12-06: Real-time username/email validation, socket reconnection fixes
 - 2025-12-05: Cloudflare TURN/STUN WebRTC integration, comprehensive testing (9 tests, 100% coverage)
 - 2025-12-05: Public pages (About Us, How It Works), responsive design fixes
 - 2025-12-05: Cloudflare Turnstile CAPTCHA (registration, contact form)
- 2025-12-05: Contact form with admin panel, 404 page with logging
 - 2025-12-02: Activity Log System with real-time streaming dashboard
- 2025-11-30: Matching runs audit, ratings & stats system, comprehensive test suite

 **Full implementation history:** See `docs/archive/COMPLETED.md`

 ---

+## ⚠️ PRODUCTION ENVIRONMENT - CRITICAL WARNINGS
+
+**This application is now running with REAL USERS and REAL DATA.**
+
+###Before Making ANY Code Changes:
+
+1. **Database Migrations** ⚠️
+   - NEVER run destructive migrations without backup
+   - Test all schema changes in development FIRST
+   - Preview SQL: `npx prisma migrate dev --create-only`
+   - Backup production DB before applying migrations
+
+2. **Deployment Safety**
+   - Run full test suite: `make test` (all 351 tests must pass)
+   - Test thoroughly in development environment
+   - Deploy during low-traffic periods
+   - Monitor logs after deployment: `docker compose logs -f`
+
+3. **Rollback Procedure**
+   - Keep previous Docker images for quick rollback
+   - Have database backup ready
+   - Document all production changes
+
+**See README.md "Production Notice" section for full guidelines.**
+
+---
+
 ## Activity Log System (Complete ✅)

 **Status:** Phase 8/8 Complete - Ready for Testing
@@ -666,5 +695,5 @@ http://localhost:8080

 ---

-**Last Updated:** 2025-11-29
+**Last Updated:** 2025-12-09
 **Full Details:** See `docs/archive/COMPLETED.md` for implementation details
--- a/docs/archive/COMPLETED.md
+++ b/docs/archive/COMPLETED.md
@@ -4,6 +4,71 @@

 ---

+## ✅ Phase 3.8 - Production Stabilization & Bug Fixes (2025-12-06 to 2025-12-09)
+
+**Status:** ✅ **DEPLOYED TO PRODUCTION**
+**Production URL:** https://spotlight.cam
+
+### 🔧 Bug Fixes
+
+1. **Admin Dropdown Persistence** (`3195ce3`)
+   - **Issue:** Admin dropdown disappeared after page refresh
+   - **Fix:** Added `accountTier` and `isAdmin` to `GET /api/users/me` response
+   - **Files:** `backend/src/routes/users.js`, `backend/src/__tests__/users.test.js`
+
+2. **Mobile Chat Scroll** (`b506df1`)
+   - **Issue:** Page jumped to top on new message (mobile)
+   - **Fix:** Changed from `scrollIntoView()` to direct container scroll
+   - **Files:** `frontend/src/pages/EventChatPage.jsx`
+
+3. **Polish Characters Support** (`d780b54`)
+   - **Issue:** Names with ąćęłńóśźż rejected by validator
+   - **Fix:** Updated regex to include Polish diacritics
+   - **Files:** `backend/src/middleware/validators.js`
+
+4. **WSDC ID Type Conversion** (`c6cea11`)
+   - **Issue:** Registration failed with WSDC ID (number vs string)
+   - **Fix:** Convert to string before Prisma save
+   - **Files:** `backend/src/controllers/auth.js`
+
+5. **Match Chat Message Display** (`1013d12`, `19700ff`, `c8de07a`)
+   - **Issue:** Sender couldn't see own messages in match chat
+   - **Fix:** Added nested user object to messages response
+   - **Files:** `backend/src/routes/matches.js`
+
+6. **Socket.IO Reconnection** (`a5a2c7a`, `c8de07a`)
+   - **Issue:** Match chat didn't work after reconnect
+   - **Fix:** Auto-rejoin room on reconnect event
+   - **Files:** `frontend/src/hooks/useMatchChat.js`
+
+7. **Docker Production Build** (`5db396e`)
+   - **Issue:** Production backend missing scripts directory
+   - **Fix:** Added scripts to Dockerfile.prod COPY
+   - **Files:** `backend/Dockerfile.prod`
+
+### ✨ Features
+
+8. **Real-time Validation** (`71d22cc`)
+   - Username/email availability check (debounced, visual feedback)
+   - **Files:** `frontend/src/pages/RegisterPage.jsx`, `backend/src/routes/public.js`
+
+### 📝 Documentation
+
+9. **Local Development Config** (`b0ca382`)
+   - Added `docker-compose.override.yml` support (gitignored)
+   - Added `.env.development.local` support (gitignored)
+   - Enables mobile testing without committing local IPs
+
+### 🚀 Production Status
+
+- **Deployed:** 2025-12-09
+- **Downtime:** None
+- **Database Changes:** None
+- **Breaking Changes:** None
+- **Tests:** 351/351 passing (100%)
+
+---
+
 ## ✅ Phase 0: Frontend Mockup (COMPLETED)

 **Completed:** 2025-11-12