@sungen/driver-data-factory 3.2.10-beta.5 → 3.2.12-beta.1

package/common/field-types/currency.yaml

@@ -1,20 +1,20 @@
 # Field-type: currency (money) — from common-checklist.xlsx (Input box · Currency).
 type: currency
-description: Số tiền — số nguyên/thập phân theo đơn vị tiền tệ; lưu ý leading-zero & giá trị 0.
+description: Money amount — integer/decimal per currency unit; watch leading-zero & the value 0.
 constraints:
   min: 0
   max: 999999999   # placeholder
-  decimalPlaces: 0 # placeholder (JPY=0, USD=2 …)
+  decimalPlaces: 0 # placeholder (JPY=0, USD=2 ...)
 valid:
-  - { id: CHK-CUR-01, value: "1000", note: "số tiền hợp lệ" }
-  - { id: CHK-CUR-02, value: "0", note: "giá trị 0 phải hiểu là 0, KHÔNG phải 'chưa nhập'" }
+  - { id: CHK-CUR-01, value: "1000", note: "valid amount" }
+  - { id: CHK-CUR-02, value: "0", note: "0 must mean 0, NOT 'not entered'" }
 boundary:
-  - { id: CHK-CUR-B1, gen: "Min / Min+1" }
-  - { id: CHK-CUR-B2, gen: "Max / Max-1" }
+  - { id: CHK-CUR-B1, gen: "min / min+1" }
+  - { id: CHK-CUR-B2, gen: "max / max-1" }
 invalid:
-  - { id: CHK-CUR-I1, gen: "chữ cái / ký tự lạ", reason: "không phải số", errorRef: M13 }
-  - { id: CHK-CUR-I2, gen: "Min-1 / Max+1", reason: "vượt biên", errorRef: M13 }
-  - { id: CHK-CUR-I3, value: "", reason: "rỗng (tuỳ spec)", errorRef: M02 }
+  - { id: CHK-CUR-I1, gen: "alphabetic / stray characters", reason: "not a number", errorRef: M13 }
+  - { id: CHK-CUR-I2, gen: "min-1 / max+1", reason: "out of bounds", errorRef: M13 }
+  - { id: CHK-CUR-I3, value: "", reason: "empty (per spec)", errorRef: M02 }
 notes:
-  - "Kiểm tra riêng: leading zero (0100) có bị cắt mất không; format hiển thị dấu phân cách nghìn."
+  - "Check separately: leading zero (0100) not stripped; thousands separator display format."
 uses_security: [sqli]

package/common/field-types/email.yaml

@@ -1,8 +1,8 @@
-# Field-type: email — seeded from common-checklist.xlsx (Input box · Email) + phuong-phap §Nguồn-2.
+# Field-type: email — seeded from common-checklist.xlsx (Input box · Email) + the 4-source method.
 # errorRef (Mxx) are PLACEHOLDERS — the generator maps them onto the project's real message codes;
-# if the project spec has none, the value is marked as a chua-chot (open) point, not invented.
+# if the project spec has none, the value is marked as an open point, not invented.
 type: email
-description: Email half-width, format <local-part>@<domain>
+description: Half-width email, format <local-part>@<domain>.
 format: "<local-part>@<domain>"
 constraints:
   charset: half-width
@@ -13,18 +13,18 @@ valid:
   - { id: CHK-EMAIL-01, value: "user@example.com", note: "normal half-width" }
   - { id: CHK-EMAIL-02, value: "u.name+tag@sub.example.co.jp", note: "dotted local + subdomain" }
 boundary:
-  - { id: CHK-EMAIL-B1, gen: "local@ đúng maxLocal", note: "local part = max (64)" }
-  - { id: CHK-EMAIL-B2, gen: "local@ maxLocal-1", note: "local part = max-1" }
-  - { id: CHK-EMAIL-B3, gen: "chuỗi tổng = maxTotal", note: "total length = max (255)" }
+  - { id: CHK-EMAIL-B1, gen: "local part = maxLocal", note: "local part = max (64)" }
+  - { id: CHK-EMAIL-B2, gen: "local part = maxLocal-1", note: "local part = max-1" }
+  - { id: CHK-EMAIL-B3, gen: "total = maxTotal", note: "total length = max (255)" }
 invalid:
-  - { id: CHK-EMAIL-I1, value: "user@", reason: "thiếu domain", errorRef: M13 }
-  - { id: CHK-EMAIL-I2, value: "user@.com", reason: "dấu . sai vị trí", errorRef: M13 }
-  - { id: CHK-EMAIL-I3, value: "u@@b.com", reason: "hai dấu @", errorRef: M13 }
-  - { id: CHK-EMAIL-I4, value: "@example.com", reason: "thiếu local-part", errorRef: M13 }
-  - { id: CHK-EMAIL-I5, value: "ｕｓｅｒ@example.com", reason: "full-width character", errorRef: M39 }
-  - { id: CHK-EMAIL-I6, gen: "local > 64 ký tự", reason: "vượt maxLocal", errorRef: M13 }
-  - { id: CHK-EMAIL-I7, gen: "tổng > 255 ký tự", reason: "vượt maxTotal", errorRef: M13 }
-  - { id: CHK-EMAIL-I8, value: "", reason: "rỗng (required)", errorRef: M02 }
+  - { id: CHK-EMAIL-I1, value: "user@", reason: "missing domain", errorRef: M13 }
+  - { id: CHK-EMAIL-I2, value: "user@.com", reason: "dot in wrong position", errorRef: M13 }
+  - { id: CHK-EMAIL-I3, value: "u@@b.com", reason: "two @ signs", errorRef: M13 }
+  - { id: CHK-EMAIL-I4, value: "@example.com", reason: "missing local-part", errorRef: M13 }
+  - { id: CHK-EMAIL-I5, value: "ｕｓｅｒ@example.com", reason: "full-width characters", errorRef: M39 }
+  - { id: CHK-EMAIL-I6, gen: "local > maxLocal", reason: "exceeds maxLocal", errorRef: M13 }
+  - { id: CHK-EMAIL-I7, gen: "total > maxTotal", reason: "exceeds maxTotal", errorRef: M13 }
+  - { id: CHK-EMAIL-I8, value: "", reason: "empty (required)", errorRef: M02 }
 notes:
-  - "Chuẩn hoá: lowercase, NFKC, trim trước khi so khớp."
-  - "Soft-delete: nếu hệ thống gắn hậu tố vào email đã xoá mềm → test maxTotal THẤP hơn giới hạn cột DB để chừa chỗ hậu tố."
+  - "Normalize: lowercase, NFKC, trim before comparison."
+  - "Soft-delete: if a deleted email gets a suffix appended, test maxTotal LOWER than the DB column limit to leave room for the suffix."

package/common/field-types/jp/katakana.yaml

@@ -1,20 +1,20 @@
-# Field-type: Katakana name (JP-specific) — from phuong-phap §Nguồn-2 (kinh nghiệm đặc thù JP).
+# Field-type: Katakana name (JP-specific) — from the 4-source method (JP field-type experience).
 type: katakana
-description: Trường chỉ nhận Katakana (họ/tên kana trong hệ thống Nhật).
+description: Katakana-only field (kana name in Japanese systems).
 constraints:
   charset: "full-width Katakana only"
 valid:
-  - { id: CHK-KANA-01, value: "ヤマダ", note: "Katakana chuẩn" }
-  - { id: CHK-KANA-02, value: "ジョウジ", note: "có dakuten + trường âm hợp lệ" }
+  - { id: CHK-KANA-01, value: "ヤマダ", note: "standard Katakana" }
+  - { id: CHK-KANA-02, value: "ジョウジ", note: "valid dakuten + long-vowel mark" }
 boundary:
-  - { id: CHK-KANA-B1, gen: "đúng min / max độ dài" }
+  - { id: CHK-KANA-B1, gen: "min / max length" }
 invalid:
-  - { id: CHK-KANA-I1, value: "yamada", reason: "lẫn ký tự Latin", errorRef: M39 }
-  - { id: CHK-KANA-I2, value: "やまだ", reason: "lẫn Hiragana", errorRef: M39 }
-  - { id: CHK-KANA-I3, value: "山田", reason: "lẫn Kanji", errorRef: M39 }
-  - { id: CHK-KANA-I4, value: "ﾔﾏﾀﾞ", reason: "half-width kana (nếu spec chỉ nhận full-width)", errorRef: M39 }
-  - { id: CHK-KANA-I5, value: "ゝ々", reason: "ký tự lặp — có tiền lệ lỗi thật nhiều hệ thống", errorRef: M39 }
-  - { id: CHK-KANA-I6, value: "ャュョ", reason: "kana nhỏ đứng một mình / sai vị trí", errorRef: M39 }
+  - { id: CHK-KANA-I1, value: "yamada", reason: "Latin characters mixed in", errorRef: M39 }
+  - { id: CHK-KANA-I2, value: "やまだ", reason: "Hiragana mixed in", errorRef: M39 }
+  - { id: CHK-KANA-I3, value: "山田", reason: "Kanji mixed in", errorRef: M39 }
+  - { id: CHK-KANA-I4, value: "ﾔﾏﾀﾞ", reason: "half-width kana (if spec requires full-width)", errorRef: M39 }
+  - { id: CHK-KANA-I5, value: "ゝ々", reason: "iteration marks — real-world bug precedent in many systems", errorRef: M39 }
+  - { id: CHK-KANA-I6, value: "ャュョ", reason: "small kana standalone / wrong position", errorRef: M39 }
 notes:
-  - "Chú ý: kana nhỏ (ゃゅょ), trường âm (ー), dakuten/handakuten, half↔full-width kana."
+  - "Watch: small kana (ゃゅょ), long-vowel mark (ー), dakuten/handakuten, half<->full-width kana."
 uses_security: [sqli, xss]

package/common/field-types/number-float.yaml

@@ -1,20 +1,20 @@
 # Field-type: number (float) — from common-checklist.xlsx (Input box · Number_Float).
 type: number-float
-description: Số thập phân — chữ số + dấu thập phân; số chữ số phần lẻ theo spec.
+description: Decimal number — digits + decimal separator; decimal places per spec.
 constraints:
   min: 0.0          # placeholder
   max: 999999.99    # placeholder
   decimalPlaces: 2  # placeholder
 valid:
-  - { id: CHK-FLOAT-01, value: "123.45", note: "hợp lệ" }
-  - { id: CHK-FLOAT-02, value: "0.5", note: "phần nguyên = 0" }
+  - { id: CHK-FLOAT-01, value: "123.45", note: "valid" }
+  - { id: CHK-FLOAT-02, value: "0.5", note: "integer part = 0" }
 boundary:
-  - { id: CHK-FLOAT-B1, gen: "Min / Min+1" }
-  - { id: CHK-FLOAT-B2, gen: "Max / Max-1" }
-  - { id: CHK-FLOAT-B3, gen: "đúng số chữ số thập phân / thừa 1 chữ số" }
+  - { id: CHK-FLOAT-B1, gen: "min / min+1" }
+  - { id: CHK-FLOAT-B2, gen: "max / max-1" }
+  - { id: CHK-FLOAT-B3, gen: "exact decimal places / one extra digit" }
 invalid:
-  - { id: CHK-FLOAT-I1, gen: "chữ cái", reason: "không phải số", errorRef: M13 }
-  - { id: CHK-FLOAT-I2, gen: "format sai (nhiều dấu chấm, +/- sai vị trí)", reason: "format sai", errorRef: M13 }
-  - { id: CHK-FLOAT-I3, gen: "Min-1 / Max+1", reason: "vượt biên", errorRef: M13 }
-  - { id: CHK-FLOAT-I4, value: "", reason: "rỗng/multi-space (tuỳ spec)", errorRef: M02 }
+  - { id: CHK-FLOAT-I1, gen: "alphabetic characters", reason: "not a number", errorRef: M13 }
+  - { id: CHK-FLOAT-I2, gen: "wrong format (multiple dots, +/- wrong position)", reason: "wrong format", errorRef: M13 }
+  - { id: CHK-FLOAT-I3, gen: "min-1 / max+1", reason: "out of bounds", errorRef: M13 }
+  - { id: CHK-FLOAT-I4, value: "", reason: "empty/multi-space (per spec)", errorRef: M02 }
 uses_security: [sqli]

package/common/field-types/number-integer.yaml

@@ -1,21 +1,21 @@
 # Field-type: number (integer) — from common-checklist.xlsx (Input box · Number_Integer).
 type: number-integer
-description: Số nguyên — chỉ chữ số, có thể có +/- ở vị trí hợp lệ.
+description: Integer — digits only, optional +/- in valid position.
 constraints:
-  min: 0          # placeholder theo spec
+  min: 0          # placeholder per spec
   max: 2147483647 # placeholder
 valid:
-  - { id: CHK-INT-01, value: "123", note: "chỉ số" }
-  - { id: CHK-INT-02, value: "-45", note: "có dấu - đầu (nếu spec cho phép âm)" }
+  - { id: CHK-INT-01, value: "123", note: "digits only" }
+  - { id: CHK-INT-02, value: "-45", note: "leading - (if spec allows negatives)" }
 boundary:
-  - { id: CHK-INT-B1, gen: "Min / Min+1" }
-  - { id: CHK-INT-B2, gen: "Max / Max-1" }
+  - { id: CHK-INT-B1, gen: "min / min+1" }
+  - { id: CHK-INT-B2, gen: "max / max-1" }
 invalid:
-  - { id: CHK-INT-I1, gen: "chữ cái", reason: "không phải số", errorRef: M13 }
-  - { id: CHK-INT-I2, gen: "số full-width (Japanese number)", reason: "full-width", errorRef: M39 }
-  - { id: CHK-INT-I3, gen: "+/- sai vị trí (giữa chuỗi)", reason: "format sai", errorRef: M13 }
-  - { id: CHK-INT-I4, gen: "Min-1 / Max+1", reason: "vượt biên", errorRef: M13 }
-  - { id: CHK-INT-I5, value: "", reason: "rỗng/multi-space (tuỳ spec)", errorRef: M02 }
+  - { id: CHK-INT-I1, gen: "alphabetic characters", reason: "not a number", errorRef: M13 }
+  - { id: CHK-INT-I2, gen: "full-width (Japanese) digits", reason: "full-width characters", errorRef: M39 }
+  - { id: CHK-INT-I3, gen: "+/- in wrong position (mid-string)", reason: "wrong format", errorRef: M13 }
+  - { id: CHK-INT-I4, gen: "min-1 / max+1", reason: "out of bounds", errorRef: M13 }
+  - { id: CHK-INT-I5, value: "", reason: "empty/multi-space (per spec)", errorRef: M02 }
 notes:
-  - "leading zero (007) có bị cắt không; redundant spaces trước/sau phải xử lý đúng."
+  - "Check leading zero (007) is not stripped; redundant spaces before/after handled correctly."
 uses_security: [sqli]

package/common/field-types/password.yaml

@@ -1,30 +1,30 @@
-# Field-type: password — seeded from common-checklist.xlsx (Input box · Password) + phuong-phap example.
+# Field-type: password — from common-checklist.xlsx (Input box · Password).
 type: password
-description: Password — độ dài + thành phần ký tự theo spec; kèm show/hide + mask.
-format: "theo ràng buộc spec (min/max, ≥1 hoa/thường/số tuỳ dự án)"
+description: Password — length + character-class rules per spec; plus show/hide + mask.
+format: "per spec (min/max, >=1 upper/lower/digit as required)"
 constraints:
-  minLength: 7        # placeholder — ghi đè bằng min thật của spec dự án
+  minLength: 7        # placeholder — override with the project spec's real min
   maxLength: 20       # placeholder
-  requires: [uppercase, lowercase, digit]   # placeholder theo spec
+  requires: [uppercase, lowercase, digit]   # placeholder per spec
 uses_security: [sqli, xss]
 valid:
-  - { id: CHK-PW-01, value: "Passw0rd", note: "đủ hoa+thường+số, trong khoảng" }
-  - { id: CHK-PW-02, note: "alpha only / numeric only / mix — nếu spec cho phép" }
-  - { id: CHK-PW-03, note: "ký tự đặc biệt hợp lệ theo spec (vd ._@)" }
+  - { id: CHK-PW-01, value: "Passw0rd", note: "upper+lower+digit, in range" }
+  - { id: CHK-PW-02, note: "alpha only / numeric only / mix — if the spec allows" }
+  - { id: CHK-PW-03, note: "valid special characters per spec (e.g. ._@)" }
 boundary:
-  - { id: CHK-PW-B1, gen: "đúng minLength", note: "min (vd Aa1bcde = 7)" }
-  - { id: CHK-PW-B2, gen: "minLength+1", note: "min+1" }
-  - { id: CHK-PW-B3, gen: "đúng maxLength", note: "max" }
-  - { id: CHK-PW-B4, gen: "maxLength-1", note: "max-1" }
+  - { id: CHK-PW-B1, gen: "min length", note: "min (e.g. Aa1bcde = 7)" }
+  - { id: CHK-PW-B2, gen: "min+1", note: "min+1" }
+  - { id: CHK-PW-B3, gen: "max length", note: "max" }
+  - { id: CHK-PW-B4, gen: "max-1", note: "max-1" }
 invalid:
-  - { id: CHK-PW-I1, value: "", reason: "rỗng/multi-space (required)", errorRef: M02 }
-  - { id: CHK-PW-I2, gen: "< minLength", reason: "dưới độ dài tối thiểu", errorRef: M29 }
-  - { id: CHK-PW-I3, gen: "> maxLength", reason: "vượt độ dài tối đa", errorRef: M30 }
-  - { id: CHK-PW-I4, value: "passw0rd", reason: "thiếu chữ hoa", errorRef: M31 }
-  - { id: CHK-PW-I5, value: "PASSW0RD", reason: "thiếu chữ thường", errorRef: M32 }
-  - { id: CHK-PW-I6, value: "Password", reason: "thiếu chữ số", errorRef: M33 }
-  - { id: CHK-PW-I7, gen: "full-width Japanese", reason: "ký tự full-width", errorRef: M39 }
-  - { id: CHK-PW-I8, gen: "space before/after hoặc giữa", reason: "khoảng trắng thừa", errorRef: M13 }
+  - { id: CHK-PW-I1, value: "", reason: "empty/multi-space (required)", errorRef: M02 }
+  - { id: CHK-PW-I2, gen: "< min length", reason: "below minimum length", errorRef: M29 }
+  - { id: CHK-PW-I3, gen: "> max length", reason: "exceeds maximum length", errorRef: M30 }
+  - { id: CHK-PW-I4, value: "passw0rd", reason: "missing uppercase", errorRef: M31 }
+  - { id: CHK-PW-I5, value: "PASSW0RD", reason: "missing lowercase", errorRef: M32 }
+  - { id: CHK-PW-I6, value: "Password", reason: "missing digit", errorRef: M33 }
+  - { id: CHK-PW-I7, gen: "full-width Japanese", reason: "full-width characters", errorRef: M39 }
+  - { id: CHK-PW-I8, gen: "space before/after or inside", reason: "redundant whitespace", errorRef: M13 }
 notes:
-  - "Kiểm tra riêng: icon show/hide password (hiển thị + toggle mask↔unmask), ký tự mask đúng spec."
-  - "Confirm Password: kế thừa toàn bộ case của password + case (confirm == password) và (confirm != password → lỗi)."
+  - "Check separately: show/hide password icon (display + toggle mask<->unmask), mask symbol per spec."
+  - "Confirm Password: inherits all password cases + (confirm == password) and (confirm != password -> error)."

package/common/field-types/phone.yaml

@@ -1,23 +1,23 @@
 # Field-type: phone number — from common-checklist.xlsx (Input box · Phone number).
 type: phone
-description: Số điện thoại — chỉ số, cho phép () - + ở vị trí hợp lệ.
+description: Phone number — digits only, allows () - + in valid positions.
 constraints:
   charset: "digits + () - +"
-  minLength: 8      # placeholder theo spec
+  minLength: 8      # placeholder per spec
   maxLength: 15     # placeholder
 valid:
-  - { id: CHK-PHONE-01, value: "0987654321", note: "chỉ số" }
-  - { id: CHK-PHONE-02, value: "+84-90-1234567", note: "có + và - đúng vị trí" }
-  - { id: CHK-PHONE-03, value: "(028)38221234", note: "có () đúng vị trí" }
+  - { id: CHK-PHONE-01, value: "0987654321", note: "digits only" }
+  - { id: CHK-PHONE-02, value: "+84-90-1234567", note: "+ and - in valid positions" }
+  - { id: CHK-PHONE-03, value: "(028)38221234", note: "() in valid positions" }
 boundary:
-  - { id: CHK-PHONE-B1, gen: "đúng min / min+1" }
-  - { id: CHK-PHONE-B2, gen: "đúng max / max-1" }
+  - { id: CHK-PHONE-B1, gen: "min / min+1 length" }
+  - { id: CHK-PHONE-B2, gen: "max / max-1 length" }
 invalid:
-  - { id: CHK-PHONE-I1, gen: "ký tự cấm []:,;\"<>\\?", reason: "ký tự không hợp lệ", errorRef: M13 }
-  - { id: CHK-PHONE-I2, gen: "số Nhật (full-width)", reason: "ký tự full-width", errorRef: M39 }
-  - { id: CHK-PHONE-I3, gen: "chữ cái", reason: "không phải số", errorRef: M13 }
-  - { id: CHK-PHONE-I4, value: "090 123 4567", reason: "khoảng trắng giữa số", errorRef: M13 }
-  - { id: CHK-PHONE-I5, gen: "+/- không ở vị trí đầu; () sai vị trí", reason: "format sai", errorRef: M13 }
-  - { id: CHK-PHONE-I6, gen: "min-1 / max+1", reason: "vượt biên", errorRef: M13 }
-  - { id: CHK-PHONE-I7, value: "", reason: "rỗng/multi-space (tuỳ spec)", errorRef: M02 }
+  - { id: CHK-PHONE-I1, gen: "forbidden chars []:,;\"<>\\?", reason: "invalid characters", errorRef: M13 }
+  - { id: CHK-PHONE-I2, gen: "full-width (Japanese) digits", reason: "full-width characters", errorRef: M39 }
+  - { id: CHK-PHONE-I3, gen: "alphabetic characters", reason: "not a number", errorRef: M13 }
+  - { id: CHK-PHONE-I4, value: "090 123 4567", reason: "spaces between digits", errorRef: M13 }
+  - { id: CHK-PHONE-I5, gen: "+/- not first; () wrong position", reason: "wrong format", errorRef: M13 }
+  - { id: CHK-PHONE-I6, gen: "min-1 / max+1", reason: "out of bounds", errorRef: M13 }
+  - { id: CHK-PHONE-I7, value: "", reason: "empty/multi-space (per spec)", errorRef: M02 }
 uses_security: [sqli]

package/common/field-types/postcode.yaml

@@ -1,16 +1,16 @@
 # Field-type: postcode / zipcode — from common-checklist.xlsx (Input box · Postcode/Zipcode).
 type: postcode
-description: Mã bưu chính — format theo vùng (JP 7 số, có thể có dấu -).
+description: Postal code — region-specific format (JP 7 digits, optional -).
 constraints:
-  format: "region-specific (vd JP: NNN-NNNN)"
+  format: "region-specific (e.g. JP: NNN-NNNN)"
   length: 7   # placeholder
 valid:
-  - { id: CHK-ZIP-01, value: "1500001", note: "7 số (JP)" }
-  - { id: CHK-ZIP-02, value: "150-0001", note: "có dấu - nếu spec cho phép" }
+  - { id: CHK-ZIP-01, value: "1500001", note: "7 digits (JP)" }
+  - { id: CHK-ZIP-02, value: "150-0001", note: "with - if the spec allows" }
 boundary:
-  - { id: CHK-ZIP-B1, gen: "đúng độ dài / độ dài-1 / +1" }
+  - { id: CHK-ZIP-B1, gen: "exact length / length-1 / +1" }
 invalid:
-  - { id: CHK-ZIP-I1, gen: "chữ cái / ký tự lạ", reason: "sai ký tự", errorRef: M13 }
-  - { id: CHK-ZIP-I2, gen: "sai format vùng", reason: "sai format", errorRef: M13 }
-  - { id: CHK-ZIP-I3, value: "", reason: "rỗng (tuỳ spec)", errorRef: M02 }
+  - { id: CHK-ZIP-I1, gen: "alphabetic / stray characters", reason: "invalid characters", errorRef: M13 }
+  - { id: CHK-ZIP-I2, gen: "wrong region format", reason: "wrong format", errorRef: M13 }
+  - { id: CHK-ZIP-I3, value: "", reason: "empty (per spec)", errorRef: M02 }
 uses_security: [sqli]

package/common/field-types/string.yaml

@@ -1,20 +1,20 @@
-# Field-type: string (text 1 dòng) — from common-checklist.xlsx (Input box · String).
+# Field-type: string (single line) — from common-checklist.xlsx (Input box · String).
 type: string
-description: Chuỗi 1 dòng — chấp nhận alnum, JP half/full-width, special, unicode, space.
+description: Single-line string — accepts alnum, JP half/full-width, special chars, unicode, spaces.
 constraints:
-  minLength: 1      # placeholder theo spec
+  minLength: 1      # placeholder per spec
   maxLength: 255    # placeholder
 uses_security: [sqli, xss]
 valid:
   - { id: CHK-STR-01, value: "Normal text 123", note: "alnum + space" }
-  - { id: CHK-STR-02, gen: "half-width Japanese", note: "半角ｶﾅ" }
+  - { id: CHK-STR-02, gen: "half-width Japanese", note: "ﾊﾟｶﾅ" }
   - { id: CHK-STR-03, gen: "full-width Japanese", note: "全角かな漢字" }
-  - { id: CHK-STR-04, gen: "special chars ~!@#$%^&*()_+{}:|<>?,./;'[]-=`", note: "ký tự đặc biệt hợp lệ" }
-  - { id: CHK-STR-05, gen: "unicode / emoji nếu spec cho phép" }
-  - { id: CHK-STR-06, gen: "copy-paste full-width JP", note: "phải xử lý đúng khi paste" }
+  - { id: CHK-STR-04, gen: "special chars ~!@#$%^&*()_+{}:|<>?,./;'[]-=`", note: "valid special characters" }
+  - { id: CHK-STR-05, gen: "unicode / emoji if the spec allows" }
+  - { id: CHK-STR-06, gen: "copy-paste full-width JP", note: "must handle paste correctly" }
 boundary:
-  - { id: CHK-STR-B1, gen: "đúng min / min+1" }
-  - { id: CHK-STR-B2, gen: "đúng max / max-1" }
+  - { id: CHK-STR-B1, gen: "min / min+1 length" }
+  - { id: CHK-STR-B2, gen: "max / max-1 length" }
 invalid:
-  - { id: CHK-STR-I1, value: "", reason: "rỗng/multi-space (success/fail tuỳ spec)", errorRef: M02 }
-  - { id: CHK-STR-I2, gen: "min-1 / max+1", reason: "vượt biên", errorRef: M13 }
+  - { id: CHK-STR-I1, value: "", reason: "empty/multi-space (success/fail per spec)", errorRef: M02 }
+  - { id: CHK-STR-I2, gen: "min-1 / max+1", reason: "out of bounds", errorRef: M13 }

package/common/security/broken-auth.yaml

@@ -1,9 +1,9 @@
 # Security payload bank: Broken authentication — from common-checklist.xlsx (Broken authentication).
 class: broken-auth
-description: Xác thực yếu — session/token/brute-force.
+description: Weak authentication — session/token/brute-force.
 payloads:
-  - { id: CHK-SEC-AUTH-01, technique: "brute force login không giới hạn", expect: "có lockout/captcha/rate-limit" }
-  - { id: CHK-SEC-AUTH-02, technique: "session không hết hạn sau logout / đổi mật khẩu", expect: "invalidate session cũ" }
-  - { id: CHK-SEC-AUTH-03, technique: "session fixation — dùng lại session id trước đăng nhập", expect: "cấp session mới sau login" }
-  - { id: CHK-SEC-AUTH-04, technique: "token đoán được / không hết hạn", expect: "token ngẫu nhiên mạnh, có TTL" }
-oracle: "Đăng nhập/duy trì phiên trái phép = lỗ hổng."
+  - { id: CHK-SEC-AUTH-01, technique: "unlimited brute-force login", expect: "lockout/captcha/rate-limit present" }
+  - { id: CHK-SEC-AUTH-02, technique: "session not expired after logout / password change", expect: "old session invalidated" }
+  - { id: CHK-SEC-AUTH-03, technique: "session fixation — reuse the pre-login session id", expect: "issues a new session after login" }
+  - { id: CHK-SEC-AUTH-04, technique: "guessable / non-expiring token", expect: "strong random token with a TTL" }
+oracle: "Unauthorized login / session persistence = a vulnerability."

package/common/security/idor.yaml

@@ -1,8 +1,8 @@
 # Security payload bank: IDOR — from common-checklist.xlsx (Insecure Direct Object Reference).
 class: idor
-description: Insecure Direct Object Reference — đổi id để truy cập tài nguyên của người khác.
+description: Insecure Direct Object Reference — change an id to access another user's resource.
 payloads:
-  - { id: CHK-SEC-IDOR-01, technique: "đổi id trên URL/param sang record của user khác", expect: "403/404, KHÔNG lộ dữ liệu người khác" }
-  - { id: CHK-SEC-IDOR-02, technique: "đoán id tuần tự (1,2,3…) trên API detail", expect: "kiểm tra quyền sở hữu, từ chối" }
-  - { id: CHK-SEC-IDOR-03, technique: "thao tác (edit/delete) resource ngoài quyền qua id", expect: "chặn ở server, không chỉ ẩn UI" }
-oracle: "Truy cập/sửa được dữ liệu ngoài quyền = lỗ hổng. Kỳ vọng: authorization check theo ownership phía server."
+  - { id: CHK-SEC-IDOR-01, technique: "change the id in URL/param to another user's record", expect: "403/404, does NOT leak the other user's data" }
+  - { id: CHK-SEC-IDOR-02, technique: "guess sequential ids (1,2,3...) on a detail API", expect: "checks ownership, rejects" }
+  - { id: CHK-SEC-IDOR-03, technique: "act (edit/delete) on a resource outside your scope via id", expect: "blocked server-side, not just hidden in the UI" }
+oracle: "Reading/modifying data outside your scope = a vulnerability. Expected: ownership authorization server-side."

package/common/security/input-validation.yaml

@@ -1,8 +1,8 @@
 # Security payload bank: Input validation — from common-checklist.xlsx (Input validation).
 class: input-validation
-description: Ràng buộc đầu vào phía server (không chỉ FE).
+description: Server-side input constraints (not just the front-end).
 payloads:
-  - { id: CHK-SEC-IV-01, technique: "vượt boundary khi FE bị bypass (gọi API trực tiếp)", expect: "server cũng chặn" }
-  - { id: CHK-SEC-IV-02, technique: "sai kiểu dữ liệu (string vào field số)", expect: "reject với lỗi hợp lệ" }
-  - { id: CHK-SEC-IV-03, technique: "control/null bytes, ký tự điều khiển", expect: "loại bỏ/reject" }
-oracle: "FE qua được nhưng BE phải chặn — test trực tiếp API bỏ qua FE."
+  - { id: CHK-SEC-IV-01, technique: "exceed boundary when the FE is bypassed (call the API directly)", expect: "the server rejects too" }
+  - { id: CHK-SEC-IV-02, technique: "wrong data type (string into a numeric field)", expect: "rejects with a valid error" }
+  - { id: CHK-SEC-IV-03, technique: "control/null bytes, control characters", expect: "stripped/rejected" }
+oracle: "The FE may pass but the BE must reject — test the API directly, bypassing the FE."

package/common/security/sqli.yaml

@@ -1,11 +1,11 @@
 # Security payload bank: SQL Injection — from common-checklist.xlsx (SQL Injection sheet).
 # Reusable adversarial values injected into the `invalid` group of any field via uses_security: [sqli].
 class: sqli
-description: SQL Injection — dữ liệu đầu vào nhằm phá câu truy vấn / bypass xác thực.
+description: SQL Injection — inputs crafted to break the query / bypass authentication.
 payloads:
-  - { id: CHK-SEC-SQLI-01, value: "admin' --", target: "login username", expect: "KHÔNG được đăng nhập bỏ qua mật khẩu" }
-  - { id: CHK-SEC-SQLI-02, value: "test' OR '1'='1", target: "ô tìm kiếm", expect: "KHÔNG trả về toàn bộ dữ liệu" }
-  - { id: CHK-SEC-SQLI-03, value: "test@test.com' OR '1'='1", target: "email đăng ký", expect: "xử lý hợp lệ, không lưu sai dữ liệu" }
-  - { id: CHK-SEC-SQLI-04, value: "test', isAdmin = 1 --", target: "sửa hồ sơ", expect: "KHÔNG nâng quyền trái phép" }
-  - { id: CHK-SEC-SQLI-05, value: "2023-01-01' OR '1'='1", target: "bộ lọc report", expect: "chỉ trả dữ liệu đúng filter" }
-oracle: "Bất kỳ dấu hiệu bypass/trả sai dữ liệu = lỗ hổng. Kỳ vọng: escape/parametrize an toàn, báo lỗi hợp lệ."
+  - { id: CHK-SEC-SQLI-01, value: "admin' --", target: "login username", expect: "must NOT log in bypassing the password" }
+  - { id: CHK-SEC-SQLI-02, value: "test' OR '1'='1", target: "search box", expect: "must NOT return all rows" }
+  - { id: CHK-SEC-SQLI-03, value: "test@test.com' OR '1'='1", target: "signup email", expect: "handled safely, no bad data stored" }
+  - { id: CHK-SEC-SQLI-04, value: "test', isAdmin = 1 --", target: "edit profile", expect: "must NOT escalate privileges" }
+  - { id: CHK-SEC-SQLI-05, value: "2023-01-01' OR '1'='1", target: "report filter", expect: "returns only the filtered data" }
+oracle: "Any sign of bypass / wrong data returned = a vulnerability. Expected: escape/parametrize safely, return a valid error."

package/common/security/upload.yaml

@@ -1,10 +1,10 @@
 # Security payload bank: Upload file — from common-checklist.xlsx (Upload file function).
 class: upload
-description: Upload file độc / vượt ràng buộc.
+description: Malicious / constraint-breaking file upload.
 payloads:
-  - { id: CHK-SEC-UP-01, technique: "file trá hình extension (shell.php.jpg)", expect: "kiểm tra MIME thật + whitelist, từ chối" }
-  - { id: CHK-SEC-UP-02, technique: "MIME mismatch (đổi Content-Type)", expect: "verify nội dung thật" }
-  - { id: CHK-SEC-UP-03, technique: "oversize vượt giới hạn", expect: "báo lỗi kích thước" }
-  - { id: CHK-SEC-UP-04, technique: "path traversal trong tên file (../../)", expect: "sanitize tên file, lưu đúng thư mục" }
-  - { id: CHK-SEC-UP-05, technique: "tên file chứa <script> / metadata độc", expect: "xử lý an toàn, không render ra DOM" }
-oracle: "Thực thi/ghi ngoài phạm vi = lỗ hổng."
+  - { id: CHK-SEC-UP-01, technique: "extension spoofing (shell.php.jpg)", expect: "checks real MIME + whitelist, rejects" }
+  - { id: CHK-SEC-UP-02, technique: "MIME mismatch (altered Content-Type)", expect: "verifies real content" }
+  - { id: CHK-SEC-UP-03, technique: "oversize beyond the limit", expect: "reports a size error" }
+  - { id: CHK-SEC-UP-04, technique: "path traversal in the filename (../../)", expect: "sanitizes the filename, stores in the right folder" }
+  - { id: CHK-SEC-UP-05, technique: "filename containing <script> / malicious metadata", expect: "handled safely, not rendered into the DOM" }
+oracle: "Execution / write outside scope = a vulnerability."

package/common/security/xss.yaml

@@ -1,12 +1,12 @@
 # Security payload bank: XSS Injection — from common-checklist.xlsx (XSS Injection sheet).
 class: xss
-description: Cross-Site Scripting — chèn script qua input/URL/attribute/file để thực thi trái phép.
+description: Cross-Site Scripting — inject script via input/URL/attribute/file to execute in the page.
 payloads:
-  - { id: CHK-SEC-XSS-01, value: "<script>alert('XSS')</script>", kind: "Reflected/Stored", expect: "hiển thị text thuần, KHÔNG thực thi script" }
-  - { id: CHK-SEC-XSS-02, value: "<img src=x onerror=alert(1)>", kind: "HTML attribute", expect: "không thực thi onerror" }
-  - { id: CHK-SEC-XSS-03, value: "<svg onload=alert(1)>", kind: "SVG payload", expect: "không thực thi onload / loại bỏ thuộc tính" }
-  - { id: CHK-SEC-XSS-04, value: "\"><script>alert(1)</script>", kind: "Attribute injection", expect: "không phá vỡ HTML, escape an toàn" }
-  - { id: CHK-SEC-XSS-05, value: "<a href=\"javascript:alert(1)\">click me</a>", kind: "Dangerous link", expect: "href bị vô hiệu / sanitize" }
-  - { id: CHK-SEC-XSS-06, value: "<script>alert(1)</script>.jpg", kind: "File name / metadata", expect: "tên file xử lý an toàn, không render ra DOM" }
-  - { id: CHK-SEC-XSS-07, value: "<h1>test</h1>", kind: "HTML injection", expect: "hiển thị dạng text, không render thẻ" }
-oracle: "Alert hiển thị / thẻ được render = lỗ hổng. Kỳ vọng: escape/sanitize, không innerHTML/eval user input."
+  - { id: CHK-SEC-XSS-01, value: "<script>alert('XSS')</script>", kind: "Reflected/Stored", expect: "renders as plain text, does NOT execute the script" }
+  - { id: CHK-SEC-XSS-02, value: "<img src=x onerror=alert(1)>", kind: "HTML attribute", expect: "does not fire onerror" }
+  - { id: CHK-SEC-XSS-03, value: "<svg onload=alert(1)>", kind: "SVG payload", expect: "does not fire onload / strips the attribute" }
+  - { id: CHK-SEC-XSS-04, value: "\"><script>alert(1)</script>", kind: "Attribute injection", expect: "does not break the HTML, escapes safely" }
+  - { id: CHK-SEC-XSS-05, value: "<a href=\"javascript:alert(1)\">click me</a>", kind: "Dangerous link", expect: "href disabled / sanitized" }
+  - { id: CHK-SEC-XSS-06, value: "<script>alert(1)</script>.jpg", kind: "File name / metadata", expect: "filename handled safely, not rendered into the DOM" }
+  - { id: CHK-SEC-XSS-07, value: "<h1>test</h1>", kind: "HTML injection", expect: "displayed as text, not rendered as a tag" }
+oracle: "An alert firing / a tag rendering = a vulnerability. Expected: escape/sanitize, no innerHTML/eval on user input."

package/common/techniques/boundary.yaml

@@ -1,6 +1,6 @@
-# Technique: Boundary Value Analysis — from phuong-phap §Nguồn-3.
+# Technique: Boundary Value Analysis — from the 4-source method.
 technique: boundary
-description: Khi field có min/max rõ ràng — sinh giá trị tại/quanh biên.
-rule: "Với [min,max]: sinh Min-1 (invalid), Min, Min+1, Max-1, Max, Max+1 (invalid)."
+description: When a field has a clear min/max — generate values at and around the boundary.
+rule: "For [min,max]: generate Min-1 (invalid), Min, Min+1, Max-1, Max, Max+1 (invalid)."
 applies_to: [number-integer, number-float, currency, string, password, phone, postcode]
-note: "Phải có 'đúng biên' (Min, Max), không chỉ 'quá biên' — off-by-one thường lọt ở đây."
+note: "Must include the exact boundary (Min, Max), not only over-boundary — off-by-one usually slips through here."

package/common/techniques/decision-table.yaml

@@ -1,6 +1,6 @@
-# Technique: Decision Table — from phuong-phap §Nguồn-3.
+# Technique: Decision Table — from the 4-source method.
 technique: decision-table
-description: Nhiều điều kiện kết hợp cùng ảnh hưởng 1 kết quả.
-rule: "Liệt kê tổ hợp điều kiện → hành động; sinh @cases theo mỗi rule row."
+description: Multiple combined conditions affecting one outcome.
+rule: "List condition combinations -> action; generate @cases from each rule row."
 applies_to: [login, permission, business-flow]
-example: "Login: mật khẩu đúng/sai × account khoá/không × 2FA bật/tắt."
+example: "Login: password correct/wrong x account locked/unlocked x 2FA on/off."

package/common/techniques/equivalence.yaml

@@ -1,6 +1,6 @@
-# Technique: Equivalence Partitioning — from phuong-phap §Nguồn-3.
+# Technique: Equivalence Partitioning — from the 4-source method.
 technique: equivalence
-description: Input chia thành nhóm cùng hành vi — chỉ cần 1 đại diện mỗi nhóm.
-rule: "Gom giá trị theo vùng tương đương (valid / mỗi loại invalid) → 1 đại diện/vùng, tránh test tràn lan."
+description: Inputs split into classes with the same behavior — one representative per class is enough.
+rule: "Group values into equivalence classes (valid / each kind of invalid) -> one representative per class, avoid over-testing."
 applies_to: [all]
-note: "Không cần 300 email sai — chỉ 1 đại diện cho mỗi CÁCH sai (thiếu @, sai vị trí ., full-width…)."
+note: "You don't need 300 bad emails — just one representative per WAY of being wrong (missing @, dot in wrong place, full-width...)."

package/common/techniques/state-transition.yaml

@@ -1,6 +1,6 @@
-# Technique: State Transition + Dependency State Coverage — from phuong-phap §Nguồn-3.
+# Technique: State Transition + Dependency State Coverage — from the 4-source method.
 technique: state-transition
-description: Đối tượng nhiều trạng thái; hoặc A phụ thuộc trạng thái của B.
-rule: "Phủ chuyển hợp lệ + chuyển NGƯỢC không hợp lệ; test X với B ở đủ trạng thái (active/chưa active/hết hạn/xoá mềm)."
+description: An object with multiple states; or A depends on the state of B.
+rule: "Cover valid transitions + INVALID reverse transitions; test X with B in every state (active/inactive/expired/soft-deleted)."
 applies_to: [workflow-entity, dependent-feature]
-example: "Draft → Submitted → Approved → Shipped (kể cả chuyển ngược không hợp lệ)."
+example: "Draft -> Submitted -> Approved -> Shipped (including invalid reverse transitions)."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sungen/driver-data-factory",
-  "version": "3.2.10-beta.5",
+  "version": "3.2.12-beta.1",
   "description": "Sungen Data Factory capability — standardized test-data generation from a field-type + security knowledge catalog (valid/boundary/invalid + traceability), the .overwrite merge layer, and (opt-in) @dataFactory runtime seeding. Design-time knowledge is runtime-free. Plugs into @sun-asterisk/sungen via the capability SPI.",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -14,7 +14,7 @@
   "author": "eqe team (engineer & quality) — Sun Asterisk",
   "license": "MIT",
   "dependencies": {
-    "@sun-asterisk/sungen": "3.2.10-beta.5",
+    "@sun-asterisk/sungen": "3.2.12-beta.1",
     "yaml": "^2.4.0"
   },
   "files": [

package/src/catalog-loader.ts

@@ -101,8 +101,8 @@ export function loadEffectiveCatalog(projectDir: string, root = commonDir()): {
         if (!merged.security[bank]) {
           warnings.push({
             fieldType: type,
-            detail: `overwrite tham chiếu security bank "${bank}" không còn trong common`,
-            suggestion: `cập nhật hoặc xoá mục "${type}" trong qa/data-factory/common.overwrite.yaml`,
+            detail: `overwrite references security bank "${bank}" that no longer exists in the common catalog`,
+            suggestion: `update or remove the "${type}" entry in qa/data-factory/common.overwrite.yaml`,
           });
         }
       }

package/src/cli.ts

@@ -13,6 +13,8 @@ import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import { loadEffectiveCatalog } from './catalog-loader';
 import { expandFieldMap, renderTestData, type FieldMap } from './generator';
 import { lintFieldMap, summarize } from './lint';
+import { generateFixture } from './fixture';
+import { ensureDataFactoryReadme } from './readme';
 
 const FIELDMAP_DIR = (cwd: string) => join(cwd, 'qa', 'data-factory');
 const fieldMapPath = (cwd: string, name: string) => join(FIELDMAP_DIR(cwd), `${name}.fields.yaml`);
@@ -55,14 +57,31 @@ async function genOne(cwd: string, name: string, opts: { force?: boolean }): Pro
   const out = testDataPath(cwd, name);
   if (!out) { console.error(`  ✗ ${name}: no qa/screens/${name} or qa/flows/${name}`); return 'missing'; }
 
-  if (existsSync(out) && !opts.force) {
-    const a = (await ask(`  ? ${name}: test-data already exists — overwrite? [y/N] `)).toLowerCase();
-    if (a !== 'y' && a !== 'yes') { console.log(`  · ${name}: skipped`); return 'skipped'; }
+  const dfData = renderTestData(expanded) as Record<string, any>;
+  const exists = existsSync(out);
+
+  // MERGE, don't clobber. Data Factory owns only the keys it generates (`_generated_by` + each
+  // field name); every OTHER key in the existing test-data (create-test's data, flow-namespaced
+  // keys like `login.email`, @cases datasets, overrides) is preserved. A regenerated field key is
+  // replaced by its standardized version (that's the point). Fixes the whole-file clobber.
+  let final = dfData;
+  let mergedInto = false;
+  if (exists) {
+    if (!opts.force) {
+      const a = (await ask(`  ? ${name}: test-data exists — merge standardized field data in (keeps other keys)? [y/N] `)).toLowerCase();
+      if (a !== 'y' && a !== 'yes') { console.log(`  · ${name}: skipped`); return 'skipped'; }
+    }
+    let existing: Record<string, any> = {};
+    try { existing = (parseYaml(readFileSync(out, 'utf8')) as Record<string, any>) || {}; } catch { existing = {}; }
+    final = { ...existing, ...dfData }; // DF-owned keys win; all other existing keys preserved
+    mergedInto = true;
   }
   mkdirSync(dirname(out), { recursive: true });
-  writeFileSync(out, stringifyYaml(renderTestData(expanded)), 'utf8');
+  writeFileSync(out, stringifyYaml(final), 'utf8');
   const blind = expanded.filter((f) => f.blindSpot).map((f) => f.name);
-  console.log(`  ✓ ${name}: wrote ${out.replace(cwd + '/', '')}${blind.length ? ` (blind spots: ${blind.join(', ')})` : ''}`);
+  const verb = mergedInto ? 'merged into' : 'wrote';
+  const fieldKeys = expanded.map((f) => f.name).length;
+  console.log(`  ✓ ${name}: ${verb} ${out.replace(cwd + '/', '')} (${fieldKeys} field key(s)${mergedInto ? ', other keys preserved' : ''})${blind.length ? ` — blind spots: ${blind.join(', ')}` : ''}`);
   return 'written';
 }
 
@@ -78,6 +97,7 @@ export function registerDataFactoryCommand(program: any): void {
     .option('--force', 'Overwrite existing test-data without asking (implies --yes)')
     .action(async (opts: { screen?: string; all?: boolean; yes?: boolean; force?: boolean }) => {
       const cwd = process.cwd();
+      ensureDataFactoryReadme(cwd);
       if (opts.screen) { await genOne(cwd, opts.screen, opts); return; }
       if (!opts.all) {
         console.error('Specify --screen <name> for one unit, or --all for every unit (with confirmation).');
@@ -105,6 +125,7 @@ export function registerDataFactoryCommand(program: any): void {
     .option('--screen <name>', 'Lint one unit (default: all field-maps)')
     .action((opts: { screen?: string }) => {
       const cwd = process.cwd();
+      ensureDataFactoryReadme(cwd);
       const names = opts.screen ? [opts.screen] : listFieldMaps(cwd);
       if (names.length === 0) { console.error('No field-maps under qa/data-factory/*.fields.yaml.'); process.exitCode = 1; return; }
       const { catalog } = loadEffectiveCatalog(cwd);
@@ -124,4 +145,32 @@ export function registerDataFactoryCommand(program: any): void {
       }
       if (totalErrors) process.exitCode = 1;
     });
+
+  data
+    .command('fixture')
+    .description('Generate a CSV import fixture from the field-map (bulk-import / file-upload testing)')
+    .requiredOption('--screen <name>', 'Unit whose field-map to build a fixture from')
+    .option('--rows <n>', 'Number of valid rows', '3')
+    .option('--invalid', 'Also write <name>.invalid.csv (one seeded-bad row per field + _violation column)')
+    .option('--force', 'Overwrite existing fixture file(s) without asking')
+    .action(async (opts: { screen: string; rows?: string; invalid?: boolean; force?: boolean }) => {
+      const cwd = process.cwd();
+      ensureDataFactoryReadme(cwd);
+      const map = loadFieldMap(cwd, opts.screen);
+      if (!map) { console.error(`✗ ${opts.screen}: no field-map at qa/data-factory/${opts.screen}.fields.yaml`); process.exitCode = 1; return; }
+      const { catalog } = loadEffectiveCatalog(cwd);
+      const res = generateFixture(map, catalog, { rows: parseInt(opts.rows || '3', 10), includeInvalid: !!opts.invalid });
+      const dir = join(cwd, 'qa', 'fixtures');
+      mkdirSync(dir, { recursive: true });
+      const validPath = join(dir, `${opts.screen}.csv`);
+      const writes: Array<[string, string]> = [[validPath, res.valid]];
+      if (res.invalid) writes.push([join(dir, `${opts.screen}.invalid.csv`), res.invalid]);
+      for (const [p] of writes) {
+        if (existsSync(p) && !opts.force) {
+          const a = (await ask(`  ? ${p.replace(cwd + '/', '')} exists — overwrite? [y/N] `)).toLowerCase();
+          if (a !== 'y' && a !== 'yes') { console.log('  · skipped'); return; }
+        }
+      }
+      for (const [p, content] of writes) { writeFileSync(p, content, 'utf8'); console.log(`  ✓ wrote ${p.replace(cwd + '/', '')} (${res.headers.length} columns)`); }
+    });
 }

package/src/fixture.ts

@@ -0,0 +1,79 @@
+/**
+ * Data Factory — CSV/file fixture generator (5b).
+ *
+ * Turns a field-map into a **bulk-import fixture file** (a CSV whose columns are the fields and whose
+ * rows are standardized data), for testing CSV/Excel import, bulk upload, etc. — the `CSV / Import /
+ * Export` checklist area. Two products:
+ *   • the VALID fixture  — N rows of valid values (should import cleanly). Unique fields get a
+ *     per-row suffix so rows don't collide.
+ *   • the INVALID fixture — one row per field's first invalid case (all-valid except that one field),
+ *     plus a trailing `_violation` column naming the field + reason + expected error — so a row-level
+ *     import-rejection test knows which row should fail and why.
+ *
+ * Deterministic: same field-map + catalog → same CSV. Columns are the flattened leaf paths (nested
+ * groups → dotted headers, e.g. `address.city`). Reference the file from an `@api` upload (`files:`)
+ * or a UI file-input step.
+ */
+import type { Catalog } from './types';
+import { expandFieldMap, type FieldMap, type ExpandedField } from './generator';
+
+interface Leaf { path: string; field: ExpandedField }
+
+/** Flatten nested groups to leaf fields with dotted-path headers. */
+function leaves(expanded: ExpandedField[], prefix = ''): Leaf[] {
+  const out: Leaf[] = [];
+  for (const f of expanded) {
+    const path = prefix ? `${prefix}.${f.name}` : f.name;
+    if (f.children) out.push(...leaves(f.children, path));
+    else out.push({ path, field: f });
+  }
+  return out;
+}
+
+const validOf = (f: ExpandedField): string => f.points.find((p) => p.group === 'valid' && p.value != null)?.value ?? '';
+const firstInvalid = (f: ExpandedField) => f.points.find((p) => p.group === 'invalid' && p.value != null);
+
+/** RFC-4180-ish CSV cell quoting. */
+function cell(v: string): string {
+  return /[",\n]/.test(v) ? `"${v.replace(/"/g, '""')}"` : v;
+}
+function row(cells: string[]): string {
+  return cells.map(cell).join(',');
+}
+
+export interface FixtureResult {
+  valid: string;               // CSV text (header + N valid rows)
+  invalid?: string;            // CSV text (header + _violation + one bad row per field)
+  headers: string[];
+}
+
+/** Build the CSV fixture(s) from a field-map. */
+export function generateFixture(map: FieldMap, catalog: Catalog, opts: { rows?: number; includeInvalid?: boolean } = {}): FixtureResult {
+  const rows = Math.max(1, opts.rows ?? 3);
+  const ls = leaves(expandFieldMap(map, catalog));
+  const headers = ls.map((l) => l.path);
+
+  // VALID rows — resolve the valid value per field; a `unique` field's `{{$timestamp}}` token is a
+  // runtime var, not valid in a static file, so replace it with the row index to keep rows distinct.
+  const validRows: string[] = [];
+  for (let i = 1; i <= rows; i++) {
+    validRows.push(row(ls.map((l) => validOf(l.field).replace(/\{\{\$timestamp\}\}/g, String(i)))));
+  }
+  const valid = [row(headers), ...validRows].join('\n') + '\n';
+
+  let invalid: string | undefined;
+  if (opts.includeInvalid) {
+    const invHeaders = [...headers, '_violation'];
+    const invRows: string[] = [];
+    for (const target of ls) {
+      const bad = firstInvalid(target.field);
+      if (!bad) continue; // no concrete invalid value to seed
+      const cells = ls.map((l) => (l === target ? (bad.value as string) : validOf(l.field).replace(/\{\{\$timestamp\}\}/g, '1')));
+      const why = `${target.path}: ${bad.reason || 'invalid'}${bad.expectedError ? ` (${bad.expectedError})` : ''}`;
+      invRows.push(row([...cells, why]));
+    }
+    invalid = [row(invHeaders), ...invRows].join('\n') + '\n';
+  }
+
+  return { valid, invalid, headers };
+}

package/src/generator.ts

@@ -13,13 +13,31 @@ import type { Catalog, FieldType, DataPoint } from './types';
 
 export interface FieldDef {
   name: string;
-  /** Catalog field-type id (email/password/…). A type absent from the catalog → blind spot. */
-  type: string;
+  /** Catalog field-type id (email/password/…). Omit for a GROUP (a field with nested `fields`). A type absent from the catalog → blind spot. */
+  type?: string;
   required?: boolean;
   /** Project overrides merged over the catalog constraints (maxLength, min, max, …). */
   constraints?: Record<string, any>;
   /** Placeholder errorRef (Mxx) → real project message code. Unmapped refs are flagged open. */
   errorMap?: Record<string, string>;
+  /**
+   * Field must be fresh/unique per test run (e.g. a register email/username that can't collide
+   * with a record left by a previous run). When true, the VALID value(s) get a runtime `{{$timestamp}}`
+   * suffix so `resolveDynamicVars` produces a new value every run — no cross-run cache, no flakiness.
+   */
+  unique?: boolean;
+  /**
+   * Nested / group field (complex form): sub-fields expanded recursively under this name
+   * (e.g. `address` → `city`, `postcode`). A field with `fields` is a group and needs no `type`.
+   */
+  fields?: FieldDef[];
+  /**
+   * Inter-field dependency: this field's rule/format depends on another field's value
+   * (e.g. postcode format `dependsOn: { field: country, value: JP }`). Carried through as metadata
+   * so the scenario weave + QA honor the relationship — the generator does not resolve the runtime
+   * condition (that is scenario/@cases logic), it records it.
+   */
+  dependsOn?: { field: string; value?: string };
 }
 
 export interface FieldMap {
@@ -43,9 +61,13 @@ export interface ExpandedPoint {
 
 export interface ExpandedField {
   name: string;
-  type: string;
+  type?: string;
   blindSpot: boolean;
   points: ExpandedPoint[];
+  /** Nested sub-fields (a group field). When present, `points` is empty and children hold the data. */
+  children?: ExpandedField[];
+  /** Recorded inter-field dependency (metadata only — not resolved deterministically). */
+  dependsOn?: { field: string; value?: string };
 }
 
 /** Deterministic filler: a string of exactly `n` chars from a charset seed. */
@@ -72,14 +94,14 @@ function synthesize(dp: DataPoint, type: string, c: Record<string, any>): { valu
   if (dp.value != null) return { value: dp.value };
   const hint = `${dp.gen || ''} ${dp.note || ''}`.toLowerCase();
 
-  // Email length boundaries. `>` / "vượt" → over-boundary (invalid, offset +1).
+  // Email length boundaries. `>` / "over" → over-boundary (invalid, offset +1).
   if (type === 'email') {
-    const over = hint.includes('>') || hint.includes('vượt') || hint.includes('over');
+    const over = hint.includes('>') || hint.includes('over');
     const offset = over ? 1 : hint.includes('-1') ? -1 : hint.includes('+1') ? 1 : 0;
     if (hint.includes('maxlocal') || (hint.includes('local') && (hint.includes('max') || over))) {
       const v = synthEmail(c, 'maxLocal', offset); return v ? { value: v } : { value: null, todo: 'maxLocal' };
     }
-    if (hint.includes('maxtotal') || (hint.includes('tổng') && (hint.includes('max') || over)) || (hint.includes('total'))) {
+    if (hint.includes('maxtotal') || hint.includes('total')) {
       const v = synthEmail(c, 'maxTotal', offset); return v ? { value: v } : { value: null, todo: 'maxTotal' };
     }
   }
@@ -126,23 +148,53 @@ function resolveError(dp: DataPoint, errorMap?: Record<string, string>): { expec
   return { expectedError: dp.errorRef, open: true }; // placeholder survives; flagged open to confirm
 }
 
+/**
+ * Make a valid value fresh-per-run by injecting a `{{$timestamp}}` token (resolved at runtime by the
+ * TestDataLoader's resolveDynamicVars). Email keeps validity via a `+tag` in the local part; other
+ * types append the token. Deterministic at compile time (same token string) — uniqueness is at run time.
+ */
+function makeUnique(value: string, type: string): string {
+  if (value.includes('{{$')) return value; // already dynamic
+  if (type === 'email' && value.includes('@')) {
+    const at = value.indexOf('@');
+    return `${value.slice(0, at)}+{{$timestamp}}${value.slice(at)}`;
+  }
+  return `${value}{{$timestamp}}`;
+}
+
 /** Expand one field into valid/boundary/invalid data points using the effective catalog. */
 export function expandField(field: FieldDef, catalog: Catalog): ExpandedField {
-  const ft: FieldType | undefined = catalog.fieldTypes[field.type];
-  if (!ft) return { name: field.name, type: field.type, blindSpot: true, points: [] };
+  // Group / nested field: no own type — expand each sub-field recursively.
+  if (field.fields && field.fields.length) {
+    return {
+      name: field.name,
+      type: undefined,
+      blindSpot: false,
+      points: [],
+      children: field.fields.map((sub) => expandField(sub, catalog)),
+      ...(field.dependsOn ? { dependsOn: field.dependsOn } : {}),
+    };
+  }
+  const ft: FieldType | undefined = field.type ? catalog.fieldTypes[field.type] : undefined;
+  if (!ft) return { name: field.name, type: field.type, blindSpot: true, points: [], ...(field.dependsOn ? { dependsOn: field.dependsOn } : {}) };
 
   const c = { ...(ft.constraints || {}), ...(field.constraints || {}) };
   const points: ExpandedPoint[] = [];
 
   const push = (dp: DataPoint, group: ExpandedPoint['group']) => {
     const s = synthesize(dp, field.type, c);
+    // Uniqueness: only the VALID (happy-path create) value gets a fresh-per-run suffix. Boundary/invalid
+    // stay literal — they test rules, not record creation.
+    const value = group === 'valid' && field.unique && s.value != null
+      ? makeUnique(s.value, field.type)
+      : s.value;
     points.push({
       id: dp.id,
       group,
-      value: s.value,
+      value,
       todo: s.todo,
       reason: dp.reason,
-      note: dp.note,
+      note: field.unique && group === 'valid' && s.value != null ? `${dp.note ? dp.note + ' · ' : ''}fresh per run` : dp.note,
       ...resolveError(dp, field.errorMap),
     });
   };
@@ -170,7 +222,7 @@ export function expandField(field: FieldDef, catalog: Catalog): ExpandedField {
     }
   }
 
-  return { name: field.name, type: field.type, blindSpot: false, points };
+  return { name: field.name, type: field.type, blindSpot: false, points, ...(field.dependsOn ? { dependsOn: field.dependsOn } : {}) };
 }
 
 /** Expand a whole field-map. */
@@ -186,23 +238,32 @@ export function renderTestData(expanded: ExpandedField[]): Record<string, any> {
   const out: Record<string, any> = {
     _generated_by: 'sungen data gen — standardized test-data (valid/boundary/invalid + CHK trace). Do not hand-edit values; edit the .fields.yaml or common.overwrite.yaml and re-run.',
   };
-  for (const f of expanded) {
-    if (f.blindSpot) {
-      out[f.name] = { _blind_spot: `type "${f.type}" not in Data Factory catalog — provide qa/data-factory/project/${f.name}.yaml` };
-      continue;
-    }
-    const valid = f.points.filter((p) => p.group === 'valid');
-    const boundary = f.points.filter((p) => p.group === 'boundary');
-    const invalid = f.points.filter((p) => p.group === 'invalid');
-    out[f.name] = {
-      valid: valid[0]?.value ?? null,
-      boundary: boundary.map((p) => trim({ id: p.id, value: p.value, note: p.note, todo: p.todo })),
-      invalid: invalid.map((p) => trim({ id: p.id, value: p.value, expected_error: p.expectedError, open: p.open, reason: p.reason, todo: p.todo })),
-    };
-  }
+  for (const f of expanded) out[f.name] = renderOne(f);
   return out;
 }
 
+/** Render one expanded field — recurses for nested groups; carries a dependsOn note. */
+function renderOne(f: ExpandedField): Record<string, any> {
+  const dep = f.dependsOn ? { _depends_on: f.dependsOn.value != null ? `${f.dependsOn.field} = ${f.dependsOn.value}` : f.dependsOn.field } : {};
+  if (f.children) {
+    const group: Record<string, any> = { ...dep };
+    for (const c of f.children) group[c.name] = renderOne(c);
+    return group;
+  }
+  if (f.blindSpot) {
+    return { _blind_spot: `type "${f.type}" not in Data Factory catalog — provide qa/data-factory/project/${f.name}.yaml`, ...dep };
+  }
+  const valid = f.points.filter((p) => p.group === 'valid');
+  const boundary = f.points.filter((p) => p.group === 'boundary');
+  const invalid = f.points.filter((p) => p.group === 'invalid');
+  return {
+    ...dep,
+    valid: valid[0]?.value ?? null,
+    boundary: boundary.map((p) => trim({ id: p.id, value: p.value, note: p.note, todo: p.todo })),
+    invalid: invalid.map((p) => trim({ id: p.id, value: p.value, expected_error: p.expectedError, open: p.open, reason: p.reason, todo: p.todo })),
+  };
+}
+
 function trim(o: Record<string, any>): Record<string, any> {
   const r: Record<string, any> = {};
   for (const [k, v] of Object.entries(o)) if (v != null) r[k] = v;

package/src/index.ts

@@ -24,6 +24,8 @@ export type { FieldDef, FieldMap, ExpandedField, ExpandedPoint } from './generat
 export { lintFieldMap, summarize } from './lint';
 export type { LintIssue } from './lint';
 export { registerDataFactoryCommand } from './cli';
+export { generateFixture } from './fixture';
+export type { FixtureResult } from './fixture';
 export { dataFactoryCoverageSensor } from './sensor';
 export { dfPreconditionCodegen } from './precondition';
 export type { Catalog, FieldType, SecurityBank, Technique, DataPoint, OverwriteWarning } from './types';

package/src/lint.ts

@@ -1,13 +1,13 @@
 /**
  * Data Factory lint — the deterministic coverage oracle from phuong-phap-tao-test-data.md §6.
  *
- * For each field it confirms the "đủ" checklist: ≥1 valid, boundary present when the field has a
+ * For each field it confirms the "is it enough" checklist: >=1 valid, boundary present when the field has a
  * length/number bound, ≥1 invalid per rule, no unresolved values, error codes mapped (not left as
  * placeholders). It also surfaces blind spots (type not in catalog) and — via the catalog loader —
  * stale `.overwrite` warnings. Pure functions; no side effects.
  */
 import type { Catalog } from './types';
-import type { FieldMap, ExpandedField } from './generator';
+import type { FieldMap, ExpandedField, FieldDef } from './generator';
 import { expandFieldMap } from './generator';
 
 export interface LintIssue {
@@ -22,11 +22,22 @@ const BOUNDED = new Set(['email', 'string', 'password', 'phone', 'postcode', 'ka
 export function lintFieldMap(map: FieldMap, catalog: Catalog): { issues: LintIssue[]; expanded: ExpandedField[] } {
   const expanded = expandFieldMap(map, catalog);
   const issues: LintIssue[] = [];
-  const byName = new Map(map.fields.map((f) => [f.name, f]));
 
-  for (const f of expanded) {
+  // Flatten nested groups to leaf fields (dotted path), pairing each with its FieldDef (for `required`).
+  const leaves: Array<{ f: ExpandedField; def?: FieldDef; path: string }> = [];
+  const walk = (efs: ExpandedField[], defs: FieldDef[], prefix: string) => {
+    for (const ef of efs) {
+      const def = defs.find((d) => d.name === ef.name);
+      const path = prefix ? `${prefix}.${ef.name}` : ef.name;
+      if (ef.children) walk(ef.children, def?.fields || [], path);
+      else leaves.push({ f: ef, def, path });
+    }
+  };
+  walk(expanded, map.fields, '');
+
+  for (const { f, def, path } of leaves) {
     if (f.blindSpot) {
-      issues.push({ field: f.name, severity: 'error', code: 'BLIND_SPOT',
+      issues.push({ field: path, severity: 'error', code: 'BLIND_SPOT',
         message: `type "${f.type}" is not in the Data Factory catalog — supply qa/data-factory/project/${f.name}.yaml (valid set, invalid/nonexistent values, error code, dependencies)` });
       continue;
     }
@@ -34,26 +45,25 @@ export function lintFieldMap(map: FieldMap, catalog: Catalog): { issues: LintIss
     const boundary = f.points.filter((p) => p.group === 'boundary');
     const invalid = f.points.filter((p) => p.group === 'invalid');
 
-    if (valid.length === 0) issues.push({ field: f.name, severity: 'error', code: 'NO_VALID', message: 'no valid representative value' });
-    if (invalid.length === 0) issues.push({ field: f.name, severity: 'error', code: 'NO_INVALID', message: 'no invalid value — every rule needs at least one' });
-    if (BOUNDED.has(f.type) && boundary.length === 0) {
-      issues.push({ field: f.name, severity: 'warn', code: 'NO_BOUNDARY', message: `type "${f.type}" usually has min/max — add boundary values or state why not (phuong-phap §6)` });
+    if (valid.length === 0) issues.push({ field: path, severity: 'error', code: 'NO_VALID', message: 'no valid representative value' });
+    if (invalid.length === 0) issues.push({ field: path, severity: 'error', code: 'NO_INVALID', message: 'no invalid value — every rule needs at least one' });
+    if (f.type && BOUNDED.has(f.type) && boundary.length === 0) {
+      issues.push({ field: path, severity: 'warn', code: 'NO_BOUNDARY', message: `type "${f.type}" usually has min/max — add boundary values or state why not (phuong-phap §6)` });
     }
 
     // Unresolved (todo) values — a boundary/gen the constraints could not synthesize.
     for (const p of f.points) {
-      if (p.todo) issues.push({ field: f.name, severity: 'warn', code: 'UNRESOLVED',
+      if (p.todo) issues.push({ field: path, severity: 'warn', code: 'UNRESOLVED',
         message: `${p.id} (${p.group}) needs input: ${p.todo}${p.note ? ` — ${p.note}` : ''}` });
     }
     // Placeholder error codes still unmapped.
     const openErrs = invalid.filter((p) => p.open);
     if (openErrs.length) {
-      issues.push({ field: f.name, severity: 'info', code: 'OPEN_ERRORREF',
+      issues.push({ field: path, severity: 'info', code: 'OPEN_ERRORREF',
         message: `${openErrs.length} invalid case(s) use placeholder error codes (${[...new Set(openErrs.map((p) => p.expectedError))].join(', ')}) — map to real codes via errorMap in the field-map, or confirm with BA/Dev` });
     }
-    const def = byName.get(f.name);
     if (def?.required && valid.length === 0) {
-      issues.push({ field: f.name, severity: 'error', code: 'REQUIRED_NO_VALID', message: 'required field with no valid value' });
+      issues.push({ field: path, severity: 'error', code: 'REQUIRED_NO_VALID', message: 'required field with no valid value' });
     }
   }
   return { issues, expanded };

package/src/readme.ts

@@ -0,0 +1,52 @@
+/**
+ * Drops a `qa/data-factory/README.md` into the user's project so the folder explains itself.
+ * Write-if-absent (never clobbers a user-edited README), like a config file.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+const README = `# \`qa/data-factory/\` — Data Factory (your project's test-data knowledge)
+
+This folder is your project's **test-data standard**: machine-readable data rules that
+\`sungen data gen\` / \`/sungen:create-data-test\` (and \`/sungen:create-test\` step 5.3) expand into
+standardized test-data — **valid / boundary / invalid** values, each carrying a \`CHK-*\` trace id back
+to the spec. It is a reusable asset that **survives \`sungen update\`** (only the driver's shipped
+catalog is refreshed; nothing here is touched).
+
+It is **not** a copy of your spec — it is the structured, reusable data-rules layer the deterministic
+generator needs, complementary to \`requirements/spec.md\` (which is prose spec per screen/flow).
+
+## What lives here
+
+| File | What it is |
+|---|---|
+| \`<name>.fields.yaml\` | **Field-map** for a screen/flow — one entry per input field: its catalog \`type\`, the project's real \`constraints\`, an \`errorMap\` (catalog placeholder code → your real message code), and optionally \`unique: true\`, nested \`fields:\`, \`dependsOn:\`. Authored from \`requirements/spec.md\`; expanded deterministically. A unit with **no input fields** (navigation/list) has no field-map — that's correct. |
+| \`common.overwrite.yaml\` | **Project-wide overrides** to the shipped catalog — your real length limits, real error codes, banned values, extra invalid cases. Deep-merged over the common (later-wins, keyed by \`type\` + data-point \`id\`). Genuinely new project knowledge the shipped catalog can't have. |
+| \`project/<entity>.yaml\` | **Blind-spot answers** — business enums, cross-entity rules, data models the catalog can't know. You fill these when Data Factory hits a field \`type\` it doesn't have (instead of it guessing). |
+| \`recipes.yaml\` | Seed recipes for the \`@dataFactory:<recipe>\` annotation — named field sets bound into \`{{recipe.*}}\` at runtime. |
+
+## Good to know
+
+- **\`sungen data gen\` merges** into \`test-data/<name>.yaml\` — it replaces only the field keys it owns
+  and preserves everything else (create-test data, flow-namespaced keys, \`@cases\`, overrides).
+- **\`unique: true\`** makes a field's valid value fresh per run (\`{{$timestamp}}\`) so a register
+  email/username never collides — no cross-run cache.
+- \`sungen data lint\` checks coverage; \`sungen data fixture\` builds a CSV import fixture under
+  \`qa/fixtures/\`.
+- Edit the field-map / \`.overwrite\` and re-run — never hand-edit the generated \`test-data\` values.
+
+Full guide: https://sungen.sun-asterisk.vn/docs/guides/data-factory
+`;
+
+/** Ensure `qa/data-factory/README.md` exists (write-if-absent). */
+export function ensureDataFactoryReadme(cwd: string): void {
+  const dir = join(cwd, 'qa', 'data-factory');
+  const path = join(dir, 'README.md');
+  if (existsSync(path)) return;
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, README, 'utf8');
+  } catch {
+    /* best-effort — a missing README must never fail a data command */
+  }
+}

package/src/types.ts

@@ -9,7 +9,7 @@ export interface DataPoint {
   id: string;
   /** Literal value (present for concrete cases). */
   value?: string;
-  /** Human instruction to synthesize the value when it depends on project constraints (e.g. "local@ đúng maxLocal"). */
+  /** Human instruction to synthesize the value when it depends on project constraints (e.g. "local part = maxLocal"). */
   gen?: string;
   /** Why this value is invalid (invalid group only). */
   reason?: string;