Policy, Level & Business Rules

01 Policy & Level: sắp xếp theo khoảng cách I/O

Trong hệ thống thực, policy lớn ấy được chẻ thành nhiều policy con: tính quy tắc nghiệp vụ, định dạng báo cáo, xác thực dữ liệu… Nghệ thuật kiến trúc là tách các policy rồi nhóm lại theo cách chúng thay đổi:

Data flow ≠ Dependency: phụ thuộc luôn trỏ LÊN cấp cao

Lấy ví dụ chương trình mã hoá (encryption): đọc ký tự ⟶ dịch qua bảng ⟶ ghi ký tự. readChar/writeChar chạm thẳng thiết bị I/O nên cấp thấp; Translate xa I/O nhất nên cấp cao nhất. Điều cốt lõi: luồng dữ liệu và hướng phụ thuộc mã nguồn không cùng chiều.

flowchart LR
  subgraph DF["① Data flow · luồng dữ liệu"]
    direction LR
    R["readChar
(thấp · gần input)"]:::out --> T1["Translate
(cao · xa I/O)"]:::core --> W["writeChar
(thấp · gần output)"]:::out
  end
  subgraph SD["② Source dependency · phụ thuộc mã nguồn"]
    direction LR
    RC["ConsoleReader"]:::out -.->|trỏ LÊN| E["Encryption
(cấp cao)"]:::core
    WC["ConsoleWriter"]:::out -.->|trỏ LÊN| E
  end
  DF --> SD
  classDef core fill:#dce7f1,stroke:#2e5e8c,color:#14233b;
  classDef out fill:#e2edf3,stroke:#2f6d93,color:#14233b;
            

02 Entity: Critical Business Rules & Data

Đỉnh cao nhất của các policy là business rules. Nói chặt chẽ, business rule là quy tắc/thủ tục giúp doanh nghiệp kiếm tiền hoặc tiết kiệm tiền — và chúng vẫn tồn tại ngay cả khi không có hệ thống máy tính nào tự động hoá chúng.

RAG · Entity là quy tắc cốt lõi, không phụ thuộc framework

RAG  Quy tắc "thế nào là một Chunk hợp lệ" (độ dài tối đa, không rỗng) là critical business rule của hệ RAG — đúng kể cả khi bạn chunk tài liệu bằng tay. Nó phải sống trong Entity, không dính FastAPI hay vector DB:

# Entity: Critical Business Rules + Data — pure business, KHÔNG biết web/DB
MAX_CHUNK = 800  # quy tắc cốt lõi: chunk vượt ngưỡng là không hợp lệ

class Chunk:
    def __init__(self, text: str, doc_id: str):
        if not text.strip():            # Critical Business Rule
            raise ValueError("chunk rỗng")
        if len(text) > MAX_CHUNK:       # tồn tại kể cả khi chunk thủ công
            raise ValueError("chunk quá dài")
        self.text, self.doc_id = text, doc_id

03 Use Case: quy tắc đặc thù ứng dụng & điều phối

Nếu Entity là quy tắc của doanh nghiệp, thì Use Case là quy tắc của ứng dụng cụ thể. Use case mô tả cách một hệ thống tự động được dùng: định nghĩa input người dùng cấp, output trả về, và các bước xử lý để tạo ra output đó.

Use Case KHÔNG biết mình được phân phối kiểu gì

Use case không mô tả giao diện. Nhìn vào một use case, bạn không thể biết ứng dụng chạy trên web, thick client, console hay là một pure service — nó chỉ nói tới dữ liệu vào ra, mặc kệ cách dữ liệu đó được truyền đi.

RAG · Use Case điều phối retrieve → rank → generate

RAG  AnswerQuestion là use case: nó không tự embed, không tự gọi LLM bằng tay — nó điều phối các bước và để Entity giữ quy tắc cốt lõi:

@dataclass            # Request/Response model: cấu trúc thuần, KHÔNG kế thừa HttpRequest
class AskRequest:  question: str
@dataclass
class AskResponse: answer: str; sources: list[str]

class AnswerQuestion:                 # application-specific use case
    def execute(self, req: AskRequest) -> AskResponse:
        chunks = self.retriever.search(req.question)   # điều phối: retrieve
        ranked = self.ranker.rank(chunks)              #          → rank
        ans    = self.generator.generate(ranked, req.question)  # → generate
        return AskResponse(answer=ans.text, sources=ans.cited)

04 Use Case ⟶ Entity: hướng phụ thuộc một chiều

Đây là điểm quan trọng nhất của chương 20, và là hệ quả trực tiếp của định nghĩa level ở phần 1: khái niệm cấp cao không biết gì về khái niệm cấp thấp hơn.

Hai mặt dưới đây là cùng một quy tắc nhìn từ hai phía — cả hai đều là tính chất mong muốn, không có bên "đúng" bên "sai".

flowchart TB
  WEB["Web / Console / Service
(detail · cấp thấp nhất)"]:::out --> UC
  UC["Use Case · AnswerQuestion
application-specific · cấp thấp hơn"]:::mid
  UC -->|phụ thuộc · trỏ LÊN| ENT["Entity · Chunk / Loan
Critical Business Rules · CẤP CAO NHẤT"]:::core
  UC -.->|trả về| RR["Request / Response model
(cấu trúc thuần · không framework)"]:::out
  classDef core fill:#14233b,stroke:#2e5e8c,color:#ffffff;
  classDef mid fill:#dce7f1,stroke:#2e5e8c,color:#14233b;
  classDef out fill:#e2edf3,stroke:#2f6d93,color:#14233b;
            

RAG · level trong pipeline: embed gần I/O, AnswerQuestion xa I/O

RAG  Xếp các thành phần RAG theo khoảng cách tới I/O: tokenizer/embed chạm thẳng dữ liệu thô ⟶ cấp thấp; AnswerQuestion điều phối ⟶ cấp cao hơn; quy tắc Chunk ⟶ cao nhất. Ranh giới ra ngoài để PHP gọi sang chỉ là một detail cấp thấp:

// PHP = detail cấp thấp nhất (gần I/O người dùng) — KHÔNG chứa business rule
// Phụ thuộc trỏ VÀO Python: PHP biết use case, use case không biết PHP/web
$res = Http::post('http://rag-svc/ask', ['question' => $q]);
return $res->json('answer');   // Request/Response model thuần băng qua ranh giới
// Bên trong rag-svc: AnswerQuestion (cấp cao) điều phối Chunk-entity (cao nhất)

05 Ghi nhớ nhanh