parsa/canina
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
canina/docs/audit/phase3.2-change-log.md
parsaaghayi f4cdca4ed1
Some checks failed
Deploy Canina / deploy (push) Failing after 29s
Details
docs(audit): finalize Phase 3 Master Task Backlog and audit planning artifacts
2026-08-06 20:54:44 +03:30

8.1 KiB
Raw Permalink Blame History

Phase 3.2 — Implementation Readiness Change Log

  • Audit Phase: Phase 3.2 — Implementation Readiness Review
  • Repository HEAD: 715873b2ecc3a72ba974bb2a2be87c5ba82bd4e7

Comprehensive Change Log

1. TASK-SEC-001

  • Task ID: TASK-SEC-001
  • Previous Contract: "Throw explicit startup error if process.env.JWT_SECRET is undefined... cross-env JWT_SECRET= npm run start:dev".
  • Revised Contract: Specified NestJS application bootstrap validation in backend/src/main.ts. If process.env.JWT_SECRET is missing, empty, or length < 32 characters (minimum 32 bytes ASCII entropy), bootstrap() logs a fatal error and throws an exception before calling app.listen(), resulting in process exit code 1.
  • Reason: Standardized application bootstrap failure architecture without embedding process termination inside child module/strategy logic.
  • Repository Evidence: backend/src/main.ts lines 8-40 (bootstrap() function).
  • Architectural Decision: Fatal startup configuration barrier in main.ts.
  • Implementation Impact: Prevents backend from opening port 3000 when secret key is absent or insecure.

2. TASK-SEC-002

  • Task ID: TASK-SEC-002
  • Previous Contract: Replace Math.random() with crypto.randomInt and sanitize response payload.
  • Revised Contract: Defined explicit interface abstraction IOtpDeliveryService / OtpDeliveryService symbol in NestJS dependency injection. Created ConsoleOtpDeliveryService for dev/test environments (logging OTP, zero disclosure in HTTP response body) and SmsGatewayOtpDeliveryService adapter for production SMS dispatch.
  • Reason: Separated OTP code generation from OTP code delivery mechanism to support automated testing without real SMS gateways.
  • Repository Evidence: backend/src/auth/auth.service.ts line 20.
  • Architectural Decision: Dependency injection port/adapter pattern for OTP delivery.
  • Implementation Impact: Enables offline, hermetic testing of OTP flows without external SMS gateway dependencies.

3. TASK-SEC-003

  • Task ID: TASK-SEC-003
  • Previous Contract: Apply @UseGuards(JwtAuthGuard, RolesGuard) and @Roles('Admin').
  • Revised Contract: Confirmed RolesGuard and @Roles decorator do not currently exist in backend/src/. Documented exact creation contract for @Roles decorator (SetMetadata('roles', roles)) and RolesGuard (Reflector metadata lookup against req.user.role).
  • Reason: Explicitly documented missing decorator and guard implementations required before annotating SettingsController.
  • Repository Evidence: backend/src/settings/settings.controller.ts line 1; absence of roles.guard.ts in backend/src/common/.
  • Architectural Decision: Custom NestJS RBAC guard and decorator implementation.
  • Implementation Impact: Unblocks RBAC authorization enforcement on administrative endpoints.

4. TASK-FIN-001

  • Task ID: TASK-FIN-001
  • Previous Contract: Contained math error in example (19.99 * 3 + 5.01 = 65.00).
  • Revised Contract: Corrected example to 19.99 * 3 + 5.01 = 64.98. Specified exact Prisma Decimal API (@prisma/client/runtime/library). Documented handling for missing product IDs (404), duplicate product IDs (400), and invalid quantities (quantity <= 0).
  • Reason: Corrected arithmetic error and specified exact DTO validation rules.
  • Repository Evidence: backend/src/orders/orders.service.ts lines 10-44, backend/prisma/schema.prisma lines 64-90.
  • Architectural Decision: Server-side price source of truth with batched Prisma Decimal calculation.
  • Implementation Impact: Ensures 100% financial calculation accuracy and single query checkout execution.

5. TASK-BUILD-001

  • Task ID: TASK-BUILD-001
  • Previous Contract: General build and test assertions.
  • Revised Contract: Segregated acceptance criteria into TypeScript source compilation (npx tsc --noEmit), seed script type correctness (seed.ts), decorator metadata import correctness (metrics.controller.ts), and Jest spec execution (npm run test) without deleting or weakening existing assertions.
  • Reason: Defined clean quality boundaries and prevented spec weakening.
  • Repository Evidence: backend/prisma/seed.ts, backend/src/common/metrics.controller.ts, spec files.
  • Architectural Decision: Strict build quality gate contract.
  • Implementation Impact: Restores clean tsc compilation and unblocks CI workflow.

6. TASK-AUTH-001

  • Task ID: TASK-AUTH-001
  • Previous Contract: In-memory token storage recommendation.
  • Revised Contract: Created docs/audit/ADR-AUTH-001.md establishing a Dual-Token Hybrid Architecture (HttpOnly Refresh Cookie + In-Memory Access Token) with Bearer header fallback. Updated TASK-AUTH-001 to reference ADR-AUTH-001.md.
  • Reason: Solves both XSS token exfiltration (storing access token in memory) and page refresh session loss (background refresh via HttpOnly cookie).
  • Repository Evidence: src/services/authService.ts, src/services/api.ts.
  • Architectural Decision: Dual-Token Hybrid Authentication Strategy.
  • Implementation Impact: Provides enterprise-grade security and seamless storefront UX.

7. TASK-FE-001

  • Task ID: TASK-FE-001
  • Previous Contract: General React Router recommendation.
  • Revised Contract: Created docs/audit/frontend-route-map.md mapping all 12 storefront routes from src/App.tsx. Detailed <BrowserRouter> setup, navigation callbacks via useNavigate(), and explicit TypeScript interfaces for subViews.
  • Reason: Root-cause analysis proved manual useState("home") view switching fails on direct URL page reloads.
  • Repository Evidence: src/App.tsx lines 54-150.
  • Architectural Decision: Declarative client-side routing with react-router-dom.
  • Implementation Impact: Enables direct deep-linking, browser history navigation, and zero explicit any state types.

8. TASK-DEVOPS-001

  • Task ID: TASK-DEVOPS-001
  • Previous Contract: General CI workflow creation.
  • Revised Contract: Confirmed remote repository hosting (https://git.parsaaghayi.ir/parsa/canino.git). Specified Gitea Actions / GitHub Actions runner compatible workflow (.github/workflows/ci.yml). Added explicit npm run lint step to frontend job.
  • Reason: Aligned CI setup with self-hosted git runner compatibility and explicit linting requirements.
  • Repository Evidence: git remote -v.
  • Architectural Decision: Declarative multi-job CI workflow.
  • Implementation Impact: Automates linting, typechecking, and test quality gates on pull requests.

9. TASK-DOC-001

  • Task ID: TASK-DOC-001
  • Previous Contract: Reconcile static swagger.yml.
  • Revised Contract: Specified a non-listener CLI script backend/scripts/generate-openapi.ts instantiating NestJS application without calling app.listen(). Configured npm run docs:generate && git diff --exit-code swagger.yml CI validation.
  • Reason: Prevents starting a live HTTP server during documentation generation.
  • Repository Evidence: backend/src/main.ts lines 29-37.
  • Architectural Decision: Non-listener OpenAPI document builder CLI tool.
  • Implementation Impact: Keeps swagger.yml 100% in sync with NestJS controller decorators automatically.

10. TASK-VERIFY-001

  • Task ID: TASK-VERIFY-001
  • Previous Contract: Subset of 8 findings.
  • Revised Contract: Reworked TASK-VERIFY-001 to cover ALL 14 verified findings across 7 distinct categories (Unit, Integration/E2E, Startup Smoke, Frontend, Build/Type/Lint, CI, Documentation/OpenAPI).
  • Reason: Ensured 100% verification coverage for every verified finding in the repository.
  • Repository Evidence: docs/audit/20-verified-findings-index.json (all 14 findings).
  • Architectural Decision: 7-Domain Automated Verification Matrix.
  • Implementation Impact: Guarantees post-remediation quality gate validation.