ctms/docs/plans/2026-03-27-production-init-implementation.md

Production Initialization Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Make production initialization use Alembic as the only schema source and seed exactly one protected administrator account with no demo data.

Architecture: A dedicated initialization entrypoint will run migrations and seed the protected administrator. The runtime backend container will stop relying on production startup side effects for database structure, and the user-management API will enforce immutability rules for the protected administrator account.

Tech Stack: FastAPI, SQLAlchemy AsyncSession, Alembic, PostgreSQL, Docker Compose, pytest

---

Task 1: Add Protected Admin Constants And Seed Logic

Files:

• Modify: backend/app/crud/user.py
• Create or Modify: backend/app/core/config.py
• Test: backend/tests/... for protected admin behavior

Step 1: Write a failing test

Add a backend test that proves the seed helper creates admin@huapont.cn with ADMIN role and ACTIVE status when the account is missing.

Step 2: Run test to verify it fails

Run: cd backend && pytest <new-test-path> -v Expected: FAIL because the current seed helper still creates admin@example.com.

Step 3: Write minimal implementation

Introduce protected admin constants and replace the current seed helper with logic that ensures the fixed admin exists with the required immutable identity fields while allowing password updates through normal user flows.

Step 4: Run test to verify it passes

Run: cd backend && pytest <new-test-path> -v Expected: PASS

Step 5: Commit

git add backend/app/crud/user.py backend/app/core/config.py <test-path>
git commit -m "feat: seed protected production admin"

Task 2: Block Destructive Changes To The Protected Admin

Files:

• Modify: backend/app/api/v1/users.py
• Modify: backend/app/crud/user.py if helper methods are needed
• Test: backend/tests/... covering update/delete constraints

Step 1: Write failing tests

Add tests showing the protected admin cannot be deleted, disabled, downgraded from ADMIN, or have its email changed, while password change remains allowed.

Step 2: Run tests to verify they fail

Run: cd backend && pytest <user-api-test-path> -v Expected: FAIL because the current API only guarantees at least one admin remains.

Step 3: Write minimal implementation

Add explicit checks in the user update and delete endpoints so the protected admin is immutable for identity and role/status fields but still allows password updates.

Step 4: Run tests to verify they pass

Run: cd backend && pytest <user-api-test-path> -v Expected: PASS

Step 5: Commit

git add backend/app/api/v1/users.py backend/app/crud/user.py <test-path>
git commit -m "feat: protect system admin account"

Task 3: Add Production Initialization Entrypoint

Files:

• Create: backend/scripts/init_production.py
• Modify: backend/app/main.py
• Modify: backend/Dockerfile if command support is needed
• Test: script-level verification or targeted unit test

Step 1: Write a failing verification

Define a verification path that proves the initialization script performs migrations and then seeds the protected admin.

Step 2: Run verification to confirm current flow is insufficient

Run: cd backend && python scripts/init_production.py --help or targeted tests Expected: FAIL because no dedicated production init command exists.

Step 3: Write minimal implementation

Create a one-shot initialization script that runs alembic upgrade head and then invokes the protected-admin seed helper. Remove production reliance on app-startup schema or admin side effects.

Step 4: Run verification to confirm it passes

Run: cd backend && python scripts/init_production.py --help and relevant tests Expected: PASS

Step 5: Commit

git add backend/scripts/init_production.py backend/app/main.py backend/Dockerfile
git commit -m "feat: add production init entrypoint"

Task 4: Align Compose And Docs With The New Production Flow

Files:

• Modify: docker-compose.yaml
• Modify: README.md
• Modify: docs/guides/release-checklist.md
• Optionally modify: database/init.sql

Step 1: Write failing verification

Document or verify that the current compose/release instructions still imply schema bootstrap from the wrong place.

Step 2: Run verification to confirm mismatch

Run: docker compose config Expected: configuration still lacks an explicit production init workflow.

Step 3: Write minimal implementation

Add a one-shot compose service or documented command for production initialization. Update docs so production deploy always runs migrations and protected-admin seeding explicitly. Remove database/init.sql from the production path or reduce it so it is no longer treated as the schema source of truth.

Step 4: Run verification to confirm it passes

Run: docker compose config Expected: PASS with the new init workflow represented in configuration or documentation.

Step 5: Commit

git add docker-compose.yaml README.md docs/guides/release-checklist.md database/init.sql
git commit -m "docs: define production database init flow"

Task 5: End-To-End Verification

Files:

• Verify only

Step 1: Validate backend tests

Run: cd backend && pytest <affected-test-selection> -v Expected: PASS

Step 2: Validate compose configuration

Run: docker compose config Expected: PASS

Step 3: Validate production init command

Run: docker compose run --rm backend python scripts/init_production.py Expected: migrations run successfully and the protected admin is ensured.

Step 4: Validate service health

Run: docker compose up -d Expected: db, backend, and nginx start successfully.

Run: curl -i http://127.0.0.1/health Expected: 200 OK