Tài liệu đào tạo nội bộ · Công ty TNHH Công nghệ PKH

Nghiệp vụ hệ thống PKHOffice

Tài liệu dành cho người phân tích nghiệp vụ (BA) mới nhận việc trên hệ thống Quản lý văn bản và điều hành. Không phải hướng dẫn bấm nút — phần đó nằm ở tài liệu hướng dẫn người dùng. Đây là mô hình nghiệp vụ, quy tắc, và những chỗ dễ hiểu sai.

PHẦN 1Hệ thống làm gì

Bối cảnh nghiệp vụ

PKHOffice giải quyết một việc: đưa quy trình ký văn bản hành chính từ giấy lên máy. Trước đây một tờ trình phải in ra, cầm đi xin ký lần lượt từng cấp, rồi mang xuống văn thư vào sổ và phát hành. Hệ thống làm đúng chuỗi đó nhưng bằng tệp PDF và chữ ký đóng lên tệp.

Bốn nhóm nghiệp vụ, theo đúng thứ tự quan trọng:

Nghiệp vụ văn bản hành chính Việt Nam chịu sự điều chỉnh của Nghị định 30/2020/NĐ-CP về công tác văn thư. Nghị định này quy định thể thức và kỹ thuật trình bày văn bản: quốc hiệu, tiêu ngữ, số và ký hiệu, nơi nhận, thể thức đề ký. BA làm việc trên hệ này cần biết NĐ30 tồn tại, vì nó là nguồn của nhiều quy tắc trong hệ thống — kể cả bộ luật kiểm tra thể thức bằng AI.

PHẦN 2Kiến trúc — điều quan trọng nhất phải biết

Nếu chỉ đọc được một phần của tài liệu này, đọc phần này

Vì sao lại như vậy: hệ mới được dựng lại từ hệ cũ theo cách chạy song song — người dùng chuyển dần sang hệ mới, trong khi hệ cũ vẫn phục vụ những nghiệp vụ chưa dựng lại xong. Hai hệ phải thấy cùng một dữ liệu, nếu không người dùng sẽ thấy hai sự thật khác nhau.

Mã nguồn hệ cũ không có sẵn — nó được dịch ngược từ tệp WAR đang chạy và nằm ở repo vps-old-refactor. Khi cần biết "hệ cũ làm thế nào", đọc mã dịch ngược đó là cách đáng tin nhất. Tài liệu thiết kế gốc không tồn tại.

PHẦN 3Từ vựng nghiệp vụ

Nói đúng từ thì mới hỏi đúng câu

PHẦN 4Vòng đời văn bản ký điện tử

Cột text.STATE — trạng thái của cả văn bản

Đường đi thuận lợi nhất của một văn bản:

Số liệu đếm từ cơ sở dữ liệu đang chạy, tháng 9/2026, đã loại văn bản bị xoá. STATE 4 chiếm đa số — phần lớn dữ liệu là văn bản đã hoàn tất.

Các nhánh rẽ khỏi đường thuận lợi:

PHẦN 5Luồng ký — mô hình quan trọng nhất

Bảng text_process — mỗi dòng là một lượt ký của một người

Đây là chỗ BA hay hiểu sai nhất, nên đọc kỹ. Một văn bản có nhiều dòng trong text_process, mỗi dòng là "người này phải ký văn bản này, ở cấp này, theo kiểu ký này". Ba cột quyết định nghiệp vụ:

SIGNATURE_TYPE — kiểu ký

Mã 1 chỉ xuất hiện trong báo cáo thời gian ký của hệ cũ, đi kèm cột REVIEW_NEW_LEVEL. Phải hỏi nghiệp vụ để chốt nghĩa của mã này trước khi viết bất cứ yêu cầu nào liên quan tới nó.

text_process.STATE — trạng thái của một lượt ký

Hai bảng, hai vai trò khác nhau

Có hai bảng dễ bị lẫn, phân biệt được là hiểu được luồng ký:

text_sign_next là thứ kích hoạt luồng ký. Có dòng text_process mà không có dòng text_sign_next nghĩa là "đã khai người ký nhưng chưa gửi đi".

PHẦN 6Vai trò và quyền

Bảng SYS_ROLE và USER_ROLE

Hệ thống có 23 vai trò khai trong bảng SYS_ROLE. Nhưng mã nguồn hệ mới chỉ thật sự kiểm 6 mã. Đây là khoảng cách BA cần nắm:

Một điểm về mô hình: vai trò luôn gắn với một đơn vị. Bảng USER_ROLE có cả SYS_ROLE_ID và SYS_ORGANIZATION_ID, nghĩa là một người có thể là Trưởng phòng ở đơn vị A và Nhân viên ở đơn vị B. Cột IS_DEFAULT đánh dấu vai trò hiện lên khi vừa đăng nhập.

PHẦN 7Mô hình dữ liệu — các bảng cần biết

Cơ sở dữ liệu vpdt có 328 bảng. Đây là 12 bảng BA sẽ gặp hàng ngày.

Hai điểm nữa về mô hình nhân sự, cùng là chỗ dễ sai:

• Bảng STAFF không có cột EMPLOYEE_ID. Nối sang vhr_employee phải qua STAFF.LOGINNAME = vhr_employee.USER_NAME.
• Nối theo USER_NAME không bảo đảm duy nhất: trong dữ liệu thật có một LOGINNAME ứng với 49 dòng vhr_employee. Khi cần cập nhật đúng một người, nối theo EMPLOYEE_ID.

PHẦN 8Sáu cái bẫy đã sập trong quá trình dựng lại

Mỗi cái đều là lỗi thật, mất thời gian thật

1. Lưu nháp mà người khác thấy trong hàng chờ ký

Khi cho phép lưu nháp cũng ghi người ký vào text_process, văn bản nháp lập tức xuất hiện trong màn "Ký duyệt" của người khác — vì truy vấn hàng chờ không lọc trạng thái nháp. Bài học nghiệp vụ: nháp là tài liệu riêng của người soạn, tuyệt đối không được lộ ra ngoài dù đã khai người ký.

2. Nhãn độ khẩn viết cứng, lệch với cơ sở dữ liệu

API trả danh sách độ khẩn viết cứng trong mã: mã 3 ghi "Rất khẩn", mã 4 ghi "Hoả tốc". Trong khi cơ sở dữ liệu ghi mã 3 = "Hỏa tốc", mã 4 = "Thượng khẩn". Người dùng chọn "Hoả tốc" thì hệ lưu thành "Thượng khẩn". Bài học: danh mục phải đọc từ cơ sở dữ liệu, đừng viết cứng.

3. Tệp đính kèm hệ cũ được mã hoá

Toàn bộ khoảng 127.000 tệp đính kèm cũ được mã hoá DES trên đĩa. Đọc trực tiếp ra chỉ thấy dữ liệu rác. Điều này ảnh hưởng mọi yêu cầu liên quan tới tệp: xem trước, tìm kiếm toàn văn, trích xuất nội dung.

4. Cơ sở dữ liệu chạy theo giờ UTC

MySQL trong hệ đặt múi giờ UTC, còn nghiệp vụ tính theo giờ Việt Nam (+07). Mọi yêu cầu có chữ "trong ngày", "theo tháng", "hạn xử lý" đều phải nói rõ tính theo giờ nào. Một hạn mức "theo ngày" tính sai múi giờ sẽ reset lúc 7 giờ sáng thay vì nửa đêm.

5. Đổi mật khẩu phải ghi vào hai bảng

Mật khẩu nằm ở cả STAFF và vhr_employee. Đổi một bảng thì người dùng vào được hệ mới nhưng không vào được hệ cũ. Mật khẩu băm theo cách của hệ cũ: base64 của SHA-1, không phải hex.

6. Giao diện từng in tên bảng cơ sở dữ liệu ra cho người dùng

Hộp thoại ký duyệt từng hiện câu "Hệ thống sẽ cập nhật text_process…" cho người dùng văn phòng đọc. Bài học cho BA: khi viết nội dung hiển thị trong yêu cầu, luôn viết bằng ngôn ngữ nghiệp vụ, đừng để lọt tên bảng, tên cột, mã trạng thái ra màn hình.

PHẦN 9Phạm vi còn thiếu

BA cần biết ranh giới hiện tại của hệ thống trước khi hứa với khách

Hệ có 207 endpoint. Phân loại theo mức độ thật sự dùng được:

Các nghiệp vụ chưa có ở cả hai đầu (không có API và cũng không có giao diện):

Về tính năng AI

Hệ có hai chức năng AI, cả hai chỉ mang tính tham khảo, không chặn quy trình ký:

• Tóm tắt văn bản — gọi nhà cung cấp AI, tốn phí mỗi lượt, có lưu lại để lần sau không gọi lại. Đo thực tế: khoảng 14.800 token, 0,018 USD, 10–15 giây một văn bản.
• Kiểm tra thể thức theo NĐ30 — chạy luật cục bộ, không tốn phí.

Điều BA phải biết: trong bộ luật kiểm thể thức, 9 trong 12 luật đang bị tắt vì đo được tỉ lệ báo nhầm trên 5% khi chạy với văn bản đã ban hành thật. Nghĩa là chức năng này hiện chỉ kiểm được một phần nhỏ. Đừng trình bày với khách như một công cụ kiểm thể thức hoàn chỉnh.

PHẦN 10Tự kiểm chứng — kỹ năng quan trọng nhất

Đừng tin tài liệu, kể cả tài liệu này. Hãy kiểm.

Tài liệu thiết kế gốc của hệ cũ không tồn tại. Tài liệu này viết dựa trên mã nguồn và dữ liệu đang chạy, nên có thể lạc hậu ngay khi mã nguồn đổi. Ba nguồn đáng tin, theo thứ tự:

Ba câu truy vấn nên biết

Đếm văn bản theo trạng thái — kiểm ngay số liệu ở Phần 4:

SELECT STATE, COUNT(*) FROM text
WHERE IS_DELETED IS NULL OR IS_DELETED = 0
GROUP BY STATE ORDER BY STATE;

Xem luồng ký thật của một văn bản — hiểu Phần 5 bằng ví dụ cụ thể:

SELECT SIGN_LEVEL, SIGNATURE_TYPE, STATE, EMP_VHR_ID, SEND_DATE, ACTION_DATE
FROM text_process WHERE TEXT_ID = <id>
ORDER BY SIGN_LEVEL, SIGNATURE_TYPE;

Xem một tính năng có thật sự được dùng hay không:

SELECT COUNT(*) FROM <tên_bảng>;

Bảng rỗng nghĩa là nghiệp vụ đó chưa ai dùng — dù giao diện và API có sẵn. Đây là cách nhanh nhất để biết một tính năng là thật hay chỉ tồn tại trên giấy.

Tài liệu kỹ thuật kèm theo