@_tc/template-core 0.2.3 → 0.2.5

package/README.md

@@ -2,7 +2,7 @@
 
 TemplateCore 是一个基于 TypeScript、Koa、React 的后台框架包。它把后端约定式加载、前端 Dashboard、Schema CRUD 页面、model 类型和类型扩展放到同一个 npm 包里，项目只需要按目录补充自己的 `app/`、`model/`、`frontend/`。
 
-组件预览地址：https://t-c-s-p.allomg.qzz.io/ui-components
+预览 & 文档地址：https://t-c-s-p.allomg.qzz.io/preview
 
 ## 安装
 
@@ -12,33 +12,10 @@ pnpm add @_tc/template-core
 
 要求：
 
-- Node.js >= 18
+- Node.js >= 22.13.0
 - pnpm >= 8
 - 使用内置前端时，需要安装 peer dependencies；完整清单以包内 `package.json` 的 `peerDependencies` 为准，包括 Koa、React、Vite、路由、状态、表单和 UI 相关依赖。
 
-## 可选：给项目 AI 助手的文档与 Skill
-
-如果你在项目中让 AI 助手协助开发，可以让它优先读取 npm 包内的 `AGENT_README.md`。安装后的路径通常是 `node_modules/@_tc/template-core/AGENT_README.md`。这份文档面向“协助使用 TemplateCore 的 AI 助手”，覆盖公开入口、最小启动、目录约定、model 配置、前端使用和构建方式。
-
-包内附带两份 Agent Skill，本质是可复用的 Agent 指令包，采用渐进式披露（SKILL.md + reference/）结构。
-
-| Skill | 用途 |
-| --- | --- |
-| `tc-generator` | 按 TemplateCore 约定生成项目、model 配置、Schema CRUD、controller 和 router。 |
-| `tc-component-usage-skills` | 指导 Agent 选用和正确使用内置 React 组件库（Button、Form、DataTable、Modal 等）。 |
-
-如果你的 Agent 支持本地 skills 目录，可以从已安装的 npm 包复制安装。以 Codex 为例：
-
-```bash
-mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
-cp -R node_modules/@_tc/template-core/.skills/tc-generator "${CODEX_HOME:-$HOME/.codex}/skills/tc-generator"
-cp -R node_modules/@_tc/template-core/.skills/tc-component-usage-skills "${CODEX_HOME:-$HOME/.codex}/skills/tc-component-usage-skills"
-```
-
-安装后重启对应 Agent，让新 skill 生效。使用时可以直接说”用 tc-generator 生成一个商品管理模块”或”用 tc-component-usage-skills 帮我写一个带搜索的分页表格”。
-
-其他 Agent 如果不支持自动安装 skill，也可以直接读取 `.skills/tc-generator/SKILL.md` 或 `.skills/tc-component-usage-skills/SKILL.md`，再按需读取 `reference/` 下的参考文件。
-
 ## 快速使用
 
 项目建议结构：
@@ -186,6 +163,24 @@ http://localhost:9000/dash?projk=demo
 
 `projk` 对应 `model/{modelKey}/project/{projectKey}.ts` 里的 `projectKey`。
 
+## 内置功能
+
+- Koa 服务启动：`serverStart(options)`。
+- 约定式加载：自动加载 `config`、`extends`、`router-schema`、`service`、`controller`、`middlewares`、根级 `middleware`、`router`。
+- 双层 app：框架内置 `app/` 和项目 `app/` 一起加载。
+- 默认项目接口：
+  - `GET /api/project/model_list`
+  - `GET /api/project/list`
+  - `GET /api/project/:key`
+- React Dashboard：内置 `/dash` 页面入口。
+- 组件预览页面：内置 `/ui-components` 页面，用于查看和测试框架内置的 UI 组件。
+- 菜单渲染：支持 `schema`、`custom`、`iframe`、`sidebar`。
+- Schema CRUD：根据 `model` 中的 `schemaConfig` 生成搜索、表格、新增、编辑、详情。
+- 内置 UI 组件：提供丰富的 React 组件库，详见下方"内置 UI 组件"章节。
+- API 中间件：错误处理、静态资源、body parser、项目上下文、接口签名、参数校验。
+- 前端构建：扫描框架和项目的 `frontend/**/*.entry.{ts,tsx,js,jsx}`，输出服务端可渲染的 `.entry.tpl`，并写入 `FEBuildKey` 供 HTML ETag 缓存失效使用。
+- 类型扩展：支持扩展 SchemaForm、SchemaTable 单元格渲染组件、CallCom、KoaApp。
+
 ## 常用公开入口
 
 完整 exports 以发布包内 `package.json` 为准，除下表外还包含 `./fe/main`、`./fe/common/request`、`./fe/*`、`./fe/rc/*`、`./fe/rc/hooks` 等子路径。
@@ -245,1961 +240,1966 @@ export const demoRouter = ((app, router) => {
 }) satisfies RouterFN
 ```
 
-## 样式与 Tailwind V4
+## model 数据如何配置
 
-使用内置前端或 UI 组件时，需要引入包内样式。默认 `@_tc/template-core/fe` 的 `initApp` 会经过源码入口 `frontend/src/main.tsx` 引入 `frontend/src/main.css`；如果项目侧自定义入口、只使用 `fe/rc` 组件，或希望样式入口更明确，建议显式引入：
+`model` 是后台菜单、项目和 Schema 页面的数据源。框架会读取：
 
-```ts
-// frontend/xxx/xxx.entry.tsx
-import '@_tc/template-core/fe/tailwind_ui.css'
+```text
+model/{modelKey}/mode.ts
+model/{modelKey}/project/{projectKey}.ts
 ```
 
-如果项目有自己的全局样式入口，也可以在 CSS 中引入：
+`mode.ts` 定义模型模板：
 
-```css
-/* frontend/main.css */
-@import "@_tc/template-core/fe/tailwind_ui.css";
+```ts
+import type { ModelDataType } from '@_tc/template-core/model'
 
-/* 扫描项目源码 */
-@source "./**/*.{js,ts,jsx,tsx}";
-@source "../model/**/*.{js,ts,jsx,tsx}";
+const model: ModelDataType = {
+  mode: 'MB',
+  name: '商品后台',
+  desc: '商品管理',
+  icon: '',
+  homePage: '/_sidebar_/product?projk=demo',
+  menuLayout: 'left',
+  menu: [
+    {
+      key: 'product',
+      name: '商品列表',
+      menuType: 'module',
+      moduleType: 'schema',
+      schemaConfig: {
+        api: '/api/product',
+        schema: {
+          type: 'object',
+          properties: {
+            product_id: {
+              type: 'string',
+              label: '商品 ID',
+              tableOption: { width: 160 },
+              detailPanelOption: {},
+              editFormOption: {
+                comType: 'input',
+                disabled: true,
+              },
+            },
+            product_name: {
+              type: 'string',
+              label: '商品名称',
+              tableOption: {},
+              searchOption: { comType: 'input' },
+              createFormOption: { comType: 'input' },
+              editFormOption: { comType: 'input' },
+              detailPanelOption: {},
+            },
+            price: {
+              type: 'number',
+              label: '价格',
+              tableOption: {},
+              createFormOption: { comType: 'inputNumber' },
+              editFormOption: { comType: 'inputNumber' },
+              detailPanelOption: {},
+            },
+          },
+          required: ['product_name'],
+        },
+        componentConfig: {
+          createForm: {
+            title: '新增商品',
+            saveBtnText: '创建',
+          },
+          editForm: {
+            title: '编辑商品',
+            saveBtnText: '保存',
+            fetchKey: 'product_id',
+          },
+          detailPanel: {
+            title: '商品详情',
+            fetchKey: 'product_id',
+          },
+        },
+        tableConfig: {
+          headerButtons: [
+            {
+              label: '新增',
+              eventKey: 'callComponent',
+              variant: 'primary',
+              eventOption: { comName: 'createForm' },
+            },
+          ],
+          rowButtons: [
+            {
+              label: '编辑',
+              eventKey: 'callComponent',
+              eventOption: { comName: 'editForm' },
+            },
+            {
+              label: '详情',
+              eventKey: 'callComponent',
+              eventOption: { comName: 'detailPanel' },
+            },
+            {
+              label: '删除',
+              eventKey: 'remove',
+              eventOption: {
+                params: {
+                  product_id: '$schema::product_id',
+                },
+              },
+            },
+          ],
+        },
+      },
+    },
+  ],
+}
+
+export default model
 ```
 
-Tailwind V4 默认会忽略 `node_modules` 和 `.gitignore` 中的文件。如果没有使用上面的 `tailwind_ui.css`，或者项目侧构建链路绕过了 TemplateCore 的样式入口，需要手动把包加入 Tailwind 扫描：
+`name`、`desc`、`icon`、`homePage` 都是可选项。Dashboard 页头标题优先使用 `desc`，没有时回退到 `name`；`icon` 可以是图片地址、图片路径、data image 或普通文本。未配置 `homePage` 时会自动跳到第一个可用菜单；配置时必须命中菜单生成的真实路由，左侧布局通常是 `/_sidebar_/{menuKey}`，顶部布局通常是 `/{menuKey}`。
 
-```css
-/* frontend/main.css */
-@import "tailwindcss";
+`project/demo.ts` 定义项目覆盖：
 
-@source "./**/*.{js,ts,jsx,tsx}";
-@source "../model/**/*.{js,ts,jsx,tsx}";
-@source "../node_modules/@_tc/template-core";
+```ts
+export default {
+  name: 'Demo 企业',
+  desc: 'Demo 企业商品后台',
+  homePage: '/_sidebar_/product?projk=demo',
+}
 ```
 
-VS Code 建议安装官方 Tailwind CSS IntelliSense 插件，并在工作区 `.vscode/settings.json` 指向项目 CSS 入口：
+合并规则：
 
-```json
-{
-  "tailwindCSS.experimental.configFile": "frontend/main.css",
-  "files.associations": {
-    "*.css": "tailwindcss"
-  },
-  "css.lint.unknownAtRules": "ignore"
+- `project` 会继承同目录上层 `mode`。
+- 对象递归合并，`project` 覆盖 `mode`。
+- 数组按 `key` 合并：同 key 覆盖，不同 key 新增。
+- `model/index.ts` 或 `model/index.js` 会被 loader 跳过。
+
+### model 数组合并示例
+
+假设 `mode.ts` 定义了两个菜单项：
+
+```ts
+// model/product/mode.ts
+export default {
+  name: '商品后台',
+  menu: [
+    {
+      key: 'product',
+      name: '商品列表',
+      menuType: 'module',
+      moduleType: 'schema',
+      schemaConfig: {
+        api: '/api/product',
+        // ... 省略 schema 配置
+      },
+    },
+    {
+      key: 'category',
+      name: '分类管理',
+      menuType: 'module',
+      moduleType: 'schema',
+      schemaConfig: {
+        api: '/api/category',
+        // ... 省略 schema 配置
+      },
+    },
+  ],
 }
 ```
 
-多入口项目可以写成对象：
+`project/demo.ts` 可以：
 
-```json
-{
-  "tailwindCSS.experimental.configFile": {
-    "frontend/main.css": "frontend/**/*.{ts,tsx,js,jsx}",
-    "frontend/admin/admin.css": "frontend/admin/**/*.{ts,tsx,js,jsx}"
-  }
+```ts
+// model/product/project/demo.ts
+export default {
+  name: 'Demo 企业商品后台',
+  menu: [
+    // 1. 覆盖：修改 product 菜单的名称和配置
+    {
+      key: 'product',
+      name: 'Demo 商品',  // 覆盖 name
+      schemaConfig: {
+        api: '/api/demo/product',  // 覆盖 api
+      },
+    },
+    // 2. 新增：添加 brand 菜单
+    {
+      key: 'brand',
+      name: '品牌管理',
+      menuType: 'module',
+      moduleType: 'schema',
+      schemaConfig: {
+        api: '/api/brand',
+      },
+    },
+    // 3. 继承：category 菜单未在 project 中定义，会完整继承 mode 的配置
+  ],
 }
 ```
 
-## 内置功能
+合并后的结果：
 
-- Koa 服务启动：`serverStart(options)`。
-- 约定式加载：自动加载 `config`、`extends`、`router-schema`、`service`、`controller`、`middlewares`、根级 `middleware`、`router`。
-- 双层 app：框架内置 `app/` 和项目 `app/` 一起加载。
-- 默认项目接口：
-  - `GET /api/project/model_list`
-  - `GET /api/project/list`
-  - `GET /api/project/:key`
-- React Dashboard：内置 `/dash` 页面入口。
-- 组件预览页面：内置 `/ui-components` 页面，用于查看和测试框架内置的 UI 组件。
-- 菜单渲染：支持 `schema`、`custom`、`iframe`、`sidebar`。
-- Schema CRUD：根据 `model` 中的 `schemaConfig` 生成搜索、表格、新增、编辑、详情。
-- 内置 UI 组件：提供丰富的 React 组件库，详见下方"内置 UI 组件"章节。
-- API 中间件：错误处理、静态资源、body parser、项目上下文、接口签名、参数校验。
-- 前端构建：扫描框架和项目的 `frontend/**/*.entry.{ts,tsx,js,jsx}`，输出服务端可渲染的 `.entry.tpl`，并写入 `FEBuildKey` 供 HTML ETag 缓存失效使用。
-- 类型扩展：支持扩展 SchemaForm、SchemaTable 单元格渲染组件、CallCom、KoaApp。
+```ts
+{
+  name: 'Demo 企业商品后台',  // project 覆盖
+  menu: [
+    {
+      key: 'product',
+      name: 'Demo 商品',  // project 覆盖
+      menuType: 'module',  // mode 继承
+      moduleType: 'schema',  // mode 继承
+      schemaConfig: {
+        api: '/api/demo/product',  // project 覆盖
+        // schema 配置会递归合并
+      },
+    },
+    {
+      key: 'category',  // mode 完整继承
+      name: '分类管理',
+      menuType: 'module',
+      moduleType: 'schema',
+      schemaConfig: {
+        api: '/api/category',
+      },
+    },
+    {
+      key: 'brand',  // project 新增
+      name: '品牌管理',
+      menuType: 'module',
+      moduleType: 'schema',
+      schemaConfig: {
+        api: '/api/brand',
+      },
+    },
+  ],
+}
+```
 
-## 前端公共能力
+**关键点**：
+- 数组合并依赖 `key` 字段，确保每个菜单项都有唯一的 `key`
+- 同 `key` 的项会递归合并，不是简单替换
+- `project` 中未定义的项会完整继承 `mode` 的配置
 
-项目侧需要 TemplateCore 前端能力时，优先从 `@_tc/template-core/fe` 导入，不要直接依赖 `frontend/src/common/...`、`frontend/src/defaultPages/...`、`frontend/src/stores/...` 这类内部路径。
+## model 数据如何引用
+
+后端可以直接调用 loader：
 
 ```ts
-import {
-  api,
-  apiFreezerStore,
-  addLanguageResources,
-  AsyncSelect,
-  clearAuthToken,
-  eventsInfo,
-  getCurrentLanguage,
-  getFallbackLanguage,
-  FreezeState,
-  get,
-  getSupportedLanguages,
-  getAuthToken,
-  LanguageSwitch,
-  localKeyMap,
-  merge,
-  modeStore,
-  post,
-  renderImportComponent,
-  registerFrontendI18nResources,
-  request,
-  schemaEventBus,
-  schemaStore,
-  setFallbackLanguage,
-  setLanguage,
-  setResources,
-  setAuthToken,
-  ThemeSwitch,
-  t,
-  useApiFreezer,
-  useModeStore,
-  useSchemaStore,
-  useText,
-} from '@_tc/template-core/fe'
+import { modelLoader, type KoaApp } from '@_tc/template-core'
 
-import type {
-  BaseResponse,
-  CallComComponentsMap,
-  CallComRenderer,
-  DashComponentsMap,
-  DashRouteGuard,
-  DashRoutesExtender,
-  FormFieldSchema,
-  ApiFreezerRequestMatcher,
-  PageParams,
-  PageResponse,
-  RequestConfig,
-  ResponseConfig,
-  SchemaTableRenderComponent,
-  SchemaTableRenderComponentsMap,
-  SchemaFormComponentsMap,
-  SchemaFormNamespace,
-  SelectProps,
-} from '@_tc/template-core/fe'
+export default (app: KoaApp) => {
+  const modelList = modelLoader(app)
+  return modelList
+}
 ```
 
-当前公共入口包含：
+前端默认不直接读文件，而是通过内置接口获取：
 
-| 类型 | 导出内容 |
-| --- | --- |
-| 应用启动 | `initApp` |
-| 内置前端组件 | `AsyncSelect`、`LanguageSwitch`、`ThemeSwitch` |
-| 组件加载辅助 | `renderImportComponent` |
-| Dash 扩展类型 | `DashRoutesExtender`、`DashRoutesContext`、`DashComponentsMap`、`DashHeaderUserAreaProps`、`DashRouteGuard` |
-| SchemaPage 类型 | `CallComComponentsMap`、`CallComRenderer`、`SchemaTableRenderComponent`、`SchemaTableRenderComponentsMap` |
-| SchemaForm 类型 | `FormFieldSchema`、`SchemaFormComponentsMap`、`SchemaFormNamespace`、`SelectProps` |
-| 请求方法 | `api`、`request`、`get`、`post`、`put`、`patch`、`del` |
-| 请求类型 | `BaseResponse`、`PageParams`、`PageResponse`、`RequestConfig`、`ResponseConfig`、`AxiosError` |
-| RAF 风格计时器 | `rafSetTimeout`、`rafSetInterval`、`rafClearTimeout`、`rafClearInterval`、`clearRafTimer`、`RafTimerId`、`RafTimerCallback` |
-| Token 工具 | `getAuthToken`、`setAuthToken`、`clearAuthToken`、`localKeyMap` |
-| 多语言工具 | `useText`、`getText`、`t`、`registerFrontendI18nResources`、`addLanguageResources`、`setLanguage`、`setFallbackLanguage`、`setResources`、`getCurrentLanguage`、`getFallbackLanguage`、`getSupportedLanguages` |
-| 请求冻结 | `apiFreezerStore`、`useApiFreezer`、`FreezeState`、`ApiFreezerRequestMatcher` |
-| 事件工具 | `eventsInfo`、`merge` |
-| 共享状态 | `modeStore`、`useModeStore`、`schemaStore`、`useSchemaStore`、`schemaEventBus` |
+```text
+GET /api/project/model_list
+GET /api/project/list?projk=demo
+GET /api/project/demo
+```
 
-`modeStore` 管项目模型和当前项目数据，`schemaStore` 管当前 Schema 页面的 schema/cache，`schemaEventBus` 用来在 Search、Table、CallCom 之间通信。
+Dashboard 会根据 `projk` 请求 `/api/project/:key`，再按返回的 `menu` 渲染页面。
 
-`renderImportComponent` 封装了 `React.lazy` + `Suspense`，默认会用页面骨架屏作为 fallback。`getAuthToken()`、`setAuthToken()` 和 `clearAuthToken()` 用于读写或清理本地短 token，`localKeyMap` 暴露对应的本地存储 key 常量。
+Schema 页面的接口约定：
 
-只使用请求层时，也可以从 `@_tc/template-core/fe/common/request` 导入 `api`、请求方法和请求类型；这是发布包显式子路径，不要下钻到 `frontend/src/common/request`。
+```text
+GET    {api}/list   -> 表格列表
+GET    {api}        -> 编辑/详情拉取，参数由 fetchKey 决定
+POST   {api}        -> 新增
+PUT    {api}        -> 编辑
+DELETE {api}        -> 删除
+```
 
-### 前端多语言
+`$schema::字段名` 表示从当前表格行读取字段值，常用于删除按钮参数。
 
-TemplateCore 前端通过 `@_tc/template-core/fe` 暴露 i18n 能力。框架内置中文、英文资源，但不会在普通自定义页面 import 前端入口时自动注册，避免非 Dashboard 页面把框架文案整包带入运行时资源。
+### 服务端兜底路由守卫
 
-默认 Dashboard 入口会自动调用 `registerFrontendI18nResources()`，所以 Dashboard、Schema CRUD、内置页头、语言切换等框架页面可以直接使用框架内置文案。自定义入口如果也要复用这些框架文案，需要在渲染前手动注册：
+项目可以创建 `app/router-guard.ts` 或 `app/router-guard.js`。它只在所有正常 `app/router/*` 路由都没有命中时执行。
 
 ```ts
-import { initApp, registerFrontendI18nResources } from '@_tc/template-core/fe'
+import type { Ctx, KoaApp } from '@_tc/template-core'
 
-initApp(App, {
-  beforeRender: async () => {
-    await registerFrontendI18nResources()
-  },
-})
-```
+export default (_app: KoaApp) => {
+  return (ctx: Ctx) => {
+    if (ctx.path.startsWith('/api/')) {
+      return {
+        status: 404,
+        body: { code: 404, message: `${ctx.path} not found` },
+      }
+    }
 
-项目可以继续追加自己的资源或新增语种。
+    return '/dash'
+  }
+}
+```
 
-**追加自定义语言资源**：
+返回字符串会 `ctx.redirect()`；返回 `{ status, body }` 会直接设置响应；无返回则使用框架默认兜底：API 路径返回 HTTP 200 + `{ code: 404, message }`，非 API 路径返回 HTTP 404 + `notFound`。
 
-```ts
-import { addLanguageResources } from '@_tc/template-core/fe'
+## 后端约定
 
-addLanguageResources('zh-CN', {
-  app: {
-    product: {
-      menu: '商品管理',
-      name: '商品名称',
-      create: '新增商品',
-      createTitle: '新增商品',
-    },
-  },
-})
+项目目录会按下面规则加载：
 
-addLanguageResources('en-US', {
-  app: {
-    product: {
-      menu: 'Products',
-      name: 'Product name',
-      create: 'Create product',
-      createTitle: 'Create product',
-    },
-  },
-})
+```text
+app/controller/**/*.(js|ts)      -> app.controller
+app/service/**/*.(js|ts)         -> app.service
+app/middlewares/**/*.(js|ts)     -> app.middlewares
+app/middleware.(js|ts)           -> 全局中间件编排，按框架 -> 项目顺序执行
+app/router/**/*.(js|ts)          -> Koa router
+app/router-schema/**/*.(js|ts)   -> app.routerSchema
+app/extends/*.(js|ts)            -> app.extends
+config/config.default.(js|ts)    -> app.config
+config/config.{env}.(js|ts)      -> app.config
+model/**/*.(js|ts)               -> 内置 project service 按需读取的项目模型配置
 ```
 
-**新增语种并切换**：
+内置扩展：
 
-```ts
-import { addLanguageResources, setLanguage } from '@_tc/template-core/fe'
+- `app.extends.$fetch`：Node 侧基于 `fetch` 的 axios 风格请求实例，支持 `get/post/put/patch/delete` 和 `create(config)`。
+- `app.extends.crypto`：Node 侧加密辅助方法，支持 base64url 编解码、HMAC 签名、签名 payload 和常量时间比较。
+- `app.extends.db`：默认 SQLite 框架数据库，提供 `getDBData/setDBData` 等通用数据方法。
 
-addLanguageResources('ja-JP', {
-  app: {
-    product: {
-      menu: '商品管理',
-    },
-  },
-})
+API controller 可以通过 `ctx.reqData` 读取统一请求参数：
 
-setLanguage('ja-JP')
+```ts
+const { query, body, headers, data } = ctx.reqData ?? {
+  query: {},
+  body: undefined,
+  headers: {},
+  data: {},
+}
 ```
 
-`addLanguageResources()` 用于追加或新增某个语种的文案，默认会深合并同语种资源；传 `{ merge: false }` 可以替换该语种资源。`setResources(resources, { merge: true })` 可批量合并多语种资源。`LanguageSwitch` 默认会把已注册语种加入选项；需要自定义展示文案时仍可传入 `options`。
+- `query` 来自 `ctx.query`。
+- `body` 来自 `ctx.request.body`。
+- `headers` 来自 `ctx.headers`。
+- `data` 是便捷合并层，当前按 `query -> body` 顺序合并；字段冲突时 body 覆盖 query。
 
-**覆盖组件内置文案**：
+`ctx.reqData` 只在 API 请求中由内置中间件注入，类型上是可选字段。router params 不在 `reqData` 里，仍然从 `ctx.params` 获取。
 
-UI 组件库内置文案也在同一份资源里，统一放在 `components` 命名空间下。项目侧可以覆盖已有文案，也可以给新增语种补齐组件文案：
+### 数据库扩展
 
-```ts
-import { addLanguageResources } from '@_tc/template-core/fe'
+默认 `app.extends.db` 使用 SQLite 保存数据，数据库文件位于项目根目录 `.template-core/template-core.sqlite`。可以在配置中调整路径：
 
-addLanguageResources('zh-CN', {
-  components: {
-    date: {
-      placeholder: '选择日期',
-      placeholderRange: '选择日期区间',
-      weekDays: ['日', '一', '二', '三', '四', '五', '六'],
-      monthFormat: 'yyyy年 M月',
-    },
-    tableSearch: {
-      search: '筛选',
-      reset: '清空',
-    },
+```ts
+// config/config.default.ts
+export default {
+  db: {
+    path: 'data/app.sqlite',
   },
-})
+}
 ```
 
-Date 组件除了文案，还依赖 `date-fns` locale 做月份格式化和周起止计算。新增非内置语种时同步注册：
+Controller 中使用：
 
 ```ts
-import { registerDateFnsLocale } from '@_tc/template-core/fe/rc/components/Date'
-import { ja } from 'date-fns/locale'
+import { baseFn, type ControllerFN, type Ctx } from '@_tc/template-core'
 
-registerDateFnsLocale('ja-JP', ja)
-```
+const getSettingController = ((app) => {
+  const BaseController = baseFn.baseControllerFn(app)
 
-React 组件 render 中使用 `useText()` 读取文案。它会订阅语言和资源变化，调用 `setLanguage()` 后组件会自动重渲染。
+  return class SettingController extends BaseController {
+    detail = async (ctx: Ctx) => {
+      const data = app.extends.db.getDBData('site-setting', {
+        namespace: 'setting',
+      })
 
-`useText()` / `getText()` 遇到 `$i18n::` 前缀会先去掉前缀再查语言资源；没有前缀时会直接把传入字符串作为 key 查询，查不到才原样返回：
+      this.success(ctx, data ?? {})
+    }
 
-```tsx
-import { useText } from '@_tc/template-core/fe'
+    save = async (ctx: Ctx) => {
+      app.extends.db.setDBData('site-setting', ctx.request.body, {
+        namespace: 'setting',
+      })
 
-function ProductTitle() {
-  const text = useText()
+      this.success(ctx, true)
+    }
+  }
+}) satisfies ControllerFN
 
-  return (
-    <>
-      <h1>{text('$i18n::app.product.menu')}</h1>
-      <span>{text('Plain title')}</span>
-    </>
-  )
-}
+export default getSettingController
 ```
 
-`getText()` 是普通函数，适合请求错误、日志、校验工具或事件回调等非 React 场景；它不会主动触发 React 组件重渲染。
+常用方法：
 
-资源注册时不写 `$i18n::` 前缀，配置中使用时才写：
+- `getDBData(key, options)`：读取 JSON 数据。
+- `setDBData(key, value, options)`：写入 JSON 数据。
+- `hasDBData(key, options)`：判断数据是否存在。
+- `deleteDBData(key, options)`：删除单条数据。
+- `listDBData(options)`：分页列出当前 namespace 下的数据。
+- `countDBData(options)` / `clearDBData(options)`：统计和清空当前 namespace。
+- `queryDB(sql, params)` / `runDB(sql, params)`：直接执行 SQLite SQL。
+- `transactionDB(handler)`：事务执行。
+- `closeDB()`：关闭连接。
 
-```ts
-const title = '$i18n::app.product.createTitle'
-```
+SQL 注入边界：
 
-**在 model / Schema 配置中使用**：
+- `getDBData`、`setDBData`、`deleteDBData`、`listDBData` 这类通用方法内部使用参数绑定，不需要手写 SQL。
+- `queryDB`、`runDB`、`getDBFirst` 是原始 SQL 入口，用户输入必须放到 `params`，不要拼接到 SQL 字符串里。
+- `execDB` 没有参数绑定能力，只建议用于固定 SQL，例如建表或迁移。
 
-```ts
-{
-  name: '$i18n::app.product.menu',
-  moduleType: 'schema',
-  schemaConfig: {
-    schema: {
-      type: 'object',
-      properties: {
-        name: {
-          type: 'string',
-          label: '$i18n::app.product.name',
-          minLength: 2,
-          createFormOption: {
-            comType: 'input',
-          },
-          tableOption: {},
-          searchOption: {},
-        },
-      },
-      required: ['name'],
-    },
-    tableConfig: {
-      headerButtons: [
-        {
-          label: '$i18n::app.product.create',
-          eventKey: 'callComponent',
-          eventOption: { comName: 'createForm' },
-        },
-      ],
-    },
-    componentConfig: {
-      createForm: {
-        title: '$i18n::app.product.createTitle',
-        saveBtnText: '$i18n::common.submit',
-      },
-    },
-  },
-}
-```
+### 加密扩展
 
-已支持 `$i18n::...` 的常用位置：
+`app.extends.crypto` 默认使用 `app.config.signKey` 作为签名密钥，适合生成登录 token、接口签名和安全比较。
 
-- 菜单名：`menu.name`
-- 项目标题：`projectInfo.desc` 或回退的 `projectInfo.name`
-- Schema 字段名：`schema.properties.*.label`
-- 表格按钮和行按钮：`headerButtons.*.label`、`rowButtons.*.label`
-- 弹窗、抽屉标题：`componentConfig.*.title`
-- 表单保存按钮：`componentConfig.*.saveBtnText`
-- 接口错误提示：`BaseResponse.message`
+常用方法：
 
-**切换语言**：
+- `base64urlEncode(value)`：把字符串或二进制数据编码为 base64url。
+- `base64urlDecode(value)`：把 base64url 解码回 UTF-8 字符串。
+- `base64urlDecodeToBuffer(value)`：把 base64url 解码回 Buffer。
+- `hmacSign(payload, options)`：对文本做 HMAC 签名，默认算法 `sha256`。
+- `safeEqual(left, right)`：常量时间比较字符串。
+- `createSignedPayload(payload, options)`：生成 `payload.signature` 形式的签名串。
+- `verifySignedPayload(token, options)`：验证并解析签名串，失败返回 `null`。
 
 ```ts
-import { i18nStore } from '@_tc/template-core/fe'
-
-i18nStore.getState().setLanguage('en-US')
-i18nStore.getState().setLanguage('zh-CN')
-```
+const token = app.extends.crypto.createSignedPayload({
+  account: 'admin',
+  exp: Date.now() + 1000 * 60 * 60 * 24 * 7,
+  iat: Date.now(),
+})
 
-默认会写入 localStorage，key 是 `tc_language`。刷新页面后会继续使用上次语言。
+const payload = app.extends.crypto.verifySignedPayload<{
+  account: string
+  exp: number
+  iat: number
+}>(token)
 
-项目页面可以直接使用语言选择组件：
+const same = app.extends.crypto.safeEqual('abc', 'abc')
+```
 
-```tsx
-import { LanguageSwitch } from '@_tc/template-core/fe'
+```ts
+// 推荐：参数绑定
+const users = app.extends.db.queryDB(
+  'SELECT * FROM user WHERE name = ?',
+  [ctx.query.name as string]
+)
 
-export function Toolbar() {
-  return <LanguageSwitch />
-}
+// 不推荐：拼接用户输入，有 SQL 注入风险
+const unsafeUsers = app.extends.db.queryDB(
+  `SELECT * FROM user WHERE name = '${ctx.query.name}'`
+)
 ```
 
-`LanguageSwitch` 默认提供 `zh-CN` 和 `en-US`，也支持传入 `options` 覆盖语言列表。组件当前是按钮 + 下拉菜单形态，`option.label` 支持 ReactNode，`buttonClassName` 可自定义触发按钮样式。组件内部会调用 `i18nStore.getState().setLanguage()`，因此会沿用 `tc_language` 的持久化行为。
+项目可以用自己的 `app/extends/db.ts` 覆盖默认实现。建议保留同一组方法名，这样 controller/service 调用方不用调整。
 
-**AJV 校验文案**：
+```ts
+// app/extends/db.ts
+import type { DB, DBFactory } from '@_tc/template-core'
 
-Schema 表单校验会把 AJV keyword 映射到内置语言 key，覆盖 `required`、`type`、`format`、`minimum`、`maximum`、`minLength`、`maxLength`、`pattern`、`enum`、`oneOf`、`anyOf` 等常见规则。
+interface DataOptions {
+  namespace?: string
+}
 
-非必填字段为空时会跳过 AJV 校验，空值包括 `undefined`、`null`、空字符串、空数组和空对象。
+const store = new Map<string, unknown>()
 
-如果需要扩展更多 AJV 文案，在源码项目中同步增加：
+const getDB = ((_app) => {
+  const toKey = (key: string, namespace = 'framework') => `${namespace}:${key}`
 
-1. `frontend/src/defaultPages/SchemaPage/utils/validator.ts` 的 `formatError()` 映射。
-2. `frontend/src/language/zh-CN.ts` 和 `frontend/src/language/en-US.ts` 文案。
-3. `frontend/src/language/index.ts` 的 `frontendLangKeys`。
+  const db = {
+    dbPath: 'memory',
+    getDBConnection: () => {
+      throw new Error('memory db 没有底层 SQLite connection')
+    },
+    execDB: () => undefined,
+    runDB: () => ({ changes: 0, lastInsertRowid: 0 }),
+    queryDB: <T extends object = Record<string, unknown>>() => [] as T[],
+    getDBFirst: <T extends object = Record<string, unknown>>() => undefined as T | undefined,
+    transactionDB: <T>(handler: (db: DB) => T) => handler(db),
+    getDBData: <T = unknown>(key: string, options?: DataOptions) => {
+      return store.get(toKey(key, options?.namespace)) as T | undefined
+    },
+    getDBDataRecord: <T = unknown>(key: string, options?: DataOptions) => {
+      const value = store.get(toKey(key, options?.namespace)) as T | undefined
+      if (value === undefined) return undefined
 
-### 前端主题切换
+      return {
+        key,
+        value,
+        namespace: options?.namespace ?? 'framework',
+        createdAt: '',
+        updatedAt: '',
+      }
+    },
+    setDBData: <T = unknown>(key: string, value: T, options?: DataOptions) => {
+      store.set(toKey(key, options?.namespace), value)
+      return { changes: 1, lastInsertRowid: 0 }
+    },
+    hasDBData: (key: string, options?: DataOptions) => {
+      return store.has(toKey(key, options?.namespace))
+    },
+    deleteDBData: (key: string, options?: DataOptions) => {
+      return store.delete(toKey(key, options?.namespace))
+    },
+    listDBData: <T = unknown>(options?: DataOptions) => {
+      const namespace = options?.namespace ?? 'framework'
 
-项目页面可以使用 `ThemeSwitch` 切换浅色和深色模式：
+      return Array.from(store.entries())
+        .filter(([key]) => key.startsWith(`${namespace}:`))
+        .map(([key, value]) => ({
+          key: key.slice(namespace.length + 1),
+          value: value as T,
+          namespace,
+          createdAt: '',
+          updatedAt: '',
+        }))
+    },
+    countDBData: () => store.size,
+    clearDBData: () => {
+      const size = store.size
+      store.clear()
+      return size
+    },
+    closeDB: () => undefined,
+  } satisfies DB
 
-```tsx
-import { ThemeSwitch } from '@_tc/template-core/fe'
+  return db
+}) satisfies DBFactory
 
-export function Toolbar() {
-  return <ThemeSwitch />
-}
+export default getDB
 ```
 
-`ThemeSwitch` 会切换 `document.documentElement` 上的 `dark` class，并同步 `color-scheme`。默认写入 localStorage，key 是 `tc_theme`。刷新页面后会优先读取本地主题；没有本地主题时，读取当前根节点是否已有 `dark` class。默认 Dashboard 会在渲染前调用 `initThemeMode()`，让已保存主题尽早生效。
+Controller 示例：
 
-常用参数：
+```ts
+import { baseFn, type ControllerFN, type Ctx } from '@_tc/template-core'
 
-| 参数 | 说明 |
-| --- | --- |
-| `value` / `onChange` | 受控模式，值为 `light` 或 `dark`。 |
-| `defaultValue` | 非受控初始主题。 |
-| `showLabel` | 是否展示当前主题文本。 |
-| `persist` | 是否写入 localStorage，默认 `true`。 |
-| `storageKey` | 自定义本地存储 key，默认 `tc_theme`。 |
-
-如需在自定义入口或组件外手动初始化/切换主题，可以从 `@_tc/template-core/fe` 导入主题工具：
+const getProductController = ((app) => {
+  const BaseController = baseFn.baseControllerFn(app)
 
-```ts
-import { applyThemeMode, getCurrentThemeMode, initThemeMode, themeSwitchStorageKey } from '@_tc/template-core/fe'
+  return class ProductController extends BaseController {
+    list = async (ctx: Ctx) => {
+      this.success(ctx, {
+        data: [],
+        page: 1,
+        pageSize: 10,
+        total: 0,
+      })
+    }
+  }
+}) satisfies ControllerFN
 
-initThemeMode()
-applyThemeMode('dark', true)
+export default getProductController
 ```
 
-RAF 风格计时器由 `@tc/common/rafTimer` 提供，浏览器优先使用 `requestAnimationFrame`，缺少 RAF 时自动降级到 `setTimeout`。
-
-`@_tc/template-core/fe/rc` 和 `@_tc/template-core/fe/rc/hooks` 也会随发布包提供对应 UI 与 hooks 入口；hooks 汇总入口包含 `useBreadcrumb`、`useExecuteOnce`、`useInit`、`useLanguage`、`usePagination`、`useRefState`、`useWatch`。
-
-`useRefState` 支持可选的 `delayTiming` 参数，传入大于 0 的值时会延迟 state 提交，并复用 `@tc/common/rafTimer` 的浏览器优先、Node/SSR 自动降级计时器实现。
-
-### 前端请求封装详解
-
-框架内置的请求封装基于 `@tc/common/http`，底层使用原生 `fetch` API，实现了类似 Axios 的接口和拦截器机制，提供了签名、鉴权、错误处理等能力。
-
-**基础配置**：
-- `BASE_URL`：固定为 `/api`
-- `timeout`：15000ms（15秒）
-- `credentials`：`'include'`，支持跨域携带 cookie
-- `window._signKey`：由服务端页面模板从 `app.config.signKey` 注入
-- 默认会先设置 `Content-Type: application/json`；如果是上传文件、`FormData` 或其他内容类型，请在请求配置里显式覆盖
-
-**请求拦截器**：
-
-每个请求会自动添加以下 headers：
+Router 示例：
 
 ```ts
-{
-  's_t': '当前时间戳',
-  's_sign': 'md5(签名密钥_时间戳)',
-  'projk': '当前项目 key（从 localStorage 读取）',
-  'Authorization': 'Bearer token（如果已登录）'
+import type { KoaApp, Router } from '@_tc/template-core'
+
+export default (app: KoaApp, router: Router) => {
+  router.get('/api/product/list', app.controller.product.list)
 }
 ```
 
-`Authorization` 默认对应服务端配置 `config.auth.ATKey`。前端本地 token 存在 `localStorage.auth_token`，项目 key 存在 `localStorage.p_J_k`；刷新 token header 名预留为 `config.auth.RTKey`，默认是 `RT`。
-
-**签名机制**：
-- 签名密钥：服务端从 `app.config.signKey` 读取，并在页面渲染时注入为 `window._signKey`
-- 签名算法：`md5(签名密钥_${时间戳})`
-- 服务端会在非 local 环境下校验签名和时间戳
-
-**响应拦截器**：
-
-- **401 处理**：自动清空 token 并跳转到 `/login`
-- **错误提取**：自动从响应中提取 `message`、`msg` 或 `errors` 字段
-- **超时处理**：请求超时会返回当前语言的超时提示
-- **网络错误**：网络异常会返回当前语言的网络错误提示
+路由挂载顺序：
 
-**使用示例**：
+- 每个 `app/router/*.ts` 文件都会获得独立的 `koa-router` 实例。
+- 可以通过 `router.level = number` 控制挂载顺序，数值越小越早挂载。
+- 默认 `level` 是 `0`，框架兜底 router 是 `99`。
+- 通配、兜底、重定向类路由建议设置较大的 `level`，避免抢先匹配项目 API。
 
 ```ts
-import { api, get, post, put, del } from '@_tc/template-core/fe'
-import type { BaseResponse, RequestConfig, ResponseConfig } from '@_tc/template-core/fe'
-
-// GET 请求
-const data = await get('/product/list', { page: 1, pageSize: 10 })
-
-// POST 请求
-const result = await post('/product', { name: '商品名称', price: 100 })
-
-// PUT 请求
-await put('/product', { id: 1, name: '新名称' })
+import type { KoaApp, Router } from '@_tc/template-core'
 
-// DELETE 请求
-await del('/product', { id: 1 })
+export default (app: KoaApp, router: Router) => {
+  router.level = 10
+  router.get('/api/fallback/:id', app.controller.fallback.detail)
+}
 ```
 
-如果希望把请求能力单独拆出来导入：
+## 前端公共能力
+
+项目侧需要 TemplateCore 前端能力时，优先从 `@_tc/template-core/fe` 导入，不要直接依赖 `frontend/src/common/...`、`frontend/src/defaultPages/...`、`frontend/src/stores/...` 这类内部路径。
 
 ```ts
 import {
   api,
+  apiFreezerStore,
+  addLanguageResources,
+  AsyncSelect,
+  clearAuthToken,
+  eventsInfo,
+  getCurrentLanguage,
+  getFallbackLanguage,
+  FreezeState,
   get,
+  getSupportedLanguages,
+  getAuthToken,
+  LanguageSwitch,
+  localKeyMap,
+  merge,
+  modeStore,
   post,
+  renderImportComponent,
+  registerFrontendI18nResources,
   request,
-} from '@_tc/template-core/fe/common/request'
+  schemaEventBus,
+  schemaStore,
+  setFallbackLanguage,
+  setLanguage,
+  setResources,
+  setAuthToken,
+  ThemeSwitch,
+  t,
+  useApiFreezer,
+  useModeStore,
+  useSchemaStore,
+  useText,
+} from '@_tc/template-core/fe'
+
 import type {
   BaseResponse,
+  CallComComponentsMap,
+  CallComRenderer,
+  DashComponentsMap,
+  DashRouteGuard,
+  DashRoutesExtender,
+  FormFieldSchema,
+  ApiFreezerRequestMatcher,
+  PageParams,
+  PageResponse,
   RequestConfig,
   ResponseConfig,
-} from '@_tc/template-core/fe/common/request'
+  SchemaTableRenderComponent,
+  SchemaTableRenderComponentsMap,
+  SchemaFormComponentsMap,
+  SchemaFormNamespace,
+  SelectProps,
+} from '@_tc/template-core/fe'
 ```
 
-**请求冻结器**：
-
-请求冻结器用于在某段流程中暂停普通 API 请求，典型场景是 RT 刷新 token：刷新期间冻结其它请求，刷新接口本身走白名单放行，刷新完成后再解冻并回放队列。
+当前公共入口包含：
 
-冻结器只在 `Freeze` 状态拦截请求；`Hibernation` 和 `Thawing` 状态都会直接放行。解冻时会按最多 4 个并发回放已冻结的请求；相同序列化参数的请求只会实际发送一次，多个调用方共享同一份响应或错误。
+| 类型 | 导出内容 |
+| --- | --- |
+| 应用启动 | `initApp` |
+| 内置前端组件 | `AsyncSelect`、`LanguageSwitch`、`ThemeSwitch` |
+| 组件加载辅助 | `renderImportComponent` |
+| Dash 扩展类型 | `DashRoutesExtender`、`DashRoutesContext`、`DashComponentsMap`、`DashHeaderUserAreaProps`、`DashRouteGuard` |
+| SchemaPage 类型 | `CallComComponentsMap`、`CallComRenderer`、`SchemaTableRenderComponent`、`SchemaTableRenderComponentsMap` |
+| SchemaForm 类型 | `FormFieldSchema`、`SchemaFormComponentsMap`、`SchemaFormNamespace`、`SelectProps` |
+| 请求方法 | `api`、`request`、`get`、`post`、`put`、`patch`、`del` |
+| 请求类型 | `BaseResponse`、`PageParams`、`PageResponse`、`RequestConfig`、`ResponseConfig`、`AxiosError` |
+| RAF 风格计时器 | `rafSetTimeout`、`rafSetInterval`、`rafClearTimeout`、`rafClearInterval`、`clearRafTimer`、`RafTimerId`、`RafTimerCallback` |
+| Token 工具 | `getAuthToken`、`setAuthToken`、`clearAuthToken`、`localKeyMap` |
+| 多语言工具 | `useText`、`getText`、`t`、`registerFrontendI18nResources`、`addLanguageResources`、`setLanguage`、`setFallbackLanguage`、`setResources`、`getCurrentLanguage`、`getFallbackLanguage`、`getSupportedLanguages` |
+| 请求冻结 | `apiFreezerStore`、`useApiFreezer`、`FreezeState`、`ApiFreezerRequestMatcher` |
+| 事件工具 | `eventsInfo`、`merge` |
+| 共享状态 | `modeStore`、`useModeStore`、`schemaStore`、`useSchemaStore`、`schemaEventBus` |
 
-```ts
-import { apiFreezerStore } from '@_tc/template-core/fe'
+`modeStore` 管项目模型和当前项目数据，`schemaStore` 管当前 Schema 页面的 schema/cache，`schemaEventBus` 用来在 Search、Table、CallCom 之间通信。
 
-const { freezing, thawing, setRequestWhitelist } = apiFreezerStore.getState()
+`renderImportComponent` 封装了 `React.lazy` + `Suspense`，默认会用页面骨架屏作为 fallback。`getAuthToken()`、`setAuthToken()` 和 `clearAuthToken()` 用于读写或清理本地短 token，`localKeyMap` 暴露对应的本地存储 key 常量。
 
-setRequestWhitelist([
-  '/auth/refresh',
-  /^\/auth\//,
-  (api) => api.includes('/refresh-token'),
-])
+只使用请求层时，也可以从 `@_tc/template-core/fe/common/request` 导入 `api`、请求方法和请求类型；这是发布包显式子路径，不要下钻到 `frontend/src/common/request`。
 
-freezing()
+### 前端多语言
 
-try {
-  await refreshToken()
-} finally {
-  thawing()
-}
-```
+TemplateCore 前端通过 `@_tc/template-core/fe` 暴露 i18n 能力。框架内置中文、英文资源，但不会在普通自定义页面 import 前端入口时自动注册，避免非 Dashboard 页面把框架文案整包带入运行时资源。
 
-白名单支持三种 matcher：
+默认 Dashboard 入口会自动调用 `registerFrontendI18nResources()`，所以 Dashboard、Schema CRUD、内置页头、语言切换等框架页面可以直接使用框架内置文案。自定义入口如果也要复用这些框架文案，需要在渲染前手动注册：
 
-- `string`：精确匹配 API 路径
-- `RegExp`：正则匹配 API 路径
-- `(api, params) => boolean`：自定义判断，`params` 是请求函数收到的完整参数
+```ts
+import { initApp, registerFrontendI18nResources } from '@_tc/template-core/fe'
 
-**注意事项**：
-- `get` 和 `del` 方法的参数会自动转为 query string
-- `post`、`put`、`patch` 方法的参数会作为 request body
-- 所有请求方法都会自动处理错误，无需手动 try-catch（除非需要自定义错误处理）
-- 底层使用原生 `fetch` API，但提供了类似 Axios 的拦截器和配置接口
+initApp(App, {
+  beforeRender: async () => {
+    await registerFrontendI18nResources()
+  },
+})
+```
 
-## 内置 UI 组件
+项目可以继续追加自己的资源或新增语种。
 
-框架通过 `@_tc/template-core/fe/rc` 提供了丰富的 React 组件库，可在项目中直接使用。
+**追加自定义语言资源**：
 
-### 基础组件
+```ts
+import { addLanguageResources } from '@_tc/template-core/fe'
 
-| 组件 | 用途 | 导入路径 |
-| --- | --- | --- |
-| `Button` | 按钮组件，支持多种样式和尺寸 | `@_tc/template-core/fe/rc` |
-| `Input` | 输入框组件，支持清空、右侧附加内容和密码显隐 | `@_tc/template-core/fe/rc` |
-| `InputNumber` | 数字输入框组件 | `@_tc/template-core/fe/rc` |
-| `Textarea` | 多行文本输入框组件 | `@_tc/template-core/fe/rc` |
-| `Select` | 下拉选择组件，支持单选和多选 | `@_tc/template-core/fe/rc` |
-| `Search` | 搜索输入组件 | `@_tc/template-core/fe/rc` |
-| `TreeSelect` | 树形选择组件 | `@_tc/template-core/fe/rc` |
-| `Dropdown` | 下拉菜单组件 | `@_tc/template-core/fe/rc` |
-| `DatePicker` | 日期选择器 | `@_tc/template-core/fe/rc` |
-| `Upload` | 文件上传组件 | `@_tc/template-core/fe/rc` |
-| `FileUpload` | 通用文件上传组件 | `@_tc/template-core/fe/rc` |
-| `ImageUpload` | 图片上传组件 | `@_tc/template-core/fe/rc` |
-| `ImagePreview` | 图片预览组件 | `@_tc/template-core/fe/rc` |
-| `Checkbox` | 复选框组件 | `@_tc/template-core/fe/rc` |
-| `Radio` | 单选框组件 | `@_tc/template-core/fe/rc` |
-| `Switch` | 开关组件 | `@_tc/template-core/fe/rc` |
+addLanguageResources('zh-CN', {
+  app: {
+    product: {
+      menu: '商品管理',
+      name: '商品名称',
+      create: '新增商品',
+      createTitle: '新增商品',
+    },
+  },
+})
 
-### 表单组件
+addLanguageResources('en-US', {
+  app: {
+    product: {
+      menu: 'Products',
+      name: 'Product name',
+      create: 'Create product',
+      createTitle: 'Create product',
+    },
+  },
+})
+```
 
-| 组件 | 用途 | 导入路径 |
-| --- | --- | --- |
-| `Form` | 表单容器组件 | `@_tc/template-core/fe/rc` |
-| `SchemaForm` | 配置驱动的表单组件，根据 schema 自动生成表单 | `@_tc/template-core/fe/rc` |
-| `FormItem` | 表单项组件 | `@_tc/template-core/fe/rc` |
+**新增语种并切换**：
 
-### 数据展示组件
+```ts
+import { addLanguageResources, setLanguage } from '@_tc/template-core/fe'
 
-| 组件 | 用途 | 导入路径 |
-| --- | --- | --- |
-| `DataTable` | 数据表格组件，支持分页、排序、筛选 | `@_tc/template-core/fe/rc` |
-| `Table` | 表格组件（含表头、列配置等子组件） | `@_tc/template-core/fe/rc` |
-| `TableSearch` | 表格搜索组件，配合 DataTable 使用 | `@_tc/template-core/fe/rc` |
-| `Pagination` | 分页组件 | `@_tc/template-core/fe/rc` |
-| `Breadcrumb` | 面包屑导航组件 | `@_tc/template-core/fe/rc` |
-| `Calendar` | 日历组件 | `@_tc/template-core/fe/rc` |
-| `TimePicker` | 时间选择器组件 | `@_tc/template-core/fe/rc` |
-| `Skeleton` | 骨架屏加载占位组件 | `@_tc/template-core/fe/rc` |
-
-### 反馈组件
-
-| 组件 | 用途 | 导入路径 |
-| --- | --- | --- |
-| `Modal` | 模态框组件 | `@_tc/template-core/fe/rc` |
-| `Drawer` | 抽屉组件 | `@_tc/template-core/fe/rc` |
-| `message` | 消息提示方法 | `@_tc/template-core/fe/rc` |
-| `Notification` | 通知组件 | `@_tc/template-core/fe/rc` |
-| `ConfirmDialog` | 确认对话框组件 | `@_tc/template-core/fe/rc` |
-| `Popup` | 弹出层组件 | `@_tc/template-core/fe/rc` |
-| `Tooltip` | 文字提示组件 | `@_tc/template-core/fe/rc` |
-| `Overlay` | 页面遮罩层组件 | `@_tc/template-core/fe/rc` |
-| `Loading` | 加载状态组件 | `@_tc/template-core/fe/rc` |
-
-### 布局组件
-
-| 组件 | 用途 | 导入路径 |
-| --- | --- | --- |
-| `Layout` | 页面布局组件 | `@_tc/template-core/fe/rc` |
-| `Card` | 卡片容器组件 | `@_tc/template-core/fe/rc` |
-| `Tabs` | 标签页组件 | `@_tc/template-core/fe/rc` |
-| `Menu` | 菜单组件（含 MenuItem 等子组件） | `@_tc/template-core/fe/rc` |
-| `Label` | 标签组件 | `@_tc/template-core/fe/rc` |
-
-### 按钮组件
+addLanguageResources('ja-JP', {
+  app: {
+    product: {
+      menu: '商品管理',
+    },
+  },
+})
 
-| 组件 | 用途 | 导入路径 |
-| --- | --- | --- |
-| `Button` | 通用按钮组件 | `@_tc/template-core/fe/rc` |
-| `AsynchronousButton` | 异步按钮组件，支持加载状态 | `@_tc/template-core/fe/rc` |
-| `SubmitButton` | 表单提交按钮组件 | `@_tc/template-core/fe/rc` |
-| `ActionBtn` | 操作按钮组件 | `@_tc/template-core/fe/rc` |
+setLanguage('ja-JP')
+```
 
-### 使用示例
+`addLanguageResources()` 用于追加或新增某个语种的文案，默认会深合并同语种资源；传 `{ merge: false }` 可以替换该语种资源。`setResources(resources, { merge: true })` 可批量合并多语种资源。`LanguageSwitch` 默认会把已注册语种加入选项；需要自定义展示文案时仍可传入 `options`。
 
-```tsx
-import { Button, Input, Select, Modal, DataTable } from '@_tc/template-core/fe/rc'
+**覆盖组件内置文案**：
 
-function MyComponent() {
-  return (
-    <div>
-      <Button variant="primary" onClick={() => console.log('clicked')}>
-        点击我
-      </Button>
+UI 组件库内置文案也在同一份资源里，统一放在 `components` 命名空间下。项目侧可以覆盖已有文案，也可以给新增语种补齐组件文案：
 
-      <Input placeholder="请输入内容" />
-      <Input type="password" placeholder="请输入密码" />
+```ts
+import { addLanguageResources } from '@_tc/template-core/fe'
 
-      <Select
-        options={[
-          { label: '选项1', value: '1' },
-          { label: '选项2', value: '2' },
-        ]}
-      />
-    </div>
-  )
-}
+addLanguageResources('zh-CN', {
+  components: {
+    date: {
+      placeholder: '选择日期',
+      placeholderRange: '选择日期区间',
+      weekDays: ['日', '一', '二', '三', '四', '五', '六'],
+      monthFormat: 'yyyy年 M月',
+    },
+    tableSearch: {
+      search: '筛选',
+      reset: '清空',
+    },
+  },
+})
 ```
 
-**注意**：
-- 所有组件都支持 TypeScript 类型提示
-- 组件样式基于 Tailwind CSS V4
-- 详细的组件 API 和示例可以访问 `/ui-components` 页面查看
-
-## 后端约定
+Date 组件除了文案，还依赖 `date-fns` locale 做月份格式化和周起止计算。新增非内置语种时同步注册：
 
-项目目录会按下面规则加载：
+```ts
+import { registerDateFnsLocale } from '@_tc/template-core/fe/rc/components/Date'
+import { ja } from 'date-fns/locale'
 
-```text
-app/controller/**/*.(js|ts)      -> app.controller
-app/service/**/*.(js|ts)         -> app.service
-app/middlewares/**/*.(js|ts)     -> app.middlewares
-app/middleware.(js|ts)           -> 全局中间件编排，按框架 -> 项目顺序执行
-app/router/**/*.(js|ts)          -> Koa router
-app/router-schema/**/*.(js|ts)   -> app.routerSchema
-app/extends/*.(js|ts)            -> app.extends
-config/config.default.(js|ts)    -> app.config
-config/config.{env}.(js|ts)      -> app.config
-model/**/*.(js|ts)               -> 内置 project service 按需读取的项目模型配置
+registerDateFnsLocale('ja-JP', ja)
 ```
 
-内置扩展：
+React 组件 render 中使用 `useText()` 读取文案。它会订阅语言和资源变化，调用 `setLanguage()` 后组件会自动重渲染。
 
-- `app.extends.$fetch`：Node 侧基于 `fetch` 的 axios 风格请求实例，支持 `get/post/put/patch/delete` 和 `create(config)`。
-- `app.extends.crypto`：Node 侧加密辅助方法，支持 base64url 编解码、HMAC 签名、签名 payload 和常量时间比较。
-- `app.extends.db`：默认 SQLite 框架数据库，提供 `getDBData/setDBData` 等通用数据方法。
+`useText()` / `getText()` 遇到 `$i18n::` 前缀会先去掉前缀再查语言资源；没有前缀时会直接把传入字符串作为 key 查询，查不到才原样返回：
 
-API controller 可以通过 `ctx.reqData` 读取统一请求参数：
+```tsx
+import { useText } from '@_tc/template-core/fe'
 
-```ts
-const { query, body, headers, data } = ctx.reqData ?? {
-  query: {},
-  body: undefined,
-  headers: {},
-  data: {},
+function ProductTitle() {
+  const text = useText()
+
+  return (
+    <>
+      <h1>{text('$i18n::app.product.menu')}</h1>
+      <span>{text('Plain title')}</span>
+    </>
+  )
 }
 ```
 
-- `query` 来自 `ctx.query`。
-- `body` 来自 `ctx.request.body`。
-- `headers` 来自 `ctx.headers`。
-- `data` 是便捷合并层，当前按 `query -> body` 顺序合并；字段冲突时 body 覆盖 query。
+`getText()` 是普通函数，适合请求错误、日志、校验工具或事件回调等非 React 场景；它不会主动触发 React 组件重渲染。
 
-`ctx.reqData` 只在 API 请求中由内置中间件注入，类型上是可选字段。router params 不在 `reqData` 里，仍然从 `ctx.params` 获取。
+资源注册时不写 `$i18n::` 前缀，配置中使用时才写：
 
-### 数据库扩展
+```ts
+const title = '$i18n::app.product.createTitle'
+```
 
-默认 `app.extends.db` 使用 SQLite 保存数据，数据库文件位于项目根目录 `.template-core/template-core.sqlite`。可以在配置中调整路径：
+**在 model / Schema 配置中使用**：
 
 ```ts
-// config/config.default.ts
-export default {
-  db: {
-    path: 'data/app.sqlite',
+{
+  name: '$i18n::app.product.menu',
+  moduleType: 'schema',
+  schemaConfig: {
+    schema: {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          label: '$i18n::app.product.name',
+          minLength: 2,
+          createFormOption: {
+            comType: 'input',
+          },
+          tableOption: {},
+          searchOption: {},
+        },
+      },
+      required: ['name'],
+    },
+    tableConfig: {
+      headerButtons: [
+        {
+          label: '$i18n::app.product.create',
+          eventKey: 'callComponent',
+          eventOption: { comName: 'createForm' },
+        },
+      ],
+    },
+    componentConfig: {
+      createForm: {
+        title: '$i18n::app.product.createTitle',
+        saveBtnText: '$i18n::common.submit',
+      },
+    },
   },
 }
 ```
 
-Controller 中使用：
+已支持 `$i18n::...` 的常用位置：
 
-```ts
-import { baseFn, type ControllerFN, type Ctx } from '@_tc/template-core'
+- 菜单名：`menu.name`
+- 项目标题：`projectInfo.desc` 或回退的 `projectInfo.name`
+- Schema 字段名：`schema.properties.*.label`
+- 表格按钮和行按钮：`headerButtons.*.label`、`rowButtons.*.label`
+- 弹窗、抽屉标题：`componentConfig.*.title`
+- 表单保存按钮：`componentConfig.*.saveBtnText`
+- 接口错误提示：`BaseResponse.message`
 
-const getSettingController = ((app) => {
-  const BaseController = baseFn.baseControllerFn(app)
+**切换语言**：
 
-  return class SettingController extends BaseController {
-    detail = async (ctx: Ctx) => {
-      const data = app.extends.db.getDBData('site-setting', {
-        namespace: 'setting',
-      })
+```ts
+import { i18nStore } from '@_tc/template-core/fe'
 
-      this.success(ctx, data ?? {})
-    }
+i18nStore.getState().setLanguage('en-US')
+i18nStore.getState().setLanguage('zh-CN')
+```
 
-    save = async (ctx: Ctx) => {
-      app.extends.db.setDBData('site-setting', ctx.request.body, {
-        namespace: 'setting',
-      })
+默认会写入 localStorage，key 是 `tc_language`。刷新页面后会继续使用上次语言。
 
-      this.success(ctx, true)
-    }
-  }
-}) satisfies ControllerFN
+项目页面可以直接使用语言选择组件：
 
-export default getSettingController
+```tsx
+import { LanguageSwitch } from '@_tc/template-core/fe'
+
+export function Toolbar() {
+  return <LanguageSwitch />
+}
 ```
 
-常用方法：
+`LanguageSwitch` 默认提供 `zh-CN` 和 `en-US`，也支持传入 `options` 覆盖语言列表。组件当前是按钮 + 下拉菜单形态，`option.label` 支持 ReactNode，`buttonClassName` 可自定义触发按钮样式。组件内部会调用 `i18nStore.getState().setLanguage()`，因此会沿用 `tc_language` 的持久化行为。
 
-- `getDBData(key, options)`：读取 JSON 数据。
-- `setDBData(key, value, options)`：写入 JSON 数据。
-- `hasDBData(key, options)`：判断数据是否存在。
-- `deleteDBData(key, options)`：删除单条数据。
-- `listDBData(options)`：分页列出当前 namespace 下的数据。
-- `countDBData(options)` / `clearDBData(options)`：统计和清空当前 namespace。
-- `queryDB(sql, params)` / `runDB(sql, params)`：直接执行 SQLite SQL。
-- `transactionDB(handler)`：事务执行。
-- `closeDB()`：关闭连接。
+**AJV 校验文案**：
 
-SQL 注入边界：
+Schema 表单校验会把 AJV keyword 映射到内置语言 key，覆盖 `required`、`type`、`format`、`minimum`、`maximum`、`minLength`、`maxLength`、`pattern`、`enum`、`oneOf`、`anyOf` 等常见规则。
 
-- `getDBData`、`setDBData`、`deleteDBData`、`listDBData` 这类通用方法内部使用参数绑定，不需要手写 SQL。
-- `queryDB`、`runDB`、`getDBFirst` 是原始 SQL 入口，用户输入必须放到 `params`，不要拼接到 SQL 字符串里。
-- `execDB` 没有参数绑定能力，只建议用于固定 SQL，例如建表或迁移。
+非必填字段为空时会跳过 AJV 校验，空值包括 `undefined`、`null`、空字符串、空数组和空对象。
 
-### 加密扩展
+如果需要扩展更多 AJV 文案，在源码项目中同步增加：
 
-`app.extends.crypto` 默认使用 `app.config.signKey` 作为签名密钥，适合生成登录 token、接口签名和安全比较。
+1. `frontend/src/defaultPages/SchemaPage/utils/validator.ts` 的 `formatError()` 映射。
+2. `frontend/src/language/zh-CN.ts` 和 `frontend/src/language/en-US.ts` 文案。
+3. `frontend/src/language/index.ts` 的 `frontendLangKeys`。
 
-常用方法：
+### 前端主题切换
 
-- `base64urlEncode(value)`：把字符串或二进制数据编码为 base64url。
-- `base64urlDecode(value)`：把 base64url 解码回 UTF-8 字符串。
-- `base64urlDecodeToBuffer(value)`：把 base64url 解码回 Buffer。
-- `hmacSign(payload, options)`：对文本做 HMAC 签名，默认算法 `sha256`。
-- `safeEqual(left, right)`：常量时间比较字符串。
-- `createSignedPayload(payload, options)`：生成 `payload.signature` 形式的签名串。
-- `verifySignedPayload(token, options)`：验证并解析签名串，失败返回 `null`。
-
-```ts
-const token = app.extends.crypto.createSignedPayload({
-  account: 'admin',
-  exp: Date.now() + 1000 * 60 * 60 * 24 * 7,
-  iat: Date.now(),
-})
+项目页面可以使用 `ThemeSwitch` 切换浅色和深色模式：
 
-const payload = app.extends.crypto.verifySignedPayload<{
-  account: string
-  exp: number
-  iat: number
-}>(token)
+```tsx
+import { ThemeSwitch } from '@_tc/template-core/fe'
 
-const same = app.extends.crypto.safeEqual('abc', 'abc')
+export function Toolbar() {
+  return <ThemeSwitch />
+}
 ```
 
-```ts
-// 推荐：参数绑定
-const users = app.extends.db.queryDB(
-  'SELECT * FROM user WHERE name = ?',
-  [ctx.query.name as string]
-)
+`ThemeSwitch` 会切换 `document.documentElement` 上的 `dark` class，并同步 `color-scheme`。默认写入 localStorage，key 是 `tc_theme`。刷新页面后会优先读取本地主题；没有本地主题时，读取当前根节点是否已有 `dark` class。默认 Dashboard 会在渲染前调用 `initThemeMode()`，让已保存主题尽早生效。
 
-// 不推荐：拼接用户输入，有 SQL 注入风险
-const unsafeUsers = app.extends.db.queryDB(
-  `SELECT * FROM user WHERE name = '${ctx.query.name}'`
-)
-```
+常用参数：
 
-项目可以用自己的 `app/extends/db.ts` 覆盖默认实现。建议保留同一组方法名，这样 controller/service 调用方不用调整。
+| 参数 | 说明 |
+| --- | --- |
+| `value` / `onChange` | 受控模式，值为 `light` 或 `dark`。 |
+| `defaultValue` | 非受控初始主题。 |
+| `showLabel` | 是否展示当前主题文本。 |
+| `persist` | 是否写入 localStorage，默认 `true`。 |
+| `storageKey` | 自定义本地存储 key，默认 `tc_theme`。 |
+
+如需在自定义入口或组件外手动初始化/切换主题，可以从 `@_tc/template-core/fe` 导入主题工具：
 
 ```ts
-// app/extends/db.ts
-import type { DB, DBFactory } from '@_tc/template-core'
+import { applyThemeMode, getCurrentThemeMode, initThemeMode, themeSwitchStorageKey } from '@_tc/template-core/fe'
 
-interface DataOptions {
-  namespace?: string
-}
+initThemeMode()
+applyThemeMode('dark', true)
+```
 
-const store = new Map<string, unknown>()
+RAF 风格计时器由 `@tc/common/rafTimer` 提供，浏览器优先使用 `requestAnimationFrame`，缺少 RAF 时自动降级到 `setTimeout`。
 
-const getDB = ((_app) => {
-  const toKey = (key: string, namespace = 'framework') => `${namespace}:${key}`
+`@_tc/template-core/fe/rc` 和 `@_tc/template-core/fe/rc/hooks` 也会随发布包提供对应 UI 与 hooks 入口；hooks 汇总入口包含 `useBreadcrumb`、`useExecuteOnce`、`useInit`、`useLanguage`、`usePagination`、`useRefState`、`useWatch`。
 
-  const db = {
-    dbPath: 'memory',
-    getDBConnection: () => {
-      throw new Error('memory db 没有底层 SQLite connection')
-    },
-    execDB: () => undefined,
-    runDB: () => ({ changes: 0, lastInsertRowid: 0 }),
-    queryDB: <T extends object = Record<string, unknown>>() => [] as T[],
-    getDBFirst: <T extends object = Record<string, unknown>>() => undefined as T | undefined,
-    transactionDB: <T>(handler: (db: DB) => T) => handler(db),
-    getDBData: <T = unknown>(key: string, options?: DataOptions) => {
-      return store.get(toKey(key, options?.namespace)) as T | undefined
-    },
-    getDBDataRecord: <T = unknown>(key: string, options?: DataOptions) => {
-      const value = store.get(toKey(key, options?.namespace)) as T | undefined
-      if (value === undefined) return undefined
+`useRefState` 支持可选的 `delayTiming` 参数，传入大于 0 的值时会延迟 state 提交，并复用 `@tc/common/rafTimer` 的浏览器优先、Node/SSR 自动降级计时器实现。
 
-      return {
-        key,
-        value,
-        namespace: options?.namespace ?? 'framework',
-        createdAt: '',
-        updatedAt: '',
-      }
-    },
-    setDBData: <T = unknown>(key: string, value: T, options?: DataOptions) => {
-      store.set(toKey(key, options?.namespace), value)
-      return { changes: 1, lastInsertRowid: 0 }
-    },
-    hasDBData: (key: string, options?: DataOptions) => {
-      return store.has(toKey(key, options?.namespace))
-    },
-    deleteDBData: (key: string, options?: DataOptions) => {
-      return store.delete(toKey(key, options?.namespace))
-    },
-    listDBData: <T = unknown>(options?: DataOptions) => {
-      const namespace = options?.namespace ?? 'framework'
+### 前端请求封装详解
 
-      return Array.from(store.entries())
-        .filter(([key]) => key.startsWith(`${namespace}:`))
-        .map(([key, value]) => ({
-          key: key.slice(namespace.length + 1),
-          value: value as T,
-          namespace,
-          createdAt: '',
-          updatedAt: '',
-        }))
-    },
-    countDBData: () => store.size,
-    clearDBData: () => {
-      const size = store.size
-      store.clear()
-      return size
-    },
-    closeDB: () => undefined,
-  } satisfies DB
+框架内置的请求封装基于 `@tc/common/http`，底层使用原生 `fetch` API，实现了类似 Axios 的接口和拦截器机制，提供了签名、鉴权、错误处理等能力。
 
-  return db
-}) satisfies DBFactory
+**基础配置**：
+- `BASE_URL`：固定为 `/api`
+- `timeout`：15000ms（15秒）
+- `credentials`：`'include'`，支持跨域携带 cookie
+- `window._signKey`：由服务端页面模板从 `app.config.signKey` 注入
+- 默认会先设置 `Content-Type: application/json`；如果是上传文件、`FormData` 或其他内容类型，请在请求配置里显式覆盖
 
-export default getDB
+**请求拦截器**：
+
+每个请求会自动添加以下 headers：
+
+```ts
+{
+  's_t': '当前时间戳',
+  's_sign': 'md5(签名密钥_时间戳)',
+  'projk': '当前项目 key（从 localStorage 读取）',
+  'Authorization': 'Bearer token（如果已登录）'
+}
 ```
 
-Controller 示例：
+`Authorization` 默认对应服务端配置 `config.auth.ATKey`。前端本地 token 存在 `localStorage.auth_token`，项目 key 存在 `localStorage.p_J_k`；刷新 token header 名预留为 `config.auth.RTKey`，默认是 `RT`。
+
+**签名机制**：
+- 签名密钥：服务端从 `app.config.signKey` 读取，并在页面渲染时注入为 `window._signKey`
+- 签名算法：`md5(签名密钥_${时间戳})`
+- 服务端会在非 local 环境下校验签名和时间戳
+
+**响应拦截器**：
+
+- **401 处理**：自动清空 token 并跳转到 `/login`
+- **错误提取**：自动从响应中提取 `message`、`msg` 或 `errors` 字段
+- **超时处理**：请求超时会返回当前语言的超时提示
+- **网络错误**：网络异常会返回当前语言的网络错误提示
+
+**使用示例**：
 
 ```ts
-import { baseFn, type ControllerFN, type Ctx } from '@_tc/template-core'
+import { api, get, post, put, del } from '@_tc/template-core/fe'
+import type { BaseResponse, RequestConfig, ResponseConfig } from '@_tc/template-core/fe'
 
-const getProductController = ((app) => {
-  const BaseController = baseFn.baseControllerFn(app)
+// GET 请求
+const data = await get('/product/list', { page: 1, pageSize: 10 })
 
-  return class ProductController extends BaseController {
-    list = async (ctx: Ctx) => {
-      this.success(ctx, {
-        data: [],
-        page: 1,
-        pageSize: 10,
-        total: 0,
-      })
-    }
-  }
-}) satisfies ControllerFN
+// POST 请求
+const result = await post('/product', { name: '商品名称', price: 100 })
 
-export default getProductController
+// PUT 请求
+await put('/product', { id: 1, name: '新名称' })
+
+// DELETE 请求
+await del('/product', { id: 1 })
 ```
 
-Router 示例：
+如果希望把请求能力单独拆出来导入：
 
 ```ts
-import type { KoaApp, Router } from '@_tc/template-core'
-
-export default (app: KoaApp, router: Router) => {
-  router.get('/api/product/list', app.controller.product.list)
-}
+import {
+  api,
+  get,
+  post,
+  request,
+} from '@_tc/template-core/fe/common/request'
+import type {
+  BaseResponse,
+  RequestConfig,
+  ResponseConfig,
+} from '@_tc/template-core/fe/common/request'
 ```
 
-路由挂载顺序：
+**请求冻结器**：
 
-- 每个 `app/router/*.ts` 文件都会获得独立的 `koa-router` 实例。
-- 可以通过 `router.level = number` 控制挂载顺序，数值越小越早挂载。
-- 默认 `level` 是 `0`，框架兜底 router 是 `99`。
-- 通配、兜底、重定向类路由建议设置较大的 `level`，避免抢先匹配项目 API。
+请求冻结器用于在某段流程中暂停普通 API 请求，典型场景是 RT 刷新 token：刷新期间冻结其它请求，刷新接口本身走白名单放行，刷新完成后再解冻并回放队列。
+
+冻结器只在 `Freeze` 状态拦截请求；`Hibernation` 和 `Thawing` 状态都会直接放行。解冻时会按最多 4 个并发回放已冻结的请求；相同序列化参数的请求只会实际发送一次，多个调用方共享同一份响应或错误。
 
 ```ts
-import type { KoaApp, Router } from '@_tc/template-core'
+import { apiFreezerStore } from '@_tc/template-core/fe'
 
-export default (app: KoaApp, router: Router) => {
-  router.level = 10
-  router.get('/api/fallback/:id', app.controller.fallback.detail)
+const { freezing, thawing, setRequestWhitelist } = apiFreezerStore.getState()
+
+setRequestWhitelist([
+  '/auth/refresh',
+  /^\/auth\//,
+  (api) => api.includes('/refresh-token'),
+])
+
+freezing()
+
+try {
+  await refreshToken()
+} finally {
+  thawing()
 }
 ```
 
-## model 数据如何配置
+白名单支持三种 matcher：
 
-`model` 是后台菜单、项目和 Schema 页面的数据源。框架会读取：
+- `string`：精确匹配 API 路径
+- `RegExp`：正则匹配 API 路径
+- `(api, params) => boolean`：自定义判断，`params` 是请求函数收到的完整参数
 
-```text
-model/{modelKey}/mode.ts
-model/{modelKey}/project/{projectKey}.ts
-```
+**注意事项**：
+- `get` 和 `del` 方法的参数会自动转为 query string
+- `post`、`put`、`patch` 方法的参数会作为 request body
+- 所有请求方法都会自动处理错误，无需手动 try-catch（除非需要自定义错误处理）
+- 底层使用原生 `fetch` API，但提供了类似 Axios 的拦截器和配置接口
 
-`mode.ts` 定义模型模板：
+## 样式与 Tailwind V4
+
+使用内置前端或 UI 组件时，需要引入包内样式。默认 `@_tc/template-core/fe` 的 `initApp` 会经过源码入口 `frontend/src/main.tsx` 引入 `frontend/src/main.css`；如果项目侧自定义入口、只使用 `fe/rc` 组件，或希望样式入口更明确，建议显式引入：
 
 ```ts
-import type { ModelDataType } from '@_tc/template-core/model'
+// frontend/xxx/xxx.entry.tsx
+import '@_tc/template-core/fe/tailwind_ui.css'
+```
 
-const model: ModelDataType = {
-  mode: 'MB',
-  name: '商品后台',
-  desc: '商品管理',
-  icon: '',
-  homePage: '/_sidebar_/product?projk=demo',
-  menuLayout: 'left',
-  menu: [
-    {
-      key: 'product',
-      name: '商品列表',
-      menuType: 'module',
-      moduleType: 'schema',
-      schemaConfig: {
-        api: '/api/product',
-        schema: {
-          type: 'object',
-          properties: {
-            product_id: {
-              type: 'string',
-              label: '商品 ID',
-              tableOption: { width: 160 },
-              detailPanelOption: {},
-              editFormOption: {
-                comType: 'input',
-                disabled: true,
-              },
-            },
-            product_name: {
-              type: 'string',
-              label: '商品名称',
-              tableOption: {},
-              searchOption: { comType: 'input' },
-              createFormOption: { comType: 'input' },
-              editFormOption: { comType: 'input' },
-              detailPanelOption: {},
-            },
-            price: {
-              type: 'number',
-              label: '价格',
-              tableOption: {},
-              createFormOption: { comType: 'inputNumber' },
-              editFormOption: { comType: 'inputNumber' },
-              detailPanelOption: {},
-            },
-          },
-          required: ['product_name'],
-        },
-        componentConfig: {
-          createForm: {
-            title: '新增商品',
-            saveBtnText: '创建',
-          },
-          editForm: {
-            title: '编辑商品',
-            saveBtnText: '保存',
-            fetchKey: 'product_id',
-          },
-          detailPanel: {
-            title: '商品详情',
-            fetchKey: 'product_id',
-          },
-        },
-        tableConfig: {
-          headerButtons: [
-            {
-              label: '新增',
-              eventKey: 'callComponent',
-              variant: 'primary',
-              eventOption: { comName: 'createForm' },
-            },
-          ],
-          rowButtons: [
-            {
-              label: '编辑',
-              eventKey: 'callComponent',
-              eventOption: { comName: 'editForm' },
-            },
-            {
-              label: '详情',
-              eventKey: 'callComponent',
-              eventOption: { comName: 'detailPanel' },
-            },
-            {
-              label: '删除',
-              eventKey: 'remove',
-              eventOption: {
-                params: {
-                  product_id: '$schema::product_id',
-                },
-              },
-            },
-          ],
-        },
-      },
-    },
-  ],
+如果项目有自己的全局样式入口，也可以在 CSS 中引入：
+
+```css
+/* frontend/main.css */
+@import "@_tc/template-core/fe/tailwind_ui.css";
+
+/* 扫描项目源码 */
+@source "./**/*.{js,ts,jsx,tsx}";
+@source "../model/**/*.{js,ts,jsx,tsx}";
+```
+
+Tailwind V4 默认会忽略 `node_modules` 和 `.gitignore` 中的文件。如果没有使用上面的 `tailwind_ui.css`，或者项目侧构建链路绕过了 TemplateCore 的样式入口，需要手动把包加入 Tailwind 扫描：
+
+```css
+/* frontend/main.css */
+@import "tailwindcss";
+
+@source "./**/*.{js,ts,jsx,tsx}";
+@source "../model/**/*.{js,ts,jsx,tsx}";
+@source "../node_modules/@_tc/template-core";
+```
+
+VS Code 建议安装官方 Tailwind CSS IntelliSense 插件，并在工作区 `.vscode/settings.json` 指向项目 CSS 入口：
+
+```json
+{
+  "tailwindCSS.experimental.configFile": "frontend/main.css",
+  "files.associations": {
+    "*.css": "tailwindcss"
+  },
+  "css.lint.unknownAtRules": "ignore"
 }
+```
 
-export default model
+多入口项目可以写成对象：
+
+```json
+{
+  "tailwindCSS.experimental.configFile": {
+    "frontend/main.css": "frontend/**/*.{ts,tsx,js,jsx}",
+    "frontend/admin/admin.css": "frontend/admin/**/*.{ts,tsx,js,jsx}"
+  }
+}
 ```
 
-`name`、`desc`、`icon`、`homePage` 都是可选项。Dashboard 页头标题优先使用 `desc`，没有时回退到 `name`；`icon` 可以是图片地址、图片路径、data image 或普通文本。未配置 `homePage` 时会自动跳到第一个可用菜单；配置时必须命中菜单生成的真实路由，左侧布局通常是 `/_sidebar_/{menuKey}`，顶部布局通常是 `/{menuKey}`。
+## 内置 UI 组件
+
+框架通过 `@_tc/template-core/fe/rc` 提供了丰富的 React 组件库，可在项目中直接使用。
+
+### 基础组件
+
+| 组件 | 用途 | 导入路径 |
+| --- | --- | --- |
+| `Button` | 按钮组件，支持多种样式和尺寸 | `@_tc/template-core/fe/rc` |
+| `Input` | 输入框组件，支持清空、右侧附加内容和密码显隐 | `@_tc/template-core/fe/rc` |
+| `InputNumber` | 数字输入框组件 | `@_tc/template-core/fe/rc` |
+| `Textarea` | 多行文本输入框组件 | `@_tc/template-core/fe/rc` |
+| `Select` | 下拉选择组件，支持单选和多选 | `@_tc/template-core/fe/rc` |
+| `Search` | 搜索输入组件 | `@_tc/template-core/fe/rc` |
+| `TreeSelect` | 树形选择组件 | `@_tc/template-core/fe/rc` |
+| `Dropdown` | 下拉菜单组件 | `@_tc/template-core/fe/rc` |
+| `DatePicker` | 日期选择器 | `@_tc/template-core/fe/rc` |
+| `Upload` | 文件上传组件 | `@_tc/template-core/fe/rc` |
+| `FileUpload` | 通用文件上传组件 | `@_tc/template-core/fe/rc` |
+| `ImageUpload` | 图片上传组件 | `@_tc/template-core/fe/rc` |
+| `ImagePreview` | 图片预览组件 | `@_tc/template-core/fe/rc` |
+| `Checkbox` | 复选框组件 | `@_tc/template-core/fe/rc` |
+| `Radio` | 单选框组件 | `@_tc/template-core/fe/rc` |
+| `Switch` | 开关组件 | `@_tc/template-core/fe/rc` |
+
+### 表单组件
+
+| 组件 | 用途 | 导入路径 |
+| --- | --- | --- |
+| `Form` | 表单容器组件 | `@_tc/template-core/fe/rc` |
+| `SchemaForm` | 配置驱动的表单组件，根据 schema 自动生成表单 | `@_tc/template-core/fe/rc` |
+| `FormItem` | 表单项组件 | `@_tc/template-core/fe/rc` |
+
+### 数据展示组件
+
+| 组件 | 用途 | 导入路径 |
+| --- | --- | --- |
+| `DataTable` | 数据表格组件，支持分页、排序、筛选 | `@_tc/template-core/fe/rc` |
+| `Table` | 表格组件（含表头、列配置等子组件） | `@_tc/template-core/fe/rc` |
+| `TableSearch` | 表格搜索组件，配合 DataTable 使用 | `@_tc/template-core/fe/rc` |
+| `Pagination` | 分页组件 | `@_tc/template-core/fe/rc` |
+| `Breadcrumb` | 面包屑导航组件 | `@_tc/template-core/fe/rc` |
+| `Calendar` | 日历组件 | `@_tc/template-core/fe/rc` |
+| `TimePicker` | 时间选择器组件 | `@_tc/template-core/fe/rc` |
+| `Skeleton` | 骨架屏加载占位组件 | `@_tc/template-core/fe/rc` |
 
-`project/demo.ts` 定义项目覆盖：
+### 反馈组件
 
-```ts
-export default {
-  name: 'Demo 企业',
-  desc: 'Demo 企业商品后台',
-  homePage: '/_sidebar_/product?projk=demo',
-}
-```
+| 组件 | 用途 | 导入路径 |
+| --- | --- | --- |
+| `Modal` | 模态框组件 | `@_tc/template-core/fe/rc` |
+| `Drawer` | 抽屉组件 | `@_tc/template-core/fe/rc` |
+| `message` | 消息提示方法 | `@_tc/template-core/fe/rc` |
+| `Notification` | 通知组件 | `@_tc/template-core/fe/rc` |
+| `ConfirmDialog` | 确认对话框组件 | `@_tc/template-core/fe/rc` |
+| `Popup` | 弹出层组件 | `@_tc/template-core/fe/rc` |
+| `Tooltip` | 文字提示组件 | `@_tc/template-core/fe/rc` |
+| `Overlay` | 页面遮罩层组件 | `@_tc/template-core/fe/rc` |
+| `Loading` | 加载状态组件 | `@_tc/template-core/fe/rc` |
 
-合并规则：
+### 布局组件
 
-- `project` 会继承同目录上层 `mode`。
-- 对象递归合并，`project` 覆盖 `mode`。
-- 数组按 `key` 合并：同 key 覆盖，不同 key 新增。
-- `model/index.ts` 或 `model/index.js` 会被 loader 跳过。
+| 组件 | 用途 | 导入路径 |
+| --- | --- | --- |
+| `Layout` | 页面布局组件 | `@_tc/template-core/fe/rc` |
+| `Card` | 卡片容器组件 | `@_tc/template-core/fe/rc` |
+| `Tabs` | 标签页组件 | `@_tc/template-core/fe/rc` |
+| `Menu` | 菜单组件（含 MenuItem 等子组件） | `@_tc/template-core/fe/rc` |
+| `Label` | 标签组件 | `@_tc/template-core/fe/rc` |
 
-### model 数组合并示例
+### 按钮组件
 
-假设 `mode.ts` 定义了两个菜单项：
+| 组件 | 用途 | 导入路径 |
+| --- | --- | --- |
+| `Button` | 通用按钮组件 | `@_tc/template-core/fe/rc` |
+| `AsynchronousButton` | 异步按钮组件，支持加载状态 | `@_tc/template-core/fe/rc` |
+| `SubmitButton` | 表单提交按钮组件 | `@_tc/template-core/fe/rc` |
+| `ActionBtn` | 操作按钮组件 | `@_tc/template-core/fe/rc` |
 
-```ts
-// model/product/mode.ts
-export default {
-  name: '商品后台',
-  menu: [
-    {
-      key: 'product',
-      name: '商品列表',
-      menuType: 'module',
-      moduleType: 'schema',
-      schemaConfig: {
-        api: '/api/product',
-        // ... 省略 schema 配置
-      },
-    },
-    {
-      key: 'category',
-      name: '分类管理',
-      menuType: 'module',
-      moduleType: 'schema',
-      schemaConfig: {
-        api: '/api/category',
-        // ... 省略 schema 配置
-      },
-    },
-  ],
-}
-```
+### 使用示例
 
-`project/demo.ts` 可以：
+```tsx
+import { Button, Input, Select, Modal, DataTable } from '@_tc/template-core/fe/rc'
 
-```ts
-// model/product/project/demo.ts
-export default {
-  name: 'Demo 企业商品后台',
-  menu: [
-    // 1. 覆盖：修改 product 菜单的名称和配置
-    {
-      key: 'product',
-      name: 'Demo 商品',  // 覆盖 name
-      schemaConfig: {
-        api: '/api/demo/product',  // 覆盖 api
-      },
-    },
-    // 2. 新增：添加 brand 菜单
-    {
-      key: 'brand',
-      name: '品牌管理',
-      menuType: 'module',
-      moduleType: 'schema',
-      schemaConfig: {
-        api: '/api/brand',
-      },
-    },
-    // 3. 继承：category 菜单未在 project 中定义，会完整继承 mode 的配置
-  ],
-}
-```
+function MyComponent() {
+  return (
+    <div>
+      <Button variant="primary" onClick={() => console.log('clicked')}>
+        点击我
+      </Button>
 
-合并后的结果：
+      <Input placeholder="请输入内容" />
+      <Input type="password" placeholder="请输入密码" />
 
-```ts
-{
-  name: 'Demo 企业商品后台',  // project 覆盖
-  menu: [
-    {
-      key: 'product',
-      name: 'Demo 商品',  // project 覆盖
-      menuType: 'module',  // mode 继承
-      moduleType: 'schema',  // mode 继承
-      schemaConfig: {
-        api: '/api/demo/product',  // project 覆盖
-        // schema 配置会递归合并
-      },
-    },
-    {
-      key: 'category',  // mode 完整继承
-      name: '分类管理',
-      menuType: 'module',
-      moduleType: 'schema',
-      schemaConfig: {
-        api: '/api/category',
-      },
-    },
-    {
-      key: 'brand',  // project 新增
-      name: '品牌管理',
-      menuType: 'module',
-      moduleType: 'schema',
-      schemaConfig: {
-        api: '/api/brand',
-      },
-    },
-  ],
+      <Select
+        options={[
+          { label: '选项1', value: '1' },
+          { label: '选项2', value: '2' },
+        ]}
+      />
+    </div>
+  )
 }
 ```
 
-**关键点**：
-- 数组合并依赖 `key` 字段，确保每个菜单项都有唯一的 `key`
-- 同 `key` 的项会递归合并，不是简单替换
-- `project` 中未定义的项会完整继承 `mode` 的配置
-
-## model 数据如何引用
-
-后端可以直接调用 loader：
-
-```ts
-import { modelLoader, type KoaApp } from '@_tc/template-core'
+**注意**：
+- 所有组件都支持 TypeScript 类型提示
+- 组件样式基于 Tailwind CSS V4
+- 详细的组件 API 和示例可以访问 `/ui-components` 页面查看
 
-export default (app: KoaApp) => {
-  const modelList = modelLoader(app)
-  return modelList
-}
-```
+## 扩展自定义前端页面
 
-前端默认不直接读文件，而是通过内置接口获取：
+新增应用入口：
 
 ```text
-GET /api/project/model_list
-GET /api/project/list?projk=demo
-GET /api/project/demo
+frontend/admin/admin.entry.tsx
 ```
 
-Dashboard 会根据 `projk` 请求 `/api/project/:key`，再按返回的 `menu` 渲染页面。
+入口文件名必须包含 `.entry.`，构建器才会扫描。
 
-Schema 页面的接口约定：
+最小入口示例：
 
-```text
-GET    {api}/list   -> 表格列表
-GET    {api}        -> 编辑/详情拉取，参数由 fetchKey 决定
-POST   {api}        -> 新增
-PUT    {api}        -> 编辑
-DELETE {api}        -> 删除
-```
+```tsx
+// frontend/admin/admin.entry.tsx
+import { initApp } from '@_tc/template-core/fe'
+import type { ReactNode } from 'react'
 
-`$schema::字段名` 表示从当前表格行读取字段值，常用于删除按钮参数。
+const AdminApp = ({ children }: { children: ReactNode }) => (
+  <main>{children}</main>
+)
 
-### 服务端兜底路由守卫
+initApp(AdminApp, {
+  initModeData: false,
+})
+```
 
-项目可以创建 `app/router-guard.ts` 或 `app/router-guard.js`。它只在所有正常 `app/router/*` 路由都没有命中时执行。
+如果需要给页面加额外 `meta`、预连接资源或启动脚本，可以在入口同目录放 `.html` 插槽文件。这个文件不是完整 HTML，只能包含 `tc-slot` 块：
 
-```ts
-import type { Ctx, KoaApp } from '@_tc/template-core'
+```html
+<!-- frontend/admin/admin.html -->
+<!-- tc-slot:head -->
+<meta name="description" content="Admin Console" />
+<link rel="preconnect" href="https://example.com" />
+<!-- /tc-slot:head -->
 
-export default (_app: KoaApp) => {
-  return (ctx: Ctx) => {
-    if (ctx.path.startsWith('/api/')) {
-      return {
-        status: 404,
-        body: { code: 404, message: `${ctx.path} not found` },
-      }
-    }
+<!-- tc-slot:body-before-root -->
+<div id="boot-mask"></div>
+<!-- /tc-slot:body-before-root -->
 
-    return '/dash'
-  }
-}
+<!-- tc-slot:body-after-root -->
+<script>
+  window.__ADMIN_BOOT_TIME__ = Date.now()
+</script>
+<!-- /tc-slot:body-after-root -->
 ```
 
-返回字符串会 `ctx.redirect()`；返回 `{ status, body }` 会直接设置响应；无返回则使用框架默认兜底：API 路径返回 HTTP 200 + `{ code: 404, message }`，非 API 路径返回 HTTP 404 + `notFound`。
+命名规则：
 
-## 如何扩展组件
+```text
+frontend/admin/admin.entry.tsx
+frontend/admin/admin.html       yes
 
-### 扩展 Dashboard 顶部用户区域
+frontend/report/index.entry.tsx
+frontend/report/index.html      yes
+frontend/report/report.html     yes
+```
 
-项目可以创建 `frontend/extended/dash/components.tsx`，通过组件映射填充内置 Dashboard 页头右侧区域。
+不要在插槽文件里写 `<!DOCTYPE html>`、`<html>`、`<body>` 或 `<div id="root"></div>`。页面外壳由 TemplateCore 的 `app/view/entry.tpl` 统一生成，`window._basePath`、`window._projKey`、`window._signKey`、`window.appOptions` 也由它注入。
+
+扩展 Dashboard 路由：
 
 ```tsx
-// frontend/extended/dash/components.tsx
-import type { DashComponentsMap } from '@_tc/template-core/fe'
+// frontend/extended/dash/customRoutes.tsx
+import type { DashRoutesExtender } from '@_tc/template-core/fe'
+
+const extendDashRoutes: DashRoutesExtender = ({ topRoutes, sidebarRoutes }) => {
+  topRoutes.push({
+    path: 'custom-page',
+    component: <div>Custom Page</div>,
+  })
 
-const components = {
-  'HeaderView.userArea': ({ projectInfo }) => {
-    return <div>{projectInfo?.name}</div>
-  },
-} satisfies DashComponentsMap
+  sidebarRoutes.push({
+    path: 'custom-sidebar-page',
+    component: <div>Custom Sidebar Page</div>,
+  })
+}
 
-export default components
+export default extendDashRoutes
 ```
 
-当前支持的 Dashboard 组件扩展槽位：
+**路径规则说明**：
 
-- `HeaderView.userArea`：Dashboard 顶部右侧区域。
+- **topRoutes**：追加到 Dashboard 顶层路由，路径相对于 `/dash`
+  - 示例：`path: 'custom-page'` → 访问路径为 `/dash/custom-page`
+  - 不要写成 `/custom-page`，使用相对路径即可
 
-### 扩展 Dashboard 登录守卫
+- **sidebarRoutes**：追加到侧边栏容器的子路由，路径相对于 `/dash/_sidebar_`
+  - 示例：`path: 'custom-sidebar-page'` → 访问路径为 `/dash/_sidebar_/custom-sidebar-page`
+  - 适用于 `menuLayout: 'left'` 的项目
 
-项目可以创建 `frontend/extended/dash/routeGuard.ts`，用于在 Dashboard 内置 `homePage` / 首菜单重定向前做登录判断。
+model 中用 `custom` 菜单指向自定义路径：
 
 ```ts
-// frontend/extended/dash/routeGuard.ts
-import type { DashRouteGuard } from '@_tc/template-core/fe'
-
-const dashRouteGuard: DashRouteGuard = ({ isLoggedIn }) => {
-  if (!isLoggedIn) return '/login'
+{
+  key: 'custom',
+  name: '自定义页面',
+  menuType: 'module',
+  moduleType: 'custom',
+  customConfig: {
+    path: '/custom-page',  // 注意：这里使用完整路径，以 / 开头
+  },
 }
-
-export default dashRouteGuard
 ```
 
-返回值规则：
-
-- 返回 `string`：框架使用 `window.location.href` 跳转，登录页不需要在 Dash 路由下。
-- 返回非 `string`：中断 Dashboard 内置重定向，使用方可自行跳转或处理提示。
-- `DashRouteGuardResult` 是 `string | undefined`；`undefined`（包括已登录分支的隐式返回）也会打断 Dashboard 内置重定向。
-- 没有自定义 `routeGuard` 文件时，框架使用兜底空对象，不影响默认 Dashboard 重定向。
-
-### 扩展 SchemaForm 字段组件
-
-1. 声明字段类型。
-2. 注册运行时组件。
-3. 在 `model` 的 `createFormOption`、`editFormOption`、`searchOption` 中使用。
+## 前端构建 buildFE
 
-类型声明：
+开发构建：
 
 ```ts
-// typing/template-core.d.ts
-import '@_tc/template-core/fe/rc'
-import type { SelectProps } from '@_tc/template-core/fe/rc'
-
-declare module '@_tc/template-core/fe/rc' {
-  export namespace SchemaFormNamespace {
-    interface FieldTypes {
-      businessSelect: true
-    }
+import { buildFE } from '@_tc/template-core/bundler'
 
-    interface PropsMap {
-      businessSelect: SelectProps & {
-        requestUrl?: string
-        valueField?: string
-        labelField?: string
-      }
-    }
-  }
-}
+await buildFE('dev')
 ```
 
-运行时注册：
+生产构建：
 
 ```ts
-// frontend/extended/SchemaForm/data.ts
-import React from 'react'
-import type { SchemaFormComponentsMap } from '@_tc/template-core/fe/rc'
+await buildFE('prod')
+```
 
-const componentsMap = {
-  businessSelect: React.lazy(async () => ({
-    default: (await import('../../components/BusinessSelect')).BusinessSelect,
-  })),
-} satisfies SchemaFormComponentsMap
+默认输出到当前导入格式对应的框架静态目录，例如 `esm/app/public/dist` 或 `cjs/app/public/dist`。如果要输出到项目：
 
-export default componentsMap
+```ts
+await buildFE('prod', {
+  output: 'run',
+})
 ```
 
-model 中使用：
+也可以压缩最终模板输出：
 
 ```ts
-status: {
-  type: 'string',
-  label: '状态',
-  searchOption: {
-    comType: 'businessSelect',
-    requestUrl: '/api/status/options',
-    valueField: 'value',
-    labelField: 'label',
-  },
-}
+await buildFE('prod', {
+  minifyHtml: true,
+})
 ```
 
-### 扩展 SchemaPage CallCom
+构建完成后会在输出目录写入 `FEBuildKey`，服务端渲染 HTML 时会用它判断本地 HTML ETag 缓存是否需要清空。
 
-CallCom 是 SchemaPage 中的弹窗、抽屉、面板类组件。内置组件有：
+## Node/backend 构建 buildBE
 
-- `createForm`
-- `editForm`
-- `detailPanel`
+消费方 Node/backend 侧构建使用 `buildBE()`。它复用发布包内的 `scripts/vite-build/buildEntries`，只是提供消费方默认配置。
 
-声明配置类型：
+最小用法：
 
 ```ts
-// typing/template-core.d.ts
-import '@_tc/template-core/model'
+import { buildBE } from '@_tc/template-core/bundler'
 
-declare module '@_tc/template-core/model' {
-  export namespace CallComNamespace {
-    interface ConfigMap {
-      auditPanel: {
-        title: string
-        fetchKey: string
-        approveApi?: string
-      }
-    }
+await buildBE()
+```
 
-    interface OptionMap {
-      auditPanel: {
-        visible?: boolean
-      }
-    }
+消费方脚本示例：
+
+```js
+// scripts/build-be.mjs
+import { buildBE } from '@_tc/template-core/bundler'
+
+await buildBE({
+  rootDir: process.cwd(),
+  input: ['index.ts', 'index.js', 'app', 'config', 'model'],
+  outDir: 'dist',
+  format: 'cjs',
+  alias: {
+    '@app': './app',
+    '@model': './model',
+  },
+})
+```
+
+```json
+{
+  "scripts": {
+    "build:be": "node scripts/build-be.mjs"
   }
 }
 ```
 
-注册运行时组件：
+监听文件变化并重新构建：
 
-```ts
-// frontend/extended/SchemaPage/CallCom/data.ts
-import { lazy } from 'react'
-import type { CallComComponentsMap } from '@_tc/template-core/fe'
+```js
+// scripts/watch-be.mjs
+import chokidar from 'chokidar'
+import { buildBE } from '@_tc/template-core/bundler'
 
-const componentsMap = {
-  auditPanel: lazy(() => import('../../components/AuditPanel')),
-} satisfies CallComComponentsMap
+const input = ['index.ts', 'index.js', 'app', 'config', 'model']
 
-export default componentsMap
-```
+let building = false
+let pending = false
 
-组件示例：
+async function runBuild() {
+  if (building) {
+    pending = true
+    return
+  }
 
-```tsx
-// frontend/src/components/AuditPanel.tsx
-import { eventsInfo, merge, schemaEventBus } from '@_tc/template-core/fe'
+  building = true
 
-export default function AuditPanel(props: {
-  data: Record<string, unknown>
-  comName: 'auditPanel'
-}) {
-  const closeAndRefresh = () => {
-    schemaEventBus.getState().emitCom({
-      type: merge(eventsInfo.closeCom, eventsInfo.initTable),
+  try {
+    console.log('[buildBE] building...')
+    await buildBE({
+      rootDir: process.cwd(),
+      input,
+      outDir: 'dist',
+      format: 'cjs',
+      alias: {
+        '@app': './app',
+        '@model': './model',
+      },
     })
-  }
+    console.log('[buildBE] done')
+  } catch (error) {
+    console.error('[buildBE] failed')
+    console.error(error)
+  } finally {
+    building = false
 
-  return (
-    <div>
-      <div>审核对象：{String(props.data.id ?? '')}</div>
-      <button onClick={closeAndRefresh}>完成</button>
-    </div>
-  )
+    if (pending) {
+      pending = false
+      await runBuild()
+    }
+  }
 }
-```
-
-model 中使用：
 
-```ts
-componentConfig: {
-  auditPanel: {
-    title: '审核',
-    fetchKey: 'id',
-    approveApi: '/api/audit/approve',
-  },
-},
-tableConfig: {
-  rowButtons: [
-    {
-      label: '审核',
-      eventKey: 'callComponent',
-      eventOption: {
-        comName: 'auditPanel',
-      },
-    },
-  ],
-},
-```
+await runBuild()
 
-字段级配置使用 `${组件名}Option`：
+chokidar
+  .watch(input, {
+    ignored: ['dist/**', 'node_modules/**'],
+    ignoreInitial: true,
+  })
+  .on('all', async (_event, filePath) => {
+    console.log(`[buildBE] changed: ${filePath}`)
+    await runBuild()
+  })
+```
 
-```ts
-remark: {
-  type: 'string',
-  label: '备注',
-  auditPanelOption: {
-    visible: true,
+```json
+{
+  "scripts": {
+    "build:be": "node scripts/build-be.mjs",
+    "build:be:watch": "node scripts/watch-be.mjs"
   },
+  "devDependencies": {
+    "chokidar": "^4.0.3"
+  }
 }
 ```
 
-### 扩展 SchemaTable 单元格渲染组件
+默认会在当前工作目录构建这些入口：
 
-SchemaPage 表格列支持通过 `tableOption.renderComponent` 使用内置或自定义注册的渲染组件。内置组件：
+```ts
+['index.ts', 'index.js', 'app', 'config', 'model']
+```
 
-- `PreviewImage`：把当前单元格值渲染成图片预览；值是数组时直接作为图片列表，值是单个字符串时自动转成单图数组。
+不存在的默认入口会自动跳过；如果没有任何匹配源码，构建仍会失败。输出到 `dist`，格式为 `cjs`。默认 `outputStructure: "preserve"` 按源路径输出，`bundleDependencies: false` 会 external Node 内置模块和 npm 包，不会把依赖打进产物。`buildBE` 会按同一组 input 扫描并复制内置白名单资源扩展，主要覆盖 `app`、`config`、`model` 目录。
 
-直接使用内置组件：
+常见配置：
 
 ```ts
-cover: {
-  type: 'string',
-  label: '封面',
-  tableOption: {
-    renderComponent: 'PreviewImage',
-    renderComponentProps: {
-      width: 48,
-      height: 48,
-    },
+await buildBE({
+  input: ['app', 'config', 'model'],
+  outDir: 'dist',
+  format: ['es', 'cjs'],
+  alias: {
+    '@app': './app',
+    '@model': './model',
   },
-}
+})
 ```
 
-自定义渲染组件时，先声明 props 类型：
+如果需要声明文件：
 
 ```ts
-// typing/template-core.d.ts
-import '@_tc/template-core/model'
-
-declare module '@_tc/template-core/model' {
-  export namespace SchemaTableNamespace {
-    interface RenderComponentPropsMap {
-      PriceCell: {
-        value?: unknown
-        record?: Record<string, unknown>
-        rowIndex?: number
-        fieldKey?: string
-        currency?: string
-      }
-    }
-  }
-}
+await buildBE({
+  dts: {
+    outDir: 'types',
+    tsconfig: 'tsconfig.json',
+  },
+})
 ```
 
-注册运行时组件：
+`buildEntries()` 底层默认生成 d.ts，但 `buildBE()` 默认关闭声明文件；需要时按上面这样显式传 `dts`。
+
+如果传入自定义 `input`，缺失路径默认会报错；需要跳过时显式打开：
 
 ```ts
-// frontend/extended/SchemaPage/SchemaTable/data.ts
-import { lazy } from 'react'
-import type { SchemaTableRenderComponentsMap } from '@_tc/template-core/fe'
+await buildBE({
+  input: ['app', 'config', 'model'],
+  allowMissingInput: true,
+})
+```
 
-const componentsMap = {
-  PriceCell: lazy(() => import('../../components/PriceCell')),
-} satisfies SchemaTableRenderComponentsMap
+## 如何扩展组件
 
-export default componentsMap
-```
+### 扩展 Dashboard 顶部用户区域
 
-组件会收到 `value`、`record`、`rowIndex`、`fieldKey`，以及 `renderComponentProps` 中的自定义参数：
+项目可以创建 `frontend/extended/dash/components.tsx`，通过组件映射填充内置 Dashboard 页头右侧区域。
 
 ```tsx
-// frontend/components/PriceCell.tsx
-export default function PriceCell(props: {
-  value?: unknown
-  currency?: string
-}) {
-  return <span>{props.currency ?? '¥'}{Number(props.value ?? 0).toFixed(2)}</span>
-}
-```
-
-model 中使用：
+// frontend/extended/dash/components.tsx
+import type { DashComponentsMap } from '@_tc/template-core/fe'
 
-```ts
-price: {
-  type: 'number',
-  label: '价格',
-  tableOption: {
-    renderComponent: 'PriceCell',
-    renderComponentProps: {
-      currency: '¥',
-    },
+const components = {
+  'HeaderView.userArea': ({ projectInfo }) => {
+    return <div>{projectInfo?.name}</div>
   },
-}
-```
-
-## 如何配置类型扩展
+} satisfies DashComponentsMap
 
-### tsconfig
+export default components
+```
 
-如果项目分了后端、前端、model 多个 TS 上下文，确保它们都 include 同一份声明文件：
+当前支持的 Dashboard 组件扩展槽位：
 
-```json
-{
-  "include": ["app/**/*", "model/**/*", "frontend/**/*", "typing/**/*.d.ts"]
-}
-```
+- `HeaderView.userArea`：Dashboard 顶部右侧区域。
 
-### SchemaForm 类型扩展
+### 扩展 Dashboard 登录守卫
 
-扩展目标：
+项目可以创建 `frontend/extended/dash/routeGuard.ts`，用于在 Dashboard 内置 `homePage` / 首菜单重定向前做登录判断。
 
 ```ts
-declare module '@_tc/template-core/fe/rc' {
-  export namespace SchemaFormNamespace {
-    interface FieldTypes {}
-    interface PropsMap {}
-  }
+// frontend/extended/dash/routeGuard.ts
+import type { DashRouteGuard } from '@_tc/template-core/fe'
+
+const dashRouteGuard: DashRouteGuard = ({ isLoggedIn }) => {
+  if (!isLoggedIn) return '/login'
 }
+
+export default dashRouteGuard
 ```
 
-- `FieldTypes` 用来增加字段类型名。
-- `PropsMap` 用来绑定该字段的 props 类型。
-- 类型声明只负责 TS 校验，运行时还必须在 `frontend/extended/SchemaForm/data.ts` 注册组件。
+返回值规则：
 
-### Model mode 类型扩展
+- 返回 `string`：框架使用 `window.location.href` 跳转，登录页不需要在 Dash 路由下。
+- 返回非 `string`：中断 Dashboard 内置重定向，使用方可自行跳转或处理提示。
+- `DashRouteGuardResult` 是 `string | undefined`；`undefined`（包括已登录分支的隐式返回）也会打断 Dashboard 内置重定向。
+- 没有自定义 `routeGuard` 文件时，框架使用兜底空对象，不影响默认 Dashboard 重定向。
 
-`mode` 和对应的数据结构一起扩展。内置 `MB` 对应管理后台菜单结构 `MBMenuType`。
+### 扩展 SchemaForm 字段组件
+
+1. 声明字段类型。
+2. 注册运行时组件。
+3. 在 `model` 的 `createFormOption`、`editFormOption`、`searchOption` 中使用。
+
+类型声明：
 
 ```ts
 // typing/template-core.d.ts
-import '@_tc/template-core/model'
+import '@_tc/template-core/fe/rc'
+import type { SelectProps } from '@_tc/template-core/fe/rc'
 
-declare module '@_tc/template-core/model' {
-  interface ModelModeMap {
-    portal: {
-      portalConfig: {
-        title: string
-        theme?: 'light' | 'dark'
+declare module '@_tc/template-core/fe/rc' {
+  export namespace SchemaFormNamespace {
+    interface FieldTypes {
+      businessSelect: true
+    }
+
+    interface PropsMap {
+      businessSelect: SelectProps & {
+        requestUrl?: string
+        valueField?: string
+        labelField?: string
       }
     }
   }
 }
 ```
 
-使用新 `mode`：
-
-```ts
-import type { ModelDataType } from '@_tc/template-core/model'
-
-const model: ModelDataType<'portal'> = {
-  mode: 'portal',
-  name: '门户',
-  desc: '门户配置',
-  homePage: '/',
-  portalConfig: {
-    title: 'Portal',
-    theme: 'light',
-  },
-}
-
-export default model
-```
-
-继续使用内置管理后台时：
+运行时注册：
 
 ```ts
-import type { ModelDataType } from '@_tc/template-core/model'
-
-const model: ModelDataType<'MB'> = {
-  mode: 'MB',
-  name: '商品后台',
-  desc: '商品管理',
-  homePage: '/_sidebar_/product?projk=demo',
-  menu: [],
-}
-```
-
-### CallCom 类型扩展
+// frontend/extended/SchemaForm/data.ts
+import React from 'react'
+import type { SchemaFormComponentsMap } from '@_tc/template-core/fe/rc'
 
-扩展目标：
+const componentsMap = {
+  businessSelect: React.lazy(async () => ({
+    default: (await import('../../components/BusinessSelect')).BusinessSelect,
+  })),
+} satisfies SchemaFormComponentsMap
 
-```ts
-declare module '@_tc/template-core/model' {
-  export namespace CallComNamespace {
-    interface ConfigMap {}
-    interface OptionMap {}
-  }
-}
+export default componentsMap
 ```
 
-- `ConfigMap` 对应 `schemaConfig.componentConfig.xxx`。
-- `OptionMap` 对应字段上的 `xxxOption`。
-- 运行时组件注册在 `frontend/extended/SchemaPage/CallCom/data.ts`。
-
-### SchemaTable 渲染组件类型扩展
-
-扩展目标：
+model 中使用：
 
 ```ts
-declare module '@_tc/template-core/model' {
-  export namespace SchemaTableNamespace {
-    interface RenderComponentPropsMap {}
-  }
+status: {
+  type: 'string',
+  label: '状态',
+  searchOption: {
+    comType: 'businessSelect',
+    requestUrl: '/api/status/options',
+    valueField: 'value',
+    labelField: 'label',
+  },
 }
 ```
 
-- `RenderComponentPropsMap` 的 key 对应 `tableOption.renderComponent`。
-- 运行时组件注册在 `frontend/extended/SchemaPage/SchemaTable/data.ts`。
-- 组件运行时会自动收到 `value`、`record`、`rowIndex`、`fieldKey`；`renderComponentProps` 只配置自定义参数。
+### 扩展 SchemaPage CallCom
 
-### KoaApp 类型扩展
+CallCom 是 SchemaPage 中的弹窗、抽屉、面板类组件。内置组件有：
 
-使用方推荐增强根包 `@_tc/template-core`：
+- `createForm`
+- `editForm`
+- `detailPanel`
+
+声明配置类型：
 
 ```ts
 // typing/template-core.d.ts
-import '@_tc/template-core'
-
-declare module '@_tc/template-core' {
-  namespace FrameworkAugment {
-    interface IServiceAugmented {
-      product: {
-        list(): Promise<unknown[]>
-      }
-    }
+import '@_tc/template-core/model'
 
-    interface IControllerAugmented {
-      product: {
-        list(ctx: import('@_tc/template-core').Ctx): Promise<void>
+declare module '@_tc/template-core/model' {
+  export namespace CallComNamespace {
+    interface ConfigMap {
+      auditPanel: {
+        title: string
+        fetchKey: string
+        approveApi?: string
       }
     }
 
-    interface IExtendsAugmented {
-      redis: {
-        get(key: string): Promise<string | null>
+    interface OptionMap {
+      auditPanel: {
+        visible?: boolean
       }
     }
-
-    interface IMiddlewaresAugmented {
-      auth: import('koa').Middleware
-    }
-
-    interface AppConfigAugmented {
-      authSecret: string
-    }
   }
 }
 ```
 
-使用：
+注册运行时组件：
 
 ```ts
-import type { KoaApp } from '@_tc/template-core'
+// frontend/extended/SchemaPage/CallCom/data.ts
+import { lazy } from 'react'
+import type { CallComComponentsMap } from '@_tc/template-core/fe'
 
-export default (app: KoaApp) => {
-  app.config.authSecret
-  app.service.product.list()
-  app.extends.$fetch.get('https://example.com/api')
-  app.extends.redis.get('token')
-}
+const componentsMap = {
+  auditPanel: lazy(() => import('../../components/AuditPanel')),
+} satisfies CallComComponentsMap
+
+export default componentsMap
 ```
 
-如果在 TemplateCore 仓库源码内部扩展，声明目标通常是内部别名 `@tc/core`；npm 使用方不要依赖 `@tc/*` 内部路径。
+组件示例：
 
-## 扩展自定义前端页面
+```tsx
+// frontend/src/components/AuditPanel.tsx
+import { eventsInfo, merge, schemaEventBus } from '@_tc/template-core/fe'
 
-新增应用入口：
+export default function AuditPanel(props: {
+  data: Record<string, unknown>
+  comName: 'auditPanel'
+}) {
+  const closeAndRefresh = () => {
+    schemaEventBus.getState().emitCom({
+      type: merge(eventsInfo.closeCom, eventsInfo.initTable),
+    })
+  }
 
-```text
-frontend/admin/admin.entry.tsx
+  return (
+    <div>
+      <div>审核对象：{String(props.data.id ?? '')}</div>
+      <button onClick={closeAndRefresh}>完成</button>
+    </div>
+  )
+}
 ```
 
-入口文件名必须包含 `.entry.`，构建器才会扫描。
-
-最小入口示例：
+model 中使用：
 
-```tsx
-// frontend/admin/admin.entry.tsx
-import { initApp } from '@_tc/template-core/fe'
-import type { ReactNode } from 'react'
+```ts
+componentConfig: {
+  auditPanel: {
+    title: '审核',
+    fetchKey: 'id',
+    approveApi: '/api/audit/approve',
+  },
+},
+tableConfig: {
+  rowButtons: [
+    {
+      label: '审核',
+      eventKey: 'callComponent',
+      eventOption: {
+        comName: 'auditPanel',
+      },
+    },
+  ],
+},
+```
 
-const AdminApp = ({ children }: { children: ReactNode }) => (
-  <main>{children}</main>
-)
+字段级配置使用 `${组件名}Option`：
 
-initApp(AdminApp, {
-  initModeData: false,
-})
+```ts
+remark: {
+  type: 'string',
+  label: '备注',
+  auditPanelOption: {
+    visible: true,
+  },
+}
 ```
 
-如果需要给页面加额外 `meta`、预连接资源或启动脚本，可以在入口同目录放 `.html` 插槽文件。这个文件不是完整 HTML，只能包含 `tc-slot` 块：
+### 扩展 SchemaTable 单元格渲染组件
 
-```html
-<!-- frontend/admin/admin.html -->
-<!-- tc-slot:head -->
-<meta name="description" content="Admin Console" />
-<link rel="preconnect" href="https://example.com" />
-<!-- /tc-slot:head -->
+SchemaPage 表格列支持通过 `tableOption.renderComponent` 使用内置或自定义注册的渲染组件。内置组件：
 
-<!-- tc-slot:body-before-root -->
-<div id="boot-mask"></div>
-<!-- /tc-slot:body-before-root -->
+- `PreviewImage`：把当前单元格值渲染成图片预览；值是数组时直接作为图片列表，值是单个字符串时自动转成单图数组。
 
-<!-- tc-slot:body-after-root -->
-<script>
-  window.__ADMIN_BOOT_TIME__ = Date.now()
-</script>
-<!-- /tc-slot:body-after-root -->
+直接使用内置组件：
+
+```ts
+cover: {
+  type: 'string',
+  label: '封面',
+  tableOption: {
+    renderComponent: 'PreviewImage',
+    renderComponentProps: {
+      width: 48,
+      height: 48,
+    },
+  },
+}
 ```
 
-命名规则：
+自定义渲染组件时，先声明 props 类型：
 
-```text
-frontend/admin/admin.entry.tsx
-frontend/admin/admin.html       yes
+```ts
+// typing/template-core.d.ts
+import '@_tc/template-core/model'
 
-frontend/report/index.entry.tsx
-frontend/report/index.html      yes
-frontend/report/report.html     yes
+declare module '@_tc/template-core/model' {
+  export namespace SchemaTableNamespace {
+    interface RenderComponentPropsMap {
+      PriceCell: {
+        value?: unknown
+        record?: Record<string, unknown>
+        rowIndex?: number
+        fieldKey?: string
+        currency?: string
+      }
+    }
+  }
+}
 ```
 
-不要在插槽文件里写 `<!DOCTYPE html>`、`<html>`、`<body>` 或 `<div id="root"></div>`。页面外壳由 TemplateCore 的 `app/view/entry.tpl` 统一生成，`window._basePath`、`window._projKey`、`window._signKey`、`window.appOptions` 也由它注入。
+注册运行时组件：
 
-扩展 Dashboard 路由：
+```ts
+// frontend/extended/SchemaPage/SchemaTable/data.ts
+import { lazy } from 'react'
+import type { SchemaTableRenderComponentsMap } from '@_tc/template-core/fe'
 
-```tsx
-// frontend/extended/dash/customRoutes.tsx
-import type { DashRoutesExtender } from '@_tc/template-core/fe'
+const componentsMap = {
+  PriceCell: lazy(() => import('../../components/PriceCell')),
+} satisfies SchemaTableRenderComponentsMap
 
-const extendDashRoutes: DashRoutesExtender = ({ topRoutes, sidebarRoutes }) => {
-  topRoutes.push({
-    path: 'custom-page',
-    component: <div>Custom Page</div>,
-  })
+export default componentsMap
+```
 
-  sidebarRoutes.push({
-    path: 'custom-sidebar-page',
-    component: <div>Custom Sidebar Page</div>,
-  })
-}
+组件会收到 `value`、`record`、`rowIndex`、`fieldKey`，以及 `renderComponentProps` 中的自定义参数：
 
-export default extendDashRoutes
+```tsx
+// frontend/components/PriceCell.tsx
+export default function PriceCell(props: {
+  value?: unknown
+  currency?: string
+}) {
+  return <span>{props.currency ?? '¥'}{Number(props.value ?? 0).toFixed(2)}</span>
+}
 ```
 
-**路径规则说明**：
+model 中使用：
 
-- **topRoutes**：追加到 Dashboard 顶层路由，路径相对于 `/dash`
-  - 示例：`path: 'custom-page'` → 访问路径为 `/dash/custom-page`
-  - 不要写成 `/custom-page`，使用相对路径即可
+```ts
+price: {
+  type: 'number',
+  label: '价格',
+  tableOption: {
+    renderComponent: 'PriceCell',
+    renderComponentProps: {
+      currency: '¥',
+    },
+  },
+}
+```
 
-- **sidebarRoutes**：追加到侧边栏容器的子路由，路径相对于 `/dash/_sidebar_`
-  - 示例：`path: 'custom-sidebar-page'` → 访问路径为 `/dash/_sidebar_/custom-sidebar-page`
-  - 适用于 `menuLayout: 'left'` 的项目
+## 如何配置类型扩展
 
-model 中用 `custom` 菜单指向自定义路径：
+### tsconfig
 
-```ts
+如果项目分了后端、前端、model 多个 TS 上下文，确保它们都 include 同一份声明文件：
+
+```json
 {
-  key: 'custom',
-  name: '自定义页面',
-  menuType: 'module',
-  moduleType: 'custom',
-  customConfig: {
-    path: '/custom-page',  // 注意：这里使用完整路径，以 / 开头
-  },
+  "include": ["app/**/*", "model/**/*", "frontend/**/*", "typing/**/*.d.ts"]
+}
+```
+
+### SchemaForm 类型扩展
+
+扩展目标：
+
+```ts
+declare module '@_tc/template-core/fe/rc' {
+  export namespace SchemaFormNamespace {
+    interface FieldTypes {}
+    interface PropsMap {}
+  }
 }
 ```
 
-## 前端构建 buildFE
+- `FieldTypes` 用来增加字段类型名。
+- `PropsMap` 用来绑定该字段的 props 类型。
+- 类型声明只负责 TS 校验，运行时还必须在 `frontend/extended/SchemaForm/data.ts` 注册组件。
 
-开发构建：
+### Model mode 类型扩展
+
+`mode` 和对应的数据结构一起扩展。内置 `MB` 对应管理后台菜单结构 `MBMenuType`。
 
 ```ts
-import { buildFE } from '@_tc/template-core/bundler'
+// typing/template-core.d.ts
+import '@_tc/template-core/model'
 
-await buildFE('dev')
+declare module '@_tc/template-core/model' {
+  interface ModelModeMap {
+    portal: {
+      portalConfig: {
+        title: string
+        theme?: 'light' | 'dark'
+      }
+    }
+  }
+}
 ```
 
-生产构建：
+使用新 `mode`：
 
 ```ts
-await buildFE('prod')
-```
+import type { ModelDataType } from '@_tc/template-core/model'
 
-默认输出到当前导入格式对应的框架静态目录，例如 `esm/app/public/dist` 或 `cjs/app/public/dist`。如果要输出到项目：
+const model: ModelDataType<'portal'> = {
+  mode: 'portal',
+  name: '门户',
+  desc: '门户配置',
+  homePage: '/',
+  portalConfig: {
+    title: 'Portal',
+    theme: 'light',
+  },
+}
 
-```ts
-await buildFE('prod', {
-  output: 'run',
-})
+export default model
 ```
 
-也可以压缩最终模板输出：
+继续使用内置管理后台时：
 
 ```ts
-await buildFE('prod', {
-  minifyHtml: true,
-})
-```
-
-构建完成后会在输出目录写入 `FEBuildKey`，服务端渲染 HTML 时会用它判断本地 HTML ETag 缓存是否需要清空。
+import type { ModelDataType } from '@_tc/template-core/model'
 
-## Node/backend 构建 buildBE
+const model: ModelDataType<'MB'> = {
+  mode: 'MB',
+  name: '商品后台',
+  desc: '商品管理',
+  homePage: '/_sidebar_/product?projk=demo',
+  menu: [],
+}
+```
 
-消费方 Node/backend 侧构建使用 `buildBE()`。它复用发布包内的 `scripts/vite-build/buildEntries`，只是提供消费方默认配置。
+### CallCom 类型扩展
 
-最小用法：
+扩展目标：
 
 ```ts
-import { buildBE } from '@_tc/template-core/bundler'
-
-await buildBE()
+declare module '@_tc/template-core/model' {
+  export namespace CallComNamespace {
+    interface ConfigMap {}
+    interface OptionMap {}
+  }
+}
 ```
 
-消费方脚本示例：
+- `ConfigMap` 对应 `schemaConfig.componentConfig.xxx`。
+- `OptionMap` 对应字段上的 `xxxOption`。
+- 运行时组件注册在 `frontend/extended/SchemaPage/CallCom/data.ts`。
 
-```js
-// scripts/build-be.mjs
-import { buildBE } from '@_tc/template-core/bundler'
+### SchemaTable 渲染组件类型扩展
 
-await buildBE({
-  rootDir: process.cwd(),
-  input: ['index.ts', 'index.js', 'app', 'config', 'model'],
-  outDir: 'dist',
-  format: 'cjs',
-  alias: {
-    '@app': './app',
-    '@model': './model',
-  },
-})
-```
+扩展目标：
 
-```json
-{
-  "scripts": {
-    "build:be": "node scripts/build-be.mjs"
+```ts
+declare module '@_tc/template-core/model' {
+  export namespace SchemaTableNamespace {
+    interface RenderComponentPropsMap {}
   }
 }
 ```
 
-监听文件变化并重新构建：
+- `RenderComponentPropsMap` 的 key 对应 `tableOption.renderComponent`。
+- 运行时组件注册在 `frontend/extended/SchemaPage/SchemaTable/data.ts`。
+- 组件运行时会自动收到 `value`、`record`、`rowIndex`、`fieldKey`；`renderComponentProps` 只配置自定义参数。
 
-```js
-// scripts/watch-be.mjs
-import chokidar from 'chokidar'
-import { buildBE } from '@_tc/template-core/bundler'
+### KoaApp 类型扩展
 
-const input = ['index.ts', 'index.js', 'app', 'config', 'model']
+使用方推荐增强根包 `@_tc/template-core`：
 
-let building = false
-let pending = false
+```ts
+// typing/template-core.d.ts
+import '@_tc/template-core'
 
-async function runBuild() {
-  if (building) {
-    pending = true
-    return
-  }
+declare module '@_tc/template-core' {
+  namespace FrameworkAugment {
+    interface IServiceAugmented {
+      product: {
+        list(): Promise<unknown[]>
+      }
+    }
 
-  building = true
+    interface IControllerAugmented {
+      product: {
+        list(ctx: import('@_tc/template-core').Ctx): Promise<void>
+      }
+    }
 
-  try {
-    console.log('[buildBE] building...')
-    await buildBE({
-      rootDir: process.cwd(),
-      input,
-      outDir: 'dist',
-      format: 'cjs',
-      alias: {
-        '@app': './app',
-        '@model': './model',
-      },
-    })
-    console.log('[buildBE] done')
-  } catch (error) {
-    console.error('[buildBE] failed')
-    console.error(error)
-  } finally {
-    building = false
+    interface IExtendsAugmented {
+      redis: {
+        get(key: string): Promise<string | null>
+      }
+    }
 
-    if (pending) {
-      pending = false
-      await runBuild()
+    interface IMiddlewaresAugmented {
+      auth: import('koa').Middleware
+    }
+
+    interface AppConfigAugmented {
+      authSecret: string
     }
   }
 }
+```
 
-await runBuild()
+使用：
 
-chokidar
-  .watch(input, {
-    ignored: ['dist/**', 'node_modules/**'],
-    ignoreInitial: true,
-  })
-  .on('all', async (_event, filePath) => {
-    console.log(`[buildBE] changed: ${filePath}`)
-    await runBuild()
-  })
-```
+```ts
+import type { KoaApp } from '@_tc/template-core'
 
-```json
-{
-  "scripts": {
-    "build:be": "node scripts/build-be.mjs",
-    "build:be:watch": "node scripts/watch-be.mjs"
-  },
-  "devDependencies": {
-    "chokidar": "^4.0.3"
-  }
+export default (app: KoaApp) => {
+  app.config.authSecret
+  app.service.product.list()
+  app.extends.$fetch.get('https://example.com/api')
+  app.extends.redis.get('token')
 }
 ```
 
-默认会在当前工作目录构建这些入口：
+如果在 TemplateCore 仓库源码内部扩展，声明目标通常是内部别名 `@tc/core`；npm 使用方不要依赖 `@tc/*` 内部路径。
 
-```ts
-['index.ts', 'index.js', 'app', 'config', 'model']
-```
+## 可选：给项目 AI 助手的文档与 Skill
 
-不存在的默认入口会自动跳过；如果没有任何匹配源码，构建仍会失败。输出到 `dist`，格式为 `cjs`。默认 `outputStructure: "preserve"` 按源路径输出，`bundleDependencies: false` 会 external Node 内置模块和 npm 包，不会把依赖打进产物。`buildBE` 会按同一组 input 扫描并复制内置白名单资源扩展，主要覆盖 `app`、`config`、`model` 目录。
+如果你在项目中让 AI 助手协助开发，可以让它优先读取 npm 包内的 `AGENT_README.md`。安装后的路径通常是 `node_modules/@_tc/template-core/AGENT_README.md`。这份文档面向“协助使用 TemplateCore 的 AI 助手”，覆盖公开入口、最小启动、目录约定、model 配置、前端使用和构建方式。
 
-常见配置：
+包内附带两份 Agent Skill，本质是可复用的 Agent 指令包，采用渐进式披露（SKILL.md + reference/）结构。
 
-```ts
-await buildBE({
-  input: ['app', 'config', 'model'],
-  outDir: 'dist',
-  format: ['es', 'cjs'],
-  alias: {
-    '@app': './app',
-    '@model': './model',
-  },
-})
-```
+| Skill | 用途 |
+| --- | --- |
+| `tc-generator` | 按 TemplateCore 约定生成项目、model 配置、Schema CRUD、controller 和 router。 |
+| `tc-component-usage-skills` | 指导 Agent 选用和正确使用内置 React 组件库（Button、Form、DataTable、Modal 等）。 |
 
-如果需要声明文件：
+如果你的 Agent 支持本地 skills 目录，可以从已安装的 npm 包复制安装。以 Codex 为例：
 
-```ts
-await buildBE({
-  dts: {
-    outDir: 'types',
-    tsconfig: 'tsconfig.json',
-  },
-})
+```bash
+mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
+cp -R node_modules/@_tc/template-core/.skills/tc-generator "${CODEX_HOME:-$HOME/.codex}/skills/tc-generator"
+cp -R node_modules/@_tc/template-core/.skills/tc-component-usage-skills "${CODEX_HOME:-$HOME/.codex}/skills/tc-component-usage-skills"
 ```
 
-`buildEntries()` 底层默认生成 d.ts，但 `buildBE()` 默认关闭声明文件；需要时按上面这样显式传 `dts`。
-
-如果传入自定义 `input`，缺失路径默认会报错；需要跳过时显式打开：
+安装后重启对应 Agent，让新 skill 生效。使用时可以直接说”用 tc-generator 生成一个商品管理模块”或”用 tc-component-usage-skills 帮我写一个带搜索的分页表格”。
 
-```ts
-await buildBE({
-  input: ['app', 'config', 'model'],
-  allowMissingInput: true,
-})
-```
+其他 Agent 如果不支持自动安装 skill，也可以直接读取 `.skills/tc-generator/SKILL.md` 或 `.skills/tc-component-usage-skills/SKILL.md`，再按需读取 `reference/` 下的参考文件。
 
 ## 注意事项