@_tc/template-core 0.0.1-bate.57 → 0.0.1-bate.58

package/AGENT_README.md

@@ -102,6 +102,24 @@ 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/middleware/*.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
@@ -118,15 +136,15 @@ const getProductController = ((app) => {
     list = async (ctx: Ctx) => {
       this.success(ctx, {
         data: products,
-        page: Number(ctx.request.query.page || 1),
-        pageSize: Number(ctx.request.query.pageSize || 10),
+        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.request.query.product_id
+        return product.product_id === ctx.reqData?.data.product_id
       })
 
       this.success(ctx, item ?? null)
@@ -140,12 +158,12 @@ export default getProductController
 Router 示例：
 
 ```ts
-import type { KoaApp, Router } from '@_tc/template-core'
+import type { RouterFN } from '@_tc/template-core'
 
-export default (app: KoaApp, router: Router) => {
+export default ((app, router) => {
   router.get('/api/product/list', app.controller.product.list)
   router.get('/api/product', app.controller.product.detail)
-}
+}) satisfies RouterFN
 ```
 
 路由挂载顺序：
@@ -156,12 +174,12 @@ export default (app: KoaApp, router: Router) => {
 - 通配、兜底、重定向类路由建议设置较大的 `level`，避免抢先匹配业务 API。
 
 ```ts
-import type { KoaApp, Router } from '@_tc/template-core'
+import type { RouterFN } from '@_tc/template-core'
 
-export default (app: KoaApp, router: Router) => {
+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' }`。

package/README.md

@@ -165,6 +165,49 @@ http://localhost:9000/dash?projk=demo
 | `@_tc/template-core/fe/tailwind_ui.css` | 前端全局样式入口，源码对应 `frontend/src/main.css` |
 | `@_tc/template-core/model` | model 配置类型 |
 
+### 后端类型
+
+`@_tc/template-core` 会导出常用 Node 侧类型，业务项目写 `app/*` 文件时建议优先复用这些类型。
+
+| 类型 | 使用场景 |
+| --- | --- |
+| `Ctx` | Controller、middleware、router handler 的 Koa 请求上下文类型，包含框架补充的 `ctx.params` 和可选 `ctx.reqData`。 |
+| `ControllerFN` | `app/controller/*.ts` 默认导出工厂函数的约束类型，适合配合 `satisfies ControllerFN` 保留 controller 实例方法类型。 |
+| `ServiceFN` | `app/service/*.ts` 默认导出工厂函数的约束类型，适合配合 `satisfies ServiceFN` 约束 service class 工厂。 |
+| `MiddlewareFN` | `app/middleware/*.ts` 默认导出工厂函数的约束类型，返回标准 Koa middleware。 |
+| `RouterFN` | `app/router/*.ts` 默认导出函数的约束类型，用于接收 `app` 和 `router` 并注册路由。 |
+
+示例：
+
+```ts
+import { baseFn, type ControllerFN, type Ctx, type MiddlewareFN, type RouterFN, type ServiceFN } from '@_tc/template-core'
+
+export const getDemoController = ((app) => {
+  const BaseController = baseFn.baseControllerFn(app)
+
+  return class DemoController extends BaseController {
+    list = async (ctx: Ctx) => {
+      this.success(ctx, ctx.reqData?.data ?? {})
+    }
+  }
+}) satisfies ControllerFN
+
+export const getDemoService = ((app) => {
+  return class DemoService {
+    readonly app = app
+  }
+}) satisfies ServiceFN
+
+export const demoMiddleware = ((app) => async (ctx, next) => {
+  app.extends.logger?.info(ctx.path)
+  await next()
+}) satisfies MiddlewareFN
+
+export const demoRouter = ((app, router) => {
+  router.get(`${app.options.apiPrefix}/demo/list`, app.controller.demo.list)
+}) satisfies RouterFN
+```
+
 ## 样式与 Tailwind V4
 
 使用内置前端或 UI 组件时，需要引入包内样式。默认 `@_tc/template-core/fe` 的 `initApp` 会经过源码入口 `frontend/src/main.tsx` 引入 `frontend/src/main.css`；如果项目侧自定义入口、只使用 `fe/rc` 组件，或希望样式入口更明确，建议显式引入：
@@ -662,6 +705,24 @@ model/**/*.(js|ts)               -> 项目模型配置
 - `app.extends.crypto`：Node 侧加密辅助方法，支持 base64url 编解码、HMAC 签名、签名 payload 和常量时间比较。
 - `app.extends.db`：默认 SQLite 框架数据库，提供 `getDBData/setDBData` 等通用数据方法。
 
+API controller 可以通过 `ctx.reqData` 读取统一请求参数：
+
+```ts
+const { query, body, headers, data } = ctx.reqData ?? {
+  query: {},
+  body: undefined,
+  headers: {},
+  data: {},
+}
+```
+
+- `query` 来自 `ctx.query`。
+- `body` 来自 `ctx.request.body`。
+- `headers` 来自 `ctx.headers`。
+- `data` 是便捷合并层，当前按 `query -> body` 顺序合并；字段冲突时 body 覆盖 query。
+
+`ctx.reqData` 只在 API 请求中由内置中间件注入，类型上是可选字段。router params 不在 `reqData` 里，仍然从 `ctx.params` 获取。
+
 ### 数据库扩展
 
 默认 `app.extends.db` 使用 SQLite 保存数据，数据库文件位于项目根目录 `.template-core/template-core.sqlite`。可以在配置中调整路径：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@_tc/template-core",
-  "version": "0.0.1-bate.57",
+  "version": "0.0.1-bate.58",
   "description": "A full-stack TypeScript admin framework powered by Koa, React, and Vite - monorepo root",
   "types": "./types/index.d.ts",
   "exports": {
@@ -64,7 +64,12 @@
     "tailwindcss": "4.2.4"
   },
   "peerDependencies": {
-    "@types/node": ">=18.0.0",
+    "@types/json-schema": "7.0.15",
+    "@types/md5": "2.3.6",
+    "@types/node": "20.19.39",
+    "@types/nunjucks": "3.2.6",
+    "@types/koa-router": "7.4.9",
+    "@types/koa": "2.15.0",
     "@vitejs/plugin-react": "6.0.1",
     "clsx": "^2.1.0",
     "date-fns": "^3.6.0",