create-lumfall 1.0.0 → 1.0.1

package/templates/document/docs/guide/getting-started.md

@@ -1,199 +0,0 @@
-# 快速开始
-
-从零搭一个最小可运行的 lumfall 业务项目。
-
-## 1. 安装
-
-```sh
-mkdir my-app && cd my-app
-pnpm init
-pnpm add lumfall
-pnpm add -D nodemon concurrently
-```
-
-::: tip 框架共享依赖无需重复安装
-业务页面可以直接 import 框架暴露的共享依赖——`vue`、`@arco-design/web-vue`、
-`vue-router`、`pinia`、`@babel/runtime`、`axios`、`lodash`、`moment`、`md5`。
-框架在 webpack.base 的 `resolve.alias` 里维护这份白名单（指向框架自身的
-依赖目录），无需在业务 `package.json` 里重复安装，且运行时保证只有一份实例
-（需要 lumfall ≥ 1.1.1，白名单见[前端构建](../frontend/build.md)）。
-
-只有框架没有的库才需要自己安装：
-
-```sh
-pnpm add <你的三方库>
-```
-:::
-
-## 2. 服务端入口
-
-`server.js`：
-
-```js
-const { serviceStart } = require("lumfall");
-
-const app = serviceStart({
-  name: "my-app",
-  // 未命中路由时的 302 兜底目标。传了 options 对象就必须显式写 homePath，
-  // 否则兜底会退化为 "/"
-  homePath: "/view/health",
-});
-
-module.exports = app;
-```
-
-框架自带 `health` 页面与接口，此时已经可以启动：
-
-```sh
-_ENV=local node server.js
-# Server running on http://0.0.0.0:3000
-```
-
-访问 `http://localhost:3000/view/health` 看到健康页，
-`http://localhost:3000/health/live` 返回 `{"status":"ok"}`。
-
-::: warning 环境变量是 `_ENV`，不是 `NODE_ENV`
-`_ENV` 的取值是 `local` / `beta` / `prod`（缺省 `local`），决定加载哪份环境配置。
-`NODE_ENV` 对框架配置加载不起作用。
-:::
-
-## 3. 前端构建入口
-
-`build.js`：
-
-```js
-const { frontendBuild } = require("lumfall");
-
-// _ENV=local 启动 Webpack dev server（HMR，默认 127.0.0.1:9002）
-// _ENV=prod  产物构建到 app/public/dist/prod/
-frontendBuild(process.env._ENV);
-```
-
-`package.json` 的 scripts：
-
-```json
-{
-  "scripts": {
-    "dev": "_ENV='local' nodemon --exitcrash server.js",
-    "prod": "_ENV='prod' node server.js",
-    "build:dev": "_ENV='local' node --max_old_space_size=4096 ./build.js",
-    "build:prod": "_ENV='prod' node ./build.js",
-    "start:dev": "concurrently --kill-others-on-fail -n webpack,server -c cyan,green \"pnpm build:dev\" \"pnpm dev\"",
-    "start:prod": "pnpm build:prod && pnpm prod"
-  }
-}
-```
-
-## 4. 写第一个 API
-
-四个文件，目录约定见[目录结构与挂载点](./structure.md)：
-
-`app/service/demo.js`：
-
-```js
-module.exports = (app) => {
-  const BaseService = require("lumfall").Service.Base(app);
-
-  return class DemoService extends BaseService {
-    greeting(name) {
-      return `hello, ${name || "world"}`;
-    }
-  };
-};
-```
-
-`app/controller/demo.js`：
-
-```js
-module.exports = (app) => {
-  const BaseController = require("lumfall").Controller.Base(app);
-
-  return class DemoController extends BaseController {
-    async getGreeting(ctx) {
-      const { demo: demoService } = this.services;
-      const message = demoService.greeting(ctx.request.query.name);
-      await this.success(ctx, { message });
-    }
-  };
-};
-```
-
-`app/router/demo.js`：
-
-```js
-module.exports = (app, router) => {
-  const { demo: demoController } = app.controllers;
-  router.get(
-    "/api/demo/greeting",
-    demoController.getGreeting.bind(demoController)
-  );
-};
-```
-
-`app/router-schema/demo.js`：
-
-```js
-module.exports = {
-  "/api/demo/greeting": {
-    get: {
-      query: {
-        type: "object",
-        properties: {
-          name: { type: "string" },
-        },
-      },
-    },
-  },
-};
-```
-
-重启服务后访问：
-
-```sh
-curl "http://localhost:3000/api/demo/greeting?name=lumfall"
-# {"success":true,"data":{"message":"hello, lumfall"},"metadata":{}}
-```
-
-参数校验不通过时返回 HTTP 200 + `code 442`（详见[路由与参数校验](../core/router-schema.md)）。
-
-## 5. 写第一个页面
-
-推荐用脚手架生成（页面名必须是 kebab-case）：
-
-```sh
-node ./node_modules/lumfall/scripts/generate-page.js hello
-# 生成 app/pages/hello/entry.hello.js + app/pages/hello/hello.vue
-```
-
-也可以手动创建，入口文件 `entry.hello.js`：
-
-```js
-import boot from "$lumfallBoot";
-import Hello from "./hello.vue";
-
-boot(Hello);
-```
-
-页面组件 `hello.vue`：
-
-```vue
-<template>
-  <main class="hello-page">
-    <h1>Hello Lumfall</h1>
-  </main>
-</template>
-```
-
-本地开发时同时起 webpack dev server 与服务：
-
-```sh
-pnpm start:dev
-```
-
-访问 `http://localhost:3000/view/hello`。改组件代码，浏览器热更新。
-
-## 6. 接下来
-
-- [目录结构与挂载点](./structure.md)：把目录约定吃透
-- [配置](./config.md)：按环境组织配置
-- [常见错误自查](../reference/faq.md)：启动失败时先看这里

package/templates/document/docs/guide/structure.md

@@ -1,98 +0,0 @@
-# 目录结构与挂载点
-
-Lumfall 的核心约定：**业务根目录 = 进程的 `process.cwd()`**。
-启动服务与执行构建都必须在业务根目录下运行，否则框架会加载错目录。
-
-## 业务项目结构
-
-```text
-<app-root>/
-├── server.js                  # 服务端入口：serviceStart()
-├── build.js                   # 前端构建入口：frontendBuild(_ENV)
-├── package.json
-├── config/                    # 配置（见「配置」）
-│   ├── config.default.js
-│   ├── config.local.js        # 可选
-│   ├── config.beta.js         # 可选
-│   └── config.prod.js         # 可选
-├── model/                     # 可选，Dashboard 的 Model + Project 配置
-└── app/
-    ├── middleware.js          # 可选，业务全局中间件注册入口
-    ├── middleware/            # 可复用中间件
-    ├── controller/
-    ├── service/
-    ├── router/
-    ├── router-schema/
-    ├── extend/
-    ├── pages/                 # Vue 页面，entry.<name>.js 是入口
-    ├── webpack.config.js      # 可选，扩展 Webpack 配置
-    └── public/                # 静态文件；构建产物在 app/public/dist/
-```
-
-## 挂载点一览
-
-文件名 / 目录名用 `kebab-case` 或 `snake_case`，加载后自动转 `camelCase`。
-
-| 业务目录 | 导出约定 | 挂载结果 |
-| --- | --- | --- |
-| `app/middleware/**/*.js` | `(app) => (ctx, next) => {}` | `app.middlewares.<dir>.<name>` |
-| `app/controller/**/*.js` | `(app) => class` | `app.controllers.<dir>.<name>`，启动时实例化 |
-| `app/service/**/*.js` | `(app) => class` | `app.services.<dir>.<name>`，启动时实例化 |
-| `app/extend/**/*.js` | `(app) => object` | 直接挂到 `app` 上，例如 `app.logger` |
-| `app/router/**/*.js` | `(app, router) => {}` | 注册路由到 `app.router` |
-| `app/router-schema/**/*.js` | schema 对象或 `(app) => map` | 合并进 `app.routerSchema` |
-| `app/middleware.js` | `(app) => { app.use(...) }` | 全局中间件注册入口 |
-| `app/webpack.config.js` | 配置对象 | 与框架 Webpack 配置 `merge.smart` 合并 |
-
-例子：
-
-- `app/service/user-service.js` → `app.services.userService`
-- `app/controller/admin/user-list.js` → `app.controllers.admin.userList`
-- `app/middleware/api/params-verify.js` → `app.middlewares.api.paramsVerify`
-
-框架自带的同名类别文件也会被加载（controller、service、middleware、router-schema、
-router、extend 都有内置实现）；页面入口同名时，**业务页面覆盖框架页面**。
-
-## app 对象上有什么
-
-启动完成后，`serviceStart()` 返回的 `app`（Koa 实例）上至少有：
-
-| 属性 | 说明 |
-| --- | --- |
-| `app.options` | `serviceStart()` 的入参 |
-| `app.baseDir` | `process.cwd()` |
-| `app.businessPath` | `<app-root>/app` 的绝对路径，**业务代码取路径用它，不要用 `__dirname`** |
-| `app.env` | 环境：`app.env.get()` 返回 `_ENV` 值 |
-| `app.middlewares` | 全部中间件（框架 + 业务） |
-| `app.routerSchema` | 合并后的 API 参数校验 schema |
-| `app.controllers` / `app.services` | 已实例化的控制器 / 服务 |
-| `app.config` | 合并后的配置（`configLoader` 之后才存在） |
-| `app.plugins` | 插件注册结果 |
-| `app.router` | KoaRouter 实例 |
-| `app.logger` | 框架日志（log4js） |
-| `app.health` | 健康检查注册器 |
-| `app.diagnostics` | 诊断清单：`app.diagnostics.getManifest()` |
-| `app.server` | `app.listen()` 返回的 server |
-| `app.stop()` | 优雅退出（Promise） |
-
-## 加载规则与三条硬约束
-
-启动流程按固定顺序同步执行（详见 [app 对象与启动流程](../core/app-instance.md)），
-由顺序推出三条约束：
-
-1. **`app.config` 在 controller / service 工厂执行期还不存在**
-   → 只能在请求阶段读配置（基类的 `this.config` getter 是安全的）
-2. **controller 比 service 先加载**
-   → 不要在 controller 工厂或构造期取 `app.services`（请求阶段用 `this.services`）
-3. **任何 loader 遇到非法导出会直接抛错并中断启动**，不会静默跳过
-   → 导出形状必须严格按上表约定
-
-## 路径书写注意
-
-- 业务路径统一走 `app.businessPath` + `path.join` / `path.resolve`，不要硬编码 `/`
-- 例外：`glob` v7 的结果始终是 `/` 分隔，拼接前先按 `/` 拆开再 `join(path.sep)`
-
-## 下一步
-
-- [Controller 与 Service](../core/controller-service.md)：写业务逻辑
-- [路由与参数校验](../core/router-schema.md)：暴露 API

package/templates/document/docs/reference/commands.md

@@ -1,70 +0,0 @@
-# 命令与环境速查
-
-## 命令速查
-
-在业务根目录（`<app-root>`）下执行：
-
-| 场景 | 命令 |
-| --- | --- |
-| 安装依赖 | `pnpm install` |
-| 本地开发（前端 HMR + 服务） | `pnpm start:dev`（= `build:dev` + `dev` 并行） |
-| 只起服务 | `_ENV=local node server.js` |
-| 生产构建 | `_ENV=prod node build.js` |
-| 生产启动 | `_ENV=prod node server.js` |
-| 构建 + 启动 | `pnpm start:prod` |
-| 生成页面 | `pnpm new-page <name> [--header]` 或 `node ./node_modules/lumfall/scripts/generate-page.js <name>` |
-| 排查挂载 | 启动后读 `app.diagnostics.getManifest()` |
-
-`new-page` 的页面名必须是 kebab-case；`--header` 套 HeaderContainer 布局。
-
-## 环境变量
-
-| 变量 | 取值 | 作用 |
-| --- | --- | --- |
-| `_ENV` | `local`（默认）/ `beta` / `prod` | 环境标识，决定加载哪份 `config.<env>.js` 与构建模式 |
-| `PORT` | 默认 3000 | Koa 服务端口 |
-| `IP` | 默认 0.0.0.0 | Koa 监听地址 |
-
-注意：**不是** `NODE_ENV`；`_ENV` 同时决定配置加载与前端构建模式。
-
-## serviceStart 选项
-
-| 选项 | 类型 | 作用 |
-| --- | --- | --- |
-| `name` | string | 应用名（页面 `<title>`） |
-| `homePath` | string | 未命中路由的 302 兜底；传 options 时必须显式声明 |
-| `configSchema` | object | 合并配置的 JSON Schema 校验 |
-| `lifecycle` | object | 启动 / 停止 hook（7 个） |
-| `plugins` | array | 插件描述符 |
-| `monitoring` | object | 请求观测 hook |
-
-## 端口速记
-
-| 端口 | 归属 |
-| --- | --- |
-| 3000 | Koa 服务（`PORT` 可覆盖） |
-| 9002 | Webpack dev server + HMR（仅 `_ENV=local` 构建，写死在框架 `webpack.dev.js`） |
-
-## 错误码速记
-
-| code | 含义 | 来源 |
-| --- | --- | --- |
-| 442 | 参数校验失败 | apiParamsVerify（router-schema） |
-| 445 | 签名校验失败 | apiSignVerify |
-| 446 | 缺 project_key | projectHandler |
-| 5000 | 服务端异常兜底 | errorHandler |
-| 4041 | 页面不存在 | ViewController |
-| 5031 | 页面模板未构建 | ViewController |
-| 50000 | 业务失败约定码 | `this.fail` 示例约定 |
-
-## 框架内置路由
-
-| 路由 | 说明 |
-| --- | --- |
-| `/view/:page`、`/view/:page/*` | 页面渲染 |
-| `/health/live` | 存活探针 |
-| `/health/ready` | 就绪探针 |
-| `/api/project/model_list` | Dashboard Model 列表（免 project_key） |
-| `/api/project/list` | Dashboard 项目列表（免 project_key） |
-| `/api/project` | Dashboard 单项目配置 |
-| 其余未命中 GET | 302 → `homePath` |

package/templates/document/docs/reference/faq.md

@@ -1,94 +0,0 @@
-# 常见错误自查
-
-启动失败或行为不符合预期时，按这份清单排查。
-
-## 启动期
-
-1. **`Class extends value ... is not a constructor`**
-   `Controller.Base` / `Service.Base` 是工厂函数，要调用：
-   `require("lumfall").Controller.Base(app)`，少写 `(app)` 就会这样报错
-
-2. **controller / service 工厂返回了对象而不是 class**
-   loader 直接抛错中断启动；检查 `return class Xxx extends Base { ... }`
-
-3. **router-schema 启动报 `does not match a registered route`**
-   schema 的 key（path）写错、漏写路由，或 method 用了大写
-   （必须小写且确实以该方法注册过）
-
-4. **`[lifecycle] hook "xxx" must be synchronous`**
-   启动期 hook 不能返回 Promise；异步初始化放到 `serviceStart()` 之前做
-   （`beforeStop` / `afterStop` 除外）
-
-5. **`unknown hook "xxx"`**
-   lifecycle 只接受七个 hook 名，见[生命周期](../core/lifecycle.md)
-
-6. **插件报 name 重复 / 缺依赖 / 循环依赖 / register 必须同步**
-   见[插件](../core/plugins.md)规则表
-
-7. **配置校验失败 `merged configuration for "prod" is invalid`**
-   合并后的配置不满足 `configSchema`；注意浅合并是整键替换，
-   环境文件里对象型配置要写完整
-
-8. **extend 报 `must export a factory function`**
-   `app/extend/` 下的文件要导出 `(app) => object`，返回值挂到 app 上
-
-9. **同名页面报 `duplicate business page entry`**
-   同一来源（业务目录）里出现了两个同名 `entry.<name>.js`
-
-## 运行期
-
-10. **配置不生效**
-    - 用的是 `NODE_ENV` 而不是 `_ENV`？环境变量是 `_ENV` ∈ local / beta / prod
-    - 配置是浅合并：环境文件里对象型配置整键替换，可能把 default 的子键覆盖丢了
-    - 在请求阶段读了吗？工厂执行期 `this.config` 是 undefined
-
-11. **挂载点拿不到（undefined）**
-    - 用文件名而不是 camelCase 挂载名？
-      `app.middlewares.apiParamsVerify` 而不是 `app.middlewares["api-params-verify"]`
-    - 用 `__dirname` 拼业务路径？业务路径统一 `app.businessPath`
-
-12. **`/view/<未知页面>` 返回 404 `4041` 而不是跳首页**
-    这是约定：页面不存在是 404 `4041`；页面存在但没构建模板是 503 `5031`；
-    只有**非 /view 的未命中路由**才 302 到 `homePath`
-
-13. **接口返回 `code 442`**
-    router-schema 校验失败，看响应 message 里的具体字段提示
-
-14. **接口返回 `code 445`**
-    签名校验失败：检查 `secret` 是否与客户端一致、时间戳是否过期（`maxAgeMs`）、
-    时间戳是否在未来
-
-15. **接口返回 `code 446`**
-    `/api/project/` 路径缺 `project_key` 头；URL 带 `?projectKey=xxx`
-    时 `$lumfallCurl` 会自动带上
-
-16. **接口返回 `code 5000`**
-    服务端异常被 errorHandler 兜底，详情在日志里（工作区 `logs/` 目录）
-
-17. **页面白屏**
-    - 看浏览器控制台与 Network：JS/CSS 404 说明产物 publicPath 对不上
-      （确认跑过对应模式的构建）
-    - dev 模式资源指向 `127.0.0.1:9002`，先起 `build:dev` 再访问 3000 端口
-
-18. **排查「文件明明写了却没生效」**
-    读诊断清单：`app.diagnostics.getManifest()`，看 `routes` / `pages`
-    里有没有你注册的东西
-
-## 工程与依赖
-
-19. **业务代码 import 框架的传递依赖报模块找不到**
-    lumfall ≥ 1.1.1 起框架已把内置依赖（vue / @arco-design/web-vue / pinia /
-    vue-router / @babel/runtime 等）暴露给业务代码，直接 import 即可；
-    旧版本（≤ 1.1.0）+ pnpm 下需在业务 `package.json` 显式声明（见[快速开始](../guide/getting-started.md)）。
-    框架没有的库仍然要先 `pnpm add`
-
-20. **`frontendBuild("beta")` 什么都不做**
-    构建只支持 `_ENV=local`（dev server）与 `_ENV=prod`（产物）
-
-21. **从错误目录启动 / 构建**
-    业务根目录 = `process.cwd()`；必须在 `<app-root>` 下执行 `node server.js`
-    与构建命令
-
-22. **服务端启动时控制台输出大量内容**
-    lumfall ≥ 1.2.0 启动日志已降级为摘要（各 loader 条目数，不打印配置内容）；
-    若仍看到全量配置 dump，说明框架版本过旧，升级即可