xiaokang/lotteryLaravel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 新增玩家管理与转账对账相关功能

Browse Source 
1.  新增完整的后台玩家管理CRUD接口，包括列表、创建、详情、更新、删除
2.  新增转账订单冲正和人工处理功能，支持待对账订单状态变更
3.  扩展钱包流水和转账订单的状态支持，新增reversed、manually_processed等状态
4.  新增玩家API数据统一输出类，标准化玩家信息返回格式
This commit is contained in:
kang
2026-05-14 10:43:33 +08:00
parent c9c1fecfcf
commit d877b5e37a
19 changed files with 569 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

0
.trae/.ignore Normal file
View File

51
app/Http/Controllers/Api/V1/Admin/Player/AdminPlayerDestroyController.php Normal file
View File

@@ -0,0 +1,51 @@
<?php
namespace App\Http\Controllers\Api\V1\Admin\Player;
use App\Models\Player;
use App\Lottery\ErrorCode;
use App\Support\ApiResponse;
use Illuminate\Http\Request;
use Illuminate\Http\JsonResponse;
use App\Http\Controllers\Controller;
use Illuminate\Database\Eloquent\Relations\HasMany;
/** DELETE /api/v1/admin/players/{player} */
final class AdminPlayerDestroyController extends Controller
{
public function __invoke(Request $request, Player $player): JsonResponse
{
$hasWallets = Player::query()
->whereKey($player->getKey())
->whereHas('wallets', static fn (HasMany $q) => $q->whereRaw('balance != 0'))
->exists();
if ($hasWallets) {
return ApiResponse::error(
'该玩家钱包仍有余额，请先清空后再删除',
ErrorCode::ValidationFailed->value,
null,
422,
);
}
$hasTickets = Player::query()
->whereKey($player->getKey())
->whereHas('ticketOrders')
->exists();
if ($hasTickets) {
return ApiResponse::error(
'该玩家存在注单记录，无法删除',
ErrorCode::ValidationFailed->value,
null,
422,
);
}
$player->wallets()->delete();
$player->delete();
return ApiResponse::success(['deleted' => true]);
}
}

43
app/Http/Controllers/Api/V1/Admin/Player/AdminPlayerIndexController.php Normal file
View File

@@ -0,0 +1,43 @@
<?php
namespace App\Http\Controllers\Api\V1\Admin\Player;
use App\Models\Player;
use Illuminate\Http\Request;
use App\Support\ApiResponse;
use Illuminate\Http\JsonResponse;
use App\Http\Controllers\Controller;
use App\Support\AdminApiList;
use App\Support\PlayerApiPresenter;
/** GET /api/v1/admin/players */
final class AdminPlayerIndexController extends Controller
{
public function __invoke(Request $request): JsonResponse
{
$p = AdminApiList::readPaging($request);
$keyword = trim((string) $request->query('keyword', ''));
$status = $request->query('status');
$q = Player::query()
->with(['wallets' => static fn ($wq) => $wq->orderBy('wallet_type')->orderBy('currency_code')])
->orderByDesc('id');
if ($keyword !== '') {
$term = '%'.addcslashes($keyword, '%_\\').'%';
$q->where(static function ($sub) use ($term): void {
$sub->where('site_player_id', 'like', $term)
->orWhere('username', 'like', $term)
->orWhere('nickname', 'like', $term);
});
}
if ($status !== null && $status !== '') {
$q->where('status', (int) $status);
}
$paginator = $q->paginate($p['perPage'], ['*'], 'page', $p['page']);
return AdminApiList::json($paginator, fn (Player $player): array => PlayerApiPresenter::listItem($player));
}
}

17
app/Http/Controllers/Api/V1/Admin/Player/AdminPlayerShowController.php Normal file
View File

@@ -0,0 +1,17 @@
<?php
namespace App\Http\Controllers\Api\V1\Admin\Player;
use App\Models\Player;
use App\Support\ApiResponse;
use Illuminate\Http\JsonResponse;
use App\Http\Controllers\Controller;
/** GET /api/v1/admin/players/{player} */
final class AdminPlayerShowController extends Controller
{
public function __invoke(Player $player): JsonResponse
{
return ApiResponse::success(PlayerApiPresenter::listItem($player));
}
}

43
app/Http/Controllers/Api/V1/Admin/Player/AdminPlayerStoreController.php Normal file
View File

@@ -0,0 +1,43 @@
<?php
namespace App\Http\Controllers\Api\V1\Admin\Player;
use App\Models\Player;
use App\Lottery\ErrorCode;
use App\Support\ApiResponse;
use Illuminate\Http\JsonResponse;
use App\Http\Controllers\Controller;
use App\Support\PlayerApiPresenter;
use App\Http\Requests\Admin\AdminPlayerStoreRequest;
/** POST /api/v1/admin/players */
final class AdminPlayerStoreController extends Controller
{
public function __invoke(AdminPlayerStoreRequest $request): JsonResponse
{
$exists = Player::query()
->where('site_code', $request->validated('site_code'))
->where('site_player_id', $request->validated('site_player_id'))
->exists();
if ($exists) {
return ApiResponse::error(
'该主站玩家已在彩票平台注册',
ErrorCode::ValidationFailed->value,
null,
422,
);
}
$player = Player::query()->create([
'site_code' => $request->validated('site_code'),
'site_player_id' => $request->validated('site_player_id'),
'username' => $request->validated('username'),
'nickname' => $request->validated('nickname'),
'default_currency' => $request->validated('default_currency', 'NPR'),
'status' => $request->validated('status', 0),
]);
return ApiResponse::success(PlayerApiPresenter::listItem($player), 201);
}
}

29
app/Http/Controllers/Api/V1/Admin/Player/AdminPlayerUpdateController.php Normal file
View File

@@ -0,0 +1,29 @@
<?php
namespace App\Http\Controllers\Api\V1\Admin\Player;
use App\Models\Player;
use App\Lottery\ErrorCode;
use App\Support\ApiResponse;
use Illuminate\Http\JsonResponse;
use App\Http\Controllers\Controller;
use App\Support\PlayerApiPresenter;
use App\Http\Requests\Admin\AdminPlayerUpdateRequest;
/** PUT /api/v1/admin/players/{player} */
final class AdminPlayerUpdateController extends Controller
{
public function __invoke(AdminPlayerUpdateRequest $request, Player $player): JsonResponse
{
$data = $request->validated();
if (isset($data['status'])) {
$data['status'] = (int) $data['status'];
}
$player->fill(array_filter($data, static fn ($v) => $v !== ''));
$player->save();
return ApiResponse::success(PlayerApiPresenter::listItem($player));
}
}

4
app/Http/Controllers/Api/V1/Admin/Wallet/TransferOrderListController.php
View File

@@ -22,14 +22,14 @@ use App\Http\Requests\Admin\TransferOrderListRequest;
* - `transfer_no`（可选，模糊匹配本地单号）
* - `external_ref_no`（可选，模糊匹配主站流水号）
* - `created_from` / `created_to`（可选，`Y-m-d`，筛选创建时间）
* - `status`（可选，逗号分隔：`processing`,`success`,`failed`,`pending_reconcile`）
* - `status`（可选，逗号分隔：`processing`,`success`,`failed`,`pending_reconcile`,`reversed`,`manually_processed`）
* - `abnormal=1`（仅看异常：processing / failed / pending_reconcile，与 `status` 同时出现时优先）
*/
final class TransferOrderListController extends Controller
{
use PaginationTrait;
private const ALLOWED_STATUS = ['processing', 'success', 'failed', 'pending_reconcile'];
private const ALLOWED_STATUS = ['processing', 'success', 'failed', 'pending_reconcile', 'reversed', 'manually_processed'];
public function __invoke(TransferOrderListRequest $request): JsonResponse
{

74
app/Http/Controllers/Api/V1/Admin/Wallet/TransferOrderReconcileController.php Normal file
View File

@@ -0,0 +1,74 @@
<?php
namespace App\Http\Controllers\Api\V1\Admin\Wallet;
use App\Models\TransferOrder;
use App\Support\ApiResponse;
use App\Support\LotteryMessage;
use App\Exceptions\WalletOperationException;
use App\Services\Wallet\LotteryTransferService;
use App\Http\Controllers\Controller;
use App\Http\Requests\Admin\Wallet\TransferOrderReverseRequest;
use App\Http\Requests\Admin\Wallet\TransferOrderManuallyProcessRequest;
use Illuminate\Http\JsonResponse;
/**
* 后台：转账订单对账操作（冲正 / 人工处理）。
* PRD §12：待对账 -> 已冲正 / 已人工处理。
*/
final class TransferOrderReconcileController extends Controller
{
public function __construct(
private readonly LotteryTransferService $transferService,
) {}
public function reverse(TransferOrderReverseRequest $request, string $transferNo): JsonResponse
{
$order = TransferOrder::query()->where('transfer_no', $transferNo)->first();
if ($order === null) {
return ApiResponse::error(__('wallet.order_not_found'), 404);
}
try {
$this->transferService->reconcileTransferOrder(
$order,
'reverse',
(string) $request->validated('remark', ''),
);
} catch (WalletOperationException $e) {
return ApiResponse::error(
LotteryMessage::wallet($request, $e->lotteryCode),
$e->lotteryCode,
null,
$e->httpStatus,
);
}
return ApiResponse::success(['transfer_no' => $transferNo, 'status' => 'reversed']);
}
public function manuallyProcess(TransferOrderManuallyProcessRequest $request, string $transferNo): JsonResponse
{
$order = TransferOrder::query()->where('transfer_no', $transferNo)->first();
if ($order === null) {
return ApiResponse::error(__('wallet.order_not_found'), 404);
}
try {
$this->transferService->reconcileTransferOrder(
$order,
'manually_process',
(string) $request->validated('remark', ''),
);
} catch (WalletOperationException $e) {
return ApiResponse::error(
LotteryMessage::wallet($request, $e->lotteryCode),
$e->lotteryCode,
null,
$e->httpStatus,
);
}
return ApiResponse::success(['transfer_no' => $transferNo, 'status' => 'manually_processed']);
}
}

2
app/Http/Controllers/Api/V1/Admin/Wallet/WalletTransactionListController.php
View File

@@ -29,7 +29,7 @@ final class WalletTransactionListController extends Controller
{
use PaginationTrait;
private const ALLOWED_STATUS = ['posted', 'pending_reconcile'];
private const ALLOWED_STATUS = ['posted', 'pending_reconcile', 'reversed'];
public function __invoke(WalletTransactionListRequest $request): JsonResponse
{

4
app/Http/Controllers/Api/V1/Wallet/WalletLogsController.php
View File

@@ -15,7 +15,7 @@ use App\Http\Controllers\Controller;
/**
* PRD §10.1.1：`GET /api/v1/wallet/logs` — 钱包流水。
*
* Query：`page`、`size`（每页条数，默认 20）、`type`（逗号分隔：transfer_in,transfer_out,bet,prize,refund）
* Query：`page`、`size`（每页条数，默认 20）、`type`（逗号分隔：transfer_in,transfer_out,bet,prize,refund,reversal）
*/
final class WalletLogsController extends Controller
{
@@ -26,6 +26,7 @@ final class WalletLogsController extends Controller
'transfer_in' => ['transfer_in'],
'transfer_out' => ['transfer_out'],
'refund' => ['transfer_out_refund'],
'reversal' => ['reversal'],
'bet' => ['bet'],
'prize' => ['prize'],
];
@@ -152,6 +153,7 @@ final class WalletLogsController extends Controller
{
return match ($biz) {
'transfer_out_refund' => 'refund',
'reversal' => 'reversal',
default => $biz,
};
}

26
app/Http/Requests/Admin/AdminPlayerIndexRequest.php Normal file
View File

@@ -0,0 +1,26 @@
<?php
namespace App\Http\Requests\Admin;
use Illuminate\Foundation\Http\FormRequest;
/**
* 玩家列表查询请求。
*
* @see AdminPlayerIndexController
*/
final class AdminPlayerIndexRequest extends FormRequest
{
public function authorize(): bool
{
return true;
}
public function rules(): array
{
return [
'keyword' => ['sometimes', 'string', 'max:128'],
'status' => ['sometimes', 'integer', 'in:0,1,2'],
];
}
}

30
app/Http/Requests/Admin/AdminPlayerStoreRequest.php Normal file
View File

@@ -0,0 +1,30 @@
<?php
namespace App\Http\Requests\Admin;
use Illuminate\Foundation\Http\FormRequest;
/**
* 玩家创建请求。
*
* @see AdminPlayerStoreController
*/
final class AdminPlayerStoreRequest extends FormRequest
{
public function authorize(): bool
{
return true;
}
public function rules(): array
{
return [
'site_code' => ['required', 'string', 'max:64'],
'site_player_id' => ['required', 'string', 'max:128'],
'username' => ['nullable', 'string', 'max:128'],
'nickname' => ['nullable', 'string', 'max:128'],
'default_currency' => ['sometimes', 'string', 'max:16'],
'status' => ['sometimes', 'integer', 'in:0,1,2'],
];
}
}

28
app/Http/Requests/Admin/AdminPlayerUpdateRequest.php Normal file
View File

@@ -0,0 +1,28 @@
<?php
namespace App\Http\Requests\Admin;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;
/**
* 玩家更新请求。
*
* @see AdminPlayerUpdateController
*/
final class AdminPlayerUpdateRequest extends FormRequest
{
public function authorize(): bool
{
return true;
}
public function rules(): array
{
return [
'username' => ['sometimes', 'string', 'max:128'],
'nickname' => ['sometimes', 'nullable', 'string', 'max:128'],
'status' => ['sometimes', 'integer', Rule::in([0, 1, 2])],
];
}
}

20
app/Http/Requests/Admin/Wallet/TransferOrderManuallyProcessRequest.php Normal file
View File

@@ -0,0 +1,20 @@
<?php
namespace App\Http\Requests\Admin\Wallet;
use Illuminate\Foundation\Http\FormRequest;
final class TransferOrderManuallyProcessRequest extends FormRequest
{
public function authorize(): bool
{
return true;
}
public function rules(): array
{
return [
'remark' => ['sometimes', 'nullable', 'string', 'max:255'],
];
}
}

20
app/Http/Requests/Admin/Wallet/TransferOrderReverseRequest.php Normal file
View File

@@ -0,0 +1,20 @@
<?php
namespace App\Http\Requests\Admin\Wallet;
use Illuminate\Foundation\Http\FormRequest;
final class TransferOrderReverseRequest extends FormRequest
{
public function authorize(): bool
{
return true;
}
public function rules(): array
{
return [
'remark' => ['sometimes', 'nullable', 'string', 'max:255'],
];
}
}

117
app/Services/Wallet/LotteryTransferService.php
View File

@@ -34,12 +34,20 @@ final class LotteryTransferService
/** PRD §6.2/6.7：主站超时待对账 */
private const ST_PENDING_RECONCILE = 'pending_reconcile';
/** PRD §12：对账后冲正 */
private const ST_REVERSED = 'reversed';
/** PRD §12：对账后人工处理 */
private const ST_MANUALLY_PROCESSED = 'manually_processed';
private const BIZ_TRANSFER_IN = 'transfer_in';
private const BIZ_TRANSFER_OUT = 'transfer_out';
private const BIZ_TRANSFER_OUT_REFUND = 'transfer_out_refund';
private const BIZ_REVERSAL = 'reversal';
private const TXN_POSTED = 'posted';
private const TXN_PENDING_RECONCILE = 'pending_reconcile';
@@ -338,6 +346,115 @@ final class LotteryTransferService
);
}
/**
* 对账操作：冲正 / 人工处理。
*
* 冲正（reverse）：主站确认未成功，对已扣彩票余额的转出单做反向操作（加回余额），标记为已冲正。
* 人工处理（manually_process）：管理员确认该订单已通过其它途径解决，仅标记状态，不动钱包。
*
* @param 'reverse'|'manually_process' $action
* @throws WalletOperationException
*/
public function reconcileTransferOrder(
TransferOrder $order,
string $action,
string $remark = '',
): void {
if ($order->status !== self::ST_PENDING_RECONCILE) {
throw new WalletOperationException(
'order_not_pending_reconcile',
ErrorCode::WalletExternalRejected->value,
422,
);
}
if ($action === 'reverse') {
$this->doReverse($order, $remark);
} elseif ($action === 'manually_process') {
$this->doManuallyProcess($order, $remark);
} else {
throw new WalletOperationException(
'invalid_reconcile_action',
ErrorCode::WalletExternalRejected->value,
422,
);
}
}
private function doReverse(TransferOrder $order, string $remark): void
{
if ($order->direction === self::DIR_OUT) {
DB::transaction(function () use ($order, $remark): void {
$wallet = $this->lockLotteryWalletById($order->player_id, $order->currency_code);
$before = (int) $wallet->balance;
$after = $before + (int) $order->amount;
$wallet->forceFill([
'balance' => $after,
'version' => (int) $wallet->version + 1,
])->save();
WalletTxn::query()->create([
'txn_no' => $this->newTxnNo(),
'player_id' => (int) $order->player_id,
'wallet_id' => $wallet->id,
'biz_type' => self::BIZ_REVERSAL,
'biz_no' => $order->transfer_no,
'direction' => self::TXN_DIR_IN,
'amount' => (int) $order->amount,
'balance_before' => $before,
'balance_after' => $after,
'status' => self::TXN_POSTED,
'external_ref_no' => null,
'idempotent_key' => null,
'remark' => $remark ?: 'reversal_pending_reconcile',
]);
$order->forceFill([
'status' => self::ST_REVERSED,
'fail_reason' => 'reversed: '.($remark ?: 'admin_reversal'),
'finished_at' => now(),
])->save();
});
} else {
$order->forceFill([
'status' => self::ST_REVERSED,
'fail_reason' => 'reversed: '.($remark ?: 'admin_reversal'),
'finished_at' => now(),
])->save();
}
}
private function doManuallyProcess(TransferOrder $order, string $remark): void
{
$order->forceFill([
'status' => self::ST_MANUALLY_PROCESSED,
'fail_reason' => 'manually_processed: '.($remark ?: 'admin_manual'),
'finished_at' => now(),
])->save();
}
private function lockLotteryWalletById(int $playerId, string $currencyCode): PlayerWallet
{
$wallet = PlayerWallet::query()
->where([
'player_id' => $playerId,
'wallet_type' => self::WALLET_TYPE_LOTTERY,
'currency_code' => $currencyCode,
])
->lockForUpdate()
->first();
if ($wallet === null) {
throw new WalletOperationException(
'wallet_not_found',
ErrorCode::WalletInvalidCurrency->value,
422,
);
}
return $wallet;
}
/**
* @return array<string, mixed>
*/

40
app/Support/PlayerApiPresenter.php Normal file
View File

@@ -0,0 +1,40 @@
<?php
namespace App\Support;
use App\Models\Player;
use App\Models\PlayerWallet;
/** 玩家 API 统一 JSON 形状（列表行 / 详情）。 */
final class PlayerApiPresenter
{
/** @return array<string, mixed> */
public static function listItem(Player $player): array
{
$wallets = $player->relationLoaded('wallets')
? $player->wallets
: $player->wallets()->get();
$walletRows = $wallets->map(static fn (PlayerWallet $w): array => [
'wallet_type' => $w->wallet_type,
'currency_code' => $w->currency_code,
'balance' => (int) $w->balance,
'frozen_balance' => (int) $w->frozen_balance,
'available_balance' => max(0, (int) $w->balance - (int) $w->frozen_balance),
'status' => (int) $w->status,
])->values()->all();
return [
'id' => (int) $player->id,
'site_code' => $player->site_code,
'site_player_id' => $player->site_player_id,
'username' => $player->username,
'nickname' => $player->nickname,
'default_currency' => $player->default_currency,
'status' => (int) $player->status,
'last_login_at' => $player->last_login_at?->toIso8601String(),
'created_at' => $player->created_at?->toIso8601String(),
'wallets' => $walletRows,
];
}
}

15
routes/api/v1/admin/player.php
View File

@@ -1,6 +1,11 @@
<?php
use Illuminate\Support\Facades\Route;
use App\Http\Controllers\Api\V1\Admin\Player\AdminPlayerIndexController;
use App\Http\Controllers\Api\V1\Admin\Player\AdminPlayerStoreController;
use App\Http\Controllers\Api\V1\Admin\Player\AdminPlayerShowController;
use App\Http\Controllers\Api\V1\Admin\Player\AdminPlayerUpdateController;
use App\Http\Controllers\Api\V1\Admin\Player\AdminPlayerDestroyController;
use App\Http\Controllers\Api\V1\Admin\Player\PlayerWalletShowController;
use App\Http\Controllers\Api\V1\Admin\Player\AdminPlayerTicketItemsIndexController;
@@ -9,6 +14,16 @@ use App\Http\Controllers\Api\V1\Admin\Player\AdminPlayerTicketItemsIndexControll
*/
Route::middleware('admin.permission:prd.users.manage|prd.users.view_finance|prd.users.view_cs')
->group(function (): void {
Route::get('players', AdminPlayerIndexController::class)
->name('api.v1.admin.players.index');
Route::post('players', AdminPlayerStoreController::class)
->name('api.v1.admin.players.store');
Route::get('players/{player}', AdminPlayerShowController::class)
->name('api.v1.admin.players.show');
Route::put('players/{player}', AdminPlayerUpdateController::class)
->name('api.v1.admin.players.update');
Route::delete('players/{player}', AdminPlayerDestroyController::class)
->name('api.v1.admin.players.destroy');
Route::get('players/{player}/wallets', PlayerWalletShowController::class)
->name('api.v1.admin.players.wallets');
Route::get('players/{player}/ticket-items', AdminPlayerTicketItemsIndexController::class)

11
routes/api/v1/admin/wallet.php
View File

@@ -2,6 +2,7 @@
use Illuminate\Support\Facades\Route;
use App\Http\Controllers\Api\V1\Admin\Wallet\TransferOrderListController;
use App\Http\Controllers\Api\V1\Admin\Wallet\TransferOrderReconcileController;
use App\Http\Controllers\Api\V1\Admin\Reconcile\ReconcileJobShowController;
use App\Http\Controllers\Api\V1\Admin\Reconcile\ReconcileJobIndexController;
use App\Http\Controllers\Api\V1\Admin\Reconcile\ReconcileJobStoreController;
@@ -20,7 +21,6 @@ Route::middleware('admin.permission:prd.wallet_reconcile.manage|prd.wallet_recon
Route::get('wallet/transactions', WalletTransactionListController::class)
->name('api.v1.admin.wallet.transactions');
// 对账任务查看
Route::get('reconcile-jobs', ReconcileJobIndexController::class)
->name('api.v1.admin.reconcile-jobs.index');
Route::get('reconcile-jobs/{reconcile_job}', ReconcileJobShowController::class)
@@ -29,6 +29,15 @@ Route::middleware('admin.permission:prd.wallet_reconcile.manage|prd.wallet_recon
->name('api.v1.admin.reconcile-jobs.items.index');
});
// 对账操作（仅管理权限）
Route::middleware('admin.permission:prd.wallet_reconcile.manage')
->group(function (): void {
Route::post('wallet/transfer-orders/{transfer_no}/reverse', [TransferOrderReconcileController::class, 'reverse'])
->name('api.v1.admin.wallet.transfer-orders.reverse');
Route::post('wallet/transfer-orders/{transfer_no}/manually-process', [TransferOrderReconcileController::class, 'manuallyProcess'])
->name('api.v1.admin.wallet.transfer-orders.manually-process');
});
// 对账任务创建（仅管理权限）
Route::middleware('admin.permission:prd.wallet_reconcile.manage')
->post('reconcile-jobs', ReconcileJobStoreController::class)