@gravito/satellite-invoice 0.1.5 → 0.2.0

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@gravito/satellite-invoice",
-  "version": "0.1.5",
+  "sideEffects": false,
+  "version": "0.2.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean --external @gravito/enterprise --external @gravito/atlas --external @gravito/core",
+    "build": "tsup src/index.ts --format esm --clean --external @gravito/enterprise --external @gravito/atlas --external @gravito/core",
+    "build:dts": "tsup src/index.ts --format esm --dts --clean --external @gravito/enterprise --external @gravito/atlas --external @gravito/core",
     "typecheck": "bun tsc -p tsconfig.json --noEmit --skipLibCheck"
   },
   "dependencies": {

package/package.json.bak

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

package/src/Application/Contexts/InvoiceAuditContext.ts

@@ -0,0 +1,96 @@
+import type { IInvoiceRepository } from '../../Domain/Contracts/IInvoiceRepository'
+import { InvoiceNotFoundError } from '../../Domain/Errors/InvoiceError'
+import type { InvoiceTrackerRole } from '../Roles/InvoiceTrackerRole'
+
+export interface QueryStatusInput {
+  invoiceId: string
+}
+
+export interface ReportInput {
+  startDate: Date
+  endDate: Date
+}
+
+export interface AuditTrailOutput {
+  invoiceId: string
+  logs: Array<{
+    action: string
+    timestamp: Date
+    details?: Record<string, any>
+  }>
+}
+
+/**
+ * 發票審計上下文 (DCI)
+ * 編排發票查詢和報告的流程
+ */
+export class InvoiceAuditContext {
+  constructor(
+    private repository: IInvoiceRepository,
+    private tracker: InvoiceTrackerRole
+  ) {}
+
+  async queryStatus(input: QueryStatusInput) {
+    const invoice = await this.repository.findById(input.invoiceId)
+    if (!invoice) {
+      throw new InvoiceNotFoundError(input.invoiceId)
+    }
+
+    await this.tracker.trackStatus(invoice)
+
+    return {
+      id: invoice.id,
+      invoiceNumber: invoice.invoiceNumberObject.value,
+      orderId: invoice.orderId,
+      status: invoice.statusObject.value,
+      amount: invoice.amountObject.value,
+      createdAt: invoice.createdAt,
+    }
+  }
+
+  async generateReport(input: ReportInput) {
+    const invoices = await this.repository.findByDateRange(input.startDate, input.endDate)
+
+    // 追蹤這些發票以供審計使用
+    for (const invoice of invoices) {
+      await this.tracker.trackStatus(invoice)
+    }
+
+    return {
+      period: { startDate: input.startDate, endDate: input.endDate },
+      summary: {
+        total: invoices.length,
+        issued: invoices.filter((inv) => inv.statusObject.isIssued()).length,
+        cancelled: invoices.filter((inv) => inv.statusObject.isCancelled()).length,
+        returned: invoices.filter((inv) => inv.statusObject.isReturned()).length,
+        totalAmount: invoices.reduce((sum: number, inv) => sum + inv.amountObject.value, 0),
+      },
+      invoices: invoices.map((inv) => ({
+        id: inv.id,
+        number: inv.invoiceNumberObject.value,
+        orderId: inv.orderId,
+        amount: inv.amountObject.value,
+        status: inv.statusObject.value,
+        createdAt: inv.createdAt,
+      })),
+    }
+  }
+
+  async getAuditTrail(input: { invoiceId: string }): Promise<AuditTrailOutput> {
+    const invoice = await this.repository.findById(input.invoiceId)
+    if (!invoice) {
+      throw new InvoiceNotFoundError(input.invoiceId)
+    }
+
+    const logs = await this.tracker.auditTrail(input.invoiceId)
+
+    return {
+      invoiceId: input.invoiceId,
+      logs: logs.map((log) => ({
+        action: log.action,
+        timestamp: log.timestamp,
+        details: log.details,
+      })),
+    }
+  }
+}

package/src/Application/Contexts/InvoiceCancellationContext.ts

@@ -0,0 +1,60 @@
+import type { IInvoiceRepository } from '../../Domain/Contracts/IInvoiceRepository'
+import { InvalidCancellationError, InvoiceNotFoundError } from '../../Domain/Errors/InvoiceError'
+import type { CancellationReason, InvoiceCancellerRole } from '../Roles/InvoiceCancellerRole'
+
+export interface CancelInvoiceInput {
+  invoiceId: string
+  reason: CancellationReason
+  notes?: string
+}
+
+export interface CancelInvoiceOutput {
+  id: string
+  invoiceNumber: string
+  previousStatus: string
+  newStatus: string
+  cancelledAt: Date
+}
+
+/**
+ * 發票取消上下文 (DCI)
+ * 編排發票取消的完整流程
+ */
+export class InvoiceCancellationContext {
+  constructor(
+    private repository: IInvoiceRepository,
+    private canceller: InvoiceCancellerRole
+  ) {}
+
+  async orchestrate(input: CancelInvoiceInput): Promise<CancelInvoiceOutput> {
+    // 1. 查詢發票
+    const invoice = await this.repository.findById(input.invoiceId)
+    if (!invoice) {
+      throw new InvoiceNotFoundError(input.invoiceId)
+    }
+
+    // 2. 驗證是否可取消
+    if (!invoice.statusObject.isIssued()) {
+      throw new InvalidCancellationError(`Cannot cancel ${invoice.statusObject.value} invoice`)
+    }
+
+    // 3. 執行取消
+    const cancelled = await this.canceller.cancel({
+      invoice,
+      reason: input.reason,
+      notes: input.notes,
+    })
+
+    // 4. 保存
+    await this.repository.save(cancelled)
+
+    // 5. 返回結果
+    return {
+      id: cancelled.id,
+      invoiceNumber: cancelled.invoiceNumberObject.value,
+      previousStatus: 'ISSUED',
+      newStatus: cancelled.statusObject.value,
+      cancelledAt: new Date(),
+    }
+  }
+}

package/src/Application/Contexts/InvoiceIssuanceContext.ts

@@ -0,0 +1,42 @@
+import type { IInvoiceRepository } from '../../Domain/Contracts/IInvoiceRepository'
+import type { Invoice } from '../../Domain/Entities/Invoice'
+import { DuplicateInvoiceError } from '../../Domain/Errors/InvoiceError'
+import type { InvoiceIssuerRole } from '../Roles/InvoiceIssuerRole'
+
+export interface IssueInvoiceInput {
+  orderId: string
+  amount: number
+  currency?: string
+  buyerIdentifier?: string
+  carrierId?: string
+}
+
+/**
+ * 發票開立上下文 (DCI)
+ * 編排發票開立的完整流程
+ */
+export class InvoiceIssuanceContext {
+  constructor(
+    private repository: IInvoiceRepository,
+    private issuer: InvoiceIssuerRole
+  ) {}
+
+  async orchestrate(input: IssueInvoiceInput): Promise<Invoice> {
+    // 1. 檢查訂單是否已有發票
+    const existing = await this.repository.findByOrderId(input.orderId)
+    if (existing) {
+      throw new DuplicateInvoiceError(input.orderId)
+    }
+
+    // 2. 生成新發票
+    const invoice = await this.issuer.issueInvoice({
+      ...input,
+      currency: input.currency ?? 'TWD',
+    })
+
+    // 3. 保存發票
+    await this.repository.save(invoice)
+
+    return invoice
+  }
+}

package/src/Application/Roles/InvoiceCancellerRole.ts

@@ -0,0 +1,97 @@
+import type { Invoice } from '../../Domain/Entities/Invoice'
+
+export type CancellationReason =
+  | 'CUSTOMER_REQUEST'
+  | 'PAYMENT_FAILED'
+  | 'ORDER_CANCELLED'
+  | 'DUPLICATE'
+  | 'OTHER'
+
+export interface CancelInvoiceInput {
+  invoice: Invoice
+  reason: CancellationReason
+  notes?: string
+}
+
+export interface CancellationRecord {
+  invoiceId: string
+  reason: CancellationReason
+  notes?: string
+  timestamp: Date
+}
+
+/**
+ * 發票取消者角色
+ */
+export interface InvoiceCancellerRole {
+  cancel(input: CancelInvoiceInput): Promise<Invoice>
+  validateCancellationEligibility(invoice: Invoice): boolean
+  recordCancellationReason(
+    invoiceId: string,
+    reason: CancellationReason,
+    notes?: string
+  ): CancellationRecord
+  notifyRelatedServices(invoiceId: string): Promise<void>
+}
+
+/**
+ * 預設發票取消者實現
+ */
+export class DefaultInvoiceCanceller implements InvoiceCancellerRole {
+  private cancellationRecords: Map<string, CancellationRecord> = new Map()
+
+  validateCancellationEligibility(invoice: Invoice): boolean {
+    return invoice.statusObject.canBeCancelled()
+  }
+
+  recordCancellationReason(
+    invoiceId: string,
+    reason: CancellationReason,
+    notes?: string
+  ): CancellationRecord {
+    const record: CancellationRecord = {
+      invoiceId,
+      reason,
+      notes,
+      timestamp: new Date(),
+    }
+    this.cancellationRecords.set(invoiceId, record)
+    return record
+  }
+
+  getCancellationRecord(invoiceId: string): CancellationRecord | undefined {
+    return this.cancellationRecords.get(invoiceId)
+  }
+
+  async notifyRelatedServices(invoiceId: string): Promise<void> {
+    const record = this.cancellationRecords.get(invoiceId)
+    if (!record) {
+      throw new Error(`No cancellation record found for invoice ${invoiceId}`)
+    }
+    // 實際實現應該透過 event bus 通知相關服務
+    // 這裡只是佔位符
+  }
+
+  async cancel(input: CancelInvoiceInput): Promise<Invoice> {
+    // 驗證是否可取消
+    if (!this.validateCancellationEligibility(input.invoice)) {
+      throw new Error(`Invoice ${input.invoice.id} cannot be cancelled`)
+    }
+
+    // 記錄取消
+    this.recordCancellationReason(input.invoice.id, input.reason, input.notes)
+
+    // 通知相關服務
+    await this.notifyRelatedServices(input.invoice.id)
+
+    // 執行取消
+    return input.invoice.cancel()
+  }
+}
+
+/**
+ * 注入函式 - 用於 DI 容器
+ */
+export function injectInvoiceCanceller(): InvoiceCancellerRole {
+  return new DefaultInvoiceCanceller()
+}

package/src/Application/Roles/InvoiceIssuerRole.ts

@@ -0,0 +1,72 @@
+import { Invoice } from '../../Domain/Entities/Invoice'
+import { InvalidOrderIdError } from '../../Domain/Errors/InvoiceError'
+import { InvoiceNumber } from '../../Domain/ValueObjects/InvoiceNumber'
+import { InvoiceTax } from '../../Domain/ValueObjects/InvoiceTax'
+
+export interface IssueInvoiceInput {
+  orderId: string
+  amount: number
+  currency?: string
+  buyerIdentifier?: string
+  carrierId?: string
+}
+
+export interface IssueInvoiceOutput {
+  invoice: Invoice
+}
+
+/**
+ * 發票發行者角色
+ */
+export interface InvoiceIssuerRole {
+  issueInvoice(input: IssueInvoiceInput): Promise<Invoice>
+  generateInvoiceNumber(): InvoiceNumber
+  calculateTax(amount: number, rate?: number): InvoiceTax
+  validateOrderForInvoicing(orderId: string): Promise<boolean>
+}
+
+/**
+ * 預設發票發行者實現
+ */
+export class DefaultInvoiceIssuer implements InvoiceIssuerRole {
+  generateInvoiceNumber(): InvoiceNumber {
+    return InvoiceNumber.generate()
+  }
+
+  calculateTax(amount: number, rate = 0.05): InvoiceTax {
+    return InvoiceTax.calculate(amount, rate)
+  }
+
+  async validateOrderForInvoicing(orderId: string): Promise<boolean> {
+    // 基本驗證 - 檢查 orderId 是否為有效字符串
+    return typeof orderId === 'string' && orderId.length > 0
+  }
+
+  async issueInvoice(input: IssueInvoiceInput): Promise<Invoice> {
+    // 驗證 orderId
+    if (!(await this.validateOrderForInvoicing(input.orderId))) {
+      throw new InvalidOrderIdError(input.orderId)
+    }
+
+    const invoiceNumber = this.generateInvoiceNumber()
+    const tax = this.calculateTax(input.amount, 0.05)
+
+    return Invoice.create({
+      orderId: input.orderId,
+      invoiceNumber: invoiceNumber.value,
+      amount: input.amount,
+      currency: input.currency ?? 'TWD',
+      tax: tax.amount,
+      taxRate: tax.rate,
+      buyerIdentifier: input.buyerIdentifier,
+      carrierId: input.carrierId,
+    })
+  }
+}
+
+/**
+ * 注入函式 - 用於 DI 容器
+ */
+export function injectInvoiceIssuer(): InvoiceIssuerRole {
+  return new DefaultInvoiceIssuer()
+}

package/src/Application/Roles/InvoiceTrackerRole.ts

@@ -0,0 +1,112 @@
+import type { Invoice } from '../../Domain/Entities/Invoice'
+
+export interface AuditLog {
+  invoiceId: string
+  action: string
+  timestamp: Date
+  details?: Record<string, any>
+}
+
+export interface ReportSummary {
+  total: number
+  issued: number
+  cancelled: number
+  returned: number
+  totalAmount: number
+}
+
+export interface ReportData {
+  summary: ReportSummary
+  invoices: Array<{
+    id: string
+    number: string
+    orderId: string
+    amount: number
+    status: string
+    createdAt: Date
+  }>
+}
+
+/**
+ * 發票追蹤者角色
+ */
+export interface InvoiceTrackerRole {
+  trackStatus(invoice: Invoice): Promise<void>
+  trackStatus(invoiceId: string): Promise<void>
+  trackInvoiceStatus(invoiceId: string): Promise<string | null>
+  generateReport(startDate: Date, endDate: Date): Promise<ReportData>
+  recordAuditLog(log: AuditLog): void
+  auditTrail(invoiceId: string): Promise<AuditLog[]>
+  trackInvoice(invoice: Invoice): void
+}
+
+/**
+ * 預設發票追蹤者實現
+ */
+export class DefaultInvoiceTracker implements InvoiceTrackerRole {
+  private invoices: Map<string, Invoice> = new Map()
+  private auditLogs: Map<string, AuditLog[]> = new Map()
+
+  trackInvoice(invoice: Invoice): void {
+    this.invoices.set(invoice.id, invoice)
+  }
+
+  async trackStatus(invoiceOrId: Invoice | string): Promise<void> {
+    // 接受 Invoice 或 string（invoiceId）
+    if (typeof invoiceOrId === 'string') {
+      // 如果是字符串，暫時不做任何操作
+      return
+    }
+    // 追蹤發票狀態
+    this.trackInvoice(invoiceOrId)
+  }
+
+  async trackInvoiceStatus(invoiceId: string): Promise<string | null> {
+    const invoice = this.invoices.get(invoiceId)
+    return invoice ? invoice.status : null
+  }
+
+  recordAuditLog(log: AuditLog): void {
+    if (!this.auditLogs.has(log.invoiceId)) {
+      this.auditLogs.set(log.invoiceId, [])
+    }
+    this.auditLogs.get(log.invoiceId)?.push(log)
+  }
+
+  async auditTrail(invoiceId: string): Promise<AuditLog[]> {
+    return this.auditLogs.get(invoiceId) ?? []
+  }
+
+  async generateReport(startDate: Date, endDate: Date): Promise<ReportData> {
+    const invoices = Array.from(this.invoices.values()).filter(
+      (inv) => inv.createdAt >= startDate && inv.createdAt <= endDate
+    )
+
+    const summary: ReportSummary = {
+      total: invoices.length,
+      issued: invoices.filter((inv) => inv.statusObject.isIssued()).length,
+      cancelled: invoices.filter((inv) => inv.statusObject.isCancelled()).length,
+      returned: invoices.filter((inv) => inv.statusObject.isReturned()).length,
+      totalAmount: invoices.reduce((sum, inv) => sum + inv.amountObject.value, 0),
+    }
+
+    return {
+      summary,
+      invoices: invoices.map((inv) => ({
+        id: inv.id,
+        number: inv.invoiceNumberObject.value,
+        orderId: inv.orderId,
+        amount: inv.amountObject.value,
+        status: inv.statusObject.value,
+        createdAt: inv.createdAt,
+      })),
+    }
+  }
+}
+
+/**
+ * 注入函式 - 用於 DI 容器
+ */
+export function injectInvoiceTracker(): InvoiceTrackerRole {
+  return new DefaultInvoiceTracker()
+}

package/src/Application/UseCases/CancelInvoice.ts

@@ -0,0 +1,32 @@
+import { UseCase } from '@gravito/enterprise'
+import type { IInvoiceRepository } from '../../Domain/Contracts/IInvoiceRepository'
+import {
+  type CancelInvoiceInput,
+  type CancelInvoiceOutput,
+  InvoiceCancellationContext,
+} from '../Contexts/InvoiceCancellationContext'
+import { type CancellationReason, DefaultInvoiceCanceller } from '../Roles/InvoiceCancellerRole'
+
+export interface CancelInvoiceUseCaseInput {
+  invoiceId: string
+  reason: CancellationReason
+  notes?: string
+}
+
+/**
+ * 發票取消 UseCase（薄殼委派）
+ * 委派到 InvoiceCancellationContext 進行實際業務流程處理
+ */
+export class CancelInvoice extends UseCase<CancelInvoiceUseCaseInput, CancelInvoiceOutput> {
+  private context: InvoiceCancellationContext
+
+  constructor(repository: IInvoiceRepository) {
+    super()
+    const canceller = new DefaultInvoiceCanceller()
+    this.context = new InvoiceCancellationContext(repository, canceller)
+  }
+
+  async execute(input: CancelInvoiceUseCaseInput): Promise<CancelInvoiceOutput> {
+    return this.context.orchestrate(input as CancelInvoiceInput)
+  }
+}

package/src/Application/UseCases/IssueInvoice.ts

@@ -1,6 +1,8 @@
 import { UseCase } from '@gravito/enterprise'
 import type { IInvoiceRepository } from '../../Domain/Contracts/IInvoiceRepository'
-import { Invoice } from '../../Domain/Entities/Invoice'
+import type { Invoice } from '../../Domain/Entities/Invoice'
+import { InvoiceIssuanceContext } from '../Contexts/InvoiceIssuanceContext'
+import { DefaultInvoiceIssuer } from '../Roles/InvoiceIssuerRole'
 
 export interface IssueInvoiceInput {
   orderId: string
@@ -9,35 +11,20 @@ export interface IssueInvoiceInput {
   carrierId?: string
 }
 
+/**
+ * 發票開立 UseCase（薄殼委派）
+ * 委派到 InvoiceIssuanceContext 進行實際業務流程處理
+ */
 export class IssueInvoice extends UseCase<IssueInvoiceInput, Invoice> {
-  constructor(private repository: IInvoiceRepository) {
+  private context: InvoiceIssuanceContext
+
+  constructor(repository: IInvoiceRepository) {
     super()
+    const issuer = new DefaultInvoiceIssuer()
+    this.context = new InvoiceIssuanceContext(repository, issuer)
   }
 
   async execute(input: IssueInvoiceInput): Promise<Invoice> {
-    // 檢查是否已開立過
-    const existing = await this.repository.findByOrderId(input.orderId)
-    if (existing) {
-      return existing
-    }
-
-    // 模擬發票號碼產生器
-    const randomNum = Math.floor(10000000 + Math.random() * 90000000)
-    const invoiceNumber = `GX-${randomNum}`
-
-    const tax = Math.round(input.amount * 0.05)
-
-    const invoice = Invoice.create({
-      orderId: input.orderId,
-      invoiceNumber,
-      amount: input.amount,
-      tax,
-      status: 'ISSUED',
-      buyerIdentifier: input.buyerIdentifier,
-      carrierId: input.carrierId,
-    })
-
-    await this.repository.save(invoice)
-    return invoice
+    return this.context.orchestrate(input)
   }
 }

package/src/Application/UseCases/QueryInvoiceStatus.ts

@@ -0,0 +1,56 @@
+import { UseCase } from '@gravito/enterprise'
+import type { IInvoiceRepository } from '../../Domain/Contracts/IInvoiceRepository'
+import { InvoiceAuditContext } from '../Contexts/InvoiceAuditContext'
+import { DefaultInvoiceTracker } from '../Roles/InvoiceTrackerRole'
+
+export interface QueryInvoiceStatusInput {
+  invoiceId: string
+}
+
+export interface QueryInvoiceStatusOutput {
+  id: string
+  invoiceNumber: string
+  orderId: string
+  status: string
+  amount: number
+  createdAt: Date
+}
+
+export interface GenerateInvoiceReportInput {
+  startDate: Date
+  endDate: Date
+}
+
+/**
+ * 發票查詢 UseCase（薄殼委派）
+ */
+export class QueryInvoiceStatus extends UseCase<QueryInvoiceStatusInput, QueryInvoiceStatusOutput> {
+  private context: InvoiceAuditContext
+
+  constructor(repository: IInvoiceRepository) {
+    super()
+    const tracker = new DefaultInvoiceTracker()
+    this.context = new InvoiceAuditContext(repository, tracker)
+  }
+
+  async execute(input: QueryInvoiceStatusInput): Promise<QueryInvoiceStatusOutput> {
+    return this.context.queryStatus(input)
+  }
+}
+
+/**
+ * 發票報告生成 UseCase（薄殼委派）
+ */
+export class GenerateInvoiceReport extends UseCase<GenerateInvoiceReportInput, any> {
+  private context: InvoiceAuditContext
+
+  constructor(repository: IInvoiceRepository) {
+    super()
+    const tracker = new DefaultInvoiceTracker()
+    this.context = new InvoiceAuditContext(repository, tracker)
+  }
+
+  async execute(input: GenerateInvoiceReportInput): Promise<any> {
+    return this.context.generateReport(input)
+  }
+}

package/src/Domain/Contracts/IInvoiceRepository.ts

@@ -5,4 +5,7 @@ export interface IInvoiceRepository {
   findById(id: string): Promise<Invoice | null>
   findByOrderId(orderId: string): Promise<Invoice | null>
   findAll(): Promise<Invoice[]>
+  findByInvoiceNumber(invoiceNumber: string): Promise<Invoice | null>
+  findByStatus(status: string): Promise<Invoice[]>
+  findByDateRange(startDate: Date, endDate: Date): Promise<Invoice[]>
 }