create-lumfall 1.0.0 → 1.1.1

package/templates/document/docs/advanced/security.md

@@ -1,88 +0,0 @@
-# 安全策略
-
-框架内置两道 API 防线，由 `config.security` 控制（不配置时等价于
-「签名关闭 + project_key 开启」），只作用于 `/api` 开头的请求。
-
-## 接口签名校验（apiSignature）
-
-开启后，所有 `/api` 请求必须携带签名请求头，防重放、防伪造：
-
-```js
-// config/config.default.js
-module.exports = {
-  security: {
-    apiSignature: {
-      enabled: true,
-      secret: process.env.API_SIGN_SECRET, // 不配时退化为默认串 "lumfall"（只适合本地）
-      maxAgeMs: 600000,                     // 时间戳有效期，默认 10 分钟
-    },
-  },
-};
-```
-
-算法：`s_sign = md5(secret + "_" + st)`。
-
-| 请求头 | 含义 |
-| --- | --- |
-| `s_sign`（或 `s_sign` 别名 `ssign`） | `md5(secret + "_" + st)` |
-| `s_t`（或 `s_t` 别名 `st`） | 毫秒时间戳 |
-
-失败条件（任一满足即拒绝，返回 `code 445`）：
-
-- 缺少签名或时间戳
-- 时间戳不是合法数字
-- 签名不匹配
-- 时间差超过 `maxAgeMs`，或时间戳在未来
-
-框架的 `$lumfallCurl` 默认带 `s_sign` / `s_t`（用默认串 `lumfall` 签名）；
-服务端换了 `secret` 时客户端要同步实现同样的算法。
-
-## project_key 校验（projectKey）
-
-多项目（多租户）场景下，归属某个项目的接口要求请求头声明项目：
-
-```js
-module.exports = {
-  security: {
-    projectKey: {
-      enabled: true,
-      headerName: "project_key", // 可改
-      freePaths: ["/api/project/custom"], // 追加豁免路径
-    },
-  },
-};
-```
-
-- 只作用于 `/api/project/` 开头的路径
-- 内置豁免：`/api/project/model_list`、`/api/project/list`
-  （项目列表页初始化时还没有项目上下文），可用 `freePaths` 追加
-- 缺少请求头返回 `code 446`；通过后 `ctx.projectKey` 可在 controller / service 里使用
-- `$lumfallCurl` 在 URL 带 `?projectKey=xxx` 时自动追加这个请求头
-
-## 错误码总表
-
-| 中间件 | 触发条件 | 响应 |
-| --- | --- | --- |
-| `apiParamsVerify` | router-schema 校验不通过 | `{ success: false, code: 442 }` |
-| `apiSignVerify` | 缺签名 / 签名不匹配 / 时间戳非法或过期 | `{ success: false, code: 445 }` |
-| `projectHandler` | 缺少 `project_key` | `{ success: false, code: 446 }` |
-
-三者都返回 HTTP 200，前端按 `success` / `code` 判断。
-
-## 中间件链位置
-
-安全策略位于框架中间件链的最后一环（最内层业务之前）：
-
-```text
-static → nunjucks → bodyParser → errorHandler → monitoring → apiParamsVerify → securityPolicy
-```
-
-所以参数校验（442）先于安全校验（445 / 446）执行。
-
-## 安全建议
-
-- 生产环境**必须**开启 `apiSignature` 并配置强随机 `secret`
-- `secret` 走环境变量或配置中心；泄露后签名机制形同虚设
-- md5 + 时间戳是轻量防重放方案；对安全等级要求更高的系统，把签名逻辑
-  换成自定义中间件（HMAC、nonce 等）替换或叠加在 `securityPolicy` 之前
-- `/view/...` 页面路由不走这两道校验，页面级权限需要业务自己控制

package/templates/document/docs/core/app-instance.md

@@ -1,114 +0,0 @@
-# app 对象与启动流程
-
-`serviceStart(options)` 返回的 `app` 是一个 Koa 实例，框架把所有能力都装配在它上面。
-理解启动流程，就理解了框架的几乎所有约束。
-
-## serviceStart 选项
-
-| 选项 | 作用 |
-| --- | --- |
-| `name` | 应用名，渲染页面模板 `<title>` 时使用 |
-| `homePath` | 完全未命中路由时的 302 兜底目标 |
-| `configSchema` | 校验合并后配置的 JSON Schema（见[配置](../guide/config.md)） |
-| `lifecycle` | 启动 / 停止 hook（见[生命周期](./lifecycle.md)） |
-| `plugins` | 插件描述符数组（见[插件](./plugins.md)） |
-| `monitoring` | 请求级观测 hook（见[请求观测](../advanced/monitoring.md)） |
-
-::: warning homePath 默认值陷阱
-完全不传参时 `homePath` 默认是 `/view/health`；但**一旦传了 options 对象**，
-框架不再套用默认值——没写 `homePath` 时兜底重定向会变成 `/`。
-所以只要传 options，就显式声明 `homePath`。
-:::
-
-其他启动相关默认值：监听 `0.0.0.0:3000`，可用 `IP` / `PORT` 环境变量覆盖。
-
-## 启动流程
-
-`serviceStart()` 内部固定按这个顺序同步装配：
-
-```js
-app.options = options;
-app.baseDir = process.cwd();
-app.businessPath = path.resolve(app.baseDir, "app");
-app.env = env();
-
-middlewareLoader(app);      // app.middlewares
-routerSchemaLoader(app);    // app.routerSchema
-controllerLoader(app);      // app.controllers（类在这里被 new）
-serviceLoader(app);         // app.services（类在这里被 new）
-configLoader(app);          // app.config
-extendLoader(app);          // 返回值直接挂到 app（app.logger / app.health / ...）
-
-registerPlugins(app, options.plugins);              // app.plugins
-
-require("<lumfall>/app/middleware.js")(app);        // 框架全局中间件
-require("<app-root>/app/middleware.js")(app);       // 业务全局中间件
-
-// lifecycle.beforeRouteLoad(app)
-routerLoader(app);                                  // app.router + 兜底 302 路由
-// lifecycle.afterRouteLoad(app)
-app.diagnostics = createDiagnostics(app);           // 诊断清单
-
-app.server = app.listen(PORT || 3000, IP || "0.0.0.0");
-// lifecycle.afterStart(app)
-```
-
-兜底路由注册在所有业务与框架路由之后：任何未命中路由的 GET 请求会
-302 到 `homePath`。业务路由先于框架路由加载，路径冲突时业务优先。
-
-任何一步抛错（文件导出不合法、schema 与路由不匹配、插件循环依赖、
-配置校验失败……）都会中断启动并抛出异常，`lifecycle.onError` 会先被调用。
-
-## 框架全局中间件链
-
-框架 `app/middleware.js` 按固定顺序 `app.use()`：
-
-```text
-koa-static(app/public)          静态资源
-koa-nunjucks-2(app/public)      模板引擎（ext: tpl）
-koa-bodyparser                  请求体解析（json / form / text）
-errorHandler                    统一异常兜底
-monitoring                      请求观测（未配置时是 passthrough）
-apiParamsVerify                 /api 参数校验（router-schema）
-securityPolicy                  安全策略（apiSignVerify + projectHandler）
-```
-
-业务的 `app/middleware.js` 在框架之后执行，因此业务中间件位于这一串的**内层**：
-请求先经过框架的静态资源、模板、bodyParser、错误处理、参数校验和安全策略，
-再到业务中间件。
-
-## 诊断清单
-
-排查「文件明明写了却没生效」时非常有用：
-
-```js
-const manifest = app.diagnostics.getManifest();
-// {
-//   version: "1.1.0",
-//   environment: "local",
-//   loaders: ["middleware", "router-schema", "controller", "service", "config", "extend", "router"],
-//   routes: [{ path, methods }],
-//   pages: [{ name, entry, route, source }],
-//   healthChecks: [{ name, timeoutMs }],
-// }
-```
-
-- `routes`：已注册路由及方法
-- `pages`：发现的页面入口，`source` 标记 `framework` / `business`
-- `healthChecks`：已注册探针
-- 内容可 JSON 序列化，不含凭证与探针函数，可以直接打成日志或挂在内部排查接口上
-
-## 优雅退出
-
-`app.stop()` 返回 Promise，可重复调用（内部会复用同一次流程）：
-
-```text
-lifecycle.beforeStop → 关闭 HTTP server → lifecycle.afterStop
-```
-
-适合在容器 / pm2 的 `SIGTERM` 处理里调用，等待在途请求处理完再退出。
-
-## 下一步
-
-- [Controller 与 Service](./controller-service.md)
-- [生命周期](./lifecycle.md)

package/templates/document/docs/core/controller-service.md

@@ -1,113 +0,0 @@
-# Controller 与 Service
-
-controller 负责接收请求、组装参数、返回统一响应；service 负责业务逻辑。
-两者都以「工厂函数返回 class」的形式编写，由 loader 自动实例化。
-
-## Controller
-
-`app/controller/<name>.js`，工厂返回 class，继承 `Controller.Base(app)`：
-
-```js
-module.exports = (app) => {
-  const BaseController = require("lumfall").Controller.Base(app);
-
-  return class ArticleController extends BaseController {
-    async getList(ctx) {
-      const { article: articleService } = this.services;
-      const { data, total } = await articleService.list({
-        page: Number(ctx.request.query.page) || 1,
-        size: Number(ctx.request.query.pageSize) || 20,
-      });
-      await this.success(ctx, data, { total });
-    }
-  };
-};
-```
-
-挂载结果：`app.controllers.article`（无子目录时）或
-`app.controllers.admin.articleList`（`app/controller/admin/article-list.js`）。
-
-基类提供：
-
-| 成员 | 说明 |
-| --- | --- |
-| `this.app` | app 实例 |
-| `this.services` | `app.services`（getter，请求阶段取，安全） |
-| `this.config` | `app.config`（getter） |
-| `this.success(ctx, data, metadata)` | 成功响应 |
-| `this.fail(ctx, message, code)` | 失败响应 |
-
-## 统一响应结构
-
-成功与失败都返回 HTTP 200，前端按 body 里的 `success` / `code` 判断：
-
-```js
-// this.success(ctx, data, metadata)
-{ "success": true, "data": ..., "metadata": { "total": 0 } }
-
-// this.fail(ctx, message, code)
-{ "success": false, "message": "获取失败", "code": 50000 }
-```
-
-::: warning this 绑定
-路由绑定 controller 方法时必须 `.bind(controller)`，
-否则方法内的 `this`（`this.services` 等）会丢失：
-
-```js
-router.get("/api/article/list", articleController.getList.bind(articleController));
-```
-:::
-
-## Service
-
-`app/service/<name>.js`，工厂返回 class，继承 `Service.Base(app)`：
-
-```js
-module.exports = (app) => {
-  const BaseService = require("lumfall").Service.Base(app);
-
-  return class ArticleService extends BaseService {
-    async list({ page = 1, size = 20 }) {
-      // 读配置用 this.config（getter，请求阶段安全）
-      // 调其他服务用 this.app.services.xxx
-      return { data: [], total: 0, page, size };
-    }
-  };
-};
-```
-
-service 基类提供 `this.app` 与 `this.config`。跨 service 调用：
-`this.app.services.orderService`。
-
-## 加载时机约束
-
-loader 顺序是 controller → service → config（详见
-[app 对象与启动流程](./app-instance.md)），由此得到两条铁律：
-
-1. **controller 工厂 / 构造期不要取 `app.services`**——那时 service 还没加载。
-   基类的 `this.services` 是 getter，请求阶段解析，所以总是安全的
-2. **不要在工厂执行期读 `app.config`**——配置还没合并。同样推迟到请求阶段
-
-```js
-// ❌ 错误：工厂执行期读配置
-module.exports = (app) => {
-  const maxSize = app.config.maxSize; // undefined，config 还没加载
-  return class extends BaseController { /* ... */ };
-};
-
-// ✅ 正确：请求阶段读
-module.exports = (app) => {
-  const BaseService = require("lumfall").Service.Base(app);
-  return class DemoService extends BaseService {
-    getInfo() {
-      return { maxSize: this.config.maxSize };
-    }
-  };
-};
-```
-
-## 状态与单例
-
-controller / service 实例在启动时创建、全进程共享——**单例**。
-不要把请求级状态挂在 `this` 上（并发请求会互相污染）；请求级数据放 `ctx`，
-跨请求状态放外部存储或通过插件初始化的客户端。

package/templates/document/docs/core/lifecycle.md

@@ -1,60 +0,0 @@
-# 生命周期
-
-`serviceStart({ lifecycle })` 提供启动与退出的 hook：
-
-```js
-serviceStart({
-  lifecycle: {
-    beforeStart(app) {},        // 全部 loader 之前
-    beforeRouteLoad(app) {},    // 全局中间件之后、路由加载之前
-    afterRouteLoad(app) {},     // 路由之后、listen 之前
-    afterStart(app) {},         // listen 之后
-    onError(error, app) {},     // 启动期异常；处理后错误仍会抛出
-    async beforeStop(app) {},   // app.stop() 的第一步
-    async afterStop(app) {},    // server 关闭之后
-  },
-});
-```
-
-## 约束
-
-- **启动期 hook（beforeStart / beforeRouteLoad / afterRouteLoad / afterStart）必须同步**，
-  返回 Promise 会直接启动失败。需要异步初始化（连数据库、拉远程配置）时，
-  在调用 `serviceStart()` **之前**完成，再把结果传进来
-- 未知的 hook 名或非函数值会启动失败
-- `onError` 只提供观测点，不能吞掉错误——处理完异常仍会向上抛
-
-```js
-// ❌ 启动期异步初始化
-lifecycle: {
-  async beforeStart(app) {
-    app.db = await connect(); // 启动失败：hook must be synchronous
-  },
-}
-
-// ✅ 先初始化，再启动
-const db = await connect();
-const app = serviceStart({
-  plugins: [{ name: "database", register: () => ({ client: db }) }],
-});
-```
-
-## 优雅退出
-
-`app.stop()` 返回 Promise，按顺序执行：
-
-```text
-lifecycle.beforeStop → server.close() → lifecycle.afterStop
-```
-
-- 可以重复调用，内部复用同一次关闭流程
-- 适合接 `SIGTERM`（容器 / pm2 场景）：
-
-```js
-process.on("SIGTERM", async () => {
-  await app.stop();
-  process.exit(0);
-});
-```
-
-- `beforeStop` / `afterStop` 是唯二支持异步的 hook，用来刷缓冲、关连接

package/templates/document/docs/core/middleware.md

@@ -1,83 +0,0 @@
-# 中间件
-
-Lumfall 有两种中间件：**可复用中间件**（目录扫描、按名挂载）和
-**全局中间件**（`app.use` 注册到请求链上）。
-
-## 可复用中间件
-
-`app/middleware/**/*.js`，导出工厂 `(app) => (ctx, next) => {}`：
-
-```js
-// app/middleware/api/logger.js
-module.exports = (app) => async (ctx, next) => {
-  const start = Date.now();
-  await next();
-  app.logger.info(`${ctx.method} ${ctx.path} ${Date.now() - start}ms`);
-};
-```
-
-挂载结果：`app.middlewares.api.logger`。框架内置的可复用中间件
-（`app.middlewares.errorHandler`、`app.middlewares.apiParamsVerify`、
-`app.middlewares.securityPolicy`、`app.middlewares.monitoring`、
-`app.middlewares.apiSignVerify`、`app.middlewares.projectHandler`）
-也是同一套约定，业务可以直接复用或覆盖。
-
-::: warning 命名
-文件名用 kebab-case / snake_case，挂载名是 camelCase：
-`params-verify.js` → `app.middlewares.xxx.paramsVerify`。
-用文件原名访问会拿到 undefined。
-:::
-
-可复用中间件**不会自动生效**，需要在路由或全局中间件里显式使用：
-
-```js
-router.post("/api/article", app.middlewares.api.logger, controller.create.bind(controller));
-```
-
-## 全局中间件
-
-`app/middleware.js`（注意是文件不是目录），导出 `(app) => {}`，
-在里面 `app.use()`：
-
-```js
-module.exports = (app) => {
-  app.use(async (ctx, next) => {
-    const start = Date.now();
-    await next();
-    console.log(`${ctx.method} ${ctx.path} ${ctx.status} ${Date.now() - start}ms`);
-  });
-};
-```
-
-执行时机：框架全局中间件之后、路由之前——所以业务全局中间件位于
-框架中间件链的**内层**。
-
-框架全局中间件的注册顺序：
-
-```text
-static → nunjucks → bodyParser → errorHandler → monitoring → apiParamsVerify → securityPolicy
-```
-
-含义：
-
-- 静态资源与页面模板在**最外层**，不受安全策略影响
-- 错误处理包住了后面所有中间件，任何内层异常都会被统一兜底
-- `/api/` 请求在进 controller 前会依次经过参数校验（442）与安全策略（445 / 446）
-- bodyParser 限制了表单大小 1000mb，支持 json / form / text
-
-## 错误处理行为
-
-`errorHandler` 的兜底策略：
-
-| 异常 | 响应 |
-| --- | --- |
-| 消息含 `template not found`（页面模板缺失） | 302 重定向到 `homePath` |
-| 其他异常 | HTTP 200 + `{ success: false, code: 5000, message: "Internal Server Error" }`，异常详情进日志 |
-
-业务代码里主动抛错会被这里兜住；想给前端返回业务错误，用
-`this.fail(ctx, message, code)` 而不是 throw。
-
-## 下一步
-
-- [安全策略](../advanced/security.md)：securityPolicy 中间件的细节
-- [请求观测](../advanced/monitoring.md)：monitoring 的使用方式

package/templates/document/docs/core/plugins.md

@@ -1,77 +0,0 @@
-# 插件
-
-插件用于把「要先于业务中间件 / 路由初始化」的能力组装起来：
-数据库连接、缓存客户端、feature 模块等。
-
-## 基本用法
-
-```js
-serviceStart({
-  plugins: [
-    {
-      name: "database",
-      register(app) {
-        return { client: connect() }; // 返回值挂到 app.plugins.database
-      },
-    },
-    {
-      name: "article-module",
-      dependencies: ["database"], // 依赖先注册
-      register(app) {
-        return { db: app.plugins.database.client };
-      },
-    },
-  ],
-});
-```
-
-注册时机：在全部 loader、config、extend 之后，全局中间件与路由**之前**——
-所以插件的产物在中间件 / 路由里已经可用。
-
-## 规则
-
-| 规则 | 违反后果 |
-| --- | --- |
-| `name` 唯一且非空 | 启动失败 |
-| `register(app)` 必须同步 | 异步 register 启动失败（异步初始化放在 `serviceStart()` 之前做） |
-| 返回值必须是普通对象或 `undefined` | 返回其他类型启动失败 |
-| `dependencies` 里声明的插件必须存在 | 缺依赖启动失败 |
-| 依赖图不能有环 | 循环依赖启动失败 |
-| 依赖先注册 | 框架按依赖拓扑排序执行 register |
-
-与生命周期 hook 一样，register 里做不了异步。标准做法是先初始化再传入：
-
-```js
-const dbClient = await connect(); // serviceStart() 之前
-
-serviceStart({
-  plugins: [
-    { name: "database", register: () => ({ client: dbClient }) },
-  ],
-});
-```
-
-## 使用插件产物
-
-- 服务端：`app.plugins.<name>`
-- 业务代码里同样遵守「请求阶段再取」的原则——插件注册在 controller / service
-  实例化**之后**，工厂执行期读 `app.plugins` 拿到的还是 undefined
-
-```js
-// app/service/user.js
-module.exports = (app) => {
-  const BaseService = require("lumfall").Service.Base(app);
-  return class UserService extends BaseService {
-    async find(id) {
-      const { client: db } = app.plugins.database; // 请求阶段取，已就绪
-      return db.query("select * from user where id = ?", [id]);
-    }
-  };
-};
-```
-
-::: tip 什么时候用插件，什么时候用 extend
-- 插件：有初始化动作、可能被其他模块依赖、需要按序装配的能力（数据库、缓存）
-- extend：挂一个现成的工具对象（`app.utils`、`app.http`），无依赖顺序诉求
-  （见[目录结构与挂载点](../guide/structure.md)）
-:::

package/templates/document/docs/core/router-schema.md

@@ -1,102 +0,0 @@
-# 路由与参数校验
-
-路由文件负责把 URL 绑到 controller 方法；router-schema 用 JSON Schema（Ajv）
-声明参数约束，框架中间件在请求进入 controller 前自动校验。
-
-## 注册路由
-
-`app/router/<name>.js`，导出 `(app, router) => {}`：
-
-```js
-module.exports = (app, router) => {
-  const { article: articleController } = app.controllers;
-
-  router.get("/api/article/list", articleController.getList.bind(articleController));
-
-  router.post(
-    "/api/article",
-    app.middlewares.apiParamsVerify, // 可选：挂额外中间件
-    articleController.create.bind(articleController)
-  );
-};
-```
-
-- 框架自带路由：`/view/:page` 与 `/view/:page/*`（页面渲染）、
-  `/health/live`、`/health/ready`、`/api/project/*`（Dashboard 数据）
-- 业务路由先于框架路由加载，同路径时业务优先
-- 完全未命中的 GET 请求 302 到 `homePath`
-
-## 声明参数校验
-
-`app/router-schema/<name>.js`，导出「path → method → schema」的映射，
-或 `(app) => map` 工厂：
-
-```js
-module.exports = {
-  "/api/article/list": {
-    get: {
-      query: {
-        type: "object",
-        properties: {
-          page: { type: "integer", minimum: 1 },
-          pageSize: { type: "integer", minimum: 1, maximum: 200 },
-        },
-      },
-    },
-  },
-  "/api/article": {
-    post: {
-      body: {
-        type: "object",
-        properties: {
-          title: { type: "string", minLength: 1 },
-        },
-        required: ["title"],
-      },
-    },
-  },
-};
-```
-
-可校验的位置：`headers` / `body` / `query` / `params`（JSON Schema draft-07 风格）。
-
-## 校验行为
-
-- 只作用于 **`/api/` 开头**的请求，其余路径不校验
-- schema 里没声明的 path / method 直接放行
-- 校验失败返回 **HTTP 200** + 业务错误码：
-
-```json
-{
-  "success": false,
-  "message": "request validate fail: data should have required property 'title'",
-  "code": 442
-}
-```
-
-## 启动期一致性校验
-
-router-schema 与路由的一致性在**启动时**校验，不匹配直接启动失败：
-
-- key（path）必须是已注册路由的 path
-- method 必须全小写，且该路由确实以这个方法注册过
-
-```text
-Error: [router] router-schema path "/api/artile/list" does not match a registered route
-```
-
-::: tip 常见坑
-- path 手打错一个字母 → 启动失败（这是故意的，把问题提前到启动期）
-- method 写成 `"GET"` → 启动失败，必须小写
-- 校验只对 `/api/` 开头的路径生效，`/view/...` 不参与
-:::
-
-## 校验器缓存
-
-Ajv 编译后的校验器按 `method + path + 位置` 缓存（schema 是启动期静态数据），
-运行时没有重复编译开销。
-
-## 下一步
-
-- [中间件](./middleware.md)：参数校验在整条中间件链的位置
-- [安全策略](../advanced/security.md)：445 / 446 错误码来自哪里