# App Foundation Status

## 1. Mục đích

Tài liệu này đánh giá nền tảng kỹ thuật của LDA trước khi QA/release. Nội dung tập trung vào: stack, cấu trúc source, khả năng chạy local, rủi ro nền tảng và điểm cần hoàn thiện.

**Ghi chú:** App Foundation Status không thay thế test execution. Nó cho biết hệ thống có nền đủ tốt để bắt đầu QA hay chưa.

## 2. Tổng quan hệ thống

| Thành phần | Source | Stack | Vai trò |
|---|---|---|---|
| Admin/CDP Frontend | `core-ops-frontend-nextjs-main` | Next.js 15.4, React 19, Tailwind 4, pnpm 9 | Trang vận hành/admin, catalog, coupon, stocktake, workflow nội bộ |
| Website Public | `website-v2-master` | Next.js 16.2, React 19.2, Tailwind 4.2, Zustand 5, OpenNext Cloudflare | Website bán hàng public |
| Backend API | `website-backend-go-main` | Go 1.25, Gin, GORM, PostgreSQL, Clean Architecture + CQRS | API dữ liệu cho website/admin |

## 3. Website Public Foundation

| Hạng mục | Trạng thái | Ghi chú |
|---|---|---|
| App Router | Present | `src/app` có homepage, product, collection, cart, checkout, static pages |
| Ecommerce Routes | Present | Có `/`, `/products/[slug]`, `/collections/[slug]`, `/gio-hang`, `/thanh-toan` |
| Design System | Present | Có docs design-system, tokens, colors, typography, spacing |
| State Management | Present | Dùng Zustand |
| Styling | Present | Tailwind CSS 4 + CSS custom properties |
| SEO | Present | Có robots, sitemap, JSON-LD structure/docs |
| Deployment | Present | Cloudflare Workers/OpenNext scripts |
| Risk | Medium | Node engine yêu cầu >= 24; cần đúng version khi build |

**Ghi chú:** Website public có cấu trúc đủ tốt để QA, nhưng release confidence chỉ tăng sau khi build, smoke và browser test pass.

## 4. Backend Foundation

| Hạng mục | Trạng thái | Ghi chú |
|---|---|---|
| Architecture | Present | Clean Architecture + CQRS |
| HTTP Router | Present | Gin, routes theo module |
| Database | Present | PostgreSQL, migrations, docker compose |
| ORM | Present | GORM |
| Catalog Source | Present | ERP readonly + web-v2 enrichment overlay |
| Module Boundaries | Present | catalog, collection, homepage, productext, seo, user, blog, promotions |
| Health Endpoint | Present | `/ping`, `/version` |
| Admin Auth | Present in routes | Admin middleware gắn vào route mutation/admin group |
| Cache Policy | Documented | Navigation, homepage, sitemap, redirect có TTL đề xuất |
| Risk | High | Nếu thiếu ERP DSN, catalog route có thể không test đủ |

**Ghi chú:** Backend có nền module rõ, nhưng cần xác nhận migration, seed data và ERP dependency trước khi QA đầy đủ.

## 5. Admin/CDP Foundation

| Hạng mục | Trạng thái | Ghi chú |
|---|---|---|
| App Shell | Present | Sidebar, header, theme, auth providers |
| UI/Form libs | Present | react-hook-form, zod, Radix, lucide, charts |
| Business Modules | Present | Stocktake, coupon/voucher, catalog specs, integrations, warranty, etc. |
| Testing Docs | Present | Có `docs/testing/NV_TEST_GUIDE.md`, `e2e-per-ticket-report.md` |
| Mock/Fallback | Present | Một số workflow dùng mock/fallback |
| Risk | High | Existing e2e report ghi nhận role/state gating gaps trong stocktake |

**Ghi chú:** Admin/CDP có nhiều nghiệp vụ phức tạp. QA cần tách rõ test bằng mock và test integration thật.

## 6. Khả năng chạy local

| Thành phần | Lệnh chính | Điều kiện | Ghi chú |
|---|---|---|---|
| Website | `pnpm install`, `pnpm dev`, `pnpm build` | Node >= 24, pnpm 10.30.1 | Port mặc định 3000 |
| Admin | `pnpm install`, `pnpm dev`, `pnpm build` | pnpm 9.14.3 | Dev script port 3300 |
| Backend | `go run . migrate up`, `go run main.go` | Go 1.25, PostgreSQL | Port có thể 3000/GIN_PORT |
| DB local | `docker compose up -d` | Docker | Postgres `localhost:15432`, Redis `localhost:16379` |

## 7. Readiness Score

| Area | Score | Lý do |
|---|---:|---|
| Source organization | 8/10 | Cấu trúc source rõ, module tách tương đối tốt |
| Documentation | 7/10 | Có README/docs, nhưng QA docs cần bổ sung execution result |
| Local setup clarity | 7/10 | README có hướng dẫn, nhưng cần thống nhất port/env |
| Test readiness | 6/10 | Có stocktake docs, thiếu automated smoke/API regression đầy đủ |
| Release confidence | 4/10 | Chưa chạy build/test thật |
| Security confidence | 5/10 | Có admin middleware, nhưng role gating stocktake từng fail |

## 8. Rủi ro nền tảng

| Risk | Severity | Ảnh hưởng | Đề xuất |
|---|---|---|---|
| Node version mismatch | Medium | Website build fail | Chuẩn hóa Node >= 24 |
| Port conflict | Medium | Không chạy cùng backend/website | Quy định `GIN_PORT` hoặc đổi web port |
| ERP dependency missing | High | Không test đủ catalog | Có ERP staging DSN hoặc seed/mock rõ |
| Role gating gaps | High | User sai quyền thao tác nghiệp vụ | Test/fix trước release |
| Mock vs real confusion | Medium | QA pass giả | Ghi rõ môi trường test |
| Missing CI gate | Medium | Regression dễ lọt | Thêm build/lint/type/go test/API smoke |

## 9. Việc cần làm để đủ nền QA

- Chuẩn hóa hướng dẫn setup local cho 3 source.
- Tạo `.env.example` rõ cho staging/local.
- Thống nhất port chạy đồng thời.
- Chuẩn bị seed data cho product, collection, voucher, SEO, stocktake.
- Thêm automated smoke test cho website routes chính.
- Thêm API contract tests cho catalog/homepage/navigation/SEO.
- Fix hoặc retest role gating trong stocktake.
- Cập nhật CI gate trước release.

## 10. Kết luận

Nền tảng source đủ để bắt đầu QA có kiểm soát, nhưng chưa đủ để kết luận release. Điều kiện cần tiếp theo là chạy build, start app, chạy smoke/API/browser tests và cập nhật QA Report.