Viết connector cho hệ thống tài liệu văn phòng luật: bài học từ tin tuyển FDE của Legora

Thử hình dung tuần đầu bạn làm việc tại một văn phòng luật. Các partner muốn hỏi đáp trên tài liệu của từng vụ việc (matter) đang nằm trong iManage. Buổi họp kỹ thuật đầu tiên gần như không ai nhắc đến model.

Trưởng bộ phận IT chỉ hỏi một câu: nếu luật sư A đang bị chặn khỏi vụ X, hệ thống của bạn có để lộ trang nào của vụ X cho A không?

Công việc của bạn bắt đầu từ chính câu hỏi ấy. Legora mô tả vị trí FDE của mình là nằm giữa product engineering và customer success. Người làm vị trí này ngồi cùng khách hàng doanh nghiệp trong và sau deployment, viết code production để nối nền tảng của Legora với hệ thống của khách hàng.

Tin tuyển dụng ghi rõ những gì cần biết: các DMS như iManage, SharePoint hoặc NetDocuments, SSO qua SAML và OIDC, API kiểu REST và webhook.

Đi kèm là một trách nhiệm cụ thể: xây và duy trì connector, script tự động hóa và công cụ dùng lại được, để các lần deployment sau chạy nhanh hơn.

Kỹ năng này không chỉ dùng ở Legora. Bạn mang được nó sang bất kỳ công ty nào bán phần mềm cho ngành có dữ liệu nhạy cảm.

Ai là chủ của tài liệu?

Khi Legora ra mắt hệ sinh thái tích hợp vào tháng 10/2026, họ nhấn mạnh một nguyên tắc: luật sư có thể duyệt, tìm và làm việc với tài liệu của vụ việc ngay trong Legora, nhưng nền tảng gốc vẫn là system of record. Câu này nghe như ghi chú cho marketing. Thực ra đây là yêu cầu thiết kế quan trọng nhất của connector.

Nguyên tắc này có hai hệ quả. DMS vẫn giữ bản chính thức của tài liệu, cùng các phiên bản, metadata và lịch sử chỉnh sửa, nên connector không được tạo ra một bản sao để rồi dần lệch khỏi bản gốc. Quyền truy cập cũng do DMS quyết định chứ không phải do bạn.

Theo LawNext, với tích hợp iManage, quyền trong iManage quyết định mỗi người dùng lấy được gì. Artificial Lawyer cũng viết rằng các ethical wall và giới hạn bảo mật mà văn phòng đang áp dụng sẽ quyết định Legora được phép truy xuất những gì.

Ethical wall là bức tường ngăn một luật sư tiếp cận hồ sơ khi có xung đột lợi ích. Để tài liệu lọt qua bức tường này là sự cố nghiêm trọng, không còn là một lỗi kỹ thuật thông thường.

Một interface, nhiều adapter

Vì sao tin tuyển dụng nhấn mạnh chữ “dùng lại được”? Văn phòng này dùng iManage, văn phòng sau dùng NetDocuments, văn phòng sau nữa lưu hết trên SharePoint. Nếu lần nào cũng viết lại từ đầu, kinh nghiệm của bạn không cộng dồn được.

Cách tách hợp lý là một interface chung cho ứng dụng gọi vào, bên dưới là adapter riêng cho từng DMS. Đoạn phác thảo sau là ví dụ minh họa thiết kế, không phải code của Legora:

from typing import Protocol

class DMSConnector(Protocol):
    def search(self, user: UserIdentity, query: str,
               matter_id: str | None = None) -> list[DocRef]: ...
    def fetch(self, user: UserIdentity, doc: DocRef) -> DocContent: ...
    def handle_event(self, event: dict) -> None: ...  # webhook: doc moved, permission changed

class IManageAdapter:
    def search(self, user, query, matter_id=None):
        token = self.tokens.for_user(user)  # user's own token, never a service account
        return self.client.search(query, matter=matter_id, auth=token)

    def fetch(self, user, doc):
        token = self.tokens.for_user(user)
        # the DMS checks permissions again on every read
        return self.client.get_document(doc.id, auth=token)

    def handle_event(self, event):
        if event["type"] in ("permission_changed", "document_moved"):
            # drop results computed under the old permissions
            self.cache.invalidate(matter_id=event["matter_id"])

Chi tiết đáng chú ý là UserIdentity có mặt trong mọi hàm. Mỗi lời gọi đều mang danh tính của người đang hỏi, lấy từ SSO (SAML hoặc OIDC), và adapter dùng chính danh tính đó để gọi DMS. Nhờ vậy DMS tự lọc theo quyền của người đó, cả khi tìm lẫn khi mở tài liệu, và bạn không phải chép lại logic phân quyền.

Thiết kế này còn có lợi khi cách kết nối thay đổi. Theo LawNext, Legora đã tích hợp iManage qua API và dự định kết nối thêm với iManage MCP Server.

Bản tin ra mắt hệ sinh thái cũng nói iManage và NetDocuments được nối qua Model Context Protocol cho phần tri thức và tìm kiếm. Nếu kiểu kết nối chỉ nằm trong adapter, bạn thay adapter mà không phải đụng vào interface hay bộ test quyền.

Ma trận sáu ô trước khi go-live

Ethical wall cần được kiểm thử như kiểm thử bảo mật. Lấy một kịch bản giả định với hai vụ việc và ba luật sư. An làm vụ 1001. Bình làm vụ 1002. Chi là luật sư của văn phòng, chưa từng tham gia vụ 1001, nhưng bị ethical wall chặn khỏi vụ này vì xung đột lợi ích.

Người dùng	Tìm trong vụ 1001	Tìm trong vụ 1002
An	Có kết quả	Rỗng
Bình	Rỗng	Có kết quả
Chi (bị ethical wall chặn khỏi 1001)	Rỗng, kể cả khi gõ đúng tên tài liệu	Rỗng

Ba người nhân hai vụ ra sáu ô, mỗi ô là một test tự động. Ô quan trọng nhất là của Chi ở vụ 1001. Nếu index tìm kiếm được dựng bằng một service account có quyền đọc toàn bộ, ô đó gần như chắc chắn sẽ trả về kết quả, tức là có rò rỉ.

Bạn cũng nên chạy lại ma trận sau mỗi lần đổi quyền. Gỡ An khỏi vụ 1001 trong DMS, gửi sự kiện webhook vào hàm handle_event, rồi kiểm tra xem lần tìm tiếp theo của An đã trả về rỗng chưa. Cache cũ thường âm thầm làm hỏng mọi thứ ở đúng chỗ này.

Làm từ đầu đến cuối ở khách hàng

Legora giao cho FDE trọn quá trình technical scoping, từ thu thập yêu cầu đến thiết kế kiến trúc tích hợp. Ở văn phòng luật, buổi scoping nên trả lời được bốn câu. DMS nào, chạy cloud hay on-premise? SSO dùng SAML hay OIDC? Ethical wall được cấu hình ở đâu? DMS có phát webhook khi quyền thay đổi không?

Sau đó, thứ tự làm nên là: interface, adapter, ánh xạ danh tính, ma trận test, xử lý webhook, rồi mới đến tính năng hỏi đáp. Nhiều người làm ngược lại vì phần hỏi đáp dễ gây ấn tượng trong demo. Nhưng chỉ một lần lộ dữ liệu là đủ để mất hợp đồng.

Bước cuối hay bị bỏ qua là đưa những gì học được về cho Engineering và Product. Tin tuyển dụng của Legora ghi rõ FDE làm việc cùng hai nhóm này để cải thiện cả tích hợp lẫn sản phẩm chung.

Nếu bạn phải tự viết một đoạn ánh xạ nhóm quyền ở ba khách hàng liên tiếp, đó là dấu hiệu nó nên trở thành một phần của connector chuẩn.

Những lỗi khiến connector không dùng lại được

Lỗi phổ biến nhất là chép cả DMS sang một kho riêng để tìm cho nhanh. Làm vậy vi phạm cả hai nguyên tắc: bản sao sẽ lệch khỏi system of record, và quyền truy cập bị đóng băng ở thời điểm chép.

Lỗi thứ hai là để logic riêng của từng khách hàng lọt vào interface chung, ví dụ một trường matter_code_format_firmB. Mọi khác biệt nên nằm trong adapter hoặc file cấu hình.

Lỗi thứ ba là bỏ qua bước ánh xạ danh tính. Email trong SSO và tên đăng nhập trong DMS không phải lúc nào cũng khớp. Chỉ cần ánh xạ sai một người là ma trận test mất hết ý nghĩa.

Thể hiện kỹ năng này trong CV

Khi đọc tin tuyển FDE, hãy để ý các cụm như “reusable connectors”, tên DMS cụ thể, SAML/OIDC và webhook. Chúng cho thấy công việc thiên về tích hợp nhiều hơn là demo.

Trong CV, đừng chỉ viết “tích hợp SharePoint”. Hãy viết rằng bạn xây một connector, dùng lại ở mấy deployment, kiểm thử phân quyền bằng bao nhiêu test case và không để lộ tài liệu nào qua ethical wall. Nhà tuyển dụng đọc dòng đó sẽ hiểu bạn đã thật sự trả lời được câu hỏi của trưởng bộ phận IT.

Model sẽ còn thay đổi, và cách kết nối cũng vậy, từ REST sang MCP rồi sang chuẩn tiếp theo. Câu hỏi “ai được xem gì” thì không đổi, và FDE nào trả lời câu đó bằng test thay vì bằng lời hứa sẽ được khách hàng tin.