README

Tích hợp Laravel với Simba (phần mềm kế toán).

📚 Documentation

• Project Docs: Model Architecture - 3-layer Model pattern (SModel → Simba\Models → Catalog\Models)
• Project Docs: Package Namespace Conventions

Mô tả ngắn gọn

Laravel Integration With Simba. Package cung cấp các model và stored procedure caller để tương tác với cơ sở dữ liệu Simba (ERP/kế toán), hỗ trợ composite primary key và xử lý charset.

⚠️ NGUYÊN TẮC BẤT BIẾN: Package chỉ hỗ trợ READ trực tiếp qua Models. Mọi thao tác INSERT/UPDATE/DELETE phải thực hiện thông qua Stored Procedures. Không thao tác trực tiếp trên bảng.

Xem chi tiết: Database Access Policy

Kiến trúc Model 3 lớp

Package sử dụng kiến trúc Model 3 lớp để phân chia trách nhiệm rõ ràng:

Diepxuan\Catalog\Models\<Model>
    extends Diepxuan\Simba\Models\<Model>
        extends Diepxuan\Simba\SModel\<Model>Model

Xem chi tiết: Model Architecture

Chức năng chính

• Cung cấp các model (SModel) tương ứng với các bảng dữ liệu trong hệ thống Simba: SysLanguage, InCT3, SoPh3, GlDmTk, GlCt, GlCdTk, SysCompany, SysCompanyResx, InDmVt, InPH3, SiSetup, SysUserCompanyRight, ArDmKh, InDmKho, SysUserInfo, InDmNhvt, ...
• Cung cấp các stored procedure caller để gọi procedure từ Simba: AsGetSoCt, AsGetSoDuKh, và class ProcedureCaller tổng quát.
• Sử dụng composite primary key (từ package eloquent-composite).
• Phụ thuộc vào package charset để xử lý encoding.
• Cấu hình kết nối database riêng (mặc định sqlsrv) qua environment variable SIMBA_CONNECTION.

Cài đặt / Sử dụng

composer require diepxuan/laravel-simba

Package không có ServiceProvider, cần sử dụng thủ công.

Cấu hình kết nối database Simba trong .env:

SIMBA_CONNECTION=sqlsrv
DB_CONNECTION_SIMBA=... (nếu dùng connection riêng)

Sử dụng model:

use Diepxuan\Simba\SModel\InDmVtModel;

$items = InDmVtModel::all();

Sử dụng stored procedure caller:

use Diepxuan\Simba\StoredProcedures\ProcedureCaller;

$result = ProcedureCaller::call('asGetSoCt', ['pMa_Cty' => '01', 'pNgay_Ct' => '2024-01-01']);

Hoặc dùng class cụ thể:

use Diepxuan\Simba\StoredProcedures\AsGetSoCt;

$result = AsGetSoCt::call($params);

Cấu trúc thư mục

laravel-simba/
├── config/
│   └── config.php                 # Cấu hình package (connection)
├── src/
│   ├── SModel/                    # Raw/table schema của SimbaERP (1:1 với bảng vật lý)
│   │   ├── SModel.php (base)
│   │   └── *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
│   │   └── AsGetSoDuKh.php
│   └── Database/                  (factories, seeders - chưa có nội dung)
├── .editorconfig
├── .gitignore
├── .php-cs-fixer.dist.php
├── LICENSE
├── README.md
└── composer.json

Liên kết đến các package liên quan

• diepxuan/php-charset (xử lý charset)
• diepxuan/laravel-core (core chung)
• diepxuan/laravel-eloquent-composite (hỗ trợ composite primary key)
• diepxuan/laravel-catalog (package sử dụng chính)

Tài liệu

• Model Architecture - Kiến trúc Model 3 lớp
• Configuration - Cấu hình package
• Database Access Policy - Chính sách truy cập database
• Stored Procedures - Danh sách stored procedures
• Troubleshooting - Xử lý sự cố

Ghi chú

Package này tích hợp với cơ sở dữ liệu Simba, phục vụ cho việc trao đổi dữ liệu giữa Laravel và hệ thống ERP Simba (phần mềm kế toán). Cần cấu hình kết nối SQL Server (sqlsrv) đúng với database Simba.