Merge pull request #136 from diepxuan/docs/ascadelph2-output-parameter

docs: bổ sung output parameter pRet và documentation cho AsCADelPH2

Author: caothu159

src/StoredProcedures/AsCADelPH2.php

@@ -8,26 +8,100 @@
  * @author     Tran Ngoc Duc <ductn@diepxuan.com>
  * @author     Tran Ngoc Duc <caothu91@gmail.com>
  *
- * @lastupdate 2026-02-12 12:36:46
+ * @lastupdate 2026-04-06 07:25:49
  */
 
 namespace Diepxuan\Simba\StoredProcedures;
 
+use Diepxuan\Simba\Helper\ParamHelper;
 use Diepxuan\Simba\SModel\SModel;
 use Illuminate\Support\Collection;
-use Diepxuan\Simba\Helper\ParamHelper;
 
+/**
+ * Class AsCADelPH2.
+ *
+ * Stored procedure: asCADelPH2
+ * Mục đích: Xóa phiếu thu/chi (bảng CAPH2 - Cash Phiếu 2).
+ * Procedure thực hiện xóa bản ghi khỏi bảng CAPH2 dựa trên số tham chiếu (stt_rec).
+ *
+ * Tham số (theo định nghĩa thực tế trong SQL Server):
+ * - @pMa_cty (nvarchar(3)): Mã công ty. Bắt buộc.
+ * - @pStt_rec (nvarchar(20)): Số tham chiếu (stt_rec) của phiếu cần xóa. Bắt buộc.
+ * - @pLUser (nvarchar(20)): Người dùng thực hiện xóa. Bắt buộc.
+ * - @pRet (int, OUTPUT): Tham số đầu ra chứa mã lỗi (@@error).
+ *   - 0: Thành công.
+ *   - Khác 0: Mã lỗi SQL Server.
+ *
+ * Giá trị trả về:
+ * - Procedure không trả về result set.
+ * - Kết quả được trả về qua output parameter @pRet.
+ * - Để lấy giá trị @pRet, cần đọc từ result của ProcedureCaller (có SELECT @pRet).
+ *
+ * Ví dụ gọi:
+ * ```php
+ * $result = AsCADelPH2::call([
+ *     'pMa_cty' => '001',
+ *     'pStt_rec' => '001wCA40000000676668',
+ *     'pLUser' => 'DUCTN',
+ * ]);
+ *
+ * // Lấy giá trị output parameter
+ * $ret = $result->first()->pRet ?? null;
+ * if ($ret === 0) {
+ *     // Xóa thành công
+ * } else {
+ *     // Có lỗi xảy ra, $ret chứa mã lỗi
+ * }
+ * ```
+ *
+ * Lưu ý:
+ * - Procedure chỉ thực hiện xóa dựa trên stt_rec.
+ * - Cần đảm bảo stt_rec tồn tại trước khi xóa.
+ * - Output parameter @pRet được xử lý tự động bởi ProcedureCaller.
+ *
+ * @see AsCAGetPH2::call() - Kiểm tra phiếu tồn tại trước khi xóa
+ */
 class AsCADelPH2
 {
+    /**
+     * Gọi stored procedure asCADelPH2.
+     *
+     * @param array $params Mảng tham số với các khóa tương ứng tên tham số.
+     *                      Các parameters có thể thiếu, sẽ dùng giá trị default.
+     *
+     * @return Collection kết quả từ procedure (chứa output parameter pRet)
+     */
     public static function call(array $params): Collection
     {
-        $paramObj = ParamHelper::fromArray($params);
+        $paramObj   = ParamHelper::fromArray($params);
         $connection = (new SModel())->getConnectionName();
 
         return ProcedureCaller::call('asCADelPH2', [
-            'pMa_cty' => $paramObj->pMa_cty ?? null,
+            'pMa_cty'  => $paramObj->pMa_cty ?? null,
             'pStt_rec' => $paramObj->pStt_rec ?? null,
-            'pLUser' => $paramObj->pLUser ?? null,
+            'pLUser'   => $paramObj->pLUser ?? null,
+            'pRet'     => ['type' => 'INT', 'output' => true],
         ], $connection);
     }
+
+    /**
+     * Call stored procedure asCADelPH2 with named parameters (helper method).
+     *
+     * @param null|string $Ma_cty  Mã công ty
+     * @param null|string $Stt_rec Số tham chiếu
+     * @param null|string $LUser   Người dùng
+     *
+     * @return Collection Kết quả từ procedure
+     */
+    public static function callWithParams(
+        ?string $Ma_cty = null,
+        ?string $Stt_rec = null,
+        ?string $LUser = null,
+    ): Collection {
+        return self::call([
+            'pMa_cty'  => $Ma_cty,
+            'pStt_rec' => $Stt_rec,
+            'pLUser'   => $LUser,
+        ]);
+    }
 }