@gravito/satellite-catalog 0.1.1

package/.dockerignore

@@ -0,0 +1,8 @@
+node_modules
+dist
+.git
+.env
+*.log
+.vscode
+.idea
+tests

package/.env.example

@@ -0,0 +1,19 @@
+# Application
+APP_NAME="catalog"
+APP_ENV=development
+APP_KEY=
+APP_DEBUG=true
+APP_URL=http://localhost:3000
+
+# Server
+PORT=3000
+
+# Database
+DB_CONNECTION=sqlite
+DB_DATABASE=database/database.sqlite
+
+# Cache
+CACHE_DRIVER=memory
+
+# Logging
+LOG_LEVEL=debug

package/ARCHITECTURE.md

@@ -0,0 +1,14 @@
+# catalog Satellite Architecture
+
+This satellite follows the Gravito Satellite Specification v1.0.
+
+## Design
+- **DDD**: Domain logic is separated from framework concerns.
+- **Dogfooding**: Uses official Gravito modules (@gravito/atlas, @gravito/stasis).
+- **Decoupled**: Inter-satellite communication happens via Contracts and Events.
+
+## Layers
+- **Domain**: Pure business rules.
+- **Application**: Orchestration of domain tasks.
+- **Infrastructure**: Implementation of persistence and external services.
+- **Interface**: HTTP and Event entry points.

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @gravito/satellite-catalog
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @gravito/atlas@1.0.1
+  - @gravito/core@1.0.0
+  - @gravito/enterprise@1.0.0
+  - @gravito/signal@1.0.0
+  - @gravito/stasis@1.0.0

package/Dockerfile

@@ -0,0 +1,25 @@
+FROM oven/bun:1.0 AS base
+WORKDIR /usr/src/app
+
+# Install dependencies
+FROM base AS install
+RUN mkdir -p /temp/dev
+COPY package.json bun.lockb /temp/dev/
+RUN cd /temp/dev && bun install --frozen-lockfile
+
+# Build application
+FROM base AS build
+COPY --from=install /temp/dev/node_modules node_modules
+COPY . .
+ENV NODE_ENV=production
+RUN bun run build
+
+# Final production image
+FROM base AS release
+COPY --from=build /usr/src/app/dist/bootstrap.js index.js
+COPY --from=build /usr/src/app/package.json .
+
+# Create a non-root user for security
+USER bun
+EXPOSE 3000/tcp
+ENTRYPOINT [ "bun", "run", "index.js" ]

package/README.md

@@ -0,0 +1,48 @@
+# 🛰️ Gravito Satellite: Catalog
+
+這是 Gravito Galaxy Architecture 中的核心商品目錄插件。它負責管理商品的靜態定義、規格（SKUs）以及無限層級的分類樹。
+
+## 🌟 核心功能
+
+- **📦 結構化商品模型**: 區分商品主體 (Product) 與 規格變體 (Variants/SKUs)。
+- **🌲 智慧型分類樹**: 使用路徑列 (Materialized Path) 實作，支援無限層級分類，且在移動分類時自動同步所有子孫路徑。
+- **🖼️ 媒體整合**: 完美整合 `@gravito/nebula`，自動將存儲 Key 解析為完整的 CDN/本地 URL。
+- **🌐 多語系支援**: 名稱與描述預設支援 JSON 格式的 i18n 儲存。
+- **🚀 高性能查詢**: 針對大數據量設計，利用索引路徑進行子分類商品的快速檢索。
+
+## 🛠️ API 接口
+
+| 方法 | 路徑 | 說明 |
+| :--- | :--- | :--- |
+| `GET` | `/api/catalog/products` | 獲取商品列表 (含 SKU) |
+| `GET` | `/api/catalog/products/:id` | 獲取單一商品詳情 |
+| `POST` | `/api/catalog/products` | 建立商品與多個 SKU (原子化) |
+| `GET` | `/api/catalog/categories` | 獲取完整的樹狀分類結構 |
+
+## 🏗️ 領域驅動設計 (DDD) 結構
+
+- **Domain**: 包含 `Category`, `Product`, `Variant` 實體與業務規則。
+- **Application**: 提供 `CreateProduct` 與 `UpdateCategory` (含路徑同步) UseCases。
+- **Infrastructure**: 基於 `Atlas` 的倉儲實現，支援事務保護。
+- **Interface**: 基於 `Photon` 的 RESTful 控制器。
+
+## ⚙️ 安裝與註冊
+
+在您的 `PlanetCore` 中註冊：
+
+```typescript
+import { CatalogServiceProvider } from '@gravito/satellite-catalog';
+
+await core.use(new CatalogServiceProvider());
+```
+
+## 🧪 驗證
+
+執行全系統校閱測試：
+```bash
+cd satellites/catalog
+bun tests/grand-review.ts
+```
+
+---
+*Created by Gravito Core Team.*

package/WHITEPAPER.md

@@ -0,0 +1,20 @@
+# Whitepaper: Gravito Catalog Satellite (Recursive Data Architecture)
+**Version:** 1.0.0 | **Author:** Gravito Engineering Team
+
+## 1. Abstract
+The Catalog Satellite provides a highly optimized structure for managing infinite product hierarchies and complex SKU relationships.
+
+## 2. Practical Application Scenarios
+
+### Case A: Global Department Store (Infinite Nesting)
+- **Problem**: A client needs a category structure like `Electronics > Audio > Headphones > Wireless`. Standard SQL joins would be slow.
+- **Solution**: Using the **Materialized Path** (`/1/5/23/42/`), we fetch the entire breadcrumb trail or all products in the "Audio" department with a single indexed string query.
+- **Result**: Sub-millisecond response times for deep navigation.
+
+### Case B: Mass Re-categorization
+- **Problem**: Moving 1,000 products from "Sale" to "Clearance" involves changing parent categories for large branches.
+- **Solution**: The `UpdateCategory` UseCase recursively recalculates and updates all descendant paths in a single atomic operation.
+- **Result**: Guaranteed tree integrity with no broken links.
+
+---
+*Gravito Framework: Precision in Data, Speed in Execution.*

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import { ServiceProvider, Container } from '@gravito/core';
+
+declare class CatalogServiceProvider extends ServiceProvider {
+    register(container: Container): void;
+    boot(): void;
+}
+
+export { CatalogServiceProvider };

package/dist/index.js

@@ -0,0 +1,321 @@
+// src/index.ts
+import { ServiceProvider } from "@gravito/core";
+
+// src/Application/UseCases/AdminListProducts.ts
+import { UseCase } from "@gravito/enterprise";
+var AdminListProducts = class extends UseCase {
+  constructor(repository) {
+    super();
+    this.repository = repository;
+  }
+  async execute() {
+    return await this.repository.findAll();
+  }
+};
+
+// src/Application/UseCases/RecoverStock.ts
+import { DB } from "@gravito/atlas";
+import { UseCase as UseCase2 } from "@gravito/enterprise";
+var RecoverStock = class extends UseCase2 {
+  async execute(input) {
+    const { variantId, quantity } = input;
+    const affected = await DB.table("product_variants").where("id", variantId).update({
+      stock: DB.raw("stock + ?", [quantity]),
+      version: DB.raw("version + 1"),
+      updated_at: /* @__PURE__ */ new Date()
+    });
+    if (affected === 0) {
+      throw new Error(`Variant [${variantId}] not found during stock recovery`);
+    }
+    console.log(`[Catalog] Stock recovered for variant ${variantId}: +${quantity}`);
+  }
+};
+
+// src/Infrastructure/Persistence/AtlasProductRepository.ts
+import { DB as DB2 } from "@gravito/atlas";
+
+// src/Domain/Entities/Product.ts
+import { Entity } from "@gravito/enterprise";
+var Variant = class extends Entity {
+  constructor(id, props) {
+    super(id);
+    this.props = props;
+  }
+  // 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 || {};
+  }
+  reduceStock(quantity) {
+    if (this.props.stock < quantity) {
+      throw new Error("Insufficient stock");
+    }
+    this.props.stock -= quantity;
+    this.props.updatedAt = /* @__PURE__ */ new Date();
+  }
+};
+var Product = class _Product extends Entity {
+  constructor(id, props) {
+    super(id);
+    this.props = props;
+  }
+  static create(id, name, slug) {
+    return new _Product(id, {
+      name,
+      slug,
+      status: "active",
+      variants: [],
+      categoryIds: [],
+      createdAt: /* @__PURE__ */ new Date(),
+      updatedAt: /* @__PURE__ */ new Date()
+    });
+  }
+  static reconstitute(id, props) {
+    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 || {};
+  }
+  setThumbnail(key) {
+    this.props.thumbnail = key;
+    this.props.updatedAt = /* @__PURE__ */ new Date();
+  }
+  addVariant(variant) {
+    this.props.variants.push(variant);
+    this.props.updatedAt = /* @__PURE__ */ new Date();
+  }
+  assignToCategory(categoryId) {
+    if (!this.props.categoryIds.includes(categoryId)) {
+      this.props.categoryIds.push(categoryId);
+      this.props.updatedAt = /* @__PURE__ */ new Date();
+    }
+  }
+};
+
+// src/Infrastructure/Persistence/AtlasProductRepository.ts
+var AtlasProductRepository = class {
+  productsTable = "products";
+  variantsTable = "product_variants";
+  pivotTable = "category_product";
+  async save(product) {
+    await DB2.transaction(async (db) => {
+      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);
+      }
+      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)
+        });
+      }
+      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) {
+    const row = await DB2.table(this.productsTable).where("id", id).first();
+    if (!row) {
+      return null;
+    }
+    const variantRows = await DB2.table(this.variantsTable).where("product_id", id).get();
+    const categoryRows = await DB2.table(this.pivotTable).where("product_id", id).get();
+    return this.mapToDomain(row, variantRows, categoryRows);
+  }
+  async findAll(_filters) {
+    const rows = await DB2.table(this.productsTable).get();
+    const products = [];
+    for (const row of rows) {
+      const variantRows = await DB2.table(this.variantsTable).where("product_id", row.id).get();
+      const categoryRows = await DB2.table(this.pivotTable).where("product_id", row.id).get();
+      products.push(this.mapToDomain(row, variantRows, categoryRows));
+    }
+    return products;
+  }
+  async delete(id) {
+    await DB2.transaction(async (db) => {
+      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();
+    });
+  }
+  mapToDomain(row, variantRows, categoryRows) {
+    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) : {}
+    });
+  }
+};
+
+// src/Interface/Http/Controllers/AdminProductController.ts
+var AdminProductController = class {
+  constructor(core) {
+    this.core = core;
+  }
+  /**
+   * GET /api/admin/v1/catalog/products
+   */
+  async index(ctx) {
+    try {
+      const useCase = this.core.container.make(
+        "catalog.usecase.adminListProducts"
+      );
+      const products = await useCase.execute();
+      return ctx.json(
+        products.map((p) => ({
+          id: p.id,
+          name: p.name,
+          price: p.props.price,
+          stock: p.props.stock,
+          status: p.props.status || "active"
+        }))
+      );
+    } catch (error) {
+      return ctx.json({ message: error.message }, 500);
+    }
+  }
+  /**
+   * PATCH /api/admin/v1/catalog/products/:id
+   */
+  async update(ctx) {
+    return ctx.json({ success: true });
+  }
+};
+
+// src/index.ts
+var CatalogServiceProvider = class extends ServiceProvider {
+  register(container) {
+    container.singleton("catalog.repository.product", () => new AtlasProductRepository());
+    container.singleton("catalog.stock.recover", () => new RecoverStock());
+    container.bind(
+      "catalog.usecase.adminListProducts",
+      () => new AdminListProducts(container.make("catalog.repository.product"))
+    );
+    container.singleton(
+      "catalog.controller.adminProduct",
+      () => new AdminProductController(this.core)
+    );
+  }
+  boot() {
+    const core = this.core;
+    if (!core) {
+      return;
+    }
+    core.logger.info("\u{1F6F0}\uFE0F Satellite Catalog is operational");
+    const adminProductCtrl = core.container.make(
+      "catalog.controller.adminProduct"
+    );
+    core.router.prefix("/api/admin/v1/catalog").group((router) => {
+      router.get("/products", (ctx) => adminProductCtrl.index(ctx));
+      router.patch("/products/:id", (ctx) => adminProductCtrl.update(ctx));
+    });
+    core.hooks.addAction(
+      "payment:refund:succeeded",
+      async (payload) => {
+        const recoverStock = core.container.make("catalog.stock.recover");
+        try {
+          for (const item of payload.items) {
+            await recoverStock.execute({
+              variantId: item.variantId,
+              quantity: item.quantity
+            });
+          }
+          core.logger.info(`[Catalog] Inventory closure completed for order: ${payload.orderId}`);
+        } catch (error) {
+          core.logger.error(`[Catalog] Failed to recover stock: ${error.message}`);
+        }
+      }
+    );
+  }
+};
+export {
+  CatalogServiceProvider
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@gravito/satellite-catalog",
+  "version": "0.1.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --external @gravito/atlas --external @gravito/enterprise --external @gravito/signal --external @gravito/stasis --external @gravito/core",
+    "test": "bun test",
+    "typecheck": "bun tsc -p tsconfig.json --noEmit --skipLibCheck"
+  },
+  "dependencies": {
+    "@gravito/atlas": "workspace:*",
+    "@gravito/enterprise": "workspace:*",
+    "@gravito/signal": "workspace:*",
+    "@gravito/stasis": "workspace:*",
+    "@gravito/core": "workspace:*"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gravito-framework/gravito.git",
+    "directory": "satellites/catalog"
+  }
+}

package/src/Application/DTOs/CategoryDTO.ts

@@ -0,0 +1,49 @@
+import type { Category } from '../../Domain/Entities/Category'
+
+export interface CategoryDTO {
+  id: string
+  parentId: string | null
+  path: string | null
+  name: Record<string, string>
+  slug: string
+  sortOrder: number
+  children?: CategoryDTO[] // For tree view
+}
+
+export class CategoryMapper {
+  static toDTO(category: Category): CategoryDTO {
+    return {
+      id: category.id,
+      parentId: category.parentId,
+      path: category.path,
+      name: category.name,
+      slug: category.slug,
+      sortOrder: category.sortOrder,
+    }
+  }
+
+  /**
+   * Helper to build a tree structure from a flat array of DTOs
+   */
+  static buildTree(dtos: CategoryDTO[]): CategoryDTO[] {
+    const map = new Map<string, CategoryDTO & { children: CategoryDTO[] }>()
+    const roots: CategoryDTO[] = []
+
+    // Initialize map
+    for (const dto of dtos) {
+      map.set(dto.id, { ...dto, children: [] })
+    }
+
+    // Link children to parents
+    for (const dto of dtos) {
+      const node = map.get(dto.id)!
+      if (dto.parentId && map.has(dto.parentId)) {
+        map.get(dto.parentId)?.children.push(node)
+      } else {
+        roots.push(node)
+      }
+    }
+
+    return roots.sort((a, b) => a.sortOrder - b.sortOrder)
+  }
+}

package/src/Application/DTOs/ProductDTO.ts

@@ -0,0 +1,74 @@
+import { app } from '@gravito/core'
+import type { Product, Variant } from '../../Domain/Entities/Product'
+
+export interface VariantDTO {
+  id: string
+  sku: string
+  name: string | null
+  price: number
+  compareAtPrice: number | null
+  stock: number
+  options: Record<string, string>
+}
+
+export interface ProductDTO {
+  id: string
+  name: Record<string, string>
+  slug: string
+  description?: string
+  brand?: string
+  status: string
+  thumbnailUrl?: string
+  variants: VariantDTO[]
+  categoryIds: string[]
+  createdAt: string
+}
+
+export class ProductMapper {
+  static toDTO(product: Product): ProductDTO {
+    let thumbnailUrl: string | undefined
+
+    if (product.thumbnail) {
+      try {
+        const storage = app().container.make('storage') as any
+        if (storage) {
+          thumbnailUrl = storage.getUrl(product.thumbnail)
+        }
+      } catch (_e) {
+        // Fallback to key if storage not available or core not booted
+        thumbnailUrl = `/storage/${product.thumbnail}`
+      }
+    }
+
+    return {
+      id: product.id,
+      name: product.name,
+      slug: product.slug,
+      // @ts-expect-error - access private props for mapping
+      description: product.props.description,
+      // @ts-expect-error
+      brand: product.props.brand,
+      // @ts-expect-error
+      status: product.props.status,
+      thumbnailUrl,
+      variants: product.variants.map((v) => this.variantToDTO(v)),
+      categoryIds: product.categoryIds,
+      // @ts-expect-error
+      createdAt: product.props.createdAt.toISOString(),
+    }
+  }
+
+  private static variantToDTO(variant: Variant): VariantDTO {
+    return {
+      id: variant.id,
+      sku: variant.sku,
+      // @ts-expect-error
+      name: variant.props.name,
+      price: variant.price,
+      // @ts-expect-error
+      compareAtPrice: variant.props.compareAtPrice,
+      stock: variant.stock,
+      options: variant.options,
+    }
+  }
+}

package/src/Application/UseCases/AdminListProducts.ts

@@ -0,0 +1,13 @@
+import { UseCase } from '@gravito/enterprise'
+import type { IProductRepository } from '../../Domain/Contracts/ICatalogRepository'
+import type { Product } from '../../Domain/Entities/Product'
+
+export class AdminListProducts extends UseCase<void, Product[]> {
+  constructor(private repository: IProductRepository) {
+    super()
+  }
+
+  async execute(): Promise<Product[]> {
+    return await this.repository.findAll()
+  }
+}