NĐ-LARK-01 — Kế hoạch dựng lại bản thiết kế vận hành 18 Lark Base

Trạng thái: DRAFT — chờ Owner đọc và góp ý trước khi mời Hội đồng AI review
Tác giả: Incomex Hội đồng AI / GPT
Ngày tạo: 2026-04-12
Loại tài liệu: Nhiệm vụ đơn lẻ / Planning SSOT draft
Mục tiêu: Dựng lại hiểu biết có kiểm soát về hệ thống Lark Base đang chạy để sửa chữa và nâng cấp an toàn

I. Bối cảnh

Hiện có một hệ thống Lark Base đang vận hành thật, đã kết nối được vào 18 Base trong folder nghiệp vụ. Nhân sự kỹ thuật nắm toàn bộ cấu trúc trước đây đã nghỉ việc. Trạng thái hiện tại là:

Hệ thống đang chạy, nhưng hiểu biết về cấu trúc và cơ chế vận hành không còn nằm trong tổ chức một cách đầy đủ.
Một phần dữ liệu đã đọc được qua Cổng 2 (chương trình đọc dữ liệu đã test chạy được).
Một phần dữ liệu đọc được qua Cổng 4 (Claude Desktop / Chrome extension / UI trực tiếp).
Dữ liệu cần khảo sát rất phức tạp: Base → Table → View → Field → Link / Lookup / Sync / Formula / Automation / Permission / Workflow.
Nếu không nhanh chóng dựng lại blueprint có kiểm soát, việc sửa chữa hoặc nâng cấp sẽ rơi vào trạng thái sửa mù, rủi ro làm gãy luồng đang chạy.

II. Mục tiêu

1. Mục tiêu tối thượng

Phải tạo ra một hệ thống khảo sát và lưu trữ có kiểm soát để:

Tải dữ liệu từ hệ thống Lark đang chạy về một cách đáng tin cậy.
Biết rõ đã tải được gì, chưa tải được gì, thiếu ở đâu, mâu thuẫn ở đâu.
Hiểu được các quan hệ giữa Base, Table, View, Field, Sync, Automation, Lookup, Formula và luồng dữ liệu thực tế.
Dựng lại bản thiết kế vận hành của hệ thống đang chạy.
Giữ lại bản thiết kế đó thành SSOT sống để về sau:
- sửa chữa phần đang hỏng,
- nâng cấp có kiểm soát,
- tránh phụ thuộc vào trí nhớ của một cá nhân.

2. Điều kiện hoàn thành

Nhiệm vụ chỉ được coi là hoàn thành khi có đủ 5 đầu ra sau:

A. Snapshot inventory — biết 18 base hiện có gì.
B. Coverage registry — biết phần nào đã đọc đủ, phần nào còn thiếu.
C. Dependency graph — biết bảng nào nối bảng nào bằng cơ chế gì.
D. Flow dossiers — biết các luồng nghiệp vụ chính đi ra sao.
E. Canonical blueprint — có tài liệu chuẩn để sửa và nâng cấp.

III. Nguyên tắc thực hiện

1. Raw trước, chuẩn hóa sau, suy luận cuối

Không được thiết kế theo kiểu đoán mô hình nghiệp vụ trước rồi ép dữ liệu vào. Phải đi theo thứ tự:

Lấy bằng chứng thô.
Lưu bằng chứng thô.
Chuẩn hóa phần nào chắc thì chuẩn hóa.
Chỉ suy luận khi đã có đủ dấu vết.

2. Cổng 2 là xương sống, Cổng 4 là bù khuyết + xác minh

Cổng 2 dùng làm nguồn chính cho dump lặp lại được, máy đọc được, có thể snapshot hàng loạt.
Cổng 4 dùng để đọc phần UI-only, phần API chưa expose đủ, hoặc để xác minh mâu thuẫn.
Không được dùng Cổng 4 làm xương sống cho toàn bộ hệ thống khảo sát.

3. Không sửa Lark trong lúc chưa có impact map

Trong giai đoạn khảo sát và dựng blueprint, mọi thay đổi vào schema / automation / relation của Lark phải được hạn chế tối đa. Nếu vừa khảo sát vừa sửa, blueprint sẽ lệch và mất giá trị làm SSOT.

4. Mọi phát hiện phải có trạng thái tin cậy

Mỗi kết luận kỹ thuật phải có mức độ chắc chắn:

HIGH — xác nhận trực tiếp từ raw evidence rõ ràng
MEDIUM — suy ra từ nhiều bằng chứng hội tụ
LOW — nghi vấn, cần xác minh thêm

5. Mọi thứ phải quay về Agent Data làm SSOT

Kết quả khảo sát không được nằm rải rác ở chat, ghi chú cá nhân hay máy cục bộ. Tài liệu chuẩn phải được đưa về Agent Data ở path chuẩn để các agent khác cùng đọc, review và dùng lại.

IV. Giải pháp tổng thể

Ô 1 — Dựng kho khảo sát trung tâm

Dùng PostgreSQL làm kho khảo sát để lưu:

dữ liệu thô lấy từ Cổng 2 / Cổng 4,
dữ liệu đã chuẩn hóa,
trạng thái coverage,
mâu thuẫn giữa các cổng,
snapshot theo thời điểm.

Ô 2 — Tách dữ liệu thành 3 lớp

2.1. Lớp raw evidence

Lưu nguyên liệu gốc theo snapshot. Ví dụ:

raw payload table list
raw payload field list
raw automation list
raw automation config
raw UI capture notes
raw permission payload

2.2. Lớp registry chuẩn hóa

Bóc ra các thực thể chuẩn:

bases
tables
fields
views
automations
relations

2.3. Lớp coverage & audit

Theo dõi:

đã lấy gì,
còn thiếu gì,
lấy từ cổng nào,
lúc nào,
có lỗi không,
có xung đột không,
confidence bao nhiêu.

Ô 3 — Không dựng kiến trúc quá lớn từ đầu

Bản đầu tiên phải đủ đơn giản để chạy được. Không làm data lake, không làm graph DB riêng, không cố mô hình hóa 100% semantics của automation ngay từ vòng đầu.

Ô 4 — Dùng PG + JSONB + Registry là phương án tối giản nhưng chắc

Thiết kế đề xuất:

PostgreSQL làm kho trung tâm
JSONB để chứa payload đa hình / phức tạp
một lớp registry để chuẩn hóa phần chắc chắn nhất
một lớp coverage để kiểm soát tiến độ và độ đầy đủ

Ô 5 — Chỉ vẽ blueprint từ dữ liệu có coverage

Không được vẽ sơ đồ từ cảm giác hoặc từ một vài ví dụ rời rạc. Chỉ vẽ blueprint khi đã biết:

dữ liệu đó lấy từ đâu,
coverage đang ở mức nào,
confidence ra sao,
có gap nào chưa khép kín không.

V. Thiết kế kỹ thuật tối giản đề xuất cho PG

5.1. Mục tiêu của PG

PG ở đây không thay thế Lark. PG là:

kho khảo sát,
registry kỹ thuật,
nơi quản lý snapshot,
nơi query dependency,
nơi kiểm soát coverage.

5.2. Thiết kế tối giản bản v1

Chỉ cần 7 bảng lõi để khởi động:

1. `snapshots`

Một lần chạy khảo sát = một snapshot.

Trường tối thiểu:

snapshot_id
taken_at
source_type (gate2, gate4, mixed)
run_label
status
notes

2. `payloads_raw`

Lưu raw evidence.

Trường tối thiểu:

payload_id
snapshot_id
base_key
entity_kind (base, table_list, field_list, view_list, automation_list, automation_config, permission, form, record_sample)
entity_ref
fetch_method
content_jsonb
content_hash
is_complete
error_code
error_message

3. `bases`

base_id
snapshot_id
app_token
base_name
folder_name
owner_name
confidence

4. `tables`

table_id
snapshot_id
base_id
table_name
table_kind_guess
config_jsonb
confidence

5. `fields`

field_id
snapshot_id
table_id
field_name
field_type
is_required
config_jsonb
confidence

6. `relations`

relation_id
snapshot_id
src_table_id
src_field_id
relation_type (link, lookup, sync, formula_ref, automation_trigger, automation_writeback)
dst_base_id
dst_table_id
dst_field_id
evidence_payload_id
confidence
notes

7. `coverage`

coverage_id
snapshot_id
base_key
entity_kind
entity_ref
probe_type
status (done, partial, missing, error)
source_type
evidence_payload_id
notes

5.3. Quy tắc thiết kế dữ liệu

Cột chuẩn cho phần ổn định.
JSONB cho phần phức tạp / chưa ổn định / khác nhau giữa các cổng.
Không relationalize sâu automation ngay ở bản đầu.
Coverage là bảng bắt buộc, không phải phụ trợ.

VI. Kế hoạch triển khai chi tiết

Giai đoạn 0 — Chốt đầu bài và khóa phạm vi

Bước 0.1

Chốt rằng phạm vi hiện tại là 18 Lark Base đã kết nối được trong folder mục tiêu.

Bước 0.2

Chốt output phải có:

inventory,
coverage,
dependency graph,
flow dossiers,
canonical blueprint.

Bước 0.3

Chốt nguyên tắc: trong giai đoạn dựng blueprint, hạn chế sửa trực tiếp vào Lark nếu chưa có impact map.

Đầu ra giai đoạn 0: một planning document được owner đồng ý về mục tiêu và phạm vi.

Giai đoạn 1 — Chuẩn bị kho khảo sát

Bước 1.1

Tạo schema PG tối giản bản v1 với 7 bảng lõi nêu trên.

Bước 1.2

Định nghĩa enum / rule tối thiểu:

source_type,
entity_kind,
coverage status,
confidence level,
relation_type.

Bước 1.3

Tạo run convention:

mỗi lần dump là 1 snapshot_id,
snapshot phải có timestamp,
snapshot phải biết lấy từ cổng nào,
mọi payload raw phải gắn snapshot.

Bước 1.4

Viết checklist expected inventory cho từng base:

base metadata,
table list,
field list,
view list,
automation list,
automation config,
permissions,
forms,
sample records nếu cần.

Đầu ra giai đoạn 1: kho PG chạy được + checklist expected inventory.

Giai đoạn 2 — Dump có kiểm soát bằng Cổng 2

Bước 2.1

Dùng Cổng 2 chạy hàng loạt qua 18 base để lấy toàn bộ phần đọc được.

Bước 2.2

Mọi dữ liệu đọc được phải ghi vào payloads_raw trước khi parse.

Bước 2.3

Sau mỗi lần ghi raw, cập nhật coverage theo entity:

done,
partial,
missing,
error.

Bước 2.4

Parse lớp đầu tiên từ raw sang:

bases
tables
fields

Bước 2.5

Sinh báo cáo coverage đầu tiên:

base nào đủ inventory cơ bản,
base nào thiếu fields,
base nào chưa có views,
phần nào Cổng 2 chưa đọc được.

Đầu ra giai đoạn 2: snapshot nền bằng Cổng 2 cho toàn bộ 18 base.

Giai đoạn 3 — Lấp gap có chọn lọc bằng Cổng 4

Bước 3.1

Từ coverage, lập danh sách gap cần Cổng 4 bù khuyết.

Bước 3.2

Ưu tiên Cổng 4 cho các loại dữ liệu sau:

sync setup,
UI-only options,
automation details chưa expose qua Cổng 2,
stage / config đặc biệt,
trường hợp API và UI mâu thuẫn.

Bước 3.3

Mọi dữ liệu lấy từ Cổng 4 cũng phải lưu raw trước.

Bước 3.4

Gắn confidence cho từng phát hiện:

trực tiếp thấy trong UI,
suy luận từ cấu hình,
chưa resolve trọn vẹn.

Bước 3.5

Cập nhật lại coverage sau khi bù khuyết.

Đầu ra giai đoạn 3: coverage được nâng từ “có inventory nền” lên “đủ để hiểu quan hệ và flow”.

Giai đoạn 4 — Chuẩn hóa quan hệ và dependency graph

Bước 4.1

Sinh relations từ các nguồn:

link fields,
lookup fields,
sync config,
formula references,
automation trigger / writeback.

Bước 4.2

Đánh dấu loại cạnh quan hệ.

Bước 4.3

Đánh dấu cạnh nào chắc chắn, cạnh nào còn nghi vấn.

Bước 4.4

Sinh ra 3 lớp sơ đồ kỹ thuật:

base map,
table relation map,
dependency heatmap.

Bước 4.5

Tìm master tables / transaction tables / reporting tables / staging tables.

Đầu ra giai đoạn 4: dependency graph của toàn bộ hệ thống Lark khảo sát được.

Giai đoạn 5 — Reverse-engineer luồng dữ liệu

Bước 5.1

Chọn ra các luồng nghiệp vụ lớn nhất và quan trọng nhất trước.

Bước 5.2

Với mỗi luồng, bắt buộc trả lời 7 câu:

dữ liệu sinh ở đâu,
ai nhập,
trigger nào chạy,
sang bảng nào,
field nào lookup / sync / formula,
trạng thái nào đổi,
đầu ra cuối cùng là gì.

Bước 5.3

Mỗi luồng được ghi thành một flow dossier riêng.

Bước 5.4

Nếu luồng còn đứt đoạn, không suy diễn bừa. Ghi rõ chỗ chưa đủ bằng chứng.

Đầu ra giai đoạn 5: bộ hồ sơ luồng nghiệp vụ thực tế.

Giai đoạn 6 — Soạn canonical blueprint

Bước 6.1

Từ inventory + coverage + relations + flow dossiers, soạn tài liệu blueprint tổng.

Bước 6.2

Blueprint tổng phải có 6 phần:

Tổng quan 18 base
Danh mục base/table/view/field chính
Quan hệ dữ liệu
Workflow / automation
Luồng nghiệp vụ chính
Rủi ro khi sửa đổi

Bước 6.3

Mỗi phát biểu trong blueprint phải truy ngược được về raw evidence hoặc registry record.

Bước 6.4

Tài liệu này trở thành SSOT chuẩn cho giai đoạn sửa chữa và nâng cấp.

Đầu ra giai đoạn 6: Lark System Blueprint bản đầu tiên.

Giai đoạn 7 — Chuẩn bị cho sửa chữa và nâng cấp

Bước 7.1

Làm impact matrix:

sửa field nào ảnh hưởng đâu,
bỏ automation nào gãy đâu,
đổi sync nào nổ dây chuyền nào.

Bước 7.2

Xác định khu vực rủi ro cao nhất của hệ thống.

Bước 7.3

Chia việc hậu blueprint thành 3 nhóm:

sửa lỗi đang hỏng,
vá vùng thiếu kiểm soát,
nâng cấp có kế hoạch.

Đầu ra giai đoạn 7: bộ tài liệu sẵn sàng cho phase repair / upgrade.

VII. Cơ chế cập nhật tiến độ

7.1. Nhịp cập nhật

Mỗi snapshot hoặc mỗi batch khảo sát phải cập nhật 3 thứ:

snapshot mới,
coverage mới,
ghi chú gap / conflict mới.

7.2. Báo cáo tiến độ tối thiểu

Mỗi lần cập nhật phải trả lời được:

đã chạy base nào,
đã lấy được loại dữ liệu nào,
còn thiếu loại nào,
phát hiện mới là gì,
mức độ chắc chắn ra sao.

7.3. Quy tắc đưa lên Agent Data

Các đầu ra cần được ghi vào Agent Data theo nhịp sau:

planning doc: 1 file trung tâm
mỗi snapshot lớn: 1 báo cáo trạng thái
mỗi flow dossier: 1 file riêng
blueprint tổng: 1 file SSOT tổng hợp

VIII. Tiêu chí thành công

Kế hoạch này được xem là thành công khi đạt đồng thời 6 tiêu chí:

Có thể dump dữ liệu từ 18 base về một cách lặp lại được.
Có bảng coverage để biết đủ / thiếu / lỗi / mâu thuẫn.
Có registry chuẩn hóa đủ để query quan hệ.
Có dependency graph thật, không phải vẽ tay cảm tính.
Có flow dossiers cho các luồng nghiệp vụ chính.
Có blueprint đủ chắc để dùng cho sửa chữa và nâng cấp.

IX. Rủi ro chính và cách khống chế

Rủi ro 1 — Chìm trong độ phức tạp

Khống chế: chỉ dùng schema PG tối giản bản v1, raw trước, JSONB cho phần chưa ổn định.

Rủi ro 2 — Cổng 2 không đọc hết

Khống chế: dùng coverage để bộc lộ gap, dùng Cổng 4 bù chọn lọc.

Rủi ro 3 — Vẽ blueprint từ dữ liệu chưa đủ

Khống chế: mọi sơ đồ phải gắn confidence và coverage.

Rủi ro 4 — Vừa khảo sát vừa sửa hệ thống

Khống chế: khóa nguyên tắc không sửa mù khi chưa có impact map.

Rủi ro 5 — Tài liệu phân tán, mất SSOT

Khống chế: mọi đầu ra quay về Agent Data theo path chuẩn.

X. Đề xuất bước tiếp theo ngay sau khi owner duyệt bản này

Chốt path SSOT chính thức cho NĐ-LARK-01.
Mời Hội đồng AI review bản DRAFT này.
Sau review, ban hành bản v1 chính thức.
Tách tiếp thành:
- kế hoạch triển khai kỹ thuật PG,
- checklist dump Cổng 2,
- checklist bù gap Cổng 4,
- template flow dossier,
- template blueprint tổng.

XI. Kết luận ngắn

Bài toán này không được giải bằng trí nhớ, cũng không được giải bằng cách vẽ sơ đồ từ cảm giác. Cách đúng là dựng một kho khảo sát có kiểm soát, lấy raw evidence đáng tin cậy, chuẩn hóa có chọn lọc, kiểm soát coverage, rồi mới reverse-engineer blueprint của hệ thống đang chạy.

Đây là con đường đơn giản nhất mà vẫn đủ chắc để sửa chữa và nâng cấp về sau.