117 lines
8.1 KiB
Markdown
117 lines
8.1 KiB
Markdown
# 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`](file:///c:/Users/parsa/Desktop/work/caninairan/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`](file:///c:/Users/parsa/Desktop/work/caninairan/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.
|