PlatoAdmin 文档

跑在 PlatoPHP 上：admin 是 Smarty 渲染的后台界面，模型、服务与语言包在 common 下。

另一个应用 api 是从 api/contracts/ 生成的 JSON 接口，与 admin 共用 common。

这里是项目自己的文档。框架的文档不在这里——在线版看 https://platophp.com。发布的 tag 把 docs/ 剥掉了，所以装完的 vendor/ 里没有；要离线看就 composer reinstall lumnd/platophp --prefer-source，之后在 vendor/lumnd/platophp/docs/，入口 llms-zh-CN.txt。

从哪读起

接口那一侧另有两篇：API 参考 看接口长什么样，API 契约与代码生成 讲接口怎么加、哪些文件是生成的。

每一篇讲的都是现在这棵树里的代码。文档和源码冲突时以源码为准，然后把文档改过来。

当前范围

后台基础域已经落地：账号、角色、会话、登录日志、操作日志、菜单、系统设置、计划任务。

api 只有认证链路——send_code、login、refresh、logout，登录方式是邮箱验证码、手机验证码、Google、Apple。

产品域还没有代码。 用户资料与设置、内容、订阅、支付都还没定稿，主树里没有它们的表也没有它们的接口。

明确没做的事，不要当成漏了：

• 短信通道没有实现，common\integration\sms 是空实现，手机号验证码会如实返回「暂时无法发送」，不会假装发了。

• 没有常驻服务在跑。lumnd/plato-workerman 装上了、命令也注册了，但没有 config/server.php，没有 server 实现，也没有跑通过一次。

几条贯穿全局的约定

• 失败只有一种机制：抛 biz_exception。没有返回值符号约定，common\middleware\catcher 是唯一把异常变成响应的地方。
• 分层是 control → service → model → db。Service 只划事务边界，规则放 Model。
• 每个控制器必须声明 $actions，每个动作 methods 与 auth 两个键都要写。少一个键不是回退到默认，是那个动作变成 500。
• 表名写 #PB#_xxx，运行时由 DB_PREFIX 替换。
• 密钥只进 .env。setting 表不得存密钥或第三方凭据——数据库会被导出、备份、拷进开发环境。
• 代码注释一律英文；界面多语言只有 zh-cn 和 en。

这份站点是怎么生成的

docs/*.md 是源，docs/build.php 生成 docs/site/*.html，docs/manifest.json 是页面清单。docs/site/ 不进仓库——CI 每次推送都重新生成并发布，改文档只改 Markdown。

想在本地看 HTML 版：

php docs/build.php          # 生成 docs/site/
php docs/build.php --check  # 只渲染校验，不落盘

生成需要 Node（走 npx marked）。composer create-project 装出来的项目里，install.php 按选中的档裁完页面清单之后会现场生成一份——每页的侧边栏和上下篇导航都嵌着整份目录，所以必须先裁后生成。那台机器上没有 Node 就跳过，Markdown 源是全的，之后自己跑一次补回来。

docs/site/api.html 是 Swagger UI，读的是 docs/api/openapi.json——那个文件是 plato api:generate 从 api/contracts/ 生成的，不要手改。

接口那一页有两份，用途不同。这一份是文档站的一页，带侧栏和上下篇，跟着 build.php 生成；docs/api/index.html 是另一份，只有 Swagger UI，是提交进仓库的普通文件，不需要 Node 也不需要构建，由 api 的 vhost 挂在 /docs/api/ 上给前端调试用——为什么挂在那边见本地运行。