Giao diện
API · product
Trang sinh tự động
Parse từ schema.graphql (SDL backend export) bằng parser graphql. Mô tả và quyền lấy nguyên văn từ description trong SDL.
10 query · 7 mutation.
Query
deletedProducts
Soft-deleted products only (WEB_ADMIN, ADD-SP-03); never a live row. Search is partial and case-insensitive on name, SKU and barcode; type and the deletedAt range (inclusive) combine with AND. Order by "sort" (default DELETED_AT_DESC), ties by id. pageSize 1..500, default 50. Requires the same permission as deleting a product (catalog.write).
query · SDL không ghi quyền
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
search | String | ||
type | ProductType | ||
deletedFrom | DateTime | ||
deletedTo | DateTime | ||
sort | DeletedProductSort | DELETED_AT_DESC | |
page | Int | 1 | |
pageSize | Int | 50 |
Trả về DeletedProductPage!
| Field | Kiểu | Mô tả |
|---|---|---|
items | [DeletedProduct!]! | |
page | Int! | |
pageSize | Int! | |
total | Int! | |
sourceStatus | SourceStatus! |
product
One product for the detail/edit screen (SP-US-03): every field, creator and last editor with their names, usage and (campaign domain) joined Group Buys. A deleted one is not_found (reason deleted). Requires catalog.read.
query · quyền: catalog.read
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
id | ID! |
Trả về Product!
| Field | Kiểu | Mô tả |
|---|---|---|
id | ID! | |
type | ProductType! | |
sku | String! | Business code (unique, case-insensitive, editable); links use id. |
name | String | Null only for a legacy Draft saved without a name. |
categoryId | ID | |
categoryPath | [String!]! | Category names from the root down to the assigned leaf. |
brandId | ID | |
brandName | String | |
tag | String | |
barcode | String | |
unit | String | |
length | Float | |
width | Float | |
height | Float | |
dimensionUnit | DimensionUnit | |
weight | Float | |
weightUnit | WeightUnit | |
requiresInstallation | Boolean! | |
description | String | Rich text: sanitized Tiptap JSON text (older plain text comes wrapped). |
status | ProductStatus! | |
components | [ComboComponent!]! | Combo only; immutable after creation. |
images | [ProductImage!]! | |
usage | ProductUsage! | |
version | Int! | |
createdAt | DateTime! | |
createdBy | ID! | |
createdByName | String | Creator's name (Người tạo); null when that Admin has no name (shown as —). |
updatedAt | DateTime! | Last update time (Cập nhật lần cuối). |
updatedBy | ID! | |
updatedByName | String | Last editor's name (bởi [tên Admin]); null when that Admin has no name. |
unitId | ID | The linked unit (ProductUnit.id); null: no unit, or a legacy text not linked to a unit. |
unitName | String | Current name of the linked unit; unit carries the label to show (unitName, else the legacy text). |
unitStatus | ProductUnitStatus | Status of the linked unit; null when unitId is null. |
shortName | String | Tên rút gọn (<= 30 characters). |
shortDescription | String | Mô tả ngắn (<= 100 characters). |
isGenuine | Boolean! | Hàng chính hãng (default false). |
accessories | [ProductAccessory!]! | In position order (<= 10). |
specs | [ProductSpec!]! | Display order of this product, as last saved (the order of the specs list sent; DEC-OWN28-SPECS-ORDER). |
joinedCampaigns | [ProductCampaign!]! | Campaigns using this product; empty unless the caller manages the catalog. |
productBulkPreview
The SP-US-04 popup before confirming (also for one product, ids: [id]): each selected live product with its verdict for the action and the unfinished Campaigns / live Combos holding it by name; deleted or unknown ids as missingIds. 1..500 distinct ids (validation_failed ids: empty|max_items|duplicate). Reads only. Requires catalog.read.
query · quyền: catalog.read
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
action | ProductStatusAction! | ||
ids | [ID!]! |
Trả về ProductBulkPreview!
| Field | Kiểu | Mô tả |
|---|---|---|
items | [ProductBulkPreviewItem!]! | The selected live products, in the order asked. |
eligibleCount | Int! | Items with verdict ELIGIBLE (the count on the confirm button; 0 disables it). |
missingIds | [ID!]! | Selected ids that do not exist or are deleted, in the order asked. |
productCodeAvailability
Duplicate check while typing / on blur (SP-US-02 AC01, SP-US-03 AC05): case-insensitive, trimmed; excludeId leaves out the product being edited. A SKU is TAKEN by any product, deleted included (Q-6); a barcode by any product not deleted (On sale, Draft or Discontinued: NEW-SP-09, B03). Advisory only: saveProduct checks again before writing (Rule #10). Requires catalog.write.
query · quyền: catalog.write
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
field | ProductCodeField! | ||
value | String! | ||
excludeId | ID |
Trả về ProductCodeAvailability!
| Field | Kiểu | Mô tả |
|---|---|---|
field | ProductCodeField! | |
value | String! | The checked value after trimming. |
status | ProductCodeStatus! |
productColumnPreference
The calling Admin's product-list columns, or the default when none are saved. Requires catalog.read.
query · quyền: catalog.read
Không có tham số.
Trả về ProductColumnPreference!
| Field | Kiểu | Mô tả |
|---|---|---|
columns | [ProductColumn!]! | Visible columns in the fixed order; SKU and NAME always included. |
isDefault | Boolean! | The columns are the default set: the first 8 (SKU, BARCODE, NAME, TYPE, CATEGORY, BRAND, CREATED_AT, STATUS). |
updatedAt | DateTime | Last save of this Admin; null while nothing is saved (the default applies). |
productComponentSearch
Products that may be added to a combo (SP-US-02 AC04-AC06): standard, On sale, not deleted (never a combo, a draft or a discontinued one), whose name or SKU contains the keyword (case-insensitive, partial; not barcode or tag). The keyword is trimmed and needs at least 3 characters (validation_failed search:min_length). The client searches on Enter or the search icon only. Requires catalog.write.
query · quyền: catalog.write
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
search | String! |
Trả về ProductComponentSearchResult!
| Field | Kiểu | Mô tả |
|---|---|---|
items | [ProductRef!]! | Live On sale standard products, by SKU then id; at most 20. |
hasMore | Boolean! | True when more than 20 products matched (ask for more characters). |
productHistory
Change events of one product, newest first (occurredAt, ties by sequence), last 24 months only (retention). Requires catalog.read; unknown product is not_found, a deleted product's history stays readable. pageSize 1..100, default 20.
query · quyền: catalog.read
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
productId | ID! | ||
filter | ProductHistoryFilter | ||
page | Int | 1 | |
pageSize | Int | 20 |
Trả về ProductHistoryPage!
| Field | Kiểu | Mô tả |
|---|---|---|
items | [ProductHistoryEvent!]! | |
page | Int! | |
pageSize | Int! | |
total | Int! | Events matching the filter (header 'N su kien'). |
sourceStatus | SourceStatus! |
productHistoryActors
Admins who changed the product (unfiltered, for the actor filter). Requires catalog.read.
query · quyền: catalog.read
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
productId | ID! |
Trả về [ProductHistoryActor!]!
| Field | Kiểu | Mô tả |
|---|---|---|
id | ID! | |
name | String | |
eventCount | Int! |
productHistoryRecent
The latest events of a product (detail card, default 4, at most 20). Requires catalog.read.
query · quyền: catalog.read
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
productId | ID! | ||
limit | Int | 4 |
Trả về [ProductHistoryEvent!]!
| Field | Kiểu | Mô tả |
|---|---|---|
id | ID! | |
productId | ID! | |
skuAtEvent | String! | The SKU as it was when the event happened (SKU can be edited). |
type | ProductHistoryEventType! | |
source | ProductHistorySource! | |
occurredAt | DateTime! | |
actorId | ID! | |
actorName | String | The Admin's name; null when the Admin has no name (never a phone or an id). |
operation | String! | |
requestId | ID! | |
correlationId | ID! | |
versionBefore | Int | |
versionAfter | Int! | |
sourceRef | ProductHistorySourceRef! | |
summary | ProductHistorySummary | |
changes | [ProductHistoryChange!]! | |
valuesMasked | Boolean! | Old/new values of this event were masked for the caller. |
products
Products (WEB_ADMIN, SP-US-01), deleted ones never included. Search is partial and case-insensitive on name, SKU, barcode and tag (the client sends the keyword the Admin committed with Enter); filters combine with AND; category includes its descendants; an absent filter means all (no default status); createdFrom/createdTo are inclusive. Order by "sort" (default UPDATED_DESC: newest update first), ties by id (stable pages). pageSize 1..500, default 50 (the screen offers 50/100/500). Requires catalog.read.
query · quyền: catalog.read
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
search | String | ||
categoryId | ID | ||
brandId | ID | ||
type | ProductType | ||
status | ProductStatus | ||
createdFrom | DateTime | ||
createdTo | DateTime | ||
sort | ProductSort | UPDATED_DESC | |
page | Int | 1 | |
pageSize | Int | 50 |
Trả về ProductPage!
| Field | Kiểu | Mô tả |
|---|---|---|
items | [Product!]! | |
page | Int! | |
pageSize | Int! | |
total | Int! | |
sourceStatus | SourceStatus! |
Mutation
bulkRestoreProducts
Restore 1..500 deleted products in ONE transaction, all or nothing: one stale, missing or non-restorable item refuses the batch and nothing is written; details name the ids. Requires catalog.write.
mutation · quyền: catalog.write
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
input | BulkRestoreProductsInput! |
Trả về BulkRestoreProductsResult!
| Field | Kiểu | Mô tả |
|---|---|---|
aggregateId | ID! | The requestId: a batch has no single aggregate. |
version | Int! | Always 1. |
status | CommandStatus! | |
requestId | ID! | |
correlationId | ID! | |
nextAction | NextAction | |
changed | Boolean! | False when every item was already live: no write, no audit row. |
restoredIds | [ID!]! | Ids restored by this command. |
items | [RestoreItemResult!]! | One entry per requested item, in id order. |
bulkSetProductStatus
Discontinue, reactivate or delete the selected products in ONE transaction: verdicts are recomputed under row locks and only ELIGIBLE products change; the rest are skipped with their current verdict. A deleted or unknown id refuses the batch (stale_version, reason batch_changed) and nothing is written. Requires catalog.write.
mutation · quyền: catalog.write
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
input | BulkSetProductStatusInput! |
Trả về BulkSetProductStatusResult!
| Field | Kiểu | Mô tả |
|---|---|---|
aggregateId | ID! | The requestId: a batch has no single aggregate. |
version | Int! | Always 1. |
status | CommandStatus! | |
requestId | ID! | |
correlationId | ID! | |
nextAction | NextAction | |
changed | Boolean! | False when nothing was eligible: no write, no audit row. |
processedIds | [ID!]! | Products changed, by id. |
skipped | [ProductBulkSkipped!]! | Products not changed, by id. |
exportProductHistory
Export the change history of one product (the page filters, newest first, last 24 months) as a private .xlsx. Requires catalog.history.export (super_admin) and an MFA step-up (forbidden, details.reason step_up_required and details.action catalog_history.export until verified; then repeat the same requestId). Old/new values are masked unless the caller holds audit.read. More than 10,000 lines is conflict/export_too_many_rows; a file over the storage cap is conflict/export_too_large; unknown product is not_found.
mutation · quyền: catalog.history.export
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
input | ExportProductHistoryInput! |
Trả về ExportProductHistoryResult!
| Field | Kiểu | Mô tả |
|---|---|---|
aggregateId | ID! | |
version | Int! | |
status | CommandStatus! | |
requestId | ID! | |
correlationId | ID! | |
nextAction | NextAction | |
rowCount | Int! | Lines of the file (one per changed field; a creation is one line). 0 with file null: nothing matched, no file. |
eventCount | Int! | Events behind those lines. |
file | ProductExportFile |
restoreProduct
Restore one soft-deleted product as Ngừng bán. Requires catalog.write (the Delete permission). A product that is already live is a no-op (ALREADY_LIVE). Errors: not_found, stale_version, validation_failed (details.reason combo_components_required | name_required).
mutation · quyền: catalog.write
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
input | RestoreProductInput! |
Trả về RestoreProductResult!
| Field | Kiểu | Mô tả |
|---|---|---|
aggregateId | ID! | |
version | Int! | |
status | CommandStatus! | |
requestId | ID! | |
correlationId | ID! | |
nextAction | NextAction | |
changed | Boolean! | False when the product was already live: no write, no audit row. |
item | RestoreItemResult! |
saveProduct
Create (Save draft / Save product) or edit a product. Requires catalog.write.
mutation · quyền: catalog.write
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
input | SaveProductInput! |
Trả về SaveProductResult!
| Field | Kiểu | Mô tả |
|---|---|---|
aggregateId | ID! | |
version | Int! | |
status | CommandStatus! | |
requestId | ID! | |
correlationId | ID! | |
nextAction | NextAction | |
changed | Boolean! | False for an edit that changes nothing: no write, same version, no audit row. |
product | Product! |
saveProductColumnPreference
Save the calling Admin's product-list columns ("Áp dụng"; "Đặt lại mặc định" then "Áp dụng" saves the default set). Last write wins per account; not audited (personal display setting). Requires catalog.read.
mutation · quyền: catalog.read
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
input | SaveProductColumnPreferenceInput! |
Trả về SaveProductColumnPreferenceResult!
| Field | Kiểu | Mô tả |
|---|---|---|
aggregateId | ID! | The Admin account id (one configuration per Admin). |
version | Int! | Version of the stored configuration; 0 while nothing is stored. |
status | CommandStatus! | |
requestId | ID! | |
correlationId | ID! | |
nextAction | NextAction | |
changed | Boolean! | False when the columns equal what already applies: nothing written. |
preference | ProductColumnPreference! |
setProductStatus
Discontinue, reactivate or delete a product. Requires catalog.write.
mutation · quyền: catalog.write
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
input | SetProductStatusInput! |
Trả về SetProductStatusResult!
| Field | Kiểu | Mô tả |
|---|---|---|
aggregateId | ID! | |
version | Int! | |
status | CommandStatus! | |
requestId | ID! | |
correlationId | ID! | |
nextAction | NextAction | |
productStatus | ProductStatus! | |
isDeleted | Boolean! | |
product | Product | Null after DELETE (a deleted product is not readable). |