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

Production Initialization Design

Goal: Replace the current production bootstrap approach with a single, explicit initialization flow that creates an empty schema via Alembic and seeds exactly one protected administrator account.

Problem

• Production currently mixes multiple initialization sources: database/init.sql, Alembic migrations, and development-only startup seed behavior.
• This creates schema drift risk and has already caused production startup failures when application models expected columns that the SQL bootstrap script did not create.
• The default administrator identity is also not aligned with the required production account.

Decisions

• Production schema source of truth becomes Alembic only.
• New production environments must start from an empty database.
• Production initialization explicitly runs schema migrations first, then ensures a fixed administrator account exists.
• No demo users, demo projects, demo fees, or any other seed business data are created in production initialization.
• The fixed administrator is admin@huapont.cn with initial password admin123.
• The fixed administrator cannot be deleted, disabled, downgraded from ADMIN, or have its email changed.
• The fixed administrator may change its password after first login.

Architecture

• A dedicated backend initialization command handles production bootstrap responsibilities.
• The command runs alembic upgrade head, then creates or repairs the protected administrator account if needed.
• The API layer enforces immutability rules for the protected administrator so UI or API requests cannot remove or weaken that account.
• The development environment may still keep development-only conveniences, but production deployment no longer depends on app startup side effects for schema creation.

Operational Flow

1. Start PostgreSQL with an empty data directory.
2. Run the one-shot backend initialization command.
3. Start long-lived backend and frontend services behind the external reverse proxy.
4. Log in with admin@huapont.cn / admin123, then change the password.

Non-Goals

• No automatic demo data import.
• No runtime auto-migration inside the long-lived backend container.
• No second schema definition maintained in database/init.sql.

Verification Targets

• Empty production database initializes successfully through Alembic.
• After initialization, the only seeded account is the fixed administrator.
• Attempts to delete, disable, change role, or change email for the protected administrator fail.
• Password change for the protected administrator succeeds.