Hệ thống Tồn kho Khả dụng & Hóa đơn GTGT

Dành cho Ban lãnh đạo

ARCHITECTURE-SPINE — hợp đồng ràng buộc cho người xây

Architecture Spine — Kazuki AI Assistant

Tài liệu này là nguồn schema và ranh giới duy nhất. Nó thay thế hoàn toàn bản spine 13/08. architecture-consensus.md hạ cấp thành nhật ký quyết định — khi hai bên chỏi nhau, spine thắng.

Design Paradigm

Hexagonal (Ports & Adapters), lõi tất định thuần, AI nằm ngoài lõi.

Ba vòng, phụ thuộc chỉ đi vào trong:

• **Lõi (core/)** — hàm thuần, không I/O, không mạng, không LLM, không đồng hồ. Nhận dữ liệu vào, trả dữ liệu ra. Toàn bộ phép tính tồn kho và đối soát nằm ở đây. Test được không cần mock.
• **Cổng (ports/)** — giao diện trừu tượng lõi dùng để nói chuyện với bên ngoài: đọc chatlog, đọc CSDL, phát tin nhắn, sinh file.
• **Bộ chuyển (adapters/)** — hiện thực cụ thể của cổng: SQLite, Telegram relay, pdfplumber, openpyxl, LLM normalizer.

AI LLM là một adapter, không bao giờ là lõi. Nó chỉ làm hai việc: bóc chuỗi thô từ văn bản gõ tay thành JSON, và diễn đạt danh sách mã lỗi đã tính sẵn thành câu tiếng Việt. Mọi con số đi qua lõi tất định.

Ánh xạ paradigm sang namespace CSDL: core_ (dữ liệu dùng chung), inv_ (Module 01), fin_ (Module 02).

Invariants & Rules

Hướng phụ thuộc — mũi tên là "được phép phụ thuộc vào":

AD-1 — Python là bên ghi CSDL duy nhất, Node là relay thuần [ADOPTED]

• Binds: toàn hệ thống
• Prevents: hai tiến trình OS cùng ghi một file SQLite; mất khả năng giữ bất biến trong bộ nhớ tiến trình
• Rule: AI Gateway (Node.js) không mở, không ghi kazuki.db. Node nhận webhook Telegram, đẩy payload sang Python qua socket cục bộ, gọi sendMessage rồi trả message_id về cho Python. Python ghi inv_bot_messages. Mọi lệnh ghi CSDL xuất phát từ một tiến trình Python duy nhất.

AD-2 — Một file SQLite dùng chung, cấu hình bắt buộc [ADOPTED]

• Binds: toàn hệ thống
• Prevents: SQLITE_BUSY do transaction hoãn nâng cấp; khóa ngoại không hiệu lực; kiểu dữ liệu trôi
• Rule: kazuki.db, journal_mode=WAL, busy_timeout=5000, foreign_keys=ON đặt lại trên từng connection, mọi bảng khai báo STRICT. Mọi transaction ghi mở bằng BEGIN IMMEDIATE — cấm transaction hoãn rồi nâng cấp lên ghi. Cấm giữ transaction xuyên qua lời gọi LLM, parse PDF/Excel, hay ghi file.

AD-3 — Spine là nguồn schema duy nhất

• Binds: mọi tài liệu và mọi code
• Prevents: năm bản định nghĩa core_vehicles mâu thuẫn như hiện trạng
• Rule: Không tài liệu nào khác được khai báo DDL. PRD và SPEC mô tả nghiệp vụ và trỏ về đây. Đổi schema thì sửa spine trước, code sau.

AD-4 — Định danh xe là CẶP (số khung, số máy)

• Binds: M02-CAP-1, mọi khâu đối soát xe
• Prevents: gõ nhầm một ký tự số khung rơi trúng một chiếc xe thật khác trong cùng lô
• Rule: Một dòng xe chỉ được chấp nhận khi **cả vin lẫn engine_no** khớp cùng một bản ghi core_vehicles. Khớp vin đơn lẻ, hoặc khớp bộ ba vin + model + màu, đều không đủ.

Căn cứ: dữ liệu đăng kiểm thật cho thấy xe cùng lô mang số khung liền nhau (RNKY6EKUMSDA02621, ...02622), cùng model, cùng màu. Sai một chữ số là rơi trúng xe kế bên và mọi kiểm tra thuộc tính đều lọt. Dãy số máy chạy độc lập với dãy số khung nên cặp này mới là kiểm tra chéo thật. Tem trên xe có sẵn cả hai số.

AD-5 — Một đại lý có nhiều pháp nhân

• Binds: M02-CAP-5
• Prevents: hóa đơn xuất sai pháp nhân — Vấn đề 3 của khách
• Rule: Tách core_customers (đại lý nhận xe) khỏi core_customer_entities (pháp nhân + MST xuất hóa đơn), quan hệ 1–N. Cấm nhét tax_code vào core_customers. Khi LXN không chỉ rõ MST mà đại lý có từ 2 pháp nhân, hệ thống hỏi lại người, tuyệt đối không suy đoán theo lịch sử, tần suất hay tên gần giống.

AD-6 — Tồn khả dụng là derived state, không bao giờ là biến đếm

• Binds: M01-CAP-3
• Prevents: cộng dồn sai, trừ hai lần, không thể tính lại sau khi sửa dữ liệu
• Rule: available luôn được tính lại từ (baseline hiện hành, tập LXN còn hiệu lực) bằng một truy vấn SQL. Cấm lưu tồn dạng cột cộng/trừ tại chỗ. Nhờ vậy mọi thao tác tính lại là idempotent.

available_tp = baseline.stock_tp − Σ qty_tp (đơn ACTIVE, còn hiệu lực) available_sx = baseline.stock_sx − Σ qty_sx (đơn ACTIVE, còn hiệu lực)

Không kẹp về 0. Số âm là tín hiệu phải báo, không phải lỗi để giấu.

AD-7 — Carry-forward theo tình trạng xuất phiếu, không theo mốc thời gian

• Binds: M01-CAP-1, M01-CAP-3
• Prevents: LXN chưa xuất hàng bị xóa giữ chỗ khi có baseline mới → bán trùng xe
• Rule: Tại mốc reset baseline, chỉ những dòng đã thực xuất mới chuyển SETTLED. Dòng còn HOLD_SX_PENDING hoặc chưa có xác nhận xuất phiếu đi xuyên baseline, giữ nguyên created_at gốc để xếp thứ tự FIFO. Khi có file AMIS sửa trong cùng ngày, effective_at kế thừa từ file mở ngày, không nhảy theo file mới.

AD-8 — Không có chuyển trạng thái nào theo thời gian

• Binds: M01-CAP-3, M02-CAP-6
• Prevents: hệ thống tự ý nhả giữ chỗ hoặc tự mở khóa tài chính
• Rule: Thời gian trôi qua chỉ đổi người được hỏi, không bao giờ tự giải phóng trạng thái. HOLD_SX_PENDING không tự hủy. Batch GENERATED không tự nhả. Mọi chuyển trạng thái giải phóng đều do người thực hiện và có ghi log.

AD-9 — Tách chế độ tin cậy theo module

• Binds: toàn hệ thống
• Prevents: đánh đổi sai giữa tốc độ và tính đúng đắn
• Rule: Module 01 được phép đọc snapshot hơi cũ (số tồn trễ vài giây không gây hại). Module 02 bắt buộc đọc và ghi trong cùng một transaction IMMEDIATE; bảo đảm chống trùng hóa đơn nằm ở tầng CSDL, không ở tầng ứng dụng.

AD-10 — Chống trùng hóa đơn bằng partial unique index, đảo ngược được

• Binds: M02-CAP-2, M02-CAP-6
• Prevents: một số khung lên hai hóa đơn; đồng thời tránh khóa chết nghiệp vụ xuất lại hợp lệ
• Rule: CREATE UNIQUE INDEX ux_vin_active ON fin_batch_items(vin) WHERE state IN ('GENERATED','INVOICED'). Trạng thái VOIDED làm bản ghi rơi khỏi index nên số khung dùng lại được. Chuyển sang VOIDED chỉ do người thực hiện, bắt buộc ghi voided_by và void_reason, không có cơ chế tự động.

AD-11 — Hóa đơn chứa được dòng không có số khung

• Binds: M02-CAP-2
• Prevents: migration bảng lõi khi phát sinh hóa đơn có ắc quy / phụ kiện
• Rule: fin_batch_items mang line_type (VEHICLE | ACCESSORY), vin nullable, kèm CHECK (line_type <> 'VEHICLE' OR vin IS NOT NULL). Khóa chính là khóa thay thế. SQLite coi mỗi NULL trong unique index là giá trị riêng nên dòng phụ kiện không đụng ux_vin_active.

AD-12 — LLM không bao giờ sinh định danh hay ô dữ liệu

• Binds: M01-CAP-2, M02-CAP-1, M02-CAP-2
• Prevents: ảo giác số liệu; ánh xạ SKU sai âm thầm
• Rule: LLM chỉ trả chuỗi thô trong JSON (raw_model_text, raw_color_text, qty) và văn bản cảnh báo dựng từ mã lỗi đã tính sẵn. Cấm LLM sinh sku_id, vin, tax_code, hay bất kỳ ô nào của file Excel upload. Ánh xạ chuỗi sang định danh là tra cứu tất định trong Python/SQL.

AD-13 — Khớp SKU: chỉ ba kết cục, không có điểm số

• Binds: M01-CAP-2
• Prevents: khớp gần đúng âm thầm ra kết quả sai
• Rule: Chuẩn hóa bằng luật cố định (hạ chữ thường, gom khoảng trắng, cắt hậu tố sạc bằng regex whitelist), rồi tra bảng alias đóng theo nguyên tắc alias dài khớp trước. Đúng một kết quả thì đi tiếp; không có kết quả hoặc nhiều kết quả thì chặn và hỏi lại người. Cấm phá hòa bằng điểm số. rapidfuzz chỉ được dùng để gợi ý hiển thị cho người, không bao giờ tự áp.

AD-14 — Vắng mặt trong báo cáo AMIS nghĩa là tồn 0, không phải sai tên

• Binds: M01-CAP-2
• Prevents: Bot kết luận sai rằng một màu hợp lệ là màu không tồn tại
• Rule: Báo cáo AMIS dạng pivot chỉ in dòng có tồn > 0. Khi model/màu không tìm thấy, Bot phát ngôn trung lập "hiện tồn = 0" và không kết luận về tính hợp lệ.

AD-15 — Đối soát 4 nguồn dựng tập ứng viên TỪ FILE A

• Binds: M02-CAP-1
• Prevents: sinh dòng hóa đơn không có chuyển động kho tương ứng trên MISA
• Rule: Tập ứng viên bắt nguồn từ FILE A (sổ chi tiết vật tư MISA, mã hàng -TP), sau đó làm giàu bằng dữ liệu nội bộ. Engine không tự sinh dòng hóa đơn từ CSDL riêng. Mỗi ứng viên đi qua chuỗi kiểm tra tất định, dừng ở lỗi đầu tiên, mỗi lỗi có mã riêng — bao gồm ENGINE_MISMATCH theo AD-4.

AD-16 — Hợp đồng đọc chatlog

• Binds: mọi code đọc chatlogs/
• Prevents: đếm trùng lệnh; lấy sai mốc thời gian nghiệp vụ; vỡ khi gặp bản ghi cũ
• Rule: Khử trùng theo khóa (chat_id, message_id), mốc so sánh là edit_date nếu có, không thì timestamp. Mốc nghiệp vụ luôn là timestamp (giờ tin vào nhóm hiện tại) — tuyệt đối không dùng forward.date. Parser phải chịu được bản ghi trước 14/08/2026 thiếu chat_title, edit_date, media.saved_path; với nhóm bản ghi đó, thứ tự dòng trong file là thứ tự đến.

AD-17 — Mọi số liệu báo ra đều kèm nguồn gốc

• Binds: M01-CAP-4
• Prevents: mất niềm tin không phục hồi được sau một lần sai
• Rule: Không báo con số trần. Luôn kèm baseline lúc mấy giờ và đã trừ mấy lệnh. Ví dụ: "Tồn khả dụng: 3 xe (baseline 08:12, đã trừ 4 LXN)". Khi báo thiếu hàng do đã xuất vào đơn khác, liệt kê ngay tên đơn và số lượng, không đợi hỏi lại.

AD-18 — Đối soát Delta mỗi sáng là điều kiện phát hành

• Binds: M01-CAP-1
• Prevents: cam kết "chính xác 100%" không có gì đo được
• Rule: Mỗi khi nạp baseline mới, hệ thống tự so tồn dự đoán cuối ngày hôm trước với số AMIS mới, báo chênh lệch theo từng mã. Kích hoạt theo sự kiện nhận file, không hẹn giờ cố định — giờ gửi thực tế dao động trong khung 8h–10h. Đây là hạng mục bắt buộc trước khi chạy chính thức, không phải tính năng phụ.

AD-19 — Luôn có đường can thiệp thủ công

• Binds: toàn hệ thống
• Prevents: người dùng đi vòng qua hệ thống một lần rồi không bao giờ quay lại
• Rule: Mọi chốt chặn tự động phải có đường ghi đè dành cho Lãnh đạo, ghi log đầy đủ ai làm và vì sao. Không có cửa thoát thì hệ thống sẽ bị bỏ qua đúng một lần và mất tin tưởng vĩnh viễn.

AD-20 — Bộ Golden-Master dựng từ dữ liệu thật

• Binds: toàn hệ thống
• Prevents: hồi quy về đúng những lỗi đã từng mắc
• Rule: Bộ test hồi quy dựng từ 17 đơn hàng thật trong test-history.md, kèm các đáp án sai đã ghi nhận làm negative assertion: VCGT không được thành VC GT 1; ghi sần không được bằng ghi đá; Slay 240W đen sần phải đọc ra 5 chứ không phải 15.

AD-21 — Chỉ một thành phần được tạo bản ghi core_skus

• Binds: M01-CAP-1, M01-CAP-2, M02-CAP-1
• Prevents: hai đường nạp cùng sinh SKU trùng cho một model+màu, làm tồn kho tách đôi âm thầm
• Rule: Chỉ đường nạp baseline AMIS (app/ingest_baseline.py) được tạo mới core_skus. Mọi đường khác — bóc tách LXN, nạp file đăng kiểm, đối soát Module 02 — chỉ được tra cứu; không tìm thấy thì chặn và hỏi lại người theo AD-13, tuyệt đối không tự tạo. Alias mới chỉ ghi khi có người xác nhận, kèm confirmed_by và confirmed_at.

Vì sao cần: nếu không có luật này, hai thành phần đều tuân thủ đủ mọi AD khác vẫn có thể tạo ra hai sku_id cho cùng một chiếc xe — một từ chữ trong file AMIS, một từ chữ trong file đăng kiểm — và tồn kho bị chia đôi mà không ai thấy.

AD-22 — core_vehicles trỏ về core_skus, không mang tên model/màu tự do

• Binds: M02-CAP-1, AD-4
• Prevents: hai bộ từ vựng model/màu song song khiến phép so khớp luôn sai
• Rule: core_vehicles mang sku_id (khóa ngoại) làm định danh chủng loại. Tên model và màu đọc từ file đăng kiểm được giữ lại dưới dạng cột thô chỉ để truy vết (raw_model_text, raw_color_text), không dùng để so khớp. Việc quy tên thô về sku_id đi qua đúng pipeline ở AD-13.

Vì sao cần: file đăng kiểm ghi màu thương mại ở cột "Màu xe (Thực tế)" còn báo cáo AMIS dùng cách viết riêng. Nếu mỗi bảng giữ một chuỗi tự do thì phép đối chiếu model/màu giữa core_vehicles và dòng LXN hoặc luôn trượt, hoặc trùng nhầm — cả hai đều hỏng mà vẫn "đúng luật".

AD-23 — Số máy do Thủ kho báo là dữ liệu khai báo, core_vehicles là thẩm quyền

• Binds: AD-4
• Prevents: hai nguồn sự thật cho cùng một số máy
• Rule: inv_order_vehicles.engine_no là con số Thủ kho khai, giữ nguyên để truy vết kể cả khi sai. core_vehicles.engine_no là thẩm quyền. Đối soát là so hai giá trị này; lệch thì báo ENGINE_MISMATCH và chặn, không bao giờ ghi đè bên nào.

Consistency Conventions

Stack

Đã kiểm chứng trên web ngày 14/08/2026. Đây là seed — khi có code thì code làm chủ.

Structural Seed

Sơ đồ khối hệ thống

Thực thể lõi

Schema chuẩn

Namespace core_ và inv_ khai báo đầy đủ vì Module 01 phải code được ngay. Namespace fin_ khai báo tới mức invariant — chi tiết cột chờ file mẫu MISA.

-- ══ CORE: dùng chung 2 module ══
CREATE TABLE core_skus (
  sku_id          INTEGER PRIMARY KEY,
  model_name      TEXT NOT NULL,
  color_name      TEXT NOT NULL,
  merged_group_id TEXT NOT NULL,   -- VC GT + VC GT 1 dùng chung 1 group
  created_at      TEXT NOT NULL,
  UNIQUE(model_name, color_name)
) STRICT;

CREATE TABLE core_sku_aliases (
  alias_id         INTEGER PRIMARY KEY,
  sku_id           INTEGER NOT NULL REFERENCES core_skus(sku_id),
  normalized_alias TEXT NOT NULL UNIQUE,  -- đã hạ chữ thường, gom khoảng trắng
  raw_alias        TEXT NOT NULL,
  confirmed_by     TEXT,                  -- alias mới chỉ thêm khi người xác nhận
  confirmed_at     TEXT
) STRICT;

CREATE TABLE core_customers (
  customer_id            INTEGER PRIMARY KEY,
  customer_code          TEXT NOT NULL UNIQUE,
  shipping_customer_name TEXT NOT NULL     -- đại lý NHẬN xe
) STRICT;

CREATE TABLE core_customer_entities (   -- AD-5: 1 đại lý N pháp nhân
  entity_id       INTEGER PRIMARY KEY,
  customer_id     INTEGER NOT NULL REFERENCES core_customers(customer_id),
  legal_name      TEXT NOT NULL,
  tax_code        TEXT NOT NULL,
  invoice_address TEXT,
  is_active       INTEGER NOT NULL DEFAULT 1,
  UNIQUE(customer_id, tax_code)
) STRICT;

CREATE TABLE core_vehicles (            -- nguồn Đăng kiểm
  vin            TEXT PRIMARY KEY,      -- 17 ký tự, 9 đầu là mã kiểu loại theo model
  engine_no      TEXT NOT NULL,         -- AD-4: bắt buộc khớp cùng vin; đây là THẨM QUYỀN (AD-23)
  sku_id         INTEGER NOT NULL REFERENCES core_skus(sku_id),  -- AD-22
  raw_model_text TEXT NOT NULL,         -- lấy từ HEADER file, không phải cột; chỉ truy vết
  raw_color_text TEXT NOT NULL,         -- lấy cột "Màu xe (Thực tế)", KHÔNG lấy "Màu sơn"
  cert_no        TEXT,
  issued_date    TEXT,
  ingest_id      INTEGER NOT NULL
) STRICT;

-- ══ INV: Module 01 ══
CREATE TABLE inv_baselines (
  baseline_id      INTEGER PRIMARY KEY,
  business_date    TEXT NOT NULL,
  received_at      TEXT NOT NULL,
  effective_at     TEXT NOT NULL,   -- AD-7: file sửa trong ngày KẾ THỪA, không nhảy
  is_day_open      INTEGER NOT NULL,
  supersedes_id    INTEGER REFERENCES inv_baselines(baseline_id),
  source_file_path TEXT NOT NULL
) STRICT;

CREATE TABLE inv_baseline_stocks (
  stock_id    INTEGER PRIMARY KEY,
  baseline_id INTEGER NOT NULL REFERENCES inv_baselines(baseline_id),
  sku_id      INTEGER NOT NULL REFERENCES core_skus(sku_id),
  stock_tp    INTEGER NOT NULL DEFAULT 0,
  stock_sx    INTEGER NOT NULL DEFAULT 0,
  UNIQUE(baseline_id, sku_id)
) STRICT;

CREATE TABLE inv_orders (
  order_id               INTEGER PRIMARY KEY,
  tg_chat_id             TEXT NOT NULL,
  tg_msg_id              TEXT NOT NULL,
  issuer_id              TEXT NOT NULL,
  customer_id            INTEGER REFERENCES core_customers(customer_id),
  tax_entity_id          INTEGER REFERENCES core_customer_entities(entity_id),
  scheduled_invoice_date TEXT,
  order_type             TEXT NOT NULL DEFAULT 'STANDARD'
                         CHECK(order_type IN ('STANDARD','DIRECT_TRANSFER')),
  status                 TEXT NOT NULL DEFAULT 'ACTIVE'
                         CHECK(status IN ('ACTIVE','CANCELLED')),
  created_at             TEXT NOT NULL,
  UNIQUE(tg_chat_id, tg_msg_id)       -- AD-16: khóa idempotency
) STRICT;

CREATE TABLE inv_order_items (
  item_id        INTEGER PRIMARY KEY,
  order_id       INTEGER NOT NULL REFERENCES inv_orders(order_id),
  sku_id         INTEGER NOT NULL REFERENCES core_skus(sku_id),
  qty_tp         INTEGER NOT NULL DEFAULT 0,
  qty_sx         INTEGER NOT NULL DEFAULT 0,
  fulfil_status  TEXT NOT NULL DEFAULT 'RESERVED'
                 CHECK(fulfil_status IN ('RESERVED','HOLD_SX_PENDING','SHIPPED','SETTLED','RELEASED'))
) STRICT;

CREATE TABLE inv_order_vehicles (       -- Nguồn 3: Thủ kho xác nhận, dùng chung 2 module
  item_id      INTEGER NOT NULL REFERENCES inv_order_items(item_id),
  vin          TEXT NOT NULL REFERENCES core_vehicles(vin),
  engine_no    TEXT NOT NULL,           -- AD-4: lưu để đối chiếu cặp
  confirmed_by TEXT NOT NULL,
  confirmed_at TEXT NOT NULL,
  input_kind   TEXT NOT NULL CHECK(input_kind IN ('TEXT','OCR','SELECT')),
  PRIMARY KEY (item_id, vin)
) STRICT;

CREATE TABLE inv_bot_messages (
  log_id              INTEGER PRIMARY KEY,
  correlation_id      TEXT NOT NULL UNIQUE,  -- sinh ở client, chống ghi trùng khi retry
  telegram_message_id TEXT,
  chat_id             TEXT NOT NULL,
  message_type        TEXT NOT NULL,
  payload_json        TEXT NOT NULL,
  created_at          TEXT NOT NULL
) STRICT;

-- ══ FIN: Module 02 — mức invariant ══
-- fin_misa_stockout   : FILE A đã parse (AD-15), append-only kèm ingest_id
-- fin_misa_invoiced   : Báo cáo 4a đã parse, dùng xác nhận hóa đơn đã phát hành
-- fin_upload_batches  : mỗi lần sinh file = 1 batch, có file_sha256 và người tạo
CREATE TABLE fin_batch_items (
  batch_item_id         INTEGER PRIMARY KEY,          -- AD-11: khóa thay thế
  batch_id              INTEGER NOT NULL REFERENCES fin_upload_batches(batch_id),
  line_type             TEXT NOT NULL CHECK(line_type IN ('VEHICLE','ACCESSORY')),
  vin                   TEXT REFERENCES core_vehicles(vin),   -- NULL với phụ kiện
  engine_no             TEXT,                          -- AD-4
  item_id               INTEGER REFERENCES inv_order_items(item_id),
  tax_code              TEXT NOT NULL,                 -- bản chụp lúc sinh file
  state                 TEXT NOT NULL
                        CHECK(state IN ('GENERATED','INVOICED','RELEASED','VOIDED')),
  invoice_no            TEXT,
  supersedes_invoice_no TEXT,                          -- neo sẵn, trống ở Phase 1
  voided_by             TEXT,
  void_reason           TEXT,
  CHECK (line_type <> 'VEHICLE' OR (vin IS NOT NULL AND engine_no IS NOT NULL)),
  CHECK (state <> 'VOIDED' OR (voided_by IS NOT NULL AND void_reason IS NOT NULL))
) STRICT;

CREATE UNIQUE INDEX ux_vin_active ON fin_batch_items(vin)
  WHERE state IN ('GENERATED','INVOICED');   -- AD-10

Luồng chính — nhận LXN mới

Luồng chính — nạp baseline AMIS buổi sáng

Cây mã nguồn

src/
  core/                  # hàm thuần — không I/O, không LLM, không đồng hồ
    availability.py      # AD-6 derived state, AD-7 carry-forward
    sku_matching.py      # AD-13 alias dài trước, ba kết cục
    reconcile.py         # AD-15 chuỗi kiểm tra 4 nguồn, AD-4 cặp vin+engine
    delta_report.py      # AD-18
  ports/                 # giao diện trừu tượng
    repository.py
    messenger.py
    file_source.py
  adapters/
    sqlite_repo.py       # AD-2 pragma, BEGIN IMMEDIATE
    telegram_relay.py    # AD-1 nói chuyện với Gateway qua socket
    pdf_parser.py        # pdfplumber
    excel_parser.py      # openpyxl, ép chuỗi cho vin/engine/mã hàng
    llm_normalizer.py    # AD-12 chỉ trả chuỗi thô
    chatlog_reader.py    # AD-16
  app/                   # điều phối use-case, transaction nằm ở đây
    ingest_baseline.py
    handle_lxn.py
    handle_query.py
    handle_cancel_edit.py
  migrations/            # .sql đánh số, ANSI, không dùng cú pháp riêng SQLite
  tests/
    golden/              # AD-20 — 17 đơn thật + negative assertions

Capability → Architecture Map

Deferred

• **Chi tiết sinh file 6.UP MQC** — vị trí cột nạp từ file cấu hình khai báo MISA_MAP. Chờ file mẫu thật từ Chị Trang. Không chặn schema hay Thuật toán 1.
• Cách dựng ứng viên khi FILE A gộp dòng — đã thiết kế sẵn hai nhánh; chọn nhánh nào chờ xem file mẫu.
• Luồng hóa đơn điều chỉnh / thay thế — ngoài Phase 1, đã neo supersedes_invoice_no.
• Thang cảnh báo leo thang cho xe kẹt Kho SX — ngưỡng 24h/48h chưa ai xác nhận. Phase 1 chỉ cảnh báo đúng địa chỉ theo spec 5.8, không leo thang tự động.
• Đấu nối MISA Open API — Non-Goal Phase 1. Tài liệu đã đăng ký tại docs/references.md kèm ba điều kiện nên mở lại.
• Quản lý tồn theo VIN ở Module 01 — AMIS quản riêng. Module 01 chỉ tính theo (model, màu).
• Môi trường triển khai & vận hành — hiện chạy một máy, một tiến trình Python, cạnh Gateway sẵn có. Chưa cần chiến lược hạ tầng riêng; xem lại khi xuất hiện máy thứ hai hoặc tiến trình ghi thứ hai (đó cũng là điều kiện xét chuyển PostgreSQL).
• Xác thực định dạng số khung bằng checksum — số khung Kazuki theo quy chuẩn kiểu loại Việt Nam, không phải VIN ISO 3779 nên không có chữ số kiểm tra. Bù bằng AD-4.

[GIẢ ĐỊNH — cần soát] Toàn bộ namespace fin_ và các AD liên quan Module 02 chưa qua xác nhận của Chị Trang. Chúng được viết ở mức invariant để đáp án nào cũng khớp (xem AD-10, AD-11), nhưng vẫn là giả định cho tới khi có buổi phỏng vấn. Module 01 thì không có giả định nào chưa xác nhận.

Bản chiếu của kiến trúc theo bốn mức

Sơ đồ C4

Mức 1 — Bối cảnh hệ thống

Ai dùng, hệ thống nói chuyện với cái gì bên ngoài.

Điểm cần thấy: không có đường tự động nào giữa hệ thống và MISA. Dữ liệu đi qua file do Kế toán gửi tay. Đây là quyết định Phase 1, không phải hạn chế kỹ thuật.

Mức 2 — Khối thành phần

Hệ thống gồm những tiến trình nào, ai nói chuyện với ai.

Hai bất biến nhìn thấy được trên sơ đồ này: chỉ có một mũi tên vào CSDL, và LLM nằm ngoài lõi.

Mức 3 — Bên trong Python Engine

Quy tắc đọc sơ đồ: core/ không có mũi tên nào đi ra. Nếu lúc code thấy cần một mũi tên như vậy thì thiết kế đã sai chỗ nào đó, không phải quy tắc sai.

Mức 4 — Vòng đời một chiếc xe qua hai module

Không phải sơ đồ C4 chuẩn, nhưng đây là thứ khó nắm nhất khi đọc hệ thống.

Hai chỗ dễ hiểu sai: **GiuChoSX không tự hết hạn (AD-8), và Voided chỉ do người bấm**, không có đường tự động nào dẫn tới nó (AD-10).

Ước lượng công sức & cơ sở báo giá

Chia việc theo Epic

Chia theo ranh giới kiến trúc, không theo màn hình hay tính năng, để mỗi epic có thể giao cho một người và hoàn thành độc lập. Đơn vị ước lượng là ngày công của một dev quen việc, chưa tính thời gian chờ khách phản hồi.

Mức tin cậy: 🟢 chắc (đủ dữ kiện, đã có mẫu thật) · 🟡 vừa (rõ nghiệp vụ, chưa có mẫu) · 🔴 thấp (chưa có xác nhận khách)

GIAI ĐOẠN A — Nền tảng (bắt buộc trước mọi thứ)

A1. Hạ tầng CSDL & bộ khung Hexagonal 🟢 — 2 ngày

Dựng kazuki.db theo schema trong spine, migration đánh số, lớp sqlite_repo với đủ pragma của AD-2, khung thư mục core/ports/adapters/app. Xong khi: chạy migration sạch trên máy trắng; test chứng minh foreign_keys và STRICT có hiệu lực; BEGIN IMMEDIATE được ép ở mọi đường ghi. Ràng buộc: AD-1, AD-2, AD-3

A2. Parser báo cáo AMIS (PDF + Excel) 🟢 — 2 ngày

pdfplumber bóc bảng tồn kho, ép chuỗi cho mọi cột mã, nạp inv_baselines + inv_baseline_stocks, idempotent khi nạp lại cùng file. Xong khi: parse đúng 100% cả 5 file PDF thật đang có; nạp lại lần hai không sinh thêm dòng. Rủi ro đã biết: đây chính là chỗ agent cũ đọc nhầm 5 thành 15 — bắt buộc có test khoá con số đó. Ràng buộc: AD-2, AD-21

A3. Từ điển SKU & pipeline khớp tất định 🟢 — 3 ngày

core_skus, core_sku_aliases, chuẩn hóa bằng luật cố định, khớp alias dài trước, ba kết cục, hàng đợi alias chưa giải được. Xong khi: 17 đơn thật khớp đúng; các negative assertion đều chặn (VCGT ≠ VC GT 1, ghi sần ≠ ghi đá). Ràng buộc: AD-13, AD-14, AD-21

GIAI ĐOẠN B — Module 01, phần demo được

B1. Engine tồn khả dụng (derived state) 🟢 — 3 ngày

Truy vấn tính tồn, phân bổ TP trước rồi SX, cờ HOLD_SX_PENDING, không kẹp âm. Xong khi: chạy lại 17 đơn thật ra đúng số anh Đức Anh đã tính tay. Ràng buộc: AD-6, AD-7, AD-8

B2. Vòng đời baseline & carry-forward 🟢 — 2 ngày

Reset mốc, kế thừa effective_at, carry-forward theo tình trạng xuất phiếu, danh sách chờ GĐKD tick xác nhận mỗi sáng. Ràng buộc: AD-7

B3. Adapter LLM bóc tách LXN 🟢 — 2 ngày

Trả JSON chuỗi thô, không sinh định danh, hợp đồng đầu ra chặt, null khi không chắc. Ràng buộc: AD-12

B4. Giao thức Bot: tra cứu, hủy, sửa 🟢 — 3 ngày

Bảng 6 cột theo đúng mẫu đã chốt, nguồn gốc số liệu inline, truy vết đơn nào đã lấy màu đó, hủy/sửa bằng reply tin gốc, lưu inv_bot_messages. Ràng buộc: AD-16, AD-17, AD-19

B5. Báo cáo Delta mỗi sáng 🟢 — 1 ngày

So tồn dự đoán hôm trước với AMIS mới, báo chênh lệch theo mã, kích hoạt theo sự kiện nhận file. Vì sao không cắt được: đây là thứ duy nhất biến cam kết "chính xác 100%" thành số đo được. Cũng là công cụ gỡ lỗi khi khách nói sai. Ràng buộc: AD-18

B6. Bộ test Golden-Master 🟢 — 2 ngày

17 đơn thật thành fixture, các đáp án sai thành negative assertion, harness replay từ chatlog. Ràng buộc: AD-20

Cộng Giai đoạn A + B: 20 ngày công. Đây là phạm vi demo cho anh Đức Anh và là Gói 1 báo giá.

GIAI ĐOẠN C — Nền dùng chung của Module 02

C1. Parser file Đăng kiểm 🟢 — 1,5 ngày

Đã có file mẫu thật và đã bóc được cấu trúc: model ở header, lấy cột "Màu xe (Thực tế)", lọc Kết quả = Đạt, khóa idempotency từ số báo cáo + lần. Ràng buộc: AD-21, AD-22

C2. Nguồn 3 — Thủ kho xác nhận số khung + số máy 🟡 — 3 ngày

Reply vào tin LXN, khớp cặp (vin, engine_no), ưu tiên cho chọn từ danh sách thay vì gõ tay. Lưu ý triển khai: đổi thói quen hàng ngày của Thủ kho — không đưa vào trước khi ký hợp đồng. Giá trị kép: đây cũng là tín hiệu xuất phiếu mà Module 01 đang thiếu, bỏ được việc GĐKD ghi tay mỗi sáng. Ràng buộc: AD-4, AD-23

GIAI ĐOẠN D — Module 02, phần còn lại

D1. Nạp 2 báo cáo MISA 🔴 — 2 ngày (chờ file mẫu)

D2. Engine đối soát 4 nguồn 🟡 — 4 ngày

Chuỗi kiểm tra tất định, dừng ở lỗi đầu, gồm ENGINE_MISMATCH. Ràng buộc: AD-4, AD-15

D3. Sinh file upload MISA 🔴 — 3 ngày *(chặn: thiếu template 6.UP MQC)*

D4. Máy trạng thái hóa đơn & batch 🟡 — 2 ngày

D5. Cảnh báo & khóa luồng 🟡 — 2 ngày

Cộng Giai đoạn C + D: 17,5 ngày công — nhưng D1 và D3 đang bị chặn, và toàn bộ D chưa có xác nhận nào từ chị Trang. Đây là Gói 2, chỉ nên báo giá sau khi phỏng vấn.

Đường găng & thứ tự làm

Đường găng của demo: A1 → A3 → B1 → B4. Rút ngắn được thì rút ở đây, không phải chỗ khác.

Ghi chú cho việc báo giá

Gói 1 (A + B, 20 ngày) — phạm vi rõ, dữ kiện đầy đủ, đã có dữ liệu thật để kiểm chứng. Báo giá cố định được, rủi ro vượt dự toán thấp.

Gói 2 (C + D, ~17,5 ngày) — con số này là ước lượng thô, chưa nên đưa vào hợp đồng. Hai hạng mục đang bị chặn vì thiếu file mẫu, và toàn bộ nghiệp vụ chưa qua xác nhận của người phụ trách. Nên chào một buổi khảo sát với chị Trang trước, rồi mới báo giá phần này.

Nên tách hai gói thay vì gộp một con số. Lý do nói thẳng được với khách: chưa phỏng vấn người phụ trách thì báo giá chỉ là đoán — đoán thiếu thì mình chịu, đoán thừa thì khách thấy đắt. Và demo Gói 1 thành công sẽ tự bán Gói 2, lúc đó đã có dữ liệu thật để báo đúng.

Chưa tính trong hai gói trên: thời gian chạy pilot song song 1–2 tuần (chỉ giám sát báo cáo Delta, không tốn ngày công phát triển), đào tạo người dùng, và vận hành sau bàn giao.