상품 카탈로그: 옵션 변형, 최소 단위 가격, 카테고리, 컬렉션, 번역, 안전한 재고 예약
설치
genpm add @core/catalog포함 내용
- src/lib/catalog/에 소스 코드, 파일 8개. (38.6kB)
- src/lib/catalog/AGENTS.md에 AI 규칙, 그리고 IDE 규칙 파일.
- .env.example에 추가되는 환경 변수: STORE_CURRENCY.
- @core/contracts, @core/db, @core/money, @core/rich-text을(를) 자동으로 해결합니다.
README
이 패키지에는 README가 없습니다.
이것이 AI가 src/lib/catalog에서 작업할 때 읽는 내용 그대로입니다. 그 외에는 컨텍스트에 아무것도 추가되지 않습니다.
@core/catalog — rules for AI agents
Purpose
Products for a store: up to 3 options (Size, Color…) and their variants with SKU, price/compare-at/cost in minor
units, stock with backorder rules, weight and image; categories (tree), manual ordered collections, tags, attributes,
per-locale translations, media references (@core/media ids), sitemap/search sources and admin resources.
reserveStock locks the variant row so two buyers can't get the last unit. No cart, prices rules or multi-warehouse.
Map
index.ts— public API:createProduct,updateProduct,getProduct,listProducts,reserveStock,releaseStock,upsertCategory,setCollection,categoryTree,lowStockVariants,catalogAdminResources.products.ts— products, variants, listing, stock.taxonomy.ts— categories and collections.sources.ts—productSitemapSource,productSearchSource.admin.ts— admin resources.schema.ts— tables.
Integration
- Env:
STORE_CURRENCY(ISO code, defaultEUR). Migrations as insrc/lib/db/AGENTS.md. - Product page:
const p = await getProduct(slug, { locale })(404 when null); showp.variantswithformat(v.price, locale)(@core/money) andv.availability; renderp.descriptionwith @core/rich-text. - Listing:
listProducts({ category, tag, collection, sort, page, minPrice, maxPrice, inStock }). - Register
productSitemapSource()(seo),productSearchSource()(search) and...catalogAdminResources()(admin). - JSON-LD with
jsonLd.product(@core/seo) usingavailabilityand the real price. - Verify: create a product with two variants in the admin and see it at
/products/<slug>.
Conventions
- Prices are integers in
STORE_CURRENCY; the server price is the only valid price (carts recompute it). - Reserve stock only inside the order transaction (
reserveStock(id, qty, tx)); release it on cancel/expiry. - Archive products instead of deleting them: orders keep references to their variants.
- Permissions:
products:read|create|update|delete.
Don't
- Don't show a compare-at price that isn't real (the EU requires the lowest price of the last 30 days for discounts).
- Don't decrement
stockwith plain updates outsidereserveStock/releaseStock. - Don't expose
costAmountin public pages or APIs.
# @core/catalog — rules for AI agents
## Purpose
Products for a store: up to 3 options (Size, Color…) and their variants with SKU, price/compare-at/cost in minor
units, stock with backorder rules, weight and image; categories (tree), manual ordered collections, tags, attributes,
per-locale translations, media references (@core/media ids), sitemap/search sources and admin resources.
`reserveStock` locks the variant row so two buyers can't get the last unit. No cart, prices rules or multi-warehouse.
## Map
- `index.ts` — public API: `createProduct`, `updateProduct`, `getProduct`, `listProducts`, `reserveStock`, `releaseStock`, `upsertCategory`, `setCollection`, `categoryTree`, `lowStockVariants`, `catalogAdminResources`.
- `products.ts` — products, variants, listing, stock. `taxonomy.ts` — categories and collections.
- `sources.ts` — `productSitemapSource`, `productSearchSource`. `admin.ts` — admin resources. `schema.ts` — tables.
## Integration
1. Env: `STORE_CURRENCY` (ISO code, default `EUR`). Migrations as in `src/lib/db/AGENTS.md`.
2. Product page: `const p = await getProduct(slug, { locale })` (404 when null); show `p.variants` with
`format(v.price, locale)` (@core/money) and `v.availability`; render `p.description` with @core/rich-text.
3. Listing: `listProducts({ category, tag, collection, sort, page, minPrice, maxPrice, inStock })`.
4. Register `productSitemapSource()` (seo), `productSearchSource()` (search) and `...catalogAdminResources()` (admin).
5. JSON-LD with `jsonLd.product` (@core/seo) using `availability` and the real price.
6. Verify: create a product with two variants in the admin and see it at `/products/<slug>`.
## Conventions
- Prices are integers in `STORE_CURRENCY`; the server price is the only valid price (carts recompute it).
- Reserve stock only inside the order transaction (`reserveStock(id, qty, tx)`); release it on cancel/expiry.
- Archive products instead of deleting them: orders keep references to their variants.
- Permissions: `products:read|create|update|delete`.
## Don't
- Don't show a compare-at price that isn't real (the EU requires the lowest price of the last 30 days for discounts).
- Don't decrement `stock` with plain updates outside `reserveStock`/`releaseStock`.
- Don't expose `costAmount` in public pages or APIs.
.genpmignore 적용 후 주입될 정확한 트리입니다. 고정 대상:
// Tablas de @core/catalog. Las recoge drizzle-kit vía src/lib/db/drizzle.config.ts.
import { boolean, index, integer, jsonb, pgTable, primaryKey, text, timestamp } from 'drizzle-orm/pg-core';
import { primaryId, timestamps } from '../db/index.ts';
import type { Doc } from '../rich-text/index.ts';
export type ProductOption = { name: string; values: string[] };
export type ProductTranslation = { name?: string; description?: Doc; seoTitle?: string; seoDescription?: string };
export const products = pgTable(
'products',
{
id: primaryId('prd'),
slug: text('slug').notNull().unique(),
name: text('name').notNull(),
description: jsonb('description').$type<Doc>(),
status: text('status', { enum: ['draft', 'active', 'archived'] }).notNull().default('draft'),
kind: text('kind', { enum: ['physical', 'digital'] }).notNull().default('physical'),
brand: text('brand'),
/** Opciones de variante en orden: `[{ name: 'Size', values: ['S','M'] }]`. */
options: jsonb('options').$type<ProductOption[]>().notNull().default([]),
tags: jsonb('tags').$type<string[]>().notNull().default([]),
/** Atributos libres para fichas y filtros (`material: ceramic`). */
attributes: jsonb('attributes').$type<Record<string, string>>().notNull().default({}),
translations: jsonb('translations').$type<Record<string, ProductTranslation>>().notNull().default({}),
seoTitle: text('seo_title'),
seoDescription: text('seo_description'),
publishedAt: timestamp('published_at', { withTimezone: true, mode: 'date' }),
...timestamps,
},
(t) => [index('products_status_idx').on(t.status, t.publishedAt)],
);
export const productVariants = pgTable(
'product_variants',
{
id: primaryId('var'),
productId: text('product_id')
.notNull()
.references(() => products.id, { onDelete: 'cascade' }),
sku: text('sku').unique(),
/** `M / Red` (o vacío si el producto no tiene opciones). */
title: text('title').notNull().default(''),
options: jsonb('options').$type<Record<string, string>>().notNull().default({}),
priceAmount: integer('price_amount').notNull(),
/** Precio "antes" (tachado). Solo si es real: ver @core/discounts y @core/pricing (regla de 30 días UE). */
compareAtAmount: integer('compare_at_amount'),
/** Coste (para márgenes; nunca se muestra). */
costAmount: integer('cost_amount'),
currency: text('currency').notNull(),
stock: integer('stock').notNull().default(0),
trackStock: boolean('track_stock').notNull().default(true),
/** Vender sin stock (bajo pedido). */
allowBackorder: boolean('allow_backorder').notNull().default(false),
lowStockThreshold: integer('low_stock_threshold').notNull().default(3),
weightGrams: integer('weight_grams'),
position: integer('position').notNull().default(0),
active: boolean('active').notNull().default(true),
/** Media de la variante (p. ej. foto del color). */
mediaId: text('media_id'),
...timestamps,
},
(t) => [index('product_variants_product_idx').on(t.productId, t.position)],
);
export const productMedia = pgTable(
'product_media',
{
productId: text('product_id')
.notNull()
.references(() => products.id, { onDelete: 'cascade' }),
mediaId: text('media_id').notNull(),
position: integer('position').notNull().default(0),
},
(t) => [primaryKey({ columns: [t.productId, t.mediaId] })],
);
export const categories = pgTable('product_categories', {
id: primaryId('cat'),
slug: text('slug').notNull().unique(),
name: text('name').notNull(),
description: text('description'),
parentId: text('parent_id'),
position: integer('position').notNull().default(0),
translations: jsonb('translations').$type<Record<string, { name?: string; description?: string }>>().notNull().default({}),
...timestamps,
});
export const productCategories = pgTable(
'product_category_links',
{
productId: text('product_id')
.notNull()
.references(() => products.id, { onDelete: 'cascade' }),
categoryId: text('category_id')
.notNull()
.references(() => categories.id, { onDelete: 'cascade' }),
},
(t) => [primaryKey({ columns: [t.productId, t.categoryId] }), index('product_category_links_cat_idx').on(t.categoryId)],
);
/** Colecciones manuales ordenadas (portada, "novedades", "más vendidos"…). */
export const collections = pgTable('product_collections', {
id: primaryId('col'),
slug: text('slug').notNull().unique(),
name: text('name').notNull(),
description: text('description'),
...timestamps,
});
export const collectionProducts = pgTable(
'product_collection_items',
{
collectionId: text('collection_id')
.notNull()
.references(() => collections.id, { onDelete: 'cascade' }),
productId: text('product_id')
.notNull()
.references(() => products.id, { onDelete: 'cascade' }),
position: integer('position').notNull().default(0),
},
(t) => [primaryKey({ columns: [t.collectionId, t.productId] })],
);
export type Product = typeof products.$inferSelect;
export type Variant = typeof productVariants.$inferSelect;
export type Category = typeof categories.$inferSelect;
export type Collection = typeof collections.$inferSelect;
이 패키지는 MCP 서버를 선언하지 않습니다.
| 버전 | 커밋 | 게시일 | 검사 |
|---|---|---|---|
| 1.0.0 | 79d3468 | 4시간 전 | 검사 통과 |
- npm
- zod ^4.0.0
- 제안됨
- GenPM은 npm 명령을 제안하고, 동의한 경우에만 실행합니다.
- 검사
- 검사 통과 · 문제 0건
- 커밋
- v1.0.0 → 79d3468925acbde57d17a18a32e9d4bdefc28b5e · 가져온 뒤 검증됨
- 스크립트
- 없음. GenPM은 패키지 코드를 절대 실행하지 않습니다.
- 라이선스
- MIT
- 품질
- 100/100
- 인정된 라이선스충족
- AGENTS.md에 목적 설명충족
- AGENTS.md에 통합 단계충족
- AGENTS.md에 규칙 또는 금지 사항충족
- 테스트 포함충족
- 보안 검사 통과충족
- 최근 6개월 내 게시충족
- 인증된 게시자충족
- 요약과 키워드충족
- 신고
- 문제가 있나요?