50 lines
4.6 KiB
Markdown
50 lines
4.6 KiB
Markdown
# Phase 3.2 / 3.3 — Implementation Readiness & Architectural Finalization Report
|
|
|
|
- **Review Phase**: Phase 3.3 — Architectural Finalization & Backlog Revision
|
|
- **Repository HEAD**: `715873b2ecc3a72ba974bb2a2be87c5ba82bd4e7`
|
|
- **Execution Mode**: `REVIEW_ONLY_NO_CODE_MUTATION`
|
|
- **Canonical Task Backlog**: [`docs/audit/MASTER-TASK-BACKLOG.md`](file:///c:/Users/parsa/Desktop/work/caninairan/docs/audit/MASTER-TASK-BACKLOG.md)
|
|
- **ADR Created**: [`docs/audit/ADR-AUTH-001.md`](file:///c:/Users/parsa/Desktop/work/caninairan/docs/audit/ADR-AUTH-001.md)
|
|
- **Route Map Created**: [`docs/audit/frontend-route-map.md`](file:///c:/Users/parsa/Desktop/work/caninairan/docs/audit/frontend-route-map.md)
|
|
|
|
---
|
|
|
|
## 1. Executive Summary & Architecture Decisions
|
|
|
|
All 5 finalized architectural decisions requested by product direction have been incorporated into the planning artifacts:
|
|
|
|
1. **Architecture Split (DECISION-003 Finalized)**:
|
|
- **Storefront (Customer-facing)**: Next.js framework for server-side rendering (SSR), dynamic open-graph metadata, and maximum SEO performance.
|
|
- **Admin Panel**: Pure, isolated React SPA. SEO is completely irrelevant; absolute priority is **Security**, **Performance**, **Lazy Loading**, and **Type Safety**.
|
|
2. **`TASK-FE-001` Refinement (Admin Panel SPA Router)**:
|
|
- Target: Admin Panel React SPA using `react-router-dom` (`createBrowserRouter`) strictly for route-level lazy loading (`lazy()`), chunk splitting, and strict Type Safety. SEO considerations removed.
|
|
3. **`TASK-AUTH-001` Refinement (Admin Panel Dual-Token Auth)**:
|
|
- Implements Dual-Token Architecture (In-memory Access Token + HttpOnly Refresh Cookie) specifically for the standalone Admin Panel per [`ADR-AUTH-001`](file:///c:/Users/parsa/Desktop/work/caninairan/docs/audit/ADR-AUTH-001.md).
|
|
4. **`TASK-SEC-001` Refinement (Dual Startup Secrets)**:
|
|
- Enforces mandatory bootstrap validation in `main.ts` for TWO secrets: `JWT_ACCESS_SECRET` and `JWT_REFRESH_SECRET` (each >= 32 characters/bytes). Fail fast (`process.exit(1)`) if either secret is missing or insecure.
|
|
5. **`TASK-FIN-001` Refinement (`Prisma.Decimal` Payload Serialization)**:
|
|
- Enforces global `DecimalInterceptor` (or DTO `Transform` decorators) converting all `Prisma.Decimal` instances in API response payloads to exact Strings (e.g. `"64.98"`) or precise Numbers before sending to clients, preventing client-side parsing crashes. Corrected total calculation example: `19.99 * 3 + 5.01 = 64.98`.
|
|
|
|
---
|
|
|
|
## 2. Updated Task Specifications Overview
|
|
|
|
| Task ID | Implementation Contract Summary | Blocked Status | Architectural Artifact |
|
|
|---|---|---|---|
|
|
| `TASK-SEC-001` | Mandatory dual secret validation (`JWT_ACCESS_SECRET` & `JWT_REFRESH_SECRET` >= 32 chars) on `main.ts` bootstrap | Unblocked | Backend Bootstrap Contract |
|
|
| `TASK-SEC-002` | `crypto.randomInt` CSPRNG OTP generation & `IOtpDeliveryService` DI port/adapter | Unblocked | AuthService Design |
|
|
| `TASK-SEC-003` | `@Roles('Admin')` decorator & `RolesGuard` implementation protecting `/api/settings` | Unblocked | NestJS RBAC Contract |
|
|
| `TASK-FIN-001` | Decimal math (`19.99 * 3 + 5.01 = 64.98`), single batch query, & global `DecimalInterceptor` payload serialization | Unblocked | Orders Service & Interceptor |
|
|
| `TASK-BUILD-001` | `seed.ts` `slug` property, `metrics.controller.ts` type-only import, & spec return shape alignment | Unblocked | TypeScript & Spec Suite |
|
|
| `TASK-AUTH-001` | Dual-token auth contract for standalone Admin Panel (In-memory Access Token + HttpOnly Refresh Cookie) | `BLOCKED_BY_DEPENDENCY` (`TASK-SEC-002`) | [`ADR-AUTH-001.md`](file:///c:/Users/parsa/Desktop/work/caninairan/docs/audit/ADR-AUTH-001.md) |
|
|
| `TASK-FE-001` | Admin Panel React SPA routing (`createBrowserRouter`), lazy-loaded module chunks & type safety | Unblocked | [`frontend-route-map.md`](file:///c:/Users/parsa/Desktop/work/caninairan/docs/audit/frontend-route-map.md) |
|
|
| `TASK-DEVOPS-001` | Multi-job Gitea/GitHub Actions CI workflow (`.github/workflows/ci.yml`) with lint, typecheck, build, test | `BLOCKED_BY_DEPENDENCY` (`TASK-BUILD-001`) | DevOps Workflow Contract |
|
|
| `TASK-DOC-001` | Non-listener CLI script `generate-openapi.ts` exporting `swagger.yml` with `git diff --exit-code` CI check | Unblocked | OpenAPI CLI Generator |
|
|
| `TASK-VERIFY-001` | 7-Domain behavior-oriented E2E verification matrix covering 100% of 14 verified audit findings | `BLOCKED_BY_DEPENDENCY` (`TASK-AUTH-001`, `TASK-SEC-003`, `TASK-FIN-001`) | Verification Matrix |
|
|
|
|
---
|
|
|
|
## 3. Final Readiness Statement
|
|
|
|
The Master Task Backlog and all supporting audit artifacts in `docs/audit/` have been updated and are **100% READY FOR HUMAN APPROVAL**.
|