TÀI LIỆU ĐẶC TẢ YÊU CẦU PHẦN MỀM (SRS) ​

HỆ THỐNG: NỀN TẢNG TRUY XUẤT NGUỒN GỐC GOTRACE ​

TXNG-F30 -- Dashboard Tổng hợp Truy xuất Nguồn gốc ​

Lịch sử thay đổi ​

1. Tổng quan tài liệu ​

1.1. Mục đích tài liệu ​

Tài liệu mô tả chi tiết chức năng Dashboard Tổng hợp Truy xuất Nguồn gốc (TXNG-F30) trong Module Truy xuất Nguồn gốc (TXNG) của hệ thống GoTrace. Chức năng cung cấp 8 dashboard chuyên biệt, tổng hợp dữ liệu từ tất cả 29 module TXNG (F01–F29), trình bày dưới dạng biểu đồ, bảng dữ liệu và stat cards, phục vụ quản lý doanh nghiệp và cán bộ QLNN theo dõi toàn diện tình hình truy xuất nguồn gốc trên địa bàn.

Tài liệu tham chiếu kiến trúc từ ATTP-F24 (Dashboard Tổng hợp ATTP) — cùng mô hình 8 dashboard aggregate, đã triển khai thành công cho module An toàn Thực phẩm.

Tài liệu là cơ sở cho đội ngũ phát triển (Developer), kiểm thử (QA), và các bên liên quan trong việc hiểu rõ yêu cầu kỹ thuật – nghiệp vụ.

1.2. Thông tin chức năng ​

1.3. Tác nhân tham gia (Actors) ​

1.4. Tham chiếu UI/UX ​

1.4.1. Bảng tham chiếu ​

1.4.2. Kiến trúc 8 lớp UX (chuẩn QLNN-F38) ​

Mọi sub-dashboard SCR-F30-01..08 PHẢI tuân thủ kiến trúc 8 lớp sau:

1.4.3. Custom hooks tái sử dụng (đặt tại apps/frontend/components/admin/txng/dashboard/hooks/) ​

Tham chiếu code chuẩn: apps/frontend/components/admin/qlnn/chuyen-nganh/index.tsx

2. Luồng nghiệp vụ (Business Flow) ​

2.1. Luồng nghiệp vụ tổng quan (ASCII diagram) ​

┌──────────────────────────────────────────────────────────────────────────────┐
│             LUỒNG TRUY CẬP DASHBOARD TỔNG HỢP TXNG                         │
├──────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  [ENTERPRISE_ADMIN / SO_ADMIN / TINH_TP_ADMIN]                              │
│         |                                                                    │
│         v                                                                    │
│  +---------------------+                                                     │
│  | 1. Truy cập menu    |                                                     │
│  | TXNG > Dashboard    |                                                     │
│  +---------------------+                                                     │
│         |                                                                    │
│         v                                                                    │
│  +---------------------+     +---------------------+                        │
│  | 2. Chọn dashboard   | --> | 3. Hệ thống kiểm tra|                        │
│  | chuyên biệt (1/8)   |     | quyền truy cập      |                        │
│  +---------------------+     +---------------------+                        │
│                                       |                                      │
│                          +------------+-------------+                        │
│                          |                          |                         │
│                     [Có quyền]              [Không có quyền]                 │
│                          |                          |                         │
│                          v                          v                         │
│  +---------------------+          +---------------------+                    │
│  | 4. Load dữ liệu     |          | Hiển thị E-F30-003  |                    │
│  | aggregate từ F01-F29 |          | "Không có quyền"    |                    │
│  +---------------------+          +---------------------+                    │
│         |                                                                    │
│         v                                                                    │
│  +---------------------+                                                     │
│  | 5. Hiển thị         |                                                     │
│  | Stat Cards +        |                                                     │
│  | Biểu đồ + Bảng     |                                                     │
│  +---------------------+                                                     │
│         |                                                                    │
│    +----+----+----+                                                          │
│    |         |    |                                                           │
│    v         v    v                                                           │
│  [Filter] [Drill] [Export]                                                   │
│    |       down     |                                                        │
│    v         |      v                                                        │
│  +-------+  |  +---------+                                                   │
│  |Reload |  |  |PDF/Excel|                                                   │
│  |data   |  |  |download |                                                   │
│  +-------+  |  +---------+                                                   │
│             v                                                                │
│  +---------------------+                                                     │
│  | Navigate đến module |                                                     │
│  | nguồn (F01-F29)     |                                                     │
│  +---------------------+                                                     │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

2.2. Diễn giải luồng (bảng bước) ​

3. Phân loại Dashboard ​

3.1. Phân loại 8 dashboard theo mục đích ​

3.2. Phân loại biểu đồ sử dụng ​

4. Danh sách màn hình ​

4.1. Bảng tổng hợp màn hình ​

4.2. Layout chuẩn 8 lớp UX (áp dụng SCR-F30-01 đến SCR-F30-08) ​

Mỗi sub-dashboard PHẢI có cấu trúc giao diện theo thứ tự sau từ trên xuống:

┌─ L1. SubHeader (sticky, height ~64px) ──────────────────────────────────────┐
│   ◀ TXNG / Dashboard {tên} · Subtitle: "DN: {tên DN} · {N} bộ lọc"          │
│                                                  [⚙️ Tùy chỉnh] [🔗 Chia sẻ URL] [📥 Xuất báo cáo] │
├─ L2. FilterBar (SearchWrapper, primary 4-col grid) ────────────────────────┤
│   [Doanh nghiệp ▾] [Vùng SX ▾] [Sản phẩm ▾] [Kỳ phân tích ▾]             │
│   ☐ So sánh kỳ liền kề (▲/▼ % trend)                                        │
│   ▸ Hiện bộ lọc nâng cao (toggle secondary 4-col grid: Loại lô, Trạng thái, GTIN, Vùng GIS) │
│                                                                  [Reset] │
├─ L3. BreadcrumbContextBar (chip row, hidden khi không có filter) ──────────┤
│   [DN: Vinamilk ×] [Vùng: Tây Nguyên ×] [SP: Sữa tươi ×]   [Reset all]     │
├─ L4. KPIStrip (grid auto-fit minmax(180px, 1fr), 8 cards) ─────────────────┤
│   [🏢 8.547  Tổng DN  ▲+12.4%]   [📦 52k Tổng SP  ▲+18.7%]   [🏷️ 284k Tổng lô  ▲+24.3%] │
│   [✅ 87.3% Tuân thủ  ▲+2.4%]   [🔗 3.4k Chuỗi HĐ  ▲+15.6%]   [🚫 1.5k Vi phạm  ▼-8.2%] │
│   [⚠️ 237 Gián đoạn  ▼-12.5%]   [⭐ 82.4% Tín nhiệm  ▲+3.1đ]                │
├─ L5. SectionContainer (vertical stack, mỗi card class .mg margin-bottom 16) ┤
│   ╔═ AnalyticalSection 1 — "Phân bố DN theo Ngành hàng" ═════════════════╗ │
│   ║ Header: [icon][title][subtitle][trend badge ▲+5.2%] [⋮ menu pin/export]║ │
│   ║ Tabs: [Số DN] [Số cơ sở] [Số chuỗi] [Tổng SP]                         ║ │
│   ║ Body: HorizontalBarChart {data, height: 320, unit: 'DN'}              ║ │
│   ║ Footer: "Top 10 ngành" [Pin 📌] [Export 📥]                           ║ │
│   ╚═══════════════════════════════════════════════════════════════════════╝ │
│   ... (lazy load IntersectionObserver — render khi scroll vào viewport)     │
├─ L7. NestedDrillDownModal (overlay, fixed top-level, hidden by default) ───┤
│   ◀ Tổng DN › Theo tỉnh › Theo ngành        [Donut|Bar|Line|Heatmap]      │
│   Tabs: [Số DN] [Số chuỗi]    Limit: [20|50|100]                            │
│   Body: chart + ranking table                                                │
└─ L8. PersonalizationPanel (right drawer 360px, hidden by default) ─────────┘
    ☑ Phân bố DN theo Ngành hàng    📌 Pin
    ☑ Top 10 chuỗi cung ứng         📌 Pin
    ☐ Heatmap tỉnh theo nguy cơ
    [Lưu preset "Theo dõi hàng ngày"] [Áp dụng] [Xoá]

Tham chiếu component code: components/admin/qlnn/chuyen-nganh/sections/analytical-section.tsx, components/admin/qlnn/chuyen-nganh/sections/kpi-strip.tsx, components/admin/qlnn/chuyen-nganh/filter/filter-bar.tsx.

4.3. Trạng thái UI (loading/empty/error) — chuẩn QLNN-F38 ​

5. Mô tả chi tiết trường dữ liệu (per dashboard) ​

5.0. Type signatures chuẩn (chia sẻ giữa 8 sub-dashboard) ​

5.0.1. IFilterState — state bộ lọc (chuẩn QLNN-F38) ​

export interface IFilterState {
  // Primary filters (luôn hiển thị)
  enterprise_id?: string | null;          // FK → enterprises (TXNG-F01). BE DTO dùng tên `company_id` (alias).
  region_id?: string | null;              // FK → production_zones (TXNG-F02). v1.0: chưa wire BE — lùi v1.5.
  product_type?: 'TRONG_TROT' | 'CHAN_NUOI' | 'THUY_SAN' | 'CHE_BIEN' | null;
  period_type: 'YEAR' | 'QUARTER' | 'MONTH' | 'WEEK' | 'DAY' | 'CUSTOM';
  period_value: string;                   // "2026" | "2026-Q2" | "2026-05" | "2026-W18" | "2026-05-05" | "2026-04-01..2026-05-05"
  compare_prev: boolean;                  // checkbox "So sánh kỳ liền kề"

  // Secondary filters (collapsible)
  batch_status?: TBatchStatus | null;     // v1.0: định nghĩa nhưng chưa wire BE — lùi v1.5.
  gtin?: string | null;                   // v1.0: chưa wire BE — lùi v1.5.
  province_id?: string | null;            // ✅ wire BE — match qua Facility.province.name.
  certificate_type?: 'VIETGAP' | 'GLOBAL_GAP' | 'HACCP' | 'ISO22000' | null;  // v1.0: chưa wire — lùi v1.5.
  // ... mở rộng theo từng sub-dashboard
}

Nguồn product_type của Batch — schema KHÔNG có cột batches.batch_type. Loại lô được derive qua chain Batch.production_plan_id → ProductionPlan.products → PlanProduct.product_type. FE form Batch (apps/frontend/validators/txng/batch/form.schema.ts) collect batch_type khi tạo Production Plan, KHÔNG lưu trực tiếp lên batches. Dashboard service JOIN qua relation để hiển thị phân loại (xem helper batchProductTypeInclude() + resolveProductType() ở apps/backend/src/modules/txng-dashboard/txng-dashboard.service.ts).

Filter product_type hiện đang dùng keyword inference trên gtin_name (PRODUCT_TYPE_KEYWORDS) thay vì JOIN relation — sẽ refactor về JOIN exact ở v1.5 sau khi thêm index plan_products(product_type).

5.0.2. IKPICard — đặc tả 1 stat-card ​

export interface IKPICard {
  key: string;                            // unique trong KPI strip, ví dụ 'total_enterprises'
  label: string;                          // "Tổng doanh nghiệp"
  icon: string;                           // emoji 🏢 hoặc icon name HeroUI
  formatted_value: string;                // "8.547" (đã format theo locale vi-VN)
  raw_value: number;                      // 8547 (dùng cho aggregate)
  prev_value?: number | string;           // dùng khi compare_prev=true
  change_percent?: number;                // +12.4 → hiển thị "▲+12.4%"
  change_points?: number;                 // dùng cho KPI dạng score (vd điểm tín nhiệm)
  trend_direction?: 'up' | 'down' | 'neutral';
  color: 'blue' | 'green' | 'orange' | 'red' | 'teal' | 'purple';
  drill_target?: string;                  // ví dụ '/admin/txng/enterprises?status=ACTIVE' — click → navigate hoặc openModal
  tooltip?: string;                       // hover info, công thức tính
}

5.0.3. ISectionMeta — đặc tả 1 AnalyticalSection ​

export interface ISectionMeta {
  section_id: string;                     // 'F30-01-section-01' (theo SCR-NN-section-NN)
  group: 'A' | 'B' | 'C' | 'D' | 'E' | 'F'; // Group trong personalization panel
  icon: string;
  title: string;
  subtitle: string;
  default_chart: 'horizontal_bar' | 'donut' | 'stacked_bar' | 'line' | 'heatmap' | 'radar' | 'progress';
  data_tabs: IDataTab[];                  // ví dụ [{key:'count', label:'Số lô'}, {key:'volume', label:'Sản lượng'}]
  can_drill_down: boolean;
  default_visibility: { [role: string]: boolean }; // BO_TU: true, ENTERPRISE_USER: false, ...
  pinned_default?: boolean;
}

export interface IDataTab {
  key: string;
  label: string;
}

5.0.4. Bộ lọc chung 4 trường primary (áp dụng SCR-F30-01..08) ​

Khi compare_prev=true: KPI card hiển thị thêm trend % so kỳ trước; AnalyticalSection có thêm overlay "kỳ trước" trên line/bar chart.

5.1. SCR-F30-01 — Dashboard Tổng quan TXNG ​

5.1.1. Stat Cards ​

5.1.2. Bộ lọc (Filters) ​

5.1.3. Biểu đồ ​

5.1.4. Bảng dữ liệu ​

5.2. SCR-F30-02 — Dashboard Sản xuất & Kế hoạch ​

5.2.1. Stat Cards ​

5.2.2. Bộ lọc (Filters) ​

5.2.3. Biểu đồ ​

5.3. SCR-F30-03 — Dashboard Lô mã & Tồn kho ​

5.3.1. Stat Cards ​

5.3.2. Biểu đồ ​

5.4. SCR-F30-04 — Dashboard Mã hóa & Tem điện tử ​

5.4.1. Stat Cards ​

5.4.2. Biểu đồ ​

5.5. SCR-F30-05 — Dashboard Chuỗi cung ứng & Phân phối ​

5.5.1. Stat Cards ​

5.5.2. Biểu đồ ​

Data shape txng-sc-07 (Map):

Array<{
  id: string;                   // 'wh-{id}' | 'pos-{id}'
  type: 'warehouse' | 'sale_point';
  name: string;
  lat: number;
  lng: number;
  sublabel?: string;            // address
}>

Data shape txng-sc-08 (Widget F33):

{
  kpi: { pending: number; in_transit: number };
  top_products: Array<{
    batch_id: string;
    name: string;                // resolve qua Batch.gtin_name
    code: string;                // resolve qua Batch.code
    total_quantity: number;      // SUM(StockTransferItem.quantity) 7 ngày
  }>;
  recent_transfers: Array<{
    id: string;
    code: string;                // StockTransfer.transfer_code
    status: string;              // PENDING_APPROVAL | IN_TRANSIT
    source_type: string;
    destination_type: string;
    created_at: string;
  }>;
} | null  // null nếu DN không có lệnh F33 nào trong 30 ngày (BR_RULE-F30-09)

5.5.3. Widget "Điều Chuyển Nội Bộ" — v1.1 (F33) ​

Stat Cards bổ sung:

Biểu đồ:

Drill-down: Click bất kỳ → điều hướng đến SCR-F33-01 với filter tương ứng.

5.5.4. Widget "Cân Bằng Tồn Kho Chuỗi" — v1.1 (F33) ​

Mô tả: So sánh tồn kho giữa các điểm bán trong cùng enterprise. Màu sắc heatmap: xanh = tồn dư (≥ ngưỡng cấu hình), đỏ = tồn thiếu (< ngưỡng tối thiểu), vàng = trung bình.

Bảng tồn kho per điểm bán:

Cảnh báo tự động:

• Sản phẩm có available_qty < min_threshold (cấu hình per enterprise) → badge đỏ CRITICAL
• Sản phẩm có available_qty > max_threshold tại điểm bán nguồn + available_qty < min_threshold tại điểm bán khác → gợi ý tạo lệnh F33

Drill-down: Click điểm bán → SCR-F33-07 (tồn kho điểm bán chi tiết).

5.6. SCR-F30-06 — Dashboard Truy vết & Thu hồi ​

5.6.1. Stat Cards ​

5.6.2. Biểu đồ ​

5.7. SCR-F30-07 — Dashboard Tích hợp & Đồng bộ ​

5.7.1. Stat Cards ​

5.7.2. Biểu đồ ​

5.8. SCR-F30-08 — Dashboard Quản lý Nhà nước TXNG ​

5.8.1. Stat Cards ​

5.8.2. Bộ lọc (Filters) ​

5.8.3. Biểu đồ ​

Data shape txng-gm-07 (Map DN):

Array<{
  id: string;                   // 'prov-{name}'
  type: 'province_cluster';
  name: string;
  lat: number;
  lng: number;
  sublabel: string;             // '{count} doanh nghiệp'
  meta: { count: number };
}>

Province legacy mapping (sáp nhập 2025): dữ liệu DN có address chứa tên tỉnh cũ (vd "Bình Dương", "Hậu Giang") được map sang tỉnh mới qua PROVINCE_LEGACY_MAP trước khi lookup centroid. Xem helper normalizeProvinceName() tại apps/backend/src/modules/txng-dashboard/txng-dashboard-modules.service.ts.

6. Danh sách Use Case ​

7. Mô tả chi tiết Use Case ​

UC-F30-01: Xem Dashboard Tổng quan TXNG ​

Pre-conditions: User đã đăng nhập, có role ENTERPRISE_ADMIN hoặc SO_ADMIN hoặc TINH_TP_ADMIN

Post-conditions: Dashboard hiển thị dữ liệu aggregate từ các module nguồn

Alternative Flow:

• AF-01: User không có quyền -> Hiển thị E-F30-003 "Không có quyền xem dashboard này"
• AF-02: Không có dữ liệu cho kỳ đã chọn -> Hiển thị E-F30-001 "Không có dữ liệu"
• AF-03: API timeout -> Hiển thị E-F30-002 "Lỗi khi tải dữ liệu", nút "Thử lại"

UC-F30-02: Xem Dashboard Sản xuất & Kế hoạch ​

Alternative Flow:

• AF-01: Không có KH trong 7 ngày tới -> Table hiển thị "Không có kế hoạch sắp đến hạn"

UC-F30-08: Xem Dashboard Quản lý Nhà nước ​

Pre-conditions: User có role SO_ADMIN hoặc TINH_TP_ADMIN

Alternative Flow:

• AF-01: ENTERPRISE_ADMIN truy cập -> Hiển thị E-F30-003 "Chỉ cán bộ QLNN mới có quyền xem"

UC-F30-09: Lọc dữ liệu Dashboard ​

Business Rules:

• ENTERPRISE_ADMIN/USER: dữ liệu tự động lọc theo enterprise_id của DN mình
• SO_ADMIN: xem dữ liệu toàn bộ DN thuộc phạm vi quản lý
• TINH_TP_ADMIN: xem dữ liệu tất cả DN, tất cả bộ lọc đều có thể thay đổi

UC-F30-10: Export Dashboard PDF/Excel ​

Pre-conditions: User có role ENTERPRISE_ADMIN hoặc SO_ADMIN hoặc TINH_TP_ADMIN

Alternative Flow:

• AF-01: File > 10.000 bản ghi -> Hiển thị W-F30-002 "Export file lớn, vui lòng chờ xử lý"
• AF-02: ENTERPRISE_USER nhấn export -> Hiển thị E-F30-003 "Không có quyền"
• AF-03: Export thất bại -> Toast error "Lỗi khi xuất file. Vui lòng thử lại."

UC-F30-11: Drill-down từ Dashboard ​

Ví dụ drill-down:

8. Thiết kế Database Schema ​

8.1. Ghi chú quan trọng ​

Dashboard F30 là chức năng aggregate read-only, KHÔNG tạo bảng dữ liệu mới cho nghiệp vụ. Tất cả dữ liệu được query trực tiếp từ các bảng của module F01-F29.

Tuy nhiên, cần 1 bảng phụ trợ cho tính năng bookmark filter của người dùng (phase 2), và 1 bảng audit log cho truy vết hành vi:

8.2. Mô tả bảng ​

8.2.1. txng_dashboard_bookmarks ​

8.2.2. txng_dashboard_audit_logs ​

8.3. Indexes ​

-- txng_dashboard_bookmarks
CREATE INDEX idx_txng_bookmarks_user_dashboard ON txng_dashboard_bookmarks(user_id, dashboard_slug) WHERE deleted_at IS NULL;
CREATE UNIQUE INDEX idx_txng_bookmarks_default ON txng_dashboard_bookmarks(user_id, dashboard_slug) WHERE is_default = true AND deleted_at IS NULL;

-- txng_dashboard_audit_logs
CREATE INDEX idx_txng_audit_user ON txng_dashboard_audit_logs(enterprise_id, user_id, created_at DESC);
CREATE INDEX idx_txng_audit_action ON txng_dashboard_audit_logs(dashboard_slug, action, created_at DESC);

-- Indexes trên bảng nguồn (để tăng tốc aggregate queries) — chỉ tạo nếu chưa có
-- F09: batches
CREATE INDEX IF NOT EXISTS idx_batches_status ON batches(enterprise_id, status) WHERE deleted_at IS NULL;
CREATE INDEX IF NOT EXISTS idx_batches_type_month ON batches(enterprise_id, batch_type, EXTRACT(YEAR FROM created_at), EXTRACT(MONTH FROM created_at)) WHERE deleted_at IS NULL;
CREATE INDEX IF NOT EXISTS idx_batches_expiry ON batches(enterprise_id, expiry_date) WHERE deleted_at IS NULL AND status NOT IN ('RECALLED','CANCELLED');

-- F16: qr_codes
CREATE INDEX IF NOT EXISTS idx_qr_scans_date ON qr_code_scans(scanned_at::date);

-- F13: recalls
CREATE INDEX IF NOT EXISTS idx_recalls_status ON recalls(enterprise_id, status) WHERE deleted_at IS NULL;

-- F22: shipment_orders
CREATE INDEX IF NOT EXISTS idx_shipments_status ON shipment_orders(enterprise_id, status) WHERE deleted_at IS NULL;

-- F10: certifications
CREATE INDEX IF NOT EXISTS idx_certs_expiry ON company_certifications(enterprise_id, expiry_date) WHERE deleted_at IS NULL;

8.4. Migration SQL ​

-- Migration: 2026_04_11_create_txng_dashboard_tables.sql

-- 1. txng_dashboard_bookmarks
CREATE TABLE IF NOT EXISTS txng_dashboard_bookmarks (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    enterprise_id UUID NOT NULL REFERENCES enterprises(id),
    user_id UUID NOT NULL REFERENCES users(id),
    dashboard_slug VARCHAR(50) NOT NULL CHECK (dashboard_slug IN (
        'tong-quan', 'san-xuat-ke-hoach', 'lo-ma-ton-kho',
        'ma-hoa-tem', 'chuoi-cung-ung', 'truy-vet-thu-hoi',
        'tich-hop-dong-bo', 'quan-ly-nha-nuoc'
    )),
    bookmark_name VARCHAR(200) NOT NULL,
    filter_config JSONB NOT NULL DEFAULT '{}',
    is_default BOOLEAN NOT NULL DEFAULT false,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    deleted_at TIMESTAMPTZ NULL
);

CREATE INDEX idx_txng_bookmarks_user_dashboard ON txng_dashboard_bookmarks(user_id, dashboard_slug) WHERE deleted_at IS NULL;
CREATE UNIQUE INDEX idx_txng_bookmarks_default ON txng_dashboard_bookmarks(user_id, dashboard_slug) WHERE is_default = true AND deleted_at IS NULL;

-- 2. txng_dashboard_audit_logs
CREATE TABLE IF NOT EXISTS txng_dashboard_audit_logs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    enterprise_id UUID NOT NULL REFERENCES enterprises(id),
    user_id UUID NOT NULL REFERENCES users(id),
    action VARCHAR(20) NOT NULL CHECK (action IN ('VIEW', 'EXPORT_PDF', 'EXPORT_EXCEL', 'FILTER', 'DRILL_DOWN')),
    dashboard_slug VARCHAR(50) NOT NULL,
    filter_params JSONB,
    export_filename VARCHAR(255),
    ip_address INET,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_txng_audit_user ON txng_dashboard_audit_logs(enterprise_id, user_id, created_at DESC);
CREATE INDEX idx_txng_audit_action ON txng_dashboard_audit_logs(dashboard_slug, action, created_at DESC);

9. Thiết kế API ​

9.1. Danh sách endpoint ​

Lưu ý: BE prefix thực tế là /api/v1/txng-dashboard/ (không có /dashboard/ segment). 3 endpoint module (4, 5, 8) gộp qua dispatcher /module/:slug để tái sử dụng code; path thiết kế ban đầu lệch nhưng giữ nguyên (cập nhật bảng dưới phản ánh thực tế impl).

Audit logging (BR-F30-12): mọi call view/drill/export tự động ghi txng_dashboard_audit_logs qua DashboardAuditInterceptor (async, không chặn response). Endpoint bookmark (10-12) KHÔNG ghi audit log.

Multi-tenant: filter param company_id optional — admin có thể xem toàn hệ thống; truyền company_id để drill-down 1 DN. SRS dùng tên field enterprise_id, BE DTO dùng company_id (alias đồng nghĩa).

9.2. Chi tiết API ​

API 1: GET /api/v1/txng/dashboard/overview ​

Query Parameters:

Response 200:

{
    "success": true,
    "data": {
        "stat_cards": {
            "total_enterprises": 2845,
            "traceability_rate": 89.5,
            "active_batches": 11250,
            "total_qr_scans": 458320,
            "active_recalls": 3,
            "unresolved_alerts": 28
        },
        "traceability_trend": [
            { "month": "T1", "current_year": 72.5, "prev_year": 65.3 },
            { "month": "T2", "current_year": 74.8, "prev_year": 67.1 }
        ],
        "batch_distribution": [
            { "type": "TRONG_TROT", "count": 4520, "color": "#2e7d32" },
            { "type": "CHAN_NUOI", "count": 2180, "color": "#0b3d91" },
            { "type": "THUY_SAN", "count": 1350, "color": "#0277bd" },
            { "type": "CHE_BIEN", "count": 3200, "color": "#fb8c00" }
        ],
        "batch_by_status_month": [
            { "month": "T1", "KHOI_TAO": 120, "DANG_SX": 280, "HOAN_THANH": 350, "DA_XUAT_KHO": 180, "DA_PHAN_PHOI": 150 }
        ],
        "top_enterprises": [
            { "enterprise_id": "uuid", "name": "Vinamilk", "batch_count": 1250 }
        ],
        "recent_alerts": [
            {
                "id": "uuid",
                "code": "CB-TXNG-00245",
                "content": "Lô rau VietGAP vượt thời gian cách ly thuốc BVTV",
                "batch_code": "LOT-TT-20260401-0412",
                "alert_level": "CAN_XU_LY",
                "created_at": "2026-04-10T09:15:00Z"
            }
        ]
    }
}

API 8: GET /api/v1/txng/dashboard/gov-oversight ​

Query Parameters:

Response 200:

{
    "success": true,
    "data": {
        "stat_cards": {
            "total_enterprises": 2845,
            "valid_cert_rate": 78.5,
            "sync_coverage": 92.3,
            "full_trace_rate": 85.2,
            "recall_incidents": 3,
            "new_onboarding": 125
        },
        "enterprise_by_district": [
            { "district": "Đông Anh", "count": 285 }
        ],
        "onboarding_trend": [
            { "month": "T1", "cumulative": 2100, "new_joined": 85 }
        ],
        "compliance_radar": [
            { "subject": "Định danh GLN/GTIN", "score": 92 },
            { "subject": "Ghi nhận CTE", "score": 85 },
            { "subject": "KDE đầy đủ", "score": 78 },
            { "subject": "Đồng bộ QG", "score": 88 },
            { "subject": "Chứng nhận hợp lệ", "score": 72 },
            { "subject": "Nhật ký SX", "score": 90 },
            { "subject": "Truy vết < 4h", "score": 95 },
            { "subject": "Mã QR/Tem", "score": 82 }
        ],
        "cert_by_standard": [
            { "standard": "VietGAP", "percentage": 45, "count": 1250 }
        ],
        "non_compliant_enterprises": [
            {
                "id": "uuid",
                "name": "Công ty TNHH Thực phẩm XYZ",
                "tax_code": "0102345678",
                "district": "Đông Anh",
                "cert_status": "EXPIRED",
                "sync_status": "ERROR",
                "batch_count": 45,
                "note": "VietGAP hết hạn 15/03/2026"
            }
        ]
    }
}

API 9: GET /api/v1/txng/dashboard/export/ ​

Path Parameters:

Query Parameters:

Response 200: Binary file download

Content-Type: application/pdf (hoặc application/vnd.openxmlformats-officedocument.spreadsheetml.sheet)
Content-Disposition: attachment; filename="Dashboard_Tong_Quan_TXNG_20260411.pdf"

Error Responses (chung cho tất cả API):

// 401 Unauthorized
{
    "success": false,
    "error": { "code": "AUTH_REQUIRED", "message": "Vui lòng đăng nhập" }
}

// 403 Forbidden
{
    "success": false,
    "error": { "code": "FORBIDDEN", "message": "Không có quyền xem dashboard này" }
}

// 500 Internal Server Error
{
    "success": false,
    "error": { "code": "INTERNAL_ERROR", "message": "Lỗi khi tải dữ liệu dashboard" }
}

10. Test Cases cho QA ​

10.1. Dashboard Tổng quan TXNG (SCR-F30-01) ​

10.2. Dashboard Sản xuất & Kế hoạch (SCR-F30-02) ​

10.3. Dashboard Lô mã & Tồn kho (SCR-F30-03) ​

10.4. Dashboard Mã hóa & Tem (SCR-F30-04) ​

10.5. Dashboard Chuỗi cung ứng (SCR-F30-05) ​

10.6. Dashboard Truy vết & Thu hồi (SCR-F30-06) ​

10.7. Dashboard Tích hợp & Đồng bộ (SCR-F30-07) ​

10.8. Dashboard Quản lý Nhà nước (SCR-F30-08) ​

10.9. Export và Phân quyền ​

11. Acceptance Criteria ​

12. Chuyển đổi trạng thái (State Transitions) ​

Dashboard F30 là chức năng read-only, không có state machine riêng cho dữ liệu. Tuy nhiên, có state management cho:

12.1. Trạng thái Loading của Dashboard ​

[IDLE] ---> (User truy cập) ---> [LOADING] ---> (API success) ---> [LOADED]
                                     |
                                     +--- (API error) ---> [ERROR] ---> (User click "Thử lại") ---> [LOADING]
                                     |
                                     +--- (API timeout) ---> [ERROR]

[LOADED] ---> (User thay đổi filter) ---> [REFRESHING] ---> (API success) ---> [LOADED]
                                              |
                                              +--- (API error) ---> [LOADED] + toast warning

12.2. Trạng thái Export ​

[IDLE] ---> (User click Export) ---> [EXPORTING] ---> (Success) ---> [IDLE] + download file
                                         |
                                         +--- (Error) ---> [IDLE] + toast error

13. Notification List ​

14. Error / Warning Message Handling ​

15. Ma trận truy xuất (Traceability Matrix) ​

16. Quy tắc nghiệp vụ (Business Rules) ​

17. Ràng buộc & Giả định (Constraints / Assumptions) ​

17.1. Ràng buộc ​

17.2. Giả định ​

18. Phụ lục (Appendix) ​

18.1. Mapping Dashboard -> Module nguồn ​

18.2. Mẫu file export PDF ​

┌─────────────────────────────────────────┐
│ GOTRACE — BÁO CÁO DASHBOARD TXNG       │
│ Tên: [Tên Dashboard]                    │
│ Ngày xuất: [dd/MM/yyyy HH:mm]           │
│ Người xuất: [Họ tên] ([Role])           │
│ Bộ lọc: [Năm, Quý, Loại SP, ...]       │
├─────────────────────────────────────────┤
│                                         │
│ ┌────┐ ┌────┐ ┌────┐ ┌────┐            │
│ │KPI1│ │KPI2│ │KPI3│ │KPI4│            │
│ └────┘ └────┘ └────┘ └────┘            │
│                                         │
│ ┌───────────────────────────────┐       │
│ │ Biểu đồ 1 (screenshot)       │       │
│ └───────────────────────────────┘       │
│                                         │
│ ┌───────────────────────────────┐       │
│ │ Biểu đồ 2 (screenshot)       │       │
│ └───────────────────────────────┘       │
│                                         │
│ ┌───────────────────────────────┐       │
│ │ Bảng dữ liệu chi tiết        │       │
│ └───────────────────────────────┘       │
│                                         │
│ Trang [x/n]                             │
└─────────────────────────────────────────┘

18.3. Mã màu stat cards ​

18.4. Quan hệ với Dashboard hiện có ​

18.5. 8 tiêu chí Radar Chart tuân thủ TCVN 12850:2019 (DB-08) ​

Hết tài liệu SRS TXNG-F30 v1.0