@_tc/template-core 0.1.16 → 0.2.0-bate.1

package/README.md

@@ -1,6 +1,6 @@
 # @_tc/template-core
 
-TemplateCore 是一个基于 TypeScript、Koa、React 的后台框架包。它把后端约定式加载、前端 Dashboard、Schema CRUD 页面、模型配置和类型扩展放到同一个 npm 包里，项目只需要按目录补充自己的 `app/`、`model/`、`frontend/`。
+TemplateCore 是一个基于 TypeScript、Koa、React 的后台框架包。它把后端约定式加载、前端 Dashboard、Schema CRUD 页面、model 类型和类型扩展放到同一个 npm 包里，项目只需要按目录补充自己的 `app/`、`model/`、`frontend/`。
 
 ## 安装
 
@@ -12,9 +12,11 @@ pnpm add @_tc/template-core
 
 - Node.js >= 18
 - pnpm >= 8
-- 使用内置前端时，需要安装 React、Vite 等 peer dependencies
+- 使用内置前端时，需要安装 peer dependencies；完整清单以包内 `package.json` 的 `peerDependencies` 为准，包括 Koa、React、Vite、路由、状态、表单和 UI 相关依赖。
 
-## 可选：AI Agent Skill
+## 可选：给项目 AI 助手的文档与 Skill
+
+如果你在项目中让 AI 助手协助开发，可以让它优先读取 npm 包内的 `AGENT_README.md`。安装后的路径通常是 `node_modules/@_tc/template-core/AGENT_README.md`。这份文档面向“协助使用 TemplateCore 的 AI 助手”，覆盖公开入口、最小启动、目录约定、model 配置、前端使用和构建方式。
 
 包内附带两份 Agent Skill，本质是可复用的 Agent 指令包，采用渐进式披露（SKILL.md + reference/）结构。
 
@@ -26,9 +28,9 @@ pnpm add @_tc/template-core
 如果你的 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”
+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 帮我写一个带搜索的分页表格”。
@@ -75,7 +77,7 @@ async function main() {
     name: 'my-admin',
     baseDir: join(__dirname, '.'),
     pageBasePage: '/',
-    additionalPublicPaths: join(__dirname, 'dist/public'),
+    additionalPublicPaths: [join(__dirname, 'dist/public')],
   })
 
   await buildFE('dev')
@@ -97,12 +99,26 @@ main().catch((error) => {
 | `baseDir` | `string` | 否 | - | 项目根目录，通常为 `join(__dirname, '.')` |
 | `pageBasePage` | `string` | 否 | `'/'` | 页面访问前缀，所有前端页面路由的基础路径 |
 | `homePage` | `string` | 否 | - | 应用首页路径 |
-| `frameBaseDir` | `string` | 否 | - | 框架根目录，通常不需要手动设置 |
-| `additionalPublicPaths` | `string | string[]` | 否 | - | 追加静态资源目录和 Nunjucks 模板查找目录，必须传绝对路径 |
+| `additionalPublicPaths` | `string | string[]` | 否 | - | 追加静态资源目录；如需同时作为 Nunjucks 模板查找目录，建议传绝对路径数组 |
+
+框架会自动读取 `config/config.default.ts` 中的配置（如 `port`、`env`、`auth` 等）。
+
+常用默认配置示例：
+
+```ts
+// config/config.default.ts
+export default {
+  port: 9000,
+  auth: {
+    ATKey: 'Authorization',
+    RTKey: 'RT',
+  },
+}
+```
 
-框架会自动读取 `config/config.default.ts` 中的配置（如 `port`、`env` 等）。
+`auth.ATKey` / `auth.RTKey` 用于约定业务鉴权中间件读取短 token 和刷新 token 的 header 名；默认分别为 `Authorization` 和 `RT`。
 
-静态资源挂载和 Nunjucks 模板查找顺序均为：框架 `app/public`、项目 `app/public`、`additionalPublicPaths`。当 `buildFE` 输出到自定义目录时，可以用 `additionalPublicPaths` 把该目录交给 Koa 提供静态资源访问和模板渲染。
+静态资源挂载顺序为：项目 `app/public`、框架 `app/public`、`additionalPublicPaths`。Nunjucks 模板查找顺序为：项目 `app/public/dist`、框架 `app/public/dist`、`additionalPublicPaths/dist`。这些目录由 `app.publicsPath` 统一维护。当 `buildFE` 输出到自定义目录时，可以用 `additionalPublicPaths` 把该目录交给 Koa 提供静态资源访问和模板渲染；如果需要模板查找也命中追加目录，请传绝对路径数组。
 
 ### buildFE 参数说明
 
@@ -111,27 +127,34 @@ buildFE(mode: 'dev' | 'prod', options?: BuildFEOptions)
 ```
 
 **mode**：构建模式
-- `'dev'`：开发模式，启动 Vite 开发服务器，支持热更新
+- `'dev'`：开发模式，构建一次并监听业务 `frontend/` 变化后重建
 - `'prod'`：生产模式，构建优化后的静态资源
 
 **options.output**：构建输出位置
-- `'frame'`（默认）：输出到框架包内的 `node_modules/@_tc/template-core/app/public/dist`
+- `'frame'`（默认）：输出到当前导入格式对应的框架静态目录，例如 `node_modules/@_tc/template-core/esm/app/public/dist` 或 `node_modules/@_tc/template-core/cjs/app/public/dist`
 - `'run'`：输出到项目根目录的 `app/public/dist`，适合 TypeScript 编译后的项目
-- `() => string`：自定义函数，返回输出目录的绝对路径
+- `() => string`：自定义函数，返回输出目录；建议返回绝对路径
+
+**options.minifyHtml**：是否压缩 Vite 输出的 HTML 内容后再写出最终 `.tpl` / `.html` 文件，默认 `false`
+
+构建完成后会在输出目录写入 `FEBuildKey`。服务端渲染 HTML 时会读取 `public/dist/FEBuildKey`，构建 key 变化后自动清空本地 HTML ETag 缓存。
 
 示例：
 
 ```ts
 // 开发模式，默认输出到框架包
-buildFE('dev')
+await buildFE('dev')
 
 // 生产模式，输出到项目目录
-buildFE('prod', { output: 'run' })
+await buildFE('prod', { output: 'run' })
 
 // 自定义输出路径
-buildFE('prod', {
+await buildFE('prod', {
   output: () => join(__dirname, 'dist/public')
 })
+
+// 压缩最终模板输出
+await buildFE('prod', { minifyHtml: true })
 ```
 
 配置文件：
@@ -151,17 +174,62 @@ http://localhost:9000/dash?projk=demo
 
 `projk` 对应 `model/{modelKey}/project/{projectKey}.ts` 里的 `projectKey`。
 
-## 公开入口
+## 常用公开入口
+
+完整 exports 以发布包内 `package.json` 为准，除下表外还包含 `./fe/main`、`./fe/*`、`./fe/rc/*`、`./fe/rc/hooks/*` 等子路径。
 
 | 入口 | 用途 |
 | --- | --- |
 | `@_tc/template-core` | 服务启动、基础 Controller/Service、Koa 类型 |
-| `@_tc/template-core/bundler` | 前端构建函数 `buildFE` |
+| `@_tc/template-core/bundler` | 构建入口，提供前端资源构建 `buildFE` 和消费方 Node/backend 构建 `buildBE` |
 | `@_tc/template-core/fe` | 前端初始化、Dash 路由扩展、请求方法、SchemaPage 事件、共享状态和内置前端组件 |
 | `@_tc/template-core/fe/rc` | UI/SchemaForm 组件和类型 |
 | `@_tc/template-core/fe/tailwind_ui.css` | 前端全局样式入口，源码对应 `frontend/src/main.css` |
 | `@_tc/template-core/model` | model 配置类型 |
 
+### 后端类型
+
+`@_tc/template-core` 会导出常用 Node 侧类型，业务项目写 `app/*` 文件时建议优先复用这些类型。
+
+| 类型 | 使用场景 |
+| --- | --- |
+| `Ctx` | Controller、middleware、router handler 的 Koa 请求上下文类型，包含框架补充的 `ctx.params` 和可选 `ctx.reqData`。 |
+| `ControllerFN` | `app/controller/*.ts` 默认导出工厂函数的约束类型，适合配合 `satisfies ControllerFN` 保留 controller 实例方法类型。 |
+| `ServiceFN` | `app/service/*.ts` 默认导出工厂函数的约束类型，适合配合 `satisfies ServiceFN` 约束 service class 工厂。 |
+| `MiddlewareFN` | `app/middlewares/*.ts` 默认导出工厂函数的约束类型，返回标准 Koa middleware。 |
+| `RouterFN` | `app/router/*.ts` 默认导出函数的约束类型，用于接收 `app` 和 `router` 并注册路由。 |
+
+示例：
+
+```ts
+import { baseFn, type ControllerFN, type Ctx, type MiddlewareFN, type RouterFN, type ServiceFN } from '@_tc/template-core'
+
+export const getDemoController = ((app) => {
+  const BaseController = baseFn.baseControllerFn(app)
+
+  return class DemoController extends BaseController {
+    list = async (ctx: Ctx) => {
+      this.success(ctx, ctx.reqData?.data ?? {})
+    }
+  }
+}) satisfies ControllerFN
+
+export const getDemoService = ((app) => {
+  return class DemoService {
+    readonly app = app
+  }
+}) satisfies ServiceFN
+
+export const demoMiddleware = ((app) => async (ctx, next) => {
+  app.extends.logger?.info(ctx.path)
+  await next()
+}) satisfies MiddlewareFN
+
+export const demoRouter = ((app, router) => {
+  router.get(`${app.options.apiPrefix}/demo/list`, app.controller.demo.list)
+}) satisfies RouterFN
+```
+
 ## 样式与 Tailwind V4
 
 使用内置前端或 UI 组件时，需要引入包内样式。默认 `@_tc/template-core/fe` 的 `initApp` 会经过源码入口 `frontend/src/main.tsx` 引入 `frontend/src/main.css`；如果项目侧自定义入口、只使用 `fe/rc` 组件，或希望样式入口更明确，建议显式引入：
@@ -219,7 +287,7 @@ VS Code 建议安装官方 Tailwind CSS IntelliSense 插件，并在工作区 `.
 ## 内置功能
 
 - Koa 服务启动：`serverStart(options)`。
-- 约定式加载：自动加载 `config`、`extend`、`router-schema`、`service`、`controller`、`middleware`、`router`。
+- 约定式加载：自动加载 `config`、`extends`、`router-schema`、`service`、`controller`、`middlewares`、根级 `middleware`、`router`。
 - 双层 app：框架内置 `app/` 和项目 `app/` 一起加载。
 - 默认项目接口：
   - `GET /api/project/model_list`
@@ -231,7 +299,7 @@ VS Code 建议安装官方 Tailwind CSS IntelliSense 插件，并在工作区 `.
 - Schema CRUD：根据 `model` 中的 `schemaConfig` 生成搜索、表格、新增、编辑、详情。
 - 内置 UI 组件：提供丰富的 React 组件库，详见下方"内置 UI 组件"章节。
 - API 中间件：错误处理、静态资源、body parser、项目上下文、接口签名、参数校验。
-- 前端构建：扫描 `frontend/**/*.entry.{ts,tsx,js,jsx}`，输出服务端可渲染的 `.entry.tpl`。
+- 前端构建：扫描框架和项目的 `frontend/**/*.entry.{ts,tsx,js,jsx}`，输出服务端可渲染的 `.entry.tpl`，并写入 `FEBuildKey` 供 HTML ETag 缓存失效使用。
 - 类型扩展：支持扩展 SchemaForm、CallCom、KoaApp。
 
 ## 前端公共能力
@@ -240,6 +308,7 @@ VS Code 建议安装官方 Tailwind CSS IntelliSense 插件，并在工作区 `.
 
 ```ts
 import {
+  api,
   apiFreezerStore,
   AsyncSelect,
   eventsInfo,
@@ -259,12 +328,18 @@ import {
 } from '@_tc/template-core/fe'
 
 import type {
+  BaseResponse,
   CallComComponentsMap,
   CallComRenderer,
   DashComponentsMap,
+  DashRouteGuard,
   DashRoutesExtender,
   FormFieldSchema,
   ApiFreezerRequestMatcher,
+  PageParams,
+  PageResponse,
+  RequestConfig,
+  ResponseConfig,
   SchemaFormComponentsMap,
   SchemaFormNamespace,
   SelectProps,
@@ -277,24 +352,27 @@ import type {
 | --- | --- |
 | 应用启动 | `initApp` |
 | 内置前端组件 | `AsyncSelect`、`LanguageSwitch`、`ThemeSwitch` |
-| Dash 扩展类型 | `DashRoutesExtender`、`DashRoutesContext`、`DashComponentsMap`、`DashHeaderUserAreaProps` |
+| Dash 扩展类型 | `DashRoutesExtender`、`DashRoutesContext`、`DashComponentsMap`、`DashHeaderUserAreaProps`、`DashRouteGuard` |
 | SchemaPage 类型 | `CallComComponentsMap`、`CallComRenderer` |
 | SchemaForm 类型 | `FormFieldSchema`、`SchemaFormComponentsMap`、`SchemaFormNamespace`、`SelectProps` |
-| 请求方法 | `request`、`get`、`post`、`put`、`patch`、`del` |
+| 请求方法 | `api`、`request`、`get`、`post`、`put`、`patch`、`del` |
+| 请求类型 | `BaseResponse`、`PageParams`、`PageResponse`、`RequestConfig`、`ResponseConfig`、`AxiosError` |
 | 请求冻结 | `apiFreezerStore`、`useApiFreezer`、`FreezeState`、`ApiFreezerRequestMatcher` |
 | 事件工具 | `eventsInfo`、`merge` |
 | 共享状态 | `modeStore`、`useModeStore`、`schemaStore`、`useSchemaStore`、`schemaEventBus` |
 
 `modeStore` 管项目模型和当前项目数据，`schemaStore` 管当前 Schema 页面的 schema/cache，`schemaEventBus` 用来在 Search、Table、CallCom 之间通信。
 
+只使用请求层时，也可以从 `@_tc/template-core/fe/common/request` 导入 `api`、请求方法和请求类型；这是发布包显式子路径，不要下钻到 `frontend/src/common/request`。
+
 ### 前端多语言
 
-TemplateCore 前端复用 `@tc/ui-react/i18n`。框架内置中文、英文资源，项目可以继续追加自己的资源。
+TemplateCore 前端通过 `@_tc/template-core/fe` 暴露 i18n 能力。框架内置中文、英文资源，项目可以继续追加自己的资源。
 
 **追加自定义语言资源**：
 
 ```ts
-import { i18nStore } from '@tc/ui-react/i18n'
+import { i18nStore } from '@_tc/template-core/fe'
 
 i18nStore.getState().addResources('zh-CN', {
   business: {
@@ -380,7 +458,7 @@ const title = '$i18n::business.product.createTitle'
 **切换语言**：
 
 ```ts
-import { i18nStore } from '@tc/ui-react/i18n'
+import { i18nStore } from '@_tc/template-core/fe'
 
 i18nStore.getState().setLanguage('en-US')
 i18nStore.getState().setLanguage('zh-CN')
@@ -398,7 +476,7 @@ export function Toolbar() {
 }
 ```
 
-`LanguageSwitch` 默认提供 `zh-CN` 和 `en-US`，也支持传入 `options` 覆盖语言列表。组件内部会调用 `i18nStore.getState().setLanguage()`，因此会沿用 `tc_language` 的持久化行为。
+`LanguageSwitch` 默认提供 `zh-CN` 和 `en-US`，也支持传入 `options` 覆盖语言列表。组件当前是按钮 + 下拉菜单形态，`option.label` 支持 ReactNode，`buttonClassName` 可自定义触发按钮样式。组件内部会调用 `i18nStore.getState().setLanguage()`，因此会沿用 `tc_language` 的持久化行为。
 
 **AJV 校验文案**：
 
@@ -459,6 +537,8 @@ export function Toolbar() {
 }
 ```
 
+`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(签名密钥_${时间戳})`
@@ -474,7 +554,8 @@ export function Toolbar() {
 **使用示例**：
 
 ```ts
-import { get, post, put, del } from '@_tc/template-core/fe'
+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 })
@@ -489,6 +570,22 @@ await put('/product', { id: 1, name: '新名称' })
 await del('/product', { id: 1 })
 ```
 
+如果希望把请求能力单独拆出来导入：
+
+```ts
+import {
+  api,
+  get,
+  post,
+  request,
+} from '@_tc/template-core/fe/common/request'
+import type {
+  BaseResponse,
+  RequestConfig,
+  ResponseConfig,
+} from '@_tc/template-core/fe/common/request'
+```
+
 **请求冻结器**：
 
 请求冻结器用于在某段流程中暂停普通 API 请求，典型场景是 RT 刷新 token：刷新期间冻结其它请求，刷新接口本身走白名单放行，刷新完成后再解冻并回放队列。
@@ -536,7 +633,7 @@ try {
 | 组件 | 用途 | 导入路径 |
 | --- | --- | --- |
 | `Button` | 按钮组件，支持多种样式和尺寸 | `@_tc/template-core/fe/rc` |
-| `Input` | 输入框组件 | `@_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` |
@@ -579,7 +676,7 @@ try {
 | --- | --- | --- |
 | `Modal` | 模态框组件 | `@_tc/template-core/fe/rc` |
 | `Drawer` | 抽屉组件 | `@_tc/template-core/fe/rc` |
-| `Message` | 消息提示组件 | `@_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` |
@@ -619,6 +716,7 @@ function MyComponent() {
       </Button>
 
       <Input placeholder="请输入内容" />
+      <Input type="password" placeholder="请输入密码" />
 
       <Select
         options={[
@@ -643,20 +741,40 @@ function MyComponent() {
 ```text
 app/controller/**/*.(js|ts)      -> app.controller
 app/service/**/*.(js|ts)         -> app.service
-app/middleware/**/*.(js|ts)      -> app.middlewares
+app/middlewares/**/*.(js|ts)     -> app.middlewares
+app/middleware.(js|ts)           -> 全局中间件编排，按框架 -> 项目顺序执行
 app/router/**/*.(js|ts)          -> Koa router
 app/router-schema/**/*.(js|ts)   -> app.routerSchema
-app/extend/*.(js|ts)             -> app.extends
+app/extends/*.(js|ts)            -> app.extends
 config/config.default.(js|ts)    -> app.config
 config/config.{env}.(js|ts)      -> app.config
-model/**/*.(js|ts)               -> 项目模型配置
+model/**/*.(js|ts)               -> 内置 project service 按需读取的项目模型配置
 ```
 
 内置扩展：
 
 - `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` 等通用数据方法。
 
+API controller 可以通过 `ctx.reqData` 读取统一请求参数：
+
+```ts
+const { query, body, headers, data } = ctx.reqData ?? {
+  query: {},
+  body: undefined,
+  headers: {},
+  data: {},
+}
+```
+
+- `query` 来自 `ctx.query`。
+- `body` 来自 `ctx.request.body`。
+- `headers` 来自 `ctx.headers`。
+- `data` 是便捷合并层，当前按 `query -> body` 顺序合并；字段冲突时 body 覆盖 query。
+
+`ctx.reqData` 只在 API 请求中由内置中间件注入，类型上是可选字段。router params 不在 `reqData` 里，仍然从 `ctx.params` 获取。
+
 ### 数据库扩展
 
 默认 `app.extends.db` 使用 SQLite 保存数据，数据库文件位于项目根目录 `.template-core/template-core.sqlite`。可以在配置中调整路径：
@@ -718,6 +836,36 @@ SQL 注入边界：
 - `queryDB`、`runDB`、`getDBFirst` 是原始 SQL 入口，用户输入必须放到 `params`，不要拼接到 SQL 字符串里。
 - `execDB` 没有参数绑定能力，只建议用于固定 SQL，例如建表或迁移。
 
+### 加密扩展
+
+`app.extends.crypto` 默认使用 `app.config.signKey` 作为签名密钥，适合生成登录 token、接口签名和安全比较。
+
+常用方法：
+
+- `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(),
+})
+
+const payload = app.extends.crypto.verifySignedPayload<{
+  account: string
+  exp: number
+  iat: number
+}>(token)
+
+const same = app.extends.crypto.safeEqual('abc', 'abc')
+```
+
 ```ts
 // 推荐：参数绑定
 const users = app.extends.db.queryDB(
@@ -731,10 +879,10 @@ const unsafeUsers = app.extends.db.queryDB(
 )
 ```
 
-业务项目可以用自己的 `app/extend/db.ts` 覆盖默认实现。建议保留同一组方法名，这样 controller/service 调用方不用调整。
+业务项目可以用自己的 `app/extends/db.ts` 覆盖默认实现。建议保留同一组方法名，这样 controller/service 调用方不用调整。
 
 ```ts
-// app/extend/db.ts
+// app/extends/db.ts
 import type { DB, DBFactory } from '@_tc/template-core'
 
 interface DataOptions {
@@ -842,6 +990,22 @@ export default (app: KoaApp, router: Router) => {
 }
 ```
 
+路由挂载顺序：
+
+- 每个 `app/router/*.ts` 文件都会获得独立的 `koa-router` 实例。
+- 可以通过 `router.level = number` 控制挂载顺序，数值越小越早挂载。
+- 默认 `level` 是 `0`，框架兜底 router 是 `99`。
+- 通配、兜底、重定向类路由建议设置较大的 `level`，避免抢先匹配业务 API。
+
+```ts
+import type { KoaApp, Router } from '@_tc/template-core'
+
+export default (app: KoaApp, router: Router) => {
+  router.level = 10
+  router.get('/api/fallback/:id', app.controller.fallback.detail)
+}
+```
+
 ## model 数据如何配置
 
 `model` 是后台菜单、项目和 Schema 页面的数据源。框架会读取：
@@ -1118,6 +1282,29 @@ DELETE {api}        -> 删除
 
 `$schema::字段名` 表示从当前表格行读取字段值，常用于删除按钮参数。
 
+### 服务端兜底路由守卫
+
+业务项目可以创建 `app/router-guard.ts` 或 `app/router-guard.js`。它只在所有正常 `app/router/*` 路由都没有命中时执行。
+
+```ts
+import type { Ctx, KoaApp } from '@_tc/template-core'
+
+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`。
+
 ## 如何扩展组件
 
 ### 扩展 Dashboard 顶部用户区域
@@ -1141,6 +1328,28 @@ export default components
 
 - `HeaderView.userArea`：Dashboard 顶部右侧区域。
 
+### 扩展 Dashboard 登录守卫
+
+业务项目可以创建 `frontend/extended/dash/routeGuard.ts`，用于在 Dashboard 内置 `homePage` / 首菜单重定向前做登录判断。
+
+```ts
+// frontend/extended/dash/routeGuard.ts
+import type { DashRouteGuard } from '@_tc/template-core/fe'
+
+const dashRouteGuard: DashRouteGuard = ({ isLoggedIn }) => {
+  if (!isLoggedIn) return '/login'
+}
+
+export default dashRouteGuard
+```
+
+返回值规则：
+
+- 返回 `string`：框架使用 `window.location.href` 跳转，登录页不需要在 Dash 路由下。
+- 返回非 `string`：中断 Dashboard 内置重定向，业务方可自行跳转或处理提示。
+- `DashRouteGuardResult` 是 `string | undefined`；`undefined`（包括已登录分支的隐式返回）也会打断 Dashboard 内置重定向。
+- 没有业务 `routeGuard` 文件时，框架使用兜底空对象，不影响默认 Dashboard 重定向。
+
 ### 扩展 SchemaForm 字段组件
 
 1. 声明字段类型。
@@ -1472,6 +1681,55 @@ frontend/admin/admin.entry.tsx
 
 入口文件名必须包含 `.entry.`，构建器才会扫描。
 
+最小入口示例：
+
+```tsx
+// frontend/admin/admin.entry.tsx
+import { initApp } from '@_tc/template-core/fe'
+import type { ReactNode } from 'react'
+
+const AdminApp = ({ children }: { children: ReactNode }) => (
+  <main>{children}</main>
+)
+
+initApp(AdminApp, {
+  initModeData: false,
+})
+```
+
+如果需要给页面加额外 `meta`、预连接资源或启动脚本，可以在入口同目录放 `.html` 插槽文件。这个文件不是完整 HTML，只能包含 `tc-slot` 块：
+
+```html
+<!-- frontend/admin/admin.html -->
+<!-- tc-slot:head -->
+<meta name="description" content="Admin Console" />
+<link rel="preconnect" href="https://example.com" />
+<!-- /tc-slot:head -->
+
+<!-- tc-slot:body-before-root -->
+<div id="boot-mask"></div>
+<!-- /tc-slot:body-before-root -->
+
+<!-- tc-slot:body-after-root -->
+<script>
+  window.__ADMIN_BOOT_TIME__ = Date.now()
+</script>
+<!-- /tc-slot:body-after-root -->
+```
+
+命名规则：
+
+```text
+frontend/admin/admin.entry.tsx
+frontend/admin/admin.html       yes
+
+frontend/report/index.entry.tsx
+frontend/report/index.html      yes
+frontend/report/report.html     yes
+```
+
+不要在插槽文件里写 `<!DOCTYPE html>`、`<html>`、`<body>` 或 `<div id="root"></div>`。页面外壳由 TemplateCore 的 `app/view/entry.tpl` 统一生成，`window._basePath`、`window._projKey`、`window._signKey`、`window.appOptions` 也由它注入。
+
 扩展 Dashboard 路由：
 
 ```tsx
@@ -1517,30 +1775,193 @@ model 中用 `custom` 菜单指向自定义路径：
 }
 ```
 
-## 构建
+## 前端构建 buildFE
 
 开发构建：
 
 ```ts
 import { buildFE } from '@_tc/template-core/bundler'
 
-buildFE('dev')
+await buildFE('dev')
 ```
 
 生产构建：
 
 ```ts
-buildFE('prod')
+await buildFE('prod')
 ```
 
-默认输出到框架包的 `app/public/dist`。如果要输出到项目：
+默认输出到当前导入格式对应的框架静态目录，例如 `esm/app/public/dist` 或 `cjs/app/public/dist`。如果要输出到项目：
 
 ```ts
-buildFE('prod', {
+await buildFE('prod', {
   output: 'run',
 })
 ```
 
+也可以压缩最终模板输出：
+
+```ts
+await buildFE('prod', {
+  minifyHtml: true,
+})
+```
+
+构建完成后会在输出目录写入 `FEBuildKey`，服务端渲染 HTML 时会用它判断本地 HTML ETag 缓存是否需要清空。
+
+## Node/backend 构建 buildBE
+
+消费方 Node/backend 侧构建使用 `buildBE()`。它复用发布包内的 `scripts/vite-build/buildEntries`，只是提供消费方默认配置。
+
+最小用法：
+
+```ts
+import { buildBE } from '@_tc/template-core/bundler'
+
+await buildBE()
+```
+
+消费方脚本示例：
+
+```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"
+  }
+}
+```
+
+监听文件变化并重新构建：
+
+```js
+// scripts/watch-be.mjs
+import chokidar from 'chokidar'
+import { buildBE } from '@_tc/template-core/bundler'
+
+const input = ['index.ts', 'index.js', 'app', 'config', 'model']
+
+let building = false
+let pending = false
+
+async function runBuild() {
+  if (building) {
+    pending = true
+    return
+  }
+
+  building = true
+
+  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
+
+    if (pending) {
+      pending = false
+      await runBuild()
+    }
+  }
+}
+
+await runBuild()
+
+chokidar
+  .watch(input, {
+    ignored: ['dist/**', 'node_modules/**'],
+    ignoreInitial: true,
+  })
+  .on('all', async (_event, filePath) => {
+    console.log(`[buildBE] changed: ${filePath}`)
+    await runBuild()
+  })
+```
+
+```json
+{
+  "scripts": {
+    "build:be": "node scripts/build-be.mjs",
+    "build:be:watch": "node scripts/watch-be.mjs"
+  },
+  "devDependencies": {
+    "chokidar": "^4.0.3"
+  }
+}
+```
+
+默认会在当前工作目录构建这些入口：
+
+```ts
+['index.ts', 'index.js', 'app', 'config', 'model']
+```
+
+不存在的默认入口会自动跳过；如果没有任何匹配源码，构建仍会失败。输出到 `dist`，格式为 `cjs`。默认 `outputStructure: "preserve"` 按源路径输出，`bundleDependencies: false` 会 external Node 内置模块和 npm 包，不会把依赖打进产物。`buildBE` 会按同一组 input 扫描并复制内置白名单资源扩展，主要覆盖 `app`、`config`、`model` 目录。
+
+常见配置：
+
+```ts
+await buildBE({
+  input: ['app', 'config', 'model'],
+  outDir: 'dist',
+  format: ['es', 'cjs'],
+  alias: {
+    '@app': './app',
+    '@model': './model',
+  },
+})
+```
+
+如果需要声明文件：
+
+```ts
+await buildBE({
+  dts: {
+    outDir: 'types',
+    tsconfig: 'tsconfig.json',
+  },
+})
+```
+
+`buildEntries()` 底层默认生成 d.ts，但 `buildBE()` 默认关闭声明文件；需要时按上面这样显式传 `dts`。
+
+如果传入自定义 `input`，缺失路径默认会报错；需要跳过时显式打开：
+
+```ts
+await buildBE({
+  input: ['app', 'config', 'model'],
+  allowMissingInput: true,
+})
+```
+
 ## 注意事项
 
 - 不要在项目代码里引用 `dist/fe/*`、`dist/model/*` 这类构建产物路径。
@@ -1548,5 +1969,7 @@ buildFE('prod', {
 - SchemaForm 和 CallCom 的类型扩展、运行时注册都要做，少一个就只会“类型通过但页面不显示”或“页面能配但类型报错”。
 - `model` 数组合并依赖稳定 `key`。
 - Dashboard 默认需要 URL 带 `?projk=项目key`。
+- Dashboard 登录守卫放在 `frontend/extended/dash/routeGuard.ts`；登录页通常不在 Dash 路由下，返回登录页 URL 即可。
+- 服务端兜底守卫放在业务 `app/router-guard.ts|js`，不是 `app/business` 子目录。
 - 前端入口必须命名为 `.entry.tsx`、`.entry.ts`、`.entry.jsx` 或 `.entry.js`。
-- **使用方不建议在 `/frontend/apps/` 下保留 `html` 文件。** Vite 构建时会根据模板文件（`app/view/entry.tpl`）自动生成 html，如果保留 html 文件，可能与模板不同步而导致内容过时。
+- 入口同目录的 `.html` 只能作为插槽文件使用，不能写完整 HTML 文档；页面外壳始终由 `app/view/entry.tpl` 生成。