@_tc/template-core 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,1108 @@
+# @_tc/template-core
+
+TemplateCore 是一个基于 TypeScript、Koa、React 的后台框架包。它把后端约定式加载、前端 Dashboard、Schema CRUD 页面、模型配置和类型扩展放到同一个 npm 包里，项目只需要按目录补充自己的 `app/`、`model/`、`frontend/`。
+
+## 安装
+
+```bash
+pnpm add @_tc/template-core
+```
+
+要求：
+
+- Node.js >= 18
+- pnpm >= 8
+- 使用内置前端时，需要安装 React、Vite 等 peer dependencies
+
+## 快速使用
+
+项目建议结构：
+
+```text
+my-admin/
+├── app/
+│   ├── controller/
+│   │   └── product.ts
+│   ├── router/
+│   │   └── product.ts
+│   └── service/
+├── config/
+│   └── config.default.ts
+├── frontend/
+│   ├── src/          # 库代码
+│   ├── apps/         # 应用入口
+│   └── extended/     # 扩展点
+├── model/
+│   └── product/
+│       ├── mode.ts
+│       └── project/
+│           └── demo.ts
+├── typing/
+│   └── template-core.d.ts
+└── index.ts
+```
+
+启动入口：
+
+```ts
+import { join } from 'path'
+import { serverStart } from '@_tc/template-core'
+import { buildFE } from '@_tc/template-core/bundler'
+
+serverStart({
+  name: 'my-admin',
+  baseDir: join(__dirname, '.'),
+  pageBasePage: '/',
+})
+
+buildFE('dev')
+```
+
+只用后端能力时，可以不调用 `buildFE('dev')`。
+
+### serverStart 参数说明
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| `name` | `string` | 否 | - | 应用名称 |
+| `baseDir` | `string` | 否 | - | 项目根目录，通常为 `join(__dirname, '.')` |
+| `pageBasePage` | `string` | 否 | `'/'` | 页面访问前缀，所有前端页面路由的基础路径 |
+| `homePage` | `string` | 否 | - | 应用首页路径 |
+| `frameBaseDir` | `string` | 否 | - | 框架根目录，通常不需要手动设置 |
+
+框架会自动读取 `config/config.default.ts` 中的配置（如 `port`、`host`、`env` 等）。
+
+### buildFE 参数说明
+
+```ts
+buildFE(mode: 'dev' | 'prod', options?: BuildFEOptions)
+```
+
+**mode**：构建模式
+- `'dev'`：开发模式，启动 Vite 开发服务器，支持热更新
+- `'prod'`：生产模式，构建优化后的静态资源
+
+**options.output**：构建输出位置
+- `'frame'`（默认）：输出到框架包内的 `node_modules/@_tc/template-core/app/public/dist`
+- `'run'`：输出到项目根目录的 `app/public/dist`，适合 TypeScript 编译后的项目
+- `() => string`：自定义函数，返回输出目录的绝对路径
+
+示例：
+
+```ts
+// 开发模式，默认输出到框架包
+buildFE('dev')
+
+// 生产模式，输出到项目目录
+buildFE('prod', { output: 'run' })
+
+// 自定义输出路径
+buildFE('prod', {
+  output: () => join(__dirname, 'dist/public')
+})
+```
+
+配置文件：
+
+```ts
+// config/config.default.ts
+export default {
+  port: 9000,
+  host: '0.0.0.0',
+}
+```
+
+访问默认后台：
+
+```text
+http://localhost:9000/dash?projk=demo
+```
+
+`projk` 对应 `model/{modelKey}/project/{projectKey}.ts` 里的 `projectKey`。
+
+## 公开入口
+
+| 入口 | 用途 |
+| --- | --- |
+| `@_tc/template-core` | 服务启动、基础 Controller/Service、Koa 类型 |
+| `@_tc/template-core/bundler` | 前端构建函数 `buildFE` |
+| `@_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 配置类型 |
+
+## 样式与 Tailwind V4
+
+使用内置前端或 UI 组件时，需要引入包内样式。默认 `@_tc/template-core/fe` 的 `initApp` 会经过源码入口 `frontend/src/main.tsx` 引入 `frontend/src/main.css`；如果项目侧自定义入口、只使用 `fe/rc` 组件，或希望样式入口更明确，建议显式引入：
+
+```ts
+// frontend/xxx/xxx.entry.tsx
+import '@_tc/template-core/fe/tailwind_ui.css'
+```
+
+如果项目有自己的全局样式入口，也可以在 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"
+}
+```
+
+多入口项目可以写成对象：
+
+```json
+{
+  "tailwindCSS.experimental.configFile": {
+    "frontend/main.css": "frontend/**/*.{ts,tsx,js,jsx}",
+    "frontend/admin/admin.css": "frontend/admin/**/*.{ts,tsx,js,jsx}"
+  }
+}
+```
+
+## 内置功能
+
+- Koa 服务启动：`serverStart(options)`。
+- 约定式加载：自动加载 `config`、`extend`、`router-schema`、`service`、`controller`、`middleware`、`router`。
+- 双层 app：框架内置 `app/` 和项目 `app/` 一起加载。
+- 默认项目接口：
+  - `GET /api/project/model_list`
+  - `GET /api/project/list`
+  - `GET /api/project/:key`
+- React Dashboard：内置 `/dash` 页面入口。
+- 组件预览页面：内置 `/testPage` 页面，用于查看和测试框架内置的 UI 组件。
+- 菜单渲染：支持 `schema`、`custom`、`iframe`、`sidebar`。
+- Schema CRUD：根据 `model` 中的 `schemaConfig` 生成搜索、表格、新增、编辑、详情。
+- 内置 UI 组件：提供丰富的 React 组件库，详见下方"内置 UI 组件"章节。
+- API 中间件：错误处理、静态资源、body parser、项目上下文、接口签名、参数校验。
+- 前端构建：扫描 `frontend/**/*.entry.{ts,tsx,js,jsx}`，输出服务端可渲染的 `.entry.tpl`。
+- 类型扩展：支持扩展 SchemaForm、CallCom、KoaApp。
+
+## 前端公共能力
+
+项目侧需要 TemplateCore 前端能力时，优先从 `@_tc/template-core/fe` 导入，不要直接依赖 `frontend/src/common/...`、`frontend/src/defaultPages/...`、`frontend/src/stores/...` 这类内部路径。
+
+```ts
+import {
+  apiFreezerStore,
+  eventsInfo,
+  FreezeState,
+  get,
+  merge,
+  modeStore,
+  post,
+  request,
+  schemaEventBus,
+  schemaStore,
+  useApiFreezer,
+  useModeStore,
+  useSchemaStore,
+} from '@_tc/template-core/fe'
+
+import type {
+  CallComComponentsMap,
+  CallComRenderer,
+  DashRoutesExtender,
+  FormFieldSchema,
+  ApiFreezerRequestMatcher,
+  SchemaFormComponentsMap,
+  SchemaFormNamespace,
+  SelectProps,
+} from '@_tc/template-core/fe'
+```
+
+当前公共入口包含：
+
+| 类型 | 导出内容 |
+| --- | --- |
+| 应用启动 | `initApp` |
+| Dash 扩展类型 | `DashRoutesExtender`、`DashRoutesContext` |
+| SchemaPage 类型 | `CallComComponentsMap`、`CallComRenderer` |
+| SchemaForm 类型 | `FormFieldSchema`、`SchemaFormComponentsMap`、`SchemaFormNamespace`、`SelectProps` |
+| 请求方法 | `request`、`get`、`post`、`put`、`patch`、`del` |
+| 请求冻结 | `apiFreezerStore`、`useApiFreezer`、`FreezeState`、`ApiFreezerRequestMatcher` |
+| 事件工具 | `eventsInfo`、`merge` |
+| 共享状态 | `modeStore`、`useModeStore`、`schemaStore`、`useSchemaStore`、`schemaEventBus` |
+
+`modeStore` 管项目模型和当前项目数据，`schemaStore` 管当前 Schema 页面的 schema/cache，`schemaEventBus` 用来在 Search、Table、CallCom 之间通信。
+
+### 前端请求封装详解
+
+框架内置的请求封装基于 `@tc/common/http`，底层使用原生 `fetch` API，实现了类似 Axios 的接口和拦截器机制，提供了签名、鉴权、错误处理等能力。
+
+**基础配置**：
+- `BASE_URL`：固定为 `/api`
+- `timeout`：15000ms（15秒）
+- `credentials`：`'include'`，支持跨域携带 cookie
+
+**请求拦截器**：
+
+每个请求会自动添加以下 headers：
+
+```ts
+{
+  's_t': '当前时间戳',
+  's_sign': 'md5(签名密钥_时间戳)',
+  'projk': '当前项目 key（从 localStorage 读取）',
+  'Authorization': 'Bearer token（如果已登录）'
+}
+```
+
+**签名机制**：
+- 签名密钥：`sakjdfnkjwjfnfkjkjldljksndf`（前后端需保持一致）
+- 签名算法：`md5(签名密钥_${时间戳})`
+- 服务端会在非 local 环境下校验签名和时间戳
+
+**响应拦截器**：
+
+- **401 处理**：自动清空 token 并跳转到 `/login`
+- **错误提取**：自动从响应中提取 `message`、`msg` 或 `errors` 字段
+- **超时处理**：请求超时会返回 "Request timed out"
+- **网络错误**：网络异常会返回 "Network error"
+
+**使用示例**：
+
+```ts
+import { get, post, put, del } 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: '新名称' })
+
+// DELETE 请求
+await del('/product', { id: 1 })
+```
+
+**请求冻结器**：
+
+请求冻结器用于在某段流程中暂停普通 API 请求，典型场景是 RT 刷新 token：刷新期间冻结其它请求，刷新接口本身走白名单放行，刷新完成后再解冻并回放队列。
+
+冻结器只在 `Freeze` 状态拦截请求；`Hibernation` 和 `Thawing` 状态都会直接放行。解冻时会按最多 4 个并发回放已冻结的请求；相同序列化参数的请求只会实际发送一次，多个调用方共享同一份响应或错误。
+
+```ts
+import { apiFreezerStore } from '@_tc/template-core/fe'
+
+const { freezing, thawing, setRequestWhitelist } = apiFreezerStore.getState()
+
+setRequestWhitelist([
+  '/auth/refresh',
+  /^\/auth\//,
+  (api) => api.includes('/refresh-token'),
+])
+
+freezing()
+
+try {
+  await refreshToken()
+} finally {
+  thawing()
+}
+```
+
+白名单支持三种 matcher：
+
+- `string`：精确匹配 API 路径
+- `RegExp`：正则匹配 API 路径
+- `(api, params) => boolean`：自定义判断，`params` 是请求函数收到的完整参数
+
+**注意事项**：
+- `get` 和 `del` 方法的参数会自动转为 query string
+- `post`、`put`、`patch` 方法的参数会作为 request body
+- 所有请求方法都会自动处理错误，无需手动 try-catch（除非需要自定义错误处理）
+- 底层使用原生 `fetch` API，但提供了类似 Axios 的拦截器和配置接口
+
+## 内置 UI 组件
+
+框架通过 `@_tc/template-core/fe/rc` 提供了丰富的 React 组件库，可在项目中直接使用。
+
+### 基础组件
+
+| 组件 | 用途 | 导入路径 |
+| --- | --- | --- |
+| `Button` | 按钮组件，支持多种样式和尺寸 | `@_tc/template-core/fe/rc` |
+| `Input` | 输入框组件 | `@_tc/template-core/fe/rc` |
+| `Select` | 下拉选择组件，支持单选和多选 | `@_tc/template-core/fe/rc` |
+| `DatePicker` | 日期选择器 | `@_tc/template-core/fe/rc` |
+| `Upload` | 文件上传组件 | `@_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` |
+| `TableSearch` | 表格搜索组件，配合 DataTable 使用 | `@_tc/template-core/fe/rc` |
+| `Pagination` | 分页组件 | `@_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` |
+| `Loading` | 加载状态组件 | `@_tc/template-core/fe/rc` |
+
+### 布局组件
+
+| 组件 | 用途 | 导入路径 |
+| --- | --- | --- |
+| `Layout` | 页面布局组件 | `@_tc/template-core/fe/rc` |
+| `Card` | 卡片容器组件 | `@_tc/template-core/fe/rc` |
+| `Tabs` | 标签页组件 | `@_tc/template-core/fe/rc` |
+
+### 使用示例
+
+```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>
+
+      <Input placeholder="请输入内容" />
+
+      <Select
+        options={[
+          { label: '选项1', value: '1' },
+          { label: '选项2', value: '2' },
+        ]}
+      />
+    </div>
+  )
+}
+```
+
+**注意**：
+- 所有组件都支持 TypeScript 类型提示
+- 组件样式基于 Tailwind CSS V4
+- 详细的组件 API 和示例可以访问 `/testPage` 页面查看
+
+## 后端约定
+
+项目目录会按下面规则加载：
+
+```text
+app/controller/**/*.(js|ts)      -> app.controller
+app/service/**/*.(js|ts)         -> app.service
+app/middleware/**/*.(js|ts)      -> app.middlewares
+app/router/**/*.(js|ts)          -> Koa router
+app/router-schema/**/*.(js|ts)   -> app.routerSchema
+app/extend/*.(js|ts)             -> app.extends
+config/config.default.(js|ts)    -> app.config
+config/config.{env}.(js|ts)      -> app.config
+model/**/*.(js|ts)               -> 项目模型配置
+```
+
+内置扩展：
+
+- `app.extends.$fetch`：Node 侧基于 `fetch` 的 axios 风格请求实例，支持 `get/post/put/patch/delete` 和 `create(config)`。
+
+Controller 示例：
+
+```ts
+import { baseFn, type ControllerFN, type Ctx } from '@_tc/template-core'
+
+const getProductController = ((app) => {
+  const BaseController = baseFn.baseControllerFn(app)
+
+  return class ProductController extends BaseController {
+    list = async (ctx: Ctx) => {
+      this.success(ctx, {
+        data: [],
+        page: 1,
+        pageSize: 10,
+        total: 0,
+      })
+    }
+  }
+}) satisfies ControllerFN
+
+export default getProductController
+```
+
+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)
+}
+```
+
+## model 数据如何配置
+
+`model` 是后台菜单、项目和 Schema 页面的数据源。框架会读取：
+
+```text
+model/{modelKey}/mode.ts
+model/{modelKey}/project/{projectKey}.ts
+```
+
+`mode.ts` 定义模型模板：
+
+```ts
+import type { ModelDataType } from '@_tc/template-core/model'
+
+const model: ModelDataType = {
+  mode: 'MB',
+  name: '商品后台',
+  desc: '商品管理',
+  icon: '',
+  homePage: '/dash?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
+```
+
+`project/demo.ts` 定义项目覆盖：
+
+```ts
+export default {
+  name: 'Demo 企业',
+  desc: 'Demo 企业商品后台',
+  homePage: '/dash?projk=demo',
+}
+```
+
+合并规则：
+
+- `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` 可以：
+
+```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 的配置
+  ],
+}
+```
+
+合并后的结果：
+
+```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` 的配置
+
+## model 数据如何引用
+
+后端可以直接调用 loader：
+
+```ts
+import { modelLoader, type KoaApp } from '@_tc/template-core'
+
+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
+```
+
+Dashboard 会根据 `projk` 请求 `/api/project/:key`，再按返回的 `menu` 渲染页面。
+
+Schema 页面的接口约定：
+
+```text
+GET    {api}/list   -> 表格列表
+GET    {api}        -> 编辑/详情拉取，参数由 fetchKey 决定
+POST   {api}        -> 新增
+PUT    {api}        -> 编辑
+DELETE {api}        -> 删除
+```
+
+`schema::字段名` 表示从当前表格行读取字段值，常用于删除按钮参数。
+
+## 如何扩展组件
+
+### 扩展 SchemaForm 字段组件
+
+1. 声明字段类型。
+2. 注册运行时组件。
+3. 在 `model` 的 `createFormOption`、`editFormOption`、`searchOption` 中使用。
+
+类型声明：
+
+```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
+    }
+
+    interface PropsMap {
+      businessSelect: SelectProps & {
+        requestUrl?: string
+        valueField?: string
+        labelField?: string
+      }
+    }
+  }
+}
+```
+
+运行时注册：
+
+```ts
+// 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
+
+export default componentsMap
+```
+
+model 中使用：
+
+```ts
+status: {
+  type: 'string',
+  label: '状态',
+  searchOption: {
+    comType: 'businessSelect',
+    requestUrl: '/api/status/options',
+    valueField: 'value',
+    labelField: 'label',
+  },
+}
+```
+
+### 扩展 SchemaPage CallCom
+
+CallCom 是 SchemaPage 中的弹窗、抽屉、面板类组件。内置组件有：
+
+- `createForm`
+- `editForm`
+- `detailPanel`
+
+声明配置类型：
+
+```ts
+// typing/template-core.d.ts
+import '@_tc/template-core/model'
+
+declare module '@_tc/template-core/model' {
+  export namespace CallComNamespace {
+    interface ConfigMap {
+      auditPanel: {
+        title: string
+        fetchKey: string
+        approveApi?: string
+      }
+    }
+
+    interface OptionMap {
+      auditPanel: {
+        visible?: boolean
+      }
+    }
+  }
+}
+```
+
+注册运行时组件：
+
+```ts
+// frontend/extended/SchemaPage/CallCom/data.ts
+import { lazy } from 'react'
+import type { CallComComponentsMap } from '@_tc/template-core/fe'
+
+const componentsMap = {
+  auditPanel: lazy(() => import('../../components/AuditPanel')),
+} satisfies CallComComponentsMap
+
+export default componentsMap
+```
+
+组件示例：
+
+```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),
+    })
+  }
+
+  return (
+    <div>
+      <div>审核对象：{String(props.data.id ?? '')}</div>
+      <button onClick={closeAndRefresh}>完成</button>
+    </div>
+  )
+}
+```
+
+model 中使用：
+
+```ts
+componentConfig: {
+  auditPanel: {
+    title: '审核',
+    fetchKey: 'id',
+    approveApi: '/api/audit/approve',
+  },
+},
+tableConfig: {
+  rowButtons: [
+    {
+      label: '审核',
+      eventKey: 'callComponent',
+      eventOption: {
+        comName: 'auditPanel',
+      },
+    },
+  ],
+},
+```
+
+字段级配置使用 `${组件名}Option`：
+
+```ts
+remark: {
+  type: 'string',
+  label: '备注',
+  auditPanelOption: {
+    visible: true,
+  },
+}
+```
+
+## 如何配置类型扩展
+
+### tsconfig
+
+如果项目分了后端、前端、model 多个 TS 上下文，确保它们都 include 同一份声明文件：
+
+```json
+{
+  "include": ["app/**/*", "model/**/*", "frontend/**/*", "typing/**/*.d.ts"]
+}
+```
+
+### SchemaForm 类型扩展
+
+扩展目标：
+
+```ts
+declare module '@_tc/template-core/fe/rc' {
+  export namespace SchemaFormNamespace {
+    interface FieldTypes {}
+    interface PropsMap {}
+  }
+}
+```
+
+- `FieldTypes` 用来增加字段类型名。
+- `PropsMap` 用来绑定该字段的 props 类型。
+- 类型声明只负责 TS 校验，运行时还必须在 `frontend/extended/SchemaForm/data.ts` 注册组件。
+
+### CallCom 类型扩展
+
+扩展目标：
+
+```ts
+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`。
+
+### KoaApp 类型扩展
+
+使用方推荐增强根包 `@_tc/template-core`：
+
+```ts
+// typing/template-core.d.ts
+import '@_tc/template-core'
+
+declare module '@_tc/template-core' {
+  namespace FrameworkAugment {
+    interface IServiceAugmented {
+      product: {
+        list(): Promise<unknown[]>
+      }
+    }
+
+    interface IControllerAugmented {
+      product: {
+        list(ctx: import('@_tc/template-core').Ctx): Promise<void>
+      }
+    }
+
+    interface IExtendsAugmented {
+      redis: {
+        get(key: string): Promise<string | null>
+      }
+    }
+
+    interface IMiddlewaresAugmented {
+      auth: import('koa').Middleware
+    }
+
+    interface AppConfigAugmented {
+      authSecret: string
+    }
+  }
+}
+```
+
+使用：
+
+```ts
+import type { KoaApp } from '@_tc/template-core'
+
+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/*` 内部路径。
+
+## 扩展自定义前端页面
+
+新增应用入口：
+
+```text
+frontend/admin/admin.entry.tsx
+```
+
+入口文件名必须包含 `.entry.`，构建器才会扫描。
+
+扩展 Dashboard 路由：
+
+```tsx
+// 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>,
+  })
+
+  sidebarRoutes.push({
+    path: 'custom-sidebar-page',
+    component: <div>Custom Sidebar Page</div>,
+  })
+}
+
+export default extendDashRoutes
+```
+
+**路径规则说明**：
+
+- **topRoutes**：追加到 Dashboard 顶层路由，路径相对于 `/dash`
+  - 示例：`path: 'custom-page'` → 访问路径为 `/dash/custom-page`
+  - 不要写成 `/custom-page`，使用相对路径即可
+
+- **sidebarRoutes**：追加到侧边栏容器的子路由，路径相对于 `/dash/_sidebar_`
+  - 示例：`path: 'custom-sidebar-page'` → 访问路径为 `/dash/_sidebar_/custom-sidebar-page`
+  - 适用于 `menuLayout: 'left'` 的项目
+
+model 中用 `custom` 菜单指向自定义路径：
+
+```ts
+{
+  key: 'custom',
+  name: '自定义页面',
+  menuType: 'module',
+  moduleType: 'custom',
+  customConfig: {
+    path: '/custom-page',  // 注意：这里使用完整路径，以 / 开头
+  },
+}
+```
+
+## 构建
+
+开发构建：
+
+```ts
+import { buildFE } from '@_tc/template-core/bundler'
+
+buildFE('dev')
+```
+
+生产构建：
+
+```ts
+buildFE('prod')
+```
+
+默认输出到框架包的 `app/public/dist`。如果要输出到项目：
+
+```ts
+buildFE('prod', {
+  output: 'run',
+})
+```
+
+## 注意事项
+
+- 不要在项目代码里引用 `dist/fe/*`、`dist/model/*` 这类构建产物路径。
+- npm 使用方只使用公开入口：`@_tc/template-core/*`。
+- SchemaForm 和 CallCom 的类型扩展、运行时注册都要做，少一个就只会“类型通过但页面不显示”或“页面能配但类型报错”。
+- `model` 数组合并依赖稳定 `key`。
+- Dashboard 默认需要 URL 带 `?projk=项目key`。
+- 前端入口必须命名为 `.entry.tsx`、`.entry.ts`、`.entry.jsx` 或 `.entry.js`。