teamwallet/docs/superpowers/plans/2026-08-01-penalty-catalog-management.md

Penalty Catalog Management Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Extend the existing team penalty catalog with secure create, inline update, and confirmed delete management in the modern frontend.

Architecture: Keep the versioned /penalty API compatible, reuse TeamAccessService for team-scoped authorization, and serialize writes by locking the owning team in a transaction. The Angular feature remains at /team/:id/more/penalties and treats backend authorization as authoritative.

Tech Stack: NestJS 9, TypeORM 0.3, class-validator, Jest, Angular 21, Angular Material, signals/RxJS, Vitest.

Global Constraints

• Only active captains, treasurers, coaches (teamRole.id >= 3) and global admins may mutate a team's catalog.
• Active team members and global admins may read a team's catalog; cross-team reads are forbidden.
• Description is trimmed and 1–120 characters; amount is EUR 0.01..10000.00 with at most two decimals.
• Normalized duplicate descriptions within one team return 409 Conflict.
• Deletes are permanent and do not alter historical transactions.
• Mutations and audit entries share one transaction; logs contain IDs and action, not catalog content.
• Do not modify myteamwallet_frontend or integrate penalties into transaction booking.

---

Task 1: Secure backend catalog contract

Files:

• Modify: myteamwallet_backend/src/penalty/**

• Modify: myteamwallet_backend/src/teams/teams.module.ts

• Modify: myteamwallet_backend/src/database/logging/model/logging-event.type.ts

• Test: myteamwallet_backend/src/penalty/*.spec.ts

• Write failing DTO, service, and HTTP-boundary tests for safe mapping, team membership, manager roles, validation, duplicate conflicts, locking, audit rollback, update, and delete.

• Run focused tests and confirm failures are caused by missing behavior.

• Implement explicit DTOs, class-level authentication, TeamAccessService reuse, transactional create/update/delete, normalized duplicate checks, and audit events.

• Run focused tests and backend build; commit the backend slice.

Task 2: Modern frontend management

Files:

• Modify: myteamwallet_frontend_modern/src/app/core/team/penalty-api.ts

• Modify: myteamwallet_frontend_modern/src/app/models/penalty.model.ts

• Modify: myteamwallet_frontend_modern/src/app/features/team/more/penalties/**

• Write failing API and component tests for reader/manager views, inline edit/cancel, delete confirmation, pessimistic refresh, errors, retry, search retention, and accessible controls.

• Run focused tests and confirm failures are caused by missing behavior.

• Implement typed update/delete calls and the responsive inline management UI using existing Material patterns.

• Run focused tests, the full modern frontend suite, and TypeScript checks; commit the frontend slice.

Task 3: Integration and review

• Run focused backend tests, backend build, full frontend tests, frontend TypeScript checks, and git diff --check.
• Confirm the legacy frontend has no feature-range diff and document the eight pre-existing backend placeholder failures separately.
• Request a read-only full-range code review; fix Critical/Important findings and re-verify.
• Run the branch-finishing workflow and preserve the worktree until the user chooses integration.