Homepage - Technical Map

Tổng quan kỹ thuật

homepage là một route module rất mỏng trong diva-admin. Nó chỉ gồm:

• module.ts để khai báo route, config và navigation,
• Layout.tsx để reuse MainLayout,
• Homepage.tsx để render banner,
• styles.scss cho layout của banner,
• i18n/vi.ts cho route label,
• types.ts chứa constant route/module id.

Không có GraphQL file, không có action/event/scheduler backend, và không có integration DB riêng cho module này.

Cấu trúc file

File	Vai trò
diva-admin/src/modules/homepage/module.ts	Khai báo route /h, child route /h/homepage, config permission và navigation
diva-admin/src/modules/homepage/Layout.tsx	Re-export MainLayout và load stylesheet
diva-admin/src/modules/homepage/pages/Homepage.tsx	Render banner tĩnh
diva-admin/src/modules/homepage/styles.scss	Canh giữa banner, giới hạn max width
diva-admin/src/modules/homepage/i18n/vi.ts	Label route Trang chủ
diva-admin/src/modules/homepage/types.ts	Constant MODULE_HOMEPAGE = "h", ROUTE_HOMEPAGE = "/h/homepage"

Route tree

/ 
└─ redirect -> /h/homepage
   └─ /h
      ├─ redirect -> /h/homepage
      └─ /h/homepage
         ├─ name: /h/homepage
         ├─ props: true
         └─ component: Homepage

Nguồn:

• diva-admin/src/router/routes.ts:32-50
• diva-admin/src/router/pos/routes.ts:29-41
• diva-admin/src/modules/homepage/module.ts:7-37

Flow render

router resolve
  -> match route name /h/homepage
  -> load Layout
  -> Layout export MainLayout + styles.scss
  -> render Homepage page
  -> show <img src="/img/homepage-banner@2x.png">

Chi tiết:

• Layout.tsx không thêm business logic nào, chỉ import MainLayout và styles.scss.
• Homepage.tsx là functional page cực mỏng, render một div.homepage chứa img.homepage__banner.
• Asset banner nằm ở diva-admin/public/img/homepage-banner@2x.png, được gọi bằng absolute path /img/homepage-banner@2x.png.

Permission và route guard

5.1 Permission model thực tế

Route config của homepage:

• permissions: []
• moduleId: "homepage"

Guard không chặn homepage theo permission chuẩn. Thay vào đó, cả hai guard đều có nhánh allow cứng cho homepage:

• diva-admin/src/router/guard.ts:67-79
• diva-admin/src/router/pos/guard.ts:67-77

5.2 Visibility ở sidebar

LeftSidebar cho phép hiển thị menu homepage qua nhánh đặc biệt:

• nav.moduleId === "homepage" được return true
• do đó menu "Trang chủ" luôn xuất hiện nếu shell đang dùng bộ navigation hiện tại

Nguồn: diva-admin/src/components/layout/main/LeftSidebar.tsx:117-137

Tích hợp liên quan

Thành phần	Tích hợp
configureUseAuth.ts	Redirect sau login về /h/homepage nếu profile có roles hoặc là CRM platform
MainHeader.tsx	Click logo/header quay về /h/homepage
routes.ts và pos/routes.ts	Root / redirect sang /h/homepage
i18n/messages/vi.ts	Merge route label Trang chủ vào dictionary chung
public/icons.svg	Icon homepage và homepage-active dùng cho navigation

Dữ liệu và GraphQL

Module này không có:

• query/mutation GraphQL riêng,
• Hasura action/event/scheduler riêng,
• bảng DB riêng,
• state store riêng.

Nghĩa là mọi thay đổi của homepage hiện tại đều là thay đổi FE tĩnh.

Rủi ro / Findings kỹ thuật

F-01. Homepage bypass permission model chuẩn

homepage được allow bằng nhánh cứng trong cả hai route guard thay vì dựa hoàn toàn vào permissions/modules của role. Điều này làm landing page luôn vào được, nhưng cũng tạo ngoại lệ lâu dài trong hệ thống phân quyền. Nguồn: diva-admin/src/router/guard.ts:67-79, diva-admin/src/router/pos/guard.ts:67-77.

F-02. Route path bị hardcode ở nhiều nơi

/h/homepage xuất hiện ở module, auth redirect, root redirect và click logo/header. Nếu đổi route sau này sẽ phải sửa nhiều điểm thủ công, dễ lệch nhau. Nguồn: diva-admin/src/modules/homepage/types.ts:1-2, diva-admin/src/router/routes.ts:34-39, diva-admin/src/modules/auth/compositions/configureUseAuth.ts:214-226, diva-admin/src/components/layout/main/MainHeader.tsx:96-118.

F-03. Banner image thiếu alt

Homepage.tsx render img nhưng không có thuộc tính alt. Với một landing page chỉ có một hình tĩnh, đây là lỗi accessibility rõ ràng và làm giảm chất lượng semantic của trang. Nguồn: diva-admin/src/modules/homepage/pages/Homepage.tsx:7-9.

F-04. props: true đang dư thừa

Child route /h/homepage khai báo props: true nhưng component Homepage không nhận prop nào. Đây không phải bug runtime ngay, nhưng là cấu hình thừa và gây hiểu nhầm rằng page phụ thuộc params. Nguồn: diva-admin/src/modules/homepage/module.ts:14-19 và diva-admin/src/modules/homepage/pages/Homepage.tsx:3-10.

F-05. Style phụ thuộc vào Layout

styles.scss chỉ được import qua Layout.tsx. Nếu Homepage bị tái sử dụng ngoài route hiện tại, style banner sẽ mất. Đây là rủi ro thiết kế nhỏ nhưng có thật trong cấu trúc hiện tại. Nguồn: diva-admin/src/modules/homepage/Layout.tsx:1-4, diva-admin/src/modules/homepage/styles.scss:1-8.

Kết luận kỹ thuật

Homepage là một module tĩnh, ít phụ thuộc, dễ bảo trì ở mức hiện tại. Điểm cần lưu ý không nằm ở business logic, mà nằm ở các ngoại lệ về permission, hardcode route và accessibility của banner.