Incomex AI Portal
KB-2C0D

NĐ-LARK-MVP — Phương án khả thi: Lark → PG → Directus → PDF

8 min read Revision 1
larkpgdirectuspdfmvpgpt

NĐ-LARK-MVP — Phương án khả thi: Lark → PG → Directus → PDF

Trạng thái: DRAFT thảo luận Tác giả: Incomex Hội đồng AI / GPT Ngày: 2026-04-12 Mục tiêu: Chuyển từ bài toán dump toàn bộ Lark sang một MVP khả thi hơn: lấy có chọn lọc một số dữ liệu cố định từ Lark, lưu về PG, rồi dùng Directus/render pipeline để sinh tài liệu/PDF tự động.

Kết luận ngắn

Đây là hướng khả thi hơn rõ rệt so với mục tiêu dump toàn bộ 18 Base ngay từ đầu.

Lý do:

  1. Không còn phụ thuộc vào việc phải hiểu hết toàn bộ cấu trúc Lark trước khi làm được việc gì.
  2. Tận dụng được năng lực hiện có của Cổng 2 như tuyến đọc dữ liệu chủ đạo.
  3. PG + Directus là hạ tầng phù hợp để lưu dữ liệu chuẩn hóa và xuất dữ liệu ra công cụ render.
  4. Có thể đi theo mô hình “vertical slice”: chọn 1-2 báo cáo/document thật sự cần, làm thông suốt từ đầu đến cuối, rồi mới mở rộng.

Quan điểm chốt

Không nên bắt đầu bằng bài toán “kết nối toàn bộ Lark với PG”. Nên bắt đầu bằng bài toán nhỏ hơn nhưng tạo ra giá trị thật:

Lark → lấy một tập field cố định → PG → Directus → render PDF / tài liệu tự động

Đây là một chu trình đóng, đo được, kiểm chứng được, và ít rủi ro hơn.

Căn cứ từ tài liệu hiện có

1. Cổng 2 đủ mạnh để làm tuyến đọc chủ đạo

Theo knowledge/dev/lark/lark-client-architecture.md, lark-client đã được thiết kế như thư viện/CLI sản xuất, có LarkReader cho các thao tác read-only như list tables, list fields, search records.

Theo knowledge/dev/lark/cong2-p6-final-report, bộ READ toolkit của Cổng 2 đã verify 15/15 endpoint đọc của Bitable v1 trên phạm vi kiểm chứng, và C2 là tuyến mạnh nhất cho inventory/read nền.

2. Không cần đụng hết automation/sync ngay từ đầu

Theo knowledge/dev/lark/mechanisms.md, nhiều phần khó như automation configs, sync setup, formula code, change stream thuộc nhóm phức tạp hoặc lệ thuộc C4/C5. Nếu mục tiêu trước mắt chỉ là lấy dữ liệu cố định để dựng document/PDF, có thể tránh phần khó này trong MVP đầu.

3. PG + Directus là mô hình phù hợp

Các tài liệu nội bộ như mission-registry-pg-report cho thấy luồng PG function/tables → Directus API → Nuxt/UI là mô hình đã tồn tại và hoạt động trong hệ hiện có. Tức là dùng PG làm nguồn dữ liệu rồi để Directus đọc/điều phối là phù hợp với hướng kiến trúc đang dùng.

Phương án khả thi nhất

A. Mục tiêu MVP

Chọn một loại đầu ra cố định để làm trước. Ví dụ:

  • 1 báo cáo nghiệp vụ PDF
  • 1 phiếu/tờ trình PDF
  • 1 hồ sơ tổng hợp PDF theo record

Không chọn mục tiêu “đọc mọi thứ trong Lark”.

B. Chỉ lấy dữ liệu cố định cần cho đầu ra đó

Thay vì lấy cả Base, chỉ lấy:

  • bảng nguồn chính
  • các field cố định cần render
  • nếu cần thì thêm 1-2 bảng lookup đơn giản

Ví dụ logic:

  1. Chọn một table nguồn trong Lark
  2. Chọn 20-40 field thật sự dùng để lên tài liệu
  3. Chọn 0-2 bảng phụ để map thêm tên/nhãn
  4. Đổ về PG theo schema ổn định
  5. Directus đọc từ PG
  6. Render PDF từ dữ liệu đã chuẩn hóa

C. Tránh đồng bộ hai chiều ở giai đoạn đầu

Giai đoạn đầu chỉ nên làm:

  • Lark → PG
  • không làm PG → Lark
  • không làm write-back
  • không làm sync hai chiều

Như vậy độ phức tạp giảm mạnh.

Kiến trúc đề xuất

Tầng 1 — Reader

  • Dùng Cổng 2 / lark-client / CLI để đọc dữ liệu từ Lark
  • Chỉ đọc các table/field đã được whitelist trong cấu hình job

Tầng 2 — Staging PG

PG có 3 lớp tối giản:

1. lark_jobs

Quản lý job nào đang kéo dữ liệu gì.

2. lark_raw_records

Lưu raw record JSON từ Lark cho từng job.

3. lark_document_rows

Bảng chuẩn hóa để render tài liệu/PDF.

Giai đoạn đầu chỉ cần ít bảng như vậy là đủ.

Tầng 3 — Directus

  • Expose lark_document_rows
  • Có thể thêm collection cấu hình template/report nếu cần
  • Dùng Directus làm lớp quản trị dữ liệu và đầu vào cho render

Tầng 4 — Render

  • Một service hoặc pipeline render nhận dữ liệu chuẩn hóa
  • Sinh PDF theo template cố định
  • Lưu file output hoặc metadata output

Thiết kế dữ liệu tối giản đề xuất

1. lark_jobs

Mỗi job = 1 cấu hình lấy dữ liệu

  • job_code
  • base_token
  • source_table_id
  • source_view_id (nếu cần)
  • field_whitelist_json
  • status
  • schedule_mode
  • notes

2. lark_job_runs

Mỗi lần chạy = 1 run

  • run_id
  • job_code
  • started_at
  • finished_at
  • status
  • rows_fetched
  • error_log

3. lark_raw_records

Lưu raw data

  • run_id
  • source_record_id
  • raw_jsonb
  • fetched_at

4. lark_document_rows

Lưu dữ liệu chuẩn hóa để render

  • row_id
  • run_id
  • source_record_id
  • document_type
  • key fields đã map ra cột thật
  • payload_jsonb cho phần linh hoạt
  • render_status

5. lark_pdf_outputs

Theo dõi file tạo ra

  • output_id
  • source_record_id
  • document_type
  • output_path / file_ref
  • rendered_at
  • status

Cách chọn phạm vi dữ liệu để làm trước

Chỉ chọn bài toán thỏa 4 điều kiện:

  1. Có 1 table nguồn rõ ràng
  2. Bộ field đầu ra khá cố định
  3. Không phụ thuộc quá nhiều vào automation/sync/formula khó
  4. Có giá trị nghiệp vụ ngay khi xuất được PDF

Nếu một báo cáo cần quá nhiều bảng, quá nhiều sync, quá nhiều suy luận từ workflow thì chưa nên chọn làm MVP.

Mô hình kết nối khả thi nhất giữa Lark và PG

Phương án nên chọn: Pull theo job cấu hình sẵn

Không làm connector “đọc mọi thứ”. Làm connector kiểu job:

  • mỗi job biết mình đọc base nào
  • đọc table nào
  • lấy những field nào
  • map sang cột PG nào
  • sinh loại tài liệu nào

Ưu điểm:

  • dễ kiểm soát
  • dễ debug
  • dễ mở rộng dần
  • không phụ thuộc việc hiểu toàn bộ Lark

Đây là cách khả thi nhất để bắt đầu.

Quy trình thực thi MVP

Bước 1

Chọn 1 loại tài liệu cần sinh tự động.

Bước 2

Chốt 1 table nguồn trong Lark và danh sách field cần lấy.

Bước 3

Thiết kế schema PG tối giản cho job đó.

Bước 4

Dùng Cổng 2 viết hoặc cấu hình job đọc dữ liệu định kỳ.

Bước 5

Nạp raw vào PG, rồi transform sang lark_document_rows.

Bước 6

Cho Directus đọc bảng chuẩn hóa.

Bước 7

Tạo pipeline render PDF từ dữ liệu chuẩn hóa.

Bước 8

Chạy thử end-to-end với dữ liệu thật.

Bước 9

Đo chất lượng:

  • có lấy đúng record không
  • field nào thiếu
  • PDF có đúng bố cục không
  • job có chạy ổn định không

Bước 10

Chỉ sau khi 1 job chạy ổn định mới nhân rộng sang loại tài liệu thứ 2.

Điều không nên làm ở giai đoạn này

  1. Không dump toàn bộ 18 Base ngay
  2. Không cố mô hình hóa toàn bộ automation/workflow ngay
  3. Không làm đồng bộ hai chiều
  4. Không làm generic engine quá sớm
  5. Không render PDF trực tiếp từ raw JSON

Đánh giá khả thi

Về kỹ thuật

Khả thi cao vì tận dụng được những gì đã có:

  • Cổng 2 để đọc dữ liệu
  • PG để lưu và transform
  • Directus để expose/quản trị
  • render pipeline để sinh PDF

Về tổ chức thực hiện

Khả thi hơn nhiều so với blueprint toàn hệ vì chỉ cần một nhóm nhỏ:

  • 1 người phụ trách C2/job reader
  • 1 người phụ trách PG/DOT schema
  • 1 người phụ trách Directus/render
  • 1 người kiểm mapping nghiệp vụ

Về giá trị

Có giá trị thực dụng cao vì sớm tạo ra đầu ra nhìn thấy được: file/tài liệu/PDF tự động.

Khuyến nghị chốt

Nên chuyển từ mục tiêu lớn: “Đọc toàn bộ Lark để hiểu tất cả rồi mới làm tiếp”

sang mục tiêu nhỏ nhưng chắc: “Làm 1 pipeline chuẩn Lark → PG → Directus → PDF cho 1 loại tài liệu thật, rồi mở rộng dần.”

Đây là con đường khả thi nhất để vừa xây được kết nối giữa Lark và PG, vừa tạo giá trị ngay, vừa không bị chìm trong độ phức tạp của toàn hệ.