L-Ami-Fiduciaire/_bmad-output/implementation-artifacts/0-5-add-foundation-database-migrations-and-declaration-status-flow.md

Story 0.5: Add Foundation Database Migrations and Declaration Status Flow

Status: done

Story

As a developer, I want the base database migrations and declaration status enforcement in place, so that future epics can build on a solid data foundation without needing to alter the schema themselves.

Acceptance Criteria

1. Given the declarations table exists (from Story 0.1), When the foundation migrations are applied, Then a permissions JSON column is added to the workspace_user pivot table (nullable, default null)
2. And the WorkspaceUser model casts permissions to array
3. And an archived_at nullable timestamp column is added to the declarations table
4. And the Declaration model has scopeActive() (whereNull('archived_at')) and scopeArchived() (whereNotNull('archived_at')) Eloquent scopes
5. And the DeclarationStatus enum includes all lifecycle values: created, en_cours, en_attente_client, termine, ferme
6. And a DeclarationObserver is registered that enforces valid status transitions per the Architecture status flow
7. And the observer auto-sets archived_at = now() when status becomes ferme
8. And invalid status transitions throw a validation error (e.g., created cannot jump to ferme)
9. And all existing tests pass with the new migrations applied

Tasks / Subtasks

• Task 1: Create migration to add permissions JSON column to workspace_user table (AC: #1)

  • 1.1: Create migration xxxx_add_permissions_to_workspace_user.php adding nullable JSON permissions column with default null
  • 1.2: Add down() method to drop the permissions column

• Task 2: Update WorkspaceUser pivot model (AC: #2)

  • 2.1: Add 'permissions' to $fillable array in app/Models/WorkspaceUser.php
  • 2.2: Add 'permissions' => 'array' to the casts() method (use method-based casts per project conventions)

• Task 3: Create migration to add archived_at to declarations table (AC: #3)

  • 3.1: Create migration xxxx_add_archived_at_to_declarations.php adding nullable timestamp archived_at column (after deleted_at)
  • 3.2: Add index on archived_at for efficient scope queries
  • 3.3: Add down() method to drop the column and index

• Task 4: Add archive scopes to Declaration model (AC: #4)

  • 4.1: Add scopeActive(Builder $query) returning $query->whereNull('archived_at')
  • 4.2: Add scopeArchived(Builder $query) returning $query->whereNotNull('archived_at')

• Task 5: Replace DeclarationStatus enum values (AC: #5)

  • 5.1: Replace ALL existing enum values in app/Enums/DeclarationStatus.php with the 5 architecture-specified values: Created = 'created', EnCours = 'en_cours', EnAttenteClient = 'en_attente_client', Termine = 'termine', Ferme = 'ferme'
  • 5.2: Add a labels(): array static method returning French display labels for each status
  • 5.3: Add a allowedTransitions(): array method returning the valid next statuses per the architecture status flow table
  • 5.4: Create a data migration to update existing declaration records from old status values to new ones (map draft → created, processing/waiting_documents/documents_received/additional_documents_requested → en_cours, waiting_client_validation → en_attente_client, validated → termine, closed → ferme, cancelled → ferme)
  • 5.5: Update all test files that reference old DeclarationStatus values to use the new enum constants

• Task 6: Create DeclarationObserver (AC: #6, #7, #8)

  • 6.1: Create app/Observers/DeclarationObserver.php directory and file
  • 6.2: Implement updating(Declaration $declaration) method that validates status transitions:
    • Check if status attribute is dirty (changed)
    • Get original status and new status
    • Look up allowed transitions from DeclarationStatus::allowedTransitions()
    • If new status is NOT in the allowed list, throw ValidationException with descriptive message
  • 6.3: Implement auto-archive in the same updating() method: if new status is ferme, set $declaration->archived_at = now()
  • 6.4: Register the observer in app/Providers/AppServiceProvider.php boot() method using Declaration::observe(DeclarationObserver::class)

• Task 7: Update existing tests and add new tests (AC: #9)

  • 7.1: Fix any test failures caused by the DeclarationStatus enum change (update factory defaults, assertions)
  • 7.2: Update DeclarationFactory to use DeclarationStatus::Created as the default status
  • 7.3: Create tests/Feature/Declaration/DeclarationStatusFlowTest.php with tests for:
    • Valid transition: created → en_cours
    • Valid transition: en_cours → en_attente_client
    • Valid transition: en_attente_client → en_cours
    • Valid transition: en_cours → termine
    • Valid transition: termine → ferme
    • Invalid transition: created → ferme (expect ValidationException)
    • Invalid transition: created → termine (expect ValidationException)
    • Auto-archive: ferme status sets archived_at
    • Scope tests: active() excludes archived, archived() includes only archived
  • 7.4: Create tests/Feature/Database/FoundationMigrationsTest.php with tests for:
    • workspace_user table has permissions column
    • declarations table has archived_at column
  • 7.5: Run composer test — all tests must pass

Dev Notes

Critical Architecture Constraints

• Docker Compose ONLY: Everything runs under Docker Compose — no local installations allowed. All commands via docker compose exec laravel.test prefix.
• DeclarationStatus Enum REPLACEMENT: The current DeclarationStatus enum has 9 values (draft, waiting_documents, documents_received, processing, additional_documents_requested, waiting_client_validation, validated, closed, cancelled) that were placeholder values from the initial codebase. These must ALL be replaced with the 5 architecture-specified values. This is NOT additive — it is a complete replacement.
• bensampo/laravel-enum: The project uses bensampo/laravel-enum ^6.12, NOT native PHP enums. Follow existing patterns in DeclarationPriority.php and DeclarationType.php.
• Model casts: Use protected function casts(): array method, NOT the $casts property (per project conventions).
• Mass assignment: Always use explicit $fillable, never $guarded = [].
• Observer registration: Register in AppServiceProvider::boot() using Declaration::observe(), NOT attribute-based registration.
• Testing: Use Pest syntax (test() closures). RefreshDatabase is auto-applied via Pest.php. Run tests with composer test.
• Scope discipline: Do NOT modify files outside story scope. No cosmetic changes (EOF newlines, import reordering) to unrelated files.

Declaration Status Flow (from Architecture)

Created → En cours → En attente client → En cours → Terminé → Fermé → [auto-archive]
                                                   ↗
Created → En cours → Terminé → Fermé → [auto-archive]

Status	Value	Meaning	Who Can Set	Next Valid Statuses
Created	created	Declaration just created	System	en_cours
En cours	en_cours	Being worked on	Owner/Manager/Worker	en_attente_client, termine
En attente client	en_attente_client	Waiting for client documents	Owner/Manager/Worker	en_cours
Terminé	termine	Work completed	Owner/Manager/Worker	ferme
Fermé	ferme	Closed (triggers auto-archive)	Owner/Manager	(archived)

Auto-archive trigger: When status becomes ferme, set archived_at = now().

Re-open from archive: Only Owner/Manager. Sets archived_at = null, status back to en_cours. (Not in scope for this story — will be in Epic 5.)

Current Enum State (MUST BE REPLACED)

The current DeclarationStatus at app/Enums/DeclarationStatus.php contains these values that will be completely removed:

const Draft = 'draft';
const WaitingDocuments = 'waiting_documents';
const DocumentsReceived = 'documents_received';
const Processing = 'processing';
const AdditionalDocumentsRequested = 'additional_documents_requested';
const WaitingClientValidation = 'waiting_client_validation';
const Validated = 'validated';
const Closed = 'closed';
const Cancelled = 'cancelled';

Data Migration Mapping

When creating the data migration (Task 5.4), map old values to new:

Old Value	New Value	Rationale
draft	created	Initial state
waiting_documents	en_cours	Active work phase
documents_received	en_cours	Active work phase
processing	en_cours	Active work phase
additional_documents_requested	en_attente_client	Waiting on client
waiting_client_validation	en_attente_client	Waiting on client
validated	termine	Completed work
closed	ferme	Closed declaration
cancelled	ferme	Treat as closed

Files to Create

File	Purpose
database/migrations/xxxx_add_permissions_to_workspace_user.php	Add permissions JSON column
database/migrations/xxxx_add_archived_at_to_declarations.php	Add archived_at timestamp column
database/migrations/xxxx_migrate_declaration_status_values.php	Data migration for status values
app/Observers/DeclarationObserver.php	Status transition validation + auto-archive
tests/Feature/Declaration/DeclarationStatusFlowTest.php	Status flow tests
tests/Feature/Database/FoundationMigrationsTest.php	Migration schema tests

Files to Modify

File	Changes
app/Enums/DeclarationStatus.php	Replace all 9 values with 5 architecture values, add labels() and allowedTransitions()
app/Models/Declaration.php	Add scopeActive() and scopeArchived() scopes
app/Models/WorkspaceUser.php	Add permissions to $fillable and casts()
app/Providers/AppServiceProvider.php	Register DeclarationObserver in boot()
database/factories/DeclarationFactory.php	Update default status to DeclarationStatus::Created
Tests referencing DeclarationStatus	Update to use new enum values

Project Structure Notes

• app/Observers/ directory does NOT exist yet — must be created
• All model casts use method-based casts() not $casts property
• WorkspaceUser extends Pivot (not Model) — verify $fillable works with Pivot models
• The declarations table already has SoftDeletes (deleted_at) — archived_at is a separate concept from soft delete
• Existing DeclarationFactory uses DeclarationStatus::Draft — must be updated

Previous Story Intelligence (Story 0.4)

Key learnings from Story 0.4:

• Docker commands: All artisan/npm commands via docker compose exec laravel.test
• Scope discipline: Story 0.2 review flagged cosmetic changes as undisciplined scope — avoid changes outside story scope
• Testing: Use composer test which clears config, runs Pint lint check, then php artisan test
• Queue:work verified: Redis is configured and operational (cache, queue, sessions)
• Test count baseline: 78 tests, 222 assertions as of Story 0.4 completion (plus any tests from uncommitted 0.2/0.3 work)

Git Intelligence

• Only 2 commits exist: initial codebase (35545c2) and BMAD setup (d380df4)
• Stories 0.2, 0.3, 0.4 are complete but changes are unstaged/uncommitted in working tree
• Branch: l-ami-fiduciaire-v1.0.0

Testing Standards

• Use Pest syntax (test() closures), never PHPUnit class-based tests
• RefreshDatabase is auto-applied via Pest.php — don't add manually
• Assertions: prefer Pest's expect() chaining over PHPUnit assert*() methods
• Use route() helper for URLs in tests, never hardcoded paths
• Feature tests grouped by domain subdirectory
• Test descriptions: lowercase, descriptive strings
• Run tests: composer test (clears config, runs Pint, runs tests)

References

• [Source: _bmad-output/planning-artifacts/epics.md#Story 0.5]
• [Source: _bmad-output/planning-artifacts/architecture.md#Declaration Status Flow]
• [Source: _bmad-output/planning-artifacts/architecture.md#D1 Permission Storage]
• [Source: _bmad-output/planning-artifacts/architecture.md#D2 Archive Strategy]
• [Source: _bmad-output/project-context.md#Critical Implementation Rules]
• [Source: app/Enums/DeclarationStatus.php (current — 9 placeholder values)]
• [Source: app/Models/Declaration.php (current — no archived_at, no scopes)]
• [Source: app/Models/WorkspaceUser.php (current — no permissions column/cast)]
• [Source: app/Providers/AppServiceProvider.php (current — no observer registration)]
• [Source: database/factories/DeclarationFactory.php (current — uses DeclarationStatus::Draft)]
• [Source: _bmad-output/implementation-artifacts/0-4-configure-redis-for-cache-queue-and-sessions.md#Dev Notes]

Change Log

• 2026-03-12: Story 0.5 implementation complete — added foundation migrations (permissions, archived_at), replaced DeclarationStatus enum with 5 architecture-specified values, created DeclarationObserver for status transition validation and auto-archive, updated all controllers/seeder/factory/tests referencing old enum values. 91 tests pass, 2 pre-existing Redis config failures unrelated to this story.
• 2026-03-12: Code review — 7 issues found (2 critical, 2 high, 3 medium), all fixed:
  • [C1] ConfirmController: changed termine → en_cours to respect observer transition rules (client confirms = back to accountant)
  • [C2] DeclarationMessageController: added created → en_cours intermediate transition before setting en_attente_client
  • [H1] UploadController: guarded status update to only fire when transition is valid
  • [H2] Declaration model: added archived_at to casts() as datetime
  • [M1] Declaration model: added archived_at to $fillable
  • [M2] DatabaseSeeder: set archived_at = now() for ferme declarations to ensure data consistency
  • [M3] DeclarationController edit form exposes all statuses (deferred — observer catches invalid transitions with validation error)
  • 93 tests pass (240 assertions) after fixes

Dev Agent Record

Agent Model Used

Claude Opus 4.6

Debug Log References

• Pint lint failure on import order in AppServiceProvider.php — fixed by reordering imports alphabetically
• RenameFoldersToDeclarationsTest rollback test failed due to new migrations changing step count — fixed by updating --step from 2 to 5

Completion Notes List

• All 7 tasks and 24 subtasks completed successfully
• 3 new migrations created and applied: permissions column, archived_at column, status data migration
• DeclarationStatus enum fully replaced: 9 old values → 5 architecture values with labels() and allowedTransitions()
• DeclarationObserver created with status transition validation + auto-archive on ferme
• 12 new tests added (10 status flow + 2 migration schema tests)
• All controllers, seeder, and factory updated to use new enum values
• 91 tests pass, 2 pre-existing RedisConnectivityTest failures (queue/session config in test env)
• No scope creep — only story-scoped files modified

File List

Created:

• database/migrations/2026_03_12_044146_add_permissions_to_workspace_user.php
• database/migrations/2026_03_12_044334_add_archived_at_to_declarations.php
• database/migrations/2026_03_12_044414_migrate_declaration_status_values.php
• app/Observers/DeclarationObserver.php
• tests/Feature/Declaration/DeclarationStatusFlowTest.php
• tests/Feature/Database/FoundationMigrationsTest.php

Modified:

• app/Enums/DeclarationStatus.php
• app/Models/Declaration.php
• app/Models/WorkspaceUser.php
• app/Providers/AppServiceProvider.php
• database/factories/DeclarationFactory.php
• app/Http/Controllers/DeclarationController.php
• app/Http/Controllers/DashboardController.php
• app/Http/Controllers/WorkspaceController.php
• app/Http/Controllers/Client/UploadController.php
• app/Http/Controllers/Client/ConfirmController.php
• app/Http/Controllers/DeclarationMessageController.php
• database/seeders/DatabaseSeeder.php
• tests/Feature/Declaration/DeclarationTypeTest.php
• tests/Feature/Database/RenameFoldersToDeclarationsTest.php