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

package/.skills/tc-generator/reference/model-schema.md

@@ -210,6 +210,24 @@ Option meaning:
 | `editFormOption` | Edit modal form field. Omit to hide from edit. |
 | `detailPanelOption` | Detail drawer field. Omit to hide from detail. |
 
+Table cell render components:
+
+```js
+cover: {
+  type: "string",
+  label: "Cover",
+  tableOption: {
+    renderComponent: "PreviewImage",
+    renderComponentProps: {
+      width: 48,
+      height: 48,
+    },
+  },
+}
+```
+
+Built-in `PreviewImage` accepts the current field value as a string or string array. Project-specific table render components are registered in `frontend/extended/SchemaPage/SchemaTable/data.ts` and referenced by `tableOption.renderComponent`.
+
 Common form `comType` values:
 
 ```text

package/.skills/tc-generator/reference/runtime-extensions.md

@@ -295,6 +295,26 @@ this.success(ctx, [
 
 For project-specific field types, create `frontend/extended/SchemaForm/data.ts` and default-export a component map keyed by field type.
 
+## SchemaTable Render Components
+
+Use `tableOption.renderComponent` when a Schema CRUD table column needs a reusable renderer. TemplateCore includes `PreviewImage` for image preview columns:
+
+```js
+cover: {
+  type: "string",
+  label: "Cover",
+  tableOption: {
+    renderComponent: "PreviewImage",
+    renderComponentProps: {
+      width: 48,
+      height: 48,
+    },
+  },
+}
+```
+
+For project-specific renderers, create `frontend/extended/SchemaPage/SchemaTable/data.ts` and default-export a component map typed as `SchemaTableRenderComponentsMap` from `@_tc/template-core/fe`. Extend `SchemaTableNamespace.RenderComponentPropsMap` from `@_tc/template-core/model` when TypeScript model config should know the renderer props.
+
 ## SchemaPage CallCom Extensions
 
 Use `frontend/extended/SchemaPage/CallCom/data.ts` when model `componentConfig` should open a custom runtime component instead of built-in create/edit/detail components. Custom components can import `schemaEventBus`, `eventsInfo`, and `merge` from `@_tc/template-core/fe` to close panels or refresh Schema tables.

package/AGENT_README.md

@@ -1,6 +1,6 @@
 # TemplateCore AI 助手速读
 
-这份文档给在消费方项目中协助开发的 AI 助手/代码代理阅读。项目本身才是 `@_tc/template-core` 的使用方；AI 通过这份速读文档快速理解包的用法和边界。它是 `README.md` 的精简版，按渐进式披露组织：先用下面的最小信息完成常见任务，只有需要深入时再读末尾的参考文档。
+这份文档由 TemplateCore 框架提供方维护，面向下游消费方项目中的 AI 助手/代码代理。消费方项目通过 `@_tc/template-core` 使用框架能力；AI 可以通过这份速读文档快速理解包的公开入口、约定用法和边界。它是 `README.md` 的面向 Agent 的精简版，按渐进式披露组织：先用下面的最小信息完成常见任务，只有需要深入时再读末尾的参考文档。
 
 ## 1. 先看结论
 
@@ -11,7 +11,7 @@ TemplateCore 是一个 TypeScript + Koa + React 的后台框架包。它提供
 - `model/` 配置驱动的菜单、项目和 CRUD 页面。
 - 前端构建 `buildFE()` 输出服务端可渲染的 `.entry.tpl`，并写入 `FEBuildKey` 供 HTML ETag 缓存失效使用。
 - 消费方 Node/backend 构建 `buildBE()`。
-- 类型扩展机制，用于扩展 SchemaForm 字段、CallCom 组件和 Koa app 类型。
+- 类型扩展机制，用于扩展 SchemaForm 字段、SchemaTable 单元格渲染组件、CallCom 组件和 Koa app 类型。
 
 优先使用公开入口，不要从包内部源码路径导入。下面这些入口以 npm 发布产物为准；源码仓库根 `package.json` 的 `exports` 会在构建发布包时生成到 `dist/package.json`。
 
@@ -19,9 +19,11 @@ TemplateCore 是一个 TypeScript + Koa + React 的后台框架包。它提供
 | --- | --- |
 | `@_tc/template-core` | `serverStart`、`baseFn`、Koa/Controller/Service 类型。 |
 | `@_tc/template-core/bundler` | `buildFE()`、`buildBE()`。 |
-| `@_tc/template-core/fe` | 前端初始化、请求方法、Dashboard/Schema 类型、共享状态、业务前端组件。 |
+| `@_tc/template-core/fe` | 前端初始化、动态组件渲染辅助、请求方法、Dashboard/Schema 类型、token 工具、RAF 计时器、共享状态、业务前端组件。 |
+| `@_tc/template-core/fe/main` | 前端初始化入口。 |
 | `@_tc/template-core/fe/common/request` | 请求实例、请求方法和请求类型的显式子路径。 |
 | `@_tc/template-core/fe/rc` | React UI 组件和 SchemaForm 组件。 |
+| `@_tc/template-core/fe/rc/hooks` | React hooks 汇总入口。 |
 | `@_tc/template-core/fe/tailwind_ui.css` | 内置前端/UI 全局样式。 |
 | `@_tc/template-core/model` | `ModelDataType` 等 model 配置类型。 |
 
@@ -367,13 +369,24 @@ import '@_tc/template-core/fe/tailwind_ui.css'
 
 ```ts
 import {
+  addLanguageResources,
+  clearRafTimer,
   api,
+  clearAuthToken,
   get,
+  getAuthToken,
+  localKeyMap,
   post,
+  renderImportComponent,
   request,
+  rafSetInterval,
+  rafSetTimeout,
   schemaEventBus,
   schemaStore,
+  setAuthToken,
+  setLanguage,
   useSchemaStore,
+  useText,
   LanguageSwitch,
   ThemeSwitch,
 } from '@_tc/template-core/fe'
@@ -401,15 +414,19 @@ import { Button, DataTable, Form, Input, Modal, Select } from '@_tc/template-cor
 常用前端能力：
 
 - 请求方法：`api`、`request`、`get`、`post`、`put`、`patch`、`del`。
+- RAF 风格计时器：`rafSetTimeout`、`rafSetInterval`、`rafClearTimeout`、`rafClearInterval`、`clearRafTimer`，缺少 RAF 时自动降级到 `setTimeout`。
 - 请求类型：`BaseResponse`、`PageParams`、`PageResponse`、`RequestConfig`、`ResponseConfig`、`AxiosError`。
 - 请求 header：自动添加 `s_t`、`s_sign`、`projk`；存在短 token 时添加 `Authorization: Bearer ${token}`。
+- 默认会先设置 `Content-Type: application/json`；如果是上传文件、`FormData` 或其他内容类型，请在请求配置里显式覆盖。
+- Token 工具：`getAuthToken()`、`setAuthToken()`、`clearAuthToken()`、`localKeyMap`；`getAuthToken()` 是同步函数，读取前无需 `await`。
 - 本地 key：短 token 是 `localStorage.auth_token`，项目 key 是 `localStorage.p_J_k`；刷新 token header 默认名是 `RT`。
-- `getAuthToken()` 是同步函数，读取前无需 `await`。
+- 组件加载辅助：`renderImportComponent(import('./Page'))` 会用 `React.lazy` + `Suspense` 渲染动态组件。
 - Schema 通信：`schemaEventBus`、`eventsInfo`、`merge`。
 - 共享状态：`modeStore`、`schemaStore`、`apiFreezerStore` 及对应 hooks。
-- 多语言：`i18nStore.getState().addResources()`，配置文案可写 `$i18n::...`。
+- 多语言：`addLanguageResources()` 追加或新增某语种文案，`setLanguage()` 切换语言，React render 中用 `useText()`，非 React 工具代码用 `getText()`，配置文案可写 `$i18n::...`。
 - 主题：`ThemeSwitch` 会同步根节点 `dark` class 和 `localStorage`。
 - `Input type="password"` 会自动显示密码显隐按钮；`allowClear` 不作用于密码输入。
+- RAF 风格计时器由 `@tc/common/rafTimer` 提供，浏览器优先使用 RAF，Node/SSR 自动降级到 `setTimeout`。
 
 不要直接依赖 `frontend/src/...`、`packages/react/ui/...` 这类包内部路径。
 
@@ -609,13 +626,14 @@ chokidar
 
 扩展前端类型或组件：
 
-1. SchemaForm 字段类型、CallCom 组件、Koa app 类型都支持 TypeScript 声明合并。
+1. SchemaForm 字段类型、SchemaTable 单元格渲染组件、CallCom 组件、Koa app 类型都支持 TypeScript 声明合并。
 2. 运行时组件通常放在业务 `frontend/extended/`。
-3. Dashboard 扩展点包括 `frontend/extended/dash/init.ts`、`frontend/extended/dash/customRoutes.tsx`、`frontend/extended/dash/components.tsx`、`frontend/extended/dash/routeGuard.ts`。
-4. `dash/init` 在 React 渲染前执行，适合注册 axios 拦截器等全局初始化逻辑；类型是 `DashInit`。
-5. `dash/routeGuard` 用来判断登录。返回登录页 URL 字符串时，Dashboard 用 `window.location.href` 跳转；`DashRouteGuardResult` 是 `string | undefined`，`undefined`（包括已登录分支的隐式返回）会打断 Dashboard 内置重定向，业务方可自行跳转。
-6. 自定义入口的 `initApp` 支持 `beforeRender` / `afterRender`，分别在 React 渲染前和首次渲染提交后触发。
-7. 优先查看公开入口 `.d.ts` 和 npm 包根目录 `README.md`；如果当前环境是源码仓库，再继续读 `docs/type-extension.md` 和 `docs/schema-form.md`。
+3. 表格单元格渲染组件注册到 `frontend/extended/SchemaPage/SchemaTable/data.ts`，字段上用 `tableOption.renderComponent` 和 `renderComponentProps`。
+4. Dashboard 扩展点包括 `frontend/extended/dash/init.ts`、`frontend/extended/dash/customRoutes.tsx`、`frontend/extended/dash/components.tsx`、`frontend/extended/dash/routeGuard.ts`。
+5. `dash/init` 在 React 渲染前执行，适合注册 axios 拦截器等全局初始化逻辑；类型是 `DashInit`。
+6. `dash/routeGuard` 用来判断登录。返回登录页 URL 字符串时，Dashboard 用 `window.location.href` 跳转；`DashRouteGuardResult` 是 `string | undefined`，`undefined`（包括已登录分支的隐式返回）会打断 Dashboard 内置重定向，业务方可自行跳转。
+7. 自定义入口的 `initApp` 支持 `beforeRender` / `afterRender`，分别在 React 渲染前和首次渲染提交后触发。
+8. 优先查看公开入口 `.d.ts` 和 npm 包根目录 `README.md`；如果当前环境是源码仓库，再继续读 `docs/type-extension.md` 和 `docs/schema-form.md`。
 
 ## 8. 继续深入
 

package/README.md

@@ -116,7 +116,7 @@ export default {
 }
 ```
 
-`auth.ATKey` / `auth.RTKey` 用于约定业务鉴权中间件读取短 token 和刷新 token 的 header 名；默认分别为 `Authorization` 和 `RT`。
+`auth.ATKey` / `auth.RTKey` 用于约定项目鉴权中间件读取短 token 和刷新 token 的 header 名；默认分别为 `Authorization` 和 `RT`。
 
 静态资源挂载顺序为：项目 `app/public`、框架 `app/public`、`additionalPublicPaths`。Nunjucks 模板查找顺序为：项目 `app/public/dist`、框架 `app/public/dist`、`additionalPublicPaths/dist`。这些目录由 `app.publicsPath` 统一维护。当 `buildFE` 输出到自定义目录时，可以用 `additionalPublicPaths` 把该目录交给 Koa 提供静态资源访问和模板渲染；如果需要模板查找也命中追加目录，请传绝对路径数组。
 
@@ -127,7 +127,7 @@ buildFE(mode: 'dev' | 'prod', options?: BuildFEOptions)
 ```
 
 **mode**：构建模式
-- `'dev'`：开发模式，构建一次并监听业务 `frontend/` 变化后重建
+- `'dev'`：开发模式，构建一次并监听项目 `frontend/` 变化后重建
 - `'prod'`：生产模式，构建优化后的静态资源
 
 **options.output**：构建输出位置
@@ -176,20 +176,23 @@ http://localhost:9000/dash?projk=demo
 
 ## 常用公开入口
 
-完整 exports 以发布包内 `package.json` 为准，除下表外还包含 `./fe/main`、`./fe/*`、`./fe/rc/*`、`./fe/rc/hooks/*` 等子路径。
+完整 exports 以发布包内 `package.json` 为准，除下表外还包含 `./fe/main`、`./fe/common/request`、`./fe/*`、`./fe/rc/*`、`./fe/rc/hooks` 等子路径。
 
 | 入口 | 用途 |
 | --- | --- |
 | `@_tc/template-core` | 服务启动、基础 Controller/Service、Koa 类型 |
 | `@_tc/template-core/bundler` | 构建入口，提供前端资源构建 `buildFE` 和消费方 Node/backend 构建 `buildBE` |
-| `@_tc/template-core/fe` | 前端初始化、Dash 路由扩展、请求方法、SchemaPage 事件、共享状态和内置前端组件 |
+| `@_tc/template-core/fe` | 前端初始化、动态组件渲染辅助、Dash 路由扩展、请求方法、SchemaPage 事件、token 工具、共享状态和内置前端组件 |
+| `@_tc/template-core/fe/main` | 前端初始化入口 |
+| `@_tc/template-core/fe/common/request` | 请求实例、请求方法和请求类型的显式子路径 |
 | `@_tc/template-core/fe/rc` | UI/SchemaForm 组件和类型 |
+| `@_tc/template-core/fe/rc/hooks` | React hooks 汇总入口 |
 | `@_tc/template-core/fe/tailwind_ui.css` | 前端全局样式入口，源码对应 `frontend/src/main.css` |
 | `@_tc/template-core/model` | model 配置类型 |
 
 ### 后端类型
 
-`@_tc/template-core` 会导出常用 Node 侧类型，业务项目写 `app/*` 文件时建议优先复用这些类型。
+`@_tc/template-core` 会导出常用 Node 侧类型，项目编写 `app/*` 文件时建议优先复用这些类型。
 
 | 类型 | 使用场景 |
 | --- | --- |
@@ -300,7 +303,7 @@ VS Code 建议安装官方 Tailwind CSS IntelliSense 插件，并在工作区 `.
 - 内置 UI 组件：提供丰富的 React 组件库，详见下方"内置 UI 组件"章节。
 - API 中间件：错误处理、静态资源、body parser、项目上下文、接口签名、参数校验。
 - 前端构建：扫描框架和项目的 `frontend/**/*.entry.{ts,tsx,js,jsx}`，输出服务端可渲染的 `.entry.tpl`，并写入 `FEBuildKey` 供 HTML ETag 缓存失效使用。
-- 类型扩展：支持扩展 SchemaForm、CallCom、KoaApp。
+- 类型扩展：支持扩展 SchemaForm、SchemaTable 单元格渲染组件、CallCom、KoaApp。
 
 ## 前端公共能力
 
@@ -310,21 +313,36 @@ VS Code 建议安装官方 Tailwind CSS IntelliSense 插件，并在工作区 `.
 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 type {
@@ -340,6 +358,8 @@ import type {
   PageResponse,
   RequestConfig,
   ResponseConfig,
+  SchemaTableRenderComponent,
+  SchemaTableRenderComponentsMap,
   SchemaFormComponentsMap,
   SchemaFormNamespace,
   SelectProps,
@@ -352,30 +372,50 @@ import type {
 | --- | --- |
 | 应用启动 | `initApp` |
 | 内置前端组件 | `AsyncSelect`、`LanguageSwitch`、`ThemeSwitch` |
+| 组件加载辅助 | `renderImportComponent` |
 | Dash 扩展类型 | `DashRoutesExtender`、`DashRoutesContext`、`DashComponentsMap`、`DashHeaderUserAreaProps`、`DashRouteGuard` |
-| SchemaPage 类型 | `CallComComponentsMap`、`CallComRenderer` |
+| 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` |
 
 `modeStore` 管项目模型和当前项目数据，`schemaStore` 管当前 Schema 页面的 schema/cache，`schemaEventBus` 用来在 Search、Table、CallCom 之间通信。
 
+`renderImportComponent` 封装了 `React.lazy` + `Suspense`，默认会用页面骨架屏作为 fallback。`getAuthToken()`、`setAuthToken()` 和 `clearAuthToken()` 用于读写或清理本地短 token，`localKeyMap` 暴露对应的本地存储 key 常量。
+
 只使用请求层时，也可以从 `@_tc/template-core/fe/common/request` 导入 `api`、请求方法和请求类型；这是发布包显式子路径，不要下钻到 `frontend/src/common/request`。
 
 ### 前端多语言
 
-TemplateCore 前端通过 `@_tc/template-core/fe` 暴露 i18n 能力。框架内置中文、英文资源，项目可以继续追加自己的资源。
+TemplateCore 前端通过 `@_tc/template-core/fe` 暴露 i18n 能力。框架内置中文、英文资源，但不会在普通自定义页面 import 前端入口时自动注册，避免非 Dashboard 页面把框架文案整包带入运行时资源。
+
+默认 Dashboard 入口会自动调用 `registerFrontendI18nResources()`，所以 Dashboard、Schema CRUD、内置页头、语言切换等框架页面可以直接使用框架内置文案。自定义入口如果也要复用这些框架文案，需要在渲染前手动注册：
+
+```ts
+import { initApp, registerFrontendI18nResources } from '@_tc/template-core/fe'
+
+initApp(App, {
+  beforeRender: async () => {
+    await registerFrontendI18nResources()
+  },
+})
+```
+
+项目可以继续追加自己的资源或新增语种。
 
 **追加自定义语言资源**：
 
 ```ts
-import { i18nStore } from '@_tc/template-core/fe'
+import { addLanguageResources } from '@_tc/template-core/fe'
 
-i18nStore.getState().addResources('zh-CN', {
-  business: {
+addLanguageResources('zh-CN', {
+  app: {
     product: {
       menu: '商品管理',
       name: '商品名称',
@@ -385,8 +425,8 @@ i18nStore.getState().addResources('zh-CN', {
   },
 })
 
-i18nStore.getState().addResources('en-US', {
-  business: {
+addLanguageResources('en-US', {
+  app: {
     product: {
       menu: 'Products',
       name: 'Product name',
@@ -397,17 +437,49 @@ i18nStore.getState().addResources('en-US', {
 })
 ```
 
+**新增语种并切换**：
+
+```ts
+import { addLanguageResources, setLanguage } from '@_tc/template-core/fe'
+
+addLanguageResources('ja-JP', {
+  app: {
+    product: {
+      menu: '商品管理',
+    },
+  },
+})
+
+setLanguage('ja-JP')
+```
+
+`addLanguageResources()` 用于追加或新增某个语种的文案，默认会深合并同语种资源；传 `{ merge: false }` 可以替换该语种资源。`setResources(resources, { merge: true })` 可批量合并多语种资源。`LanguageSwitch` 默认会把已注册语种加入选项；需要自定义展示文案时仍可传入 `options`。
+
+React 组件 render 中使用 `useText()` 读取文案。它会订阅语言和资源变化，调用 `setLanguage()` 后组件会自动重渲染：
+
+```tsx
+import { useText } from '@_tc/template-core/fe'
+
+function ProductTitle() {
+  const text = useText()
+
+  return <h1>{text('$i18n::app.product.menu')}</h1>
+}
+```
+
+`getText()` 是普通函数，适合请求错误、日志、校验工具或事件回调等非 React 场景；它不会主动触发 React 组件重渲染。
+
 资源注册时不写 `$i18n::` 前缀，配置中使用时才写：
 
 ```ts
-const title = '$i18n::business.product.createTitle'
+const title = '$i18n::app.product.createTitle'
 ```
 
 **在 model / Schema 配置中使用**：
 
 ```ts
 {
-  name: '$i18n::business.product.menu',
+  name: '$i18n::app.product.menu',
   moduleType: 'schema',
   schemaConfig: {
     schema: {
@@ -415,7 +487,7 @@ const title = '$i18n::business.product.createTitle'
       properties: {
         name: {
           type: 'string',
-          label: '$i18n::business.product.name',
+          label: '$i18n::app.product.name',
           minLength: 2,
           createFormOption: {
             comType: 'input',
@@ -429,7 +501,7 @@ const title = '$i18n::business.product.createTitle'
     tableConfig: {
       headerButtons: [
         {
-          label: '$i18n::business.product.create',
+          label: '$i18n::app.product.create',
           eventKey: 'callComponent',
           eventOption: { comName: 'createForm' },
         },
@@ -437,7 +509,7 @@ const title = '$i18n::business.product.createTitle'
     },
     componentConfig: {
       createForm: {
-        title: '$i18n::business.product.createTitle',
+        title: '$i18n::app.product.createTitle',
         saveBtnText: '$i18n::common.submit',
       },
     },
@@ -502,7 +574,7 @@ export function Toolbar() {
 }
 ```
 
-`ThemeSwitch` 会切换 `document.documentElement` 上的 `dark` class，并同步 `color-scheme`。默认写入 localStorage，key 是 `tc_theme`。刷新页面后会优先读取本地主题；没有本地主题时，读取当前根节点是否已有 `dark` class。
+`ThemeSwitch` 会切换 `document.documentElement` 上的 `dark` class，并同步 `color-scheme`。默认写入 localStorage，key 是 `tc_theme`。刷新页面后会优先读取本地主题；没有本地主题时，读取当前根节点是否已有 `dark` class。默认 Dashboard 会在渲染前调用 `initThemeMode()`，让已保存主题尽早生效。
 
 常用参数：
 
@@ -514,6 +586,21 @@ export function Toolbar() {
 | `persist` | 是否写入 localStorage，默认 `true`。 |
 | `storageKey` | 自定义本地存储 key，默认 `tc_theme`。 |
 
+如需在自定义入口或组件外手动初始化/切换主题，可以从 `@_tc/template-core/fe` 导入主题工具：
+
+```ts
+import { applyThemeMode, getCurrentThemeMode, initThemeMode, themeSwitchStorageKey } from '@_tc/template-core/fe'
+
+initThemeMode()
+applyThemeMode('dark', true)
+```
+
+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 的接口和拦截器机制，提供了签名、鉴权、错误处理等能力。
@@ -523,6 +610,7 @@ export function Toolbar() {
 - `timeout`：15000ms（15秒）
 - `credentials`：`'include'`，支持跨域携带 cookie
 - `window._signKey`：由服务端页面模板从 `app.config.signKey` 注入
+- 默认会先设置 `Content-Type: application/json`；如果是上传文件、`FormData` 或其他内容类型，请在请求配置里显式覆盖
 
 **请求拦截器**：
 
@@ -879,7 +967,7 @@ const unsafeUsers = app.extends.db.queryDB(
 )
 ```
 
-业务项目可以用自己的 `app/extends/db.ts` 覆盖默认实现。建议保留同一组方法名，这样 controller/service 调用方不用调整。
+项目可以用自己的 `app/extends/db.ts` 覆盖默认实现。建议保留同一组方法名，这样 controller/service 调用方不用调整。
 
 ```ts
 // app/extends/db.ts
@@ -995,7 +1083,7 @@ export default (app: KoaApp, router: Router) => {
 - 每个 `app/router/*.ts` 文件都会获得独立的 `koa-router` 实例。
 - 可以通过 `router.level = number` 控制挂载顺序，数值越小越早挂载。
 - 默认 `level` 是 `0`，框架兜底 router 是 `99`。
-- 通配、兜底、重定向类路由建议设置较大的 `level`，避免抢先匹配业务 API。
+- 通配、兜底、重定向类路由建议设置较大的 `level`，避免抢先匹配项目 API。
 
 ```ts
 import type { KoaApp, Router } from '@_tc/template-core'
@@ -1284,7 +1372,7 @@ DELETE {api}        -> 删除
 
 ### 服务端兜底路由守卫
 
-业务项目可以创建 `app/router-guard.ts` 或 `app/router-guard.js`。它只在所有正常 `app/router/*` 路由都没有命中时执行。
+项目可以创建 `app/router-guard.ts` 或 `app/router-guard.js`。它只在所有正常 `app/router/*` 路由都没有命中时执行。
 
 ```ts
 import type { Ctx, KoaApp } from '@_tc/template-core'
@@ -1309,7 +1397,7 @@ export default (_app: KoaApp) => {
 
 ### 扩展 Dashboard 顶部用户区域
 
-业务项目可以创建 `frontend/extended/dash/components.tsx`，通过组件映射填充内置 Dashboard 页头右侧区域。
+项目可以创建 `frontend/extended/dash/components.tsx`，通过组件映射填充内置 Dashboard 页头右侧区域。
 
 ```tsx
 // frontend/extended/dash/components.tsx
@@ -1330,7 +1418,7 @@ export default components
 
 ### 扩展 Dashboard 登录守卫
 
-业务项目可以创建 `frontend/extended/dash/routeGuard.ts`，用于在 Dashboard 内置 `homePage` / 首菜单重定向前做登录判断。
+项目可以创建 `frontend/extended/dash/routeGuard.ts`，用于在 Dashboard 内置 `homePage` / 首菜单重定向前做登录判断。
 
 ```ts
 // frontend/extended/dash/routeGuard.ts
@@ -1346,9 +1434,9 @@ export default dashRouteGuard
 返回值规则：
 
 - 返回 `string`：框架使用 `window.location.href` 跳转，登录页不需要在 Dash 路由下。
-- 返回非 `string`：中断 Dashboard 内置重定向，业务方可自行跳转或处理提示。
+- 返回非 `string`：中断 Dashboard 内置重定向，使用方可自行跳转或处理提示。
 - `DashRouteGuardResult` 是 `string | undefined`；`undefined`（包括已登录分支的隐式返回）也会打断 Dashboard 内置重定向。
-- 没有业务 `routeGuard` 文件时，框架使用兜底空对象，不影响默认 Dashboard 重定向。
+- 没有自定义 `routeGuard` 文件时，框架使用兜底空对象，不影响默认 Dashboard 重定向。
 
 ### 扩展 SchemaForm 字段组件
 
@@ -1518,6 +1606,90 @@ remark: {
 }
 ```
 
+### 扩展 SchemaTable 单元格渲染组件
+
+SchemaPage 表格列支持通过 `tableOption.renderComponent` 使用内置或自定义注册的渲染组件。内置组件：
+
+- `PreviewImage`：把当前单元格值渲染成图片预览；值是数组时直接作为图片列表，值是单个字符串时自动转成单图数组。
+
+直接使用内置组件：
+
+```ts
+cover: {
+  type: 'string',
+  label: '封面',
+  tableOption: {
+    renderComponent: 'PreviewImage',
+    renderComponentProps: {
+      width: 48,
+      height: 48,
+    },
+  },
+}
+```
+
+自定义渲染组件时，先声明 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
+      }
+    }
+  }
+}
+```
+
+注册运行时组件：
+
+```ts
+// frontend/extended/SchemaPage/SchemaTable/data.ts
+import { lazy } from 'react'
+import type { SchemaTableRenderComponentsMap } from '@_tc/template-core/fe'
+
+const componentsMap = {
+  PriceCell: lazy(() => import('../../components/PriceCell')),
+} satisfies SchemaTableRenderComponentsMap
+
+export default componentsMap
+```
+
+组件会收到 `value`、`record`、`rowIndex`、`fieldKey`，以及 `renderComponentProps` 中的自定义参数：
+
+```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 中使用：
+
+```ts
+price: {
+  type: 'number',
+  label: '价格',
+  tableOption: {
+    renderComponent: 'PriceCell',
+    renderComponentProps: {
+      currency: '¥',
+    },
+  },
+}
+```
+
 ## 如何配置类型扩展
 
 ### tsconfig
@@ -1617,6 +1789,22 @@ declare module '@_tc/template-core/model' {
 - `OptionMap` 对应字段上的 `xxxOption`。
 - 运行时组件注册在 `frontend/extended/SchemaPage/CallCom/data.ts`。
 
+### SchemaTable 渲染组件类型扩展
+
+扩展目标：
+
+```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` 只配置自定义参数。
+
 ### KoaApp 类型扩展
 
 使用方推荐增强根包 `@_tc/template-core`：
@@ -1970,6 +2158,6 @@ await buildBE({
 - `model` 数组合并依赖稳定 `key`。
 - Dashboard 默认需要 URL 带 `?projk=项目key`。
 - Dashboard 登录守卫放在 `frontend/extended/dash/routeGuard.ts`；登录页通常不在 Dash 路由下，返回登录页 URL 即可。
-- 服务端兜底守卫放在业务 `app/router-guard.ts|js`，不是 `app/business` 子目录。
+- 服务端兜底守卫放在项目根目录的 `app/router-guard.ts|js`。
 - 前端入口必须命名为 `.entry.tsx`、`.entry.ts`、`.entry.jsx` 或 `.entry.js`。
 - 入口同目录的 `.html` 只能作为插槽文件使用，不能写完整 HTML 文档；页面外壳始终由 `app/view/entry.tpl` 生成。

package/cjs/app/controller/view.js

@@ -1 +1 @@
-const e=require(`../../packages/common/string/index.js`);var t=e=>JSON.stringify(e).replace(/</g,`\\u003c`).replace(/>/g,`\\u003e`).replace(/&/g,`\\u0026`).replace(/\u2028/g,`\\u2028`).replace(/\u2029/g,`\\u2029`),n=(n=>class{async renderPage(r,i){let a=r.path;if(n.extends.localCacheHtmlEtag.keepFreshFEBuildKey(),a.includes(`${n.options.apiPrefix}/`))await i();else{n.extends.logger.log(` - render page: `+r.params.page);try{let i=r.query.projk;Array.isArray(i)&&(i=e.joinStr(...i));let a={projKey:i??``,name:n.options?.name??``,env:n.envs.get(),basePath:t(`${n.options.pageBasePage}${r.params.page}`),projKeyJson:t(String(r.query.projk??``)),signKey:t(n.config.signKey),options:t(n.options)},o=n.extends.renderView(`${r.params.page}.entry.tpl`,r,a),s=e.joinStr(a.basePath,a.name,a.env,a.projKey);if(!n.extends.localCacheHtmlEtag.hasEtag(s)){let e=n.extends.crypto.hmacSign(o);n.extends.localCacheHtmlEtag.setEtag(s,e)}let c=n.extends.localCacheHtmlEtag.getEtag(s);c||console.log(`---- etag 缓存异常 请检查服务 ----`),r.etag=c??Date.now()+``}catch(e){console.log(`-------------- render view error --------------`),console.log(e),n.extends.generateErrorMessage(`template not found`,{status:404,showError:!0,code:0})}}}});module.exports=n;
+const e=require(`../../packages/common/string/index.js`);var t=e=>JSON.stringify(e).replace(/</g,`\\u003c`).replace(/>/g,`\\u003e`).replace(/&/g,`\\u0026`).replace(/\u2028/g,`\\u2028`).replace(/\u2029/g,`\\u2029`),n=(n=>class{async renderPage(r,i){let a=r.path;if(n.extends.localCacheHtmlEtag.keepFreshFEBuildKey(),a.includes(`${n.options.apiPrefix}/`))await i();else{n.extends.logger.log(` - render page: `+r.params.page);try{let i=r.query.projk;Array.isArray(i)&&(i=e.joinStr(...i));let a={projKey:i??``,name:n.options?.name??``,env:n.envs.get(),basePath:t(`${n.options.pageBasePage}${r.params.page}`),projKeyJson:t(String(r.query.projk??``)),signKey:t(n.config.signKey),options:t(n.options)},o=n.extends.renderView(`${r.params.page}.entry.tpl`,r,a),s=e.joinStr(a.basePath,a.name,a.env,a.projKey);if(!n.extends.localCacheHtmlEtag.hasEtag(s)){let e=n.extends.crypto.hmacSign(o);n.extends.localCacheHtmlEtag.setEtag(s,e)}let c=n.extends.localCacheHtmlEtag.getEtag(s);if(c||console.log(`---- etag 缓存异常 请检查服务 ----`),r.etag=c??Date.now()+``,r.fresh){r.status=304;return}}catch(e){console.log(`-------------- render view error --------------`),console.log(e),n.extends.generateErrorMessage(`template not found`,{status:404,showError:!0,code:0})}}}});module.exports=n;

package/cjs/bundler/buildFE.js

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`../packages/common/log/index.js`),t=require(`./state.js`),n=require(`./dev.js`),r=require(`./prod.js`);var i=(i,a)=>{switch(t.setBuildFEOptions(a),i){case`dev`:return n.dev();case`prod`:return r.prod();default:return e.logRed(`Usage: npx tsx scripts/index.ts [dev|prod]`),Promise.resolve()}};exports.buildFE=i;

package/cjs/bundler/index.js

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`../packages/common/log/index.js`),t=require(`./buildBE.js`),n=require(`./state.js`),r=require(`./dev.js`),i=require(`./prod.js`);var a=(t,a)=>{switch(n.setBuildFEOptions(a),t){case`dev`:return r.dev();case`prod`:return i.prod();default:return e.logRed(`Usage: npx tsx scripts/index.ts [dev|prod]`),Promise.resolve()}};exports.buildBE=t.buildBE,exports.buildFE=a;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`./buildBE.js`),t=require(`./buildFE.js`);exports.buildBE=e.buildBE,exports.buildFE=t.buildFE;