
仕様書 là căn cứ của mọi dòng code trong dự án offshore Việt – Nhật. Comtor đọc nhầm một chữ 以上 hay 未満, cả team có thể code sai cả một màn hình.
IT Comtor mới vào nghề thường gặp ba khó khăn. Không biết tài liệu nào dùng để làm gì. Gặp văn phong cứng như 〜とする, 〜こと. Và không biết khi nào nên hỏi lại khách, hỏi thế nào cho đúng.
Bài này đi từ cách phân loại tài liệu, bố cục thường gặp, cấu trúc câu đặc trưng, đến 12 dòng spec mẫu có dịch và giải thích. Phần cuối hướng dẫn lập 質問票, kèm 3 đoạn hội thoại audio comtor hỏi lại khách về một dòng spec.
Đọc spec là kỹ năng đọc, nhưng hỏi lại khách là kỹ năng nói. Bạn có thể luyện phần nói với CoroAI trên Corodomo qua các kịch bản công việc, có nhận xét về phát âm và cách diễn đạt.
Trong dự án Nhật, tài liệu đi theo từng công đoạn: "làm gì", "làm thế nào", rồi "kiểm tra ra sao". Comtor cần biết mình đang cầm tài liệu nào, vì mỗi loại có mức chi tiết khác nhau.
| Tài liệu | Cách đọc | Trả lời câu hỏi | Comtor dùng khi |
|---|---|---|---|
| 要件定義書 | ようけんていぎしょ | Hệ thống cần làm gì, để giải quyết vấn đề gì | Nắm bối cảnh, mục đích nghiệp vụ |
| 基本設計書 (外部設計書) | きほんせっけいしょ (がいぶせっけいしょ) | Người dùng thấy gì: màn hình, báo biểu, giao tiếp với hệ thống khác | Dịch cho dev, hỏi đáp spec với khách |
| 詳細設計書 (内部設計書) | しょうさいせっけいしょ (ないぶせっけいしょ) | Bên trong xử lý thế nào: logic, class, SQL | Thường do đội offshore viết, comtor dịch sang tiếng Nhật |
| 画面仕様書 | がめんしようしょ | Từng màn hình: bố cục, hạng mục, kiểm tra, thông báo | Tài liệu đọc nhiều nhất hằng ngày |
| テスト仕様書 | テストしようしょ | Kiểm tra cái gì, thao tác ra sao, kết quả mong đợi là gì | Dịch test case, đối chiếu khi báo bug |
Tên gọi khác nhau tùy công ty. 外部設計 thường tương đương 基本設計, 内部設計 tương đương 詳細設計. 画面仕様書 thường là một phần của bộ 基本設計. Về nghĩa, 仕様 là "cái gì", 設計 là "làm thế nào", nhưng thực tế hai từ hay được dùng lẫn.
Mỗi tài liệu thiết kế thường ứng với một mức kiểm thử (mô hình chữ V). Cách chia cụ thể khác nhau giữa các công ty, nhưng một cách phổ biến như sau:
Phần lớn tài liệu thiết kế ở Nhật được viết bằng Excel, mỗi sheet một nội dung. Comtor mới hay chỉ đọc sheet đầu rồi bỏ sót phần quan trọng. Hãy mở hết các sheet trước khi dịch.
| Mục / sheet | Cách đọc | Nội dung | Cần chú ý |
|---|---|---|---|
| 表紙 | ひょうし | Trang bìa: tên tài liệu, phiên bản, ngày | Kiểm tra đúng phiên bản mới nhất |
| 改訂履歴 | かいていりれき | Lịch sử sửa đổi: ngày, phiên bản, nội dung sửa | Đọc đầu tiên khi nhận bản mới |
| 画面レイアウト | がめんレイアウト | Hình bố cục màn hình, đánh số hạng mục | Đối chiếu số với bảng hạng mục |
| 画面項目定義 | がめんこうもくていぎ | Bảng định nghĩa từng hạng mục: tên, loại, độ dài | Phần quan trọng nhất cho dev |
| イベント定義 | イベントていぎ | Xử lý khi nhấn nút, khi mở màn hình | Thứ tự xử lý, điều kiện rẽ nhánh |
| 入力チェック仕様 | にゅうりょくチェックしよう | Quy tắc kiểm tra dữ liệu nhập | Mốc biên, thứ tự kiểm tra |
| エラーメッセージ一覧 | エラーメッセージいちらん | Mã lỗi và nội dung thông báo | Mã lỗi phải khớp với phần kiểm tra |
| 画面遷移図 | がめんせんいず | Sơ đồ chuyển màn hình | Màn hình đi đâu sau mỗi thao tác |
Bảng 画面項目定義 thường có các cột 項目名, 物理名, 種別, 必須, 桁数, 文字種, 初期値 và 備考. Trong đó, 物理名 (ぶつりめい) là tên trong code hoặc DB, 文字種 (もじしゅ) là loại ký tự được phép nhập.
Văn bản spec tiếng Nhật dùng thể thường, câu ngắn và hầu như không có chủ ngữ. Chủ ngữ ngầm hiểu là "hệ thống". Nắm được các mẫu dưới đây, bạn sẽ đọc được phần lớn các dòng spec.
| Mẫu | Cách đọc | Nghĩa trong spec | Ví dụ |
|---|---|---|---|
| 〜とする | とする | Quy định là ~ | 初期値は「未選択」とする。 |
| 〜こと | こと | Phải ~ (yêu cầu bắt buộc) | 必ず入力すること。 |
| 〜ものとする | ものとする | Quy định là ~ (văn trang trọng) | 削除は論理削除(ろんりさくじょ)で行うものとする。 |
| 〜場合は | ばあいは | Trong trường hợp ~ | 未入力の場合は、エラーとする。 |
| 〜時 | じ | Khi ~ | 押下時、初期表示時 |
| 〜以外 | いがい | Ngoài ~, khác ~ | 管理者以外の場合 |
| 〜以上/〜以下 | いじょう/いか | ≥ / ≤ (bao gồm mốc) | 8文字以上20文字以下 |
| 〜未満/〜を超える | みまん/をこえる | < / > (không gồm mốc) | 18歳未満、30日を超えた場合 |
| 〜以内 | いない | Trong phạm vi ~ (≤) | 全角100文字以内 |
| 〜以前/〜以降 | いぜん/いこう | Từ ~ trở về trước / trở đi (gồm mốc) | 終了日以前の日付 |
| ただし | ただし | Tuy nhiên (ngoại lệ) | ただし、管理者は除く。 |
| 〜に準ずる | にじゅんずる | Theo như ~, tương tự ~ | 共通仕様に準ずる。 |
| 〜を参照 | をさんしょう | Xem ~ | 別紙「コード一覧」を参照。 |
| 未定/TBD | みてい | Chưa quyết định | Đưa ngay vào 質問票 |
Cần phân biệt sắc thái của 〜とする và 〜こと. 〜とする mô tả quyết định thiết kế: "hệ thống làm như vậy". 〜こと là yêu cầu bắt buộc: "phải làm như vậy". Khi dịch sang tiếng Việt, 〜こと nên dịch là "phải", không phải "việc".
Nhóm từ này xuất hiện trong gần như mọi 画面仕様書. Hãy học theo cặp đối lập để không nhầm.
| Từ | Cách đọc | Nghĩa trong spec |
|---|---|---|
| 必須/任意 | ひっす/にんい | Bắt buộc nhập / không bắt buộc |
| 活性/非活性 | かっせい/ひかっせい | Thao tác được (enabled) / bị vô hiệu (disabled, vẫn hiển thị) |
| 表示/非表示 | ひょうじ/ひひょうじ | Hiển thị / ẩn hoàn toàn |
| 押下 | おうか | Nhấn, click (nút) |
| 遷移 | せんい | Chuyển sang màn hình khác |
| 初期表示/初期値 | しょきひょうじ/しょきち | Trạng thái khi mở màn hình lần đầu / giá trị mặc định |
| 桁数 | けたすう | Độ dài tối đa (số ký tự hoặc số byte) |
| 半角/全角 | はんかく/ぜんかく | Ký tự nửa độ rộng / toàn độ rộng |
| 英数字 | えいすうじ | Chữ cái Latin và chữ số |
| 前方一致/部分一致 | ぜんぽういっち/ぶぶんいっち | Khớp phần đầu / khớp bất kỳ phần nào |
| 昇順/降順 | しょうじゅん/こうじゅん | Sắp xếp tăng dần / giảm dần |
| 相関チェック | そうかんチェック | Kiểm tra liên quan giữa nhiều trường (ví dụ ngày bắt đầu ≤ ngày kết thúc) |
Cặp dễ nhầm nhất là 非活性 và 非表示. 非活性 nghĩa là nút vẫn nằm đó nhưng bị xám, không nhấn được. 非表示 nghĩa là nút biến mất khỏi màn hình. Dịch sai chữ này, dev sẽ làm sai giao diện và tester sẽ báo bug ngược.
Đoạn hội thoại dưới đây là comtor hỏi lại khách về đúng chữ 非活性. Chị Linh là comtor, anh Suzuki là người phụ trách phía khách. Câu hỏi: nút xóa cần hiển thị thế nào, và có cần tooltip không?
Nút xóa vẫn hiển thị nhưng bị xám (グレーアウト), không nhấn được. Lần này không cần hiển thị lý do khi rê chuột.
| Người nói | Tiếng Nhật | Tiếng Việt |
|---|---|---|
| Linh | 鈴木さん、画面仕様書の件で、一点確認させてください。 | Anh Suzuki, cho tôi xác nhận một điểm về tài liệu đặc tả màn hình. |
| Suzuki | はい、どうぞ。 | Vâng, mời chị. |
| Linh | 権限が管理者以外の場合、削除ボタンは非活性とする、と記載がございます。これは、ボタンは表示したまま、押せない状態にするという意味でしょうか。 | Tài liệu ghi: nếu quyền không phải quản trị viên thì nút xóa ở trạng thái vô hiệu. Ý là nút vẫn hiển thị nhưng không nhấn được, đúng không ạ? |
| Suzuki | そうです。非表示ではなく、グレーアウトしてください。 | Đúng vậy. Không phải ẩn đi, mà làm xám nút. |
| Linh | 承知しました。マウスを合わせたときに、理由を表示する必要はございますか。 | Tôi hiểu rồi. Khi rê chuột vào, có cần hiển thị lý do không ạ? |
| Suzuki | いえ、今回は不要です。 | Không, lần này không cần. |
Mười hai dòng dưới đây mô phỏng văn phong spec thật trong dự án web nghiệp vụ. Hãy che cột giữa, tự dịch trước, rồi mới đối chiếu. Cột cuối là điều comtor cần lưu ý hoặc nên hỏi lại.
| Dòng spec | Dịch | Giải thích, điểm cần hỏi |
|---|---|---|
| ユーザーIDは半角英数字8桁以上20桁以下とする。 | User ID gồm chữ và số nửa độ rộng, dài từ 8 đến 20 ký tự. | Gồm cả 8 và 20. Hỏi: có cho phép ký hiệu như "_" không? |
| パスワードが8文字未満の場合は、エラーメッセージE001を表示すること。 | Nếu mật khẩu dưới 8 ký tự thì phải hiển thị thông báo lỗi E001. | 未満: 7 ký tự trở xuống mới lỗi. 〜こと là yêu cầu bắt buộc. |
| 検索条件が未入力の場合は、全件を表示する。 | Nếu không nhập điều kiện tìm kiếm thì hiển thị toàn bộ. | Hỏi: dữ liệu nhiều thì có phân trang hay giới hạn số dòng không? |
| 権限が「管理者」以外の場合、「削除」ボタンを非活性とする。 | Nếu quyền không phải "Quản trị viên" thì nút "Xóa" ở trạng thái vô hiệu. | Nút vẫn hiển thị, chỉ không nhấn được. |
| 「登録」ボタン押下時、確認ダイアログを表示する。 | Khi nhấn nút "Đăng ký", hiển thị hộp thoại xác nhận. | 押下時 = khi nhấn. Hỏi: nhấn "Hủy" thì giữ lại dữ liệu đã nhập không? |
| 初期表示時、検索結果一覧は非表示とする。 | Khi mở màn hình lần đầu, không hiển thị danh sách kết quả. | Danh sách chỉ hiện sau khi nhấn tìm kiếm. |
| 処理完了後、一覧画面へ遷移する。 | Sau khi xử lý xong, chuyển sang màn hình danh sách. | Hỏi: điều kiện tìm kiếm trước đó có được giữ lại không? |
| 開始日は終了日以前の日付であること。 | Ngày bắt đầu phải là ngày trước hoặc bằng ngày kết thúc. | 以前 gồm cả ngày đó: cùng một ngày vẫn hợp lệ. Đây là 相関チェック. |
| 申込日から30日を超えた場合は、キャンセル不可とする。 | Quá 30 ngày kể từ ngày đăng ký thì không được hủy. | Ngày thứ 30 vẫn hủy được. Hỏi: ngày đăng ký tính là ngày 0 hay ngày 1? |
| 備考は全角100文字以内とする。 | Ghi chú tối đa 100 ký tự toàn độ rộng. | Hỏi: nhập ký tự nửa độ rộng thì đếm thế nào? |
| 金額は3桁区切りで表示し、小数点以下は切り捨てとする。 | Số tiền hiển thị có dấu phân cách hàng nghìn, phần thập phân bị bỏ (làm tròn xuống). | 切り捨て là làm tròn xuống, 四捨五入 là làm tròn thường, 切り上げ là làm tròn lên. |
| 郵便番号は任意項目とする。ただし、入力された場合は半角数字7桁であること。 | Mã bưu chính không bắt buộc. Tuy nhiên, nếu đã nhập thì phải là 7 chữ số nửa độ rộng. | Hỏi: có chấp nhận dấu gạch ngang như 123-4567 không? |
Nhiều dòng spec "đọc thì hiểu" nhưng vẫn cần hỏi. Phát hiện chỗ trống trước khi dev code là giá trị lớn nhất của comtor.
Lỗi dịch nguy hiểm nhất nằm ở những từ trông quá dễ, như 以上 hay 以下. Dịch 8文字以上 thành "trên 8 ký tự", dev sẽ code sai điều kiện biên.
| Từ | Dịch sai hay gặp | Dịch đúng |
|---|---|---|
| 以上 | "Trên 8" (hiểu là > 8) | "Từ 8 trở lên" (≥ 8) |
| 以下 | "Dưới 20" (hiểu là < 20) | "Từ 20 trở xuống" (≤ 20) |
| 未満 | "Tối đa 8" | "Dưới 8", không gồm 8 (< 8) |
| 超/〜を超える | "Từ 30 trở lên" | "Trên 30", không gồm 30 (> 30) |
| 以前/以降 | "Trước / sau ngày đó" (không gồm) | Gồm cả ngày đó. Còn 〜より前 thì không gồm. |
| 押下 | "Ấn xuống", "đè" | "Nhấn", "click" |
| 非活性 | "Ẩn", "không hoạt động" | "Vô hiệu, bị xám" (vẫn hiển thị) |
| 任意 | "Tùy ý" | "Không bắt buộc" (optional) |
| 〜こと | "Việc ~" | "Phải ~" |
| 等(など/とう) | Bỏ qua khi dịch | "v.v.": danh sách chưa đầy đủ, cần hỏi |
| 適宜(てきぎ) | "Phù hợp" rồi bỏ qua | "Tùy tình huống": mơ hồ, cần hỏi |
| 原則として | "Về nguyên tắc" rồi bỏ qua | Có ngoại lệ: hỏi ngoại lệ là gì |
Một cái bẫy khác là 桁数. Trong nhiều hệ thống cũ dùng mã Shift_JIS, 桁数 được đếm bằng byte: một ký tự toàn độ rộng tính là 2 桁. Nếu DB dùng UTF-8, một ký tự tiếng Nhật thường chiếm 3 byte. Vì vậy, khi thấy 桁数, luôn hỏi đó là số ký tự hay số byte.
Đoạn hội thoại sau là comtor xác nhận đúng mốc biên của 以上 và 以下. Câu hỏi: mật khẩu dài 20 ký tự có hợp lệ không, và 21 ký tự thì sao?
Mật khẩu 20 ký tự hợp lệ. Từ 21 ký tự trở lên thì hiển thị lỗi kiểm tra nhập liệu.
| Người nói | Tiếng Nhật | Tiếng Việt |
|---|---|---|
| Linh | パスワードの項目に、八文字以上二十文字以下とありますが、二十文字ちょうどは入力できる、という理解でよろしいでしょうか。 | Ở hạng mục mật khẩu có ghi từ 8 đến 20 ký tự. Tôi hiểu là nhập đúng 20 ký tự vẫn được, như vậy có đúng không ạ? |
| Suzuki | はい、二十文字までは入力できます。 | Đúng, nhập được đến 20 ký tự. |
| Linh | ありがとうございます。では、二十一文字以上の場合は、入力チェックのエラーを表示する、ということで進めます。 | Cảm ơn anh. Vậy từ 21 ký tự trở lên thì hiển thị lỗi kiểm tra nhập liệu, chúng tôi sẽ làm theo hướng đó. |
| Suzuki | はい、それで大丈夫です。 | Vâng, như vậy là được. |
Khi nhận tài liệu mới, đừng dịch từ dòng đầu đến dòng cuối. Hãy đọc theo lớp, từ tổng quan đến chi tiết, để phát hiện mâu thuẫn trước khi tốn công dịch.
Mọi điểm chưa rõ đưa vào 質問票 (しつもんひょう), nhiều dự án gọi là QA表. Câu trả lời trong 質問票 có giá trị như spec, nên phải ghi rõ ràng và đánh số.
| No | 資料名・版 | 該当箇所 | 質問内容 | 当方の想定 | ステータス |
|---|---|---|---|---|---|
| 1 | 画面仕様書_会員登録 v1.2 | イベント定義 No.3 | 確認ダイアログで「キャンセル」を押下した場合、入力内容は保持されますでしょうか。 | 入力内容を保持したまま、元の画面に戻ると想定しております。 | 回答待ち |
| 2 | 画面仕様書_会員登録 v1.2 | 3.4節 | 「メールアドレス等」の「等」には、ほかにどの項目が含まれますでしょうか。 | メールアドレスと電話番号の2項目と想定しております。 | 回答待ち |
| 3 | 基本設計書 v2.0/画面仕様書 v1.2 | 氏名 | 基本設計書では20桁、画面仕様書では40桁となっております。どちらが正でしょうか。 | 最新の画面仕様書(40桁)が正と想定しております。 | 回答済み |
Cột 当方の想定 (とうほうのそうてい, cách hiểu của bên mình) là bí quyết quan trọng nhất. Có sẵn đề xuất, khách chỉ cần xác nhận hoặc sửa lại, nhanh hơn nhiều so với câu hỏi mở. Trong văn viết, 正 (せい) nghĩa là "bản chuẩn".
Đoạn hội thoại cuối xử lý câu hỏi số 3 trong bảng. Câu hỏi: con số nào đúng, và 桁数 được đếm theo đơn vị nào?
40 桁 trong 画面仕様書 là đúng vì đó là bản mới hơn. 桁数 đếm theo byte: một ký tự toàn độ rộng tính là 2 桁. Anh Suzuki sẽ tự sửa 基本設計書.
| Người nói | Tiếng Nhật | Tiếng Việt |
|---|---|---|
| Linh | 基本設計書と画面仕様書で、氏名の桁数が異なっております。基本設計書では二十桁、画面仕様書では四十桁ですが、どちらが正しいでしょうか。 | Độ dài họ tên ở tài liệu thiết kế cơ bản và tài liệu đặc tả màn hình đang khác nhau. Một bên 20, một bên 40, bên nào đúng ạ? |
| Suzuki | すみません、画面仕様書のほうが新しいので、四十桁が正しいです。 | Xin lỗi, tài liệu đặc tả màn hình mới hơn, nên 40 là đúng. |
| Linh | 承知しました。もう一点、この桁数は文字数でしょうか、それともバイト数でしょうか。 | Tôi hiểu rồi. Thêm một điểm nữa, độ dài này tính theo số ký tự hay số byte ạ? |
| Suzuki | バイト数です。全角は一文字を二桁として数えてください。 | Theo số byte. Ký tự toàn độ rộng thì tính mỗi ký tự là 2. |
| Linh | かしこまりました。基本設計書の修正も、お願いしてよろしいでしょうか。 | Vâng ạ. Nhờ anh sửa luôn tài liệu thiết kế cơ bản được không ạ? |
| Suzuki | はい、こちらで修正しておきます。 | Vâng, bên tôi sẽ sửa. |
Bài học từ đoạn này: 40 byte với ký tự toàn độ rộng chính là 20 ký tự. Có thể hai tài liệu không mâu thuẫn, mà chỉ đếm khác đơn vị. Comtor giỏi là người nhìn ra những chỗ như vậy và hỏi đúng câu.
Đọc thêm: Daily meeting tiếng Nhật: 30 câu thường gặp và cách trả lời · Tiếng Nhật khách hàng IT: 30 câu xác nhận spec, tránh hiểu nhầm
Về nghĩa, 仕様書 mô tả hệ thống cần như thế nào, 設計書 mô tả cách làm ra nó. Trong thực tế dự án, hai từ thường được dùng lẫn. Ví dụ 画面仕様書 thường nằm trong bộ 基本設計書.
Nên bắt đầu với 画面仕様書, vì nó cụ thể và gắn với việc dev đang làm. Song song, đọc phần tổng quan của 要件定義書 để hiểu nghiệp vụ. Khi đã quen, chuyển sang テスト仕様書 và 詳細設計書.
Có. 8以上 nghĩa là từ 8 trở lên, gồm cả 8. Tương tự, 以下, 以内, 以前, 以降 đều gồm mốc. Ngược lại, 未満 và 〜を超える không gồm mốc.
Có thể dùng để đọc lướt. Nhưng máy dịch hay dịch sai 以上, 未満, 非活性 và bỏ qua chữ 等. Dòng nào có con số, điều kiện hoặc ngoại lệ, hãy tự đọc lại.
Gửi càng sớm càng tốt, lý tưởng là trước khi dev code phần đó. Không giới hạn số câu, nhưng mỗi câu phải rõ ràng và có đề xuất. Gom theo màn hình giúp khách trả lời nhanh hơn.
Đọc 仕様書 tiếng Nhật là kỹ năng nền tảng của IT Comtor, và cũng là bước đầu trên con đường lên BrSE. Hãy nhớ ba điểm chính:
Muốn nghe quen cách kỹ sư Nhật nói về thiết kế, hãy dán video chia sẻ kỹ thuật trên YouTube vào học qua video trên Corodomo. Bạn có phụ đề song ngữ và tra từ bằng AI ngay trong video. Đọc thêm Tiếng Nhật cho kỹ sư IT để mở rộng vốn từ, và BrSE tiếng Nhật: lộ trình và kỹ năng để thấy bước tiếp theo của nghề.
Học cùng Corodomo: Học ngoại ngữ · Học qua video · Luyện thi