Tài liệu đặc tả thiết kế phần mềm: từ yêu cầu sang kiến trúc

Tài liệu đặc tả thiết kế phần mềm ghi lại cách hệ thống được xây, khác với đặc tả yêu cầu mô tả hệ thống phải làm gì. Một tài liệu dùng được có chín phần, trong đó phần quan trọng nhất là quyết định kiến trúc kèm lựa chọn đã cân nhắc và lý do loại bỏ.

Tóm tắt nhanh

• Đặc tả yêu cầu trả lời "làm gì"; đặc tả thiết kế trả lời "làm bằng cách nào và vì sao".
• Giá trị lớn nhất của tài liệu thiết kế là ghi lại lựa chọn đã loại bỏ, không phải mô tả cấu trúc thư mục.
• Chín phần: bối cảnh, ràng buộc, quyết định kiến trúc, mô hình dữ liệu, giao diện, luồng xử lý, phi chức năng, triển khai, truy vết.
• Một quyết định thiết kế nên có ít nhất ba lựa chọn và tiêu chí chấm điểm.
• Tài liệu không có phần truy vết sẽ không chứng minh được yêu cầu nào đã được đáp ứng.

Đặc tả thiết kế khác đặc tả yêu cầu ở đâu

Hai tài liệu này không thay thế nhau. Thiếu đặc tả yêu cầu, đội kỹ thuật tự quyết định phạm vi. Thiếu đặc tả thiết kế, đội kỹ thuật tự quyết định kiến trúc, và người vận hành không biết hệ thống chạy thế nào khi có sự cố.

Chín phần của một tài liệu thiết kế dùng được

Độ dài gợi ý này dành cho một hệ thống nghiệp vụ cỡ vừa; với hệ thống lớn, mỗi phần có thể tách thành tài liệu riêng.

Phần 1 đến 3: bối cảnh, ràng buộc và quyết định

Bối cảnh nên viết ngắn và cụ thể. Một đoạn mô tả người dùng, vấn đề và phạm vi. Tránh mô tả lại toàn bộ đặc tả yêu cầu; chỉ cần đủ để người đọc hiểu vì sao hệ thống tồn tại.

Ràng buộc là phần hay bị bỏ nhưng lại quyết định phần lớn thiết kế. Ràng buộc gồm công nghệ hiện có, hạ tầng được phép dùng, yêu cầu pháp lý về lưu trữ dữ liệu, thời hạn, và năng lực của đội vận hành. Một thiết kế đúng về mặt kỹ thuật nhưng vượt năng lực vận hành là thiết kế sai.

Quyết định kiến trúc là phần có giá trị nhất. Mỗi quyết định nên được viết thành một mục ngắn gồm bốn dòng: quyết định là gì, các lựa chọn đã xem xét, lý do chọn, và điều gì sẽ khiến quyết định này bị xem lại. Dòng thứ tư quan trọng vì nó biến quyết định thành thứ có thể kiểm tra theo thời gian.

Phần 4 đến 6: dữ liệu, giao diện và luồng xử lý

Mô hình dữ liệu nên có ba thứ: danh sách thực thể kèm ý nghĩa, quan hệ giữa chúng, và các quy tắc toàn vẹn không thể biểu diễn bằng khoá ngoại. Quy tắc toàn vẹn là phần hay bị bỏ nhất, ví dụ "một đơn hàng không thể chuyển sang trạng thái đã giao nếu chưa có ngày xuất kho".

Giao diện gồm hai loại: giao diện giữa các thành phần bên trong và giao diện với hệ thống bên ngoài. Với loại thứ hai, cần ghi rõ định dạng, cách xử lý lỗi, cách thử lại và giới hạn tần suất. Đây là phần gây sự cố nhiều nhất khi tích hợp.

Luồng xử lý nên có ba loại: luồng chính, luồng lỗi, luồng biên. Luồng chính là trường hợp bình thường. Luồng lỗi là khi một bước thất bại, ví dụ thanh toán bị từ chối. Luồng biên là khi dữ liệu bất thường, ví dụ đơn hàng không có mặt hàng hoặc số tiền bằng không. Ba loại này đủ để người kiểm thử viết kịch bản.

Phần 7 đến 9: phi chức năng, triển khai và truy vết

Phi chức năng cần viết thành con số kiểm tra được. "Hệ thống phải nhanh" không kiểm tra được. "Trang danh sách tải xong trong 2 giây với 5.000 bản ghi trên mạng 4G" kiểm tra được. Các nhóm nên có: thời gian phản hồi, số người dùng đồng thời, dung lượng lưu trữ, thời gian sao lưu, thời gian khôi phục.

Triển khai cần ghi môi trường, cách cấu hình, quy trình phát hành, cách quay lui, và cách giám sát. Phần này thường được viết bởi người vận hành, không phải người thiết kế, vì nó phản ánh ràng buộc thực tế của hạ tầng.

Truy vết là một bảng hai cột: mã yêu cầu và phần thiết kế tương ứng. Bảng này cho phép trả lời hai câu hỏi quan trọng: yêu cầu nào chưa có thiết kế, và phần thiết kế nào không phục vụ yêu cầu nào. Câu hỏi thứ hai giúp loại bỏ phần thừa trước khi xây.

Một quyết định thiết kế viết theo ba lựa chọn

Ví dụ: hệ thống cần gửi thông báo cho khách hàng khi đơn hàng đổi trạng thái. Có ba cách.

Cách A: gửi đồng bộ trong luồng xử lý. Khi trạng thái đổi, gọi dịch vụ gửi tin ngay và chờ kết quả. Ưu điểm là đơn giản, biết ngay thành công hay thất bại. Nhược điểm là nếu dịch vụ gửi tin chậm hoặc lỗi, thao tác đổi trạng thái cũng chậm hoặc lỗi theo.

Cách B: đưa vào hàng đợi, gửi bất đồng bộ. Thao tác đổi trạng thái ghi vào hàng đợi rồi trả về ngay; một tiến trình khác gửi tin. Ưu điểm là tách rời độ tin cậy của hai hệ thống. Nhược điểm là cần thêm hạ tầng, cần xử lý thử lại và cần cách xem trạng thái gửi.

Cách C: quét định kỳ. Một tác vụ chạy mỗi vài phút, tìm các bản ghi chưa gửi và gửi. Ưu điểm là đơn giản nhất, không cần hạ tầng mới. Nhược điểm là độ trễ, và khó xử lý khi số lượng bản ghi lớn.

Với một hệ thống bán hàng có vài trăm đơn mỗi ngày, cách C thường đủ và rẻ nhất. Với hệ thống có vài chục nghìn đơn mỗi ngày, cách B phù hợp hơn. Cách A chỉ nên dùng khi thông báo không quan trọng và lưu lượng thấp.

Cả ba cách đều đúng về mặt kỹ thuật; quyết định phụ thuộc vào ràng buộc. Tài liệu thiết kế tốt ghi lại cả ba và lý do chọn, để sau này khi lưu lượng tăng, người đọc biết khi nào nên xem lại.

Câu hỏi thường gặp

Tài liệu thiết kế có bắt buộc phải dài không?

Không. Độ dài phụ thuộc vào số quyết định cần ghi lại, không phụ thuộc vào quy mô dự án. Một hệ thống nhỏ có thể có tài liệu thiết kế năm trang nếu các quyết định đơn giản. Một hệ thống tích hợp nhiều bên có thể cần ba mươi trang vì có nhiều quyết định về giao diện và xử lý lỗi.

Nên viết tài liệu thiết kế trước hay sau khi xây?

Trước khi xây phần chính, và cập nhật trong quá trình xây. Mục đích của tài liệu là giúp người khác rà quyết định trước khi chi phí sửa còn thấp. Viết hoàn toàn sau khi xây chỉ tạo ra bản mô tả, không tạo ra cơ hội phát hiện sai.

Ai nên viết tài liệu thiết kế?

Người trực tiếp ra quyết định kỹ thuật, thường là kiến trúc sư hoặc trưởng nhóm kỹ thuật, viết phần quyết định. Người vận hành viết phần triển khai. Người phụ trách nghiệp vụ xác nhận phần luồng xử lý. Cách phân công này giữ nguyên tắc: người hiểu rủi ro nhất viết phần tương ứng.

Tài liệu thiết kế có cần cập nhật khi hệ thống thay đổi không?

Có, nhưng theo cách có kiểm soát. Không nên viết lại toàn bộ tài liệu mỗi lần thay đổi. Cách làm phổ biến là thêm quyết định mới, đánh dấu quyết định cũ đã bị thay thế, và ghi ngày. Như vậy người đọc vẫn thấy được lịch sử lý do, không chỉ thấy trạng thái hiện tại.

Cập nhật và kiểm chứng

Cập nhật tháng 11/2026. Phần bàn giao tài liệu và mã nguồn được đối chiếu với:

• Luật Sở hữu trí tuệ số 50/2005/QH11, sửa đổi bởi Luật số 131/2025/QH15 — vanban.chinhphu.vn
• Nghị định số 17/2023/NĐ-CP, phần bảo hộ chương trình máy tính — vanban.chinhphu.vn

Đây không phải tư vấn pháp lý hay tư vấn thuế. Cấu trúc tài liệu phù hợp phụ thuộc vào sản phẩm và đội ngũ cụ thể; nội dung bài viết là khung tham chiếu, không phải mẫu bắt buộc.

Bài viết liên quan: mẫu tài liệu đặc tả API, quy trình kiểm thử phần mềm là gì, quy trình phát triển phần mềm là gì và thuế GTGT của phần mềm là bao nhiêu.

Nếu bạn cần một bản đặc tả đủ rõ để đội kỹ thuật không phải tự đoán quyết định, WinSell xây dựng phần mềm theo yêu cầu theo bốn giai đoạn Khám phá, Đặc tả, Xây dựng, Bàn giao và đo lường — xem dịch vụ của WinSell. Báo giá sau khi chốt phạm vi.