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-F46 -- Kích hoạt & Vòng đời Dịch vụ Doanh nghiệp ​

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 Kích hoạt & Vòng đời Dịch vụ Doanh nghiệp (TXNG-F46) trong Module Vận hành Nền tảng (Platform Operations) của hệ thống GoTrace.

Chức năng cho phép Quản trị viên Nền tảng GoTrace (PLATFORM_ADMIN) thực hiện toàn bộ nghiệp vụ thương mại vận hành trên một Doanh nghiệp (DN) khách hàng:

1. Tạo yêu cầu kích hoạt dịch vụ cho một DN: chọn DN chưa-active, chọn gói dịch vụ (service_plans — TXNG-F45), nhập mã hợp đồng, thời hạn (term_months), số ngày dùng thử (trial_days), bonus QR/sản phẩm, upload hồ sơ (hợp đồng/MOU/phụ lục).
2. Kích hoạt dịch vụ: chuyển DRAFT → TRIAL (hoặc → ACTIVE khi trial_days = 0), chốt plan_snapshot (phí/quota/features tại thời điểm kích hoạt).
3. Quản lý vòng đời: chuyển trial sang chính thức (TRIAL → ACTIVE), gia hạn (EXPIRED → ACTIVE, extend paid_until_date), chấm dứt (→ TERMINATED, bắt buộc lý do), mở lại (REACTIVATE).
4. Login gate (login gate): chặn đăng nhập của mọi user thuộc DN khi dịch vụ ở trạng thái EXPIRED/TERMINATED; đánh giá hết hạn theo kiểu lazy khi đăng nhập (không cần cron ở v1).

Điểm cốt lõi khác biệt so với các module nghiệp vụ khác: đây là state machine 5 trạng thái (SERVICE_STATUS) với login gate tác động trực tiếp đến AuthService.login() + JwtStrategy.validate(), và nhật ký append-only immutable (subscription_histories) được ghi trong cùng transaction với mọi thay đổi trạng thái, kèm invalidate cache user_perms:{userId} và mirror companies.status.

Đây là module vận hành thương mại nội bộ GoTrace, KHÔNG phát sinh CTE/KDE truy xuất (nêu rõ trong Section 17 — Ràng buộc). Nguồn sự thật (source of truth) của trạng thái dịch vụ là company_subscriptions; companies.status chỉ là bản mirror phục vụ chặn đăng nhập nhanh.

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-F46_Kich_Hoat_Va_Vong_Doi_Dich_Vu_Doanh_Nghiep.md).

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

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

Ghi chú phân quyền: SALE_STAFF (impl ROLE.AGENT = numeric 2) không là actor trực tiếp của F46; nghiệp vụ onboard/chăm sóc KH nằm ngoài hệ thống, sale thao tác qua tài khoản PLATFORM_ADMIN. Mọi endpoint ghi/chuyển trạng thái đều chặn qua AdminGuard.

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 KÍCH HOẠT & VÒNG ĐỜI DỊCH VỤ DOANH NGHIỆP (F46)                     │
├────────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                        │
│  ╔══════════════════════════════════════════════════════════════════════════════════╗ │
│  ║          PHẦN A: PLATFORM_ADMIN TẠO & VẬN HÀNH VÒNG ĐỜI DỊCH VỤ                    ║ │
│  ╚══════════════════════════════════════════════════════════════════════════════════╝ │
│                                                                                        │
│   ┌────────────────┐   ┌──────────────────────────────┐                                │
│   │ DN đã đăng ký  │──>│ ADMIN TẠO YÊU CẦU KÍCH HOẠT   │  (UC-F46-01)                   │
│   │ (companies)    │   │ • Chọn DN (service_status ∈  │                                │
│   │ chưa có sub    │   │   {chưa có / DRAFT / EXPIRED │                                │
│   │ hoặc DRAFT     │   │   / TERMINATED})             │                                │
│   └────────────────┘   │ • Chọn plan (F45, ACTIVE)    │                                │
│                        │ • contract_code + term_months│                                │
│                        │ • trial_days (mặc định 7)    │                                │
│                        │ • bonus_qr / bonus_products  │                                │
│                        │ • upload hồ sơ (CONTRACT...) │                                │
│                        │ → status = DRAFT             │                                │
│                        │ → history {action: CREATE}   │                                │
│                        └──────────────┬───────────────┘                                │
│                                       │                                                 │
│                     ┌─────────────────┤ (UC-F46-02: SỬA — ghi history UPDATE)           │
│                     │                 ▼                                                 │
│                     │      ┌────────────────────────────┐                               │
│                     │      │ ADMIN KÍCH HOẠT (ACTIVATE)  │  (UC-F46-03)                  │
│                     │      │ • chốt plan_snapshot        │                               │
│                     │      │ • effective_qr_quota =      │                               │
│                     │      │   plan.qr + bonus_qr        │                               │
│                     │      │ • trial_end = start+trial   │                               │
│                     │      │ • trial_days>0 → TRIAL      │                               │
│                     │      │   trial_days=0 → ACTIVE     │                               │
│                     │      │ ▸ history {ACTIVATE}        │                               │
│                     │      │ ▸ mirror companies.status   │                               │
│                     │      │ ▸ invalidate user_perms     │                               │
│                     │      └───────┬──────────────┬──────┘                              │
│                     │              │              │                                     │
│                     │      trial_days>0    trial_days=0                                 │
│                     │              ▼              ▼                                     │
│                     │       ┌───────────┐   ┌───────────┐                               │
│                     │       │  TRIAL     │   │  ACTIVE    │<───────┐                     │
│                     │       │ (dùng thử) │   │ (chính     │        │ RENEW               │
│                     │       └─────┬──────┘   │  thức)     │        │ (UC-F46-05)         │
│                     │             │          └─────┬──────┘        │                     │
│                     │  chuyển ACTIVE (UC-F46-04)    │              │                     │
│                     │             └──────►──────────┘              │                     │
│                     │             │ hết hạn (lazy)  │ hết hạn(lazy) │                     │
│                     │             ▼                 ▼              │                     │
│                     │          ┌────────────────────────┐         │                     │
│                     │          │        EXPIRED          │─────────┘                     │
│                     │          │ (hết trial/hết kỳ)      │                               │
│                     │          └───────────┬────────────┘                               │
│                     │                       │                                            │
│                     │        TERMINATE (bắt buộc reason, UC-F46-06)                      │
│                     └───────────────────────┼──────────────►┌────────────────┐          │
│                                             ▼                │  TERMINATED     │          │
│                                    (từ TRIAL/ACTIVE/EXPIRED) │  (chấm dứt)     │          │
│                                                              └───────┬─────────┘          │
│                                              REACTIVATE (mở lại) ◄────┘                    │
│                                                                                        │
│  ════════════════════════════════════════════════════════════════════════════════════ │
│  ╔══════════════════════════════════════════════════════════════════════════════════╗ │
│  ║          PHẦN B: LOGIN GATE (SYSTEM — lazy-expire khi user DN đăng nhập)           ║ │
│  ╚══════════════════════════════════════════════════════════════════════════════════╝ │
│                                                                                        │
│   ┌──────────────┐   ┌──────────────────────────┐   ┌──────────────────────────────┐  │
│   │ User DN gọi  │──>│ AuthService.login()       │──>│ Đọc companies.status (mirror) │  │
│   │ POST /login  │   │ + JwtStrategy.validate()  │   │ + company_subscriptions       │  │
│   └──────────────┘   └──────────────────────────┘   └──────────────┬───────────────┘  │
│                                                                     │                    │
│         ┌───────────────────────────────────────────────────────────┤                   │
│         ▼                          ▼                                 ▼                   │
│  ┌─────────────┐          ┌──────────────────────┐        ┌──────────────────────────┐ │
│  │ EXPIRED     │          │ stored TRIAL/ACTIVE   │        │ TRIAL/ACTIVE còn hạn     │ │
│  │ hoặc        │          │ nhưng quá hạn theo    │        │ hoặc DRAFT               │ │
│  │ TERMINATED  │          │ ngày → LAZY-EXPIRE:   │        │ → CHO PHÉP đăng nhập     │ │
│  │ → 403 chặn  │          │ flip EXPIRED + history│        │ (cache user_perms 10')   │ │
│  │ (2 message) │          │ + mirror + invalidate │        └──────────────────────────┘ │
│  └─────────────┘          │ → rồi 403 chặn        │                                      │
│                           └──────────────────────┘                                      │
│                                                                                        │
└────────────────────────────────────────────────────────────────────────────────────────┘

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

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

3.1. Trạng thái dịch vụ (SERVICE_STATUS — Canonical §2.43) ​

Vòng đời sử dụng dịch vụ của một DN (company_subscriptions.service_status; mirror sang companies.status). Đánh giá "hết hạn" theo kiểu lazy khi đăng nhập (không cần cron ở v1).

Chỉ PLATFORM_ADMIN được chuyển trạng thái. Mọi transition ghi subscription_histories (§2.46) trong cùng $transaction + invalidate cache user_perms:{userId} của mọi user thuộc DN + mirror companies.status.

3.2. Bảng effective-status (lazy-evaluate theo ngày) ​

Trạng thái hiển thị/hiệu lực được tính tại thời điểm đọc (login hoặc admin mở màn hình) dựa trên stored service_status và ngày hệ thống. Nếu stored ≠ effective → thực hiện flip + ghi history (chỉ với login của user DN; màn admin chỉ hiển thị badge "quá hạn" nhắc admin, không tự flip trừ khi login trigger).

3.3. Phân loại tài liệu (Subscription Document Type — Canonical §2.47) ​

3.4. Phân loại thao tác nhật ký (Subscription History Action — Canonical §2.46) ​

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

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

5.1. SCR-F46-01: Danh sách yêu cầu kích hoạt ​

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

Thanh công cụ (Toolbar):

Bảng dữ liệu (Data Table):

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

5.2. SCR-F46-02: Tạo yêu cầu kích hoạt ​

Card 1: Chọn Doanh nghiệp ​

Card 2: Gói dịch vụ & Điều khoản ​

Card 3: Hồ sơ đính kèm (Documents) ​

Hành động Footer ​

• Nút "Lưu nháp" (Primary): INSERT company_subscriptions {service_status: DRAFT} + history {CREATE}.
• Nút "Lưu & Kích hoạt ngay" (Secondary): tạo DRAFT rồi gọi luôn UC-F46-03.
• Nút "Hủy" (Tertiary): đóng form không lưu.

5.3. SCR-F46-03: Sửa yêu cầu kích hoạt ​

Chỉ khả dụng khi service_status = DRAFT (BR-F46 — sau kích hoạt các trường điều khoản đã bị chốt qua plan_snapshot). Form giống SCR-F46-02, load data hiện tại. Khi lưu:

• Optimistic lock qua version (E-F46-007 nếu lệch).
• INSERT subscription_histories {action: UPDATE, changes_json = diff before/after} bắt buộc.
• KHÔNG cho đổi company_id (bất biến sau tạo).

5.4. SCR-F46-04: Chi tiết yêu cầu kích hoạt ​

Header Info Box (read-only):

Tabs:

• Tab "Thông tin": toàn bộ field subscription read-only + plan_snapshot (phí/quota/features đã chốt).
• Tab "Hồ sơ": gallery subscription_documents (CONTRACT/MOU/APPENDIX/OTHER), download.
• Tab "Lịch sử" ({CompanySubscriptionHistoryTab}): timeline subscription_histories (components/admin/shared/timeline.tsx) — mỗi action hiển thị: actor, action, from_status → to_status, changed_at, reason, diff changes_json.

Action buttons (theo service_status):

Dialog xác nhận theo hành động:

5.5. SCR-F46-05: Tab "Lịch sử sử dụng dịch vụ" ​

Component {CompanySubscriptionHistoryTab} nhúng vào màn chi tiết DN (/quan-ly/doanh-nghiep/[id]/chi-tiet). Dùng components/admin/shared/timeline.tsx (TimelineEvent[]).

Multi-tenant: ENTERPRISE_ADMIN/ENTERPRISE_USER chỉ thấy tab này với company_id = current_company_id (BR-F46-14). PLATFORM_ADMIN thấy mọi DN.

6. Danh sách Use Case ​

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

UC-F46-01: Tạo yêu cầu kích hoạt ​

Mô tả: PLATFORM_ADMIN tạo một yêu cầu kích hoạt dịch vụ cho DN đủ điều kiện.

Tiền điều kiện:

• User đăng nhập là PLATFORM_ADMIN (qua AdminGuard).
• DN được chọn có service_status ∈ {chưa có subscription, DRAFT, EXPIRED, TERMINATED} (BR-F46-02).
• Có ít nhất 1 gói service_plans ở status = ACTIVE.

Hậu điều kiện:

• Một bản ghi company_subscriptions {service_status: DRAFT} được tạo.
• Nếu có upload: một hoặc nhiều subscription_documents.
• Một subscription_histories {action: CREATE} được tạo (cùng transaction).
• companies.status mirror = 0 (DRAFT).

Alternative Flow:

UC-F46-02: Sửa yêu cầu kích hoạt ​

Tiền điều kiện: PLATFORM_ADMIN; subscription ở service_status = DRAFT.

Hậu điều kiện: subscription cập nhật; subscription_histories {action: UPDATE, changes_json} bắt buộc.

Alternative Flow:

UC-F46-03: Kích hoạt dịch vụ ​

Mô tả: PLATFORM_ADMIN kích hoạt subscription từ DRAFT; chốt snapshot; login gate của DN chuyển sang cho phép.

Tiền điều kiện: PLATFORM_ADMIN; subscription ở service_status = DRAFT; gói tham chiếu còn tồn tại.

Hậu điều kiện: service_status = TRIAL (hoặc ACTIVE nếu trial_days=0); plan_snapshot chốt; history {ACTIVATE}; companies.status mirror; cache user_perms invalidated.

Alternative Flow:

UC-F46-04: Chuyển sang ACTIVE ​

Tiền điều kiện: PLATFORM_ADMIN; subscription ở service_status = TRIAL.

Hậu điều kiện: service_status = ACTIVE; active_start_date + paid_until_date set; history {ACTIVATE}; mirror; invalidate cache.

Alternative Flow: service_status ≠ TRIAL → E-F46-001.

UC-F46-05: Gia hạn dịch vụ ​

Tiền điều kiện: PLATFORM_ADMIN; subscription ở service_status ∈ {ACTIVE, EXPIRED}.

Hậu điều kiện: paid_until_date extend; nếu từ EXPIRED → ACTIVE; history {RENEW}; mirror; invalidate cache.

Alternative Flow: service_status ∉ {ACTIVE, EXPIRED} → E-F46-001.

UC-F46-06: Chấm dứt dịch vụ ​

Tiền điều kiện: PLATFORM_ADMIN; subscription ở service_status ∈ {TRIAL, ACTIVE, EXPIRED}.

Hậu điều kiện: service_status = TERMINATED (bắt buộc terminate_reason); history {TERMINATE}; mirror companies.status = 4; invalidate cache → user DN bị chặn login.

Alternative Flow:

UC-F46-07: Chặn đăng nhập + lazy-expire (Login Gate) ​

Mô tả: SYSTEM chặn đăng nhập của user thuộc DN có dịch vụ EXPIRED/TERMINATED; đồng thời lazy-expire khi stored TRIAL/ACTIVE đã quá hạn theo ngày.

Tiền điều kiện: User thuộc một DN gọi POST /api/v1/auth/login (hoặc mọi request qua JwtStrategy.validate()).

Hậu điều kiện: Login bị chặn (403) nếu EXPIRED/TERMINATED; nếu lazy-expire, trạng thái flip + history + mirror + cache invalidated trong cùng transaction.

Alternative Flow:

UC-F46-08: Xem lịch sử sử dụng dịch vụ ​

Tiền điều kiện: PLATFORM_ADMIN (mọi DN) HOẶC ENTERPRISE_ADMIN/ENTERPRISE_USER (chỉ DN của mình).

Alternative Flow: DN cố xem company_id ≠ của mình → 403 "Không có quyền xem lịch sử của DN khác".

UC-F46-09: Mở lại dịch vụ (Reactivate) ​

Tiền điều kiện: PLATFORM_ADMIN; subscription ở service_status = TERMINATED.

Hậu điều kiện: service_status = TRIAL/ACTIVE; history {REACTIVATE}; mirror; invalidate cache.

8. Thiết kế Database Schema ​

8.1. ER Diagram ​

┌─────────────────────────────────┐        ┌─────────────────────────────────┐
│         companies (F01)          │        │       service_plans (F45)        │
│  id (BIGINT, PK)                │        │  id (BIGSERIAL, PK)             │
│  company_tax_code               │        │  plan_code (UNIQUE)             │
│  company_name                   │        │  plan_name                      │
│  company_email, contact_phone   │        │  setup_fee, standardization_fee │
│  status (INT) ◄── mirror         │        │  maintenance_fee_year           │
│    service_status (0..4)        │        │  qr_quota_year, max_products    │
│  sale_user_id                   │        │  features (JSONB)               │
└──────────┬──────────────────────┘        │  status (DRAFT/ACTIVE/DEPRECATED)│
           │ 1:1 (hiện hành)                └──────────┬──────────────────────┘
           │                                            │ N:1 (plan_id + snapshot)
           ▼                                            ▼
┌──────────────────────────────────────────────────────────────────────────┐
│                       company_subscriptions (F46)                         │
│  id (BIGSERIAL, PK)                                                       │
│  company_id (BIGINT, FK → companies)  ── UNIQUE WHERE deleted_at IS NULL  │
│  plan_id (BIGINT, FK → service_plans)                                     │
│  plan_code (VARCHAR 30) ── snapshot                                       │
│  contract_code (VARCHAR 100) ── UNIQUE partial                            │
│  service_status (VARCHAR 20) ── DRAFT/TRIAL/ACTIVE/EXPIRED/TERMINATED     │
│  service_start_date, trial_days, trial_end_date                          │
│  active_start_date, term_months, paid_until_date                        │
│  bonus_qr_quota, bonus_max_products                                      │
│  effective_qr_quota, effective_max_products                             │
│  plan_snapshot (JSONB) ── chốt phí/quota/features lúc kích hoạt          │
│  discount_percent                                                       │
│  activated_at/by, terminated_at/by, terminate_reason, expired_at        │
│  version (INT) ── optimistic lock                                        │
│  created_by/at, updated_by/at, deleted_at                               │
└──────┬────────────────────────────┬──────────────────────────────────────┘
       │ 1:N                        │ 1:N
       ▼                            ▼
┌───────────────────────────┐  ┌──────────────────────────────────────────┐
│  subscription_documents   │  │  subscription_histories (APPEND-ONLY)    │
│  id (BIGSERIAL, PK)       │  │  id (BIGSERIAL, PK)                       │
│  subscription_id          │  │  subscription_id (FK)                    │
│   (FK ON DELETE CASCADE)  │  │  company_id (BIGINT)                      │
│  doc_type (CONTRACT/MOU/  │  │  action (CREATE/UPDATE/ACTIVATE/RENEW/    │
│   APPENDIX/OTHER)         │  │   EXPIRE/TERMINATE/REACTIVATE)           │
│  file_name, file_url      │  │  from_status, to_status                   │
│  file_size, mime_type     │  │  changed_by, changed_at                   │
│  uploaded_by/at           │  │  changes_json (JSONB — diff before/after) │
│  deleted_at               │  │  reason, ip_address                       │
└───────────────────────────┘  │  ── IMMUTABLE (trigger chống UPDATE/DELETE)│
                               └──────────────────────────────────────────┘

8.2. Mô tả bảng ​

Bảng company_subscriptions (1 bản ghi hiện hành / DN) ​

Bảng subscription_documents ​

Bảng subscription_histories (APPEND-ONLY, immutable) ​

8.3. Indexes ​

company_subscriptions:

• UNIQUE (company_id) WHERE deleted_at IS NULL — 1 subscription hiện hành/DN (BR-F46-10)
• UNIQUE (contract_code) WHERE contract_code IS NOT NULL AND deleted_at IS NULL (BR-F46-11)
• INDEX (service_status)
• INDEX (service_start_date)
• INDEX (activated_at)
• INDEX (paid_until_date)

subscription_documents:

• INDEX (subscription_id)

subscription_histories:

• INDEX (subscription_id, changed_at DESC)
• INDEX (company_id, changed_at DESC)

companies (mirror):

• INDEX (status) — phục vụ login gate đọc nhanh

8.4. Migration SQL ​

-- =========================================================================
-- Migration: TXNG-F46 — Kích hoạt & Vòng đời Dịch vụ Doanh nghiệp
-- Depends: TXNG-F45 (service_plans), companies, users
-- =========================================================================

-- 1) company_subscriptions -----------------------------------------------
CREATE TABLE company_subscriptions (
    id                     BIGSERIAL PRIMARY KEY,
    company_id             BIGINT NOT NULL REFERENCES companies(id),
    plan_id                BIGINT NOT NULL REFERENCES service_plans(id),
    plan_code              VARCHAR(30) NOT NULL,
    contract_code          VARCHAR(100),
    service_status         VARCHAR(20) NOT NULL DEFAULT 'DRAFT'
                             CHECK (service_status IN ('DRAFT','TRIAL','ACTIVE','EXPIRED','TERMINATED')),
    service_start_date     DATE DEFAULT CURRENT_DATE,
    trial_days             INT NOT NULL DEFAULT 7 CHECK (trial_days >= 0),
    trial_end_date         DATE,
    active_start_date      DATE,
    term_months            INT CHECK (term_months IS NULL OR term_months > 0),
    paid_until_date        DATE,
    bonus_qr_quota         INT NOT NULL DEFAULT 0 CHECK (bonus_qr_quota >= 0),
    bonus_max_products     INT NOT NULL DEFAULT 0 CHECK (bonus_max_products >= 0),
    effective_qr_quota     INT,
    effective_max_products INT,
    plan_snapshot          JSONB,
    discount_percent       NUMERIC(5,2) NOT NULL DEFAULT 0 CHECK (discount_percent >= 0 AND discount_percent <= 100),
    note                   TEXT,
    activated_at           TIMESTAMPTZ,
    activated_by           BIGINT REFERENCES users(id),
    terminated_at          TIMESTAMPTZ,
    terminated_by          BIGINT REFERENCES users(id),
    terminate_reason       TEXT,
    expired_at             TIMESTAMPTZ,
    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,
    -- TERMINATED bắt buộc có lý do
    CONSTRAINT chk_terminate_reason
        CHECK (service_status <> 'TERMINATED' OR terminate_reason IS NOT NULL)
);

CREATE UNIQUE INDEX uq_company_subscriptions_company
    ON company_subscriptions (company_id) WHERE deleted_at IS NULL;
CREATE UNIQUE INDEX uq_company_subscriptions_contract
    ON company_subscriptions (contract_code)
    WHERE contract_code IS NOT NULL AND deleted_at IS NULL;
CREATE INDEX idx_company_subscriptions_status       ON company_subscriptions (service_status);
CREATE INDEX idx_company_subscriptions_start        ON company_subscriptions (service_start_date);
CREATE INDEX idx_company_subscriptions_activated    ON company_subscriptions (activated_at);
CREATE INDEX idx_company_subscriptions_paid_until   ON company_subscriptions (paid_until_date);

-- 2) subscription_documents ----------------------------------------------
CREATE TABLE subscription_documents (
    id               BIGSERIAL PRIMARY KEY,
    subscription_id  BIGINT NOT NULL REFERENCES company_subscriptions(id) ON DELETE CASCADE,
    doc_type         VARCHAR(20) NOT NULL
                       CHECK (doc_type IN ('CONTRACT','MOU','APPENDIX','OTHER')),
    file_name        VARCHAR(255) NOT NULL,
    file_url         VARCHAR(500) NOT NULL,
    file_size        BIGINT CHECK (file_size IS NULL OR file_size <= 20971520),
    mime_type        VARCHAR(100)
                       CHECK (mime_type IS NULL OR mime_type IN ('application/pdf','image/jpeg','image/png')),
    uploaded_by      BIGINT REFERENCES users(id),
    uploaded_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    deleted_at       TIMESTAMPTZ
);
CREATE INDEX idx_subscription_documents_sub ON subscription_documents (subscription_id);

-- 3) subscription_histories (APPEND-ONLY) --------------------------------
CREATE TABLE subscription_histories (
    id               BIGSERIAL PRIMARY KEY,
    subscription_id  BIGINT NOT NULL REFERENCES company_subscriptions(id),
    company_id       BIGINT NOT NULL,
    action           VARCHAR(20) NOT NULL
                       CHECK (action IN ('CREATE','UPDATE','ACTIVATE','RENEW','EXPIRE','TERMINATE','REACTIVATE')),
    from_status      VARCHAR(20),
    to_status        VARCHAR(20),
    changed_by       BIGINT REFERENCES users(id),
    changed_at       TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    changes_json     JSONB,
    reason           TEXT,
    ip_address       VARCHAR(45)
);
CREATE INDEX idx_subscription_histories_sub
    ON subscription_histories (subscription_id, changed_at DESC);
CREATE INDEX idx_subscription_histories_company
    ON subscription_histories (company_id, changed_at DESC);

-- 4) Trigger chống UPDATE/DELETE trên subscription_histories (immutable) --
CREATE OR REPLACE FUNCTION trg_block_subscription_histories_mutation()
RETURNS TRIGGER AS $$
BEGIN
    RAISE EXCEPTION 'subscription_histories is append-only (immutable audit log); % không được phép', TG_OP;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER block_subscription_histories_update
    BEFORE UPDATE ON subscription_histories
    FOR EACH ROW EXECUTE FUNCTION trg_block_subscription_histories_mutation();
CREATE TRIGGER block_subscription_histories_delete
    BEFORE DELETE ON subscription_histories
    FOR EACH ROW EXECUTE FUNCTION trg_block_subscription_histories_mutation();

-- 5) Mirror companies.status ---------------------------------------------
-- companies.status (INT, đã có sẵn) = mirror service_status:
--   DRAFT=0, TRIAL=1, ACTIVE=2, EXPIRED=3, TERMINATED=4
-- Nguồn sự thật = company_subscriptions.service_status; cập nhật cùng transaction.
COMMENT ON COLUMN companies.status IS
    'Mirror company_subscriptions.service_status (DRAFT=0,TRIAL=1,ACTIVE=2,EXPIRED=3,TERMINATED=4) — phục vụ login gate; nguồn sự thật = company_subscriptions';

-- =========================================================================
-- INSERT ví dụ: kích hoạt DN id=1001 gói PKG_STANDARD, trial 7 ngày
-- =========================================================================
-- Giả định service_plans có bản ghi PKG_STANDARD id=2 (qr_quota_year=20000, max_products=50)
INSERT INTO company_subscriptions (
    company_id, plan_id, plan_code, contract_code, service_status,
    service_start_date, trial_days, trial_end_date, term_months,
    bonus_qr_quota, bonus_max_products, effective_qr_quota, effective_max_products,
    discount_percent, created_by, created_at, updated_at
) VALUES (
    1001, 2, 'PKG_STANDARD', 'HD-2026-0001', 'DRAFT',
    '2026-07-01', 7, '2026-07-08', 12,
    0, 0, 20000, 50,
    0, 1, NOW(), NOW()
);

-- Ghi nhật ký CREATE (cùng transaction thực tế)
INSERT INTO subscription_histories (
    subscription_id, company_id, action, from_status, to_status,
    changed_by, changed_at, reason, ip_address
) VALUES (
    currval('company_subscriptions_id_seq'), 1001, 'CREATE', NULL, 'DRAFT',
    1, NOW(), 'Tạo yêu cầu kích hoạt gói Chuẩn hóa', '10.0.0.5'
);

-- Ví dụ ACTIVATE (DRAFT -> TRIAL): mirror companies.status = 1
-- UPDATE company_subscriptions SET service_status='TRIAL', plan_snapshot='{...}'::jsonb,
--     activated_at=NOW(), activated_by=1, version=version+1 WHERE id=...;
-- INSERT subscription_histories (..., action='ACTIVATE', from_status='DRAFT', to_status='TRIAL', ...);
-- UPDATE companies SET status=1 WHERE id=1001;

9. Thiết kế API ​

9.1. Danh sách endpoint ​

Tất cả endpoint quản trị dùng prefix /api/v1/admin, Bearer Token JWT, chặn qua AdminGuard (chỉ PLATFORM_ADMIN). Envelope: { success, statusCode, data }.

9.2. Chi tiết API ​

9.2.1. POST /api/v1/admin/company-subscriptions — Tạo yêu cầu ​

Request:

{
  "company_id": 1001,
  "plan_id": 2,
  "contract_code": "HD-2026-0001",
  "term_months": 12,
  "trial_days": 7,
  "service_start_date": "2026-07-01",
  "bonus_qr_quota": 0,
  "bonus_max_products": 0,
  "discount_percent": 0,
  "note": "Khách giới thiệu bởi sale A"
}

Response 201:

{
  "success": true,
  "statusCode": 201,
  "data": {
    "id": 55,
    "company_id": 1001,
    "plan_code": "PKG_STANDARD",
    "service_status": "DRAFT",
    "contract_code": "HD-2026-0001",
    "trial_end_date": "2026-07-08",
    "effective_qr_quota": 20000,
    "effective_max_products": 50,
    "version": 1
  }
}

Lỗi: 400 (E-F46-001/002/003), 409 (BR-F46-10 concurrent).

9.2.2. POST /api/v1/admin/company-subscriptions/:id/activate — Kích hoạt ​

Request: { "version": 1 } (optimistic lock; body có thể kèm active_start_date khi chuyển TRIAL→ACTIVE).

Response 200:

{
  "success": true,
  "statusCode": 200,
  "data": {
    "id": 55,
    "service_status": "TRIAL",
    "trial_end_date": "2026-07-08",
    "activated_at": "2026-07-01T03:00:00Z",
    "plan_snapshot": {
      "setup_fee": 3000000, "standardization_fee": 5000000,
      "maintenance_fee_year": 9500000, "qr_quota_year": 20000,
      "max_products": 50, "features": { "recall_management": false, "api_integration": "none" }
    },
    "companies_status_mirror": 1,
    "version": 2
  }
}

Lỗi: 400 (E-F46-001), 409 (E-F46-007 version lệch).

9.2.3. POST /api/v1/admin/company-subscriptions/:id/renew — Gia hạn ​

Request: { "term_months": 12, "version": 3 } Response 200: { "success": true, "statusCode": 200, "data": { "service_status": "ACTIVE", "paid_until_date": "2027-07-08", "version": 4 } }

9.2.4. POST /api/v1/admin/company-subscriptions/:id/terminate — Chấm dứt ​

Request: { "terminate_reason": "DN vi phạm điều khoản hợp đồng dịch vụ", "version": 4 } Response 200: { "success": true, "statusCode": 200, "data": { "service_status": "TERMINATED", "terminated_at": "2026-09-01T02:00:00Z", "companies_status_mirror": 4, "version": 5 } } Lỗi: 400 (E-F46-004 thiếu/ngắn reason).

9.2.5. POST /api/v1/admin/company-subscriptions/:id/documents — Upload hồ sơ ​

Request: multipart/form-data — doc_type=CONTRACT, file=@hopdong.pdf (FileFieldsInterceptor). Response 201: { "success": true, "statusCode": 201, "data": { "id": 88, "doc_type": "CONTRACT", "file_name": "hopdong.pdf", "file_url": "subscriptions/55/hopdong.pdf", "file_size": 1048576 } } Lỗi: 400 (E-F46-003 quá 20MB / sai định dạng).

9.2.6. GET /api/v1/companies/:id/subscription-history — Lịch sử dịch vụ ​

Response 200:

{
  "success": true,
  "statusCode": 200,
  "data": {
    "current": { "plan_code": "PKG_STANDARD", "service_status": "ACTIVE", "paid_until_date": "2027-07-08" },
    "histories": [
      { "action": "ACTIVATE", "from_status": "DRAFT", "to_status": "TRIAL", "changed_at": "2026-07-01T03:00:00Z", "changed_by": "Admin GoTrace" },
      { "action": "ACTIVATE", "from_status": "TRIAL", "to_status": "ACTIVE", "changed_at": "2026-07-08T01:00:00Z" }
    ]
  }
}

Multi-tenant: nếu caller là ENTERPRISE_ADMIN/USER, server ép company_id = current_company_id; truy vấn DN khác → 403 (BR-F46-14).

9.2.7. POST /api/v1/auth/login — Login gate (SỬA) ​

Request: { "email": "user@dn.com", "password": "..." }

Xử lý bổ sung (login gate):

1. Xác thực credential (như cũ).
2. Đọc companies.status (mirror) của DN user.
3. Nếu status = 1 (TRIAL)/2 (ACTIVE): kiểm tra lazy-expire theo trial_end_date/paid_until_date; nếu quá hạn → flip EXPIRED (transaction: UPDATE + history {EXPIRE} + mirror status=3 + invalidate user_perms:{userId} mọi user DN).
4. Nếu (sau lazy) EXPIRED → 403 SERVICE_EXPIRED; nếu TERMINATED → 403 SERVICE_TERMINATED.
5. Ngược lại (DRAFT/TRIAL/ACTIVE còn hạn) → phát JWT; JwtStrategy.validate() cache user_perms:{userId} 10'.

Response 403 — EXPIRED (E-F46-005):

{
  "success": false,
  "statusCode": 403,
  "error": { "code": "SERVICE_EXPIRED", "message": "Cần liên hệ sale của gotrace để kích hoạt dịch vụ" }
}

Response 403 — TERMINATED (E-F46-006):

{
  "success": false,
  "statusCode": 403,
  "error": { "code": "SERVICE_TERMINATED", "message": "Cần liên hệ với quản trị viên gotrace" }
}

9.2.8. GET /api/v1/admin/company-subscriptions — Danh sách ​

Query params: page, page_size, service_status, plan_code, active_from, active_to, keyword (MST/tên/SĐT/email). Response 200:

{
  "success": true,
  "statusCode": 200,
  "data": {
    "items": [ { "id": 55, "company_name": "Công ty ABC", "company_tax_code": "0101234567", "plan_code": "PKG_STANDARD", "service_status": "ACTIVE", "paid_until_date": "2027-07-08" } ],
    "pagination": { "page": 1, "page_size": 20, "total_items": 137, "total_pages": 7 }
  }
}

10. Test Cases cho QA ​

11. Acceptance Criteria ​

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

Bảng đầy đủ transition của SERVICE_STATUS. Mọi transition (trừ không có) thực hiện trong cùng $transaction: ghi subscription_histories + mirror companies.status + invalidate cache user_perms.

Các transition không hợp lệ (vd EXPIRED → TRIAL trực tiếp, ACTIVE → DRAFT) đều bị chặn với E-F46-001.

13. Notification List ​

Ghi chú: N-F46-02/N-F46-03 ở v1 phát khi có sự kiện login/thao tác admin phát hiện (không cron). Warning W-F46-001/002 (Section 14) là biến thể hiển thị trên UI admin.

14. Error / Warning Message Handling ​

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

14.2. Warnings (cho phép tiếp tục, cảnh báo) ​

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) ​

Ràng buộc:

1. Không cron ở v1 — hết hạn (EXPIRED) đánh giá theo kiểu lazy khi user DN đăng nhập (UC-F46-07). Cron quét paid_until_date/trial_end_date nền tảng là hạng mục v1.5 (để notification N-F46-02/03 chủ động hơn).
2. Cache invalidation — mọi chuyển trạng thái phải xóa key user_perms:{userId} của mọi user thuộc DN; nếu Redis lỗi, transaction DB vẫn commit, cache tự hết hạn ≤ 10' (fail-safe, không block nghiệp vụ).
3. Optimistic lock — dùng cột version; không dùng pessimistic lock để tránh giữ khóa lâu.
4. Mirror companies.status — chỉ để chặn login rẻ; nguồn sự thật là company_subscriptions.service_status. Nếu lệch (do lỗi), ưu tiên company_subscriptions; cần job đối soát định kỳ (v1.5).
5. KHÔNG CTE/KDE — TXNG-F46 là module vận hành thương mại nội bộ, KHÔNG phát sinh Critical Tracking Event / Key Data Element và KHÔNG tham gia chuỗi truy xuất TCVN 12850:2019.
6. Giá VND chưa gồm VAT — mọi phí trong plan_snapshot là NUMERIC, VND, chưa bao gồm VAT (BR-F45-10).
7. Immutable audit — subscription_histories chặn UPDATE/DELETE bằng trigger; retention ≥ 2 năm (khuyến nghị ≥ 5 năm theo hồ sơ hợp đồng).
8. SLA — GET list ≤ 500ms; write (activate/renew/terminate transaction) ≤ 1 giây; login gate thêm ≤ 50ms (đọc mirror, không JOIN).

Giả định:

1. TXNG-F45 (service_plans) đã seed 4 gói canonical (PKG_BASIC/STANDARD/LINKED/ENTERPRISE) ở status = ACTIVE trước khi kích hoạt DN.
2. TXNG-F01 (companies) đã có DN với company_tax_code, thông tin liên hệ đầy đủ.
3. AuthService.login() + JwtStrategy.validate() đã có cơ chế cache user_perms:{userId} 10' để login gate hook vào.
4. MinioStorageService + FileFieldsInterceptor sẵn sàng cho upload hồ sơ.
5. Sale thao tác qua tài khoản PLATFORM_ADMIN; SALE_STAFF không phải actor trực tiếp.

18. Phụ lục (Appendix) ​

18.1. Bảng seed 4 gói tham chiếu (từ docs/sale/Sale_Pricing.md, đối chiếu TXNG-F45) ​

Tổng năm đầu = setup_fee + standardization_fee + maintenance_fee_year. Từ năm 2 = maintenance_fee_year. Chiết khấu duy trì: 2 năm −10%, 3 năm −20% (trước VAT). Giá VND, chưa gồm VAT.

18.2. Ví dụ plan_snapshot JSONB (chốt lúc kích hoạt) ​

{
  "plan_code": "PKG_STANDARD",
  "setup_fee": 3000000,
  "standardization_fee": 5000000,
  "maintenance_fee_year": 9500000,
  "qr_quota_year": 20000,
  "max_products": 50,
  "max_users": 5,
  "storage_gb": 3,
  "extra_qr_fee": 120,
  "extra_product_fee": 490000,
  "discount_2y_percent": 10,
  "discount_3y_percent": 20,
  "features": {
    "supply_chain_link": false,
    "recall_management": false,
    "operation_log": false,
    "api_integration": "none",
    "blockchain": "optional",
    "public_trace_page": "standard",
    "qr_scan_stats": true,
    "dashboard": true
  },
  "snapshot_at": "2026-07-01T03:00:00Z"
}

18.3. Ví dụ changes_json cho action UPDATE ​

{
  "term_months": { "before": 12, "after": 24 },
  "discount_percent": { "before": 0, "after": 10 },
  "bonus_qr_quota": { "before": 0, "after": 5000 }
}

18.4. Map trạng thái ↔ mirror companies.status ​

18.5. Thuật ngữ (Glossary) ​

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