wanzi/ftb-project-management
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1bf630a7bc9adb54d4fe948c193b60ca9f1dbcb0
ftb-project-management/docs/superpowers/plans/2026-07-08-v24-domain-crud-migration.md

15 KiB
Raw Blame History

V2.4 Domain CRUD Migration Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Move V2.4.0 through V2.4.5 from AppData-primary writes to domain CRUD primary writes backed by relation tables, while keeping AppData only as compatibility and migration fallback.

Architecture: Keep V2.2 query APIs and V2.3 AppData sync as compatibility infrastructure, then add focused NestJS domain modules that write relation tables directly and reuse Xiaobao dirty marking plus work-activity evidence rules. Frontend stores switch one domain at a time to domain APIs with AppData fallback reads until each AppData document is no longer a source of truth.

Tech Stack: Next.js 14 App Router, Zustand stores, NestJS, Prisma, PostgreSQL partitioned relation tables, Jest, node:test, TypeScript.

Global Constraints

  • Work only in /Users/wanzi/Documents/xiaowanzi-claudecode/ftb-project-management-v24-worktree on branch codex/v2.4-domain-crud.
  • Do not edit the original dirty checkout.
  • Do not push unless the user explicitly asks.
  • Follow TDD: each behavior change starts with a failing test, then minimal implementation, then verification.
  • Keep /workspace and /xiaobao-warning as relation-table read aggregations.
  • Keep AppData as compatibility fallback only; do not introduce long-term dual-source writes.
  • For partitioned tables, every lookup or mutation must carry the partition key: productId for requirements and versionId for version detail entities.
  • pnpm lint is not a V2.4 gate until the baseline ESLint setup is fixed; current baseline fails because server/shared lint tooling is missing.

Task 1: V2.4.0 Domain Contract Unification

Files:

  • Modify: packages/shared/src/enums.ts
  • Modify: packages/shared/src/index.ts
  • Modify: apps/server/src/modules/requirement/requirement.service.spec.ts
  • Modify: apps/server/src/modules/requirement/requirement.service.ts
  • Modify: apps/server/src/modules/requirement/dto/update-requirement-status.dto.ts
  • Modify: apps/web/lib/requirement.ts
  • Modify: apps/web/lib/dev-task.ts
  • Modify: apps/web/lib/test-case.ts
  • Modify: apps/web/lib/bug.ts
  • Modify: apps/web/lib/version-plan.ts

Interfaces:

  • Produces: shared status constants/enums for Requirement, VersionPlan, DevTask, TestCase, Bug, and Version.

  • Consumes: current frontend status values documented in docs/architecture.md.

  • Add failing shared contract tests proving shared statuses equal current frontend statuses.

  • Add failing backend tests proving Requirement transitions use pending_review -> adopted/rejected, rejected -> pending_review, and adopted -> planned -> developing -> testing -> released -> closed.

  • Replace old shared draft/reviewing/approved/delivered requirement status contract with current domain statuses.

  • Add shared contracts for VersionPlanStatus, DevTaskStatus, TestCaseStatus, BugStatus, and VersionStatus.

  • Update backend Requirement DTO validation and service transition table.

  • Run targeted tests: pnpm --filter server test -- requirement.service.spec.ts and shared/web tests added in this task.

  • Run gates: pnpm type-check, pnpm test, pnpm build, DATABASE_URL=postgresql://postgres:postgres@localhost:5432/ftb_pm pnpm --filter server exec prisma validate --schema prisma/schema.prisma, pnpm deploy:verify.

  • Commit: feat(v2.4): 统一领域状态契约.

Task 2: V2.4.1 Product / Project / Version Root Main Writes

Files:

  • Create: apps/server/src/modules/project/project.module.ts
  • Create: apps/server/src/modules/project/project.controller.ts
  • Create: apps/server/src/modules/project/project.service.ts
  • Create: apps/server/src/modules/project/dto/create-project.dto.ts
  • Create: apps/server/src/modules/project/dto/update-project.dto.ts
  • Create: apps/server/src/modules/project/project.service.spec.ts
  • Create: apps/server/src/modules/version/version.module.ts
  • Create: apps/server/src/modules/version/version.controller.ts
  • Create: apps/server/src/modules/version/version.service.ts
  • Create: apps/server/src/modules/version/dto/create-version.dto.ts
  • Create: apps/server/src/modules/version/dto/update-version.dto.ts
  • Create: apps/server/src/modules/version/version.service.spec.ts
  • Modify: apps/server/src/modules/product/product.service.ts
  • Modify: apps/server/src/app.module.ts
  • Create: apps/web/lib/domain-api.ts
  • Modify: apps/web/stores/useProductStore.ts
  • Modify: apps/web/lib/product-overview-persistence.test.ts
  • Modify: apps/web/lib/product-store-persistence-source.test.ts

Interfaces:

  • Produces: /api/v1/products, /api/v1/products/:productId/projects, /api/v1/products/:productId/versions, and /api/v1/products/:productId/projects/:projectId/versions.

  • Consumes: existing product/project/version tree shape from products-overview.

  • Add failing backend tests for project create/list/update/delete by productId.

  • Add failing backend tests for version create/list/update/delete by productId and optional projectId.

  • Add failing tests proving deleting a version releases linked requirements and deletes version-scoped plans/tasks/test cases/bugs.

  • Add failing frontend tests proving useProductStore saves root mutations through domain APIs and falls back to products-overview when APIs are unavailable.

  • Implement Project and Version modules with conservative DTO validation.

  • Keep Product CRUD as the top-level root and add child include helpers only where needed.

  • Switch Product store mutations to domain APIs while retaining AppData compatibility read.

  • Run targeted backend and frontend tests.

  • Run full gates and commit: feat(v2.4): 切换根数据领域主写.

Task 3: V2.4.2 Requirement Main Writes And Server Pagination

Files:

  • Modify: apps/server/src/modules/requirement/requirement.controller.ts
  • Modify: apps/server/src/modules/requirement/requirement.service.ts
  • Modify: apps/server/src/modules/requirement/dto/create-requirement.dto.ts
  • Modify: apps/server/src/modules/requirement/dto/update-requirement.dto.ts
  • Modify: apps/server/src/modules/requirement/requirement.service.spec.ts
  • Modify: apps/server/src/modules/v22-query/v22-query.service.ts
  • Modify: apps/web/lib/requirement-v22-query.ts
  • Modify: apps/web/stores/useRequirementStore.ts
  • Modify: apps/web/lib/requirement-sort.test.ts
  • Modify: apps/web/lib/requirement-v22-query.test.ts

Interfaces:

  • Produces: requirement create/update/delete/status/link APIs that write requirements directly by (id, productId).

  • Produces: server-side list contract with productId, projectId, versionId, status, priority, type, q, sort, cursor, and limit.

  • Add failing backend tests for server pagination, search, filters, sort, cursor, and partition-key validation.

  • Add failing tests for create/update fields currently present in frontend requirements: projectId, versionId, type, sourceType, sourceTarget, and platform.

  • Add failing frontend tests proving requirement pool calls server pagination and does not require loading the full AppData document for list/search/filter/sort.

  • Implement service-side query parsing and safe order fields.

  • Switch useRequirementStore create/update/delete/status/link writes to Requirement APIs.

  • Keep AppData read fallback only when relation API is unavailable.

  • Run targeted tests and full gates.

  • Commit: feat(v2.4): 切换需求池领域主写.

Task 4: V2.4.3 VersionPlan / DevTask Main Writes

Files:

  • Create: apps/server/src/modules/version-plan/version-plan.module.ts
  • Create: apps/server/src/modules/version-plan/version-plan.controller.ts
  • Create: apps/server/src/modules/version-plan/version-plan.service.ts
  • Create: apps/server/src/modules/version-plan/dto/create-version-plan.dto.ts
  • Create: apps/server/src/modules/version-plan/dto/update-version-plan.dto.ts
  • Create: apps/server/src/modules/version-plan/version-plan.service.spec.ts
  • Create: apps/server/src/modules/dev-task/dev-task.module.ts
  • Create: apps/server/src/modules/dev-task/dev-task.controller.ts
  • Create: apps/server/src/modules/dev-task/dev-task.service.ts
  • Create: apps/server/src/modules/dev-task/dto/create-dev-task.dto.ts
  • Create: apps/server/src/modules/dev-task/dto/update-dev-task.dto.ts
  • Create: apps/server/src/modules/dev-task/dev-task.service.spec.ts
  • Create: apps/server/src/modules/work-activity/work-activity.module.ts
  • Create: apps/server/src/modules/work-activity/work-activity.service.ts
  • Create: apps/server/src/modules/work-activity/work-activity.service.spec.ts
  • Modify: apps/server/src/modules/migration/app-data-v23-sync.service.ts
  • Modify: apps/server/src/app.module.ts
  • Modify: apps/web/stores/useVersionPlanStore.ts
  • Modify: apps/web/stores/useDevTaskStore.ts
  • Modify: apps/web/stores/useWorkActivityStore.ts
  • Modify: apps/web/lib/version-plan.test.ts
  • Modify: apps/web/lib/version-plan-workflow.test.ts
  • Modify: apps/web/lib/dev-task.test.ts
  • Modify: apps/web/lib/dev-task-transitions.test.ts

Interfaces:

  • Produces: /api/v1/versions/:versionId/plans and /api/v1/versions/:versionId/dev-tasks.

  • Produces: minimal relational WorkActivityService.record() for successful plan/task domain actions.

  • Add failing backend tests for VersionPlan create/update/status/complete writing version_plans.

  • Add failing backend tests for DevTask create/update/status/block/unblock/transfer writing dev_tasks by (id, versionId).

  • Add failing backend tests proving status changes create work_activities records and mark Xiaobao summaries dirty.

  • Add failing frontend tests proving plan/task stores write domain APIs and append activity evidence from API responses.

  • Implement VersionPlan and DevTask modules using existing frontend workflow rules as the contract.

  • Add minimal WorkActivity service and reuse V2.3 dirty-summary strategy.

  • Switch version plan and dev task stores to domain writes with AppData fallback read only.

  • Run targeted tests and full gates.

  • Commit: feat(v2.4): 切换计划与开发任务主写.

Task 5: V2.4.4 TestCase / Bug Main Writes

Files:

  • Create: apps/server/src/modules/test-case/test-case.module.ts
  • Create: apps/server/src/modules/test-case/test-case.controller.ts
  • Create: apps/server/src/modules/test-case/test-case.service.ts
  • Create: apps/server/src/modules/test-case/dto/create-test-case.dto.ts
  • Create: apps/server/src/modules/test-case/dto/update-test-case.dto.ts
  • Create: apps/server/src/modules/test-case/test-case.service.spec.ts
  • Create: apps/server/src/modules/bug/bug.module.ts
  • Create: apps/server/src/modules/bug/bug.controller.ts
  • Create: apps/server/src/modules/bug/bug.service.ts
  • Create: apps/server/src/modules/bug/dto/create-bug.dto.ts
  • Create: apps/server/src/modules/bug/dto/update-bug.dto.ts
  • Create: apps/server/src/modules/bug/bug.service.spec.ts
  • Modify: apps/server/src/modules/work-activity/work-activity.service.ts
  • Modify: apps/server/src/app.module.ts
  • Modify: apps/web/stores/useTestCaseStore.ts
  • Modify: apps/web/stores/useBugStore.ts
  • Modify: apps/web/lib/test-case.test.ts
  • Modify: apps/web/lib/test-case-workflow.test.ts
  • Modify: apps/web/lib/bug.test.ts
  • Modify: apps/web/lib/bug-workflow.test.ts

Interfaces:

  • Produces: /api/v1/versions/:versionId/test-cases and /api/v1/versions/:versionId/bugs.

  • Consumes: TestCase round-copy workflow and Bug status workflow already defined in frontend helpers.

  • Add failing backend tests for TestCase create/update/status/round-copy by (id, versionId).

  • Add failing backend tests for Bug create/update/status/transfer/close by (id, versionId).

  • Add failing tests proving TestCase/Bug writes create activity evidence and mark Xiaobao dirty.

  • Add failing frontend tests proving stores write domain APIs and preserve existing workflow outputs.

  • Implement TestCase and Bug modules.

  • Switch test case and bug stores to domain writes with AppData fallback read only.

  • Run targeted tests and full gates.

  • Commit: feat(v2.4): 切换测试与缺陷主写.

Task 6: V2.4.5 Dictionaries, Members, Worklogs, Overtime, Activity Evidence Consolidation

Files:

  • Create: apps/server/src/modules/member/member.module.ts
  • Create: apps/server/src/modules/member/member.controller.ts
  • Create: apps/server/src/modules/member/member.service.ts
  • Create: apps/server/src/modules/member/member.service.spec.ts
  • Create: apps/server/src/modules/task-category/task-category.module.ts
  • Create: apps/server/src/modules/task-category/task-category.controller.ts
  • Create: apps/server/src/modules/task-category/task-category.service.ts
  • Create: apps/server/src/modules/task-category/task-category.service.spec.ts
  • Create: apps/server/src/modules/task-worklog/task-worklog.module.ts
  • Create: apps/server/src/modules/task-worklog/task-worklog.controller.ts
  • Create: apps/server/src/modules/task-worklog/task-worklog.service.ts
  • Create: apps/server/src/modules/task-worklog/task-worklog.service.spec.ts
  • Create: apps/server/src/modules/overtime/overtime.module.ts
  • Create: apps/server/src/modules/overtime/overtime.controller.ts
  • Create: apps/server/src/modules/overtime/overtime.service.ts
  • Create: apps/server/src/modules/overtime/overtime.service.spec.ts
  • Modify: apps/server/src/modules/work-activity/work-activity.service.ts
  • Modify: apps/server/src/app.module.ts
  • Modify: apps/web/stores/useMemberStore.ts
  • Modify: apps/web/stores/useTaskCategoryStore.ts
  • Modify: apps/web/stores/useTaskWorklogStore.ts
  • Modify: apps/web/stores/useOvertimeStore.ts
  • Modify: apps/web/stores/useWorkActivityStore.ts
  • Modify: docs/architecture.md
  • Modify: docs/decisions.md
  • Modify: docs/roadmap.md
  • Modify: docs/workflow.md

Interfaces:

  • Produces: domain APIs for members, task categories, task worklogs, overtime records, and activity records.

  • Consumes: existing AppData keys only for compatibility import/fallback during the transition.

  • Add failing backend tests for member CRUD, protected built-in admin behavior, and role/department fields used by the UI.

  • Add failing backend tests for task category CRUD and uniqueness by (group, name).

  • Add failing backend tests for append-style TaskWorklog, OvertimeRecord, and WorkActivity writes.

  • Add failing frontend tests proving dictionary/member/evidence stores no longer save AppData as the main write path.

  • Implement the remaining domain modules.

  • Switch stores to domain writes, preserving fallback reads and current UI data shapes.

  • Update architecture, decisions, workflow, and roadmap to mark V2.4.0-V2.4.5 complete and clarify AppData is now compatibility/migration fallback.

  • Run full gates: pnpm type-check, pnpm test, pnpm build, DATABASE_URL=postgresql://postgres:postgres@localhost:5432/ftb_pm pnpm --filter server exec prisma validate --schema prisma/schema.prisma, pnpm deploy:verify.

  • Commit: feat(v2.4): 完成领域主写迁移.