# 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.