Mockup artifacts — TNSU EMS

ฐานข้อมูลแบบหน้าจอสำหรับ internal tracker: Sitemap, Page flow, Screen Listing

โครงสร้าง

mockups/
  catalog.json                         # index ของ manifest ตาม stable Screen ID
  design-system/
    tokens.json                        # สี ตัวอักษร ระยะห่าง — ข้อเสนอ
    components.json                    # index องค์ประกอบที่ใช้ร่วม
  components/<component-id>/
    component.json                     # หน้าที่ props/states, token references, accessibility
    preview.svg                        # ภาพตัวอย่างองค์ประกอบ
  screens/<MODULE>/<SCREEN-ID>/
    screen.json                        # ชื่อ channel modules, route proposal, Use cases, provenance
    variants/<STATE>/preview.svg       # visual artifact แยกสถานะ
  references/<REFERENCE-ID>/
    screen.json                        # อ้างภาพ proposal เดิม ไม่คัดลอกไฟล์ภาพ
  sitemap/graph.json                   # เส้น navigation ร่าง
  page-flows/<W-ID>/flow.json          # mapping ระหว่าง step/ผลลัพธ์กับ screen + state
  tools/build_catalog.py              # seed / ตรวจความครบของ artifacts

ข้อมูลตั้งต้น: 164 screen IDs ที่มีใน use-case explorer และ 6 proposal references รวม 170 records สถานะ default/loading/empty/error/pending/success เป็น wireframe ร่าง ไม่ใช่หน้าจอ final 164 แบบที่ออกแบบและอนุมัติแล้ว ชื่อของบางรหัส องค์ประกอบ route และการจับคู่ขั้นตอนเป็นข้อเสนอให้ตรวจแก้ ภาพเดิมยังอยู่ docs/agent/assets/ui/ และมี provenance แยกจาก wireframes ใหม่

หน้าจอ สถานะ และการปรากฏใน diagram

Screen = ตัวตนหน้าจอ เช่น A01 มี manifest เดียวและ ID ถาวร แม้ใช้หลาย module หรือหลาย Use cases
Variant = ภาพ/รายละเอียดสถานะของหน้าเดียว เช่น error หรือ pending เลือกใช้ตามบริบท ไม่ได้หมายความว่าทุกหน้าต้องมี error/success ทางธุรกิจเหมือนกัน
Node occurrence = การปรากฏของหน้าจอใน diagram มี node ID ของตัวเอง อ้าง screen_id + variant และ step_id จึงใช้ A01 ได้หลายครั้งโดยแต่ละครั้งมี state/ตำแหน่ง/คำอธิบายต่างกัน
Component = องค์ประกอบที่นำกลับมาใช้ เช่น status-banner หรือ form-field; เก็บสัญญา props/states และภาพตัวอย่าง เป็น design artifacts ยังไม่ใช่ Vue component ของผลิตภัณฑ์
Graph = occurrence + เส้นที่มี label/หัวลูกศร แยกจากตัว screen จึงไม่ต้องคัดลอกภาพเมื่อเชื่อมเพิ่ม

ตัวอย่างใน flow:

{
  "use_case": "W-41",
  "status": "proposed",
  "mapping": {
    "step-1": {"screen_id": "A01", "variant": "default", "status": "proposed"},
    "outcome-6-3": {"screen_id": "A03", "variant": "error", "status": "proposed"}
  }
}

Page flow ร่างอ่านโหนด/Decision/เส้นจาก draftDiagram() ของ canonical Use case จึงเก็บทางข้าม วนกลับ ขอเอกสารเพิ่ม และผลลัพธ์อื่นครบตามที่ต้นฉบับระบุ ขั้นระบบที่ไม่มี UI คงเป็น Process; ไม่สมมติว่าทุกงาน backend มีหน้าจอ การจับคู่ role/prefix เป็นร่าง และแก้ mapping เป็น manual ได้ใน Properties ภาพสถานะร่างของ alternate outcome ไม่ใช่การอนุมัติผลธุรกรรม

Sitemap อ้าง source screen-list order และกลุ่มบทบาทเป็น navigation ที่เสนอ เพราะต้นฉบับไม่ได้ให้ sitemap ที่ยืนยันครบทุกเส้น ใช้เป็นจุดเริ่มตรวจ/ลากแก้ ไม่อ้างว่า array ของรหัสหน้าจอเป็นลำดับจริงที่ตัดสินแล้ว รองรับ cycle สำหรับเส้นกลับ/นำทาง ใช้ layout ที่ collapse cycles และแบ่งแถวไม่ให้ค้าง

เพิ่มหรือแก้แบบหน้าจอ

ใช้ ID เดิมเมื่อต้องแก้หน้าเดิม เพิ่ม variant เมื่อเป็นสถานะของหน้าเดิม เพิ่ม ID ใหม่เมื่อเป็นคนละหน้า
แก้ screen.json และไฟล์ภาพเฉพาะหน้า/variant; ไฟล์ preview รองรับ SVG, PNG, JPG หรือ WebP ใช้ข้อมูลตัวอย่างที่ไม่ใช่บุคคลจริง
เพิ่ม manifest ใน catalog.json ถ้าเป็นหน้าจอใหม่ ระบุ source, status และ Use-case references โดยไม่สร้างข้อมูลยืนยันเทียม
อ้าง component IDs ที่อยู่ใน design-system catalog หรือเพิ่ม component artifact ใหม่พร้อม accessibility/states
แก้ source mapping ใน page-flows/<W-ID>/flow.json หากต้องเปลี่ยนร่างตั้งต้น; ใน tracker เปลี่ยน Properties/เพิ่ม occurrence/ลากเส้นแล้ว Save เพื่อเก็บแบบที่ทีมทำงานร่วมกัน
รัน python3 mockups/tools/build_catalog.py --check และ cd tracker && go test ./...

python3 mockups/tools/build_catalog.py สร้าง artifacts ที่ยังไม่มีและเติม index โดยไม่ทับแบบเดิม ส่วน --refresh ใช้ regenerate seeded artifacts ทั้งชุด เท่านั้น และจะทับการแก้ไฟล์ร่างเหล่านั้น ต้องตรวจ diff/สำรองงานก่อนใช้กับชุดที่ออกแบบต่อแล้ว ตัว checker จะแจ้งเมื่อ source references/mappings ไม่ตรง ไม่อัปเดตความหมายของแบบเก่าเงียบ ๆ

Tokens และ component contracts เป็นข้อเสนอในการออกแบบ Preview SVG เป็น artifact ที่เก็บแยกและแก้ได้ การแก้ token JSON ไม่อ้างว่าจะ rewrite SVG ที่ผู้ใช้ออกแบบเองโดยอัตโนมัติ

การบันทึกร่วมและ revision

แบบที่ผู้ใช้บันทึกอยู่ที่ tracker/data/mockups/graphs/<sitemap|W-ID>.json (หรือ <-data>/mockups/graphs/ บน test server) เก็บ graph ปัจจุบันและ history ในไฟล์เดียว เขียนแบบ atomic และตรวจ revision เพื่อป้องกันการบันทึกทับงานอีกคน Restore สร้าง revision ใหม่โดยเก็บ snapshot เดิมครบ

Source artifacts ไม่ถูกเขียนทับจากปุ่ม Save; เมื่อ source/catalog เปลี่ยน แสดง notice โดยยังเก็บ saved graph เดิม ใช้ Reset to source เมื่อตรวจแล้วและ Save เพื่อเพิ่ม revision ใหม่ การ reset ไม่ยืนยัน Development Approval ของ Use case

Editor รองรับ image cards, screen/state mapping, process/decision/start/end, เส้น/label/หัวลูกศร, grid 20, Ctrl+wheel zoom, pan, fit, arrange, Undo/Redo, ค้นหาและ focus หน้าจอ รวมทั้ง scope ตาม module/channel ใน Sitemap ตัวกรองซ่อนเฉพาะมุมมอง ไม่ลบหน้าที่ซ่อนออกจาก graph ที่บันทึก

API

Method	Path	Purpose
GET	`/api/mockups/catalog`	Screen/variant catalog
GET	`/api/mockups/graphs/{sitemap\|W-ID}`	Current saved graph or source draft, source-change status
GET	`/api/mockups/graphs/{key}?draft=1`	Source draft retaining current revision as save base
PUT	`/api/mockups/graphs/{key}`	Save graph with expected revision
GET	`/api/mockups/graphs/{key}/revisions`	Immutable snapshots
POST	`/api/mockups/graphs/{key}/restore`	`{revision, target_revision}` restores as new revision
GET	`/mockup-assets/{artifact-path}`	Allowlisted preview artifacts only

Writes require same Origin/Referer. Stale save/restore returns 409; invalid screen/state/connection is rejected. Asset paths are confined to catalog previews in the repository; symlinks outside are rejected. Diagram history and screenshots of tests use temporary data only.

รุ่นของภาพที่ต้องเก็บย้อนหลัง

Graph revision เก็บตำแหน่ง/เส้น/คำอธิบายและ screen/variant references ไม่ได้คัดลอก bytes ของภาพทุกครั้ง หากแบบผ่าน baseline แล้ว ให้คงไฟล์และ variant ID เก่าไว้ เพิ่ม visual revision เป็น variant ID/โฟลเดอร์ใหม่ เช่น variants/default-r2/preview.svg แล้วเลือกให้ occurrence ใช้รุ่นนั้น วิธีนี้ทำให้ Restore กลับ reference รุ่นเก่าได้โดยภาพเก่ายังอยู่ ใช้ Git เก็บประวัติ manifest/component/source เพิ่มเติม อย่าตีความว่า Restore graph จะกู้ภาพที่ถูกเขียนทับใน filesystem ได้

ทุก screen ตั้งต้นต้องมี variant default; ให้คง variant นี้ไว้เมื่อเพิ่ม state/visual revisions อื่น ชื่อหน้าจอเป็น stable Screen ID ส่วน revision ของภาพใช้ variant ID/ไฟล์ที่ไม่ทับรุ่นเก่า

ชื่อ Module และ Page flow groups

catalog.json.module_names เป็นชื่อเต็มสำหรับการแสดงผล รหัสเดิมยังใช้ใน manifests, filters, URLs และ graph references ภายใน UI แสดงชื่อเต็มในตาราง รายละเอียด ตัวกรอง หัวกลุ่ม และภาพ wireframe ร่าง ไม่เพิ่มรหัสย่อหน้าชื่อ

หน้าเลือก Page flow หุบ/แสดงตาม Module ได้ พร้อม Expand all / Collapse all จำสถานะด้วย browser storage แยกจาก Use cases การค้นหาจะเปิดกลุ่มที่ตรงชั่วคราว และกลับไปใช้สถานะที่บันทึกไว้เมื่อล้างคำค้น

Dark mode ใช้คู่สี filled controls --btn-bg / --on-btn เพื่อไม่เอาสีหัวข้อ --accent ซึ่งเป็นสีอ่อนมาเป็นพื้นหลังใต้ข้อความสีขาว Regression tests ตรวจคู่สีใน explicit และ OS light/dark, active/hover states และข้อความใน diagram