# Task D.7.2 Setup Readiness and Verification APIs

Date: 2026-07-02
Status: implemented

## Scope Delivered

- Added setup API contracts:
  - `src/features/setup/api/types.ts`
  - `src/features/setup/api/service.ts`
  - `src/features/setup/api/queries.ts`
- Added read-only setup server services:
  - `src/features/setup/server/readiness.service.ts`
  - `src/features/setup/server/verification.service.ts`
- Added thin protected route handlers:
  - `src/app/api/setup/readiness/route.ts`
  - `src/app/api/setup/verify/route.ts`

## Behavior

- `GET /api/setup/readiness`
  - protected by `requireSystemRole('super_admin')`
  - returns structured setup readiness checks
  - checks environment, database, migrations/schema queryability, storage smoke test, local upload directory, PDF template/mapping readiness, and optional email configuration

- `POST /api/setup/verify`
  - protected by `requireSystemRole('super_admin')`
  - accepts optional `organizationId` and `administratorEmail`
  - falls back to the current session active organization when `organizationId` is not provided
  - returns structured verification checks for administrator, membership, CRM assignment, organization, branch/product type options, document sequences, approval workflow/matrix, PDF, notification templates, report definitions, email config, and planned CSV/manifest checks

## Safety Notes

- No seed execution was added.
- No CSV import was added.
- No reset/reseed behavior was added.
- No setup state tables or migrations were added.
- The only intentional write-like behavior is the readiness storage smoke test, which writes a temporary setup object and immediately deletes it. Cleanup failures are reported as warnings.
- Document sequence checks are read-only and do not call `generateNextDocumentCode()`.
- Report verification checks query report definition rows directly and do not call report services that audit report views.

## Verification

- `npm run typecheck`: passed.
- `npx oxlint src/features/setup src/app/api/setup`: passed.
- `npm run lint`: failed due to pre-existing unrelated lint errors/warnings outside this task, including `src/features/foundation/document-template/server/management-service.ts` and skill asset scripts.

## Follow-up

- D.7.3 can add static CSV template pack.
- D.7.8 should replace planned CSV preview/seed manifest warnings with persisted setup state checks.