@_tc/template-core 0.0.1-bate.56 → 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/cjs/app/controller/project.js

@@ -1 +1 @@
-const e=require(`./base.js`);var t=(t=>{let n=e(t);return class extends n{getModelList=async e=>{let t=(await this.service.project.getModelList()).reduce((e,t)=>{let{model:n,project:r}=t,{key:i,name:a,desc:o}=n,s={key:i,name:a,desc:o},c=Object.keys(r).reduce((e,t)=>{let{key:n,name:i,desc:a,homePage:o}=r[t];return e[t]={key:n,name:i,desc:a,homePage:o},e},{});return e.push({model:s,project:c}),e},[]);this.success(e,t)};getProjectList=async e=>{let{projk:t}=e.query,n=(await this.service.project.getList(t))?.map(e=>{let{modelKey:t,key:n,name:r,desc:i,homePage:a}=e;return{modelKey:t,key:n,name:r,desc:i,homePage:a}});this.success(e,n)};getProject=async e=>{let{key:t}=e.params,n=this.service.project.getProject(t);if(!n){this.fail(e,10001,`获取项目异常`);return}this.success(e,n)}}});module.exports=t;
+const e=require(`./base.js`);var t=(t=>{let n=e(t);return class extends n{getModelList=async e=>{let t=(await this.service.project.getModelList()).reduce((e,t)=>{let{model:n,project:r}=t,{key:i,name:a,desc:o}=n,s={key:i,name:a,desc:o},c=Object.keys(r).reduce((e,t)=>{let{key:n,name:i,desc:a,homePage:o}=r[t];return e[t]={key:n,name:i,desc:a,homePage:o},e},{});return e.push({model:s,project:c}),e},[]);this.success(e,t)};getProjectList=async e=>{let t=e.reqData?.data.projk,n=(await this.service.project.getList(t))?.map(e=>{let{modelKey:t,key:n,name:r,desc:i,homePage:a}=e;return{modelKey:t,key:n,name:r,desc:i,homePage:a}});this.success(e,n)};getProject=async e=>{let{key:t}=e.params;if(!t){this.fail(e,10001,`获取项目异常`);return}let n=this.service.project.getProject(t);if(!n){this.fail(e,10001,`获取项目异常`);return}this.success(e,n)}}});module.exports=t;

package/cjs/app/middleware/error-handle.js

@@ -1 +1 @@
-var e={},t=t=>async(n,r)=>{try{await r()}catch(r){let{status:i=200,message:a,detail:o,code:s=5e4,returnError:c}=r;if(t.extends.logger?.info(`error info -> ${JSON.stringify(r)}`),t.extends.logger?.error(`-- [excption] --`,r),t.extends.logger?.error(`-- [excption] info --`,i,a,o),a?.includes(`template not found`)){let r=n.req.url;if(e[r]===void 0?e[r]=0:e[r]+=1,e[r]<t.config.notFoundRedirectCount){n.status=302,n.redirect(t.options?.homePage??`/`);return}else e[r]=0}c?(n.status=i,n.body={code:s,message:a}):(n.status=200,n.body={code:5e4,message:`网络错误`})}};module.exports=t;
+var e={},t=t=>async(n,r)=>{try{await r()}catch(r){let{status:i=200,message:a,detail:o,code:s=5e4,returnError:c}=r;if(t.extends.logger?.info(`error info -> ${JSON.stringify(r)}`),t.extends.logger?.error(`-- [excption] --`,r),t.extends.logger?.error(`-- [excption] info --`,i,a,o),a?.includes(`template not found`)){let r=n.path??n.req.url??n.url;if(e[r]===void 0?e[r]=0:e[r]+=1,e[r]<t.config.notFoundRedirectCount){n.status=302,n.redirect(t.options?.homePage??`/`);return}else e[r]=0}c?(n.status=i,n.body={code:s,message:a}):(n.status=200,n.body={code:5e4,message:`网络错误`})}};module.exports=t;

package/cjs/app/middleware/request-parameter-parsing.js

@@ -0,0 +1 @@
+var e=e=>typeof e==`object`&&!!e&&!Array.isArray(e),t=(t=>async(n,r)=>{if(n.path.includes(`${t.options.apiPrefix}/`)){let{query:t,headers:r}=n,i=n.request.body;n.reqData={query:t,body:i,headers:r,data:{...t,...e(i)?i:{}}}}await r()});module.exports=t;

package/cjs/app/middleware.js

@@ -1 +1 @@
-const e=require(`../_virtual/_rolldown/runtime.js`),t=require(`../packages/core/paths.js`);let n=require(`koa-compress`);n=e.__toESM(n);let r=require(`path`),i=require(`koa-bodyparser`);i=e.__toESM(i);let a=require(`koa-static`);a=e.__toESM(a);var o=(0,i.default)({formLimit:`1000mb`,enableTypes:[`form`,`json`,`text`]}),s=e=>{let i=e.envs.isLocal()?{maxage:0,setHeaders(e){e.setHeader(`Cache-Control`,`no-store, no-cache, must-revalidate, proxy-revalidate`),e.setHeader(`Pragma`,`no-cache`),e.setHeader(`Expires`,`0`)}}:{maxage:365*24*60*60*1e3};e.use(e.middlewares.errorHandle),e.use((0,n.default)({threshold:2048}));let s=(0,r.resolve)(t.getAppPath(e,`business`),`./public`),c=(0,r.resolve)(t.getAppPath(e,`frame`),`./public`),l=e.options.additionalPublicPaths??[];l=Array.isArray(l)?l:[l],e.use((0,a.default)(c,i)),e.use((0,a.default)(s,i)),l.forEach(t=>e.use((0,a.default)(t,i))),e.use(o),e.use(e.middlewares.projectHandler),!e.envs.isLocal()&&e.use(e.middlewares.apiSignVerify),e.use(e.middlewares.apiParamsVerify)};module.exports=s;
+const e=require(`../_virtual/_rolldown/runtime.js`),t=require(`../packages/core/paths.js`);let n=require(`koa-compress`);n=e.__toESM(n);let r=require(`path`),i=require(`koa-bodyparser`);i=e.__toESM(i);let a=require(`koa-static`);a=e.__toESM(a);var o=(0,i.default)({formLimit:`1000mb`,enableTypes:[`form`,`json`,`text`]}),s=e=>{let i=e.envs.isLocal()?{maxage:0,setHeaders(e){e.setHeader(`Cache-Control`,`no-store, no-cache, must-revalidate, proxy-revalidate`),e.setHeader(`Pragma`,`no-cache`),e.setHeader(`Expires`,`0`)}}:{maxage:365*24*60*60*1e3};e.use(e.middlewares.errorHandle),e.use((0,n.default)({threshold:2048}));let s=(0,r.resolve)(t.getAppPath(e,`business`),`./public`),c=(0,r.resolve)(t.getAppPath(e,`frame`),`./public`),l=e.options.additionalPublicPaths??[];l=Array.isArray(l)?l:[l],e.use((0,a.default)(c,i)),e.use((0,a.default)(s,i)),l.forEach(t=>e.use((0,a.default)(t,i))),e.use(o),e.use(e.middlewares.requestParameterParsing),e.use(e.middlewares.projectHandler),!e.envs.isLocal()&&e.use(e.middlewares.apiSignVerify),e.use(e.middlewares.apiParamsVerify)};module.exports=s;

package/esm/app/controller/project.js

@@ -26,7 +26,7 @@ var t = ((t) => {
 			this.success(e, t);
 		};
 		getProjectList = async (e) => {
-			let { projk: t } = e.query, n = (await this.service.project.getList(t))?.map((e) => {
+			let t = e.reqData?.data.projk, n = (await this.service.project.getList(t))?.map((e) => {
 				let { modelKey: t, key: n, name: r, desc: i, homePage: a } = e;
 				return {
 					modelKey: t,
@@ -39,7 +39,12 @@ var t = ((t) => {
 			this.success(e, n);
 		};
 		getProject = async (e) => {
-			let { key: t } = e.params, n = this.service.project.getProject(t);
+			let { key: t } = e.params;
+			if (!t) {
+				this.fail(e, 10001, "获取项目异常");
+				return;
+			}
+			let n = this.service.project.getProject(t);
 			if (!n) {
 				this.fail(e, 10001, "获取项目异常");
 				return;

package/esm/app/middleware/error-handle.js

@@ -5,7 +5,7 @@ var e = {}, t = (t) => async (n, r) => {
 	} catch (r) {
 		let { status: i = 200, message: a, detail: o, code: s = 5e4, returnError: c } = r;
 		if (t.extends.logger?.info(`error info -> ${JSON.stringify(r)}`), t.extends.logger?.error("-- [excption] --", r), t.extends.logger?.error("-- [excption] info --", i, a, o), a?.includes("template not found")) {
-			let r = n.req.url;
+			let r = n.path ?? n.req.url ?? n.url;
 			if (e[r] === void 0 ? e[r] = 0 : e[r] += 1, e[r] < t.config.notFoundRedirectCount) {
 				n.status = 302, n.redirect(t.options?.homePage ?? "/");
 				return;

package/esm/app/middleware/request-parameter-parsing.js

@@ -0,0 +1,18 @@
+//#region app/middleware/request-parameter-parsing.ts
+var e = (e) => typeof e == "object" && !!e && !Array.isArray(e), t = ((t) => async (n, r) => {
+	if (n.path.includes(`${t.options.apiPrefix}/`)) {
+		let { query: t, headers: r } = n, i = n.request.body;
+		n.reqData = {
+			query: t,
+			body: i,
+			headers: r,
+			data: {
+				...t,
+				...e(i) ? i : {}
+			}
+		};
+	}
+	await r();
+});
+//#endregion
+export { t as default };

package/esm/app/middleware.js

@@ -20,7 +20,7 @@ var a = r({
 	} : { maxage: 365 * 24 * 60 * 60 * 1e3 };
 	r.use(r.middlewares.errorHandle), r.use(t({ threshold: 2048 }));
 	let s = n(e(r, "business"), "./public"), c = n(e(r, "frame"), "./public"), l = r.options.additionalPublicPaths ?? [];
-	l = Array.isArray(l) ? l : [l], r.use(i(c, o)), r.use(i(s, o)), l.forEach((e) => r.use(i(e, o))), r.use(a), r.use(r.middlewares.projectHandler), !r.envs.isLocal() && r.use(r.middlewares.apiSignVerify), r.use(r.middlewares.apiParamsVerify);
+	l = Array.isArray(l) ? l : [l], r.use(i(c, o)), r.use(i(s, o)), l.forEach((e) => r.use(i(e, o))), r.use(a), r.use(r.middlewares.requestParameterParsing), r.use(r.middlewares.projectHandler), !r.envs.isLocal() && r.use(r.middlewares.apiSignVerify), r.use(r.middlewares.apiParamsVerify);
 };
 //#endregion
 export { o as default };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@_tc/template-core",
-  "version": "0.0.1-bate.56",
+  "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",

package/types/app/middleware/request-parameter-parsing.d.ts

@@ -0,0 +1,7 @@
+/**
+ * - 统一处理请求参数获取
+ * - 除了params  因为params 必须经过router才会有
+ * - 而当前中间件是在 router之前追加，router params 仍然从 ctx.params 获取
+ */
+declare const requestParameterParsing: (app: import("../../packages/core/index").KoaApp) => (ctx: import("app/type").Ctx, next: import("koa").Next) => Promise<void>;
+export default requestParameterParsing;

package/types/app/type.d.ts

@@ -1,6 +1,34 @@
+import type Koa from "koa";
+import type Router from "koa-router";
+import type { IncomingHttpHeaders } from "http";
+import type { ParsedUrlQuery } from "querystring";
 export type KoaApp = import('./typings').KoaApp;
 export type KoaRouter = import('./typings').KoaRouter;
-export type Ctx = KoaApp['context'];
+export type CtxParams = Router.IRouterParamContext['params'];
+export interface CtxReqData {
+    /**
+     * URL query 参数。
+     */
+    query: ParsedUrlQuery;
+    /**
+     * bodyparser 解析后的请求 body。
+     */
+    body: unknown;
+    /**
+     * 原始请求 headers。
+     */
+    headers: IncomingHttpHeaders;
+    /**
+     * 便捷合并层：当前中间件会按 query -> body 的顺序合并。
+     * 字段有冲突时，后面的来源会覆盖前面的来源；需要精确来源时请使用 query/body/headers。
+     */
+    data: Record<string, unknown>;
+}
+export type Ctx = Router.RouterContext<Koa.DefaultState, Koa.DefaultContext> & {
+    params: CtxParams;
+    reqData?: CtxReqData;
+};
+export type MiddlewareFN = (app: KoaApp) => (ctx: Ctx, next: Koa.Next) => Promise<void>;
+export type RouterFN = (app: KoaApp, router: KoaRouter) => void;
 export type ControllerFN<T extends object = object> = (app: KoaApp) => new () => T;
 export type ServiceFN<T extends object = object> = (app: KoaApp) => new () => T;
-export type RouterFN = (app: KoaApp, router: KoaRouter) => void;

package/types/app/typings.d.ts

@@ -35,6 +35,7 @@ declare module '../packages/core/index' {
             errorHandle: import('koa').Middleware;
             apiSignVerify: import('koa').Middleware;
             apiParamsVerify: import('koa').Middleware;
+            requestParameterParsing: import('koa').Middleware;
             projectHandler: import('koa').Middleware;
         }
         interface AppConfigAugmented extends Partial<DefaultAppConfig> {

package/types/index.d.ts

@@ -5,7 +5,7 @@ import { MOmit } from "./typings/type";
 export type { FrameworkAugment, KoaApp } from "./packages/core/index";
 export type { CryptoExtend, CryptoHashAlgorithm, HmacSignOptions, SignedPayloadOptions, VerifySignedPayloadOptions, } from "./app/extend/crypto";
 export type { DB, DBDataOptions, DBDataRecord, DBFactory, DBRunResult, FrameworkDB, ListDBDataOptions, SQLiteParams, SQLiteValue, } from "./app/extend/db";
-export type { ControllerFN, Ctx, RouterFN, ServiceFN } from "./app/type";
+export type { ControllerFN, Ctx, MiddlewareFN, RouterFN, ServiceFN } from "./app/type";
 export type { Router };
 export declare const serverStart: (options?: MOmit<StartOptions, "frameBaseDir">) => Promise<import("./packages/core/index").KoaApp>;
 export declare const baseFn: {