Reference · ใช้คำให้ตรงกัน Reference · one word, one meaning

พจนานุกรมคำศัพท์ Zyra

คำเดียวกันต้องหมายถึงสิ่งเดียวกันทั้งทีม — ทั้งใน spec, PR, ClickUp และ UI copy หน้านี้เป็นเวอร์ชันอ่านง่ายของ zyra-doc/guides/glossary.md ซึ่งยังเป็นต้นฉบับอ้างอิงหลัก

Zyra glossary

One word should mean one thing across specs, PRs, ClickUp and UI copy. This is the readable version of zyra-doc/guides/glossary.md, which remains the canonical source.

ไม่พบคำที่ค้นหา — ลองคำสั้นลง หรือดูต้นฉบับที่ zyra-doc/guides/glossary.md No match — try a shorter word, or check the canonical zyra-doc/guides/glossary.md

1ชื่อ product & moduleProduct & modules

คำที่ใช้	ห้ามใช้	ความหมาย
Zyra	ZyRA, ZYRA (ยกเว้นใน constant)	ชื่อผลิตภัณฑ์
Virtual Office	Virtual Office Room, VO	โมดูลแผนที่ 2D avatar-based ตัวหลัก
Space Builder	Workspace List, Workspace Page	หน้ารายการ workspace ทั้งหมด (ชื่อตาม Figma)
Space / Workspace	Office, Room	ใช้แทนกันได้ — Workspace ใช้ใน backend/DB, Space ใช้ใน UI copy

Use	Never	Meaning
Zyra	ZyRA, ZYRA (except in constants)	The product name
Virtual Office	Virtual Office Room, VO	The main 2D avatar-based map module
Space Builder	Workspace List, Workspace Page	The screen listing every workspace (name comes from Figma)
Space / Workspace	Office, Room	Interchangeable — Workspace in backend/DB, Space in UI copy

2Entity หลักCore entities

Entity	ความหมาย
Workspace	พื้นที่ทำงาน 1 ชุด มี map, member, capacity — เก็บใน `tb_workspace`
Map	แผนที่ 2D ใน workspace หนึ่ง — เก็บใน `tb_map`; workspace หนึ่งมีได้หลาย map (หลายชั้น)
Room / Room Zone	พื้นที่ย่อยบน map สูงสุด 20 ห้องต่อ map
Private Zone	Room แบบปิด ต้อง Knock ก่อนเข้า (`knock_required: true`)
Zone Section	session ของกลุ่มคนที่กำลังใช้ zone นั้น — `tb_zone_section` + `tb_zone_section_member`
Avatar	ตัวละคร pixel-art ที่แทน user บน map (คนละอย่างกับรูปโปรไฟล์)
Spawn Point	จุดเกิดของ avatar เมื่อเข้า workspace ครั้งแรกหรือหลัง re-join
Office Session	session ของ user ที่ active บน map — เก็บใน Redis ไม่ใช่ DB
Presence	ข้อมูลว่าใคร online บน map ณ ขณะนั้น (จาก WebSocket + Redis)

Entity	Meaning
Workspace	One working area with a map, members and capacity — stored in `tb_workspace`
Map	A 2D map inside a workspace — `tb_map`; a workspace can hold several (multiple floors)
Room / room zone	A sub-area of a map, max 20 per map
Private Zone	A closed room you must knock into (`knock_required: true`)
Zone Section	The session of people currently using a zone — `tb_zone_section` + `tb_zone_section_member`
Avatar	The pixel-art character representing a user on the map (not the profile picture)
Spawn Point	Where an avatar appears on first entry or after re-joining
Office Session	A user's active session on the map — kept in Redis, not the DB
Presence	Who is online on the map right now (from WebSocket + Redis)

3RoleRoles

Role	สี badge	สิทธิ์
Owner	orange / amber	สิทธิ์สูงสุด เชิญได้ทุก role — ออกจาก workspace ไม่ได้จนกว่าจะ Transfer Ownership
Admin / Space Admin	purple	จัดการ member ได้ แต่เชิญได้เฉพาะระดับ Member
Member	blue	ใช้งาน workspace ได้ ออกได้ตลอด
Pending	gray	ถูกเชิญแล้วแต่ยังไม่ยืนยัน — แสดงว่า “รอยืนยัน”
`role_` ใน DB	—	ระดับระบบ: `MEMBER` · `ADMIN` · `SYSADMIN` (คนละชั้นกับ role ใน workspace)

Role	Badge colour	Rights
Owner	orange / amber	Full rights, invites any role — cannot leave until ownership is transferred
Admin / space admin	purple	Manages members but can only invite at Member level
Member	blue	Uses the workspace; may leave at any time
Pending	gray	Invited but not yet accepted — shown as "awaiting confirmation"
`role_` in the DB	—	Platform level: `MEMBER` · `ADMIN` · `SYSADMIN` (a different axis from workspace role)

4Map & zoneMap & zones

คำ	ความหมาย
Collision Layer	layer ที่กำหนด tile ที่ avatar เดินผ่านไม่ได้
Block zone	zone type ที่ทำให้ tile ทั้งบริเวณเดินไม่ได้ (ไม่ใช่ object)
Barrier	collision tile ที่มองไม่เห็นตรงขอบ private zone — กันเดินเข้าโดยไม่ได้รับอนุญาต
Spotlight zone	zone ที่เสียงถูก broadcast ไปทั้งชั้น
Meeting zone	zone ที่เข้าโหมดประชุม (video grid + chat ของ zone)
zone tiles	zone ที่ไม่ใช่สี่เหลี่ยม เก็บเป็น JSONB ใน `tb_map_zone.tiles` — ใช้ helper ใน `lib/zone-utils.ts` ห้ามคำนวณ AABB ดิบ
walkable_group	ตัวชี้ว่า object เป็นพื้นที่เดินได้ — ใช้ตัดสิน render order ชั้นพื้น
wall_mounted	object ที่ติดผนัง — render อยู่หน้าสุดเสมอ
zIndex	ลำดับ render: floor < objects < avatars < UI overlay
last_position	tile ล่าสุดที่ user อยู่ ใช้เป็น spawn เมื่อกลับเข้ามา
Tiled	โปรแกรมออกแบบ map ที่ export เป็น `map.json`

Term	Meaning
Collision layer	The layer marking tiles an avatar cannot walk through
Block zone	A zone type that makes its whole area unwalkable (not an object)
Barrier	Invisible collision tiles along a private zone's edge, stopping uninvited entry
Spotlight zone	A zone whose audio is broadcast to the entire floor
Meeting zone	A zone that switches you into meeting mode (video grid + zone chat)
Zone tiles	Non-rectangular zones stored as JSONB in `tb_map_zone.tiles` — use the helpers in `lib/zone-utils.ts`, never raw AABB maths
walkable_group	Marks an object as walkable surface — decides floor-level render order
wall_mounted	A wall-attached object — always rendered front-most
zIndex	Render order: floor < objects < avatars < UI overlay
last_position	The user's last tile, used as the spawn point when they return
Tiled	The map editor used for design; exports `map.json`

5Movement & engineMovement & engine

คำ	ความหมาย
zyra-engine	game engine ของ Virtual Office (PixiJS) — import จาก `@/zyra-engine`
WASD	เดินด้วยคีย์บอร์ด W/A/S/D หรือปุ่มลูกศร
Click-to-move	คลิกบน map แล้วเดินไปตามเส้นทางที่หาให้
Sprint	กด Shift ค้างเพื่อวิ่ง — ค่าความเร็วต้องตรงกันทั้ง client และ zyra-ws
Path-based movement	โมเดลปัจจุบัน: `move_to` (ส่ง path) → server คิด `duration_ms` → `moving` → จบด้วย `stop`
force_sync	server สั่งให้ client เด้งกลับไปตำแหน่งจริง เมื่อ state ไม่ตรงกัน
Desync	อาการที่หน้าจอเราและ peer เห็นไม่ตรงกัน (วาร์ป, ลื่นไถล, นั่งแล้วหลุด)
AOI (Area of Interest)	grid 16×16 tile ที่ใช้จำกัดการ broadcast ตำแหน่งให้เฉพาะ 3×3 cell รอบตัว
Silent Block	เดินชนสิ่งกีดขวางแล้วหยุดเฉย ๆ ไม่มี error
TILE_SIZE / PLAYER_SPEED	32 px ต่อ tile · 120 px/s

Term	Meaning
zyra-engine	The Virtual Office game engine (PixiJS) — imported from `@/zyra-engine`
WASD	Keyboard walking with W/A/S/D or the arrow keys
Click-to-move	Click the map and the avatar walks the path found for it
Sprint	Hold Shift to run — the speed constant must match on client and zyra-ws
Path-based movement	The current model: `move_to` (send the path) → server computes `duration_ms` → `moving` → ends with `stop`
force_sync	The server snapping a client back to the authoritative position when state diverges
Desync	Your screen and a peer's disagreeing (warps, sliding, sliding off a chair)
AOI (area of interest)	A 16×16-tile grid limiting position broadcast to the 3×3 cells around you
Silent block	Walking into an obstacle just stops you — no error is shown
TILE_SIZE / PLAYER_SPEED	32 px per tile · 120 px/s

6Social & presenceSocial & presence

คำ	ชื่อใน UI	ความหมาย
Wave	ทักทาย	ส่ง gesture ทักทาย ไม่ต้องอยู่ใกล้ — cooldown 10 วินาทีต่อคน
Follow	ติดตาม	เดินตาม avatar อื่นอัตโนมัติ เก็บใน Redis เท่านั้น
Knock	ขอเข้าห้อง	ขอเข้า private zone — คนในห้องกด Allow / Deny
Progressive Cooldown	—	ถูก Deny ครั้งที่ 1–2 รอ 30 วินาที, ครั้งที่ 3+ รอ 5 นาที
Spotlight broadcast	—	พูดออกไปทั้งชั้นจาก spotlight zone
Proximity chat	—	วงสนทนาที่เกิดจากการเดินเข้าใกล้กัน
Presenter guard	—	กฎว่าหนึ่ง zone แชร์จอพร้อมกันได้สูงสุด 2 คน
HUD	—	UI ที่ลอยอยู่บนแผนที่ (member panel, chat, minimap, status)
Heartbeat	—	สัญญาณต่ออายุ presence ใน Redis (TTL 35 วินาที)

Term	UI name	Meaning
Wave	Wave	A greeting gesture; no proximity needed — 10s cooldown per person
Follow	Follow	Automatically walking after another avatar; stored only in Redis
Knock	Knock	Requesting entry to a private zone — those inside press Allow / Deny
Progressive cooldown	—	After a deny: 30s for the 1st–2nd, 5 minutes from the 3rd on
Spotlight broadcast	—	Speaking to the whole floor from a spotlight zone
Proximity chat	—	The conversation circle formed by walking close to someone
Presenter guard	—	The rule capping one zone at two simultaneous screen shares
HUD	—	The UI floating over the map (member panel, chat, minimap, status)
Heartbeat	—	The signal refreshing presence TTL in Redis (35s)

7Availability statusAvailability status

Status	ชื่อใน UI	ความหมาย
available	Active	พร้อมคุย
busy	Busy	ไม่ว่าง แต่ยังรับ Wave
away	Away	ไม่อยู่หน้าจอชั่วคราว
dnd	Do not disturb	บล็อก Wave notification ทั้งหมด
offline	—	ออกจาก office แล้ว — ระบบตั้งให้อัตโนมัติ
meeting	Meeting	สถานะที่ client คิดเอง เมื่ออยู่ใน meeting zone ตั้งแต่ 2 คน — ไม่ได้เก็บใน DB
Custom message	—	ข้อความสั้นที่ผู้ใช้พิมพ์ต่อท้ายสถานะ

Status	UI name	Meaning
available	Active	Happy to talk
busy	Busy	Heads down, but still receives waves
away	Away	Temporarily away from the screen
dnd	Do not disturb	Blocks all wave notifications
offline	—	Left the office — set automatically
meeting	Meeting	Derived client-side when 2+ people share a meeting zone — never stored in the DB
Custom message	—	The short text a user appends to their status

◆

สีของ status ต้องอ่านจาก lib/presence-status.ts เท่านั้น — ห้าม hardcode สีซ้ำในหน้าอื่น

◆

Status colours come from lib/presence-status.ts only — never re-hardcode them elsewhere.

8UI & หน้าจอUI & screens

ชื่อ	อยู่ที่	ความหมาย
Space Builder	`/`	หน้ารายการ workspace 3 แท็บ (All / My / Shared with me)
Before Enter Space	modal	popup เลือก avatar + ตั้งชื่อ ก่อน join
Loading Workspace	`/workspace/[id]/loading`	หน้าโหลด: connect → map → members
Virtual Office	`/workspace/[id]/play`	หน้าแผนที่หลักพร้อม HUD
Left Sidebar	—	แถบไอคอนด้านซ้าย (Map, People, Chat, Notifications, Help, Settings, Profile)
Bottom Toolbar	—	Mic, Cam, Screen share, Emoji, Wave, Lock
Minimap	—	แผนที่ย่อมุมล่างขวา แสดงโซนและสมาชิก
Zone Enter Panel	—	panel ที่เด้งเมื่อเดินเข้าโซน (video grid + chat ของโซน)
Knock Overlay / Notification	—	การ์ดขออนุญาตเข้า และ popup แจ้งเจ้าของห้อง (Allow / Deny)
Status Picker	—	popover เลือก availability status
Player Context Menu	—	เมนูตอนคลิก avatar คนอื่น (Wave, Follow, Chat, View profile)
Help Center	panel	ปุ่ม “?” → บทความช่วยเหลือ + Contact Support
AdminSidebar	`components/admin/`	sidebar ที่ทุกหน้า admin ต้องใช้

Name	Where	Meaning
Space Builder	`/`	The workspace list with three tabs (All / My / Shared with me)
Before Enter Space	modal	The popup for picking an avatar and name before joining
Loading Workspace	`/workspace/[id]/loading`	The loading screen: connect → map → members
Virtual Office	`/workspace/[id]/play`	The main map screen with its HUD
Left sidebar	—	The icon rail (Map, People, Chat, Notifications, Help, Settings, Profile)
Bottom toolbar	—	Mic, cam, screen share, emoji, wave, lock
Minimap	—	The small map bottom-right showing zones and members
Zone enter panel	—	The panel that appears on entering a zone (video grid + zone chat)
Knock overlay / notification	—	The request card, and the owner's popup with Allow / Deny
Status picker	—	The popover for choosing an availability status
Player context menu	—	The menu on clicking another avatar (Wave, Follow, Chat, View profile)
Help Center	panel	The "?" button → help articles + Contact Support
AdminSidebar	`components/admin/`	The sidebar every admin page must use

9Invite & membershipInvite & membership

คำ	ความหมาย
Invitation Token	token ในลิงก์เชิญที่ส่งทางอีเมล — หมดอายุ 7 วัน
Join Link	ลิงก์ถาวรต่อ workspace (ต่างจาก invitation token) สร้างใหม่ได้เพื่อยกเลิกอันเก่า
Join Request	คำขอเข้าจากคนที่มาทางลิงก์ — Owner/Admin กด Approve / Reject
Pending Invite	คำเชิญที่ส่งแล้วแต่ยังไม่ถูกรับ
Auto-accept Invite	token ถูกรับอัตโนมัติหลังสมัคร + ยืนยัน OTP หรือหลัง Google OAuth
Transfer Ownership	Owner ส่งสิทธิ์ให้ Admin คนอื่น — owner เดิมกลายเป็น Admin
Leave Confirmation	ต้องพิมพ์ชื่อ workspace ให้ตรง (case-sensitive) ก่อนออก
Capacity	จำนวนคนสูงสุดที่ workspace รับได้ — เต็มแล้ว WS join จะถูกปฏิเสธ
1 batch = 10 email	เชิญได้สูงสุด 10 อีเมลต่อครั้ง

Term	Meaning
Invitation token	The token in an emailed invite link — expires after 7 days
Join link	A permanent per-workspace link (unlike the invite token); regenerate it to kill the old one
Join request	A request from someone arriving via the link — Owner/Admin approves or rejects
Pending invite	An invite that was sent but not yet accepted
Auto-accept invite	The token is accepted automatically after signup + OTP, or after Google OAuth
Transfer ownership	The owner hands ownership to an Admin — the old owner becomes an Admin
Leave confirmation	You must type the workspace name exactly (case-sensitive) to leave
Capacity	The workspace's people limit — once full, WS joins are refused
1 batch = 10 emails	Up to ten addresses per invite batch

10WebSocket eventWebSocket events

Event	ทิศทาง	ความหมาย
`welcome`	S → C	state ทั้งหมดตอน connect (`me`, `players[]`)
`joined` / `left`	S → C	มีคน join / disconnect
`move_to` / `stop`	C → S	เริ่มเดินตาม path / หยุดเดิน
`moving` / `stopped`	S → C	peer เริ่ม/จบการเดิน พร้อม `duration_ms`
`moved`	S → C	อัปเดตตำแหน่งความถี่สูง — ส่งเป็น binary frame (`0x01`)
`status` / `status_changed`	C → S / S → C	เปลี่ยน availability status
`wave` / `wave_received`	C → S / S → C	ทักทาย และ notification ถึงปลายทาง
`knock` / `knock_decision`	C → S	เคาะประตู และการตัดสิน allow/deny
`room_enter` / `room_exit`	C → S	เข้า/ออกห้อง (คนละอย่างกับ media room)
`section_sync`	ทั้งสองทาง	sync สถานะ zone section (จำนวนคน, ล็อกหรือไม่)
`capacity_reached`	S → C	workspace เต็ม — connection ถูกปิด
`server_drain`	S → C	server กำลังจะปิด บอกให้ reconnect ใหม่

Event	Direction	Meaning
`welcome`	S → C	Full state on connect (`me`, `players[]`)
`joined` / `left`	S → C	Someone joined / disconnected
`move_to` / `stop`	C → S	Start walking a path / stop walking
`moving` / `stopped`	S → C	A peer started or finished a walk, with `duration_ms`
`moved`	S → C	High-frequency position update — sent as a binary frame (`0x01`)
`status` / `status_changed`	C → S / S → C	Availability status change
`wave` / `wave_received`	C → S / S → C	A wave, and the notification delivered to the target
`knock` / `knock_decision`	C → S	Knocking, and the allow/deny decision
`room_enter` / `room_exit`	C → S	Entering/leaving a room (not the same as a media room)
`section_sync`	both ways	Syncs zone-section state (member count, locked or not)
`capacity_reached`	S → C	The workspace is full — the connection is closed
`server_drain`	S → C	The server is shutting down; reconnect after the given delay

11กฎธุรกิจที่พูดถึงบ่อยBusiness rules people quote

คำ	ความหมาย
Office เต็ม	online count ≥ capacity → เข้าไม่ได้
Max 20 rooms	จำนวน room สูงสุดต่อ map
Solo Workspace	workspace ที่มี owner คนเดียวเป็นสมาชิก
Private zone claim	การจับจองโซนส่วนตัว — claim ได้ทันที และการ claim ใหม่ย้ายความเป็นเจ้าของ
Screen share max 2	หนึ่ง zone แชร์จอพร้อมกันได้ 2 คน
OTP	รหัส 6 หลักยืนยันการสมัคร มีเวลาหมดอายุและจำกัดจำนวนครั้ง
Login lock	ผิดครบจำนวนครั้ง → ล็อกชั่วคราว และล็อกนานขึ้นถ้าเกิดซ้ำ
S3 only	ไฟล์/รูปทุกอย่างเก็บบน Cloudflare R2 ไม่เก็บลง filesystem ของ API
Member API separation	member page เรียกได้แค่ `/api/user/` ห้าม `/api/admin/`

Term	Meaning
Office full	online count ≥ capacity → nobody else can enter
Max 20 rooms	The room limit per map
Solo workspace	A workspace whose only member is its owner
Private zone claim	Claiming a private zone — instant, and a new claim transfers ownership
Screen share max 2	Two simultaneous presenters per zone
OTP	The 6-digit signup code, with an expiry and an attempt limit
Login lock	Enough wrong attempts locks the account temporarily, longer on repeats
S3 only	Every file and image lives on Cloudflare R2, never the API's filesystem
Member API separation	Member pages may call `/api/user/` only, never `/api/admin/`

12Scenario / test idScenario / test ids

Prefix	โมดูล
`SC-VO-*`	Virtual Office
`SC-SB-*`	Space Builder
`SC-PROFILE-*`	Profile / Settings
`SC-UG-*`	User Guide / Help Center
`SC-UM-*`	User Management
`SC-AV-*`	Avatar Management
`SC-ANC-*`	Announcement
`TC-*`	test case ที่คู่กับ scenario นั้น
`ZYR-{n}`	เลข ticket ของ support ที่ผู้ใช้ส่งเข้ามา

Prefix	Module
`SC-VO-*`	Virtual Office
`SC-SB-*`	Space Builder
`SC-PROFILE-*`	Profile / Settings
`SC-UG-*`	User Guide / Help Center
`SC-UM-*`	User Management
`SC-AV-*`	Avatar Management
`SC-ANC-*`	Announcement
`TC-*`	The test case paired with a scenario
`ZYR-{n}`	A user-submitted support ticket number

◆

ต้นฉบับที่ครบที่สุดคือ zyra-doc/guides/glossary.md — ถ้าเพิ่มคำใหม่ ให้เพิ่มที่นั่นก่อนแล้วค่อยอัปเดตหน้านี้ตาม

◆

The fullest source is zyra-doc/guides/glossary.md — add new terms there first, then mirror them here.