create-lumfall 1.0.0 → 1.1.1

package/templates/document/docs/frontend/curl.md

@@ -1,75 +0,0 @@
-# 请求工具 curl
-
-框架提供统一的请求工具 `$lumfallCurl`，封装了 axios、统一响应处理、
-接口签名与 project_key 透传。
-
-## 基本用法
-
-```js
-import $curl from "$lumfallCurl";
-
-const res = await $curl({
-  url: "/api/project/product/list",
-  method: "get",            // 默认 post
-  query: { page: "1", pageSize: "20" },  // query 参数
-  data: { title: "x" },     // 请求体
-  headers: {},              // 额外请求头
-  timeout: 60000,           // 默认 60000ms
-  responseType: "json",
-});
-
-if (res && res.success) {
-  console.log(res.data, res.metadata);
-}
-```
-
-返回值是接口的 body（`{ success, data, metadata }` 或
-`{ success: false, message, code }`），网络异常时返回包含错误信息的对象，
-**不会 reject**——业务代码统一按 `res.success` 判断。
-
-## 自动处理的协议细节
-
-### 接口签名
-
-每个请求自动携带 `s_t`（毫秒时间戳）与 `s_sign`（`md5("lumfall_" + st)`），
-对应服务端的 apiSignature 校验（见[安全策略](../advanced/security.md)）。
-注意：默认签名串是 `lumfall`，服务端配置了自定义 `secret` 时，
-客户端要用同样的 secret 重新生成签名。
-
-### project_key
-
-页面 URL 带 `?projectKey=xxx` 时（`window.__LUMFALL__.projectKey`），
-对 `/api/project/` 开头的请求自动追加 `project_key` 请求头，
-对应服务端的 projectHandler 校验。
-
-### 错误码提示
-
-`success: false` 时按 code 弹出 Arco Message 错误提示：
-
-| code | 提示 |
-| --- | --- |
-| 442 | Invalid request parameters（参数校验失败） |
-| 445 | Invalid request（签名校验失败） |
-| 446 | Required parameter is missing（缺 project_key） |
-| 50000 | 显示服务端 message（`this.fail` 的默认约定码） |
-| 其他 | Network Error |
-
-业务想自定义失败处理时，忽略提示逻辑直接处理返回值即可。
-
-## window.__LUMFALL__
-
-curl 依赖页面模板注入的全局数据（见[页面系统](./page.md)）：
-
-```js
-window.__LUMFALL__ = {
-  name: "my-app",
-  env: "local",
-  options: { /* serviceStart 的 options */ },
-  projectKey: "",
-};
-```
-
-## 下一步
-
-- [安全策略](../advanced/security.md)：签名与 project_key 的服务端逻辑
-- [Dashboard 与 Model 配置](../advanced/dashboard.md)：curl 在 Dashboard 页面里的使用

package/templates/document/docs/frontend/page.md

@@ -1,99 +0,0 @@
-# 页面系统
-
-前端页面放在 `app/pages/<page-name>/` 下，由 Webpack 按 `entry.<page-name>.js`
-自动发现为入口，Koa 通过 `/view/<page-name>` 渲染。
-
-## 页面结构
-
-```text
-app/pages/
-└── project-list/
-    ├── entry.project-list.js    # 入口文件（命名必须是 entry.<page-name>.js）
-    └── project-list.vue         # 页面组件
-```
-
-入口文件通常长这样（`$lumfallBoot` 是框架提供的启动器别名）：
-
-```js
-import boot from "$lumfallBoot";
-import Page from "./project-list.vue";
-
-boot(Page);
-```
-
-需要 vue-router 的页面（多视图），把路由数组作为第二个参数传入：
-
-```js
-import boot from "$lumfallBoot";
-import Page from "./dashboard.vue";
-
-boot(Page, {
-  routes: [
-    { path: "/view/dashboard", component: () => import("./dashboard.vue") },
-    { path: "/view/dashboard/todo", component: () => import("./todo/todo.vue") },
-  ],
-});
-```
-
-::: warning 路由 base
-`boot` 内部用 `createWebHistory()` 创建 router（base 为 `/`），所以路由 path
-要写**完整路径**（`/view/<page>/...`），且必须与框架服务端路由 `/view/:page/*`
-的前缀一致，否则刷新页面会被兜底重定向。
-:::
-
-## 访问与错误码
-
-- 页面访问路径：`/view/<page-name>`
-- 页面不存在（入口没被发现）：HTTP 404 + `code 4041`
-- 页面存在但模板没构建出来（没执行过构建）：HTTP 503 + `code 5031`
-- 模板渲染异常（含 `template not found`）会 302 到 `homePath`
-
-## 用脚手架生成页面
-
-```sh
-# package.json 里配置了 new-page 脚本时
-pnpm new-page project-list            # 生成 entry.project-list.js + project-list.vue
-pnpm new-page report --header         # 额外套 HeaderContainer 布局
-
-# 没配脚本时直接调用框架的脚手架
-node ./node_modules/lumfall/scripts/generate-page.js project-list
-```
-
-- 页面名必须是 kebab-case（小写字母开头），已存在的目录会被拒绝
-- `--header` 生成的页面用框架的 `HeaderContainer` 组件做整体布局
-
-## boot 做了什么
-
-`$lumfallBoot`（框架 `app/pages/boot.js`）依次完成：
-
-1. `createApp(pageComponent)`
-2. 注册 Arco Design Vue（含图标库）与 Pinia
-3. 若传了 `routes`：创建 vue-router（history 模式），等 `router.isReady()` 后挂载；
-   否则直接挂载到 `#root`
-
-所以页面里可以直接使用 `a-*` 组件、`pinia` store，无需手动注册。
-
-## 服务端注入的全局数据
-
-页面模板由 nunjucks 渲染，`window.__LUMFALL__` 上有服务端注入的数据：
-
-```js
-window.__LUMFALL__ = {
-  name: "my-app",        // serviceStart 的 options.name
-  env: "local",          // _ENV 值
-  options: { ... },      // serviceStart 的完整 options（JSON）
-  projectKey: "",        // URL query 里的 projectKey（Dashboard 场景）
-};
-```
-
-## 页面发现规则
-
-- 框架自带页面（`dashboard`、`health`）与业务页面一起被发现
-- **同名时业务页面覆盖框架页面**
-- 同一来源（framework 或 business）内出现同名入口会启动报错
-- 排查页面是否被发现：`app.diagnostics.getManifest().pages`
-
-## 下一步
-
-- [前端构建](./build.md)：Webpack 管线与别名
-- [内置组件](./widgets.md)：HeaderContainer / schema 三件套

package/templates/document/docs/frontend/widgets.md

@@ -1,151 +0,0 @@
-# 内置组件
-
-框架内置了一组布局与 schema 驱动的组件（Arco Design Vue 风格），
-业务页面直接通过别名引用，用于快速搭建列表页 / 表单页 / 管理台。
-
-::: tip schema 三件套与 DSL 的关系
-本页讲的是**独立使用**这些组件的 props / 事件；在 Dashboard 里由
-[DSL 配置](../dsl/overview.md)驱动它们时，schema 的 `xxxOption`
-如何拆分、按钮与动态表单如何声明，见
-[schema 模块 DSL](../dsl/schema.md) 与[按钮与动态表单](../dsl/schema-actions.md)。
-:::
-
-## 布局组件
-
-### HeaderContainer
-
-```vue
-<template>
-  <HeaderContainer title="商品管理">
-    <template #menu-content>
-      <!-- 顶部导航区（如 a-menu） -->
-    </template>
-    <template #setting-content>
-      <!-- 右上设置区 -->
-    </template>
-    <template #main-content>
-      <!-- 主体内容 -->
-    </template>
-  </HeaderContainer>
-</template>
-
-<script setup>
-import HeaderContainer from "$lumfallHeaderContainer";
-</script>
-```
-
-- props：`title`（标题，默认配 logo）
-- slots：`menu-content`（顶栏中部）、`setting-content`（顶栏右侧，自带用户下拉）、
-  `main-content`（主体）
-
-### SiderContainer
-
-```vue
-<template>
-  <SiderContainer>
-    <template #menu-content>
-      <!-- 左侧菜单（如 a-menu mode="vertical"） -->
-    </template>
-    <template #main-content>
-      <!-- 主体内容 -->
-    </template>
-  </SiderContainer>
-</template>
-
-<script setup>
-import SiderContainer from "$lumfallSiderContainer";
-</script>
-```
-
-## Schema 三件套
-
-一套用 JSON Schema 描述「表格 / 搜索栏 / 表单」的组件，schema 里每个字段的
-`option` 控制对应控件的渲染。Dashboard 的 schema 菜单模块就用它们驱动页面
-（见 [Dashboard 与 Model 配置](../advanced/dashboard.md)）。
-
-### SchemaTable
-
-```vue
-<template>
-  <SchemaTable
-    :schema="tableSchema"
-    api="/api/project/product/list"
-    :buttons="buttons"
-    @operate="handleOperate"
-  />
-</template>
-
-<script setup>
-import SchemaTable from "$lumfallSchemaTable";
-</script>
-```
-
-- props：
-  - `schema`：字段 schema；`option.visible` 控制列显示，
-    `option.enumList`（`[{ label, value }]`）把枚举值渲染成彩色标签，
-    其余 `option` 透传给 `a-table-column`
-  - `api`：列表接口**基址**——组件实际请求 `GET <api>/list`，
-    分页参数 `page` / `pageSize`，期望 `{ data, metadata: { total } }` 响应结构
-  - `apiParams`：额外查询参数
-  - `buttons`：操作列按钮 `[{ label, eventKey, eventOption, ...aButtonConfig }]`
-- emits：`operate`（点操作按钮，携带 `{ btnConfig, rowData }`）
-- 自带分页器（10/20/50/100/200 每页），默认省略号 + tooltip 防长文本撑破列宽
-
-### SchemaSearchBar
-
-```vue
-<template>
-  <SchemaSearchBar :schema="searchSchema" @search="onSearch" @load="onLoad" />
-</template>
-
-<script setup>
-import SchemaSearchBar from "$lumfallSchemaSearchBar";
-</script>
-```
-
-- props：`schema`（每个字段的 `option.componentType` 支持
-  `input` / `select` / `dynamicSelect` / `dateRange`，`option.default` 为默认值）
-- emits：`search`（点查询，携带表单值）、`reset`（点重置）、
-  `load`（动态控件就绪后触发一次，携带默认值）
-- 字段值由各控件 `getValue()` 合并产出
-
-### SchemaForm
-
-```vue
-<template>
-  <SchemaForm ref="formRef" :schema="formSchema" :model="formData" />
-  <a-button type="primary" @click="submit">提交</a-button>
-</template>
-
-<script setup>
-import SchemaForm from "$lumfallSchemaForm";
-
-const formRef = ref(null);
-
-const submit = async () => {
-  if (!formRef.value.validate()) return;
-  const value = formRef.value.getValue();
-  // ...提交
-};
-</script>
-```
-
-- props：`schema`（字段 `option.componentType` 支持 `input` / `inputNumber` /
-  `select`；`option.required` 必填校验；`option.visible` / `option.disabled` /
-  `option.default` / `option.enumList`）、`model`（受控数据）
-- expose：`validate()`（全部表单项校验，返回布尔）、`getValue()`
-  （合并全部字段值）
-
-### 扩展控件
-
-schema 组件的控件类型通过配置文件注册，业务可扩展自己的控件类型：
-`app/pages/widgets/schema-form/form-item-config.js`、
-`app/pages/widgets/schema-search-bar/complex-view/search-item-config.js`、
-`app/pages/dashboard/complex-view/schema-view/components/component-config.js`
-（分别对应别名 `$businessFormItemConfig` / `$businessSearchItemConfig` /
-`$businessComponentConfig`，见[前端构建](./build.md)）。
-
-## 下一步
-
-- [DSL 总览](../dsl/overview.md)：用配置驱动这些组件生成整站管理台
-- [请求工具 curl](./curl.md)：组件内部如何发请求

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

@@ -1,108 +0,0 @@
-# 配置
-
-配置放在业务根目录的 `config/` 下，按 `_ENV` 环境分层加载，**四层浅合并**，
-后面的覆盖前面的同名键：
-
-```text
-框架 config.default.js → 业务 config.default.js → 框架 config.<env>.js → 业务 config.<env>.js
-```
-
-环境由环境变量 `_ENV` 决定（`local` / `beta` / `prod`，缺省 `local`），
-**不是 `NODE_ENV`**。`_ENV` 不存在对应的配置文件时按空对象处理，不会报错。
-
-## 基本用法
-
-```js
-// config/config.default.js
-module.exports = {
-  name: "my-app",
-  apiBasePath: "/api",
-  security: {
-    apiSignature: { enabled: false, maxAgeMs: 600000 },
-    projectKey: { enabled: true, headerName: "project_key" },
-  },
-};
-```
-
-```js
-// config/config.prod.js —— 只写需要覆盖的键
-module.exports = {
-  security: {
-    apiSignature: { enabled: true, secret: process.env.API_SIGN_SECRET },
-  },
-};
-```
-
-::: warning 浅合并
-合并是**一层**的浅合并（`Object.assign` 语义）：对象型配置在环境文件里
-覆盖时是**整键替换**，不是深合并。上例的 `security` 会整体替换 default 里的
-`security`，所以环境文件里要写完整的安全配置，不要只写变化的子键。
-:::
-
-## 工厂形式
-
-配置文件也可以导出工厂函数 `(app) => object`，适合需要读 `app` 信息的场景。
-工厂**必须返回普通对象**，否则启动直接失败：
-
-```js
-// config/config.prod.js
-module.exports = (app) => ({
-  port: process.env.PORT,
-  env: app.env.get(),
-});
-```
-
-## 读取配置
-
-- 服务端在**请求阶段**读 `app.config`（controller / service 基类的 `this.config`
-  getter 是安全的）
-- 不要在 loader 工厂执行期或构造期读 `app.config`——`configLoader` 在 controller /
-  service 之后才执行，那时它还不存在
-- 前端页面可从 `window.__LUMFALL__.options` 拿到 `serviceStart` 的入参
-  （注意是 options，不是 config；需要下发的值请通过接口返回）
-
-## JSON Schema 强校验
-
-需要强约束配置时，在 `serviceStart` 传入 `configSchema`（JSON Schema，Ajv 校验）。
-合并后的配置不匹配会**启动失败**，错误信息指明环境、字段路径和原因：
-
-```js
-// server.js
-const app = serviceStart({
-  name: "my-app",
-  homePath: "/view/home",
-  configSchema: {
-    type: "object",
-    properties: {
-      name: { type: "string" },
-      "security": {
-        type: "object",
-        properties: {
-          apiSignature: {
-            type: "object",
-            properties: {
-              enabled: { type: "boolean" },
-              secret: { type: "string" },
-            },
-            required: ["enabled"],
-          },
-        },
-      },
-    },
-    required: ["name"],
-  },
-});
-```
-
-校验失败示例：
-
-```text
-Error: [config] merged configuration for "prod" is invalid: /security/apiSignature
-  should have required property 'enabled'
-```
-
-## 生产环境建议
-
-- 密钥、连接串走环境变量（`process.env.XXX`）或配置中心，不要提交进仓库
-- 开启 `configSchema`，把「配置写错」从运行时问题提前到启动失败
-- 敏感配置不要通过接口原样下发给前端

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

@@ -1,115 +0,0 @@
-# 构建与部署
-
-## 两种构建
-
-`frontendBuild(_ENV)` 只认两个值，其他值什么都不做（所以 `_ENV=beta` 没有 dev 构建）：
-
-| `_ENV` | 行为 |
-| --- | --- |
-| `local` | 启动 Webpack dev server（Express，默认 `127.0.0.1:9002`），HMR 热更新，内存编译 |
-| `prod` | 完整产物构建到 `app/public/dist/prod/`，同时把每个页面的模板写到 `app/public/dist/entry.<name>.tpl` |
-
-## 产物结构
-
-`_ENV=prod node build.js` 之后：
-
-```text
-app/public/dist/
-├── dev/                       # _ENV=local 构建产物（含 dev/entry.<page>.tpl 模板）
-└── prod/
-    ├── js/
-    │   ├── runtime~entry.<page>_*.bundle.js
-    │   ├── vendor_*.bundle.js     # node_modules 第三方库
-    │   ├── common_*.bundle.js     # 被 ≥2 个入口引用的业务公共代码
-    │   └── entry.<page>_*.bundle.js
-    ├── css/
-    │   ├── vendor_*.bundle.css
-    │   └── ...
-    └── entry.<page>.tpl       # 页面模板（Koa 用 nunjucks 渲染，按模式分目录）
-```
-
-- 分包策略（vendor / common / runtime）目的是让第三方与公共代码的长缓存稳定，
-  业务代码改动不影响 vendor 的 hash
-- 生产构建会先清空 `app/public/dist/` 再输出
-- 模板里的资源以 `/dist/prod/` 为 publicPath，由 Koa 的静态目录（`app/public`）直接服务
-- 页面模板按模式分目录（lumfall ≥ 1.2.0）：dev 构建写 `dist/dev/`、prod 构建写 `dist/prod/`，服务按 `_ENV` 渲染对应目录——模式不匹配时返回 503 并提示应执行的构建命令，不会白屏
-
-::: tip 模式不匹配时的表现（lumfall ≥ 1.2.0）
-dev 与 prod 构建的模板按模式分目录存放，服务只渲染 `_ENV` 对应目录的模板。
-跑过 dev 构建后直接以 prod 模式启动（没执行 `build:prod`），页面请求会返回
-503（code 5031）并附上应执行的构建命令——按提示重新构建即可，不会再出现
-无报错的白屏。
-:::
-
-## 本地开发
-
-```sh
-pnpm start:dev
-# = concurrently "pnpm build:dev" "pnpm dev"
-```
-
-- Webpack dev server 监听 `127.0.0.1:9002`，负责产出 JS/CSS 与 HMR 长连接
-- Koa 服务监听 `0.0.0.0:3000`，页面模板在编译完成后写到磁盘
-  （`app/public/dist/entry.<name>.tpl`），模板里的资源 URL 指向 dev server
-- 页面访问走 Koa（`http://localhost:3000/view/<name>`），不要直接访问 9002
-
-`PORT` / `IP` 环境变量可以覆盖 Koa 监听地址：
-
-```sh
-PORT=8080 IP=127.0.0.1 _ENV=local node server.js
-```
-
-## 生产部署
-
-```sh
-pnpm install
-_ENV=prod node build.js
-_ENV=prod node server.js
-```
-
-通常再配一个进程守护（pm2 / systemd / 容器）：
-
-```sh
-# pm2 示例
-pm2 start server.js --name my-app --env _ENV=prod
-```
-
-- 服务器只需要 `server.js` + 构建产物；`build.js` 可以在 CI 里执行
-- 健康检查接入负载均衡：存活探针用 `/health/live`，就绪探针用 `/health/ready`
-  （详见 [健康检查](../advanced/health.md)）
-- 日志输出在工作区 `logs/` 目录（log4js），注意持久化或采集
-
-## 端口与地址速记
-
-| 变量 | 默认 | 说明 |
-| --- | --- | --- |
-| `PORT` | 3000 | Koa 服务端口 |
-| `IP` | 0.0.0.0 | Koa 监听地址 |
-| dev server | 127.0.0.1:9002 | Webpack dev server（HMR），端口写在框架 `webpack.dev.js` |
-
-## 静态托管（Vercel / Netlify / Nginx）
-
-不依赖 `/api` 的纯前端项目（页面数据都在构建期打包，比如文档站）可以脱离
-Koa 以**纯静态站点**部署，不需要 Node 进程：
-
-1. 正常执行 `_ENV=prod` 构建，产物为 `app/public/dist/` 下的
-   `entry.<page>.tpl`（页面外壳）与 `prod/`（带 hash 的静态资源）
-2. 把 `.tpl` 里的 `window.__LUMFALL__` 占位符替换为静态值，另存为 `app.html`
-3. 配置 SPA rewrite：`/view/<page>` 与 `/view/<page>/:path*` → `app.html`；
-   其余静态资源按原路径放行（模板里资源 URL 是 `/dist/prod/...` 绝对路径，
-   保持目录结构即可）
-4. 原来的 302 兜底用一个静态跳转页替代（`/` → 目标页面）
-
-完整可运行的参考实现见 `lumfall-document/` 的 `scripts/build-static.js`
-（`pnpm build:static` 一键产出 `dist-static/`，含 vercel.json rewrite 与
-长缓存头，可直接部署 Vercel）。
-
-::: tip 什么时候可以静态托管
-页面只用「构建期已知的数据」——文档站、纯展示页、营销页。只要页面运行时
-会调 `/api`（如 Dashboard、业务页面），就需要 Koa 服务，走上面的服务端部署。
-:::
-
-## 下一步
-
-- [app 对象与启动流程](../core/app-instance.md)：理解启动时发生了什么
-- [健康检查](../advanced/health.md)：接入业务依赖探针