程序更新与备份
Updater 模型负责程序更新相关能力：
- 获取当前版本。
- 检查远程更新。
- 下载更新包。
- 创建备份。
- 安装更新。
- 查看迁移状态。
- 执行待处理迁移。
- 写入更新日志。
维护人员在修改更新逻辑时必须考虑：
- 更新前备份是否可靠。
- 更新失败能否给出清楚错误。
- 是否会覆盖用户上传文件。
- 是否会覆盖用户自定义主题。
- 数据库迁移是否可重复检测。
- 更新日志是否能帮助排查。
部署说明
根目录部署
常规部署只需要把源码放在网站根目录，Web 服务器入口指向该目录。访问首页后系统会自动初始化数据库。
子目录部署
系统支持二级目录部署，APP_BASE_PATH 会根据请求路径计算。主题模板里的内部链接应使用 url()，不要手写绝对路径。
<a href="<?= h(url('/products')) ?>">Products</a>这样无论部署在根目录还是 /b2b 子目录，链接都能保持正确。
敏感目录保护
生产环境必须禁止直接访问：
app/storage/Documents/.env- 数据库文件。
- 备份文件。
- 更新包。
主题开发验收清单
主题目录包含
style.css、blocks.php、functions.php、header.php、footer.php。style.css 顶部包含主题元数据。blocks.php 可以被 include 并返回数组。客户需要编辑的文案、图片、按钮、颜色、数量和链接都已暴露到区块。
产品展示区块使用
product_picker。轮播图区块使用
select 选择已有轮播图。模板输出使用
h()、url()、asset_url()。产品列表和产品详情读取真实产品数据。
产品详情支持阶梯价格、SKU 价格、价格区间和面谈价格。
询盘按钮和联系表单能正常提交。
Header 和 Footer 优先读取全局站点设置。
手机端没有横向滚动和文字遮挡。
主题不修改核心表结构，不删除用户区块配置。
后台功能验收清单
新增路由已注册。
控制器做了登录和权限检查。
POST 请求包含 CSRF。
数据写入经过模型封装。
用户输入已校验。
错误提示对运营人员可理解。
列表页支持必要的搜索、筛选或分页。
删除操作有确认或防误触设计。
新表结构通过迁移创建。
更新后后台导航和权限映射一致。
常用排查命令
# 查看产品价格模式相关代码
rg "price_mode|product_skus|product_prices" app themes
查看主题区块字段
rg "product_picker|slider_slug|type’ => ‘select’" themes/default/blocks.php
查看迁移文件
ls app/Migrations
查看后台路由
rg "admin/" app/routes.php
查看未转义输出风险
rg "echo \$|<\?= \$" themes app/views
开发原则
- 保持零构建、易部署的运行体验。
- 独立业务功能优先通过 Plugin API 扩展，核心功能遵循现有 MVC 和模型模式。
- 表结构变更必须走核心迁移或插件自己的命名空间迁移。
- 主题只做展示和配置，不侵入核心业务。
- 后台权限必须在控制器或插件路由层检查。
- 所有用户输入都需要校验，所有输出都需要转义。
- 商品、媒体、轮播、菜单尽量读取真实系统数据，不用假字段替代。
- 修改共享能力时补充最小可验证路径，例如前台页面、后台保存、迁移执行、插件启停和移动端检查。