@gravito/satellite-invoice 0.1.4 → 0.2.0

package/src/Infrastructure/Persistence/AtlasInvoiceRepository.ts

@@ -6,11 +6,25 @@ class InvoiceModel extends Model {
   static override table = 'invoices'
 }
 
+/**
+ * Atlas ORM 發票 Repository
+ * 實現 IInvoiceRepository 介面
+ */
 export class AtlasInvoiceRepository implements IInvoiceRepository {
   async save(invoice: Invoice): Promise<void> {
+    const snapshot = invoice.toSnapshot()
     const data = {
-      id: invoice.id,
-      ...invoice.unpack(),
+      id: snapshot.id,
+      orderId: snapshot.orderId,
+      invoiceNumber: snapshot.invoiceNumber,
+      amount: snapshot.amount,
+      amountCurrency: snapshot.amountCurrency,
+      tax: snapshot.tax,
+      taxRate: snapshot.taxRate,
+      status: snapshot.status,
+      buyerIdentifier: snapshot.buyerIdentifier,
+      carrierId: snapshot.carrierId,
+      createdAt: snapshot.createdAt,
     }
 
     const existing = await InvoiceModel.find(invoice.id)
@@ -23,16 +37,131 @@ export class AtlasInvoiceRepository implements IInvoiceRepository {
 
   async findById(id: string): Promise<Invoice | null> {
     const row = await InvoiceModel.find(id)
-    return row ? Invoice.create((row as any).props, (row as any).props.id) : null
+    if (!row) {
+      return null
+    }
+    const snapshot = row as any
+    return Invoice.fromSnapshot({
+      id: snapshot.id,
+      orderId: snapshot.orderId,
+      invoiceNumber: snapshot.invoiceNumber,
+      amount: snapshot.amount,
+      amountCurrency: snapshot.amountCurrency,
+      tax: snapshot.tax,
+      taxRate: snapshot.taxRate,
+      status: snapshot.status,
+      buyerIdentifier: snapshot.buyerIdentifier,
+      carrierId: snapshot.carrierId,
+      createdAt: snapshot.createdAt,
+    })
   }
 
   async findByOrderId(orderId: string): Promise<Invoice | null> {
-    const row = await (InvoiceModel.query() as any).where('order_id', orderId).first()
-    return row ? Invoice.create(row.props, row.props.id) : null
+    const row = await (InvoiceModel.query() as any).where('orderId', orderId).first()
+    if (!row) {
+      return null
+    }
+    const snapshot = row
+    return Invoice.fromSnapshot({
+      id: snapshot.id,
+      orderId: snapshot.orderId,
+      invoiceNumber: snapshot.invoiceNumber,
+      amount: snapshot.amount,
+      amountCurrency: snapshot.amountCurrency,
+      tax: snapshot.tax,
+      taxRate: snapshot.taxRate,
+      status: snapshot.status,
+      buyerIdentifier: snapshot.buyerIdentifier,
+      carrierId: snapshot.carrierId,
+      createdAt: snapshot.createdAt,
+    })
   }
 
   async findAll(): Promise<Invoice[]> {
     const rows = await InvoiceModel.all()
-    return rows.map((row) => Invoice.create((row as any).props, (row as any).props.id))
+    return rows.map((row) =>
+      Invoice.fromSnapshot({
+        id: (row as any).id,
+        orderId: (row as any).orderId,
+        invoiceNumber: (row as any).invoiceNumber,
+        amount: (row as any).amount,
+        amountCurrency: (row as any).amountCurrency,
+        tax: (row as any).tax,
+        taxRate: (row as any).taxRate,
+        status: (row as any).status,
+        buyerIdentifier: (row as any).buyerIdentifier,
+        carrierId: (row as any).carrierId,
+        createdAt: (row as any).createdAt,
+      })
+    )
+  }
+
+  /**
+   * 按發票號碼查詢
+   */
+  async findByInvoiceNumber(invoiceNumber: string): Promise<Invoice | null> {
+    const row = await (InvoiceModel.query() as any).where('invoiceNumber', invoiceNumber).first()
+    if (!row) {
+      return null
+    }
+    const snapshot = row
+    return Invoice.fromSnapshot({
+      id: snapshot.id,
+      orderId: snapshot.orderId,
+      invoiceNumber: snapshot.invoiceNumber,
+      amount: snapshot.amount,
+      amountCurrency: snapshot.amountCurrency,
+      tax: snapshot.tax,
+      taxRate: snapshot.taxRate,
+      status: snapshot.status,
+      buyerIdentifier: snapshot.buyerIdentifier,
+      carrierId: snapshot.carrierId,
+      createdAt: snapshot.createdAt,
+    })
+  }
+
+  /**
+   * 按狀態查詢
+   */
+  async findByStatus(status: string): Promise<Invoice[]> {
+    const rows = await (InvoiceModel.query() as any).where('status', status)
+    return rows.map((row: any) =>
+      Invoice.fromSnapshot({
+        id: row.id,
+        orderId: row.orderId,
+        invoiceNumber: row.invoiceNumber,
+        amount: row.amount,
+        amountCurrency: row.amountCurrency,
+        tax: row.tax,
+        taxRate: row.taxRate,
+        status: row.status,
+        buyerIdentifier: row.buyerIdentifier,
+        carrierId: row.carrierId,
+        createdAt: row.createdAt,
+      })
+    )
+  }
+
+  /**
+   * 按日期範圍查詢
+   */
+  async findByDateRange(startDate: Date, endDate: Date): Promise<Invoice[]> {
+    const rows = await (InvoiceModel.query() as any).whereBetween('createdAt', [startDate, endDate])
+
+    return rows.map((row: any) =>
+      Invoice.fromSnapshot({
+        id: row.id,
+        orderId: row.orderId,
+        invoiceNumber: row.invoiceNumber,
+        amount: row.amount,
+        amountCurrency: row.amountCurrency,
+        tax: row.tax,
+        taxRate: row.taxRate,
+        status: row.status,
+        buyerIdentifier: row.buyerIdentifier,
+        carrierId: row.carrierId,
+        createdAt: row.createdAt,
+      })
+    )
   }
 }

package/src/Interface/Http/Controllers/AdminInvoiceController.ts

@@ -1,32 +1,278 @@
 import type { PlanetCore } from '@gravito/core'
+import type { CancelInvoice } from '../../../Application/UseCases/CancelInvoice'
 import type { IssueInvoice } from '../../../Application/UseCases/IssueInvoice'
+import type {
+  GenerateInvoiceReport,
+  QueryInvoiceStatus,
+} from '../../../Application/UseCases/QueryInvoiceStatus'
 import type { Invoice } from '../../../Domain/Entities/Invoice'
+import {
+  DuplicateInvoiceError,
+  InvalidCancellationError,
+  InvoiceError,
+  InvoiceNotFoundError,
+} from '../../../Domain/Errors/InvoiceError'
 
+/**
+ * 發票管理控制器
+ * 提供完整的 API 端點
+ */
 export class AdminInvoiceController {
   constructor(private core: PlanetCore) {}
 
+  /**
+   * GET /invoices - 列表查詢發票
+   */
   async index(ctx: any) {
-    // 獲取所有發票清單
-    const repo = this.core.container.make('invoice.repository') as any
-    const invoices = await repo.findAll()
-    return ctx.json(
-      invoices.map((inv: Invoice) => ({
-        id: inv.id,
-        ...inv.unpack(),
-      }))
-    )
+    try {
+      const repo = this.core.container.make('invoice.repository') as any
+      const invoices = await repo.findAll()
+
+      return ctx.json({
+        success: true,
+        data: invoices.map((inv: Invoice) => inv.unpack()),
+        meta: {
+          total: invoices.length,
+        },
+      })
+    } catch (error) {
+      this.logError('Failed to list invoices', error)
+      return ctx.json(
+        {
+          success: false,
+          error: '無法獲取發票列表',
+        },
+        500
+      )
+    }
   }
 
+  /**
+   * POST /invoices - 開立新發票
+   */
   async store(ctx: any) {
-    const body = await ctx.req.json()
-    const useCase = this.core.container.make<IssueInvoice>('invoice.usecase.issue')
-    const invoice = await useCase.execute(body)
-    return ctx.json({
-      success: true,
-      data: {
-        id: invoice.id,
-        number: invoice.invoiceNumber,
+    try {
+      const body = await ctx.req.json()
+
+      // 驗證必要欄位
+      if (!body.orderId || !body.amount) {
+        return ctx.json(
+          {
+            success: false,
+            error: '缺少必要欄位：orderId, amount',
+          },
+          400
+        )
+      }
+
+      const useCase = this.core.container.make<IssueInvoice>('invoice.usecase.issue')
+      const invoice = await useCase.execute(body)
+
+      return ctx.json({
+        success: true,
+        data: {
+          id: invoice.id,
+          invoiceNumber: invoice.invoiceNumber,
+          orderId: invoice.orderId,
+          amount: invoice.amount,
+          status: invoice.status,
+          createdAt: invoice.createdAt,
+        },
+      })
+    } catch (error) {
+      return this.handleError(ctx, error, 'Failed to issue invoice')
+    }
+  }
+
+  /**
+   * GET /invoices/:id - 查詢發票狀態
+   */
+  async show(ctx: any) {
+    try {
+      const invoiceId = ctx.param('id')
+
+      if (!invoiceId) {
+        return ctx.json(
+          {
+            success: false,
+            error: '缺少發票 ID',
+          },
+          400
+        )
+      }
+
+      const useCase = this.core.container.make<QueryInvoiceStatus>('invoice.usecase.query')
+      const result = await useCase.execute({ invoiceId })
+
+      return ctx.json({
+        success: true,
+        data: result,
+      })
+    } catch (error) {
+      return this.handleError(ctx, error, 'Failed to query invoice status')
+    }
+  }
+
+  /**
+   * POST /invoices/:id/cancel - 取消發票
+   */
+  async cancel(ctx: any) {
+    try {
+      const invoiceId = ctx.param('id')
+      const body = await ctx.req.json()
+
+      if (!invoiceId) {
+        return ctx.json(
+          {
+            success: false,
+            error: '缺少發票 ID',
+          },
+          400
+        )
+      }
+
+      if (!body.reason) {
+        return ctx.json(
+          {
+            success: false,
+            error: '缺少取消原因',
+          },
+          400
+        )
+      }
+
+      const useCase = this.core.container.make<CancelInvoice>('invoice.usecase.cancel')
+      const result = await useCase.execute({
+        invoiceId,
+        reason: body.reason,
+        notes: body.notes,
+      })
+
+      return ctx.json({
+        success: true,
+        data: result,
+      })
+    } catch (error) {
+      return this.handleError(ctx, error, 'Failed to cancel invoice')
+    }
+  }
+
+  /**
+   * GET /invoices/report - 生成發票報告
+   */
+  async report(ctx: any) {
+    try {
+      const startDate = ctx.query('startDate')
+      const endDate = ctx.query('endDate')
+
+      if (!startDate || !endDate) {
+        return ctx.json(
+          {
+            success: false,
+            error: '缺少日期範圍參數：startDate, endDate',
+          },
+          400
+        )
+      }
+
+      const start = new Date(startDate)
+      const end = new Date(endDate)
+
+      if (isNaN(start.getTime()) || isNaN(end.getTime())) {
+        return ctx.json(
+          {
+            success: false,
+            error: '無效的日期格式',
+          },
+          400
+        )
+      }
+
+      const useCase = this.core.container.make<GenerateInvoiceReport>('invoice.usecase.report')
+      const report = await useCase.execute({
+        startDate: start,
+        endDate: end,
+      })
+
+      return ctx.json({
+        success: true,
+        data: report,
+      })
+    } catch (error) {
+      this.logError('Failed to generate report', error)
+      return ctx.json(
+        {
+          success: false,
+          error: '無法生成報告',
+        },
+        500
+      )
+    }
+  }
+
+  /**
+   * 處理錯誤
+   */
+  private handleError(ctx: any, error: unknown, message: string): any {
+    if (error instanceof InvoiceNotFoundError) {
+      return ctx.json(
+        {
+          success: false,
+          error: error.message,
+        },
+        404
+      )
+    }
+
+    if (error instanceof DuplicateInvoiceError) {
+      return ctx.json(
+        {
+          success: false,
+          error: error.message,
+        },
+        409
+      )
+    }
+
+    if (error instanceof InvalidCancellationError) {
+      return ctx.json(
+        {
+          success: false,
+          error: error.message,
+        },
+        400
+      )
+    }
+
+    if (error instanceof InvoiceError) {
+      this.logError(message, error)
+      return ctx.json(
+        {
+          success: false,
+          error: error.message,
+        },
+        400
+      )
+    }
+
+    this.logError(message, error)
+    return ctx.json(
+      {
+        success: false,
+        error: '伺服器內部錯誤',
       },
-    })
+      500
+    )
+  }
+
+  /**
+   * 記錄錯誤
+   */
+  private logError(message: string, error: unknown): void {
+    if (this.core?.logger) {
+      this.core.logger.error(
+        `[Invoice] ${message}: ${error instanceof Error ? error.message : String(error)}`
+      )
+    }
   }
 }

package/src/index.ts

@@ -1,15 +1,57 @@
 import { type Container, ServiceProvider } from '@gravito/core'
+import { CancelInvoice } from './Application/UseCases/CancelInvoice'
 import { IssueInvoice } from './Application/UseCases/IssueInvoice'
+import {
+  GenerateInvoiceReport,
+  QueryInvoiceStatus,
+} from './Application/UseCases/QueryInvoiceStatus'
 import { AtlasInvoiceRepository } from './Infrastructure/Persistence/AtlasInvoiceRepository'
 import { AdminInvoiceController } from './Interface/Http/Controllers/AdminInvoiceController'
 
+// Infrastructure Exports
+export type { IInvoiceRepository } from './Domain/Contracts/IInvoiceRepository'
+// Domain Exports
+export { Invoice, type InvoiceProps, type InvoiceSnapshot } from './Domain/Entities/Invoice'
+export {
+  DuplicateInvoiceError,
+  InvalidAmountError,
+  InvalidCancellationError,
+  InvalidInvoiceNumberError,
+  InvalidTaxError,
+  InvalidTransitionError,
+  InvoiceError,
+  InvoiceNotFoundError,
+} from './Domain/Errors/InvoiceError'
+export { InvoiceAmount, type InvoiceAmountProps } from './Domain/ValueObjects/InvoiceAmount'
+export { InvoiceNumber, type InvoiceNumberProps } from './Domain/ValueObjects/InvoiceNumber'
+export { InvoiceStatus, type InvoiceStatusType } from './Domain/ValueObjects/InvoiceStatus'
+export { InvoiceTax, type InvoiceTaxProps } from './Domain/ValueObjects/InvoiceTax'
+export { AtlasInvoiceRepository } from './Infrastructure/Persistence/AtlasInvoiceRepository'
+
 export class InvoiceServiceProvider extends ServiceProvider {
   register(container: Container): void {
+    // 註冊 Repository
     container.singleton('invoice.repository', () => new AtlasInvoiceRepository())
+
+    // 註冊 UseCase
     container.bind(
       'invoice.usecase.issue',
       () => new IssueInvoice(container.make('invoice.repository'))
     )
+    container.bind(
+      'invoice.usecase.cancel',
+      () => new CancelInvoice(container.make('invoice.repository'))
+    )
+    container.bind(
+      'invoice.usecase.query',
+      () => new QueryInvoiceStatus(container.make('invoice.repository'))
+    )
+    container.bind(
+      'invoice.usecase.report',
+      () => new GenerateInvoiceReport(container.make('invoice.repository'))
+    )
+
+    // 註冊 Controller
     container.singleton('invoice.controller.admin', () => new AdminInvoiceController(this.core!))
   }
 
@@ -25,8 +67,20 @@ export class InvoiceServiceProvider extends ServiceProvider {
 
     // 註冊管理路由
     core.router.prefix('/api/admin/v1/invoices').group((router) => {
+      // 發票列表
       router.get('/', (ctx) => controller.index(ctx))
+
+      // 開立發票
       router.post('/', (ctx) => controller.store(ctx))
+
+      // 查詢發票狀態
+      router.get('/:id', (ctx) => controller.show(ctx))
+
+      // 取消發票
+      router.post('/:id/cancel', (ctx) => controller.cancel(ctx))
+
+      // 生成報告
+      router.get('/report', (ctx) => controller.report(ctx))
     })
 
     /**
@@ -40,13 +94,13 @@ export class InvoiceServiceProvider extends ServiceProvider {
         const issueUseCase = core.container.make<IssueInvoice>('invoice.usecase.issue')
 
         try {
-          const invoice = await issueUseCase.execute({
+          const invoice = (await issueUseCase.execute({
             orderId: payload.orderId,
             amount: payload.amount,
             buyerIdentifier: payload.buyer?.identifier,
             carrierId: payload.buyer?.carrierId,
-          })
-          core.logger.info(`[Invoice] Automatically issued: ${invoice.invoiceNumber}`)
+          })) as any
+          core.logger.info(`[Invoice] Automatically issued: ${invoice.invoiceNumber.value}`)
         } catch (error: any) {
           core.logger.error(`[Invoice] Auto-issue failed: ${error.message}`)
         }