237 lines
15 KiB
Markdown
237 lines
15 KiB
Markdown
# 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`.
|
|
|
|
- [x] Add failing shared contract tests proving shared statuses equal current frontend statuses.
|
|
- [x] Add failing backend tests proving Requirement transitions use `pending_review -> adopted/rejected`, `rejected -> pending_review`, and `adopted -> planned -> developing -> testing -> released -> closed`.
|
|
- [x] Replace old shared `draft/reviewing/approved/delivered` requirement status contract with current domain statuses.
|
|
- [x] Add shared contracts for `VersionPlanStatus`, `DevTaskStatus`, `TestCaseStatus`, `BugStatus`, and `VersionStatus`.
|
|
- [x] Update backend Requirement DTO validation and service transition table.
|
|
- [x] Run targeted tests: `pnpm --filter server test -- requirement.service.spec.ts` and shared/web tests added in this task.
|
|
- [x] 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`.
|
|
- [x] 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`.
|
|
|
|
- [x] Add failing backend tests for project create/list/update/delete by `productId`.
|
|
- [x] Add failing backend tests for version create/list/update/delete by `productId` and optional `projectId`.
|
|
- [x] Add failing tests proving deleting a version releases linked requirements and deletes version-scoped plans/tasks/test cases/bugs.
|
|
- [x] Add failing frontend tests proving `useProductStore` saves root mutations through domain APIs and falls back to `products-overview` when APIs are unavailable.
|
|
- [x] Implement Project and Version modules with conservative DTO validation.
|
|
- [x] Keep Product CRUD as the top-level root and add child include helpers only where needed.
|
|
- [x] Switch Product store mutations to domain APIs while retaining AppData compatibility read.
|
|
- [x] Run targeted backend and frontend tests.
|
|
- [x] 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`.
|
|
|
|
- [x] Add failing backend tests for server pagination, search, filters, sort, cursor, and partition-key validation.
|
|
- [x] Add failing tests for create/update fields currently present in frontend requirements: `projectId`, `versionId`, `type`, `sourceType`, `sourceTarget`, and `platform`.
|
|
- [x] Add failing frontend tests proving requirement pool calls server pagination and does not require loading the full AppData document for list/search/filter/sort.
|
|
- [x] Implement service-side query parsing and safe order fields.
|
|
- [x] Switch `useRequirementStore` create/update/delete/status/link writes to Requirement APIs.
|
|
- [x] Keep AppData read fallback only when relation API is unavailable.
|
|
- [x] Run targeted tests and full gates.
|
|
- [x] 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.
|
|
|
|
- [x] Add failing backend tests for VersionPlan create/update/status/complete writing `version_plans`.
|
|
- [x] Add failing backend tests for DevTask create/update/status/block/unblock/transfer writing `dev_tasks` by `(id, versionId)`.
|
|
- [x] Add failing backend tests proving status changes create `work_activities` records and mark Xiaobao summaries dirty.
|
|
- [x] Add failing frontend tests proving plan/task stores write domain APIs and append activity evidence from API responses.
|
|
- [x] Implement VersionPlan and DevTask modules using existing frontend workflow rules as the contract.
|
|
- [x] Add minimal WorkActivity service and reuse V2.3 dirty-summary strategy.
|
|
- [x] Switch version plan and dev task stores to domain writes with AppData fallback read only.
|
|
- [x] Run targeted tests and full gates.
|
|
- [x] 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.
|
|
|
|
- [x] Add failing backend tests for TestCase create/update/status/round-copy by `(id, versionId)`.
|
|
- [x] Add failing backend tests for Bug create/update/status/transfer/close by `(id, versionId)`.
|
|
- [x] Add failing tests proving TestCase/Bug writes create activity evidence and mark Xiaobao dirty.
|
|
- [x] Add failing frontend tests proving stores write domain APIs and preserve existing workflow outputs.
|
|
- [x] Implement TestCase and Bug modules.
|
|
- [x] Switch test case and bug stores to domain writes with AppData fallback read only.
|
|
- [x] Run targeted tests and full gates.
|
|
- [x] 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): 完成领域主写迁移`.
|