Phân tích Mã nguồn Boxme AI Insight

Quick Reference
Dự án: boxme-insight
Loại: Web App (Angular Embedded Module)
Ngôn ngữ: TypeScript 5.9+
Framework: Angular 19+ (Standalone, Signals, TailwindCSS 4)
Trạng thái: Production / Active
API Integration: 28+ insights từ insights.omisell.com

Kiến trúc Tổng quan

Mô tả: Frontend Angular 19 giao tiếp với backend qua REST API. Backend xử lý AI inference (LLM), truy vấn PostgreSQL, và gửi thông báo qua Telegram/Email/Lark. Frontend nhận token JWT từ parent app (oms.boxme.asia) để xác thực.

Cấu trúc Thư mục

text

src/app/
├── app.ts                        # Root component (bootstrap)
├── app.config.ts                 # Providers, interceptors config
├── app.routes.ts                 # Main routing (lazy-loaded)
│
├── core/                         # Core singletons
│   ├── auth/
│   │   ├── auth.service.ts      # JWT token management, user signals
│   │   └── auth.guard.ts        # Route protection guard
│   ├── interceptors/
│   │   ├── auth.interceptor.ts  # Append JWT header
│   │   ├── error.interceptor.ts # Global 401/403/500 handling
│   │   └── demo.interceptor.ts  # Mock data for demo mode
│   ├── models/
│   │   └── ai-providers.ts      # Provider/model definitions
│   ├── services/
│   │   ├── api.service.ts       # Central HTTP service (all endpoints)
│   │   ├── theme.service.ts     # Dark/light mode
│   │   ├── ai-config.service.ts # AI connector state
│   │   ├── header-state.service.ts  # Dynamic header state
│   │   └── permission.service.ts    # RBAC checks
│   └── demo/                    # Mock data generators
│       ├── mock-chat-responses.ts
│       ├── mock-insights.ts
│       ├── mock-execute-responses.ts
│       ├── mock-settings.ts
│       ├── mock-dashboard.ts
│       └── delay.utils.ts
│
├── features/                    # Feature modules (lazy-loaded)
│   ├── chat/
│   │   ├── chat.component.ts
│   │   ├── services/chat.service.ts
│   │   └── components/          # message-list, message-bubble, chat-input,
│   │                            # artifact-renderer, suggested-questions
│   ├── dashboard/
│   │   ├── dashboard.routes.ts
│   │   ├── services/dashboard.service.ts
│   │   └── components/          # dashboard-list, dashboard-view, widget-card,
│   │                            # settings-dialog, schedule-dialog, share-dialog,
│   │                            # filter-preset-bar
│   ├── insights/
│   │   ├── insights.routes.ts
│   │   ├── insight-catalog.component.ts
│   │   └── insight-detail.component.ts
│   └── settings/
│       ├── settings.routes.ts
│       ├── settings.component.ts
│       └── components/          # ai-config-wizard, onboarding-dialog,
│                                # channel-config-dialog
│
├── layout/                      # App shell
│   ├── main-layout/main-layout.component.ts
│   ├── header/header.component.ts
│   └── sidebar/sidebar.component.ts
│
└── shared/                      # Reusable components & models
    ├── models/
    │   ├── api.models.ts        # All TypeScript interfaces (365 lines)
    │   └── index.ts
    └── components/
        ├── chart-renderer.component.ts   # ECharts wrapper
        └── data-table.component.ts       # Paginated data table

Phụ thuộc Chính (Dependencies)

Category	Package	Version	Purpose
Framework	`@angular/core`	^21.2.0	Frontend framework
UI	`@angular/material`	^21.2.6	Material Design components
Styling	`tailwindcss`	^4.2.2	Utility-first CSS
Charts	`echarts` + `ngx-echarts`	^6.0.0, ^21.0.0	Chart rendering
Markdown	`ngx-markdown` + `marked`	^21.2.0, ^17.0.6	AI response parsing
Diagrams	`mermaid`	^11.14.0	Diagram rendering
Icons	`lucide-angular`	^1.0.0	Icon library
Export	`jspdf`, `xlsx`	^4.2.1, ^0.18.5	PDF/Excel export
Reactive	`rxjs`	~7.8.0	Observable streams
Testing	`vitest`	^4.0.8	Unit tests

Route Map

Path	Component	Auth	Loading	Mô tả
`/`	Redirect → `/chat`	Yes	—	Trang mặc định
`/chat`	`ChatComponent`	Yes	Lazy	Giao diện AI Chatbot
`/insights`	`InsightCatalogComponent`	Yes	Lazy	Catalog insight phân tích
`/insights/:queryCode`	`InsightDetailComponent`	Yes	Lazy	Chi tiết insight + execute
`/dashboard`	`DashboardListComponent`	Yes	Lazy	Danh sách dashboards
`/dashboard/:id`	`DashboardViewComponent`	Yes	Lazy	Xem/chỉnh sửa dashboard
`/settings`	`SettingsComponent`	Yes	Lazy	Cài đặt AI, channels, subscriptions
`**`	Redirect → `/chat`	—	—	Fallback

Source: (src/app/app.routes.ts:1), (src/app/features/dashboard/dashboard.routes.ts:1), (src/app/features/insights/insights.routes.ts:1)

Data Models Chính

Authentication & User

Interface	Fields	Source
`UserInfo`	id, email, name, seller_type, country, company_name?, role, tenant_id	(`api.models.ts:7`)
`SellerType`	`'boxme_only'` \| `'omisell_only'` \| `'boxme_and_omisell'`	(`api.models.ts:1`)
`OrgRole`	`'owner'` \| `'admin'` \| `'member'`	(`api.models.ts:2`)

AI Chat

Interface	Key Fields	Source
`AIChatRequest`	question, insight_code?, granularity?, filters?	(`api.models.ts`)
`AIChatResponse`	mode, intent, explanation, data[], chart_hint?, alerts[], execution_status	(`api.models.ts`)
`ChatMessage`	id, role, content, timestamp, artifacts?, mode?, rating?	(`api.models.ts`)
`Artifact`	type (`chart` \| `table` \| `kpi`), data[], chartHint?, title?	(`api.models.ts`)

Insights

Interface	Key Fields	Source
`InsightRead`	query_code, name, description, category, seller_type, granularities[], filter_config[], chart_hint?, tags?	(`api.models.ts`)
`ExecuteRequest`	granularity, end_date?, country?, sort_by?, filters?, limit?	(`api.models.ts`)
`ExecuteResponse`	data[], chart_hint?, alerts[], total_rows, execution_time_ms	(`api.models.ts`)

Dashboards

Interface	Key Fields	Source
`Dashboard`	id, name, description?, is_shared, shared_with_emails?, widget_ids[], global_filter_presets[]	(`api.models.ts`)
`DashboardWidget`	id, title, widget_type, display_size, data_source, insight_code?, snapshot_data?	(`api.models.ts`)
`DashboardSubscription`	id, dashboard_id, channel_ids[], schedule, schedule_time, is_active	(`api.models.ts`)

Visualization

Interface	Key Fields	Source
`ChartHint`	chart_type, x_column, y_columns[], title	(`api.models.ts`)
`ChartType`	`bar` \| `line` \| `pie` \| `stacked_bar` \| `grouped_bar` \| `area` \| `heatmap`	(`api.models.ts`)
`DataRow`	`Record<string, unknown>`	(`api.models.ts`)

Notifications & Subscriptions

Interface	Key Fields	Source
`NotificationChannel`	id, channel_type, config, is_verified	(`api.models.ts`)
`InsightSubscription`	id, insight_code, channel_id, schedule, granularity, is_active	(`api.models.ts`)
`DeliveryLog`	id, subscription_id, insight_name, channel_type, status, error_message?	(`api.models.ts`)

AI Connectors

Interface	Key Fields	Source
`AIConnector`	provider, api_key_masked, is_active, model?, model_label?	(`api.models.ts`)
`AIConnectorCreateRequest`	provider, api_key, model?	(`api.models.ts`)
`AIConnectorTestResponse`	success, message, latency_ms?	(`api.models.ts`)

Luồng Hoạt động Dữ liệu

Mô tả: Ứng dụng dùng Angular Signals (không dùng NgRx) để quản lý state. Tất cả component giao tiếp qua HttpClient với pipeline interceptors: demoInterceptor → authInterceptor → errorInterceptor. Response JSON chứa data[], chart_hint, alerts[] được parse bởi chart-renderer và data-table.

Key Files

File	Vai trò	Dòng
`src/app/core/services/api.service.ts`	Central HTTP service — tất cả API calls	274
`src/app/shared/models/api.models.ts`	Tất cả TypeScript interfaces	365
`src/app/core/auth/auth.service.ts`	JWT token management, user signals	158
`src/app/core/interceptors/demo.interceptor.ts`	Demo mode mock data	256
`src/app/core/models/ai-providers.ts`	AI provider/model definitions	222
`src/app/features/chat/services/chat.service.ts`	Chat message state	~100
`src/app/features/dashboard/services/dashboard.service.ts`	Dashboard state	~150
`src/app/core/services/permission.service.ts`	RBAC permission checks	42
`src/app/shared/components/chart-renderer.component.ts`	ECharts wrapper	~200
`src/styles.css`	Tailwind theme + brand colors	~150

Test Coverage

Framework	Thư mục Test	Ghi chú
Vitest	`src/*/.spec.ts`	Unit tests cho components & services

Liên kết

Kiến trúc Hệ thống — Sơ đồ kiến trúc chi tiết + ADR
Data Flow — Luồng dữ liệu chi tiết
API Reference — Tài liệu API đầy đủ

Phân tích Mã nguồn Boxme AI Insight ​

Kiến trúc Tổng quan ​

Cấu trúc Thư mục ​

Phụ thuộc Chính (Dependencies) ​

Route Map ​

Data Models Chính ​

Authentication & User ​

AI Chat ​

Insights ​

Dashboards ​

Visualization ​

Notifications & Subscriptions ​

AI Connectors ​

Luồng Hoạt động Dữ liệu ​

Key Files ​

Test Coverage ​

Liên kết ​