@gravito/satellite-catalog 0.1.1

package/src/Application/UseCases/CreateProduct.ts

@@ -0,0 +1,70 @@
+import type { PlanetCore } from '@gravito/core'
+import { UseCase } from '@gravito/enterprise'
+import type { IProductRepository } from '../../Domain/Contracts/ICatalogRepository'
+import { Product, Variant } from '../../Domain/Entities/Product'
+import { type ProductDTO, ProductMapper } from '../DTOs/ProductDTO'
+
+export interface CreateProductInput {
+  name: Record<string, string>
+  slug: string
+  brand?: string
+  categoryIds?: string[]
+  variants: {
+    sku: string
+    name?: string
+    price: number
+    stock: number
+    options: Record<string, string>
+  }[]
+}
+
+export class CreateProduct extends UseCase<CreateProductInput, ProductDTO> {
+  constructor(
+    private repository: IProductRepository,
+    private core: PlanetCore
+  ) {
+    super()
+  }
+
+  async execute(input: CreateProductInput): Promise<ProductDTO> {
+    // 1. 建立 Product 主體
+    const product = Product.create(crypto.randomUUID(), input.name, input.slug)
+
+    // @ts-expect-error
+    product.props.brand = input.brand
+
+    // 2. 加入分類
+    if (input.categoryIds) {
+      input.categoryIds.forEach((cid) => {
+        product.assignToCategory(cid)
+      })
+    }
+
+    // 3. 建立變體 (SKUs)
+    input.variants.forEach((v) => {
+      const variant = new Variant(crypto.randomUUID(), {
+        productId: product.id,
+        sku: v.sku,
+        name: v.name || null,
+        price: v.price,
+        compareAtPrice: null,
+        stock: v.stock,
+        options: v.options,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      })
+      product.addVariant(variant)
+    })
+
+    // 4. 存入持久化層
+    await this.repository.save(product)
+
+    // 5. 觸發 Hook，讓外部系統同步 (如：Search Indexer)
+    await this.core.hooks.doAction('catalog:product-created', {
+      productId: product.id,
+      skuCount: product.variants.length,
+    })
+
+    return ProductMapper.toDTO(product)
+  }
+}

package/src/Application/UseCases/RecoverStock.ts

@@ -0,0 +1,32 @@
+import { DB } from '@gravito/atlas'
+import { UseCase } from '@gravito/enterprise'
+
+export interface RecoverStockInput {
+  variantId: string
+  quantity: number
+}
+
+/**
+ * RecoverStock - 安全回滾庫存 (支持 OCC)
+ * 用於訂單退貨、取消或超時未支付場景
+ */
+export class RecoverStock extends UseCase<RecoverStockInput, void> {
+  async execute(input: RecoverStockInput): Promise<void> {
+    const { variantId, quantity } = input
+
+    // 使用 SQL 原子操作增加庫存，並讓 version 自增，確保 OCC 一致性
+    const affected = await DB.table('product_variants')
+      .where('id', variantId)
+      .update({
+        stock: DB.raw('stock + ?', [quantity]),
+        version: DB.raw('version + 1'),
+        updated_at: new Date(),
+      })
+
+    if (affected === 0) {
+      throw new Error(`Variant [${variantId}] not found during stock recovery`)
+    }
+
+    console.log(`[Catalog] Stock recovered for variant ${variantId}: +${quantity}`)
+  }
+}

package/src/Application/UseCases/UpdateCategory.ts

@@ -0,0 +1,74 @@
+import type { PlanetCore } from '@gravito/core'
+import { UseCase } from '@gravito/enterprise'
+import type { ICategoryRepository } from '../../Domain/Contracts/ICatalogRepository'
+import { type CategoryDTO, CategoryMapper } from '../DTOs/CategoryDTO'
+
+export interface UpdateCategoryInput {
+  id: string
+  name?: Record<string, string>
+  parentId?: string | null
+}
+
+export class UpdateCategory extends UseCase<UpdateCategoryInput, CategoryDTO> {
+  constructor(
+    private repository: ICategoryRepository,
+    private core: PlanetCore
+  ) {
+    super()
+  }
+
+  async execute(input: UpdateCategoryInput): Promise<CategoryDTO> {
+    const category = await this.repository.findById(input.id)
+    if (!category) {
+      throw new Error('Category not found')
+    }
+
+    const oldPath = category.path
+    const isMoving = input.parentId !== undefined && input.parentId !== category.parentId
+
+    // 1. 更新基本屬性
+    if (input.name) {
+      // @ts-expect-error
+      category.props.name = input.name
+    }
+
+    // 2. 處理移動邏輯 (關鍵！)
+    if (isMoving) {
+      category.moveTo(input.parentId!)
+
+      // 獲取新父節點的路徑
+      const newParent = input.parentId ? await this.repository.findById(input.parentId) : null
+      const newPath = newParent ? `${newParent.path}/${category.slug}` : category.slug
+
+      // 3. 同步更新所有子孫路徑 (必須在更新自己之前，使用舊路徑查找)
+      if (oldPath) {
+        const descendants = await this.repository.findByPathPrefix(oldPath)
+        console.log(`[Debug] 找到子孫數量: ${descendants.length} (使用前綴: ${oldPath})`)
+        for (const desc of descendants) {
+          if (desc.id === category.id) {
+            continue
+          }
+
+          // 確保只替換開頭的路徑部分
+          const subPath = desc.path?.substring(oldPath.length)
+          // @ts-expect-error
+          desc.props.path = newPath + subPath
+          await this.repository.save(desc)
+        }
+      }
+
+      // 更新自己
+      // @ts-expect-error
+      category.props.path = newPath
+    }
+
+    await this.repository.save(category)
+
+    await this.core.hooks.doAction('catalog:category-updated', {
+      categoryId: category.id,
+      moved: isMoving,
+    })
+
+    return CategoryMapper.toDTO(category)
+  }
+}

package/src/Domain/Contracts/ICatalogRepository.ts

@@ -0,0 +1,19 @@
+import type { Category } from '../Entities/Category'
+import type { Product } from '../Entities/Product'
+
+export interface ICategoryRepository {
+  save(category: Category): Promise<void>
+  findById(id: string): Promise<Category | null>
+  findAll(): Promise<Category[]>
+  findByParentId(parentId: string | null): Promise<Category[]>
+  /** 獲取某路徑下的所有子分類 (用於同步更新) */
+  findByPathPrefix(path: string): Promise<Category[]>
+  delete(id: string): Promise<void>
+}
+
+export interface IProductRepository {
+  save(product: Product): Promise<void>
+  findById(id: string): Promise<Product | null>
+  findAll(filters?: any): Promise<Product[]>
+  delete(id: string): Promise<void>
+}

package/src/Domain/Entities/Category.ts

@@ -0,0 +1,83 @@
+import { Entity } from '@gravito/enterprise'
+
+export interface CategoryProps {
+  parentId: string | null
+  path: string | null
+  name: Record<string, string> // i18n
+  slug: string
+  description?: string
+  sortOrder: number
+  createdAt: Date
+  updatedAt: Date
+  metadata?: Record<string, any>
+}
+
+export class Category extends Entity<string> {
+  private constructor(
+    id: string,
+    private props: CategoryProps
+  ) {
+    super(id)
+  }
+
+  static create(
+    id: string,
+    name: Record<string, string>,
+    slug: string,
+    parentId: string | null = null
+  ): Category {
+    return new Category(id, {
+      parentId,
+      path: null, // Will be computed by repository/service
+      name,
+      slug,
+      sortOrder: 0,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    })
+  }
+
+  static reconstitute(id: string, props: CategoryProps): Category {
+    return new Category(id, props)
+  }
+
+  // Getters
+  get parentId() {
+    return this.props.parentId
+  }
+  get path() {
+    return this.props.path
+  }
+  get name() {
+    return this.props.name
+  }
+  get slug() {
+    return this.props.slug
+  }
+  get sortOrder() {
+    return this.props.sortOrder
+  }
+  get metadata() {
+    return this.props.metadata || {}
+  }
+
+  /**
+   * Update the path based on parent's path
+   */
+  public updatePath(parentPath: string | null): void {
+    if (parentPath) {
+      this.props.path = `${parentPath}/${this.props.slug}`
+    } else {
+      this.props.path = this.props.slug
+    }
+    this.props.updatedAt = new Date()
+  }
+
+  /**
+   * Change the parent category
+   */
+  public moveTo(newParentId: string | null): void {
+    this.props.parentId = newParentId
+    this.props.updatedAt = new Date()
+  }
+}

package/src/Domain/Entities/Product.ts

@@ -0,0 +1,124 @@
+import { Entity } from '@gravito/enterprise'
+
+export interface VariantProps {
+  productId: string
+  sku: string
+  name: string | null
+  price: number
+  compareAtPrice: number | null
+  stock: number
+  options: Record<string, string> // e.g., {"color": "Red"}
+  createdAt: Date
+  updatedAt: Date
+  metadata?: Record<string, any>
+}
+
+export class Variant extends Entity<string> {
+  constructor(
+    id: string,
+    private props: VariantProps
+  ) {
+    super(id)
+  }
+
+  // Getters
+  get sku() {
+    return this.props.sku
+  }
+  get price() {
+    return this.props.price
+  }
+  get stock() {
+    return this.props.stock
+  }
+  get options() {
+    return this.props.options
+  }
+  get metadata() {
+    return this.props.metadata || {}
+  }
+
+  public reduceStock(quantity: number): void {
+    if (this.props.stock < quantity) {
+      throw new Error('Insufficient stock')
+    }
+    this.props.stock -= quantity
+    this.props.updatedAt = new Date()
+  }
+}
+
+export interface ProductProps {
+  name: Record<string, string> // i18n
+  slug: string
+  description?: string
+  brand?: string
+  status: 'active' | 'draft' | 'archived'
+  thumbnail?: string // Storage key
+  variants: Variant[]
+  categoryIds: string[]
+  createdAt: Date
+  updatedAt: Date
+  metadata?: Record<string, any>
+}
+
+export class Product extends Entity<string> {
+  private constructor(
+    id: string,
+    private props: ProductProps
+  ) {
+    super(id)
+  }
+
+  static create(id: string, name: Record<string, string>, slug: string): Product {
+    return new Product(id, {
+      name,
+      slug,
+      status: 'active',
+      variants: [],
+      categoryIds: [],
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    })
+  }
+
+  static reconstitute(id: string, props: ProductProps): Product {
+    return new Product(id, props)
+  }
+
+  // Getters
+  get name() {
+    return this.props.name
+  }
+  get slug() {
+    return this.props.slug
+  }
+  get thumbnail() {
+    return this.props.thumbnail
+  }
+  get variants() {
+    return this.props.variants
+  }
+  get categoryIds() {
+    return this.props.categoryIds
+  }
+  get metadata() {
+    return this.props.metadata || {}
+  }
+
+  public setThumbnail(key: string): void {
+    this.props.thumbnail = key
+    this.props.updatedAt = new Date()
+  }
+
+  public addVariant(variant: Variant): void {
+    this.props.variants.push(variant)
+    this.props.updatedAt = new Date()
+  }
+
+  public assignToCategory(categoryId: string): void {
+    if (!this.props.categoryIds.includes(categoryId)) {
+      this.props.categoryIds.push(categoryId)
+      this.props.updatedAt = new Date()
+    }
+  }
+}

package/src/Infrastructure/Persistence/AtlasCategoryRepository.ts

@@ -0,0 +1,77 @@
+import { DB } from '@gravito/atlas'
+import type { ICategoryRepository } from '../../Domain/Contracts/ICatalogRepository'
+import { Category } from '../../Domain/Entities/Category'
+
+export class AtlasCategoryRepository implements ICategoryRepository {
+  private table = 'categories'
+
+  async save(category: Category): Promise<void> {
+    const data = {
+      id: category.id,
+      parent_id: category.parentId,
+      path: category.path,
+      name: JSON.stringify(category.name),
+      slug: category.slug,
+      sort_order: category.sortOrder,
+      // @ts-expect-error
+      description: category.props.description || null,
+      // @ts-expect-error
+      created_at: category.props.createdAt,
+      // @ts-expect-error
+      updated_at: category.props.updatedAt,
+      metadata: JSON.stringify(category.metadata),
+    }
+
+    const exists = await DB.table(this.table).where('id', category.id).first()
+    if (exists) {
+      await DB.table(this.table).where('id', category.id).update(data)
+    } else {
+      await DB.table(this.table).insert(data)
+    }
+  }
+
+  async findById(id: string): Promise<Category | null> {
+    const row = await DB.table(this.table).where('id', id).first()
+    return row ? this.mapToDomain(row) : null
+  }
+
+  async findAll(): Promise<Category[]> {
+    const rows = await DB.table(this.table).orderBy('sort_order', 'asc').get()
+    return rows.map((row: any) => this.mapToDomain(row))
+  }
+
+  async findByParentId(parentId: string | null): Promise<Category[]> {
+    const query = DB.table(this.table)
+    if (parentId === null) {
+      query.whereNull('parent_id')
+    } else {
+      query.where('parent_id', parentId)
+    }
+    const rows = await query.orderBy('sort_order', 'asc').get()
+    return rows.map((row: any) => this.mapToDomain(row))
+  }
+
+  async findByPathPrefix(path: string): Promise<Category[]> {
+    // 獲取該路徑下的所有後代
+    const rows = await DB.table(this.table).where('path', 'like', `${path}/%`).get()
+    return rows.map((row: any) => this.mapToDomain(row))
+  }
+
+  async delete(id: string): Promise<void> {
+    await DB.table(this.table).where('id', id).delete()
+  }
+
+  private mapToDomain(row: any): Category {
+    return Category.reconstitute(row.id, {
+      parentId: row.parent_id,
+      path: row.path,
+      name: JSON.parse(row.name),
+      slug: row.slug,
+      description: row.description,
+      sortOrder: row.sort_order,
+      createdAt: new Date(row.created_at),
+      updatedAt: new Date(row.updated_at || row.created_at),
+      metadata: row.metadata ? JSON.parse(row.metadata) : {},
+    })
+  }
+}

package/src/Infrastructure/Persistence/AtlasProductRepository.ts

@@ -0,0 +1,136 @@
+import type { ConnectionContract } from '@gravito/atlas'
+import { DB } from '@gravito/atlas'
+import type { IProductRepository } from '../../Domain/Contracts/ICatalogRepository'
+import { Product, Variant } from '../../Domain/Entities/Product'
+
+export class AtlasProductRepository implements IProductRepository {
+  private productsTable = 'products'
+  private variantsTable = 'product_variants'
+  private pivotTable = 'category_product'
+
+  async save(product: Product): Promise<void> {
+    await DB.transaction(async (db: ConnectionContract) => {
+      // 1. 保存商品主體
+      const productData = {
+        id: product.id,
+        name: JSON.stringify(product.name),
+        slug: product.slug,
+        // @ts-expect-error
+        description: product.props.description || null,
+        // @ts-expect-error
+        brand: product.props.brand || null,
+        // @ts-expect-error
+        status: product.props.status,
+        thumbnail: product.thumbnail || null,
+        // @ts-expect-error
+        created_at: product.props.createdAt,
+        // @ts-expect-error
+        updated_at: product.props.updatedAt,
+        metadata: JSON.stringify(product.metadata),
+      }
+
+      const exists = await db.table(this.productsTable).where('id', product.id).first()
+      if (exists) {
+        await db.table(this.productsTable).where('id', product.id).update(productData)
+      } else {
+        await db.table(this.productsTable).insert(productData)
+      }
+
+      // 2. 同步變體 (簡單起見，先刪除舊的再插入新的，或實作 upsert)
+      await db.table(this.variantsTable).where('product_id', product.id).delete()
+      for (const variant of product.variants) {
+        await db.table(this.variantsTable).insert({
+          id: variant.id,
+          product_id: product.id,
+          sku: variant.sku,
+          // @ts-expect-error
+          name: variant.props.name,
+          price: variant.price,
+          // @ts-expect-error
+          compare_at_price: variant.props.compareAtPrice,
+          stock: variant.stock,
+          options: JSON.stringify(variant.options),
+          // @ts-expect-error
+          created_at: variant.props.createdAt,
+          // @ts-expect-error
+          updated_at: variant.props.updatedAt,
+          metadata: JSON.stringify(variant.metadata),
+        })
+      }
+
+      // 3. 同步分類關聯
+      await db.table(this.pivotTable).where('product_id', product.id).delete()
+      for (const categoryId of product.categoryIds) {
+        await db.table(this.pivotTable).insert({
+          product_id: product.id,
+          category_id: categoryId,
+        })
+      }
+    })
+  }
+
+  async findById(id: string): Promise<Product | null> {
+    const row = await DB.table(this.productsTable).where('id', id).first()
+    if (!row) {
+      return null
+    }
+
+    const variantRows = await DB.table(this.variantsTable).where('product_id', id).get()
+    const categoryRows = await DB.table(this.pivotTable).where('product_id', id).get()
+
+    return this.mapToDomain(row, variantRows, categoryRows)
+  }
+
+  async findAll(_filters?: any): Promise<Product[]> {
+    const rows = await DB.table(this.productsTable).get()
+    const products: Product[] = []
+
+    for (const row of rows) {
+      const variantRows = await DB.table(this.variantsTable).where('product_id', row.id).get()
+      const categoryRows = await DB.table(this.pivotTable).where('product_id', row.id).get()
+      products.push(this.mapToDomain(row, variantRows, categoryRows))
+    }
+
+    return products
+  }
+
+  async delete(id: string): Promise<void> {
+    await DB.transaction(async (db: ConnectionContract) => {
+      await db.table(this.pivotTable).where('product_id', id).delete()
+      await db.table(this.variantsTable).where('product_id', id).delete()
+      await db.table(this.productsTable).where('id', id).delete()
+    })
+  }
+
+  private mapToDomain(row: any, variantRows: any[], categoryRows: any[]): Product {
+    const variants = variantRows.map(
+      (v) =>
+        new Variant(v.id, {
+          productId: v.product_id,
+          sku: v.sku,
+          name: v.name,
+          price: v.price,
+          compareAtPrice: v.compare_at_price,
+          stock: v.stock,
+          options: JSON.parse(v.options),
+          createdAt: new Date(v.created_at),
+          updatedAt: new Date(v.updated_at || v.created_at),
+          metadata: v.metadata ? JSON.parse(v.metadata) : {},
+        })
+    )
+
+    return Product.reconstitute(row.id, {
+      name: JSON.parse(row.name),
+      slug: row.slug,
+      description: row.description,
+      brand: row.brand,
+      status: row.status,
+      thumbnail: row.thumbnail,
+      variants,
+      categoryIds: categoryRows.map((c) => c.category_id),
+      createdAt: new Date(row.created_at),
+      updatedAt: new Date(row.updated_at || row.created_at),
+      metadata: row.metadata ? JSON.parse(row.metadata) : {},
+    })
+  }
+}

package/src/Infrastructure/Persistence/Migrations/20250101_create_catalog_tables.ts

@@ -0,0 +1,64 @@
+import { type Blueprint, Schema } from '@gravito/atlas'
+
+/**
+ * Migration to create Catalog tables: categories, products, and variants.
+ */
+export default {
+  async up() {
+    // 1. Categories Table (Nested Set / Path Pattern)
+    await Schema.create('categories', (table: Blueprint) => {
+      table.string('id').primary()
+      table.string('parent_id').nullable()
+      table.string('path').nullable() // e.g., "electronics/computers/laptops"
+      table.string('name') // Unified i18n JSON
+      table.string('slug').unique()
+      table.text('description').nullable()
+      table.integer('sort_order').default(0)
+      table.timestamp('created_at').default('CURRENT_TIMESTAMP')
+      table.timestamp('updated_at').nullable()
+      table.text('metadata').nullable()
+    })
+
+    // 2. Products Table
+    await Schema.create('products', (table: Blueprint) => {
+      table.string('id').primary()
+      table.string('name')
+      table.string('slug').unique()
+      table.text('description').nullable()
+      table.string('brand').nullable()
+      table.string('status').default('active') // active, draft, archived
+      table.string('thumbnail').nullable()
+      table.timestamp('created_at').default('CURRENT_TIMESTAMP')
+      table.timestamp('updated_at').nullable()
+      table.text('metadata').nullable()
+    })
+
+    // 3. Product Variants (SKUs)
+    await Schema.create('product_variants', (table: Blueprint) => {
+      table.string('id').primary()
+      table.string('product_id')
+      table.string('sku').unique()
+      table.string('name').nullable() // Optional variant specific name
+      table.decimal('price', 15, 2)
+      table.decimal('compare_at_price', 15, 2).nullable() // Original price for sales
+      table.integer('stock').default(0)
+      table.text('options').nullable() // e.g., {"color": "Blue", "size": "XL"}
+      table.timestamp('created_at').default('CURRENT_TIMESTAMP')
+      table.timestamp('updated_at').nullable()
+      table.text('metadata').nullable()
+    })
+
+    // 4. Pivot Table: Product belongs to many Categories
+    await Schema.create('category_product', (table: Blueprint) => {
+      table.string('category_id').primary()
+      table.string('product_id').primary()
+    })
+  },
+
+  async down() {
+    await Schema.dropIfExists('category_product')
+    await Schema.dropIfExists('product_variants')
+    await Schema.dropIfExists('products')
+    await Schema.dropIfExists('categories')
+  },
+}