billing

type AffiliateReader = wallet.AffiliateReader

type AuthMethodReader = wallet.AuthMethodReader

type CurrencyRateCache = exchangerate.Cache

type DailyOrderReport = adminorder.DailyReport

type DailyOrderReportLine = adminorder.DailyReportLine

type Deps struct {
	PaidOrders  PaidOrderDependencies
	Orders      repository.OrderRepo
	OrderEvents OrderEventStore
	Payments    repository.PaymentRepo
	Coupons     repository.CouponRepo
	Withdrawals repository.UserWithdrawalRepo
	Plans       PlanReader
	UserSubs    UserSubscriptionReader
	// Store carries the billing-scoped transactions of the order and wallet
	// flows, the wallet view and the inbox markers. Subscription writes are
	// exposed only by the Inventory capability.
	Store     Store
	Inventory checkout.Inventory
	Tx        Transactor
	Queue     OrderQueue
	// Redis carries the outbox's wake-ups to the order event streams and
	// bounds the streams' concurrency.
	Redis *redis.Client
	// SingleModel forbids holding more than one blocking subscription;
	// runtime-mutable, read per request.
	SingleModel func() bool
	// CurrencyUnit is the site currency used for gateway verification;
	// runtime-mutable, read per request.
	CurrencyUnit func() string

	// InvitePolicy snapshots the runtime-mutable site-wide referral
	// fallback for the commission stage; UserProfiles resolves referral
	// settings, and the referrer a refund charges back, from the identity
	// domain.
	InvitePolicy func() (percentage uint8, onlyFirstPurchase bool)
	UserProfiles activation.ProfileReader

	// Wallet-specific dependencies: audit-log statements and the
	// identity-domain read ports. UserCache invalidates the identity
	// module's user cache after a balance checkout.
	Logs        repository.LogRepo
	UserCache   UserCache
	Affiliates  AffiliateReader
	AuthMethods AuthMethodReader

	// Portal-specific dependencies.
	PortalPlans        PortalPlanReader
	GuestAccounts      GuestAccountReader
	Sessions           SessionStore
	GuestCheckoutCache GuestCheckoutCache
	ExchangeRate       ExchangeRateCache
	Portal             PortalConfig
}

type EmailAliasReader = portal.EmailAliasReader

type ExchangeRateCache = portal.ExchangeRateCache

type GuestAccountReader = portal.GuestAccountReader

type GuestCheckoutCache = portal.GuestCheckoutCache

type GuestVerification = portal.GuestVerification

type OrderEventStore interface {
	v2orch.EventReader
	orderevents.Outbox
}

type OrderQueue interface {
	EnqueueActivation(ctx context.Context, orderNo string) error
	EnqueueDeferredClose(ctx context.Context, orderNo string) error
}

type OrderStatistics interface {
	// OrderRevenueOn, OrderRevenueInMonth and OrderRevenueTotal sum the
	// orders of date's day, of date's month and of all time.
	OrderRevenueOn(ctx context.Context, date time.Time) (order.OrdersTotal, error)
	OrderRevenueInMonth(ctx context.Context, date time.Time) (order.OrdersTotal, error)
	OrderRevenueTotal(ctx context.Context) (order.OrdersTotal, error)
	// DailyOrderRevenue breaks date's month down by day and
	// MonthlyOrderRevenue the last months up to date's by month.
	DailyOrderRevenue(ctx context.Context, date time.Time) ([]order.OrdersTotalWithDate, error)
	MonthlyOrderRevenue(ctx context.Context, date time.Time) ([]order.OrdersTotalWithDate, error)
	// PayingUsersOn, PayingUsersInMonth and PayingUsersTotal count the
	// buyers of new orders and of renewals of date's day, of date's month
	// and of all time.
	PayingUsersOn(ctx context.Context, date time.Time) (newUsers, renewalUsers int64, err error)
	PayingUsersInMonth(ctx context.Context, date time.Time) (newUsers, renewalUsers int64, err error)
	PayingUsersTotal(ctx context.Context) (newUsers, renewalUsers int64, err error)
}

type PaidOrderDependencies = activation.WorkflowDeps

type PaymentCallbackStyle = gateway.CallbackStyle

type PaymentNotification = gateway.Notification

type PlanReader = checkout.PlanReader

type PortalConfig = portal.Config

type PortalPlanReader = portal.PlanReader

type RegistrationPolicy = portal.RegistrationPolicy

type Service interface {
	// OrderStatistics serves the other modules' reads of order figures.
	OrderStatistics

	CreateOrder(ctx context.Context, req *dto.CreateOrderRequest) error
	GetOrderList(ctx context.Context, req *dto.GetOrderListRequest) (*dto.GetOrderListResponse, error)
	// UpdateOrderStatus applies the admin's Pending->Paid transition and
	// enqueues activation, or closes the order through the same close flow
	// as owner and expiry closes.
	UpdateOrderStatus(ctx context.Context, req *dto.UpdateOrderStatusRequest) error

	CreatePaymentMethod(ctx context.Context, req *dto.CreatePaymentMethodRequest) (*dto.PaymentConfig, error)
	UpdatePaymentMethod(ctx context.Context, req *dto.UpdatePaymentMethodRequest) (*dto.PaymentConfig, error)
	DeletePaymentMethod(ctx context.Context, req *dto.DeletePaymentMethodRequest) error
	GetPaymentMethodList(ctx context.Context, req *dto.GetPaymentMethodListRequest) (*dto.GetPaymentMethodListResponse, error)
	GetPaymentPlatform(ctx context.Context) (*dto.PaymentPlatformResponse, error)

	CreateCoupon(ctx context.Context, req *dto.CreateCouponRequest) error
	UpdateCoupon(ctx context.Context, req *dto.UpdateCouponRequest) error
	DeleteCoupon(ctx context.Context, req *dto.DeleteCouponRequest) error
	BatchDeleteCoupon(ctx context.Context, req *dto.BatchDeleteCouponRequest) error
	GetCouponList(ctx context.Context, req *dto.GetCouponListRequest) (*dto.GetCouponListResponse, error)

	// The user-facing order queries resolve the current user from the request
	// context, enforce ownership and never expose referrer commission.
	QueryOrderDetail(ctx context.Context, req *dto.QueryOrderDetailRequest) (*dto.OrderDetail, error)
	QueryOrderList(ctx context.Context, req *dto.QueryOrderListRequest) (*dto.QueryOrderListResponse, error)

	// The checkout flows resolve the current user from the request context.
	Purchase(ctx context.Context, req *dto.PurchaseOrderRequest) (*dto.PurchaseOrderResponse, error)
	Renewal(ctx context.Context, req *dto.RenewalOrderRequest) (*dto.RenewalOrderResponse, error)
	ResetTraffic(ctx context.Context, req *dto.ResetTrafficOrderRequest) (*dto.ResetTrafficOrderResponse, error)
	Recharge(ctx context.Context, req *dto.RechargeOrderRequest) (*dto.RechargeOrderResponse, error)
	PreCreateOrder(ctx context.Context, req *dto.PurchaseOrderRequest) (*dto.PreOrderResponse, error)
	// CloseOrder settles gateway-collected money instead of closing, releases
	// coupon and gift reservations, and returns reserved plan inventory.
	CloseOrder(ctx context.Context, req *dto.CloseOrderRequest) error

	// The portal flows serve the guest storefront; checkout resolves the
	// client IP from the request context.
	PortalPurchase(ctx context.Context, req *dto.PortalPurchaseRequest) (*dto.PortalPurchaseResponse, error)
	PortalPrePurchase(ctx context.Context, req *dto.PrePurchaseOrderRequest) (*dto.PrePurchaseOrderResponse, error)
	PortalCheckout(ctx context.Context, req *dto.CheckoutOrderRequest) (*dto.CheckoutOrderResponse, error)
	QueryPurchaseOrder(ctx context.Context, req *dto.QueryPurchaseOrderRequest) (*dto.QueryPurchaseOrderResponse, error)
	GetAvailablePaymentMethods(ctx context.Context) (*dto.GetAvailablePaymentMethodsResponse, error)
	GetPortalSubscription(ctx context.Context, req *dto.GetSubscriptionRequest) (*dto.GetSubscriptionResponse, error)
	// IssuePortalSession exchanges a completed guest purchase for a normal
	// authenticated session.
	IssuePortalSession(ctx context.Context, userID int64) (string, error)

	// FindPaymentMethodByToken reads the payment method whose notify URL
	// carries token, with the repository's error unwrapped: the notify
	// middleware resolves a callback's method with it and answers a failed
	// lookup with that error.
	FindPaymentMethodByToken(ctx context.Context, token string) (*paymentEntity.Payment, error)
	// PaymentNotify authenticates and settles a gateway callback. It reads
	// the payment method the notify middleware resolved from the request
	// context; every gateway goes through the same verification.
	PaymentNotify(ctx context.Context, notification PaymentNotification) error
	// PaymentCallbackStyle reports how a platform delivers its callbacks and
	// expects them answered; false for a platform without a gateway.
	PaymentCallbackStyle(platform string) (PaymentCallbackStyle, bool)

	// The V2 orchestration: idempotent create-and-checkout, guest checkout
	// capabilities and SSE event-stream tickets.
	V2CreateAndCheckout(ctx context.Context, req *dto.V2CreateOrderRequest, idempotencyKey string) (*dto.V2OrderResponse, error)
	V2Checkout(ctx context.Context, orderNo string, req *dto.V2CheckoutOrderRequest) (*dto.V2OrderResponse, error)
	V2GetOrder(ctx context.Context, orderNo, checkoutToken string) (*dto.V2OrderResponse, error)
	V2EventTicket(ctx context.Context, orderNo, checkoutToken string) (*dto.V2EventTicketResponse, error)
	V2Session(ctx context.Context, orderNo, checkoutToken string) (*dto.V2OrderSessionResponse, error)
	// V2StreamOrderEvents serves an order's event stream to sink until ctx
	// ends or the ticket expires: the snapshot, the events after the replay
	// cursor, then live events. It returns an error only when the stream is
	// refused, before anything reached the sink (ErrTooManyEventStreams
	// when the ticket holds its maximum of concurrent streams).
	V2StreamOrderEvents(ctx context.Context, req V2EventStreamRequest, sink V2EventSink) error

	// PublishOrderEvents drains the order-event outbox the streams replay:
	// it broadcasts the oldest unpublished events, 500 at most, on their
	// orders' Redis channels to wake the streams, marking each published.
	// The first failure ends the run with its error, and the next run
	// publishes what this one did not. CleanupOrderEvents deletes the
	// published events created before cutoff and reports how many; an
	// unpublished event is kept whatever its age.
	PublishOrderEvents(ctx context.Context) error
	CleanupOrderEvents(ctx context.Context, cutoff time.Time) (int64, error)

	// The wallet flows resolve the current user from the request context:
	// commission withdrawal, balance/commission statements and the affiliate
	// earnings overview.
	CommissionWithdraw(ctx context.Context, req *dto.CommissionWithdrawRequest) (*dto.WithdrawalLog, error)
	QueryUserBalanceLog(ctx context.Context) (*dto.QueryUserBalanceLogListResponse, error)
	QueryUserCommissionLog(ctx context.Context, req *dto.QueryUserCommissionLogListRequest) (*dto.QueryUserCommissionLogListResponse, error)
	QueryWithdrawalLog(ctx context.Context, req *dto.QueryWithdrawalLogListRequest) (*dto.QueryWithdrawalLogListResponse, error)
	GetWithdrawalList(ctx context.Context, req *dto.GetWithdrawalListRequest) (*dto.GetWithdrawalListResponse, error)
	ReviewWithdrawal(ctx context.Context, req *dto.ReviewWithdrawalRequest) error
	QueryUserAffiliate(ctx context.Context) (*dto.QueryUserAffiliateCountResponse, error)
	QueryUserAffiliateList(ctx context.Context, req *dto.QueryUserAffiliateListRequest) (*dto.QueryUserAffiliateListResponse, error)

	// The wallet as other modules reach it (ADR-001 rules 2 and 4): they read
	// the billing-owned wallet table and move money only through these
	// methods, each movement in a billing transaction of its own that runs
	// after the requesting module committed its part.
	//
	// FindWallet reads a user's wallet; a user without a wallet row reads as
	// nil. FindWallets reads several; users without a row are absent from
	// the map.
	FindWallet(ctx context.Context, userID int64) (*walletEntity.Wallet, error)
	FindWallets(ctx context.Context, userIDs []int64) (map[int64]*walletEntity.Wallet, error)
	// OpenWallet sets the opening balance, gift amount and commission of an
	// account an administrator created. AdjustWallet applies an
	// administrator's wallet edit: under the wallet lock each amount the
	// adjustment sets becomes the wallet's, with an audit log recording the
	// change and the resulting amount; amounts left nil or already equal are
	// left alone.
	OpenWallet(ctx context.Context, opening walletEntity.Wallet) error
	AdjustWallet(ctx context.Context, adjustment walletEntity.Adjustment) error
	// UnsubscribeRefundSettled reports whether the refund of a cancelled user
	// subscription was settled. SettleUnsubscribeRefund settles it: amount,
	// capped at what the order and its paid renewals cost, goes back to the
	// buyer's wallet (gift amount first for a balance-paid order), the
	// referrer loses the commission share the refund takes back, and the
	// refund marker is recorded, all in one billing transaction. A
	// subscription without an order (orderID 0) only gets the marker; a
	// second settlement fails on it.
	UnsubscribeRefundSettled(ctx context.Context, subscriptionID int64) (bool, error)
	SettleUnsubscribeRefund(ctx context.Context, userID, subscriptionID, orderID, amount int64) error
	// QuotaGiftCredited reports whether a quota task's gift for a
	// subscription was credited. CreditQuotaGift credits amount to the gift
	// balance of the subscription's owner with its gift log dated at, exactly
	// once per (task, subscription); a zero amount only records the marker.
	QuotaGiftCredited(ctx context.Context, taskID, subscriptionID int64) (bool, error)
	CreditQuotaGift(ctx context.Context, taskID, subscriptionID, userID, amount int64, at time.Time) error

	// The order reads of the subscription module's fulfillment and refund
	// quote: an order by id or number, and an order with its renewals.
	FindOrder(ctx context.Context, id int64) (*order.Order, error)
	FindOrderByNo(ctx context.Context, orderNo string) (*order.Order, error)
	FindOrderDetails(ctx context.Context, id int64) (*order.Details, error)
	// OrdersByStatusAfter pages the orders in status by ascending id: at most
	// limit (1000 when limit is outside 1..1000) of those after afterID. The
	// pending and paid reconcilers walk their orders with it.
	OrdersByStatusAfter(ctx context.Context, status uint8, afterID int64, limit int) ([]*order.Order, error)

	// The billing-owned paid-order workflow and its idempotent stages:
	// recharge credit, referral commission and final settlement.
	ActivatePaidOrder(ctx context.Context, orderNo string) error
	ActivateRecharge(ctx context.Context, orderNo string) (balance int64, err error)
	SettleOrderCommission(ctx context.Context, orderNo string, buyerID int64) error
	FinalizeOrder(ctx context.Context, orderNo string) error

	// DailyOrderReport totals one day's settled orders for the operations
	// report; plan names are resolved so the caller only formats.
	DailyOrderReport(ctx context.Context, date time.Time) (*DailyOrderReport, error)
}

type SessionStore = portal.SessionStore

type Store interface {
	InBillingTx(ctx context.Context, fn func(repository.BillingStore) error) error
	Inbox() repository.InboxRepo
	Wallet() repository.WalletRepo
}

type Transactor interface {
	InBillingTx(ctx context.Context, fn func(repository.BillingStore) error) error
}

type UserCache interface {
	ClearUserCache(ctx context.Context, userIDs ...int64) error
}

type UserSubscriptionReader = checkout.UserSubscriptionReader

type V2EventSink = v2orch.EventSink

type V2EventStreamRequest = v2orch.StreamRequest