灯塔 CMS 开发文档

数据模型与迁移

SQLite 数据结构、价格模型和数据库迁移规范。

适用版本：1.3.4更新日期：2026-10-12

数据库设计

当前版本由 22 个核心迁移文件维护站点、商品、内容、应用商店和插件平台的数据结构。插件还可以在自己的命名空间内维护独立迁移。

核心业务表

表用途关键字段
settings全站设置key、value，包含 site_currency。
users后台账号role、permissions、password_hash。
product_categories商品分类slug、parent_id。
products商品slug、images_json、price_mode、deleted_at。
product_prices阶梯价格min_qty、max_qty、price。
product_skus多规格 SKUsku_name、min_qty、price、deleted_at。
posts文章、案例、页面post_type、slug、content、seo_*。
messages联系留言联系人、邮箱、电话、留言内容。
inquiries商品询盘商品、数量、客户信息、状态。
media_files媒体库文件路径、类型、大小、文件夹。
menus / menu_items导航菜单Slug、层级、排序、链接。
sliders / slider_items轮播图Slug、图片、标题、按钮链接。
app_store_theme_installs主题安装远程资源、版本、安装记录。
plugins / plugin_*插件平台版本、设置、迁移、任务、运行记录和日志。
update_logs更新日志版本、状态、日志、备份信息。
migrations迁移记录已执行迁移版本。

产品价格模式

products.price_mode 控制详情页显示方式：

值前台含义关联数据
tier阶梯价格product_prices
sku多规格 SKU 价格product_skus
range价格区间products.price_range_min、products.price_range_max
negotiable面谈价格不展示固定价格，引导询盘

辅助函数负责标准化模式：

function product_price_modes(): array {
    return ['tier', 'sku', 'range', 'negotiable'];
}

function normalize_product_price_mode(string $mode, string $fallback = ‘tier’): string {
return in_array($mode, product_price_modes(), true) ? $mode : $fallback;
}

兼容提醒

product_prices.currency 是历史字段。当前价格展示统一读取 settings.site_currency，避免同一站点不同产品显示混乱。

添加新数据表

新增数据表必须写迁移，不要直接修改现有数据库文件。

步骤：

  1. 在 app/Migrations/ 创建时间戳文件。
  2. up() 中创建表、索引和默认数据。
  3. down() 中写回滚逻辑。
  4. 创建模型封装读写。
  5. 在控制器中调用模型。
  6. 登录后台程序更新页检查迁移状态。

建议：

  • SQLite 中新增列前先检查列是否存在。
  • 表和索引使用 IF NOT EXISTS。
  • 迁移要幂等，重复执行不应破坏数据。
  • 不要在迁移里删除用户数据，除非功能明确要求且有备份。