@sun-asterisk/sungen 2.6.15 → 2.7.0-beta.0

package/src/orchestrator/templates/ai-instructions/claude-skill-viewpoint-group-a-data-entry.md

@@ -0,0 +1,203 @@
+# GROUP A: DATA ENTRY
+
+> The user feeds data into the system — field by field, file by file, or in bulk.
+
+Patterns: 1. Form & Inputs · 2. File Upload · 3. Import / Export
+See `SKILL.md` for the 4 Viewpoints, Shared Checks, and Security Tag Rules.
+
+---
+
+## 1. Form & Inputs
+
+> **Base pattern.** The field-level validation here is inherited by Create (4), Update (5), Login (15), Register (16), Password (17). Generate this as a standalone section only for a plain form with no more-specific role (settings, profile, contact) — see *Pattern selection* in `SKILL.md`.
+
+**Apply when**: the screen has at least 1 input field and 1 submit button that sends data to the server, and no more-specific pattern (4/5/15/16/17) applies.
+
+**Shared checks applied**: XSS/Injection
+
+---
+
+### Tier 1 — @high
+
+**[VP-LOGIC] Business behavior**
+
+- All required fields empty → Submit button is disabled, no request is sent on click
+- All required fields filled validly → Submit button becomes enabled and clickable
+- Submit the form with valid data → success feedback appears (toast/message/redirect), data is saved to the system
+- Submit the form → server returns an error (5xx, business error) → error message appears, all entered data is preserved on the form
+- User clicks submit twice in a row before the response arrives → only 1 request is sent, no duplicate record is created
+- Field A value changes → Field B updates its options accordingly immediately (field dependency; override if the spec uses field visibility: Field B is shown/hidden instead of changing options)
+
+**[VP-VAL] Input validation**
+
+- Submit while a required field is empty (applies if Submit is not disabled — Pattern B) → error message appears right at that field, not only a generic toast
+- Enter beyond max length → field accepts no more characters (HTML maxlength default; override if the spec uses server-side: input accepted but rejected on submit with an error stating the limit)
+- Enter the wrong format (email, phone, date…) → error message appears at the field, field is highlighted (text comes from {{format_error}} in test-data.yaml)
+- User fixes the field after an error → the error clears immediately once the value becomes valid (real-time clear)
+- Input containing only whitespace → treated as empty, submit shows the required error (override if the spec requires auto-trim and accept)
+
+**[VP-SEC]** → Apply Shared Check: XSS/Injection
+
+---
+
+### Tier 2 — @normal + @low
+
+**[VP-UI] Interface states**
+
+- [@normal] Required fields have a visual indicator (asterisk, color, "Required" label)
+- [@normal] Disabled fields: visually dimmed, cursor not-allowed, accept no input
+- [@normal] Focused field: border/outline highlight is clear, distinguishable from an unfocused field
+- [@low] Tab order: the Tab key moves focus in a logical order, top to bottom, left to right
+- [@low] Placeholder text: shows the correct hint text per spec, disappears once the user starts typing
+- [@low] Character counter (if the spec has one): shows the remaining character count, changes color near or at the limit
+
+**[VP-VAL] Boundary values**
+
+4 TCs per range (min-1, min, max, max+1). Default tag = @normal (Tier 2).
+**Override to @high (Tier 1)** when the field is on a critical business rule or the spec uses inclusive operators (`<=`, `>=`).
+
+- [@normal] Exactly the min value → accepted, no error
+- [@normal] Exactly the max value → accepted, no error
+- [@normal] Min - 1 unit → rejected, appropriate error
+- [@normal] Max + 1 unit → rejected, appropriate error
+
+---
+
+### ⚡ Cross-pattern interactions
+
+- **+ Modal/Dialog**: Form inside a modal → on submit success the modal closes, background data updates immediately without a full-page reload
+- **+ Create/Add**: Apply this entire checklist. Add: the form opens as a blank slate, no data cached from a previous submit or a previous open
+- **+ Update/Edit**: Apply this entire checklist. Add: the form pre-fills the correct current data from the DB
+- **+ Notification**: Submit success → toast shows {{success_message}} from test-data.yaml, auto-dismisses after a few seconds
+
+---
+
+## 2. File Upload
+
+**Apply when**: the screen has a component letting the user upload a file (image, PDF, video, document…). It can be standalone or a field within a larger form.
+
+**Shared checks applied**: XSS/Injection (via file name)
+
+---
+
+### Tier 1 — @high
+
+**[VP-LOGIC] Upload behavior**
+
+- Upload a file of the right type and size → upload succeeds, file name/thumbnail/preview appears in the UI
+- Upload in progress → progress indicator appears, the form's submit button is disabled until the upload completes
+- Upload fails (network error, server timeout) → error message states the reason clearly, the user can retry
+- User removes an uploaded file → the file is removed from the form and deleted from the server immediately (override if the spec uses lazy delete: only deleted on form submit)
+- Multiple files (if the spec allows) → each file has its own upload progress and status
+
+**[VP-VAL] File constraints**
+
+- Upload a file with a disallowed extension (not in the whitelist) → rejected immediately, error lists the allowed types
+- Upload a file exceeding the size limit → rejected, error states the limit and the actual size of the selected file
+- Submit the form without uploading a file (field required) → "file required" error appears, the form does not submit
+- Upload an empty file (0 bytes) → rejected with an appropriate error
+
+**[VP-SEC]**
+
+- Upload a file with a valid extension but whose real MIME type is executable (file-type spoofing) → server validates the real MIME type and rejects it
+- File name containing a path-traversal string (`../../etc/passwd`, `../config`) → file name is sanitized, not executed, no path is exposed
+- Upload without authentication → 401/403, the file is not stored on the server
+
+---
+
+### Tier 2 — @normal + @low
+
+**[VP-UI] Interface states**
+
+- [@normal] Drop zone or "Choose file" button is clearly visible and easy to recognize
+- [@normal] The list of accepted file types and the size limit appear in the UI (helper text or tooltip)
+- [@normal] During upload: progress bar or percentage is shown, a cancel button is available
+- [@normal] Upload success: thumbnail (image) or file icon + file name + size are clearly shown
+- [@normal] Multiple upload with a limit: a "2/5 files" counter shows, the upload button hides/disables when the limit is reached
+- [@low] Drag & drop: dragging a file over the zone → drop zone highlights, upload starts automatically on drop
+
+**[VP-VAL] Edge cases**
+
+- [@normal] Upload a file with the same name as an existing one → rejected, error "File already exists" (override if the spec defines overwrite or auto-rename to file(1))
+- [@normal] File name with special characters or Unicode (accented Vietnamese) → upload succeeds, the name is displayed correctly
+
+---
+
+### ⚡ Cross-pattern interactions
+
+- **+ Form & Inputs**: Upload is a field in the form → the form cannot submit if the upload is incomplete or failed
+- **+ Create/Add**: The created record includes the correct file reference, the file is accessible after reopening the record
+- **+ Update/Edit**: The current file is shown → the user can replace it (new upload overwrites the old) or remove it separately
+- **+ Modal/Dialog**: Upload inside a modal → the modal does not close while uploading, progress is not lost
+- **+ Notification**: Upload success/fail → toast shows the correct message and the correct type (success/error)
+
+---
+
+## 3. Import / Export
+
+**Apply when**: the screen has a function to bulk-import data from a file (CSV, Excel) or export the current data to a file.
+
+**Shared checks applied**: Loading State
+
+---
+
+### Tier 1 — @high
+
+**[VP-LOGIC] Import behavior**
+
+*No preview:*
+- Upload a valid file (correct format, all required columns, valid data) → import succeeds, the number of imported records is clearly shown
+- After import → new data appears in the list/table immediately without a reload (override if the spec requires a manual reload)
+- Large file (many records, async processing) → UI shows "processing", the user gets a notification when done
+
+*With preview:*
+- Upload a file → a preview table appears with the parsed data, the user sees it before confirming
+- Preview shows inline errors for each invalid row: highlights the row, states the column and the reason
+- User confirms after viewing the preview → valid records are imported, invalid rows are skipped with a row-level error summary (override if the spec requires rejecting all when any row is invalid)
+- User cancels at the preview step → no record is created, the system returns to the state before the upload
+
+*Export:*
+- User clicks Export → the file download starts automatically, format CSV (override if the spec uses XLSX or another format)
+- Export with an active filter → the file contains only the filtered data, not the entire dataset
+- Export success → the file downloads without navigating the user away from the current page
+
+**[VP-VAL] File & data validation**
+
+- Import a file in the wrong format (not CSV/Excel, wrong delimiter) → rejected, error states the required format with an example
+- Import a file missing required columns → rejected, error lists the missing column names
+- Import a file with a wrong column header name → rejected, error lists the required column names (override if the spec allows partial import ignoring unknown columns)
+- Import records with a key that already exists → skip that row, count it under "Y skipped" in the result summary (override if the spec requires overwrite or rejecting the whole file)
+- Import a file with invalid data in cells (wrong type, over max length) → row-level errors state the row number, column, and reason
+
+**[VP-SEC]**
+
+- Import an Excel file containing formula injection (`=HYPERLINK(...)`, `=CMD(...)` in a cell) → the cell value is sanitized to plain text, not executed
+- Export another user's/tenant's data via IDOR (changing a param in the URL/request) → blocked, 403 Forbidden
+
+---
+
+### Tier 2 — @normal + @low
+
+**[VP-UI] Interface states**
+
+- [@normal] Import: accepted file types, size limit, and a "download template" link appear clearly before the user picks a file
+- [@normal] Import processing: progress/spinner shows, the Import button is disabled to prevent a double submit
+- [@normal] Import result summary: "X records imported, Y skipped, Z failed" is clearly shown, with a downloadable error report if the spec requires
+- [@normal] Export: the Export button switches to a loading state while generating the file
+- [@low] Template download: the template file has the correct column headers and at least 1 row of example data
+
+**[VP-VAL] Edge cases**
+
+- [@normal] Import an empty file (header row only, no data) → warning "No data to import", no crash, no record created
+- [@normal] Export when data is empty → the file still downloads, with the header row only and no data rows (override if the spec wants to block the download and show a "No data to export" toast)
+- [@normal] Export a large file (10k+ records) → the file generates within the allowed timeout, no 504 error
+- [@normal] Export encoding is correct: opening the CSV in Excel shows no broken Vietnamese font (UTF-8 BOM)
+
+---
+
+### ⚡ Cross-pattern interactions
+
+- **+ Data Table**: After import → the table auto-refreshes to show new records; Export takes exactly the data currently shown in the table
+- **+ Filter**: Export with an active filter → the exported file count matches the number of records shown in the UI
+- **+ Pagination**: After import → the total count in the pagination updates correctly
+- **+ Notification**: Import/Export complete (especially async) → toast or notification shows the result summary

package/src/orchestrator/templates/ai-instructions/claude-skill-viewpoint-group-b-data-ops.md

@@ -0,0 +1,179 @@
+# GROUP B: DATA OPERATIONS
+
+> The user creates, edits, or deletes a specific record in the system.
+
+Patterns: 4. Create / Add · 5. Update / Edit · 6. Delete
+See `SKILL.md` for the 4 Viewpoints, Shared Checks, and Security Tag Rules.
+
+---
+
+## 4. Create / Add
+
+**Apply when**: the screen has a function to create a new record (an "Add", "Create", "New" button, or a link to a create form).
+
+**Inherits**: Form & Inputs — field-level validation (required, format, maxlength, whitespace, real-time error clear). Generate those once here; this pattern adds the create-specific rules below.
+
+**Shared checks applied**: XSS/Injection
+
+---
+
+### Tier 1 — @high
+
+**[VP-LOGIC] Create behavior**
+
+- Open the create form → all fields are empty (blank slate), no data cached from a previous open or a previous submit
+- Submit the form with valid data → the record is created successfully, success feedback appears (toast and/or redirect), no error on the form
+- The new record appears in the correct position in the list per the current sort rule (usually newest first)
+- Submit success → toast shows {{success_message}} from test-data.yaml, auto-dismisses after a few seconds
+- Cancel / navigate away while the form is dirty → confirmation dialog "Discard changes?"; choosing Discard → no record is created in the DB
+- User clicks Save twice in a row before the response → only 1 record is created, no duplicate
+
+**[VP-VAL] Unique constraints**
+
+- Enter a value duplicating an existing unique field (e.g. email, employee code) → rejected, inline error right at that field
+- Required fields empty → the form cannot submit, no record is created in the DB (Submit disabled, or an inline error at each field on Submit click — depends on impl)
+- Enter the wrong format → inline error at the field, field highlighted (text comes from {{format_error}} in test-data.yaml)
+
+**[VP-SEC]**
+
+- POST request to create a record without authentication → 401/403, no record is created in the DB
+- POST request to create a record beyond the user's privilege (lower role) → 403 Forbidden from the server
+
+---
+
+### Tier 2 — @normal + @low
+
+**[VP-UI] Interface states**
+
+- [@normal] Form opens: required fields have a visual indicator (asterisk, color), optional fields do not
+- [@normal] Navigate away while the form is unchanged (pristine) → no confirmation dialog appears
+- [@low] Autofocus: the cursor moves to the first field automatically when the form opens
+- [@low] "Save & Add Another" (if the spec has it): save succeeds → the form resets to blank, no redirect
+
+**[VP-VAL] Dependency**
+
+- [@normal] Select Field A (parent dropdown) → Field B (child dropdown) updates its options accordingly
+- [@normal] Fields with default values: the value is shown when the form opens, the user can clear it and enter another value
+
+---
+
+### ⚡ Cross-pattern interactions
+
+- **+ Form & Inputs**: Apply the entire VP-VAL checklist of Form & Inputs (boundary values, real-time error clear)
+- **+ File Upload**: A form with a file upload field → cannot submit if the upload is not finished
+- **+ Modal/Dialog**: Form inside a modal → on submit success the modal closes, the background list auto-refreshes
+- **+ Data Table**: The new record appears in the table in the correct position, the total count increases by 1
+
+---
+
+## 5. Update / Edit
+
+**Apply when**: the screen has a function to edit an existing record (an "Edit" button, a pencil icon, or inline edit).
+
+**Inherits**: Form & Inputs — field-level validation (required, format, maxlength, whitespace, real-time error clear). Generate those once here; this pattern adds the edit-specific rules below.
+
+**Shared checks applied**: XSS/Injection
+
+---
+
+### Tier 1 — @high
+
+**[VP-LOGIC] Edit behavior**
+
+- Open the edit form → all fields are pre-filled with the correct current data from the DB (text, selected dropdown, date, radio, checkbox)
+- Change data and save → the record is updated in the DB, the UI reflects the new data immediately without a full-page reload
+- Save success → toast shows {{success_message}} from test-data.yaml, auto-dismisses after a few seconds
+- Cancel / navigate away while the form is dirty → confirmation dialog "Discard changes?"; choosing Discard → the DB is unchanged, data stays at the old value
+- Save when the form has no changes (pristine) → no redundant DB UPDATE: either the Save button is disabled, or a request is sent but the server returns a no-op (verify via the Network tab: no write operation)
+
+**[VP-VAL] Validation on edit**
+
+- Change a unique field to a value already used by another record → rejected, inline error at the field
+- Leave a unique field of the same record unchanged → save succeeds, no self-duplicate error
+- Clear a required field → the Submit button becomes disabled again (override if the spec validates on submit: an inline error appears at the field on Submit click)
+- Readonly / identity fields (ID, created date, username) → cannot be edited, accept no click/input
+
+**[VP-SEC]**
+
+- PUT/PATCH request without authentication → 401/403, the DB is unchanged
+- Edit a record belonging to another user/tenant (IDOR) → 403 Forbidden, the DB is unchanged
+- Edit a record that has been deleted (stale link) → 404 Not Found
+
+---
+
+### Tier 2 — @normal + @low
+
+**[VP-UI] Interface states**
+
+- [@normal] Readonly fields: visually dimmed, cursor not-allowed, accept no input
+- [@normal] Unsaved-changes indicator: the title or tab shows a "•" or "(unsaved)" mark while the form is dirty
+- [@normal] Concurrent edit: the server returns 409 Conflict on save → the error message clearly states "data was changed by someone else", the user does not lose entered data and is guided to reload to see the latest version
+- [@low] "Last updated by [user] at [time]": the username and timestamp match exactly the last edit in the DB
+
+**[VP-VAL] Dependency on edit**
+
+- [@normal] Field dependency works as in Create: changing Field A → Field B updates its options, without resetting unrelated fields
+
+---
+
+### ⚡ Cross-pattern interactions
+
+- **+ Form & Inputs**: Apply the entire VP-VAL checklist of Form & Inputs
+- **+ File Upload**: The current file is shown → the user can replace it (new upload) or remove it, no need to re-upload if unchanged
+- **+ Modal/Dialog**: Edit form inside a modal → on submit success the modal closes, the background data refreshes immediately
+- **+ Data Table**: The row in the table reflects the new data immediately after a successful edit, without reloading the whole table
+
+---
+
+## 6. Delete
+
+**Apply when**: the screen has a function to delete a record (a "Delete" button, a trash icon, or a context-menu action).
+
+**Shared checks applied**: (no default shared check)
+
+---
+
+### Tier 1 — @high
+
+**[VP-LOGIC] Delete behavior**
+
+- Click Delete → a confirmation dialog must appear (no immediate delete), the confirm button uses a warning color (red/orange)
+- Confirm the delete → the record disappears from the UI immediately, a toast shows the delete success message
+- Cancel the confirmation → the dialog closes, the record stays in the UI and in the DB, no API is called
+- Delete the last record on the current page (pagination) → automatically go to the previous page, no blank page is shown
+- Delete a record referenced by another record (foreign key) → blocked, error message states the name of the module still using this record, the record is not deleted
+
+**[VP-VAL] Delete type**
+
+- Soft delete (default): the record is hidden from the main list, still in the DB with the flag `is_deleted = true`, the direct URL → 404 (override if the spec uses hard delete: the record is fully removed from the DB)
+
+**[VP-SEC]**
+
+- DELETE request without authentication → 401/403, the record is not deleted from the DB
+- DELETE a record belonging to another user/tenant (IDOR via API) → 403 Forbidden, the record is not deleted
+- Directly access the URL of a deleted record (soft or hard) → 404 Not Found
+
+---
+
+### Tier 2 — @normal + @low
+
+**[VP-UI] Interface states**
+
+- [@normal] Confirmation dialog: a clear title "Delete [record name]?", a body explaining the action cannot be undone
+- [@normal] Deleting (loading): the confirm button shows a spinner and is disabled to prevent a double-click
+- [@normal] Delete button: visually a warning (red color or a warning icon), not placed next to Save to avoid mis-clicks
+- [@low] Bulk delete (if the spec has it): select multiple records → one confirmation for all, count stated clearly "Delete 3 records?"
+
+**[VP-VAL] Dependency**
+
+- [@normal] Cascade delete (if the spec has it): delete a parent → the confirmation dialog lists how many children will be deleted with it
+- [@normal] Set Null (if the spec has it): delete a parent → child records still exist, the reference field becomes "Unassigned" or null
+
+---
+
+### ⚡ Cross-pattern interactions
+
+- **+ Data Table**: The record disappears from the table immediately, the total count decreases by 1, the pagination adjusts itself
+- **+ Modal/Dialog**: The delete confirmation is a modal → close the modal after deleting, the background table refreshes
+- **+ List/Card View**: The card/row disappears immediately after a successful delete, no page reload needed
+- **+ Notification**: The delete-success toast shows {{delete_success_message}} from test-data.yaml

package/src/orchestrator/templates/ai-instructions/claude-skill-viewpoint-group-c-data-explore.md

@@ -0,0 +1,233 @@
+# GROUP C: DATA EXPLORATION
+
+> The user searches, filters, and browses existing data in the system.
+
+Patterns: 7. Data Table · 8. Search · 9. Filter · 10. List / Card View
+See `SKILL.md` for the 4 Viewpoints, Shared Checks, and Security Tag Rules.
+
+---
+
+## 7. Data Table
+
+**Apply when**: the screen shows data as a table with rows and columns, usually with sort, pagination, and row-level actions.
+
+**Shared checks applied**: Loading State, Empty State, XSS/Injection (data from the DB displayed safely)
+
+---
+
+### Tier 1 — @high
+
+**[VP-LOGIC] Table behavior**
+
+- Table finishes loading → the number of rows shown matches the configured page size (e.g. 10, 20, 50 rows/page)
+- The total record count in the UI ("Total: X records") matches exactly the real record count in the DB
+- Click a sortable column header → data re-sorts in the correct order (ASC first, DESC second), the sort icon changes accordingly
+- Click a sortable column header once → sort ASC, ↑ icon shows; twice → sort DESC, ↓ icon shows; three times → back to unsorted, icon disappears
+- Click an action button (Edit/Delete/View) on a row → the action applies to that exact row (correct record ID, not a different row)
+- *Pagination:* Click page 2 → the table shows the correct next records, no overlap with page 1
+- *Pagination:* Change the page size → the table reloads with the new row count, resets to page 1
+
+**[VP-VAL] Data integrity**
+
+- The value in each cell matches exactly the data in the DB (amount, date, status label, unit)
+- Long text in a cell → truncated with `...`, does not break the layout or push the column out
+- A column with a null/empty value → shows a placeholder (em dash or empty cell), not raw "undefined" or "null", the cell layout does not break
+
+**[VP-SEC]**
+
+- Data from the DB containing HTML/script tags → rendered as literal text, not executed (XSS)
+- A user without permission to view a sensitive column (salary, national ID…) → the column is fully hidden from the DOM, not leaked via the API response (override if the spec wants to show `***` so the user knows the field exists)
+
+---
+
+### Tier 2 — @normal + @low
+
+**[VP-UI] Interface states**
+
+- [@normal] Sortable column header: has an arrow/indicator icon and a pointer cursor; a non-sortable column has no icon
+- [@normal] Sticky header: scroll down vertically → the header row stays fixed, the column headers are always visible
+- [@normal] Sticky action column (if the table scrolls horizontally): the Edit/Delete column is fixed on the right, not scrolled out of the viewport
+- [@normal] Row hover: the background color changes slightly, clearly indicating which row is hovered
+- [@normal] Pagination controls: Previous is disabled on page 1; Next is disabled on the last page; the current page is highlighted
+- [@low] Column resize (if present): drag the header border to change the width, without affecting the data
+
+**[VP-VAL] Edge cases**
+
+- [@normal] Table with 1 row → pagination is fully hidden (override if the spec wants "Page 1 of 1"), no UI glitch
+- [@normal] Sort on a datetime column → sorts correctly by the real timestamp, not alphabetically as a string
+- [@normal] Sort on a numeric column → sorts correctly by numeric value (10 > 9), not as a string ("10" < "9")
+
+---
+
+### ⚡ Cross-pattern interactions
+
+- **+ Search**: Search submit → the table filters immediately, pagination resets to page 1, the sort state is preserved
+- **+ Filter**: Apply a filter → the table shows only matching rows, the total count updates, pagination resets to page 1
+- **+ Update/Edit**: Save an edit successfully → the row in the table reflects the new data immediately, no full-page reload
+- **+ Delete**: Delete a record → the row disappears immediately, the total count decreases by 1, pagination adjusts itself
+- **+ Import/Export**: After import → the table auto-refreshes; Export takes exactly the data currently shown (current filter + sort)
+
+---
+
+## 8. Search
+
+**Apply when**: the screen has a search box (search bar) letting the user filter data by keyword.
+
+**Shared checks applied**: Empty State, XSS/Injection
+
+---
+
+### Tier 1 — @high
+
+**[VP-LOGIC] Search behavior**
+
+*Basic search:*
+- Enter a valid keyword → results show the correct records containing the keyword (case-insensitive)
+- Partial-match keyword → records containing the keyword anywhere all appear
+- Enter a keyword matching no record → the Empty State message appears ("No results found"), the layout does not break
+- Clear the keyword → the list reloads to the default state (all records), no need to press Search again
+
+*Advanced search (if the spec has multiple search fields):*
+- Fill multiple fields → results satisfy ALL filled conditions (AND logic)
+- Leave some fields empty → filter only by the filled fields, empty fields are ignored
+
+**[VP-VAL] Input handling**
+
+- Input containing only whitespace → auto-trimmed, search with empty string → results as if not searched
+- Enter special characters (single quote `'`, `%`, `_`) → treated as literal text, the query is not broken, results are valid
+- Input beyond max length → field accepts no more characters (HTML maxlength default)
+
+**[VP-SEC]** → Apply Shared Check: XSS/Injection (the search term shown in the results must be escaped correctly) + **SQL injection layer 2** (the search field reaches a LIKE query → test the API-level bypass `@high @manual`)
+
+---
+
+### Tier 2 — @normal + @low
+
+**[VP-UI] Interface states**
+
+- [@normal] A search icon or placeholder clearly hints what the field is for ("Search by name, email…")
+- [@normal] Clear button (X): appears when there is text, click → the field empties and the list resets, no navigation away from the page
+- [@normal] Search trigger: debounce ~300ms after stopping typing, or press Enter → the API call runs, a loading indicator shows in the table
+- [@low] The keyword is highlighted in the results: the matching text portion is bold or a standout color
+
+**[VP-VAL] Edge cases**
+
+- [@normal] Keyword is pure digits (e.g. "12345") → searches correctly in numeric fields and text fields
+- [@normal] Keyword is accented Vietnamese → results are correct, no encoding glitch
+
+---
+
+### ⚡ Cross-pattern interactions
+
+- **+ Data Table**: Search submit → the table filters immediately, pagination resets to page 1
+- **+ Filter**: Search + Filter both active → results satisfy BOTH conditions (AND)
+- **+ Pagination**: Search returns many results → pagination shows correctly, the total count updates
+
+---
+
+## 9. Filter
+
+**Apply when**: the screen has filters (dropdown, date range picker, checkbox group, radio group…) to narrow down the displayed dataset.
+
+**Shared checks applied**: Empty State, URL Manipulation
+
+---
+
+### Tier 1 — @high
+
+**[VP-LOGIC] Filter behavior**
+
+- Select 1 filter value → the list/table shows only matching records, the total count updates correctly
+- Select multiple values within the same filter group → show records matching ANY value in the group (OR logic within the group)
+- Apply multiple filter groups at once → show records matching ALL groups (AND across groups)
+- Reset / Clear All filters → the list returns to default, all filter controls return to their initial values
+- A filter combination yielding 0 results → the Empty State appears, the layout does not break
+- Dependent filter (if the screen has one): select Filter A → Filter B's options reset and reload per A's value immediately, no stale old options retained
+
+**[VP-VAL] Input validation**
+
+- Date range: start date > end date → the Apply button is disabled, the filter is not activated
+- Numeric range: min > max → the Apply button is disabled, the filter is not activated
+- Dropdown filter: options match exactly the real data in the DB (no orphan option)
+
+**[VP-SEC]** → Apply Shared Check: URL Manipulation (tampered filter params → fallback to default, no crash)
+
+---
+
+### Tier 2 — @normal + @low
+
+**[VP-UI] Interface states**
+
+- [@normal] Active filters: shown as clear tags/chips, each tag has an X to remove that filter individually
+- [@normal] Collapse/expand the filter panel: the selected state of the filters is preserved, not reset on collapse
+- [@normal] Filter count badge: "Filters (3)" or an indicator shows the number of active filters
+- [@low] Filter options in alphabetical order (override if the spec uses frequency sort or a custom order), not random on each open
+
+**[VP-VAL] Edge cases**
+
+- [@normal] A filter option removed from the DB (orphan option) → does not appear in the dropdown, no crash even if the URL still has the old param
+- [@normal] Filter with a date range spanning a different timezone → results are correct per the server's timezone
+
+---
+
+### ⚡ Cross-pattern interactions
+
+- **+ Search**: Filter + Search both active → AND logic, total records = the intersection of both conditions
+- **+ Data Table**: Apply a filter → the table reloads, pagination resets to page 1, the sort state is preserved
+- **+ Export**: Export with an active filter → the file contains only filtered records, not the entire dataset
+- **+ Pagination**: A filter changing the total count → pagination recalculates, automatically goes to page 1
+
+---
+
+## 10. List / Card View
+
+**Apply when**: the screen shows many records as a list (rows) or cards (grid), possibly with infinite scroll or a "Load More" button instead of traditional pagination.
+
+**Shared checks applied**: Loading State, Empty State
+
+---
+
+### Tier 1 — @high
+
+**[VP-LOGIC] Navigation & actions**
+
+- Click a card/row → navigate to the correct detail page of that record (correct ID, not a different record)
+- A quick action directly on the card (Like, Bookmark, Add to Cart, Status toggle) → changes the state immediately without navigating to another page
+- *Infinite scroll:* Scroll to the bottom → the next records are appended to the list, the scroll position does not jump back to the top
+- *Load More button:* Click "Load More" → the next records are appended, the total count updates
+- Broken image (image URL is broken or returns 404) → a placeholder image is shown, the card layout does not break
+
+**[VP-VAL] Data integrity**
+
+- The values shown on the card (price, status, tag, rating) match exactly the data in the DB
+- The total count ("Showing X of Y") matches the real total records after applying the current filter/search
+
+**[VP-SEC]**
+
+- Sensitive data (national ID, bank account number) of another user is not shown in the card → verify the DOM does not contain this data
+- A quick action (Like, Follow) without auth → redirect to Login, the action is not performed
+
+---
+
+### Tier 2 — @normal + @low
+
+**[VP-UI] Interface states**
+
+- [@normal] Interactive cards: a clear hover effect (shadow, scale, or overlay) + pointer cursor; non-interactive (informational only) cards: no hover effect, default cursor
+- [@normal] Grid/List layout toggle (if present): the switch changes the layout immediately, the data is unchanged, the preference is saved on page reload
+- [@normal] Skeleton loading: while fetching → skeleton cards show the correct count and layout, no blank screen
+- [@low] Lazy-loading images: images in the viewport load first, images outside load when scrolled to
+
+**[VP-VAL] Edge cases**
+
+- [@normal] A card with very long text (title, description) → text truncates with single-line ellipsis, does not break the card width (override if the spec uses a multi-line clamp: max 2-3 lines)
+- [@normal] Load More / infinite scroll with total < page size → the "Load More" button is fully hidden (override if the spec wants it shown disabled with "No more records")
+
+---
+
+### ⚡ Cross-pattern interactions
+
+- **+ Search**: Keyword submit → the list filters immediately, showing only cards matching the keyword
+- **+ Filter**: Apply a filter → the list reloads, showing only cards matching the condition
+- **+ Delete**: Delete a record → the card disappears from the list immediately, the total count decreases by 1
+- **+ Update/Edit**: Edit successfully → the card reflects the new data immediately (name, status, image)