README

Laravel 後台引擎。用一行字串 DSL 描述欄位,換到一整套後台 CRUD:清單、篩選、排序、分頁、表單驗證、複製、拖曳排序、匯出、稽核軌跡、以及以選單樹為基礎的授權模型。

class WidgetController extends CrudController {

    protected string $model = Widget::class;

    protected array $lists = ['id', 'title', 'status:select', 'category.title=category_title', 'create_time'];

    protected array $forms = ['title', 'status:select', 'category_id:select', 'content:text'];

}

上面這個類別會生出十個端點、一份帶型別與驗證規則的欄位描述、以及一組可以逐項授權的權限點。

目錄

• 套件不提供什麼
• 安裝 —— 從 composer require 到能登入
• 五個必讀概念
• 開一個自己的功能
• 前台身分（member / vendor） —— 套件只給零件
• 訊息 —— 送訊息、派送與 worker、後台查詢、重發與取消、Push 訂閱(Member)、Telegram 綁定與 Webhook、自訂訊息通道
• 參考 —— 端點、設定鍵、cfg 設定鍵、主控台指令、錯誤代碼、資料表
• 給前端 —— 請求形狀、回應形狀、語系、驗證碼
• 沿用套件的 lint —— 選用,共用同一套風格檢查
• 已知限制與取捨 —— 安全、規模與效能、資料生命週期、行為細節
• 從舊版升級

套件不提供什麼

先講界線,因為這些是刻意的決定,不是還沒做:

安裝

照順序走,每一步都有驗證動作。 中間任何一步失敗,不要往下走 —— 這套件的失敗多半是靜默的。

1. 環境

驗證:

php -r 'exit(function_exists("imagettftext") ? 0 : 1);' || echo 'GD 缺少 FreeType,後台將完全登不進去'

composer.json 只能要求 ext-gd 存在,擋不掉「有 GD 但沒有 FreeType」。這一條與 cache store 那一條都要到第一次有人登入才會爆,所以請把上面那行放進部署腳本或 CI —— 它回非零 exit code。

2. 安裝套件

composer require matrix-platform/laravel-base

服務提供者會自動註冊（extra.laravel.providers）。migration 與路由自動載入,不需要也不能發佈。

3. 建立 config/matrix.php

這個檔案一定要自己建。 套件的預設值走 mergeConfigFrom,只合併頂層 key —— 你宣告 messaging 就會整個取代掉套件的 messaging（包含它底下的 channels）。所以要嘛整份照抄,要嘛只宣告你真的要改的頂層 key,並把該 key 的完整內容一起寫上。

完整範本（等同套件出貨值）:

<?php

use MatrixPlatform\Models\MailLog;
use MatrixPlatform\Models\Member;
use MatrixPlatform\Models\SmsLog;
use MatrixPlatform\Models\Vendor;

return [

    'admin-api-prefix' => 'admin',

    'admin-menus' => 'base',

    'api-prefix' => 'api',

    'file-private-disk' => 'local',

    'file-public-disk' => 'public',

    'locales' => 'tw en',

    'member-model' => Member::class,

    'messaging' => [
        'channels' => [
            'mail' => ['model' => MailLog::class, 'queue' => 'messaging-mail'],
            'sms' => ['model' => SmsLog::class, 'queue' => 'messaging-sms'],
        ],
    ],

    'packages' => 'app base',

    'resource-cfg' => [],

    'resource-i18n' => [],

    'resource-i18n-menu' => [],

    'resource-i18n-model' => [],

    'resource-i18n-options' => [],

    'resource-i18n-template' => [],

    'vendor-model' => Vendor::class,

];

語系要對得起來。 locales 列出的每一個值,都必須在 resources/i18n/{語系}/ 底下有對應目錄。Laravel 預設的 APP_LOCALE=en 可以直接用;若你設成 zh_TW 之類的值,套件找不到 resources/i18n/zh_TW/,整個後台的標題、選單、錯誤訊息會退化成原始 token（畫面看起來還在跑,只是字都變成 errors.permission-denied 這種東西）。

4. 跑 migration

php artisan migrate

套件的 migration 檔名是 0001_ 到 0007_,字串排序落在 Laravel 內建的 0001_01_01_* 之後、你自己的日期式 migration 之前。你自己的表如果要用套件的主鍵慣例,順序不能反過來 —— 0001_foundation 建立 base_id 與 base_ranking 兩個 sequence,你的 migration 必須排在它後面。

驗證: base_user、base_group、base_auth_token 等 17 張表存在。

5. 跑 seeder

套件出貨兩個 seeder,都不會自動執行,要在你自己的 DatabaseSeeder 裡呼叫:

public function run(): void {
    $this->call(\MatrixPlatform\Database\Seeders\UserSeeder::class);
    $this->call(\MatrixPlatform\Database\Seeders\CitySeeder::class);   // 台灣縣市與行政區,不需要就別跑
}

UserSeeder 建兩個帳號:root@matrix（id = 1）與 admin（id = 2）。兩個都沒有密碼,而且 id 是寫死的 —— 那是權限模型的一部分（見五個必讀概念）。

CitySeeder 寫入 394 列,而且每一列都會產生一筆稽核紀錄 —— 這是刻意的,稽核軌跡要答得出「這批資料是誰在什麼時候放進來的」。

驗證: base_user 有 id 1 與 2 兩列。

6. 設定管理員密碼

php artisan matrix:passwd root@matrix

指令會問兩次密碼。密碼規則來自 cfg('admin.password-pattern'),出貨值是「至少 8 碼、含英文與數字」。同一規則也套用在登入後自行改密碼與後台使用者表單的非空密碼;重設成功會撤銷該帳號所有既有 session。

這是建立管理員的唯一官方入口。 後台介面建出來的帳號一律是一般使用者 —— 因為 id 來自從 10000000 起跳的共用 sequence,而管理員等級是由 id 區間決定的。

驗證: 下一步能登入。

7. 打第一個請求

先產生加密金鑰圈:

php artisan matrix:rotate-encryption-key

matrix.admin-api-encryption 與 matrix.vendor-api-encryption 出貨是開的,金鑰圈空著的時候 encryption-key 只會回 encryption-unavailable,整個後台開不起來。

然後下面這兩個 curl 還是會失敗——加密開著的時候明文請求一律回 invalid-envelope,auth/captcha 與 auth/login 沒有宣告 #[Action(encrypted: false)]。要用 curl 驗證,先在你的 config/matrix.php 把 'admin-api-encryption' => false 關掉;要驗證加密路徑,用瀏覽器端(前端 initConfig 的 encryption 也是預設開的),或照給前端那節的線路格式自己組信封。

# 1. 取驗證碼(匿名)
curl -X POST http://localhost/admin/auth/captcha
# → {"success":true,"data":{"token":"...","image":"data:image/png;base64,..."}}

# 2. 登入(把圖片裡的字讀出來當 code)
curl -X POST http://localhost/admin/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"root@matrix","password":"...","token":"上一步的 token","code":"圖片裡的字"}'
# → {"success":true,"data":{"token":"..."}}

驗證: 拿到 token。用它打 POST admin/auth/profile 應該回傳選單樹與個人資料。

8. 註冊排程(如果要用訊息或 token 清理)

套件不註冊排程。在你的 routes/console.php:

Schedule::command('matrix:prune-tokens')->daily()->withoutOverlapping();
Schedule::command('matrix:prune-drive-files')->daily()->withoutOverlapping();
Schedule::command('messages:dispatch')->everyMinute()->withoutOverlapping();

withoutOverlapping() 不是裝飾:兩個 prune 行程同時跑會互相搶同一批列。

訊息還需要 queue worker。mail、sms、push、telegram 各有自己的 queue,而每條 queue 只能有一個 worker:

php artisan queue:work --queue=messaging-mail
php artisan queue:work --queue=messaging-sms
php artisan queue:work --queue=messaging-push
php artisan queue:work --queue=messaging-telegram

worker 會睡掉供應商的 interval 來節流,所以 --timeout 與 connection 的 retry_after 都必須大於最大的 interval。這三個數字沒對齊、或漏開一條 worker 的後果與訊號,見派送與 worker。

五個必讀概念

1. 回應永遠是 HTTP 200,狀態碼在 body 裡

{ "success": true,  "data": { } }
{ "success": false, "code": 404, "error": "data-not-found", "message": "查無資料" }
{ "success": false, "code": 422, "error": "validation-failed", "message": "...", "fields": { "username": ["required"] } }

這不是風格偏好:客戶端的防火牆會擋掉非 200 的回應。error 欄位就是 i18n key,message 是後端已經翻好的字串 —— 前端可以直接顯示 message,也可以拿 error 自己對照。唯一的例外是 GET api/files/{path}——它要直接當 <img src> 或瀏覽器重定向目標用,回真正的 302/404,不走信封(見「端點」表)。

信封的範圍是套件的兩個路由前綴。 admin/ 與 api/ 底下打不到的路徑、用錯方法的請求,都會回信封格式的 404,GET api/files/{path} 除外——它是刻意不信封化的公開檔案讀取端點。這兩個前綴之外的請求不受影響 —— 你自己的網頁 404 還是 Laravel 原本的樣子。

代價要知道:因為兜底路由吃下所有方法,「方法用錯」不再回 405,而是回 404 信封。前端分不出「網址拼錯」與「方法用錯」。

2. 全部端點都是 POST

除了 GET api/files/{path}(公開檔案讀取,詳見「端點」表)之外,其餘沒有一個 GET。讀取(清單、詳情)也是 POST。用 GET 打其他端點會拿到 404 信封。

3. 身分、middleware,以及順序

順序是約束,不是機制保證。 把 permission-api 掛在 user-api 前面不會有人阻止你,但授權會先跑,拿到的是 401 而不是 403。

token 兩種帶法:Authorization: Bearer {token},或登入時自動下的 matrix-user cookie。cookie 是 httpOnly,secure 跟隨 config('session.secure') —— 本機開發走 HTTP 時那個值必須是 false,否則瀏覽器不會回送,症狀是「登入成功但下一個請求就 401」。跨網域的前端要送 credentials: 'include',而且 CORS 要自己設(套件的前綴不在 Laravel 預設的 cors.paths 裡)。

4. 選單即權限

選單樹不只是導覽,它就是權限模型本身。

// resources/menu/{bundle}.php —— 縮排跟著選單層次,不是格式錯誤
'widget' => ['icon' => 'fa-solid fa-cube', 'ranking' => 100, 'parent' => 'catalog', 'group' => true, 'tag' => 'query'],

    'widget/{id}' => ['parent' => 'widget', 'tag' => 'query'],
    'widget/{id}/update' => ['parent' => 'widget', 'tag' => 'update'],
    'widget/delete' => ['parent' => 'widget', 'tag' => 'delete'],
    'widget/insert' => ['parent' => 'widget', 'tag' => 'insert'],
    'widget/new' => ['parent' => 'widget', 'tag' => 'insert'],

三條規則:

1. key 就是路由 URI(去掉 admin/ 前綴),逐字相同,含 {id} 佔位符。
2. group => true 的節點是授權單位,它底下子節點的 tag 匯總成可以授予的動作。
3. 每一個端點都必須有對應的節點。漏一個,那個端點對所有人回 403 —— 包含 ROOT。

權限值存在 base_user.permissions 與 base_group.permissions 兩個 jsonb 欄位,形狀是 {"widget": {"query": true}}。

等級寫在主鍵裡:

共用 sequence 從 10000000 起跳,所以後台介面建出來的帳號一律是 Regular —— 等級不可能被提權改掉,因為它不是一個欄位。管理員只能用 seeder 或手動指定 id 建立。

帳號管理也遵守同一個階層:Root 可以管理所有帳號;Admin 可以管理 Admin 與 Regular,但看不到 Root;Regular 即使取得 user 權限,也只能管理其他 Regular。超出可管理範圍的帳號在清單中不會出現,讀取、更新與刪除則回 data-not-found;任何帳號都不能刪除自己。

5. 資源疊層:你的檔案覆蓋套件的

設定、翻譯、選單都走同一套疊層。config('matrix.packages') 出貨 'app base',app 就是你的 Laravel 專案,排前面的覆蓋排後面的。

bundle 一律扁平:只有一層 key,key 本身可以含點,取值時當字面看待,不做巢狀路徑解析。

resources/style/cfg/{bundle}.php 只是欄位型別表,不是欄位白名單——沒被它列到的 key 照樣會出現在資源後台,型別退回 text、呈現退回 plain。唯一的例外是標記了 'secret' => true 的 key:

'password' => ['type' => 'text', 'presentation' => 'password', 'secret' => true],

機密欄位的實際值永遠不離開伺服器——data 回傳的是遮罩 ••••••••(沒設定過則是空字串),default 與 placeholder 一律空白。寫回時遮罩值代表「不變更」,送新值才覆寫,送空字串才清除。出貨已標的是 gmail.password、telegram.bot-token、telegram.webhook-secret、webpush.private-key、mitake.password、google-translate.api-key、ip2location-bin.download-token、ip2location-webservice.api-key、captcha-recaptcha.secret、captcha-turnstile.secret;自訂 bundle 裡的憑證要自己標,漏標的症狀是那把密鑰以明文出現在後台 API 回應裡。

這一層跟 matrix.resource-cfg 的 bundle 白名單是兩件事:白名單決定「這個 bundle 能不能編輯」,secret 決定「bundle 裡哪些 key 的值看得到」。有了後者,含憑證的混合型 bundle 才能安全地進白名單。

合併是逐 key 遞迴的（排前的覆蓋排後的、key 對 key）,所以覆蓋一個選單節點時,低優先層那個節點多出來的 key（icon、tag 之類）會滲進合併結果,沒辦法個別移除。要整個移除一個節點,把該 key 的值設成 null —— 節點消失、端點對所有人 403、群組離開權限樹。但移除節點只擋端點與新授權:已經授出的權限仍然有效,因為授權檢查讀的是 base_user.permissions / base_group.permissions 存的 JSON,不是選單樹。

開一個自己的功能

以一個 Widget 為例,六個步驟,少一個都不會動。

資料表已經 migrate 好的話,可以先跑 matrix:make-crud {table} 偷懶:它會反向產生步驟 2、3、4 的 Model/Declaration/Controller 草稿,以及步驟 6 欄位標題用的 resources/i18n/{locale}/model/{table}.php。它是輔助草稿工具,不是黑盒——呈現方式、--title、--parent 猜不到或猜錯風險高的地方一律留白或印出警示,產生後務必自己核對一遍再送出,路由/選單/選單翻譯仍要照下面步驟 5、6 手動加。細節看主控台指令。

1. 資料表

Schema::create('base_widget', function (BaseBlueprint $table) {
    $table->primaryKey();                    // 抽 base_id 共用序列
    $table->text('title');
    $table->integer('category_id')->nullable();
    $table->ranking();                       // 抽 base_ranking 共用序列,要拖曳排序才需要
    $table->schedules();                     // enable_time / disable_time,需要上下架才用
    $table->auditings();                     // create_time / update_time / creator_id / updater_id
});

型別提示寫 BaseBlueprint 而不是 Blueprint,否則靜態檢查看不到那幾個自訂方法。

主鍵一定要走 primaryKey()。 用 $table->id() 會拿到從 1 開始的 bigint,而 id 1 是 ROOT —— 稽核紀錄的歸屬會靜默錯亂。

2. Model

class Widget extends BaseModel {

    protected $table = 'base_widget';

}

3. 欄位宣告 —— 沒有它,CRUD 端點會 500

#[Declared(WidgetDeclaration::class)]
class Widget extends BaseModel { }

class WidgetDeclaration implements Declares {

    /**
     * @return array<string, Definition>
     */
    public function definitions(): array {
        return array_merge(
            Definitions::primaryKey(),
            [
                'title' => Definition::text(),
                'category_id' => Definition::integer()
            ],
            Definitions::schedules(),
            Definitions::auditings()
        );
    }

    public function metadata(): Metadata {
        return new Metadata('widget', 'title');
    }

}

Metadata 的第一個參數是 alias,它必須等於選單節點的路徑前綴;第二個是「這一列叫什麼」的欄位（麵包屑與排序頁會用）。第三個參數可以指定父層關聯,巢狀資源才需要。第四個參數 ranking 可指定排序用的欄位名稱,CrudController 會用它推導預設的 $sorting/$sortable;第五、六個參數 enable/disable 標記上下架時間欄位,接上後解鎖 POST admin/schedule/toggle(單筆立即切換)與 admin/{prefix}/arrange、arrange/save(拖曳式批次上下架)兩支既有 API。

沒有 #[Declared] 的 model 一進 CRUD 端點就是 undeclared-model。

JSON 欄位形狀依情境動態變動,用 Definition::composite()。

'data' => Definition::composite('announcement-data')

參數是一個 cfg group 名稱,對應 resources/cfg/{group}.php。這份 cfg 檔案要有一個 driver key,指向你自己實作的 TypeResolver(resolve(?Model $model, mixed $input): ?string,沿用既有 resolve_driver() 慣例),負責當下算出一個「type 字串」;其餘 key 是「type 字串 → 子欄位定義 class」的對照表,每個子欄位定義 class 實作 Variant(格式跟 Declares::definitions() 一樣,但不用寫 metadata())。表單裡會依 driver 算出的 type 展開對應的子欄位、送出時驗證、存檔轉回單一 JSON。

這個欄位不需要對應到任何真實的 DB 欄位存 type 值——TypeResolver::resolve() 要依據什麼判斷(另一個欄位的值、目前操作者、資料庫查詢……)完全是你的邏輯,引擎只在需要知道「這次要用哪個 variant」的當下呼叫它。沒有設定 driver 時安全降級成不展開、不驗證,不會出錯。只支援一層,子欄位不能再是 Definition::composite()。

4. Controller

class WidgetController extends CrudController {

    protected string $model = Widget::class;

    protected ?array $lists = ['title', 'category.title=category_title', 'enable_time'];

    protected array $updates = ['*title', 'category_id:select', 'enable_time', 'disable_time'];

}

* 開頭代表必填。= 後面是別名。. 走關聯。: 後面是型別或呈現方式。

5. 路由 —— 必須掛在 admin 前綴之下

Route::middleware(['encrypted-api', 'envelope-api', 'locale-api'])->group(function () {
    Route::prefix(config('matrix.admin-api-prefix'))->group(function () {
        Route::middleware(['user-api', 'permission-api'])->group(function () {
            ActionRoutes::mount('widget', WidgetController::class);
        });
    });
});

前綴不對,AdminPermission 認不出這是套件的路由,全部 403。

encrypted-api 漏掉的話,那一組路由不會解密,但前端還是會加密。 前端是按前綴決定要不要封信封的(它不知道哪些路由掛了什麼 middleware),所以你自己的 admin 端點只要少掛這一層,收到的 body 就是 {kid, epk, iv, ts, ct} 這個信封本身,症狀是每一個欄位都 validation-failed。這三個別名的順序也是約束:encrypted-api 必須在 envelope-api 之前,否則錯誤信封不會被加密。

6. 選單與翻譯

resources/menu/app.php（然後把 admin-menus 改成 'app base'）:

'catalog' => ['icon' => 'fa-solid fa-box', 'ranking' => 300, 'parent' => null],

    'widget' => ['icon' => 'fa-solid fa-cube', 'ranking' => 100, 'parent' => 'catalog', 'group' => true, 'tag' => 'query'],

        'widget/{id}' => ['parent' => 'widget', 'tag' => 'query'],
        'widget/{id}/update' => ['parent' => 'widget', 'tag' => 'update'],
        'widget/delete' => ['parent' => 'widget', 'tag' => 'delete'],
        'widget/insert' => ['parent' => 'widget', 'tag' => 'insert'],
        'widget/new' => ['parent' => 'widget', 'tag' => 'insert'],

resources/i18n/en/menu/app.php 放對應標題,resources/i18n/en/model/base_widget.php 放欄位標題:

return [
    'title' => 'Name',
    'title:placeholder' => 'Enter a name',
    'category_id' => 'Category',
];

欄位標題找不到時的行為是「看起來正常但可能不對」 —— 先退到 model/default.php 的通用標籤（create_time 之類的共用欄位都在那裡）,再退到字面 {title}。所以漏翻譯不一定看得出來。

前台身分（member / vendor）

套件只提供零件,整個流程歸你:

訊息

送訊息

MailService、SmsService、PushService、TelegramService 共用同一組公開介面(定義在 MessageService):schedule()、send()、resend()、cancel()。

app(MailService::class)->schedule(now()->addHour(), 'alice@example.com', 'welcome', ['name' => 'Alice']);
app(SmsService::class)->send('0912345678', 'otp', ['code' => '123456']);
app(PushService::class)->send('42', null, [], ['provider' => 'webpush', 'title' => '通知', 'content' => '你有一筆新訂單']);
app(TelegramService::class)->send('42', null, [], ['provider' => 'telegram', 'content' => '你有一筆新訂單']);

app(MailService::class)->resend($id);
app(MailService::class)->cancel($id);

schedule($at, $to, $template = null, $vars = [], $options = []) 回傳寫進 base_mail_log / base_sms_log / base_push_log / base_telegram_log 的那一列;send($to, $template = null, $vars = [], $options = []) 是 schedule(now(), ...) 的薄封裝,等同「立即送」。樣板檔案放 resources/i18n/{語系}/template/{name}.php。resend(int|string $reference) 複製一筆既有紀錄(清空 send_time / response / error、schedule_time 設回 now())重新排入佇列,原始那筆不受影響;cancel(int|string $reference) 只對還是 Scheduled 的紀錄生效,把它改成 Failed(error 設為 'cancelled'),對已經是終端狀態(Success / Failed)的紀錄呼叫是冪等的,不會報錯也不會改動它。

派送與 worker

後台查詢、重發與取消

mail-log / sms-log / push-log / telegram-log 四個 Admin controller 都繼承同一個抽象基底 MessageLogController,唯讀:只有列表({prefix})、查看單筆({prefix}/{id})、{prefix}/{id}/resend、{prefix}/{id}/cancel 四個動作有登記選單節點、對授權使用者開放,其餘 CRUD 動作(見上方端點表的附註)一律 403。resend/cancel 內部就是呼叫對應 MessageService 的同名方法,回傳 {"id": ...}(resend 是新那筆的 id)。四個 controller 本身沒有額外邏輯,只設定各自的 $model、$service、$lists。

Push 訂閱(Member)

Push 是唯一需要前端配合的通道:瀏覽器要先用 Web Push API 取得 endpoint / keys.p256dh / keys.auth,再呼叫 MemberPushSubscriptionController 存進 base_push_subscription,PushService::send() 才推得出去。

Service worker 註冊、Notification.requestPermission()、呼叫這兩支 API,都是前端(消費端 repo)的工作,不在這個套件範圍內。

Telegram 綁定與 Webhook

Telegram 的訂閱對象是後台使用者(User),不是前台會員(Member)——這個通道設計給營運/維運告警之類「後台人員自己訂閱通知」的情境。base_telegram_log.chat_id 是雙語意欄位,不額外加欄位區分,靠「查不查得到訂閱紀錄」解析:TelegramDriver 先判斷這個值是不是負數——Telegram 的規則是群組/頻道 chat_id 恆為負數、個人(這裡是 User)恆為正數,天然不會撞號,所以負數直接當成目標 chat_id 送(固定群組/頻道模式,send($chatId, ...) 時 $to 直接傳 chat_id 字串),連查都不用查;非負數才去查 base_telegram_subscription.user_id,查到就送去對應的訂閱 chat_id(User 訂閱模式),查不到就跟負數的情況一樣、把值本身當字面 chat_id 送。

跟 Push 用 JS 直接呼叫 subscribe API 不同,User 訂閱需要使用者主動在 Telegram 裡點一個連結、跟 bot 對話。綁定端點掛在 admin 前綴、user-api middleware 底下(跟 admin/user/preference 同層,不需要額外權限,登入即可管理自己的綁定):

這是套件目前唯一一個接收外部主動呼叫的端點(前面所有端點都是「我們主動對外呼叫」或「被已登入使用者呼叫」),所以認證方式也不同——不是 token,是 header:呼叫方要帶 X-Telegram-Bot-Api-Secret-Token,值要等於 cfg('telegram.webhook-secret'),對不上或這把密鑰根本沒設定,一律 403。跑 php artisan messages:telegram-webhook 之前記得先把 telegram.bot-token 與 telegram.webhook-secret 設定好(這支指令本身也會檢查,兩個空字串會直接失敗、不呼叫 Telegram)。

無效或已過期的 token 會被靜靜忽略(不是 /start 開頭的訊息也一樣),webhook 一律回 200 系列的成功——Telegram 只在乎「有沒有收到」,不在乎綁定有沒有真的成功。

自訂訊息通道

參考

以下表格是契約。守門測試（tests/Feature/ReadmeTest.php）會把第一欄的識別字拿去跟實際的路由表、設定、指令、資料表對照 —— 表格寫錯或程式改了沒回來改表,測試就會紅。

端點

除了 GET api/files/{path}(公開檔案讀取,見下方說明)之外,其餘全部是 POST。路徑省略前綴（admin、api 與 vendor 分別來自 matrix.admin-api-prefix、matrix.api-prefix 與 matrix.vendor-api-prefix）。

POST encryption-key 是唯一不在任何前綴底下的端點:三組 API 共用同一個金鑰圈,而它是拿公鑰的地方,所以它不能落在任何一組的加密範圍裡——沒有公鑰就沒有信封,拿公鑰的請求自己不可能是信封。它同時也宣告了 #[Action(encrypted: false)],所以「它是明文」是寫下來的事實,不是靠它剛好落在所有前綴之外推論出來的。

GET api/files/{path} 是唯一的例外:不需要身分、不走信封,直接回 302(公開上傳檔案)、200(串流,drive-linked 檔案)或 404(私有/不存在)。路由用 Route::get() 註冊,Laravel 會自動一併掛上 HEAD(任何 Route 只要方法含 GET 就一定含 HEAD,框架內建行為,無法關閉),所以「端點」表裡這一列的方法欄是 GET\|HEAD。

「授權」= 登入 + 該選單節點的權限。user / group 的 export、copy、sort 端點存在但套件出貨的選單沒有對應節點,所以預設對所有人 403 —— 那三個動作在套件自己的兩個 controller 上是關閉的。mail-log / sms-log / push-log / telegram-log 更進一步:選單只登記了列表、{id}、{id}/resend、{id}/cancel 四個節點,其餘十個(new、insert、{id}/update、{id}/copy、delete、export、sort、sort/save、arrange、arrange/save)全部因為選單沒有節點而預設對所有人(含 ROOT)403——是刻意設計,訊息紀錄只能查詢與重發/取消,不能被手動增刪改。api/telegram/webhook 標「匿名*」是因為它不掛任何登入態 middleware(呼叫方是 Telegram 伺服器,沒有我們的 session/token 可帶),但自己驗證 X-Telegram-Bot-Api-Secret-Token header 等於 cfg('telegram.webhook-secret'),沒設定這把密鑰就對所有請求一律 403(見Telegram 綁定與 Webhook)。

設定鍵

config/matrix.php。改任何一個都要記得 mergeConfigFrom 只合併頂層 key。

白名單只擋非 ROOT。ROOT 不受它限制。

cfg 設定鍵

可以在資源後台線上編輯,也可以在自己的 resources/cfg/{bundle}.php 覆蓋。

gmail、mitake、webpush 與 telegram 是出貨的供應商 bundle。加一個供應商就是加一份 resources/cfg/{名稱}.php,鍵的形狀照上面四組。

主控台指令

錯誤代碼

資料表

給前端

請求形狀

清單（POST admin/widget）:

{
  "filters": {
    "title": { "op": "contains", "value": "abc" },
    "status": { "op": "in", "value": [1, 2] },
    "create_time": { "op": "between", "from": "2026-01-01 00:00:00", "to": "2026-01-31 23:59:59" }
  },
  "sort": [{ "name": "create_time", "direction": "desc" }],
  "page": 1,
  "size": 10
}

• 每個欄位可以用哪些 op,由清單回應的 columns[].op 告訴你。送不被允許的欄位或運算子會靜默忽略,不會報錯。
• between 用 from / to（可以只給一邊）,其餘用 value。
• date / datetime 欄位的值必須完全符合 columns[].format 給的格式,一個字元都不能差:date 只收 matrix.date-format（出貨 Y-m-d）,datetime 只收 matrix.datetime-format（出貨 Y-m-d H:i:s）,兩者不互通。不符回 422 invalid-filter-value。所以查一整天要自己補時間:from 是 00:00:00、to 是 23:59:59——只送 2026-01-31 會被擋下,而在舊版那樣送會漏掉當天所有資料（BETWEEN 對 timestamp 欄位截在 00:00:00）。
• page 或 size 給 0 以下 = 不分頁,一次全回。

詳情 / 編輯頁（POST admin/widget/{id}）不需要 body。

新增與更新（admin/widget/insert、admin/widget/{id}/update）:欄位平鋪在最上層。

更新是全量覆寫,不是局部更新。 每一個可寫欄位都會被加上 present 驗證規則 —— 不送就是 422,送 null 就是把它清成 null。前端要送完整的表單,不能只送改過的欄位。

刪除:{"id": [1, 2, 3]},任一筆不存在整批失敗（data-not-found）。

拖曳排序儲存（admin/widget/sort/save）:{"order": [3, 1, 2]},必須是完整集合,少一筆就是 invalid-sort-order。

回應形狀

清單回應含 columns（欄位描述）、rows、pagination、actions、title、麵包屑等。columns[] 每一項的三個維度要分開讀:

• type 是資料型別（text / integer / float / boolean / date / datetime / json）—— 決定驗證與比較。
• presentation 是呈現方式（plain / hidden / select / multi-select / password / count / switch）—— 決定畫面怎麼畫。宣告時給的字串若不是這七個,會原樣送給前端,那是自訂呈現方式的出口。
• writable 是這一欄送回來會不會被寫入。

一個「有選項的整數欄位」是 type: integer + presentation: select,三個維度都完整。

type 是 date 或 datetime 的欄位另外帶一個 format(例如 YYYY-MM-DD、YYYY-MM-DD HH:mm:ss,即 matrix.date-format / matrix.datetime-format 轉成前端慣用的日期格式代號),rows/data 裡該欄位的實際字串就是照這個格式輸出;其餘型別 format 是 null。

不可寫有兩種原因:readonly 宣告、以及跨關聯或聚合欄位(group.title、count(orders))。 只有第一種在 columns[] 上另有 readonly 鍵看得出來,所以前端要看 writable,不要看 readonly —— 否則第二種會畫出一顆改了完全沒效果的輸入框,而使用者會看到「已儲存」。virtual(+ 前綴)不影響 writable:虛擬欄位不落庫,但照樣可以收值交給 guards / 覆寫的 service 處理。

writable: false 的欄位不在 present 驗證的範圍內,送不送都可以;writable: true 的每一個都必須出現在 body 裡,那與上面「更新是全量覆寫」是同一件事的兩面。

action 的 url 不含前綴。 回應給的是 widget/{id}/update 這種相對路徑,前端要自己接上 admin/。

語系

送 Matrix-Locale: en header。值必須在 matrix.locales 裡,否則退回應用程式的預設語系。

驗證碼

前後端必須成對。 後端的 matrix.admin-captcha-provider 決定驗哪一種憑證,前端的 config.captcha 決定畫哪一種元件——兩邊對不上的話登入一律 422。每個 driver 會宣告自己要哪些憑證欄位(captcha-image 要 token + code,Turnstile / reCAPTCHA 只要 token,captcha-none 兩個都不要),所以前端少送的時候錯誤是 validation-failed 並在 fields 裡指名缺的是 token 還是 code,而不是含糊的驗證碼錯誤。

這個鍵只管後台登入。前台(member / vendor)的登入端點本來就要你自己做,要驗證碼就自己呼叫 app(CaptchaService::class)->driver('captcha-turnstile')——bundle 名必填,套件沒有替前台準備設定鍵,所以前後台要不要用同一個 driver 完全由你決定。

前端那半邊在宿主應用的 src/router/index.js:

initConfig({
    captcha: MxCaptchaTurnstile,
    captchaSiteKey: "0x4AAAAAAA..."
});

site key 是公開值,本來就會出現在前端 bundle 裡;secret 相反,只放後端。兩個 cfg bundle 的 secret 出貨都是空字串,自己填——空著不會放行,而是每次驗證都失敗、登入一律擋下。不想改檔就用 base_resource_override 存(見驗證碼服務掛掉時怎麼進後台),那張表同樣吃得下 secret。

⚠️ action 兩邊都寫死成 login。 前端的 turnstile.js / recaptcha.js 裡是常數、不吃設定,後端 cfg('captcha-{turnstile,recaptcha}.action') 的出貨值也是 login。只改後端那一個會讓每次驗證都失敗——要改就兩邊一起改,不然別動。

Cloudflare Turnstile

1. Cloudflare 儀表板 → Turnstile → 新增 widget,Widget Mode 選 Managed。
2. 把要跑後台的網域加進 widget 的 hostname 清單(本機開發另外加 localhost)。
3. Site Key 填進前端的 captchaSiteKey,Secret Key 填進 cfg('captcha-turnstile.secret')。

前端 render 時帶 appearance: "interaction-only",所以多數訪客什麼都不會看到,只有被判定可疑的才跳挑戰。這個外觀設定只對 Managed 與 Non-Interactive 生效——widget 建成 Invisible 的話它不起作用。

Google reCAPTCHA

前端載的是 enterprise.js、呼叫 grecaptcha.enterprise.execute(),所以要建的是 reCAPTCHA Enterprise 的 score-based key(傳統 v2 那種勾選框已經無法申請新金鑰)。

1. Google Cloud Console → Fraud Defense(reCAPTCHA 現在的所在)→ Keys → 新增 website key,類型選 Score-based。
2. 網域加進該 key 的 domain 清單。
3. Key ID 就是 site key,填進前端的 captchaSiteKey。
4. Secret 要另外拿:Key details → Integration 分頁 → Use Legacy Key,對話框裡那把才是 cfg('captcha-recaptcha.secret') 要的值。

⚠️ 第 4 步是最容易卡住的地方。Enterprise 的 key 詳情頁預設不顯示 secret key,因為 Google 假設你會用 CreateAssessment API(要 service account)。這個 driver 走的是舊的 siteverify 端點,吃的是那把 legacy secret——每一把 Enterprise key 都有,只是藏在 Use Legacy Key 後面。

分數門檻是 cfg('captcha-recaptcha.threshold'),出貨 0.5。調它之前先看已知限制與取捨裡關於「分數不夠的真人沒有自證管道」那條。

傳輸加密

三組前綴各有各的開關,出貨值是 admin 開、vendor 開、api 關。開關關著的那一組一切照舊,以下完全不存在。開著的那一組,該前綴底下所有 POST 端點(除了宣告 #[Action(encrypted: false)] 的 action)的 request 與 response body 都是加密信封,明文請求一律回 invalid-envelope。

後台前端只打 admin,所以下面一律以它為例。

每開一個分頁做一次:POST encryption-key(明文,不在任何前綴底下)拿 {"kid", "public_key"},public_key 是 base64 的 SPKI DER,用 crypto.subtle.importKey('spki', ..., {name: 'ECDH', namedCurve: 'P-256'}, false, []) 匯入。

每次呼叫做一次:產生一組用完即丟的 P-256 金鑰對 → 跟伺服器公鑰做 ECDH → HKDF-SHA256 衍生出這次專用的 AES-256-GCM 金鑰,參數是 salt 空、info 為 UTF-8 的 matrix-api-v1、長度 256 bit。

{ "kid": "...", "epk": "<base64 SPKI>", "ts": 1757000000, "iv": "<base64 12 bytes>", "ct": "<base64 密文+tag>" }

• ts 是秒為單位的 Unix 時間戳,與伺服器時間差超過 cfg('encryption.window') 就是 invalid-envelope。
• epk 是一次性公鑰,同時當作防重放的 nonce:同一個 epk 只能用一次,重送第二次是 invalid-envelope。
• AAD 是 request|{METHOD} {path}|{ts} 的 UTF-8 位元組。path 是完整的 URL 路徑去掉開頭斜線(即瀏覽器的 new URL(...).pathname,應用程式裝在子目錄時包含子目錄),例如 request|POST admin/user/insert|1757000000。少了它,同一份密文可以被原封不動搬去別支端點。
• ct 是 crypto.subtle.encrypt 的原始輸出(密文後面接 16 bytes 的 GCM tag),不用自己拆。

回應是 {"iv", "ct"},用同一把衍生金鑰、新的 IV、AAD 換成 response|{METHOD} {path}|{ts}。解開之後才是平常那個 {"success": ...} 信封,錯誤信封也一樣被加密。

唯一的例外是解密失敗:中介層自己擋下來的錯誤沒有金鑰可以加密,會以明文回 {"success": false, "code": 400, "error": "invalid-envelope", "message": "..."}。前端在解密前必須先認這個形狀,不要無條件把回應丟進 crypto.subtle.decrypt。

沿用套件的 lint

選用。 前提是你的 app 也照套件那套風格公約寫:<?php //> 開頭、class 主體前後空一行、成員字母序、禁 ??、禁 saveQuietly 一類繞過 model 事件的寫法。不打算全套照用就不要接 —— 這些檢查沒有開關。（違規訊息會引用 CLAUDE.md,那是套件自己的風格公約文件,沒隨套件出貨,規則摘要見本節末的表格。）

套件的 require-dev 不會遞移到你的專案,工具要自己裝:

composer require --dev friendsofphp/php-cs-fixer larastan/larastan

1. composer.json

"scripts": {
    "format": "php-cs-fixer fix",
    "lint": [
        "php-cs-fixer fix --dry-run --diff",
        "@php vendor/matrix-platform/laravel-base/bin/style-check.php"
    ],
    "stan": "phpstan analyse --memory-limit=1G"
}

style-check.php 不傳參數時檢查當前工作目錄,而 composer script 的 cwd 就是 composer.json 所在的目錄,所以不用給路徑。要檢查別的目錄就傳第一個參數:@php vendor/.../bin/style-check.php packages/foo。

2. .php-cs-fixer.php

finder 指你自己的目錄,rules 引用套件那一份:

<?php //>

$finder = PhpCsFixer\Finder::create()
    ->in([__DIR__ . '/app', __DIR__ . '/config', __DIR__ . '/database', __DIR__ . '/resources', __DIR__ . '/routes', __DIR__ . '/tests'])
    ->name('*.php')
    ->notPath('#(^|/)menu/[^/]+\.php$#');

return (new PhpCsFixer\Config())
    ->setFinder($finder)
    ->setIndent('    ')
    ->setLineEnding("\n")
    ->setRiskyAllowed(false)
    ->setRules(require __DIR__ . '/vendor/matrix-platform/laravel-base/.php-cs-fixer.rules.php');

notPath 那行不要省。選單 bundle（menu/*.php,含 resources/i18n/*/menu/*.php）的縮排跟著選單層次走,array_indentation 會把它拉平。

3. phpstan.neon

這裡沒有共用檔:套件的設定只有 level: 8 一個參數,抄一行比多一層 include 划算。

includes:
    - vendor/larastan/larastan/extension.neon

parameters:
    level: 8
    paths:
        - app
        - tests
    tmpDir: build/phpstan

style-check 檢查什麼

腳本掃 app、bin、config、database、resources、routes、src、tests,不存在的目錄跳過,所以套件與宿主共用同一份預設。規則按路徑前綴分派:

程式碼放在這幾個目錄之外（例如模組化的 modules/）就完全不會被掃到,前綴對不上的部分也會靜默跳過對應檢查 —— 沒有警告。

已知限制與取捨

每一條都是刻意的決定或已知的缺陷,不是待辦清單。放在這裡是因為它們會影響你的部署決定。

安全

驗證碼服務掛掉時怎麼進後台

config/matrix.php 出貨模板裡沒有任何 env(),所以照抄的話改 provider 等於改檔加重新部署 —— 凌晨三點那不是逃生門。資源後台的 cfg 編輯介面也不能用,因為它要先登入,而登入正是被擋住的那件事。

第一道逃生門其實很便宜:那個檔案是你自己應用的(套件只 mergeConfigFrom 預設值,見安裝),所以你大可自己寫成 'admin-captcha-provider' => env('MATRIX_ADMIN_CAPTCHA_PROVIDER', 'captcha-none'),事後只要改 .env。代價是若有 config:cache 就得再跑一次 php artisan config:cache —— 零改碼,但不是零操作。

沒事先鋪這條線、而且現在不能部署的話,才輪到下面這個:

實際可用的是 DB override(Resources::overrides() 會把 base_resource_override 疊在 cfg 預設值上):

INSERT INTO base_resource_override (bundle, data, create_time)
VALUES ('cfg/captcha-turnstile', '{"driver":"MatrixPlatform\\Captcha\\NoneDriver"}', NOW());

⚠️ 那是兩個反斜線,不是四個,而且 create_time 不能省。 PostgreSQL 的 standard_conforming_strings 預設是 on,字串字面量裡的反斜線不再被跳脫,所以 JSON 的 \\ 剛好解成一個反斜線;寫成四個會存進 MatrixPlatform\\Captcha\\NoneDriver,那不是合法的類別名稱,resolve_driver() 會改丟 invalid-captcha-driver —— 逃生門反而把門鎖得更死。create_time 是 NOT NULL 且沒有預設值,漏掉會直接被資料庫擋下(這個至少是大聲失敗)。

php artisan matrix:clear-resource-cache

驗證碼立刻放行,零部署、零改檔。清快取那一步不能省 —— overrides() 是 rememberForever。

同一張表也可以只調參數而不整個關掉,例如把 reCAPTCHA 的分數門檻放寬:{"threshold":0.1}。

⚠️ 服務恢復之後,先前被擋掉的失敗仍然佔著登入節流的配額,可能還要等一個 admin.login-throttle-window 或自己清掉 rate limiter。

⚠️ 新增或改動 cfg bundle 的檔案之後也要跑同一個指令 —— Resources::merge() 把「這個 bundle 不存在」也一起 forever 快取了,不清的話會一直拿到 invalid-captcha-driver。

規模與效能

資料生命週期

行為細節

請求與交易

權限與帳號

複製、匯出與排序

資料寫入與稽核

選單與回應契約

從舊版升級

這是下一個大版本,不保證與舊版相容。已知要動的: