Bản đồ Điều hướng Dự án (Project Navigation Map)
Bundle OKF 0.1 · 74 conceitos · Hieu-Le-Hoang/Project-Tracker
Open source Repository Open in the app JSON README (API)
About
# Bản đồ Điều hướng Dự án (Project Navigation Map)
Bản đồ chỉ đường cho toàn bộ dự án **Project Tracker**. Cập nhật 2026-08-11 (commit `fbf7589`).
- [README.md](./README.md) — Trang bìa: mô tả, trạng thái, quickstart, điều hướng
- [decisions/README.md](./decisions/README.md) — Sổ quyết định (Decision Register)
- [log.md](./log.md) — Nhật ký thay đổi theo ngày
---
## Tài liệu
- 📁 [decisions](./decisions/) — **ADR: bất biến, append-only.** Vì sao chọn cách này
- [README.md](./decisions/README.md) — Sổ quyết định + cách thêm/đổi ADR
- [0000-adr-template.md](./decisions/0000-adr-template.md) — Mẫu ADR
- [0001-record-architecture-decisions.md](./decisions/0001-record-architecture-decisions.md) — Ghi quyết định dưới dạng ADR
- [0002-feature-based-folder-architecture.md](./decisions/0002-feature-based-folder-architecture.md) — Cấu trúc feature-based dưới `src/`
- [0003-auth-via-msal-azure-ad.md](./decisions/0003-auth-via-msal-azure-ad.md) — Xác thực MSAL Azure AD
- [0004-tailwind-css-qu
Details
- Kind
- OKF bundles
- Topic
- Maps, weather & travel
- Publisher
- hieu-le-hoang
- Origin
- okf_github
- Category
- dados
- Version
- 0.1
- Last push
- 2026-08-11T04:45:30Z
- Repository state
- ativo
- Language
- TypeScript
- Added
- 2026-09-09 19:04:11
- Updated
- 2026-09-09 19:04:11
- Origin id
Hieu-Le-Hoang/Project-Tracker:index.md
README
# Project Tracker
Dashboard quản lý dự án & công việc nội bộ cho team IT WeCare. Kết nối trực tiếp Dataverse
(Power Platform) để quản lý projects, tasks, tech resources và sinh weekly report bằng AI.
**Stack**: React 19 · Vite 6 · TypeScript 5.8 · MSAL Azure AD · Dataverse Web API v9.2
---
## Trạng thái
Đang chạy ổn định, tự động deploy lên GitHub Pages mỗi khi push `main`.
Xác thực bằng Azure AD thật (MSAL), phân quyền Edit qua whitelist email.
Codebase theo cấu trúc **feature-based** (`app` → `features` → `shared`, 0 cross-feature import).
Tài liệu tách theo nguyên tắc:
```
decisions/ BẤT BIẾN, append-only -> vì sao chọn thế này
docs/ MUTABLE, cập nhật tự do -> hiện tại đang thế nào
```
Rủi ro lớn nhất còn tồn: **không có test nào và CI không typecheck** —
xem [docs/roadmap.md](./docs/roadmap.md) mục Chất lượng.
---
## Chạy locally
**Yêu cầu**: Node.js 20+
```bash
pnpm install # KHÔNG dùng npm — xem decisions/0008
cp .env.example .env.local # rồi điền giá trị thật
lefthook install # bật git hook; bỏ bước này thì KHÔNG cửa nào chặn bạn
pnpm run dev # http://localhost:3000
```
`.env.local` cần tối thiểu 3 biến sau, thiếu là **không đăng nhập được**:
```bash
VITE_MSAL_CLIENT_ID=<client-id cua App Registration tren Azure AD>
VITE_MSAL_TENANT_ID=<tenant-id>
VITE_DATAVERSE_URL=https://<org>.crm5.dynamics.com/api/data/v9.2/
```
Ba biến tuỳ chọn cho tính năng AI Weekly Report: `GEMINI_API_KEY`,
`OLLAMA_BASE_URL`, `OLLAMA_MODEL`.
Chi tiết từng biến, cơ chế inject và cấu hình redirect URI:
[docs/tech-stack.md](./docs/tech-stack.md).
### Commands
```bash
pnpm run dev # dev server, cong 3000
pnpm run build # build production ra dist/
pnpm run preview # xem truoc ban build
sh scripts/verify.sh # GATE — security · arch-boundaries · doc-paths · typecheck
sh scripts/prove-gates.sh # chung minh cac gate that su do duoc (2-4 phut)
```
> `pnpm run build` chỉ chạy `vite build`, **không typecheck**. `scripts/verify.sh` mới là cửa —
> và pre-push tự chạy nó.
---
## Điều hướng tài liệu
| Cần biết | Đọc |
|---|---|
| Hệ thống đang thế nào — phân tầng, thư mục, luồng auth, luồng dữ liệu, ERD | [docs/architecture.md](./docs/architecture.md) |
| Stack, commands, biến môi trường, CI/CD | [docs/tech-stack.md](./docs/tech-stack.md) |
| Đã xong gì, còn gì phải làm | [docs/roadmap.md](./docs/roadmap.md) |
| Vì sao chọn cách này | [decisions/](./decisions/README.md) |
| Harness: gate nào đang chạy, chặn ai, đã chứng minh chưa | [PROGRESS.md](./PROGRESS.md) · [docs/harness.md](./docs/harness.md) |
| Bản đồ từng file | [index.md](./index.md) |
| Lịch sử thay đổi | [log.md](./log.md) |
| Yêu cầu nghiệp vụ · Hướng dẫn dùng · Test case | [docs/](./docs/) |
---
## Cấu trúc
```text
src/
├── main.tsx Entry — initializeMsal() TRUOC createRoot()
├── app/ Tang ung dung: App.tsx + routes/{Dashboard, ProjectDetail}
├── components/ UI dung chung, khong biet domain
├── features/ project · task · report · auth (KHONG import lan nhau)
├── hooks/ useApiData — stale-while-revalidate
├── lib/ dataverseService · aiService · apiCache
├── config/ constants.ts
└── types/ index.ts
```
Alias `@` trỏ `./src`, khai báo song song ở [vite.config.ts](./vite.config.ts) và
[tsconfig.json](./tsconfig.json) — sửa một chỗ phải sửa cả hai.
Ranh giới kiến trúc và cách kiểm tra: [docs/architecture.md](./docs/architecture.md) ·
[ADR 0002](./decisions/0002-feature-based-folder-architecture.md).