From 34b7aa7a91398c493217320e96a62130065d9140 Mon Sep 17 00:00:00 2001
From: unknown <kate522@88.com>
Date: Fri, 17 Jul 2026 19:30:53 +0800
Subject: [PATCH] fix(autoload): canary DomainModel after Composer load

Stale vendor/ after the PSR-4 cutover omits AKSRT\ from
autoload_psr4, so helpers fatal on DomainModel constants.
Fail loud with composer install/dump-autoload guidance and
document the deploy step in README + ADR.
---
 README.md                             | 38 +++++++++++++++++++++++++--
 functions.php                         | 18 +++++++++++--
 tools/adr-classes-domain-placement.md |  7 +++--
 3 files changed, 57 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index a1a51ca7..722c776f 100644
--- a/README.md
+++ b/README.md
@@ -94,14 +94,48 @@ AKSRT-theme/
 
 ## 安装方式
 
+主题类型（`AKSRT\…`）通过 Composer PSR-4 从 `src/AKSRT/` 自动加载；`vendor/` 不进 Git。**部署或更新主题后必须在主题根目录生成 autoload**，否则会出现 `Class "AKSRT\Core\DomainModel" not found` 等致命错误。
+
+### 前置：Composer（必做）
+
+在主题目录（含 `composer.json` 的那一层）执行：
+
+```bash
+# 首次或依赖变更后（安装第三方库 + 生成主题 PSR-4）
+composer install --no-dev --optimize-autoloader
+
+# 仅 composer.json autoload 映射变更时（无需重下包）
+composer dump-autoload -o
+```
+
+确认：
+
+```bash
+php -r "require 'vendor/autoload.php'; echo class_exists('AKSRT\\\\Core\\\\DomainModel') ? \"ok\\n\" : \"missing\\n\";"
+```
+
+应输出 `ok`。若 PHP 开启了 OPcache，重载 php-fpm / 重启 PHP 后再访问站点。
+
 ### 方式一：直接上传（推荐）
 
 1. 将整个 `AKSRT-theme` 文件夹上传到 `wp-content/themes/`
-2. WordPress 后台 → **外观** → **主题** → 找到 **AKSRT** → **激活**
+2. 在服务器主题目录执行上一节的 `composer install`（若打包时已带上完整 `vendor/` 且已 `dump-autoload`，可跳过）
+3. WordPress 后台 → **外观** → **主题** → 找到 **AKSRT** → **激活**
 
 ### 方式二：ZIP 打包上传
 
-压缩为 `.zip` 后通过 WordPress 后台上传。
+压缩为 `.zip` 后通过 WordPress 后台上传；上传后同样需要在服务器主题目录生成/校验 Composer autoload（见上）。
+
+### 生产急救（已白屏 / DomainModel not found）
+
+SSH 进入主题目录后：
+
+```bash
+cd /path/to/wp-content/themes/AKsrt-theme   # 以实际路径为准
+composer install --no-dev --optimize-autoloader
+# 或仅刷新映射：composer dump-autoload -o
+# 可选：reload php-fpm / 清 OPcache
+```
 
 ---
 
diff --git a/functions.php b/functions.php
index 96334071..da58522d 100644
--- a/functions.php
+++ b/functions.php
@@ -63,18 +63,32 @@ if (!function_exists('aksrt_get_setting')) {
 }
 
 // ============================================================
-// 加载 Composer 依赖（OAuth2 客户端库等）
+// 加载 Composer 依赖（第三方库 + 主题 PSR-4：AKSRT\ → src/AKSRT/）
 // ============================================================
 $composer_autoload = AKSRT_DIR . '/vendor/autoload.php';
 if (!file_exists($composer_autoload)) {
     wp_die(
-        esc_html__('AKSRT requires Composer dependencies. Run composer install in the theme directory.', 'aksrt'),
+        esc_html__('AKSRT requires Composer dependencies. Run "composer install" in the theme directory.', 'aksrt'),
         esc_html__('AKSRT theme', 'aksrt'),
         ['response' => 500]
     );
 }
 require_once $composer_autoload;
 
+// Theme classes live under src/AKSRT/ and only load via Composer PSR-4.
+// Stale vendor/ (e.g. install before composer.json gained "AKSRT\\") leaves
+// autoload_psr4 without AKSRT\ and fatals on the first DomainModel reference.
+if (!class_exists(\AKSRT\Core\DomainModel::class, true)) {
+    wp_die(
+        esc_html__(
+            'AKSRT class autoload is incomplete: AKSRT\\Core\\DomainModel was not found. In the theme directory run "composer install" (or "composer dump-autoload -o"), then clear any opcode cache (opcache_reset / php-fpm reload).',
+            'aksrt'
+        ),
+        esc_html__('AKSRT theme', 'aksrt'),
+        ['response' => 500]
+    );
+}
+
 // ============================================================
 // 加载 Bootstrap（辅助函数 → 类文件 → 核心钩子）
 // ============================================================
diff --git a/tools/adr-classes-domain-placement.md b/tools/adr-classes-domain-placement.md
index 9c27987a..968e772d 100644
--- a/tools/adr-classes-domain-placement.md
+++ b/tools/adr-classes-domain-placement.md
@@ -42,8 +42,11 @@ Domain folders were frozen after the root→domain move. Theme types then migrat
 ### Loader
 
 1. `functions.php` loads `vendor/autoload.php` (Composer: third-party + theme PSR-4)
-2. `inc/bootstrap.php` loads helpers + procedural modules (`inc/modules/*`) + core-hooks only
-3. Singleton `init()` remains in `functions.php` using FQCNs
+2. Immediately after, canary `class_exists(\AKSRT\Core\DomainModel::class)` — if missing, `wp_die` with `composer install` / `composer dump-autoload -o` (stale `vendor/` after PSR-4 cutover is the common failure)
+3. `inc/bootstrap.php` loads helpers + procedural modules (`inc/modules/*`) + core-hooks only
+4. Singleton `init()` remains in `functions.php` using FQCNs
+
+Deploy note: `vendor/` is gitignored. After pull/upload, run `composer install --no-dev --optimize-autoloader` (or at least `composer dump-autoload -o`) in the theme root so `autoload_psr4` includes `"AKSRT\\": ["…/src/AKSRT"]`.
 
 ### Procedural (not PSR-4)