lakutata 3.0.0 → 3.1.0

package/doc/zh/ProjectStructure.md

@@ -0,0 +1,102 @@
+# Lakutata 项目结构
+
+本页介绍 `lakutata create` 创建的项目：`default` 模板的文件、其他模板的工作区、它们的脚本和可选功能，以及如何制作自己的模板。
+
+## 1. 默认模板
+
+```
+my-app/
+  package.json
+  tsconfig.json
+  README.md
+  .gitignore
+  src/
+    App.ts                           启动应用
+    config/Config.ts                 应用的选项：组件、入口、适配器
+    controllers/ExampleController.ts 动作
+    dtos/GreetDTO.ts                 动作的输入
+    tests/App.spec.ts                测试（node --test）
+  build/                             编译后的应用（npm run build）
+```
+
+`src/App.ts` 用 `src/config/Config.ts` 中的选项启动应用，并记录启动日志：
+
+```typescript
+import {Application, type ILogger} from 'lakutata'
+import {config} from './config/Config.js'
+
+Application
+    .run(config)
+    .onLaunched((app: Application, log: ILogger): void => log.info('%s started in %s mode', app.appName, app.mode()))
+    .onFatalException((error: Error, log: ILogger): void => log.error('The application cannot start: %s', error.message))
+```
+
+`config()` 返回应用的选项：应用的 ID 和名称、运行模式（`NODE_ENV=production` 时为 `production`），以及 `entrypoint` 组件，它在环境变量 `PORT` 指定的端口（默认 8080）上通过 HTTP 提供 `ExampleController`。它写成函数，是为了让测试可以在自己的端口上启动应用：`src/tests/App.spec.ts` 运行 `Application.run(config(18080))`，请求 `/example?name=you`，最后销毁应用。
+
+| 脚本 | 作用 |
+|---|---|
+| `dev` | 先 `build`，再启动应用 |
+| `build` | 删除 `build/`（`lakutata clean`），再把 `src/` 编译到其中（`tsc`） |
+| `start` | 启动编译好的应用（`node build/App.js`） |
+| `test` | 先 `build`，再运行测试（`node --test "build/tests/**/*.spec.js"`） |
+| `migration:generate`、`migration:create`、`migration:run`、`migration:revert`、`migration:show` | 数据库迁移（`lakutata migration`，见 [Migrations](Migrations.md)） |
+
+这个模板在 `tsconfig.json` 中写了自己的编译选项（取 `lakutata/tsconfig.json` 中它需要的那些，并使用 `module: "NodeNext"` 和 source map）；项目也可以像 `cli` 以外的工作区模板那样继承 `lakutata/tsconfig.json`。
+
+## 2. 工作区模板
+
+其他模板都是 npm 工作区：应用是 `packages/app` 这个包，带界面或安装包的模板还会加上 `packages/ui`（网页，或 Electron 的渲染进程）和 `packages/resources`（图标）。`service` 模板：
+
+```
+shop/
+  package.json                       工作区：workspaces ["packages/*"]，以及脚本
+  Dockerfile                         服务的镜像
+  packages/
+    app/
+      package.json
+      tsconfig.json                  extends lakutata/tsconfig.json
+      src/
+        App.ts
+        config/Config.ts             express 适配器、中间件、compression
+        controllers/ExampleController.ts
+        controllers/HealthController.ts    GET /health
+        dtos/GreetDTO.ts
+        middlewares/Authenticate.ts  设置了 API_TOKEN 时校验 Bearer 令牌
+        tests/App.spec.ts
+```
+
+| 脚本（根目录） | 作用 |
+|---|---|
+| `npm run build` | 按依赖顺序构建每个包（`lakutata run rebuild`） |
+| `npm test` | 先构建每个包，再运行它们的测试（`npm run build && lakutata run test`） |
+| `npm run dev` | 同时启动每个包的 `dev` 脚本（`lakutata run dev --parallel`）：应用，以及界面的开发服务器（如果有界面） |
+| `npm start` | 启动编译好的应用（`npm start -w app`） |
+| `npm run version:patch` | 给每个包设置下一个补丁版本（`lakutata version patch --yes`） |
+
+其他模板在这个结构上增加了：
+
+- `web-react` 和 `web-vue`：`packages/ui`，一个 Vite 应用。开发时，它的开发服务器（`http://localhost:5173`）把 `/api` 转发给应用；构建之后，由应用自己提供这些页面（动作都在 `/api` 之下）。应用的 `lakutata.resources` 会在打包时带上构建好的页面。
+- `web-next` 和 `web-nuxt`：`packages/ui`，一个 Next.js 或 Nuxt 应用，由应用在同一个进程中渲染。
+- `cli`：一个命令行工具（`commanderCLIEntrypoint`），带有 `package:bundle` 和 `package:exe` 脚本，把它打包到 `dist/`（[Packaging](Packaging.md)）。
+- `electron-react` 和 `electron-vue`：`packages/app` 中是 Electron 的主进程（它的窗口，以及通过 IPC 提供的服务动作），`packages/ui` 中是渲染进程，还有制作安装包的脚本。
+
+打包产物写到工作区根目录的 `dist/` 中；`.gitignore` 忽略 `build`、`dist` 以及界面的构建输出。
+
+## 3. 可选功能
+
+`lakutata create --with <features>`（或在终端里列出的选项）给模板加上可选功能：
+
+| 功能 | 模板 | 加入的内容 |
+|---|---|---|
+| `i18n` | 全部 | `src/locales` 中各语言的消息（`en`、`zh-CN`）、`i18n` 组件、语言中间件，以及 `i18n:check` 和 `i18n:types` 脚本（[I18n](I18n.md)） |
+| `installer` | `cli`、`service`、`web-*` | 应用的 `lakutata.installer`、制作安装包的脚本（在本机制作，以及在 Docker 中制作 Linux 的安装包），服务类模板还会注册系统服务（[Installers](Installers.md)） |
+
+Electron 模板不需要这个功能也能制作安装包。
+
+## 4. 自己的模板
+
+`--template` 也可以指定不在官方列表中的模板：`npm:<package>[@<version>]`、`github:<owner>/<repo>[#<ref>]`，或者一个目录。没有 `template/` 子目录的目录会原样复制；模板包（和官方模板一样）包含：
+
+- `template/`：项目的文件。npm 不会发布某些点文件，所以它们以 `_` 开头命名，创建时再改名（`_gitignore` 变成 `.gitignore`）。文本文件中的 `{$APP_NAME}`、`{$APP_ID}`、`{$APP_DESC}`、`{$APP_AUTHOR}`、`{$APP_LICENSE}` 和 `{$LAKUTATA_VERSION}` 会被替换。
+- `features/<name>/`：每个功能的文件，在模板 `package.json` 的 `lakutata.features` 中声明并附上说明。这些文件会加入项目：项目中已有的 JSON 文件与之合并（数组整体替换），其他文件替换模板中的同名文件。
+- 只对某个功能保留的代码块：位于 `//@if i18n` 和 `//@end` 之间的行（可以有 `//@else`，`@if !i18n` 表示相反的条件），写成该文件的注释形式（`#@if`、`<!--@if-->`、`/*@if*/`）。

package/doc/zh/Queue.md

@@ -0,0 +1,214 @@
+# Lakutata 消息队列
+
+**Queue 组件**（`lakutata/com/queue`，`@lakutata/queue` 包）把消息加入队列，用 `@QueueAction` 声明的控制器动作通过 `queueEntrypoint` 适配器处理这些消息，和其他传输方式一样使用输入 DTO、访问控制和中间件。动作正常返回时消息被确认；失败后重新投递，次数用完后进入死信队列；动作的返回值就是这条消息的结果。队列可以放在内存、Redis、NATS JetStream、RabbitMQ 或 Kafka 中，换驱动不需要改动作的代码。更多细节见 `@lakutata/queue` 的 README。
+
+## 1. 配置
+
+用 `buildQueueOptions` 在应用的 `components` 中声明 `Queue`（按惯例命名为 `queue`），把队列的适配器交给 entrypoint，并让 entrypoint 在启动时创建（`bootstrap: ['entrypoint']`；否则它要到第一次被使用时才创建，动作不会开始消费）。不指定 `driver` 时，消息保存在进程的内存中。
+
+```typescript
+import {Application} from 'lakutata'
+import {buildEntrypoints} from 'lakutata/com/entrypoint'
+import {buildQueueOptions, queueEntrypoint} from 'lakutata/com/queue'
+
+Application.run(() => ({
+    id: 'image.app',
+    name: 'Images',
+    components: {
+        queue: buildQueueOptions({
+            driver: {type: 'redis', url: 'redis://127.0.0.1:6379'},
+            //消费者的默认设置
+            defaults: {attempts: 5, backoff: {type: 'exponential', delay: '1s', max: '1m'}, concurrency: 4},
+            //为 result() 和 request() 保存的结果
+            results: {keep: '1d'}
+        }),
+        entrypoint: buildEntrypoints({
+            controllers: [],
+            //把消息投递给 @QueueAction 动作
+            queue: queueEntrypoint('queue')
+        })
+    },
+    //在启动时创建：动作从此开始消费
+    bootstrap: ['entrypoint']
+}))
+```
+
+| 驱动 | 需要安装 | 服务端 | 说明 |
+|---|---|---|---|
+| `{type: 'memory'}`（默认） | | | 只在当前进程内有效：进程退出后消息丢失；用于开发、测试、桌面应用 |
+| `{type: 'redis', url}` | `bullmq`、`ioredis` | Redis 5.0 起（建议 6.2 起） | 基于 BullMQ：支持优先级、延迟、去重；请使用 `maxmemory-policy noeviction` |
+| `{type: 'nats', servers}` | `nats` | NATS 2.9.4 起，需开启 JetStream（`-js`） | stream 保留消息 `maxAge`（7 天）；2 分钟内去重；不支持优先级 |
+| `{type: 'rabbitmq', url}` | `amqplib` | RabbitMQ 3.6 起 | 优先级 0–10，支持延迟；需要 `results.store` |
+| `{type: 'kafka', brokers}` | `@platformatic/kafka`（Node.js 22.22 / 24.6 起） | Kafka 3.5 起 | 按键保序，`partitions`（默认 1）；需要 `results.store` |
+| `{type: 'custom', driver}` | | | 应用自己实现的 `QueueDriver` |
+
+客户端都是可选的 peer 依赖，在组件启动时才加载：缺少客户端包时启动失败并抛出 `QueueDriverNotFoundException`，服务端版本太旧时抛出 `QueueDriverVersionException`，连不上服务端时抛出连接错误。启动之后，驱动会自动重连。使用服务端的驱动还接受 `prefix`（默认 `lakutata`），作为它们在服务端创建的名称的前缀，用来隔开共用同一个服务端的应用。
+
+组件的其他选项：
+
+- `defaults`：消费者的默认设置：`attempts`（3）、`backoff`（指数退避，从 1 秒到 1 分钟）、`concurrency`（1）、`timeout`（不限）、`group`（应用的 `appId`）。
+- `results`：`keep` 是结果保留多久（默认 1 天），`store` 是代替驱动保存结果的 `Cacher` 组件的名称。RabbitMQ 和 Kafka 自身不保存结果，需要指定一个各应用共用的存储（例如 Redis）。`false` 表示不保存结果。
+- `codec`：`'messagepack'`（默认，和 `@lakutata/nats` 相同）、`'json'`（方便其他语言的服务对接）或自定义的 `QueueCodec`。
+- `requestTimeout`：`request()` 和 `result()` 的等待时间（30 秒）。
+
+```typescript
+import {Application} from 'lakutata'
+import {buildCacherOptions} from 'lakutata/com/cacher'
+import {buildQueueOptions} from 'lakutata/com/queue'
+
+Application.run(() => ({
+    id: 'billing.app',
+    name: 'Billing',
+    components: {
+        //各应用共用的结果（对 RabbitMQ 来说还有各队列的组）
+        cache: buildCacherOptions({stores: [{type: 'redis', host: '127.0.0.1'}]}),
+        queue: buildQueueOptions({
+            driver: {type: 'rabbitmq', url: 'amqp://guest:guest@127.0.0.1:5672', prefix: 'billing'},
+            results: {keep: '2h', store: 'cache'}
+        })
+    }
+}))
+```
+
+## 2. 消费者：`@QueueAction`
+
+```text
+@QueueAction(queue, dto?, options?)
+```
+
+被装饰的方法处理一个队列的消息：输入就是消息，经过 DTO 校验；`this.context` 是 `QueueContext`。方法的返回值就是这条消息的结果。同一个方法还可以同时带有其他传输方式的装饰器（HTTP 路由、服务动作等）。选项包括所有动作通用的选项（`name`、`acl`、`rule`、`middlewares` 等），以及：
+
+- `group`：消费这个队列的组（默认是队列的 `defaults.group`，否则是应用的 `appId`）；
+- `concurrency`：一个实例同时处理的消息数；
+- `attempts`、`backoff`：消息进入死信队列之前的投递次数，以及两次投递之间的等待；
+- `timeout`：处理的时间上限（到时中止，然后重试）；
+- `ordered`：同一个 `key` 的消息按顺序逐条处理（内存和 Kafka 驱动）；
+- `output`：把返回值作为一条新消息发到这个队列（返回值须为对象；返回 `undefined` 时不发送）。
+
+```typescript
+import {DTO} from 'lakutata'
+import {Controller} from 'lakutata/com/entrypoint'
+import {Expect} from 'lakutata/decorator/dto'
+import {QueueAction, type QueueContext, type QueueDeadLetter} from 'lakutata/com/queue'
+
+class ExtractInput extends DTO {
+    @Expect(DTO.Number().integer().required())
+    public id: number
+}
+
+class ImageController extends Controller {
+    //同时处理 4 条，最多 5 次尝试，每次最长 10 分钟，结果发往 image.index
+    @QueueAction('image.extract', ExtractInput, {concurrency: 4, attempts: 5, timeout: '10m', output: 'image.index'})
+    public async extract(input: ExtractInput): Promise<{id: number, pages: number}> {
+        const context: QueueContext = this.context as QueueContext
+        console.log(`消息 ${context.jobId} 的第 ${context.attempt} 次尝试，共 ${context.attempts} 次`)
+        //到达处理时限时被中止：this.signal
+        this.signal?.throwIfAborted()
+        return {id: input.id, pages: 12}
+    }
+
+    @QueueAction('image.index')
+    public async index(input: {id: number, pages: number}): Promise<void> {
+        console.log(`图片 ${input.id}：${input.pages} 页`)
+    }
+
+    //尝试次数用完的消息
+    @QueueAction('image.extract.dead')
+    public async failed(input: QueueDeadLetter): Promise<void> {
+        console.error(input.jobId, input.attempts, input.error.message)
+    }
+}
+```
+
+上下文中包含 `queue`、`jobId`、`group`、`attempt`（首次投递为 1）、允许的 `attempts`、应用的 `headers` 和 `publishedAt`；它的 `type` 是 `'QUEUE'`，供多种传输方式共用的中间件和访问规则区分。
+
+`queueEntrypoint(componentName, {name, middlewares, onError})` 在应用启动时检查各动作的选项并登记它们的组，应用启动完成后开始消费。每次处理失败（无论是否重试）都会调用 `onError(error, action, context)`；默认把失败写入应用的日志。
+
+不使用控制器时，可以用 `queue.consume(name, processor, options)` 以函数 `(input, context, signal) => result` 处理队列，它返回一个可以 `stop()` 的订阅：
+
+```typescript
+import type {Queue, QueueJobContext} from 'lakutata/com/queue'
+
+declare const queue: Queue
+const subscription = await queue.consume('mail.send', async (input: Record<string, any>, context: QueueJobContext, signal: AbortSignal): Promise<void> => {
+    signal.throwIfAborted()
+    console.log(`发邮件给 ${input.to}（${context.jobId}）`)
+}, {group: 'mailer', concurrency: 2})
+await subscription.stop()
+```
+
+## 3. 生产者：`add`、`request`、`result`
+
+```typescript
+import {Component} from 'lakutata'
+import {Inject} from 'lakutata/decorator/di'
+import {type Job, type Queue, QueueJobFailedException} from 'lakutata/com/queue'
+
+class Images extends Component {
+    @Inject('queue')
+    protected readonly queue: Queue
+
+    public async work(): Promise<void> {
+        //发出即不管：10 秒后投递；同一编号的消息还在等待时丢弃（dedupe）
+        await this.queue.add('image.extract', {id: 7}, {jobId: 'image-7', dedupe: true, delay: '10s'})
+
+        //发出并等待结果：动作的返回值，或最后一次的错误
+        try {
+            const result: {pages: number} = await this.queue.request('image.extract', {id: 8}, {timeout: '30s'})
+            console.log(result.pages)
+        } catch (error) {
+            if (error instanceof QueueJobFailedException) console.error(error.error.message, error.attempts)
+        }
+
+        //现在发出，之后凭编号读取结果（任何实例都可以读），只要结果还保留着
+        const job: Job = await this.queue.add('image.extract', {id: 9}, {priority: 5, headers: {origin: 'upload'}})
+        console.log(await job.result({timeout: '1m'}))
+        console.log(await this.queue.result('image.extract', job.id, {wait: false}))
+    }
+}
+```
+
+消息的选项：`jobId`（默认随机 UUID）、`dedupe`、`delay`、`priority`（越大越先）、`key`（保序的键）、`attempts` 和 `backoff`（代替消费者的设置）、`headers`（前缀 `x-lkt-` 保留给框架）。驱动不支持的选项会抛出 `QueueCapabilityException`；`queue.capabilities` 给出驱动支持的能力。
+
+`request()` 以动作的返回值完成；消息失败时以 `QueueJobFailedException` 拒绝；超时（`QueueRequestTimeoutException`）时消息仍留在队列中，之后还能读取它的结果。`result()` 和 `job.result()` 会等到消息处理完（`wait: false` 只读取当前已保存的结果）；没有在时间内处理完时抛出 `QueueResultNotFoundException`，结果已不再保留时抛出 `QueueResultExpiredException`。有多个组消费同一个队列时，`request()` 和 `result()` 要用 `group` 指明要哪个组的结果（否则抛出 `QueueAmbiguousGroupException`）。
+
+## 4. 投递
+
+- **至少一次。** 动作正常返回时消息被确认。抛出错误时，等待 `backoff` 后重新投递，最多 `attempts` 次，之后作为 `QueueDeadLetter`（`{queue, jobId, group, input, error, attempts, failedAt}`）进入 `<队列名>.dead`，它和普通队列一样。一条消息可能被处理两次（进程崩溃、停机），动作应当是幂等的。
+- **重试解决不了的不重试。** 输入不合法（`InvalidValueException`）、没有访问权限、动作不存在、返回值校验失败（`@Return`）、消息或结果无法编码：消息直接进入死信队列。动作抛出 `QueueDiscardException` 时丢弃这条消息：确认它，不进死信，也不保存结果。
+- **处理时限。** 处理超过 `timeout` 时以 `QueueProcessingTimeoutException` 失败并重试：它的 signal 被中止，之后的返回值被丢弃。投递有租约的驱动（NATS）会在处理期间自动续租。
+- **停机。** 应用停止时，消费者停止取新消息，正在处理的消息有 entrypoint 的 `shutdownTimeout` 时间完成；届时仍未完成的消息以后重新投递，既不确认也不进死信。
+- **组。** 同一个组的多个实例分摊消息；不同的组各收一份。动作的组默认是所在应用的 `appId`：两个应用消费同一个队列时会各收一份，除非它们指定相同的 `group`。组在登记之后才开始接收消息（应用启动时登记其动作的组，`consume()` 和 `queue.prepare(name, {group})` 也会登记）：使用服务端的驱动时，队列在任何组登记之前收到的消息不会被投递；内存驱动则把这些消息留给第一个登记的组，每个队列最多保留 `backlog` 条（默认为 `{type: 'memory', backlog: 1000}`），超出时丢弃最早的消息。所以没有人消费的死信队列（`<queue>.dead`）只在内存中保留最近的 1000 条消息。组登记后一直保存在服务端，所以即使组的所有实例都没有运行，发给它的消息也会保留。
+- **消息内容。** 消息是一个对象，也就是动作的输入。使用默认编解码时，`Date` 会变成 ISO 字符串（输入 DTO 可以把它转回 `Date`；返回值仍是字符串），`bigint` 会被拒绝。
+
+## 5. 各驱动的比较
+
+| | 内存 | Redis | NATS JetStream | RabbitMQ | Kafka |
+|---|---|---|---|---|---|
+| 延迟 | ✓ | ✓ | ✓ | ✓（延迟队列） | — |
+| 优先级 | ✓ | ✓ | — | ✓（0–10） | — |
+| 去重 | 消息保留期间 | 消息保留期间 | 2 分钟内 | — | — |
+| 按 `key` 保序 | ✓ | — | — | — | ✓（分区） |
+| 结果 | ✓ | ✓ | ✓ | `results.store` | `results.store` |
+| `request()` | 回复通道 | 回复通道 | 回复通道 | 回复通道 | 读取结果 |
+| 重试 | 延迟重投 | 延迟重投 | 延迟重投 | 经延迟队列发送副本 | 原地等待，占住分区 |
+| 停机时放弃计为一次尝试 | 否 | 是 | 是 | 否 | 否 |
+| 重启后消息仍在 | 否 | 是 | 是 | 是 | 是 |
+
+在 Kafka 上，同一个分区的消息按顺序逐条处理：`concurrency` 表示一个实例同时处理几个分区；一条消息的尝试次数由正在处理它的实例计数。RabbitMQ 无法列出一个队列有哪些组：组件把它们记在 `results.store` 中，各应用必须共用这个存储，`request()` 和 `result()` 才能在不指定组时找到组。
+
+## 6. 异常
+
+| 异常 | 什么时候 |
+|---|---|
+| `QueueInvalidMessageException`（400） | 消息不是对象、队列名为空、消息头使用了 `x-lkt-`、值无法编码 |
+| `QueueCapabilityException` | 驱动不支持的选项（`priority`、`dedupe`、`delay`、`ordered`），没有保存结果 |
+| `QueueRequestTimeoutException`（504） | `request()` 没有在时间内得到结果 |
+| `QueueResultNotFoundException`（404） | `result()` 时消息还没处理完，或编号不存在 |
+| `QueueResultExpiredException`（410） | `result()` 时结果已不再保留 |
+| `QueueAmbiguousGroupException`（400） | 有多个组消费队列时，`request()` 或 `result()` 没有指定 `group` |
+| `QueueJobFailedException` | `request()` 或 `result()` 的消息处理失败（带有它的 `error` 和 `attempts`） |
+| `QueueProcessingTimeoutException`（504） | 处理超过 `timeout` 而失败（会重试） |
+| `QueueDiscardException` | 由动作抛出，表示丢弃这条消息 |
+| `QueueDriverNotFoundException` | 驱动的客户端包没有安装 |
+| `QueueDriverVersionException` | 服务端版本低于驱动支持的最低版本 |

package/doc/zh/Schedules.md

@@ -0,0 +1,193 @@
+# Lakutata 定时任务
+
+`@Schedule` 让控制器的方法按计划执行：每隔固定时间执行一次，或者在 cron 表达式指定的时间执行。负责执行这些方法的是定时适配器，即 `lakutata/com/entrypoint` 中的 `scheduleEntrypoint()`，不需要安装其他包。
+
+## 1. 第一个定时任务
+
+```typescript
+import {Application} from 'lakutata'
+import {buildEntrypoints, Controller, scheduleEntrypoint} from 'lakutata/com/entrypoint'
+import {Schedule} from 'lakutata/decorator/ctrl'
+
+class JobController extends Controller {
+    //每 30 秒一次
+    @Schedule('30s')
+    public async heartbeat(): Promise<void> {
+        console.log('Still alive')
+    }
+
+    //每天上海时间 03:00
+    @Schedule({cron: '0 3 * * *', timezone: 'Asia/Shanghai'})
+    public async purge(): Promise<void> {
+        console.log('Purging the expired sessions')
+    }
+}
+
+Application.run(() => ({
+    id: 'jobs.app',
+    name: 'Jobs',
+    components: {
+        entrypoint: buildEntrypoints({
+            controllers: [JobController],
+            schedule: scheduleEntrypoint()
+        })
+    },
+    bootstrap: ['entrypoint']
+}))
+```
+
+- 定时任务在应用启动完成后才开始。入口必须列在 `bootstrap` 里，并且要配置 `schedule` 适配器：没有它，标了 `@Schedule` 的方法永远不会执行。
+- 按间隔执行的任务，第一次执行是在启动后过了一个间隔，而不是启动时立即执行（如果启动时也要执行一次，见下文的 `immediate`）。
+- 应用的每个实例都会执行定时任务。如果同一时间只想让一个实例执行，见第 4 节。
+
+## 2. 计划的写法
+
+`@Schedule(schedule, options?)` 的第一个参数是计划。第二个参数是所有动作通用的动作选项（`name`、`description`、`acl`、`rule`、`middlewares`、`groups`）。和其他动作装饰器不同，它不接受 DTO：定时任务没有输入。控制器的 `@Prefix` 对定时任务不起作用。
+
+计划可以是：
+
+| 计划 | 含义 |
+|---|---|
+| `'30s'`、`'1h30m'`、`'1.5h'` | 用时长表示的间隔 |
+| `5000` | 以毫秒表示的间隔 |
+| `'0 */5 * * * *'`、`'@daily'` | cron 表达式（不是时长的字符串都按 cron 表达式处理） |
+| `{every: '30s', ...}` | 间隔，可加下表中的选项 |
+| `{cron: '0 3 * * *', timezone: 'Asia/Shanghai', ...}` | cron 表达式，可指定时区并加下表中的选项 |
+
+时长由数字加单位组成，单位是 `ms`、`s`、`m`、`h` 或 `d`。多段会相加（`1h30m`），可以带小数（`1.5h`），中间可以有空格。没有单位的数字（`'30'`）不算时长：它会被当成 cron 表达式，然后报错。
+
+对象形式的选项：
+
+| 选项 | 默认值 | 含义 |
+|---|---|---|
+| `overlap` | `false` | 上一次还没执行完时，也开始新的一次。默认会跳过这一次 |
+| `immediate` | `false` | 应用启动完成后立即额外执行一次 |
+| `exclusive` | `false` | 同一时间只在应用的一个实例中执行（见第 4 节） |
+| `timezone` | 进程所在的时区 | cron 表达式使用的 IANA 时区 |
+
+### cron 表达式
+
+cron 表达式有 6 个字段；省略秒时是 5 个字段，秒取 0：
+
+```text
+┌──────────── 秒（0-59），可省略
+│ ┌────────── 分（0-59）
+│ │ ┌──────── 时（0-23）
+│ │ │ ┌────── 日（1-31）
+│ │ │ │ ┌──── 月（1-12，或 jan-dec）
+│ │ │ │ │ ┌── 星期（0-7，或 sun-sat；0 和 7 都是星期日）
+│ │ │ │ │ │
+* * * * * *
+```
+
+每个字段可以写 `*`（或 `?`）、单个值、范围（`1-5`）、步长（`*/15`、`10/15`、`10-40/15`），或用逗号分隔的列表（`1,15,30`）。月份和星期的英文缩写不区分大小写（`mon-fri`）。日和星期两个字段都有限制时，满足其中任意一个就算匹配，与传统 cron 相同。
+
+支持的宏有 `@yearly`（或 `@annually`）、`@monthly`、`@weekly`、`@daily`（或 `@midnight`）和 `@hourly`。不支持 `L`、`W`、`#` 和 `@reboot`。
+
+| 表达式 | 执行时间 |
+|---|---|
+| `'*/10 * * * * *'` | 每 10 秒 |
+| `'0 */5 * * *'` | 每 5 分钟 |
+| `'30 9 * * mon-fri'` | 周一到周五的 09:30 |
+| `'0 0 1 * *'` | 每月 1 日零点 |
+
+**夏令时。** 在会调整时钟的时区里，春季被跳过的时刻（纽约 2026 年 3 月 8 日的 02:30）当天不会执行，秋季重复出现的时刻只执行一次。
+
+**写错时。** 间隔或 cron 表达式不合法会抛出 `SyntaxError`，时区不存在会抛出 `RangeError`，这些错误在定义控制器类时就会抛出，应用还没启动。没有任何日期能匹配的表达式（比如 2 月 30 日，`'0 0 30 2 *'`）同样会抛出 `SyntaxError`：它永远不会执行。
+
+## 3. 什么时候执行
+
+- **间隔：** 启动后过一个间隔执行第一次，之后每隔一个间隔执行一次。
+- **cron：** 每次都安排在下一个与表达式匹配的时间。
+- **错过的执行**会被跳过，不会补上：进程被挂起过（比如笔记本休眠）之后，任务在下一个计划时间执行。
+- **重叠：** 默认情况下，上一次还在执行时，这一次会被跳过。设置 `overlap: true` 后，同一个任务可以同时有多次在执行。
+- **`immediate: true`** 会在应用启动完成后立即额外执行一次。
+
+## 4. 只在一个实例中执行
+
+应用常常同时运行多个实例（多个容器、多台服务器）。声明了 `exclusive: true` 的任务，同一时间只会在其中一个实例中执行：
+
+```typescript
+import {Controller} from 'lakutata/com/entrypoint'
+import {Schedule} from 'lakutata/decorator/ctrl'
+
+class ReportController extends Controller {
+    //每 5 分钟，只在一个实例中执行
+    @Schedule({every: '5m', exclusive: true})
+    public async build(): Promise<void> {
+    }
+
+    //每天 03:00，使用组件 locks 中名为 schedule:purge 的锁
+    @Schedule({cron: '0 3 * * *', exclusive: {mutex: 'locks', key: 'purge'}})
+    public async purge(): Promise<void> {
+    }
+}
+```
+
+- 应用需要一个各实例共用的互斥锁组件，默认名为 `mutex`，也可以用 `exclusive.mutex` 指定（见 [Mutex](Mutex.md) 第 4 节）。没有这个组件时，任务不会执行，错误会写入日志。
+- 每次执行前先尝试获取锁 `schedule:<key>`，key 默认是动作名，也可以用 `exclusive.key` 指定。没拿到锁的实例跳过这一次。
+- 独占任务的间隔按时钟对齐（每 5 分钟就是 :00、:05、:10……），这样所有实例安排的时间都相同。
+- 执行结束后，锁会一直保留到计划时间之后半个周期（最多 30 秒），这样即使某个实例的时钟稍慢，也不会把任务再执行一遍。
+
+## 5. 执行过程中
+
+每次执行都像处理一个请求：它在自己的作用域里得到一个新的控制器，经过入口的中间件和访问控制。方法不会收到输入，返回值也会被忽略。
+
+`this.context` 是一个 `ScheduleContext`：
+
+| 属性 | 含义 |
+|---|---|
+| `schedule` | 计划的文字形式：`'every 30s'`、`'cron 0 3 * * *'` |
+| `scheduledAt` | 这次执行的计划时间（`Date`）；实际开始可能晚几毫秒 |
+| `run` | 这是本进程中的第几次执行，从 1 开始（被跳过的不计入） |
+
+```typescript
+import {Controller, type ScheduleContext} from 'lakutata/com/entrypoint'
+import {Schedule} from 'lakutata/decorator/ctrl'
+
+class JobController extends Controller {
+    @Schedule({every: '1m', immediate: true})
+    public async sync(): Promise<void> {
+        const context: ScheduleContext = this.context as ScheduleContext
+        console.log(`Run ${context.run} of ${context.schedule}, planned at ${context.scheduledAt.toISOString()}`)
+    }
+}
+```
+
+## 6. 错误与跳过
+
+某一次执行抛出错误，不会影响这个任务：后面的执行照常进行。默认情况下，错误由应用的日志组件（`log`）记录，没有日志组件时写到控制台。适配器的选项可以替换这一行为：
+
+```typescript
+import {scheduleEntrypoint} from 'lakutata/com/entrypoint'
+
+export const schedule = scheduleEntrypoint({
+    //某次执行失败
+    onError: (error, action, context): void => {
+        console.error(`${action.name} failed at ${context.scheduledAt.toISOString()}: ${(error as Error).message}`)
+    },
+    //某次执行被跳过：上一次还没结束（'overlap'），或者锁在别的实例手里（'exclusive'）
+    onSkip: (action, scheduledAt, reason): void => {
+        console.warn(`${action.name} skipped at ${scheduledAt.toISOString()} (${reason})`)
+    }
+})
+```
+
+适配器还接受 `middlewares`（定时任务专用的中间件，在入口的中间件之后执行）和 `name`。
+
+## 7. 停止
+
+应用停止时，不再开始新的执行，独占任务会释放它们的锁。正在执行的任务有入口的 `shutdownTimeout`（默认 30 秒）可以完成，超时后会被中止：`this.signal` 会被触发，耗时长的任务可以检查它并提前结束。
+
+## 8. 计算下一次的时间
+
+`lakutata/com/entrypoint` 中的 `Cron` 和 `parseDuration` 就是定时任务使用的解析器：
+
+```typescript
+import {Cron, parseDuration} from 'lakutata/com/entrypoint'
+
+const cron: Cron = new Cron('30 9 * * mon-fri', 'Asia/Shanghai')
+//给定时间之后的下一个时间（精确到秒），永远不匹配时为 undefined
+console.log(cron.next(new Date('2026-10-16T12:00:00Z'))) //2026-10-19T01:30:00.000Z，即上海时间周一 09:30
+console.log(parseDuration('1h30m')) //5400000
+```

package/doc/zh/Security.md

@@ -1,6 +1,6 @@
 # Lakutata 安全
 
-`lakutata/security`（`@lakutata/security` 包）提供基于 bcrypt 的密码哈希（`PasswordHash`）、基于 HMAC 的消息签名（`Mac`）、基于 AES-256-GCM 的认证加密（`Crypt`），支持密钥轮换，以及它们底层的函数。它基于 `node:crypto` 实现（bcrypt 用 JavaScript 实现），没有可选依赖。`lakutata/provider/passwordHash` 只导出 `PasswordHash`。更多细节见 `@lakutata/security` 的 README。
+`lakutata/security`（`@lakutata/security` 包）提供基于 bcrypt 的密码哈希（`PasswordHash`）、基于 HMAC 的消息签名（`Mac`）和基于 AES-256-GCM 的认证加密（`Crypt`），以及它们所基于的函数；其中 `Mac` 和 `Crypt` 支持密钥轮换。它基于 `node:crypto` 实现（bcrypt 用 JavaScript 实现），没有可选依赖。`lakutata/provider/passwordHash` 只导出 `PasswordHash`。更多细节见 `@lakutata/security` 的 README。
 
 ## 1. 提供者
 
@@ -33,7 +33,7 @@ Application
         const token: string = mac.signMessage('user:42')
         //消息被篡改时抛出 InvalidSignatureException
         console.log(mac.unsignMessage(token))
-        //分离的签名
+        //单独的签名，不附在消息上
         const signature: string = mac.sign('payload')
         console.log(mac.verify('payload', signature))
 
@@ -46,7 +46,7 @@ Application
 
 - **密码**：`PasswordHash.hash()` 拒绝 UTF-8 编码超过 72 字节的密码（bcrypt 会忽略超出的字节），抛出 `PasswordTooLongException`；对这类密码，`validate()` 返回 `false`。哈希值请原样保存，并用 `validate()` 校验，不要用 `===` 比较。
 - **密钥**：`Mac` 和 `Crypt` 的密钥是至少 16 个字符的字符串。请用 `generateSecret()` 生成（32 个随机字节，base64url）：把密码当作密钥使用容易被暴力破解。
-- **密钥轮换**：把新密钥放在最前面，在仍需读取旧密钥签名或加密的数据期间保留旧密钥。
+- **密钥轮换**：把新密钥放在最前面；只要还要读取用旧密钥签名或加密的数据，就保留旧密钥。
 - **格式**：签名和加密数据都是不带填充的 base64url 字符串，可以安全地用于 URL 和 Cookie。
 
 ## 2. 按用途选择工具
@@ -81,7 +81,7 @@ const body: string = JSON.stringify({order: 42})
 const signature: string = hmac(body, key, 'sha512')
 console.log(verifyHMAC(body, signature, key, 'sha512'))
 
-//用随机密钥加密，可以用当前或之前的密钥解密
+//用一个密钥加密，用给出的任一密钥解密：当前的或之前的
 const encrypted: string = encryptByKey('card ending 4242', key)
 console.log(decryptByKey(encrypted, [key, generateSecret()]).toString('utf8'))
 
@@ -95,10 +95,10 @@ console.log(constantTimeEqual('presented-token', process.env.API_TOKEN ?? ''))
 
 ## 4. 错误
 
-| 异常 | 时机 |
+| 异常 | 什么时候 |
 |---|---|
 | `PasswordTooLongException` | `PasswordHash.hash()` 的密码 UTF-8 编码超过 72 字节 |
-| `InvalidSignatureException` | `Mac.unsignMessage()` 的消息被篡改、没有签名或由未知密钥签名 |
+| `InvalidSignatureException` | `Mac.unsignMessage()` 的消息被篡改过、没有签名，或者由未知的密钥签名 |
 | `DecryptionFailedException` | `Crypt.decrypt()`、`decryptString()`、`decryptByKey()`、`decryptByPassword()`：密钥或口令错误，数据被篡改或截断 |
 | `InvalidObjectOptionsException`（来自 `lakutata`） | 应用启动时提供者的选项不合法：没有密钥、密钥短于 16 个字符、未知算法、`saltRounds` 不在 4 到 31 之间 |