Revise milestone 5 docs for admin code management

Author: tkxkd0159

docs/SPEC.md

@@ -1,10 +1,10 @@
-# Milestone 5: Beta Onboarding and Nickname Identity
+# Milestone 5: Beta Onboarding, Internal Admin Auth, and Invitation Code Management
 
-This directory contains the milestone and task documents for the beta onboarding and nickname identity rollout.
+This directory contains the milestone and task documents for the revised Milestone 5 rollout.
 
-- Milestone doc: [Milestone 5: Beta Onboarding and Nickname Identity](./milestone-5-beta-onboarding-and-nickname-identity.md)
-- Task 01: [User Identity and Beta Access Foundation](./task-01-user-identity-and-beta-access-foundation.md)
-- Task 02: [Signup Completion and Auth Gating](./task-02-signup-completion-and-auth-gating.md)
-- Task 03: [Nickname Profile and Public Shelf Sharing](./task-03-nickname-profile-and-public-shelf-sharing.md)
-- Task 04: [Nickname-Based Club Invitation Flow](./task-04-nickname-based-club-invitation-flow.md)
+- Milestone doc: [Milestone 5: Beta Onboarding, Internal Admin Auth, and Invitation Code Management](./milestone-5-beta-onboarding-admin-auth-and-invitation-codes.md)
+- Task 01: [User and Admin Identity Foundation](./task-01-user-and-admin-identity-foundation.md)
+- Task 02: [Signup Completion and Public App Auth Gating](./task-02-signup-completion-and-public-app-auth-gating.md)
+- Task 03: [Internal Admin Auth and Invitation Code Management](./task-03-internal-admin-auth-and-invitation-code-management.md)
+- Task 04: [Nickname Profile, Public Shelf Sharing, and Club Invites](./task-04-nickname-profile-public-shelf-sharing-and-club-invites.md)
 - Task 05: [Quality Gates and Regression Coverage](./task-05-quality-gates-and-regression-coverage.md)

docs/tasks/milestone-5/README.md

@@ -0,0 +1,44 @@
+# Milestone 5: Beta Onboarding, Internal Admin Auth, and Invitation Code Management
+
+## Goal
+Deliver the closed-beta onboarding and service-native identity workflow on top of the existing auth, books, clubs, threads, shelves, and reviews foundation, while adding an internal-only admin panel for invitation-code management:
+
+- require completed signup after OAuth before public app access
+- collect a stable nickname, gender, country, favorite genres, and an invitation code
+- use nickname as the public app identity across profile, shelves, clubs, threads, and reviews
+- change public shelf sharing to nickname-based URLs
+- change private-club invite targeting from email to nickname-resolved user identity
+- add internal admin auth and admin UI for DB-backed invitation-code management
+
+## Current Baseline
+- `bookapp.users` currently stores provider metadata only and Google login immediately creates a usable app user.
+- Milestones 2 through 4 already provide clubs, discussions, shelves, and reviews on top of the current auth foundation.
+- The app has no internal-admin auth path, no admin route tree, and no credentials-based sign-in.
+- Beta access is currently documented as a shared env-backed code rather than a database-managed domain.
+- Private club invites are email-targeted and invite acceptance still matches by email or user id.
+- Public shelf routes are keyed by `userId`, not nickname.
+
+## Planning Assumptions
+- Internal admins are manually created in Supabase UI and stored with `provider = 'internal'`.
+- Internal admins use email/password only and do not participate in public signup or the public product routes.
+- Invitation codes are future-ready through `purpose`, optional expiry, and optional max uses, but only `BETA_SIGNUP` redemption is implemented in Milestone 5.
+- Nickname is immutable in Milestone 5 and is validated as a lowercase URL-safe handle.
+- Private club invites remain a separate domain from admin-managed invitation codes.
+- Milestone 5 does not add a public profile route, nickname change UI, or in-app admin-user bootstrap flow.
+
+## Delivery Order
+1. [Task 01: User and Admin Identity Foundation](./task-01-user-and-admin-identity-foundation.md)
+2. [Task 02: Signup Completion and Public App Auth Gating](./task-02-signup-completion-and-public-app-auth-gating.md)
+3. [Task 03: Internal Admin Auth and Invitation Code Management](./task-03-internal-admin-auth-and-invitation-code-management.md)
+4. [Task 04: Nickname Profile, Public Shelf Sharing, and Club Invites](./task-04-nickname-profile-public-shelf-sharing-and-club-invites.md)
+5. [Task 05: Quality Gates and Regression Coverage](./task-05-quality-gates-and-regression-coverage.md)
+
+## Milestone Exit Criteria
+- OAuth-authenticated public users cannot reach the reader app until they complete Book by Book signup.
+- Completing signup persists nickname, gender, country, favorite genres, and signup completion state, and atomically redeems a valid `BETA_SIGNUP` invitation code.
+- Internal admins can sign in through `/admin/signin` and manage invitation codes from `/admin/invitation-codes`.
+- Invitation codes are stored hashed, support active/inactive state, and can optionally expire or cap uses.
+- Nickname becomes the default user-facing identity across `/me`, shelves, clubs, threads, reviews, and invite pages.
+- Public shelf sharing works by nickname route while preserving the existing signed-in-only public shelf access model.
+- Private club invites are created by nickname and accepted only by the targeted signed-in public user.
+- Milestone 5 passes `pnpm lint`, `pnpm build`, `pnpm test`, `pnpm test:integration`, and required Playwright coverage for onboarding, admin auth, invitation-code management, nickname routing, and invite flows.

docs/tasks/milestone-5/milestone-5-beta-onboarding-admin-auth-and-invitation-codes.md

@@ -0,0 +1,57 @@
+# Task 01: User and Admin Identity Foundation
+
+## Goal
+Add the schema, shared validation, repository contracts, and identity helpers needed for every Milestone 5 public-user onboarding, internal-admin auth, invitation-code, sharing, and invite flow.
+
+## Scope
+- Extend the app-facing database shape and domain contracts for public users:
+  - `nickname`
+  - `gender`
+  - `countryCode`
+  - `favoriteGenres`
+  - `signupCompletedAt`
+- Extend the `users` model for internal admins with a nullable `passwordHash` used only for `provider = 'internal'`.
+- Add the schema migration and source-of-truth schema updates needed to persist:
+  - the new public-user profile fields on `bookapp.users`
+  - internal admin password-hash support on `bookapp.users`
+  - `invitation_codes`
+  - `invitation_code_redemptions`
+- Define shared validation and normalization helpers for:
+  - nickname format and uniqueness
+  - gender enum parsing
+  - ISO country selection
+  - favorite-genre allowlist validation
+  - internal admin email normalization
+  - invitation-code hashing and lookup inputs
+- Define shared domain contracts for:
+  - `InvitationCodePurpose`
+  - `InvitationCodeRecord`
+  - `InvitationCodeRedemptionRecord`
+  - public user vs internal admin session identity
+- Update auth and user repository contracts so app identity no longer depends on provider email for normal signed-in flows.
+
+## Implementation Notes
+- Keep the public profile fields and internal password hash on `bookapp.users`; do not introduce a separate profile table or admin table in Milestone 5.
+- `signup_completed_at` remains the source of truth for whether a public signed-in user can use the reader app.
+- Internal admins are represented by:
+  - `provider = 'internal'`
+  - `provider_user_id = normalized email`
+  - password-hash verification
+- Internal admins are manually created in Supabase UI and are not provisioned by the app.
+- OAuth-linked public users still use `auth_accounts`; internal credentials auth can resolve directly from `users`.
+- Invitation codes must be stored hashed and modeled for future purposes even though only `BETA_SIGNUP` is redeemed in this milestone.
+
+## Acceptance Criteria
+- The database schema and app-facing types expose all required Milestone 5 public-user, internal-admin, and invitation-code fields.
+- Shared validation covers nickname normalization, allowed genre values, required country/gender selection, internal admin auth inputs, and invitation-code hashing contracts.
+- Reusable repository helpers can distinguish incomplete public users, completed public users, and internal admins without route-local duplication.
+- Shared display helpers make nickname the first-class reader-facing identity.
+- Shared code-management types are stable enough to support future invitation-code purposes without revisiting the schema shape.
+
+## Expected Touchpoints
+- `db/schema/data.sql`
+- `db/migrations/*`
+- `types/db/index.ts`
+- `lib/auth/*`
+- `tests/unit/auth*.test.ts`
+- invitation-code validation and repository helpers

docs/tasks/milestone-5/milestone-5-beta-onboarding-and-nickname-identity.md

@@ -0,0 +1,46 @@
+# Task 02: Signup Completion and Public App Auth Gating
+
+## Goal
+Implement the completed-signup flow so authenticated but incomplete public users are routed through `/signup` before they can use the reader-facing app.
+
+## Scope
+- Add `/signup` as the authenticated onboarding route for incomplete public users.
+- Build the signup-completion form for:
+  - nickname
+  - gender
+  - country
+  - favorite genres
+  - invitation code
+- Add the `completeSignup({ nickname, gender, countryCode, favoriteGenres, invitationCode, callbackUrl? })` mutation.
+- Validate and redeem an active `BETA_SIGNUP` invitation code transactionally during signup completion.
+- Preserve safe callback URLs from:
+  - sign-in redirects
+  - invite acceptance entry points
+  - direct protected-page hits by incomplete public users
+- Redirect incomplete public users away from reader-facing protected routes and protected mutations until `signup_completed_at` is set.
+- Redirect completed public users away from `/signup` to the callback destination or `/books/search`.
+
+## Implementation Notes
+- Keep Google OAuth as the only public-user provider for Milestone 5, but treat OAuth and completed signup as separate lifecycle steps.
+- The onboarding route should require an authenticated public session; signed-out users still go to `/signin`.
+- Internal admins should never use `/signup`; route guards should redirect them to `/admin/invitation-codes`.
+- Reuse existing safe-return URL handling patterns rather than accepting arbitrary external redirects.
+- Invite links and other protected deep links should survive the onboarding detour by preserving callback intent.
+- Sign-out remains available to incomplete public users.
+- Invitation-code redemption should record audit history and enforce inactive, expired, exhausted, and wrong-purpose rejections on the server.
+
+## Acceptance Criteria
+- A newly authenticated but incomplete public user is redirected to `/signup` before any reader-facing app surface renders.
+- Completing signup writes the required profile fields, marks signup complete, redeems the code, and redirects the user back to the intended destination.
+- Protected reader-facing server actions reject incomplete public users consistently.
+- Completed public users cannot accidentally return to `/signup` as a normal app page.
+- Invalid, inactive, expired, exhausted, and wrong-purpose invitation codes are rejected with clear server-enforced behavior.
+
+## Expected Touchpoints
+- `app/signup/page.tsx`
+- `app/signin/page.tsx`
+- `app/auth/error/page.tsx`
+- `app/api/auth/[...nextauth]/route.ts`
+- `proxy.ts`
+- `lib/auth/server.ts`
+- signup-completion server actions and tests