上手教材 · 从 0 手把手 · moo-engine-skeleton
跳过基建期，
直接写业务
基于 Laravel 12 的企业级后端工程骨架：内置 代码生成器、双守卫 JWT、动作级 ACL 与可选的 moo-system,克隆即得一个能跑、能生成代码、带完整认证授权的底座 —— 再配一套从零、全程真机验证的九章教程。
# 同级已克隆 moo-scaffold / moo-system cd engine/ composer install cp .env.example .env php artisan key:generate php artisan jwt:secret --force php artisan migrate --seed # 开发 UI: http://127.0.0.1:8088/scaffold php artisan serve --port=8088
Positioning
一个起点，三重身份
团队多个生产项目沉淀出一套高度一致的后端实践，但分散在各业务仓库里 —— 新项目启动、新人上手都要反复「考古」。这个骨架把它提炼成一个从 0 开始的标准起点。
新项目脚手架
备齐依赖后克隆即得一个可运行、可生成代码、带完整认证授权的后端底座。
新人教学载体
九章教程照实记录每条命令与结果，配零依赖网页引导器，新人可独立复现整个搭建过程。
生产经验回灌池
生产踩过的坑（JWT 续签丢 claim、孤儿 token、nestedset 静默等 27 项）以代码 + 文档双重固化，反向校准生产仓库。
The course
九章，从空目录到带认证授权的后端
每一步都写进教程、照实记录命令与真机结果。前 6 章零付费依赖，第 7 章接商业包为可选进阶，8–9 章覆盖部署与增量开发。
安装 Laravel
engine/ 子目录工程布局，横切接线落在 bootstrap/app.php。
接入 moo-scaffold
YAML 代码生成器装好，以 foods 表为样例实体跑通生成。
JWT 登录认证（自建用户）
自建最简 User 实现 JWTSubject，零付费依赖完成认证教学。
JWT 加固与生产化
persistent_claims、黑名单宽限、滑动续期、防孤儿 token —— 生产踩坑回灌。
给 Food 上 JWT 与 ACL
以 Food 实体演示 401 → 403 → 200 完整授权闭环。
移动端分片与 user 守卫
独立 Api/ 分片（前缀 app），与后台物理隔离、双向不通。
安装 moo-system · 可选进阶
接商业包，后台主体 User → Personnel 仅改一行，验证可替换性。
部署上线
包从 path 仓库切 VCS/Packagist，一行 cp 切换生产配置。
增量开发工作流
moo:adder 增量补码不覆盖业务代码，配回归测试演练。
零依赖网页引导器
docs/index.html 单文件（内联全部 CSS/JS），分步模式 + 进度记忆 + 代码一键复制，php -S 即启。
教学路径自成一套
从简入繁、异常监控很早就植入(§1.7 即跑监控采集测试）—— 刻意不照搬「开发→测试→运营」的对外展示顺序，让新手从写第一个接口起就看得见自己的报错。
Run it
克隆 → migrate --seed → 能登录
九章全部搭建完成并经真机验证，仓库代码是第 9 章最终态。.env.example 预设 QUEUE_CONNECTION=sync 等，开箱可见操作日志。
硬前置（只读容易忽略）
- —
engine/composer.json以 path 仓库指向同级目录的moo-scaffold与moo-system—— 只克隆本仓直接composer install会失败。 - —moo-scaffold 开源 MIT 但未上 Packagist;moo-system 是商业包需授权 —— 两者都要先克隆到同级目录。
- —「零付费依赖」指前 6 章不需要商业包，不等于「零前置」。
- ✓想低成本上手：前 6 章的 JWT / ACL / 分片只用 scaffold(MIT、免费） 就讲透；moo-system 是第 7 章的可选进阶，没授权也能学完核心。
| 自建用户 | admin@example.com / password |
| Personnel 管理员 | 13800000000 / admin888 |
| Scaffold 开发 UI | 自定 — moo:account:add(seed 不创建） |
Conventions
五条架构约定（与生产完全对齐）
骨架不只是「能跑」，它把团队的工程约定固化下来 —— 照着写，就和生产代码一个心智模型。
入口即边界
无 Service/Repository 层，逻辑分布在轻量 Controller（编排）、Model(boot() 守卫 + trait）、Resource（输出）三处。
镜像对称分片
Admin/（后台 api/admin）与 Api/（移动端 app）各自一套，互不渗透。
响应无信封
成功直接返回 Resource，错误 {"message"：…};HTTP 状态码承载语义（业务错误 522 / 校验 422 / 401 / 403）。
处处软删
完整回收站 / 恢复 / 永久删除生命周期，每行带 options 动作列表。
枚举不进 $casts
字段保持裸 int，显式 Enum::tryFrom() 转换，规避枚举实例比较陷阱。
Route::iResource 宏
批量删除 / 回收站 / 恢复 / 永久删除一把抓；反射校验 action 真实存在才注册，杜绝幻影路由。
JWT，做到生产化加固
零付费依赖的完整 JWT 实现 —— 不是教学玩具，每条都来自生产踩坑回灌。
- ▸admin / user 双守卫双向隔离:token 内嵌 guard claim，后台 token 调移动端接口 401，反之亦然
- ▸persistent_claims=['guard']：杜绝续签丢 guard claim 导致的偶发 401
- ▸黑名单 90 秒宽限：续签瞬间并发在途请求不被误杀
- ▸refresh 防孤儿 token：刷新路由不挂续签中间件，避免派生两个有效 token
- ▸滑动续期（活跃无感长登录）+ 移动端单设备语义（旧 token 立即进黑名单）
权限到「动作」，业务零侵入
控制器动作粒度的权限引擎，host 定义契约、包与自建代码共同消费。
- ▸Gate 多态：自建 User 与 moo-system Personnel 通吃，主体切换不动授权代码
- ▸基类
callAction()先boot()再自动鉴权，业务代码零侵入 - ▸ACL key 两步生成：
Class::methodsnake 化拼明文 →md5截 16 位入库 - ▸
transform_methods权限复用，避免权限点爆炸 - ▸第 7 章无缝切角色制，含个人中心白名单兜底（防零授权锁死）
All wired
前几层「怎么用」的集大成
骨架不是又一个工具，而是把生态里几个工具接好、跑通、演示一遍的官方示范 —— 新人/新项目的入口。
moo-scaffold
代码生成器已接好，foods 样例实体演示全套产物。开发期生效，不是运行时框架。
moo-system
第 7 章 · 可选商业包，8 个开箱后台模块；骨架完成全部 host 契约实现 + 真机联调，不装前六章也完全自洽。
monitor → 监控云
监控采集很早就植入（§1.7 有 MonitorTest），第一天就看得见报错；云端监控进阶在后面章节。
Quality
用真机测，不是 demo
双守卫认证、ACL、移动端、增量产物、监控采集、种子完整性，php artisan test 全绿。
现象 → 原因 → 解决 → 章节，全部来自真实搭建与生产回灌。
跨进程行为模拟
测试基类重置整条 jwt 服务链单例，复现真实跨进程的续签丢 claim 问题。
cleanroom 验证
主线七章经「从零重做」洁净环境终极验证，修复全部卡点后定稿。
这是这套生态的「上手入口」
克隆下来照着九章走一遍，scaffold、认证、ACL、监控就都串起来了 —— 新人建立心智模型，新项目跳过基建期。