687 lines
27 KiB
Markdown
687 lines
27 KiB
Markdown
# V2.5-V2.8 Parallel Task Breakdown Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** After V2.4 relation-table domain writes are complete, split V2.5-V2.8 into approval-ready parallel work streams with clear dependencies, gates, files, and acceptance criteria.
|
|
|
|
**Architecture:** V2.5 owns data correctness, permissions, audit, and AppData retirement. V2.6 owns scale, background processing, and Xiaobao backendization. V2.7 owns enterprise collaboration and management governance. V2.8 owns production hardening and operational closure. Each stream should run in its own Codex thread/worktree, with this current thread acting as coordinator and integration reviewer.
|
|
|
|
**Tech Stack:** Next.js 14 App Router, Zustand, Tailwind/Shadcn UI, NestJS, Prisma, PostgreSQL partitioned tables, Redis when background job coordination needs a runtime store, Docker Compose, GitHub Actions.
|
|
|
|
## Global Constraints
|
|
|
|
- V2.4 is treated as complete before executing this plan: domain CRUD main writes exist for core domains and AppData is no longer the business write source.
|
|
- Do not delete AppData data directly; AppData retirement order is `禁写 -> 双读核对 -> 移除 fallback -> 只读归档/导出 -> 后续删表`.
|
|
- Permissions and audit must be enforced on server-side domain APIs, not only in frontend guards.
|
|
- Keep current frontend state shape where practical; migrate persistence boundaries, not UI behavior, unless the task explicitly says otherwise.
|
|
- High-growth queries must stay scoped by partition keys: `productId`, `versionId`, or `createdAt`.
|
|
- Every implementation task must include tests and update `docs/architecture.md`, `docs/decisions.md`, `docs/workflow.md`, or `docs/roadmap.md` when it changes architecture, decisions, workflow, or milestones.
|
|
- Do not push unless the user explicitly asks.
|
|
|
|
---
|
|
|
|
## Parallel Execution Topology
|
|
|
|
### Coordinator Thread
|
|
|
|
**Purpose:** Keep the merged truth, review cross-stream contracts, and decide integration order.
|
|
|
|
**Responsibilities:**
|
|
- [ ] Confirm V2.4 completion commit/branch before opening execution threads.
|
|
- [ ] Create four execution threads after user approval.
|
|
- [ ] Assign each thread a branch/worktree.
|
|
- [ ] Review PR/diff from each stream before merging.
|
|
- [ ] Resolve contract conflicts across RBAC, audit events, background jobs, notifications, and deployment scripts.
|
|
|
|
### Recommended Execution Threads
|
|
|
|
| Thread | Branch | Scope | Can Start Immediately After V2.4 |
|
|
|---|---|---|---|
|
|
| V2.5 | `codex/v25-appdata-rbac-audit` | AppData retirement, RBAC, audit, consistency | Yes |
|
|
| V2.6 | `codex/v26-performance-xiaobao-bg` | Scale testing, query performance, Xiaobao background worker | Yes, but notification hooks wait for V2.7 |
|
|
| V2.7 | `codex/v27-enterprise-collab-governance` | Notifications, collaboration, management governance | Yes for schema/design; server enforcement depends on V2.5 permission contracts |
|
|
| V2.8 | `codex/v28-production-ops-closure` | Backup, restore, smoke tests, monitoring, runbooks | Yes |
|
|
|
|
---
|
|
|
|
## Shared Contracts To Freeze First
|
|
|
|
### Task S1: Cross-Stream Contract Freeze
|
|
|
|
**Files:**
|
|
- Create: `docs/superpowers/plans/2026-07-08-v25-v28-contracts.md`
|
|
- Modify: `docs/architecture.md`
|
|
- Modify: `docs/decisions.md`
|
|
|
|
**Interfaces:**
|
|
- Produces: stable contracts for `actorId`, `resourceScope`, `AuditEvent`, `Permission`, `BackgroundJob`, and `Notification`.
|
|
- Consumes: V2.4 domain CRUD API request/response shape.
|
|
|
|
**Checklist:**
|
|
- [ ] Define `actorId` source: server extracts from authenticated session/JWT; frontend does not submit trusted actor identity.
|
|
- [ ] Define resource scope shape: `{ productId?: string; projectId?: string; versionId?: string; entityType: string; entityId: string }`.
|
|
- [ ] Define audit event fields: `id`, `actorId`, `action`, `entityType`, `entityId`, `resourceScope`, `before`, `after`, `metadata`, `createdAt`.
|
|
- [ ] Define permission naming: `<domain>:<action>`, for example `version:update`, `bug:close`, `audit:view`.
|
|
- [ ] Define background job fields: `id`, `type`, `status`, `dedupeKey`, `payload`, `lockedAt`, `lockedBy`, `attempts`, `lastError`, `createdAt`, `updatedAt`.
|
|
- [ ] Define notification fields: `id`, `recipientId`, `type`, `title`, `body`, `resourceLink`, `readAt`, `createdAt`.
|
|
- [ ] Add a decision record explaining that each parallel stream may extend but not break these contracts.
|
|
|
|
**Acceptance:**
|
|
- [ ] Four execution threads can implement independently without inventing incompatible shapes.
|
|
- [ ] Docs state which stream owns each contract.
|
|
|
|
---
|
|
|
|
## V2.5: AppData Retirement + RBAC/Audit/Consistency
|
|
|
|
### Task 2.5.1: Server Auth Context And RBAC Guard
|
|
|
|
**Files:**
|
|
- Create: `apps/server/src/common/auth/auth-context.ts`
|
|
- Create: `apps/server/src/common/auth/current-user.decorator.ts`
|
|
- Create: `apps/server/src/common/auth/permission.guard.ts`
|
|
- Create: `apps/server/src/common/auth/permission.decorator.ts`
|
|
- Create: `apps/server/src/common/auth/permission.service.ts`
|
|
- Test: `apps/server/src/common/auth/permission.guard.spec.ts`
|
|
- Test: `apps/server/src/common/auth/permission.service.spec.ts`
|
|
|
|
**Scope:**
|
|
- [ ] Resolve current user from authenticated request.
|
|
- [ ] Enforce permission on server endpoints.
|
|
- [ ] Support super-admin wildcard `*`.
|
|
- [ ] Support project/version membership derived from relation tables.
|
|
|
|
**Acceptance:**
|
|
- [ ] A request without current user is rejected for protected domain APIs.
|
|
- [ ] A user without required permission is rejected.
|
|
- [ ] A super-admin role passes.
|
|
- [ ] Permission checks can be unit-tested without HTTP server startup.
|
|
|
|
**Verification:**
|
|
- [ ] `pnpm --filter server test -- permission`
|
|
- [ ] `pnpm --filter server exec prisma validate --schema prisma/schema.prisma`
|
|
|
|
### Task 2.5.2: Audit Event Table And Writer
|
|
|
|
**Files:**
|
|
- Modify: `apps/server/prisma/schema.prisma`
|
|
- Create: `apps/server/src/modules/audit/audit.module.ts`
|
|
- Create: `apps/server/src/modules/audit/audit.service.ts`
|
|
- Create: `apps/server/src/modules/audit/audit.controller.ts`
|
|
- Create: `apps/server/src/modules/audit/dto/list-audit-events.dto.ts`
|
|
- Test: `apps/server/src/modules/audit/audit.service.spec.ts`
|
|
- Test: `apps/server/src/modules/audit/audit.controller.spec.ts`
|
|
|
|
**Scope:**
|
|
- [ ] Add append-only `audit_events` table, range-partitioned by `created_at` if migration pattern supports it.
|
|
- [ ] Add `AuditService.record()` with best-effort failure isolation for non-critical audit reads, but strict audit write for mutating domain APIs.
|
|
- [ ] Add list API filtered by entity, actor, date range, and resource scope.
|
|
- [ ] Redact secrets, passwords, tokens, and AI provider keys from `before`/`after`.
|
|
|
|
**Acceptance:**
|
|
- [ ] Domain writes can record audit event in same transaction when required.
|
|
- [ ] Audit list API requires `audit:view`.
|
|
- [ ] Sensitive fields never appear in audit payload.
|
|
|
|
**Verification:**
|
|
- [ ] `pnpm --filter server test -- audit`
|
|
- [ ] `pnpm --filter server exec prisma validate --schema prisma/schema.prisma`
|
|
|
|
### Task 2.5.3: Attach Audit And Permissions To Domain APIs
|
|
|
|
**Files:**
|
|
- Modify: `apps/server/src/modules/product/*`
|
|
- Modify: V2.4 domain modules for project, version, version-plan, dev-task, test-case, bug, member, task-category, task-worklog, overtime, work-activity
|
|
- Test: corresponding module `*.spec.ts`
|
|
|
|
**Scope:**
|
|
- [ ] Apply permission decorators to every mutating endpoint.
|
|
- [ ] Pass `actorId` into service methods from server auth context.
|
|
- [ ] Record `create`, `update`, `delete`, `status_change`, `assign`, `block`, `unblock`, `close`, and `restore` audit events.
|
|
- [ ] Ensure audit `resourceScope` includes partition key where available.
|
|
|
|
**Acceptance:**
|
|
- [ ] Every mutating domain endpoint has a permission decorator.
|
|
- [ ] Every mutating domain service path records an audit event.
|
|
- [ ] Tests cover at least one allowed and one denied request per major domain.
|
|
|
|
**Verification:**
|
|
- [ ] `pnpm --filter server test`
|
|
- [ ] `pnpm --filter server exec prisma validate --schema prisma/schema.prisma`
|
|
|
|
### Task 2.5.4: AppData Write Freeze
|
|
|
|
**Files:**
|
|
- Modify: `apps/server/src/modules/data/data.service.ts`
|
|
- Modify: `apps/server/src/modules/data/data.controller.ts`
|
|
- Create: `apps/server/src/modules/data/app-data-retirement.service.ts`
|
|
- Create: `apps/server/src/modules/data/app-data-retirement.config.ts`
|
|
- Test: `apps/server/src/modules/data/app-data-retirement.service.spec.ts`
|
|
- Test: `apps/server/src/modules/data/data.service.spec.ts`
|
|
|
|
**Scope:**
|
|
- [ ] Introduce per-key retirement state: `active`, `write_frozen`, `read_only_archive`.
|
|
- [ ] Reject writes for frozen keys with `409 APP_DATA_WRITE_FROZEN`.
|
|
- [ ] Keep reads available for diagnostics and rollback.
|
|
- [ ] Add env override for emergency rollback only when explicitly configured.
|
|
|
|
**Acceptance:**
|
|
- [ ] Frozen AppData key cannot be written through `/data/:key`.
|
|
- [ ] Read still returns value/version.
|
|
- [ ] Error includes the domain API path to use instead.
|
|
|
|
**Verification:**
|
|
- [ ] `pnpm --filter server test -- data`
|
|
|
|
### Task 2.5.5: AppData Export And Archive Tooling
|
|
|
|
**Files:**
|
|
- Create: `scripts/export-appdata-archive.mjs`
|
|
- Create: `scripts/verify-appdata-archive.mjs`
|
|
- Modify: `package.json`
|
|
- Modify: `docs/deployment.md`
|
|
- Test: `apps/web/lib/server-data.test.ts` only if client behavior changes
|
|
|
|
**Scope:**
|
|
- [ ] Export allowed AppData keys to timestamped JSON.
|
|
- [ ] Include row count, checksum, key list, and app version metadata.
|
|
- [ ] Verify archive can be parsed and checksums match.
|
|
- [ ] Document pre-retirement backup procedure.
|
|
|
|
**Acceptance:**
|
|
- [ ] `pnpm appdata:export --out ./backups/appdata-YYYYMMDD.json` creates archive.
|
|
- [ ] `pnpm appdata:verify --file ./backups/appdata-YYYYMMDD.json` validates archive.
|
|
- [ ] Deployment docs include rollback note.
|
|
|
|
**Verification:**
|
|
- [ ] `pnpm appdata:verify --file <fixture>`
|
|
- [ ] `pnpm deploy:verify`
|
|
|
|
### Task 2.5.6: Relation/AppData Consistency Verifier
|
|
|
|
**Files:**
|
|
- Create: `apps/server/src/modules/consistency/consistency.module.ts`
|
|
- Create: `apps/server/src/modules/consistency/consistency.service.ts`
|
|
- Create: `apps/server/src/modules/consistency/consistency.controller.ts`
|
|
- Create: `scripts/check-v25-consistency.mjs`
|
|
- Test: `apps/server/src/modules/consistency/consistency.service.spec.ts`
|
|
|
|
**Scope:**
|
|
- [ ] Verify counts per domain.
|
|
- [ ] Verify partition key completeness.
|
|
- [ ] Verify orphan references.
|
|
- [ ] Verify required audit coverage for sampled writes.
|
|
- [ ] Output machine-readable JSON and human-readable summary.
|
|
|
|
**Acceptance:**
|
|
- [ ] Command exits non-zero on orphan references or count mismatch.
|
|
- [ ] Command prints remediation hints by domain.
|
|
- [ ] Admin API requires `consistency:view`.
|
|
|
|
**Verification:**
|
|
- [ ] `pnpm --filter server test -- consistency`
|
|
- [ ] `pnpm consistency:check`
|
|
|
|
### Task 2.5.7: Admin UI For Audit And Consistency
|
|
|
|
**Files:**
|
|
- Create: `apps/web/app/admin/audit/page.tsx`
|
|
- Create: `apps/web/app/admin/consistency/page.tsx`
|
|
- Create: `apps/web/lib/audit-api.ts`
|
|
- Create: `apps/web/lib/consistency-api.ts`
|
|
- Modify: `apps/web/lib/permissions.ts`
|
|
- Modify: `apps/web/components/layout/Sidebar.tsx` or existing navigation component
|
|
- Test: `apps/web/lib/audit-api.test.ts`
|
|
- Test: `apps/web/lib/consistency-api.test.ts`
|
|
|
|
**Scope:**
|
|
- [ ] Add audit search UI by actor, domain, entity, date.
|
|
- [ ] Add consistency dashboard with last run result and downloadable JSON.
|
|
- [ ] Gate pages by `audit:view` and `consistency:view`.
|
|
|
|
**Acceptance:**
|
|
- [ ] Non-authorized user cannot open admin pages.
|
|
- [ ] Audit page shows redacted payload.
|
|
- [ ] Consistency page makes failed checks obvious.
|
|
|
|
**Verification:**
|
|
- [ ] `pnpm --filter web test -- audit consistency`
|
|
- [ ] `pnpm type-check`
|
|
|
|
### V2.5 Completion Gate
|
|
|
|
- [ ] All AppData business keys are at least `write_frozen` or documented as retained archive.
|
|
- [ ] All mutating domain APIs enforce server-side permission checks.
|
|
- [ ] All mutating domain APIs write audit events.
|
|
- [ ] Consistency checker passes on local migrated data.
|
|
- [ ] `docs/roadmap.md` marks V2.5 complete only after backup/export procedure is verified.
|
|
|
|
---
|
|
|
|
## V2.6: Large-Data Performance + Xiaobao Backendization
|
|
|
|
### Task 2.6.1: Large Data Fixture And Performance Harness
|
|
|
|
**Files:**
|
|
- Create: `scripts/seed-large-dataset.mjs`
|
|
- Create: `scripts/perf-check.mjs`
|
|
- Create: `docs/performance.md`
|
|
- Modify: `package.json`
|
|
|
|
**Scope:**
|
|
- [ ] Generate deterministic products, projects, versions, requirements, plans, tasks, test cases, bugs, work activities, snapshots.
|
|
- [ ] Support sizes: `small`, `medium`, `large`.
|
|
- [ ] Measure key APIs: version detail, requirement pool, workspace, Xiaobao warning, audit search.
|
|
- [ ] Write thresholds into `docs/performance.md`.
|
|
|
|
**Acceptance:**
|
|
- [ ] `pnpm perf:seed -- --size medium` is repeatable.
|
|
- [ ] `pnpm perf:check` prints p50/p95 and exits non-zero if thresholds fail.
|
|
|
|
**Verification:**
|
|
- [ ] `pnpm perf:seed -- --size small`
|
|
- [ ] `pnpm perf:check`
|
|
|
|
### Task 2.6.2: Query Budget And Index Audit
|
|
|
|
**Files:**
|
|
- Modify: `apps/server/prisma/schema.prisma`
|
|
- Create: `scripts/explain-hot-queries.mjs`
|
|
- Create: `docs/performance-hot-queries.md`
|
|
- Test: server query tests for affected services
|
|
|
|
**Scope:**
|
|
- [ ] Capture EXPLAIN plans for hot APIs.
|
|
- [ ] Add missing indexes that align with `productId`, `versionId`, `createdAt`, `assigneeId`, `status`.
|
|
- [ ] Ensure no hot API does accidental full-table scans.
|
|
|
|
**Acceptance:**
|
|
- [ ] Hot queries document includes query, partition key, index, threshold.
|
|
- [ ] `pnpm perf:explain` produces stable output.
|
|
|
|
**Verification:**
|
|
- [ ] `pnpm --filter server exec prisma validate --schema prisma/schema.prisma`
|
|
- [ ] `pnpm perf:explain`
|
|
|
|
### Task 2.6.3: Background Job Runtime
|
|
|
|
**Files:**
|
|
- Modify: `apps/server/prisma/schema.prisma`
|
|
- Create: `apps/server/src/modules/jobs/jobs.module.ts`
|
|
- Create: `apps/server/src/modules/jobs/jobs.service.ts`
|
|
- Create: `apps/server/src/modules/jobs/jobs.worker.ts`
|
|
- Create: `apps/server/src/modules/jobs/job-lock.service.ts`
|
|
- Test: `apps/server/src/modules/jobs/jobs.service.spec.ts`
|
|
- Test: `apps/server/src/modules/jobs/job-lock.service.spec.ts`
|
|
|
|
**Scope:**
|
|
- [ ] Add persisted background job table.
|
|
- [ ] Add enqueue with `dedupeKey`.
|
|
- [ ] Add lock/lease to avoid duplicate worker execution.
|
|
- [ ] Add retry with bounded attempts and last error.
|
|
- [ ] Keep worker disabled by default in tests.
|
|
|
|
**Acceptance:**
|
|
- [ ] Duplicate enqueue with same active dedupe key does not create duplicate active jobs.
|
|
- [ ] Expired lock can be reclaimed.
|
|
- [ ] Failed job retries and eventually marks `failed`.
|
|
|
|
**Verification:**
|
|
- [ ] `pnpm --filter server test -- jobs`
|
|
|
|
### Task 2.6.4: Xiaobao Risk Background Worker
|
|
|
|
**Files:**
|
|
- Create: `apps/server/src/modules/xiaobao/xiaobao.module.ts`
|
|
- Create: `apps/server/src/modules/xiaobao/xiaobao-risk.service.ts`
|
|
- Create: `apps/server/src/modules/xiaobao/xiaobao-risk.worker.ts`
|
|
- Create: `apps/server/src/modules/xiaobao/xiaobao-risk.controller.ts`
|
|
- Modify: V2.4 domain services that mark `xiaobao_risk_summaries.dirty=true`
|
|
- Test: `apps/server/src/modules/xiaobao/xiaobao-risk.service.spec.ts`
|
|
- Test: `apps/server/src/modules/xiaobao/xiaobao-risk.worker.spec.ts`
|
|
|
|
**Scope:**
|
|
- [ ] Move Xiaobao risk summary refresh to server-side job.
|
|
- [ ] Reuse current deterministic risk rules from frontend by porting into server pure functions or shared package.
|
|
- [ ] Keep AI interpretation as explanation only.
|
|
- [ ] Add cooldown and dirty summary processing.
|
|
|
|
**Acceptance:**
|
|
- [ ] Mutating version/task/test/bug/activity writes enqueue or mark risk recompute.
|
|
- [ ] Worker refreshes summary without opening `/xiaobao-warning`.
|
|
- [ ] Existing frontend can load precomputed summaries.
|
|
|
|
**Verification:**
|
|
- [ ] `pnpm --filter server test -- xiaobao`
|
|
- [ ] `pnpm --filter web test -- xiaobao`
|
|
|
|
### Task 2.6.5: Server-Side Xiaobao AI Interpretation Queue
|
|
|
|
**Files:**
|
|
- Create: `apps/server/src/modules/xiaobao/xiaobao-ai.service.ts`
|
|
- Modify: `apps/server/src/modules/ai/ai.module.ts`
|
|
- Modify: `apps/server/src/modules/ai/prompts/risk-interpret.ts`
|
|
- Test: `apps/server/src/modules/xiaobao/xiaobao-ai.service.spec.ts`
|
|
|
|
**Scope:**
|
|
- [ ] Trigger AI interpretation from backend when risk meets policy.
|
|
- [ ] Respect cooldown and risk-upgrade bypass.
|
|
- [ ] Store insight cache in relation table.
|
|
- [ ] Never mutate Version, DevTask, TestCase, Bug, Requirement, or Member.
|
|
|
|
**Acceptance:**
|
|
- [ ] `on_track` does not enqueue AI.
|
|
- [ ] `blocked` enqueues AI unless cooldown blocks it.
|
|
- [ ] Risk upgrade bypasses cooldown.
|
|
|
|
**Verification:**
|
|
- [ ] `pnpm --filter server test -- xiaobao-ai`
|
|
|
|
### Task 2.6.6: Runtime Performance Dashboard
|
|
|
|
**Files:**
|
|
- Create: `apps/server/src/modules/ops/ops.module.ts`
|
|
- Create: `apps/server/src/modules/ops/ops.controller.ts`
|
|
- Create: `apps/server/src/modules/ops/ops.service.ts`
|
|
- Create: `apps/web/app/admin/ops/page.tsx`
|
|
- Modify: `apps/web/lib/permissions.ts`
|
|
- Test: `apps/server/src/modules/ops/ops.service.spec.ts`
|
|
|
|
**Scope:**
|
|
- [ ] Surface slow request counters, slow query counters, job queue status, Xiaobao dirty summary count.
|
|
- [ ] Gate by `ops:view`.
|
|
- [ ] Do not expose secrets.
|
|
|
|
**Acceptance:**
|
|
- [ ] Admin can see queue health and slow endpoint summary.
|
|
- [ ] Non-admin cannot access ops page/API.
|
|
|
|
**Verification:**
|
|
- [ ] `pnpm --filter server test -- ops`
|
|
- [ ] `pnpm type-check`
|
|
|
|
### V2.6 Completion Gate
|
|
|
|
- [ ] Performance harness exists and thresholds are documented.
|
|
- [ ] Hot API p95 meets agreed thresholds on medium fixture.
|
|
- [ ] Xiaobao summaries refresh without page open.
|
|
- [ ] Background jobs are idempotent and retry safely.
|
|
|
|
---
|
|
|
|
## V2.7: Enterprise Collaboration + Management Governance
|
|
|
|
### Task 2.7.1: Notification Domain
|
|
|
|
**Files:**
|
|
- Modify: `apps/server/prisma/schema.prisma`
|
|
- Create: `apps/server/src/modules/notification/notification.module.ts`
|
|
- Create: `apps/server/src/modules/notification/notification.service.ts`
|
|
- Create: `apps/server/src/modules/notification/notification.controller.ts`
|
|
- Create: `apps/web/stores/useNotificationStore.ts`
|
|
- Create: `apps/web/components/notification/NotificationBell.tsx`
|
|
- Test: `apps/server/src/modules/notification/notification.service.spec.ts`
|
|
|
|
**Scope:**
|
|
- [ ] Store notification records per user.
|
|
- [ ] Add APIs to list, mark read, mark all read.
|
|
- [ ] Add frontend bell and unread count.
|
|
- [ ] Initial event sources: assignment, mention, risk alert, overdue item.
|
|
|
|
**Acceptance:**
|
|
- [ ] User sees only their notifications.
|
|
- [ ] Mark read updates count immediately.
|
|
- [ ] Notification links route to product/project/version/entity context.
|
|
|
|
**Verification:**
|
|
- [ ] `pnpm --filter server test -- notification`
|
|
- [ ] `pnpm type-check`
|
|
|
|
### Task 2.7.2: Comments And Mentions
|
|
|
|
**Files:**
|
|
- Modify: `apps/server/prisma/schema.prisma`
|
|
- Create: `apps/server/src/modules/comment/comment.module.ts`
|
|
- Create: `apps/server/src/modules/comment/comment.service.ts`
|
|
- Create: `apps/server/src/modules/comment/comment.controller.ts`
|
|
- Create: `apps/web/components/comment/CommentPanel.tsx`
|
|
- Test: `apps/server/src/modules/comment/comment.service.spec.ts`
|
|
|
|
**Scope:**
|
|
- [ ] Add generic comments for DevTask, TestCase, Bug, Requirement, VersionPlan.
|
|
- [ ] Parse `@memberName` or explicit selected member mentions.
|
|
- [ ] Create notifications for mentions.
|
|
- [ ] Audit comment create/delete.
|
|
|
|
**Acceptance:**
|
|
- [ ] Comment permissions follow entity visibility.
|
|
- [ ] Mentioned user receives notification.
|
|
- [ ] Deleted comment is soft-deleted or audit-visible.
|
|
|
|
**Verification:**
|
|
- [ ] `pnpm --filter server test -- comment`
|
|
- [ ] `pnpm type-check`
|
|
|
|
### Task 2.7.3: Project Membership Governance
|
|
|
|
**Files:**
|
|
- Create: `apps/server/src/modules/project-member/project-member.module.ts`
|
|
- Create: `apps/server/src/modules/project-member/project-member.service.ts`
|
|
- Create: `apps/server/src/modules/project-member/project-member.controller.ts`
|
|
- Modify: `apps/web/app/projects/[id]/page.tsx`
|
|
- Create: `apps/web/components/project/ProjectMemberPanel.tsx`
|
|
- Test: `apps/server/src/modules/project-member/project-member.service.spec.ts`
|
|
|
|
**Scope:**
|
|
- [ ] Manage project roles: Owner/Admin/Member/Viewer.
|
|
- [ ] Prevent last Owner removal.
|
|
- [ ] Sync version member visibility with project membership.
|
|
- [ ] Audit role changes.
|
|
|
|
**Acceptance:**
|
|
- [ ] Viewer cannot mutate project content.
|
|
- [ ] Owner cannot remove the final Owner.
|
|
- [ ] Membership change appears in audit log.
|
|
|
|
**Verification:**
|
|
- [ ] `pnpm --filter server test -- project-member`
|
|
- [ ] `pnpm type-check`
|
|
|
|
### Task 2.7.4: Management Overview Dashboard
|
|
|
|
**Files:**
|
|
- Create: `apps/server/src/modules/management/management.module.ts`
|
|
- Create: `apps/server/src/modules/management/management.service.ts`
|
|
- Create: `apps/server/src/modules/management/management.controller.ts`
|
|
- Create: `apps/web/app/admin/management/page.tsx`
|
|
- Test: `apps/server/src/modules/management/management.service.spec.ts`
|
|
|
|
**Scope:**
|
|
- [ ] Aggregate active versions, overdue work, unresolved blockers, risk levels, workload by member.
|
|
- [ ] Scope by manager permission.
|
|
- [ ] Use relation tables and summaries, not AppData.
|
|
|
|
**Acceptance:**
|
|
- [ ] Manager sees all permitted projects.
|
|
- [ ] Non-manager sees no global dashboard.
|
|
- [ ] Query stays partition/index-aware.
|
|
|
|
**Verification:**
|
|
- [ ] `pnpm --filter server test -- management`
|
|
- [ ] `pnpm perf:check`
|
|
|
|
### Task 2.7.5: Governance Settings And Dictionaries
|
|
|
|
**Files:**
|
|
- Create: `apps/server/src/modules/governance/governance.module.ts`
|
|
- Create: `apps/server/src/modules/governance/governance.service.ts`
|
|
- Create: `apps/server/src/modules/governance/governance.controller.ts`
|
|
- Create: `apps/web/app/admin/governance/page.tsx`
|
|
- Modify: `apps/web/lib/permissions.ts`
|
|
- Test: `apps/server/src/modules/governance/governance.service.spec.ts`
|
|
|
|
**Scope:**
|
|
- [ ] Centralize task category governance.
|
|
- [ ] Centralize requirement type/platform/source dictionaries.
|
|
- [ ] Add change audit and soft-delete safeguards.
|
|
- [ ] Add import/export for dictionaries.
|
|
|
|
**Acceptance:**
|
|
- [ ] Used dictionary item cannot be hard-deleted.
|
|
- [ ] Dictionary change is audited.
|
|
- [ ] Export/import round trip preserves IDs.
|
|
|
|
**Verification:**
|
|
- [ ] `pnpm --filter server test -- governance`
|
|
- [ ] `pnpm type-check`
|
|
|
|
### V2.7 Completion Gate
|
|
|
|
- [ ] Notifications cover assignments, mentions, Xiaobao risk alerts, overdue work.
|
|
- [ ] Project membership is server-enforced.
|
|
- [ ] Management dashboard uses relation tables only.
|
|
- [ ] Governance changes are audited and permission-gated.
|
|
|
|
---
|
|
|
|
## V2.8: Production Hardening + Operations Closure
|
|
|
|
### Task 2.8.1: Backup And Restore Automation
|
|
|
|
**Files:**
|
|
- Create: `scripts/backup-postgres.mjs`
|
|
- Create: `scripts/restore-postgres.mjs`
|
|
- Create: `scripts/backup-server-data.mjs`
|
|
- Modify: `package.json`
|
|
- Modify: `docs/deployment.md`
|
|
|
|
**Scope:**
|
|
- [ ] Backup PostgreSQL volume via `pg_dump`.
|
|
- [ ] Backup server data volume for AI provider config.
|
|
- [ ] Restore into a fresh database.
|
|
- [ ] Document production and local-server flows.
|
|
|
|
**Acceptance:**
|
|
- [ ] Backup command writes timestamped files.
|
|
- [ ] Restore command refuses to overwrite without explicit flag.
|
|
- [ ] Restore procedure is documented.
|
|
|
|
**Verification:**
|
|
- [ ] `pnpm backup:postgres -- --dry-run`
|
|
- [ ] `pnpm restore:postgres -- --dry-run`
|
|
|
|
### Task 2.8.2: Release Smoke Test Suite
|
|
|
|
**Files:**
|
|
- Create: `scripts/smoke-test-release.mjs`
|
|
- Modify: `package.json`
|
|
- Modify: `.github/workflows/deploy.yml` or current deployment workflow
|
|
- Modify: `docs/deployment.md`
|
|
|
|
**Scope:**
|
|
- [ ] Check health/version endpoint.
|
|
- [ ] Check frontend root.
|
|
- [ ] Check authenticated or admin-safe API probes where possible.
|
|
- [ ] Check core API availability: products, V2.2 reads, config/ai.
|
|
|
|
**Acceptance:**
|
|
- [ ] CI deployment fails when smoke test fails.
|
|
- [ ] Smoke output includes failing URL and status.
|
|
|
|
**Verification:**
|
|
- [ ] `pnpm deploy:smoke -- --base-url http://localhost:8080`
|
|
|
|
### Task 2.8.3: Monitoring And Alerting Baseline
|
|
|
|
**Files:**
|
|
- Create: `deploy/monitoring/README.md`
|
|
- Create: `deploy/monitoring/prometheus.yml` if Prometheus is chosen
|
|
- Create: `deploy/monitoring/grafana-dashboard.json` if Grafana is chosen
|
|
- Modify: `docker-compose.prod.yml`
|
|
- Modify: `docs/deployment.md`
|
|
|
|
**Scope:**
|
|
- [ ] Decide minimal monitoring path: logs-first or Prometheus/Grafana.
|
|
- [ ] Track API slow requests, Prisma slow queries, job failures, Xiaobao stale summaries, disk pressure, DB availability.
|
|
- [ ] Add alert routing placeholders without committing secrets.
|
|
|
|
**Acceptance:**
|
|
- [ ] Operator can see service health and slow endpoints.
|
|
- [ ] Alert config is documented and does not contain real credentials.
|
|
|
|
**Verification:**
|
|
- [ ] `pnpm deploy:verify`
|
|
- [ ] `docker compose -f docker-compose.prod.yml config`
|
|
|
|
### Task 2.8.4: Migration Rollback And Runbook
|
|
|
|
**Files:**
|
|
- Create: `docs/runbooks/migration-rollback.md`
|
|
- Create: `docs/runbooks/appdata-retirement.md`
|
|
- Create: `docs/runbooks/xiaobao-background-jobs.md`
|
|
- Modify: `docs/deployment.md`
|
|
|
|
**Scope:**
|
|
- [ ] Document rollback from failed migration.
|
|
- [ ] Document AppData archive restore usage.
|
|
- [ ] Document background job stuck/failed recovery.
|
|
- [ ] Document when to disable worker.
|
|
|
|
**Acceptance:**
|
|
- [ ] Runbook has step-by-step commands.
|
|
- [ ] Runbook names rollback decision points.
|
|
- [ ] Runbook lists data loss risks explicitly.
|
|
|
|
**Verification:**
|
|
- [ ] Manual review by coordinator thread.
|
|
- [ ] `rg -n "TODO|TBD" docs/runbooks docs/deployment.md` returns no placeholder.
|
|
|
|
### Task 2.8.5: Production Readiness Checklist
|
|
|
|
**Files:**
|
|
- Create: `docs/production-readiness.md`
|
|
- Modify: `docs/roadmap.md`
|
|
|
|
**Scope:**
|
|
- [ ] Checklist for backup, restore, smoke tests, monitoring, audit, RBAC, consistency, performance.
|
|
- [ ] Include “go/no-go” criteria.
|
|
- [ ] Include post-release verification.
|
|
|
|
**Acceptance:**
|
|
- [ ] Release cannot be called stable until checklist passes.
|
|
- [ ] Roadmap can mark V2.8 complete only after checklist evidence exists.
|
|
|
|
**Verification:**
|
|
- [ ] `pnpm deploy:verify`
|
|
- [ ] `pnpm perf:check`
|
|
- [ ] `pnpm consistency:check`
|
|
- [ ] `pnpm deploy:smoke -- --base-url <target>`
|
|
|
|
### V2.8 Completion Gate
|
|
|
|
- [ ] Backup and restore dry runs pass.
|
|
- [ ] Smoke tests run in CI/CD.
|
|
- [ ] Monitoring baseline is documented and deployable.
|
|
- [ ] Rollback runbooks exist and have no placeholders.
|
|
- [ ] Production readiness checklist has evidence for every item.
|
|
|
|
---
|
|
|
|
## Integration Order
|
|
|
|
1. Merge V2.5 first because it owns shared AppData retirement, RBAC, audit, and consistency contracts.
|
|
2. Merge V2.6 second after reviewing its background job runtime and Xiaobao worker hooks against V2.5 permission/audit contracts.
|
|
3. Merge V2.7 third after notification and governance behavior is checked against V2.5 RBAC and V2.6 Xiaobao alert hooks.
|
|
4. Merge V2.8 last so production smoke tests, runbooks, monitoring, backup/restore, and readiness checks validate the integrated result.
|
|
5. Final coordinator pass updates `docs/roadmap.md` completion states, runs centralized validation, then pushes to `master` only after explicit user approval.
|
|
|
|
## Confirmed Execution Decisions
|
|
|
|
- [x] Four streams run in separate Codex threads and separate worktrees.
|
|
- [x] All four streams may start implementation after their implementation plan is written.
|
|
- [x] Each stream commits locally after self-contained verified work.
|
|
- [x] Streams do not push.
|
|
- [x] Coordinator merges completed streams in order: V2.5 -> V2.6 -> V2.7 -> V2.8.
|
|
- [x] Coordinator runs unified validation after all four streams are merged.
|
|
- [x] Coordinator pushes `master` only when the user explicitly asks.
|