create-dp-koa 1.1.5 → 1.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-dp-koa",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "description": "Scaffold a DP-Koa framework project from the official template",
   "type": "module",
   "bin": {

package/template/docs/DOCUMENTATION_INDEX.md

@@ -41,6 +41,7 @@ DP-Koa Framework 完整文档体系索引，按功能模块和用户角色分类
 | [服务拦截器指南](SERVICE_INTERCEPTOR_GUIDE.md) | docs/ | 拦截器使用 | 2024-01-01 |
 | [服务层指南](SERVICE_PATTERN_GUIDE.md) | docs/ | 服务层设计模式 | 2024-01-01 |
 | [事务管理使用](TRANSACTION_MANAGER_USAGE.md) | docs/ | 事务处理 | 2024-01-01 |
+| [Session 注解使用指南](SESSION_DECORATOR_GUIDE.md) | docs/ | Session 注入与配置说明 | 2026-04-24 |
 | [Swagger 集成指南](SWAGGER_INTEGRATION_GUIDE.md) | docs/ | API 文档配置 | 2024-01-01 |
 | [测试指南](TESTING_GUIDE.md) | docs/ | 测试策略和工具 | 2024-01-01 |
 
@@ -139,6 +140,7 @@ DP-Koa Framework 完整文档体系索引，按功能模块和用户角色分类
 | 功能模块 | 相关文档 | 描述 |
 |----------|----------|------|
 | 注解系统 | [企业级注解系统指南](ENTERPRISE_ANNOTATION_SYSTEM_GUIDE.md) | 装饰器注解使用 |
+| Session 注解 | [Session 注解使用指南](SESSION_DECORATOR_GUIDE.md) | `@Session()` 与 `@Session('key')` |
 | 拦截器 | [服务拦截器指南](SERVICE_INTERCEPTOR_GUIDE.md) | 请求/响应拦截 |
 | 服务层 | [服务层指南](SERVICE_PATTERN_GUIDE.md) | 业务逻辑设计 |
 | 事务管理 | [事务管理使用](TRANSACTION_MANAGER_USAGE.md) | 数据库事务处理 |

package/template/docs/SESSION_DECORATOR_GUIDE.md

@@ -0,0 +1,85 @@
+# Session 注解使用指南
+
+本文档说明 `dp-koa-framework-core` 内建的 Session 能力，以及控制器参数注解 `@Session()` / `@Session('key')` 的使用方式。
+
+## 1. 设计目标
+
+- 保留现有 JWT + `ctx.state` 体系，不替代既有认证链路。
+- 在控制器层提供传统 Session 读写能力，用于 OAuth2/SSO 等临时会话场景。
+- Session 作为核心包内建功能，业务项目无需在 `app.ts` 手动 `app.use(session(...))`。
+
+## 2. 启用方式
+
+`dp-koa-framework-core` 在 `bootstrap` 期间自动注册 Session 中间件，无需额外启用。
+
+默认配置：
+
+- cookie key: `dpkoa.sid`
+- maxAge: `24h`
+- `httpOnly: true`
+- `signed: true`
+- `rolling: true`
+- `sameSite: 'lax'`
+
+## 3. 环境变量配置
+
+- `SESSION_KEYS`: 多个签名 key，逗号分隔（推荐）
+- `SESSION_SECRET`: 单个签名 key（兜底）
+- `SESSION_KEY`: cookie 名称，默认 `dpkoa.sid`
+- `SESSION_MAX_AGE_MS`: 会话过期时间（毫秒），默认 `86400000`
+
+说明：
+
+- 若 `SESSION_KEYS` 存在，则优先使用；
+- 否则使用 `SESSION_SECRET`；
+- 都未配置时使用框架默认值（建议生产环境务必覆盖）。
+
+## 4. 控制器注解用法
+
+### 4.1 注入整段 Session
+
+```ts
+@Get('/profile')
+async profile(@Session() session: any) {
+  return {
+    code: 0,
+    data: {
+      uid: session?.uid ?? null,
+    },
+  };
+}
+```
+
+### 4.2 按 key 注入
+
+```ts
+@Get('/profile')
+async profile(@Session('uid') uid: string) {
+  return { code: 0, data: { uid } };
+}
+```
+
+### 4.3 与 `@State` 并存
+
+```ts
+@Get('/secure')
+async secure(
+  @Session('uid') uid: string,
+  @State('user') user: any
+) {
+  return { code: 0, data: { uid, user } };
+}
+```
+
+## 5. 与 DTO 校验参数兼容说明
+
+- `@Session('uid')` 中字符串参数被识别为 key 选择器；
+- `@Session(SomeDto)` 中函数参数仍按既有语义作为 `validate` 处理；
+- `@State` 同步支持相同规则（`@State('user')` 可按 key 读取）。
+
+## 6. OAuth2/SSO 场景建议
+
+- Session 仅存短期握手数据（如 `state`、`pkceVerifier`、临时 uid）。
+- 登录完成后及时清理一次性字段，避免重放。
+- 生产环境务必配置稳定签名 key（`SESSION_KEYS`/`SESSION_SECRET`）。
+- 跨域回调场景需重点校验 cookie 策略（域名、`SameSite`、代理 HTTPS）。

package/template/package.json

@@ -65,8 +65,8 @@
     "dotenv": "^16.5.0",
     "dp-ioc2": "^1.0.1",
     "dp-mqueue": "^1.0.4",
-    "dp-koa-framework-core": "^0.1.2",
-    "dp-koa-framework-libs": "^0.1.2",
+    "dp-koa-framework-core": "^0.1.6",
+    "dp-koa-framework-libs": "^0.1.4",
     "jsonwebtoken": "^9.0.2",
     "koa": "^3.0.0",
     "koa-body": "^6.0.1",