快速开始
五步安装：指向 public/ → 配置数据库 → 运行安装向导 → 填系统设置 → 保护安装锁。本地体验可用 PHP 内置服务器：
php -S 127.0.0.1:8080 -t public public/index.php php bin/migrate.php --status # 查看迁移状态 php bin/migrate.php # 执行迁移
命令行入口统一收拢在 bin/，迁移不要绕过它单独执行。
目录结构
public/—— 唯一 Web 入口、静态资源与短时下载区apcore/System/—— 启动装配与 CI4 应用目录，不建议修改apcore/Core/—— 核心能力：主题引擎、字段、钩子、应用管理、存储apcore/addon/—— 业务应用，按目录名自动发现apcore/My/—— 覆盖层，客户现场定制放这里template/—— 主题包，位于 Web 根之外apcore/storage/—— 升级与市场运行数据，Web 根之外cache/—— 可清理的缓存与临时产物
应用与插件
自成一块业务、有后台菜单的算「应用」；只把能力挂给别人调用的通道/驱动算「插件」（短信、对象存储、设备驱动等）。两类在后台分开管理。
一个应用就是一个目录，自带清单、路由、菜单、权限点、迁移与后台页面：
apcore/addon/Demo/ ├── Config/App.php # 名称、类型、版本、权限点 ├── Config/Routes.php # 路由（handler 用完全限定名） ├── Config/Menu.php # 后台菜单条目 ├── Controllers/ # 前台 / 后台控制器 ├── Models/ Services/ # 数据与业务 ├── Database/Migrations/ # 可逆迁移 └── Assets/admin/ # 后台页面（单文件 + jQuery）
启用后菜单、路由、权限点自动就位；停用则菜单消失，卸载走迁移回滚。
模板与主题
主题放在 template/<id>/，由 manifest.php + pages/<page>.php + partials/ 组成，静态资源放 public/static/theme/<id>/。切换主题改配置或走后台「模板主题」即可。
模板标签极简，支持变量、条件、循环与片段引入：
{{ site.name }} 变量（默认转义）
{{ article.content|raw }} 原样输出富文本
{{#if site.icp }}...{{/if }} 条件
{{#each nav as item }}...{{/each }} 循环
{{#include "header" }} 引入片段
注意：标签解析器不支持 {{#if}} 嵌套，也没有 {{#else}} 与 |default 过滤器；循环内部要展示可空字段，直接写变量即可（缺失时输出空串）。主题还可以为某个栏目提供 pages/column-<slug>.php 专属页，优先于通用详情页。
后台页面
后台页面用单文件 + jQuery 写，统一复用 ap-* 组件与设计变量，不引入另一套样式。数据通过 AP.api() 走后台接口：
AP.api('/demo/list').then(function (rows) { /* 渲染表格 */ });
AP.api('/demo/save', { method: 'POST', body: data });
列表、表单、抽屉、操作列都有现成约定；新页面请沿用，避免自成一套视觉。
自定义字段
字段由 schema 驱动，内置 15 种类型（文本、多行、富文本、数字、开关、下拉、单选、多选、标签、日期、图片、附件等）。在应用里注册字段模型后，表单渲染与存储自动跟上，加字段不用改前端。
钩子事件
注册、订单、支付等关键动作的前后都有框架级事件契约。业务方在 Config/Hooks.php 里挂载回调，不要在核心流程里内联业务逻辑：
return [
'order.after_create' => [['priority' => 100, 'callback' => ...]],
];
升级与排错
升级包带 RSA 签名与完整性清单，升级前可比对官方文件哈希、识别现场被改动的文件。出包白名单只含核心与官方应用目录，模板、配置、上传、客户自建应用不下发。
排错顺序建议：先看 cache/logs/ 当日日志 → 检查目录权限与 PHP 扩展 → 确认 Web 根指向 public/ → 再看迁移状态。可选组件（zip、redis、workerman 等）缺失时框架会自动降级，不必先怀疑功能没实现。
常见问题
- 搬家后后台菜单为空？ 超管权限点与角色权限有关，先在后台点「更新缓存」清权限缓存。
- 换模板要改 PHP 吗？ 不用，程序模板分离，改
template/目录即可。 - 接口 404？ 检查路由 handler 是否用了前导反斜杠的完全限定名。
- 页面显示 function () { [native code] }？ 模板当值渲染的标识符写在了 methods 里，挪进 computed。