@_tc/template-core 0.0.1-bate.46 → 0.0.1-bate.47

package/types/scripts/vite-build/normalize.d.ts

@@ -0,0 +1,66 @@
+import type { Alias } from "vite";
+import type { BuildEntriesConfig, BuildFormat, CopyConfig, ExtensionConfig, IgnoreConfig, NormalizedCopyConfig, NormalizedDtsConfig } from "./types.ts";
+/**
+ * 标准化文件扩展名配置
+ * 合并默认扩展名和自定义扩展名，确保扩展名以点开头
+ * @param extensionOptions - 扩展名配置，包含 input 数组和 mergeDefault 标志
+ * @returns 标准化后的扩展名数组（去重）
+ */
+export declare function normalizeExtensions(extensionOptions?: ExtensionConfig): string[];
+/**
+ * 标准化忽略配置
+ * 提供默认值确保返回完整的配置对象
+ * @param ignoreOptions - 忽略配置
+ * @returns 包含 input 和 importPolicy 的完整配置对象
+ */
+export declare function normalizeIgnore(ignoreOptions?: IgnoreConfig): Required<IgnoreConfig>;
+/**
+ * 标准化路径别名配置
+ * 支持对象格式和数组格式，将相对路径转换为绝对路径
+ * @param aliasOptions - 别名配置（对象或数组格式）
+ * @param rootDir - 项目根目录
+ * @returns Vite Alias 数组
+ */
+export declare function normalizeAlias(aliasOptions: BuildEntriesConfig['alias'], rootDir: string): Alias[];
+/**
+ * 标准化非代码文件扩展名配置
+ * 用于识别需要复制而非编译的资源文件
+ * @param extensionOptions - 扩展名配置
+ * @returns 标准化后的扩展名数组（去重）
+ */
+export declare function normalizeNonCodeExtensions(extensionOptions?: ExtensionConfig): string[];
+/**
+ * 标准化输出格式配置
+ * 确保返回有效的格式数组
+ * @param formatOptions - 格式配置（单个格式或数组）
+ * @returns 格式数组，默认 ['es', 'cjs']
+ */
+export declare function normalizeFormats(formatOptions?: BuildFormat | BuildFormat[]): BuildFormat[];
+/**
+ * 标准化类型声明文件配置
+ * 支持布尔值、对象配置或 undefined
+ * @param dtsOptions - DTS 配置选项
+ * @param outputRoot - 输出根目录
+ * @returns 标准化的 DTS 配置对象
+ */
+export declare function normalizeDtsConfig(dtsOptions: BuildEntriesConfig['dts'], outputRoot: string): NormalizedDtsConfig;
+/**
+ * 标准化格式输出目录映射
+ * 默认保持历史行为：es -> esm, cjs -> cjs
+ */
+export declare function normalizeFormatOutDir(formatOutDir: BuildEntriesConfig['formatOutDir']): Partial<Record<BuildFormat, string>>;
+/**
+ * 检查并阻止将资源文件扩展名添加到代码扩展名列表
+ * 防止将 .css、.svg 等文件当作代码编译
+ * @param extensions - 代码文件扩展名列表
+ * @param nonCodeExtensions - 非代码文件扩展名列表
+ * @throws 如果发现资源文件扩展名混入代码扩展名列表
+ */
+export declare function assertNoCommonAssetExtensions(extensions: string[], nonCodeExtensions: string[]): void;
+/**
+ * 标准化复制文件配置
+ * 配置需要原样复制的资源文件
+ * @param copyOptions - 复制配置
+ * @returns 标准化的复制配置对象
+ */
+export declare function normalizeCopy(copyOptions?: CopyConfig): NormalizedCopyConfig;

package/types/scripts/vite-build/plugins.d.ts

@@ -0,0 +1,67 @@
+import type { Plugin, PluginOption } from "vite";
+import type { BuildContext, BuildEntriesFilePlugin, BuildEntriesFilePluginOptions, InternalPlugin } from "./types.ts";
+/**
+ * 创建构建文件插件的基础工厂函数
+ * 用于创建可以处理文件复制或转换的 Vite 插件
+ * @param pluginOptions - 插件配置选项
+ * @returns BuildEntriesFilePlugin 对象
+ */
+export declare function createBuildEntriesFilePlugin(pluginOptions?: BuildEntriesFilePluginOptions): BuildEntriesFilePlugin;
+/**
+ * 创建文件复制插件
+ * 用于将非代码文件原样复制到输出目录
+ * @param options - 插件配置选项
+ * @param options.rename - 可选的重命名函数
+ * @returns BuildEntriesFilePlugin 对象，kind 为 'copy'
+ */
+export declare function createCopyPlugin(options?: BuildEntriesFilePluginOptions): BuildEntriesFilePlugin;
+/**
+ * 创建文件转换插件
+ * 用于对文件内容进行自定义转换处理
+ * @param options - 插件配置选项
+ * @param options.transform - 文件转换函数
+ * @returns BuildEntriesFilePlugin 对象
+ */
+export declare function createFilePlugin(options?: BuildEntriesFilePluginOptions): BuildEntriesFilePlugin;
+/**
+ * 将 BuildEntriesFilePlugin 转换为实际的 Vite 插件
+ * 在 writeBundle 阶段处理文件并输出到目标目录
+ * @param plugin - BuildEntriesFilePlugin 实例
+ * @param buildContext - 构建上下文信息
+ * @returns Vite Plugin 对象
+ */
+export declare function hydrateFilePlugin(plugin: BuildEntriesFilePlugin, buildContext: BuildContext): Plugin;
+/**
+ * 准备 Vite 插件列表
+ * 将内部插件格式转换为标准 Vite 插件
+ * @param plugins - 内部插件列表
+ * @param buildContext - 构建上下文信息
+ * @returns 标准 Vite 插件数组
+ */
+export declare function prepareVitePlugins(plugins: InternalPlugin[], buildContext: BuildContext): Plugin[];
+/**
+ * 标准化插件配置
+ * 支持多种配置格式：数组、对象配置或 undefined
+ * @param pluginOptions - 插件配置
+ * @param defaultPlugins - 默认插件列表
+ * @returns 标准化的内部插件数组
+ */
+export declare function normalizePlugins(pluginOptions: {
+    input?: PluginOption[];
+    mergeDefault?: boolean;
+} | PluginOption[] | undefined, defaultPlugins?: InternalPlugin[]): InternalPlugin[];
+/**
+ * 合并默认插件和用户插件
+ * 如果用户提供了自定义复制插件，则移除默认的复制插件
+ * @param defaultPlugins - 默认插件列表
+ * @param inputPlugins - 用户插件列表
+ * @returns 合并后的插件数组
+ */
+export declare function mergePlugins(defaultPlugins: InternalPlugin[], inputPlugins: InternalPlugin[]): InternalPlugin[];
+/**
+ * 扁平化插件选项数组
+ * 递归处理嵌套数组，过滤空值
+ * @param pluginOptions - 可能包含嵌套的插件选项数组
+ * @returns 扁平化的内部插件数组
+ */
+export declare function flattenPluginOptions(pluginOptions: PluginOption[]): InternalPlugin[];

package/types/scripts/vite-build/resolve.d.ts

@@ -0,0 +1,61 @@
+import type { Alias } from "vite";
+import type { ExternalMatcher, ExternalOption, ExtensionConfig } from "./types.ts";
+/**
+ * 解析导入路径的实际文件位置
+ * 处理相对路径、路径别名和扩展名补全
+ * @param importer - 导入文件的绝对路径
+ * @param source - 导入标识符
+ * @param extensions - 需要尝试的文件扩展名
+ * @param aliases - 路径别名配置
+ * @returns 解析后的文件绝对路径
+ */
+export declare function resolveImportPath(importer: string, source: string, extensions: string[], aliases: Alias[]): Promise<string>;
+/**
+ * 创建路径忽略判断函数
+ * 用于检查给定路径是否在忽略列表中
+ * @param ignorePaths - 需要忽略的路径列表（相对或绝对）
+ * @param rootDir - 项目根目录
+ * @returns 判断函数，接收路径返回是否应被忽略
+ */
+export declare function createIgnoreMatcher(ignorePaths: string[], rootDir: string): (targetPath: string) => boolean;
+/**
+ * 检查模块标识符是否匹配某个别名
+ * @param id - 模块标识符
+ * @param aliases - 路径别名配置
+ * @returns 是否匹配别名
+ */
+export declare function matchesAlias(id: string, aliases: Alias[]): boolean;
+/**
+ * 判断导入是否为裸模块导入（npm 包）
+ * @param id - 模块标识符
+ * @returns 是否为裸模块导入
+ */
+export declare function isBareImport(id: string): boolean;
+/**
+ * 检查模块是否匹配外部依赖规则
+ * @param id - 模块标识符
+ * @param importer - 导入者文件路径
+ * @param matcher - 匹配器（字符串、正则或函数）
+ * @returns 是否匹配外部依赖规则
+ */
+export declare function matchesExternalRule(id: string, importer: string | undefined, matcher: ExternalMatcher): boolean;
+/**
+ * 创建外部依赖判断函数
+ * 用于判断模块是否应该被视为外部依赖（不打包）
+ * @param aliases - 路径别名配置
+ * @param externalOption - 外部依赖配置
+ * @param externalNodeBuiltins - 是否将 Node.js 内置模块视为外部依赖，默认 true
+ * @param externalPackages - 是否将所有 npm 包视为外部依赖，默认 false
+ * @returns 外部依赖判断函数
+ */
+export declare function createExternalPredicate(aliases: Alias[], externalOption?: ExternalOption, externalNodeBuiltins?: boolean, externalPackages?: boolean): (id: string, importer?: string) => boolean;
+/**
+ * 创建扩展名匹配器
+ * 用于快速判断文件是否具有指定的扩展名
+ * @param extensionOptions - 扩展名配置
+ * @returns 包含扩展名数组和测试函数的对象
+ */
+export declare function createExtensionMatcher(extensionOptions?: ExtensionConfig): {
+    extensions: string[];
+    test: (filePath: string) => boolean;
+};

package/types/scripts/vite-build/types.d.ts

@@ -0,0 +1,174 @@
+import type { Alias, LibraryFormats, Plugin, PluginOption } from "vite";
+export type ImportPolicy = 'error' | 'skip';
+export type BuildFormat = LibraryFormats;
+export type OutputStructure = 'preserve' | 'bundle';
+export type ExtensionConfig = {
+    input?: string[];
+    mergeDefault?: boolean;
+};
+export type IgnoreConfig = {
+    input?: string[];
+    importPolicy?: ImportPolicy;
+};
+export type CopyConfig = {
+    input?: string[];
+    ignore?: {
+        input?: string[];
+    };
+    extensions?: ExtensionConfig;
+    onlyConfiguredExtensions?: boolean;
+};
+export type PluginsConfig = {
+    input?: PluginOption[];
+    mergeDefault?: boolean;
+};
+export type FilePluginOutput = {
+    type: 'copy';
+    fileName?: string;
+    sourcePath: string;
+} | {
+    type: 'emit';
+    fileName?: string;
+    content: string;
+};
+export type FilePluginContext = {
+    filePath: string;
+    relativePath: string;
+    rootDir: string;
+    outDir: string;
+    format: BuildFormat;
+    read: () => Promise<string>;
+};
+export type BuildEntriesFilePluginOptions = {
+    name?: string;
+    apply?: 'build' | 'serve';
+    enforce?: 'pre' | 'post';
+    kind?: 'copy';
+    allowMissing?: boolean;
+    onlyConfiguredExtensions?: boolean;
+    input?: string[];
+    rootDir?: string;
+    ignore?: {
+        input?: string[];
+    };
+    extensions?: ExtensionConfig;
+    copyExtensions?: ExtensionConfig;
+    test?: (filePath: string) => boolean;
+    rename?: (relativePath: string, filePath: string) => string;
+    transform?: (context: FilePluginContext) => Promise<FilePluginOutput | FilePluginOutput[] | void> | FilePluginOutput | FilePluginOutput[] | void;
+};
+export type BuildEntriesFilePlugin = {
+    name: string;
+    apply?: 'build' | 'serve';
+    enforce?: 'pre' | 'post';
+    kind?: 'copy';
+    __buildEntriesFilePlugin: BuildEntriesFilePluginOptions;
+};
+export type InternalPlugin = Plugin & Partial<BuildEntriesFilePlugin>;
+export type StringAlias = Alias & {
+    find: string;
+};
+export type BuildEntriesConfig = {
+    input?: string[];
+    format?: BuildFormat | BuildFormat[];
+    outputStructure?: OutputStructure;
+    formatOutDir?: Partial<Record<BuildFormat, string>>;
+    alias?: Record<string, string> | Alias[];
+    external?: ExternalOption;
+    externalNodeBuiltins?: boolean;
+    bundleDependencies?: boolean;
+    externalPackages?: boolean;
+    allowMissingInput?: boolean;
+    ignore?: IgnoreConfig;
+    copy?: CopyConfig;
+    minify?: boolean;
+    dtsOnly?: boolean;
+    preserveSideEffectStyleImports?: boolean;
+    extensions?: ExtensionConfig;
+    nonCodeExtensions?: ExtensionConfig;
+    plugins?: PluginOption[] | PluginsConfig;
+    dts?: boolean | {
+        enabled?: boolean;
+        outDir?: string;
+        tsconfig?: string;
+        tempDir?: string;
+        rewriteAliases?: boolean;
+        rewriteAliasMode?: 'source' | 'declaration';
+        rewriteAlias?: Record<string, string> | Alias[];
+        useInputFiles?: boolean;
+        clean?: boolean;
+    };
+    outDir?: string;
+    rootDir?: string;
+};
+export type ExternalMatcher = string | RegExp | ((id: string, importer?: string) => boolean);
+export type ExternalOption = ExternalMatcher | ExternalMatcher[];
+export type BuildEntriesResult = {
+    alias: Alias[];
+    formats: BuildFormat[];
+    outputStructure: OutputStructure;
+    bundleDependencies: boolean;
+    extensions: string[];
+    files: string[];
+    ignore: Required<IgnoreConfig>;
+    copy: NormalizedCopyConfig;
+    plugins: string[];
+    outputs: Record<string, string>;
+    dts: {
+        enabled: boolean;
+        outDir?: string;
+    };
+};
+export type PluginFileHandler = {
+    test: (filePath: string) => boolean;
+    transform: (context: FilePluginContext) => Promise<FilePluginOutput | FilePluginOutput[] | void> | FilePluginOutput | FilePluginOutput[] | void;
+};
+export type CollectedPluginFile = {
+    filePath: string;
+    plugin: PluginFileHandler;
+};
+export type BuildContext = {
+    inputPaths: string[];
+    rootDir: string;
+    ignorePaths: string[];
+    extensions: string[];
+    allowMissingInput: boolean;
+    outDir: string;
+    format: BuildFormat;
+};
+export type NormalizedCopyConfig = {
+    input?: string[];
+    ignore?: {
+        input?: string[];
+    };
+    extensions: ExtensionConfig;
+    onlyConfiguredExtensions: boolean;
+};
+export type RunBuildOptions = {
+    format: BuildFormat;
+    outDir: string;
+    entry: Record<string, string>;
+    outputStructure: OutputStructure;
+    emptyOutDir: boolean;
+    minify?: boolean;
+    rootDir: string;
+    preserveSideEffectStyleImports?: boolean;
+    plugins: Plugin[];
+    aliases: Alias[];
+    external: (id: string, importer?: string) => boolean;
+};
+export type NormalizedDtsConfig = {
+    enabled: boolean;
+    outDir: string;
+    tsconfig?: string;
+    tempDir?: string;
+    rewriteAliases: boolean;
+    rewriteAliasMode: 'source' | 'declaration';
+    rewriteAlias?: Record<string, string> | Alias[];
+    useInputFiles: boolean;
+    clean: boolean;
+};
+export type AliasRewriteRule = {
+    find: string;
+    replacement: string;
+};

package/types/scripts/vite-build/utils.d.ts

@@ -0,0 +1,35 @@
+import type { Alias } from "vite";
+import type { StringAlias } from "./types.ts";
+/**
+ * 检查路径是否存在
+ * @param targetPath - 目标路径
+ * @returns 路径是否存在
+ */
+export declare function pathExists(targetPath: string): Promise<boolean>;
+/**
+ * 将路径转换为 POSIX 格式（使用正斜杠）
+ * 确保跨平台路径一致性
+ * @param value - 输入路径
+ * @returns POSIX 格式路径
+ */
+export declare function toPosixPath(value: string): string;
+/**
+ * 确保相对导入路径格式正确
+ * 为不以点开头的相对路径添加 './' 前缀
+ * @param value - 相对路径
+ * @returns 格式化后的相对导入路径
+ */
+export declare function ensureRelativeImportPath(value: string): string;
+/**
+ * 将值转换为数组
+ * @param value - 输入值（单个值、数组、null 或 undefined）
+ * @returns 数组
+ */
+export declare function toArray<T>(value: T | T[] | null | undefined): T[];
+/**
+ * 判断别名是否为字符串类型别名
+ * 用于区分字符串别名和正则别名
+ * @param alias - Vite Alias 对象
+ * @returns 是否为字符串别名
+ */
+export declare function isStringAlias(alias: Alias): alias is StringAlias;

package/types/typings/type.d.ts

@@ -1,3 +1,4 @@
 export type MOmit<T, K extends keyof T> = Omit<T, K>;
 export type UnionToTuple<T> = [T] extends [never] ? [] : ((t: T) => T) extends (t: infer U) => infer U ? [...UnionToTuple<Exclude<T, U>>, U] : never;
 export type MergeType<T extends unknown[]> = T extends [infer F, ...infer R] ? F & (R extends [] ? MergeType<R> : {}) : {};
+export type GetInstance<T extends (...args: never[]) => unknown> = T extends (...args: never[]) => infer R ? R extends new () => infer C ? C : R extends Promise<infer P> ? P extends new () => infer C2 ? C2 : never : never : never;

package/cjs/app/README.md

@@ -1,286 +0,0 @@
-# app 模块说明
-
-## 0. 先看结论
-
-`app` 是 TemplateCore 内置的 Koa 应用层。
-
-- 它提供框架默认 controller、service、middleware、router、extend、router-schema 和页面模板。
-- 它和业务项目的 `app/` 会被 `@tc/core` 一起加载，形成“框架默认能力 + 业务覆盖/扩展”的结构。
-- 它主要承接两类请求：后台页面渲染，以及 `/api/project/*` 项目模型接口。
-
-适合先读：
-
-- 想看服务中间件顺序：看 `middleware.ts`。
-- 想看页面怎么渲染：看 `router/view.ts`、`controller/view.ts`、`view/entry.tpl`。
-- 想看项目数据接口：看 `router/project.ts`、`controller/project.ts`、`service/project.ts`。
-
-## 关联阅读
-
-- [packages/core 模块](../packages/core/README.md)：Koa app 创建、loader 顺序和双路径加载。
-- [frontend 模块](../frontend/README.md)：页面模板加载后的 React 运行层。
-- [bundler 模块](../bundler/README.md)：生成 `app/public/dist/*.entry.tpl` 的构建逻辑。
-- [model 模块](../model/README.md)：项目 API 返回的模型配置结构。
-
-## 1. 模块边界
-
-`app` 做这些事：
-
-- 装配内置 Koa 全局中间件。
-- 提供静态资源服务。
-- 渲染前端入口模板。
-- 提供项目模型相关 API。
-- 提供统一响应结构和基础 Controller/Service。
-- 提供 API 签名校验、参数校验、错误处理。
-- 对 `@tc/core` 做 TypeScript 类型增强。
-
-`app` 不做这些事：
-
-- 不实现 React 页面内部逻辑。
-- 不扫描 `.entry.*` 前端入口。
-- 不负责最终构建输出。
-- 不直接维护业务 CRUD 数据；业务数据由业务 controller/service 实现。
-
-## 2. 目录地图
-
-| 路径 | 作用 |
-| --- | --- |
-| `middleware.ts` | 框架全局中间件装配入口。 |
-| `middleware/*` | 具体中间件：错误处理、签名校验、参数校验、项目信息处理。 |
-| `router/view.ts` | 页面路由，匹配 `pageBasePage + :page`。 |
-| `controller/view.ts` | 渲染 `dist/{page}.entry.tpl`。 |
-| `view/entry.tpl` | 默认页面模板，注入前端运行需要的全局变量。 |
-| `router/project.ts` | 项目模型 API 路由。 |
-| `controller/project.ts` | 项目模型 API controller。 |
-| `service/project.ts` | 调用 `loaderModel(app)` 读取业务 model 配置。 |
-| `controller/base.ts` | 基础 Controller，提供 `success/fail/sendData`。 |
-| `service/base.ts` | 基础 Service，提供 `app/config/curl`。 |
-| `router-schema/project.ts` | 项目 API 的 JSON Schema 校验配置。 |
-| `extend/*` | 挂到 `app.extends` 的扩展能力。 |
-| `typings.ts` | 对 `@tc/core` 的模块增强声明。 |
-| `data/signKey.ts` | API 签名 key。 |
-
-## 3. 服务加载链路
-
-根入口 `index.ts` 导出 `serverStart(options)`，内部调用 `@tc/core` 的 `start`：
-
-```text
-serverStart(options)
-  -> start({ ...options, frameBaseDir })
-  -> core 加载 frame app + business app
-  -> config
-  -> extend
-  -> router-schema
-  -> service
-  -> controller
-  -> middleware 目录
-  -> app/middleware.ts 全局装配
-  -> router
-  -> listen
-```
-
-```mermaid
-flowchart TD
-  A["serverStart(options)"] --> B["@tc/core start"]
-  B --> C["configLoader"]
-  C --> D["extendLoader"]
-  D --> E["routerSchemaLoader"]
-  E --> F["serviceLoader"]
-  F --> G["controllerLoader"]
-  G --> H["middlewareLoader"]
-  H --> I["app/middleware.ts"]
-  I --> J["routerLoader"]
-  J --> K["app.listen"]
-```
-
-这里的 `app/` 是框架内置目录，业务项目也可以有自己的 `app/`。`@tc/core` 会把两者放进 `app.paths`：
-
-```text
-frame app    -> TemplateCore/app
-business app -> project/app
-```
-
-大多数 loader 都会同时扫描这两个目录。
-
-## 4. 中间件顺序
-
-`app/middleware.ts` 中的顺序是运行时请求的主干：
-
-```text
-errorHandle
-  -> compress
-  -> koaStatic(frame app/public)
-  -> koaStatic(business app/public)
-  -> koaBody
-  -> projectHandler
-  -> apiSignVerify 非 local
-  -> apiParamsVerify
-  -> router/controller/service
-```
-
-设计原因：
-
-- `errorHandle` 最靠前，用于捕获后续中间件和 controller 抛出的错误。
-- 静态资源在 body parser 前，减少不必要的请求解析。
-- `projectHandler` 在 API 校验前写入项目上下文。
-- `apiSignVerify` 只在非 local 环境启用。
-- `apiParamsVerify` 依赖 `app.routerSchema` 和当前路由信息。
-
-## 5. 页面渲染链路
-
-请求 `/dash?projk=xxx` 这类页面时：
-
-```text
-GET /dash
-  -> app/router/view.ts
-  -> app.controller.view.renderPage
-  -> app.extends.renderView("dist/dash.entry.tpl", ctx, context)
-  -> app/view/entry.tpl 或构建后的 tpl
-  -> 注入 window._basePath / window._projKey / window.appOptions
-  -> 浏览器加载前端 bundle
-```
-
-```mermaid
-sequenceDiagram
-  participant Browser
-  participant Router as app/router/view.ts
-  participant Controller as app/controller/view.ts
-  participant Nunjucks as app.extends.renderView
-  participant Frontend as frontend bundle
-  Browser->>Router: GET /dash?projk=xxx
-  Router->>Controller: renderPage(ctx)
-  Controller->>Nunjucks: render dist/dash.entry.tpl
-  Nunjucks-->>Browser: HTML + window variables
-  Browser->>Frontend: load /dist assets
-```
-
-页面名和前端入口强绑定：
-
-```text
-frontend/dash/dash.entry.tsx
-  -> bundler 输出 app/public/dist/dash.entry.tpl
-  -> GET /dash 渲染 dist/dash.entry.tpl
-```
-
-## 6. 项目 API
-
-内置项目 API 用于给前端 Dashboard 提供模型和菜单数据。
-
-| 路由 | 作用 |
-| --- | --- |
-| `GET /api/project/model_list` | 返回模型列表和项目摘要。 |
-| `GET /api/project/list?projk=xxx` | 返回项目列表，可按 key 过滤。 |
-| `GET /api/project/:key` | 返回单个项目完整配置。 |
-
-数据来源：
-
-```text
-app/service/project.ts
-  -> loaderModel(app)
-  -> 读取 business baseDir/model
-  -> 合并 model 配置和 project 覆盖配置
-```
-
-响应统一为：
-
-```ts
-{
-  data: unknown,
-  code: number,
-  message: string
-}
-```
-
-## 7. Controller 和 Service 约定
-
-框架内置 Controller/Service 都是工厂函数：
-
-```ts
-export default (app) => class XxxController {}
-export default (app) => class XxxService {}
-```
-
-`@tc/core` loader 会：
-
-1. 执行默认导出函数，传入 `app`。
-2. 拿到 class。
-3. `new` 出实例。
-4. 挂到 `app.controller.xxx` 或 `app.service.xxx`。
-
-基础 Controller 提供：
-
-- `success(ctx, data)`
-- `fail(ctx, code, message)`
-- `sendData(ctx, data, code, message, status)`
-
-基础 Service 提供：
-
-- `app`
-- `config`
-- `curl`，即 `superagent`
-
-## 8. 扩展能力
-
-`app/extend/*` 会挂到 `app.extends`。
-
-| 扩展 | 作用 |
-| --- | --- |
-| `render-view.ts` | Nunjucks 渲染封装。 |
-| `logger.ts` | local 使用 console，非 local 使用 log4js。 |
-| `generateErrorMessage.ts` | 构造并抛出可被 `errorHandle` 捕获的错误。 |
-| `parsingParamsOnUrl.ts` | 根据路由模板解析 URL params。 |
-| `db.ts` | 当前为占位扩展。 |
-
-`logger.ts` 在非 local 环境下可覆盖原生 `console`，由 `overwriteOriginalLogs` 控制。
-
-## 9. 参数校验与错误处理
-
-`router-schema/*` 会被加载到 `app.routerSchema`。`apiParamsVerify` 会在 `/api` 请求中尝试：
-
-1. 根据当前 path 找到匹配路由。
-2. 从 route path 中解析 params。
-3. 收集 `params/body/query/headers`。
-4. 找到对应 schema。
-5. 用 AJV 校验。
-6. 失败时通过 `generateErrorMessage` 抛出错误。
-
-`errorHandle` 会统一捕获错误。对 `template not found` 有特殊逻辑：
-
-- 未超过 `notFoundRedirectCount` 时重定向到 `homePage`。
-- 超过后返回普通错误响应。
-
-## 10. 类型增强
-
-`app/typings.ts` 通过 TypeScript module augmentation 扩展 `@tc/core`：
-
-- `app.controller.project`
-- `app.controller.view`
-- `app.service.project`
-- `app.extends.logger`
-- `app.extends.renderView`
-- `app.middlewares.errorHandle`
-- `app.config` 默认配置类型
-
-新增内置能力后，建议同步更新 `app/typings.ts`，否则调用侧类型会丢失。
-
-## 11. 注意事项
-
-- 页面模板名和前端入口名强绑定，请求 `/dash` 会寻找 `dist/dash.entry.tpl`。
-- `projectHandler` 只对路径包含 `/api/proj/` 的请求强制要求 header `projk`，`/api/project/*` 不在这个判断内。
-- `apiParamsVerify` 当前匹配路由时固定用 `r.match(path, "get")`，对非 GET 的覆盖需要结合实现确认。
-- `renderPage` 中模板不存在会抛出 `template not found`，由 `errorHandle` 接住。
-- `app/extend/db.ts` 当前是占位，不代表框架已内置数据库能力。
-- 非 local 环境下 API 签名校验会生效，前后端签名 key 必须一致。
-
-## 12. 常见问题
-
-### 页面模板找不到
-
-确认 `bundler` 已经生成 `app/public/dist/{page}.entry.tpl`，并且访问路径里的 `{page}` 和 entry 名一致。
-
-### 非 local 环境接口返回签名错误
-
-检查前端 `s_sign` 生成逻辑和服务端 `app/data/signKey.ts` 是否一致，同时确认请求时间戳没有超过超时时间。
-
-### 新增 controller 后类型没有提示
-
-运行时可能已经可用，但 TypeScript 类型需要在 `app/typings.ts` 或业务自己的模块增强文件中补充。