从哪里开始
已知目标、需要最短正确路径时用 How to。首次搭建项目用 Getting started。需要完整 API、选项与边界情况时用 Documentation。
- 结果明确、需要步骤与代码时优先用这些配方
- Getting started — 新项目、CLI、目录结构、第一个插件
- Documentation — 后端 / 前端完整 API 参考
- Troubleshooting — 启动、DI、热更新、Tailwind、403 / UI 缺失
创建插件
用 @quan-erp/cli 脚手架（或复制 sample-es），对齐目录 / metadata / 包名与 @quan-erp/* 版本，加入第一个功能，运行 quan-erp watch，再在 Modules UI 中 Install。
- 何时 — 在 plugins/ 下新建插件
- 结果 — Install 后 shell 中出现菜单/路由
如何创建公开页
用 AppRegistry.rootRoute.add() 注册无 ERP 外壳的空白布局页面——不要用 route.add()。用于客户门户、厨房看板、二维码菜单等。
- 何时 — UI 不能显示侧栏 / 管理外壳
- 关键 API — rootRoute.add，路径以 /${metadata.name} 为前缀
如何做移动端适配
桌面表格搭配移动端卡片列表，使用 useMediaQuery / SCREENS，并用共享 UI 辅助保持底栏与 FAB 间距一致。
- 何时 — 页面需同时适配手机与桌面
- 要点 — isMobile 门控、卡片列表 vs 密集表格
添加浮动操作按钮
使用 @quan-erp/shared-ui 的 FloatingActionButton 添加仅移动端的主操作。用 isMobile 控制显示，并在底栏可见时调整位置。
- 何时 — 移动端列表上的创建 / 主操作
- 关键 API — FloatingActionButton、useIsContainInBottomNavBar
添加新的数据库源
优先使用共享默认 DataSource（plugin: "default"）。仅在需要单独主机、库、报表库或副本时，在根 @Module 上用 @Database 打开自定义连接。
- 何时 — 需要超出共享 Postgres 的隔离
- 关键 API — @Database、匹配的 plugin + name 实体、@InjectDatabaseSource
添加缓存
在根模块上用 @Cache 声明缓存（内存或从环境变量读取的 Redis），用 @CacheClient 注入，并可选用 @CacheRoute / @CacheFn 缓存 HTTP 路由或方法结果。
- 何时 — 重复读取、会话/令牌存储、昂贵计算
- 关键 API — @Cache、@CacheClient、路由/方法辅助、跨插件复用
如何为插件创建数据库迁移
通过 IPlugin.getMigrations() 返回实现 getName、getSource、up、down 的 IDatabaseMigration 类交付 schema 变更。生产升级不要依赖 synchronize。
- 何时 — 增删改 schema 或一次性回填
- 关键 API — IDatabaseMigration、getMigrations()、可选 onMigrate()
插件前端与后端资源
随插件打包静态文件：后端放在 backend/assets/ 并用 AppFolder；前端 URL 用 PluginAssets.network。不要硬编码 APP_DATA_FOLDER；不要在运行时写入 asset 目录。
- 何时 — 模板、种子 JSON、Logo 等打包静态文件
- 关键 API — AppFolder.getPluginAssetFolder / getPluginDataFolder、PluginAssets.network