Transaction System Specification - NFSandbox/sh_trade_backend GitHub Wiki
This article will focus on the system implementation of the Transaction system.
ORM Data Fields
Timestamps
- Compulsory
created_time
Time when buyer start a transaction
- Optional
accepted_time
Time when seller accept the transactionconfirmed_time
Time when seller confirm transaction finishedcompleted_time
Time when buyer confirm transaction finished
For more info about the design, check out Transaction Design page in Ref.
There are 3 gaps that may cause a timeout in this system. Some of them lead to Transaction Cancel, some of them lead to other operations like auto-confirm.
Seller Accept Timeout
Seller did not accept the transaction in time after buyer started a transaction.
This should lead to Transaction Cancel with cancel reason: seller_accept_timeout
Seller Confirm Timeout
Similar to Seller Accept Timeout, with cancel reason: seller_confirm_timeout
Buyer Confirm Timeout
This will not lead to the cancellation of a transaction. The default action will be auto-confirm this transaction.
Cancel Reason
Cancel reason is represented using an Enum
class:
class TradeCancelReason(Enum):
seller_rejected = "seller_rejected"
seller_accept_timeout = "seller_accept_timeout"
cancelled_by_buyer = "cancelled_by_buyer"
cancelled_by_seller = "cancelled_by_seller"
seller_confirm_timeout = "seller_confirm_timeout"
Cancel reason is Nullable, usually be set when timeout or user manually cancel a transaction.
Endpoints Design
The following only list endpoints and infos that are not be abled to directly into the code comment, and act more as a supplement to the endpoint docs and code comments. Please also read API endpoints comment before using them.
Get Transactions
Just like the Transactions in other apps, we categorized the transaction mainly by it's state:
- Active
- Pending
- Processing
- Inactive
- Completed
- Cancelled
Basically, we should provide a unified endpoint to allow users retrieving all related transactions. Endpoint receives a list of Transaction Type as parameter, which will later be used as filtering conditions.
Also, special marks active
and inactive
should be allowed to passed to endpoint as filter. And this is recommended way of using this endpoint. This is because more transaction state could be added to the systems in the future, and using active
and inactive
could improve forward compatiblity in some cases.
Another thing to notice is that: this endpoint will return transaction related to current user, both considering current user as buyer and seller. This means the transaction with this user as the seller will also appeared in the result list.
Accept Transaction
Endpoint will check:
- If item is valid to start a transaction. (This is because, if an item is valid for start a new transaction, then it should be valid to have a accepted transaction)
- If the transaction is in
pending
state.
If check passed, endpoint will update accepted_time
, update transaction state to processing
Confirm Transaction
Before a user
try to confirm a transaction
, we need to check:
- If this user seller or buyer of the transaction
- If the transaction is in
processing
state
If check passed, we need to check:
- If the user is seller
- Update
confirmed_time
, notify buyer to confirm.
- Update
- If the user is buyer
- Update
confirmed_time
, callcomplete_transaction()
- Update
Note that do not directly complete transaction using functions like complete_transaction()
. Instead, using confirm_transaction()
to finally trigger the state update of transaction state and mark it as success
.
However, some of the logic could be seperated into functions like complete_transaction()
, for example:
- Update transaction
completed_time
- Update transaction
state
- Update item
state
- Notify users.
- Etc.