# Mockup artifacts — TNSU EMS

ฐานข้อมูลแบบหน้าจอสำหรับ internal tracker: [Sitemap](http://localhost:8099/mockup/sitemap), [Page flow](http://localhost:8099/mockup/page-flow), [Screen Listing](http://localhost:8099/mockup/screens)

## โครงสร้าง

```text
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:

```json
{
  "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 และแบ่งแถวไม่ให้ค้าง

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

1. ใช้ ID เดิมเมื่อต้องแก้หน้าเดิม เพิ่ม variant เมื่อเป็นสถานะของหน้าเดิม เพิ่ม ID ใหม่เมื่อเป็นคนละหน้า
2. แก้ `screen.json` และไฟล์ภาพเฉพาะหน้า/variant; ไฟล์ preview รองรับ SVG, PNG, JPG หรือ WebP ใช้ข้อมูลตัวอย่างที่ไม่ใช่บุคคลจริง
3. เพิ่ม manifest ใน `catalog.json` ถ้าเป็นหน้าจอใหม่ ระบุ source, status และ Use-case references โดยไม่สร้างข้อมูลยืนยันเทียม
4. อ้าง component IDs ที่อยู่ใน design-system catalog หรือเพิ่ม component artifact ใหม่พร้อม accessibility/states
5. แก้ source mapping ใน `page-flows/<W-ID>/flow.json` หากต้องเปลี่ยนร่างตั้งต้น; ใน tracker เปลี่ยน Properties/เพิ่ม occurrence/ลากเส้นแล้ว Save เพื่อเก็บแบบที่ทีมทำงานร่วมกัน
6. รัน `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