# Public Team Sharing 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:** Add revocable public team links with controlled management, safe public DTOs, sharing, and QR presentation.

**Architecture:** The backend stores a disabled-by-default public-access flag and a random token on each team. Authenticated management endpoints enforce team membership and a minimum team role, while a separate public controller returns deliberately shaped responses and verifies player ownership. The modern Angular frontend consumes these endpoints through focused API services and presents management under “Mehr”.

**Tech Stack:** NestJS 9, TypeORM 0.3, Jest, Angular 21 standalone components/signals, Angular Material, Vitest, `qrcode`.

## Global Constraints

- Modify only `myteamwallet_backend` and `myteamwallet_frontend_modern`; leave the legacy frontend untouched.
- New teams are private by default; disabled or invalid links return HTTP 404.
- Team roles 3–5 and global admins may mutate sharing; authenticated team members may read and share an enabled link.
- Public responses expose only the agreed team, active-player, penalty, and transaction fields.
- Follow red-green-refactor for every behavior change.

---

### Task 1: Backend persistence and access policy

**Files:**

- Modify: `myteamwallet_backend/src/teams/entities/team.entity.ts`
- Create: `myteamwallet_backend/src/database/migrations/1785513600000-AddTeamPublicAccess.ts`
- Create: `myteamwallet_backend/src/teams/team-access.service.ts`
- Test: `myteamwallet_backend/src/teams/team-access.service.spec.ts`

**Interfaces:**

- Produce `Team.publicAccessEnabled`, `Team.publicAccessToken`, `TeamAccessService.assertMember(userId, teamId)`, and `TeamAccessService.assertManager(userId, teamId)`.

- [ ] Write tests proving admins bypass membership, members can read, roles 3–5 can manage, and lower/non-members receive `ForbiddenException`.
- [ ] Run the focused Jest test and confirm failure because the service and fields do not exist.
- [ ] Implement the entity fields, reversible migration, and repository-backed access service using the user’s highest role in the team.
- [ ] Run the focused test and backend build.
- [ ] Commit the backend persistence/policy change.

### Task 2: Backend management and public APIs

**Files:**

- Create: `myteamwallet_backend/src/teams/dto/public-access.dto.ts`
- Create: `myteamwallet_backend/src/teams/public-teams.controller.ts`
- Modify: `myteamwallet_backend/src/teams/teams.controller.ts`, `teams.service.ts`, `teams.module.ts`
- Modify: `myteamwallet_backend/src/penalty/penalty.controller.ts`
- Test: `myteamwallet_backend/src/teams/teams.service.spec.ts`, `teams.controller.spec.ts`

**Interfaces:**

- Produce `GET/PATCH /teams/:id/public-access`, `POST /teams/:id/public-access/rotate`, `GET /public/teams/:token`, and `GET /public/teams/:token/players/:playerId/transactions`.
- Public team response contains `name`, `balance`, `outstanding`, active players (`id`, names, balance), and penalties (`id`, description, amount`).

- [ ] Write failing service/controller tests for activation, stable reactivation, rotation, disabled/unknown tokens, cross-team player rejection, 20-item ordering, and response whitelisting.
- [ ] Run focused backend tests and verify expected failures.
- [ ] Implement DTOs, token generation with `randomBytes(32)`, management endpoints, safe public queries, and module wiring.
- [ ] Remove the old anonymous alias handlers and require authentication for direct team-penalty loading.
- [ ] Run focused tests, the full backend suite, and backend build.
- [ ] Commit the completed backend API.

### Task 3: Frontend API contracts and routes

**Files:**

- Create: `myteamwallet_frontend_modern/src/app/models/public-access.model.ts`
- Create: `myteamwallet_frontend_modern/src/app/core/team/public-access-api.ts`
- Modify: `myteamwallet_frontend_modern/src/app/core/team/public-team-api.ts`, `app.routes.ts`
- Test: matching API and route specs.

**Interfaces:**

- Produce typed status, public-team, and public-player-history responses plus API methods for status, enable/disable, rotate, public overview, and public history.

- [ ] Write failing HttpTestingController and router tests for all new URLs and payloads.
- [ ] Run focused Vitest specs and confirm expected failures.
- [ ] Implement the typed API clients and token-based route contract.
- [ ] Run focused specs and commit the frontend API layer.

### Task 4: Sharing management UI

**Files:**

- Create: `myteamwallet_frontend_modern/src/app/features/team/more/public-access/*`
- Modify: `myteamwallet_frontend_modern/src/app/features/team/more/more.html`, `app.routes.ts`, `package.json`
- Test: `public-access.spec.ts`, affected route/more specs.

**Interfaces:**

- Consume `PublicAccessApi`; render state, role-gated mutations, copy/share, QR, preview, and rotate confirmation.

- [ ] Install `qrcode` and its types, then write failing component tests for visibility, permissions, activation, disable, rotation confirmation, copy, native share, and fallback behavior.
- [ ] Run focused tests and verify failures.
- [ ] Implement the standalone Material component, responsive styles, accessible QR alternative, and “Mehr” navigation entry.
- [ ] Run focused tests and commit the management UI.

### Task 5: Public pages and end-to-end verification

**Files:**

- Modify: `myteamwallet_frontend_modern/src/app/features/public-team/public-team.*`, `public-player.*`
- Test: both public component specs.

**Interfaces:**

- Consume combined public overview and player-history DTOs; do not call the authenticated penalty API.

- [ ] Write failing tests proving combined response rendering, player identity rendering, invalid-token state, and absence of the separate penalty request.
- [ ] Run focused tests and verify failures.
- [ ] Update both public pages and models to use the token APIs.
- [ ] Run all frontend tests and production build; run all backend tests and build.
- [ ] Review both diffs for public-data leakage and confirm the legacy frontend remains untouched.
- [ ] Commit final integration fixes.