75 lines
3.3 KiB
Markdown
75 lines
3.3 KiB
Markdown
# Pick'n'Play
|
|
|
|
Pick'n'Play is a .NET 10 ASP.NET Core Minimal API app with a static HTML/CSS/JS frontend and SQLite persistence.
|
|
|
|
## Quick Start
|
|
|
|
1. Restore and build:
|
|
`dotnet build GameList.sln`
|
|
2. Apply DB migrations explicitly:
|
|
`dotnet ef database update`
|
|
3. Run tests:
|
|
`dotnet test GameList.Tests/GameList.Tests.csproj`
|
|
4. Run locally:
|
|
`dotnet run --project GameList.csproj`
|
|
5. Open:
|
|
`http://localhost:5000` (or the URL shown by `dotnet run`)
|
|
|
|
## Frontend Tooling
|
|
|
|
- Install tooling: `npm install`
|
|
- Lint JS: `npm run lint`
|
|
- Check formatting: `npm run format:check`
|
|
- Apply formatting: `npm run format`
|
|
|
|
## Core Behavior
|
|
|
|
- Authentication: username/password with HttpOnly `player` cookie.
|
|
- Admin authorization: authenticated account with `IsAdmin=true`.
|
|
- Owner model: first valid admin-key registration becomes `owner`; admins can grant/revoke admin role for non-owner accounts.
|
|
- Core invariants are DB-enforced: single owner account and non-joker suggestion cap.
|
|
- Gameplay phases: `Suggest`, `Vote`, `Results`.
|
|
- Realtime sync: `/api/events/state` (SSE) plus `ETag`-based conditional `/api/state` reads to reduce polling load.
|
|
- Storage: SQLite database under `App_Data/gamelist.db`.
|
|
- Migrations are deployment-time operations (`dotnet ef database update`); app startup does not auto-migrate.
|
|
- Security defaults: rate-limited auth/admin routes, baseline browser security headers, production HTTPS+HSTS enforcement.
|
|
- CSRF baseline: authenticated mutating API requests require same-origin `Origin`/`Referer` headers.
|
|
- Password hashes are versioned and upgraded on successful login/admin-password verification; current rollout uses Argon2id for new hashes while transparently upgrading legacy PBKDF2 hashes.
|
|
|
|
## Password Hash Migration Plan
|
|
|
|
1. Existing hashes remain valid under versioned verification (`LegacyVersion=1`).
|
|
2. Successful authentication transparently rehashes credentials to `CurrentVersion=3` (Argon2id) and persists the upgraded hash metadata.
|
|
3. Legacy versions can be retired after full rollout once no remaining accounts depend on them.
|
|
|
|
## Module Ownership
|
|
|
|
- `Program.cs`: startup wiring, middleware order, route registration.
|
|
- `Endpoints/`: endpoint adapters plus application workflow services (`ServiceResult<T>` outputs mapped to HTTP at the edge).
|
|
- `Infrastructure/`: filters, middleware, identity helpers.
|
|
- `Data/`: EF Core `DbContext` and migrations.
|
|
- `Domain/`: entities and enums.
|
|
- `Contracts/`: request/response DTOs.
|
|
- `wwwroot/`: static frontend assets.
|
|
- `GameList.Tests/`: integration and helper tests.
|
|
- `scripts/`: deployment scripts (`scripts/deploy-ftp.ps1`, `scripts/deploy-ftp1.ps1`).
|
|
- `deploy.ps1`: local shortcut wrapper that runs FTP deploy using `scripts/deploy-ftp.profile.psd1`.
|
|
Deploy sets frontend `<meta name="app-base">` automatically from deploy profile `BasePath` (or inferred from `RemoteDir`).
|
|
|
|
## Operations
|
|
|
|
- API surface and endpoint contract: `API.md`
|
|
- Product/feature expectations: `SPEC.md`
|
|
- IIS deployment notes: `IIS.md`
|
|
- Test strategy details: `TESTS.md`
|
|
|
|
## CI
|
|
|
|
GitHub Actions workflow: `.github/workflows/ci.yml`
|
|
|
|
- Restores dependencies
|
|
- Runs frontend lint and format checks
|
|
- Builds with warnings treated as errors
|
|
- Runs `GameList.Tests` with coverage collection
|
|
- Enforces minimum coverage thresholds (line 90%, branch 70%)
|