repository

type AdsRepo interface {
	Insert(ctx context.Context, data *ads.Ads) error
	FindOne(ctx context.Context, id int64) (*ads.Ads, error)
	Update(ctx context.Context, data *ads.Ads) error
	Delete(ctx context.Context, id int64) error
	GetAdsListByPage(ctx context.Context, page, size int, filter ads.Filter) (int64, []*ads.Ads, error)
}

type AnnouncementRepo interface {
	Insert(ctx context.Context, data *announcement.Announcement) error
	FindOne(ctx context.Context, id int64) (*announcement.Announcement, error)
	Update(ctx context.Context, data *announcement.Announcement) error
	Delete(ctx context.Context, id int64) error
	GetAnnouncementListByPage(ctx context.Context, page, size int, filter announcement.Filter) (int64, []*announcement.Announcement, error)
}

type AuthRepo interface {
	Insert(ctx context.Context, data *auth.Auth) error
	FindOne(ctx context.Context, id int64) (*auth.Auth, error)
	Update(ctx context.Context, data *auth.Auth) error
	Delete(ctx context.Context, id int64) error
	GetAuthListByPage(ctx context.Context) ([]*auth.Auth, error)
	FindOneByMethod(ctx context.Context, platform string) (*auth.Auth, error)
	FindAll(ctx context.Context) ([]*auth.Auth, error)
}

type BillingBuilder func(conn ModuleConn) BillingRepos

type BillingRepos struct {
	Orders      OrderRepo
	OrderEvents OrderEventRepo
	Payments    PaymentRepo
	Coupons     CouponRepo
	Withdrawals UserWithdrawalRepo
	Wallets     WalletRepo
	// OrderStats feeds the identity bundle's user-statistics merge.
	OrderStats OrderStatsBridge
}

type BillingStore interface {
	Order() OrderRepo
	OrderEvent() OrderEventRepo
	Payment() PaymentRepo
	Coupon() CouponRepo
	UserWithdrawal() UserWithdrawalRepo
	Wallet() WalletRepo
	Inbox() InboxRepo
	Outbox() OutboxRepo
	Log() LogRepo
}

type BillingTransactor interface {
	InBillingTx(context.Context, func(BillingStore) error) error
}

type Builders struct {
	Platform     PlatformBuilder
	Billing      BillingBuilder
	Subscription SubscriptionBuilder
	Identity     IdentityBuilder
	Network      NetworkBuilder
	Support      SupportBuilder
	Notification NotificationBuilder
}

type ClientRepo interface {
	Insert(ctx context.Context, data *client.SubscribeApplication) error
	FindOne(ctx context.Context, id int64) (*client.SubscribeApplication, error)
	Update(ctx context.Context, data *client.SubscribeApplication) error
	Delete(ctx context.Context, id int64) error
	List(ctx context.Context) ([]*client.SubscribeApplication, error)
}

type CouponRepo interface {
	Insert(ctx context.Context, data *coupon.Coupon) error
	FindOne(ctx context.Context, id int64) (*coupon.Coupon, error)
	FindOneByCode(ctx context.Context, code string) (*coupon.Coupon, error)
	Update(ctx context.Context, data *coupon.Coupon) error
	Delete(ctx context.Context, id int64) error
	UpdateCount(ctx context.Context, code string) error
	// ReserveUsage atomically claims one coupon use. now is a Unix
	// millisecond timestamp, matching the stored start/expire columns.
	ReserveUsage(ctx context.Context, code string, now int64) (bool, error)
	ReleaseUsage(ctx context.Context, code string) error
	QueryCouponListByPage(ctx context.Context, page, size int, subscribe int64, search string) (total int64, list []*coupon.Coupon, err error)
	BatchDelete(ctx context.Context, ids []int64) error
}

type DocumentRepo interface {
	Insert(ctx context.Context, data *document.Document) error
	FindOne(ctx context.Context, id int64) (*document.Document, error)
	Update(ctx context.Context, data *document.Document) error
	Delete(ctx context.Context, id int64) error
	QueryDocumentDetail(ctx context.Context, id int64) (*document.Document, error)
	QueryDocumentList(ctx context.Context, page, size int, tag string, search string) (int64, []*document.Document, error)
	GetDocumentListByAll(ctx context.Context) (int64, []*document.Document, error)
}

type EntitlementRepo interface {
	PlanIDs(context.Context, string) ([]int64, error)
	InsertRevision(context.Context, *entitlement.Revision) error
	FindStateForUpdate(context.Context, string) (*entitlement.State, error)
	InsertState(context.Context, *entitlement.State) error
	UpdateState(context.Context, *entitlement.State) error
	FindPeriod(context.Context, string) (*entitlement.Period, error)
	InsertPeriod(context.Context, *entitlement.Period) error
	UpdatePeriod(context.Context, *entitlement.Period) error
}

type GormStore struct {
	// contains filtered or unexported fields
}

type IdentityBridges struct {
	SubscriptionCache SubscriptionCacheBridge
	SubscriptionScope SubscriptionScopeBridge
	OrderStats        OrderStatsBridge
}

type IdentityBuilder func(conn ModuleConn, bridges IdentityBridges) IdentityRepos

type IdentityRepos struct {
	Users     UserRepo
	UserAuths UserAuthRepo
	Devices   UserDeviceRepo
	UserCache UserCacheRepo
	Auths     AuthRepo
}

type IdentityStore interface {
	User() UserRepo
	UserAuth() UserAuthRepo
	UserDevice() UserDeviceRepo
	Auth() AuthRepo
	Inbox() InboxRepo
	Outbox() OutboxRepo
	Log() LogRepo
}

type IdentityTransactor interface {
	InIdentityTx(context.Context, func(IdentityStore) error) error
}

type InboxRepo = kernel.InboxRepo

type LogRepo = kernel.LogRepo

type MobileNormalization struct {
	// Converted bindings now hold their number in E.164.
	Converted int
	// Conflicts kept their stored form because another binding already
	// holds the E.164 number; Unparsable ones are not phone numbers.
	Conflicts  int
	Unparsable int
}

type ModuleConn = kernel.ModuleConn

type NetworkBuilder func(conn ModuleConn) NetworkRepos

type NetworkRepos struct {
	Nodes   NodeRepo
	Traffic TrafficRepo
	// NodeKeys feeds the subscription bundle's plan cache invalidation.
	NodeKeys NodeCacheKeyBridge
}

type NetworkStore interface {
	Node() NodeRepo
	TrafficLog() TrafficRepo
	Inbox() InboxRepo
	Outbox() OutboxRepo
	Log() LogRepo
}

type NetworkTransactor interface {
	InNetworkTx(context.Context, func(NetworkStore) error) error
}

type NodeCacheKeyBridge interface {
	ClearNodeUserListCaches(ctx context.Context, nodeIDs []int64, tags []string) error
}

type NodeRepo interface {
	// server
	InsertServer(ctx context.Context, data *node.Server) error
	FindOneServer(ctx context.Context, id int64) (*node.Server, error)
	UpdateServer(ctx context.Context, data *node.Server) error
	UpdateServerProtocolsIfCurrent(ctx context.Context, id int64, current, updated string) (bool, error)
	BatchUpdateServerLastReportedAt(ctx context.Context, reports map[int64]time.Time) error
	DeleteServer(ctx context.Context, id int64) error
	FindServerConfigOverride(ctx context.Context, serverId int64) (*node.ServerConfigOverride, error)
	SaveServerConfigOverride(ctx context.Context, data *node.ServerConfigOverride) error
	DeleteServerConfigOverride(ctx context.Context, serverId int64) error
	QueryServerList(ctx context.Context, ids []int64) (servers []*node.Server, err error)
	// node
	InsertNode(ctx context.Context, data *node.Node) error
	FindOneNode(ctx context.Context, id int64) (*node.Node, error)
	UpdateNode(ctx context.Context, data *node.Node) error
	DeleteNode(ctx context.Context, id int64) error
	// cache
	StatusCache(ctx context.Context, serverId int64) (node.Status, error)
	UpdateStatusCache(ctx context.Context, serverId int64, status *node.Status) error
	OnlineUserSubscribe(ctx context.Context, serverId int64, protocol string) (node.OnlineUserSubscribe, error)
	UpdateOnlineUserSubscribe(ctx context.Context, serverId int64, protocol string, subscribe node.OnlineUserSubscribe) error
	OnlineUserSubscribeGlobal(ctx context.Context) (int64, error)
	UpdateOnlineUserSubscribeGlobal(ctx context.Context, subscribe node.OnlineUserSubscribe) error
	// query
	FilterServerList(ctx context.Context, params *node.FilterParams) (int64, []*node.Server, error)
	FilterNodeList(ctx context.Context, params *node.FilterNodeParams) (int64, []*node.Node, error)
	ListNodes(ctx context.Context, params *node.FilterNodeParams) ([]*node.Node, error)
	ListNodesByScope(ctx context.Context, nodeIDs []int64, tags []string, enabled *bool, preload bool) ([]*node.Node, error)
	QueryNodeSorts(ctx context.Context) ([]node.SortItem, error)
	QueryServerSorts(ctx context.Context) ([]node.SortItem, error)
	UpdateNodeSort(ctx context.Context, id int64, sort int64) error
	UpdateServerSort(ctx context.Context, id int64, sort int64) error
	QueryNodeTags(ctx context.Context) ([]string, error)
	CountEnabledNodes(ctx context.Context) (int64, error)
	CountServersByReportStatus(ctx context.Context, cutoff time.Time) (int64, int64, error)
	QueryServerAddresses(ctx context.Context) ([]string, error)
	QueryEnabledNodeProtocols(ctx context.Context) ([]string, error)
	ClearServerCache(ctx context.Context, serverId int64) error
	ServerCacheGeneration(ctx context.Context, serverId int64) (int64, error)
	SetServerCache(ctx context.Context, serverId int64, key string, value any, generation int64) error
}

type NotificationBuilder func(conn ModuleConn) NotificationRepos

type NotificationRepos struct {
	TelegramTopics TelegramTopicRepo
}

type OrderEventRepo interface {
	FindOne(ctx context.Context, id int64) (*order.Event, error)
	ListAfter(ctx context.Context, orderNo string, afterID int64, limit int) ([]*order.Event, error)
	EarliestID(ctx context.Context, orderNo string) (int64, error)
	ListUnpublished(ctx context.Context, limit int) ([]*order.Event, error)
	MarkPublished(ctx context.Context, id int64, publishedAt time.Time) (bool, error)
	DeletePublishedBefore(ctx context.Context, cutoff time.Time) (int64, error)
}

type OrderRepo interface {
	Insert(ctx context.Context, data *order.Order) error
	FindOne(ctx context.Context, id int64) (*order.Order, error)
	FindOneByOrderNo(ctx context.Context, orderNo string) (*order.Order, error)
	FindOneByIdempotencyKey(ctx context.Context, key string) (*order.Order, error)
	FindOneByOrderNoForUpdate(ctx context.Context, orderNo string) (*order.Order, error)
	Update(ctx context.Context, data *order.Order) error
	Delete(ctx context.Context, id int64) error
	UpdateOrderStatusFrom(ctx context.Context, orderNo string, from, status uint8) (bool, error)
	UpdatePaymentExpectation(ctx context.Context, orderNo string, amount int64, currency string) (bool, error)
	SetPaymentTradeNoIfEmpty(ctx context.Context, orderNo, tradeNo string) (bool, error)
	BeginPaymentSession(ctx context.Context, orderNo string) (bool, error)
	CompletePaymentSession(ctx context.Context, orderNo, tradeNo, session string) (bool, error)
	MarkOrderPaid(ctx context.Context, orderNo, tradeNo string) (bool, error)
	// SetCommission records the referral commission paid for the order and
	// the referrer credited with it; a refund reverses it in proportion
	// against that referrer, whoever refers the buyer by then.
	SetCommission(ctx context.Context, orderNo string, amount, refererID int64) error
	// HasCommissionedOrder reports whether another order of the user has
	// already earned a referral commission.
	HasCommissionedOrder(ctx context.Context, userID int64, exceptOrderNo string) (bool, error)
	CountPendingByPaymentID(ctx context.Context, paymentID int64) (int64, error)
	QueryOrdersByStatusAfterID(ctx context.Context, status uint8, afterID int64, limit int) ([]*order.Order, error)
	CountUserCouponUsage(ctx context.Context, userID int64, coupon string) (int64, error)
	// CountPendingGuestOrders counts the unpaid orders a canonical guest
	// identity created at or after since and still holds before its account
	// exists.
	CountPendingGuestOrders(ctx context.Context, authType, identifier string, since time.Time) (int64, error)
	QueryOrderListByPage(ctx context.Context, page, size int, status uint8, user, subscribe int64, search string) (int64, []*order.Details, error)
	FindOneDetails(ctx context.Context, id int64) (*order.Details, error)
	FindOneDetailsByOrderNo(ctx context.Context, orderNo string) (*order.Details, error)
	QueryMonthlyOrders(ctx context.Context, date time.Time) (order.OrdersTotal, error)
	QueryDateOrders(ctx context.Context, date time.Time) (order.OrdersTotal, error)
	QueryTotalOrders(ctx context.Context) (order.OrdersTotal, error)
	QueryMonthlyUserCounts(ctx context.Context, date time.Time) (int64, int64, error)
	QueryDateUserCounts(ctx context.Context, date time.Time) (int64, int64, error)
	QueryTotalUserCounts(ctx context.Context) (int64, int64, error)
	IsUserEligibleForNewOrder(ctx context.Context, userID int64) (bool, error)
	QueryDailyOrdersList(ctx context.Context, date time.Time) ([]order.OrdersTotalWithDate, error)
	// QueryDailyReport totals one day's settled orders with the plan and
	// payment-method breakdowns the daily operations report needs.
	QueryDailyReport(ctx context.Context, date time.Time) (*order.DailyReport, error)
	QueryMonthlyOrdersList(ctx context.Context, date time.Time) ([]order.OrdersTotalWithDate, error)
}

type OrderStatsBridge interface {
	// OrderUserCountsByBucket counts distinct ordering users per date bucket
	// ("day" or "month"); isNew selects first-purchase orders.
	OrderUserCountsByBucket(ctx context.Context, isNew bool, since time.Time, until *time.Time, bucket string) (map[string]int64, error)
}

type OutboxRepo = kernel.OutboxRepo

type PaymentRepo interface {
	Insert(ctx context.Context, data *payment.Payment) error
	FindOne(ctx context.Context, id int64) (*payment.Payment, error)
	Update(ctx context.Context, data *payment.Payment) error
	Delete(ctx context.Context, id int64) error
	FindOneByPaymentToken(ctx context.Context, token string) (*payment.Payment, error)
	FindAll(ctx context.Context) ([]*payment.Payment, error)
	FindListByPage(ctx context.Context, page, size int, req *payment.Filter) (int64, []*payment.Payment, error)
	FindAvailableMethods(ctx context.Context) ([]*payment.Payment, error)
}

type PlatformBuilder = kernel.PlatformBuilder

type PlatformRepos = kernel.PlatformRepos

type PlatformStore = kernel.PlatformStore

type PlatformTransactor = kernel.PlatformTransactor

type Store interface {
	Ads() AdsRepo
	Announcement() AnnouncementRepo
	Auth() AuthRepo
	Client() ClientRepo
	Coupon() CouponRepo
	Document() DocumentRepo
	Inbox() InboxRepo
	// Outbox appends domain events that commit with the domain transaction.
	Outbox() OutboxRepo
	Log() LogRepo
	Node() NodeRepo
	Order() OrderRepo
	OrderEvent() OrderEventRepo
	Payment() PaymentRepo
	Subscribe() SubscribeRepo
	Entitlement() EntitlementRepo
	System() SystemRepo
	Task() TaskRepo
	// TelegramTopic maps forum topics in the admin Telegram group to the
	// conversation each carries.
	TelegramTopic() TelegramTopicRepo
	Ticket() TicketRepo
	TrafficLog() TrafficRepo
	User() UserRepo
	UserAuth() UserAuthRepo
	UserSubscription() UserSubscriptionRepo
	UserDevice() UserDeviceRepo
	UserWithdrawal() UserWithdrawalRepo
	SubscriptionTraffic() SubscriptionTrafficRepo
	UserCache() UserCacheRepo
	// Wallet exposes the billing view of the user table's money columns
	// (ADR-001 step 5 data debt).
	Wallet() WalletRepo

	InTx(ctx context.Context, fn func(store Store) error) error

	// Domain-scoped transactions (ADR-001 step 2): the closure receives only
	// its domain's store view, so cross-domain writes fail to compile.
	InBillingTx(ctx context.Context, fn func(BillingStore) error) error
	InSubscriptionTx(ctx context.Context, fn func(SubscriptionStore) error) error
	InIdentityTx(ctx context.Context, fn func(IdentityStore) error) error
	InNetworkTx(ctx context.Context, fn func(NetworkStore) error) error
	InPlatformTx(ctx context.Context, fn func(PlatformStore) error) error
}

type SubscribeRepo interface {
	Insert(ctx context.Context, data *subscribe.Subscribe) error
	FindOne(ctx context.Context, id int64) (*subscribe.Subscribe, error)
	Update(ctx context.Context, data *subscribe.Subscribe) error
	ReserveInventory(ctx context.Context, id int64) (bool, error)
	RestoreInventory(ctx context.Context, id int64) error
	Delete(ctx context.Context, id int64) error
	FilterList(ctx context.Context, params *subscribe.FilterParams) (int64, []*subscribe.Subscribe, error)
	FindByNodeScope(ctx context.Context, nodeIDs []int64, tags []string) ([]*subscribe.Subscribe, error)
	ClearCache(ctx context.Context, id ...int64) error
	QuerySubscribeMinSortByIds(ctx context.Context, ids []int64) (int64, error)
	QueryResetCycleSubscribeIds(ctx context.Context, resetCycle int) ([]int64, error)
	UpdateSort(ctx context.Context, data []*subscribe.Subscribe) error
	QueryGroupList(ctx context.Context) (int64, []*subscribe.Group, error)
	CreateGroup(ctx context.Context, data *subscribe.Group) error
	UpdateGroup(ctx context.Context, data *subscribe.Group) error
	DeleteGroup(ctx context.Context, id int64) error
	BatchDeleteGroup(ctx context.Context, ids []int64) error
}

type SubscriptionBuilder func(conn ModuleConn, nodes NodeCacheKeyBridge) SubscriptionRepos

type SubscriptionCacheBridge interface {
	QueryUserSubscribe(ctx context.Context, userId int64, status ...int64) ([]*usersub.SubscribeDetails, error)
	ClearSubscribeCache(ctx context.Context, data ...*usersub.Subscribe) error
	UpdateUserSubscribeCache(ctx context.Context, data *usersub.Subscribe) error
}

type SubscriptionCredentialRotation struct {
	Previous *usersub.Subscribe
	Token    string
	UUID     string
}

type SubscriptionRepos struct {
	Entitlements EntitlementRepo
	Plans        SubscribeRepo
	UserSubs     UserSubscriptionRepo
	Traffic      SubscriptionTrafficRepo
	// Clients holds the subscribe_application rows delivery renders for.
	Clients ClientRepo
	// CacheBridge feeds the identity bundle's cross-domain cache cascade.
	CacheBridge SubscriptionCacheBridge
	// ScopeBridge feeds the identity bundle's subscription-membership
	// filters.
	ScopeBridge SubscriptionScopeBridge
}

type SubscriptionScopeBridge interface {
	SubscriptionUserIDs(ctx context.Context, filter SubscriptionUserFilter) ([]int64, error)
}

type SubscriptionStore interface {
	Entitlement() EntitlementRepo
	Subscribe() SubscribeRepo
	UserSubscription() UserSubscriptionRepo
	SubscriptionTraffic() SubscriptionTrafficRepo
	Inbox() InboxRepo
	Outbox() OutboxRepo
	Log() LogRepo
}

type SubscriptionTrafficRepo interface {
	// FindTrafficResetCandidates returns the in-term subscriptions of the
	// plans a calendar reset may clear at now (started, unexpired, Active or
	// Finished) that are not yet reset for day. Which of them are due is the
	// reset cycle's decision; the rows carry what it needs.
	FindTrafficResetCandidates(ctx context.Context, planIDs []int64, now, day time.Time) ([]*usersub.Subscribe, error)
	// ResetSubscribeTrafficOnce locks the given subscriptions that are still
	// candidates, clears their traffic, reactivates the Finished ones, marks
	// them reset for day and returns them. Run it inside a subscription
	// transaction together with the reset's audit rows.
	ResetSubscribeTrafficOnce(ctx context.Context, ids []int64, now, day time.Time) ([]*usersub.Subscribe, error)
}

type SubscriptionTransactor interface {
	InSubscriptionTx(context.Context, func(SubscriptionStore) error) error
}

type SubscriptionUserFilter struct {
	UserSubscribeID *int64
	SubscribeID     *int64
	// Token matches the subscription token or UUID.
	Token    string
	Statuses []int64
}

type SupportBuilder func(conn ModuleConn) SupportRepos

type SupportRepos struct {
	Tickets       TicketRepo
	Announcements AnnouncementRepo
	Ads           AdsRepo
	Documents     DocumentRepo
}

type SystemRepo = kernel.SystemRepo

type TaskRepo = kernel.TaskRepo

type TelegramTopicRepo interface {
	Insert(ctx context.Context, data *telegramtopic.Topic) error
	FindByKindRef(ctx context.Context, chatID int64, kind uint8, refID int64) (*telegramtopic.Topic, error)
	FindByThread(ctx context.Context, chatID, threadID int64) (*telegramtopic.Topic, error)
	// UpdateThread repoints a mapping after its topic was deleted in
	// Telegram and had to be recreated.
	UpdateThread(ctx context.Context, id, threadID int64) error
	UpdateStatus(ctx context.Context, id int64, status uint8) error
}

type TicketRepo interface {
	Insert(ctx context.Context, data *ticket.Ticket) error
	FindOne(ctx context.Context, id int64) (*ticket.Ticket, error)
	Update(ctx context.Context, data *ticket.Ticket) error
	Delete(ctx context.Context, id int64) error
	QueryTicketDetail(ctx context.Context, id int64) (*ticket.Details, error)
	InsertTicketFollow(ctx context.Context, data *ticket.Follow) error
	QueryTicketList(ctx context.Context, page, size int, userId int64, status *uint8, search string) (int64, []*ticket.Ticket, error)
	UpdateTicketStatus(ctx context.Context, id, userId int64, status uint8) error
	QueryWaitReplyTotal(ctx context.Context) (int64, error)
}

type TrafficRepo interface {
	InsertBatch(ctx context.Context, data []*traffic.TrafficLog, batchSize int) error
	QueryTrafficSummary(ctx context.Context, start, end time.Time) (*traffic.TotalTraffic, error)
	TopServersTrafficByDay(ctx context.Context, date time.Time, limit int) ([]traffic.ServerTrafficRanking, error)
	TopUsersTrafficByDay(ctx context.Context, date time.Time, limit int) ([]traffic.UserTrafficRanking, error)
	QueryServerTrafficRanking(ctx context.Context, start, end time.Time) ([]traffic.ServerTrafficRanking, error)
	QueryUserTrafficRanking(ctx context.Context, start, end time.Time) ([]traffic.UserTrafficRanking, error)
	QueryTrafficLogPageList(ctx context.Context, userId, subscribeId int64, page, size int) ([]*traffic.TrafficLog, int64, error)
	QueryTrafficLogDetails(ctx context.Context, filter *traffic.TrafficLogDetailsFilter) ([]*traffic.TrafficLog, int64, error)
	DeleteBeforeBatch(ctx context.Context, end time.Time, limit int) (int64, error)
}

type UserAuthRepo interface {
	FindUserAuthMethods(ctx context.Context, userId int64) ([]*user.AuthMethods, error)
	FindUserAuthMethodsByUserIds(ctx context.Context, method string, userIds []int64) ([]*user.AuthMethods, error)
	FindUserAuthMethodByOpenID(ctx context.Context, method, openID string) (*user.AuthMethods, error)
	// FindEmailAlias returns an email binding of a live account that reaches
	// the same mailbox as email under another spelling.
	FindEmailAlias(ctx context.Context, email string) (*user.AuthMethods, error)
	ValidateEmailIdentityUniqueness(ctx context.Context) error
	FindUserAuthMethodByPlatform(ctx context.Context, userId int64, platform string) (*user.AuthMethods, error)
	FindUserAuthMethodByUserId(ctx context.Context, method string, userId int64) (*user.AuthMethods, error)
	InsertUserAuthMethods(ctx context.Context, data *user.AuthMethods) error
	UpdateUserAuthMethods(ctx context.Context, data *user.AuthMethods) error
	DeleteUserAuthMethods(ctx context.Context, userId int64, platform string) error
	UpdateUserAuthMethodOwner(ctx context.Context, authType, identifier string, userId int64) error
	DeleteUserAuthMethodByIdentifier(ctx context.Context, authType, identifier string) error
	UpsertUserAuthMethod(ctx context.Context, data *user.AuthMethods) error
	// NormalizeMobileIdentifiers converts the phone numbers stored in
	// another form than E.164 (the admin panel used to store
	// "<area>-<number>") to E.164. It is idempotent; a number whose E.164
	// form another binding already holds stays as it is and is reported.
	NormalizeMobileIdentifiers(ctx context.Context) (MobileNormalization, error)
}

type UserCacheRepo interface {
	ClearUserCache(ctx context.Context, data ...*user.User) error
	ClearSubscribeCache(ctx context.Context, data ...*usersub.Subscribe) error
	ClearDeviceCache(ctx context.Context, data ...*user.Device) error
	ClearAuthMethodCache(ctx context.Context, data ...*user.AuthMethods) error
	BatchClearRelatedCache(ctx context.Context, data *user.User) error
	// Deprecated: UpdateUserCache only ever cleared the cache; use
	// ClearUserCache.
	UpdateUserCache(ctx context.Context, data *user.User) error
	UpdateUserSubscribeCache(ctx context.Context, data *usersub.Subscribe) error
}

type UserDeviceRepo interface {
	InsertDevice(ctx context.Context, data *user.Device) error
	FindOneDevice(ctx context.Context, id int64) (*user.Device, error)
	// FindDeviceForAuth always reads current state, bypassing cached projections.
	FindDeviceForAuth(ctx context.Context, id int64) (*user.Device, error)
	// TouchDevice only updates access metadata for the same enabled owner.
	TouchDevice(ctx context.Context, id, userID int64, ip, userAgent string) (bool, error)
	FindOneDeviceByIdentifier(ctx context.Context, id string) (*user.Device, error)
	SetDeviceEnabled(ctx context.Context, id int64, enabled bool) error
	SetDeviceOnline(ctx context.Context, id int64, online bool) error
	DeleteDevice(ctx context.Context, id int64) error
	QueryDeviceList(ctx context.Context, userid int64) ([]*user.Device, int64, error)
	QueryDevicePageList(ctx context.Context, userid, subscribeId int64, page, size int) ([]*user.Device, int64, error)
	FindDeviceOnlineRecord(ctx context.Context, userId int64, startTime, endTime string) (*user.DeviceOnlineRecord, error)
	InsertDeviceOnlineRecord(ctx context.Context, data *user.DeviceOnlineRecord) error
}

type UserRepo interface {
	Insert(ctx context.Context, data *user.User) error
	FindOne(ctx context.Context, id int64) (*user.User, error)
	FindAccountState(ctx context.Context, id int64) (*user.AccountState, error)
	FindOneForUpdate(ctx context.Context, id int64) (*user.User, error)
	FindOneByEmail(ctx context.Context, email string) (*user.User, error)
	FindOneByReferCode(ctx context.Context, referCode string) (*user.User, error)
	// UpdateColumns writes only the named columns. There is deliberately no
	// whole-row update: a snapshot saved back whole reverts whatever changed
	// meanwhile, including an administrator's disable or demotion.
	UpdateColumns(ctx context.Context, id int64, columns map[string]any) error
	UpgradePasswordHash(ctx context.Context, id int64, currentHash, password, algo, salt string) (bool, error)
	Delete(ctx context.Context, id int64) error
	BatchDeleteUser(ctx context.Context, ids []int64) error
	QueryPageList(ctx context.Context, page, size int, filter *user.UserFilterParams) ([]*user.User, int64, error)
	FindUsersByIds(ctx context.Context, ids []int64) ([]*user.User, error)
	FindEnabledUserIDs(ctx context.Context, ids []int64) ([]int64, error)
	CountAffiliates(ctx context.Context, refererId int64) (int64, error)
	QueryAffiliateList(ctx context.Context, refererId int64, page, size int) ([]*user.User, int64, error)
	QueryAdminUsers(ctx context.Context) ([]*user.User, error)
	CountEnabledUsers(ctx context.Context) (int64, error)
	// QueryRegisterUserTotal counts the registered accounts; the ByDate and
	// ByMonthly variants count those registered on date's day or month.
	QueryRegisterUserTotal(ctx context.Context) (int64, error)
	QueryRegisterUserTotalByDate(ctx context.Context, date time.Time) (int64, error)
	QueryRegisterUserTotalByMonthly(ctx context.Context, date time.Time) (int64, error)
	// Deprecated: use QueryRegisterUserTotal.
	QueryResisterUserTotal(ctx context.Context) (int64, error)
	// Deprecated: use QueryRegisterUserTotalByDate.
	QueryResisterUserTotalByDate(ctx context.Context, date time.Time) (int64, error)
	// Deprecated: use QueryRegisterUserTotalByMonthly.
	QueryResisterUserTotalByMonthly(ctx context.Context, date time.Time) (int64, error)
	QueryEmailRecipients(ctx context.Context, filter *user.EmailRecipientFilter) ([]string, error)
	CountEmailRecipients(ctx context.Context, filter *user.EmailRecipientFilter) (int64, error)
	QueryDailyUserStatisticsList(ctx context.Context, date time.Time) ([]user.UserStatisticsWithDate, error)
	QueryMonthlyUserStatisticsList(ctx context.Context, date time.Time) ([]user.UserStatisticsWithDate, error)
}

type UserSubscriptionRepo interface {
	// LockUserSerial serializes subscription-creating flows per user inside
	// the current transaction (seed-and-lock on the subscription domain's
	// serial table). It replaces the fulfillment stage's cross-domain
	// user-row lock.
	LockUserSerial(ctx context.Context, userID int64) error
	InsertSubscribe(ctx context.Context, data *usersub.Subscribe) error
	FindOneSubscribe(ctx context.Context, id int64) (*usersub.Subscribe, error)
	FindOneSubscribeForUpdate(ctx context.Context, id int64) (*usersub.Subscribe, error)
	FindOneSubscribeByOrderId(ctx context.Context, orderId int64) (*usersub.Subscribe, error)
	FindOneSubscribeByToken(ctx context.Context, token string) (*usersub.Subscribe, error)
	FindOneSubscribeByTokenForUpdate(ctx context.Context, token string) (*usersub.Subscribe, error)
	// UpdateSubscribeColumns writes only the named columns of data.Id (plus
	// updated_at); concurrent writes to every other column survive. Callers
	// that derive a column from the row's current value read the row with
	// FindOneSubscribeForUpdate in the same subscription transaction first.
	// A provider-managed row accepts only usersub.LocalControlColumns and is
	// reactivated only inside its provider period; anything else fails with
	// usersub.ErrProviderManaged.
	UpdateSubscribeColumns(ctx context.Context, data *usersub.Subscribe, columns ...string) error
	// RotateSubscribeCredentials gives each subscription the token and UUID
	// of its rotation in batched column updates, and invalidates the cache
	// entries of the previous credentials as well as the new ones.
	RotateSubscribeCredentials(ctx context.Context, rotations []SubscriptionCredentialRotation) error
	// ApplyEntitlementProjection is only called with a locked provider row.
	ApplyEntitlementProjection(ctx context.Context, data *usersub.Subscribe) error
	DeleteSubscribeById(ctx context.Context, id int64) error
	// ClearSubscribeCache drops the cached entries of the subscriptions: by
	// id, by token and their owners' subscription lists.
	ClearSubscribeCache(ctx context.Context, data ...*usersub.Subscribe) error
	BatchUpdateUserSubscribeWithTraffic(ctx context.Context, deltas []trafficEntity.SubscribeTrafficDelta) error
	// FindUsersSubscribeBySubscribeIds returns the plans' subscriptions a
	// node may serve now (usersub.ServableCondition).
	FindUsersSubscribeBySubscribeIds(ctx context.Context, subscribeIds []int64) ([]*usersub.Subscribe, error)
	FindUserSubscribesByStatus(ctx context.Context, status ...int64) ([]*usersub.Subscribe, error)
	FindSubscribesByIds(ctx context.Context, ids []int64) ([]*usersub.Subscribe, error)
	// FindSubscribeDetailsByIds loads the subscriptions with their plans in
	// one round trip per table; missing ids are absent from the result.
	FindSubscribeDetailsByIds(ctx context.Context, ids []int64) ([]*usersub.SubscribeDetails, error)
	// FindSubscribeDetailsByUserIds loads every subscription of the users,
	// whatever its status, with its plan: one round trip per table however
	// many users there are.
	FindSubscribeDetailsByUserIds(ctx context.Context, userIds []int64) ([]*usersub.SubscribeDetails, error)
	CountQuotaConsumingSubscriptions(ctx context.Context, userId, subscribeId int64) (int64, error)
	HasBlockingSubscription(ctx context.Context, userId int64) (bool, error)
	CountUserSubscribesBySubscribeIdAndStatus(ctx context.Context, subscribeId int64, status ...int64) (int64, error)
	QueryActiveSubscriptions(ctx context.Context, subscribeId ...int64) (map[int64]int64, error)
	QueryUserSubscribe(ctx context.Context, userId int64, status ...int64) ([]*usersub.SubscribeDetails, error)
	FindOneSubscribeDetailsById(ctx context.Context, id int64) (*usersub.SubscribeDetails, error)
	FindOneUserSubscribe(ctx context.Context, id int64) (*usersub.SubscribeDetails, error)
	FindTrafficExceededSubscribes(ctx context.Context) ([]*usersub.Subscribe, error)
	FindExpiredSubscribes(ctx context.Context, now time.Time) ([]*usersub.Subscribe, error)
	// FindExpiringSubscribes returns active subscriptions expiring inside the
	// window, for the pre-expiry reminder.
	FindExpiringSubscribes(ctx context.Context, from, to time.Time) ([]*usersub.Subscribe, error)
	MarkSubscribesFinished(ctx context.Context, ids []int64, status uint8, finishedAt time.Time) error
	QuerySubscribeIdsByFilter(ctx context.Context, filter *usersub.SubscribeFilter) ([]int64, error)
	CountSubscribesByFilter(ctx context.Context, filter *usersub.SubscribeFilter) (int64, error)
}

type UserWithdrawalRepo interface {
	InsertWithdrawal(ctx context.Context, data *walletEntity.Withdrawal) error
	FindWithdrawalForUpdate(ctx context.Context, id int64) (*walletEntity.Withdrawal, error)
	QueryWithdrawalList(ctx context.Context, userID int64, status *uint8, page, size int) ([]*walletEntity.Withdrawal, int64, error)
	UpdateWithdrawalStatus(ctx context.Context, id int64, from, to uint8, reason string) (bool, error)
}

type WalletRepo interface {
	// FindOneForUpdate locks and returns the wallet row, seeding it from a
	// zero state when the account has none yet.
	FindOneForUpdate(ctx context.Context, userId int64) (*walletEntity.Wallet, error)
	// FindWallet and FindWalletsByUserIds are the plain (non-locking) reads
	// of the wallet table for display composition; a missing row reads as
	// nil (single) or is absent from the map (batch).
	FindWallet(ctx context.Context, userId int64) (*walletEntity.Wallet, error)
	FindWalletsByUserIds(ctx context.Context, userIds []int64) (map[int64]*walletEntity.Wallet, error)
	// UpdateBalanceFields persists the balance and gift columns;
	// UpdateCommission persists the commission column.
	UpdateBalanceFields(ctx context.Context, data *walletEntity.Wallet) error
	UpdateCommission(ctx context.Context, data *walletEntity.Wallet) error
}