From 45658e42fa10945cd7f6f369f3ab47478bad96f6 Mon Sep 17 00:00:00 2001
From: Bastian Wagner <bastian.wagner@softconcis.de>
Date: Sat, 1 Aug 2026 12:52:07 +0200
Subject: [PATCH] docs: add penalty catalog management plan

---
 .../2026-08-01-penalty-catalog-management.md  | 53 +++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-08-01-penalty-catalog-management.md

diff --git a/docs/superpowers/plans/2026-08-01-penalty-catalog-management.md b/docs/superpowers/plans/2026-08-01-penalty-catalog-management.md
new file mode 100644
index 0000000..8002f05
--- /dev/null
+++ b/docs/superpowers/plans/2026-08-01-penalty-catalog-management.md
@@ -0,0 +1,53 @@
+# 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.