Tài liệu Basic Design và Detail Design trong dự án Nhật
Trong những năm đầu đi làm và có cơ hội làm việc các dự án Nhật, tôi được tham gia vào nhiều dự án phát triển hệ thống quản lý sản xuất.
Qua quá trình đó, tôi nhận ra cách người Nhật tổ chức tài liệu thiết kế phần mềm
— gồm Basic Design và Detail Design
— là nền tảng cốt lõi của toàn bộ quy trình phát triển. Mọi thứ được mô tả chi tiết, có quy tắc, và giúp đội dự án hiểu cùng một ngôn ngữ.
Bài viết này chia sẻ cách hiểu, cấu trúc và phương pháp viết tài liệu thiết kế phần mềm trong môi trường dự án Nhật Bản, dựa trên kinh nghiệm thực tế triển khai nhiều module sản xuất khác nhau.
(Lưu ý: các ảnh trong bài đăng được tham khảo từ nhiều nguồn kỹ thuật trang web Nhật để giúp minh họa rõ hơn cho nội dung)
1. Phân biệt Basic Design và Detail Design
Basic Design (基本設計書) là tài liệu mô tả tổng quan hệ thống: định nghĩa phạm vi, quy tắc nghiệp vụ, và luồng xử lý chính.
Đây là giai đoạn “thiết kế khung”.
Detail Design (詳細設計書) là tài liệu triển khai chi tiết, mô tả rõ cách hệ thống hoạt động bên trong: logic xử lý, cấu trúc dữ liệu, và cách các thành phần giao tiếp với nhau.
Đây là bước “thiết kế chi tiết kỹ thuật”.
Basic Design giúp toàn bộ nhóm hiểu “hệ thống cần làm gì”,
Detail Design giúp kỹ sư nắm rõ “hệ thống sẽ làm như thế nào”.
Hai giai đoạn này gắn liền với nhau và quyết định trực tiếp đến chất lượng dự án.
2. Cấu trúc của Basic Design
Trong dự án Nhật, Basic Design thường có cấu trúc tiêu chuẩn như sau:
- Tên hệ thống và module: ví dụ “生産管理システム (Production Management System)”.
- Tên màn hình hoặc chức năng: ví dụ “P_I201 – 生産指示登録画面 (Màn hình đăng ký lệnh sản xuất)”.
- Mục tiêu: mô tả mục đích nghiệp vụ của chức năng (ví dụ: đăng ký, sửa, xóa lệnh sản xuất theo mã sản phẩm).
- Luồng xử lý tổng quan: trình bày sơ đồ xử lý từ nhập dữ liệu đến lưu trữ và phản hồi.
- Dữ liệu chính: mô tả các bảng liên quan như ProductionOrder, ProductMaster, LineMaster…
- Quy tắc nghiệp vụ: mô tả ràng buộc (ví dụ: ngày chỉ thị không nhỏ hơn ngày hiện tại, số lượng > 0).
3. Cấu trúc chi tiết của Detail Design
Detail Design cụ thể hóa từng nội dung của Basic Design để lập trình viên có thể triển khai chính xác. Dưới đây là cấu trúc thông thường trong dự án Nhật:
3.1. Thông tin chung về màn hình / chức năng
Ví dụ:
Mã chức năng: P_I201
Tên chức năng: 生産指示登録画面 (Màn hình đăng ký lệnh sản xuất)
Người dùng: Bộ phận kế hoạch sản xuất
Mục tiêu: Tạo lệnh sản xuất mới hoặc chỉnh sửa lệnh đã có.
Điều kiện truy cập: Người dùng có quyền “製造指示管理”.
3.2. Mô tả các trường dữ liệu (Field Definition)
Các trường trong màn hình được mô tả chi tiết:
- Tên hiển thị: “生産指示番号 (Mã chỉ thị sản xuất)”
- Kiểu dữ liệu: String
- Bắt buộc: Có
- Giá trị mặc định: Tự sinh theo format YYYYMMDD-nnn
- Nguồn dữ liệu: Sequence từ bảng ProductionOrder
- Mô tả: Mã duy nhất của lệnh sản xuất trong hệ thống
3.3. Mapping dữ liệu (Data Mapping)
Ví dụ:
ProductionOrderNo → ProductionOrder.OrderNo
ProductCode → ProductMaster.ProductCode
PlanDate → ProductionOrder.PlanDate
3.4. Logic xử lý (Processing Logic)
Ví dụ:
Khi người dùng nhấn “登録 (Đăng ký)”
→ kiểm tra dữ liệu đầu vào
→ ghi vào bảng ProductionOrder
→ hiển thị thông báo “登録が完了しました” (Đăng ký thành công).
3.5. Xử lý lỗi và thông báo (Error Handling)
Ví dụ:
ERR201 – Ngày sản xuất nhỏ hơn ngày hiện tại → “生産日が本日より前です。”
ERR202 – Mã sản phẩm không tồn tại → “製品コードが存在しません。”
3.6. Giao diện người dùng (UI Layout) – tham khảo
Mô tả bố cục màn hình:
– Vùng nhập thông tin lệnh sản xuất (sản phẩm, ngày, số lượng)
– Bảng danh sách lệnh đã tạo
– Nút chức năng: Đăng ký / Xóa / Tìm kiếm / Reset
– Điều kiện hiển thị: chỉ bật nút Xóa khi chọn một dòng hợp lệ.
4. Mối liên hệ giữa Basic Design và Detail Design
Ví dụ:
Basic quy định “Ngày chỉ thị không nhỏ hơn ngày hiện tại”
→ Detail cụ thể hóa điều kiện kiểm tra “PlanDate < Today → ERR201”。
5. Kết luận
Việc viết tài liệu Basic Design và Detail Design là kỹ năng quan trọng giúp dự án Nhật Bản duy trì tính chính xác và khả năng bảo trì.
Một tài liệu rõ ràng, thống nhất và có cấu trúc giúp tất cả các bên
— từ kỹ sư, tester, đến quản lý
— phối hợp hiệu quả và hạn chế sai sót.
Nếu Basic Design giúp mọi người hiểu “cái gì cần làm”, thì Detail Design hướng dẫn chi tiết “làm như thế nào”.
Khi hai phần này được liên kết chặt chẽ, dự án sẽ đạt độ ổn định, chính xác và phản ánh đúng tinh thần kỹ lưỡng của kỹ sư Nhật.
