@gravito/satellite-invoice 0.1.4 → 0.2.0

package/tests/Application/Roles/InvoiceCancellerRole.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from 'bun:test'
+import {
+  DefaultInvoiceCanceller,
+  injectInvoiceCanceller,
+} from '../../../src/Application/Roles/InvoiceCancellerRole'
+import { Invoice } from '../../../src/Domain/Entities/Invoice'
+
+describe('InvoiceCancellerRole', () => {
+  it('應該驗證 ISSUED 狀態的發票可被取消', () => {
+    const canceller = new DefaultInvoiceCanceller()
+    const invoice = Invoice.create({
+      orderId: 'order-123',
+      invoiceNumber: 'GX-12345678',
+      amount: 1000,
+      tax: 50,
+      status: 'ISSUED',
+    })
+
+    const canCancel = canceller.validateCancellationEligibility(invoice)
+
+    expect(canCancel).toBe(true)
+  })
+
+  it('應該驗證 CANCELLED 狀態的發票不可被取消', () => {
+    const canceller = new DefaultInvoiceCanceller()
+    const invoice = Invoice.create({
+      orderId: 'order-123',
+      invoiceNumber: 'GX-12345678',
+      amount: 1000,
+      tax: 50,
+      status: 'ISSUED',
+    })
+    const cancelledInvoice = invoice.cancel()
+
+    const canCancel = canceller.validateCancellationEligibility(cancelledInvoice)
+
+    expect(canCancel).toBe(false)
+  })
+
+  it('應該記錄取消原因', () => {
+    const canceller = new DefaultInvoiceCanceller()
+    const record = canceller.recordCancellationReason(
+      'invoice-123',
+      'CUSTOMER_REQUEST',
+      'Customer changed mind'
+    )
+
+    expect(record.invoiceId).toBe('invoice-123')
+    expect(record.reason).toBe('CUSTOMER_REQUEST')
+    expect(record.notes).toBe('Customer changed mind')
+    expect(record.timestamp).toBeInstanceOf(Date)
+  })
+
+  it('應該支援各種取消原因', () => {
+    const canceller = new DefaultInvoiceCanceller()
+    const reasons = [
+      'CUSTOMER_REQUEST',
+      'PAYMENT_FAILED',
+      'ORDER_CANCELLED',
+      'DUPLICATE',
+      'OTHER',
+    ] as const
+
+    for (const reason of reasons) {
+      const record = canceller.recordCancellationReason('invoice-123', reason)
+      expect(record.reason).toBe(reason)
+    }
+  })
+
+  it('應該取得已記錄的取消記錄', () => {
+    const canceller = new DefaultInvoiceCanceller()
+    canceller.recordCancellationReason('invoice-123', 'CUSTOMER_REQUEST')
+
+    const record = (canceller as any).getCancellationRecord('invoice-123')
+
+    expect(record).toBeDefined()
+    expect(record.invoiceId).toBe('invoice-123')
+    expect(record.reason).toBe('CUSTOMER_REQUEST')
+  })
+
+  it('應該在沒有取消記錄時通知服務時拋出錯誤', async () => {
+    const canceller = new DefaultInvoiceCanceller()
+
+    try {
+      await canceller.notifyRelatedServices('invoice-123')
+      expect(true).toBe(false) // 應該拋出錯誤
+    } catch (error) {
+      expect((error as Error).message).toContain('No cancellation record found')
+    }
+  })
+
+  it('應該能在已記錄後通知相關服務', async () => {
+    const canceller = new DefaultInvoiceCanceller()
+    canceller.recordCancellationReason('invoice-123', 'CUSTOMER_REQUEST')
+
+    // 應該不拋出錯誤
+    await canceller.notifyRelatedServices('invoice-123')
+    expect(true).toBe(true)
+  })
+
+  it('應該能透過注入函式取得角色', () => {
+    const canceller = injectInvoiceCanceller()
+
+    expect(canceller).toBeDefined()
+    expect(canceller.validateCancellationEligibility).toBeDefined()
+    expect(canceller.recordCancellationReason).toBeDefined()
+    expect(canceller.notifyRelatedServices).toBeDefined()
+  })
+})

package/tests/Application/Roles/InvoiceIssuerRole.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'bun:test'
+import {
+  DefaultInvoiceIssuer,
+  injectInvoiceIssuer,
+} from '../../../src/Application/Roles/InvoiceIssuerRole'
+
+describe('InvoiceIssuerRole', () => {
+  it('應該生成有效的發票號碼', () => {
+    const issuer = new DefaultInvoiceIssuer()
+    const invoiceNumber = issuer.generateInvoiceNumber()
+
+    expect(invoiceNumber.value).toMatch(/^GX-\d{8}$/)
+  })
+
+  it('應該生成不同的發票號碼', () => {
+    const issuer = new DefaultInvoiceIssuer()
+    const number1 = issuer.generateInvoiceNumber()
+    const number2 = issuer.generateInvoiceNumber()
+
+    expect(number1.value).not.toBe(number2.value)
+  })
+
+  it('應該計算預設稅額（5%）', () => {
+    const issuer = new DefaultInvoiceIssuer()
+    const tax = issuer.calculateTax(1000)
+
+    expect(tax.value).toBe(50)
+    expect(tax.rate).toBe(0.05)
+  })
+
+  it('應該計算自訂稅率的稅額', () => {
+    const issuer = new DefaultInvoiceIssuer()
+    const tax = issuer.calculateTax(1000, 0.1)
+
+    expect(tax.value).toBe(100)
+    expect(tax.rate).toBe(0.1)
+  })
+
+  it('應該驗證有效的訂單', async () => {
+    const issuer = new DefaultInvoiceIssuer()
+    const result = await issuer.validateOrderForInvoicing('order-123')
+
+    expect(result).toBe(true)
+  })
+
+  it('應該拒絕無效的訂單 ID', async () => {
+    const issuer = new DefaultInvoiceIssuer()
+
+    const result1 = await issuer.validateOrderForInvoicing('')
+    const result2 = await issuer.validateOrderForInvoicing(null as any)
+    const result3 = await issuer.validateOrderForInvoicing(undefined as any)
+
+    expect(result1).toBe(false)
+    expect(result2).toBe(false)
+    expect(result3).toBe(false)
+  })
+
+  it('應該能透過注入函式取得角色', () => {
+    const issuer = injectInvoiceIssuer()
+
+    expect(issuer).toBeDefined()
+    expect(issuer.generateInvoiceNumber).toBeDefined()
+    expect(issuer.calculateTax).toBeDefined()
+    expect(issuer.validateOrderForInvoicing).toBeDefined()
+  })
+})

package/tests/Application/Roles/InvoiceTrackerRole.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, it } from 'bun:test'
+import {
+  DefaultInvoiceTracker,
+  injectInvoiceTracker,
+} from '../../../src/Application/Roles/InvoiceTrackerRole'
+import { Invoice } from '../../../src/Domain/Entities/Invoice'
+import { InvoiceNumber } from '../../../src/Domain/ValueObjects/InvoiceNumber'
+
+describe('InvoiceTrackerRole', () => {
+  it('應該追蹤現存的發票狀態', async () => {
+    const tracker = new DefaultInvoiceTracker()
+    const invoice = Invoice.create({
+      orderId: 'order-123',
+      invoiceNumber: 'GX-12345678',
+      amount: 1000,
+      tax: 50,
+      status: 'ISSUED',
+    })
+
+    tracker.trackInvoice(invoice)
+
+    const status = await tracker.trackInvoiceStatus(invoice.id)
+
+    expect(status).toBeDefined()
+    expect(status).toBe('ISSUED')
+  })
+
+  it('應該在發票不存在時返回 null', async () => {
+    const tracker = new DefaultInvoiceTracker()
+
+    const status = await tracker.trackInvoiceStatus('non-existent-id')
+
+    expect(status).toBeNull()
+  })
+
+  it('應該取得審計日誌', async () => {
+    const tracker = new DefaultInvoiceTracker()
+    const invoice = Invoice.create({
+      orderId: 'order-123',
+      invoiceNumber: 'GX-12345678',
+      amount: 1000,
+      tax: 50,
+      status: 'ISSUED',
+    })
+
+    tracker.trackInvoice(invoice)
+    tracker.recordAuditLog({
+      invoiceId: invoice.id,
+      action: 'CREATED',
+      timestamp: new Date(),
+      details: { amount: 1000 },
+    })
+
+    const logs = await tracker.auditTrail(invoice.id)
+
+    expect(logs.length).toBe(1)
+    expect(logs[0].action).toBe('CREATED')
+  })
+
+  it('應該在沒有日誌時返回空陣列', async () => {
+    const tracker = new DefaultInvoiceTracker()
+
+    const logs = await tracker.auditTrail('non-existent-id')
+
+    expect(logs).toEqual([])
+  })
+
+  it('應該生成報告', async () => {
+    const tracker = new DefaultInvoiceTracker()
+
+    // 建立多張發票
+    for (let i = 0; i < 3; i++) {
+      const invoice = Invoice.create({
+        orderId: `order-${i}`,
+        invoiceNumber: `GX-${String(i).padStart(8, '0')}`,
+        amount: 1000 * (i + 1),
+        tax: 50 * (i + 1),
+        status: 'ISSUED',
+      })
+      tracker.trackInvoice(invoice)
+    }
+
+    const now = new Date()
+    const startDate = new Date(now.getTime() - 24 * 60 * 60 * 1000) // 昨天
+    const endDate = new Date(now.getTime() + 24 * 60 * 60 * 1000) // 明天
+
+    const report = await tracker.generateReport(startDate, endDate)
+
+    expect(report.summary.total).toBe(3)
+    expect(report.summary.issued).toBe(3)
+    expect(report.summary.cancelled).toBe(0)
+    expect(report.summary.returned).toBe(0)
+    expect(report.summary.totalAmount).toBe(1000 + 2000 + 3000)
+    expect(report.invoices.length).toBe(3)
+  })
+
+  it('應該在日期範圍外篩選發票', async () => {
+    const tracker = new DefaultInvoiceTracker()
+    const invoice = Invoice.create({
+      orderId: 'order-123',
+      invoiceNumber: 'GX-12345678',
+      amount: 1000,
+      tax: 50,
+      status: 'ISSUED',
+    })
+    tracker.trackInvoice(invoice)
+
+    // 查詢過去時間範圍（發票在未來）
+    const pastStart = new Date('2020-01-01')
+    const pastEnd = new Date('2020-12-31')
+
+    const report = await tracker.generateReport(pastStart, pastEnd)
+
+    expect(report.summary.total).toBe(0)
+    expect(report.invoices.length).toBe(0)
+  })
+
+  it('應該能透過注入函式取得角色', () => {
+    const tracker = injectInvoiceTracker()
+
+    expect(tracker).toBeDefined()
+    expect(tracker.trackInvoiceStatus).toBeDefined()
+    expect(tracker.auditTrail).toBeDefined()
+    expect(tracker.generateReport).toBeDefined()
+  })
+})

package/tests/Application/UseCases/CancelInvoice.test.ts

@@ -0,0 +1,175 @@
+import { beforeEach, describe, expect, it } from 'bun:test'
+import { CancelInvoice } from '../../../src/Application/UseCases/CancelInvoice'
+import type { IInvoiceRepository } from '../../../src/Domain/Contracts/IInvoiceRepository'
+import { Invoice } from '../../../src/Domain/Entities/Invoice'
+import {
+  InvalidCancellationError,
+  InvoiceNotFoundError,
+} from '../../../src/Domain/Errors/InvoiceError'
+import { InvoiceNumber } from '../../../src/Domain/ValueObjects/InvoiceNumber'
+
+// Mock Repository
+class MockRepository implements IInvoiceRepository {
+  private invoices: Map<string, Invoice> = new Map()
+
+  async save(invoice: Invoice): Promise<void> {
+    this.invoices.set(invoice.id, invoice)
+  }
+
+  async findById(id: string): Promise<Invoice | null> {
+    return this.invoices.get(id) || null
+  }
+
+  async findByOrderId(orderId: string): Promise<Invoice | null> {
+    for (const invoice of this.invoices.values()) {
+      if (invoice.orderId === orderId) {
+        return invoice
+      }
+    }
+    return null
+  }
+
+  async findAll(): Promise<Invoice[]> {
+    return Array.from(this.invoices.values())
+  }
+
+  async findByInvoiceNumber(invoiceNumber: string): Promise<Invoice | null> {
+    for (const invoice of this.invoices.values()) {
+      if (invoice.invoiceNumber === invoiceNumber) {
+        return invoice
+      }
+    }
+    return null
+  }
+
+  async findByStatus(status: string): Promise<Invoice[]> {
+    return Array.from(this.invoices.values()).filter((inv) => inv.status === status)
+  }
+
+  async findByDateRange(startDate: Date, endDate: Date): Promise<Invoice[]> {
+    return Array.from(this.invoices.values()).filter(
+      (inv) => inv.createdAt >= startDate && inv.createdAt <= endDate
+    )
+  }
+}
+
+describe('CancelInvoice UseCase', () => {
+  let useCase: CancelInvoice
+  let repository: MockRepository
+
+  beforeEach(() => {
+    repository = new MockRepository()
+    useCase = new CancelInvoice(repository)
+  })
+
+  it('應該成功取消發票', async () => {
+    const invoice = Invoice.create(
+      {
+        orderId: 'order-123',
+        invoiceNumber: 'GX-12345678',
+        amount: 1000,
+        tax: 50,
+        status: 'ISSUED',
+      },
+      'inv-123'
+    )
+    await repository.save(invoice)
+
+    const result = await useCase.execute({
+      invoiceId: 'inv-123',
+      reason: 'CUSTOMER_REQUEST',
+      notes: 'Customer changed their mind',
+    })
+
+    expect(result.id).toBe('inv-123')
+    expect(result.previousStatus).toBe('ISSUED')
+    expect(result.newStatus).toBe('CANCELLED')
+  })
+
+  it('應該支援各種取消原因', async () => {
+    const reasons = [
+      'CUSTOMER_REQUEST',
+      'PAYMENT_FAILED',
+      'ORDER_CANCELLED',
+      'DUPLICATE',
+      'OTHER',
+    ] as const
+
+    for (const reason of reasons) {
+      const invoice = Invoice.create({
+        orderId: `order-${reason}`,
+        invoiceNumber: InvoiceNumber.generate().value,
+        amount: 1000,
+        tax: 50,
+        status: 'ISSUED',
+      })
+      await repository.save(invoice)
+
+      const result = await useCase.execute({
+        invoiceId: invoice.id,
+        reason,
+      })
+
+      expect(result.newStatus).toBe('CANCELLED')
+    }
+  })
+
+  it('應該在發票不存在時拋出錯誤', async () => {
+    try {
+      await useCase.execute({
+        invoiceId: 'non-existent',
+        reason: 'CUSTOMER_REQUEST',
+      })
+      expect(true).toBe(false) // 應該拋出錯誤
+    } catch (error) {
+      expect(error).toBeInstanceOf(InvoiceNotFoundError)
+    }
+  })
+
+  it('應該拒絕取消已取消的發票', async () => {
+    const invoice = Invoice.create(
+      {
+        orderId: 'order-123',
+        invoiceNumber: 'GX-12345678',
+        amount: 1000,
+        tax: 50,
+        status: 'ISSUED',
+      },
+      'inv-123'
+    )
+    const cancelledInvoice = invoice.cancel()
+    await repository.save(cancelledInvoice)
+
+    try {
+      await useCase.execute({
+        invoiceId: 'inv-123',
+        reason: 'CUSTOMER_REQUEST',
+      })
+      expect(true).toBe(false) // 應該拋出錯誤
+    } catch (error) {
+      expect(error).toBeInstanceOf(InvalidCancellationError)
+    }
+  })
+
+  it('應該更新發票狀態在 Repository 中', async () => {
+    const invoice = Invoice.create(
+      {
+        orderId: 'order-123',
+        invoiceNumber: 'GX-12345678',
+        amount: 1000,
+        tax: 50,
+        status: 'ISSUED',
+      },
+      'inv-123'
+    )
+    await repository.save(invoice)
+
+    await useCase.execute({
+      invoiceId: 'inv-123',
+      reason: 'CUSTOMER_REQUEST',
+    })
+
+    const updated = await repository.findById('inv-123')
+    expect(updated?.status).toBe('CANCELLED')
+  })
+})

package/tests/Application/UseCases/IssueInvoice.test.ts

@@ -0,0 +1,169 @@
+import { beforeEach, describe, expect, it } from 'bun:test'
+import { IssueInvoice } from '../../../src/Application/UseCases/IssueInvoice'
+import type { IInvoiceRepository } from '../../../src/Domain/Contracts/IInvoiceRepository'
+import type { Invoice } from '../../../src/Domain/Entities/Invoice'
+import { DuplicateInvoiceError, InvoiceError } from '../../../src/Domain/Errors/InvoiceError'
+
+// Mock Repository
+class MockRepository implements IInvoiceRepository {
+  private invoices: Map<string, Invoice> = new Map()
+
+  async save(invoice: Invoice): Promise<void> {
+    this.invoices.set(invoice.id, invoice)
+  }
+
+  async findById(id: string): Promise<Invoice | null> {
+    return this.invoices.get(id) || null
+  }
+
+  async findByOrderId(orderId: string): Promise<Invoice | null> {
+    for (const invoice of this.invoices.values()) {
+      if (invoice.orderId === orderId) {
+        return invoice
+      }
+    }
+    return null
+  }
+
+  async findAll(): Promise<Invoice[]> {
+    return Array.from(this.invoices.values())
+  }
+
+  async findByInvoiceNumber(invoiceNumber: string): Promise<Invoice | null> {
+    for (const invoice of this.invoices.values()) {
+      if (invoice.invoiceNumber === invoiceNumber) {
+        return invoice
+      }
+    }
+    return null
+  }
+
+  async findByStatus(status: string): Promise<Invoice[]> {
+    return Array.from(this.invoices.values()).filter((inv) => inv.status === status)
+  }
+
+  async findByDateRange(startDate: Date, endDate: Date): Promise<Invoice[]> {
+    return Array.from(this.invoices.values()).filter(
+      (inv) => inv.createdAt >= startDate && inv.createdAt <= endDate
+    )
+  }
+}
+
+describe('IssueInvoice UseCase (薄殼委派)', () => {
+  let useCase: IssueInvoice
+  let repository: MockRepository
+
+  beforeEach(() => {
+    repository = new MockRepository()
+    useCase = new IssueInvoice(repository)
+  })
+
+  it('應該成功開立發票', async () => {
+    const result = await useCase.execute({
+      orderId: 'order-123',
+      amount: 1000,
+    })
+
+    expect(result.id).toBeDefined()
+    expect(result.orderId).toBe('order-123')
+    expect(result.invoiceNumber).toMatch(/^GX-\d{8}$/)
+    expect(result.amount).toBe(1000)
+    expect(result.status).toBe('ISSUED')
+  })
+
+  it('應該帶著買方和運送商識別碼開立發票', async () => {
+    const result = await useCase.execute({
+      orderId: 'order-123',
+      amount: 1000,
+      buyerIdentifier: 'buyer-123',
+      carrierId: 'carrier-456',
+    })
+
+    expect(result.buyerIdentifier).toBe('buyer-123')
+    expect(result.carrierId).toBe('carrier-456')
+  })
+
+  it('應該保存發票到 Repository', async () => {
+    const result = await useCase.execute({
+      orderId: 'order-123',
+      amount: 1000,
+    })
+
+    const saved = await repository.findById(result.id)
+    expect(saved).toBeDefined()
+    expect(saved?.orderId).toBe('order-123')
+  })
+
+  it('應該拒絕重複的訂單 ID', async () => {
+    // 第一次開票成功
+    await useCase.execute({
+      orderId: 'order-123',
+      amount: 1000,
+    })
+
+    // 第二次應該失敗
+    try {
+      await useCase.execute({
+        orderId: 'order-123',
+        amount: 1000,
+      })
+      expect(true).toBe(false) // 應該拋出錯誤
+    } catch (error) {
+      expect(error).toBeInstanceOf(DuplicateInvoiceError)
+    }
+  })
+
+  it('應該在無效的訂單時拋出錯誤', async () => {
+    try {
+      await useCase.execute({
+        orderId: '',
+        amount: 1000,
+      })
+      expect(true).toBe(false) // 應該拋出錯誤
+    } catch (error) {
+      expect(error).toBeInstanceOf(InvoiceError)
+    }
+  })
+
+  it('應該計算正確的稅額（5%）', async () => {
+    const result = await useCase.execute({
+      orderId: 'order-123',
+      amount: 1000,
+    })
+
+    expect(result.tax).toBe(50)
+    expect(result.taxObject.rate).toBe(0.05)
+  })
+
+  it('應該生成不同的發票號碼', async () => {
+    const result1 = await useCase.execute({
+      orderId: 'order-1',
+      amount: 1000,
+    })
+
+    const result2 = await useCase.execute({
+      orderId: 'order-2',
+      amount: 1000,
+    })
+
+    expect(result1.invoiceNumber).not.toBe(result2.invoiceNumber)
+  })
+
+  it('應該通過 Context 委派進行完整流程', async () => {
+    const result = await useCase.execute({
+      orderId: 'order-123',
+      amount: 1000,
+      buyerIdentifier: 'buyer-123',
+    })
+
+    // 驗證委派流程正常工作
+    expect(result).toBeDefined()
+    expect(result.id).toBeDefined()
+    expect(result.invoiceNumber).toBeDefined()
+
+    // 驗證發票已保存
+    const saved = await repository.findById(result.id)
+    expect(saved).toBeDefined()
+    expect(saved?.buyerIdentifier).toBe('buyer-123')
+  })
+})