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

package/AGENT_README.md

@@ -0,0 +1,635 @@
+# TemplateCore AI 助手速读
+
+这份文档给在消费方项目中协助开发的 AI 助手/代码代理阅读。项目本身才是 `@_tc/template-core` 的使用方；AI 通过这份速读文档快速理解包的用法和边界。它是 `README.md` 的精简版，按渐进式披露组织：先用下面的最小信息完成常见任务，只有需要深入时再读末尾的参考文档。
+
+## 1. 先看结论
+
+TemplateCore 是一个 TypeScript + Koa + React 的后台框架包。它提供：
+
+- Koa 服务启动和约定式后端加载。
+- 内置 Dashboard、Schema CRUD 页面和 React UI 组件库。
+- `model/` 配置驱动的菜单、项目和 CRUD 页面。
+- 前端构建 `buildFE()` 输出服务端可渲染的 `.entry.tpl`，并写入 `FEBuildKey` 供 HTML ETag 缓存失效使用。
+- 消费方 Node/backend 构建 `buildBE()`。
+- 类型扩展机制，用于扩展 SchemaForm 字段、CallCom 组件和 Koa app 类型。
+
+优先使用公开入口，不要从包内部源码路径导入。下面这些入口以 npm 发布产物为准；源码仓库根 `package.json` 的 `exports` 会在构建发布包时生成到 `dist/package.json`。
+
+| 入口 | 用途 |
+| --- | --- |
+| `@_tc/template-core` | `serverStart`、`baseFn`、Koa/Controller/Service 类型。 |
+| `@_tc/template-core/bundler` | `buildFE()`、`buildBE()`。 |
+| `@_tc/template-core/fe` | 前端初始化、请求方法、Dashboard/Schema 类型、共享状态、业务前端组件。 |
+| `@_tc/template-core/fe/common/request` | 请求实例、请求方法和请求类型的显式子路径。 |
+| `@_tc/template-core/fe/rc` | React UI 组件和 SchemaForm 组件。 |
+| `@_tc/template-core/fe/tailwind_ui.css` | 内置前端/UI 全局样式。 |
+| `@_tc/template-core/model` | `ModelDataType` 等 model 配置类型。 |
+
+## 2. 最小业务项目
+
+推荐结构：
+
+```text
+my-admin/
+├── app/
+│   ├── controller/
+│   │   └── product.ts
+│   └── router/
+│       └── product.ts
+├── config/
+│   └── config.default.ts
+├── model/
+│   └── product/
+│       ├── mode.ts
+│       └── project/
+│           └── demo.ts
+└── index.ts
+```
+
+启动入口：
+
+```ts
+import { join } from 'path'
+import { serverStart } from '@_tc/template-core'
+import { buildFE } from '@_tc/template-core/bundler'
+
+async function main() {
+  await serverStart({
+    name: 'my-admin',
+    baseDir: join(__dirname, '.'),
+  })
+
+  await buildFE('dev')
+}
+
+main().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})
+```
+
+只使用后端能力时，可以不调用 `buildFE('dev')`。
+
+配置：
+
+```ts
+// config/config.default.ts
+export default {
+  port: 9000,
+  auth: {
+    ATKey: 'Authorization',
+    RTKey: 'RT',
+  },
+}
+```
+
+`auth.ATKey` / `auth.RTKey` 是业务鉴权中间件读取短 token 和刷新 token header 的默认约定；默认分别是 `Authorization` / `RT`。
+
+访问内置后台：
+
+```text
+http://localhost:9000/dash?projk=demo
+```
+
+`projk` 对应 `model/{modelKey}/project/{projectKey}.ts` 里的 `projectKey`，运行时按 project key 全局查找，建议保持全局唯一。
+
+## 3. 后端约定
+
+`serverStart({ baseDir })` 会按目录自动加载业务代码；`model/` 由内置 project service 通过 `modelLoader(app)` 读取，不会在 `serverStart` 阶段直接挂到 `app.model`：
+
+```text
+app/controller/**/*.(js|ts)      -> app.controller
+app/service/**/*.(js|ts)         -> app.service
+app/middlewares/**/*.(js|ts)     -> app.middlewares
+app/middleware.(js|ts)           -> 全局中间件编排，按 frame -> business 顺序执行
+app/router/**/*.(js|ts)          -> Koa router
+app/router-guard.(js|ts)         -> 兜底路由守卫
+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 读取的项目模型配置
+```
+
+常用后端类型：
+
+| 类型 | 使用场景 |
+| --- | --- |
+| `Ctx` | Controller、middleware、router handler 的请求上下文，包含 `ctx.params` 和可选 `ctx.reqData`。 |
+| `ControllerFN` | 约束 `app/controller/*.ts` 默认导出的 controller 工厂。 |
+| `ServiceFN` | 约束 `app/service/*.ts` 默认导出的 service 工厂。 |
+| `MiddlewareFN` | 约束 `app/middlewares/*.ts` 默认导出的 middleware 工厂。 |
+| `RouterFN` | 约束 `app/router/*.ts` 默认导出的路由注册函数。 |
+
+`ctx.reqData` 是 API 请求的统一参数入口：
+
+- `ctx.reqData.query` 来自 `ctx.query`。
+- `ctx.reqData.body` 来自 `ctx.request.body`。
+- `ctx.reqData.headers` 来自 `ctx.headers`。
+- `ctx.reqData.data` 按 `query -> body` 合并；字段冲突时 body 覆盖 query。
+- router params 不在 `reqData` 里，继续用 `ctx.params`。
+
+Controller 示例：
+
+```ts
+import { baseFn, type ControllerFN, type Ctx } from '@_tc/template-core'
+
+const products = [
+  { product_id: '1', product_name: '商品 A', price: 100 },
+]
+
+const getProductController = ((app) => {
+  const BaseController = baseFn.baseControllerFn(app)
+
+  return class ProductController extends BaseController {
+    list = async (ctx: Ctx) => {
+      this.success(ctx, {
+        data: products,
+        page: Number(ctx.reqData?.data.page || 1),
+        pageSize: Number(ctx.reqData?.data.pageSize || 10),
+        total: products.length,
+      })
+    }
+
+    detail = async (ctx: Ctx) => {
+      const item = products.find((product) => {
+        return product.product_id === ctx.reqData?.data.product_id
+      })
+
+      this.success(ctx, item ?? null)
+    }
+  }
+}) satisfies ControllerFN
+
+export default getProductController
+```
+
+Router 示例：
+
+```ts
+import type { RouterFN } from '@_tc/template-core'
+
+export default ((app, router) => {
+  router.get('/api/product/list', app.controller.product.list)
+  router.get('/api/product', app.controller.product.detail)
+}) satisfies RouterFN
+```
+
+路由挂载顺序：
+
+- 每个 `app/router/*.ts` 文件都会获得独立的 `koa-router` 实例。
+- 可以通过 `router.level = number` 控制挂载顺序，数值越小越早挂载。
+- 默认 `level` 是 `0`，框架兜底 router 是 `99`。
+- 通配、兜底、重定向类路由建议设置较大的 `level`，避免抢先匹配业务 API。
+
+```ts
+import type { RouterFN } from '@_tc/template-core'
+
+export default ((app, router) => {
+  router.level = 10
+  router.get('/api/fallback/:id', app.controller.fallback.detail)
+}) satisfies RouterFN
+```
+
+内置响应约定：`BaseController.success(ctx, data)` 返回 `{ data, code: 0, message: 'ok' }`。
+
+兜底路由守卫：
+
+```ts
+// app/router-guard.ts
+import type { Ctx, KoaApp } from '@_tc/template-core'
+
+export default (_app: KoaApp) => {
+  return (ctx: Ctx) => {
+    if (!ctx.path.startsWith('/api/')) return '/dash'
+  }
+}
+```
+
+`router-guard` 只在所有正常 router 都没命中时执行。返回字符串会重定向；返回 `{ status, body }` 会直接设置响应；无返回则走默认兜底：API 路径返回 HTTP 200 + `{ code: 404, message }`，非 API 路径返回 HTTP 404 + `notFound`。
+
+内置扩展：
+
+- `app.extends.$fetch`：Node 侧 axios 风格 fetch 实例。
+- `app.extends.crypto`：Node 侧加密辅助方法，支持 base64url 编解码、HMAC 签名、签名 payload 和常量时间比较。
+- `app.extends.db`：默认 SQLite 数据存储，可用业务 `app/extends/db.ts` 覆盖。
+
+## 4. model 配置
+
+`model` 是内置 Dashboard 和 Schema CRUD 的数据源。
+
+```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: '商品管理',
+  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
+```
+
+`project/demo.ts` 示例：
+
+```ts
+export default {
+  name: 'Demo 企业',
+  desc: 'Demo 企业商品后台',
+  homePage: '/_sidebar_/product?projk=demo',
+}
+```
+
+合并规则：
+
+- `project` 会继承同目录上层 `mode`。
+- 对象递归合并，`project` 覆盖 `mode`。
+- 数组按 `key` 合并：同 key 覆盖，不同 key 新增。
+- `model/index.ts` 和 `model/index.js` 会被 loader 跳过。
+
+常见菜单模块：
+
+| `moduleType` | 用途 |
+| --- | --- |
+| `schema` | 配置驱动 CRUD 页面，使用 `schemaConfig`。 |
+| `custom` | 自定义前端页面，使用 `customConfig.path`。 |
+| `iframe` | iframe 页面，使用 `iframeConfig.path`。 |
+| `sidebar` | 顶部菜单下挂左侧菜单，使用 `sidebarConfig.menu`。 |
+
+## 5. 前端使用
+
+使用内置组件或自定义前端入口时，确保引入样式：
+
+```ts
+import '@_tc/template-core/fe/tailwind_ui.css'
+```
+
+前端公共能力优先从 `@_tc/template-core/fe` 导入：
+
+```ts
+import {
+  api,
+  get,
+  post,
+  request,
+  schemaEventBus,
+  schemaStore,
+  useSchemaStore,
+  LanguageSwitch,
+  ThemeSwitch,
+} from '@_tc/template-core/fe'
+
+import type {
+  BaseResponse,
+  RequestConfig,
+  ResponseConfig,
+} from '@_tc/template-core/fe'
+```
+
+只需要请求层时，可以走显式子路径：
+
+```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'
+```
+
+UI 组件从 `@_tc/template-core/fe/rc` 导入：
+
+```tsx
+import { Button, DataTable, Form, Input, Modal, Select } from '@_tc/template-core/fe/rc'
+```
+
+常用前端能力：
+
+- 请求方法：`api`、`request`、`get`、`post`、`put`、`patch`、`del`。
+- 请求类型：`BaseResponse`、`PageParams`、`PageResponse`、`RequestConfig`、`ResponseConfig`、`AxiosError`。
+- 请求 header：自动添加 `s_t`、`s_sign`、`projk`；存在短 token 时添加 `Authorization: Bearer ${token}`。
+- 本地 key：短 token 是 `localStorage.auth_token`，项目 key 是 `localStorage.p_J_k`；刷新 token header 默认名是 `RT`。
+- `getAuthToken()` 是同步函数，读取前无需 `await`。
+- Schema 通信：`schemaEventBus`、`eventsInfo`、`merge`。
+- 共享状态：`modeStore`、`schemaStore`、`apiFreezerStore` 及对应 hooks。
+- 多语言：`i18nStore.getState().addResources()`，配置文案可写 `$i18n::...`。
+- 主题：`ThemeSwitch` 会同步根节点 `dark` class 和 `localStorage`。
+- `Input type="password"` 会自动显示密码显隐按钮；`allowClear` 不作用于密码输入。
+
+不要直接依赖 `frontend/src/...`、`packages/react/ui/...` 这类包内部路径。
+
+### 自定义前端入口和 HTML 插槽
+
+前端入口必须命名为 `.entry.tsx`、`.entry.ts`、`.entry.jsx` 或 `.entry.js`，否则 `buildFE()` 不会扫描。
+
+最小入口：
+
+```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,
+  beforeRender: async () => {
+    // 注册请求拦截器等渲染前初始化逻辑
+  },
+  afterRender: () => {
+    // 首次渲染提交后的逻辑
+  },
+})
+```
+
+如果需要给页面加额外 `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` 也由它注入。构建器会把合成后的临时 HTML 写入 `.tc-entry-html/`，这个目录不要提交，也不要在业务代码中引用。
+
+## 6. 构建
+
+前端资源构建：
+
+```ts
+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 构建：
+
+```ts
+import { buildBE } from '@_tc/template-core/bundler'
+
+await buildBE()
+```
+
+`buildBE()` 默认：
+
+- 构建当前工作目录的 `index.ts`、`index.js`、`app`、`config`、`model`。
+- 输出到 `dist`。
+- 输出格式为 `cjs`。
+- 外部化 Node 内置模块和 npm 包。
+- 默认不生成 `.d.ts`。
+- 默认不注入 alias；需要时显式传 `alias`。
+
+自定义示例：
+
+```ts
+await buildBE({
+  input: ['app', 'config', 'model/index.ts'],
+  outDir: 'dist',
+  format: ['es', 'cjs'],
+  dts: true,
+  alias: {
+    '@app': './app',
+    '@model': './model',
+  },
+})
+```
+
+消费方脚本示例：
+
+```js
+// scripts/build-be.mjs
+import { buildBE } from '@_tc/template-core/bundler'
+
+await buildBE({
+  input: ['index.ts', 'index.js', 'app', 'config', 'model'],
+  outDir: 'dist',
+  format: 'cjs',
+})
+```
+
+监听文件变化重新构建：
+
+```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 {
+    await buildBE({ input, outDir: 'dist', format: 'cjs' })
+  } finally {
+    building = false
+
+    if (pending) {
+      pending = false
+      await runBuild()
+    }
+  }
+}
+
+await runBuild()
+
+chokidar
+  .watch(input, {
+    ignored: ['dist/**', 'node_modules/**'],
+    ignoreInitial: true,
+  })
+  .on('all', runBuild)
+```
+
+```json
+{
+  "scripts": {
+    "build:be": "node scripts/build-be.mjs",
+    "build:be:watch": "node scripts/watch-be.mjs"
+  }
+}
+```
+
+## 7. 常见任务速查
+
+新增后端接口：
+
+1. 在 `app/controller/*.ts` 写 controller。
+2. 在 `app/router/*.ts` 注册路由。
+3. 返回数据时优先用 `this.success(ctx, data)`。
+
+新增一个 Schema CRUD 页面：
+
+1. 在 `model/{modelKey}/mode.ts` 或 `project/{projectKey}.ts` 添加菜单项。
+2. 菜单项使用 `menuType: 'module'`、`moduleType: 'schema'`。
+3. `schemaConfig.api` 指向后端资源 API。
+4. 字段在 `schema.properties` 中配置 `tableOption`、`searchOption`、`createFormOption`、`editFormOption`、`detailPanelOption`。
+5. 需要新增/编辑/详情时，在 `componentConfig` 和 `tableConfig` 配置按钮与弹层。
+
+新增自定义前端页面：
+
+1. 在业务 `frontend/` 下添加入口 `*.entry.tsx`。
+2. 需要样式时引入 `@_tc/template-core/fe/tailwind_ui.css`。
+3. 如需改 head 或 root 前后内容，只添加入口同目录 `.html` 插槽文件，不要写完整 HTML。
+4. 在 `model` 菜单中使用 `moduleType: 'custom'`，让 `customConfig.path` 指向页面路径。
+5. 使用 `buildFE('dev')` 或 `buildFE('prod')` 生成资源。
+
+扩展前端类型或组件：
+
+1. SchemaForm 字段类型、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`。
+
+## 8. 继续深入
+
+需要更多信息时，按任务读取：
+
+| 任务 | 建议阅读 |
+| --- | --- |
+| 完整安装和使用说明 | npm 包根目录 `README.md` |
+| 生成项目、model、CRUD | npm 包：`.skills/tc-generator/SKILL.md`；源码仓库：`skills/tc-generator/SKILL.md` |
+| 组件选型和用法 | npm 包：`.skills/tc-component-usage-skills/SKILL.md`；源码仓库：`skills/tc-component-usage-skills/SKILL.md` |
+| model/schema 配置细节 | npm 包：`.skills/tc-generator/reference/model-schema.md`；源码仓库：`skills/tc-generator/reference/model-schema.md` |
+| 完整 CRUD 示例 | npm 包：`.skills/tc-generator/reference/example.md`；源码仓库：`skills/tc-generator/reference/example.md` |
+| 可复制项目骨架 | npm 包：`.skills/tc-generator/reference/project-template/`；源码仓库：`skills/tc-generator/reference/project-template/` |
+| UI 组件现场预览 | 启动服务后访问 `/ui-components` |
+| 已安装包的类型细节 | 查看对应公开入口的 `.d.ts` 文件 |
+
+如果当前环境是源码仓库而不是 npm 安装目录，还可以继续读 `docs/`、`frontend/README.md`、`model/README.md`、`bundler/README.md` 和 `BUILD.md`。