Ba văn bản, mỗi văn bản 1–2 trang, viết trước khi code chạy thật: tính năng được làm gì, dữ liệu nào rời cửa hàng, và nhà cung cấp model giữ dữ liệu đó ra sao. Mỗi câu phải trỏ được tới một bằng chứng.Three documents, 1–2 pages each, written before the code runs for real: what the feature may do, which data leaves the shop, and how the model vendor keeps it. Every sentence must point to evidence.
Câu hỏi về một tính năng AI luôn rơi vào ba nhóm. Mỗi nhóm có một văn bản trả lời, ứng với một nhóm control Annex A. Viết trước khi lên production; viết sau sự cố thì đó là biên bản sự cố.Questions about an AI feature always fall into three groups. Each has one document that answers it and maps to one group of Annex A controls. Write them before production; written after an incident, they are a post-mortem.
Làm gì, cho ai, không được dùng vào việc gì, rủi ro đã biết.What it does, for whom, what it must not be used for, known risks.
Từng trường: nguồn, quyền dùng, có PII không, gửi gì cho ai, ghi log thế nào.Every field: source, right to use, PII or not, what goes to whom, how it is logged.
maskPII() và test của nóEvidence: maskPII() and its testsVendor giữ dữ liệu bao lâu, ở đâu, có huấn luyện trên đó không, điều khoản gì.How long the vendor keeps data, where, whether it trains on it, which terms apply.
Mỗi văn bản 1–2 trang. Dài hơn thì không ai review kỹ, mà M2 cần đúng bước review đó. Nên đọc trước: ai-pilot-audit-ready.1–2 pages each. Longer, and nobody reviews it properly — and M2 depends on exactly that review. Read first: ai-pilot-audit-ready.
Cửa hàng online 5 dev ở các bài trước (shop-web Next.js, shop-api Node), bán đồ gia dụng ở Việt Nam, có vài khách nhận hàng ở EU. Pilot: khung chat trả lời trạng thái đơn, ngày giao, chính sách đổi trả và soạn yêu cầu hoàn tiền.The 5-dev online shop from earlier topics (shop-web Next.js, shop-api Node), selling household goods in Vietnam with a few EU customers. The pilot: a chat that answers order status, delivery dates and return policy, and drafts refund requests.
Khách ──► shop-web chat ──► shop-api ──► maskPII() ──► Anthropic API
│ claude-sonnet-5-5
├── get_order(order_id) read
├── get_policy(topic) read
└── create_refund_request ──► CS approval queue
claude-sonnet-5-5 qua Anthropic API. Không fine-tuning, không vector DB.via the Anthropic API. No fine-tuning, no vector DB.order-assistant@1.4.0 — prompt có version trong shop-api/prompts/.— versioned prompt in shop-api/prompts/.Bốn mục bắt buộc: mục đích, người dùng, giới hạn sử dụng, rủi ro đã biết. Model làm được rất nhiều việc, nên design doc phải nói rõ việc nào tính năng được phép làm, và chặn phần còn lại bằng cơ chế gì.Four required sections: purpose, users, usage limits, known risks. A model can do a great deal, so the design doc must say what the feature is allowed to do, and which mechanism blocks the rest.
Cột thứ ba quan trọng hơn cột thứ hai. Chỉ viết "không được" mà không có cơ chế chặn, thì đó là lời hứa, không phải thiết kế.The third column matters more than the second. "Must not" without a blocking mechanism is a promise, not a design.
Các bài sau không thêm rủi ro mới; chúng lấp cột bằng chứng.Later topics add no new risks; they fill the evidence column.
Không viết "chúng tôi dùng dữ liệu đơn hàng". Liệt kê từng trường và trả lời bốn câu: nguồn, quyền dùng, có PII (thông tin định danh cá nhân) không, đi đâu. Quy tắc chọn: model có cần trường này để trả lời không? Model cần tỉnh để ước tính ngày giao, không cần số nhà.Never write "we use order data". List every field and answer four questions: source, right to use, PII or not, where it goes. The rule: does the model need this field to answer? It needs the province for delivery estimates, not the house number.
| TrườngField | NguồnSource | PII? | Gửi cho vendorSent to vendor | Ghi logLogged |
|---|---|---|---|---|
| Tin nhắn của kháchCustomer message | Khung chatChat widget | Có thể cóPossibly | Che rồi gửiMasked, then sent | CheMasked |
| Tên gọiFirst name | customers.first_name | PII | GửiSent | CheMasked |
| Họ tên, SĐT, emailFull name, phone, email | customers.* | PII | KhôngNo | KhôngNo |
| Địa chỉ giao hàngShipping address | orders.shipping_address | PII | Chỉ tỉnh/thànhProvince only | KhôngNo |
| Mặt hàng, số lượng, giá, trạng thái, ETAItems, quantity, price, status, ETA | orders, order_items | KhôngNo | GửiSent | Gửi nguyênAs-is |
| Thông tin thanh toánPayment details | Cổng thanh toánPayment gateway | PII tài chínhFinancial PII | Không bao giờNever | KhôngNo |
Lớp 1 che trước khi gửi vendor, lớp 2 che trước khi ghi log (cả đầu ra, phòng khi model lặp lại PII). Mã đơn được giữ — model cần nó.Layer 1 masks before the vendor call, layer 2 before logging (output too, in case the model repeats PII). The order number is kept — the model needs it.
Regex chỉ là lớp đầu: nó bắt SĐT, email, số thẻ, địa chỉ có số nhà, nhưng không bắt tên người hay địa chỉ viết tự do. Test của hàm che (dấu cách, +84, chữ hoa, gạch nối) chính là bằng chứng cho A.7.6.Regex is only the first layer: it catches phones, emails, card numbers and numbered addresses, but not names or free-form addresses. The masking tests (spaces, +84, upper case, dashes) are the evidence for A.7.6.
Luật Bảo vệ dữ liệu cá nhân số 91/2025/QH15 (hiệu lực 1/1/2026) có điều riêng về chuyển dữ liệu cá nhân xuyên biên giới (Điều 20) kèm hồ sơ đánh giá tác động. Điều kiện chi tiết và nghị định hướng dẫn: chưa xác minh ở bài này, bài M4 sẽ đi sâu. Data sheet ghi ba điều: chính sách bảo mật đã nhắc tới vendor AI ở nước ngoài chưa; cơ sở dùng từng nhóm dữ liệu; ai ký quyết định gửi dữ liệu ra ngoài.Vietnam's Personal Data Protection Law No. 91/2025/QH15 (effective 1 Jan 2026) has a dedicated article on cross-border transfers (Article 20) with an impact-assessment dossier. Detailed conditions and implementing decrees: not verified here; the M4 topic goes deeper. The data sheet records three things: whether the privacy notice mentions an AI vendor abroad; the basis for each data group; who signed off sending data out.
Tiêu chí có viền cam là bắt buộc: trượt một cái thì điểm các tiêu chí khác cao cỡ nào cũng không dùng.Criteria with an orange edge are required: fail one and the vendor is out, however well it scores elsewhere.
| Tiêu chíCriterion | Anthropic API | OpenAI API | Gemini Developer API (trả phí)Gemini Developer API (paid) |
|---|---|---|---|
| Huấn luyệnTraining | Không (Commercial Terms)No (Commercial Terms) | Không, trừ khi bạn đồng ý (opt in)No, unless you opt in | Không, với Paid ServicesNo, on Paid Services |
| Lưu mặc địnhDefault retention | Xoá trong 30 ngày; ngoại lệ: Files API, vi phạm usage policy, pháp luậtDeleted within 30 days; exceptions: Files API, policy enforcement, law | Tối đa 30 ngày (giám sát lạm dụng); Responses API store ≥ 30 ngàyUp to 30 days (abuse monitoring); Responses API store ≥ 30 days | "Thời gian giới hạn" để phát hiện vi phạm; 55 ngày (thông báo 11/2024) "A limited period" for abuse detection; 55 days (Nov 2024 notice) chưa xác minhnot verified |
| ZDR | Có, qua sales; không cho Covered Models (Fable 5.1, Mythos 5.1, Fable 5, Mythos 5)Yes, via sales; not for Covered Models (Fable 5.1, Mythos 5.1, Fable 5, Mythos 5) | Có, cần OpenAI duyệt trướcYes, with OpenAI's prior approval | Không đảm bảo trên Developer API; dùng Vertex AINot guaranteed on the Developer API; use Vertex AI |
| Khi bị gắn cờWhen flagged | Có thể tới 2 năm, kể cả có ZDRUp to 2 years, even under ZDR | Lâu hơn khi luật yêu cầuLonger when the law requires | Chưa xác minhNot verified |
| VùngRegion | inference_geo: global / us (×1,1); lưu trữ chỉ USstorage US only | US, EU, UAE (xử lý + lưu); vài nước khác chỉ lưu trữ, không xử lýUS, EU, UAE (processing + storage); some countries storage only | Chưa xác minhNot verified; Vertex AI có chọn vùngVertex AI offers regions |
| DPA | Kèm Commercial TermsPart of Commercial Terms | Công khai, bản hiệu lực 1/1/2026Public, effective 1 Jan 2026 | Chưa xác minh chi tiếtDetails not verified |
| Sub-processor | Danh sách công khaiPublic list | Công khai, có đăng ký thông báoPublic, with notifications | Chưa xác minhNot verified |
Chính sách vendor đổi thường xuyên. Bảng ghi lại trang chính thức ngày 2026-11-01 — kiểm tra lại trước khi quyết định thật, và lưu link + ngày kiểm tra vào bản đánh giá.Vendor policies change often. The table records the official pages on 2026-11-01 — re-check before a real decision, and keep links + check date in your assessment.
store của Responses API, grounding Google Search (30 ngày, không tắt được). Bật tính năng mới = đánh giá lại.Files API, code execution, Responses API store, Google Search grounding (30 days, no opt-out). New feature = re-assess.global: us tốn thêm 10% mà không giải quyết gì.With all three vendors, the data leaves Vietnam. The right question is "masked enough, legal basis in place?". So the shop keeps global: us costs 10% more and solves nothing.Điền form bên trái; sơ đồ luồng dữ liệu và ba file Markdown cập nhật ngay. Bấm "Nạp ví dụ cửa hàng" để xem bản đầy đủ. Dữ liệu chỉ lưu trong trình duyệt của bạn.Fill in the form; the data-flow diagram and the three Markdown files update live. Press "Load shop example" to see a complete version. Data stays in your browser.
Đổi vendor sẽ nạp lại kết quả đã kiểm tra ngày 2026-11-01.Changing the vendor reloads the results checked on 2026-11-01.
M2 chỉ xong khi người khác đọc và ký. Người viết tự duyệt thì không tính. Cửa hàng 5 người thì một người review nhiều văn bản cũng được, miễn không phải người viết.M2 is done only when someone else reads and signs. Self-approval does not count. In a 5-person shop one person may review several documents, as long as they did not write them.
# shop-api/.github/CODEOWNERS /docs/ai/ @shop/ops-manager @shop/cs-lead # shop-api/docs/ai/order-assistant/ design.md data-sheet.md vendor-assessment.md risk-register.md
Mỗi lần sửa là một PR, cần người trong CODEOWNERS duyệt. Khi auditor hỏi "ai duyệt, khi nào", bạn gửi link PR. Lịch sử git là bằng chứng có dấu thời gian, không cần thêm công cụ.Every change is a PR that needs a CODEOWNERS approval. When an auditor asks "who approved, when", send the PR link. Git history is timestamped evidence, with no extra tooling.
| Câu hỏiQuestion | TrướcBefore | SauAfter |
|---|---|---|
| Trợ lý được làm gì?What may the assistant do? | "Thì trả lời khách thôi""Answer customers, I guess" | Bảng giới hạn, có cơ chế chặnA limits table with blocking mechanisms |
| Gửi gì cho Anthropic?What do we send to Anthropic? | "Chắc là tin nhắn""Probably the messages" | Từng trường, hàm che + testPer field, masking + tests |
| Họ giữ bao lâu?How long do they keep it? | "Họ nói không train mà""They said no training" | ≤ 30 ngày, 2 năm nếu bị gắn cờ, link + ngày≤ 30 days, 2 years if flagged, link + date |
| Ai duyệt?Who approved? | Không aiNobody | PR được CS lead, quản lý vận hành duyệtPR approved by CS lead, operations manager |
| Đổi model được không?Can we switch models? | Đổi luônJust switch | Đánh giá lại vendor + chạy eval (M3)Re-assess vendor + run evals (M3) |
| Anti-pattern | Vì sao hỏngWhy it fails | Thay bằngInstead |
|---|---|---|
| Design doc 15 trangA 15-page design doc | Không ai review hết, duyệt thành hình thứcNobody reviews it all; approval becomes a formality | 1–2 trang, chi tiết để ở link1–2 pages, details behind links |
| "Dữ liệu: dữ liệu đơn hàng""Data: order data" | Không trả lời được "gửi trường nào"Cannot answer "which fields are sent" | Bảng từng trườngA per-field table |
| Chỉ che trước khi gửi vendorMasking only before the vendor call | Log nội bộ vẫn chứa SĐT, địa chỉInternal logs still hold phones, addresses | Che cả hai lớpMask at both layers |
| Đánh giá vendor không ghi ngày, modelVendor assessment without date or model | Chính sách đổi, văn bản vẫn ghi "đạt"Policies change, the document still says "pass" | Model id, link, ngày kiểm tra, ngày đánh giá lạiModel id, links, check date, re-assessment date |
| Tin bài blog tổng hợpTrusting aggregator blogs | Thường lỗi thời hoặc saiOften outdated or wrong | Chỉ trích trang chính thứcCite official pages only |
| Người viết tự duyệtAuthors approving their own docs | Không có góc nhìn thứ haiNo second pair of eyes | Reviewer khác người viết, duyệt qua PRA different reviewer, via PR |
"Không được" mà không có cơ chế chặn chỉ là lời hứa. Cột hành động cho dev biết phải code gì (từ chối, chuyển nhân viên, không cấp tool), cho reviewer biết phải kiểm tra gì."Not allowed" without a mechanism is a promise. The action column tells devs what to build (refuse, hand off, withhold the tool) and reviewers what to check.
Tối thiểu hoá dữ liệu: chỉ gửi trường model thật sự cần. Trường không gửi thì không thể lộ ở phía vendor.Data minimisation: send only what the model needs. A field never sent cannot leak on the vendor side.
Log giữ lâu hơn, nhiều người đọc hơn và hay bị copy sang dashboard, ticket. Lộ từ log cũng là lộ.Logs live longer, have more readers and get copied into dashboards and tickets. A leak from logs is still a leak.
Model cụ thể và ngày kiểm tra. ZDR phải xin, không tự có, và không áp cho Covered Models. Ghi "đã xin hay chưa, cho model nào".The specific model and the check date. ZDR must be requested and excludes Covered Models. Record "requested or not, for which model".
Cả ba: data sheet (trường mới, ảnh có thể chứa PII), đánh giá vendor (Files API lưu tới khi bạn xoá), design doc (mục đích và giới hạn mới).All three: data sheet (new field, photos may hold PII), vendor assessment (Files API keeps files until you delete them), design doc (new purpose and limits).
PR có người duyệt, dấu thời gian, diff và lịch sử; CODEOWNERS bắt đúng người duyệt. Email không truy lại được và không gắn với version văn bản.A PR has an approver, timestamp, diff and history; CODEOWNERS enforces the right reviewer. Email is untraceable and not tied to a document version.