box-nestjs-monorepo/action-plans/20251222-ACT-01.md

Assumptions we’ll stick to

• Provider video metadata is used as-is (including updatedAt: DateTime).
• Ads cache keys are box:app:adpool:<AdType> and Ads payload is already slimmed (status=1, seq asc).
• We won’t add DB fields unless we’re doing the User migration step.

---

Tomorrow Action Plan

Phase 0 — Prep and guardrails

1. Confirm API contract snapshots

   • Current login response shape
   • Current video endpoints response shape (even if incomplete)

2. Confirm Redis key spec and payload contracts

   • Ads cache keys + fields
   • Video cache keys + fields (use provider fields as-is)

Deliverable: quick “contract notes” doc/comment so we don’t drift while implementing multiple endpoints.

---

Phase 1 — Login returns Ads (highest leverage)

1. Update login flow to return Ads payload (likely home-related adTypes)
   • Decide which AdTypes are returned on login (e.g. STARTUP, BANNER, POPUP_* etc.)
   • Read from Redis first (box:app:adpool:<AdType>), DB fallback if missing, then rebuild cache
   • Ensure returned Ads are already filtered (status=1) and sorted by seq asc

Deliverable: login response includes ads (grouped by adType or whatever your app contract expects).

---

Phase 2 — Video listing/search endpoints (build foundation once, reuse everywhere)

1. /api/v1/video/list

   • Define baseline filters + pagination (current behavior, don’t invent new ones)
   • Implement Redis list/payload strategy if we’re ready; otherwise DB-first with safe caching behind it

2. /api/v1/video/category/

   • Category list endpoint should reuse the same “list IDs → fetch payloads” pattern
   • Stable sorting and pagination

3. /api/v1/video/search-by-tag

   • Define tag input: tagId / tag name / categoryId constraints
   • Implement query + caching (tag list key) and reuse payload key

Deliverable: list/search endpoints are consistent and share the same internal list-builder + payload fetcher.

---

Phase 3 — Recommendation endpoints (depends on Phase 2)

1. /api/v1/video/recommended

   • Add optional parameters (only the ones you explicitly want)

     • Example buckets: categoryId, tagId, country, excludeIds, limit

   • Implement “better results” logic without breaking old callers (default behavior unchanged)

2. /api/v1/recommendation/videos/{videoId}/similar (fix the typo: you wrote /api/v1/api/v1/...)

   • Similarity rules: tag overlap / same category / same country / exclude same id
   • Reuse existing list/payload pattern
   • Ensure deterministic ordering

Deliverable: recommended + similar endpoints work and don’t duplicate query logic.

---

Phase 4 — Prisma migration: User from box-stats → box-admin

1. Model migration design

   • Identify current User schema in box-stats and all places it’s referenced
   • Decide target schema in box-admin (migration-safe; avoid breaking fields)

2. Data migration strategy

• One-time migration script: copy users + indexes
• Dual-read / cutover plan if needed (keep backward compatibility)
• “Optimize may be required”: focus on indexes + query hotspots after migration

Deliverable: User model lives in box-admin, references updated, and box-stats dependency reduced/removed safely.

---

Implementation order (recommended)

1. Login returns Ads
2. Video list
3. Video category
4. Search-by-tag
5. Recommended (optional params)
6. Similar videos
7. Prisma User migration

---

Testing checklist (quick but effective)

• Login response includes Ads and is stable even when Redis is empty
• Video endpoints: pagination + ordering + empty results
• Recommended/similar: excludes current videoId, respects optional params, no duplicates
• Migration: User read/write still works after cutover; seed/admin login still ok

---

If you paste your current login response DTO (or the controller return object), I’ll turn Phase 1 into a tight Codex prompt that edits the right files without guessing.