fix: harden admin access, repair ORM joins, and add migration/tests

TESTING_WALKTHROUGH.md

@@ -0,0 +1,162 @@
+# Yellow Bank Soal - Testing Walkthrough Guide
+
+Date: 2026-03-31
+
+This guide walks through local verification after the defect-fix batch:
+- model mapping/FK fixes
+- admin runtime gating and auth wiring
+- query and normalization fixes
+- migration baseline setup
+
+## 1) Prerequisites
+
+- Python 3.10+
+- PostgreSQL (for integration/API tests)
+- Redis (required when `ENABLE_ADMIN=true`)
+
+## 2) Environment Setup
+
+From project root:
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+```
+
+Create `.env` from `.env.example` and set at minimum:
+
+```env
+DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/irt_bank_soal
+REDIS_URL=redis://localhost:6379/0
+ENVIRONMENT=development
+
+# Keep false unless explicitly testing admin:
+ENABLE_ADMIN=false
+
+# Required only when ENABLE_ADMIN=true
+ADMIN_USERNAME=admin
+ADMIN_PASSWORD=change-me
+ADMIN_SESSION_EXPIRE_SECONDS=3600
+```
+
+## 3) Fast Checks (No DB Required)
+
+### 3.1 Compile check
+
+```bash
+.venv/bin/python -m compileall -q app tests alembic
+```
+
+Expected: no errors.
+
+### 3.2 Model mapping smoke test
+
+```bash
+.venv/bin/python - <<'PY'
+from sqlalchemy.orm import configure_mappers
+import app.models  # noqa: F401
+configure_mappers()
+print("mappers_ok")
+PY
+```
+
+Expected output:
+
+```text
+mappers_ok
+```
+
+### 3.3 Unit tests
+
+```bash
+.venv/bin/pytest -q
+```
+
+Expected: all tests pass.
+
+## 4) Migration Checks
+
+### 4.1 Confirm migration chain
+
+```bash
+.venv/bin/alembic history
+```
+
+Expected head:
+
+```text
+<base> -> 20260331_000001 (head), initial schema
+```
+
+### 4.2 Offline SQL generation (safe dry run)
+
+```bash
+.venv/bin/alembic upgrade head --sql > /tmp/alembic_upgrade.sql
+head -n 30 /tmp/alembic_upgrade.sql
+```
+
+Expected: SQL script containing `CREATE TABLE` for `websites`, `tryouts`, `users`, `items`, `sessions`, `tryout_stats`, `user_answers`.
+
+### 4.3 Apply migration to DB (online)
+
+```bash
+.venv/bin/alembic upgrade head
+```
+
+Expected: upgrade completes without error.
+
+## 5) API Smoke Test
+
+Start app:
+
+```bash
+.venv/bin/uvicorn app.main:app --reload --port 8000
+```
+
+Then check:
+
+```bash
+curl -s http://127.0.0.1:8000/health | jq
+```
+
+Expected:
+- `status` is `healthy` or `degraded` (if DB unavailable)
+- API responds with JSON (no startup crash)
+
+## 6) Admin Auth Test (Optional)
+
+Only for explicit admin verification.
+
+1. Ensure Redis is running.
+2. Set:
+
+```env
+ENABLE_ADMIN=true
+ADMIN_USERNAME=admin
+ADMIN_PASSWORD=change-me
+```
+
+3. Start server and open:
+- `http://127.0.0.1:8000/admin/login`
+
+4. Validate:
+- invalid credentials -> login page with error
+- valid credentials -> redirect to admin dashboard
+- logout -> access token removed and redirected to login
+
+## 7) Regression Targets Checklist
+
+- [ ] ORM mapper configuration succeeds (`mappers_ok`)
+- [ ] normalization tests are assertion-based and passing
+- [ ] cast-related query paths run without SQLAlchemy cast errors
+- [ ] `avg_nn` in tryout comparison is derived from session NN aggregates
+- [ ] admin endpoints are disabled when `ENABLE_ADMIN=false`
+- [ ] admin login works only with configured credentials when enabled
+- [ ] Alembic migration history and SQL generation are valid
+
+## 8) Troubleshooting
+
+- `ModuleNotFoundError`: use `.venv/bin/python` and `.venv/bin/pytest`.
+- admin startup errors: verify `ENABLE_ADMIN`, `ADMIN_USERNAME`, `ADMIN_PASSWORD`.
+- Redis errors on admin login: ensure `REDIS_URL` is reachable.
+- migration connection errors: verify `DATABASE_URL` and DB service availability.