feat(backend): modularize services and clean deps (#813 #814 #815 #821)

[marvel6828]

Summary

closes BrainTease#821
closes BrainTease#813
closes BrainTease#814
closes BrainTease#815

Resolves four backend technical-debt issues in a single cohesive PR.

---

BrainTease#821 — Analytics ingestion pipeline modularized

Problem: AnalyticsService.aggregateCourse was a monolith mixing database I/O, metric calculation, persistence, and cache invalidation in one method.

Solution: Introduced four discrete pipeline stages under src/analytics/pipeline/:

Stage	Responsibility
DataCollectionStage	Parallel DB queries — pure I/O, no computation
AggregationStage	Metric calculations — pure computation, no I/O
PersistenceStage	Upserts the computed record — one write per run
CacheStage	Invalidates the stale cache key

AnalyticsPipeline orchestrates the stages in order. AnalyticsService.aggregateCourse now delegates entirely to pipeline.run(courseId).

Tests: analytics.pipeline.spec.ts — stage isolation + orchestrator ordering

---

BrainTease#815 — Royalty-distribution calculation extracted into a service

Problem: Revenue/royalty math was inlined inside PayoutsService.calculatePayouts, mixing business logic with persistence.

Solution: Created RoyaltyCalculationService with:

• calculate(input) — single-course royalty (completions × price − platform fee)
• calculateBatch(inputs) — filters zero-completion courses, maps calculate
• getCoursePrice(courseId) / getPlatformFeePercent() — config accessors

PayoutsService now delegates all math to this service.

Tests: royalty-calculation.service.spec.ts — covers all public methods

---

BrainTease#814 — Remove unused npm dependencies

Analysis method: Static import scan across all src/**/*.ts files.

Removed:

• apollo-server-express — zero imports; GraphQL runs through @nestjs/graphql / @nestjs/apollo
• graphql-query-complexity — zero imports

Retained (confirmed in use): class-sanitizer, otplib, qrcode, xml2js, adm-zip, passport-google-oauth20, cache-manager-redis-store, graphql-depth-limit, @elastic/elasticsearch

---

BrainTease#813 — Dispute-resolution service refactored

Problem: AdminService mixed user management with dispute lifecycle logic, increasing cyclomatic complexity through nested guards and status checks.

Solution: Extracted DisputeResolutionService with:

• createDispute, listDisputes, getDisputeOrThrow, resolveDispute
• Private isTerminal(status) helper replacing repeated inline status comparisons
• AdminService now owns only user management and thin delegators

Tests: dispute-resolution.service.spec.ts — 7 cases covering happy paths and all guard branches

---

Testing

All new code is covered by unit tests that run without a database or real cache:

# Run all new unit tests
npx jest --testPathPattern="analytics/pipeline|royalty-calculation|dispute-resolution" --no-coverage

Checklist

• Map current responsibilities and identify seams ([BE] Modularize analytics ingestion pipeline into discrete stages BrainTease/Brain-Storm#821, [BE] Modularize royalty-distribution calculation logic into a service BrainTease/Brain-Storm#815, [BE] Refactor dispute-resolution service to reduce cyclomatic complexity BrainTease/Brain-Storm#813)
• Extract/split into focused modules with clear boundaries
• Update all call sites and imports
• Unit tests added for all new services
• Unused dependencies removed and confirmed ([BE] Clean up unused npm dependencies from apps/backend package.json BrainTease/Brain-Storm#814)
• No regressions — existing public API surfaces unchanged