|Si.dZddlmZddlmZddlmZddlmZmZddl m Z m Z m Z m Z mZddlmZmZmZmZmZmZmZdd lmZmZmZdd lmZdd lmZdd lm Z e r dd l!m"Z"ddl#m$Z$edGddZ%eGddZ&GddZ'y)z&Wallet service for point transactions.) annotations) dataclass)datetime)Decimal ROUND_HALF_UP) TYPE_CHECKINGAnyDictListOptional)HookExecutionErrorHookRejectionErrorInsufficientBalanceErrorInvalidParamsErrorInvalidPointTypeErrorUserNotFoundErrorWalletOperationError) HookManagerHookType PostHookError) HookContext)get_global_registry)transfer_completed)Model)WalletRepositoryProtocolT)frozenceZdZUdZded<ded<ded<ded<ded <d ed <d ed <ded <ded<ded<ded<y)TransactionRecordz'Represents a wallet transaction record. int | Noneidstrwtypeintiiduidtyperamountbalance trans_typedescrcdateDict[str, Any] extra_dataN)__name__ __module__ __qualname____doc____annotations__N/home/cursorai/projects/django-wallet-utils/src/django_wallet_utils/service.pyrrs?1N J H H I O  J Jr5rcjeZdZUdZded<dZded<dZded<dZded <dZd ed <dZ d ed <ddZ y)TransactionResulta Result of a wallet transaction with hook execution status. Attributes: success: Whether the transaction was successful transaction_id: Transaction ID if successful error_code: Error code if transaction failed (PRE hook rejection or validation error) error_message: Human-readable error message if failed error_details: Additional error context if failed post_hook_errors: List of errors from POST hooks (transaction still successful) boolsuccessNr transaction_id str | None error_code error_messagezDict[str, Any] | None error_detailszList[PostHookError] | Nonepost_hook_errorsc\|j|jd}|jr+|j|j|jxsid|d<|j rJ|j Dcgc]1}|j |j|j|jd3c}|d<|Scc}w)z(Convert to dictionary for API responses.)r:r;codemessagedetailserrorhookrCrDrEwarnings) r:r;r=r>r?r@ hook_namerDrE)selfresulterrs r6to_dictzTransactionResult.to_dictDs||"11  ??----3F7O   00"1C  MMNN"{{"{{  1"F:  "s+6B))returnr-) r/r0r1r2r3r;r=r>r?r@rNr4r5r6r8r8/sH M!%NJ%!J ! $M:$+/M(/3707r5r8ceZdZdZhdZdddZ d ddZ d ddZ d ddZddZ dd Z d dd Z dd Z d dd Z edd Zy) WalletServicez Python port of the legacy WalletPoint PHP class. The service works with a WalletRepositoryProtocol that only needs to define point types. All balance operations and transaction recording are handled automatically. > r!r%r&r'r,r+r#r(r)r*cd||_||_|rtt|_yd|_y)a Initialize the wallet service. Args: repository: WalletRepositoryProtocol instance that defines point types and provides User model enable_hooks: Whether to enable hook execution (default: False for backward compatibility) N) repository enable_hooksrr hook_manager)rKrSrTs r6__init__zWalletService.__init__vs.%(BNK(;(=>TXr5Nc|i}|jd|||||d||jj}|j|d} t dt | } |j td| zt} |jrX|jrL|jj||} td||| |||||  } |jj|  |jj)||| d }t/d|||d | ||||j1|jd i } |jj3|}g}|jr>|jr2td||| |||||d|i } |jj5| }|jrtd||r|SdS|S#t$r7} td| j | j"| j$ cYd} ~ Sd} ~ wt&$rwxYw#t*$r} t-d | | d} ~ wwxYw#t*$r} t-d| | d} ~ wwxYw)a Add points to a user wallet balance. Args: user_id: The user ID point_type: The type of wallet to add to (e.g., "credit_balance") amount: The amount to add (must be positive) remarks: Description/remarks for the transaction trans_type: Transaction type code (integer constant, optional) params: Extra parameters dict with optional 'data' key for additional fields iid: Initiator ID - ID of the user who performed this transaction (-100 for system) Returns: The transaction ID (legacy behavior) or TransactionResult (if hooks are enabled) Raises: InvalidPointTypeError: If point type doesn't exist InvalidParamsError: If params are invalid WalletOperationError: If the operation fails HookRejectionError: If a PRE hook rejects the transaction NaddFr0.1rounding) operationuser_id point_typer(remarksr*r%paramscurrent_balancer:r=r>r?allow_negativezError adding user point: cdata r!r#r%r&r'r(r)r*r+r,r.#Error creating transaction record: r; r]r^r_r(r`r*r%rarbmetadataTr:r;r@)_validate_add_deduct_pointrSget_point_typesgetmaxr$quantizerrrTrUget_user_balancerexecute_pre_hooksrr8r=rDrErupdate_balance Exceptionrr_get_current_datetimecreate_transaction_recordexecute_post_hooks)rKr^r_r(r`r*rar% point_typesdecimal_placesamount_roundedrbcontexte balance_afterrecordr;r@s r6 add_pointzWalletService.add_points> >F '' 7JUF oo557 $Q7QN 34 >)ITab   !2!2"oo>>w SO!%%% / G !!33G< O OO::7JP^ot:uM #!!!,,.zz&"-   Y!__FFvNN    !2!2!%%% -*N; G $00CCGL    $-5E!1 LP  y& (! ||"#))"#))  &    O&)B1#'FGQ N O& Y&)LQC'PQWX X YsN G&H:H2 H,H;HH H/H**H/2 I;I  Ic |i}|jd||||||||jj} | j|d} t dt | } |j td| zt} |jr[|jrO|jj||} td||| ||||| d|i } |jj|  |jj)||| | \}}|s~|jj||} t/| }t/|}|jr"td d d|d| dd|d| d||d St1d|d| dd|d| d||t3d|||d| ||||j5|jdi } |jj7|}g}|jr?|jr3td||| |||||||d } |jj9| }|jrtd||r|SdS|S#t$r7}td |j |j"|j$ cYd}~Sd}~wt&$rwxYw#t*$r}t-d ||d}~wwxYw#t*$r}t-d||d}~wwxYw)a Deduct points from a user wallet balance using atomic SQL operation. Uses SQL WHERE clause to prevent race conditions and ensure balance sufficiency. Args: user_id: The user ID point_type: The type of wallet to deduct from amount: The amount to deduct (must be positive) remarks: Description/remarks for the transaction trans_type: Transaction type code (integer constant, optional) allow_negative: Whether to allow negative balance (default: False) params: Extra parameters dict with optional 'data' key for additional fields iid: Initiator ID - ID of the user who performed this transaction (-100 for system) Returns: The transaction ID (legacy behavior) or TransactionResult (if hooks are enabled) Raises: InsufficientBalanceError: If insufficient balance and allow_negative=False InvalidPointTypeError: If point type doesn't exist InvalidParamsError: If params are invalid WalletOperationError: If the operation fails HookRejectionError: If a PRE hook rejects the transaction NdeductrYrrZr[rerjFrcrdzError deducting user point: INSUFFICIENT_BALANCEz6Insufficient balance for this transaction. Available: .fz , Requested: ) available requesteddrgrhri)r;reTrl)rmrSrnrorpr$rqrrrTrUrrrrsrr8r=rDrErdeduct_balance_atomicrurfloatrrrvrwrx)rKr^r_r(r`r*rerar%ryrzr{rbr|r}r:r~rrrr;r@s r6 deduct_pointzWalletService.deduct_pointsH >F '' gz67JX^ oo557 $Q7QN 34 >)ITab   !2!2"oo>>w SO!"%%% /*N; G !!33G< R%)__%J%J^N&K& "G]"oo>>w SOo.If I  (!5$Z[defgufvvwdwZxy//8>:J!8K.L#N&/%.#  /LYWXYgXhhiViLjk""+An-=Q+>!?A'' #!!!,,.zz&"-   Y!__FFvNN    !2!2!"%%% -,:n] G $00CCGL    $-5E!1 LP  s& (! ||"#))"#))  &   R&)EaS'IJPQ Q RZ Y&)LQC'PQWX X YsN I )"JJ9 J,JJJ J6"J11J69 KKKc Xddlm} ddlm} || }|sd}|dkr t dd |j |||j || |j j|d |jr`|jrT|j j||} t!d|||||| ||d|xsii|  } |jj#||xsi}|j}d |_ | j/5di|d|ii}|j1||||d|d|d || }di|d|ii}|j3||||d|d||| }|j j||}|j j||}|j5|}|j5|}ddd||_ d}d||||||||d }|r|jr|t!d|||||| ||d|i||||||d }|jj7|}|r@|Dcgc]1}|j8|j&|j(|j*d!3c}|d"<t;j<|j>|||||||# |S#t$r8} d tt| jvrtd |d|| d} ~ wwxYw#t$$r1} d | j&| j(| j*ddcYd} ~ Sd} ~ wt,$rwxYw#1swYexYw#||_ wxYwcc}w)$u Transfer points between two users atomically. The transfer is wrapped in a database transaction to ensure both deduction and addition succeed or fail together. Supports same-type transfers (e.g., cash → cash) and cross-type transfers (e.g., cash → credit). Args: from_user_id: The sender's user ID to_user_id: The recipient's user ID from_point_type: The point type to deduct from sender to_point_type: The point type to add to recipient amount: The amount to transfer (must be positive) remarks: Description for the transaction (default: "Point transfer") trans_type: Transaction type code (defaults to WALLET_TRANSFER) metadata: Optional metadata dict to attach to both transaction records iid: Initiator ID - ID of the user who performed this transaction (-100 for system) Returns: Dict with keys: - success: True if successful, False if rejected by hook - transfer_id: Unique transfer identifier (from_transaction_id:to_transaction_id) - from_transaction_id: Transaction ID for sender's deduction - to_transaction_id: Transaction ID for recipient's addition - from_user_id: Sender's user ID - to_user_id: Recipient's user ID - from_point_type: Sender's point type - to_point_type: Recipient's point type - amount: Transfer amount - from_balance: Sender's balance after transfer - to_balance: Recipient's balance after transfer - error: Error details if rejected (only if hooks enabled) - warnings: POST hook errors if any (only if hooks enabled) Raises: UserNotFoundError: If recipient doesn't exist InsufficientBalanceError: If sender has insufficient balance (only if hooks disabled) InvalidPointTypeError: If point type doesn't exist InvalidParamsError: If parameters are invalid WalletOperationError: If the transfer fails HookRejectionError: If a PRE hook rejects the transaction (only if hooks disabled) Example: # Same point type transfer result = service.transfer_points( from_user_id=1, to_user_id=2, from_point_type="cash_balance", to_point_type="cash_balance", amount=Decimal("100.00"), remarks="Transfer to friend", ) # Cross-type transfer result = service.transfer_points( from_user_id=1, to_user_id=2, from_point_type="cash_balance", to_point_type="credit_balance", amount=Decimal("50.00"), remarks="Cash to credit conversion", ) r) transactionr )WALLET_TRANSFERNzPoint transferz Transfer amount must be positivetransfer_pointsmethodF) for_update DoesNotExistzRecipient user with ID z does not exist)r^transferrg) r]r^r_r(r`r*r% to_user_id to_point_typerarbrB)r:rF transfer_toz (to user ))r^r_r(r`r*rerar% transfer_fromz (from user )r^r_r(r`r*rar%:T) r: transfer_idfrom_transaction_idto_transaction_id from_user_idrfrom_point_typerr( from_balance to_balance)rrrrr) r]r^r_r(r`r*r%rrrarbrkrGrI) senderrrrrrr( from_record to_recordrk) django.dbrtransaction_typesrr_validate_user_point_typerS_get_balance_objectrur"r'r/rrTrUrrrrsrr=rDrEratomicrrget_transaction_by_idrxrJrsend __class__)rKrrrrr(r`r*rkr%db_transactionrr}rbr|transfer_metadataoriginal_enable_hooks from_paramsr to_paramsrrrrrrrLr@rMs r6rzWalletService.transfer_pointssV <6  (J&G Q;$%GPab b &&|_E &&z=A  OO / / u / M   !2!2"oo>>|_]O!$$*%%+B/ / G !!33G<%N!% 1 1!% 6&&(%'W*;'W]J'WX &*&7&7(.!&iz*Q?)#(&'8 '#$%Y(9%Y?L%YZ $(NN&,!&i|L>C)$%3%! $?? o^ !__==j-X #889LM  667HI A)F!6D --Q/@.AB !2($.*($   !T%6%6!$$*%%+ 12 ,#.+>):$0", G( $00CCGL  0& 0 !$ ##&;;#&;;  0&z" >>#%!+'#&  q T!W%5%5!66'-j\I&   6& $ ! #$99#$99&  )(F!6D Z&sa J:K/L?B,L+L6L' K 3KK L &K=7L =L LL L$cb|jj}||vrtd|d|y)z Validate whether the given point type is valid. Raises: InvalidPointTypeError: If point type doesn't exist No such point ( ) exists!r_N)rSrnr)rKr^r_ valid_typess r6rz'WalletService._validate_user_point_types>oo557 [ ('!*Y7J  )r5c |j|||dk(rdnd} t|tstd| d| d|vr|drt|dtstd| d| g} |dj D]"} | |j vs| j | $| r%d j| } td| d | d | y y y ) z Validate parameters for add/deduct point operations. Raises: InvalidPointTypeError: If point type doesn't exist InvalidParamsError: If params are invalid rXrrzInvalid params for z(), it must be a dict!rrgzInvalid params["data"] for z, z-(), some of the data parameters are invalid: !N)r isinstancedictrkeysRESERVED_FIELDSappendjoin) rK add_deductr^r_r(r`r*rerarinvalid_fieldsfield fields_strs r6rmz(WalletService._validate_add_deduct_points$ &&w ; *e 3&$'$':6(BX%Ybhi i V vfVnd3(1&9OPY_ N,,.D000"))%0/!YY~6 (1&9fgqfrrst!!/ r5c |jj} | jj} || j |} |A|jj } || vrt d|d|| j |} || j |} |%|dvrtd |d | j | } || j | } |7t|trtj|}| j | } |7t|trtj|}| j |} | jd} | dkDr| | d} || d|} g} | D]}t|j|j|j |j"|j$|j&|j(|j*|j,t/|j0dr|j0j3nt|j0|j4xsi }| j7|| S)a Retrieve wallet transaction history with various filters. Args: user_id: Filter by user ID (uid field) point_type: Filter by wallet/point type (wtype field) trans_type: Filter by transaction type code (trans_type field, integer constant) transaction_type: Filter by transaction type ('c' for credit, 'd' for debit) (type field) iid: Filter by initiator ID (iid field) - user who performed the transaction (-100 for system) start_date: Filter transactions from this date (inclusive) (cdate field) end_date: Filter transactions until this date (inclusive) (cdate field) limit: Maximum number of records to return offset: Number of records to skip (for pagination) Returns: List of TransactionRecord objects Example: # Get all transactions for a user transactions = service.get_transaction_history(user_id=123) # Get credit transactions for a specific point type transactions = service.get_transaction_history( user_id=123, point_type="credit_balance", transaction_type="c", ) # Get transactions by transaction type code from django_wallet_utils.transaction_types import WALLET_DEPOSIT transactions = service.get_transaction_history( user_id=123, trans_type=WALLET_DEPOSIT, ) # Get transactions in date range from datetime import datetime, timedelta end = datetime.now() start = end - timedelta(days=30) transactions = service.get_transaction_history( user_id=123, start_date=start, end_date=end, limit=100, ) Nr&rrrr#r*rfrInvalid transaction_type: &. Must be 'c' (credit) or 'd' (debit).r'r% cdate__gte cdate__ltez-cdater isoformatrh)rSget_wallet_modelobjectsallfilterrnrrrr"r fromisoformatorder_byrr!r#r%r&r'r(r)r*r+hasattrr,rr.r)rKr^r_r*transaction_typer% start_dateend_datelimitoffset wallet_modelquerysetrrecordsobjrs r6get_transaction_historyz%WalletService.get_transaction_historys8t779 ''++-  73H  !//99;K,+%j\;  Z8H  !*=H  'z1(01A0BBhi ,<=H ?3/H  !*c*%33J? *=H  (C(#11(;(;H$$X. A:(H  'HC&66iiGGGGXXzz >>ii/6syy+/Ncii))+TWX[XaXaTb>>/R F NN6 " r5c|jj} |jj|}t |j |j |j|j|j|j|j|j|jt|jdr|jj!nt#|j|j$xsi S#|j&$rYywxYw)z Get a single transaction by its ID. Args: transaction_id: The transaction ID Returns: TransactionRecord if found, None otherwise )r!rrhN)rSrrrorr!r#r%r&r'r(r)r*r+rr,rr"r.r)rKr;rrs r6rz#WalletService.get_transaction_by_idPs779  &&**n*=C$66iiGGGGXXzz >>ii/6syy+/Ncii))+TWX[XaXaTb>>/R  ((  sCC99D  D c|jj}|jj} || j |} |A|jj } || vrt d|d|| j |} || j |} |%|dvrtd|d | j | } || j | } |7t|trtj|}| j | } |7t|trtj|}| j | } | jS)a Count transactions matching the given filters. Args: user_id: Filter by user ID (uid field) point_type: Filter by wallet/point type (wtype field) trans_type: Filter by transaction type code (trans_type field, integer constant) transaction_type: Filter by transaction type ('c' for credit, 'd' for debit) (type field) iid: Filter by initiator ID (iid field) - user who performed the transaction (-100 for system) start_date: Filter transactions from this date (inclusive) (cdate field) end_date: Filter transactions until this date (inclusive) (cdate field) Returns: Number of transactions matching the filters rrrrrrrrrrrrr) rSrrrrrnrrrr"rrcount) rKr^r_r*rr%rrrrrs r6count_transactionsz WalletService.count_transactionsmsd2779 ''++-  73H  !//99;K,+%j\;  Z8H  !*=H  'z1(01A0BBhi ,<=H ?3/H  !*c*%33J? *=H  (C(#11(;(;H~~r5cFtjjS)z*Get current datetime as ISO format string.)rnowrr4r5r6rvz#WalletService._get_current_datetimes||~''))r5)F)rSz'WalletRepositoryProtocol'rTr9)NN)r^r$r_r"r(rr`r"r*r raOptional[Dict[str, Any]]r%r$rOint | TransactionResult)NFNr)r^r$r_r"r(rr`r"r*r rer9rarr%r$rOr)NNr)rr$rr$rr"rr"r(rr`r"r*r rkrr%r$rOr-)r^r$r_r"rONone)rr"r^r$r_r"r(rr`r"r*r rer9rar-rOr) NNNNNNNNr)r^r r_r<r*r rr<r%r rdatetime | str | Nonerrrr rr$rOzlist[TransactionRecord])r;r$rOzTransactionRecord | None)NNNNNNN)r^r r_r<r*r rr<r%r rrrrrOr$)rOr")r/r0r1r2rrVrrrrrmrrr staticmethodrvr4r5r6rQrQ`s O Y$"&+/{{{ {  {  {){{ !{F"&$+/^^^ ^  ^  ^^)^^ !^N!%-1yyy y  y  yyy+yy yv ))) )  )  )))) )Z#!%!%'+,0*. ||| | % |  |*|(||| !||>#!%!%'+,0*.@ @ @  @ % @  @ *@ (@  @ D**r5rQN)(r2 __future__r dataclassesrrdecimalrrtypingrr r r r exceptionsrrrrrrrdjango_package_hooksrrrhooksrrrsignalsrdjango.db.modelsrrSrrr8rQr4r5r6rs,"!*;;FE!'&4 $     -- -`R *R *r5