@ynight/framework 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 diaogroup
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,512 @@
-# Temporary Holding Version
+# @ynight/framework
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> 框架主入口——把服务端装配（Koa）、客户端运行时（Vue 3 + Element Plus + Pinia）、模型 DSL（defineModel / defineControlContracts）和内置静态资源整合在同一个包中。
+
+`@ynight/framework` 是 Elpis 的统一运行时包。应用开发者主要依赖此包：服务端用 `@ynight/framework`（或 `@ynight/framework/server`）启动 Koa 应用、装配业务模块；客户端用 `@ynight/framework/client` 启动内置后台；模型层用 `@ynight/framework/model` 声明菜单 / 模块 / 自定义控件契约。
+
+底层能力来自 `@ynight/core`（Koa 容器与生命周期）、`@ynight/contracts`（DSL 类型契约）与 `@ynight/model-runtime`（模型加载与校验）。
+
+## 子导出（Sub-path Exports）
+
+| 子路径                        | 角色             | 主要内容                                                                                                                |
+| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `@ynight/framework`（默认）   | 服务端装配入口   | `createApplication`、`startApplication`、`defineServer`、`BaseService`、`BaseController`、类型集合                      |
+| `@ynight/framework/server`    | 同上（显式路径） | 与默认入口导出完全一致，便于需要明确语义的位置                                                                          |
+| `@ynight/framework/model`     | 模型 / 菜单 DSL  | `defineModel`、`defineControlContracts`、`custom` / `iframe` / `group` / `sider` / `schema` 等菜单工厂；契约 / DTO 类型 |
+| `@ynight/framework/client`    | 内置后台客户端   | `createAdminApp`、`defineClientExtensions`、`SchemaForm`、`SchemaTable`、schema 解析工具                                |
+| `@ynight/framework/assets`    | 框架静态资源     | `frameworkPageNames`、`readFrameworkPage`、`frameworkAssetsRoot`                                                        |
+| `@ynight/framework/style.css` | 客户端样式       | 客户端运行时需要的样式（含 Element Plus 的扩展）                                                                        |
+
+## 安装
+
+```bash
+pnpm add @ynight/framework element-plus pinia vue vue-router
+```
+
+> `@ynight/framework` 在 `peerDependencies` 里显式声明 `element-plus ^2.13.1`、`pinia ^3.0.4`、`vue ^3.5.26`、`vue-router ^4.6.4`，需要在宿主应用中安装这些包（按版本范围匹配）。
+>
+> 包内部还依赖 `ajv` / `ajv-formats` / `ajv-i18n` / `koa` / `koa-bodyparser` / `koa-static` / `lodash` 等运行时依赖，以及 `@ynight/contracts`、`@ynight/core`、`@ynight/model-runtime` 三个工作空间内部包。
+
+要求 Node.js `>=22.0.0`。
+
+---
+
+## 服务端（`@ynight/framework` 或 `@ynight/framework/server`）
+
+服务端入口基于 Koa + `@koa/router`，把"业务模块扫描 → 模型加载 → 路由校验 → 鉴权 → 静态资源 → History 兜底"装配为一个托管应用。
+
+### 核心 API
+
+| API                                                                     | 说明                                                                                                             |
+| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `createApplication(context)`                                            | 创建已装配的 Koa 应用，不监听端口；返回 `ManagedApplication`（含 `app / listen / close`）                        |
+| `startApplication(context)`                                             | 一键装配并按 `production` 模式启动（即使环境变量是 development 也强制为 production，因为这是真正对外监听的场景） |
+| `defineServer(setup)`                                                   | 类型断言助手：声明 `ServerExtension`（auth / devAnonymous / onReady / onClose）并享受完整类型提示                |
+| `defineRoutes(setup)`                                                   | 类型断言助手：声明 `RouteFactory`，返回值可为 `RouteDefinition[]` 或 `undefined`（Proxy 模式）                   |
+| `defineConfig(config)`                                                  | 类型断言助手：声明 `ElpisConfig` 对象或基于 mode 的工厂                                                          |
+| `BaseService` / `BaseController`                                        | 业务基类（构造期注入 `app`；控制器提供 `success` / `fail` 统一响应封装）                                         |
+| `resolveConfig(rootDir, mode, input?)`                                  | 解析 `elpis.config` + 环境变量 + 默认值，返回 `{ config, paths }`                                                |
+| `resolveApplicationPaths(rootDir, config?, mode?, publicRootOverride?)` | 计算并校验所有生成路径（带"必须在根目录内"、"禁止覆盖受保护目录"等安全校验）                                     |
+| `createLegacyApplication`                                               | 旧版迁移桥接（直接透传 `@ynight/core` 的 `createApplication`），仅供存量项目使用                                 |
+
+### 最小示例
+
+```typescript
+// entry.ts
+import { createApplication, defineServer } from '@ynight/framework';
+
+const app = await createApplication({
+  rootDir: __dirname,
+  mode: process.env.NODE_ENV === 'production' ? 'production' : 'development',
+  moduleExtension: '.js', // CLI 编译后业务模块的扩展名
+  server: defineServer({
+    auth: myAuthAdapter,
+    devAnonymous: true, // 仅非生产生效
+    onReady(app) {
+      // 可继续 app.use() 注册额外中间件或探针
+    },
+  }),
+});
+
+await app.listen({ host: '0.0.0.0', port: 3000 });
+```
+
+### `createApplication` 装配顺序（严格按阶段执行）
+
+`createApplication` 在一个 try/catch 中按以下顺序装配；任一阶段抛错都会在 finally 中尝试关闭已启动容器并抛出原错误。
+
+1. **解析配置与路径**：调用 `resolveConfig(rootDir, mode, context.config)`；当传入 `moduleRoot` 时，重新拼接 `serverRoot / modelRoot / sharedRoot`，便于 CLI 在 `dist` 中加载业务模块。
+2. **预热框架内置页面**：通过 `frameworkPageNames.forEach(p => readFrameworkPage(...))` 把 `project-list / dashboard / error` 三个 HTML 模板读入缓存，保证后续路由兜底能同步返回 HTML。
+3. **加载并校验业务模型**：
+   - `loadModels({ modelDir, extension })` 加载 `model/` 目录下所有模块；
+   - 对每个项目检查 `mode === 'site'` 直接抛错（site 模板尚未实现，启动期拒止，避免运行时半成品）；
+   - `validateModels(models, { controlContracts })` 校验模型（控件契约 JSON Schema）；
+   - 通过 `loadControlContracts` 装载 `model.controlContracts` 索引文件（不存在则为空对象，配置缺失时抛 `ERR_CONTROL_CONTRACT_MISSING`）。
+4. **创建 Koa 容器**：通过 `createApplicationContainer` 装配 host/port/closeTimeoutMs，并通过 `validateListen` 钩子确保 `devAnonymous` 仅监听回环地址（`127.0.0.1 / localhost / ::1 / 0:0:0:0:0:0:0:1`）。
+5. **注入框架扩展字段**：用 `Object.defineProperties` 把 `config / paths / mode / framework / routerSchema / serverExtension` 设为只读；`service / controller / middlewares` 在装载阶段写入，标记为 writable。
+6. **注册全局错误兜底 + bodyParser + 认证/匿名中间件**：
+   - 顶层 try/catch 中间件：捕获下游所有抛错，统一输出 `{ success, code, message }` 结构（`/api/*` 路径）或 `text/plain` 兜底（其它路径），并触发 `app.emit('error', error, ctx)`；
+   - `bodyParser`（启用 json/form/text 三种类型）；
+   - 认证：调用 `serverExtension.auth.authenticate(ctx)`；未登录时回退到 `devAnonymous`（仅非生产）或返回 401 + `WWW-Authenticate` 头。
+7. **业务装载**：`server/service/` 与 `server/controller/` 通过 `loadClassModules` 自动实例化（构造期注入 `app`），`server/middleware/` 下的工厂被依次 `app.use(...)`。
+8. **注册框架内置路由**（业务路由与之冲突会立即报错）：
+   - `GET /api/session`——当前登录身份 + 公共配置；
+   - `GET /api/project/model_list`——按模型聚合的可见项目列表；
+   - `GET /api/project/list`——扁平项目列表（支持 `?modelKey=...` 过滤）；
+   - `GET /api/project`——单个项目详情（按 `?projectKey=...` 过滤 + 菜单授权过滤）。
+9. **注册业务路由 + 参数校验**：
+   - 业务路由文件支持两种声明方式：
+     - **Proxy 模式**：`export default (app, router) => { router.get('/api/foo', handler); router.post('/api/foo', handler); }`；
+     - **声明式**：`export default defineRoutes(app => [{ method, path, handler, access?, schema?, projectRequired? }])`；
+   - 路由注册按"路由级 access → attachProject（写入 ctx.state.projectKey）→ 内联 schema 或集中 schema → handler"装配；
+   - 装配完成后调用 `assertNoOrphanSchemas`，确保 `router-schema/` 目录下每条校验规则都对应一个实际路由（避免定义却未使用的死代码）。
+10. **静态资源 + History 兜底**：
+    - `koaStatic(publicRoot)` 之前先做两道护栏：`/api/*` 永远走接口（含同名静态文件也不能劫持）；含扩展名的静态业务资源会经过 `module=public, action=read` 授权；
+    - 兜底中间件：`/api/*` 未匹配路由返回 404 结构化响应；非 API + 404 + GET/HEAD 走 `pageForPath` 命中 `project-list / dashboard / error` 任一页面，否则尝试 `redirectCustomPageShortcut`（自定义菜单短链重定向），最终 404 兜底。
+11. **`onReady` 钩子**：所有装配完成后调用 `serverExtension.onReady?.(app)`。
+
+### `ApplicationContext`
+
+```typescript
+interface ApplicationContext {
+  rootDir: string; // 项目根目录（必填）
+  sourceRoot?: string; // 配置所在源码根，未传则等于 rootDir
+  moduleRoot?: string; // CLI 编译产物根；提供后从该目录加载 server/model
+  mode?: ElpisMode; // 覆盖 NODE_ENV 推断
+  moduleExtension?: '.ts' | '.js' | '.cjs'; // 业务模块扩展名；未传则按目录推断
+  config?: ConfigInput; // ElpisConfig 或基于 mode 的工厂函数
+  server?: ServerExtension; // 认证 / 钩子
+  publicRoot?: string; // 覆盖默认的 ./public 静态资源目录
+}
+```
+
+### `ApplicationContext` 装配出的 `FrameworkApplication`
+
+`createApplication` 通过 `Object.defineProperties` 在 Koa 实例上追加以下只读 / 可写字段：
+
+| 字段                               | 读写性   | 说明                                                      |
+| ---------------------------------- | -------- | --------------------------------------------------------- |
+| `config: ResolvedElpisConfig`      | 只读     | 解析后的运行时配置（含默认值 + 环境变量覆盖）             |
+| `paths: ApplicationPaths`          | 只读     | 所有目录的绝对路径集合                                    |
+| `mode: ElpisMode`                  | 只读     | 当前运行模式                                              |
+| `framework: FrameworkServices`     | 只读     | `{ models, routerSchemas, controlContracts }`             |
+| `routerSchema: RouterSchemas`      | 只读     | 集中维护的请求校验规则                                    |
+| `serverExtension: ServerExtension` | 只读     | 业务注入的扩展（auth / devAnonymous / onReady / onClose） |
+| `service: BusinessServices`        | writable | 业务 service 索引（key 为文件名）                         |
+| `controller: BusinessControllers`  | writable | 业务 controller 索引                                      |
+| `middlewares: BusinessMiddlewares` | writable | 业务 middleware 索引（中间件已挂载，这里主要用于可见性）  |
+
+### 业务模块约定
+
+业务模块按"约定优于配置"的方式被框架扫描：
+
+| 目录                             | 导出                                                        | 说明                                                  |
+| -------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------- |
+| `server/controller/<name>.ts`    | `export default class extends BaseController`               | 构造期接收 `app`；实例被索引到 `app.controller[name]` |
+| `server/service/<name>.ts`       | `export default class extends BaseService`                  | 同上；实例被索引到 `app.service[name]`                |
+| `server/middleware/<name>.ts`    | `export default (app) => Middleware`                        | 工厂在装配期被调用，返回值依次 `app.use()`            |
+| `server/router/<name>.ts`        | `export default (app, router) => void \| RouteDefinition[]` | 推荐 Proxy 模式；声明式用 `defineRoutes`              |
+| `server/router-schema/<name>.ts` | `export default { '/api/xxx': { get: { query: {...} } } }`  | 集中维护的请求参数校验                                |
+| `model/<name>.ts`                | `defineModel({ ... })` 或 `defineControlContracts({ ... })` | 由 `@ynight/framework/model` 提供工厂                 |
+
+### 路由校验（schema）
+
+框架提供两种校验来源：
+
+1. **路由内联 schema**：在 `RouteDefinition.schema` 字段直接写 `body/query/params/headers` 四位置的 JSON Schema；
+2. **集中校验规则**：`server/router-schema/<name>.ts` 默认导出 `{ '/api/path': { get: { query: ... }, post: { body: ... } } }`，按路由 + HTTP 方法匹配。
+
+校验器基于 Ajv（`allErrors` + `coerceTypes` + `strict`）并注入 `ajv-formats`。校验顺序为 `body → query → params → headers`，任一位置失败立即返回：
+
+```json
+{
+  "success": false,
+  "code": 400,
+  "message": "参数校验失败: body.field.x [required] 必须有 property \"x\""
+}
+```
+
+启动期还会做"孤儿 schema"检查：集中规则里出现但没有任何业务路由对应的方法会在 `createApplication` 阶段直接抛错，避免"定义却未使用"的死代码。
+
+### 认证与授权
+
+`ServerExtension.auth` 是可选的 `AuthAdapter`：
+
+```typescript
+interface AuthAdapter {
+  challenge?: string; // 401 响应的 WWW-Authenticate 头
+  authenticate(ctx): AuthIdentity | null | Promise<AuthIdentity | null>;
+  authorize(ctx, access, identity): boolean | Promise<boolean>;
+}
+```
+
+框架在以下四层做授权判定：
+
+1. **路由级 access**：在 `RouteDefinition.access` 或 `RouteDefinition.projectRequired` 中声明；命中失败直接 403/400；
+2. **模块级 access**：业务路由按"`{ module: <routePath>, action: <method> }`"调用 `authorize`；
+3. **项目级 access**：内部路由 `/api/project/*`、菜单可见性、项目详情都通过 `isProjectAllowed` 判定；
+4. **静态资源 access**：`public` 目录下的含扩展名静态资源也会经过 `module=public, action=read` 的授权。
+
+`devAnonymous` 字段：
+
+- 仅在非生产（`development` / `test`）生效；
+- 必须显式开启（`!auth && !devAnonymous` 时 `createApplication` 直接抛错，防止"忘记关"导致开发配置漏到测试）；
+- 启用时 `validateListen` 会强制 host 必须是回环地址（`127.0.0.1 / localhost / ::1`）。
+
+### `BaseService` / `BaseController`
+
+```typescript
+class ProductService extends BaseService {
+  async list(query: { id: string }) {
+    return this.app.service.otherService.someMethod(query);
+  }
+}
+
+class ProductController extends BaseController {
+  async list(ctx) {
+    try {
+      const data = await this.app.service.product.list(ctx.query);
+      this.success(ctx, data);
+    } catch (error) {
+      this.fail(ctx, error.message, 500);
+    }
+  }
+}
+```
+
+`BaseController.success(ctx, data, metadata?)` 与 `BaseController.fail(ctx, message, code?, errors?)` 输出统一的 `{ success, data/code/message, metadata?/errors? }` 协议，便于前端统一处理。
+
+### 静态资源与 History 兜底
+
+- `/api/*` 路径永远不会被静态文件劫持；
+- 含扩展名的静态业务资源也走授权（`module=public, action=read`）；
+- 无扩展名的路径会落到框架内置 HTML 模板（History 兜底）：`/project-list`、`/dashboard*`、`/error`；
+- `custom` 模块还支持"短链重定向"：直接访问原始 `moduleConfig.path` 时，框架自动重定向到带 `projectKey/key/siderKey` query 的 dashboard 形式。
+
+### 路由定义示例（声明式）
+
+```typescript
+// server/router/product.ts
+import { defineRoutes } from '@ynight/framework';
+
+export default defineRoutes(app => [
+  {
+    method: 'GET',
+    path: '/api/product',
+    projectRequired: true,
+    access: { module: '/api/product', action: 'read' },
+    schema: {
+      query: {
+        type: 'object',
+        properties: { page: { type: 'integer', minimum: 1 } },
+        required: ['page'],
+      },
+    },
+    handler(ctx) {
+      return app.service.product.list(ctx.query);
+    },
+  },
+]);
+```
+
+### 路由定义示例（Proxy 模式）
+
+```typescript
+// server/router/order.ts
+export default (app, router) => {
+  router.get('/api/order', async ctx => {
+    ctx.body = { success: true, data: await app.service.order.list(ctx.query) };
+  });
+
+  router.post('/api/order', async ctx => {
+    ctx.body = { success: true, data: await app.service.order.create(ctx.request.body) };
+  });
+};
+```
+
+---
+
+## 模型 / 菜单 DSL（`@ynight/framework/model`）
+
+模型入口只导出 DSL、查询工具与 DTO 类型，避免业务侧误用到服务端装配 API。模块入口：
+
+```typescript
+export * from './model/index';
+```
+
+`src/model/index.ts` 主要导出：
+
+- **工厂函数**：`defineModel`、`defineControlContracts`、`custom`、`iframe`、`group`、`sider`、`schema`；
+- **透传自 `@ynight/contracts` 的工具与常量**：`EventKey`、`MenuType`、`ModuleType`、`SchemaComponentName`、`SchemaFormControlType`、`transQueryToString`；
+- **类型**：`BusinessControls`、`IModel`、`MenuItemType`、`ModuleItem`、`SiderModuleConfig`、`PathModuleConfig`、`ButtonConfig`、`TableColumnConfig`、`CreateFormConfig`、`UpdateFormConfig`、`DetailViewConfig`、`SchemaProperty`、`SchemaModuleConfig`、`SchemaFormFieldConfig`、`DynamicSelectConfig`、`AsyncSearchSelectConfig`、`TagInputConfig`、`ChoiceOption`、`CascaderOption`、`ProjectDto`、`ModelDto` 等。
+
+### `defineModel`
+
+```typescript
+import { defineModel, schema } from '@ynight/framework/model';
+
+export default defineModel({
+  key: 'admin',
+  name: '管理后台',
+  desc: '示例模型',
+  project: {
+    'demo-project': {
+      key: 'demo-project',
+      name: '示例项目',
+      desc: '示例项目',
+      homePage: '/dashboard',
+      menu: [
+        schema('user-list', '用户列表', {
+          api: '/api/user',
+          schema: { type: 'object', properties: { id: { type: 'string' } } },
+          tableConfig: { ... },
+          searchConfig: { ... },
+          components: { CreateForm: {...}, UpdateForm: {...}, DetailView: {...} },
+        }),
+      ],
+    },
+  },
+});
+```
+
+`defineModel` 仅做类型断言（identity），让业务侧在写模型字面量时获得完整字段补全；通过可选的 `__controls` 把业务自定义控件类型透传给后续钩子，配合 `defineControlContracts` 可以让 `schema` 字段中的 `control` 类型受 `IModel` 推断约束。
+
+### `defineControlContracts`
+
+```typescript
+import { defineControlContracts } from '@ynight/framework/model';
+
+export default defineControlContracts({
+  AsyncSearchSelect: {
+    propsSchema: {
+      type: 'object',
+      properties: { api: { type: 'string' } },
+      required: ['api'],
+    },
+  },
+  TagInput: {
+    propsSchema: {
+      type: 'object',
+      properties: { max: { type: 'integer', minimum: 1 } },
+    },
+  },
+});
+```
+
+控件契约通过 `model.controlContracts` 索引文件路径注入到 `createApplication`；模型装载阶段会使用 Ajv 对每个控件实例的 `component.config.props` 进行校验。
+
+### 菜单工厂
+
+| 工厂                              | 说明                                                                |
+| --------------------------------- | ------------------------------------------------------------------- |
+| `custom(key, name, path)`         | 声明一个"自定义模块"菜单项（业务方提供独立路由 + 页面，跨项目通用） |
+| `iframe(key, name, path)`         | 声明 iframe 模块菜单项（path 为第三方页面 URL）                     |
+| `group(key, name, subMenu)`       | 侧边栏分组（子菜单为空时整组不渲染）                                |
+| `sider(key, name, menu)`          | 侧边栏容器（自身对应一个可访问的页面）                              |
+| `schema(key, name, moduleConfig)` | schema 驱动的表格式 CRUD 页面                                       |
+
+每种菜单对应 `moduleType` 之一（`custom` / `iframe` / `sider` / `schema`），由前端 dashboard 据此渲染。
+
+---
+
+## 客户端（`@ynight/framework/client`）
+
+内置后台客户端基于 Vue 3 + Pinia + Vue Router 4 + Element Plus。模块入口 `src/client/index.ts` 统一对外暴露：
+
+- **入口 API**：`createAdminApp(options)`、`defineClientExtensions(setup)`；
+- **运行时**：`useElpisContext()`（组件内获取上下文）、`createClientContext`、`installClientContext`；
+- **核心组件**：`SchemaForm`、`SchemaTable`（DSL 驱动的表单 / 表格）；
+- **默认壳层**：`DefaultProjectListPage`、`DefaultDashboardPage`（可通过 `extensions.shell` 整体替换）；
+- **schema 工具**：`resolveSchemaOptions`、`buildSchemaViewData`、`validateControlReferences`、`resolveMenuPath`、`findMenuTrail`、`findMenu`、`firstModule`、`SchemaViewDataInjectKey`；
+- **通用工具**：`createLogger(scope)`、`measureButtonWidth(label)`；
+- **类型**：`AdminAppRuntime`、`ApiResult`、`ClientExtensions`、`ControlRegistration`、`CreateAdminAppOptions`、`ElpisClientContext`、`FormValue(s)`、`RequestAdapter`、`RequestAdapterOption`、`ShellExtensions`、`ViewField`、`ViewSchema`、`SchemaFormProps`、`SchemaFormExposed`、`SchemaFormValidationFailedPayload`、`SchemaFormSchema`、`TableSchema`、`DtoSchema`、`DtoSchemaProperty`、`AjvFieldError`、以及 contracts 中的 `IModel`、`MenuItemType`、`ModelDto`、`ProjectDto`。
+
+### `createAdminApp(options)`
+
+```typescript
+import { createAdminApp, defineClientExtensions } from '@ynight/framework/client';
+
+const runtime = await createAdminApp({
+  page: 'project-list',
+  mount: '#root',
+  // base: '/project-list',  // 默认等于 /<page>
+  config: {
+    /* 任意启动配置键值对 */
+  },
+  extensions: defineClientExtensions({
+    controls: {
+      AsyncSearchSelect: { component: AsyncSearchSelectImpl },
+      TagInput: { component: TagInputImpl },
+    },
+    shell: {
+      projectList: MyProjectList,
+      dashboard: MyDashboard, // 内部需含 <router-view />
+    },
+  }),
+  requestAdapter: async (input, init) => fetch(input, init), // 可选
+});
+
+// runtime.app / runtime.router / runtime.pinia / runtime.context / runtime.mounted
+```
+
+装配流程：
+
+1. 构造 vue-router（HTML5 history 模式），按 `page` 生成对应路由；
+2. 创建 Pinia 状态管理实例；
+3. 注册 Element Plus → Pinia → Router 到 Vue 应用；
+4. 通过 `installClientContext` 把 `ElpisClientContext` 注入到应用，业务组件可用 `useElpisContext()` 拿到；
+5. 等 router 首次解析完成后挂载到 DOM（避免首屏空白竞态）。
+
+返回的 `AdminAppRuntime`：
+
+| 字段      | 类型                 | 说明                                |
+| --------- | -------------------- | ----------------------------------- |
+| `app`     | `App`                | Vue 应用实例                        |
+| `router`  | `Router`             | vue-router 实例                     |
+| `pinia`   | `Pinia`              | Pinia 实例                          |
+| `context` | `ElpisClientContext` | 客户端上下文                        |
+| `mounted` | `Promise<App>`       | router 就绪并完成首次挂载的 Promise |
+
+### 客户端上下文（`ElpisClientContext`）
+
+通过 `useElpisContext()` 获取，包含：
+
+- `projectKey: ComputedRef<string | undefined>`——当前项目 key（URL query 优先）；
+- `currentProject: Ref<ProjectDto | undefined>`、`currentModel: Ref<IModel | undefined>`、`projectList: Ref<ProjectDto[]>`、`modelList: Ref<ModelDto[]>`、`user: Ref<... | null>`；
+- `config: Readonly<Record<string, unknown>>`——启动配置；
+- `requestAdapter: RequestAdapter`——生效的请求适配器；
+- `request<T>(input, init?): Promise<ApiResult<T>>`——通用请求方法，自动对同源 `/api/` 注入 `projectKey`（query + header），自动解析 `{ success, data, message, metadata }` 响应；
+- `setProject(project)`——切换当前项目。
+
+业务侧可传入自定义 `RequestAdapter`（函数或 `{ request }` 对象），用于 Mock / 统一前缀 / 鉴权注入等场景。
+
+### `defineClientExtensions(setup)`
+
+类型断言助手，仅做类型层面穿透，让业务侧在书写 extensions 配置时获得完整的 TypeScript 类型推断（如自定义控件名对应的 component 类型），运行时不产生任何额外开销。
+
+### 内置组件
+
+- **`SchemaForm`**（`src/widgets/schema-form/index.vue`）——DSL 驱动的表单，基于 `el-form` 的表单校验管控 + AJV 的表单校验；
+- **`SchemaTable`**（`src/widgets/schema-table/index.vue`）——DSL 驱动的表格；
+- **默认壳层**：`ProjectListPage`、`DashboardPage`、`ErrorPage`、`PageSkeleton`、`ModuleHost`、`SchemaView`；
+- **complex-view 自定义控件**：`async-search-select`、`dynamic-select`、`tag-input`、`upload` 等。
+
+### DSL 解析
+
+- **`resolveSchemaOptions(property)`**：从 JSON Schema 的 `oneOf` / `items.oneOf` 中提取 `{label, value}[]`，用于 Select / SelectV2 / RadioGroup / CheckboxGroup / Segmented 等枚举类控件；
+- **`createViewSchema(schema, getOption, inheritRequired?)`**：合并 option + required + 注入 options，产出渲染所需的 `ViewSchema`；
+- **`buildSchemaViewData(menu, extensions)`**：装配表格 / 搜索表单 / CreateForm / UpdateForm / DetailView 的视图数据；同时校验 `extensions.controls` 是否注册了 schema 字段引用的自定义控件；
+- **`validateControlReferences(module, extensions)`**：校验 `search / CreateForm / UpdateForm / DetailView` 四场景的 `option.comType`，Element Plus 内置控件直接放行；
+- **`resolveMenuPath(menu)`**：根据菜单项返回 dashboard 路由 path（custom / iframe / schema / sider / group 各自规则）；
+- **`findMenuTrail(menus, matches)`**：在菜单树中查找所有满足 matches 的菜单，并保留分组 / 侧栏祖先；
+- **`findMenu(menus, key)`**：按 key 精确查找（递归分组与侧栏）；
+- **`firstModule(menus)`**：返回菜单树中的第一个 module（深度优先）。
+
+### 通用工具
+
+- **`createLogger(scope)`**——轻量日志器（debug/warn/error，自动加 `[scope]` 前缀）；
+- **`measureButtonWidth(label)`**——按字符估算按钮宽度（CJK 14px、其它 7px、padding 16px）；
+- **`SchemaViewDataInjectKey`**——Vue `provide/inject` 注入键（类型 `SchemaViewData`），由 schema 视图容器提供。
+
+---
+
+## 静态资源（`@ynight/framework/assets`）
+
+`src/assets/index.ts` 提供框架内置后台的 HTML 模板定位与读取能力，模板由 CLI 在构建阶段生成到 `assets/` 目录下。
+
+```typescript
+export const frameworkPageNames = ['project-list', 'dashboard', 'error'] as const;
+export type FrameworkPageName = (typeof frameworkPageNames)[number];
+
+export const frameworkAssetsRoot = path.resolve(__dirname, '../../assets');
+
+export function frameworkPagePath(publicRoot: string, page: FrameworkPageName): string;
+export function readFrameworkPage(publicRoot: string, page: FrameworkPageName): string;
+```
+
+- `frameworkPageNames`——约束合法的框架页面名称；
+- `frameworkAssetsRoot`——框架内置资源根目录的绝对路径；
+- `frameworkPagePath(publicRoot, page)`——根据公共资源根与页面名解析模板绝对路径；
+- `readFrameworkPage(publicRoot, page)`——读取模板 HTML；模板不存在抛 `ELPIS_PUBLIC_TEMPLATE_MISSING`，模板缺少 `#root` 挂载节点抛 `ELPIS_PUBLIC_TEMPLATE_INVALID`。
+
+服务端装配阶段会预热三个页面（`createApplication` 第 2 步），确保 History 兜底能同步响应 HTML。
+
+---
+
+## 安全与配置约束
+
+`createApplication` / `resolveConfig` 在多个层面保证配置安全：
+
+- **强制认证**：生产模式（`mode === 'production'`）必须有 `serverExtension.auth`，否则抛 `ELPIS_AUTH_REQUIRED`；
+- **devAnonymous 显式**：非生产模式下若没有 auth，必须显式设置 `devAnonymous: true`，否则同样抛 `ELPIS_AUTH_REQUIRED`；
+- **回环地址护栏**：devAnonymous 仅允许监听回环地址（`127.0.0.1 / localhost / ::1 / 0:0:0:0:0:0:0:1`），由 `validateListen` 钩子在 `createApplicationContainer` 中保证；
+- **路径安全**：所有生成路径（`generatedRoot / compiledRoot / outputRoot / serverRoot / modelRoot / sharedRoot / publicRoot`）必须位于 `sourceRoot` 内，防御目录穿越（`..`、绝对路径）与 symlink 逃逸（`realpath` 逐段校验）；
+- **输出目录安全**：`build.outDir`（`outputRoot`）额外禁止覆盖 `node_modules / server / model / .git` 等受保护目录；
+- **配置字段白名单**：`ElpisConfig` 顶级字段限定为 `server / model / client / public / dev / build`，其它字段启动期报错；
+- **路由 schema 完整性**：启动期校验集中 schema 不存在"孤儿"，避免定义却未使用；
+- **业务路由冲突**：业务路由若与框架内置路由（`/api/session` / `/api/project/*`）同名/同方法立即抛错；
+- **history 兜底**：模板缺失抛 `ELPIS_PUBLIC_TEMPLATE_MISSING`，缺少 `#root` 节点抛 `ELPIS_PUBLIC_TEMPLATE_INVALID`；
+- **site 模板**：模型中声明 `mode === 'site'` 时启动期直接拒止（`ELPIS_UNSUPPORTED_TEMPLATE`，尚未实现）。
+
+---
+
+## 相关包
+
+- **`@ynight/core`**——底层引擎（Koa 应用容器、模块加载、应用生命周期）；
+- **`@ynight/contracts`**——DSL 类型契约（菜单 / 模块 / 控件 / DTO 等），被 `@ynight/framework/model` 透传；
+- **`@ynight/model-runtime`**——模型加载与校验运行时（`loadModels` / `validateModels` / 控件契约）；
+- **`@ynight/cli`**——工程脚手架与开发命令（生成 elpis.config / 编译业务模块 / 启动 dev / build）。
+
+---
+
+## 引擎要求
+
+```
+node >=22.0.0
+```
+
+---
+
+## 许可证
+
+MIT