refactor: document simba model layers (#217)

* refactor(simba): document model layers and align imports

* fix(simba): avoid company code as generic primary key

* fix(simba): record composite primary key columns

* refactor(simba): drop legacy non-Model SModel classes

* docs: merge model layer plans

* feat(simba): add direct models for generated schema

---------

Co-authored-by: portal-bot <bot@portal>

Author: caothu159

README.md

@@ -53,9 +53,9 @@ DB_CONNECTION_SIMBA=... (nếu dùng connection riêng)
 Sử dụng model:
 
 ```php
-use Diepxuan\Simba\SModel\InDmVt;
+use Diepxuan\Simba\SModel\InDmVtModel;
 
-$items = InDmVt::all();
+$items = InDmVtModel::all();
 ```
 
 Sử dụng stored procedure caller:
@@ -81,35 +81,11 @@ laravel-simba/
 ├── config/
 │   └── config.php                 # Cấu hình package (connection)
 ├── src/
-│   ├── SModel/                    # Các model Simba (bảng dữ liệu)
+│   ├── SModel/                    # Raw/table schema của SimbaERP (1:1 với bảng vật lý)
 │   │   ├── SModel.php (base)
-│   │   ├── SysLanguage.php
-│   │   ├── InCT3.php
-│   │   ├── SoPh3.php
-│   │   ├── GlDmTk.php
-│   │   ├── GlCt.php
-│   │   ├── GlCdTk.php
-│   │   ├── SysCompany.php
-│   │   ├── SysCompanyResx.php
-│   │   ├── InDmVt.php
-│   │   ├── InPH3.php
-│   │   ├── SiSetup.php
-│   │   ├── SysUserCompanyRight.php
-│   │   ├── ArDmKh.php
-│   │   ├── InDmKho.php
-│   │   ├── SysUserInfo.php
-│   │   └── InDmNhvt.php
-│   ├── Models/                    # Các model mở rộng (có thể thêm scope)
-│   │   ├── SysCompany.php
-│   │   ├── SysUserCompanyRight.php
-│   │   ├── InDmVt.php
-│   │   ├── InDmKho.php
-│   │   ├── SysUserInfo.php
-│   │   ├── ArDmKh.php
-│   │   ├── SoPh3.php
-│   │   ├── InDmNhvt.php
-│   │   ├── SiSetup.php
-│   │   └── GlCt.php
+│   │   └── *Model.php             # Mỗi file tương ứng một bảng, tên theo chuẩn <Table>Model
+│   ├── Models/                    # Model Simba có behavior/query helper trực tiếp dùng trong code
+│   │   └── <Table>.php            # Extend từ <Table>Model tương ứng ở SModel
 │   ├── StoredProcedures/          # Các class gọi stored procedure
 │   │   ├── ProcedureCaller.php
 │   │   ├── AsGetSoCt.php

src/Models/ApCt1.php

@@ -13,6 +13,7 @@
 
 namespace Diepxuan\Simba\Models;
 
+use Diepxuan\Simba\Models\Concerns\HasSimbaCompositeKey;
 use Diepxuan\Simba\SModel\ApCt1Model as Model;
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Support\Collection;
@@ -25,6 +26,8 @@
  */
 class ApCt1 extends Model
 {
+    use HasSimbaCompositeKey;
+
     /** Filter theo mã công ty */
     public function scopeFilterByMaCty(Builder $query, ?string $maCty): Builder
     {

src/Models/ApCt3.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * @copyright  © 2019 Dxvn, Inc.
+ *
+ * @author     Tran Ngoc Duc <ductn@diepxuan.com>
+ *
+ * @lastupdate 2026-06-21
+ */
+
+namespace Diepxuan\Simba\Models;
+
+use Diepxuan\Simba\Models\Concerns\HasSimbaCompositeKey;
+use Diepxuan\Simba\SModel\ApCt3Model;
+
+/**
+ * Model ApCt3.
+ *
+ * Lớp Simba model trực tiếp cho bảng `ApCt3`, kế thừa schema từ `ApCt3Model`.
+ */
+class ApCt3 extends ApCt3Model
+{
+    use HasSimbaCompositeKey;
+
+}

src/Models/ApCt4.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * @copyright  © 2019 Dxvn, Inc.
+ *
+ * @author     Tran Ngoc Duc <ductn@diepxuan.com>
+ *
+ * @lastupdate 2026-06-21
+ */
+
+namespace Diepxuan\Simba\Models;
+
+use Diepxuan\Simba\Models\Concerns\HasSimbaCompositeKey;
+use Diepxuan\Simba\SModel\ApCt4Model;
+
+/**
+ * Model ApCt4.
+ *
+ * Lớp Simba model trực tiếp cho bảng `ApCt4`, kế thừa schema từ `ApCt4Model`.
+ */
+class ApCt4 extends ApCt4Model
+{
+    use HasSimbaCompositeKey;
+
+}

src/Models/ApPh1.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * @copyright  © 2019 Dxvn, Inc.
+ *
+ * @author     Tran Ngoc Duc <ductn@diepxuan.com>
+ *
+ * @lastupdate 2026-06-21
+ */
+
+namespace Diepxuan\Simba\Models;
+
+use Diepxuan\Simba\Models\Concerns\HasSimbaCompositeKey;
+use Diepxuan\Simba\SModel\ApPh1Model;
+
+/**
+ * Model ApPh1.
+ *
+ * Lớp Simba model trực tiếp cho bảng `ApPh1`, kế thừa schema từ `ApPh1Model`.
+ */
+class ApPh1 extends ApPh1Model
+{
+    use HasSimbaCompositeKey;
+
+}

src/Models/ApPh3.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * @copyright  © 2019 Dxvn, Inc.
+ *
+ * @author     Tran Ngoc Duc <ductn@diepxuan.com>
+ *
+ * @lastupdate 2026-06-21
+ */
+
+namespace Diepxuan\Simba\Models;
+
+use Diepxuan\Simba\Models\Concerns\HasSimbaCompositeKey;
+use Diepxuan\Simba\SModel\ApPh3Model;
+
+/**
+ * Model ApPh3.
+ *
+ * Lớp Simba model trực tiếp cho bảng `ApPh3`, kế thừa schema từ `ApPh3Model`.
+ */
+class ApPh3 extends ApPh3Model
+{
+    use HasSimbaCompositeKey;
+
+}

src/Models/ApPh4.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * @copyright  © 2019 Dxvn, Inc.
+ *
+ * @author     Tran Ngoc Duc <ductn@diepxuan.com>
+ *
+ * @lastupdate 2026-06-21
+ */
+
+namespace Diepxuan\Simba\Models;
+
+use Diepxuan\Simba\Models\Concerns\HasSimbaCompositeKey;
+use Diepxuan\Simba\SModel\ApPh4Model;
+
+/**
+ * Model ApPh4.
+ *
+ * Lớp Simba model trực tiếp cho bảng `ApPh4`, kế thừa schema từ `ApPh4Model`.
+ */
+class ApPh4 extends ApPh4Model
+{
+    use HasSimbaCompositeKey;
+
+}

src/Models/ApTt.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * @copyright  © 2019 Dxvn, Inc.
+ *
+ * @author     Tran Ngoc Duc <ductn@diepxuan.com>
+ *
+ * @lastupdate 2026-06-21
+ */
+
+namespace Diepxuan\Simba\Models;
+
+use Diepxuan\Simba\Models\Concerns\HasSimbaCompositeKey;
+use Diepxuan\Simba\SModel\ApTtModel;
+
+/**
+ * Model ApTt.
+ *
+ * Lớp Simba model trực tiếp cho bảng `ApTt`, kế thừa schema từ `ApTtModel`.
+ */
+class ApTt extends ApTtModel
+{
+    use HasSimbaCompositeKey;
+
+}

src/Models/ArCdKh.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * @copyright  © 2019 Dxvn, Inc.
+ *
+ * @author     Tran Ngoc Duc <ductn@diepxuan.com>
+ *
+ * @lastupdate 2026-06-21
+ */
+
+namespace Diepxuan\Simba\Models;
+
+use Diepxuan\Simba\Models\Concerns\HasSimbaCompositeKey;
+use Diepxuan\Simba\SModel\ArCdKhModel;
+
+/**
+ * Model ArCdKh.
+ *
+ * Lớp Simba model trực tiếp cho bảng `ArCdKh`, kế thừa schema từ `ArCdKhModel`.
+ */
+class ArCdKh extends ArCdKhModel
+{
+    use HasSimbaCompositeKey;
+
+}

src/Models/ArCdKh13.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * @copyright  © 2019 Dxvn, Inc.
+ *
+ * @author     Tran Ngoc Duc <ductn@diepxuan.com>
+ *
+ * @lastupdate 2026-06-21
+ */
+
+namespace Diepxuan\Simba\Models;
+
+use Diepxuan\Simba\Models\Concerns\HasSimbaCompositeKey;
+use Diepxuan\Simba\SModel\ArCdKh13Model;
+
+/**
+ * Model ArCdKh13.
+ *
+ * Lớp Simba model trực tiếp cho bảng `ArCdKh13`, kế thừa schema từ `ArCdKh13Model`.
+ */
+class ArCdKh13 extends ArCdKh13Model
+{
+    use HasSimbaCompositeKey;
+
+}