chanjs 2.7.8 → 2.7.11

package/doc/02-/345/223/215/345/272/224/344/270/216/351/224/231/350/257/257.md

@@ -0,0 +1,255 @@
+# 02 · 响应与错误：success / fail / AppError / CODE
+
+统一的响应格式和错误体系，是接口"好对接"的关键。Chanjs 提供两层：
+
+1. **响应信封**：`success()` / `fail()`（Controller 里直接 `this.success` / `this.fail`）。
+2. **错误对象**：`AppError` 及其子类（如 `ValidationError`、`ForbiddenError`），配合全局错误处理器，把异常自动转成标准 JSON。
+
+---
+
+## 一、响应信封（所有 JSON 接口统一）
+
+无论成功失败，前端拿到的结构都是：
+
+```json
+{ "success": true,  "code": 0,    "msg": "操作成功", "data": {} }
+{ "success": false, "code": 1008, "msg": "验证码错误", "data": null }
+```
+
+| 字段 | 含义 |
+|---|---|
+| `success` | 布尔，是否成功 |
+| `code` | 业务码（见下文 CODE 表）|
+| `msg` | 给前端的提示文案 |
+| `data` | 业务数据，失败时为 `null` |
+
+### 1.1 `success(opts)` / `this.success(opts)`
+
+纯函数（可直接 `import { success }` 或 Controller 内 `this.success`）。
+
+```js
+success();                          // {success:true, code:0, msg:"操作成功", data:{}}
+success({ data: [1,2,3] });         // 带数据
+success({ data: row, msg: "查询成功" });
+```
+
+| 参数 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `opts.data` | any | `{}` | 返回数据 |
+| `opts.msg` | string | `"操作成功"` | 提示 |
+
+### 1.2 `fail(opts)` / `this.fail(opts)`
+
+```js
+fail("用户名已存在");                 // 字符串当 msg，code 默认 1008
+fail({ code: 1006, msg: "参数缺失" });
+fail({ code: 1008, data: {...} });  // 也可附带 data
+```
+
+| 参数 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `opts`(string) | string | — | 当 `msg`，`code=1008` |
+| `opts.msg` | string | — | 提示 |
+| `opts.code` | number | `1008` | 业务码 |
+| `opts.data` | any | `{}` | 附带数据 |
+
+> 也可以脱离 Controller 直接用裸函数：`import { success, fail } from "chanjs"`。
+> 但**在 Controller 里优先用 `this.success/this.fail`**，因为它们已经在正确的 `this` 上下文里。
+
+### 1.3 其它响应辅助函数
+
+| 函数 | 签名 | 说明 |
+|---|---|---|
+| `routeNotFound` | `routeNotFound(req)` | 生成 404 路由不存在响应体：`{success:false,code:1004,msg:"请求的资源不存在",data:{path,method}}` |
+| `serializeError` | `serializeError(err, exposeDetail=false)` | 把错误序列化成统一响应对象。AppError 提取 `code/msg`+自定义字段；原生错误生产环境脱敏（仅 `exposeDetail=true` 时附带堆栈）|
+| `buildErrorHtml` | `buildErrorHtml(status, errorMsg, code, req)` | 生成内置兜底错误 HTML 页（无模板依赖）。4 个参数：`status`(HTTP 码)、`errorMsg`(文案)、`code`(业务码或 `HTTP_xxx`)、`req` |
+| `respondError` | `respondError(res, req, { httpStatus=500, code=500, msg, data=null })` | 按请求类型分流：API（XHR / Accept=json）返回 JSON，浏览器页（Accept=html）渲染 HTML 错误页 |
+
+```js
+import { routeNotFound, serializeError, buildErrorHtml, respondError } from "chanjs";
+
+const body = routeNotFound(req);                 // 404 体
+const obj = serializeError(err, false);          // 错误→响应对象
+respondError(res, req, { httpStatus: 403, code: 1003, msg: "无权限" });
+```
+
+> ⚠️ 旧文档把 `buildErrorHtml(err)` / `respondError(res, err)` 写成单参数是**错误**的，实际签名见上表。
+
+---
+
+## 二、错误码 CODE 字典
+
+`CODE`（数字→文案映射）与语义常量 `CODE_XXX` 都从 `chanjs` 导出，避免硬编码数字。
+
+```js
+import { CODE, CODE_OK, CODE_AUTH_FAILED, getCodeMsg } from "chanjs";
+
+CODE[0];              // "操作成功"（按业务码取提示文案）
+CODE_OK;              // 0
+CODE_AUTH_FAILED;     // 1001
+getCodeMsg(1001);     // "认证失败"
+```
+
+### 2.1 完整 CODE 表（`response/code.js` 权威）
+
+| 业务码 | 常量 | 文案 | HTTP 状态（对应错误类）|
+|---|---|---|---|
+| `0` | `CODE_OK` | 操作成功 | 200 |
+| `1001` | `CODE_AUTH_FAILED` | 认证失败 | 401 |
+| `1002` | `CODE_TOKEN_EXPIRED` | 令牌已过期 | 401 |
+| `1003` | `CODE_FORBIDDEN` | 权限不足 | 403 |
+| `1004` | `CODE_NOT_FOUND` | 资源不存在 | 404 |
+| `1005` | `CODE_CONFLICT` | 资源已存在 | 409 |
+| `1006` | `CODE_PARAM_INVALID` | 参数无效 | 422 |
+| `1007` | `CODE_PARAM_MISSING` | 参数缺失 | 400 |
+| `1008` | `CODE_BUSINESS_FAIL` | 业务处理失败 | 400 |
+| `1009` | `CODE_RATE_LIMIT` | 请求过于频繁 | 429 |
+| `1010` | `CODE_DEVICE_ERROR` | 登录设备异常 | 403 |
+| `1011` | `CODE_BLOCKED` | 访问已被限制 | 403 |
+| `5001` | `CODE_SYSTEM_ERROR` | 系统内部错误 | 500 |
+| `5002` | `CODE_SERVICE_BUSY` | 服务繁忙，请稍后再试 | 503 |
+| `6001` | `CODE_DB_CONNECTION_ERROR` | 数据库连接失败 | 503 |
+| `6002` | `CODE_DB_ACCESS_DENIED` | 数据库访问被拒绝 | 503 |
+| `6003` | — | 存在关联数据，操作失败 | 409 |
+| `6004` | — | 数据库字段错误 | 400 |
+| `6005` | — | 数据重复，违反唯一性约束 | 409 |
+| `6006` | — | 目标表不存在 | 500 |
+| `6007` | `CODE_DB_OPERATION_TIMEOUT` | 数据库操作超时 | 503 |
+| `6008` | — | 数据库语法错误，请检查查询语句 | 500 |
+| `6009` | — | 数据库连接已关闭，请重试 | 500 |
+
+> 注：`CODE` 数字是完整权威来源；语义常量只覆盖了常用码（1001–1011、5001、5002、6001、6002、6007）。
+> 未提供常量的码可直接用数字（如 `6005`）。
+
+`getCodeMsg(code, fallback="操作失败")`：按码取默认文案，查不到返回 `fallback`。
+
+---
+
+## 三、AppError 错误族（推荐用"抛错"代替 `this.fail`）
+
+比起在 Controller 里 `return this.fail(...)`，更优雅的是**直接 throw 一个错误对象**，
+框架的全局错误处理器会自动把它转成标准 JSON。这样业务逻辑（Service/Repository）里也能直接抛。
+
+### 3.1 基类 `AppError`
+
+```js
+import { AppError } from "chanjs";
+
+// 构造：code(业务码), msg(文案), httpStatus(HTTP状态), cause(底层错误)
+throw new AppError(1008, "用户名已存在", 400);
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `code` | number | ✅ | 业务码 |
+| `msg` | string | ✅ | 提示 |
+| `httpStatus` | number | ❌ | HTTP 状态，默认 400 |
+| `cause` | Error | ❌ | 底层原始错误（会被记录进日志）|
+
+> 🛑 **顺序不能写反**：`new AppError("用户名已存在", 1008)` 是**错的**（会把 msg 当 code）。
+> 正确是 `new AppError(1008, "用户名已存在")`。
+
+### 3.2 预定义子类（最常用）
+
+这些子类已把 `code` 和 `httpStatus` 绑定好，你只管传文案：
+
+```js
+import {
+  AuthError, TokenExpiredError, ForbiddenError, NotFoundError,
+  ConflictError, ValidationError, ParamMissingError, BusinessError,
+  RateLimitError, BlockedError, SystemError, ServiceBusyError,
+  DbConnectionError, DbAccessDeniedError, DbTimeoutError,
+} from "chanjs";
+
+throw new ValidationError("标题不能为空");          // code=1006, http=422
+throw new ForbiddenError("无权限");                  // code=1003, http=403
+throw new NotFoundError("文章不存在");               // code=1004, http=404
+throw new BusinessError("库存不足");                 // code=1008, http=400
+throw new AuthError("请先登录");                     // code=1001, http=401
+throw new RateLimitError("请求过于频繁");            // code=1009, http=429
+```
+
+**带额外字段**：`ValidationError` 支持第二个参数传字段列表（用于前端高亮）；`RateLimitError` / `BlockedError` 可传 `retryAfter`：
+```js
+throw new ValidationError("参数校验失败", ["title", "content"]);
+throw new RateLimitError("请求过于频繁", 30);   // retryAfter = 30s
+```
+
+**带底层错误**：把数据库异常包进去，便于排查：
+```js
+try { await repo.insert(data); }
+catch (e) { throw new SystemError("写入失败", e); }
+```
+
+**两种构造写法**（所有子类通用）：
+```js
+new ValidationError("标题不能为空");                       // 字符串当 msg
+new ValidationError({ msg: "标题不能为空", fields: [...] }); // 对象写法，可带 extraProps / cause
+```
+
+### 3.3 辅助函数
+
+```js
+import { isAppError, describeError, errorExtraProps, parseStack, wrapDbError } from "chanjs";
+
+isAppError(err);        // 判断是不是业务错误（AppError 实例）
+describeError(err);     // 递归生成可读错误链路（含 ECONNREFUSED/ENOTFOUND 等智能提示 + cause 链）
+errorExtraProps(err);   // 提取错误附加属性字符串，用于日志
+parseStack(err.stack);  // 解析出 { message, file, line }，定位报错文件
+wrapDbError(err);       // 把数据库底层异常转成对应 AppError 子类
+```
+
+**`wrapDbError` 很实用**：在 Repository 里 catch 数据库错误后调用，会自动映射成友好错误：
+```js
+import { wrapDbError } from "chanjs";
+try { /* knex 操作 */ }
+catch (e) { throw wrapDbError(e); }
+// ER_DUP_ENTRY / 23505      → ConflictError("数据已存在")
+// ER_ACCESS_DENIED_ERROR    → DbAccessDeniedError("数据库访问被拒绝")
+// ER_NO_SUCH_TABLE          → SystemError("数据表不存在")
+// ER_BAD_FIELD_ERROR        → ParamMissingError("数据库字段错误")
+// ER_ROW_IS_REFERENCED_2    → ConflictError("存在关联数据，操作失败")
+// ECONNREFUSED/ENOTFOUND/…  → DbConnectionError("数据库连接失败")
+// 其它                       → SystemError("数据操作异常")
+```
+
+> `describeError` 内置递归深度限制（10 层）防栈溢出，并会展开 `AggregateError`。
+
+---
+
+## 四、完整示例：用抛错写业务
+
+```js
+import { Controller } from "chanjs";
+import { ValidationError, NotFoundError } from "chanjs";
+import { ArticleService } from "../service/ArticleService.js";
+
+export class ArticleController extends Controller {
+  constructor() { super(); this.service = new ArticleService(); }
+
+  async detail(req, res) {
+    const { id } = req.query;
+    if (!id) throw new ValidationError("缺少 id");
+
+    const row = await this.service.getById(id);
+    if (!row) throw new NotFoundError("文章不存在");  // 抛错即可，框架接管响应
+
+    this.success({ data: row });
+  }
+}
+```
+
+不用写 `try/catch` 返回失败——抛出 `AppError` 子类后，全局错误处理器会输出：
+```json
+{ "success": false, "code": 1004, "msg": "文章不存在", "data": null }
+```
+
+---
+
+## 五、常见坑
+
+1. **`AppError` 参数顺序写反**：`new AppError("消息", 1008)` → 实际 `code` 变成字符串，前端判断全错。永远是 `(code, msg, httpStatus)`。
+2. **在 Service 里 `return this.fail`**：Service 没有 `this.fail`，请用 `throw new XxxError(...)`。
+3. **裸 `throw new Error("xx")`**：会被当成系统错误（500），建议业务错误都用 `AppError` 子类。
+4. **`code` 硬编码**：优先用 `CODE.XXX` 常量，避免数字漂移。
+5. **`buildErrorHtml` / `respondError` 参数个数**：实际分别是 4 参和 3 参（见 1.3），旧文档单参写法是错的。

package/doc/03-/345/256/211/345/205/250/346/250/241/345/235/227.md

@@ -0,0 +1,264 @@
+# 03 · 安全模块：JWT / XSS 过滤 / 关键词校验 / 限流 / 加解密
+
+做登录、表单提交、评论、上传时必看。所有函数都从 `"chanjs"` 导出。
+
+---
+
+## 一、JWT 登录态（setToken / getToken / verifyToken / revokeToken）
+
+文件：`security/jwt.js`。基于 `jsonwebtoken`，用 HS256 签名。黑名单存在 `store`（见 04 文档）。
+
+### 1.1 `setToken(data, secretKey, expire="7d")` —— 签发令牌
+
+```js
+import { setToken } from "chanjs";
+
+const token = setToken(
+  { userId: 1, role: "admin" },   // 载荷（不要放密码等敏感信息）
+  process.env.JWT_SECRET,         // 签名密钥（必须配，否则返回 null）
+  "7d"                            // 有效期：'7d' / '2h' / 3600(秒)
+);
+// token 是字符串；secret 缺失返回 null
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `data` | object | ✅ | 载荷（用户标识等）|
+| `secretKey` | string | ✅ | 签名密钥，通常取 `process.env.JWT_SECRET` |
+| `expire` | string | ❌ | 有效期（数字按秒，字符串如 `'7d'`/`'2h'`），默认 `"7d"` |
+
+> 登录成功后用 `res.cookie("token", token, {...})` 下发给浏览器（见 ChanCMS 的 `Member.login` / `SysUser.login`）。
+> 会员端用的是 `ut` cookie（httpOnly），后台用 `token` cookie。
+
+### 1.2 `verifyToken(token, secretKey)` —— 校验（异步）
+
+```js
+import { verifyToken } from "chanjs";
+
+const { valid, reason, payload } = await verifyToken(token, process.env.JWT_SECRET);
+if (!valid) {
+  // reason: "missing" | "expired" | "invalid" | "revoked"
+  throw new AuthError("登录失效");
+}
+console.log(payload.userId);
+```
+
+返回对象：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `valid` | boolean | 是否合法 |
+| `reason` | string | 失败原因：`"missing"`（无 token）/ `"expired"`（过期）/ `"invalid"`（签名无效/伪造）/ `"revoked"`（已注销）|
+| `payload` | object | 合法时的载荷 |
+| `error` | Error | 失败时的原始错误（仅验签阶段）|
+
+> 🔒 流程：先验签（无效/过期直接拒）→ 再查黑名单（已注销则拒）。
+
+### 1.3 `getToken(token, secretKey)` —— 取载荷（校验成功才返回）
+
+```js
+const payload = await getToken(token, process.env.JWT_SECRET);
+// 合法 → payload；非法 → null
+```
+
+### 1.4 `revokeToken(token, ttl)` —— 注销（加入黑名单）
+
+```js
+import { revokeToken } from "chanjs";
+
+// 改密码/登出时调用：把旧 token 写入黑名单，ttl = 旧 token 剩余毫秒数
+const decoded = await getToken(oldToken, secret);
+const ttl = decoded.exp * 1000 - Date.now();   // 剩余有效期(ms)
+await revokeToken(oldToken, ttl);
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `token` | string | ✅ | 要注销的令牌 |
+| `ttl` | number | ✅ | 黑名单存活毫秒数（一般传 token 剩余有效期）；`<=0` 视为无需注销，直接返回 `true` |
+
+> ⚠️ `revokeToken` 当前已在 `chanjs/index.js` 中显式导出（`import { revokeToken } from "chanjs"` 可直接用）。
+> 新增 import 前仍建议核对 `index.js` 导出列表，避免漏导出导致整模块加载失败。
+
+### 1.5 黑名单存储
+
+`revokeToken` / `verifyToken` 的黑名单存在 `store`（见 04 文档）。Redis 开启时跨进程生效；
+未开启时降级为内存（单机有效）。可用环境变量 `JWT_REVOCATION_FAIL_CLOSE=true` 切换为
+"存储异常即拦截"（fail-close，适合金融/权限敏感场景）。
+
+---
+
+## 二、XSS 过滤 `filterXSS(data)`
+
+文件：`security/xss-filter.js`。基于 `xss` 库，对用户输入做净化，**递归支持对象/数组/字符串**。
+
+```js
+import { filterXSS } from "chanjs";
+
+const clean = filterXSS(userHtml);          // 字符串：去掉 <script>、onerror= 等危险内容
+const cleanObj = filterXSS({ title, body }); // 对象/数组：逐字段递归净化
+```
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `data` | string \| object \| Array | 待净化数据；字符串直接净化，对象/数组递归处理（循环引用安全）|
+| **返回** | 同输入类型 | 净化后的数据；`number/boolean/null/undefined` 原值返回 |
+
+**使用场景**：评论、留言、富文本字段入库前净化；或渲染前净化。
+ChanCMS 在 `BookChapter` 保存章节内容时复用它（**复用优先，不要自己重写**）。
+
+---
+
+## 三、关键词 / 安全校验 `checkKeywords(text, options?)`
+
+文件：`security/checker.js`。检查文本是否命中敏感词 / 攻击特征（SQL 注入、命令注入、XSS、路径穿越等）。
+
+```js
+import { checkKeywords } from "chanjs";
+
+const hit = checkKeywords(commentText);
+if (hit) {
+  // hit = { category: "xss", keyword: "<script" }
+  throw new BusinessError(`内容包含违规词：${hit.keyword}`);
+}
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `text` | string | ✅ | 待检测文本（空白直接返回 `null`）|
+| `options.scope` | `"body"` | ❌ | 传 `"body"` 时跳过「路径/文件/英文词」等易误杀的分类（wholeWord/extensions/directories/sensitiveIdentifiers/encoding），只对语义敏感词做匹配；不传则全量扫描 |
+
+**返回**：命中时 `{ category: string, keyword: string }`；未命中或空白时 `null`。
+
+> ⚠️ **返回结构不是 `{ blocked, reason, keyword }`**（旧文档有误）。命中对象含 `category`（分类，如 `sqlInjection`/`xss`/`commandInjection`）和 `keyword`（命中的具体词）。
+> 判断"是否命中"用 `if (hit)` 即可。
+
+**`scope:"body"` 为什么重要（真实踩坑）：**
+评论、留言这类"正文"里常含正常链接（如 `https://example.com/a.html`），若按全量规则扫描会误判为攻击。
+传 `scope: "body"` 可只匹配语义敏感词，放行正常链接。
+
+```js
+// 正文内容检测（推荐）
+checkKeywords(content, { scope: "body" });
+
+// URL / 路径检测（默认全量）
+checkKeywords(someUrl);
+```
+
+### 3.1 路径忽略校验 `isIgnored(path, ignorePaths)`
+
+配套工具：判断请求路径是否命中忽略列表（大小写不敏感、去尾斜杠，支持精确/前缀匹配）。
+> 注意：`isIgnored` 未挂到包根导出，需用深导入：`import { isIgnored } from "chanjs/security/checker.js"`。
+
+```js
+import { isIgnored } from "chanjs/security/checker.js";
+
+isIgnored("/api/health", ["/api/health", "/public"]); // true
+```
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `path` | string | 当前请求路径 |
+| `ignorePaths` | string[] | 忽略路径列表 |
+| **返回** | boolean | 命中返回 `true` |
+
+---
+
+## 四、接口限流 `createRateLimitMiddleware(opts)`
+
+文件：`security/rate-limit.js`。防止爆破 / 刷接口。**按 IP + UID 双维度限流**（自动从 `req` 取客户端 IP 与 `req.user?.uid`）。
+
+```js
+import { createRateLimitMiddleware } from "chanjs";
+
+const emailLimiter = createRateLimitMiddleware({
+  windowMs: 5 * 60 * 1000,   // 时间窗口：5 分钟（支持数字毫秒 或 "1s"/"1m"/"1h"/"1d" 字符串）
+  max: 10,                    // 窗口内最多 10 次（默认 60）
+  ignorePaths: ["/api/health"], // 这些路径跳过限流（默认 []）
+});
+
+router.post("/sendEmail", emailLimiter, ctrl.sendEmail.bind(ctrl));
+```
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|---|---|---|---|---|
+| `windowMs` | number \| string | ❌ | `60000` | 时间窗口：数字按毫秒；字符串形如 `"1m"`（s/m/h/d 单位）|
+| `max` | number | ❌ | `60` | 窗口内最大请求数（IP 维度和 UID 维度各自独立计数）|
+| `ignorePaths` | string[] | ❌ | `[]` | 命中即跳过限流的路径前缀列表 |
+
+> ⚠️ **旧文档的 `keyPrefix` / `limitKey` 选项不存在**——当前实现固定为「IP + 登录用户 UID」双维度，无法自定义维度函数。
+> 超限时中间件直接返回 **`code=1009`（`CODE_RATE_LIMIT`，HTTP 429）**，无需你手写。
+> 存储异常时 fail-close 直接拦截（同样返回 429）。
+
+---
+
+## 五、对称加解密 `aesEncrypt / aesDecrypt`（⚠️ 异步）
+
+文件：`security/sign.js`。基于 AES-256-GCM（内置 scrypt 密钥派生 + LRU 缓存），用于加密敏感字段（如配置里的密钥）。
+
+```js
+import { aesEncrypt, aesDecrypt } from "chanjs";
+
+// ⚠️ 这两个函数是异步的，必须 await！
+const cipher = await aesEncrypt(plainText, secretKey);   // 输出 iv+tag+密文 合并 base64
+const plain  = await aesDecrypt(cipher, secretKey);
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `data` | string \| object | ✅ | 明文（对象会被 JSON 字符串化）/ 密文 |
+| `secretKey` | string | ✅ | 派生密钥的口令；建议统一配置环境变量 `AES_SALT` 固定盐值（未配置会有一次告警并用 secret 派生）|
+
+> 🛑 **大坑**：`aesEncrypt` / `aesDecrypt` 是 **`async` 函数**，调用必须 `await`。
+> 漏写 `await` 会得到 `Promise` 而非字符串，后续比较/存储会全部错位。
+
+---
+
+## 六、安全模块速查表
+
+| 函数 | 同步/异步 | 典型用途 | 注意 |
+|---|---|---|---|
+| `setToken` | 同步 | 登录签发 | secret 缺失返回 null |
+| `getToken` | 异步 | 取载荷 | 非法返回 null |
+| `verifyToken` | 异步 | 校验 | 先验签再查黑名单；reason 含 `revoked` |
+| `revokeToken` | 异步 | 登出/改密注销 | 需传剩余 ttl(ms) |
+| `filterXSS` | 同步 | 富文本净化 | 支持对象/数组递归；复用，别重写 |
+| `checkKeywords` | 同步 | 敏感词 | 命中返回 `{category,keyword}`，未命中 `null`；正文用 `scope:"body"` |
+| `isIgnored` | 同步 | 路径跳过判断 | 配合限流/扫描忽略列表 |
+| `createRateLimitMiddleware` | 同步(返中间件) | 限流 | 选项 `{windowMs,max,ignorePaths}`；超限 `code=1009` |
+| `aesEncrypt` / `aesDecrypt` | **异步** | 字段加密 | 必须 `await` |
+
+---
+
+## 七、综合示例：登录 + 限流 + 注销
+
+```js
+import { Controller } from "chanjs";
+import { setToken, getToken, revokeToken } from "chanjs";
+import { createRateLimitMiddleware } from "chanjs";
+import { AuthError } from "chanjs";
+
+const loginLimiter = createRateLimitMiddleware({ windowMs: 10*60*1000, max: 5 });
+
+export class UserController extends Controller {
+  async login(req, res) {
+    const { username, password } = req.body;
+    const user = await this.service.verify(username, password);  // 业务校验
+    if (!user) throw new AuthError("账号或密码错误");
+
+    const token = setToken({ userId: user.id }, process.env.JWT_SECRET, "7d");
+    res.cookie("token", token, { httpOnly: true, sameSite: "strict" });
+    this.success({ data: { token, user } });
+  }
+
+  async logout(req, res) {
+    const token = req.cookies.token;
+    const payload = await getToken(token, process.env.JWT_SECRET);
+    if (payload) {
+      const ttl = payload.exp * 1000 - Date.now();
+      await revokeToken(token, ttl);   // 加入黑名单
+    }
+    this.success({ msg: "已退出" });
+  }
+}
+```

package/doc/04-/345/255/230/345/202/250/344/270/216/347/274/223/345/255/230.md

@@ -0,0 +1,157 @@
+# 04 · 存储与缓存：store / cache
+
+文件：`storage/index.js`，对外导出两个单例：`store`（Redis/内存适配层）和 `cache`（纯内存缓存）。
+它们的 API 形状与 Redis 客户端保持一致，让业务侧无需关心底层是 Redis 还是内存。
+
+> ⚠️ **`store` 与 `cache` 的 ttl 单位都是「毫秒（ms）」**，两者一致（旧文档称 cache 用秒是**错误**的）。
+> 例：`store.set(k, v, 5*60*1000)` 与 `cache.set(k, v, 5*60*1000)` 都是 5 分钟。
+
+---
+
+## 一、`store` —— 通用键值存储（令牌黑名单 / 限流计数 / 临时状态）
+
+`store` 背后优先用 **Redis**（配置了 `REDIS_ENABLED` 时），否则降级为**进程内 Map**。
+因此它适合：登录态黑名单、限流计数、验证码、分布式锁等"需要跨请求/跨进程共享"的数据。
+所有方法失败时返回安全默认值（`null`/`false`/`0`），**不会抛异常上抛**。
+
+### 1.1 方法签名
+
+```js
+import { store } from "chanjs";
+
+await store.init({ REDIS_ENABLED, REDIS });   // 框架启动时已自动 init，业务一般不用手动调
+await store.set(key, value, ttl);             // 写入
+const v = await store.get(key);               // 读取（不存在/异常返回 null）
+await store.del(key);                         // 删除（不存在返回 false）
+const ok = await store.exists(key);           // 是否存在（bool）
+const n = await store.incr(key);              // 原子自增（新 key 返回 1，异常返回 0）
+const n2 = await store.incrAndExpire(key, ttl); // 原子自增并设 TTL（限流专用）
+await store.expire(key, ttl);                 // 为已存在 key 设过期（key 不存在返回 false）
+const info = store.getInfo();                 // 诊断信息（健康检查用）
+await store.close();                          // 关闭并释放资源（优雅停机自动调）
+```
+
+| 方法 | 签名 | 返回 | 说明 |
+|---|---|---|---|
+| `init` | `init({REDIS_ENABLED, REDIS})` | Promise | 框架启动自动调用；业务无需手动 |
+| `set` | `set(key, value, ttl=60000)` | Promise\<boolean\> | `ttl` 单位**毫秒**；`ttl<=0` 视 Redis 为永久 |
+| `get` | `get(key)` | Promise\<any\> | 未命中/异常返回 `null`（JSON 自动反序列化）|
+| `del` | `del(key)` | Promise\<boolean\> | 删除；不存在/异常返回 `false` |
+| `exists` | `exists(key)` | Promise\<boolean\> | 是否存在 |
+| `incr` | `incr(key)` | Promise\<number\> | 原子自增；首次返回 1，异常返回 0 |
+| `incrAndExpire` | `incrAndExpire(key, ttlMs)` | Promise\<number\> | 原子自增并设过期（限流场景专用），返回计数 |
+| `expire` | `expire(key, ttlMs)` | Promise\<boolean\> | 给已存在 key 设过期；不存在返回 `false` |
+| `getInfo` | `getInfo()` | `{mode, memorySize, redisConnected, circuitOpen}` | 诊断：当前后端模式/内存条目数/Redis 状态/是否熔断 |
+| `close` | `close()` | Promise | 关闭 Redis、清空内存；优雅停机自动调 |
+
+> ⚠️ **没有 `ttl(key)` 方法**（旧文档列出的是错误的）。想看剩余有效期可用 `getInfo()` 做健康诊断，
+> 或直接用 `expire()` 续期。
+
+### 1.2 实战：邮箱验证码
+
+```js
+import { store } from "chanjs";
+
+// 发送验证码
+await store.set(`email:code:${email}`, code, 5 * 60 * 1000);  // 5 分钟有效（ms）
+
+// 校验验证码
+const saved = await store.get(`email:code:${email}`);
+if (!saved || saved !== inputCode) throw new BusinessError("验证码错误");
+await store.del(`email:code:${email}`);
+```
+
+### 1.3 实战：JWT 黑名单（框架内部已用）
+
+`security/jwt.js` 的 `revokeToken` 就是 `store.set("jwt:revoked:"+token, 1, ttl)`。
+你无需直接使用，理解其机制即可。
+
+### 1.4 降级与容错
+
+- Redis 未开启 → 自动用内存 Map（**单机有效，多实例不共享**）。
+- Redis 连接失败 → 框架 `warn` 并降级内存，不阻断启动。
+- **熔断保护**：Redis 运行时连续失败 5 次触发熔断，30s 冷却期内全部走内存；冷却后自动尝试恢复。
+- 黑名单查询异常时：默认 fail-open（放行），可用 `JWT_REVOCATION_FAIL_CLOSE=true` 切 fail-close。
+
+---
+
+## 二、`cache` —— 进程内内存缓存（热点数据 / 配置 / 模板变量）
+
+`cache` 是**纯进程内 LRU + 惰性 TTL 缓存**（默认容量 10w，惰性清理间隔 10s、单批最多 1000 条）。
+适合放"读多写少、允许短暂不一致"的数据，如站点配置、导航树、模板变量。它**更快、零网络开销**，
+但**重启即丢、不跨进程**。方法都是**同步**的。
+
+### 2.1 方法签名
+
+```js
+import { cache } from "chanjs";
+
+cache.set(key, value, ttl);   // ttl 单位毫秒；不传默认 5 分钟；ttl<=0 视为永久
+const v = cache.get(key);     // 命中返回原值；未命中/过期返回 null
+cache.has(key);               // 是否存在（命中同样刷新 LRU）
+cache.del(key);               // 删除，返回是否删除成功
+cache.clear();                // 清空全部（慎用）
+cache.size();                 // 当前条目数
+const n = cache.incr(key, ttlMs);          // 原子自增（新 key 用默认 60s TTL）
+const n2 = cache.incrAndExpire(key, ttlMs); // 自增并刷新过期（限流专用）
+cache.expire(key, ttlMs);    // 为已存在 key 刷新过期；不存在返回 false
+```
+
+| 方法 | 签名 | 返回 | 说明 |
+|---|---|---|---|
+| `set` | `set(key, value, ttl=300000)` | void | `ttl` 单位**毫秒**（默认 5 分钟）；`ttl<=0` 永久 |
+| `get` | `get(key)` | any | 未命中/过期返回 `null` |
+| `has` | `has(key)` | boolean | 是否存在（刷新 LRU）|
+| `del` | `del(key)` | boolean | 删除成功返回 `true` |
+| `clear` | `clear()` | void | 清空（一般只在测试或全量刷新时用）|
+| `size` | `size()` | number | 当前缓存条目数 |
+| `incr` | `incr(key, ttlMs=60000)` | number | 原子自增；新建 key 起始值 1 |
+| `incrAndExpire` | `incrAndExpire(key, ttlMs)` | number | 自增并刷新过期（限流/计数）|
+| `expire` | `expire(key, ttlMs)` | boolean | 给已存在 key 刷新过期；不存在返回 `false` |
+
+> ⚠️ `cache` 是**同步**的，不要画蛇添足 `await`；`store` 是**异步**的，必须 `await`。
+> `set` 的 `ttl` 同样是**毫秒**——和 `store` 单位一致（旧文档的"秒"是错误）。
+
+### 2.2 实战：缓存站点配置 30 分钟
+
+```js
+import { cache } from "chanjs";
+
+async function getSiteConfig() {
+  const hit = cache.get("site:config");
+  if (hit) return hit;
+
+  const cfg = await siteRepo.find({ type: "site" });
+  cache.set("site:config", cfg, 30 * 60 * 1000);  // 缓存 30 分钟（ms）
+  return cfg;
+}
+```
+
+> ChanCMS 的 `web/middleware/init.js` 正是用 `cache` 把 `site/nav/category` 等全局变量缓存，
+> 避免每次请求都查库。
+
+---
+
+## 三、store vs cache 怎么选
+
+| 维度 | `store` | `cache` |
+|---|---|---|
+| 后端 | Redis（可降级内存）| 纯内存 LRU |
+| 同步性 | 异步（返回 Promise，必须 `await`）| 同步（直接返回值）|
+| 跨进程/多实例 | ✅（Redis 时）| ❌ 仅本进程 |
+| ttl 单位 | 毫秒 | 毫秒（一致）|
+| 典型用途 | 验证码、令牌黑名单、限流、分布式锁 | 配置、导航树、模板变量、热点列表 |
+| 一致性要求 | 强（如注销要立即生效）| 弱（允许分钟级过期）|
+
+**经验法则**：涉及"安全/状态正确性"用 `store`；涉及"性能/少查库"用 `cache`。
+
+---
+
+## 四、常见坑
+
+1. **ttl 单位**：`store.set` 与 `cache.set` 的 ttl **都是毫秒**。写错会让缓存瞬间失效或永不过期。
+2. **`store` 是异步**：方法返回 Promise 必须 `await`；`cache` 是同步的，别画蛇添足 `await`。
+3. **`store.get` 返回 `null` 当"未命中"**：判断存在要用 `exists()`，不要 `if(get)` 区分（值为 `0`/`false` 也会误判）。
+4. **`store` 没有 `ttl(key)`**：旧文档列出的该方法不存在，请用 `getInfo()` / `expire()`。
+5. **内存 `cache` 重启即丢**：不要往 `cache` 放必须持久的数据（如未提交的订单）。
+6. **Redis 未开时 `store` 仅单机**：多实例部署务必开启 `REDIS_ENABLED`，否则限流/黑名单不共享。