@_tc/template-core 0.0.1-bate.5 → 0.0.1-bate.50

package/AGENT_README.md

@@ -0,0 +1,506 @@
+# TemplateCore AI 助手速读
+
+这份文档给在消费方项目中协助开发的 AI 助手/代码代理阅读。项目本身才是 `@_tc/template-core` 的使用方；AI 通过这份速读文档快速理解包的用法和边界。它是 `README.md` 的精简版，按渐进式披露组织：先用下面的最小信息完成常见任务，只有需要深入时再读末尾的参考文档。
+
+## 1. 先看结论
+
+TemplateCore 是一个 TypeScript + Koa + React 的后台框架包。它提供：
+
+- Koa 服务启动和约定式后端加载。
+- 内置 Dashboard、Schema CRUD 页面和 React UI 组件库。
+- `model/` 配置驱动的菜单、项目和 CRUD 页面。
+- 前端构建 `buildFE()` 和消费方 Node/backend 构建 `buildBE()`。
+- 类型扩展机制，用于扩展 SchemaForm 字段、CallCom 组件和 Koa app 类型。
+
+优先使用公开入口，不要从包内部源码路径导入。
+
+| 入口 | 用途 |
+| --- | --- |
+| `@_tc/template-core` | `serverStart`、`baseFn`、Koa/Controller/Service 类型。 |
+| `@_tc/template-core/bundler` | `buildFE()`、`buildBE()`。 |
+| `@_tc/template-core/fe` | 前端初始化、请求方法、Dashboard/Schema 类型、共享状态、业务前端组件。 |
+| `@_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,
+}
+```
+
+访问内置后台：
+
+```text
+http://localhost:9000/dash?projk=demo
+```
+
+`projk` 对应 `model/{modelKey}/project/{projectKey}.ts`。
+
+## 3. 后端约定
+
+`serverStart({ baseDir })` 会按目录自动加载业务代码：
+
+```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)               -> 项目模型配置
+```
+
+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.request.query.page || 1),
+        pageSize: Number(ctx.request.query.pageSize || 10),
+        total: products.length,
+      })
+    }
+
+    detail = async (ctx: Ctx) => {
+      const item = products.find((product) => {
+        return product.product_id === ctx.request.query.product_id
+      })
+
+      this.success(ctx, item ?? null)
+    }
+  }
+}) 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)
+  router.get('/api/product', app.controller.product.detail)
+}
+```
+
+路由挂载顺序：
+
+- 每个 `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)
+}
+```
+
+内置响应约定：`BaseController.success(ctx, data)` 返回 `{ data, code: 0, message: 'ok' }`。
+
+内置扩展：
+
+- `app.extends.$fetch`：Node 侧 axios 风格 fetch 实例。
+- `app.extends.db`：默认 SQLite 数据存储，可用业务 `app/extend/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 {
+  get,
+  post,
+  request,
+  schemaEventBus,
+  schemaStore,
+  useSchemaStore,
+  LanguageSwitch,
+  ThemeSwitch,
+} from '@_tc/template-core/fe'
+```
+
+UI 组件从 `@_tc/template-core/fe/rc` 导入：
+
+```tsx
+import { Button, DataTable, Form, Input, Modal, Select } from '@_tc/template-core/fe/rc'
+```
+
+常用前端能力：
+
+- 请求方法：`request`、`get`、`post`、`put`、`patch`、`del`。
+- Schema 通信：`schemaEventBus`、`eventsInfo`、`merge`。
+- 共享状态：`modeStore`、`schemaStore`、`apiFreezerStore` 及对应 hooks。
+- 多语言：`i18nStore.addResources()`，配置文案可写 `$i18n::...`。
+- 主题：`ThemeSwitch` 会同步根节点 `dark` class 和 `localStorage`。
+
+不要直接依赖 `frontend/src/...`、`packages/react/ui/...` 这类包内部路径。
+
+## 6. 构建
+
+前端资源构建：
+
+```ts
+import { buildFE } from '@_tc/template-core/bundler'
+
+await buildFE('dev')
+await buildFE('prod', { output: 'run' })
+```
+
+`buildFE('dev')` 是构建一次并监听业务 `frontend/` 变化后重建，不是 Vite dev server/HMR。
+
+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. 在 `model` 菜单中使用 `moduleType: 'custom'`，让 `customConfig.path` 指向页面路径。
+4. 使用 `buildFE('dev')` 或 `buildFE('prod')` 生成资源。
+
+扩展前端类型或组件：
+
+1. SchemaForm 字段类型、CallCom 组件、Koa app 类型都支持 TypeScript 声明合并。
+2. 运行时组件通常放在业务 `frontend/extended/`。
+3. 优先查看公开入口 `.d.ts` 和 npm 包根目录 `README.md`；如果当前环境是源码仓库，再继续读 `docs/type-extension.md` 和 `docs/schema-form.md`。
+
+## 8. 继续深入
+
+需要更多信息时，按任务读取：
+
+| 任务 | 建议阅读 |
+| --- | --- |
+| 完整安装和使用说明 | npm 包根目录 `README.md` |
+| 生成项目、model、CRUD | `.skills/tc-generator/SKILL.md` |
+| 组件选型和用法 | `.skills/tc-component-usage-skills/SKILL.md` |
+| model/schema 配置细节 | `.skills/tc-generator/reference/model-schema.md` |
+| 完整 CRUD 示例 | `.skills/tc-generator/reference/example.md` |
+| 可复制项目骨架 | `.skills/tc-generator/reference/project-template/` |
+| UI 组件现场预览 | 启动服务后访问 `/ui-components` |
+| 已安装包的类型细节 | 查看对应公开入口的 `.d.ts` 文件 |
+
+如果当前环境是源码仓库而不是 npm 安装目录，还可以继续读 `docs/`、`frontend/README.md`、`model/README.md`、`bundler/README.md` 和 `BUILD.md`。