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-F45 -- Cấu hình Gói Dịch vụ ​

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 Cấu hình Gói Dịch vụ (TXNG-F45) trong Module Quản trị Nền tảng của hệ thống GoTrace.

Chức năng cho phép Quản trị viên Nền tảng (PLATFORM_ADMIN) cấu hình động danh mục các gói dịch vụ thương mại mà GoTrace bán cho Doanh nghiệp (DN), theo bảng giá gốc docs/sale/Sale_Pricing.md (hiệu lực 01/06/2026). Mỗi gói định nghĩa đầy đủ:

1. Nhóm phí: phí khởi tạo (setup_fee), phí chuẩn hóa và liên kết (standardization_fee), phí duy trì hệ thống theo năm (maintenance_fee_year).
2. Quota / giới hạn: sản lượng mã QR/năm (qr_quota_year), số sản phẩm tối đa (max_products), số người dùng tối đa (max_users), dung lượng lưu trữ (storage_gb).
3. Phí phát sinh vượt hạn mức: phí mỗi mã QR tăng thêm (extra_qr_fee), phí mỗi mã sản phẩm tăng thêm (extra_product_fee).
4. Đào tạo & hỗ trợ: hình thức đào tạo (training_type), số lần Onsite (training_onsite_count), số ngày hỗ trợ go-live (go_live_support_days), cam kết SLA (sla_support).
5. Ma trận tính năng (features JSONB): so sánh chi tiết tính năng giữa 4 gói theo Phụ lục của Sale_Pricing.
6. Chính sách chiết khấu duy trì: chiết khấu 2 năm (discount_2y_percent, mặc định 10%), 3 năm (discount_3y_percent, mặc định 20%), áp dụng trước VAT.

Gói dịch vụ được cấu hình tại F45 là nguồn dữ liệu chuẩn (canonical) cho luồng Kích hoạt & Vòng đời Dịch vụ DN (TXNG-F46): khi kích hoạt một DN, hệ thống chốt bản sao (plan_snapshot) cấu hình gói tại thời điểm kích hoạt để đảm bảo tính bất biến của hợp đồng.

Tài liệu là cơ sở cho đội ngũ phát triển (Developer), kiểm thử (QA), DBA và Business Analyst để triển khai chức năng phù hợp với BRD tương ứng (docs/brd/BRD_TXNG-F45_Cau_Hinh_Goi_Dich_Vu.md).

Phạm vi loại trừ (Out of scope): TXNG-F45 là module vận hành thương mại nội bộ, KHÔNG phát sinh Critical Tracking Event (CTE) / Key Data Element (KDE) truy xuất nguồn gốc. Việc kích hoạt, dùng thử, gia hạn, chấm dứt dịch vụ và chặn đăng nhập thuộc phạm vi TXNG-F46.

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

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

Ghi chú phân quyền: Mọi endpoint ghi (POST/PUT/PATCH) đều đi qua prefix /api/v1/admin/... và AdminGuard chặn theo ROLE.ADMIN. Endpoint đọc công khai GET /api/v1/service-plans/public không yêu cầu quyền admin nhưng chỉ trả về gói công khai đang bán.

1.4. Tham chiếu UI/UX ​

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

2.1. Luồng nghiệp vụ tổng quan ​

┌──────────────────────────────────────────────────────────────────────────────────────┐
│                    LUỒNG CẤU HÌNH GÓI DỊCH VỤ (F45)                                  │
├──────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                      │
│  ╔══════════════════════════════════════════════════════════════════════════════╗  │
│  ║               SEED KHỞI TẠO: 4 GÓI CANONICAL (Migration)                     ║  │
│  ╚══════════════════════════════════════════════════════════════════════════════╝  │
│    ┌───────────────┐  ┌────────────────┐  ┌───────────────┐  ┌────────────────┐    │
│    │ PKG_BASIC     │  │ PKG_STANDARD   │  │ PKG_LINKED    │  │ PKG_ENTERPRISE │    │
│    │ Gói Cơ bản    │  │ Gói Chuẩn hóa  │  │ Gói Liên kết  │  │ Gói Quản trị   │    │
│    │ status=ACTIVE │  │ status=ACTIVE  │  │ status=ACTIVE │  │ status=ACTIVE  │    │
│    └───────────────┘  └────────────────┘  └───────────────┘  └────────────────┘    │
│                                    │                                                  │
│  ════════════════════════════════════════════════════════════════════════════════  │
│                                    ▼                                                  │
│    ┌────────────────────────────────────────────────────────────────────────┐      │
│    │ PLATFORM_ADMIN mở SCR-F45-01 (Danh sách gói)                            │      │
│    │ • Xem/tìm kiếm/lọc theo trạng thái, từ khóa                             │      │
│    └───────────────────────────────┬────────────────────────────────────────┘      │
│                                     │                                                │
│         ┌───────────────────────────┼───────────────────────────┐                   │
│         ▼                           ▼                           ▼                   │
│  ┌─────────────┐            ┌─────────────┐            ┌─────────────────┐          │
│  │ TẠO GÓI MỚI │            │ SỬA GÓI     │            │ ĐỔI TRẠNG THÁI  │          │
│  │ (UC-F45-01) │            │ (UC-F45-02) │            │ (UC-F45-03)     │          │
│  │ SCR-F45-02  │            │ SCR-F45-02  │            │ SCR-F45-01/03   │          │
│  │ status=DRAFT│            │ • tăng      │            │ DRAFT→ACTIVE    │          │
│  │             │            │   version   │            │ ACTIVE⇄DEPRECAT │          │
│  └──────┬──────┘            └──────┬──────┘            └────────┬────────┘          │
│         │                          │                           │                    │
│         └──────────────────────────┼───────────────────────────┘                    │
│                                     ▼                                                │
│    ┌────────────────────────────────────────────────────────────────────────┐      │
│    │ AUDIT: mỗi thao tác ghi service_plans.updated_by + version++ (khi sửa   │      │
│    │ phí/quota); soft delete deleted_at; validate plan_code immutable        │      │
│    └───────────────────────────────┬────────────────────────────────────────┘      │
│                                     ▼                                                │
│    ┌────────────────────────────────────────────────────────────────────────┐      │
│    │ TIÊU THỤ: TXNG-F46 đọc gói status=ACTIVE để kích hoạt DN                │      │
│    │ → chốt plan_snapshot (bất biến); gói DEPRECATED KHÔNG được chọn mới     │      │
│    │ nhưng DN đang dùng vẫn giữ snapshot cũ                                  │      │
│    └────────────────────────────────────────────────────────────────────────┘      │
│                                                                                      │
└──────────────────────────────────────────────────────────────────────────────────────┘

2.2. Diễn giải luồng ​

3. Phân loại / Trạng thái ​

3.1. Trạng thái gói dịch vụ (SERVICE_PLAN_STATUS — Canonical §2.45) ​

3.2. Mã gói canonical (SERVICE_PLAN_CODE — Canonical §2.44) ​

plan_code là dữ liệu động; admin có thể thêm gói mới với mã UPPER_SNAKE_CASE bắt đầu bằng PKG_. 4 mã trên là seed canonical bắt buộc.

3.3. Hình thức đào tạo (Training Type) ​

3.4. Chu kỳ thanh toán (Billing Cycle) ​

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

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

5.1. SCR-F45-01: Danh sách Gói Dịch vụ ​

Summary cards (đếm theo trạng thái):

Thanh công cụ (Toolbar):

Bảng dữ liệu (TableWrapper):

Phân trang: 10 / 20 / 50 / 100 bản ghi/trang. Response envelope { page, page_size, total_items, total_pages }.

5.2. SCR-F45-02: Tạo / Sửa Gói Dịch vụ ​

Card 1: Thông tin định danh ​

Card 2: Cấu hình phí (Fees — VND, chưa gồm VAT) ​

Tổng phí năm đầu (hiển thị read-only, computed): setup_fee + standardization_fee + maintenance_fee_year. Từ năm 2: maintenance_fee_year.

Card 3: Cấu hình quota / giới hạn ​

Card 4: Đào tạo & hỗ trợ ​

Card 5: Ma trận tính năng (features JSONB) ​

JSON schema features (giá trị mỗi khóa ∈ {true, false, "OPTIONAL", "CUSTOM"} hoặc số/chuỗi mô tả mức):

Card 6: Chính sách chiết khấu & thanh toán ​

Trường hệ thống (read-only, hiển thị ở SCR-F45-03) ​

Hành động Footer ​

• Nút "Lưu" (Primary): Validate + tạo/cập nhật gói (status giữ nguyên; gói mới = DRAFT).
• Nút "Hủy" (Tertiary): Đóng form không lưu.

5.3. SCR-F45-03: Chi tiết Gói Dịch vụ ​

Header Info Box (read-only): plan_code lớn + badge trạng thái màu; plan_name; tổng phí năm đầu; version; người tạo/cập nhật + thời điểm.

Tabs:

• Tab "Thông tin": Hiển thị toàn bộ field từ SCR-F45-02 read-only (định danh, phí, quota, đào tạo, chiết khấu).
• Tab "Ma trận tính năng" ({FeatureMatrixTable}): Render features JSONB thành bảng dễ đọc (✔ / — / Tùy chọn / Tùy chỉnh).
• Tab "Lịch sử version" ({PlanVersionTimeline}): Hiển thị các mốc thay đổi (version, người sửa, thời điểm, tóm tắt trường thay đổi) — nguồn từ updated_by + version và log audit.

Action buttons (theo status + role PLATFORM_ADMIN):

6. Danh sách Use Case ​

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

UC-F45-01: Tạo gói dịch vụ ​

Mô tả: PLATFORM_ADMIN tạo một gói dịch vụ mới với cấu hình đầy đủ phí, quota, tính năng.

Tiền điều kiện:

• User đã đăng nhập, role = ROLE.ADMIN (PLATFORM_ADMIN), qua AdminGuard.
• plan_code dự kiến chưa tồn tại (trong các bản ghi chưa xóa mềm).

Hậu điều kiện:

• Một bản ghi service_plans ở status = DRAFT, version = 1 được tạo.

Alternative Flow:

UC-F45-02: Sửa gói dịch vụ ​

Tiền điều kiện: User là PLATFORM_ADMIN; gói tồn tại, chưa xóa mềm.

Hậu điều kiện: Cấu hình cập nhật; nếu thay đổi phí/quota → version++; ghi audit; plan_code không đổi.

Alternative Flow:

UC-F45-03: Đổi trạng thái gói ​

Tiền điều kiện: User là PLATFORM_ADMIN; transition hợp lệ theo Section 12.

Hậu điều kiện: status cập nhật; ghi audit.

Alternative Flow:

UC-F45-04: Xem danh sách / chi tiết gói ​

8. Thiết kế Database Schema ​

8.1. ER Diagram ​

┌─────────────────────────────────┐         ┌─────────────────────────────────┐
│           users                  │         │          companies (F01)         │
│  id (BIGINT, PK)                │         │  id (BIGINT, PK)                │
│  role (INT)                     │         │  status (INT) ── mirror F46      │
└──────────┬──────────────────────┘         └──────────┬──────────────────────┘
           │ 1:N (created_by, updated_by)              │ 1:N (qua F46)
           ▼                                            │
┌──────────────────────────────────────────────────────┼───────────────────────┐
│                       service_plans (F45)             │                       │
│  id (BIGSERIAL, PK)                                   │                       │
│  plan_code (VARCHAR 30) ── UNIQUE WHERE deleted_at IS NULL                    │
│  plan_name (VARCHAR 150)                                                      │
│  target_audience (TEXT)                                                       │
│  setup_fee, standardization_fee, maintenance_fee_year (NUMERIC 14,2)          │
│  qr_quota_year, max_products, max_users, storage_gb (INT)                     │
│  extra_qr_fee (NUMERIC 10,2), extra_product_fee (NUMERIC 12,2)                │
│  training_type (VARCHAR 20), training_onsite_count (INT)                      │
│  go_live_support_days (INT), sla_support (VARCHAR 100)                        │
│  features (JSONB)                                                             │
│  discount_2y_percent, discount_3y_percent (NUMERIC 5,2)                       │
│  billing_cycle (VARCHAR 20), currency (VARCHAR 10)                            │
│  status (VARCHAR 20) ── DRAFT / ACTIVE / DEPRECATED                           │
│  display_order (INT), is_public (BOOLEAN), effective_from (DATE)              │
│  version (INT)                                                                │
│  created_by, updated_by (BIGINT FK → users)                                  │
│  created_at, updated_at (TIMESTAMPTZ), deleted_at (TIMESTAMPTZ NULL)          │
└──────────────────────────────────┬────────────────────────────────────────────┘
                                    │ 1:N (tham chiếu qua F46 khi kích hoạt)
                                    ▼
                    ┌──────────────────────────────────────────┐
                    │  company_subscriptions (F46)             │
                    │  plan_id (BIGINT FK → service_plans)     │
                    │  plan_code (VARCHAR 30) ── snapshot      │
                    │  plan_snapshot (JSONB) ── chốt cấu hình  │
                    └──────────────────────────────────────────┘

8.2. Mô tả bảng ​

Bảng service_plans ​

8.3. Indexes ​

8.4. Migration SQL ​

-- =====================================================================
-- Migration: TXNG-F45 — service_plans (Cấu hình Gói Dịch vụ)
-- =====================================================================

CREATE TABLE IF NOT EXISTS service_plans (
    id                     BIGSERIAL     PRIMARY KEY,
    plan_code              VARCHAR(30)   NOT NULL,
    plan_name              VARCHAR(150)  NOT NULL,
    target_audience        TEXT,
    setup_fee              NUMERIC(14,2) NOT NULL DEFAULT 0 CHECK (setup_fee >= 0),
    standardization_fee    NUMERIC(14,2) NOT NULL DEFAULT 0 CHECK (standardization_fee >= 0),
    maintenance_fee_year   NUMERIC(14,2) NOT NULL DEFAULT 0 CHECK (maintenance_fee_year >= 0),
    qr_quota_year          INT           NOT NULL DEFAULT 0 CHECK (qr_quota_year >= 0),
    max_products           INT           NOT NULL DEFAULT 0 CHECK (max_products >= 0),
    max_users              INT           NOT NULL DEFAULT 0 CHECK (max_users >= 0),
    storage_gb             INT           NOT NULL DEFAULT 0 CHECK (storage_gb >= 0),
    extra_qr_fee           NUMERIC(10,2) NOT NULL DEFAULT 0 CHECK (extra_qr_fee >= 0),
    extra_product_fee      NUMERIC(12,2) NOT NULL DEFAULT 0 CHECK (extra_product_fee >= 0),
    training_type          VARCHAR(20)   NOT NULL DEFAULT 'ONLINE'
                             CHECK (training_type IN ('ONLINE','ONSITE')),
    training_onsite_count  INT           NOT NULL DEFAULT 0 CHECK (training_onsite_count >= 0),
    go_live_support_days   INT           NOT NULL DEFAULT 0 CHECK (go_live_support_days >= 0),
    sla_support            VARCHAR(100),
    features               JSONB         NOT NULL DEFAULT '{}'::jsonb,
    discount_2y_percent    NUMERIC(5,2)  NOT NULL DEFAULT 10 CHECK (discount_2y_percent BETWEEN 0 AND 100),
    discount_3y_percent    NUMERIC(5,2)  NOT NULL DEFAULT 20 CHECK (discount_3y_percent BETWEEN 0 AND 100),
    billing_cycle          VARCHAR(20)   NOT NULL DEFAULT 'ANNUAL' CHECK (billing_cycle IN ('ANNUAL')),
    currency               VARCHAR(10)   NOT NULL DEFAULT 'VND',
    status                 VARCHAR(20)   NOT NULL DEFAULT 'DRAFT'
                             CHECK (status IN ('DRAFT','ACTIVE','DEPRECATED')),
    display_order          INT           NOT NULL DEFAULT 0,
    is_public              BOOLEAN       NOT NULL DEFAULT true,
    effective_from         DATE,
    version                INT           NOT NULL DEFAULT 1,
    created_by             BIGINT        REFERENCES users(id),
    updated_by             BIGINT        REFERENCES users(id),
    created_at             TIMESTAMPTZ   NOT NULL DEFAULT NOW(),
    updated_at             TIMESTAMPTZ   NOT NULL DEFAULT NOW(),
    deleted_at             TIMESTAMPTZ
);

CREATE UNIQUE INDEX IF NOT EXISTS uq_service_plans_code
    ON service_plans (plan_code) WHERE deleted_at IS NULL;
CREATE INDEX IF NOT EXISTS idx_service_plans_status
    ON service_plans (status);
CREATE INDEX IF NOT EXISTS idx_service_plans_display_order
    ON service_plans (display_order);

-- =====================================================================
-- SEED: 4 gói canonical theo docs/sale/Sale_Pricing.md (hiệu lực 01/06/2026)
-- =====================================================================

INSERT INTO service_plans (
    plan_code, plan_name, target_audience,
    setup_fee, standardization_fee, maintenance_fee_year,
    qr_quota_year, max_products, max_users, storage_gb,
    extra_qr_fee, extra_product_fee,
    training_type, training_onsite_count, go_live_support_days, sla_support,
    features, discount_2y_percent, discount_3y_percent,
    billing_cycle, currency, status, display_order, is_public,
    effective_from, version
) VALUES
-- ----- PKG_BASIC — Gói Cơ bản -----
(
    'PKG_BASIC', 'Gói Cơ bản',
    'Dành cho chủ thể OCOP, HTX, hộ kinh doanh cần số hóa dữ liệu cơ bản, QR truy xuất, chứng nhận, vùng nguyên liệu và trang truy xuất công khai.',
    2000000, 3000000, 4500000,
    5000, 10, 2, 1,
    150, 490000,
    'ONLINE', 0, 7, 'Trong giờ hành chính',
    '{
        "company_profile": true,
        "product_catalog_standardization": true,
        "material_input_standardization": true,
        "certification_standardization": true,
        "growing_area_standardization": true,
        "customer_agent_standardization": true,
        "staff_standardization": true,
        "production_process_standardization": false,
        "product_lot_code_consulting": false,
        "qr_traceability": true,
        "public_trace_page": "STANDARD",
        "qr_scan_statistics": true,
        "supply_chain_linking": false,
        "product_recall_management": false,
        "operation_dashboard": true,
        "activity_log": false,
        "api_integration": false,
        "blockchain": false
    }'::jsonb,
    10, 20, 'ANNUAL', 'VND', 'ACTIVE', 1, true, DATE '2026-06-01', 1
),
-- ----- PKG_STANDARD — Gói Chuẩn hóa -----
(
    'PKG_STANDARD', 'Gói Chuẩn hóa',
    'Dành cho Doanh nghiệp cần chuẩn hóa dữ liệu sản phẩm, quy trình sản xuất, lô, chứng nhận, kiểm nghiệm và QR truy xuất trên một hệ thống thống nhất.',
    3000000, 5000000, 9500000,
    20000, 50, 5, 3,
    120, 490000,
    'ONLINE', 0, 15, '24/7',
    '{
        "company_profile": true,
        "product_catalog_standardization": true,
        "material_input_standardization": true,
        "certification_standardization": true,
        "growing_area_standardization": true,
        "customer_agent_standardization": true,
        "staff_standardization": true,
        "production_process_standardization": true,
        "product_lot_code_consulting": true,
        "qr_traceability": true,
        "public_trace_page": "STANDARD",
        "qr_scan_statistics": true,
        "supply_chain_linking": false,
        "product_recall_management": false,
        "operation_dashboard": true,
        "activity_log": false,
        "api_integration": false,
        "blockchain": "OPTIONAL"
    }'::jsonb,
    10, 20, 'ANNUAL', 'VND', 'ACTIVE', 2, true, DATE '2026-06-01', 1
),
-- ----- PKG_LINKED — Gói Liên kết -----
(
    'PKG_LINKED', 'Gói Liên kết',
    'Dành cho Doanh nghiệp có nhiều nhà cung cấp, đối tác phân phối, lô sản xuất cần liên kết dữ liệu để truy xuất toàn bộ chuỗi cung ứng.',
    6000000, 8000000, 25500000,
    100000, 150, 20, 10,
    100, 490000,
    'ONSITE', 1, 30, 'Ưu tiên 24/7',
    '{
        "company_profile": true,
        "product_catalog_standardization": true,
        "material_input_standardization": true,
        "certification_standardization": true,
        "growing_area_standardization": true,
        "customer_agent_standardization": true,
        "staff_standardization": true,
        "production_process_standardization": true,
        "product_lot_code_consulting": true,
        "qr_traceability": true,
        "public_trace_page": "STANDARD",
        "qr_scan_statistics": "CUSTOM",
        "supply_chain_linking": true,
        "product_recall_management": true,
        "operation_dashboard": "CUSTOM",
        "activity_log": true,
        "api_integration": "BASIC",
        "blockchain": "OPTIONAL"
    }'::jsonb,
    10, 20, 'ANNUAL', 'VND', 'ACTIVE', 3, true, DATE '2026-06-01', 1
),
-- ----- PKG_ENTERPRISE — Gói Quản trị -----
(
    'PKG_ENTERPRISE', 'Gói Quản trị',
    'Dành cho Doanh nghiệp xuất khẩu, DN quy mô lớn (BigCorp) hoặc doanh nghiệp cần dashboard, cảnh báo, phân quyền, mở rộng API và tích hợp nâng cao.',
    9000000, 15000000, 85000000,
    500000, 500, 50, 50,
    80, 490000,
    'ONSITE', 3, 60, 'Ưu tiên 24/7',
    '{
        "company_profile": true,
        "product_catalog_standardization": true,
        "material_input_standardization": true,
        "certification_standardization": true,
        "growing_area_standardization": true,
        "customer_agent_standardization": true,
        "staff_standardization": true,
        "production_process_standardization": true,
        "product_lot_code_consulting": true,
        "qr_traceability": true,
        "public_trace_page": "CUSTOM",
        "qr_scan_statistics": "CUSTOM",
        "supply_chain_linking": true,
        "product_recall_management": true,
        "operation_dashboard": "CUSTOM",
        "activity_log": true,
        "api_integration": "CUSTOM",
        "blockchain": "OPTIONAL"
    }'::jsonb,
    10, 20, 'ANNUAL', 'VND', 'ACTIVE', 4, true, DATE '2026-06-01', 1
)
ON CONFLICT DO NOTHING;

Đối chiếu tổng phí năm đầu (setup + standardization + maintenance): PKG_BASIC = 9.500.000; PKG_STANDARD = 17.500.000; PKG_LINKED = 39.500.000; PKG_ENTERPRISE = 109.000.000 VND — khớp 100% Sale_Pricing.md. Từ năm 2 = maintenance_fee_year: 4.500.000 / 9.500.000 / 25.500.000 / 85.000.000 VND.

9. Thiết kế API ​

9.1. Danh sách endpoint ​

9.2. Chi tiết API ​

9.2.1. GET /api/v1/admin/service-plans ​

Query params: status (DRAFT/ACTIVE/DEPRECATED), keyword (≥ 2 ký tự, match plan_code/plan_name), page (default 1), page_size (default 20, ∈ {10,20,50,100}).

Response 200:

{
  "success": true,
  "statusCode": 200,
  "data": {
    "items": [
      {
        "id": 1,
        "plan_code": "PKG_BASIC",
        "plan_name": "Gói Cơ bản",
        "setup_fee": 2000000,
        "standardization_fee": 3000000,
        "maintenance_fee_year": 4500000,
        "first_year_total": 9500000,
        "qr_quota_year": 5000,
        "max_products": 10,
        "status": "ACTIVE",
        "display_order": 1,
        "version": 1
      }
    ],
    "pagination": { "page": 1, "page_size": 20, "total_items": 4, "total_pages": 1 }
  }
}

9.2.2. POST /api/v1/admin/service-plans ​

Request:

{
  "plan_code": "PKG_PREMIUM",
  "plan_name": "Gói Cao cấp",
  "target_audience": "DN chuỗi đa quốc gia",
  "setup_fee": 12000000,
  "standardization_fee": 18000000,
  "maintenance_fee_year": 120000000,
  "qr_quota_year": 1000000,
  "max_products": 1000,
  "max_users": 100,
  "storage_gb": 100,
  "extra_qr_fee": 60,
  "extra_product_fee": 490000,
  "training_type": "ONSITE",
  "training_onsite_count": 5,
  "go_live_support_days": 90,
  "sla_support": "Ưu tiên 24/7",
  "features": { "company_profile": true, "qr_traceability": true, "api_integration": "CUSTOM" },
  "discount_2y_percent": 10,
  "discount_3y_percent": 20,
  "billing_cycle": "ANNUAL",
  "display_order": 5,
  "is_public": true,
  "effective_from": "2026-07-01"
}

Response 201:

{ "success": true, "statusCode": 201, "data": { "id": 5, "plan_code": "PKG_PREMIUM", "status": "DRAFT", "version": 1 } }

Response 409 (trùng mã):

{ "success": false, "statusCode": 409, "error": { "code": "E-F45-001", "message": "Mã gói đã tồn tại" } }

9.2.3. GET /api/v1/admin/service-plans/:id ​

Response 200: trả về toàn bộ field service_plans (kể cả features, discount_*, audit fields, first_year_total computed).

Response 404:

{ "success": false, "statusCode": 404, "error": { "code": "E-F45-007", "message": "Không tìm thấy gói dịch vụ" } }

9.2.4. PUT /api/v1/admin/service-plans/:id ​

Request: như POST nhưng KHÔNG chấp nhận đổi plan_code (nếu gửi khác giá trị gốc → 400 E-F45-002).

Response 200:

{ "success": true, "statusCode": 200, "data": { "id": 1, "plan_code": "PKG_BASIC", "version": 2 } }

Response 400 (đổi mã gói):

{ "success": false, "statusCode": 400, "error": { "code": "E-F45-002", "message": "Không được thay đổi mã gói sau khi tạo" } }

9.2.5. PATCH /api/v1/admin/service-plans/:id/status ​

Request:

{ "status": "ACTIVE" }

Response 200:

{ "success": true, "statusCode": 200, "data": { "id": 1, "status": "ACTIVE" } }

Response 400 (transition không hợp lệ):

{ "success": false, "statusCode": 400, "error": { "code": "E-F45-005", "message": "Chuyển trạng thái không hợp lệ" } }

9.2.6. DELETE /api/v1/admin/service-plans/:id ​

Response 200:

{ "success": true, "statusCode": 200, "data": { "id": 5, "deleted_at": "2026-07-01T10:30:00Z" } }

Response 409 (đang có DN dùng):

{ "success": false, "statusCode": 409, "error": { "code": "E-F45-006", "message": "Không thể xóa gói đang có doanh nghiệp sử dụng" } }

9.2.7. GET /api/v1/service-plans/public ​

Response 200: danh sách gói status = ACTIVE AND is_public = true, chỉ trả trường công khai (plan_code, plan_name, target_audience, phí, quota, features, discount_, sla_support, training_), KHÔNG trả created_by/updated_by/deleted_at.

10. Test Cases cho QA ​

11. Acceptance Criteria ​

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

SERVICE_PLAN_STATUS state machine:

                    ┌─────────┐
        (tạo mới)   │  DRAFT  │
        ──────────► │         │
                    └────┬────┘
                         │ Kích hoạt (UC-F45-03)
                         ▼
                    ┌─────────┐   Ngừng bán    ┌──────────────┐
                    │ ACTIVE  │ ─────────────► │ DEPRECATED   │
                    │         │ ◄───────────── │              │
                    └─────────┘    Mở lại      └──────────────┘

Transition KHÔNG hợp lệ (chặn, E-F45-005): DRAFT→DEPRECATED, ACTIVE→DRAFT, DEPRECATED→DRAFT, và mọi self-transition.

Xóa mềm (deleted_at) áp dụng cho DRAFT và DEPRECATED khi chưa DN nào dùng; không phải một status mà là cờ soft delete độc lập.

13. Notification List ​

Module vận hành thương mại nội bộ: notification chỉ gửi in-app cho nhóm PLATFORM_ADMIN. Không gửi cho DN (DN chỉ xem bảng giá public).

14. Error / Warning Message Handling ​

14.1. Error (chặn hành động) ​

14.2. Warning (cho phép tiếp tục) ​

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 ​

1. Module vận hành thương mại: TXNG-F45 KHÔNG phát sinh Critical Tracking Event (CTE) / Key Data Element (KDE) truy xuất nguồn gốc. Không áp dụng TCVN 12850:2019 / FDA FSMA 204 / GS1 EPCIS cho chức năng này.
2. Phân quyền cứng: Toàn bộ thao tác ghi chỉ dành cho PLATFORM_ADMIN (impl ROLE.ADMIN = numeric 1), chặn qua AdminGuard, prefix /api/v1/admin/.... ENTERPRISE_ADMIN chỉ xem bảng giá public.
3. Tính bất biến hợp đồng: Thay đổi cấu hình gói (kể cả giá) KHÔNG tác động ngược tới DN đang dùng — F46 đã chốt plan_snapshot tại thời điểm kích hoạt.
4. Không multi-tenant scope trong F45: service_plans là bảng cấu hình nền tảng dùng chung, KHÔNG có company_id. Ràng buộc multi-tenant chỉ áp dụng ở F46 (bảng company_subscriptions lọc theo company_id).
5. Tiền tệ: v1.0 chỉ hỗ trợ VND; currency để mở rộng tương lai. Giá chưa gồm VAT.
6. Chu kỳ thanh toán: v1.0 chỉ ANNUAL.
7. SLA hiệu năng: Page load ≤ 2 giây; API read (list/detail) ≤ 500ms; API write ≤ 1 giây.

17.2. Giả định ​

1. Bảng users và companies (F01) đã tồn tại; FK created_by/updated_by → users(id).
2. Migration seed 4 gói chạy 1 lần khi khởi tạo hệ thống (idempotent qua ON CONFLICT DO NOTHING + unique index).
3. F46 sẽ đọc service_plans khi kích hoạt; ràng buộc "không xóa gói đang dùng" dựa trên tồn tại bản ghi company_subscriptions.plan_id.
4. Số liệu Sale_Pricing.md (19/05/2026, hiệu lực 01/06/2026) là nguồn chuẩn; khi bảng giá đổi, admin cập nhật qua UI (không cần migration mới).
5. Việc tăng version chỉ là số nguyên đơn giản (không tạo bản ghi lịch sử version riêng trong v1.0); lịch sử chi tiết trước/sau thuộc phạm vi audit log chung.

18. Phụ lục (Appendix) ​

18.1. Bảng phí 4 gói (đối chiếu Sale_Pricing.md) ​

Chiết khấu duy trì: 2 năm giảm 10%, 3 năm giảm 20% (trước VAT). Báo giá chưa gồm VAT, chưa gồm chi phí in tem vật lý và phí bên thứ ba.

18.2. Ma trận so sánh tính năng 4 gói (Sale_Pricing Phụ lục) ​

Quy ước: ✔ = có · — = không · Tùy chọn = mua thêm · Tùy chỉnh = mức cao hơn / cấu hình riêng.

18.3. Công thức tính phí liên quan ​

• Tổng phí năm đầu = setup_fee + standardization_fee + maintenance_fee_year.
• Phí từ năm 2 = maintenance_fee_year (× (1 − chiết khấu kỳ) nếu ký nhiều năm).
• Phí duy trì 2 năm = maintenance_fee_year × 2 × (1 − discount_2y_percent/100), trước VAT.
• Phí duy trì 3 năm = maintenance_fee_year × 3 × (1 − discount_3y_percent/100), trước VAT.
• Phí vượt QR = (số QR dùng − qr_quota_year − bonus_qr_quota) × extra_qr_fee (chỉ tính phần dương; bonus_* do F46 quản lý).
• Phí vượt SP = (số SP − max_products − bonus_max_products) × extra_product_fee, cộng vào phí duy trì kỳ tiếp.

Hết tài liệu SRS TXNG-F45.