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

package/.skills/tc-component-usage-skills/reference/template-core-frontend.md

@@ -19,7 +19,7 @@ Inside this repository, use `@tc/ui-react` for the raw UI workspace package. In
 <LanguageSwitch />
 ```
 
-Default languages are `zh-CN` and `en-US`. Pass `options` to replace the list. `onChange(language)` receives the selected language string. The component calls `i18nStore.getState().setLanguage()`, so it uses the same `tc_language` persistence as the UI i18n runtime.
+Default languages are `zh-CN` and `en-US`. Pass `options` to replace the list. The current UI is a button-triggered dropdown; `option.label` can be a ReactNode and `buttonClassName` customizes the trigger. `onChange(language)` receives the selected language string. The component calls `i18nStore.getState().setLanguage()`, so it uses the same `tc_language` persistence as the UI i18n runtime.
 
 Useful props:
 
@@ -31,6 +31,13 @@ interface LanguageSwitchProps {
   defaultValue?: LanguageSwitchValue
   options?: Array<{ label: ReactNode; value: LanguageSwitchValue; searchText?: string }>
   onChange?: (language: LanguageSwitchValue) => void
+  disabled?: boolean
+  loading?: boolean
+  placeholder?: string
+  clearable?: boolean
+  searchable?: boolean
+  buttonClassName?: string
+  getPopupContainer?: (() => HTMLElement) | 'parent'
 }
 ```
 

package/.skills/tc-generator/SKILL.md

@@ -28,10 +28,11 @@ Use this skill to generate or update TemplateCore business code.
 ## TemplateCore Conventions
 
 - Start the app with `serverStart({ name, baseDir })` from `@_tc/template-core`.
-- Start the built-in frontend with `await buildFE("dev")` from `@_tc/template-core/bundler` when the user needs the admin UI. The current API returns `Promise<void>`; in dev mode it performs the initial build, then watches the business `frontend/` directory.
+- Start the built-in frontend with `await buildFE("dev")` from `@_tc/template-core/bundler` when the user needs the admin UI. The current API returns `Promise<void>`; in dev mode it performs the initial build, then watches the business `frontend/` directory. Use `buildFE("prod", { output: "run", minifyHtml: true })` when the generated project should emit its own `app/public/dist` templates and compact final `.tpl` output.
+- `buildFE()` writes `FEBuildKey` into the output directory; the server uses it to invalidate local HTML ETag cache after frontend rebuilds.
 - If `buildFE("dev")` is used in a standalone project, include the TemplateCore peer dependencies or use the package manager's peer dependency auto-install behavior.
 - Business code lives under the user's `baseDir`, not inside TemplateCore framework folders.
-- The framework provides `app.extends.db` as a default SQLite-backed KV/SQL helper. Use it for small framework/business settings; override `app/extend/db.js` only when the project needs a custom storage implementation.
+- The framework provides `app.extends.db` as a default SQLite-backed KV/SQL helper. Use it for small framework/business settings; override `app/extends/db.js` only when the project needs a custom storage implementation.
 - Backend loaders map filenames to camelCase fields:
   - `app/controller/product.js` -> `app.controller.product`
   - `app/service/user-profile.js` -> `app.service.userProfile`

package/.skills/tc-generator/reference/example.md

@@ -34,7 +34,7 @@ async function main() {
     baseDir: join(__dirname, "."),
   });
 
-  buildFE("dev");
+  await buildFE("dev");
 }
 
 main().catch((error) => {

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/project-template/index.js

@@ -8,7 +8,7 @@ async function main() {
     baseDir: join(__dirname, "."),
   });
 
-  buildFE("dev");
+  await buildFE("dev");
 }
 
 main().catch((error) => {

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

@@ -74,7 +74,7 @@ module.exports = (app) => {
 };
 ```
 
-If the runtime does not support the built-in SQLite module or the project needs another store, generate `app/extend/db.js` or `app/extend/db.ts` and preserve the same method names so existing controllers keep working.
+If the runtime does not support the built-in SQLite module or the project needs another store, generate `app/extends/db.js` or `app/extends/db.ts` and preserve the same method names so existing controllers keep working.
 
 ## Default Crypto
 
@@ -257,7 +257,7 @@ import { Button, DataTable, TableSearch } from '@_tc/template-core/fe/rc'
 
 Inside this source repository, use `@tc/ui-react` for the raw UI workspace package. The `@_tc/template-core/fe/rc` path is for published TemplateCore consumers.
 
-`LanguageSwitch` updates the shared i18n language and persists through `tc_language`. `ThemeSwitch` toggles the root `dark` class and persists through `tc_theme`. `AsyncSelect` loads options from a `fetchConfig` endpoint returning `{ label, value, searchText? }[]`.
+`LanguageSwitch` is a button-triggered dropdown that updates the shared i18n language and persists through `tc_language`; use `buttonClassName` when the trigger needs custom sizing or styling. `ThemeSwitch` toggles the root `dark` class and persists through `tc_theme`. `AsyncSelect` loads options from a `fetchConfig` endpoint returning `{ label, value, searchText? }[]`.
 
 ## SchemaForm Extensions
 
@@ -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. 先看结论
 
@@ -9,8 +9,9 @@ TemplateCore 是一个 TypeScript + Koa + React 的后台框架包。它提供
 - Koa 服务启动和约定式后端加载。
 - 内置 Dashboard、Schema CRUD 页面和 React UI 组件库。
 - `model/` 配置驱动的菜单、项目和 CRUD 页面。
-- 前端构建 `buildFE()` 和消费方 Node/backend 构建 `buildBE()`。
-- 类型扩展机制，用于扩展 SchemaForm 字段、CallCom 组件和 Koa app 类型。
+- 前端构建 `buildFE()` 输出服务端可渲染的 `.entry.tpl`，并写入 `FEBuildKey` 供 HTML ETag 缓存失效使用。
+- 消费方 Node/backend 构建 `buildBE()`。
+- 类型扩展机制，用于扩展 SchemaForm 字段、SchemaTable 单元格渲染组件、CallCom 组件和 Koa app 类型。
 
 优先使用公开入口，不要从包内部源码路径导入。下面这些入口以 npm 发布产物为准；源码仓库根 `package.json` 的 `exports` 会在构建发布包时生成到 `dist/package.json`。
 
@@ -18,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 配置类型。 |
 
@@ -104,7 +107,7 @@ app/middleware.(js|ts)           -> 全局中间件编排，按 frame -> busines
 app/router/**/*.(js|ts)          -> Koa router
 app/router-guard.(js|ts)         -> 兜底路由守卫
 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)               -> 内置 project service 读取的项目模型配置
@@ -211,7 +214,7 @@ export default (_app: KoaApp) => {
 
 - `app.extends.$fetch`：Node 侧 axios 风格 fetch 实例。
 - `app.extends.crypto`：Node 侧加密辅助方法，支持 base64url 编解码、HMAC 签名、签名 payload 和常量时间比较。
-- `app.extends.db`：默认 SQLite 数据存储，可用业务 `app/extend/db.ts` 覆盖。
+- `app.extends.db`：默认 SQLite 数据存储，可用业务 `app/extends/db.ts` 覆盖。
 
 ## 4. model 配置
 
@@ -366,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'
@@ -400,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/...` 这类包内部路径。
 
@@ -480,9 +498,11 @@ import { buildFE } from '@_tc/template-core/bundler'
 
 await buildFE('dev')
 await buildFE('prod', { output: 'run' })
+await buildFE('prod', { output: 'run', minifyHtml: true })
 ```
 
 `buildFE('dev')` 是构建一次并监听业务 `frontend/` 变化后重建，不是 Vite dev server/HMR。
+`minifyHtml: true` 会压缩最终 `.tpl` 模板输出；构建完成后会写入 `FEBuildKey`，服务端渲染 HTML 时用它判断本地 HTML ETag 缓存是否需要清空。
 
 Node/backend 构建：
 
@@ -606,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. 继续深入