領域事件與命令

預設範本的 Reaction 中已註冊的 Event、Command 及其處理方式。

發布於 2026年9月20日

一次業務變動會先產生 Event，再由 Event 建立一或多個 Command。Reaction 只處理已註冊至 src/core/reaction/events/index.ts 和 src/core/reaction/commands/index.ts 的定義。

Event

`EventInput`

Prop

Type

已註冊的 Event

Event	`type`	輸入要點	產生的 Command
`UserSignupEvent`	`user_signed_up`	Subject、來源，以及選填的角色和註冊郵件	`grant_role`、`send_email`
`UserEmailVerifiedEvent`	`user_email_verified`	使用者 Subject、`verifiedEmail`、`emailHash`、`verifiedAt`、`purpose`	帳號電子郵件驗證成功，且電子郵件地址符合管理員名單時，產生 `grant_role`
`PaymentSucceededEvent`	`payment_succeeded`	Subject、來源，以及選填的角色和權益	`grant_role`、`grant_entitlement`
`SubscriptionCreatedEvent`	`subscription_created`	Subject、訂閱來源，以及選填的角色和權益	`grant_role`、`grant_entitlement`
`SubscriptionUpdatedEvent`	`subscription_updated`	Subject、訂閱來源，以及選填的完整角色和權益設定	先撤銷該來源的既有內容，再依新設定重新授予
`SubscriptionEndedEvent`	`subscription_ended`	Subject、訂閱來源，以及選填的角色和權益	`revoke_role`、`revoke_entitlement`
`UserEmailUpdatedEvent`	`user_email_updated`	使用者 Subject、電子郵件地址摘要，以及選填的舊電子郵件地址通知資料	同步付款服務供應商的電子郵件地址，並視需要向舊地址寄送安全性提醒
`UserTwoFactorSecurityChangedEvent`	`user_two_factor_security_changed`	使用者、電子郵件地址、姓名、語言、發生時間和安全性設定網址	`send_email`
`EntitlementCycleDueEvent`	`entitlement_cycle_due`	選填的下一筆週期權益紀錄	`process_due_entitlement_cycles`
`DataCleanupEvent`	`data_cleanup`	`olderThan`	`purge_stale_data`
`NotificationRequestedEvent`	`notification_requested`	通知目標和訊息	`send_notification`

SubscriptionUpdatedEvent 和 SubscriptionEndedEvent 處理 roles、entitlements 時，必須區分欄位不存在與空陣列。欄位不存在時，不處理這類資料。空陣列則會撤銷該來源下的全部角色或權益。

UserEmailVerifiedEvent 的 purpose 為 account 或 password_reset。只有本站帳號的電子郵件驗證流程，會依 adminEmails 的精確比對結果授予 admin 角色。密碼重設驗證不會授予角色，OAuth 供應商傳回的電子郵件已驗證宣告，也不能取代本站驗證。

UserEmailUpdatedEvent 預設設定 continueOnFailure: true。同步付款電子郵件地址與寄送安全性提醒彼此獨立，即使其中一項重試後仍失敗，另一項也會繼續執行。

Command

`CommandDraft`

Prop

Type

key 僅用於區分同一 Event 中的不同步驟，不決定執行順序，也不作為 Event 等冪鍵或 Command 執行 ID。

已註冊的 Command

Command	`type`	模式	用途
`GrantRoleCommand`	`grant_role`	`sync`	依來源為 Subject 授予角色
`RevokeRoleCommand`	`revoke_role`	`sync`	依來源撤銷角色或靜態能力
`GrantEntitlementCommand`	`grant_entitlement`	`sync`	依來源為 Subject 授予權益
`RevokeEntitlementCommand`	`revoke_entitlement`	`sync`	依來源撤銷權益或動態能力
`SendEmailCommand`	`send_email`	`async`	依已註冊郵件範本產生內容並寄送郵件
`SendNotificationCommand`	`send_notification`	`async`	透過設定的通知管道傳送訊息
`CreateUserNotificationCommand`	`create_user_notification`	`async`	建立已發布的站內通知，Command ID 同時作為通知 ID
`SyncPaymentCustomerEmailCommand`	`sync_payment_customer_email`	`async`	將使用者最新的已驗證電子郵件地址同步至付款服務供應商的 Customer
`ProcessDueEntitlementCyclesCommand`	`process_due_entitlement_cycles`	`async`	處理到期的週期權益，並安排下一次執行
`PurgeStaleDataCommand`	`purge_stale_data`	`async`	清理超過指定時間的資料

範本中所有 Command 的預設版本都是 1，最大嘗試次數都是 3。每個 Command 定義可以另外設定這兩個值。Event 建立 Command 時，也可以只修改本次執行的 maxAttempts。

sync Command 會在 Event 執行過程中立即處理，async Command 則交給 ASYNC_POLICY_TASK_QUEUE。無論採用哪種模式，執行紀錄都會寫入 command_execution。

執行狀態

`EventExecutionStatus`

值	含義
`processing`	未觸發終止條件，且仍有 Command 等待執行
`completed`	沒有 Command 處於等待、業務失敗或例外狀態
`partial_failed`	`continueOnFailure` 為 `true`，全部 Command 已結束，其中至少一個傳回業務失敗
`failed`	`continueOnFailure` 為 `false`，且至少一個 Command 傳回業務失敗
`errored`	至少一個 Command 執行時擲出例外

Event 狀態由其 Command 狀態計算得出，不另外儲存，以免兩份狀態不一致。

`CommandExecutionStatus`

pending、succeeded、failed、errored 分別表示等待執行、執行成功、傳回業務失敗和擲出例外。

註冊位置

新增 Event 後，必須加入 src/core/reaction/events/index.ts 的 events 陣列。新增 Command 後，必須加入 src/core/reaction/commands/index.ts 的 commands 陣列。若只建立檔案而未註冊，Reaction 就無法辨識這項定義。