comunidadhll/ai/tasks/pending/TASK-177-harden-annual-ranking-snapshot-operations.md

id, title, status, type, team, supporting_teams, roadmap_item, priority

id	title	status	type	team	supporting_teams	roadmap_item	priority
TASK-177-harden-annual-ranking-snapshot-operations	Harden annual ranking snapshot operations	pending	backend	Backend Senior	Arquitecto de Base de Datos PM	foundation	medium

TASK-177-harden-annual-ranking-snapshot-operations - Harden annual ranking snapshot operations

Goal

Improve annual ranking snapshot reliability for production use without recalculating on public requests or changing visible frontend behavior.

Context

The annual snapshot flow is implemented and documented, but edge cases around missing data, empty years, unsupported years/metrics, and limit normalization should be hardened with small, verifiable backend improvements.

Steps

1. Read the listed files first.
2. Review generation and read flow for annual ranking snapshots.
3. Apply small validation and response consistency improvements in backend code.
4. Ensure snapshot behavior remains stable for ready/empty/missing and unsupported metric states.
5. Document any follow-up work that should remain a separate task instead of broadening this one.

Files to Read First

• AGENTS.md
• ai/repo-context.md
• ai/architecture-index.md
• docs/stats-section-functional-plan.md
• docs/annual-ranking-snapshot-runbook.md
• backend/app/routes.py
• backend/app/rcon_annual_rankings.py
• backend/app/rcon_historical_leaderboards.py
• ai/tasks/done/TASK-171-validate-stats-section-with-backend-data.md
• ai/tasks/done/TASK-173-add-annual-ranking-snapshot-runbook.md

Expected Files to Modify

• backend/app/rcon_annual_rankings.py
• backend/app/routes.py only if endpoint mapping/validation requires changes
• docs/annual-ranking-snapshot-runbook.md only if documented operations change
• ai/tasks/done/TASK-177-harden-annual-ranking-snapshot-operations.md

Constraints

• No frontend modifications unless a strict critical backend-related bug requires it (and document the reason).
• No new architecture.
• No major migrations.
• Do not re-enable Elo/MMR.
• Do not reintroduce Comunidad Hispana #03.
• Do not use public scoreboard as primary source.
• Do not recalculate annual ranking in each public request.
• Keep changes small and independently verifiable.

Validation

• Run powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1.
• Test annual ranking endpoint for:
  • current year with metric=kills
  • past year with no data
  • future year missing snapshot
  • unsupported metric
  • low limit, e.g. 3
  • high limit, verifying normalization if applicable
• Run git diff --name-only and verify scoped files only.

Outcome

Document applied hardening, validated responses, known limits, and whether a future task is needed for scheduled/hardening automation.