npm package: @ospgroupvn/fe-osp-shared
Description: **Shared Frontend Package for Multi-Repo Architecture**
Latest version: 1.0.0

# fe-osp-shared

**Shared Frontend Package for Multi-Repo Architecture**

---

## Tổng quan

`fe-osp-shared` là package React/TypeScript dùng chung cho các frontend repo trong hệ sinh thái OSP. Đây là nền tảng trung tâm giúp đồng bộ hóa UI, logic, xác thực, theme, i18n, networking, config, test... giữa các repo FE, tối ưu cho mô hình multi-repo hiện đại.

### Tính năng nổi bật & Lợi ích cho multi-repo

| **Phần**                         | **Ý nghĩa & lợi ích cho multi-repo**                                                                                  | **Cụ thể sẽ làm**                                                                                                                                                                                                                                                                                      | **Package + Note**                                                                                                                                                                                                 |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Auth (Xác thực & Phân quyền)** | Gom logic xác thực & phân quyền, tránh code lại nhiều repo, đảm bảo quản lý token & quyền thống nhất                  | - `authBaseSlice`, `authState`<br>- Hook `useAuth`, `hasPermission`<br>- `tokenManager.ts` quản lý token<br>- `PermissionWrapper` ẩn/hiện UI theo quyền<br>- `AuthService` login/logout/refresh                                                                                                        | **Package**: redux toolkit, axios<br>**Note**: Đảm bảo flow refresh token; Repo con cần wrap `<AppProvider>`                                                                                                       |
| **Theme (UI & Appearance)**      | Đồng bộ giao diện toàn hệ thống (Light/Dark, Ant Design + Tailwind). Đảm bảo mọi repo có UI nhất quán, đồng bộ token. | **Ant Design**:<br>- `themeBaseSlice`<br>- `AppThemeProvider` wrap toàn app<br>- `ThemeAdapter` config token<br>- `theme.config.ts`, `themeUtils.ts`<br>**Tailwind**:<br>- Đồng bộ tokens trong `themeSlice`<br>- Repo con mở rộng config qua `presets` trong `tailwind.config.ts` để import từ shared | **Package**: @ant-design/cssinjs, tailwindcss (cài tại repo con)<br>**Note**: Không cài `tailwindcss/vite` trong shared. Mỗi repo Tailwind cần `tailwind.config.ts` riêng; dùng `presets` để gộp config từ shared. |
| **Config & Environment**         | Quản lý cấu hình theo môi trường (local/remote). Dễ scale khi nhiều repo cần cùng 1 chuẩn.                            | - `configBaseSlice` lưu config<br>- Hook `useConfig`<br>- `loadConfigFromEnv` (.env)<br>- `loadConfigFromRemote` (BE endpoint)                                                                                                                                                                         | **Package**: dotenv (Vite built-in)<br>**Note**: Quy tắc load `.env` → `.env.[mode]` → `.env.local` (ưu tiên cao nhất)                                                                                             |
| **Common UI**                    | Gom component UI tái sử dụng, giảm lặp code, đồng bộ UX                                                               | - Component: `Loading`, `EmptyState`, `ErrorPage`, `NotFound`<br>- `PermissionWrapper` (liên quan Auth)                                                                                                                                                                                                | **Package**: Ant Design<br>**Note**: Wrap lại Ant Design để đồng bộ style                                                                                                                                          |
| **i18n (Đa ngôn ngữ)**           | Chuẩn hóa đa ngôn ngữ, dễ scale thị trường & repo                                                                     | - Tích hợp `react-i18next`<br>- File dịch: `locales/en.json`, `vi.json`…<br>- Hook `useLanguage`<br>- Component `LanguageSelector`                                                                                                                                                                     | **Package**: react-i18next, i18next-browser-languagedetector<br>**Note**: Repo con chỉ cần import hook & cac file dịch phải dat đung rule                                                                          |
| **Networking (API & Services)**  | Gom chuẩn gọi API, tránh mỗi repo tự xử lý. Interceptor token thống nhất.                                             | - `apiService` (axios + interceptor)<br>- `apiCall<T>` với chuẩn `BaseResponse<T>`<br>- `notiService` (wrap antd notification)<br>- Hook `onRequest/onResponse/onError`                                                                                                                                | **Package**: axios<br>**Note**: Interceptor gắn token tự động; repo con có thể override                                                                                                                            |
| **Utils Functions**              | Gom các hàm xử lý chung, tránh viết lại.                                                                              | - `dateUtils`, `numberUtils`, `stringUtils`, `objectUtils`, `validateUtils`, `themeUtils`                                                                                                                                                                                                              | **Package**: dayjs<br>**Note**: Chỉ import hàm cần dùng để tránh bundle lớn                                                                                                                                        |
| **Testing Utils**                | Chuẩn hóa test, dễ mock API & render component đồng bộ                                                                | - `renderWithProviders()`<br>- MSW mock API<br>- Setup Jest + RTL                                                                                                                                                                                                                                      | **Package**: jest, @testing-library/react, @testing-library/jest-dom, jest-environment-jsdom, ts-jest, msw<br>**Note**: Đảm bảo test pass cho slice, hooks, services, utils                                        |

---

## Cấu trúc thư mục

```
fe-osp-shared/
├── src/
│   ├── components/         # Các component UI dùng chung
│   ├── hooks/              # Custom hooks
│   ├── services/           # Service API, notification, storage...
│   ├── store/              # Redux store, slice, typed hooks
│   ├── utils/              # Helper function, xử lý dữ liệu
│   ├── config/             # Cấu hình theme, đa ngôn ngữ
│   ├── constants/          # Hằng số dùng chung
│   ├── types/              # TypeScript types
│   └── locales/            # File ngôn ngữ
├── package.json
├── README.md
└── ...
```

---

## Ứng dụng thực tế

- **Tái sử dụng UI/logic**: Các repo FE chỉ cần cài package này là có thể dùng lại toàn bộ component, hooks, store, service chuẩn hóa.
- **Đồng bộ giao diện**: Theme, ngôn ngữ, notification, error page... nhất quán trên mọi repo.
- **Dễ bảo trì**: Sửa đổi, nâng cấp ở shared repo sẽ tự động áp dụng cho mọi consumer repo.
- **Tối ưu test**: Đã có sẵn unit test cho mọi thành phần, dễ dàng CI/CD.

---

## Đóng góp & phát triển

- Fork, PR, issue tại repo này.
- Đảm bảo test pass trước khi merge.
- Định hướng: mở rộng thêm component, service, tích hợp CI/CD, publish npm.

---

## License

MIT