面向扩展与主题开发的技术说明

技术栈

项目坚持零框架、零构建的部署体验，但内部仍然按清晰层次组织代码，便于后续扩展。

系统架构

请求从 Web 服务器重写到 index.php，入口文件完成环境初始化、自动加载、辅助函数加载、数据库连接和路由分发。

HTTP 请求
  -> Apache/Nginx 重写到 index.php
  -> 定义常量、Session、错误处理
  -> PSR-4 自动加载 App\ 命名空间
  -> 加载 app/Helpers/Helpers.php
  -> Database::getInstance() 并执行待处理迁移
  -> Router 匹配 app/routes.php
  -> Controller 调用 Model
  -> 渲染后台视图或 themes/{theme} 前台模板

路由与页面扩展

新增前台页面通常只需要注册路由、增加控制器方法和创建主题模板。不要把页面逻辑直接写进入口文件。

// 1. app/routes.php 注册路由
$router->add('GET', '/faq', [SiteController::class, 'faq']);

// 2. SiteController 添加方法
public function faq(): void
{
    $this->renderSite('faq', [
        'seo' => ['title' => 'FAQ']
    ]);
}

// 3. themes/default/faq.php 创建模板
// 使用 h()、url()、asset_url() 输出动态内容

数据库迁移

数据库结构演进通过 app/Migrations/ 下的时间戳文件管理。系统初始化数据库或发现新迁移时会自动执行，避免手动导入 SQL。

// app/Migrations/20260412120000_create_faqs_table.php
return new class {
    public function up(SQLite3 $db): void
    {
        $db->exec('CREATE TABLE IF NOT EXISTS faqs (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            question TEXT NOT NULL,
            answer TEXT NOT NULL,
            sort_order INTEGER DEFAULT 0,
            created_at TEXT NOT NULL
        )');
    }

    public function down(SQLite3 $db): void
    {
        $db->exec('DROP TABLE IF EXISTS faqs');
    }
};

数据模型

系统围绕外贸官网常见业务建模：用户、站点设置、产品、内容、询盘、留言、媒体、菜单、轮播和更新记录。

主题开发

主题是 SHOPAGG 的主要扩展面。主题目录只负责前台展示和可配置区块，不应修改核心表结构或破坏用户数据。

/*
Theme Name: Furniture
Theme URI: https://example.com
Author: Your Name
Description: B2B furniture website theme.
Version: 1.0.0
License: MIT
*/

// blocks.php
return [
    'home_featured' => [
        'label' => '首页 - 热销产品',
        'description' => '使用产品选择器勾选展示商品。',
        'fields' => [
            'heading' => ['type' => 'text', 'label' => '标题', 'default' => 'Hot Products'],
            'product_ids' => [
                'type' => 'product_picker',
                'label' => '勾选商品列表',
                'default' => '',
                'limit' => 8,
                'status' => 'active',
            ],
        ],
    ],
];

安全规范

模板和扩展代码必须尊重系统的安全边界，尤其是后台配置值、媒体路径、URL 和上传文件。

<h2><?= h(block('home_about', 'heading')) ?></h2>
<p><?= nl2br(h(block('home_about', 'text'))) ?></p>
<a href="<?= h(url('/products')) ?>">Products</a>
<img src="<?= h(asset_url($image)) ?>" alt="<?= h($title) ?>">

验收清单

新增功能或主题交付前，至少完成语法、字段、数据和响应式检查。以下命令来自项目文档中的主题质量要求。

# PHP 语法检查
find themes/{theme_name} -name '*.php' -print0 | xargs -0 -n1 php -l

# 检查产品选择器、媒体字段和轮播下拉
rg "product_picker|media_type_key|slider_slug|type' => 'select'" themes/{theme_name}/blocks.php

# 检查是否存在可疑静态产品字段
rg "item[0-9]+_(title|image|url)" themes/{theme_name}/blocks.php