MOPC-Portal/docs/round-redesign-architecture-docs/mixed-round-design-implementation-docs/phase-01-schema-runtime-foundation/schema-spec.md

Phase 01 Schema Specification

Summary

Introduce the canonical orchestration entities and remove legacy dependency assumptions around single roundId progression.

New Canonical Tables

1. Pipeline
2. Track
3. Stage
4. StageTransition
5. ProjectStageState
6. RoutingRule
7. Cohort
8. CohortProject
9. LiveProgressCursor
10. NotificationPolicy
11. OverrideAction
12. DecisionAuditLog

Award Governance Extensions

• Add DecisionMode = JURY_VOTE | AWARD_MASTER | ADMIN
• Add award-scoped governance metadata to award track configs
• Add award winner finalization audit event contracts

Migration Model

• Build new schema directly as canonical target.
• Keep migration files deterministic and replay-safe.
• Do not implement dual-write or compatibility tables.

Required Constraints

1. trackId + sortOrder unique in Stage
2. projectId + trackId + stageId unique in ProjectStageState
3. fromStageId + toStageId unique in StageTransition
4. cohortId + projectId unique in CohortProject

Required Indexes

• ProjectStageState(projectId, trackId, state)
• ProjectStageState(stageId, state)
• RoutingRule(pipelineId, isActive, priority)
• StageTransition(fromStageId, priority)
• DecisionAuditLog(entityType, entityId, createdAt)
• LiveProgressCursor(stageId, sessionId)

Data Initialization Rules

• Every seeded project must start with one intake-stage state.
• Seed must include main track plus at least two award tracks with different routing modes.
• Seed must include representative roles: admins, jury, applicants, observer, audience contexts.

Integrity Checks

• No orphan states.
• No invalid transition targets across pipelines.
• No duplicate active state rows for same (project, track, stage).