## ssr

https://stackblitz.com/edit/bluwy-create-vite-extra-fuc1kcnj?file=index.html,server.js,src%2FApp.vue,src%2Fcomponents%2FHelloWorld.vue,src%2Fassets%2Fvue.svg

bun run server.ts

bunx tsc .\server.ts --module NodeNext --target esnext --moduleResolution nodenext




## koa3-demo

当前支持功能：

 - [ ] 路由
 - [x] 日志
 - [ ] 权限
 - [x] 数据库
 - [ ] 缓存
 - [ ] 界面
 - [ ] 定时任务 
 - [ ] htmx
 - [x] 环境变量验证

## 快速开始

### 1. 环境配置

复制环境变量模板文件：
```bash
cp .env.example .env
```

编辑 `.env` 文件，设置必需的环境变量：
- `SESSION_SECRET`: 会话密钥（至少32个字符）
- `JWT_SECRET`: JWT密钥（至少32个字符）

### 2. 安装依赖
```bash
bun install
```

### 3. 初始化数据库
```bash
bun run dev:init
```

### 4. 启动开发服务器
```bash
bun run dev
```

## 环境变量说明

项目启动时会自动验证环境变量配置，确保应用安全性：

### 必需环境变量
- `SESSION_SECRET`: 会话密钥，支持多密钥轮换（逗号分隔）
- `JWT_SECRET`: JWT令牌密钥（最少32字符）

### 可选环境变量
- `NODE_ENV`: 运行环境 (development/production/test)
- `PORT`: 服务器端口 (默认: 3000)
- `LOG_DIR`: 日志目录 (默认: logs)
- `HTTPS_ENABLE`: 是否启用HTTPS (默认: off)

详细配置请参考 `.env.example` 文件。

### 数据库查询缓存（QueryBuilder 扩展）

为 Knex QueryBuilder 增加了内存级缓存能力，支持 TTL、自定义 key、只读/只写、按前缀失效与全局工具访问。默认 key 为查询的 `toString()`，也可通过 `cacheAs()` 指定。

可用方法：

- `cache(ttlMs?)`: 读取缓存，不存在则执行 SQL 并写入缓存；可选 TTL（毫秒）。
- `cacheAs(customKey)`: 为当前查询设置自定义缓存 key（链式，返回 builder）。
- `cacheSet(value, ttlMs?)`: 手动写入当前查询 key 的缓存，返回写入的值。
- `cacheGet()`: 仅从缓存读取当前查询 key 的值（不命中则返回 `undefined`，不会执行 SQL）。
- `cacheInvalidate()`: 使当前查询 key 的缓存失效（删除）。
- `cacheInvalidateByPrefix(prefix)`: 按前缀批量失效。

全局工具（命名导出 `DbQueryCache`，便于在查询构建器之外操作缓存）：

- `get/set/has/delete/clear/clearByPrefix/stats()`

示例：

```js
import db, { DbQueryCache } from "./src/db/index.js"

// 1) 简单缓存 5 秒
const u1 = await db("users").where({ id: 1 }).first().cache(5000)

// 2) 自定义 key + 只读命中
const key = "users:count:active"
const count = await db("users").where({ active: 1 }).count({ c: "*" }).cacheAs(key).cache(10000)
const cachedOnly = db("users").where({ active: 1 }).cacheAs(key).cacheGet() // 命中则返回值，不命中为 undefined

// 3) 手动写入/覆盖缓存 15 秒
db("users").where({ active: 1 }).cacheAs(key).cacheSet([{ c: 123 }], 15000)

// 4) 单点或前缀失效
db("users").where({ active: 1 }).cacheAs(key).cacheInvalidate()
db.queryBuilder().cacheInvalidateByPrefix("users:")

// 5) 全局操作
DbQueryCache.clearByPrefix("users:")
const stats = DbQueryCache.stats() // { size, valid, expired }
```

注意：

- 该实现为进程内内存缓存，适合单实例与读多写少场景；多实例下需用外部缓存（如 Redis）替换/扩展。
- TTL 为可选，未设置则永久有效，直到被失效或进程重启。
- 自定义 key 建议使用明确的命名空间前缀（如 `users:`、`site:`），以便使用前缀批量失效。

## 📚 项目文档

- [环境变量配置指南](./docs/environment-setup.md) - 详细的环境配置说明
- [项目规范检查报告](./docs/project-standards-review.md) - 完整的规范评估和改进记录
- [改进任务跟踪](./docs/improvement-tasks.md) - 项目改进任务的执行状态

## 🔧 开发和部署

### 测试环境变量配置
```bash
bun run test:env
```

### 生产环境部署
```bash
# 使用Docker
docker-compose up -d

# 或直接构建
docker build -t koa3-demo .
docker run -p 3000:3000 koa3-demo
```