1. 维护代码健壮

2. 更新项目结构文档
2026-05-09 18:34:26 +08:00 · 2026-04-27 16:20:41 +08:00
parent 9a16a88640
commit 0e5de50337
198 changed files with 21038 additions and 702 deletions
--- a/app/http/api/controller/cashier/CashierController.php
+++ b/app/http/api/controller/cashier/CashierController.php
@@ -0,0 +1,67 @@
+<?php
+
+namespace app\http\api\controller\cashier;
+
+use app\common\base\BaseController;
+use app\http\api\validation\CashierValidator;
+use app\service\payment\cashier\CashierService;
+use support\Request;
+use support\Response;
+
+/**
+ * 收银台控制器。
+ *
+ * 提供收银台上下文查询和支付确认入口。
+ */
+class CashierController extends BaseController
+{
+    public function __construct(
+        protected CashierService $cashierService
+    ) {
+    }
+
+    /**
+     * 查询收银台上下文。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
+    public function context(Request $request): Response
+    {
+        $payload = $this->validated($request->all(), CashierValidator::class, 'context');
+
+        return $this->success(
+            $this->cashierService->context((string) ($payload['biz_no'] ?? ''))
+        );
+    }
+
+    /**
+     * 确认收银台支付方式。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
+    public function confirm(Request $request): Response
+    {
+        $payload = $this->validated($request->all(), CashierValidator::class, 'confirm');
+
+        return $this->success(
+            $this->cashierService->confirm($payload, $request)
+        );
+    }
+
+    /**
+     * 查询支付页详情。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
+    public function payOrder(Request $request): Response
+    {
+        $payload = $this->validated($request->all(), CashierValidator::class, 'pay_order');
+
+        return $this->success(
+            $this->cashierService->payOrderDetail((string) ($payload['pay_no'] ?? ''))
+        );
+    }
+}
--- a/app/http/api/controller/epay/EpayV1Controller.php
+++ b/app/http/api/controller/epay/EpayV1Controller.php
@@ -0,0 +1,87 @@
+<?php
+
+namespace app\http\api\controller\epay;
+
+use app\common\base\BaseController;
+use app\service\payment\epay\EpayV1ProtocolService;
+use app\http\api\validation\EpayV1Validator;
+use support\Request;
+use support\Response;
+
+/**
+ * ePay V1 控制器。
+ *
+ * 负责承接旧版页面跳转、API 支付与旧接口兼容查询。
+ */
+class EpayV1Controller extends BaseController
+{
+    /**
+     * 构造方法。
+     *
+     * @param EpayV1ProtocolService $epayV1ProtocolService V1 协议服务
+     */
+    public function __construct(
+        protected EpayV1ProtocolService $epayV1ProtocolService
+    ) {
+    }
+
+    /**
+     * 页面跳转支付入口。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
+    public function submit(Request $request): Response
+    {
+        $payload = $this->validated($request->all(), EpayV1Validator::class, 'submit');
+        return $this->epayV1ProtocolService->submit($payload, $request);
+    }
+
+    /**
+     * API 支付入口。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
+    public function mapi(Request $request): Response
+    {
+        $payload = $this->validated($request->all(), EpayV1Validator::class, 'mapi');
+        return json($this->epayV1ProtocolService->mapi($payload, $request));
+    }
+
+    /**
+     * 旧版兼容 API 入口。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
+    public function api(Request $request): Response
+    {
+        $payload = $request->all();
+        $scene = $this->resolveApiScene((string) ($payload['act'] ?? ''));
+        if ($scene === null) {
+            return json(['code' => 0, 'msg' => '不支持的操作类型']);
+        }
+
+        $payload = $this->validated($payload, EpayV1Validator::class, $scene);
+        return json($this->epayV1ProtocolService->api($payload));
+    }
+
+    /**
+     * 映射旧版 `act` 到验证场景。
+     *
+     * @param string $act 接口动作
+     * @return string|null 验证场景
+     */
+    private function resolveApiScene(string $act): ?string
+    {
+        return match (strtolower(trim($act))) {
+            'query' => 'api_query',
+            'settle' => 'api_settle',
+            'order' => 'api_order',
+            'orders' => 'api_orders',
+            'refund' => 'api_refund',
+            default => null,
+        };
+    }
+}
--- a/app/http/api/controller/epay/EpayV2Controller.php
+++ b/app/http/api/controller/epay/EpayV2Controller.php
@@ -0,0 +1,173 @@
+<?php
+
+namespace app\http\api\controller\epay;
+
+use app\common\base\BaseController;
+use app\http\api\validation\EpayV2Validator;
+use app\service\payment\epay\EpayV2ProtocolService;
+use app\service\payment\order\PayOrderService;
+use support\Request;
+use support\Response;
+
+/**
+ * ePay V2 控制器。
+ *
+ * 负责承接新版支付、查询、退款、商户与转账接口。
+ */
+class EpayV2Controller extends BaseController
+{
+    /**
+     * 构造方法。
+     *
+     * @param EpayV2ProtocolService $epayV2ProtocolService V2 协议服务
+     */
+    public function __construct(
+        protected EpayV2ProtocolService $epayV2ProtocolService,
+        protected PayOrderService $payOrderService
+    ) {
+    }
+
+    /**
+     * 页面跳转支付入口。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
+    public function submit(Request $request): Response
+    {
+        $payload = $this->validated($request->all(), EpayV2Validator::class, 'submit');
+        return $this->epayV2ProtocolService->submit($payload, $request);
+    }
+
+    /**
+     * API 下单入口。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
+    public function create(Request $request): Response
+    {
+        $payload = $this->validated($request->all(), EpayV2Validator::class, 'create');
+        return json($this->epayV2ProtocolService->create($payload, $request));
+    }
+
+    /**
+     * 支付单查询入口。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
+    public function query(Request $request): Response
+    {
+        $payload = $this->validated($request->all(), EpayV2Validator::class, 'query');
+        return json($this->epayV2ProtocolService->query($payload));
+    }
+
+    /**
+     * 退款发起入口。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
+    public function refund(Request $request): Response
+    {
+        $payload = $this->validated($request->all(), EpayV2Validator::class, 'refund');
+        return json($this->epayV2ProtocolService->refund($payload));
+    }
+
+    /**
+     * 退款查询入口。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
+    public function refundQuery(Request $request): Response
+    {
+        $payload = $this->validated($request->all(), EpayV2Validator::class, 'refund_query');
+        return json($this->epayV2ProtocolService->refundQuery($payload));
+    }
+
+    /**
+     * 关闭订单入口。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
+    public function close(Request $request): Response
+    {
+        $payload = $this->validated($request->all(), EpayV2Validator::class, 'close');
+        return json($this->epayV2ProtocolService->close($payload));
+    }
+
+    /**
+     * 商户信息查询入口。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
+    public function merchantInfo(Request $request): Response
+    {
+        $payload = $this->validated($request->all(), EpayV2Validator::class, 'merchant_info');
+        return json($this->epayV2ProtocolService->merchantInfo($payload));
+    }
+
+    /**
+     * 商户订单列表入口。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
+    public function merchantOrders(Request $request): Response
+    {
+        $payload = $this->validated($request->all(), EpayV2Validator::class, 'merchant_orders');
+        return json($this->epayV2ProtocolService->merchantOrders($payload));
+    }
+
+    /**
+     * 转账发起入口。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
+    public function transferSubmit(Request $request): Response
+    {
+        $payload = $this->validated($request->all(), EpayV2Validator::class, 'transfer_submit');
+        return json($this->epayV2ProtocolService->transferSubmit($payload));
+    }
+
+    /**
+     * 转账查询入口。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
+    public function transferQuery(Request $request): Response
+    {
+        $payload = $this->validated($request->all(), EpayV2Validator::class, 'transfer_query');
+        return json($this->epayV2ProtocolService->transferQuery($payload));
+    }
+
+    /**
+     * 转账余额查询入口。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
+    public function transferBalance(Request $request): Response
+    {
+        $payload = $this->validated($request->all(), EpayV2Validator::class, 'transfer_balance');
+        return json($this->epayV2ProtocolService->transferBalance($payload));
+    }
+
+    /**
+     * 渠道回调入口。
+     *
+     * @param Request $request 请求对象
+     * @param string $payNo 支付单号
+     * @return string|Response
+     */
+    public function callback(Request $request, string $payNo): string|Response
+    {
+        return $this->payOrderService->handlePluginCallback($payNo, $request);
+    }
+}