npm install @rytass/wms-base-nestjs-module

import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { WMSBaseModule } from '@rytass/wms-base-nestjs-module';

@Module({
  imports: [
    TypeOrmModule.forRoot({
      type: 'postgres',
      // ... database config
    }),
    WMSBaseModule.forRoot({
      allowNegativeStock: false, // 預設: false, 禁止負庫存
    }),
  ],
})
export class AppModule {}

import { WMSBaseModule, WMSBaseModuleAsyncOptions } from '@rytass/wms-base-nestjs-module';
import { ConfigService } from '@nestjs/config';

@Module({
  imports: [
    // useFactory 方式
    WMSBaseModule.forRootAsync({
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        allowNegativeStock: config.get('WMS_ALLOW_NEGATIVE_STOCK', false),
      }),
    }),

    // 或 useClass 方式（使用自訂 Factory）
    // WMSBaseModule.forRootAsync({
    //   useClass: WMSConfigFactory,
    // }),

    // 或 useExisting 方式（重用現有 Factory）
    // WMSBaseModule.forRootAsync({
    //   useExisting: ExistingWMSConfigFactory,
    // }),
  ],
})
export class AppModule {}

import { LocationEntity } from '@rytass/wms-base-nestjs-module';

// 基礎結構 - Table: 'locations'
@Entity('locations')
@TableInheritance({ column: { type: 'varchar', name: 'entityName' } })
@Tree('materialized-path')
class LocationEntity {
  @PrimaryColumn({ type: 'varchar' })
  id: string;

  @TreeChildren()
  children: LocationEntity[];

  @TreeParent()
  parent: LocationEntity;

  @CreateDateColumn()
  createdAt: Date;

  @UpdateDateColumn()
  updatedAt: Date;

  @DeleteDateColumn()
  deletedAt: Date | null;  // Soft delete
}

import { MaterialEntity } from '@rytass/wms-base-nestjs-module';

// Table: 'materials'
@Entity('materials')
@TableInheritance({ column: { type: 'varchar', name: 'entityName' } })
class MaterialEntity {
  @PrimaryColumn({ type: 'varchar' })
  id: string;

  @CreateDateColumn()
  createdAt: Date;

  @UpdateDateColumn()
  updatedAt: Date;

  @DeleteDateColumn()
  deletedAt: Date | null;  // Soft delete

  @OneToMany(() => BatchEntity, batch => batch.material)
  batches: Relation<BatchEntity[]>;

  @OneToMany(() => StockEntity, stock => stock.material)
  stocks: Relation<StockEntity[]>;
}

import { BatchEntity } from '@rytass/wms-base-nestjs-module';

// Table: 'batches'
// 複合主鍵: id + materialId
@Entity('batches')
class BatchEntity {
  @PrimaryColumn('varchar')
  id: string;

  @PrimaryColumn('varchar')
  materialId: string;

  @ManyToOne(() => MaterialEntity, material => material.batches)
  @JoinColumn({ name: 'materialId', referencedColumnName: 'id' })
  material: Relation<MaterialEntity>;

  @OneToMany(() => StockEntity, stock => stock.batch)
  stocks: Relation<StockEntity[]>;
}

import { StockEntity } from '@rytass/wms-base-nestjs-module';

// Table: 'stocks'
@Entity('stocks')
@TableInheritance({ column: { type: 'varchar', name: 'entityName' } })
class StockEntity {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @Column({ type: 'varchar' })
  materialId: string;

  @Column({ type: 'varchar' })
  batchId: string;

  @Column({ type: 'varchar' })
  locationId: string;

  @Column({ type: 'varchar' })
  orderId: string;

  @Column({ type: 'numeric' })
  quantity: number;     // 正數為入庫，負數為出庫

  @ManyToOne(() => MaterialEntity, material => material.stocks)
  @JoinColumn({ name: 'materialId', referencedColumnName: 'id' })
  material: Relation<MaterialEntity>;

  @ManyToOne(() => BatchEntity, batch => batch.stocks)
  @JoinColumn([
    { name: 'materialId', referencedColumnName: 'materialId' },
    { name: 'batchId', referencedColumnName: 'id' },
  ])
  batch: Relation<BatchEntity>;

  @ManyToOne(() => OrderEntity, order => order.stocks)
  @JoinColumn({ name: 'orderId', referencedColumnName: 'id' })
  order: Relation<OrderEntity>;

  @CreateDateColumn()
  createdAt: Date;
}

import { OrderEntity } from '@rytass/wms-base-nestjs-module';

// Table: 'orders'
@Entity('orders')
@TableInheritance({ column: { type: 'varchar', name: 'entityName' } })
class OrderEntity {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @OneToMany(() => StockEntity, stock => stock.order)
  stocks: Relation<StockEntity>[];
}

// WarehouseMapService 可直接 import
import { WarehouseMapService } from '@rytass/wms-base-nestjs-module';

// WarehouseMapEntity 需從原始碼路徑 import（若必要）

// Table: 'warehouse_maps'
@Entity('warehouse_maps')
class WarehouseMapEntity {
  @PrimaryColumn('varchar')  // 對應 locationId
  id: string;

  @Column({ type: 'jsonb' })
  mapData: MapData;

  @CreateDateColumn()
  createdAt: Date;

  @UpdateDateColumn()
  updatedAt: Date;
}

import { LocationService, LocationEntity } from '@rytass/wms-base-nestjs-module';

@Injectable()
export class WarehouseService {
  constructor(private readonly locationService: LocationService) {}

  // 建立儲位
  async createLocation() {
    // 建立根儲位
    const warehouse = await this.locationService.create({
      id: 'WAREHOUSE-A',
    });

    // 建立子儲位
    const zone = await this.locationService.create({
      id: 'ZONE-A1',
      parentId: 'WAREHOUSE-A',
    });

    return zone;
  }

  // 封存儲位 (Soft Delete)
  // 注意: 只有庫存為 0 的儲位才能封存
  async archiveLocation(id: string) {
    await this.locationService.archive(id);
    // 會連同所有子儲位一起封存
  }

  // 解除封存
  async unArchiveLocation(id: string) {
    const location = await this.locationService.unArchive(id);
    return location;
  }
}

import { MaterialService, MaterialEntity } from '@rytass/wms-base-nestjs-module';

@Injectable()
export class ProductService {
  constructor(private readonly materialService: MaterialService) {}

  // 建立物料
  async createMaterial() {
    const material = await this.materialService.create({
      id: 'SKU-001',
    });

    return material;
  }
}

import {
  StockService,
  StockFindDto,
  StockFindAllDto,
  StockSorter,
} from '@rytass/wms-base-nestjs-module';

@Injectable()
export class InventoryService {
  constructor(private readonly stockService: StockService) {}

  // 查詢庫存數量 (回傳加總數量)
  // find() 可選傳入 manager 參數供交易使用
  async getStockQuantity(locationId: string, materialId: string): Promise<number> {
    return this.stockService.find({
      locationIds: [locationId],
      materialIds: [materialId],
      exactLocationMatch: true, // 只查詢該儲位，不包含子儲位
    });
  }

  // 查詢儲位樹下的總庫存 (包含所有子儲位)
  async getTotalStock(locationId: string): Promise<number> {
    return this.stockService.find({
      locationIds: [locationId],
      // exactLocationMatch: false (預設) - 包含所有子儲位
    });
  }

  // 查詢庫存異動記錄
  async getTransactionLogs(options: StockFindAllDto) {
    return this.stockService.findTransactions({
      locationIds: ['WAREHOUSE-A'],
      materialIds: ['SKU-001'],
      batchIds: ['BATCH-001'],
      offset: 0,
      limit: 20,  // 最大 100
      sorter: StockSorter.CREATED_AT_DESC,
    });
    // 回傳: StockCollectionDto { transactionLogs, total, offset, limit }
  }
}

interface StockCollectionDto {
  transactionLogs: StockTransactionLogDto[];
  total: number;
  offset: number;
  limit: number;
}

// 泛型版本，排除關聯欄位
type StockTransactionLogDto<Stock extends StockEntity = StockEntity> = Omit<
  Stock,
  'material' | 'batch' | 'location' | 'order'
>;

// 實際包含欄位（以預設 StockEntity 為例）:
// { id, materialId, batchId, locationId, orderId, quantity, createdAt }
// 注意: 原始碼 Omit 了 'location'，但 StockEntity 實際上沒有 location relation
// （只有 locationId 欄位），這是防禦性設計

import {
  OrderService,
  OrderEntity,
  OrderCreateDto,
  BatchCreateDto,
} from '@rytass/wms-base-nestjs-module';
import { Entity, Column } from 'typeorm';

// 擴展訂單 Entity
@Entity('custom_orders')
export class CustomOrderEntity extends OrderEntity {
  @Column()
  orderNumber: string;

  @Column()
  type: 'INBOUND' | 'OUTBOUND';
}

@Injectable()
export class OrderManagementService {
  constructor(private readonly orderService: OrderService) {}

  // 建立入庫訂單
  async createInboundOrder() {
    const order = await this.orderService.createOrder(CustomOrderEntity, {
      order: {
        orderNumber: 'IN-2024-001',
        type: 'INBOUND',
      },
      batches: [
        {
          id: 'BATCH-001',
          materialId: 'SKU-001',
          locationId: 'ZONE-A1',
          quantity: 100, // 正數: 入庫
        },
      ],
    });

    return order;
  }

  // 建立出庫訂單
  async createOutboundOrder() {
    const order = await this.orderService.createOrder(CustomOrderEntity, {
      order: {
        orderNumber: 'OUT-2024-001',
        type: 'OUTBOUND',
      },
      batches: [
        {
          id: 'BATCH-001',
          materialId: 'SKU-001',
          locationId: 'ZONE-A1',
          quantity: -50, // 負數: 出庫
        },
      ],
    });

    return order;
    // 若 allowNegativeStock: false 且庫存不足，會拋出 StockQuantityNotEnoughError
  }

  // 檢查是否可建立庫存異動
  async canCreateStock(batch: BatchCreateDto): Promise<boolean> {
    return this.orderService.canCreateStock(batch);
  }
}

interface BatchCreateDto {
  id: string;
  materialId: string;
  locationId: string;
  quantity: number;
}

type OrderDto<O extends OrderEntity = OrderEntity> = DeepPartial<Omit<O, 'stocks'>>;

type OrderCreateDto<O extends OrderEntity = OrderEntity> = {
  order: OrderDto<O>;
  batches: BatchCreateDto[];
};

import { WarehouseMapService } from '@rytass/wms-base-nestjs-module';
// MapRangeType/MapRangeColor 可直接使用字串值或自行定義 enum

// 可自行定義 enum 或使用字串常數
enum MapRangeType {
  RECTANGLE = 'RECTANGLE',
  POLYGON = 'POLYGON',
}

enum MapRangeColor {
  RED = 'RED',
  YELLOW = 'YELLOW',
  GREEN = 'GREEN',
  BLUE = 'BLUE',
  BLACK = 'BLACK',
}

@Injectable()
export class MapService {
  constructor(private readonly warehouseMapService: WarehouseMapService) {}

  // 更新倉庫地圖
  async updateMap(locationId: string) {
    const map = await this.warehouseMapService.updateMap(
      locationId,
      // backgrounds: 背景圖片
      [
        {
          id: 'bg-1',
          filename: 'warehouse-floor.png',
          x: 0,
          y: 0,
          width: 1000,
          height: 800,
        },
      ],
      // ranges: 區域標記
      [
        // 矩形區域
        {
          id: 'zone-a1',
          type: MapRangeType.RECTANGLE,
          color: MapRangeColor.GREEN,
          x: 100,
          y: 100,
          width: 200,
          height: 150,
        },
        // 多邊形區域
        {
          id: 'zone-special',
          type: MapRangeType.POLYGON,
          color: MapRangeColor.YELLOW,
          points: [
            { x: 400, y: 100 },
            { x: 500, y: 100 },
            { x: 550, y: 200 },
            { x: 400, y: 200 },
          ],
        },
      ],
    );

    return map;
  }

  // 取得地圖資料
  async getMap(locationId: string) {
    return this.warehouseMapService.getMapById(locationId);
    // 若不存在回傳: { id, backgrounds: [], ranges: [] }
  }

  // 刪除地圖
  async deleteMap(locationId: string) {
    await this.warehouseMapService.deleteMapById(locationId);
  }
}

import {
  WMSBaseModule,
  LocationEntity,
  MaterialEntity,
  StockEntity,
  BatchEntity,
  OrderEntity,
} from '@rytass/wms-base-nestjs-module';
import { Entity, Column } from 'typeorm';

// 擴展儲位
@Entity('custom_locations')
export class CustomLocationEntity extends LocationEntity {
  @Column()
  name: string;

  @Column({ nullable: true })
  description: string;
}

// 擴展物料
@Entity('custom_materials')
export class CustomMaterialEntity extends MaterialEntity {
  @Column()
  name: string;

  @Column()
  sku: string;
}

// 模組設定
@Module({
  imports: [
    WMSBaseModule.forRoot({
      locationEntity: CustomLocationEntity,
      materialEntity: CustomMaterialEntity,
      stockEntity: StockEntity,  // 使用預設
      batchEntity: BatchEntity,  // 使用預設
      orderEntity: OrderEntity,  // 使用預設
      allowNegativeStock: false,
    }),
  ],
})
export class AppModule {}

interface MapData {
  id: string;
  backgrounds: MapBackground[];
  ranges: (MapRectangleRange | MapPolygonRange)[];
}

interface MapBackground {
  id: string;
  filename: string;
  x: number;
  y: number;
  height: number;
  width: number;
}

interface MapRange {
  id: string;
  type: MapRangeType;
  color: string;
}

interface MapRectangleRange extends MapRange {
  x: number;
  y: number;
  width: number;
  height: number;
}

interface MapPolygonRange extends MapRange {
  points: MapPolygonRangePoint[];
}

interface MapPolygonRangePoint {
  x: number;
  y: number;
}