@ynight/framework 0.0.0-stage → 0.0.1

package/dist/server/application.js

@@ -0,0 +1,1082 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApplication = createApplication;
+exports.startApplication = startApplication;
+const tslib_1 = require("tslib");
+const node_fs_1 = tslib_1.__importDefault(require("node:fs"));
+const node_path_1 = tslib_1.__importDefault(require("node:path"));
+const router_1 = tslib_1.__importDefault(require("@koa/router"));
+const koa_bodyparser_1 = tslib_1.__importDefault(require("koa-bodyparser"));
+const koa_static_1 = tslib_1.__importDefault(require("koa-static"));
+const ajv_1 = tslib_1.__importDefault(require("ajv"));
+const ajv_formats_1 = tslib_1.__importDefault(require("ajv-formats"));
+const core_1 = require("@ynight/core");
+const model_runtime_1 = require("@ynight/model-runtime");
+const assets_1 = require("../assets");
+const define_routes_1 = require("./define-routes");
+const config_1 = require("./config");
+/**
+ * 加载业务 middleware 目录下所有模块。
+ *
+ * 文件必须默认导出一个工厂函数 `export default (app) => Middleware`：
+ * 1. 工厂在装配阶段被调用，接收 FrameworkApplication 实例；
+ * 2. 返回的中间件按文件遍历顺序注册到 app.use()，因此"先注册先执行"；
+ * 3. 工厂返回值不是函数时抛出明确错误，避免被静默忽略。
+ */
+function loadMiddlewares(root, extension, app) {
+    (0, core_1.listModuleFiles)(root, extension).forEach(filePath => {
+        const factory = (0, core_1.readModule)(filePath);
+        if (typeof factory !== 'function') {
+            throw new Error(`业务中间件必须导出函数: ${filePath}`);
+        }
+        const middleware = factory(app);
+        if (typeof middleware !== 'function') {
+            throw new Error(`业务中间件工厂必须返回 Koa 中间件: ${filePath}`);
+        }
+        app.use(middleware);
+    });
+}
+/**
+ * 从 server/router-schema 目录加载集中维护的请求参数校验规则。
+ *
+ * 文件结构示例：
+ * ```ts
+ * export default {
+ *   '/api/product': {
+ *     get: { query: { type: 'object', properties: { id: { type: 'string' } } } },
+ *     post: { body: { ... } },
+ *   },
+ *   '/api/order/:id': { get: { params: { ... } } },
+ * };
+ * ```
+ *
+ * 校验规则：
+ * - 路径必须以 / 开头
+ * - 方法必须属于 HTTP 动词集合（大小写不敏感）
+ * - 值必须是对象或布尔（兼容 Ajv 的 boolean schema）
+ * - 同一路由同一方法重复声明直接报错（避免后写覆盖前写造成调试困惑）
+ */
+function loadRouterSchemas(root, extension) {
+    const result = {};
+    (0, core_1.listModuleFiles)(root, extension).forEach(filePath => {
+        const value = (0, core_1.readModule)(filePath);
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            throw new Error(`路由校验规则必须导出对象: ${filePath}`);
+        }
+        Object.entries(value).forEach(([routePath, methods]) => {
+            if (!routePath.startsWith('/') || !methods || typeof methods !== 'object') {
+                throw new Error(`路由校验规则路径无效: ${filePath} -> ${routePath}`);
+            }
+            const current = result[routePath] ?? {};
+            Object.entries(methods).forEach(([method, schema]) => {
+                if (!/^(get|post|put|patch|delete|head)$/i.test(method)) {
+                    throw new Error(`路由校验规则方法无效: ${filePath} -> ${method}`);
+                }
+                if (schema === null ||
+                    (typeof schema !== 'object' && typeof schema !== 'boolean') ||
+                    (typeof schema === 'object' && Array.isArray(schema))) {
+                    throw new Error(`路由校验规则必须是对象: ${filePath} -> ${routePath}.${method}`);
+                }
+                const normalizedMethod = method.toLowerCase();
+                if (normalizedMethod in current) {
+                    throw new Error(`路由校验规则重复: ${filePath} -> ${routePath}.${method}`);
+                }
+                current[normalizedMethod] = schema;
+            });
+            result[routePath] = current;
+        });
+    });
+    return result;
+}
+/**
+ * 将 Ajv 的 ErrorObject 转换为人类可读的位置描述。
+ *
+ * - `required` 错误：追加缺失字段名
+ * - `additionalProperties` 错误：追加多余字段名
+ * - `instancePath`（JSON Pointer）转回点分路径，并对数字段使用 `[idx]` 表示
+ * - 输出格式：`{configPath}.{instancePath}.{property} [keyword] message`
+ *
+ * 主要供开发期日志与 400 响应体 message 字段使用。
+ */
+function formatAjvError(error, configPath) {
+    const property = error.keyword === 'required'
+        ? error.params.missingProperty
+        : error.keyword === 'additionalProperties'
+            ? error.params.additionalProperty
+            : undefined;
+    const suffix = typeof property === 'string' ? `.${property}` : '';
+    const instancePath = error.instancePath
+        .split('/')
+        .slice(1)
+        // Ajv 使用 JSON Pointer（RFC 6901）：~1 → /、~0 → ~，需还原字面字符
+        .map(segment => segment.replaceAll('~1', '/').replaceAll('~0', '~'))
+        // 数组下标用 [i] 形式，对象键用 .key 形式
+        .map(segment => (/^\d+$/.test(segment) ? `[${segment}]` : `.${segment}`))
+        .join('');
+    return `${configPath}${instancePath}${suffix} [${error.keyword}] ${error.message ?? '校验失败'}`;
+}
+/**
+ * 创建专用于请求参数校验的 Ajv 实例。
+ *
+ * - allErrors：收集所有错误而非遇到第一个就返回，方便前端一次性提示
+ * - coerceTypes：自动将 query/path 中的字符串转成 number/boolean，减少业务侧样板代码
+ * - strict：严格模式，避免"未知关键字"被静默忽略
+ *
+ * addFormats 注入 format（date / uri / email 等）的标准校验能力。
+ */
+function createRequestSchemaCompiler() {
+    const ajv = new ajv_1.default({ allErrors: true, coerceTypes: true, strict: true });
+    (0, ajv_formats_1.default)(ajv);
+    return ajv;
+}
+/**
+ * 将单条路由的请求校验规则编译为 Ajv 校验函数。
+ *
+ * - 仅支持 body/query/params/headers 四类位置；其它键直接抛错（早期失败优于静默忽略）
+ * - 任意 schema 编译失败抛错，附带 configPath 与 Ajv 原消息（cause 链保留原始异常）
+ * - 全部未声明时返回 undefined，调用方按"无校验"处理
+ */
+function compileRequestSchemas(schemas, configPath, ajv) {
+    if (!schemas) {
+        return undefined;
+    }
+    if (!schemas || typeof schemas !== 'object' || Array.isArray(schemas)) {
+        throw new Error(`路由校验规则 ${configPath} 必须是对象`);
+    }
+    const supportedParts = new Set(['body', 'query', 'params', 'headers']);
+    for (const part of Object.keys(schemas)) {
+        if (!supportedParts.has(part)) {
+            throw new Error(`路由校验规则 ${configPath} 包含未知参数位置: ${part}`);
+        }
+    }
+    const result = {};
+    for (const part of ['body', 'query', 'params', 'headers']) {
+        const schema = schemas[part];
+        if (schema === undefined) {
+            continue;
+        }
+        try {
+            result[part] = ajv.compile(schema);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`路由校验规则 ${configPath}.${part} 无效: ${message}`, { cause: error });
+        }
+    }
+    return result;
+}
+/**
+ * 批量编译 router-schema 目录下所有规则。
+ * 返回值结构与 RouterSchemas 一致，但每个值已被替换为 CompiledRequestSchemas。
+ */
+function compileRouterSchemas(schemas, ajv) {
+    const result = {};
+    for (const [routePath, methods] of Object.entries(schemas)) {
+        result[routePath] = {};
+        for (const [method, requestSchemas] of Object.entries(methods)) {
+            result[routePath][method] =
+                compileRequestSchemas(requestSchemas, `${method.toUpperCase()} ${routePath}`, ajv) ?? {};
+        }
+    }
+    return result;
+}
+/**
+ * 从请求中提取 projectKey 并写入 ctx.state.projectKey。
+ * 优先顺序：自定义头 `projectKey` > query `projectKey`。
+ *
+ * 返回值：最终使用的 projectKey（可能为 undefined），便于调用方判断"是否需要中断请求"。
+ */
+function attachProject(ctx) {
+    const fromHeader = ctx.get('projectKey');
+    const fromQuery = ctx.query.projectKey;
+    const value = fromHeader || (typeof fromQuery === 'string' ? fromQuery : undefined);
+    if (value) {
+        ctx.state.projectKey = value;
+    }
+    return value;
+}
+/**
+ * 把已加载模型展开为"扁平的项目列表"，便于统一做授权与返回数据组装。
+ * 每个条目包含：项目 key、项目内容（IModel）、所属 model 的 key。
+ */
+function allProjects(models) {
+    return models.flatMap(item => Object.entries(item.project).map(([key, project]) => ({ key, project, modelKey: item.key })));
+}
+/**
+ * 构造对外公开的项目 DTO：
+ * - 去掉内部私有字段（如 model 内部标记）
+ * - 补充 modelKey（前端 dashboard 据此选择模型运行时）
+ * - homePage 缺省时补空串，避免 undefined 进入 JSON 序列化
+ */
+function publicProject(modelKey, key, project) {
+    return {
+        key,
+        name: project.name,
+        desc: project.desc,
+        homePage: project.homePage ?? '',
+        modelKey,
+    };
+}
+/**
+ * 将 AuthIdentity 投影为对外可见的安全字段。
+ * 仅暴露 id 与可选 name，其它业务字段（如角色、token）不会进入 API 响应。
+ */
+function publicIdentity(identity) {
+    if (!identity) {
+        return null;
+    }
+    return { id: identity.id, ...(identity.name === undefined ? {} : { name: identity.name }) };
+}
+/**
+ * 判定当前用户是否对指定 projectKey 具备访问权限。
+ *
+ * 关键细节：
+ * 1. 未配置 AuthAdapter 时直接放行（保留最小可用状态，便于早期原型）
+ * 2. 无身份时拒绝访问（即便 devAnonymous 模式也不应绕过项目级授权）
+ * 3. 调用 authorize 前临时写入 projectKey，使适配器可以基于项目决策；
+ *    调用结束（finally）后恢复原值，避免污染后续请求
+ * 4. 默认 access 为 `module='project', action='read'`，与路由注册处的语义对齐
+ */
+async function isProjectAllowed(ctx, app, projectKey, access = { module: 'project', action: 'read' }) {
+    if (!app.serverExtension.auth) {
+        return true;
+    }
+    const identity = ctx.state.user;
+    if (!identity) {
+        return false;
+    }
+    const previous = ctx.state.projectKey;
+    ctx.state.projectKey = projectKey;
+    try {
+        return await app.serverExtension.auth.authorize(ctx, access, identity);
+    }
+    finally {
+        if (previous === undefined) {
+            delete ctx.state.projectKey;
+        }
+        else {
+            ctx.state.projectKey = previous;
+        }
+    }
+}
+/**
+ * 过滤当前用户实际可见的项目列表。
+ * - 可按 modelKey 缩小范围（用于 /api/project/list?modelKey=xxx）
+ * - 项目级权限失败的项目直接丢弃
+ */
+async function visibleProjects(ctx, app, models, modelKey) {
+    const result = [];
+    for (const item of allProjects(models)) {
+        if (modelKey && item.modelKey !== modelKey) {
+            continue;
+        }
+        if (await isProjectAllowed(ctx, app, item.key)) {
+            result.push(item);
+        }
+    }
+    return result;
+}
+/**
+ * 构造 `/api/project/model_list` 的响应：每个模型 + 其下当前用户可见的项目列表。
+ * - 没有任何可见项目的模型会被过滤掉，避免暴露空模型
+ */
+async function publicModels(ctx, app, models) {
+    const projects = await visibleProjects(ctx, app, models);
+    return models
+        .map(item => ({
+        key: item.key,
+        name: item.model.name,
+        desc: item.model.desc,
+        project: projects
+            .filter(project => project.modelKey === item.key)
+            .map(project => publicProject(item.key, project.key, project.project)),
+    }))
+        .filter(item => item.project.length > 0);
+}
+/**
+ * 在全部项目中按字符串精确匹配查找。
+ * 命中失败返回 undefined，由调用方决定 404 行为。
+ */
+function findProject(models, projectKey) {
+    return allProjects(models).find(item => item.key === projectKey);
+}
+/**
+ * 模块可见性判定。
+ * - 未配置 AuthAdapter 时一律放行
+ * - 传入模块 key（通常为路由路径），动作固定为 read
+ */
+async function isModuleAllowed(ctx, app, moduleKey) {
+    if (!app.serverExtension.auth) {
+        return true;
+    }
+    const identity = ctx.state.user;
+    return Boolean(identity &&
+        (await app.serverExtension.auth.authorize(ctx, { module: moduleKey, action: 'read' }, identity)));
+}
+/**
+ * 对菜单进行授权过滤，仅保留当前用户可见的项。
+ *
+ * 递归规则：
+ * - group：递归子菜单，过滤后若空则丢弃整个分组
+ * - sider（侧边栏容器）：递归内部 menu，过滤后若空则保留空容器（避免结构破坏）
+ * - 其它 module：按 key 做 read 权限判定
+ */
+async function visibleMenu(ctx, app, menu) {
+    const result = [];
+    for (const item of menu) {
+        if (!(await isModuleAllowed(ctx, app, item.key))) {
+            continue;
+        }
+        if (item.menuType === 'group') {
+            const subMenu = await visibleMenu(ctx, app, item.subMenu);
+            if (subMenu.length > 0) {
+                result.push({ ...item, subMenu });
+            }
+        }
+        else if (item.moduleType === 'sider') {
+            const subMenu = await visibleMenu(ctx, app, item.moduleConfig.menu);
+            if (subMenu.length > 0) {
+                result.push({ ...item, moduleConfig: { ...item.moduleConfig, menu: subMenu } });
+            }
+        }
+        else {
+            result.push(item);
+        }
+    }
+    return result;
+}
+/**
+ * 返回对外可见的项目详情（含菜单授权过滤结果）。
+ *
+ * 同样采用"临时覆盖 → 调用 → finally 还原"的模式，与 isProjectAllowed 保持一致，
+ * 避免授权适配器读到的 ctx.state.projectKey 与调用方预期不符。
+ */
+async function publicProjectDetail(ctx, app, projectKey, project) {
+    const previous = ctx.state.projectKey;
+    ctx.state.projectKey = projectKey;
+    try {
+        return { ...project, menu: await visibleMenu(ctx, app, project.menu) };
+    }
+    finally {
+        if (previous === undefined) {
+            delete ctx.state.projectKey;
+        }
+        else {
+            ctx.state.projectKey = previous;
+        }
+    }
+}
+/**
+ * 构造请求参数校验中间件。
+ *
+ * - 按 body → query → params → headers 顺序校验，任一失败立即返回 400
+ * - 错误信息包含 Ajv 的所有错误（每条按 formatAjvError 格式化）
+ * - 校验成功或未声明时透传到下游（即 next()）
+ */
+function requestSchemaMiddleware(schema) {
+    return async (ctx, next) => {
+        if (schema) {
+            for (const part of ['body', 'query', 'params', 'headers']) {
+                const validate = schema[part];
+                if (!validate) {
+                    continue;
+                }
+                const value = part === 'body'
+                    ? ctx.request.body
+                    : part === 'query'
+                        ? ctx.query
+                        : part === 'params'
+                            ? ctx.params
+                            : ctx.headers;
+                if (!validate(value)) {
+                    const details = (validate.errors ?? [])
+                        .map(error => formatAjvError(error, part))
+                        .join('; ');
+                    ctx.status = 400;
+                    ctx.body = {
+                        success: false,
+                        code: 400,
+                        message: `参数校验失败: ${details || part}`,
+                        errors: validate.errors,
+                    };
+                    return;
+                }
+            }
+        }
+        await next();
+    };
+}
+/**
+ * 把单个 RouteDefinition 注册到 @koa/router 实例上。
+ *
+ * 装配顺序（从外到内）：
+ *   1. accessMiddleware：
+ *      - projectRequired 时强制要求 projectKey，缺失返回 400
+ *      - 路由级 access 鉴权，失败返回 403
+ *   2. requestSchemaMiddleware：参数校验（内联 > 集中）
+ *   3. handler：业务处理函数
+ *
+ * 路由 ID（method + path）必须唯一，重复注册立即抛错。
+ */
+function registerRoute(router, route, app, schemas, registered, ajv) {
+    const method = route.method.toLowerCase();
+    if (!route.path.startsWith('/')) {
+        throw new Error(`路由路径必须以 / 开头: ${route.path}`);
+    }
+    const routeId = `${method} ${route.path}`;
+    if (registered.has(routeId)) {
+        throw new Error(`路由重复注册: ${routeId}`);
+    }
+    registered.add(routeId);
+    const accessMiddleware = async (ctx, next) => {
+        if (route.projectRequired && !attachProject(ctx)) {
+            ctx.status = 400;
+            ctx.body = { success: false, code: 400, message: '缺少 projectKey' };
+            return;
+        }
+        if (route.access && app.serverExtension.auth) {
+            const identity = ctx.state.user;
+            if (!identity || !(await app.serverExtension.auth.authorize(ctx, route.access, identity))) {
+                ctx.status = 403;
+                ctx.body = { success: false, code: 403, message: '无权访问当前资源' };
+                return;
+            }
+        }
+        await next();
+    };
+    const inlineSchemas = compileRequestSchemas(route.schema, `${route.method} ${route.path}`, ajv);
+    const compiledSchemas = inlineSchemas ?? schemas[route.path]?.[method];
+    router[method](route.path, accessMiddleware, requestSchemaMiddleware(compiledSchemas), async (ctx) => route.handler(ctx));
+}
+/**
+ * 注册业务 router 目录下的所有路由。
+ *
+ * 该函数通过 Proxy 拦截 router.get/post/... 方法，在原有 Router 之上包裹一层：
+ *   - attachProject：把 projectKey 写入 ctx.state，便于后续授权/业务使用
+ *   - 模块级鉴权：未配置 AuthAdapter 时放行，否则按"路由路径 + 方法"判定
+ *   - 参数校验：自动应用 router-schema 目录下的集中规则
+ *
+ * 同时提供 reserve 机制：
+ * - reserved 用于记录框架内置路由；业务路由与之冲突直接报错
+ * - registered 跟踪已注册路由（含内置 + 业务），重复声明抛错
+ *
+ * 业务侧有两种声明方式：
+ *   1. `export default (app, router) => { router.get('/x', handler) }`（推荐，Proxy 模式）
+ *   2. `export default (app) => [{ method, path, handler, ... }]`（声明式，经 registerRoute）
+ */
+function registerBusinessRoutes(router, root, extension, app, schemas, registered, reserved, ajv) {
+    const methods = new Set(['get', 'post', 'put', 'patch', 'delete', 'head']);
+    const businessRouter = new Proxy(router, {
+        get(target, property, receiver) {
+            if (typeof property === 'string' && methods.has(property)) {
+                return (routePath, ...handlers) => {
+                    const routeId = `${property} ${routePath}`;
+                    if (reserved.has(routeId) || registered.has(routeId)) {
+                        throw new Error(`业务路由与框架路由冲突: ${routeId}`);
+                    }
+                    if (!routePath.startsWith('/')) {
+                        throw new Error(`路由路径必须以 / 开头: ${routePath}`);
+                    }
+                    registered.add(routeId);
+                    const register = target[property];
+                    register.call(target, routePath, async (ctx, next) => {
+                        attachProject(ctx);
+                        if (app.serverExtension.auth) {
+                            const identity = ctx.state.user;
+                            if (!identity ||
+                                !(await app.serverExtension.auth.authorize(ctx, { module: routePath, action: property }, identity))) {
+                                ctx.status = 403;
+                                ctx.body = { success: false, code: 403, message: '无权访问当前资源' };
+                                return;
+                            }
+                        }
+                        await next();
+                    }, requestSchemaMiddleware(schemas[routePath]?.[property]), ...handlers);
+                    return target;
+                };
+            }
+            return Reflect.get(target, property, receiver);
+        },
+    });
+    (0, core_1.listModuleFiles)(root, extension).forEach(filePath => {
+        const exported = (0, core_1.readModule)(filePath);
+        if (typeof exported !== 'function') {
+            throw new Error(`业务路由必须导出函数: ${filePath}`);
+        }
+        const result = exported(app, businessRouter);
+        if ((0, define_routes_1.isRouteList)(result)) {
+            result.forEach(route => registerRoute(router, route, app, schemas, registered, ajv));
+        }
+        else if (result !== undefined && result !== router) {
+            throw new Error(`业务路由工厂返回了不支持的值: ${filePath}`);
+        }
+    });
+}
+/**
+ * 校验 router-schema 目录下的每条规则都对应了一个实际路由。
+ *
+ * 目的：避免"定义却未使用"的死代码——一旦路由被删除，集中校验规则极易被遗忘。
+ * 不通过则在启动期抛错，强制开发者清理或补齐路由。
+ */
+function assertNoOrphanSchemas(schemas, registered) {
+    Object.entries(schemas).forEach(([routePath, methods]) => Object.keys(methods).forEach(method => {
+        if (!registered.has(`${method.toLowerCase()} ${routePath}`)) {
+            throw new Error(`路由校验规则没有匹配的实际路由: ${method.toUpperCase()} ${routePath}`);
+        }
+    }));
+}
+/**
+ * 加载控件契约（controlContracts）索引文件。
+ * - 文件不存在时返回空对象（视为"无契约"）
+ * - 加载内容必须为对象，否则抛错
+ * - 抛错信息使用统一前缀 `ELPIS_CONTROL_CONTRACT_MISSING:` 便于上层聚合错误识别
+ */
+function loadControlContracts(filePath) {
+    if (!filePath) {
+        return {};
+    }
+    if (!node_fs_1.default.existsSync(filePath)) {
+        throw new Error(`ELPIS_CONTROL_CONTRACT_MISSING: 控件契约文件不存在: ${filePath}`);
+    }
+    const value = (0, core_1.readModule)(filePath);
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`控件契约必须导出对象: ${filePath}`);
+    }
+    return value;
+}
+/**
+ * 根据请求路径返回对应的框架内置页面名称。
+ *
+ * 映射规则：
+ * - `/error` → error
+ * - `/project-list` 或配置的 homePage（剥离 query） → project-list
+ * - dashboardBase 自身或以其开头的子路径（且不包含点号视为 HTML） → dashboard
+ *
+ * 返回 undefined 表示"不属于框架内置页面"，由调用方走 404 或自定义菜单重定向兜底。
+ */
+function pageForPath(config, requestPath) {
+    const dashboardBase = config.client.dashboardBase === '/' ? '' : config.client.dashboardBase;
+    if (requestPath === '/error') {
+        return 'error';
+    }
+    if (requestPath === '/project-list' || requestPath === config.public.homePage.split('?')[0]) {
+        return 'project-list';
+    }
+    if (requestPath === dashboardBase ||
+        (dashboardBase && requestPath.startsWith(`${dashboardBase}/`))) {
+        const rest = requestPath.slice(dashboardBase.length).replace(/^\/+/, '');
+        // 路径中存在点号视为静态资源，不返回框架页面
+        if (!rest || !rest.includes('.')) {
+            return 'dashboard';
+        }
+    }
+    return undefined;
+}
+/** 仅将显式接受 HTML 的浏览器导航视为页面请求，避免把通配资源请求当作页面兜底。 */
+function acceptsHtmlDocument(ctx) {
+    return ctx
+        .get('accept')
+        .split(',')
+        .some(mediaRange => {
+        const [mediaType, ...parameters] = mediaRange.trim().split(';');
+        if (!['text/html', 'application/xhtml+xml'].includes(mediaType?.toLowerCase() ?? '')) {
+            return false;
+        }
+        const quality = parameters.find(parameter => /^q\s*=/i.test(parameter.trim()));
+        return !quality || Number(quality.split('=')[1]) > 0;
+    });
+}
+/** API 前缀只包含 `/api` 本身和其子路径，避免误伤 `/apiary` 等普通页面。 */
+function isApiPath(requestPath) {
+    return requestPath === '/api' || requestPath.startsWith('/api/');
+}
+/** 检查请求路径是否对应 publicRoot 下的文件或静态目录首页。 */
+async function hasStaticFile(publicRoot, requestPath) {
+    let decodedPath;
+    try {
+        decodedPath = decodeURIComponent(requestPath);
+    }
+    catch {
+        return false;
+    }
+    const root = node_path_1.default.resolve(publicRoot);
+    const target = node_path_1.default.resolve(root, `.${decodedPath}`);
+    const relativePath = node_path_1.default.relative(root, target);
+    if (relativePath === '..' ||
+        relativePath.startsWith(`..${node_path_1.default.sep}`) ||
+        node_path_1.default.isAbsolute(relativePath)) {
+        return false;
+    }
+    try {
+        const targetStat = await node_fs_1.default.promises.stat(target);
+        if (targetStat.isFile()) {
+            return true;
+        }
+        if (targetStat.isDirectory()) {
+            return (await node_fs_1.default.promises.stat(node_path_1.default.join(target, 'index.html'))).isFile();
+        }
+    }
+    catch {
+        return false;
+    }
+    return false;
+}
+/**
+ * 在项目菜单树中递归查找匹配当前请求路径的自定义菜单项。
+ * - group：递归子菜单
+ * - sider：递归内部 menu，并把当前 sider.key 透传，便于后续路由参数化
+ * - custom：按 moduleConfig.path 精确匹配
+ * 匹配成功返回 CustomMenuMatch；未匹配返回 undefined。
+ */
+function findCustomMenu(menu, requestPath, siderKey) {
+    for (const item of menu) {
+        if (item.menuType === 'group') {
+            const nested = findCustomMenu(item.subMenu, requestPath, siderKey);
+            if (nested) {
+                return nested;
+            }
+            continue;
+        }
+        if (item.moduleType === 'sider') {
+            const nested = findCustomMenu(item.moduleConfig.menu, requestPath, siderKey ?? item.key);
+            if (nested) {
+                return nested;
+            }
+            continue;
+        }
+        if (item.moduleType === 'custom' && item.moduleConfig.path === requestPath) {
+            return siderKey ? { menu: item, siderKey } : { menu: item };
+        }
+    }
+    return undefined;
+}
+/**
+ * 处理 History 路由 + 自定义菜单的短链重定向：
+ * - 当用户直接访问一个 custom 菜单的原始 path 时，将其重定向到 dashboard 形式
+ *   （携带 projectKey/key/siderKey 等 query）
+ *
+ * 行为：
+ * 1. 按 requestedProjectKey 过滤候选项目；未提供时使用全部
+ * 2. 对每个候选项目，临时写入 ctx.state.projectKey 后再进行菜单授权/匹配
+ * 3. 唯一命中：构造带 query 的目标 URL 并 ctx.redirect
+ * 4. 多命中且未指定 projectKey：跳转回 /project-list 由用户选择
+ * 5. 其余情况返回 false，交给上游走 404 兜底
+ */
+async function redirectCustomPageShortcut(ctx, app, models) {
+    const requestedProjectKey = typeof ctx.query.projectKey === 'string' ? ctx.query.projectKey : undefined;
+    const projects = await visibleProjects(ctx, app, models);
+    const candidates = requestedProjectKey
+        ? projects.filter(item => item.key === requestedProjectKey)
+        : projects;
+    const matches = [];
+    for (const project of candidates) {
+        const previous = ctx.state.projectKey;
+        ctx.state.projectKey = project.key;
+        try {
+            const match = findCustomMenu(await visibleMenu(ctx, app, project.project.menu), ctx.path);
+            if (match) {
+                matches.push({ projectKey: project.key, match });
+            }
+        }
+        finally {
+            if (previous === undefined) {
+                delete ctx.state.projectKey;
+            }
+            else {
+                ctx.state.projectKey = previous;
+            }
+        }
+    }
+    if (matches.length !== 1) {
+        if (!requestedProjectKey && matches.length > 1) {
+            // 多项目都匹配同一自定义路径且未指定项目：回到项目列表让用户自行选择
+            ctx.redirect('/project-list');
+            return true;
+        }
+        return false;
+    }
+    const match = matches[0];
+    if (!match) {
+        return false;
+    }
+    const { projectKey, match: customMatch } = match;
+    const { menu, siderKey } = customMatch;
+    const dashboardBase = app.config.client.dashboardBase === '/' ? '' : app.config.client.dashboardBase;
+    const query = new URLSearchParams(ctx.querystring);
+    query.set('projectKey', projectKey);
+    query.set('key', siderKey ?? menu.key);
+    if (siderKey) {
+        query.set('siderKey', menu.key);
+    }
+    else {
+        query.delete('siderKey');
+    }
+    const suffix = query.toString() ? `?${query.toString()}` : '';
+    ctx.redirect(`${dashboardBase}${siderKey ? `/sider${ctx.path}` : ctx.path}${suffix}`);
+    return true;
+}
+/**
+ * 判断 host 是否为回环地址（含 IPv4 与 IPv6 形式）。
+ * - 仅在 devAnonymous + 非生产场景下使用，避免匿名认证在公网监听
+ */
+function isLoopbackHost(host) {
+    return (host === '127.0.0.1' || host === 'localhost' || host === '::1' || host === '0:0:0:0:0:0:0:1');
+}
+/**
+ * 根据实际存在的业务模块推断加载扩展名。
+ * 优先级：.js > .cjs > .ts；空项目按编译产物约定返回 .js。
+ *
+ * CLI dev/build 流程会把业务模块输出为 .js，因此推断逻辑主要面向：
+ *   - 用户未显式传入 moduleExtension
+ *   - 框架内部 listFiles 需要按确定扩展名扫描
+ */
+function inferModuleExtension(paths) {
+    if ((0, core_1.listModuleFiles)(paths.modelRoot, '.js').length || (0, core_1.listModuleFiles)(paths.serverRoot, '.js').length) {
+        return '.js';
+    }
+    if ((0, core_1.listModuleFiles)(paths.modelRoot, '.cjs').length || (0, core_1.listModuleFiles)(paths.serverRoot, '.cjs').length) {
+        return '.cjs';
+    }
+    if ((0, core_1.listModuleFiles)(paths.modelRoot, '.ts').length || (0, core_1.listModuleFiles)(paths.serverRoot, '.ts').length) {
+        return '.ts';
+    }
+    // 空项目也按编译产物约定处理；CLI dev/build 会把业务模块输出为 JavaScript。
+    return '.js';
+}
+/**
+ * 装配整个 Elpis 框架应用。
+ *
+ * 装配顺序（严格按以下阶段执行；任一阶段抛错都会在 finally 中清理已启动的容器）：
+ *   1. 解析配置与路径（resolveConfig / resolveApplicationPaths）
+ *   2. 预热框架内置页面（readFrameworkPage）以暴露同步访问
+ *   3. 加载并校验业务模型（loadModels + validateModels，拒止 site 模板）
+ *   4. 创建 Koa 容器（createApplicationContainer）并挂载框架扩展字段
+ *   5. 注册全局错误处理 + bodyParser + 认证/匿名中间件
+ *   6. 加载业务 service / controller / middleware
+ *   7. 注册框架内置路由（/api/session、/api/project/list 等）
+ *   8. 注册业务路由（含 router-schema 集中校验）并断言无孤儿 schema
+ *   9. 注册静态资源 + History 兜底（pageForPath / 自定义菜单短链 / 未命中路径 302 到 homePage）
+ *  10. 调用 serverExtension.onReady 钩子
+ *
+ * 重要安全约束：
+ *   - 生产模式必须显式注入 AuthAdapter；未提供直接抛错
+ *   - 非生产模式若无 AuthAdapter，必须显式开启 devAnonymous（防遗忘）
+ *   - devAnonymous 不允许在生产中生效；且 listen 必须为回环地址
+ *
+ * @param context 装配上下文（见 {@link ApplicationContext}）
+ * @returns       托管应用（含 app/listen/close）
+ */
+async function createApplication(context) {
+    const sourceRoot = node_path_1.default.resolve(context.sourceRoot ?? context.rootDir);
+    const mode = context.mode ?? (process.env.NODE_ENV === 'production' ? 'production' : 'development');
+    const serverExtension = context.server ?? {};
+    // 生产环境必须有真实认证；防止误把开发配置部署到线上
+    if (mode === 'production' && !serverExtension.auth) {
+        throw new Error('ELPIS_AUTH_REQUIRED: 生产环境必须提供真实认证适配器');
+    }
+    const resolved = (0, config_1.resolveConfig)(sourceRoot, mode, context.config);
+    const configuredPaths = context.publicRoot
+        ? (0, config_1.resolveApplicationPaths)(sourceRoot, resolved.config, mode, context.publicRoot)
+        : resolved.paths;
+    const moduleRoot = context.moduleRoot ? node_path_1.default.resolve(context.moduleRoot) : undefined;
+    const paths = moduleRoot
+        ? {
+            ...configuredPaths,
+            serverRoot: node_path_1.default.resolve(moduleRoot, resolved.config.server.businessDir ?? 'server'),
+            modelRoot: node_path_1.default.resolve(moduleRoot, resolved.config.model.dir ?? 'model'),
+            sharedRoot: node_path_1.default.resolve(moduleRoot, 'shared'),
+        }
+        : configuredPaths;
+    const moduleExtension = context.moduleExtension ?? inferModuleExtension(paths);
+    // devAnonymous 仅在非生产下生效，且必须显式开启，避免"忘记关"导致开发配置漏到测试
+    if (mode !== 'production' && !serverExtension.auth && !serverExtension.devAnonymous) {
+        throw new Error('ELPIS_AUTH_REQUIRED: 非生产环境也必须显式启用 devAnonymous 或提供认证适配器');
+    }
+    if (moduleExtension !== '.ts' && moduleExtension !== '.js' && moduleExtension !== '.cjs') {
+        throw new Error(`不支持的业务模块扩展名: ${moduleExtension}`);
+    }
+    // 预热：把框架页面读入内存，确保后续路由兜底可以同步响应 HTML
+    assets_1.frameworkPageNames.forEach(page => (0, assets_1.readFrameworkPage)(paths.publicRoot, page));
+    const controlContractPath = resolved.config.model.controlContracts
+        ? node_path_1.default.resolve(moduleRoot ?? paths.sourceRoot, resolved.config.model.controlContracts)
+        : undefined;
+    const controlContracts = loadControlContracts(controlContractPath);
+    const models = (0, model_runtime_1.loadModels)({ modelDir: paths.modelRoot, extension: moduleExtension });
+    for (const loaded of models) {
+        const entries = [
+            [`model.${loaded.key}`, loaded.model],
+            ...Object.entries(loaded.project).map(([key, model]) => [`model.${loaded.key}.project.${key}`, model]),
+        ];
+        for (const [modelPath, model] of entries) {
+            // site 模板尚未实现，启动期直接拒止，避免运行时出现半成品页面
+            if (model && typeof model === 'object' && 'mode' in model && model.mode === 'site') {
+                throw new Error(`ELPIS_UNSUPPORTED_TEMPLATE: ${modelPath}.mode 的 site 模板尚未实现`);
+            }
+        }
+    }
+    (0, model_runtime_1.validateModels)(models, { controlContracts });
+    const application = (0, core_1.createApplicationContainer)({
+        host: resolved.config.server.host,
+        port: resolved.config.server.port,
+        closeTimeoutMs: resolved.config.server.closeTimeoutMs ?? 10_000,
+        // 监听前的安全护栏：devAnonymous 仅允许绑定回环地址
+        validateListen: listenHost => {
+            if (mode !== 'production' && serverExtension.devAnonymous && !isLoopbackHost(listenHost)) {
+                throw new Error('ELPIS_AUTH_REQUIRED: devAnonymous 仅允许监听回环地址');
+            }
+        },
+        onClose: app => serverExtension.onClose?.(app),
+    });
+    const app = application.app;
+    try {
+        const routerSchemas = loadRouterSchemas(node_path_1.default.resolve(paths.serverRoot, 'router-schema'), moduleExtension);
+        const schemaCompiler = createRequestSchemaCompiler();
+        const compiledRouterSchemas = compileRouterSchemas(routerSchemas, schemaCompiler);
+        // 通过 Object.defineProperties 注入只读扩展字段，避免业务意外改写
+        Object.defineProperties(app, {
+            config: { value: resolved.config },
+            paths: { value: paths },
+            mode: { value: mode },
+            framework: { value: { models, routerSchemas, controlContracts } },
+            routerSchema: { value: routerSchemas },
+            // service/controller/middlewares 需在装载阶段写入，因此声明为 writable
+            service: { value: {}, writable: true },
+            controller: { value: {}, writable: true },
+            middlewares: { value: {}, writable: true },
+            serverExtension: { value: serverExtension },
+        });
+        // 全局错误兜底中间件：
+        // - 任何下游中间件抛错都会被这里捕获
+        // - /api 路径返回结构化错误响应，否则按 text/plain 兜底
+        // - 总是触发 app.emit('error', ...) 以便业务 onReady 注册的探针记录
+        app.use(async (ctx, next) => {
+            try {
+                await next();
+            }
+            catch (error) {
+                const status = error && typeof error === 'object' && 'status' in error ? Number(error.status) : 500;
+                ctx.status = status >= 400 && status < 600 ? status : 500;
+                if (isApiPath(ctx.path)) {
+                    ctx.body = {
+                        success: false,
+                        code: ctx.status,
+                        message: ctx.status >= 500
+                            ? '服务器内部错误'
+                            : error instanceof Error
+                                ? error.message
+                                : '请求失败',
+                    };
+                }
+                else {
+                    ctx.type = 'text/plain';
+                    ctx.body = ctx.status >= 500 ? 'Internal Server Error' : '请求失败';
+                }
+                app.emit('error', error, ctx);
+            }
+        });
+        app.use((0, koa_bodyparser_1.default)({ enableTypes: ['json', 'form', 'text'] }));
+        if (serverExtension.auth) {
+            // 真实认证中间件：解析 token / session 后写入 ctx.state.user
+            app.use(async (ctx, next) => {
+                const identity = await serverExtension.auth.authenticate(ctx);
+                if (!identity) {
+                    if (mode !== 'production' && serverExtension.devAnonymous) {
+                        ctx.state.user = {
+                            id: 'development-anonymous',
+                            name: '开发匿名用户',
+                        };
+                        await next();
+                        return;
+                    }
+                    if (isApiPath(ctx.path)) {
+                        ctx.status = 401;
+                        ctx.set('WWW-Authenticate', serverExtension.auth.challenge ?? 'Bearer realm="elpis"');
+                        ctx.body = { success: false, code: 401, message: '未登录' };
+                        return;
+                    }
+                    ctx.status = 401;
+                    ctx.set('WWW-Authenticate', serverExtension.auth.challenge ?? 'Bearer realm="elpis"');
+                    ctx.type = 'text/plain';
+                    ctx.body = '未登录';
+                    return;
+                }
+                ctx.state.user = identity;
+                await next();
+            });
+        }
+        else {
+            // 无认证适配器时，devAnonymous 已显式开启；写入固定匿名身份
+            app.use(async (ctx, next) => {
+                ctx.state.user = {
+                    id: 'development-anonymous',
+                    name: '开发匿名用户',
+                };
+                await next();
+            });
+        }
+        const businessRoot = paths.serverRoot;
+        // 业务 service / controller 通过类装饰方式装载；loadClassModules 自动实例化并注入 app
+        app.service = (0, core_1.loadClassModules)(node_path_1.default.resolve(businessRoot, 'service'), moduleExtension, app);
+        app.controller = (0, core_1.loadClassModules)(node_path_1.default.resolve(businessRoot, 'controller'), moduleExtension, app);
+        loadMiddlewares(node_path_1.default.resolve(businessRoot, 'middleware'), moduleExtension, app);
+        const router = new router_1.default();
+        const registered = new Set();
+        const reserved = new Set();
+        // 框架内置路由：业务路由若与之同名/同方法直接报错，避免静默覆盖关键接口
+        const addBuiltin = (method, routePath, handler) => {
+            const routeId = `${method} ${routePath}`;
+            reserved.add(routeId);
+            registered.add(routeId);
+            const register = router[method];
+            register.call(router, routePath, handler);
+        };
+        // /api/session：当前登录身份 + 公共配置（前端启动时获取）
+        addBuiltin('get', '/api/session', ctx => {
+            ctx.body = {
+                success: true,
+                data: {
+                    user: publicIdentity(ctx.state.user),
+                    public: resolved.config.public,
+                },
+            };
+        });
+        // /api/project/model_list：模型 + 可见项目（用于项目列表页）
+        addBuiltin('get', '/api/project/model_list', async (ctx) => {
+            ctx.body = { success: true, data: await publicModels(ctx, app, models) };
+        });
+        // /api/project/list：项目列表（支持 ?modelKey 过滤）
+        addBuiltin('get', '/api/project/list', async (ctx) => {
+            const modelKey = typeof ctx.query.modelKey === 'string' ? ctx.query.modelKey : undefined;
+            const projects = await visibleProjects(ctx, app, models, modelKey);
+            ctx.body = {
+                success: true,
+                data: projects.map(item => publicProject(item.modelKey, item.key, item.project)),
+            };
+        });
+        // /api/project：单个项目详情（含菜单授权过滤）
+        addBuiltin('get', '/api/project', async (ctx) => {
+            const projectKey = typeof ctx.query.projectKey === 'string' ? ctx.query.projectKey : undefined;
+            if (!projectKey) {
+                ctx.status = 400;
+                ctx.body = { success: false, code: 400, message: '缺少 projectKey' };
+                return;
+            }
+            const item = findProject(models, projectKey);
+            if (!item) {
+                ctx.status = 404;
+                ctx.body = { success: false, code: 404, message: '项目不存在' };
+                return;
+            }
+            if (!(await isProjectAllowed(ctx, app, projectKey))) {
+                ctx.status = 403;
+                ctx.body = { success: false, code: 403, message: '无权访问当前项目' };
+                return;
+            }
+            ctx.body = {
+                success: true,
+                data: await publicProjectDetail(ctx, app, item.key, item.project),
+            };
+        });
+        registerBusinessRoutes(router, node_path_1.default.resolve(businessRoot, 'router'), moduleExtension, app, compiledRouterSchemas, registered, reserved, schemaCompiler);
+        // 启动期校验：避免"定义了校验却忘记挂路由"的死代码
+        assertNoOrphanSchemas(routerSchemas, registered);
+        app.use(router.routes());
+        app.use(router.allowedMethods());
+        if (node_fs_1.default.existsSync(paths.publicRoot)) {
+            // 静态资源托管：
+            // 1. /api 和 /api/* 永远走接口，不被同名静态文件劫持；
+            // 2. 含扩展名的静态业务资源也走授权（用 module=public, action=read）；
+            // 3. 无扩展名的路径（History 路由）交由下方的页面兜底中间件处理。
+            const staticMiddleware = (0, koa_static_1.default)(paths.publicRoot);
+            app.use(async (ctx, next) => {
+                // API 路径永远不能被同名静态文件劫持成 HTML 或其他资源。
+                if (isApiPath(ctx.path)) {
+                    await next();
+                    return;
+                }
+                // 真实静态资源必须授权；缺失的带点号页面路径仍可按 HTML 导航进入 History 兜底。
+                if (ctx.path.includes('.') &&
+                    app.serverExtension.auth &&
+                    (!acceptsHtmlDocument(ctx) || (await hasStaticFile(paths.publicRoot, ctx.path)))) {
+                    attachProject(ctx);
+                    const identity = ctx.state.user;
+                    if (!identity ||
+                        !(await app.serverExtension.auth.authorize(ctx, { module: 'public', action: 'read' }, identity))) {
+                        ctx.status = 403;
+                        ctx.body = { success: false, code: 403, message: '无权访问当前资源' };
+                        return;
+                    }
+                }
+                await staticMiddleware(ctx, next);
+            });
+        }
+        // History 路由兜底：
+        // - /api 或 /api/* 未匹配路由 → 404 结构化响应
+        // - 非 API + 404 + GET/HEAD 依次尝试：框架页面 → HTML 页面请求的自定义菜单短链 → homePage；
+        //   非 HTML 请求保留 404，静态文件已由上方中间件处理
+        app.use(async (ctx) => {
+            if (isApiPath(ctx.path)) {
+                // 利用 koa-router 注入的内部字段判断是否有路由匹配
+                const matchedRoute = ctx._matchedRoute;
+                if (!matchedRoute) {
+                    ctx.status = 404;
+                    ctx.body = { success: false, code: 404, message: '接口不存在' };
+                }
+                return;
+            }
+            // 已显式写过状态码或非 GET/HEAD 的请求不再做 History 兜底
+            if (ctx.status !== 404 || !['GET', 'HEAD'].includes(ctx.method)) {
+                return;
+            }
+            const page = pageForPath(resolved.config, ctx.path);
+            if (page) {
+                ctx.type = 'html';
+                ctx.body = (0, assets_1.readFrameworkPage)(paths.publicRoot, page);
+                return;
+            }
+            // 未命中的非 HTML 请求通常是缺失静态资源或程序化请求，保留 404。
+            if (!acceptsHtmlDocument(ctx)) {
+                ctx.status = 404;
+                ctx.type = 'text/plain';
+                ctx.body = '404 Not Found';
+                return;
+            }
+            // 框架页面未命中：尝试 custom 菜单短链重定向
+            if (await redirectCustomPageShortcut(ctx, app, models)) {
+                return;
+            }
+            // 兜底收敛：302 到配置的 homePage；homePage 剥 query 后为根路径或
+            // 空串时，为避免循环改为原路径渲染项目列表页
+            const homePagePath = resolved.config.public.homePage.split('?')[0];
+            if (homePagePath && homePagePath !== '/') {
+                ctx.redirect(resolved.config.public.homePage);
+                return;
+            }
+            ctx.type = 'html';
+            ctx.body = (0, assets_1.readFrameworkPage)(paths.publicRoot, 'project-list');
+        });
+        await serverExtension.onReady?.(app);
+    }
+    catch (error) {
+        // 任一阶段失败：先尝试关闭已启动容器（释放端口/句柄），再抛出原错误
+        try {
+            await application.close();
+        }
+        catch (cleanupError) {
+            // 聚合两个错误，方便上层一次性看到"初始化失败 + 清理失败"
+            throw new AggregateError([error, cleanupError], '应用初始化失败且清理失败');
+        }
+        throw error;
+    }
+    return application;
+}
+/**
+ * 一键装配 + 启动：默认按 production 模式装配（即使环境变量为 development），
+ * 因为 startApplication 面向"真正开始对外监听"的场景。
+ *
+ * 适合 CLI / 容器入口调用；测试或本地热重载请直接使用 {@link createApplication}。
+ */
+async function startApplication(context) {
+    return (0, core_1.startApplicationContainer)(await createApplication({ ...context, mode: context.mode ?? 'production' }));
+}
+//# sourceMappingURL=application.js.map