From aec3f2ff980e8edd26557834d387c5332394ab65 Mon Sep 17 00:00:00 2001 From: NHoarau Date: Fri, 12 Jun 2026 23:15:55 +0400 Subject: [PATCH] feat(project-crud-sync): add planning artifacts for CRUD project lifecycle - proposal.md: defines scope and motivation for unified CRUD operations - design.md: documents architecture decisions (Postgres, Docker Compose, Nest CLI scaffolding, Schema-Driven Pipes from @workspace/schema) - specs: contract for project lifecycle management, migrations and seeding - tasks: implementation checklist covering infra, API, Web and testing --- .../changes/project-crud-sync/.openspec.yaml | 2 ++ openspec/changes/project-crud-sync/design.md | 27 +++++++++++++++++++ .../changes/project-crud-sync/proposal.md | 21 +++++++++++++++ .../specs/project-full-lifecycle/spec.md | 22 +++++++++++++++ openspec/changes/project-crud-sync/tasks.md | 19 +++++++++++++ 5 files changed, 91 insertions(+) create mode 100644 openspec/changes/project-crud-sync/.openspec.yaml create mode 100644 openspec/changes/project-crud-sync/design.md create mode 100644 openspec/changes/project-crud-sync/proposal.md create mode 100644 openspec/changes/project-crud-sync/specs/project-full-lifecycle/spec.md create mode 100644 openspec/changes/project-crud-sync/tasks.md diff --git a/openspec/changes/project-crud-sync/.openspec.yaml b/openspec/changes/project-crud-sync/.openspec.yaml new file mode 100644 index 0000000..8fe2055 --- /dev/null +++ b/openspec/changes/project-crud-sync/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-06-12 diff --git a/openspec/changes/project-crud-sync/design.md b/openspec/changes/project-crud-sync/design.md new file mode 100644 index 0000000..3aa6057 --- /dev/null +++ b/openspec/changes/project-crud-sync/design.md @@ -0,0 +1,27 @@ +## Context + +The previous context remains: a unified technical layer for full CRUD operations is required for the `Project` resource across API and Web UI layers. The goal is to establish a canonical method for initializing a Project resource that can be consumed both programmatically (via API) and through the standard user interface. This requires centralizing validation and persistence logic. + +## Goals / Non-Goals + +**Goals:** +* To expose a stable, RESTful endpoint (`POST /api/v1/projects`) for project creation. +* To ensure data consistency: any project created via the API must behave identically to one created via the Web UI (and vice versa). +* To establish `project-creation` as the single source of truth requirement for project setup. +* **Local Development**: The entire stack (API, Web, DB) must be orchestrated via Docker Compose to guarantee a reproducible and persistent development environment. + +**Non-Goals:** +* Implementing granular ownership/permission checks within the creation payload itself; this should be handled by middleware/services post-creation. +* Handling advanced lifecycle events (e.g., project suspension) via the creation endpoint—these should use dedicated endpoints. + +## Decisions + +* **Architecture**: The implementation must use a clear separation of concerns: Controllers handle HTTP concerns (routing, validation), Services encapsulate business logic, and Repositories handle data access. NestJS's module system enforces this structure naturally. +* **Database Technology & Setup**: PostgreSQL is mandated as the standard database engine for persistence. The root of the monorepo MUST have a `docker-compose.yml` dedicated to infrastructure services (Postgres, volumes). API and Web apps run natively via `pnpm dev` — no containerization for application code in development. +* **Lifecycle Management**: Database migrations (schema versioning) must be executed *manually* via a dedicated CLI tool. This is critical for controlling both local and production deployment processes. +* **Input Validation Standard (NEW)**: Input validation for all API endpoints MUST be handled at the Controller level using **Schema-Driven Pipes**. All schemas used (`Project` DTOs, etc.) must be imported from and adhere to the contract defined in the shared `@workspace/schema` package. + +## Risks / Trade-offs + +[Risk] The migration tooling might not cleanly support optional data seeding after a schema change. +[Mitigation] We must provide clear setup steps in the final documentation (`tasks.md`) to ensure developers run migrations first, then seed scripts separately (and idempotently). diff --git a/openspec/changes/project-crud-sync/proposal.md b/openspec/changes/project-crud-sync/proposal.md new file mode 100644 index 0000000..a572c96 --- /dev/null +++ b/openspec/changes/project-crud-sync/proposal.md @@ -0,0 +1,21 @@ +## Why + +Current project management lacks a unified layer for full CRUD operations. The ability to create, read, update, and delete projects must be available consistently across both the internal API and the public Web UI. Furthermore, robust data lifecycle management—including database migrations (schema changes) and repeatable initial population via seeding—is required to ensure data integrity and development ease. + +## What Changes + +* **New Capability**: Full Project Lifecycle Management will be implemented: Create (C), Read (R), Update (U), Delete (D). +* **Technical Change**: The system must incorporate a dedicated, idempotent database migration mechanism for the `Project` entity. +* **Data Initialization**: Implement optional seeding mechanisms to populate initial dummy data or test scenarios upon deployment/setup. + +## Capabilities + +### New Capabilities +- `project-full-lifecycle`: Governing all CRUD operations and the associated schema management (migrations) for the Project resource. + +### Modified Capabilities + + +## Impact + +This change affects the core persistence layer, requiring database migrations (`Project` table/schema), service logic updates in both API and Web layers to handle full CRUD operations, and introducing new tooling/hooks for schema versioning (migrations) and initial data population (seeding scripts). diff --git a/openspec/changes/project-crud-sync/specs/project-full-lifecycle/spec.md b/openspec/changes/project-crud-sync/specs/project-full-lifecycle/spec.md new file mode 100644 index 0000000..af3e37b --- /dev/null +++ b/openspec/changes/project-crud-sync/specs/project-full-lifecycle/spec.md @@ -0,0 +1,22 @@ +## ADDED Requirements + +### Requirement: Project Lifecycle Management (CRUD) +The system SHALL provide full CRUD functionality for the `Project` resource, managed by a central service layer. All operations must be atomic and transactionally consistent across API and Web paths. This includes validation on creation (name uniqueness). + +#### Scenario: Successful Project Creation +- **WHEN** valid payload {name, ownerId, templateType} is submitted to POST /projects +- **THEN** a unique Project resource record is created with status 'ACTIVE', and all related metadata are initialized correctly. + +### Requirement: Schema Migration Enforcement +The system SHALL enforce database schema changes via versioned migrations (e.g., using an established ORM migration tool). The deployment process MUST fail if the current schema does not match the expected state defined by the latest migration script. + +#### Scenario: Applying New Schema +- **WHEN** deploying a change requiring a new column (`last_updated`) on `projects` table +- **THEN** the deployment pipeline runs the required migration, adding the column without breaking existing application runtime logic (e.g., providing a default value or nullability). + +### Requirement: Optional Data Seeding +The system SHALL support optional data seeding scripts for development and testing environments. These scripts MUST be idempotent to allow multiple safe executions. + +#### Scenario: Running Seed Scripts +- **WHEN** running the setup script `pnpm run db:seed` in a test environment with existing data +- **THEN** any record matching seed criteria (e.g., default user) is updated rather than duplicated, and the script logs successful updates/inserts. \ No newline at end of file diff --git a/openspec/changes/project-crud-sync/tasks.md b/openspec/changes/project-crud-sync/tasks.md new file mode 100644 index 0000000..f3d32b5 --- /dev/null +++ b/openspec/changes/project-crud-sync/tasks.md @@ -0,0 +1,19 @@ +## 1. Database & Infrastructure Setup (Mandatory First Step) + +- [ ] 1.1 **Dockerization**: Create a root `docker-compose.yml` (`work-hub-server/docker-compose.yml`) that declares a PostgreSQL service and named volumes for persistence. Do NOT include API or Web app containers — they run natively during development. +- [ ] 1.2 **Persistence**: Define and map persistent volumes in the root `docker-compose.yml` to ensure project data survives container restarts. +- [ ] 1.3 **CLI Utility**: Implement a dedicated command/utility (e.g., `db:setup`) that orchestrates the execution of migrations and seeding, ensuring idempotency. + +## 2. API Layer Implementation (API) + +- [ ] 2.1 **Scaffolding**: Use the Nest CLI (`nest generate resource`) to create the basic resource structure for Project (Controller, Service, Module). This ensures adherence to module structure, dependency injection patterns, and common boilerplate across all APIs in the monorepo. +- [ ] 2.2 Implement necessary request validation using **Schema-Driven Pipes** that import their structure from `@workspace/schema`, ensuring consistency between API and Web layers. + +## 3. Web Layer Implementation (Web) + +- [ ] 3.1 Update `apps/web` store/composables to call the new API endpoints and manage state correctly following successful write or delete operations. + +## 4. Testing & Tooling + +- [ ] 4.1 Write comprehensive unit tests covering the Controller, the Service, and the Repository layers. +- [ ] 4.2 Update E2E test suites to verify complete CRUD workflows via HTTP calls and UI interactions, ensuring the service layer is correctly tested against a containerized DB.