# Hydro API Docs — Full Reference

> Hydro 在线评测系统插件开发 API 文档（完整版）。
> Deployed: https://hydro-plugin-api-reference.pages.dev
> Source: https://github.com/hydro-dev/Hydro

---

## 核心

### Context 与 Service

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/context.ts

```ts
import { Context, Service, Fiber, FiberState } from 'hydrooj'
```

# Context 与 Service

构成 Hydro 可扩展性基础的核心插件系统类。基类来自 `cordis`。

```ts
import { Context, Service, Fiber, FiberState } from 'hydrooj';
```

## Context

每个插件可访问的核心对象。提供事件订阅、服务注入、路由注册和生命周期管理功能。

`Context` 继承自 `cordis.Context`，通过 `ApiMixin` 服务添加了 Hydro 特有的方法。`WebService` 还混入了 `Route`、`Connection` 和 `withHandlerClass`。

### 路由方法

由 `WebService` 混入，用于注册 HTTP 和 WebSocket 处理器。

| 方法 | 说明 |
|------|------|
| `Route(name, path, Handler, ...permPrivChecker)` | 注册 HTTP 路由；绑定 `name`、`path` 和 `Handler` 类，可附加权限/特权守卫。 |
| `Connection(name, path, Handler, ...permPrivChecker)` | 注册 WebSocket 连接端点；签名与 `Route` 相同，但用于持久连接。 |

### 事件方法

继承自 `cordis.Context`。Hydro 定义了自己的 `EventMap`（参见 `Events`），包含领域相关事件。

| 方法 | 说明 |
|------|------|
| `on(event, callback)` | 订阅事件；返回一个 `Disposable`，调用即可移除监听器。 |
| `emit(event, ...args)` | 同步触发事件，通知所有已注册的监听器。 |
| `parallel(event, ...args)` | 触发事件并并发运行所有监听器；返回 `Promise`，在所有监听器完成后 resolve。 |
| `broadcast(event, ...args)` | 跨所有集群进程广播事件（PM2 或 MongoDB 总线）；在每个节点上调用 `parallel`。 |

### 生命周期与插件方法

继承自 `cordis.Context`，用于管理插件和副作用。

| 方法 | 说明 |
|------|------|
| `plugin(Plugin, config?)` | 在当前上下文注册并初始化插件（类或函数）；返回 `Fiber`。 |
| `effect(() => Disposable)` | 注册副作用；返回的清理函数在上下文销毁时调用。 |
| `mixin(serviceId, methods)` | 将服务实例上的命名方法混入上下文原型，使其可通过 `ctx.method()` 调用。 |
| `inject` | 在插件/服务类上声明服务依赖（静态 `inject` 数组）。 |

### Hydro 特有方法

由 `ApiMixin` 添加 —— 可作为每个上下文实例的直接方法调用。

| 方法 | 说明 |
|------|------|
| `addScript(name, description, schema, run)` | 注册一个具名管理脚本，包含输入验证和异步执行函数。 |
| `provideModule(type, id, module)` | 注册一个可插拔模块（如 `'hash'`、`'problemSearch'`）到全局模块注册表。 |
| `injectUI(node, name, args?, ...permPrivChecker)` | 将 UI 组件注入到前端插槽（`Nav`、`ProblemAdd`、`ControlPanel` 等），可附加权限守卫。 |
| `setImmediate(callback)` | 在下一个事件循环 tick 调度回调；上下文销毁时自动清理。 |

### Context 属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `loader` | `Loader` | 管理插件生命周期和热重载的插件加载器服务。 |
| `check` | `CheckService` | 用于健康监测的检查/ping 服务。 |
| `domain` | `DomainDoc?` | 当前域文档（在域作用域的上下文中可用）。 |
| `geoip` | `GeoIP?` | GeoIP 解析服务（可选，可能未加载）。 |

---

## Service

所有 Hydro 服务的抽象基类。继承 `cordis.Service<T, Context>`。

```ts
import { Service } from 'hydrooj';

export default class MyService extends Service {
    static inject = ['database'];  // 声明依赖

    constructor(ctx: Context) {
        super(ctx, 'myService');
    }
}
```

服务通过 `ctx.plugin(MyService)` 注册，以其服务 ID 在上下文中可用。其他插件通过静态 `inject` 数组声明依赖。

---

## 类型

`Fiber` 和 `FiberState` 从 `hydrooj` 重新导出（源自 `cordis`，适配 Hydro 的 `Context`）。`Disposable` 和 `Plugin` 为 `cordis` 内部类型，供参考。

| 类型 | 说明 |
|------|------|
| `Fiber` | `cordis.Fiber<Context>` —— 表示插件在上下文树中的生命周期节点；追踪状态（pending、loading、active、disposed）。 |
| `FiberState` | Fiber 生命周期状态枚举：`PENDING`、`LOADING`、`ACTIVE`、`DISPOSED` 等。 |
| `Disposable` | `() => void` —— 由 `on()`、`effect()` 等注册方法返回的清理函数（`cordis` 类型，需从 `cordis` 直接导入）。 |
| `Plugin` | 插件定义的类型别名 —— 可以是继承 `Service` 的类或 `(ctx, config) => void` 函数（`cordis` 类型，需从 `cordis` 直接导入）。 |

### 错误类 (Error Classes)

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/error.ts

# 错误类 (Error Classes)

Hydro 插件开发中可用的所有错误类型，包括基础错误类和 Hydro 自定义业务错误。

> **Source**: `packages/hydrooj/src/error.ts`, `@hydrooj/framework/error`

## 导入

```ts
import {
    HydroError, UserFacingError, BadRequestError, ForbiddenError, NotFoundError,
    CreateError,
    // ... 自定义错误类
} from 'hydrooj';
```

## CreateError 工厂函数

`CreateError` 用于创建自定义错误类。所有 Hydro 内置错误均通过此函数生成。

### 签名

```ts
function CreateError(
    name: string,
    Base: typeof UserFacingError,
    message: string | ((this: HydroError) => string),
    httpStatus?: number
): typeof UserFacingError;
```

### 参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `name` | `string` | 错误类名称，同时作为错误 `name` 属性 |
| `Base` | `typeof UserFacingError` | 父错误类，决定 HTTP 状态码默认值 |
| `message` | `string \| (this: HydroError) => string` | 错误消息模板，支持 `{0}` `{1}` `{2}` 占位符；或返回消息的函数 |
| `httpStatus` | `number` | 可选，覆盖 HTTP 状态码 |

### 用法示例

```ts
import { CreateError, ForbiddenError } from 'hydrooj';

// 简单消息 + 占位符
export const MyError = CreateError('MyError', ForbiddenError, 'Something went wrong: {0}');

// 动态消息（基于 this.params 计算）
export const DynamicError = CreateError('DynamicError', ForbiddenError, function (this: HydroError) {
    return `Value is ${this.params[0]}`;
});

// 抛出
throw new MyError('detail info');
```

消息模板中的 `{0}`、`{1}`、`{2}` 会被替换为构造函数传入的参数（`this.params`）。

---

## 基础错误类

由 `@hydrooj/framework/error` 导出，构成错误继承体系。

| 类名 | HTTP 状态码 | 说明 |
|------|------------|------|
| `HydroError` | — | 所有 Hydro 错误的基类。持有 `name`、`params`、`message` 属性 |
| `UserFacingError` | 500 | 面向用户的错误基类，继承 `HydroError`。带 HTTP 状态码 |
| `BadRequestError` | 400 | 请求参数或业务逻辑无效，继承 `UserFacingError` |
| `ForbiddenError` | 403 | 权限不足或操作被拒绝，继承 `UserFacingError` |
| `NotFoundError` | 404 | 资源不存在，继承 `UserFacingError` |

继承关系：

```
HydroError
└── UserFacingError (500)
    ├── BadRequestError (400)
    ├── ForbiddenError (403)
    └── NotFoundError (404)
```

---

## Hydro 自定义错误

以下错误均定义于 `packages/hydrooj/src/error.ts`，通过 `CreateError` 创建。

### Internal / Server Error (500)

继承 `UserFacingError`，表示服务端异常。

| 错误类 | 默认消息 |
|--------|----------|
| `RemoteOnlineJudgeError` | `RemoteOnlineJudgeError` |
| `SendMailError` | `Failed to send mail to {0}. (1)` |

### Permission / Auth Errors (403)

继承 `ForbiddenError`，表示权限验证失败。

| 错误类 | 默认消息 |
|--------|----------|
| `LoginError` | `Invalid password for user {0}.` |
| `BuiltinLoginError` | `Builtin login is disabled.` |
| `AccessDeniedError` | `Access denied.` |
| `InvalidTokenError` | `The {0} Token is invalid.` |
| `BlacklistedError` | `Address or user {0} is blacklisted.` |
| `VerifyPasswordError` | `Passwords don't match.` |
| `OpcountExceededError` | `Too frequent operations of {0} (limit: {2} operations in {1} seconds).` |
| `PermissionError` | `You don't have the required permission ({0}) in this domain.` *动态* |
| `PrivilegeError` | `You don't have the required privilege.` *动态* |
| `CurrentPasswordError` | `Current password doesn't match.` |

> `PermissionError`：若 `params[0]` 为 `bigint` 权限标志，自动替换为对应的权限描述文本。
>
> `PrivilegeError`：若缺少 `PRIV_USER_PROFILE`，消息变为 `"You're not logged in."`。

### User / Domain Errors (403)

继承 `ForbiddenError`，表示用户或域操作冲突。

| 错误类 | 默认消息 |
|--------|----------|
| `UserAlreadyExistError` | `User {0} already exists.` |
| `RoleAlreadyExistError` | `This role already exists.` |
| `DomainAlreadyExistsError` | `The domain {0} already exists.` |
| `DomainJoinForbiddenError` | `You are not allowed to join domain {0}. {1}` |
| `DomainJoinAlreadyMemberError` | `Failed to join the domain. You are already a member.` |
| `InvalidJoinInvitationCodeError` | `The invitation code you provided is invalid.` |
| `AlreadyVotedError` | `You've already voted.` |

### Contest / Homework Errors (403)

继承 `ForbiddenError`，表示比赛/作业相关业务规则违反。

| 错误类 | 默认消息 |
|--------|----------|
| `ContestNotAttendedError` | `You haven't attended this contest yet.` |
| `ContestAlreadyAttendedError` | `You've already attended this contest.` |
| `ContestNotLiveError` | `This contest is not live.` |
| `ContestNotEndedError` | `This contest is not ended.` |
| `ContestScoreboardHiddenError` | `Contest scoreboard is not visible.` |
| `HomeworkNotLiveError` | `This homework is not open.` |
| `HomeworkNotAttendedError` | `You haven't claimed this homework yet.` |

### Training Errors (403)

继承 `ForbiddenError`。

| 错误类 | 默认消息 |
|--------|----------|
| `TrainingAlreadyEnrollError` | `You've already enrolled this training.` |

### Problem / File Errors (403)

继承 `ForbiddenError`，表示题目或文件操作被拒绝。

| 错误类 | 默认消息 |
|--------|----------|
| `NotAssignedError` | `You are not assigned to this {0}.` |
| `FileLimitExceededError` | `File {0} limit exceeded.` |
| `FileUploadError` | `File upload failed.` |
| `FileExistsError` | `File {0} already exists.` |
| `HackFailedError` | `Hack failed: {0}` |
| `ProblemAlreadyExistError` | `Problem {0} already exists.` |
| `ProblemAlreadyUsedByContestError` | `Problem {0} is already used by contest {1}.` |
| `ProblemNotAllowPretestError` | `Pretesting is not supported for {0}.` |
| `ProblemNotAllowLanguageError` | `This language is not allowed to submit.` | 注意：虽然 JS 变量名为 `ProblemNotAllowLanguageError`，但通过 `CreateError` 注册的内部错误名（`.name` 属性）为 `ProblemNotAllowSubmitError` |
| `ProblemNotAllowCopyError` | `You are not allowed to copy this problem from {0} to {1}.` |
| `DiscussionLockedError` | `The discussion is locked, you can not reply anymore.` |
| `RequireProError` | `RequireProError` |

### Validation / Logic Errors (400)

继承 `BadRequestError`，表示请求参数或业务逻辑无效。

| 错误类 | 默认消息 |
|--------|----------|
| `PretestRejudgeFailedError` | `Cannot rejudge a pretest record.` |
| `HackRejudgeFailedError` | `Cannot rejudge a hack record.` |
| `CannotDeleteSystemDomainError` | `You are not allowed to delete system domain.` |
| `OnlyOwnerCanDeleteDomainError` | `You are not the owner of this domain.` |
| `CannotEditSuperAdminError` | `You are not allowed to edit super admin in web.` |
| `ProblemConfigError` | `Invalid problem config.` |
| `ProblemIsReferencedError` | `Cannot {0} of a referenced problem.` |
| `AuthOperationError` | `{0} is already {1}.` |
| `NotLaunchedByPM2Error` | `Not launched by PM2.` |

### Not Found Errors (404)

继承 `NotFoundError`，表示资源不存在。

| 错误类 | 默认消息 |
|--------|----------|
| `UserNotFoundError` | `User {0} not found.` |
| `NoProblemError` | `No problem.` |
| `RecordNotFoundError` | `Record {0} not found.` |
| `ProblemDataNotFoundError` | `Data of problem {0} not found.` |
| `MessageNotFoundError` | `Message {0} not found.` |
| `DocumentNotFoundError` | `Document {2} not found.` |

### Document Sub-type Not Found (404)

继承 `DocumentNotFoundError`（间接继承 `NotFoundError`），表示特定类型的文档不存在。

| 错误类 | 默认消息 |
|--------|----------|
| `ProblemNotFoundError` | `Problem {1} not found.` |
| `SolutionNotFoundError` | `Solution {1} not found.` |
| `TrainingNotFoundError` | `Training {1} not found.` |
| `ContestNotFoundError` | `Contest {1} not found.` |
| `DiscussionNotFoundError` | `Discussion {1} not found.` |
| `DiscussionNodeNotFoundError` | `Discussion node {1} not found.` |

继承关系：

```
NotFoundError
└── DocumentNotFoundError ("Document {2} not found.")
    ├── ProblemNotFoundError ("Problem {1} not found.")
    ├── SolutionNotFoundError ("Solution {1} not found.")
    ├── TrainingNotFoundError ("Training {1} not found.")
    ├── ContestNotFoundError ("Contest {1} not found.")
    ├── DiscussionNotFoundError ("Discussion {1} not found.")
    └── DiscussionNodeNotFoundError ("Discussion node {1} not found.")
```

### EventMap (事件总线)

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/service/bus.ts

# EventMap (事件总线)

Hydro 插件系统的事件总线。所有可监听事件定义在 `EventMap` 接口中，通过 `cordis` 框架的事件机制分发。

> **Source**: `packages/hydrooj/src/service/bus.ts`
>
> ```ts
> import { Events } from 'hydrooj'; // re-exported as Events
> import type { EventMap } from 'hydrooj'; // original type name
> ```

---

## 使用模式

### ctx.on() — 订阅事件

注册事件监听器，返回一个 `Disposable` 函数，调用即可取消订阅。

```ts
const dispose = ctx.on('problem/add', (doc, docId) => {
    console.log('New problem added:', docId);
});
// 取消订阅
dispose();
```

### ctx.emit() — 同步触发

同步触发事件，所有监听器按注册顺序执行。

```ts
ctx.emit('record/change', rdoc, $set, $push, body);
```

### ctx.parallel() — 并发触发

触发事件，所有监听器并发执行，返回 `Promise` 在全部完成后 resolve。

```ts
await ctx.parallel('app/ready');
```

### ctx.broadcast() — 跨进程广播

跨集群广播事件（PM2 或 MongoDB 总线）。每个节点收到后以 `parallel` 方式执行。

```ts
ctx.broadcast('record/judge', rdoc, updated, pdoc, updater);
```

---

## App Lifecycle

| Event | Signature | Description |
|-------|-----------|-------------|
| `app/listen` | `() => void` | HTTP 服务器开始监听端口时触发。 |
| `app/started` | `() => void` | 应用启动完成时触发。 |
| `app/ready` | `() => VoidReturn` | 所有插件加载完毕、应用就绪时触发。用于异步初始化。 |
| `app/exit` | `() => VoidReturn` | 应用即将关闭时触发。用于清理资源。 |
| `app/before-reload` | `(entries: Set<string>) => VoidReturn` | 热重载发生前触发，`entries` 为即将重载的插件路径集合。 |
| `app/reload` | `(entries: Set<string>) => VoidReturn` | 热重载完成后触发。 |

## File Watch

| Event | Signature | Description |
|-------|-----------|-------------|
| `app/watch/change` | `(path: string) => VoidReturn` | 监视的文件内容发生变更时触发。 |
| `app/watch/unlink` | `(path: string) => VoidReturn` | 监视的文件被删除时触发。 |

## Database

| Event | Signature | Description |
|-------|-----------|-------------|
| `database/connect` | `(db: Db) => void` | 数据库连接建立后触发，传入 `Db` 实例。 |
| `database/config` | `() => VoidReturn` | 数据库配置加载时触发。 |

## System

| Event | Signature | Description |
|-------|-----------|-------------|
| `system/setting` | `(args: Record<string, any>) => VoidReturn` | 系统设置变更时触发。 |
| `system/setting-loaded` | `() => VoidReturn` | 系统设置加载完毕时触发。 |
| `bus/broadcast` | `(event: keyof EventMap, payload: any, trace?: string) => VoidReturn` | 跨进程广播消息到达时触发。一般不直接监听，由 `ctx.broadcast()` 内部使用。 |
| `monitor/update` | `(type: 'server' \| 'judge', $set: any) => VoidReturn` | 监控数据更新时触发。 |
| `monitor/collect` | `(info: any) => VoidReturn` | 收集监控信息时触发。 |
| `api/update` | `() => void` | API 路由更新时触发。 |

## Scheduled Task

| Event | Signature | Description |
|-------|-----------|-------------|
| `task/daily` | `() => void` | 每日定时任务触发。 |
| `task/daily/finish` | `(pref: Record<string, number>) => void` | 每日任务完成后触发，传入执行偏好统计。 |

## Subscription (WebSocket)

| Event | Signature | Description |
|-------|-----------|-------------|
| `subscription/init` | `(h: ConnectionHandler<Context>, privileged: boolean) => VoidReturn` | WebSocket 订阅初始化时触发。 |
| `subscription/subscribe` | `(channel: string, user: User, metadata: Record<string, string>) => VoidReturn` | 用户订阅某频道时触发。 |
| `subscription/enable` | `(channel: string, h: ConnectionHandler<Context>, privileged: boolean, onDispose: (disposable: () => void) => void) => VoidReturn` | 订阅频道激活时触发；通过 `onDispose` 注册清理回调。 |

## User

| Event | Signature | Description |
|-------|-----------|-------------|
| `user/message` | `(uid: number[], mdoc: Omit<MessageDoc, 'to'>) => void` | 用户收到消息时触发。 |
| `user/get` | `(udoc: User) => void` | 用户信息被查询时触发。 |
| `user/delcache` | `(content: string \| true) => void` | 用户缓存失效时触发。 |
| `user/import/parse` | `(payload: any) => VoidReturn` | 用户导入解析阶段触发。 |
| `user/import/create` | `(uid: number, udoc: any) => VoidReturn` | 用户导入创建阶段触发。 |

## Domain

| Event | Signature | Description |
|-------|-----------|-------------|
| `domain/create` | `(ddoc: DomainDoc) => VoidReturn` | 域创建后触发。 |
| `domain/before-get` | `(query: Filter<DomainDoc>) => VoidReturn` | 域查询前触发，可修改查询条件。 |
| `domain/get` | `(ddoc: DomainDoc) => VoidReturn` | 域查询后触发。 |
| `domain/before-update` | `(domainId: string, $set: Partial<DomainDoc>) => VoidReturn` | 域更新前触发，可拦截或修改更新内容。 |
| `domain/update` | `(domainId: string, $set: Partial<DomainDoc>, ddoc: DomainDoc) => VoidReturn` | 域更新后触发。 |
| `domain/delete` | `(domainId: string) => VoidReturn` | 域删除后触发。 |
| `domain/delete-cache` | `(domainId: string) => VoidReturn` | 域缓存失效时触发。 |

## Document

| Event | Signature | Description |
|-------|-----------|-------------|
| `document/add` | `(doc: any) => VoidReturn` | 文档创建后触发。 |
| `document/set` | `<T extends keyof DocType>(domainId: string, docType: T, docId: DocType[T], $set: any, $unset: OnlyFieldsOfType<DocType[T], any, true \| '' \| 1>) => VoidReturn` | 文档更新时触发。泛型参数 `T` 对应文档类型键。 |

## Discussion

| Event | Signature | Description |
|-------|-----------|-------------|
| `discussion/before-add` | `(payload: Partial<DiscussionDoc>) => VoidReturn` | 讨论创建前触发，可修改内容。 |
| `discussion/add` | `(payload: Partial<DiscussionDoc>) => VoidReturn` | 讨论创建后触发。 |

## Problem

| Event | Signature | Description |
|-------|-----------|-------------|
| `problem/before-add` | `(domainId: string, content: string, owner: number, docId: number, doc: Partial<ProblemDoc>) => VoidReturn` | 题目创建前触发。 |
| `problem/add` | `(doc: Partial<ProblemDoc>, docId: number) => VoidReturn` | 题目创建后触发。 |
| `problem/before-edit` | `(doc: Partial<ProblemDoc>, $unset: OnlyFieldsOfType<ProblemDoc, any, true \| '' \| 1>) => VoidReturn` | 题目编辑前触发。 |
| `problem/edit` | `(doc: ProblemDoc) => VoidReturn` | 题目编辑后触发。 |
| `problem/before-del` | `(domainId: string, docId: number) => VoidReturn` | 题目删除前触发。 |
| `problem/list` | `(query: Filter<ProblemDoc>, handler: any, sort?: string[]) => VoidReturn` | 题目列表查询时触发。 |
| `problem/get` | `(doc: ProblemDoc, handler: any) => VoidReturn` | 题目详情查询后触发。 |
| `problem/delete` | `(domainId: string, docId: number) => VoidReturn` | 题目删除后触发。 |
| `problem/addTestdata` | `(domainId: string, docId: number, name: string, payload: Omit<FileInfo, '_id'>) => VoidReturn` | 测试数据文件添加后触发。 |
| `problem/renameTestdata` | `(domainId: string, docId: number, name: string, newName: string) => VoidReturn` | 测试数据文件重命名后触发。 |
| `problem/delTestdata` | `(domainId: string, docId: number, name: string[]) => VoidReturn` | 测试数据文件删除后触发。 |
| `problem/addAdditionalFile` | `(domainId: string, docId: number, name: string, payload: Omit<FileInfo, '_id'>) => VoidReturn` | 附加文件添加后触发。 |
| `problem/renameAdditionalFile` | `(domainId: string, docId: number, name: string, newName: string) => VoidReturn` | 附加文件重命名后触发。 |
| `problem/delAdditionalFile` | `(domainId: string, docId: number, name: string[]) => VoidReturn` | 附加文件删除后触发。 |

## Contest

| Event | Signature | Description |
|-------|-----------|-------------|
| `contest/before-add` | `(payload: Partial<Tdoc>) => VoidReturn` | 比赛创建前触发。 |
| `contest/add` | `(payload: Partial<Tdoc>, id: ObjectId) => VoidReturn` | 比赛创建后触发。 |
| `contest/before-edit` | `(tdoc: Tdoc, $set: Partial<Tdoc>) => VoidReturn` | 比赛编辑前触发。 |
| `contest/edit` | `(payload: Tdoc) => VoidReturn` | 比赛编辑后触发。 |
| `contest/list` | `(query: Filter<Tdoc>, handler: any) => VoidReturn` | 比赛列表查询时触发。 |
| `contest/scoreboard` | `(tdoc: Tdoc, rows: ScoreboardRow[], udict: BaseUserDict, pdict: ProblemDict) => VoidReturn` | 比赛排行榜计算时触发，可修改排名结果。 |
| `contest/balloon` | `(domainId: string, tid: ObjectId, bdoc: ContestBalloonDoc) => VoidReturn` | 比赛气球（AC 提示）事件触发。 |
| `contest/del` | `(domainId: string, tid: ObjectId) => VoidReturn` | 比赛删除后触发。 |

## Training

| Event | Signature | Description |
|-------|-----------|-------------|
| `training/list` | `(query: Filter<TrainingDoc>, handler: any) => VoidReturn` | 训练计划列表查询时触发。 |
| `training/get` | `(tdoc: TrainingDoc, handler: any) => VoidReturn` | 训练计划详情查询后触发。 |

## Record

| Event | Signature | Description |
|-------|-----------|-------------|
| `record/change` | `(rdoc: RecordDoc, $set?: any, $push?: any, body?: any) => void` | 评测记录状态变更时同步触发。 |
| `record/judge` | `(rdoc: RecordDoc, updated: boolean, pdoc?: ProblemDoc, updater?: any) => VoidReturn` | 评测记录进入判题阶段时并发触发。 |

## OpLog

| Event | Signature | Description |
|-------|-----------|-------------|
| `oplog/log` | `(type: string, handler: Handler<Context> \| ConnectionHandler<Context>, args: any, data: any) => VoidReturn` | 操作日志记录时触发。 |

---

## 内部广播机制

Hydro 使用两种跨进程广播实现（`bus.ts` 中的 `apply` 函数）：

1. **PM2 模式** — 集群部署时，通过 PM2 的 `launchBus` + BSON 序列化在进程间传递事件。
2. **进程内直调模式** — 单进程或无 PM2 时，`bus/broadcast` 事件直接在本进程内调用 `app.parallel(event, ...payload)`。

插件开发者无需关心底层实现，统一使用 `ctx.broadcast()` 即可。

---

## 框架

### @hydrooj/framework 装饰器与验证器

> Source: https://github.com/hydro-dev/Hydro/blob/master/framework/framework/decorators.ts

# @hydrooj/framework 装饰器与验证器

用于路由处理方法的参数绑定装饰器和类型验证器。

```ts
import { param, query, post, route, Types } from 'hydrooj';
```

## 参数装饰器

将处理方法的参数绑定到特定请求源的装饰器。它们在将值传递给方法之前进行提取、验证和转换。

| 装饰器 | 来源 | 说明 |
|--------|------|------|
| `param` | 全部（query + body） | 从合并后的请求参数中绑定参数。 |
| `query` | 查询字符串 | 从 `request.query` 绑定参数（GET 参数）。 |
| `get` | 查询字符串 | `query` 的别名。 |
| `post` | 请求体 | 从 `request.body` 绑定参数（POST body）。 |
| `route` | 路由参数 | 从路由路径参数及 `domainId` 绑定参数。 |
| `subscribe` | — | 将方法（或类）注册为指定频道名的 WebSocket 订阅处理器。 |

### 用法

每个参数装饰器接受 `(name: string, type?: Type, ...options)`：

```ts
class MyHandler extends Handler {
    @param('name', Types.ShortString)
    @param('page', Types.PositiveInt, true)       // 可选
    @param('tags', Types.CommaSeperatedArray)
    async run(name: string, page: number | undefined, tags: string[]) { }
}
```

### 签名

```ts
(name: string, type: Type, validate?: Validator | null, convert?: Converter) => MethodDecorator
(name: string, type?: Type, isOptional?: boolean, validate?: Validator, convert?: Converter) => MethodDecorator
```

`Type` 可以是 Schemastery schema 或元组 `[convert, validate?, isOptional?]`。

## 类型验证器 — `Types`

预置的类型定义，组合了转换器和验证器。每个都是 `Type<T>`，可用作任何参数装饰器的第二个参数。

### 字符串类型

| 名称 | 输出 | 说明 |
|------|------|------|
| `Types.Content` | `string` | 多行文本内容（去除首尾空格，最长 65535 字符）。 |
| `Types.Key` | `string` | 标识符键（`/^[\w-]{1,255}$/`，SASLprep）。 |
| `Types.Name` | `string` | 通用名称字段（1–255 字符，SASLprep）。**@deprecated** |
| `Types.Username` | `string` | 用户名（3–31 字符或 2 个 CJK 字符，SASLprep）。 |
| `Types.Password` | `string` | 密码字符串（6–255 字符）。 |
| `Types.UidOrName` | `string` | 用户 ID（数字）或用户名（3–31 字符或 2 个 CJK 字符，SASLprep）。 |
| `Types.Email` | `string` | 邮箱地址（`user@domain.tld`，SASLprep）。 |
| `Types.Filename` | `string` | 文件名（1–255 字符，不含 `\/?#~!|*`，SASLprep）。 |
| `Types.DomainId` | `string` | 域标识符（字母开头，4–32 个 `\w` 字符，SASLprep）。 |
| `Types.ProblemId` | `string \| number` | 题目 ID —— 数字字符串自动转换为 `number`。 |
| `Types.Role` | `string` | 角色名（1–31 个 `\w` 或 CJK 字符，SASLprep）。 |
| `Types.Title` | `string` | 短标题（1–64 字符，去除首尾空格）。 |
| `Types.ShortString` | `string` | 短字符串（1–255 字符）。 |
| `Types.String` | `string` | 任意非空字符串。 |
| `Types.Emoji` | `string` | 单个 emoji 字符。 |

### 数值类型

| 名称 | 输出 | 说明 |
|------|------|------|
| `Types.Int` | `number` | 有符号整数（从字符串转换）。 |
| `Types.UnsignedInt` | `number` | 非负整数（允许零）。 |
| `Types.PositiveInt` | `number` | 正整数（≥ 1）。 |
| `Types.Float` | `number` | 有限浮点数（从字符串转换）。 |

### 特殊类型

| 名称 | 输出 | 说明 |
|------|------|------|
| `Types.ObjectId` | `ObjectId` | MongoDB ObjectId（通过 `ObjectId.isValid` 验证）。 |
| `Types.Boolean` | `boolean` | 布尔值 —— 除 `'false'`/`'off'`/`'no'`/`'0'` 外的值为真；始终可选。 |
| `Types.Date` | `string` | `YYYY-MM-DD` 格式的日期字符串（零填充）。 |
| `Types.Time` | `string` | `HH:MM` 格式的时间字符串（零填充）。 |

### 组合类型

| 名称 | 输出 | 说明 |
|------|------|------|
| `Types.Range(arr \| obj)` | `T` | 接受给定数组或对象键中的任意值；数字字符串自动转换为 `number`。 |
| `Types.NumericArray` | `number[]` | 有限数字数组（逗号分隔字符串或 JSON 数组）。 |
| `Types.CommaSeperatedArray` | `string[]` | 以逗号分隔的字符串数组。 |
| `Types.Set` | `Set<any>` | 将数组或单个值转换为 `Set`。 |
| `Types.Any` | `any` | 透传，不做验证。 |
| `Types.ArrayOf(type, isOptional?)` | `T[]` | 将任意 `Type<T>` 包装为数组变体；可选元素变为 `undefined`。 |
| `Types.AnyOf(...types)` | `T` | 联合类型 —— 接受匹配给定类型中任意一个的值。 |

## 工具类型

重新导出的 TypeScript 类型，用于构建自定义验证器：

| 类型 | 说明 |
|------|------|
| `Converter<T>` | `(value: any) => T` —— 将原始输入转换为类型化输出。 |
| `Validator` | `(value: any) => boolean` —— 值有效时返回 `true`。 |
| `Type<T>` | `Schema<T> \| readonly [Converter<T>, Validator?, (boolean \| 'convert')?]` —— Schemastery schema 或 `[convert, validate?, optional?]` 元组。 |

### @hydrooj/framework 重新导出

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/plugin-api.ts

# @hydrooj/framework 重新导出

通过 `hydrooj` 从 `@hydrooj/framework` 重新导出的核心 Web 框架接口。

## 概述

这些符号是 Hydro 插件中定义路由、处理器和 API 操作的基础构建块。

```ts
import {
    Apis, APIS, HandlerCommon, httpServer,
    Mutation, Query, Router, Subscription, WebService,
} from 'hydrooj';
```

## API 定义辅助工具

| 导出 | 类型 | 说明 |
|------|------|------|
| `Query` | Function | 定义只读 API 操作；返回 `ApiCall<'Query', Arg, Res>`。 |
| `Mutation` | Function | 定义写入 API 操作；返回 `ApiCall<'Mutation', Arg, Res>`。 |
| `Subscription` | Function | 定义实时事件流 API 操作；返回带 `emit` 回调的 `ApiCall<'Subscription', Arg, Res>`。 |

## API 注册表

| 导出 | 类型 | 说明 |
|------|------|------|
| `Apis` | Interface | 描述所有已注册 API 操作按命名空间组织的类型化形状的 TypeScript 接口。 |
| `APIS` | Object | 运行时字典，持有所有已注册的 API 调用定义。插件通过 `ApiService.provide()` 将其 API 注册到此对象。 |

## 处理器

| 导出 | 类型 | 说明 |
|------|------|------|
| `HandlerCommon` | Class | HTTP 和 WebSocket 处理器的基类；提供 `request`、`response`、`args`、`user` 及工具方法如 `checkPerm()`、`checkPriv()`、`url()`、`renderHTML()`。 |

## 路由与服务器

| 导出 | 类型 | 说明 |
|------|------|------|
| `Router` | Class | 扩展的 Koa Router（`@koa/router`），支持 WebSocket（`ws()` 方法）和可释放的路由注册。 |
| `httpServer` | `http.Server` | 底层 Node.js `http.Server` 实例。 |
| `WebService` | Class | 核心 Web 服务器服务（继承 cordis `Service`）；管理路由/连接注册（`ctx.Route()`、`ctx.Connection()`）、中间件层、处理器混入和模板渲染器。 |

---

## 处理器

### JudgeHandler

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/handler/judge.ts

```ts
import { JudgeHandler, JudgeResultCallbackContext, postJudge } from 'hydrooj'
```

# JudgeHandler

评测系统扩展接口，用于处理评测任务生命周期、结果回调和守护进程通信。

`JudgeHandler` 是整个模块的命名空间重新导出。单独的命名导出（`JudgeResultCallbackContext`、`postJudge`）也可直接使用。

---

## 类

### `JudgeResultCallbackContext`

管理单个评测任务结果回调的生命周期。通过内部 promise 链序列化所有 `next`/`end` 操作以确保更新有序。实现了 `then` 方法，因此实例可以直接被 await（在 `end()` 被调用时 resolve）。

**构造函数**: `new JudgeResultCallbackContext(ctx: Context, task: Omit<Task, '_id'> & { type: string })`

| 属性 | 类型 | 说明 |
|------|------|------|
| `ctx` | `Context` | 用于广播事件的 Cordis 上下文 |
| `task` | `Omit<Task, '_id'> & { type: string }` | 正在处理的评测任务 |

#### 实例方法

| 方法 | 说明 |
|------|------|
| `next(body: Partial<JudgeResultBody>)` | 追加中间评测结果（进度更新）。内部序列化以保证顺序。 |
| `end(body?: Partial<JudgeResultBody>)` | 结束评测任务。设置 `judgeAt`/`judger`，清除 `progress`，触发 `postJudge`，并 resolve 可等待的 promise。不传 body 则直接 resolve 而不更新。 |
| `reset()` | 将记录重置为等待状态并重新入队。当评测守护进程在评测过程中断开连接时使用。 |

#### 静态方法

| 方法 | 说明 |
|------|------|
| `JudgeResultCallbackContext.next(domainId: string, rid: ObjectId, body: Partial<JudgeResultBody>)` | 无需实例即可发送中间结果更新。广播 `record/change`。 |
| `JudgeResultCallbackContext.end(domainId: string, rid: ObjectId, body: Partial<JudgeResultBody>)` | 无需实例即可结束评测任务。设置 `judgeAt`/`judger`，触发 `postJudge`，广播 `record/change`。 |
| `JudgeResultCallbackContext.postJudge(rdoc: RecordDoc, context?: JudgeResultCallbackContext)` | 评测后处理：更新题目/比赛状态，递增通过计数，触发 `record/judge` 生命周期钩子。 |

### `JudgeConnectionHandler`（继承 `ConnectionHandler`）

评测守护进程连接的 WebSocket 处理器。管理任务分发、语言配置同步和守护进程生命周期。

> **备注**: 这是 Hydro 核心注册的内部处理器。插件通常不会继承此类。

### `JudgeFilesDownloadHandler`（继承 `Handler`）

评测文件下载（提交代码和测试数据）的 HTTP 处理器。注册在 `GET/POST /judge/files`，需要 `PRIV_JUDGE`。

### `JudgeFileUpdateHandler`（继承 `Handler`）

评测文件上传（如 hack 测试数据）的 HTTP 处理器。注册在 `POST /judge/upload`，需要 `PRIV_JUDGE`。

---

## 函数

### `processJudgeFileCallback(rid: ObjectId, filename: string, filePath: string): Promise<void>`

验证并上传评测生成的文件作为题目测试数据。在调用 `problem.addTestdata` 之前检查文件数量/大小限制和用户权限。

---

## 已废弃

> 以下内容已废弃，不应在新代码中使用。

| 导出 | 替代方案 | 说明 |
|------|----------|------|
| `postJudge(rdoc: RecordDoc)` | `JudgeResultCallbackContext.postJudge(rdoc)` | 作为独立函数的评测后处理 |
| `next(payload: any)` | `JudgeResultCallbackContext.next(...)` | 使用 payload 对象的静态式 next 回调 |
| `end(payload: any)` | `JudgeResultCallbackContext.end(...)` | 使用 payload 对象的静态式 end 回调 |
| `JudgeHandler.apply.next` | — | `apply` 函数上的已废弃别名 |
| `JudgeHandler.apply.end` | — | `apply` 函数上的已废弃别名 |

---

## 生命周期

`apply(ctx)` 函数在启动时注册以下内容：

- 路由 `judge_files_download` 在 `/judge/files` → `JudgeFilesDownloadHandler`（需要 `PRIV_JUDGE`）
- 路由 `judge_files_upload` 在 `/judge/upload` → `JudgeFileUpdateHandler`（需要 `PRIV_JUDGE`）
- 连接 `judge_conn` 在 `/judge/conn` → `JudgeConnectionHandler`（需要 `PRIV_JUDGE`）
- `record/judge` 事件监听器 —— 处理成功的 hack 提交，自动添加 hack 数据并触发重测

---

## 备注

- `JudgeResultCallbackContext` 通过内部 promise 链序列化 `next`/`end` 调用 —— 调用方无需处理排序问题。
- 受控重测模式（`meta.rejudge === 'controlled'`）将结果写入 `record.collHistory` 而非实时记录，以便审核后再应用。
- 当评测守护进程断开连接（连接清理）时，所有进行中的任务将通过 `reset()` 重置并重新入队。

---

## 数据模型

### BlackListModel

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/model/blacklist.ts

```ts
import { BlackListModel } from 'hydrooj'
```

# BlackListModel

用于按 ID 封禁用户或实体的黑名单模型，支持可选过期时间。

`BlackListModel` 是纯静态类。所有方法均通过类本身调用（如 `BlackListModel.add(...)`）。

所有方法均使用 `@ArgMethod` 装饰 —— 可通过参数/CLI 模式调用。

---

## 方法

### 查找

#### `get(id: string): Promise<WithId<Document> | null>`

按 ID 查找黑名单条目。未找到时返回 `null`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `id` | `string` | — | 要查找的实体 ID |
| **返回值** | `Promise<WithId<Document> \| null>` | | |

### 创建与变更

#### `add(id: string, expire?: Date | number): Promise<WithId<Document>>`

将 ID 添加到黑名单，支持可选过期时间。使用 upsert —— 如果条目已存在则更新 `expireAt`。

**过期逻辑：**
- `expire === 0` → 从现在起 1000 个月（实际上永久）
- `expire` 为 `number` → 从现在起该月数
- `expire` 为 `Date` → 直接使用
- `expire` 省略 → 从现在起 365 天

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `id` | `string` | — | 要封禁的实体 ID |
| `expire` | `Date \| number` | `365 天` | 过期时间：Date 直接使用，number 为月数，0 为永久 |
| **返回值** | `Promise<WithId<Document>>` | | 新建或更新后的文档 |

### 删除

#### `del(id: string): Promise<DeleteResult>`

按 ID 删除黑名单条目。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `id` | `string` | — | 要解封的实体 ID |
| **返回值** | `Promise<DeleteResult>` | | |

---

## 属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `coll` | `Collection` | MongoDB `blacklist` 集合（模块级 `db.collection` 引用，非类属性） |

---

## 备注

- 集合在 `expireAt` 上使用 MongoDB TTL 索引 —— 过期条目由 MongoDB 自动删除。
- `add` 设置 `expire=0` 时将过期时间设为 1000 个月，并非真正永久。
- TTL 索引在启动时由 `apply()` 创建：`{ expireAt: -1 }`（`expireAfterSeconds: 0`）。

### BuiltinModel

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/model/builtin.ts

```ts
import { BuiltinModel } from 'hydrooj'
```

# BuiltinModel

内置常量、权限标志、特权标志、评测状态枚举和 UI 元数据，从 `@hydrooj/common` 重新导出并由 Hydro 扩展。

---

## 常量

### PERM —— 域级权限位标志

将权限名映射到 `bigint` 值的对象。在域用户角色上用作位掩码。

| 常量 | 位 | 说明 |
|------|-----|------|
| `PERM_NONE` | `0n` | 无权限 |
| `PERM_VIEW` | `1n << 0` | 查看此域 |
| `PERM_EDIT_DOMAIN` | `1n << 1` | 编辑域设置 |
| `PERM_MOD_BADGE` | `1n << 2` | 显示 MOD 徽章 |
| `PERM_CREATE_PROBLEM` | `1n << 4` | 创建题目 |
| `PERM_EDIT_PROBLEM` | `1n << 5` | 编辑任意题目 |
| `PERM_EDIT_PROBLEM_SELF` | `1n << 6` | 编辑自己的题目 |
| `PERM_VIEW_PROBLEM` | `1n << 7` | 查看题目 |
| `PERM_VIEW_PROBLEM_HIDDEN` | `1n << 8` | 查看隐藏题目 |
| `PERM_SUBMIT_PROBLEM` | `1n << 9` | 提交题目解答 |
| `PERM_READ_PROBLEM_DATA` | `1n << 10` | 读取题目测试数据 |
| `PERM_READ_RECORD_CODE` | `1n << 12` | 读取所有记录代码 |
| `PERM_REJUDGE_PROBLEM` | `1n << 13` | 重测题目 |
| `PERM_REJUDGE` | `1n << 14` | 重测记录 |
| `PERM_VIEW_PROBLEM_SOLUTION` | `1n << 15` | 查看题解 |
| `PERM_CREATE_PROBLEM_SOLUTION` | `1n << 16` | 创建题解 |
| `PERM_VOTE_PROBLEM_SOLUTION` | `1n << 17` | 为题解投票 |
| `PERM_EDIT_PROBLEM_SOLUTION` | `1n << 18` | 编辑任意题解 |
| `PERM_EDIT_PROBLEM_SOLUTION_SELF` | `1n << 19` | 编辑自己的题解 |
| `PERM_DELETE_PROBLEM_SOLUTION` | `1n << 20` | 删除任意题解 |
| `PERM_DELETE_PROBLEM_SOLUTION_SELF` | `1n << 21` | 删除自己的题解 |
| `PERM_REPLY_PROBLEM_SOLUTION` | `1n << 22` | 回复题解 |
| `PERM_EDIT_PROBLEM_SOLUTION_REPLY_SELF` | `1n << 24` | 编辑自己的题解回复 |
| `PERM_DELETE_PROBLEM_SOLUTION_REPLY` | `1n << 25` | 删除任意题解回复 |
| `PERM_DELETE_PROBLEM_SOLUTION_REPLY_SELF` | `1n << 26` | 删除自己的题解回复 |
| `PERM_VIEW_DISCUSSION` | `1n << 27` | 查看讨论 |
| `PERM_CREATE_DISCUSSION` | `1n << 28` | 创建讨论 |
| `PERM_HIGHLIGHT_DISCUSSION` | `1n << 29` | 高亮讨论 |
| `PERM_EDIT_DISCUSSION` | `1n << 30` | 编辑任意讨论 |
| `PERM_EDIT_DISCUSSION_SELF` | `1n << 31` | 编辑自己的讨论 |
| `PERM_DELETE_DISCUSSION` | `1n << 32` | 删除任意讨论 |
| `PERM_DELETE_DISCUSSION_SELF` | `1n << 33` | 删除自己的讨论 |
| `PERM_REPLY_DISCUSSION` | `1n << 34` | 回复讨论 |
| `PERM_EDIT_DISCUSSION_REPLY_SELF` | `1n << 36` | 编辑自己的讨论回复 |
| `PERM_DELETE_DISCUSSION_REPLY` | `1n << 38` | 删除任意讨论回复 |
| `PERM_DELETE_DISCUSSION_REPLY_SELF` | `1n << 39` | 删除自己的讨论回复 |
| `PERM_DELETE_DISCUSSION_REPLY_SELF_DISCUSSION` | `1n << 40` | 删除自己讨论中的回复 |
| `PERM_VIEW_CONTEST` | `1n << 41` | 查看比赛 |
| `PERM_VIEW_CONTEST_SCOREBOARD` | `1n << 42` | 查看比赛排行榜 |
| `PERM_VIEW_CONTEST_HIDDEN_SCOREBOARD` | `1n << 43` | 查看隐藏的比赛排行榜 |
| `PERM_CREATE_CONTEST` | `1n << 44` | 创建比赛 |
| `PERM_ATTEND_CONTEST` | `1n << 45` | 参加比赛 |
| `PERM_VIEW_TRAINING` | `1n << 46` | 查看训练计划 |
| `PERM_CREATE_TRAINING` | `1n << 47` | 创建训练计划 |
| `PERM_EDIT_TRAINING` | `1n << 48` | 编辑任意训练计划 |
| `PERM_EDIT_TRAINING_SELF` | `1n << 49` | 编辑自己的训练计划 |
| `PERM_EDIT_CONTEST` | `1n << 50` | 编辑任意比赛 |
| `PERM_EDIT_CONTEST_SELF` | `1n << 51` | 编辑自己的比赛 |
| `PERM_VIEW_HOMEWORK` | `1n << 52` | 查看作业 |
| `PERM_VIEW_HOMEWORK_SCOREBOARD` | `1n << 53` | 查看作业排行榜 |
| `PERM_VIEW_HOMEWORK_HIDDEN_SCOREBOARD` | `1n << 54` | 查看隐藏的作业排行榜 |
| `PERM_CREATE_HOMEWORK` | `1n << 55` | 创建作业 |
| `PERM_ATTEND_HOMEWORK` | `1n << 56` | 认领作业 |
| `PERM_EDIT_HOMEWORK` | `1n << 57` | 编辑任意作业 |
| `PERM_EDIT_HOMEWORK_SELF` | `1n << 58` | 编辑自己的作业 |
| `PERM_VIEW_RANKING` | `1n << 59` | 查看排名 |
| `PERM_NEVER` | `1n << 60` | 占位符：永不授予 |
| `PERM_PIN_DISCUSSION` | `1n << 61` | 置顶讨论 |
| `PERM_ADD_REACTION` | `1n << 62` | 对讨论使用表情回应 |
| `PERM_PIN_TRAINING` | `1n << 63` | 置顶训练计划 |
| `PERM_LOCK_DISCUSSION` | `1n << 64` | 锁定讨论 |
| `PERM_VIEW_PROBLEM_SOLUTION_ACCEPT` | `1n << 65` | 通过后查看题解 |
| `PERM_READ_RECORD_CODE_ACCEPT` | `1n << 66` | 通过后查看记录代码 |
| `PERM_VIEW_USER_PRIVATE_INFO` | `1n << 67` | 查看域用户私有信息 |
| `PERM_VIEW_HIDDEN_CONTEST` | `1n << 68` | 查看所有比赛（含隐藏） |
| `PERM_VIEW_HIDDEN_HOMEWORK` | `1n << 69` | 查看所有作业（含隐藏） |
| `PERM_VIEW_RECORD` | `1n << 70` | 查看其他用户的记录 |

**复合角色**（预计算的组合）：

| 常量 | 值 | 说明 |
|------|-----|------|
| `PERM_ALL` | `-1n` | 所有权限（所有位设为 1） |
| `PERM_BASIC` | 查看权限的并集 | 访客的基础查看权限 |
| `PERM_DEFAULT` | 查看 + 创建/自己编辑/提交/投票/回复/参加的并集 | 注册用户的默认权限 |
| `PERM_ADMIN` | `-1n` | `PERM_ALL` 的别名 |

### PRIV —— 系统级特权位标志

将特权名映射到 `number`（位移）值的对象。用于站点范围的用户特权。

| 常量 | 位 | 说明 |
|------|-----|------|
| `PRIV_NONE` | `0` | 无特权 |
| `PRIV_EDIT_SYSTEM` | `1 << 0` | 编辑系统设置（从 `PRIV_SET_PRIV` 重命名） |
| `PRIV_SET_PERM` | `1 << 1` | 设置域权限 |
| `PRIV_USER_PROFILE` | `1 << 2` | 编辑用户资料 |
| `PRIV_REGISTER_USER` | `1 << 3` | 注册新用户 |
| `PRIV_READ_PROBLEM_DATA` | `1 << 4` | 读取题目测试数据 |
| `PRIV_READ_RECORD_CODE` | `1 << 7` | 读取所有记录代码 |
| `PRIV_VIEW_HIDDEN_RECORD` | `1 << 8` | 查看隐藏记录 |
| `PRIV_JUDGE` | `1 << 9` | 作为评测节点 |
| `PRIV_CREATE_DOMAIN` | `1 << 10` | 创建新域 |
| `PRIV_VIEW_ALL_DOMAIN` | `1 << 11` | 查看所有域 |
| `PRIV_MANAGE_ALL_DOMAIN` | `1 << 12` | 管理所有域 |
| `PRIV_REJUDGE` | `1 << 13` | 站点范围重测记录 |
| `PRIV_VIEW_USER_SECRET` | `1 << 14` | 查看用户密钥 |
| `PRIV_VIEW_JUDGE_STATISTICS` | `1 << 15` | 查看评测统计 |
| `PRIV_CREATE_FILE` | `1 << 16` | 在存储中创建文件 |
| `PRIV_UNLIMITED_QUOTA` | `1 << 17` | 绕过存储配额限制 |
| `PRIV_DELETE_FILE` | `1 << 18` | 从存储中删除文件 |
| `PRIV_NEVER` | `1 << 20` | 占位符：永不授予 |
| `PRIV_UNLIMITED_ACCESS` | `1 << 22` | 绕过所有访问检查 |
| `PRIV_VIEW_SYSTEM_NOTIFICATION` | `1 << 23` | 查看系统通知 |
| `PRIV_SEND_MESSAGE` | `1 << 24` | 发送消息 |
| `PRIV_MOD_BADGE` | `1 << 25` | 全局显示 MOD 徽章 |

**复合角色**：

| 常量 | 值 | 说明 |
|------|-----|------|
| `PRIV_ALL` | `-1` | 所有特权 |
| `PRIV_DEFAULT` | `USER_PROFILE + CREATE_FILE + SEND_MESSAGE` | 注册用户的默认特权 |

### STATUS —— 评测状态枚举

评测结果状态码枚举。

| 值 | 名称 | 说明 |
|-----|------|------|
| `0` | `STATUS_WAITING` | 等待评测 |
| `1` | `STATUS_ACCEPTED` | 答案正确 |
| `2` | `STATUS_WRONG_ANSWER` | 答案错误 |
| `3` | `STATUS_TIME_LIMIT_EXCEEDED` | 超过时间限制 |
| `4` | `STATUS_MEMORY_LIMIT_EXCEEDED` | 超过内存限制 |
| `5` | `STATUS_OUTPUT_LIMIT_EXCEEDED` | 超过输出限制 |
| `6` | `STATUS_RUNTIME_ERROR` | 运行时错误 |
| `7` | `STATUS_COMPILE_ERROR` | 编译错误 |
| `8` | `STATUS_SYSTEM_ERROR` | 系统错误 |
| `9` | `STATUS_CANCELED` | 提交已取消 |
| `10` | `STATUS_ETC` | 未知错误 |
| `11` | `STATUS_HACKED` | 解法被 Hack |
| `20` | `STATUS_JUDGING` | 正在评测 |
| `21` | `STATUS_COMPILING` | 正在编译 |
| `22` | `STATUS_FETCHED` | 已被评测机获取 |
| `30` | `STATUS_IGNORED` | 提交被忽略 |
| `31` | `STATUS_FORMAT_ERROR` | 格式错误 |
| `32` | `STATUS_HACK_SUCCESSFUL` | Hack 成功 |
| `33` | `STATUS_HACK_UNSUCCESSFUL` | Hack 失败 |

### 状态查找映射

| 导出 | 类型 | 说明 |
|------|------|------|
| `STATUS_TEXTS` | `Record<STATUS, string>` | 每个状态码的完整显示名（如 `"Wrong Answer"`） |
| `STATUS_SHORT_TEXTS` | `Partial<Record<STATUS, string>>` | 每个状态码的缩写（如 `"WA"`、`"TLE"`） |
| `STATUS_CODES` | `Record<STATUS, string>` | 语义类别：`"pending"`、`"pass"`、`"fail"`、`"progress"`、`"ignored"` |
| `NORMAL_STATUS` | `STATUS[]` | 最终结果状态（AC 到 CE）—— 不包括进行中和特殊状态 |

### 用户性别常量

| 导出 | 类型 | 说明 |
|------|------|------|
| `USER_GENDER_MALE` | `0` | 男性常量 |
| `USER_GENDER_FEMALE` | `1` | 女性常量 |
| `USER_GENDER_OTHER` | `2` | 其他性别常量 |
| `USER_GENDERS` | `number[]` | 所有性别值的数组 `[0, 1, 2]` |
| `USER_GENDER_RANGE` | `Record<number, string>` | 显示标签：`"Boy ♂"`、`"Girl ♀"`、`"Other"` |
| `USER_GENDER_ICONS` | `Record<number, string>` | 图标符号：`"♂"`、`"♀"`、`"?"` |

### PERMS

所有域级权限描述符的数组，每个包含 `{ family, key, desc }`。按 family 分组：

| Family | 权限 |
|--------|------|
| `perm_general` | `PERM_VIEW`, `PERM_VIEW_USER_PRIVATE_INFO`, `PERM_EDIT_DOMAIN`, `PERM_MOD_BADGE` |
| `perm_problem` | `PERM_CREATE_PROBLEM`, `PERM_EDIT_PROBLEM`, `PERM_EDIT_PROBLEM_SELF`, `PERM_VIEW_PROBLEM`, `PERM_VIEW_PROBLEM_HIDDEN`, `PERM_SUBMIT_PROBLEM`, `PERM_READ_PROBLEM_DATA` |
| `perm_record` | `PERM_VIEW_RECORD`, `PERM_READ_RECORD_CODE`, `PERM_READ_RECORD_CODE_ACCEPT`, `PERM_REJUDGE_PROBLEM`, `PERM_REJUDGE` |
| `perm_problem_solution` | 题解 CRUD、投票和回复的 12 个权限 |
| `perm_discussion` | 讨论 CRUD、置顶、高亮、锁定、回应和回复的 15 个权限 |
| `perm_contest` | `PERM_VIEW_CONTEST`, `PERM_VIEW_CONTEST_SCOREBOARD`, `PERM_VIEW_CONTEST_HIDDEN_SCOREBOARD`, `PERM_CREATE_CONTEST`, `PERM_ATTEND_CONTEST`, `PERM_EDIT_CONTEST`, `PERM_EDIT_CONTEST_SELF`, `PERM_VIEW_HIDDEN_CONTEST` |
| `perm_homework` | `PERM_VIEW_HOMEWORK`, `PERM_VIEW_HOMEWORK_SCOREBOARD`, `PERM_VIEW_HOMEWORK_HIDDEN_SCOREBOARD`, `PERM_CREATE_HOMEWORK`, `PERM_ATTEND_HOMEWORK`, `PERM_EDIT_HOMEWORK`, `PERM_EDIT_HOMEWORK_SELF`, `PERM_VIEW_HIDDEN_HOMEWORK` |
| `perm_training` | `PERM_VIEW_TRAINING`, `PERM_CREATE_TRAINING`, `PERM_EDIT_TRAINING`, `PERM_PIN_TRAINING`, `PERM_EDIT_TRAINING_SELF` |
| `perm_ranking` | `PERM_VIEW_RANKING` |

### PERMS_BY_FAMILY

`Record<string, PermissionDescriptor[]>` —— 按自动生成的 `family` 索引分组的 `PERMS`。用于按类别渲染权限设置 UI。

### LEVELS

`number[]` —— `[100, 90, 70, 55, 40, 30, 20, 10, 5, 2, 1]` —— 11 个用户等级的百分比阈值。排名百分位低于阈值的用户获得该等级。

### BUILTIN_ROLES

预定义的角色权限集：

| 角色 | 值 | 说明 |
|------|-----|------|
| `guest` | `PERM.PERM_BASIC` | 访客（仅查看）权限 |
| `default` | `PERM.PERM_DEFAULT` | 注册用户默认权限 |
| `root` | `PERM.PERM_ALL` | 完整管理员权限 |

### DEFAULT_NODES

默认讨论节点分类及其子节点（中文标签）。用于为新域填充初始讨论板结构。

### CATEGORIES

题目类别分类 —— 一个 `Record<string, string[]>`，将顶层算法类别映射到子类别标签。用于题目分类。

---

## 方法

### 工具与工厂

#### `getScoreColor(score: number | string): string`

返回数值分数（0–100）对应的十六进制颜色字符串（`#rrggbb`），以 10 分为一档映射红到绿的渐变。非有限值返回 `#000000`。

#### `Permission(family: string, key: bigint, desc: string): PermissionDescriptor`

工厂函数，创建权限描述符对象 `{ family, key, desc }`。内部用于构建 `PERMS` 数组。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `family` | `string` | — | 权限所属分类 |
| `key` | `bigint` | — | 权限常量值（如 `PERM.PERM_VIEW`） |
| `desc` | `string` | — | 权限描述 |
| **返回值** | `PermissionDescriptor` | | `{ family, key, desc }` |

---

## 备注

- `PERM` 标志是 `bigint`（域作用域）；`PRIV` 标志是 `number`（系统作用域）。两者都用按位 OR（`|`）组合，按位 AND（`&`）检查。
- `PERM_VIEW_DISPLAYNAME` 已废弃 —— 请使用 `PERM_VIEW_USER_PRIVATE_INFO`（相同位位置 `1n << 67`）。
- `PRIV_EDIT_SYSTEM` 从 `PRIV_SET_PRIV` 重命名而来；`PRIV_JUDGE` 从更早的名称重命名而来。
- 模块在加载时注册自身到 `global.Hydro.model.builtin`。
- 通过 `export * from '@hydrooj/common/permission'` 和 `export * from '@hydrooj/common/status'` 重新导出。

### ContestModel

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/model/contest.ts

```ts
import { ContestModel } from 'hydrooj'
```

# ContestModel

比赛模型，用于管理多种评分规则（ACM/ICPC、OI、IOI、IOI Strict、Ledo、Assignment）的比赛、排行榜生成、气球通知、答疑和打印任务。

ContestModel 是导出函数的普通模块（非类）。所有函数直接调用。它将 CRUD 和状态操作委托给共享的 `document` 模块，使用 `TYPE_CONTEST = 30`。

---

## 类型导出

### `PrintTaskStatus`

枚举值：`pending`、`printing`、`printed`、`failed`。用于比赛打印任务状态追踪。

---

## 常量

### `RULES: ContestRules`

将规则名映射到其规则定义的对象。键：`acm`、`oi`、`homework`、`ioi`、`ledo`、`strictioi`。每个规则定义评分逻辑、排行榜渲染、可见性控制和记录投影行为。

### `buildContestRule<T>(def): ContestRule<T>`

工厂函数，从部分定义构建新的比赛规则，继承并绑定基础规则中所有未指定的函数。内部用于创建内置规则。

---

## 方法

### 状态谓词

根据比赛的 `beginAt`/`endAt` 时间戳评估当前阶段的工具函数。

#### `isNew(tdoc: Tdoc, days?: number): boolean`

比赛在距今 `days` 天之后开始时返回 `true`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `tdoc` | `Tdoc` | — | 比赛文档 |
| `days` | `number` | `1` | 天数阈值 |
| **返回值** | `boolean` | | |

#### `isUpcoming(tdoc: Tdoc, days?: number): boolean`

比赛在 `days` 天内开始但尚未开始时返回 `true`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `tdoc` | `Tdoc` | — | 比赛文档 |
| `days` | `number` | `7` | 天数阈值 |
| **返回值** | `boolean` | | |

#### `isNotStarted(tdoc: Tdoc): boolean`

当前时间早于 `tdoc.beginAt` 时返回 `true`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `tdoc` | `Tdoc` | — | 比赛文档 |
| **返回值** | `boolean` | | |

#### `isOngoing(tdoc: Tdoc, tsdoc?: any): boolean`

当前时间在 `beginAt` 和 `endAt` 之间时返回 `true`。对于限时比赛，还会检查用户的 `startAt` 未超过允许的时长。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `tdoc` | `Tdoc` | — | 比赛文档 |
| `tsdoc` | `any` | — | 用户比赛状态文档 |
| **返回值** | `boolean` | | |

#### `isDone(tdoc: Tdoc, tsdoc?: any): boolean`

比赛已结束时返回 `true`。对于限时比赛，还会考虑用户的 `startAt` 加上时长。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `tdoc` | `Tdoc` | — | 比赛文档 |
| `tsdoc` | `any` | — | 用户比赛状态文档 |
| **返回值** | `boolean` | | |

#### `isLocked(tdoc: Tdoc, time?: Date): boolean`

排行榜已锁定（`lockAt` 已设置且已过）且尚未解锁时返回 `true`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `tdoc` | `Tdoc` | — | 比赛文档 |
| `time` | `Date` | `new Date()` | 用于比较的时间点 |
| **返回值** | `boolean` | | |

#### `isExtended(tdoc: Tdoc): boolean`

当前时间在罚时/延期时段（在 `penaltySince` 和 `endAt` 之间）时返回 `true`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `tdoc` | `Tdoc` | — | 比赛文档 |
| **返回值** | `boolean` | | |

#### `statusText(tdoc: Tdoc, tsdoc?: any): string`

返回可读的状态字符串：`'New'`、`'Ready (☆▽☆)'`、`'Live...'` 或 `'Done'`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `tdoc` | `Tdoc` | — | 比赛文档 |
| `tsdoc` | `any` | — | 用户比赛状态文档 |
| **返回值** | `string` | | |

---

### CRUD

#### `add(domainId: string, title: string, content: string, owner: number, rule: string, beginAt?: Date, endAt?: Date, pids?: number[], rated?: boolean, data?: any): Promise<ObjectId>`

创建新比赛。验证规则存在且 `beginAt < endAt`。触发 `contest/before-add` 和 `contest/add` 总线事件。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `title` | `string` | — | 比赛标题 |
| `content` | `string` | — | 比赛描述/正文 |
| `owner` | `number` | — | 创建者 UID |
| `rule` | `string` | — | 比赛规则名（`acm`、`oi`、`ioi` 等） |
| `beginAt` | `Date` | `new Date()` | 开始时间 |
| `endAt` | `Date` | `new Date()` | 结束时间 |
| `pids` | `number[]` | `[]` | 题目 ID 列表 |
| `rated` | `boolean` | `false` | 是否为 rated 比赛 |
| `data` | `Partial<Tdoc>` | `{}` | 附加数据（如比赛特定配置） |
| **返回值** | `Promise<ObjectId>` | | 新比赛 ID |

```typescript
// 创建 ACM 规则的比赛
const tid = await contest.add(
  'system',
  '2024 校内选拔赛',
  '## 比赛说明\n...',
  session.uid,
  'acm',
  new Date('2024-06-01T09:00:00'),
  new Date('2024-06-01T14:00:00'),
  [1001, 1002, 1003, 1004, 1005],
  true,
);
```

#### `edit(domainId: string, tid: ObjectId, $set: Partial<Tdoc>): Promise<Tdoc>`

更新比赛字段。如果规则有变更则验证。触发 `contest/before-edit` 和 `contest/edit` 总线事件。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `tid` | `ObjectId` | — | 比赛 ID |
| `$set` | `Partial<Tdoc>` | — | 要更新的字段 |
| **返回值** | `Promise<Tdoc>` | | 更新后的比赛文档 |

```typescript
// 延长比赛结束时间
const updated = await contest.edit(
  'system',
  tid,
  { endAt: new Date('2024-06-01T15:00:00') },
);

// 修改比赛规则并更新题目列表
await contest.edit('system', tid, {
  rule: 'oi',
  pids: [1001, 1002, 1003],
});
```

#### `del(domainId: string, tid: ObjectId): Promise<void>`

删除比赛及所有关联的用户状态。触发 `contest/del` 总线事件。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `tid` | `ObjectId` | — | 比赛 ID |
| **返回值** | `Promise<void>` | | |

#### `get(domainId: string, tid: ObjectId): Promise<Tdoc>`

按 ID 获取单个比赛。未找到时抛出 `ContestNotFoundError`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `tid` | `ObjectId` | — | 比赛 ID |
| **返回值** | `Promise<Tdoc>` | | 比赛文档 |

#### `getMulti(domainId: string, query?: any): FindCursor<Tdoc>`

返回匹配查询的比赛游标，按 `beginAt` 降序排列。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `query` | `any` | — | MongoDB 查询过滤器 |
| **返回值** | `FindCursor<Tdoc>` | | 比赛游标 |

#### `getRelated(domainId: string, pid: number, rule?: string): Promise<Tdoc[]>`

查找包含指定题目（`pids` 中包含 `pid`）的比赛。除非指定了 `rule`，否则过滤隐藏规则。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `pid` | `number` | — | 题目 ID |
| `rule` | `string` | — | 按规则过滤（如 `'acm'`） |
| **返回值** | `Promise<Tdoc[]>` | | 关联的比赛列表 |

#### `count(domainId: string, query: any): Promise<number>`

返回匹配查询的比赛数量。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `query` | `any` | — | MongoDB 查询过滤器 |
| **返回值** | `Promise<number>` | | 匹配数量 |

---

### 状态管理

#### `getStatus(domainId: string, tid: ObjectId, uid: number): Promise<Tsdoc | null>`

获取单个用户的比赛状态。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `tid` | `ObjectId` | — | 比赛 ID |
| `uid` | `number` | — | 用户 ID |
| **返回值** | `Promise<Tsdoc \| null>` | | 用户状态或 `null` |

#### `getMultiStatus(domainId: string, query: any): FindCursor`

返回匹配查询的比赛状态游标。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `query` | `any` | — | MongoDB 查询过滤器 |
| **返回值** | `FindCursor` | | 状态游标 |

#### `getListStatus(domainId: string, uid: number, tids: ObjectId[]): Promise<Record<string, Tsdoc>>`

批量获取指定用户多场比赛的状态，以 `tid.toHexString()` 为键的映射返回。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `uid` | `number` | — | 用户 ID |
| `tids` | `ObjectId[]` | — | 比赛 ID 数组 |
| **返回值** | `Promise<Record<string, Tsdoc>>` | | 以十六进制 ID 为键的状态映射 |

#### `setStatus(domainId: string, tid: ObjectId, uid: number, $set: any): Promise<void>`

覆盖用户在指定比赛上的状态字段。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `tid` | `ObjectId` | — | 比赛 ID |
| `uid` | `number` | — | 用户 ID |
| `$set` | `any` | — | 要设置的状态字段 |
| **返回值** | `Promise<void>` | | |

#### `updateStatus(domainId: string, tid: ObjectId, uid: number, rid: ObjectId, pid: number, { status?, score?, subtasks?, lang? }?: { status?: STATUS, score?: number, subtasks?: Record<number, SubtaskResult>, lang?: string }): Promise<Tsdoc>`

推入新的日志条目（提交结果），并使用比赛规则的 `stat` 函数重新计算用户统计。使用基于修订号的状态更新以确保并发安全。同时对通过的提交触发气球创建。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `tid` | `ObjectId` | — | 比赛 ID |
| `uid` | `number` | — | 用户 ID |
| `rid` | `ObjectId` | — | 评测记录 ID |
| `pid` | `number` | — | 题目 ID |
| `opts` | `{ status?: STATUS, score?: number, subtasks?: Record<number, SubtaskResult>, lang?: string }` | `{}` | 额外选项（评测状态、分数、子任务结果、语言） |
| **返回值** | `Promise<Tsdoc>` | | 更新后的用户状态 |

```typescript
// 提交通过后更新比赛状态
const tsdoc = await contest.updateStatus(
  'system',
  tid,
  session.uid,
  rid,
  1001,
  { status: STATUS.STATUS_ACCEPTED, score: 100 },
);
```

#### `countStatus(domainId: string, query: any): Promise<number>`

返回匹配查询的比赛状态数量。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `query` | `any` | — | MongoDB 查询过滤器 |
| **返回值** | `Promise<number>` | | 匹配数量 |

#### `attend(domainId: string, tid: ObjectId, uid: number, payload?: any): Promise<{}>`

为用户报名比赛。已报名时抛出 `ContestAlreadyAttendedError`。使用 `cappedIncStatus` 原子性防止重复报名。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `tid` | `ObjectId` | — | 比赛 ID |
| `uid` | `number` | — | 用户 ID |
| `payload` | `any` | — | 附加报名信息 |
| **返回值** | `Promise<{}>` | | |

```typescript
// 用户报名比赛
await contest.attend('system', tid, session.uid);

// 带附加信息报名（如队伍名）
await contest.attend('system', tid, session.uid, {
  teamName: '测试小队',
});
```

#### `getAndListStatus(domainId: string, tid: ObjectId): Promise<[Tdoc, Tsdoc[]]>`

获取比赛文档及按规则的 `statusSort` 排序的所有用户状态。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `tid` | `ObjectId` | — | 比赛 ID |
| **返回值** | `Promise<[Tdoc, Tsdoc[]]>` | | 比赛文档和排序后的状态列表 |

#### `recalcStatus(domainId: string, tid: ObjectId): Promise<Tsdoc[]>`

使用比赛规则的 `stat` 函数从日志重新计算所有用户状态。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `tid` | `ObjectId` | — | 比赛 ID |
| **返回值** | `Promise<Tsdoc[]>` | | 重新计算后的状态列表 |

#### `unlockScoreboard(domainId: string, tid: ObjectId): Promise<void>`

解锁已锁定的排行榜，设置 `unlocked: true` 并重新计算所有状态。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `tid` | `ObjectId` | — | 比赛 ID |
| **返回值** | `Promise<void>` | | |

---

### 排行榜

检查用户是否可以查看某些比赛信息的函数。均使用 `this` 上下文，包含 `{ user: User }`。

#### `canViewHiddenScoreboard(this: { user }, tdoc: Tdoc): boolean`

用户拥有比赛或具有 `PERM_VIEW_CONTEST_HIDDEN_SCOREBOARD`（作业为 `PERM_VIEW_HOMEWORK_HIDDEN_SCOREBOARD`）时返回 `true`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `this` | `{ user: User }` | — | 上下文，包含当前用户 |
| `tdoc` | `Tdoc` | — | 比赛文档 |
| **返回值** | `boolean` | | |

#### `canShowRecord(this: { user }, tdoc: Tdoc, allowPermOverride?: boolean): boolean`

比赛规则允许在当前时间显示所有记录，或用户具有排行榜覆盖权限时返回 `true`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `this` | `{ user: User }` | — | 上下文，包含当前用户 |
| `tdoc` | `Tdoc` | — | 比赛文档 |
| `allowPermOverride` | `boolean` | `true` | 是否允许权限覆盖 |
| **返回值** | `boolean` | | |

#### `canShowSelfRecord(this: { user }, tdoc: Tdoc, allowPermOverride?: boolean): boolean`

比赛规则允许显示用户自己的记录，或用户具有排行榜覆盖权限时返回 `true`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `this` | `{ user: User }` | — | 上下文，包含当前用户 |
| `tdoc` | `Tdoc` | — | 比赛文档 |
| `allowPermOverride` | `boolean` | `true` | 是否允许权限覆盖 |
| **返回值** | `boolean` | | |

#### `canShowScoreboard(this: { user }, tdoc: Tdoc, allowPermOverride?: boolean): boolean`

比赛规则允许显示排行榜，或用户具有排行榜覆盖权限时返回 `true`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `this` | `{ user: User }` | — | 上下文，包含当前用户 |
| `tdoc` | `Tdoc` | — | 比赛文档 |
| `allowPermOverride` | `boolean` | `true` | 是否允许权限覆盖 |
| **返回值** | `boolean` | | |

#### `getScoreboard(this: Handler, domainId: string, tid: ObjectId, config: any): Promise<[Tdoc, ScoreboardRow[], BaseUserDict, ProblemDict]>`

使用规则的 `scoreboard` 函数构建完整排行榜。排行榜不可见时抛出 `ContestScoreboardHiddenError`。触发 `contest/scoreboard` 总线事件。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `this` | `Handler` | — | 请求处理上下文 |
| `domainId` | `string` | — | 域 ID |
| `tid` | `ObjectId` | — | 比赛 ID |
| `config` | `any` | — | 排行榜配置选项 |
| **返回值** | `Promise<[Tdoc, ScoreboardRow[], BaseUserDict, ProblemDict]>` | | 比赛文档、排行榜行、用户字典、题目字典 |

```typescript
// 获取完整排行榜
const [tdoc, rows, udict, pdict] = await contest.getScoreboard.call(
  handler,
  'system',
  tid,
  { showDisplayName: true },
);

// rows 为排行数据，udict 为用户信息字典，pdict 为题目信息字典
for (const row of rows) {
  console.log(row.rank, udict[row.uid]?.uname, row.score);
}
```

---

### 气球

ACM 风格首 A 通知的气球管理。

#### `addBalloon(domainId: string, tid: ObjectId, uid: number, rid: ObjectId, pid: number): Promise<ObjectId | null>`

为通过的提交添加气球。判断是否为该题目的首次通过。触发 `contest/balloon` 事件。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `tid` | `ObjectId` | — | 比赛 ID |
| `uid` | `number` | — | 用户 ID |
| `rid` | `ObjectId` | — | 评测记录 ID |
| `pid` | `number` | — | 题目 ID |
| **返回值** | `Promise<ObjectId \| null>` | | 气球 ID，非首次通过返回 `null` |

#### `getBalloon(domainId: string, tid: ObjectId, _id: ObjectId): Promise<BalloonDoc>`

按 ID 获取单个气球。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `tid` | `ObjectId` | — | 比赛 ID |
| `_id` | `ObjectId` | — | 气球 ID |
| **返回值** | `Promise<BalloonDoc>` | | 气球文档 |

#### `getMultiBalloon(domainId: string, tid: ObjectId, query?: any): FindCursor`

返回比赛的气球游标。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `tid` | `ObjectId` | — | 比赛 ID |
| `query` | `any` | — | MongoDB 查询过滤器 |
| **返回值** | `FindCursor` | | 气球游标 |

#### `updateBalloon(domainId: string, tid: ObjectId, _id: ObjectId, $set: any): Promise<BalloonDoc>`

更新气球字段。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `tid` | `ObjectId` | — | 比赛 ID |
| `_id` | `ObjectId` | — | 气球 ID |
| `$set` | `any` | — | 要更新的字段 |
| **返回值** | `Promise<BalloonDoc>` | | 更新后的气球文档 |

---

### 答疑

比赛答疑（提问/回答）管理，以 `TYPE_CONTEST_CLARIFICATION` 类型的子文档存储。

#### `addClarification(domainId: string, tid: ObjectId, owner: number, content: string, ip: string, subject?: number): Promise<ObjectId>`

在比赛上创建新的答疑问题。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `tid` | `ObjectId` | — | 比赛 ID |
| `owner` | `number` | — | 提问者 UID |
| `content` | `string` | — | 问题内容 |
| `ip` | `string` | — | 提问者 IP 地址 |
| `subject` | `number` | `0` | 答疑主题 |
| **返回值** | `Promise<ObjectId>` | | 答疑 ID |

#### `addClarificationReply(domainId: string, did: ObjectId, owner: number, content: string, ip: string): Promise<[any, ObjectId]>`

为已有答疑追加回复。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `did` | `ObjectId` | — | 答疑 ID |
| `owner` | `number` | — | 回复者 UID |
| `content` | `string` | — | 回复内容 |
| `ip` | `string` | — | 回复者 IP 地址 |
| **返回值** | `Promise<[any, ObjectId]>` | | 更新后的文档与回复 ID |

#### `getClarification(domainId: string, did: ObjectId): Promise<ClarificationDoc>`

按 ID 获取单个答疑。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `did` | `ObjectId` | — | 答疑 ID |
| **返回值** | `Promise<ClarificationDoc>` | | 答疑文档 |

#### `getMultiClarification(domainId: string, tid: ObjectId, owner?: number): Promise<ClarificationDoc[]>`

列出比赛的答疑。如果指定 `owner`，则仅包含该用户可见的答疑（owner `$in: [owner, 0]`）。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `tid` | `ObjectId` | — | 比赛 ID |
| `owner` | `number` | — | 过滤可见答疑的用户 ID |
| **返回值** | `Promise<ClarificationDoc[]>` | | 答疑列表 |

---

### 打印任务

现场比赛的打印任务管理。使用 `TYPE_CONTEST_PRINT`。

#### `addPrintTask(domainId: string, tid: ObjectId, uid: number, name: string, content: string): Promise<ObjectId>`

创建 `pending` 状态的新打印任务。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `tid` | `ObjectId` | — | 比赛 ID |
| `uid` | `number` | — | 提交者 UID |
| `name` | `string` | — | 打印任务名称 |
| `content` | `string` | — | 打印内容 |
| **返回值** | `Promise<ObjectId>` | | 打印任务 ID |

#### `updatePrintTask(domainId: string, tid: ObjectId, taskId: ObjectId, $set: any): Promise<boolean>`

更新打印任务字段。修改成功返回 `true`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `tid` | `ObjectId` | — | 比赛 ID |
| `taskId` | `ObjectId` | — | 打印任务 ID |
| `$set` | `any` | — | 要更新的字段 |
| **返回值** | `Promise<boolean>` | | 是否修改成功 |

#### `allocatePrintTask(domainId: string, tid: ObjectId): Promise<PrintDoc | null>`

原子性地领取下一个待处理打印任务，将其状态设为 `printing`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `tid` | `ObjectId` | — | 比赛 ID |
| **返回值** | `Promise<PrintDoc \| null>` | | 打印任务文档或 `null`（无待处理任务） |

#### `getMultiPrintTask(domainId: string, tid: ObjectId, query?: any): FindCursor`

返回比赛的打印任务游标，按 `_id` 升序排列。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `tid` | `ObjectId` | — | 比赛 ID |
| `query` | `any` | — | MongoDB 查询过滤器 |
| **返回值** | `FindCursor` | | 打印任务游标 |

---

### 其他

#### `applyProjection(tdoc: Tdoc, rdoc: RecordDoc, udoc: User): RecordDoc`

应用比赛规则的 `applyProjection`，在比赛进行期间脱敏记录中的敏感字段（分数、时间、内存、测试用例等）。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `tdoc` | `Tdoc` | — | 比赛文档 |
| `rdoc` | `RecordDoc` | — | 评测记录文档 |
| `udoc` | `User` | — | 用户文档 |
| **返回值** | `RecordDoc` | | 脱敏后的记录文档 |

#### `apply(ctx: Context): Promise<void>`

生命周期钩子。注册 `contest/balloon` 事件监听器（发送首 A 消息）并确保气球集合上的数据库索引。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `ctx` | `Context` | — | 插件上下文 |
| **返回值** | `Promise<void>` | | |

---

## 备注

- 比赛是文档类型模型（`TYPE_CONTEST = 30`）。CRUD 和状态操作委托给共享的 `document` 模块。
- 六种内置规则：`acm`（XCPC）、`oi`、`ioi`、`strictioi`、`ledo`、`homework`（隐藏）。每个规则定义 `stat`、`scoreboard`、`scoreboardRow`、`scoreboardHeader`、`showScoreboard`、`showRecord`、`showSelfRecord`、`applyProjection` 和 `check`。
- `updateStatus` 使用基于修订号的状态（`revPushStatus` + `revSetStatus`）实现日志更新的乐观并发控制。
- `attend` 使用 `cappedIncStatus`（上限为 1）原子性防止重复报名；重新抛出为 `ContestAlreadyAttendedError`。
- `add` 和 `edit` 触发前/后总线事件（`contest/before-add`、`contest/add`、`contest/before-edit`、`contest/edit`）。
- 答疑使用 `TYPE_CONTEST_CLARIFICATION` 作为独立 docType，通过父引用关联比赛。
- 打印任务使用 `TYPE_CONTEST_PRINT` 作为独立 docType，通过父引用关联比赛。

### DiscussionModel

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/model/discussion.ts

```ts
import { DiscussionModel } from 'hydrooj'
```

# DiscussionModel

讨论（论坛）模型，用于管理线程化讨论、回复、嵌套尾隔回复、表情回应、讨论节点（分类）和父实体解析。

DiscussionModel 是导出函数的普通模块（非类）。所有函数直接调用（如 `DiscussionModel.add(...)`）。

---

## 类型导出

### `DiscussionDoc`

继承 `Document` —— 讨论文档的形状。

### `Field`

```typescript
type Field = keyof DiscussionDoc
```

所有讨论文档字段名的联合类型。

---

## 常量

### `typeDisplay: Record<number, string>`

将文档类型常量映射到可读名称：`{ 10: 'problem', 20: 'node', 30: 'contest', 40: 'training' }`。

### `PROJECTION_LIST: Field[]`

列表视图中返回的字段：`_id`、`domainId`、`docType`、`docId`、`highlight`、`nReply`、`views`、`pin`、`updateAt`、`owner`、`parentId`、`parentType`、`title`、`hidden`。

### `PROJECTION_PUBLIC: Field[]`

详情视图中返回的字段 —— 在 `PROJECTION_LIST` 基础上增加 `content`、`edited`、`react`、`maintainer`、`lock`。

### `HISTORY_PROJECTION_PUBLIC: (keyof DiscussionHistoryDoc)[]`

历史视图中返回的字段：`title`、`content`、`docId`、`uid`、`time`。

---

## 方法

### 讨论 CRUD

#### `add(domainId: string, parentType: number, parentId: ObjectId | number | string, owner: number, title: string, content: string, ip: string | null = null, highlight: boolean, pin: boolean, hidden?: boolean): Promise<ObjectId>`

在父实体（题目、比赛、训练计划或节点）下创建新讨论。触发 `discussion/before-add` 和 `discussion/add` 总线事件。返回新讨论 ID。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `parentType` | `number` | — | 父实体类型常量 |
| `parentId` | `ObjectId \| number \| string` | — | 父实体 ID |
| `owner` | `number` | — | 创建者 UID |
| `title` | `string` | — | 讨论标题 |
| `content` | `string` | — | 讨论内容 |
| `ip` | `string \| null` | `null` | 创建者 IP 地址 |
| `highlight` | `boolean` | — | 是否高亮 |
| `pin` | `boolean` | — | 是否置顶 |
| `hidden` | `boolean` | `false` | 是否隐藏 |
| **返回值** | `Promise<ObjectId>` | | 新讨论 ID |

```typescript
// 在题目下创建讨论
const did = await DiscussionModel.add(
  'system',                          // domainId
  10,                                // parentType (TYPE_PROBLEM)
  problemId,                         // parentId
  12345,                             // owner
  '关于时间限制的疑问',               // title
  '这道题的 1s 时限是否合理？',       // content
  '127.0.0.1',                       // ip
  false,                             // highlight
  false,                             // pin
);

// 在讨论节点下创建置顶讨论
const pinnedDid = await DiscussionModel.add(
  'system',
  30,                                // parentType (TYPE_DISCUSSION_NODE)
  'general',                         // parentId (节点字符串 ID)
  12345,
  '版规公告',
  '请遵守社区规范...',
  undefined,                         // ip
  true,                              // highlight
  true,                              // pin
  false,                             // hidden
);
```

#### `get<T extends Field>(domainId: string, did: ObjectId, projection?: T[]): Promise<Pick<DiscussionDoc, T>>`

按 ID 获取单个讨论，支持指定字段投影。默认为 `PROJECTION_PUBLIC`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `did` | `ObjectId` | — | 讨论 ID |
| `projection` | `T[]` | `PROJECTION_PUBLIC` | 返回字段列表 |
| **返回值** | `Promise<Pick<DiscussionDoc, T>>` | | |

#### `edit(domainId: string, did: ObjectId, $set: Partial<DiscussionDoc>): Promise<DiscussionDoc>`

更新讨论字段。如果 `content` 有变更，自动在 `coll` 集合中插入历史记录。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `did` | `ObjectId` | — | 讨论 ID |
| `$set` | `Partial<DiscussionDoc>` | — | 要更新的字段 |
| **返回值** | `Promise<DiscussionDoc>` | | |

#### `del(domainId: string, did: ObjectId): Promise<void>`

删除讨论及所有关联的回复、状态和历史记录。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `did` | `ObjectId` | — | 讨论 ID |
| **返回值** | `Promise<void>` | | |

#### `inc(domainId: string, did: ObjectId, key: NumberKeys<DiscussionDoc>, value: number): Promise<DiscussionDoc | null>`

原子性递增讨论上的数字字段（如 `views`）。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `did` | `ObjectId` | — | 讨论 ID |
| `key` | `NumberKeys<DiscussionDoc>` | — | 要递增的字段名 |
| `value` | `number` | — | 递增量 |
| **返回值** | `Promise<DiscussionDoc \| null>` | | |

#### `getMulti(domainId: string, query?: Filter<DiscussionDoc>, projection?: Field[]): FindCursor<DiscussionDoc>`

返回匹配查询的讨论游标，按 `pin` 降序然后 `docId` 降序排列。默认为 `PROJECTION_LIST`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `query` | `Filter<DiscussionDoc>` | — | 过滤条件 |
| `projection` | `Field[]` | `PROJECTION_LIST` | 返回字段列表 |
| **返回值** | `FindCursor<DiscussionDoc>` | | |

#### `count(domainId: string, query: Filter<DiscussionDoc>): Promise<number>`

返回匹配给定查询的讨论数量。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `query` | `Filter<DiscussionDoc>` | — | 过滤条件 |
| **返回值** | `Promise<number>` | | |

### 回复 CRUD

#### `addReply(domainId: string, did: ObjectId, owner: number, content: string, ip: string): Promise<ObjectId>`

为讨论添加回复。原子性递增 `nReply` 并更新父讨论的 `updateAt`。返回新回复 ID。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `did` | `ObjectId` | — | 讨论 ID |
| `owner` | `number` | — | 回复者 UID |
| `content` | `string` | — | 回复内容 |
| `ip` | `string` | — | 回复者 IP 地址 |
| **返回值** | `Promise<ObjectId>` | | 新回复 ID |

#### `getReply(domainId: string, drid: ObjectId): Promise<DiscussionReplyDoc | null>`

按 ID 获取单个回复。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `drid` | `ObjectId` | — | 回复 ID |
| **返回值** | `Promise<DiscussionReplyDoc \| null>` | | |

#### `editReply(domainId: string, drid: ObjectId, content: string, uid: number, ip: string): Promise<DiscussionReplyDoc | null>`

更新回复内容。自动插入历史记录并设置 `edited: true`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `drid` | `ObjectId` | — | 回复 ID |
| `content` | `string` | — | 新内容 |
| `uid` | `number` | — | 编辑者 UID |
| `ip` | `string` | — | 编辑者 IP 地址 |
| **返回值** | `Promise<DiscussionReplyDoc \| null>` | | |

#### `delReply(domainId: string, drid: ObjectId): Promise<void>`

删除回复及所有尾隔回复和历史记录。原子性递减父讨论的 `nReply`。回复不存在时抛出 `DocumentNotFoundError`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `drid` | `ObjectId` | — | 回复 ID |
| **返回值** | `Promise<void>` | | |

#### `getMultiReply(domainId: string, did: ObjectId): FindCursor<DiscussionReplyDoc>`

返回讨论的回复游标，按 `_id` 降序排列。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `did` | `ObjectId` | — | 讨论 ID |
| **返回值** | `FindCursor<DiscussionReplyDoc>` | | |

#### `getListReply(domainId: string, did: ObjectId): Promise<DiscussionReplyDoc[]>`

以数组形式返回讨论的所有回复（`getMultiReply` 的便捷封装）。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `did` | `ObjectId` | — | 讨论 ID |
| **返回值** | `Promise<DiscussionReplyDoc[]>` | | |

### 尾隔回复

尾隔回复是嵌套在顶级回复中的二级回复，存储在 `DiscussionReplyDoc` 的 `reply` 数组字段中。

#### `addTailReply(domainId: string, drid: ObjectId, owner: number, content: string, ip: string): Promise<[DiscussionReplyDoc, ObjectId]>`

为顶级回复添加嵌套回复。同时更新父讨论的 `updateAt`。返回更新后的父回复文档和新尾隔回复 ID。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `drid` | `ObjectId` | — | 父回复 ID |
| `owner` | `number` | — | 回复者 UID |
| `content` | `string` | — | 回复内容 |
| `ip` | `string` | — | 回复者 IP 地址 |
| **返回值** | `Promise<[DiscussionReplyDoc, ObjectId]>` | | 父回复文档和新尾隔回复 ID |

```typescript
// 向回复添加尾隔回复（二级嵌套）
const [updatedReply, tailReplyId] = await DiscussionModel.addTailReply(
  'system',                          // domainId
  replyId,                           // drid (父回复 ID)
  12345,                             // owner
  '感谢解答，非常清楚！',             // content
  '127.0.0.1',                       // ip
);
console.log('新尾隔回复 ID:', tailReplyId);
```

#### `getTailReply(domainId: string, drid: ObjectId, drrid: ObjectId): Promise<[DiscussionReplyDoc, DiscussionTailReplyDoc] | [null, null]>`

获取父回复中的指定尾隔回复。未找到时返回 `[null, null]`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `drid` | `ObjectId` | — | 父回复 ID |
| `drrid` | `ObjectId` | — | 尾隔回复 ID |
| **返回值** | `Promise<[DiscussionReplyDoc, DiscussionTailReplyDoc] \| [null, null]>` | | |

#### `editTailReply(domainId: string, drid: ObjectId, drrid: ObjectId, content: string, uid: number, ip: string): Promise<DiscussionTailReplyDoc>`

更新尾隔回复内容。自动插入历史记录并设置 `edited: true`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `drid` | `ObjectId` | — | 父回复 ID |
| `drrid` | `ObjectId` | — | 尾隔回复 ID |
| `content` | `string` | — | 新内容 |
| `uid` | `number` | — | 编辑者 UID |
| `ip` | `string` | — | 编辑者 IP 地址 |
| **返回值** | `Promise<DiscussionTailReplyDoc>` | | |

#### `delTailReply(domainId: string, drid: ObjectId, drrid: ObjectId): Promise<[void, void]>`

删除尾隔回复及其关联的历史记录。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `drid` | `ObjectId` | — | 父回复 ID |
| `drrid` | `ObjectId` | — | 尾隔回复 ID |
| **返回值** | `Promise<[void, void]>` | | |

### 表情回应

#### `react(domainId: string, docType: keyof DocType, did: ObjectId, id: string, uid: number, reverse?: boolean): Promise<[any, any]>`

切换用户对讨论或回复的表情回应（`id`）。如果 `reverse` 为 true，则移除回应。返回 `[updatedDoc, statusDoc]`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `keyof DocType` | — | 文档类型 |
| `did` | `ObjectId` | — | 讨论/回复 ID |
| `id` | `string` | — | emoji ID |
| `uid` | `number` | — | 用户 ID |
| `reverse` | `boolean` | `false` | 为 `true` 时移除回应 |
| **返回值** | `Promise<[any, any]>` | | `[updatedDoc, statusDoc]` |

```typescript
// 对讨论点赞（emoji ID "like"）
const [doc, status] = await DiscussionModel.react(
  'system',                          // domainId
  21,                                // docType (TYPE_DISCUSSION)
  discussionId,                      // did
  'like',                            // id (emoji ID)
  12345,                             // uid
);

// 取消点赞
await DiscussionModel.react(
  'system',
  21,
  discussionId,
  'like',
  12345,
  true,                              // reverse = true → 移除
);
```

#### `getReaction(domainId: string, docType: keyof DocType, did: ObjectId, uid: number): Promise<Record<string, number>>`

返回用户对文档的回应状态，以 emoji ID 到值的映射返回。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `keyof DocType` | — | 文档类型 |
| `did` | `ObjectId` | — | 文档 ID |
| `uid` | `number` | — | 用户 ID |
| **返回值** | `Promise<Record<string, number>>` | | emoji ID → 值的映射 |

### 历史

#### `getHistory(domainId: string, docId: ObjectId, query?: Filter<DiscussionHistoryDoc>, projection?: (keyof DiscussionHistoryDoc)[]): Promise<DiscussionHistoryDoc[]>`

返回讨论或回复的编辑历史记录，按 `time` 降序排列。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docId` | `ObjectId` | — | 讨论/回复 ID |
| `query` | `Filter<DiscussionHistoryDoc>` | — | 过滤条件 |
| `projection` | `(keyof DiscussionHistoryDoc)[]` | — | 返回字段列表 |
| **返回值** | `Promise<DiscussionHistoryDoc[]>` | | |

### 用户状态

#### `setStar(domainId: string, did: ObjectId, uid: number, star: boolean): Promise<void>`

设置或清除用户对讨论的星标。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `did` | `ObjectId` | — | 讨论 ID |
| `uid` | `number` | — | 用户 ID |
| `star` | `boolean` | — | `true` 星标，`false` 取消 |
| **返回值** | `Promise<void>` | | |

#### `getStatus(domainId: string, did: ObjectId, uid: number): Promise<any>`

获取用户对讨论的状态记录（包括星标、回应等）。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `did` | `ObjectId` | — | 讨论 ID |
| `uid` | `number` | — | 用户 ID |
| **返回值** | `Promise<any>` | | |

#### `setStatus(domainId: string, did: ObjectId, uid: number, $set: any): Promise<void>`

覆盖用户对讨论的状态字段。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `did` | `ObjectId` | — | 讨论 ID |
| `uid` | `number` | — | 用户 ID |
| `$set` | `any` | — | 要设置的状态字段 |
| **返回值** | `Promise<void>` | | |

### 节点（分类）

讨论节点作为顶层分类，用于组织讨论。

#### `addNode(domainId: string, _id: string, category: string, args?: any): Promise<any>`

创建具有指定 ID 和分类名称的讨论节点。可选 `args` 用于附加字段。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `_id` | `string` | — | 节点 ID |
| `category` | `string` | — | 分类名称 |
| `args` | `any` | — | 附加字段 |
| **返回值** | `Promise<any>` | | |

#### `getNode(domainId: string, _id: string): Promise<any>`

按字符串 ID 获取单个讨论节点。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `_id` | `string` | — | 节点 ID |
| **返回值** | `Promise<any>` | | |

#### `getNodes(domainId: string): Promise<any[]>`

以数组形式返回域的所有讨论节点。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| **返回值** | `Promise<any[]>` | | |

#### `flushNodes(domainId: string): Promise<any>`

删除域的所有讨论节点。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| **返回值** | `Promise<any>` | | |

### 虚拟节点（父实体）

虚拟节点解析讨论所附属的父实体（题目、比赛、训练计划或讨论节点）。

#### `getVnode(domainId: string, type: number, id: string, uid?: number): Promise<any>`

解析讨论的父实体。处理题目（按数字 ID）、比赛/训练计划（按 ObjectId）和讨论节点（按字符串 ID）。可选地为指定用户填充 `attend` 状态。未找到时抛出 `DiscussionNodeNotFoundError`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `type` | `number` | — | 父实体类型 |
| `id` | `string` | — | 父实体 ID |
| `uid` | `number` | — | 用于填充 `attend` 状态的用户 ID |
| **返回值** | `Promise<any>` | | |

#### `getListVnodes(domainId: string, ddocs: any, getHidden?: boolean, assign?: string[]): Promise<Record<number, Record<string, any>>>`

批量解析多个讨论的父实体。返回嵌套映射 `{ [parentType]: { [parentId]: vnode } }`。默认过滤隐藏节点和受作业组限制的项目。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `ddocs` | `any` | — | 讨论文档数组 |
| `getHidden` | `boolean` | `false` | 是否包含隐藏节点 |
| `assign` | `string[]` | — | 作业组限制过滤 |
| **返回值** | `Promise<Record<number, Record<string, any>>>` | | |

#### `checkVNodeVisibility(type: number, vnode: any, user: User): boolean`

用户被允许查看父实体时返回 `true`。检查隐藏题目可见性和比赛/训练计划的作业组限制。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `type` | `number` | — | 父实体类型 |
| `vnode` | `any` | — | 虚拟节点对象 |
| `user` | `User` | — | 当前用户 |
| **返回值** | `boolean` | | 是否可见 |

---

## 属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `coll` | `Collection<DiscussionHistoryDoc>` | MongoDB `discussion.history` 集合 —— 存储编辑历史记录 |

---

## 备注

- 讨论是文档类型模型（`TYPE_DISCUSSION = 21`）。CRUD 和状态操作委托给共享的 `document` 模块。
- 模型支持三级嵌套：**讨论** → **回复** → **尾隔回复**。
- 所有内容变更（讨论编辑、回复编辑、尾隔回复编辑）会自动在 `discussion.history` 集合中插入历史记录。
- `add()` 触发总线事件（`discussion/before-add`、`discussion/add`），使插件可以拦截或响应讨论创建。
- `apply(ctx)` 注册生命周期钩子：题目删除时级联删除关联讨论，题目编辑时同步 `hidden` 状态到关联讨论。

### DocumentModel

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/model/document.ts

```ts
import { DocumentModel } from 'hydrooj'
```

# DocumentModel

通用文档存储模型，提供跨所有文档类型（题目、比赛、训练计划、讨论等）的类型化 CRUD、子文档操作和每用户状态追踪。

DocumentModel 是导出函数的普通模块（非类）。所有函数直接调用。它是高级模型（ProblemModel、ContestModel、TrainingModel、DiscussionModel）委托的基础数据访问层。

---

## 类型导出

### DocType

将类型常量映射到对应的文档接口：

```typescript
interface DocType {
    [TYPE_PROBLEM]: ProblemDoc;
    [TYPE_PROBLEM_SOLUTION]: any;
    [TYPE_PROBLEM_LIST]: any;
    [TYPE_DISCUSSION_NODE]: any;
    [TYPE_DISCUSSION]: DiscussionDoc;
    [TYPE_DISCUSSION_REPLY]: DiscussionReplyDoc;
    [TYPE_CONTEST]: Tdoc;
    [TYPE_CONTEST_PRINT]: ContestPrintDoc;
    [TYPE_CONTEST_CLARIFICATION]: ContestClarificationDoc;
    [TYPE_TRAINING]: TrainingDoc;
}
```

### DocStatusType

将类型常量映射到状态文档接口（如 `TYPE_PROBLEM` 对应 `ProblemStatusDoc`）。

---

## 常量

### DocType 常量

| 常量 | 值 | 说明 |
|------|-----|------|
| `TYPE_PROBLEM` | `10` | 题目文档 |
| `TYPE_PROBLEM_SOLUTION` | `11` | 题解题 |
| `TYPE_PROBLEM_LIST` | `12` | 题单 / 作业 |
| `TYPE_DISCUSSION_NODE` | `20` | 讨论分类节点 |
| `TYPE_DISCUSSION` | `21` | 讨论帖 |
| `TYPE_DISCUSSION_REPLY` | `22` | 讨论回复 |
| `TYPE_CONTEST` | `30` | 比赛文档 |
| `TYPE_CONTEST_CLARIFICATION` | `31` | 比赛答疑请求 |
| `TYPE_CONTEST_PRINT` | `32` | 比赛打印任务 |
| `TYPE_TRAINING` | `40` | 训练计划 |

---

## 方法

### 文档 CRUD

#### `add(domainId: string, content: string, owner: number, docType: number, docId?: ObjectId, parentType?: number, parentId?: ObjectId | number | string, args?: any): Promise<ObjectId>`

插入新文档。如果提供了 `docId` 则返回 `docId`，否则返回生成的 `ObjectId`。插入前触发 `document/add` 总线事件。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `content` | `string` | — | 文档内容 |
| `owner` | `number` | — | 所有者 UID |
| `docType` | `number` | — | 文档类型常量 |
| `docId` | `ObjectId` | — | 指定文档 ID（可选） |
| `parentType` | `number` | — | 父文档类型 |
| `parentId` | `ObjectId \| number \| string` | — | 父文档 ID |
| `args` | `any` | — | 附加字段 |
| **返回值** | `Promise<ObjectId>` | | 新文档 ID |

#### `get(domainId: string, docType: number, docId: ObjectId, projection?: any): Promise<Doc | null>`

按组合键 `(domainId, docType, docId)` 获取单个文档。未找到时返回 `null`。接受可选字段投影。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `number` | — | 文档类型常量 |
| `docId` | `ObjectId` | — | 文档 ID |
| `projection` | `any` | — | 字段投影 |
| **返回值** | `Promise<Doc \| null>` | | |

#### `getMulti(domainId: string, docType: number, query?: Filter<Doc>, projection?: any): FindCursor<Doc>`

返回匹配查询的多文档 `FindCursor`。接受可选过滤器和投影。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `number` | — | 文档类型常量 |
| `query` | `Filter<Doc>` | — | 过滤条件 |
| `projection` | `any` | — | 字段投影 |
| **返回值** | `FindCursor<Doc>` | | |

#### `set(domainId: string, docType: number, docId: ObjectId, $set?: any, $unset?: any, $push?: any): Promise<Doc>`

使用 `$set`、`$unset` 和/或 `$push` 操作符原子性更新文档。返回更新后的文档。更新前触发 `document/set` 总线事件。文档不存在时执行 upsert。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `number` | — | 文档类型常量 |
| `docId` | `ObjectId` | — | 文档 ID |
| `$set` | `any` | — | 要设置的字段 |
| `$unset` | `any` | — | 要移除的字段 |
| `$push` | `any` | — | 要推入数组的元素 |
| **返回值** | `Promise<Doc>` | | 更新后的文档 |

#### `inc(domainId: string, docType: number, docId: ObjectId, key: string, value: number): Promise<Doc | null>`

原子性递增数值字段 `value`。返回更新后的文档（文档不存在时返回 `null`）。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `number` | — | 文档类型常量 |
| `docId` | `ObjectId` | — | 文档 ID |
| `key` | `string` | — | 要递增的字段名 |
| `value` | `number` | — | 递增量 |
| **返回值** | `Promise<Doc \| null>` | | 更新后的文档（文档不存在时返回 `null`） |

#### `incAndSet(domainId: string, docType: number, docId: ObjectId, key: string, value: number, args: any): Promise<Doc | null>`

在单次操作中原子性递增数值字段并设置附加字段。返回更新后的文档（文档不存在时返回 `null`）。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `number` | — | 文档类型常量 |
| `docId` | `ObjectId` | — | 文档 ID |
| `key` | `string` | — | 要递增的字段名 |
| `value` | `number` | — | 递增量 |
| `args` | `any` | — | 附加设置字段 |
| **返回值** | `Promise<Doc \| null>` | | 更新后的文档（文档不存在时返回 `null`） |

#### `count(domainId: string, docType: number, query?: Filter<Doc>): Promise<number>`

统计匹配过滤器的文档数量。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `number` | — | 文档类型常量 |
| `query` | `Filter<Doc>` | — | 过滤条件 |
| **返回值** | `Promise<number>` | | 匹配的文档数量 |

#### `deleteOne(domainId: string, docType: number, docId: ObjectId): Promise<[DeleteResult, DeleteResult]>`

删除单个文档及其关联的状态记录。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `number` | — | 文档类型常量 |
| `docId` | `ObjectId` | — | 文档 ID |
| **返回值** | `Promise<[DeleteResult, DeleteResult]>` | | 文档删除结果和状态删除结果 |

#### `deleteMulti(domainId: string, docType: number, query?: Filter<Doc>): Promise<DeleteResult>`

删除匹配过滤器的多个文档。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `number` | — | 文档类型常量 |
| `query` | `Filter<Doc>` | — | 过滤条件 |
| **返回值** | `Promise<DeleteResult>` | | |

### 子文档操作

这些方法操作文档内的数组字段（如回复、标签）。

#### `push(domainId: string, docType: number, docId: ObjectId, key: string, ...): Promise<[Doc, ObjectId]>` *（两个重载）*

**对象形式**: `push(domainId, docType, docId, key, value)` —— 将对象推入数组字段。
**内容形式**: `push(domainId, docType, docId, key, content, owner, args?)` —— 推入带自动生成 `_id` 的新子文档。
返回 `[updatedDoc, subId]`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `number` | — | 文档类型常量 |
| `docId` | `ObjectId` | — | 文档 ID |
| `key` | `string` | — | 数组字段名 |
| `value` | `any` | — | 要推入的对象（对象形式） |
| `content` | `string` | — | 子文档内容（内容形式） |
| `owner` | `number` | — | 子文档所有者 UID（内容形式） |
| `args` | `any` | — | 附加字段（内容形式） |
| **返回值** | `Promise<[Doc, ObjectId]>` | | 更新后的文档和子文档 ID |

#### `pull(domainId: string, docType: number, docId: ObjectId, setKey: string, contents: any): Promise<Doc>`

从数组字段中移除匹配给定过滤器的子文档。返回更新后的文档。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `number` | — | 文档类型常量 |
| `docId` | `ObjectId` | — | 文档 ID |
| `setKey` | `string` | — | 数组字段名 |
| `contents` | `any` | — | 移除过滤器 |
| **返回值** | `Promise<Doc>` | | 更新后的文档 |

#### `getSub(domainId: string, docType: number, docId: ObjectId, key: string, subId: ObjectId): Promise<[Doc | null, SubDoc | null]>`

从数组字段中按 `_id` 获取特定子文档。返回 `[parentDoc, subDoc]`，未找到时返回 `[null, null]`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `number` | — | 文档类型常量 |
| `docId` | `ObjectId` | — | 文档 ID |
| `key` | `string` | — | 数组字段名 |
| `subId` | `ObjectId` | — | 子文档 ID |
| **返回值** | `Promise<[Doc \| null, SubDoc \| null]>` | | |

#### `setSub(domainId: string, docType: number, docId: ObjectId, key: string, subId: ObjectId, args: any): Promise<Doc>`

更新按 `_id` 标识的特定子文档字段。使用位置 `$` 操作符。返回更新后的父文档。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `number` | — | 文档类型常量 |
| `docId` | `ObjectId` | — | 文档 ID |
| `key` | `string` | — | 数组字段名 |
| `subId` | `ObjectId` | — | 子文档 ID |
| `args` | `any` | — | 要设置的字段 |
| **返回值** | `Promise<Doc>` | | 更新后的父文档 |

#### `deleteSub(domainId: string, docType: number, docId: ObjectId, key: string, subId: ObjectId | ObjectId[]): Promise<Doc>`

从数组字段中按 `_id` 移除一个或多个子文档。接受单个 ID 或 ID 数组。返回更新后的文档。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `number` | — | 文档类型常量 |
| `docId` | `ObjectId` | — | 文档 ID |
| `key` | `string` | — | 数组字段名 |
| `subId` | `ObjectId \| ObjectId[]` | — | 子文档 ID（单个或数组） |
| **返回值** | `Promise<Doc>` | | 更新后的文档 |

#### `addToSet(domainId: string, docType: number, docId: ObjectId, setKey: string, content: string): Promise<Doc>`

仅在数组字段中不存在时添加字符串值（通过 `$addToSet` 去重）。返回更新后的文档。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `number` | — | 文档类型常量 |
| `docId` | `ObjectId` | — | 文档 ID |
| `setKey` | `string` | — | 数组字段名 |
| `content` | `string` | — | 要添加的值 |
| **返回值** | `Promise<Doc>` | | 更新后的文档 |

### 状态 CRUD

状态记录追踪每用户状态（分数、提交、报名），以 `(domainId, docType, docId, uid)` 为键。

#### `getStatus(domainId: string, docType: number, docId: ObjectId, uid: number): Promise<StatusDoc | null>`

获取单个状态记录。未找到时返回 `null`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `number` | — | 文档类型常量 |
| `docId` | `ObjectId` | — | 文档 ID |
| `uid` | `number` | — | 用户 ID |
| **返回值** | `Promise<StatusDoc \| null>` | | |

#### `getMultiStatus(domainId: string, docType: number, args: any): FindCursor<StatusDoc>`

返回匹配过滤器的状态记录 `FindCursor`（限定域范围）。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `number` | — | 文档类型常量 |
| `args` | `any` | — | 过滤条件 |
| **返回值** | `FindCursor<StatusDoc>` | | |

#### `getMultiStatusWithoutDomain(docType: number, args: any): FindCursor<StatusDoc>`

返回匹配过滤器的状态记录 `FindCursor`（跨域）。用于系统级查询。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `docType` | `number` | — | 文档类型常量 |
| `args` | `any` | — | 过滤条件 |
| **返回值** | `FindCursor<StatusDoc>` | | |

#### `setStatus(domainId: string, docType: number, docId: ObjectId, uid: number, args: any, returnDocument?: 'before' | 'after'): Promise<StatusDoc>`

设置状态记录字段，不存在时 upsert。`returnDocument` 控制返回的文档是更新 `'before'` 还是 `'after'`（默认 `'after'`）。返回 `'before'` 时使用 `readConcern: 'majority'`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `number` | — | 文档类型常量 |
| `docId` | `ObjectId` | — | 文档 ID |
| `uid` | `number` | — | 用户 ID |
| `args` | `any` | — | 要设置的字段 |
| `returnDocument` | `'before' \| 'after'` | `'after'` | 返回更新前还是更新后的文档 |
| **返回值** | `Promise<StatusDoc>` | | |

```typescript
// 设置用户对题目的状态
const status = await document.setStatus(
  'system',                          // domainId
  document.TYPE_PROBLEM,             // docType
  problemDocId,                      // docId
  12345,                             // uid
  { score: 100, accept: true },      // args
);

// 获取更新前的状态（用于检测变更）
const before = await document.setStatus(
  'system',
  document.TYPE_PROBLEM,
  problemDocId,
  12345,
  { star: true },
  'before',                          // returnDocument
);
```

#### `setMultiStatus(domainId: string, docType: number, query: any, args: any): Promise<void>`

批量更新匹配过滤器的多个状态记录。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `number` | — | 文档类型常量 |
| `query` | `any` | — | 过滤条件 |
| `args` | `any` | — | 要设置的字段 |
| **返回值** | `Promise<void>` | | |

#### `countStatus(domainId: string, docType: number, query?: any): Promise<number>`

统计匹配过滤器的状态记录数量。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `number` | — | 文档类型常量 |
| `query` | `any` | — | 过滤条件 |
| **返回值** | `Promise<number>` | | |

#### `deleteMultiStatus(domainId: string, docType: number, query?: any): Promise<void>`

删除匹配过滤器的状态记录。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `number` | — | 文档类型常量 |
| `query` | `any` | — | 过滤条件 |
| **返回值** | `Promise<void>` | | |

#### `incStatus(domainId: string, docType: number, docId: ObjectId, uid: number, key: string, value: number): Promise<StatusDoc>`

原子性递增状态记录上的数值字段。不存在时 upsert。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `number` | — | 文档类型常量 |
| `docId` | `ObjectId` | — | 文档 ID |
| `uid` | `number` | — | 用户 ID |
| `key` | `string` | — | 要递增的字段名 |
| `value` | `number` | — | 递增量 |
| **返回值** | `Promise<StatusDoc>` | | |

#### `setStatusIfCondition(domainId: string, docType: number, docId: ObjectId, uid: number, filter: any, args?: any, returnDocument?: 'before' | 'after'): Promise<StatusDoc | false>`

条件性设置状态字段 —— 仅在附加 `filter` 匹配时更新。出错时返回 `false`（捕获异常）。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `number` | — | 文档类型常量 |
| `docId` | `ObjectId` | — | 文档 ID |
| `uid` | `number` | — | 用户 ID |
| `filter` | `any` | — | 额外过滤条件 |
| `args` | `any` | — | 要设置的字段 |
| `returnDocument` | `'before' \| 'after'` | `'after'` | 返回更新前还是更新后的文档 |
| **返回值** | `Promise<StatusDoc \| false>` | | 条件不满足时返回 `false` |

#### `setIfNotStatus(domainId: string, docType: number, docId: ObjectId, uid: number, key: string, value: any, ifNot: any, args: any, returnDocument?: 'before' | 'after'): Promise<StatusDoc | false>`

仅当字段当前值不为 `ifNot` 时设置为 `value`。委托 `setStatusIfCondition` 使用 `$ne` 过滤器。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `number` | — | 文档类型常量 |
| `docId` | `ObjectId` | — | 文档 ID |
| `uid` | `number` | — | 用户 ID |
| `key` | `string` | — | 字段名 |
| `value` | `any` | — | 目标值 |
| `ifNot` | `any` | — | 排除的当前值 |
| `args` | `any` | — | 附加设置字段 |
| `returnDocument` | `'before' \| 'after'` | `'after'` | 返回更新前还是更新后的文档 |
| **返回值** | `Promise<StatusDoc \| false>` | | 条件不满足时返回 `false` |

#### `cappedIncStatus(domainId: string, docType: number, docId: ObjectId, uid: number, key: string, value: number, minValue?: number, maxValue?: number, setPayload?: any): Promise<StatusDoc>`

原子性递增数值字段但限制在 `[minValue, maxValue]` 范围内（默认 `[-1, 1]`）。字段将超出上限时递增被静默跳过。可选择在同一操作中设置附加字段。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `number` | — | 文档类型常量 |
| `docId` | `ObjectId` | — | 文档 ID |
| `uid` | `number` | — | 用户 ID |
| `key` | `string` | — | 要递增的字段名 |
| `value` | `number` | — | 递增量 |
| `minValue` | `number` | `-1` | 最小值 |
| `maxValue` | `number` | `1` | 最大值 |
| `setPayload` | `any` | — | 同步设置的附加字段 |
| **返回值** | `Promise<StatusDoc>` | | |

```typescript
// 比赛签到：attendance 字段从 -1 → 0 → 1，上限为 1
const status = await document.cappedIncStatus(
  'system',                          // domainId
  document.TYPE_CONTEST,             // docType
  contestDocId,                      // docId
  12345,                             // uid
  'attendance',                      // key
  1,                                 // value
  -1,                                // minValue
  1,                                 // maxValue
  { attendAt: new Date() },          // setPayload
);
```

### 基于修订号的状态操作

这些方法在状态记录上维护 `rev`（修订计数器）用于乐观并发控制。

#### `revInitStatus(domainId: string, docType: number, docId: ObjectId, uid: number): Promise<StatusDoc>`

初始化或递增状态记录上的 `rev` 计数器。不存在时 upsert。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `number` | — | 文档类型常量 |
| `docId` | `ObjectId` | — | 文档 ID |
| `uid` | `number` | — | 用户 ID |
| **返回值** | `Promise<StatusDoc>` | | |

#### `revPushStatus(domainId: string, docType: number, docId: ObjectId, uid: number, key: string, value: any, id?: ObjectId): Promise<StatusDoc>`

将值推入带修订追踪的状态数组字段。如果已存在匹配 `id` 的元素，则替换而非推入。两种情况均递增 `rev`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `number` | — | 文档类型常量 |
| `docId` | `ObjectId` | — | 文档 ID |
| `uid` | `number` | — | 用户 ID |
| `key` | `string` | — | 数组字段名 |
| `value` | `any` | — | 要推入/替换的值 |
| `id` | `string` | `'_id'` | 子元素 ID 字段名（匹配则替换） |
| **返回值** | `Promise<StatusDoc>` | | |

```typescript
// 比赛排行榜：推入每题提交详情，带修订追踪
const status = await document.revPushStatus(
  'system',                          // domainId
  document.TYPE_CONTEST,             // docType
  contestDocId,                      // docId
  12345,                             // uid
  'detail',                          // key
  { pid: problemId, score: 100 },    // value
  detailId,                          // id（如果匹配则替换，否则推入）
);
```

#### `revSetStatus(domainId: string, docType: number, docId: ObjectId, uid: number, rev: number, args: any): Promise<StatusDoc>`

仅当当前 `rev` 匹配提供的值时设置状态字段，然后递增 `rev`。用于乐观锁。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docType` | `number` | — | 文档类型常量 |
| `docId` | `ObjectId` | — | 文档 ID |
| `uid` | `number` | — | 用户 ID |
| `rev` | `number` | — | 期望的当前修订号 |
| `args` | `any` | — | 要设置的字段 |
| **返回值** | `Promise<StatusDoc>` | | |

---

## 属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `coll` | `Collection<Doc>` | MongoDB `document` 集合 —— 存储所有文档记录 |
| `collStatus` | `Collection<StatusDoc>` | MongoDB `document.status` 集合 —— 存储每用户状态记录 |

---

## 备注

- `apply(ctx)` 注册数据库索引和 `domain/delete` 清理处理器。在应用启动时调用一次。
- 插入前触发 `document/add` 总线事件；更新前触发 `document/set` 总线事件。
- `push` 方法有两个重载：对象形式和内容形式。

### DomainModel

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/model/domain.ts

```ts
import { DomainModel } from 'hydrooj'
```

# DomainModel

域（租户/组织）模型，提供域 CRUD、用户角色成员管理、角色权限管理和加入设置。

`DomainModel` 是纯静态类。所有方法均通过类本身调用（如 `DomainModel.get(...)`）。

---

## 类型导出

### `DomainDoc`

定义在 `packages/hydrooj/src/interface.ts`：

```typescript
interface DomainDoc extends Record<string, any> {
    _id: string;          // 域 ID
    owner: number;        // 所有者 UID
    roles: Dictionary<string>;  // 角色名 → 权限 bigint 字符串
    avatar: string;       // 域头像 URL
    bulletin: string;     // 域公告文本
    _join?: any;          // 加入设置（method, role, expire, code）
    host?: string[];      // 自定义 host 头
}
```

注意：`DomainDoc` 继承 `Record<string, any>`，因此允许任意附加字段。

---

## 常量

### 加入方式

| 常量 | 值 | 说明 |
|------|-----|------|
| `JOIN_METHOD_NONE` | `0` | 不允许任何用户加入此域 |
| `JOIN_METHOD_ALL` | `1` | 允许任何用户加入此域 |
| `JOIN_METHOD_CODE` | `2` | 允许任何用户通过邀请码加入 |

### 加入有效期

| 常量 | 值 | 说明 |
|------|-----|------|
| `JOIN_EXPIRATION_KEEP_CURRENT` | `0` | 保持当前有效期 |
| `JOIN_EXPIRATION_UNLIMITED` | `-1` | 永不过期 |
| _(数字键)_ | `3`, `24`, `72`, `168`, `720` | 3 小时 / 1 天 / 3 天 / 1 周 / 1 个月 |

---

## 方法

### 域 CRUD

#### `add(domainId: string, owner: number, name: string, bulletin: string): Promise<string>`

创建新域，指定所有者、名称和公告；将所有者设为 `root` 角色。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `owner` | `number` | — | 所有者 UID |
| `name` | `string` | — | 域名称 |
| `bulletin` | `string` | — | 域公告文本 |
| **返回值** | `Promise<string>` | | |

#### `get(domainId: string): Promise<DomainDoc | null>`

按 ID 获取域（对 `lower` 字段不区分大小写查找），带 LRU 缓存。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| **返回值** | `Promise<DomainDoc \| null>` | | |

#### `getByHost(host: string): Promise<DomainDoc | null>`

按 `host` 字段获取域，带 LRU 缓存（也缓存 `null` 未命中）。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `host` | `string` | — | 自定义 host 头值 |
| **返回值** | `Promise<DomainDoc \| null>` | | |

#### `getMulti(query?: Filter<DomainDoc>): Cursor<DomainDoc>`

获取匹配过滤器的域游标。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `query` | `Filter<DomainDoc>` | — | MongoDB 过滤条件 |
| **返回值** | `Cursor<DomainDoc>` | | |

#### `getList(domainIds: string[]): Promise<Record<string, DomainDoc | null>>`

以域 ID 为键的字典形式获取多个域（内部使用 `get`，遵循缓存）。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainIds` | `string[]` | — | 域 ID 数组 |
| **返回值** | `Promise<Record<string, DomainDoc \| null>>` | | |

#### `edit(domainId: string, $set: Partial<DomainDoc>): Promise<DomainDoc | null>`

按 ID 更新城字段；广播缓存失效。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `$set` | `Partial<DomainDoc>` | — | 要更新的字段 |
| **返回值** | `Promise<DomainDoc \| null>` | | |

#### `inc(domainId: string, field: NumberKeys<DomainDoc>, n: number): Promise<number | null>`

原子性递增域上的数值字段；广播缓存失效。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `field` | `NumberKeys<DomainDoc>` | — | 要递增的数值字段名 |
| `n` | `number` | — | 递增量 |
| **返回值** | `Promise<number \| null>` | | |

#### `getPrefixSearch(prefix: string, limit?: number): Promise<DomainDoc[]>`

按 ID 或名称前缀搜索域（正则，不区分大小写）；默认限制 50。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `prefix` | `string` | — | 搜索前缀 |
| `limit` | `number` | `50` | 返回数量上限 |
| **返回值** | `Promise<DomainDoc[]>` | | |

#### `del(domainId: string): Promise<void>`

删除域及所有用户关联；触发 `domain/delete` 事件并使缓存失效。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| **返回值** | `Promise<void>` | | |

### 域用户管理

#### `countUser(domainId: string, role?: string): Promise<number>`

统计域中的已加入用户，可选按角色过滤。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `role` | `string` | — | 可选角色过滤 |
| **返回值** | `Promise<number>` | | |

#### `getDomainUser(domainId: string, udoc: { _id: number, priv: number }): Promise<any>`

获取域用户记录，包含有效角色和计算后的 `perm`（考虑用户特权如 `PRIV_MANAGE_ALL_DOMAIN`）。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `udoc` | `{ _id: number, priv: number }` | — | 用户文档（至少含 `_id` 和 `priv`） |
| **返回值** | `Promise<any>` | | |

#### `getDomainUserMulti(domainId: string, uids: number[]): Cursor<any>`

按 UID 获取多个域用户记录的游标。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `uids` | `number[]` | — | 用户 ID 数组 |
| **返回值** | `Cursor<any>` | | |

#### `getDictUserByDomainId(uid: number): Promise<Record<string, any>>`

获取用户的所有已加入域用户记录，以 `domainId` 为键。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `uid` | `number` | — | 用户 ID |
| **返回值** | `Promise<Record<string, any>>` | | |

#### `setUserRole(domainId: string, uid: MaybeArray<number>, role: string, autojoin?: boolean): Promise<any>`

设置域中的用户角色；支持单个或批量 UID；可选自动加入。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `uid` | `MaybeArray<number>` | — | 单个或批量用户 ID |
| `role` | `string` | — | 目标角色名 |
| `autojoin` | `boolean` | `false` | 是否自动加入域 |
| **返回值** | `Promise<any>` | | |

#### `setJoin(domainId: string, uid: MaybeArray<number>, join: boolean): Promise<void>`

设置域中用户的加入状态。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `uid` | `MaybeArray<number>` | — | 单个或批量用户 ID |
| `join` | `boolean` | — | 加入状态 |
| **返回值** | `Promise<void>` | | |

#### `setUserInDomain(domainId: string, uid: number, params: any): Promise<any>`

设置域用户记录的指定字段（upsert）。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `uid` | `number` | — | 用户 ID |
| `params` | `any` | — | 要设置的字段 |
| **返回值** | `Promise<any>` | | |

#### `updateUserInDomain(domainId: string, uid: number, update: any): Promise<any>`

对域用户记录应用任意 MongoDB 更新（upsert）。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `uid` | `number` | — | 用户 ID |
| `update` | `any` | — | MongoDB 更新操作 |
| **返回值** | `Promise<any>` | | |

#### `setMultiUserInDomain(domainId: string, query: any, params: any): Promise<any>`

批量使用 `$set` 更新匹配查询的域用户（upsert）。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `query` | `any` | — | 匹配条件 |
| `params` | `any` | — | 要设置的字段 |
| **返回值** | `Promise<any>` | | |

#### `getMultiUserInDomain(domainId: string, query?: any): Cursor<any>`

获取匹配查询的域用户游标。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `query` | `any` | — | 匹配条件 |
| **返回值** | `Cursor<any>` | | |

#### `incUserInDomain(domainId: string, uid: number, field: string, n: number = 1): Promise<any>`

对域用户记录执行读-改-写递增数值字段；返回更新后的文档。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `uid` | `number` | — | 用户 ID |
| `field` | `string` | — | 要递增的字段名 |
| `n` | `number` | `1` | 递增量 |
| **返回值** | `Promise<any>` | | |

### 角色管理

#### `getRoles(domainId: string | DomainDoc, count?: boolean): Promise<any[]>`

获取域的所有角色（内置 + 自定义），可选附带每角色的用户计数。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string \| DomainDoc` | — | 域 ID 或域文档 |
| `count` | `boolean` | `false` | 是否附带每角色用户计数 |
| **返回值** | `Promise<any[]>` | | |

#### `setRoles(domainId: string, roles: Dictionary<bigint | string>): Promise<any>`

设置多个角色及其权限（合并到已有角色中）。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `roles` | `Dictionary<bigint \| string>` | — | 角色名 → 权限映射 |
| **返回值** | `Promise<any>` | | |

#### `addRole(domainId: string, name: string, permission: bigint): Promise<any>`

添加具有指定权限的新自定义角色。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `name` | `string` | — | 角色名 |
| `permission` | `bigint` | — | 角色权限 |
| **返回值** | `Promise<any>` | | |

#### `deleteRoles(domainId: string, roles: string[]): Promise<void>`

删除角色并将所有受影响的用户重置为 `default` 角色。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `roles` | `string[]` | — | 要删除的角色名数组 |
| **返回值** | `Promise<void>` | | |

### 加入设置

#### `getJoinSettings(ddoc: DomainDoc, roles: string[]): any | null`

如果域允许加入且角色被允许，则获取加入设置；加入被禁用或已过期时返回 `null`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `ddoc` | `DomainDoc` | — | 域文档 |
| `roles` | `string[]` | — | 允许加入的角色列表 |
| **返回值** | `any \| null` | | |

---

## 属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `coll` | `Collection` | MongoDB `domain` 集合 |
| `collUser` | `Collection` | MongoDB `domain.user` 集合 |

---

## 事件

| 事件 | 参数 | 说明 |
|------|------|------|
| `domain/create` | `ddoc: DomainDoc` | 域创建时触发（DB 插入前） |
| `domain/before-get` | `query: Filter<DomainDoc>` | 域查询前触发；允许修改查询条件 |
| `domain/get` | `ddoc: DomainDoc` | 域成功获取后触发 |
| `domain/before-update` | `domainId, $set` | 域更新前触发 |
| `domain/update` | `domainId, $set, ddoc` | 域更新后触发（含更新后的文档） |
| `domain/delete` | `domainId` | 域删除后触发 |
| `domain/delete-cache` | `domainId` | 跨集群广播使域缓存失效 |

---

## 备注

- 使用 `LRUCache`，最大 1000 条目，TTL 300000ms（5 分钟）。
- 缓存键：ID 查找使用 `id::{lower}`，host 查找使用 `host::{host}`。
- 缓存通过 `domain/delete-cache` 广播（跨集群）在编辑、递增、角色变更和删除时失效。
- `getByHost` 缓存 `null` 结果（未找到 host 对应的域）。

### MessageModel

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/model/message.ts

```ts
import { MessageModel } from 'hydrooj'
```

# MessageModel

消息模型，用于发送、查询和删除用户消息及系统通知。

`MessageModel` 是纯静态类。所有方法均通过类本身调用（如 `MessageModel.send(...)`）。

---

## 类型导出

### `MessageDoc`

```typescript
interface MessageDoc {
    from: number;
    to: number | number[];
    content: string;
    flag: number;
}
```

---

## 常量

| 常量 | 值 | 说明 |
|------|-----|------|
| `FLAG_UNREAD` | `1` | 消息未读 |
| `FLAG_ALERT` | `2` | 消息为警报 |
| `FLAG_RICHTEXT` | `4` | 消息包含富文本 |
| `FLAG_INFO` | `8` | 信息性消息 |
| `FLAG_I18N` | `16` | 内容为 i18n 键 |

标志为位掩码值 —— 使用按位 OR 组合（如 `FLAG_INFO | FLAG_I18N`）。

---

## 方法

### 发送

#### `send(from: number, to: number | number[], content: string, flag?: number): Promise<BaseMessage>`

从用户 `from` 向一个或多个接收者发送消息。默认为 `FLAG_UNREAD`。广播 `user/message` 事件并递增接收者的 `unreadMsg` 计数。返回消息文档（如果 `to` 为空则不含 `_id`）。

**@ArgMethod**

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `from` | `number` | — | 发送者 UID |
| `to` | `number \| number[]` | — | 接收者 UID 或 UID 数组 |
| `content` | `string` | — | 消息内容 |
| `flag` | `number` | `FLAG_UNREAD` | 标志位掩码 |
| **返回值** | `Promise<BaseMessage>` | | 消息文档 |

#### `sendInfo(to: number, content: string): Promise<void>`

向单个用户发送临时信息/i18n 通知。组合 `FLAG_INFO | FLAG_I18N`。通过 `user/message` 广播，但**不**持久化到数据库。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `to` | `number` | — | 接收者 UID |
| `content` | `string` | — | i18n 键或消息内容 |
| **返回值** | `Promise<void>` | | |

#### `sendNotification(message: string, ...args: any[]): Promise<any[]>`

向所有具有 `PRIV_VIEW_SYSTEM_NOTIFICATION` 的用户发送翻译后的通知。`message` 通过 `app.i18n` 使用每个接收者的 `viewLang` 翻译，`args` 传递给 `format()`。消息以 `FLAG_RICHTEXT` 发送。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `message` | `string` | — | i18n 消息键 |
| `args` | `any[]` | — | 传递给 `format()` 的参数 |
| **返回值** | `Promise<any[]>` | | 每个接收者的发送结果 |

### 查询

#### `get(_id: ObjectId): Promise<MessageDoc>`

按 `_id` 获取单个消息。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `_id` | `ObjectId` | — | 消息 ID |
| **返回值** | `Promise<MessageDoc>` | | |

#### `getByUser(uid: number): Promise<MessageDoc[]>`

获取指定用户发送或接收的最多 1000 条消息，按 `_id` 降序排列（最新在前）。

**@ArgMethod**

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `uid` | `number` | — | 用户 UID |
| **返回值** | `Promise<MessageDoc[]>` | | 最多 1000 条消息 |

#### `getMany(query: Filter<MessageDoc>, sort: any, page: number, limit: number): Promise<MessageDoc[]>`

带自定义过滤和排序的分页消息列表。应用 `skip((page-1)*limit)`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `query` | `Filter<MessageDoc>` | — | MongoDB 过滤条件 |
| `sort` | `any` | — | 排序条件 |
| `page` | `number` | — | 页码（从 1 开始） |
| `limit` | `number` | — | 每页数量 |
| **返回值** | `Promise<MessageDoc[]>` | | |

#### `getMulti(uid: number): Cursor<MessageDoc>`

获取指定用户发送或接收的所有消息的 MongoDB 游标。无排序或限制 —— 调用方控制迭代。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `uid` | `number` | — | 用户 UID |
| **返回值** | `Cursor<MessageDoc>` | | |

### 删除

#### `del(_id: ObjectId): Promise<DeleteResult>`

按 `_id` 删除单个消息。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `_id` | `ObjectId` | — | 消息 ID |
| **返回值** | `Promise<DeleteResult>` | | |

### 统计

#### `count(query?: Filter<MessageDoc>): Promise<number>`

统计匹配给定过滤器的消息数量。默认为所有消息。

**@ArgMethod**

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `query` | `Filter<MessageDoc>` | — | 过滤条件 |
| **返回值** | `Promise<number>` | | |

---

## 属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `coll` | `Collection<MessageDoc>` | MongoDB `message` 集合 |

---

## 备注

- `send` 同时持久化到 MongoDB 并实时广播 `user/message`。
- `sendInfo` 是即发即弃 —— 它广播但不写入数据库。
- `sendNotification` 用于系统级公告（如维护通知）。
- `getByUser` 限制结果为 1000 条；使用 `getMulti` 进行无限制的游标迭代。
- **索引**：`{ to: 1, _id: -1 }`（按接收者查找）、`{ from: 1, _id: -1 }`（按发送者查找）。

### OauthModel

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/model/oauth.ts

```ts
import { OauthModel } from 'hydrooj'
```

# OauthModel

OAuth 提供商与账号关联模型，用于注册第三方登录提供商、查找关联账号以及管理平台到用户的映射。

与大多数模型不同，`OauthModel` 继承自 `Service`，通过 `ctx.oauth` 访问而非使用静态方法。

---

## 类型导出

### `OauthMap`

```typescript
interface OauthMap {
    platform: string;  // OAuth 平台名称（如 'github'、'google'、'mail'）
    id: string;        // 来自提供商的 openId
    uid: number;       // 目标 Hydro 用户 ID
}
```

### `OAuthProvider`

```typescript
interface OAuthProvider {
    text: string;              // 显示标签
    name: string;              // 提供商标识符
    icon?: string;             // 图标 URL 或标识符
    hidden?: boolean;          // 若为 true，不在登录界面显示
    get: (this: Handler) => Promise<void>;                         // 发起 OAuth 流程
    callback: (this: Handler, args: Record<string, any>) => Promise<OAuthUserResponse>;  // 处理 OAuth 回调
    canRegister?: boolean;     // 该提供商是否允许新用户注册
    lockUsername?: boolean;    // 关联后用户名是否锁定
}
```

### `OAuthUserResponse`

```typescript
interface OAuthUserResponse {
    _id: string;                           // 外部用户 ID
    email: string;                         // 用户邮箱
    avatar?: string;                       // 头像 URL
    bio?: string;                          // 用户简介
    uname?: string[];                      // 用户名候选列表
    viewLang?: string;                     // 首选语言
    set?: Record<string, any>;             // 需设置到用户文档的字段
    setInDomain?: Record<string, any>;     // 需设置到域用户文档的字段
}
```

---

## 方法

### 查找

#### `get(platform: string, id: string): Promise<number | null>`

查找与平台+openId 对关联的 Hydro 用户 ID。返回关联的 `uid`，若无映射则返回 `null`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `platform` | `string` | — | OAuth 平台名称（如 `'github'`） |
| `id` | `string` | — | 来自提供商的 openId |
| **返回值** | `Promise<number \| null>` | | 关联的用户 UID，或 `null` |

### 账号关联

#### `set(platform: string, id: string, uid: number): Promise<number>`

创建或更新 OAuth 账号映射。使用 upsert 操作。返回 upsert 文档的 `uid`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `platform` | `string` | — | OAuth 平台名称 |
| `id` | `string` | — | 来自提供商的 openId |
| `uid` | `number` | — | Hydro 用户 UID |
| **返回值** | `Promise<number>` | | 关联的用户 UID |

#### `unbind(platform: string, uid: number): Promise<void>`

按平台和用户 ID 移除 OAuth 账号映射。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `platform` | `string` | — | OAuth 平台名称 |
| `uid` | `number` | — | Hydro 用户 UID |
| **返回值** | `Promise<void>` | | |

#### `list(uid: number): Promise<OauthMap[]>`

列出用户的所有 OAuth 账号映射。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `uid` | `number` | — | Hydro 用户 UID |
| **返回值** | `Promise<OauthMap[]>` | | |

### 提供商注册

#### `provide(name: string, provider: OAuthProvider): Promise<void>`

注册一个 OAuth 提供商。若同名提供商已存在则抛出异常。当服务上下文销毁时，提供商会自动清理。使用 `ctx.effect()` 注册并附带清理逻辑——上下文销毁时自动移除提供商。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `name` | `string` | — | 提供商标识符 |
| `provider` | `OAuthProvider` | — | 提供商配置对象 |
| **返回值** | `Promise<void>` | | |

```typescript
// 注册自定义 OAuth 提供商
ctx.oauth.provide('github', {
    text: 'GitHub',
    name: 'github',
    icon: 'github',
    async get() { /* 重定向到 GitHub OAuth */ },
    async callback(args) {
        // 用 code 换取用户信息
        return { _id: '...', email: '...', uname: ['...'] };
    },
});

// 查找关联用户
const uid = await ctx.oauth.get('github', openId);

// 关联账号
await ctx.oauth.set('github', openId, uid);

// 列出用户的关联账号
const links = await ctx.oauth.list(uid);

// 解除关联
await ctx.oauth.unbind('github', uid);
```

---

## 属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `coll` | `Collection<OauthMap>` | MongoDB `oauth` 集合 |
| `providers` | `Record<string, OAuthProvider>` | 已注册的 OAuth 提供商，按名称索引 |

---

## 备注

- **索引**：在启动时通过 `[Context.init]` 创建——`{ platform: 1, id: 1 }`（唯一索引，每个 platform+openId 仅一条映射）、`{ uid: 1, platform: 1 }`（列出用户的关联账号）。

### OpcountModel

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/model/opcount.ts

```ts
import { OpcountModel } from 'hydrooj'
```

# OpcountModel

频率限制模型，用于跟踪和强制执行时间窗口内的操作计数。

`OpcountModel` 是一个纯模块，导出函数而非类。所有方法直接调用（如 `OpcountModel.inc(...)`）。

---

## 方法

### 频率限制

#### `inc(op: string, ident: string, periodSecs: number, maxOperations: number): Promise<number>`

在当前时间窗口内，对指定操作类型和标识符的操作计数器进行原子递增。返回新计数值。若已达到限制则抛出 `OpcountExceededError`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `op` | `string` | — | 操作类型标识符（如 `"login"`、`"submit"`） |
| `ident` | `string` | — | 调用者的唯一标识（如用户 ID、IP 地址） |
| `periodSecs` | `number` | — | 频率限制窗口的时长（秒） |
| `maxOperations` | `number` | — | 一个窗口内允许的最大操作次数 |
| **返回值** | `Promise<number>` | | 新计数值 |

### 生命周期

#### `apply(): Promise<void>`

在启动时创建所需的 MongoDB 索引。在应用初始化期间调用一次。

---

## 备注

- 时间窗口对齐到固定边界（基于 `periodSecs`），而非从首次请求开始滑动。
- 当 upsert 命中唯一约束（计数器已存在且达到上限）时，捕获 duplicate key error 并以 `OpcountExceededError` 重新抛出。
- `OpcountExceededError` 继承自 `ForbiddenError`，消息为：*"Too frequent operations of {op} (limit: {maxOperations} operations in {periodSecs} seconds)."*
- `apply()` 创建以下索引：`{ expireAt: -1 }`（TTL，自动删除过期窗口）、`{ op: 1, ident: 1, expireAt: 1 }`（unique，确保每个操作/标识/窗口仅一个计数器）。

### OplogModel

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/model/oplog.ts

```ts
import { OplogModel } from 'hydrooj'
```

# OplogModel

操作日志模型，用于记录和查询审计日志条目。

`OplogModel` 是一个纯模块，导出函数而非类。所有方法直接调用（如 `OplogModel.log(...)`）。

---

## 方法

### 日志记录

#### `log(handler: Handler | ConnectionHandler, type: string, data: any): Promise<ObjectId>`

从 HTTP 处理器上下文记录一条操作日志。自动捕获请求元数据（域、user-agent、referer、路径、IP、操作者）。在插入前触发 `oplog/log` 总线事件。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `handler` | `Handler \| ConnectionHandler` | — | 请求处理器，用于提取请求上下文 |
| `type` | `string` | — | 操作类型标识符（如 `"problem.create"`、`"user.login"`） |
| `data` | `any` | — | 与日志条目一起存储的附加数据 |
| **返回值** | `Promise<ObjectId>` | | 新插入文档的 `_id` |

#### `add(data: Partial<OplogDoc> & { type: string }): Promise<ObjectId>`

插入一条原始操作日志，不带请求上下文。适用于系统级或后台任务的日志记录。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `data` | `Partial<OplogDoc> & { type: string }` | — | 部分操作日志文档。必须包含 `type`。若提供 `_id`，则重映射为 `id` |
| **返回值** | `Promise<ObjectId>` | | 新插入文档的 `_id` |

### 查询

#### `get(id: ObjectId): Promise<OplogDoc | null>`

通过 `_id` 获取单条操作日志。未找到则返回 `null`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `id` | `ObjectId` | — | 日志条目 `_id` |
| **返回值** | `Promise<OplogDoc> \| null` | | |

---

## 属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `coll` | `Collection<OplogDoc>` | MongoDB `oplog` 集合，用于自定义查询 |

---

## 备注

- `log()` 在存储前会对处理器参数进行清洗：去除 `password`/`verifyPassword` 字段及以 `__` 开头的键，并将键名中的 `$` 和 `.` 字符替换为 `_`。
- `log()` 通过 `bus.parallel()` 在数据库插入前触发 `oplog/log` 总线事件，允许插件响应或增强日志条目。
- `add()` **不会**自动填充请求元数据（时间、domainId、操作者等）——调用方需按需手动提供。

### ProblemModel

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/model/problem.ts

```ts
import { ProblemModel } from 'hydrooj'
```

# ProblemModel

题目管理模型，提供增删改查操作、测试数据/附件管理、导入导出以及每用户状态跟踪。

`ProblemModel` 是一个纯静态类。所有方法直接在类上调用（如 `ProblemModel.get(...)`）。它封装了 `document` 子系统，文档类型为 `TYPE_PROBLEM`。

---

## 类型导出

### `ProblemDoc`

主要题目文档类型。继承 `Document`（提供 `_id`、`docId`、`docType`、`domainId`、`owner`、`maintainer?`）。通过 `interface.ts` 中的模块扩充声明的额外字段：

| 字段 | 类型 | 说明 |
|------|------|------|
| `pid` | `string` | 题目标识符（如 `"A"`、`"abc-123"`） |
| `title` | `string` | 题目标题 |
| `content` | `string` | 题面（纯文本、HTML 或多语言 JSON） |
| `nSubmit` | `number` | 总提交数 |
| `nAccept` | `number` | 总通过数 |
| `tag` | `string[]` | 标签/分类 |
| `data` | `FileInfo[]` | 测试数据文件元数据 |
| `additional_file` | `FileInfo[]` | 附加文件元数据 |
| `hidden` | `boolean?` | 是否隐藏题目 |
| `html` | `boolean?` | 内容是否为原始 HTML |
| `stats` | `any?` | 统计对象 |
| `difficulty` | `number?` | 难度等级 |
| `sort` | `string?` | 用于排序的排序键 |
| `config` | `string?` | 评测配置（YAML 字符串） |
| `reference` | `{ domainId: string, pid: number }?` | 源题目引用（用于复制的题目） |

### `ProblemDict`

```typescript
type ProblemDict = NumericDictionary<ProblemDoc>
```

以 `docId`（数字）和 `pid`（字符串）为键的字典。

### `ProblemStatusDoc`

每用户题目状态文档。继承 `StatusDocBase`。

| 字段 | 类型 | 说明 |
|------|------|------|
| `docId` | `number` | 题目 docId |
| `docType` | `10` | 始终为 `TYPE_PROBLEM` |
| `uid` | `number` | 用户 ID |
| `rid` | `ObjectId?` | 最佳/最新提交的记录 ID |
| `score` | `number?` | 最佳分数 |
| `status` | `number?` | 最佳状态码 |
| `star` | `boolean?` | 用户是否收藏了该题目 |

### `Field`

```typescript
type Field = keyof ProblemDoc;
```

所有 ProblemDoc 字段名的联合类型。用于投影数组。

---

## 常量

### 投影常量

为常见查询模式预构建的字段投影数组。

| 常量 | 字段 | 用途 |
|------|------|------|
| `PROJECTION_LIST` | `_id`, `domainId`, `docType`, `docId`, `pid`, `owner`, `title`, `nSubmit`, `nAccept`, `difficulty`, `tag`, `hidden`, `stats` | 题目列表页 |
| `PROJECTION_CONTEST_LIST` | `PROJECTION_BASE` + `config` | 比赛题目列表 |
| `PROJECTION_CONTEST_DETAIL` | `PROJECTION_CONTEST_LIST` + `content`, `html`, `data`, `additional_file`, `reference`, `maintainer` | 比赛题目详情 |
| `PROJECTION_PUBLIC` | `PROJECTION_LIST` + `content`, `html`, `data`, `config`, `additional_file`, `reference`, `maintainer` | 完整公开题目视图 |

---

## 方法

### 增删改查

#### `add(domainId: string, pid: string = '', title: string, content: string, owner: number, tag?: string[], meta?: ProblemCreateOptions): Promise<number>`

创建新题目，`docId` 自动递增。触发 `problem/before-add` 和 `problem/add` 事件。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `pid` | `string` | `''` | 题目标识符 |
| `title` | `string` | — | 题目标题 |
| `content` | `string` | — | 题面 |
| `owner` | `number` | — | 拥有者用户 ID |
| `tag` | `string[]` | `[]` | 标签 |
| `meta` | `ProblemCreateOptions` | `{}` | 附加选项 |
| **返回值** | `Promise<number>` | | 新 `docId` |

```typescript
// 创建新题目
const docId = await ProblemModel.add(
  'system',             // domainId
  'A',                  // pid
  '两数之和',            // title
  '给定两个整数 a 和 b', // content
  uid,                  // owner
  ['数学', '入门'],      // tag
);

// 创建隐藏题目
const hiddenDocId = await ProblemModel.add(
  'system', 'B', '隐藏题', '题面内容', uid,
  [],
  { hidden: true },
);
```

#### `addWithId(domainId: string, docId: number, pid: string = '', title: string, content: string, owner: number, tag?: string[], meta?: ProblemCreateOptions): Promise<number>`

使用指定 `docId` 创建题目。由 `add` 和导入逻辑内部使用。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docId` | `number` | — | 指定的 `docId` |
| `pid` | `string` | `''` | 题目标识符 |
| `title` | `string` | — | 题目标题 |
| `content` | `string` | — | 题面 |
| `owner` | `number` | — | 拥有者用户 ID |
| `tag` | `string[]` | `[]` | 标签 |
| `meta` | `ProblemCreateOptions` | `{}` | 附加选项 |
| **返回值** | `Promise<number>` | | 新 `docId` |

#### `get(domainId: string, pid: string | number, projection?: Projection<ProblemDoc>, rawConfig?: boolean): Promise<ProblemDoc | null>`

通过数字 `docId` 或字符串 `pid` 获取单个题目。除非 `rawConfig` 为 `true`，否则自动解析评测配置。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `pid` | `string \| number` | — | 题目 ID 或 pid |
| `projection` | `Projection<ProblemDoc>` | `PROJECTION_PUBLIC` | 要返回的字段 |
| `rawConfig` | `boolean` | `false` | 跳过配置解析 |
| **返回值** | `Promise<ProblemDoc \| null>` | | |

#### `getMulti(domainId: string, query: Filter<ProblemDoc>, projection?: Field[]): MongoDB.Cursor<ProblemDoc>`

获取查询多个题目的 MongoDB 游标，按 `sort` 字段排序。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `query` | `Filter<ProblemDoc>` | — | MongoDB 过滤器 |
| `projection` | `Field[]` | `PROJECTION_LIST` | 要返回的字段 |
| **返回值** | `MongoDB.Cursor<ProblemDoc>` | | |

#### `list(domainId: string, query: Filter<ProblemDoc>, page: number, pageSize: number, projection?: Field[]): Promise<[ProblemDoc[], number, number]>` *(已弃用)*

分页题目列表。返回 `[docs, count, page]`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `query` | `Filter<ProblemDoc>` | — | MongoDB 过滤器 |
| `page` | `number` | — | 页码 |
| `pageSize` | `number` | — | 每页数量 |
| `projection` | `Field[]` | `PROJECTION_LIST` | 要返回的字段 |
| **返回值** | `Promise<[ProblemDoc[], number, number]>` | | `[docs, count, page]` |

#### `edit(domainId: string, _id: number, $set: Partial<ProblemDoc>): Promise<ProblemDoc>`

更新题目字段。`pid` 变更时重新计算 `sort` 键。触发 `problem/before-edit` 和 `problem/edit` 事件。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `_id` | `number` | — | 题目 `docId` |
| `$set` | `Partial<ProblemDoc>` | — | 要更新的字段 |
| **返回值** | `Promise<ProblemDoc>` | | 更新后的文档 |

#### `del(domainId: string, docId: number): Promise<boolean>`

删除题目、其状态和关联的存储文件。触发 `problem/before-del` 和 `problem/delete` 事件。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docId` | `number` | — | 题目 `docId` |
| **返回值** | `Promise<boolean>` | | 是否有内容被删除 |

#### `count(domainId: string, query: Filter<ProblemDoc>): Promise<number>`

统计匹配过滤条件的题目数量。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `query` | `Filter<ProblemDoc>` | — | MongoDB 过滤器 |
| **返回值** | `Promise<number>` | | |

#### `copy(domainId: string, _id: number, target: string, pid?: string, hidden?: boolean): Promise<number>`

将题目复制到另一个域，创建指向原始题目的引用链接。返回新题目的 `docId`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 源域 ID |
| `_id` | `number` | — | 题目 `docId` |
| `target` | `string` | — | 目标域 ID |
| `pid` | `string` | — | 目标域中的题目 PID |
| `hidden` | `boolean` | — | 是否在目标域中隐藏 |

#### `random(domainId: string, query: Filter<ProblemDoc>): Promise<string | number | null>`

获取匹配过滤条件的随机题目 `pid` 或 `docId`。未找到则返回 `null`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `query` | `Filter<ProblemDoc>` | — | MongoDB 过滤器 |
| **返回值** | `Promise<string \| number \| null>` | | |

### 批量查找

#### `getList(domainId: string, pids: number[], canViewHidden?: number | boolean, doThrow?: boolean, projection?: Field[], indexByDocIdOnly?: boolean): Promise<ProblemDict>`

获取多个题目作为 `ProblemDict`。解析引用、解析配置，可选对缺失题目抛出异常。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `pids` | `number[]` | — | `docId` 数组 |
| `canViewHidden` | `number \| boolean` | `false` | UID（检查拥有者/维护者关系）或 `true` 跳过检查 |
| `doThrow` | `boolean` | `true` | 题目缺失时抛出异常 |
| `projection` | `Field[]` | `PROJECTION_PUBLIC` | 要返回的字段 |
| `indexByDocIdOnly` | `boolean` | `false` | 仅按 `docId` 索引，跳过 `pid` 键 |
| **返回值** | `Promise<ProblemDict>` | | |

### 状态跟踪

#### `getStatus(domainId: string, docId: number, uid: number): Promise<ProblemStatusDoc | null>`

获取指定用户在特定题目上的状态记录。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `docId` | `number` | — | 题目 `docId` |
| `uid` | `number` | — | 用户 ID |
| **返回值** | `Promise<ProblemStatusDoc \| null>` | | |

#### `getMultiStatus(domainId: string, query: Filter<ProblemStatusDoc>): MongoDB.Cursor<ProblemStatusDoc>`

获取查询题目状态文档的游标。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `query` | `Filter<ProblemStatusDoc>` | — | MongoDB 过滤器 |
| **返回值** | `MongoDB.Cursor<ProblemStatusDoc>` | | |

#### `getListStatus(domainId: string, uid: number, pids: number[]): Promise<NumericDictionary<ProblemStatusDoc>>`

获取多个题目的状态记录，以 `docId` 为键的字典。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `uid` | `number` | — | 用户 ID |
| `pids` | `number[]` | — | `docId` 数组 |
| **返回值** | `Promise<NumericDictionary<ProblemStatusDoc>>` | | |

#### `updateStatus(domainId: string, pid: number, uid: number, rid: ObjectId, status: number, score: number): Promise<boolean>`

更新用户在题目上的状态。仅在新状态更优时更新（通过始终优先）。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `pid` | `number` | — | 题目 `docId` |
| `uid` | `number` | — | 用户 ID |
| `rid` | `ObjectId` | — | 记录 ID |
| `status` | `number` | — | 状态码 |
| `score` | `number` | — | 分数 |
| **返回值** | `Promise<boolean>` | | 状态是否被更新 |

#### `incStatus(domainId: string, pid: number, uid: number, key: NumberKeys<ProblemStatusDoc>, count: number): Promise<void>`

递增用户题目状态上的数字字段。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `pid` | `number` | — | 题目 `docId` |
| `uid` | `number` | — | 用户 ID |
| `key` | `NumberKeys<ProblemStatusDoc>` | — | 要递增的字段名 |
| `count` | `number` | — | 递增量 |

#### `setStar(domainId: string, pid: number, uid: number, star: boolean): Promise<void>`

设置或取消用户题目状态上的收藏标记。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `pid` | `number` | — | 题目 `docId` |
| `uid` | `number` | — | 用户 ID |
| `star` | `boolean` | — | `true` 收藏，`false` 取消收藏 |

### 测试数据管理

#### `addTestdata(domainId: string, pid: number, name: string, f: Readable | Buffer | string, operator?: number): Promise<void>`

上传测试数据文件。更新题目文档中的 `data` 数组。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `pid` | `number` | — | 题目 `docId` |
| `name` | `string` | — | 文件名 |
| `f` | `Readable \| Buffer \| string` | — | 文件内容或路径 |
| `operator` | `number` | `1` | 操作者用户 ID |

#### `renameTestdata(domainId: string, pid: number, file: string, newName: string, operator?: number): Promise<void>`

在存储和文档元数据中重命名测试数据文件。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `pid` | `number` | — | 题目 `docId` |
| `file` | `string` | — | 原文件名 |
| `newName` | `string` | — | 新文件名 |
| `operator` | `number` | `1` | 操作者用户 ID |

#### `delTestdata(domainId: string, pid: number, name: string | string[], operator?: number): Promise<void>`

删除一个或多个测试数据文件。`name` 可以是单个字符串或数组。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `pid` | `number` | — | 题目 `docId` |
| `name` | `string \| string[]` | — | 要删除的文件名 |
| `operator` | `number` | `1` | 操作者用户 ID |

### 附加文件管理

#### `addAdditionalFile(domainId: string, pid: number, name: string, f: Readable | Buffer | string, operator?: number, skipUpload?: boolean): Promise<void>`

上传附加文件（如附件）。类似 `addTestdata`，但操作 `additional_file` 数组。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `pid` | `number` | — | 题目 `docId` |
| `name` | `string` | — | 文件名 |
| `f` | `Readable \| Buffer \| string` | — | 文件内容或路径 |
| `operator` | `number` | `1` | 操作者用户 ID |
| `skipUpload` | `boolean` | `false` | 跳过存储上传（仅元数据） |

#### `renameAdditionalFile(domainId: string, pid: number, file: string, newName: string, operator?: number): Promise<void>`

重命名附加文件。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `pid` | `number` | — | 题目 `docId` |
| `file` | `string` | — | 原文件名 |
| `newName` | `string` | — | 新文件名 |
| `operator` | `number` | `1` | 操作者用户 ID |

#### `delAdditionalFile(domainId: string, pid: number, name: string | string[], operator?: number): Promise<void>`

删除一个或多个附加文件。`name` 接受 `string | string[]`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `pid` | `number` | — | 题目 `docId` |
| `name` | `string \| string[]` | — | 要删除的文件名 |
| `operator` | `number` | `1` | 操作者用户 ID |

### 子文档辅助

#### `push(domainId: string, _id: number, key: ArrayKeys<ProblemDoc>, value: ProblemDoc[typeof key][0]): Promise<[Doc, ObjectId]>`

向数组字段（`data` 或 `additional_file`）追加元素。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `_id` | `number` | — | 题目 `docId` |
| `key` | `ArrayKeys<ProblemDoc>` | — | 数组字段名 |
| `value` | `ProblemDoc[typeof key][0]` | — | 要追加的元素 |
| **返回值** | `Promise<[Doc, ObjectId]>` | | 更新后的文档和新元素 ID |

#### `pull(domainId: string, pid: number, key: ArrayKeys<ProblemDoc>, values: ProblemDoc[typeof key][0][]): Promise<DocType[typeof key]>`

按值从数组字段中移除元素。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `pid` | `number` | — | 题目 `docId` |
| `key` | `ArrayKeys<ProblemDoc>` | — | 数组字段名 |
| `values` | `ProblemDoc[typeof key][0][]` | — | 要移除的值 |
| **返回值** | `Promise<DocType[typeof key]>` | | 更新后的文档 |

#### `inc(domainId: string, _id: number, field: NumberKeys<ProblemDoc> | string, n: number): Promise<ProblemDoc>`

递增数字字段（如 `nSubmit`、`nAccept`）。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `_id` | `number` | — | 题目 `docId` |
| `field` | `NumberKeys<ProblemDoc> \| string` | — | 要递增的字段名 |
| `n` | `number` | — | 递增量（负数为递减） |
| **返回值** | `Promise<ProblemDoc>` | | 更新后的文档 |

### 权限检查

#### `canViewBy(pdoc: ProblemDoc, udoc: User): boolean`

检查用户是否可以查看题目。若用户拥有 `PERM_VIEW_PROBLEM` 且拥有/维护该题目，或拥有 `PERM_VIEW_PROBLEM_HIDDEN`，或题目未隐藏，则返回 `true`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `pdoc` | `ProblemDoc` | — | 题目文档 |
| `udoc` | `User` | — | 用户文档 |
| **返回值** | `boolean` | | |

### 导入 / 导出

#### `import(domainId: string, filepath: string, options?: ProblemImportOptions): Promise<void>`

从 ZIP 归档或目录导入题目。支持 Hydro、ICPC 和 DOMjudge 包格式。触发进度回调并处理配置合并。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 目标域 |
| `filepath` | `string` | — | `.zip` 文件或目录路径 |
| `options.preferredPrefix` | `string?` | — | 导入时替换 PID 前缀 |
| `options.progress` | `Function?` | — | 进度回调 |
| `options.override` | `boolean` | `false` | 覆盖已有题目 |
| `options.operator` | `number` | `1` | 操作者用户 ID |
| `options.delSource` | `boolean?` | — | 导入后删除源文件 |
| `options.hidden` | `boolean?` | — | 将导入的题目标记为隐藏 |

```typescript
// 从 ZIP 文件导入题目
await ProblemModel.import('system', '/tmp/problems.zip');

// 导入时指定前缀和进度回调
await ProblemModel.import('system', '/tmp/problems.zip', {
  preferredPrefix: 'contest-',
  override: true,
  progress: (current, total) => {
    console.log(`导入进度: ${current}/${total}`);
  },
});

// 导入目录并标记为隐藏
await ProblemModel.import('system', '/data/problems/', {
  hidden: true,
  operator: uid,
});
```

#### `export(domainId: string, pidFilter?: string): Promise<void>`

导出所有题目（或匹配 PID 正则过滤器的题目）为 ZIP 归档，保存到当前工作目录。输出文件路径打印到控制台。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `pidFilter` | `string` | `''` | PID 正则过滤器（留空导出全部） |
| **返回值** | `Promise<void>` | | 无返回值 |

```typescript
// 导出域内所有题目
const zipPath = await ProblemModel.export('system');

// 仅导出匹配前缀的题目
const partialPath = await ProblemModel.export('system', '^contest-');

// zipPath/partialPath 为生成的 ZIP 文件路径
```

---

## 属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `default` | `ProblemDoc` | 模板 `ProblemDoc`，所有字段设为安全默认值 |
| `deleted` | `ProblemDoc` | 哨兵 `ProblemDoc`，用作已删除题目的占位符 |

---

## 事件

以下事件在 ProblemModel 操作期间通过 `bus` 触发：

| 事件 | 参数 | 触发时机 |
|------|------|----------|
| `problem/before-add` | `domainId, content, owner, docId, args` | 创建题目前 |
| `problem/add` | `args, result` | 创建题目后 |
| `problem/before-edit` | `$set, $unset` | 编辑题目前 |
| `problem/edit` | `result` | 编辑题目后 |
| `problem/before-del` | `domainId, docId` | 删除题目前 |
| `problem/delete` | `domainId, docId` | 删除题目后 |
| `problem/addTestdata` | `domainId, pid, name, payload` | 添加测试数据后 |
| `problem/renameTestdata` | `domainId, pid, file, newName` | 重命名测试数据后 |
| `problem/delTestdata` | `domainId, pid, names` | 删除测试数据后 |
| `problem/addAdditionalFile` | `domainId, pid, name, payload` | 添加附加文件后 |
| `problem/renameAdditionalFile` | `domainId, pid, file, newName` | 重命名附加文件后 |
| `problem/delAdditionalFile` | `domainId, pid, names` | 删除附加文件后 |

### RecordModel

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/model/record.ts

```ts
import { RecordModel } from 'hydrooj'
```

# RecordModel

评测记录模型，提供提交创建、评测任务分发、结果更新、重测/重置和提交统计。

`RecordModel` 是一个纯静态类。所有方法直接在类上调用（如 `RecordModel.get(...)`）。

---

## 类型导出

### `RecordDoc`

主要记录文档类型。在 `packages/hydrooj/src/interface.ts` 中定义为基于 `RecordPayload`（来自 `@hydrooj/common`）的映射类型：

```typescript
type RecordDoc = {
    [K in keyof RecordPayload]: K extends 'hackTarget' | 'contest' ? ObjectId : RecordPayload[K];
} & {
    _id: ObjectId;
    notify?: boolean;
};
```

`RecordPayload`（继承 `RecordJudgeInfo`）中的关键字段：

| 字段 | 类型 | 说明 |
|------|------|------|
| `domainId` | `string` | 记录所属的域 |
| `pid` | `number` | 题目 ID |
| `uid` | `number` | 提交者用户 ID |
| `lang` | `string` | 提交语言 |
| `code` | `string` | 提交的源代码 |
| `status` | `number` | 评测状态（来自 `STATUS` 枚举） |
| `score` | `number` | 总分 |
| `time` | `number` | 总用时（毫秒） |
| `memory` | `number` | 总内存（KB） |
| `rejudged` | `boolean` | 是否为重测 |
| `progress` | `number?` | 评测进度百分比 |
| `source` | `string?` | 来源标识符 |
| `contest` | `ObjectId?` | 比赛 ID（或预测试/生成的哨兵值） |
| `input` | `string \| string[]?` | 预测试输入数据 |
| `hackTarget` | `ObjectId?` | Hack 提交的目标记录 ID |
| `files` | `Record<string, string>?` | 附加文件 |
| `judgeTexts` | `(string \| JudgeMessage)[]` | 评测输出消息 |
| `compilerTexts` | `string[]` | 编译器输出消息 |
| `testCases` | `Required<TestCase>[]` | 每个测试点的结果 |
| `judger` | `number` | 评测者用户 ID |
| `judgeAt` | `Date` | 评测时间戳 |
| `subtasks` | `Record<number, SubtaskResult>?` | 子任务结果 |

### `RecordStatDoc`

存储在 `record.stat` 集合中的统计文档，用于唯一提交/通过提交跟踪：

| 字段 | 类型 | 说明 |
|------|------|------|
| `_id` | `ObjectId` | 与记录的 `_id` 相同 |
| `domainId` | `string` | 域 ID |
| `pid` | `number` | 题目 ID |
| `uid` | `number` | 用户 ID |
| `time` | `number` | 用时 |
| `memory` | `number` | 内存 |
| `length` | `number` | 代码长度 |
| `lang` | `string` | 语言 |

### `RecordHistoryDoc`

记录重置重测时归档到 `record.history` 中的评测结果：

| 字段 | 类型 | 说明 |
|------|------|------|
| `_id` | `ObjectId` | 历史条目 ID |
| `rid` | `ObjectId` | 原始记录 ID |
| *(继承自 `RecordJudgeInfo`)* | | `score`、`time`、`memory`、`status`、`judgeTexts`、`compilerTexts`、`testCases`、`subtasks`、`judger`、`judgeAt` |

### `JudgeMeta`

传递给评测任务的元数据：

| 字段 | 类型 | 说明 |
|------|------|------|
| `problemOwner` | `number` | 题目拥有者 UID |
| `hackRejudge?` | `string` | Hack 重测标识符 |
| `rejudge?` | `boolean \| 'controlled'` | 重测模式 |
| `type?` | `string` | 评测类型提示 |

---

## 属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `coll` | `Collection<RecordDoc>` | MongoDB 集合 `record` |
| `collStat` | `Collection<RecordStatDoc>` | MongoDB 集合 `record.stat` |
| `collHistory` | `Collection<RecordHistoryDoc>` | MongoDB 集合 `record.history` |
| `PROJECTION_LIST` | `(keyof RecordDoc)[]` | 列表视图中包含的字段（17 个字段） |
| `STAT_QUERY` | `object` | 统计查询的排序方式，每个键映射为 `[降序排序, 升序排序]` 二元组（`time`、`memory`、`length`、`date`） |
| `RECORD_PRETEST` | `ObjectId` | 预测试记录的哨兵 ID（`000...000`） |
| `RECORD_GENERATE` | `ObjectId` | 生成记录的哨兵 ID（`000...001`） |

---

## 方法

### 查找

#### `get(_id: ObjectId): Promise<RecordDoc | null>`

通过 ObjectId 获取单条记录。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `_id` | `ObjectId` | — | 记录 ID |
| **返回值** | `Promise<RecordDoc \| null>` | | |

#### `get(domainId: string, _id: ObjectId): Promise<RecordDoc | null>`

通过 domainId 和 ObjectId 获取单条记录。若记录的 domainId 不匹配则返回 `null`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `_id` | `ObjectId` | — | 记录 ID |
| **返回值** | `Promise<RecordDoc \| null>` | | |

#### `getMulti(domainId: string, query: any, options?: FindOptions): Cursor<RecordDoc>`

查询多条记录。自动按 `domainId` 限定范围。返回 MongoDB 游标。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `query` | `any` | — | MongoDB 查询过滤器 |
| `options` | `FindOptions` | — | 查询选项（排序、投影等） |
| **返回值** | `Cursor<RecordDoc>` | | 记录游标 |

#### `getMultiStat(domainId: string, query: any, sortBy?: any): Cursor<RecordStatDoc>`

查询多条统计文档。默认按 `_id` 降序排序。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `query` | `any` | — | MongoDB 查询过滤器 |
| `sortBy` | `any` | — | 排序方式 |
| **返回值** | `Cursor<RecordStatDoc>` | | 统计文档游标 |

#### `getList(domainId: string, rids: ObjectId[], fields?: (keyof RecordDoc)[]): Promise<Record<string, Partial<RecordDoc>>>`

通过 ID 数组获取记录，返回以十六进制字符串 `_id` 为键的映射。对输入 ID 去重。可选择投影特定字段。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `rids` | `ObjectId[]` | — | 记录 ID 数组 |
| `fields` | `(keyof RecordDoc)[]` | — | 投影字段列表 |
| **返回值** | `Promise<Record<string, Partial<RecordDoc>>>` | | 以十六进制 ID 为键的记录映射 |

#### `count(domainId: string, query: any): Promise<number>`

统计匹配查询的记录数，按 `domainId` 限定范围。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `query` | `any` | — | MongoDB 查询过滤器 |
| **返回值** | `Promise<number>` | | 匹配数量 |

---

### 统计

#### `stat(domainId?: string): Promise<{ d5min, d1h, day, week, month, year, total }>`

获取各时间窗口的提交计数：5 分钟、1 小时、1 天、1 周、1 月、1 年和总计。可按域限定范围。

使用 `@ArgMethod` 装饰器修饰。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID（省略则统计全部） |
| **返回值** | `Promise<{ d5min, d1h, day, week, month, year, total }>` | | 各时间窗口计数 |

---

### 提交与评测

#### `add(domainId: string, pid: number, uid: number, lang: string, code: string, addTask: boolean, args?: any): Promise<ObjectId>`

创建新的评测记录。插入到 `coll` 中并可选分发评测任务。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `pid` | `number` | — | 题目 ID |
| `uid` | `number` | — | 提交者 UID |
| `lang` | `string` | — | 语言标识符 |
| `code` | `string` | — | 源代码 |
| `addTask` | `boolean` | — | 是否立即分发评测任务 |
| `args.type` | `'judge' \| 'rejudge' \| 'pretest' \| 'hack' \| 'generate'` | `'judge'` | 提交类型 |
| `args.contest` | `ObjectId?` | — | 比赛 ID |
| `args.input` | `string[]?` | — | 预测试输入数据 |
| `args.files` | `Record<string, string>?` | — | 附加文件 |
| `args.hackTarget` | `ObjectId?` | — | Hack 的目标记录 |
| `args.notify` | `boolean?` | — | 评测完成时是否发送通知 |
| **返回值** | `Promise<ObjectId>` | | 插入记录的 ObjectId |

```typescript
// 标准提交
const rid = await RecordModel.add(
  'system',
  1001,
  session.uid,
  'cpp',
  '#include <bits/stdc++.h>\nint main() {}',
  true,
);

// 预测试提交
const pretestRid = await RecordModel.add(
  'system',
  1001,
  session.uid,
  'cpp',
  code,
  true,
  { type: 'pretest', input: ['1 2\n', '3 4\n'] },
);

// Hack 提交
const hackRid = await RecordModel.add(
  'system',
  1001,
  session.uid,
  'cpp',
  hackInput,
  true,
  { type: 'hack', hackTarget: targetRid, contest: tid },
);
```

#### `judge(domainId: string, rids: MaybeArray<ObjectId> | RecordDoc, priority?: number, config?: ProblemConfigFile, meta?: Partial<JudgeMeta>): Promise<any>`

提交一条或多条记录进行评测。解析题目（跟随引用），删除这些记录的已有任务，并创建新的评测任务。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `rids` | `MaybeArray<ObjectId> \| RecordDoc` | — | 记录 ID 或文档 |
| `priority` | `number` | `0` | 任务优先级 |
| `config` | `ProblemConfigFile` | `{}` | 覆盖评测配置 |
| `meta` | `Partial<JudgeMeta>` | `{}` | 评测元数据 |
| **返回值** | `Promise<any>` | | |

```typescript
// 提交单条记录评测
await RecordModel.judge('system', rid);

// 重测多条记录（带自定义优先级和元数据）
await RecordModel.judge(
  'system',
  [rid1, rid2, rid3],
  1,
  {},
  { rejudge: true, problemOwner: uid },
);

// 使用自定义评测配置重测
await RecordModel.judge(
  'system',
  rid,
  0,
  { timeLimit: 5000, memoryLimit: 512 },
  { type: 'rejudge' },
);
```

#### `submissionPriority(uid: number, base?: number): Promise<number>`

计算用户的动态提交优先级。根据近期提交量和待处理任务降低优先级。用于限制高频提交者。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `uid` | `number` | — | 用户 ID |
| `base` | `number` | — | 基础优先级 |
| **返回值** | `Promise<number>` | | 计算后的优先级 |

---

### 更新

#### `update(domainId: string, _id: ObjectId | ObjectId[], $set?: any, $push?: any, $unset?: any, $inc?: any): Promise<RecordDoc | null>`

更新单条或多条记录。接受 MongoDB 更新操作符（`$set`、`$push`、`$unset`、`$inc`）。当 `_id` 为数组时执行 `updateMany` 并返回 `null`；否则返回更新后的文档。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `_id` | `ObjectId \| ObjectId[]` | — | 记录 ID 或 ID 数组（数组时批量更新） |
| `$set` | `any` | — | 要设置的字段 |
| `$push` | `any` | — | 要追加的字段 |
| `$unset` | `any` | — | 要删除的字段 |
| `$inc` | `any` | — | 要增减的字段 |
| **返回值** | `Promise<RecordDoc \| null>` | | 更新后的文档（批量更新返回 `null`） |

#### `updateMulti(domainId: string, $match: any, $set?: any, $push?: any, $unset?: any): Promise<number>`

更新匹配过滤器的多条记录。返回修改的文档数量。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `$match` | `any` | — | MongoDB 匹配过滤器 |
| `$set` | `any` | — | 要设置的字段 |
| `$push` | `any` | — | 要追加的字段 |
| `$unset` | `any` | — | 要删除的字段 |
| **返回值** | `Promise<number>` | | 修改的文档数量 |

#### `reset(domainId: string, rid: ObjectId | ObjectId[], isRejudge: boolean): Promise<RecordDoc | null>`

重置一条或多条记录以进行重测。将当前评测结果归档到 `record.history`，将所有评测字段清除为默认值，并删除关联的统计条目和任务。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域 ID |
| `rid` | `ObjectId \| ObjectId[]` | — | 记录 ID 或 ID 数组 |
| `isRejudge` | `boolean` | — | 是否为重测（`true` 时标记 `rejudged`） |
| **返回值** | `Promise<RecordDoc \| null>` | | 重置后的文档（批量重置返回 `null`） |

```typescript
// 重测单条记录
await RecordModel.reset('system', rid, true);
// 记录状态清除，旧结果归档到 record.history，随后可调用 judge 重新评测
await RecordModel.judge('system', rid, 0, {}, { rejudge: true });

// 批量重测某题目的所有记录
const rids = await RecordModel.getMulti('system', { pid: 1001 }).map(r => r._id).toArray();
await RecordModel.reset('system', rids, true);
await RecordModel.judge('system', rids);
```

---

## 事件

| 事件 | 参数 | 说明 |
|------|------|------|
| `record/change` | `RecordDoc` | 创建新记录时广播（通过 `add()`） |
| `record/judge` | `rdoc: RecordDoc, updated: boolean` | 评测完成时触发；对通过的提交更新 `record.stat` 并发送通知 |

### ScheduleModel

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/model/schedule.ts

```ts
import { ScheduleModel } from 'hydrooj'
```

# ScheduleModel

定时任务模型，用于创建、查询和删除延迟或周期性任务。

`ScheduleModel` 是一个纯静态类。所有方法直接在类上调用（如 `ScheduleModel.add(...)`）。

---

## 类型导出

### `Schedule`

定义在 `packages/hydrooj/src/interface.ts` 中：

```typescript
interface Schedule {
    _id: ObjectId;
    type: string;
    subType?: string;
    executeAfter: Date;
    // interval is not explicitly declared — it is accessed at runtime via the
    // index signature below (e.g. res.interval as [number, moment.UnitOfTime]).
    [key: string]: any;
}
```

索引签名允许根据任务类型携带任意字段（如 `domainId`、自定义负载数据）。

---

## 方法

### 创建

#### `add(task: Partial<Schedule> & { type: string }): Promise<ObjectId>`

插入一条新的定时任务。若省略 `executeAfter`，默认为 `new Date()`（立即执行）。返回插入文档的 `_id`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `task` | `Partial<Schedule> & { type: string }` | — | 任务定义。必须包含 `type` |
| **返回值** | `Promise<ObjectId>` | | 新文档的 `_id` |

### 查询

#### `get(_id: ObjectId): Promise<Schedule | null>`

通过 `_id` 查找单条定时任务。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `_id` | `ObjectId` | — | 任务 `_id` |
| **返回值** | `Promise<Schedule \| null>` | | |

#### `count(query: Filter<Schedule>): Promise<number>`

统计匹配给定过滤条件的文档数量。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `query` | `Filter<Schedule>` | — | MongoDB 过滤条件 |
| **返回值** | `Promise<number>` | | |

#### `getFirst(query: Filter<Schedule>): Promise<Schedule | null>`

原子性地查找并删除匹配过滤条件中最早到期的任务（`executeAfter < now`）。若任务设有 `interval`，则自动重新调度——将 `executeAfter` 推进一个间隔周期。若无到期任务（或在 CI 环境中运行）则返回 `null`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `query` | `Filter<Schedule>` | — | MongoDB 过滤条件 |
| **返回值** | `Promise<Schedule \| null>` | | |

```typescript
// 消费到期任务
const task = await ScheduleModel.getFirst({ type: 'judge' });
if (task) {
  // 处理任务...
  // 若 task.interval 存在，已自动重新调度
}
```

### 删除

#### `del(_id: ObjectId): Promise<DeleteResult>`

通过 `_id` 删除单条定时任务。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `_id` | `ObjectId` | — | 任务 `_id` |
| **返回值** | `Promise<DeleteResult>` | | |

#### `deleteMany(query: Filter<Schedule>): Promise<DeleteResult>`

删除匹配给定过滤条件的所有定时任务。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `query` | `Filter<Schedule>` | — | MongoDB 过滤条件 |
| **返回值** | `Promise<DeleteResult>` | | |

---

## 属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `coll` | `Collection<Schedule>` | MongoDB `schedule` 集合 |

---

## 事件

| 事件 | 参数 | 说明 |
|------|------|------|
| `domain/delete` | `domainId` | 清理被删除域的所有定时任务 |
| `task/daily` | — | 插件运行每日维护逻辑的钩子 |
| `task/daily/finish` | `pref` | 每日任务完成后触发，负载包含计时统计 |

---

## 备注

- `apply()` 函数注册了一个内置的 `task.daily` 工作处理器，用于运行清理（预测试/生成记录）、RP 重算、题目统计和可选的更新检查。
- 每日任务在首次启动时自动创建（次日凌晨 03:00），以 1 天为周期循环执行。
- `getFirst` 使用 `findOneAndDelete` 实现原子消费——并发工作者安全。
- 复合索引 `{ type: 1, subType: 1, executeAfter: -1 }` 用于按类型高效查找任务。

### SettingModel

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/model/setting.ts

```ts
import { SettingModel } from 'hydrooj'
```

# SettingModel

设置注册模型，用于声明用户级、域级和系统级设置。

`SettingModel` 是一个纯模块，导出常量和注册函数而非类。插件使用它将自定义设置注册到相应的分类中。

---

## 类型导出

### `SettingType`

```typescript
type SettingType = "text" | "yaml" | "number" | "float" | "markdown" | "password" | "boolean" | "textarea" | [string, string][] | Record<string, string> | "json"
```

设置值类型的类型别名。

---

## 常量

### 标志常量

| 常量 | 值 | 说明 |
|------|-----|------|
| `FLAG_HIDDEN` | `1` | 在设置界面隐藏 |
| `FLAG_DISABLED` | `2` | 显示但不可编辑 |
| `FLAG_SECRET` | `4` | 密钥字段（如密码） |
| `FLAG_PRO` | `8` | 需要 Hydro Pro |
| `FLAG_PUBLIC` | `16` | 对非管理员用户可见 |
| `FLAG_PRIVATE` | `32` | 仅对拥有者可见 |

### 集合常量

由注册函数填充的只读数组：

| 常量 | 说明 |
|------|------|
| `PREFERENCE_SETTINGS` | 所有已注册的偏好设置 |
| `ACCOUNT_SETTINGS` | 所有已注册的账户设置 |
| `DOMAIN_SETTINGS` | 所有已注册的域设置 |
| `DOMAIN_USER_SETTINGS` | 所有已注册的域用户设置 |
| `SYSTEM_SETTINGS` | 所有已注册的系统设置 |
| `SETTINGS` | 合并的偏好 + 账户设置数组（扁平） |

由注册函数填充的只读字典（按键索引）：

| 常量 | 说明 |
|------|------|
| `SETTINGS_BY_KEY` | 偏好 + 账户设置的查找映射 |
| `DOMAIN_SETTINGS_BY_KEY` | 域设置的查找映射 |
| `DOMAIN_USER_SETTINGS_BY_KEY` | 域用户设置的查找映射 |
| `SYSTEM_SETTINGS_BY_KEY` | 系统设置的查找映射 |

---

## 方法

### 设置工厂

#### `Setting(family: string, key: string, value?: any, type?: SettingType, name?: string, desc?: string, flag?: number, validation?: (val: any) => boolean): Setting`

创建一个设置描述符对象。这是所有注册函数使用的底层工厂函数。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `family` | `string` | — | 用于 UI 分类的组/族名（如 `"setting_basic"`） |
| `key` | `string` | — | 唯一设置键（如 `"pagination.problem"`） |
| `value` | `any` | `null` | 默认值 |
| `type` | `SettingType` | `"text"` | 输入类型。对象类型渲染为 `<select>`（内部转换为 `type: 'select'`，`range` 字段保存选项）。`type: 'yaml'` 配合非字符串 `value` 时，内部转换为 `type: 'textarea'`，`subType: 'yaml'` |
| `name` | `string` | `""` | 显示名称 |
| `desc` | `string` | `""` | 描述文本 |
| `flag` | `number` | `0` | `FLAG_*` 常量的位运算组合 |
| `validation` | `(val: any) => boolean` | _(optional)_ | 可选验证器 |
| **返回值** | `Setting` | | 设置描述符对象 |

### 注册函数

每个注册函数接受 `Setting[]` 或 schemastery `Schema` 对象，将其注册到相应集合中，并返回一个**销毁函数**（`() => void`）用于移除这些设置。

#### `PreferenceSetting(...settings: (Setting | Schema)[]): () => void`

注册偏好级设置（每用户的显示/UI 偏好，如语言、时区）。添加到 `PREFERENCE_SETTINGS`、`SETTINGS` 和 `SETTINGS_BY_KEY`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `...settings` | `(Setting \| Schema)[]` | — | 设置描述符或 schemastery Schema |
| **返回值** | `() => void` | | 销毁函数，调用后移除已注册设置 |

#### `AccountSetting(...settings: (Setting | Schema)[]): () => void`

注册账户级设置（用户资料信息，如头像、简介、手机）。添加到 `ACCOUNT_SETTINGS`、`SETTINGS` 和 `SETTINGS_BY_KEY`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `...settings` | `(Setting \| Schema)[]` | — | 设置描述符或 schemastery Schema |
| **返回值** | `() => void` | | 销毁函数，调用后移除已注册设置 |

#### `DomainSetting(...settings: (Setting | Schema)[]): () => void`

注册域级设置（每域配置，如名称、公告）。添加到 `DOMAIN_SETTINGS` 和 `DOMAIN_SETTINGS_BY_KEY`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `...settings` | `(Setting \| Schema)[]` | — | 设置描述符或 schemastery Schema |
| **返回值** | `() => void` | | 销毁函数，调用后移除已注册设置 |

#### `DomainUserSetting(...settings: (Setting | Schema)[]): () => void`

注册域用户级设置（每用户每域的数据，如显示名称、排名）。添加到 `DOMAIN_USER_SETTINGS` 和 `DOMAIN_USER_SETTINGS_BY_KEY`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `...settings` | `(Setting \| Schema)[]` | — | 设置描述符或 schemastery Schema |
| **返回值** | `() => void` | | 销毁函数，调用后移除已注册设置 |

#### `SystemSetting(...settings: (Setting | Schema)[]): () => void`

注册系统级设置（全局服务器配置，如 SMTP、限制、分页）。添加到 `SYSTEM_SETTINGS` 和 `SYSTEM_SETTINGS_BY_KEY`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `...settings` | `(Setting \| Schema)[]` | — | 设置描述符或 schemastery Schema |
| **返回值** | `() => void` | | 销毁函数，调用后移除已注册设置 |

---

## 属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `langs` | `Record<string, LangConfig>` | 从 `hydrooj.langs` 系统设置解析得到的语言配置。该设置变更时动态更新 |

---

## 备注

- 所有注册函数除 `Setting` 描述符外还接受 **schemastery `Schema` 对象**——会通过 `schemaToSettings()` 自动转换。
- 每个注册函数返回一个销毁回调。调用它可从所有相关集合中移除设置，支持插件清理。
- 重复的设置键会触发警告日志但不会被阻止。
- `Setting` 接口（来自 `hydrooj/src/interface.ts`）定义了结构：`{ family, key, range, value, type, subType?, name, desc, flag, validation? }`。

### SolutionModel

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/model/solution.ts

```ts
import { SolutionModel } from 'hydrooj'
```

# SolutionModel

题解模型，用于管理题目题解、回复和投票。

`SolutionModel` 是一个纯静态类。所有方法直接在类上调用（如 `SolutionModel.add(...)`）。

所有方法委托给通用的 `document` 子系统，使用 `document.TYPE_PROBLEM_SOLUTION` 作为文档类型。

---

## 方法

### 增删改查

#### `add(domainId: string, pid: number, owner: number, content: string): Promise<ObjectId>`

为题目 `pid` 创建一条新题解。初始化时 `reply` 数组为空，`vote: 0`。返回插入文档的 `_id`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `pid` | `number` | — | 题目 ID |
| `owner` | `number` | — | 创建者 UID |
| `content` | `string` | — | 题解内容 |
| **返回值** | `Promise<ObjectId>` | | 新文档 ID |

#### `get(domainId: string, psid: ObjectId): Promise<Document>`

通过 ID 获取单条题解。未找到则抛出 `SolutionNotFoundError`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `psid` | `ObjectId` | — | 题解 ID |
| **返回值** | `Promise<Document>` | | |

#### `getMany(domainId: string, query: any, sort: any, page: number, limit: number): Promise<Document[]>`

分页获取匹配 `query` 的题解列表，按 `sort` 排序。使用 `skip`/`limit` 进行分页。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `query` | `any` | — | 查询条件 |
| `sort` | `any` | — | 排序条件 |
| `page` | `number` | — | 页码（从 1 开始） |
| `limit` | `number` | — | 每页数量 |
| **返回值** | `Promise<Document[]>` | | |

#### `edit(domainId: string, psid: ObjectId, content: string): Promise<void>`

更新已有题解的内容。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `psid` | `ObjectId` | — | 题解 ID |
| `content` | `string` | — | 新内容 |
| **返回值** | `Promise<void>` | | |

#### `del(domainId: string, psid: ObjectId): Promise<[void, void]>`

并行删除题解及其所有关联的状态记录（投票）。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `psid` | `ObjectId` | — | 题解 ID |
| **返回值** | `Promise<[void, void]>` | | |

#### `count(domainId: string, query: any): Promise<number>`

统计匹配给定查询的题解数量。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `query` | `any` | — | 查询条件 |
| **返回值** | `Promise<number>` | | |

### 列表

#### `getMulti(domainId: string, pid: number, query?: any): Cursor<Document>`

获取指定题目的所有题解。结果按 `vote` 降序排列（最高票优先）。可传入额外的查询过滤条件。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `pid` | `number` | — | 题目 ID |
| `query` | `any` | — | 额外过滤条件 |
| **返回值** | `Cursor<Document>` | | |

#### `getByUser(domainId: string, uid: number): Cursor<Document>`

获取指定用户的所有题解。结果按 `_id` 降序排列（最新优先）。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `uid` | `number` | — | 用户 UID |
| **返回值** | `Cursor<Document>` | | |

### 回复

#### `reply(domainId: string, psid: ObjectId, owner: number, content: string): Promise<void>`

为题解添加一条回复。追加到 `reply` 子文档数组中。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `psid` | `ObjectId` | — | 题解 ID |
| `owner` | `number` | — | 回复者 UID |
| `content` | `string` | — | 回复内容 |
| **返回值** | `Promise<void>` | | |

#### `getReply(domainId: string, psid: ObjectId, psrid: ObjectId): Promise<Document>`

通过 ID 获取题解中的特定回复。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `psid` | `ObjectId` | — | 题解 ID |
| `psrid` | `ObjectId` | — | 回复 ID |
| **返回值** | `Promise<Document>` | | |

#### `editReply(domainId: string, psid: ObjectId, psrid: ObjectId, content: string): Promise<void>`

更新已有回复的内容。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `psid` | `ObjectId` | — | 题解 ID |
| `psrid` | `ObjectId` | — | 回复 ID |
| `content` | `string` | — | 新内容 |
| **返回值** | `Promise<void>` | | |

#### `delReply(domainId: string, psid: ObjectId, psrid: ObjectId): Promise<void>`

删除题解中的特定回复。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `psid` | `ObjectId` | — | 题解 ID |
| `psrid` | `ObjectId` | — | 回复 ID |
| **返回值** | `Promise<void>` | | |

### 投票

#### `vote(domainId: string, psid: ObjectId, uid: number, value: number): Promise<Document>`

对题解进行投票或更新投票。跟踪每用户的投票状态——若用户已投票，则调整投票差值（不重复计数）。若新投票与现有投票相同则为空操作。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `psid` | `ObjectId` | — | 题解 ID |
| `uid` | `number` | — | 投票者 UID |
| `value` | `number` | — | 投票值（正/负） |
| **返回值** | `Promise<Document>` | | |

#### `getListStatus(domainId: string, psids: ObjectId[], uid: number): Promise<Record<string, { docId: ObjectId, vote: number }>>`

批量获取当前用户对多条题解的投票状态。返回以题解 ID 字符串为键的映射。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `psids` | `ObjectId[]` | — | 题解 ID 数组 |
| `uid` | `number` | — | 用户 UID |
| **返回值** | `Promise<Record<string, { docId: ObjectId, vote: number }>>` | | |

---

## 事件

| 事件 | 参数 | 说明 |
|------|------|------|
| `problem/delete` | `domainId, pid` | 删除被删除题目的所有题解及其状态记录 |

---

## 备注

- 题解使用通用 `document` 子系统，文档类型为 `TYPE_PROBLEM_SOLUTION`，父类型为 `TYPE_PROBLEM`。
- `vote` 使用 `document.setStatus` 配合 `'before'` 策略检测先前的投票，然后通过 `document.inc` 调整题解的 `vote` 计数——防止重复计数。
- `del` 执行两个并行删除：文档本身和所有关联的状态记录。

### StorageModel

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/model/storage.ts

```ts
import { StorageModel } from 'hydrooj'
```

# StorageModel

文件存储模型，用于管理通过对象存储后端进行的文件上传、下载和生命周期管理。

`StorageModel` 是一个纯静态类。所有方法直接在类上调用（如 `StorageModel.put(...)`）。

---

## 方法

### 上传与写入

#### `put(path: string, file: string | Buffer | Readable, owner?: number): Promise<string>`

将文件上传到指定路径的存储中。先删除同路径的已有文件，生成唯一存储 ID，并同时存储到对象存储和 MongoDB 中。返回 `path`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `path` | `string` | — | 存储路径 |
| `file` | `string \| Buffer \| Readable` | — | 文件路径、Buffer 或可读流 |
| `owner` | `number` | — | 文件所有者 UID |
| **返回值** | `Promise<string>` | | 存储 `path` |

```typescript
// 从 Buffer 上传
const path = await StorageModel.put(
  'problem/1000/statement.md',
  Buffer.from('# Hello World\n题目描述...'),
  session.uid,
);

// 从文件路径上传
const path2 = await StorageModel.put(
  'problem/1000/testdata/in.txt',
  '/tmp/test_input.txt',
);
```

#### `copy(src: string, dst: string): Promise<string>`

在目标路径创建文件副本。副本通过 `link` 字段引用原始存储对象（不重复存储）。先删除 `dst` 处的已有文件。返回新的存储 `_id`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `src` | `string` | — | 源文件路径 |
| `dst` | `string` | — | 目标文件路径 |
| **返回值** | `Promise<string>` | | 新存储 `_id` |

### 读取与下载

#### `get(path: string, savePath?: string): Promise<Readable | string>`

按路径获取文件。更新 `lastUsage` 时间戳。若文档包含 `link` 字段，则跟踪到实际存储对象。若提供 `savePath`，则保存到磁盘并返回文件路径；否则返回 `Readable` 流。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `path` | `string` | — | 文件存储路径 |
| `savePath` | `string` | — | 可选本地保存路径；提供则返回文件路径字符串 |
| **返回值** | `Promise<Readable \| string>` | | `Readable` 流或本地文件路径 |

#### `getMeta(path: string): Promise<object | null>`

按路径返回文件元数据：`Content-Type`、`size`、`lastModified`、`etag` 及自定义元数据。未找到则返回 `null`。更新 `lastUsage` 时间戳。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `path` | `string` | — | 文件存储路径 |
| **返回值** | `Promise<object \| null>` | | 元数据对象或 `null` |

#### `signDownloadLink(target: string, filename?: string, noExpire?: boolean, useAlternativeEndpointFor?: 'user' | 'judge'): Promise<string>`

生成用于下载文件的签名 URL。支持可选的文件名覆盖、禁用过期时间，以及为用户或评测端指定备用端点路由。更新 `lastUsage` 时间戳。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `target` | `string` | — | 文件存储路径 |
| `filename` | `string` | — | 下载时显示的文件名 |
| `noExpire` | `boolean` | `false` | 禁用签名 URL 过期 |
| `useAlternativeEndpointFor` | `'user' \| 'judge'` | — | 使用备用端点路由 |
| **返回值** | `Promise<string>` | | 签名下载 URL |

```typescript
// 生成带自定义文件名的下载链接
const url = await StorageModel.signDownloadLink(
  'problem/1000/statement.md',
  '题目描述.md',
);

// 为评测端生成不过期链接
const judgeUrl = await StorageModel.signDownloadLink(
  'problem/1000/testdata/in.txt',
  undefined,
  true,
  'judge',
);
```

### 文件操作

#### `rename(path: string, newPath: string, operator?: null | number): Promise<UpdateResult>`

在数据库中重命名文件路径。可选择记录执行重命名的操作者。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `path` | `string` | — | 当前文件路径 |
| `newPath` | `string` | — | 新文件路径 |
| `operator` | `null \| number` | `1` | 执行重命名的用户 UID |
| **返回值** | `Promise<UpdateResult>` | | |

#### `move(src: string, dst: string): Promise<boolean>`

将文件从 `src` 移动到 `dst` 路径。若源文件存在并已移动则返回 `true`，否则返回 `false`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `src` | `string` | — | 源文件路径 |
| `dst` | `string` | — | 目标文件路径 |
| **返回值** | `Promise<boolean>` | | 是否成功移动 |

#### `del(path: string[], operator?: number): Promise<void>`

将文件标记为待删除。不会立即删除——将 `autoDelete` 设为 7 天后。处理关联文件时会交换 ID，确保仍被其他文档引用的文件保持可访问。操作者信息记录用于审计。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `path` | `string[]` | — | 要删除的文件路径数组 |
| `operator` | `number` | `1` | 执行删除的用户 UID |
| **返回值** | `Promise<void>` | | |

```typescript
// 标记文件为待删除（7天后自动清理）
await StorageModel.del(
  ['problem/1000/old_statement.md', 'problem/1000/old_testdata.zip'],
  session.uid,
);
```

#### `list(target: string, recursive?: boolean): Promise<object[]>`

列出目标路径前缀下的文件。返回包含额外 `name` 字段（相对路径）的文件文档数组。非递归模式仅列出直接子项。拒绝包含 `..` 或 `//` 的路径。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `target` | `string` | — | 路径前缀 |
| `recursive` | `boolean` | `true` | 是否递归列出子目录 |
| **返回值** | `Promise<object[]>` | | 文件文档数组（含 `name` 字段） |

#### `exists(path: string): Promise<boolean>`

检查给定路径是否存在文件（排除已自动删除的文件）。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `path` | `string` | — | 文件存储路径 |
| **返回值** | `Promise<boolean>` | | |

### 工具方法

#### `generateId(ext: string): string`

生成格式为 `{3字符nanoid}/{nanoid}{ext}` 的唯一存储 ID。将 `_` 和 `-` 替换为 `0` 以确保文件名安全。始终小写。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `ext` | `string` | — | 文件扩展名（含 `.`） |
| **返回值** | `string` | | 唯一存储 ID |

---

## 属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `coll` | `Collection` | MongoDB `storage` 集合 |

---

## 类型导出

该文件还导出一个内部使用的非类函数：

- `apply(ctx: Context)` — 注册域删除处理器（域删除时清理文件）和 `storage.prune` 工作器，定期移除过期文件。

---

## 事件

| 事件 | 参数 | 说明 |
|------|------|------|
| `storage.prune` | — | 定时任务（每小时运行），清理过期文件 |

---

## 备注

- 文件不会通过 `del()` 立即删除——它们被标记为 `autoDelete`（7 天），由 `storage.prune` 定时任务（每小时运行）清理。
- `copy()` 创建一个轻量级引用（`link` 字段）指向原始存储对象，而非在对象存储中重复数据。
- `_swapId` 是一个私有方法，交换两条文件记录的元数据以安全处理关联文件的删除。
- `storage.prune` 任务还会清理超过 `submission.saveDays` 系统设置的提交文件，并遵循 `server.keepFiles` 跳过清理。

**索引**：在启动时通过 `apply()` 创建（仅在 `NODE_APP_INSTANCE=0` 时）：

| 键 | 选项 | 说明 |
|-----|------|------|
| `{ path: 1 }` | — | 按文件路径的主查找 |
| `{ path: 1, autoDelete: 1 }` | sparse | 从查询中排除已删除的文件 |
| `{ link: 1 }` | sparse | 解析关联/复制的文件 |

### SystemModel

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/model/system.ts

```ts
import { SystemModel } from 'hydrooj'
```

# SystemModel

系统级键值设置存储，基于 MongoDB 并带有内存缓存。

`SystemModel` 是 `SystemModelService`（继承 `Service`）的 `serviceInstance` 代理。在启动时将所有系统设置加载到内存缓存中，并通过广播总线保持集群节点间同步。

---

## 方法

### 读写操作

#### `get(key: K): SystemKeys[K]`

从内存缓存中获取单个系统设置。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `key` | `K extends keyof SystemKeys` \| `string` | — | 设置键 |
| **返回值** | `SystemKeys[K]` \| `any` | | 缓存值 |

```typescript
const serverName = SystemModel.get('server.name'); // string
const smtpPort = SystemModel.get('smtp.port');      // number
```

#### `getMany(keys: (keyof SystemKeys)[]): any[]`

一次获取多个系统设置。对最多 6 个键提供类型化元组返回。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `keys` | `(keyof SystemKeys)[]` | — | 设置键数组 |
| **返回值** | `any[]`（对 ≤6 个键为类型化元组） | | 按相同顺序排列的缓存值数组 |

```typescript
const [name, url] = SystemModel.getMany(['server.name', 'server.url']);
```

#### `set(_id: K, value: SystemKeys[K], broadcast?: boolean): Promise<SystemKeys[K]>`

将设置写入 MongoDB，更新本地缓存，并可选地广播到其他集群节点。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `_id` | `K extends keyof SystemKeys` \| `string` | — | 设置键 |
| `value` | `SystemKeys[K]` \| `any` | — | 要存储的值 |
| `broadcast` | `boolean` | `true` | 是否在集群节点间同步 |
| **返回值** | `Promise<SystemKeys[K]>` | | 存储的值 |

```typescript
await SystemModel.set('server.name', 'My Judge');
await SystemModel.set('custom.key', data, false); // 仅本地
```

---

## 属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `coll` | `MongoDB.Collection` | `system` MongoDB 集合 |
| `cache` | `Record<string, any>` | 所有设置的内存缓存；启动时从默认值和数据库填充 |

---

## 类型导出

### `SystemKeys`

`SystemKeys` 接口（`packages/hydrooj/src/interface.ts`）中定义的已知类型化键：

| 键 | 类型 |
|-----|------|
| `smtp.user` | `string` |
| `smtp.from` | `string` |
| `smtp.pass` | `string` |
| `smtp.host` | `string` |
| `smtp.port` | `number` |
| `smtp.secure` | `boolean` |
| `installid` | `string` |
| `server.name` | `string` |
| `server.url` | `string` |
| `server.xff` | `string` |
| `server.xhost` | `string` |
| `server.host` | `string` |
| `server.port` | `number` |
| `server.language` | `string` |
| `limit.problem_files_max` | `number` |
| `problem.categories` | `string` |
| `session.keys` | `string[]` |
| `session.saved_expire_seconds` | `number` |
| `session.unsaved_expire_seconds` | `number` |
| `user.quota` | `number` |

也可使用任意字符串键——返回类型为 `any`。

---

## 备注

- 在服务启动时（`[Service.init]`），SystemModel 执行以下操作：
  1. 从 `SYSTEM_SETTINGS` 加载默认值
  2. 读取 `system` MongoDB 集合中的所有文档并填充 `cache`
  3. 触发 `database/config` 事件
  4. 订阅 `system/setting` 广播事件以保持集群节点间缓存同步

### TaskModel

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/model/task.ts

```ts
import { TaskModel } from 'hydrooj'
```

# TaskModel

后台任务队列模型，用于入队、消费和管理异步任务。

`TaskModel` 是一个纯静态类。所有方法直接在类上调用（如 `TaskModel.add(...)`）。

---

## 类型导出

### `Task`

```typescript
interface Task {
    _id: ObjectId;
    type: string;
    subType?: string;
    priority: number;
    [key: string]: any;
}
```

引用自 `packages/hydrooj/src/interface.ts`。

---

## 方法

### 入队

#### `add(task: Partial<Task> & { type: string }): Promise<ObjectId>`

向队列插入单条任务。自动生成 `_id`，`priority` 默认为 `0`。返回插入的任务 ID。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `task` | `Partial<Task> & { type: string }` | — | 任务对象，`type` 必填 |
| **返回值** | `Promise<ObjectId>` | | 新任务 ID |

#### `addMany(tasks: Task[]): Promise<ObjectId[]>`

批量插入多条任务。返回插入的 ID 数组。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `tasks` | `Task[]` | — | 任务数组 |
| **返回值** | `Promise<ObjectId[]>` | | 新任务 ID 数组 |

### 读取

#### `get(_id: ObjectId): Promise<Task | null>`

通过 ID 获取单条任务。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `_id` | `ObjectId` | — | 任务 ID |
| **返回值** | `Promise<Task \| null>` | | |

#### `count(query: Filter<Task>): Promise<number>`

返回匹配给定查询的任务数量。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `query` | `Filter<Task>` | — | 查询条件 |
| **返回值** | `Promise<number>` | | |

### 删除

#### `del(_id: ObjectId): Promise<DeleteResult>`

通过 ID 删除单条任务。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `_id` | `ObjectId` | — | 任务 ID |
| **返回值** | `Promise<DeleteResult>` | | |

#### `deleteMany(query: Filter<Task>): Promise<DeleteResult>`

删除匹配给定查询的所有任务。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `query` | `Filter<Task>` | — | 查询条件 |
| **返回值** | `Promise<DeleteResult>` | | |

### 消费

#### `getFirst(query: Filter<Task>): Promise<Task | null>`

原子性地查找并移除匹配查询中优先级最高的任务（按 `priority` 降序）。未找到任务或在 CI 模式下返回 `null`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `query` | `Filter<Task>` | — | 匹配条件 |
| **返回值** | `Promise<Task \| null>` | | |

#### `consume(query: any, cb: (t: Task) => Promise<void>, destroyOnError?: boolean, concurrency?: number): Consumer`

创建一个 `Consumer` 实例，持续轮询匹配的任务并通过回调处理。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `query` | `any` | — | 任务匹配条件 |
| `cb` | `(t: Task) => Promise<void>` | — | 任务处理回调 |
| `destroyOnError` | `boolean` | `true` | 出错时是否销毁消费者 |
| `concurrency` | `number` | `1` | 最大并发处理数 |
| **返回值** | `Consumer` | | 消费者实例 |

```typescript
// 创建一个并发度为 4 的任务消费者
const consumer = TaskModel.consume(
    { type: 'judge' },
    async (task) => {
        // 处理判题任务
        await processJudgeTask(task);
    },
    true,   // destroyOnError
    4,      // concurrency
);

// 停止消费
consumer.destroy();
```

---

## Consumer

由 `TaskModel.consume()` 返回。管理一个拾取任务并并发处理的轮询循环。

| 方法 | 说明 |
|------|------|
| `consume()` | 内部轮询循环。不应直接调用。 |
| `destroy()` | 停止消费者并取消轮询循环。在 `app/exit` 时也会自动调用。 |
| `setConcurrency(n: number)` | 更新并行处理任务的最大数量。 |
| `setQuery(query: string)` | 更新任务匹配的过滤查询。 |

---

## 属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `coll` | `Collection` | MongoDB `task` 集合 |

---

## 备注

- `getFirst` 是原子操作（使用 `findOneAndDelete`）——并发消费者安全。
- 任务失败时不会自动重试。`Consumer` 类捕获错误后可选销毁自身（`destroyOnError`）。
- `apply()` 函数还通过 `event` 集合和变更流（副本集）或轮询回退来设置跨进程事件广播。
- `Consumer` 的轮询间隔与可用并发槽位成反比。
- **索引**：在启动时通过 `apply()` 创建（仅在 `NODE_APP_INSTANCE=0` 时）——`{ type: 1, subType: 1, priority: -1 }` 优化 `getFirst` 查询。

### TokenModel

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/model/token.ts

```ts
import { TokenModel } from 'hydrooj'
```

# TokenModel

令牌管理模型，用于创建、查询、更新和删除各种令牌类型（会话、注册、密码重置、OAuth 等）。

`TokenModel` 是一个纯静态类。所有方法直接在类上调用（如 `TokenModel.add(...)`）。

---

## 类型导出

### `TokenDoc`

定义在 `packages/hydrooj/src/interface.ts` 中：

```typescript
interface TokenDoc {
    _id: string;
    tokenType: number;
    createAt: Date;
    updateAt: Date;
    expireAt: Date;
    [key: string]: any;
}
```

索引签名允许根据令牌类型携带任意数据字段（如 `uid`、`email`、`challenge`）。

---

## 常量

### 令牌类型

| 常量 | 值 | 标签 | 说明 |
|------|-----|------|------|
| `TYPE_SESSION` | `0` | Session | 浏览器会话令牌 |
| `TYPE_REGISTRATION` | `2` | Registration | 邮箱注册验证码 |
| `TYPE_CHANGEMAIL` | `3` | Change Email | 邮箱变更验证码 |
| `TYPE_OAUTH` | `4` | OAuth | OAuth 提供商令牌 |
| `TYPE_LOSTPASS` | `5` | Lost Password | 密码重置验证码 |
| `TYPE_EXPORT` | `6` | Export | 数据导出任务令牌 |
| `TYPE_IMPORT` | `7` | Import | 数据导入任务令牌 |
| `TYPE_WEBAUTHN` | `8` | WebAuthn | WebAuthn 挑战令牌 |

`TYPE_TEXTS` 将每个类型编号映射为可读标签。

---

## 方法

### 增删改查

#### `add(tokenType: number, expireSeconds: number, data: any, id?: string): Promise<[string, TokenDoc]>`

创建一条新令牌记录，ID 可自动生成或自定义。自动设置 `createAt`、`updateAt` 和 `expireAt`（now + `expireSeconds`）。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `tokenType` | `number` | — | 令牌类型常量（如 `TYPE_SESSION`） |
| `expireSeconds` | `number` | — | 令牌有效时长（秒） |
| `data` | `any` | — | 令牌附加数据（如 `uid`、`email`） |
| `id` | `string` | `randomstring(32)` | 自定义令牌 ID |
| **返回值** | `Promise<[string, TokenDoc]>` | | `[tokenId, tokenDoc]` 元组 |

```typescript
// 创建注册验证令牌
const [tokenId, tokenDoc] = await TokenModel.add(
  TokenModel.TYPE_REGISTRATION,
  3600,           // 1 小时有效
  { email: 'user@example.com', uid: 12345 },
);
```

#### `get(tokenId: string, tokenType: number): Promise<TokenDoc | null>`

按 ID 和类型查找单条令牌。`@ArgMethod`

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `tokenId` | `string` | — | 令牌 ID |
| `tokenType` | `number` | — | 令牌类型常量 |
| **返回值** | `Promise<TokenDoc \| null>` | | |

#### `getMulti(tokenType: number, query?: Filter<TokenDoc>): Cursor<TokenDoc>`

按类型查找多条令牌，可附加 MongoDB 过滤条件。返回游标（非数组），使用 `.toArray()` 获取完整数据。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `tokenType` | `number` | — | 令牌类型常量 |
| `query` | `Filter<TokenDoc>` | `{}` | 附加过滤条件 |
| **返回值** | `Cursor<TokenDoc>` | | |

#### `update(tokenId: string, tokenType: number, expireSeconds: number, data: object): Promise<TokenDoc | null>`

更新令牌数据并延长过期时间。将 `updateAt` 设为当前时间，`expireAt` 设为当前时间 + `expireSeconds`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `tokenId` | `string` | — | 令牌 ID |
| `tokenType` | `number` | — | 令牌类型常量 |
| `expireSeconds` | `number` | — | 新的有效时长（秒） |
| `data` | `object` | — | 更新的数据 |
| **返回值** | `Promise<TokenDoc \| null>` | | 更新后的文档，未找到返回 `null` |

#### `del(tokenId: string, tokenType: number): Promise<boolean>`

按 ID 和类型删除单条令牌。`@ArgMethod`

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `tokenId` | `string` | — | 令牌 ID |
| `tokenType` | `number` | — | 令牌类型常量 |
| **返回值** | `Promise<boolean>` | | 文档被删除时返回 `true` |

#### `createOrUpdate(tokenType: number, expireSeconds: number, data: any): Promise<string>`

创建令牌，或更新匹配 `tokenType` + `data` 的已有令牌。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `tokenType` | `number` | — | 令牌类型常量 |
| `expireSeconds` | `number` | — | 有效时长（秒） |
| `data` | `any` | — | 令牌附加数据（也作为查找条件） |
| **返回值** | `Promise<string>` | | 令牌 ID（已有或新创建的） |

### 会话查询

#### `getSessionListByUid(uid: number): Promise<TokenDoc[]>`

获取用户的最多 100 条会话令牌，按最近更新排序。`@ArgMethod`

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `uid` | `number` | — | 用户 ID |
| **返回值** | `Promise<TokenDoc[]>` | | |

#### `getMostRecentSessionByUid(uid: number, projection: string[]): Promise<TokenDoc | null>`

获取用户最近更新的会话，可选择返回字段。仅返回 `projection` 中列出的字段（不含 `_id`）。`@ArgMethod`

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `uid` | `number` | — | 用户 ID |
| `projection` | `string[]` | — | 要返回的字段列表 |
| **返回值** | `Promise<TokenDoc \| null>` | | |

### 批量操作

#### `delByUid(uid: number): Promise<any>`

删除用户的所有令牌（所有类型）。用于用户封禁/登出流程，一次性撤销所有会话和待处理令牌。`@ArgMethod`

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `uid` | `number` | — | 用户 ID |
| **返回值** | `Promise<any>` | | |

---

## 属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `coll` | `Collection<TokenDoc>` | MongoDB `token` 集合 |

---

## 备注

- 启动时通过 `apply()` 创建索引：`{ uid: 1, tokenType: 1, updateAt: -1 }`（稀疏索引）、`{ expireAt: -1 }`（TTL 索引，`expireAfterSeconds: 0`，MongoDB 自动删除过期令牌）。
- 标记 `@ArgMethod` 的方法可通过参数/CLI 模式调用：`get`、`del`、`getSessionListByUid`、`getMostRecentSessionByUid`、`delByUid`。

### TrainingModel

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/model/training.ts

```ts
import { TrainingModel } from 'hydrooj'
```

# TrainingModel

训练计划（课程）模型，用于管理 DAG 结构的训练计划、用户注册和进度跟踪。

与 `TaskModel` 不同，`TrainingModel` 是一个纯模块，导出函数而非类。所有函数直接调用（如 `TrainingModel.add(...)`）。

---

## 类型导出

### `TrainingNode`

```typescript
interface TrainingNode {
    _id: number;
    title: string;
    requireNids: number[];
    pids: number[];
}
```

### `TrainingDoc`

```typescript
interface TrainingDoc extends Omit<Tdoc, 'docType'> {
    docType: 40; // document.TYPE_TRAINING
    description: string;
    pin?: number;
    dag: TrainingNode[];
}
```

引用自 `packages/hydrooj/src/interface.ts`。

---

## 方法

### 增删改查

#### `add(domainId: string, title: string, content: string, owner: number, dag?: TrainingNode[], description?: string, pin?: number): Promise<ObjectId>`

创建一条新训练计划。默认值：`dag=[]`、`description=''`、`pin=0`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `title` | `string` | — | 训练计划标题 |
| `content` | `string` | — | 训练计划内容 |
| `owner` | `number` | — | 创建者 UID |
| `dag` | `TrainingNode[]` | `[]` | DAG 节点数组 |
| `description` | `string` | `''` | 描述文本 |
| `pin` | `number` | `0` | 置顶权重 |
| **返回值** | `Promise<ObjectId>` | | 新训练计划的 ObjectId |

#### `edit(domainId: string, tid: ObjectId, $set: Partial<TrainingDoc>): Promise<TrainingDoc>`

更新匹配给定部分文档的训练计划字段。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `tid` | `ObjectId` | — | 训练计划 ID |
| `$set` | `Partial<TrainingDoc>` | — | 要更新的字段 |
| **返回值** | `Promise<TrainingDoc>` | | 更新后的训练计划文档 |

#### `del(domainId: string, tid: ObjectId): Promise<[void, void]>`

删除训练计划及其所有关联的用户状态。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `tid` | `ObjectId` | — | 训练计划 ID |
| **返回值** | `Promise<[void, void]>` | | |

#### `get(domainId: string, tid: ObjectId): Promise<TrainingDoc>`

通过 ID 获取单条训练计划。未找到则抛出 `TrainingNotFoundError`。同时将 DAG 中的 `pids` 值规范化为整数。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `tid` | `ObjectId` | — | 训练计划 ID |
| **返回值** | `Promise<TrainingDoc>` | | |

#### `getMulti(domainId: string, query?: Filter<TrainingDoc>): FindCursor<TrainingDoc>`

返回匹配查询的训练计划游标，按 `pin` 降序然后 `_id` 降序排列。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `query` | `Filter<TrainingDoc>` | — | 查询条件 |
| **返回值** | `FindCursor<TrainingDoc>` | | |

#### `getList(domainId: string, tids: ObjectId[]): Promise<Record<string, TrainingDoc>>`

通过 ID 获取多条训练计划，返回以 `docId.toString()` 为键的映射。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `tids` | `ObjectId[]` | — | 训练计划 ID 数组 |
| **返回值** | `Promise<Record<string, TrainingDoc>>` | | |

#### `count(domainId: string, query: Filter<TrainingDoc>): Promise<number>`

返回匹配给定查询的训练计划数量。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `query` | `Filter<TrainingDoc>` | — | 查询条件 |
| **返回值** | `Promise<number>` | | |

### 注册与状态

#### `enroll(domainId: string, tid: ObjectId, uid: number): Promise<any>`

将用户注册到训练计划中。若已注册则抛出 `TrainingAlreadyEnrollError`。递增训练计划的 `attend` 计数器。返回 `document.inc` 的结果。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `tid` | `ObjectId` | — | 训练计划 ID |
| `uid` | `number` | — | 用户 UID |
| **返回值** | `Promise<any>` | | `document.inc` 的返回值 |

```typescript
// 注册用户到训练计划
const newCount = await TrainingModel.enroll(
    'system',           // domainId
    trainingId,         // tid
    12345,              // uid
);
// 若用户已注册，抛出 TrainingAlreadyEnrollError
```

#### `getStatus(domainId: string, tid: ObjectId, uid: number): Promise<TrainingStatusDoc | null>`

获取指定用户在特定训练计划中的状态。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `tid` | `ObjectId` | — | 训练计划 ID |
| `uid` | `number` | — | 用户 UID |
| **返回值** | `Promise<TrainingStatusDoc \| null>` | | |

#### `getMultiStatus(domainId: string, query: Filter<TrainingDoc>): FindCursor<TrainingStatusDoc>`

返回匹配给定查询的训练计划状态游标。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `query` | `Filter<TrainingDoc>` | — | 查询条件 |
| **返回值** | `FindCursor<TrainingStatusDoc>` | | |

#### `getListStatus(domainId: string, uid: number, tids: ObjectId[]): Promise<Record<string, TrainingStatusDoc>>`

获取指定用户在多条训练计划中的状态，返回以 `docId` 为键的映射。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `uid` | `number` | — | 用户 UID |
| `tids` | `ObjectId[]` | — | 训练计划 ID 数组 |
| **返回值** | `Promise<Record<string, TrainingStatusDoc>>` | | |

#### `setStatus(domainId: string, tid: ObjectId, uid: number, $set: any): Promise<void>`

设置（覆盖）用户在特定训练计划中的状态字段。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `tid` | `ObjectId` | — | 训练计划 ID |
| `uid` | `number` | — | 用户 UID |
| `$set` | `any` | — | 要设置的状态字段 |
| **返回值** | `Promise<void>` | | |

### DAG 辅助函数

用于评估训练计划 DAG 中节点完成状态的工具函数。

#### `getPids(dag: TrainingNode[]): number[]`

提取 DAG 中所有节点的唯一父 ID（`pids`）集合。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `dag` | `TrainingNode[]` | — | DAG 节点数组 |
| **返回值** | `number[]` | | 唯一 `pids` 集合 |

#### `isDone(node: TrainingNode, doneNids: Set<number>, donePids: Set<number>): boolean`

若节点的必需节点 ID 和父题目 ID 均已满足，返回 `true`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `node` | `TrainingNode` | — | DAG 节点 |
| `doneNids` | `Set<number>` | — | 已完成的节点 ID 集合 |
| `donePids` | `Set<number>` | — | 已完成的题目 ID 集合 |
| **返回值** | `boolean` | | |

#### `isProgress(node: TrainingNode, doneNids: Set<number>, donePids: Set<number>, progPids: Set<number>): boolean`

若节点的要求已满足但部分父题目未完成，且至少一个父题目已完成或正在进行中，返回 `true`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `node` | `TrainingNode` | — | DAG 节点 |
| `doneNids` | `Set<number>` | — | 已完成的节点 ID 集合 |
| `donePids` | `Set<number>` | — | 已完成的题目 ID 集合 |
| `progPids` | `Set<number>` | — | 进行中的题目 ID 集合 |
| **返回值** | `boolean` | | |

#### `isOpen(node: TrainingNode, doneNids: Set<number>, donePids: Set<number>, progPids: Set<number>): boolean`

若节点的要求已满足，且无父题目已完成或正在进行中，返回 `true`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `node` | `TrainingNode` | — | DAG 节点 |
| `doneNids` | `Set<number>` | — | 已完成的节点 ID 集合 |
| `donePids` | `Set<number>` | — | 已完成的题目 ID 集合 |
| `progPids` | `Set<number>` | — | 进行中的题目 ID 集合 |
| **返回值** | `boolean` | | |

#### `isInvalid(node: TrainingNode, doneNids: Set<number>): boolean`

若节点的必需节点 ID **未**全部满足（即前置条件未达成），返回 `true`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `node` | `TrainingNode` | — | DAG 节点 |
| `doneNids` | `Set<number>` | — | 已完成的节点 ID 集合 |
| **返回值** | `boolean` | | |

---

## 备注

- 训练计划是一种文档类型模型（`TYPE_TRAINING = 40`）。增删改查和状态操作委托给共享的 `document` 模块。
- `enroll` 是原子操作——使用 `setIfNotStatus` 防止重复注册，冲突时抛出 `TrainingAlreadyEnrollError`。
- `get` 会规范化 DAG 的 `pids` 值（将数字字符串解析为整数）以保持向后兼容。
- DAG 辅助函数（`isDone`、`isProgress`、`isOpen`、`isInvalid`）接受 `Set<number>` 和 `number[]`——内部会自动转换为 `Set`。

### UserModel

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/model/user.ts

```ts
import { UserModel } from 'hydrooj'
```

# UserModel

用户管理模型，提供增删改查操作、认证辅助和用户组管理。

`UserModel` 是一个纯静态类。所有方法直接在类上调用（如 `UserModel.getById(...)`）。它封装了 `user`、`vuser` 和 `user.group` MongoDB 集合，并带有 LRU 缓存。

---

## 方法

### 查找

#### `getById(domainId: string, _id: number, scope?: bigint | string): Promise<User | null>`

在域内通过数字 ID 获取单个用户。返回完整初始化的 `User` 实例或 `null`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `_id` | `number` | — | 用户 ID（负数 ID 查找虚拟用户） |
| `scope` | `bigint \| string` | `PERM.PERM_ALL` | 权限范围掩码 |
| **返回值** | `Promise<User \| null>` | | |

#### `getByUname(domainId: string, uname: string): Promise<User | null>`

在域内通过用户名获取单个用户。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `uname` | `string` | — | 用户名（不区分大小写） |
| **返回值** | `Promise<User \| null>` | | |

#### `getByEmail(domainId: string, mail: string): Promise<User | null>`

在域内通过邮箱地址获取单个用户。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `mail` | `string` | — | 邮箱地址（不区分大小写，应用 Gmail 规范化） |
| **返回值** | `Promise<User \| null>` | | |

#### `getList(domainId: string, uids: number[]): Promise<Udict>`

以 UID 为键获取多个用户的字典。缺失用户回退为 `defaultUser`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `uids` | `number[]` | — | 用户 ID 数组 |
| **返回值** | `Promise<Udict>` | | `Record<number, User>` |

#### `getPrefixList(domainId: string, prefix: string, limit?: number): Promise<User[]>`

通过用户名或显示名前缀搜索用户。同时搜索 `unameLower` 和域显示名。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `prefix` | `string` | — | 搜索前缀（不区分大小写） |
| `limit` | `number` | `50` | 最大结果数 |
| **返回值** | `Promise<User[]>` | | |

#### `getMulti(params?: Filter<Udoc>, projection?: (keyof Udoc)[]): MongoDB.Cursor<Udoc>`

获取用于查询用户的 MongoDB 游标，支持可选过滤和字段投影。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `params` | `Filter<Udoc>` | — | MongoDB 查询过滤器 |
| `projection` | `(keyof Udoc)[]` | — | 要包含的字段 |
| **返回值** | `MongoDB.Cursor<Udoc>` | | |

#### `getListForRender(domainId: string, uids: number[], showPrivateInfo?: boolean, extraFields?: string[]): Promise<BaseUserDict>`

获取为前端渲染优化的用户信息字典。合并用户文档、虚拟用户文档和域用户文档。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `uids` | `number[]` | — | 要获取的用户 ID |
| `showPrivateInfo` | `boolean` | — | 是否包含私有字段 |
| `extraFields` | `string[]` | — | 额外要包含的字段 |
| **返回值** | `Promise<BaseUserDict>` | | |

### 创建

#### `create(mail: string, uname: string, password: string, uid?: number, regip?: string, priv?: number): Promise<number>`

注册新用户。若未提供则自动分配 UID。等待数据库同步后返回。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `mail` | `string` | — | 邮箱地址 |
| `uname` | `string` | — | 显示名 |
| `password` | `string` | — | 明文密码 |
| `uid` | `number?` | auto | 强制指定 UID，或自动分配 |
| `regip` | `string` | `'127.0.0.1'` | 注册 IP |
| `priv` | `number` | `system.get('default.priv')` | 初始权限等级 |
| **返回值** | `Promise<number>` | | 分配的用户 ID |

```typescript
// 注册新用户
const uid = await UserModel.create(
  'user@example.com',   // mail
  '张三',                // uname
  'securePassword123',  // password
);

// 指定 UID 和初始权限
const adminUid = await UserModel.create(
  'admin@example.com',
  '管理员',
  'adminPassword',
  1000,                 // uid（强制指定）
  '127.0.0.1',          // regip
  PRIV.PRIV_ALL,        // priv
);
```

#### `ensureVuser(uname: string): Promise<number>`

确保存在用于比赛显示的虚拟用户。若不存在则创建一个递减负数 ID。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `uname` | `string` | — | 虚拟用户显示名 |
| **返回值** | `Promise<number>` | | 虚拟用户 ID |

### 变更

#### `setById(uid: number, $set?: Partial<Udoc>, $unset?: Partial<Udoc>, $push?: object): Promise<Udoc | null>`

使用 MongoDB 更新操作符更新用户文档。自动使缓存失效。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `uid` | `number` | — | 用户 ID |
| `$set` | `Partial<Udoc>` | — | 要设置的字段 |
| `$unset` | `Partial<Udoc>` | — | 要取消设置的字段 |
| `$push` | `object` | — | 要追加的字段（数组追加） |
| **返回值** | `Promise<Udoc \| null>` | | 更新后的文档（虚拟用户返回 null） |

#### `setUname(uid: number, uname: string): Promise<Udoc | null>`

更改用户的显示名。同时更新 `uname` 和 `unameLower`。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `uid` | `number` | — | 用户 ID |
| `uname` | `string` | — | 新的显示名 |
| **返回值** | `Promise<Udoc \| null>` | | 更新后的文档 |

#### `setEmail(uid: number, mail: string): Promise<Udoc | null>`

更改用户的邮箱。应用 Gmail 规范化（`handleMailLower`）。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `uid` | `number` | — | 用户 ID |
| `mail` | `string` | — | 新的邮箱地址 |
| **返回值** | `Promise<Udoc \| null>` | | 更新后的文档 |

#### `setPassword(uid: number, password: string): Promise<Udoc>`

重置用户密码。生成新的盐值并使用 `hydro` 哈希类型重新哈希。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `uid` | `number` | — | 用户 ID |
| `password` | `string` | — | 新的明文密码 |

#### `setPriv(uid: number, priv: number): Promise<Udoc>`

直接设置用户的权限等级。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `uid` | `number` | — | 用户 ID |
| `priv` | `number` | — | 权限位掩码（参见 `PRIV` 常量） |
| **返回值** | `Promise<Udoc>` | | 更新后的文档 |

#### `setSuperAdmin(uid: number): Promise<Udoc>`

将用户提升为超级管理员（`PRIV.PRIV_ALL`）。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `uid` | `number` | — | 用户 ID |

#### `setJudge(uid: number): Promise<Udoc>`

将用户设置为评测员并赋予相应权限（`USER_PROFILE | JUDGE | VIEW_ALL_DOMAIN | READ_PROBLEM_DATA | UNLIMITED_ACCESS`）。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `uid` | `number` | — | 用户 ID |

#### `ban(uid: number, reason?: string): Promise<[Udoc | null, any]>`

封禁用户：将权限设为 `PRIV_NONE` 并撤销所有令牌。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `uid` | `number` | — | 用户 ID |
| `reason` | `string` | `''` | 封禁原因，存储在 `banReason` 中 |

```typescript
// 封禁用户并记录原因
await UserModel.ban(uid, '违反社区规范');

// 封禁用户（无原因）
await UserModel.ban(uid);
```

#### `inc(_id: number | number[], field: string, n?: number): Promise<Udoc[] | null>`

递增一个或多个用户的数字字段。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `_id` | `number \| number[]` | — | 用户 ID |
| `field` | `string` | — | 要递增的字段名 |
| `n` | `number` | `1` | 递增量（负数为递减） |
| **返回值** | `Promise<Udoc[] \| null>` | | 递增前的文档 |

### 用户组

#### `listGroup(domainId: string, uid?: number): Promise<any>`

列出域中的用户组。若提供 `uid`，则仅返回包含该用户的组及隐式的自身组。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `uid` | `number` | — | 可选，筛选包含该用户的组 |

#### `delGroup(domainId: string, name: string): Promise<void>`

按名称删除用户组。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `name` | `string` | — | 用户组名称 |

#### `updateGroup(domainId: string, name: string, uids: number[]): Promise<void>`

创建或更新包含指定成员 UID 的用户组。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `domainId` | `string` | — | 域上下文 |
| `name` | `string` | — | 用户组名称 |
| `uids` | `number[]` | — | 成员 UID 数组 |

---

## 属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `coll` | `Collection<Udoc>` | `user` MongoDB 集合 |
| `collGroup` | `Collection<GDoc>` | `user.group` MongoDB 集合 |
| `cache` | `LRUCache<string, User>` | LRU 缓存（最大 10000，TTL 5 分钟），以 `type/key/domainId` 为键 |
| `defaultUser` | `Udoc` | 缺失用户的默认用户文档模板 |

---

## User 类

`getById` 等方法返回 `User` 实例。`User` 类封装了 `Udoc` + 域用户文档，并提供：

| 方法 | 说明 |
|------|------|
| `own(doc, arg?)` | 检查用户是否拥有（或维护）某个文档。传入 `bigint` 权限以限定检查条件，或 `true` 表示仅限拥有者。 |
| `hasPerm(...perms)` | 检查用户是否拥有给定权限位中的**任一**权限（与范围取交集）。 |
| `hasPriv(...privs)` | 检查用户是否拥有给定特权位中的**任一**特权。 |
| `checkPassword(password)` | 用存储的哈希验证明文密码。 |
| `private()` | 返回清洗后的私有视图（头像已解析，置顶域已展开）。 |
| `getFields(type?)` | 获取 `'public'` 或 `'private'` 序列化的字段名。 |
| `serialize(h)` | 序列化为 JSON，根据查看者权限过滤字段。 |

### User 关键属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `_id` | `number` | 用户 ID |
| `uname` | `string` | 显示名 |
| `mail` | `string` | 邮箱地址 |
| `priv` | `number` | 全局特权位掩码 |
| `perm` | `bigint` | 域范围权限位掩码 |
| `role` | `string` | 域角色（如 `'default'`） |
| `scope` | `bigint` | 权限范围掩码 |
| `regat` | `Date` | 注册时间 |
| `loginat` | `Date` | 最后登录时间 |
| `tfa` | `boolean` | 是否启用了两步验证 |
| `group` | `string[]?` | 域组成员关系 |

---

## 服务

### Handler, ConnectionHandler & requireSudo

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/service/server.ts

```ts
import { Handler, ConnectionHandler, requireSudo } from 'hydrooj'
```

# Handler, ConnectionHandler & requireSudo

服务端处理类及用于请求处理的 sudo 装饰器。

---

## 类

### `Handler`

HTTP 请求处理类，继承自 `@hydrooj/framework` 的 `HandlerOriginal<Context>`。新增 `domain` 属性，并继承框架的全部 handler 工具方法（`request`、`response`、`args`、`user`、`checkPerm`、`checkPriv`、`url`、`renderHTML` 等）。这是所有 Hydro HTTP 路由处理器的基类。

| 属性 | 类型 | 说明 |
|----------|------|-------------|
| `domain` | `DomainDoc` | 当前域文档，在 handler 创建时注入 |

```typescript
import { Handler } from 'hydrooj';

class MyHandler extends Handler {
  async get() {
    const { domain, user } = this;
    // domain._id, domain.host, etc.
  }
}
```

### `ConnectionHandler`

WebSocket 连接处理类，继承自 `@hydrooj/framework` 的 `ConnectionHandlerOriginal<Context>`。新增 `domain` 属性，并继承框架的 WebSocket 工具方法（`send`、`close` 等）。这是所有 Hydro WebSocket 连接处理器的基类。

| 属性 | 类型 | 说明 |
|----------|------|-------------|
| `domain` | `DomainDoc` | 当前域文档，在 handler 创建时注入 |

```typescript
import { ConnectionHandler } from 'hydrooj';

class MyConnection extends ConnectionHandler {
  async prepare() {
    this.send({ type: 'welcome', domain: this.domain._id });
  }
}
```

---

## 装饰器

### `requireSudo`

方法装饰器，在执行被装饰的处理方法前强制要求 sudo（重新认证）权限。若用户拥有有效的 sudo 会话（最近一小时内），则正常执行原方法；否则重定向至 sudo 确认页面。

**行为**：
- 检查 `session.sudo` 时间戳 —— 有效期为 1 小时
- sudo 有效时：恢复已保存的 `referer` 请求头，继续执行原方法
- sudo 缺失或过期时：将请求上下文保存至 `session.sudoArgs`，重定向至 `user_sudo` 页面

```typescript
import { Handler, requireSudo } from 'hydrooj';

class AdminHandler extends Handler {
  @requireSudo
  async post() {
    // 此处理器要求用户在过去一小时内
    // 通过 sudo 确认页面完成重新认证
  }
}
```

---

## 备注

- `Handler` 和 `ConnectionHandler` 均为框架类的重新导出，使用 Hydro 的 `Context` 类型参数并新增了 `domain` 属性。`domain` 通过 `handler/create` 生命周期钩子注入。
- 额外的 handler 混入方法（`paginate`、`limitRate`、`checkPerm`、`checkPriv`、`progress`、`renderTitle`、`url`、`translate`）在服务启动时通过 `server.handlerMixin()` 注册 —— 参见 `@hydrooj/framework` 的 `HandlerCommon` 基础接口。
- `requireSudo` 专为安全敏感操作设计，防止在共享计算机上利用记住的密码进行误操作。

### SettingService

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/settings.ts

```ts
import { SettingService } from 'hydrooj'
```

# SettingService

系统配置服务，提供配置读写、基于 Schema 的校验，以及插件设置注册功能。

访问：`ctx.setting`（Cordis 服务，以 `'setting'` 注入）

`SettingService` 是一个 Cordis `Service`，负责管理 Hydro 基于 YAML 的系统配置。它从 `system` MongoDB 集合加载配置，根据已注册的 Schema 进行校验，并通过基于代理的 getter 提供响应式访问。插件通过五个注册方法（PreferenceSetting、AccountSetting 等）注册设置 Schema，当插件的上下文被销毁时自动清理。

---

## 属性

| 属性 | 类型 | 说明 |
|----------|------|-------------|
| `settings` | `Schema[]` | 当前已注册的配置 Schema 数组 |
| `configSource` | `string` | 当前系统配置的原始 YAML 字符串 |
| `systemConfig` | `any`（私有） | 解析后的配置对象 |
| `applied` | `any`（私有） | 经 Schema 校验后的配置对象 |

---

## 公开方法

### `get(key: string): any`

通过点分路径键读取配置值。解析顺序：先查找域配置（`ctx.domain.config`），再查找系统配置，最后以 `global.Hydro.model.system.get` 作为兜底。未找到时返回 `null` 或 `undefined`。

### `setConfig(key: string, value: any): Promise<void>`

将指定配置键（点分路径）设为给定值。将增量应用到当前配置，根据所有已注册的 Schema 进行校验，持久化到数据库并重新加载。

### `requestConfig<T, S>(s: Schema<T, S>, dynamic?: boolean): S`

注册一个 Schema 用于配置校验，并返回当前已校验的配置值。当 `dynamic` 为 `true`（默认值）时，返回值为响应式代理：读取嵌套属性正常工作，**写入**属性时会自动调用 `setConfig` 持久化更改。Schema 在上下文销毁时自动移除。

### `loadConfig(): Promise<void>`

从 `system` MongoDB 集合加载系统配置（YAML 格式），根据所有已注册的 Schema 进行校验，并触发 `system/setting` 事件。在服务初始化期间自动调用。

### `saveConfig(config: any): Promise<void>`

根据所有已注册的 Schema 校验给定配置对象（校验失败时抛出异常），序列化为 YAML，持久化到 `system` 集合，然后调用 `loadConfig` 刷新内存状态并通知监听器。

---

## 注册方法

这些方法封装了 `SettingModel` 中对应的函数（参见 [SettingModel 文档](../models/setting-model.md)），并添加了基于上下文的自动清理。每个方法返回 `void`，注册的设置与插件上下文生命周期绑定。

### `PreferenceSetting(...args): void`

注册偏好级设置（用户级别，跨域）。委托给 `SettingModel.PreferenceSetting`。上下文结束时自动清理。

### `AccountSetting(...args): void`

注册账户级设置（用户级别的认证/安全设置）。委托给 `SettingModel.AccountSetting`。上下文结束时自动清理。

### `DomainSetting(...args): void`

注册域级设置（域级别配置）。委托给 `SettingModel.DomainSetting`。上下文结束时自动清理。

### `DomainUserSetting(...args): void`

注册域用户级设置（作用域限定在特定域的用户偏好）。委托给 `SettingModel.DomainUserSetting`。上下文结束时自动清理。

### `SystemSetting(...args): void`

注册系统级设置（对所有域可见的全局配置）。委托给 `SettingModel.SystemSetting`。上下文结束时自动清理。

---

## 内部方法

以下方法供内部使用，插件开发者通常不需要直接调用。

| 方法 | 说明 |
|--------|-------------|
| `_applySchema()` | 根据所有已注册的 Schema 校验 `systemConfig`，将结果存储在 `applied` 中 |
| `_get(key: string)` | 按点分路径遍历已校验的 `applied` 配置；拒绝黑名单路径段 |
| `applyDelta(source, key, value)` | 返回 `source` 的深拷贝，其中指定键设为 `value` |
| `isPatchValid(key, value)` | 测试应用增量后是否能通过 Schema 校验 |
| `_tryMigrateConfig(schema)` | 将旧格式设置（每个键一个文档）迁移到统一 YAML 配置（排队执行） |

### db (MongoService) & Collections

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/service/db.ts

```ts
import { db, Collections } from 'hydrooj'
```

# db (MongoService) & Collections

MongoDB 数据库服务，提供集合访问、索引管理、分页和排名工具。

访问：`ctx.db`（推荐）或 `db`（已弃用的全局代理）

---

## MongoService (`ctx.db`)

注册为 `'db'` 键的 Cordis `Service`。在 `database/connect` 生命周期事件后可通过 `ctx.db` 使用。

### 属性

| 属性 | 类型 | 说明 |
|----------|------|-------------|
| `client` | `MongoClient` | 底层 MongoDB 客户端实例 |
| `db` | `Db` | 已连接数据库的原生 MongoDB `Db` 实例 |

### 方法

#### `collection<K extends keyof Collections>(c: K): Collection<Collections[K]>`

返回带类型的 MongoDB 集合。遵循 `prefix` 和 `collectionMap` 配置进行名称重映射。

#### `paginate<T>(cursor: FindCursor<T>, page: number, pageSize: number): Promise<[docs: T[], numPages: number, count: number]>`

对查找游标进行分页。返回一个元组，包含当前页文档、总页数和总文档数。`page <= 0` 时抛出 `ValidationError`。

#### `ranked<T>(cursor: T[] | FindCursor<T>, equ: (a: T, b: T) => boolean): Promise<[number, T][]>`

为已排序的结果分配密集排名。带有 `unrank: true` 的文档排名为 `0`。并列文档（根据 `equ` 比较器判断）共享相同排名。

#### `ensureIndexes<T>(coll: Collection<T>, ...indexes: IndexDescription[]): Promise<void>`

在集合上创建或更新索引。仅在 `NODE_APP_INSTANCE=0` 时运行。按名称/键比较现有索引，若定义已更改则先删除再重建。文本索引有特殊处理以避免冲突。

#### `clearIndexes<T>(coll: Collection<T>, dropIndex?: string[]): Promise<void>`

删除集合中已存在的指定索引。仅在 `NODE_APP_INSTANCE=0` 时运行。

#### `fixExpireAfter(): Promise<void>`

针对 MongoDB TTL 索引在非副本集模式下无法自动过期的变通方案。手动删除超过 `expireAfterSeconds` 阈值的文档。每小时通过定时器调用。

### 静态方法

#### `MongoService.getUrl(): Promise<string | null>`

从配置或环境变量解析 MongoDB 连接 URL。未加载配置时返回 `null`。CI 模式下启动内存中的 `mongodb-memory-server` 实例。

---

## Collections

将集合名称映射到其文档类型的 TypeScript 接口。通过 `packages/hydrooj/src/interface.ts` 中的模块声明合并进行扩展。

**导出**: `import { Collections } from 'hydrooj';`

### 已定义集合

| 集合名称 | 文档类型 | 说明 |
|-----------------|---------------|-------------|
| `blacklist` | `BlacklistDoc` | IP/邮箱黑名单条目 |
| `domain` | `DomainDoc` | 域（站点）文档 |
| `domain.user` | `any` | 域用户成员记录 |
| `record` | `RecordDoc` | 提交/评测记录 |
| `record.stat` | `RecordStatDoc` | 聚合记录统计 |
| `record.history` | `RecordHistoryDoc` | 记录变更历史 |
| `document` | `any` | 通用文档（题目、比赛、训练、讨论等） |
| `document.status` | `StatusDocBase & { [K in keyof DocStatusType]: { docType: K } & DocStatusType[K] }[keyof DocStatusType]` | 用户级别的文档状态（`StatusDocBase` 与按 docType 区分的判别联合类型的交集） |
| `discussion.history` | `DiscussionHistoryDoc` | 讨论/回复编辑历史 |
| `user` | `Udoc` | 用户账户 |
| `user.preference` | `UserPreferenceDoc` | 用户偏好设置 |
| `vuser` | `VUdoc` | 虚拟用户 |
| `user.group` | `GDoc` | 用户组 |
| `check` | `System` | 系统健康检查记录 |
| `message` | `MessageDoc` | 用户消息/通知 |
| `token` | `TokenDoc` | 认证令牌 |
| `status` | `any` | 系统状态记录 |
| `oauth` | `OauthMap` | OAuth 提供商映射 |
| `system` | `System` | 系统配置文档 |
| `task` | `Task` | 后台任务队列条目 |
| `storage` | `FileNode` | 文件存储元数据 |
| `oplog` | `OplogDoc` | 操作审计日志条目 |
| `event` | `EventDoc` | 域事件记录 |
| `opcount` | `OpCountDoc` | 频率限制操作计数器 |
| `schedule` | `Schedule` | 定时任务定义 |
| `contest.balloon` | `ContestBalloonDoc` | 比赛气球（通知）记录 |
| `lock` | `LockDoc` | 分布式锁条目 |

### 用法

```typescript
import { Collections } from 'hydrooj';

// 通过 ctx.db 访问带类型的集合
const coll = ctx.db.collection('document');       // Collection<any>
const userColl = ctx.db.collection('user');       // Collection<Udoc>
```

---

## 备注

- `db`（默认导出）是一个已弃用的 Proxy，转发到 `app.get('db')`。插件中推荐使用 `ctx.db`。
- `Collections` 接口在 `service/db.ts` 中声明为空，通过 `interface.ts` 中的 `declare module './service/db'` 进行扩展。
- 插件可通过相同的声明合并模式扩展 `Collections` 来注册自定义集合类型。

### StorageService

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/service/storage.ts

```ts
import { StorageService } from 'hydrooj'
```

# StorageService

文件存储后端服务，提供上传、下载、删除和签名 URL 生成。支持本地文件系统和 S3 兼容对象存储。

访问：`ctx.storage`（实例，服务启动后可用）

`StorageService` 是一个命名空间导出，包含两个后端类（`RemoteStorageService` 用于 S3，`LocalStorageService` 用于文件系统）以及 `Config` schema 和 `encodeRFC5987ValueChars` 工具。运行时，`ctx.storage` 返回所配置的后端实例。

两个后端共享相同的公开 API 接口：

---

## 公开方法

### `put(target: string, file: string | Buffer | Readable, meta?: Record<string, string>): Promise<void>`

将文件上传到存储路径。接受文件路径、Buffer 或 Readable 流。S3 后端对大于 5MB 的文件使用分片上传，并支持 `meta` 元数据参数。本地后端写入磁盘，不支持 `meta` 参数（该参数被忽略）。路径会进行校验（不允许 `..`、`//` 等）。

### `get(target: string, path?: string): Promise<Readable | null>`

获取文件。默认返回 `Readable` 流。若提供 `path`，则将文件同时保存到该本地路径；此时 S3 后端返回 `null`，本地后端仍返回 `Readable` 流。

### `del(target: string | string[]): Promise<void>`

删除一个或多个文件。接受单个路径字符串或路径数组。S3 后端对多个目标使用批量 `DeleteObjectsCommand`。

### `getMeta(target: string): Promise<{ size, lastModified, etag, metaData }>`

返回文件元数据：`size`（字节）、`lastModified`（Date）、`etag`（string）和 `metaData`（record）。本地后端从 Base64 编码的路径计算 etag。

### `signDownloadLink(target: string, filename?: string, noExpire?: boolean, useAlternativeEndpointFor?: 'user' | 'judge'): Promise<string>`

生成签名下载 URL。S3 后端使用预签名 URL（为兼容阿里云最长 7 天，默认 30 分钟）。本地后端通过 `/storage` 端点生成 HMAC 签名路径（默认 10 分钟有效期）。支持为用户或判题机访问使用备用端点路由。

### `signUpload(target: string, size: number): Promise<{ url, fields }>`

生成预签名 POST 用于浏览器直传（仅 S3）。包含 ±50 字节容差的内容长度范围条件。10 分钟有效期。本地后端抛出 `Error('Not implemented')`。

### `isLinkValid(link: string): Promise<boolean>`

验证签名链接的 HMAC 签名。仅在本地后端有效（S3 后端返回 `false`）。

### `status(): Promise<{ type, status, error, ... }>`

返回服务健康信息：`type`（`'S3'` 或 `'Local'`）、`status`（布尔值）、`error`（字符串）及后端特定字段（`bucket`、`dir`）。

---

## 属性

| 属性 | 类型 | 说明 |
|----------|------|-------------|
| `client` | `S3Client \| null` | S3 客户端实例（本地后端为 null） |
| `error` | `string \| null` | 最近一次错误消息，健康时 S3 后端为 `null`、本地后端为空字符串 |

---

## 导出（命名空间）

| 导出 | 类型 | 说明 |
|--------|------|-------------|
| `Config` | `Schema` | 存储配置 Schema（校验 `type`、`path`/`endPoint`、凭证等） |
| `encodeRFC5987ValueChars` | `(str: string) => string` | 按 RFC 5987 编码文件名用于 `Content-Disposition` 请求头 |
| `apply` | `(ctx, config) => Promise<void>` | 服务生命周期：实例化后端、启动、注册 `/fs` 代理路由、提供 `ctx.storage` |

---

## 配置

`Config` schema 校验以下字段：

| 字段 | 默认值 | 说明 |
|-------|---------|-------------|
| `type` | — | `'file'`（本地）或 `'s3'` |
| `endPointForUser` | `'/fs/'` | 面向用户的文件访问 URL 前缀 |
| `endPointForJudge` | `'/fs/'` | 面向判题机的文件访问 URL 前缀 |

**本地模式（`type: 'file'`）**：

| 字段 | 默认值 | 说明 |
|-------|---------|-------------|
| `path` | `/data/file/hydro` | 本地存储目录 |
| `secret` | `nanoid()` | 签名链接的 HMAC 密钥 |

**S3 模式（`type: 's3'`）**：

| 字段 | 默认值 | 说明 |
|-------|---------|-------------|
| `endPoint` | — | S3 端点 URL |
| `accessKey` | — | Access Key ID |
| `secretKey` | — | Secret Access Key |
| `bucket` | `'hydro'` | 存储桶名称 |
| `region` | `'us-east-1'` | 区域 |
| `pathStyle` | `true` | 使用路径风格寻址 |

---

## 备注

- `ctx.storage` 在启动时通过 `ctx.provide('storage', service)` 提供。
- 两个后端均校验路径以防止遍历攻击（`..`）、双斜杠（`//`）和尾部 `/.`。
- `apply` 函数注册 `/fs/` 代理路由用于直接文件访问。
- 备用端点允许通过不同 URL（CDN、内网等）路由用户/判题机的文件流量。

---

## 工具 (Backend)

### 工具库

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/lib/

```ts
import { nanoid, moment, buildContent, definePlugin, _, Schema, ObjectId, ... } from 'hydrooj'
```

# 工具库

插件开发者可用的各种工具函数和重新导出的第三方模块。

---

## 核心重新导出（libs.ts）

`libs.ts` 通过 `export *` 和具名导出提供了大量核心依赖的统一入口：

### 传递模块导出

| 模块 | 说明 |
|------|------|
| `./interface` | 所有接口类型定义（`export *`） |
| `./typeutils` | 类型工具函数（`export *`） |
| `./utils` | 通用工具函数（`export *`） |

### 第三方依赖重新导出

| 导出名 | 来源 | 说明 |
|--------|------|------|
| `_` | `lodash` | Lodash 工具库 |
| `ObjectID` | `mongodb`（别名） | MongoDB `ObjectId` 的别名 |
| `ObjectId` | `mongodb` | MongoDB ObjectId 类 |
| `Filter` | `mongodb` | MongoDB 查询过滤器类型 |
| `Schema` | `schemastery` | Schema 验证库 |
| `superagent` | `superagent` | HTTP 请求库 |
| `Zip` | `@zip.js/zip.js` | ZIP 文件处理库 |
| `AdmZip` | `adm-zip` | **@deprecated** 请使用 `Zip` 代替 |
| `WebSocket` | `@hydrooj/framework` | WebSocket 类 |
| `WebSocketServer` | `@hydrooj/framework` | WebSocket 服务器类 |

### definePlugin

```typescript
function definePlugin<T = never>(args: {
  inject?: keyof Context[] | Record<keyof Context, any>;
  apply: (ctx: Context, config: T) => Promise<void> | void;
  schema?: Schema<T>;
  name?: string;
  Config?: Schema<T>;
}): typeof args
```

插件定义辅助函数。接受插件配置并原样返回，用于获得类型推断支持。

**参数**：
- `inject` — 依赖注入声明，指定插件需要的服务。
- `apply` — 插件主函数，接收 `Context` 和配置对象。
- `schema` / `Config` — 插件配置的 Schema 验证定义（两者等效）。
- `name` — 插件名称。

---

## 工具库函数

以下函数来自 `packages/hydrooj/src/lib/` 目录：

## 重新导出的第三方模块

### nanoid

```typescript
import { nanoid } from 'hydrooj';
```

从 [`nanoid`](https://github.com/ai/nanoid) 包重新导出。生成唯一的 URL 友好字符串 ID。内部用于生成令牌 ID、存储键和其他随机标识符。

### moment

```typescript
import { moment } from 'hydrooj';
```

作为 `moment-timezone` 的默认导出重新导出。支持完整时区的日期/时间操作库。请使用此模块而非裸 `moment` 以获取时区感知的日期处理。

### isMoment

```typescript
import { isMoment } from 'hydrooj';
```

从 `moment-timezone` 重新导出。类型守卫函数，当给定值为 Moment.js 对象时返回 `true`。

---

## 内容构建

### buildContent

```typescript
function buildContent(
  source: ProblemSource,
  type?: 'markdown' | 'html',
  translate?: (s: string) => string
): string
```

将结构化的题目描述对象转换为格式化的 markdown 或 HTML 字符串。各节（背景、描述、输入、输出、提示、来源）使用适当的标题渲染。样例输入/输出格式化为围栏代码块（markdown）或 `<pre><code>` 块（HTML）。

**参数**：
- `source` — 具有可选字段的对象：`background`、`description`、`input`、`output`、`samples`、`samplesRaw`、`hint`、`source`。也接受旧版数组格式以向后兼容。
- `type` — 输出格式，默认 `'markdown'`。
- `translate` — 可选的翻译函数，应用于节标题（如将 `"Background"` 翻译为本地化文本）。

---

## MIME 类型检测

### mime

```typescript
function mime(file: string): string
```

返回给定文件名的 MIME 类型。`.in`、`.out`、`.ans` 扩展名特殊处理为 `'text/plain'`（竞赛编程中常见）。回退到 `mime-types` 查找，最后为 `'application/octet-stream'`。

---

## 难度计算

### difficultyAlgorithm

```typescript
function difficultyAlgorithm(nSubmit: number, nAccept: number): number | null
```

根据提交数和通过数计算题目难度分数（1-10）。使用对数正态概率密度函数的数值积分，按通过率加权。当 `nSubmit` 为 0 时返回 `null`。

---

## Rating 计算

### rating

```typescript
function rating(users: RatingInputUser[]): RatingOutputUser[]
```

实现 Codeforces 风格的 Elo 评分系统。接收包含 `old` 评分、`rank` 和 `uid` 的用户数组，返回比赛后的新评分。处理种子计算、增量标准化和反膨胀调整。

**类型**：

```typescript
interface RatingInputUser {
  old: number;   // 原评分
  uid: number;   // 用户标识
  rank: number;  // 比赛排名（从 1 开始）
}

interface RatingOutputUser {
  new: number;   // 更新后的评分
  uid: number;   // 用户标识
}
```

---

## 头像 URL 生成

### avatar

```typescript
function avatar(src: string, size?: number, fallback?: string): string
```

从带有提供者前缀的标识字符串（如 `"gravatar:user@example.com"`、`"qq:12345"`、`"github:username"`、`"url:https://..."`）生成头像 URL。当提供者未知或字符串无法解析时，回退到使用空邮箱的 Gravatar。

**参数**：
- `src` — 带提供者前缀的标识符（格式：`"provider:value"`）。
- `size` — 请求的图片尺寸（像素），默认 `64`。
- `fallback` — 当主地址为空或无法解析时使用的备选 `src`。

**内置提供者**：

| 提供者    | 格式                 | 说明                              |
|-----------|----------------------|-----------------------------------|
| `gravatar` | `gravatar:email`    | 通过 MD5 邮箱哈希的 Gravatar 头像 |
| `qq`      | `qq:QQ号`           | 通过 q1.qlogo.cn 的 QQ 头像      |
| `github`  | `github:username`   | GitHub 头像                       |
| `url`     | `url:https://...`   | 直接 URL 透传                     |

---

## 题目配置解析

### testdataConfig

```typescript
function testdataConfig(
  config: string | ProblemConfigFile = {},
  files: string[]
): Promise<ProblemConfig>
```

将题目配置（YAML 字符串或预解析对象）和测试用例文件名列表解析为汇总的 `ProblemConfig` 对象。计算所有子任务的聚合时间/内存限制，统计测试点数量，并提取 `type`、`hackable`、`langs`、`redirect` 等元数据。

**备注**：在 Hydro 插件 API 中以 `testdataConfig` 导出（从内部 `parseConfig` 函数名别名而来）。

---

## 邮件

### sendMail

```typescript
function sendMail(
  to: string,
  subject: string,
  text: string,
  html: string
): Promise<any>
```

使用系统配置中的 SMTP 设置（`smtp.host`、`smtp.port`、`smtp.secure`、`smtp.user`、`smtp.pass`、`smtp.from`）发送邮件。内部使用 `nodemailer`。失败时抛出 `SendMailError`。

---

## 密码哈希

### pwsh

```typescript
function pwsh(password: string, salt: string): Promise<string>
```

使用给定盐值对密码进行 PBKDF2 哈希（SHA-256、100,000 次迭代、64 字节密钥）。返回派生密钥的前 64 个十六进制字符。在模块加载时注册为 `global.Hydro.module.hash.hydro`。

---

## UI 上下文

### UiContextBase

```typescript
interface UiContextBase {
  cdn_prefix: string;
  cdn_dynamic: boolean;
  url_prefix: string;
  ws_prefix: string;
}
```

提供默认 CDN、URL 和 WebSocket 前缀值的常量对象。用作基础模板，在每次请求时根据特定域的覆盖（CDN URL、WebSocket 前缀、域信息）进行扩展。

### pipelineUtils

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/hydrooj/src/pipelineUtils.ts

```ts
import { iterateAllDomain, iterateAllUser, ... } from 'hydrooj'
```

# pipelineUtils

批量迭代工具，用于遍历系统中给定类型的所有文档。适用于迁移脚本、批量数据处理和后台维护任务。

所有函数**顺序**处理文档（逐个处理），完成时返回 `Promise<true>`。

---

## 函数

### iterateAllDomain

```typescript
iterateAllDomain(
  cb: (ddoc: DomainDoc, current?: number, total?: number) => Promise<any>
): Promise<true>
```

加载所有域并逐一调用回调。提供 `current`（从 0 开始的索引）和 `total` 进度计数器。

### iterateAllUser

```typescript
iterateAllUser(
  cb: (udoc: Udoc, current?: number, total?: number) => Promise<any>
): Promise<true>
```

加载所有用户并逐一调用回调。提供 `current`（从 0 开始的索引）和 `total` 进度计数器。

### iterateAllContest

```typescript
iterateAllContest(
  cb: (tdoc: Tdoc) => Promise<any>
): Promise<true>
```

迭代所有域，再迭代每个域中的所有比赛。**不**提供进度计数器。

### iterateAllPsdoc

```typescript
iterateAllPsdoc(
  filter: Filter<ProblemStatusDoc>,
  cb: (psdoc: ProblemStatusDoc) => Promise<any>
): Promise<true>
```

迭代所有域，再迭代每个域中匹配 `filter` 的所有题目状态文档（docType 为 `TYPE_PROBLEM`）。使用基于游标的迭代。

### iterateAllProblemInDomain

```typescript
iterateAllProblemInDomain(
  domainId: string,
  fields: (Field | string)[],
  cb: (pdoc: PartialProblemDoc, current?: number, total?: number) => Promise<any>
): Promise<true>
```

迭代单个域中的所有题目，仅获取指定的 `fields`。自动注入 `domainId` 和 `docId` 到字段列表中。

如果回调返回真值，则通过 `problem.edit()` **自动更新**该文档。这支持在迭代期间就地修改文档。提供从 1 开始的 `current` 和 `total` 进度计数器。

### iterateAllProblem

```typescript
iterateAllProblem(
  fields: (Field | string)[],
  cb: (pdoc: PartialProblemDoc, current?: number, total?: number) => Promise<any>
): Promise<true>
```

迭代所有域，再迭代每个域中的所有题目。字段投影和自动编辑行为与 `iterateAllProblemInDomain` 相同。

### iterateAllRecord

```typescript
iterateAllRecord(
  cb: (rdoc: RecordDoc, current: number, total: number) => any
): Promise<true>
```

迭代系统中的**所有**评测记录，按 `_id` 升序排列。与其他函数不同，回调签名中 `current` 和 `total` 是必需的（非可选）。使用基于游标的迭代。

---

## 类型

```typescript
interface PartialProblemDoc extends ProblemDoc {
    [key: string]: any;
}
```

`ProblemDoc` 的宽松版本，在通过 `iterateAllProblemInDomain` / `iterateAllProblem` 投影特定字段时使用。

---

## 备注

- 所有函数在迭代前会将完整结果集加载到内存中（`iterateAllPsdoc` 和 `iterateAllRecord` 除外，它们使用游标）。对于非常大的集合，需注意内存使用。
- `iterateAllProblemInDomain` 是唯一支持就地文档修改的函数 — 回调返回真值会触发自动 `problem.edit()` 调用。
- `iterateAllContest`、`iterateAllPsdoc` 和 `iterateAllProblem` 是组合迭代器，以 `iterateAllDomain` 作为外层循环嵌套。

---

## Other

### index



---

## 子组件

### AutoComplete 组件

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/components/autocomplete/

```ts
import { AutoComplete } from '@hydrooj/ui-default'
```

# AutoComplete 组件

Source: `packages/ui-default/components/autocomplete/`

基于 DOM 的自动完成组件族，绑定到 `<input>` 元素并渲染 React 下拉选择器。所有子类继承自 `AutoComplete` 基类，通过 `DOMAttachedObject` 模式挂载到页面 DOM。

## 基类

### AutoComplete

Source: `packages/ui-default/components/autocomplete/index.tsx`

通用自动完成基类，将一个 `<input>` DOM 元素包装为带下拉建议列表的选择器。内部使用 `@hydrooj/components` 的 `AutoComplete` React 组件进行渲染。

```ts
class AutoComplete<Options extends Record<string, any> = object, Multi extends boolean = boolean> extends DOMAttachedObject
```

- `DOMAttachKey`: `ucwAutoCompleteInstance`

**构造参数：**
- `$dom` — 要绑定的 jQuery DOM 元素（通常是 `<input>`）
- `options` — 配置选项（见 `AutoCompleteOptions`）

**AutoCompleteOptions 接口：**

| 属性 | 类型 | 说明 |
|------|------|------|
| `multi` | `boolean` | 是否允许多选 |
| `defaultItems` | `string` | 默认选中的项（逗号分隔） |
| `width` | `string` | 组件宽度 |
| `height` | `string` | 组件高度 |
| `classes` | `string` | 附加的 CSS 类名 |
| `listStyle` | `any` | 下拉列表样式 |
| `allowEmptyQuery` | `boolean` | 是否允许空查询触发搜索 |
| `freeSolo` | `boolean` | 是否允许自由输入（不在列表中的值） |
| `freeSoloConverter` | `any` | 自由输入值的转换函数 |
| `onChange` | `(value) => any` | 选中值变化时的回调 |
| `items` | `() => Promise<any[]>` | 异步获取候选项列表 |
| `render` | `() => string` | 自定义候选项渲染 |
| `text` | `() => string` | 自定义选中项文本 |

> **构造函数额外参数**：`component`（`React.ComponentType<any>`，自定义 React 组件覆盖默认）和 `props`（`Record<string, any>`，传递给 React 组件的额外属性）通过交叉类型传入，不属于 `AutoCompleteOptions` 接口。

**实例方法：**

| 方法 | 说明 |
|------|------|
| `clear(clearValue?: boolean)` | 清除选中值或仅关闭下拉列表 |
| `onChange(val)` | 设置值或注册变化监听器 |
| `attach()` | 挂载 React 组件到 DOM |
| `open()` | 打开下拉建议列表 |
| `close()` | 关闭下拉建议列表 |
| `value()` | 获取当前选中值：单选模式返回首个选中项对象（或 `null`），多选模式返回 `(string \| number)[]` |
| `detach()` | 卸载组件并清理 DOM |
| `focus()` | 聚焦输入框 |

## 子类组件

### AssignSelectAutoComplete

Source: `packages/ui-default/components/autocomplete/AssignSelectAutoComplete.tsx`

题目评测者/管理员分配选择器，默认多选模式。用于比赛或作业中将用户分配为评测者或管理员。

```ts
class AssignSelectAutoComplete<Multi extends boolean> extends AutoComplete
```

- `DOMAttachKey`: `ucwAssignSelectAutoCompleteInstance`
- 默认 `multi: true`，`value()` 返回逗号分隔的选中键字符串

### CustomSelectAutoComplete

Source: `packages/ui-default/components/autocomplete/CustomSelectAutoComplete.tsx`

自定义数据源的下拉选择器，调用方通过 `data` 选项直接提供候选项列表。

```ts
class CustomSelectAutoComplete<Multi extends boolean> extends AutoComplete<CustomSelectOptions>
```

- `DOMAttachKey`: `ucwCustomSelectAutoCompleteInstance`
- 额外选项 `data: any[]` — 静态候选项数据

### DomainSelectAutoComplete

Source: `packages/ui-default/components/autocomplete/DomainSelectAutoComplete.tsx`

域名（站点）选择器，用于在多个 Hydro 站点/域之间切换选择。

```ts
class DomainSelectAutoComplete<Multi extends boolean> extends AutoComplete
```

- `DOMAttachKey`: `ucwDomainSelectAutoCompleteInstance`
- 默认高度 `34px`

### ProblemSelectAutoComplete

Source: `packages/ui-default/components/autocomplete/ProblemSelectAutoComplete.tsx`

题目选择器，用于搜索和选择题库中的题目。

```ts
class ProblemSelectAutoComplete extends AutoComplete
```

- `DOMAttachKey`: `ucwProblemSelectAutoCompleteInstance`

### UserSelectAutoComplete

Source: `packages/ui-default/components/autocomplete/UserSelectAutoComplete.tsx`

用户选择器，用于搜索和选择系统用户。

```ts
class UserSelectAutoComplete<Multi extends boolean> extends AutoComplete
```

- `DOMAttachKey`: `ucwUserSelectAutoCompleteInstance`
- `value()` 在多选模式下返回 `number[]`（用户 ID 数组），单选模式返回首个选中用户对象（或 `null`）

### FileSelectAutoComplete

Source: `packages/ui-default/components/autocomplete/FileSelectAutoComplete.tsx`

文件选择器，从给定文件列表中选择文件。

```ts
class FileSelectAutoComplete<Multi extends boolean> extends AutoComplete<FileSelectOptions>
```

- `DOMAttachKey`: `ucwFileSelectAutoCompleteInstance`
- 额外选项 `data: { id: string; name: string }[]` — 文件列表

### LanguageSelectAutoComplete

Source: `packages/ui-default/components/autocomplete/LanguageSelectAutoComplete.tsx`

编程语言选择器，用于选择题目的提交语言。

```ts
class LanguageSelectAutoComplete<Multi extends boolean> extends AutoComplete<LanguageSelectOptions>
```

- `DOMAttachKey`: `ucwLanguageSelectAutoCompleteInstance`
- 额外选项 `withAuto: boolean` — 是否包含"自动"选项

### loadMonaco

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/components/monaco/loader.ts

# loadMonaco

源码: [`packages/ui-default/components/monaco/loader.ts`](https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/components/monaco/loader.ts)

按需加载 Monaco 编辑器，支持可选语言特性和插件扩展。对并发的加载调用进行序列化以避免重复初始化。

## 函数

### load

```ts
async function load(features?: string[]): Promise<{
  monaco: typeof import('monaco-editor/esm/vs/editor/editor.api');
  registerAction: (editor: monaco.editor.IStandaloneCodeEditor, model: monaco.editor.IModel, element?: HTMLElement) => Promise<any> | null;
  customOptions: monaco.editor.IStandaloneDiffEditorConstructionOptions;
  renderMarkdown: typeof import('monaco-editor/esm/vs/base/browser/markdownRenderer').renderMarkdown;
}>
```

默认导出，从插件 API 以 `loadMonaco` 名称重新导出。加载 Monaco 编辑器及指定特性。特性仅加载一次；后续调用中已加载的特性会被跳过。

**参数:**
- `features`（默认 `['markdown']`）— 要加载的特性名称数组。内置特性：`'markdown'`、`'typescript'`、`'yaml'`。插件贡献的特性通过 `getFeatures('monaco-{feat}')` 解析。

**行为:**
1. 通过内部 Promise 链序列化并发调用。
2. 首次调用时加载 i18n 语言数据（支持 zh、zh_TW、ko）。
3. 动态导入 `./index`（Monaco 编辑器模块）。
4. 遍历 `features`，通过内置加载器或外部插件加载器逐个加载。
5. 等待主题加载完成。
6. 返回 Monaco 实例及辅助工具。

**返回值:**
- `monaco` — 完整的 Monaco 编辑器 API 模块。
- `registerAction` — 在编辑器实例上注册键盘快捷键（Ctrl+Enter 提交、Ctrl+Shift+P 命令面板、Alt+Shift+F 格式化）。同时在 markdown 模式下启用图片/zip 粘贴上传。
- `customOptions` — 从 `localStorage('editor.config')` 读取的持久化编辑器配置。可变；更改通过 `saveCustomOptions()` 保存。
- `renderMarkdown` — 从 `monaco-editor/esm/vs/base/browser/markdownRenderer` 重新导出。

## 函数（已弃用）

### legacyLoadExternalModule

```ts
async function legacyLoadExternalModule(target: string): Promise<any>
```

**@deprecated** 通过向 `<head>` 注入 `<script>` 元素加载外部脚本。结果缓存在 `window.exports` 中。供外部特性加载器内部使用，用于基于 URL 的插件脚本。

## 内置特性加载器

| 特性 | 说明 |
|---------|-------------|
| `i18n` | 加载 Monaco UI 翻译的语言数据（zh、zh_TW、ko）。首次 `load()` 调用时自动加载。 |
| `markdown` | 导入 `./languages/markdown` 提供 Markdown 语法支持。 |
| `typescript` | 导入 `./languages/typescript` 并调用 `loadTypes()` 提供 TypeScript/JavaScript 支持。 |
| `yaml` | 导入 `./languages/yaml` 提供 YAML 语法支持。 |
| `external` | 通过 `getFeatures('monaco-{feat}')` 加载插件贡献的特性。每个条目可以是函数、URL 字符串或模块路径。 |

### download / ZipDownloader

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/components/zipDownloader/index.ts

```ts
import { download, ZipDownloader } from '@hydrooj/ui-default'
```

# download / ZipDownloader

源码: [`packages/ui-default/components/zipDownloader/index.ts`](https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/components/zipDownloader/index.ts)

使用 `streamsaver` 创建并流式传输 ZIP 压缩包到浏览器，支持并发文件下载和重试逻辑。

## 函数

### download

```ts
async function download(
  filename: string,
  targets: { filename: string; url?: string; content?: string }[]
): Promise<void>
```

下载包含给定目标文件的 ZIP 压缩包。使用 `streamsaver` 将 ZIP 直接流式写入磁盘，无需将整个压缩包保存在内存中。文件以并发方式获取（最多 5 个并行），失败时自动重试。

**参数:**
- `filename` — 生成的 ZIP 文件名（如 `"Export.zip"`）。
- `targets` — 要包含的文件数组。每个目标必须包含 `filename` 以及 `url`（要获取的远程文件）或 `content`（内存中的字符串）之一。

**行为:**
1. 确保浏览器有 `WritableStream`（必要时加载 polyfill）。
2. 通过 `streamsaver.createWriteStream` 创建写入流。
3. 以并发数 5 排队所有文件下载。每个失败的下载最多重试 5 次，间隔 3 秒。
4. 将 ZIP 流（通过 `createZipStream`）管道传输到文件流。
5. 下载期间通过 `beforeunload` / `unload` 监听器阻止浏览器关闭。
6. 遇到不可恢复的错误时：记录到 Sentry，停止下载，显示错误通知。

### downloadProblemSet

```ts
async function downloadProblemSet(
  pids: number[],
  name?: string
): Promise<void>
```

将一个或多个题目导出为 ZIP 压缩包。收集题目元数据、内容、测试数据和附加文件，然后委托给 `download`。触发 `problemset/download` 生命周期钩子，以便插件注入额外文件。

**参数:**
- `pids` — 要导出的题目数字 ID 数组。
- `name`（默认 `"Export"`）— ZIP 文件的基本名称（变为 `{name}.zip`）。

**行为:**
1. 触发 `ctx.serial('problemset/download', pids, name, targets)` — 插件可推送额外目标。
2. 对每个题目：
   - 通过 `api('problem', ...)` 获取题目元数据并序列化为 `problem.yaml`。
   - 解析内容：若为 JSON 对象，将每个键拆分为 `problem_{key}.md`；否则写入 `problem.md`。
   - 获取测试数据和附加文件的签名下载链接。
3. 调用 `download(name + '.zip', targets)` 流式输出 ZIP。
4. 出错时：记录到 Sentry 并显示错误通知。

## EventMap 扩展

模块在前端 `EventMap` 上声明了 `problemset/download` 事件：

```ts
interface EventMap {
  'problemset/download': (
    pids: number[],
    name: string,
    targets: { filename: string; url?: string; content?: string }[]
  ) => void;
}
```

插件可通过 `ctx.on('problemset/download', ...)` 监听，在下载开始前向 ZIP 注入额外文件。

---

## UI 组件

### 前端插件系统核心

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/context.ts

```ts
import { Context, ctx, Service } from '@hydrooj/ui-default'
```

# 前端插件系统核心

源码: [`packages/ui-default/context.ts`](https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/context.ts)、[`packages/ui-default/api.ts`](https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/api.ts)

前端插件系统基于 [Cordis](https://github.com/shigma/cordis)，与 Hydro 后端使用的插件框架相同。本页文档化前端插件可用的核心类型和全局上下文实例。

## 导出

### Context

```ts
class Context extends cordis.Context { }
```

核心插件上下文。前端插件接收一个 `Context` 实例用于注册生命周期钩子、服务和事件监听器。继承自 `cordis.Context`，未添加额外方法 —— 所有功能来自 Cordis 基类。

上下文有一个 `broadcast` 属性别名指向 `emit`，为广播事件到所有监听器提供了语义化的简写。

### ctx

```ts
const ctx: Context
```

全局前端插件上下文单例。在模块加载时以 `new Context()` 创建。导入并使用它来在前端注册插件、监听事件和访问服务。

用法示例：
```ts
import { ctx } from '@hydrooj/ui-default';

ctx.on('some-event', (payload) => { /* handle */ });
```

### Service

```ts
class Service<C extends Context = Context> extends cordis.Service<C> { }
```

前端服务的基类。继承自 `cordis.Service`，未添加额外方法。插件通过子类化 `Service` 来提供可通过 Cordis 依赖注入使用的可复用功能。

### EventMap

```ts
interface EventMap { }
```

空接口，作为前端事件类型声明的扩展点。插件可通过 TypeScript 声明合并添加自定义事件签名：

```ts
declare module '@hydrooj/ui-default' {
  interface EventMap {
    'my-plugin/event': (data: MyData) => void
  }
}
```

### Events

```ts
interface Events<C extends Context = Context> extends cordis.Events<C>, EventMap { }
```

组合事件接口，合并了 Cordis 内置事件与 Hydro 前端 `EventMap`。可通过 `Context[Context.events]` 访问。

### Fiber

```ts
type Fiber = cordis.Fiber<Context>
```

以 Hydro 的 `Context` 参数化的 Cordis Fiber 类型别名。表示插件在上下文树中的生命周期作用域。

### Disposable

```ts
type Disposable = cordis.Disposable
```

从 Cordis 重新导出。由注册方法（如 `ctx.on()`、`ctx.effect()`）返回的清理函数。调用它可移除已注册的资源。

### FiberState

```ts
type FiberState = cordis.FiberState
```

从 Cordis 重新导出。表示 Fiber 的生命周期状态（如 `active`、`disposed`）。

### Plugin

```ts
type Plugin = cordis.Plugin
```

从 Cordis 重新导出。使用 `ctx.plugin()` 定义和注册插件时的插件描述符类型。

## 架构说明

- `context.ts` 定义了 Cordis 基础原语的 Hydro 特定子类/包装器，而所有实际的插件功能（生命周期钩子、依赖注入、事件系统）来自 Cordis 基类。
- `api.ts` 从 `context.ts` 重新导出 `Context`、`ctx` 和 `Service`，使其作为 `@hydrooj/ui-default` 公开 API 的一部分可用。
- `EventMap` 在 `api.ts` 中声明为空，设计为通过 TypeScript 声明合并由插件扩展。
- 前端 `Context` 与后端 `Context` 是独立的实例 —— 它们共享相同的 Cordis 架构，但运行在不同环境中（浏览器 vs Node.js）。

### 对话框系统

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/components/dialog/index.tsx

```ts
import { Dialog, InfoDialog, ActionDialog, ConfirmDialog, prompt, confirm, alert } from '@hydrooj/ui-default'
```

# 对话框系统

源码: [`packages/ui-default/components/dialog/index.tsx`](https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/components/dialog/index.tsx)、[`packages/ui-default/components/dialog/DomDialog.ts`](https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/components/dialog/DomDialog.ts)

对话框系统提供模态覆盖层用于用户交互 —— 从简单提示到复杂的多字段表单。基于 jQuery DOM 操作构建，表单内容使用 React 渲染。

## 类

### Dialog

```ts
class Dialog
```

基础模态对话框。构造一个基于 jQuery 的覆盖层，包含主体区域和操作按钮栏。包装 `DomDialog` 实现显示/隐藏动画和操作分发。

**属性:** `options`（DialogOptions）、`$dom`（JQuery）、`domDialogInstance`（DomDialog）

**方法:**
- `open()` — 显示对话框；返回 `Promise<string>`，在操作名称（如 `"ok"`、`"cancel"`）上 resolve。
- `close()` — 隐藏对话框。

### InfoDialog

```ts
class InfoDialog extends Dialog
```

预配置了 "Ok" 按钮的 `Dialog`。支持通过点击背景和 Escape 键关闭。

### ActionDialog

```ts
class ActionDialog extends Dialog
```

预配置了 "Cancel" 和 "Ok" 按钮的 `Dialog`。支持通过点击背景和 Escape 键关闭。包含 `clear()` 方法，重置所有输入值。

### ConfirmDialog

```ts
class ConfirmDialog extends Dialog
```

预配置了 "No" 和 "Yes" 按钮的 `Dialog`。当 `options.canCancel` 为 true 时，增加 "Cancel" 按钮并启用背景/Escape 关闭。

## 函数

### prompt

```ts
async function prompt<T extends string, R extends Record<T, Field>>(
  title: string, fields: R, options?: PromptOptions
): Promise<Result<T, R> | null>
```

显示包含给定字段的模态表单。返回将字段名映射到值的类型化对象，取消时返回 `null`。接受前会校验 `required` 字段。

### confirm

```ts
async function confirm(text: string): Promise<boolean>
```

显示包含给定消息的 `ConfirmDialog`。点击 "Yes" 返回 `true`，否则返回 `false`。

### alert

```ts
async function alert(text: string): Promise<string>
```

显示包含给定消息的 `InfoDialog`。关闭时以操作字符串 resolve。

## 接口

### Field

```ts
interface Field {
  type: 'text' | 'checkbox' | 'user' | 'userId' | 'username' | 'domain';
  options?: string[] | Record<string, string>;
  placeholder?: string;
  label?: string;
  autofocus?: boolean;
  required?: boolean;
  default?: string;
  columns?: number;  // 网格列宽；负值触发换行
}
```

描述 `prompt()` 的单个表单字段。`type` 同时决定 UI 控件和结果对象中的返回类型：

| type | 控件 | 结果类型 |
|------|--------|-------------|
| `'text'` | 文本输入 / 下拉选择（有 `options` 时） | `string` |
| `'checkbox'` | 复选框 | `boolean` |
| `'user'` | 用户自动补全 | `any`（用户对象） |
| `'userId'` | 用户自动补全 | `number` |
| `'username'` | 用户自动补全 | `string` |
| `'domain'` | 域自动补全 | `string` |

### DialogOptions

```ts
interface DialogOptions {
  classes: string;
  $body: HTMLElement | JQuery<HTMLElement> | string;
  $action: any;
  width?: string;
  height?: string;
  cancelByClickingBack?: boolean;
  cancelByEsc?: boolean;
  canCancel?: boolean;
  onDispatch?: (data: any) => any;
}
```

所有对话框类的配置。`onDispatch` 返回 `false` 可阻止对话框关闭。

### 懒加载系统

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/lazyload.ts

```ts
import { load, getFeatures, loadFeatures, provideFeature } from '@hydrooj/ui-default'
```

# 懒加载系统

源码: [`packages/ui-default/lazyload.ts`](https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/lazyload.ts)

前端模块懒加载系统，用于动态加载脚本和管理插件贡献的特性。支持内置懒加载模块（通过脚本注入）和外部注册的特性。

## 函数

### load

```ts
async function load(name: string): Promise<any>
```

默认导出。通过注入 `<script>` 标签并等待模块的解析回调来动态加载懒加载模块。对 `'echarts'` 和 `'moment'` 做特殊处理，使用原生动态导入。对相同名称的后续调用返回缓存结果。

**参数:**
- `name` — 要加载的模块名称。必须存在于 `window.lazyloadMetadata` 中（格式为 `{name}.lazy.js`），或是特殊情况之一（`'echarts'`、`'moment'`）。

**行为:**
1. 检查特殊情况（`echarts`、`moment`）— 直接使用 `import()`。
2. 验证模块存在于 `window.lazyloadMetadata` 中。
3. 若已在加载/已加载，从 `lazyModules[name]` 返回缓存的 Promise。
4. 创建 `<script>` 元素，指向 `{host}lazy/{hash}/{name}.lazy.js`（若配置了 CDN 则使用 CDN）。
5. 在 `window.lazyModuleResolver[name]` 中注册解析器以 resolve 该 Promise。
6. 设置 30 秒超时，超时则 reject。
7. 将脚本追加到 `document.body`。

### getFeatures

```ts
async function getFeatures(name: string): Promise<(string | (() => Promise<any>))[]>
```

收集匹配给定名称的所有已注册特性（包括带版本号的变体如 `name@version`）。同时搜索插件注册的 `features` 映射和旧的 `window.externalModules`。返回合并后的特性条目数组（函数或 URL 字符串）。

**参数:**
- `name` — 要查询的特性名称。匹配精确名称及任何 `name@...` 变体。

### loadFeatures

```ts
async function loadFeatures(name: string, ...args: any[]): Promise<void>
```

加载并应用注册在给定名称下的所有特性。每个特性名称仅尝试加载一次——名称在加载开始前即标记到 `loaded` 数组中，因此即使加载失败也不会重试。每个特性条目根据其类型以不同方式解析：

- **函数** — 直接以 `...args` 调用。
- **URL 字符串**（以 `http` 或 `/` 开头）— 通过 `legacyLoadExternalModule` 加载，然后调用已解析模块的 `apply` 或 `default` 函数。
- **模块路径字符串** — 通过 `load()` 加载，然后调用模块的 `apply` 或 `default.apply` 函数。

**参数:**
- `name` — 要加载的特性名称。
- `...args` — 转发给每个特性 apply 函数的参数。

### provideFeature

```ts
function provideFeature(name: string, content: string | (() => Promise<any>)): void
```

注册一个特性，后续可通过 `loadFeatures()` 加载。若特性名称已注册或已加载，则在控制台发出警告。

**参数:**
- `name` — 特性名称。可包含版本后缀（如 `'markdown@2'`）。
- `content` — 返回 Promise 的函数，或 URL/模块路径字符串。

## 属性

### loaded

```ts
const loaded: string[]
```

导出数组，跟踪已被 `loadFeatures()` 加载的特性名称。内部用于幂等检查 —— 一旦名称出现在此数组中，`loadFeatures()` 在后续调用中会跳过它。

### Notification, Rotator & selectUser

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/components/notification/index.ts

```ts
import { Notification, Rotator, selectUser } from '@hydrooj/ui-default'
```

# Notification, Rotator & selectUser

源码: [`packages/ui-default/components/notification/index.ts`](https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/components/notification/index.ts)、[`packages/ui-default/components/rotator/index.js`](https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/components/rotator/index.js)、[`packages/ui-default/components/selectUser.tsx`](https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/components/selectUser.tsx)

三个 UI 工具：Toast 样式通知、动画数字翻转器、用户选择对话框。

---

## Notification

```ts
class Notification
```

双模式通知系统。静态方法（`success`、`info`、`warn`、`error`）渲染 Mantine Toast 通知。构造函数创建旧版基于 jQuery 的通知，支持可选头像、标题和点击动作。

### 静态方法（Mantine Toast）

| 方法 | 签名 | 说明 |
|--------|-----------|-------------|
| `success` | `(message: string, duration?: number) => string` | 显示带勾选图标的绿色成功 Toast。 |
| `info` | `(message: string, duration?: number) => string` | 显示带信息图标的蓝色提示 Toast。 |
| `warn` | `(message: string, duration?: number) => string` | 显示带警告图标的橙色警告 Toast。 |
| `error` | `(message: string, duration?: number) => string` | 显示带关闭图标的红色错误 Toast。 |

所有静态方法委托给 `@mantine/notifications`，返回通知 `id`。

### 实例 API（旧版 jQuery 通知）

**构造函数:** `new Notification(options: NotificationOptions)`

```ts
interface NotificationOptions {
  avatar?: string;    // 头像图片 URL
  title?: string;     // 通知标题
  message: string;    // 正文内容（换行符转换为 <p> 元素）
  type?: string;      // 追加到通知元素的 CSS 类后缀
  duration?: number;  // 自动隐藏延迟（毫秒，默认 3000）
  action?: any;       // 点击回调（默认空操作）
}
```

**方法:**

| 方法 | 签名 | 说明 |
|--------|-----------|-------------|
| `show` | `(autohide?: boolean) => void` | 显示通知；若 `autohide` 为 true（默认），在 `duration` 后自动隐藏。 |
| `hide` | `() => void` | 隐藏通知，200ms 过渡动画后移除 DOM 元素。 |
| `handleClick` | `() => void` | 点击时调用 `action` 回调。 |

---

## Rotator

```ts
class Rotator extends DOMAttachedObject
```

动画值显示组件，将旧值滑出、新值滑入。通过数值比较确定滑动方向 —— 较大值从下方滑入，较小值从上方滑入。

**DOM 绑定:** `data-vjRotatorInstance`（通过 `DOMAttachedObject.DOMAttachKey = 'vjRotatorInstance'`）

**构造函数:** `new Rotator($dom: JQuery)` — 读取元素的文本内容作为初始值。

**方法:**

| 方法 | 签名 | 说明 |
|--------|-----------|-------------|
| `setValue` | `(value: string) => void` | 动画过渡到新值。值未变时不执行操作。 |
| `getValue` | `() => string` | 返回当前显示的值。 |

**动画行为:** 旧元素滑动到 `pos--above` 或 `pos--below`（与进入方向相反），新元素从另一侧开始并过渡到 `pos--original`。每次过渡动画总时长 4000ms。

---

## selectUser

```ts
function selectUser(): Promise<any>
```

打开带用户自动补全字段的 `prompt` 对话框。返回选定的用户对象，对话框取消时返回 `undefined`。

同时注册为全局变量 `window.Hydro.components.selectUser`。

### initPageLoader

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/hydro.ts

```ts
import { initPageLoader } from '@hydrooj/ui-default'
```

# initPageLoader

源码：[`packages/ui-default/hydro.ts`](https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/hydro.ts)，从 [`packages/ui-default/api.ts`](https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/api.ts) 重新导出

## 函数

### initPageLoader

```ts
async function initPageLoader(): Promise<void>
```

初始化前端页面加载器：创建 `PageLoader`，从 `data-page` 属性解析当前页面名称，构建生命周期回调序列（autoload beforeLoading → 命名 beforeLoading → autoload afterLoading → 命名 afterLoading），并按顺序执行每个回调。完成后隐藏页面加载遮罩层，触发区块动画，并触发 `vjPageFullyInitialized` DOM 事件。

**行为细节：**

- **页面解析** — 读取 `document.documentElement.getAttribute('data-page')` 确定当前路由名称。
- **回调序列** — 调用 `buildSequence()` 收集具有匹配 `beforeLoading`/`afterLoading` 钩子的页面，然后按以下顺序迭代：autoload before → 命名 before → autoload after → 命名 after。
- **嵌套加载** — 每个回调接收一个 `loadPage(depth, type)` 函数，可以按模块名递归调用另一个页面的生命周期钩子，深度上限为 32。
- **错误处理** — 单个回调失败会被捕获，通过 `window.captureException?.(e)`（Sentry）报告，并以 `Notification.warn()` 通知；继续执行剩余回调。
- **性能日志** — 开发模式下，耗时 >16ms 的回调会被记录；生产环境下仅记录 >256ms 的回调。
- **加载后处理** — 所有回调完成后：隐藏 `.page-loader`，运行区块淡入动画，在 `.section` 元素上触发 `vjLayout` 事件，并在 `$(document)` 上触发 `vjPageFullyInitialized`。

## 内部辅助函数

以下函数未导出，但被 `initPageLoader` 引用：

### buildSequence

```ts
function buildSequence(pages: Page[], type: 'before' | 'after'): Array<{ page: Page; func: Callback; type: string }>
```

过滤具有 `beforeLoading` 或 `afterLoading` 钩子的页面，返回 `{ page, func, type }` 对象数组用于顺序执行。

### PageLoader (类)

源码：[`packages/ui-default/misc/PageLoader.js`](https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/misc/PageLoader.js)

```ts
class PageLoader {
  pageInstances: Page[]

  constructor()
  getAutoloadPages(): Page[]
  getNamedPage(pageName: string): Page[]
  getPage(moduleName: string): Page[]
}
```

收集所有已注册页面（通过 `require.context` 从 `pages/` 和 `components/` 目录加载的内置页面，加上 `window.Hydro.extraPages`），过滤出有效的 `Page` 实例，并立即调用纯函数入口。

| 方法 | 说明 |
|------|------|
| `getAutoloadPages()` | 返回所有 `autoload = true` 的页面实例。 |
| `getNamedPage(pageName)` | 通过 `isNameMatch()` 返回名称匹配给定路由名称的页面实例。 |
| `getPage(moduleName)` | 返回匹配给定 `moduleName` 属性的页面实例。 |

## 另见

- [页面注册系统](./page.md) — `Page`、`NamedPage`、`AutoloadPage`、`addPage()`

### 前端页面注册系统

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/misc/Page.ts

```ts
import { Page, NamedPage, AutoloadPage, addPage } from '@hydrooj/ui-default'
```

# 前端页面注册系统

源码：[`packages/ui-default/misc/Page.ts`](https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/misc/Page.ts)、[`packages/ui-default/api.ts`](https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/api.ts)

Hydro 前端使用页面注册系统来组织每个页面的初始化逻辑。插件通过 `addPage()` 注册页面实例，页面加载器在页面切换时适时调用生命周期回调（`beforeLoading`、`afterLoading`）。

## 类

### Page

```ts
class Page {
  name: string | string[];
  moduleName?: string;
  autoload: boolean;        // Page 中始终为 false
  afterLoading?: Callback;
  beforeLoading?: Callback;

  constructor(pagename: string | string[], afterLoading?: Callback, beforeLoading?: Callback);
  constructor(pagename: string | string[], moduleName: string, afterLoading?: Callback, beforeLoading?: Callback);

  isNameMatch(name: string): boolean;
}
```

所有页面注册的基类。匹配特定路由名称并提供生命周期钩子。

**构造函数参数（重载）：**

| 参数 | 类型 | 说明 |
|------|------|------|
| `pagename` | `string \| string[]` | 要匹配的页面路由名称。对应 `<html>` 上的 `data-page` 属性。 |
| `moduleName` | `string` | *（可选）* 当第二个参数为字符串类型时提供，用作 `PageLoader.getPage()` 的模块名标识符。 |
| `afterLoading` | `Callback` | 页面 DOM 加载完成后调用。 |
| `beforeLoading` | `Callback` | 页面 DOM 加载前调用。 |

构造函数会检测第二个参数是字符串（`moduleName`）还是函数（`afterLoading`），并据此解构。

**回调类型：**

```ts
type Callback = (pagename: string, loadPage: (name: string) => Promise<any>) => any;
```

- `pagename` — 当前页面的路由名称。
- `loadPage` — 按模块名动态加载另一个已注册页面的函数，支持嵌套页面加载（深度限制为 32，防止无限递归）。

**属性：**

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `name` | `string \| string[]` | *（构造函数）* | 此页面匹配的路由名称。 |
| `moduleName` | `string \| undefined` | `undefined` | 可选模块名，用于通过 `PageLoader.getPage()` 查找。 |
| `autoload` | `boolean` | `false` | 此页面的钩子是否在每条路由上运行。 |
| `afterLoading` | `Callback \| undefined` | `undefined` | 加载后生命周期钩子。 |
| `beforeLoading` | `Callback \| undefined` | `undefined` | 加载前生命周期钩子。 |

**方法：**

| 方法 | 签名 | 说明 |
|------|------|------|
| `isNameMatch` | `(name: string) => boolean` | 测试给定路由名称是否匹配此页面。字符串名称时检查严格相等；数组名称时检查包含关系。 |

### NamedPage

```ts
class NamedPage extends Page { }
```

`Page` 的空子类，无额外行为。语义上用于表示该页面是路由特定的（非自动加载）。`autoload` 始终为 `false`。

这是最常用的类 — Hydro 中大多数页面注册为 `new NamedPage(...)`。

### AutoloadPage

```ts
class AutoloadPage extends Page {
  constructor(pagename: string | string[], afterLoading?: Callback, beforeLoading?: Callback);
  constructor(pagename: string | string[], moduleName: string, afterLoading?: Callback, beforeLoading?: Callback);
}
```

继承 `Page` 并在构造函数中设置 `autoload = true`。自动加载页面的生命周期钩子在**每次**路由变更时都会调用，无论路由名称是否匹配。适用于全局页面增强（如通知、提示框、键盘快捷键）。

## 函数

### addPage

```ts
function addPage(page: Page | (() => Promise<void> | void)): void
```

向页面加载器注册页面实例或初始化函数。

- **`page: Page`** — `Page`、`NamedPage` 或 `AutoloadPage` 实例。将被 `PageLoader` 收集并与路由匹配。
- **`page: () => Promise<void> | void`** — 纯函数。在 `PageLoader` 构造时立即调用（处理完所有 `Page` 实例之后）。用于不需要路由匹配的副作用初始化。

页面存储在 `window.Hydro.extraPages` 中。`PageLoader` 构造函数将内置页面（来自 `pages/` 和 `components/` 目录）与额外页面合并，过滤出有效的 `Page` 实例，并直接调用纯函数。

## 生命周期

页面加载器在 `initPageLoader()` 期间按特定顺序运行生命周期回调：

```
1. 自动加载页面 — beforeLoading   （所有自动加载页面，按注册顺序）
2. 命名页面     — beforeLoading   （匹配当前路由的页面）
3. 自动加载页面 — afterLoading    （所有自动加载页面，按注册顺序）
4. 命名页面     — afterLoading     （匹配当前路由的页面）
```

### beforeLoading

```ts
beforeLoading?: (pagename: string, loadPage: (name: string) => Promise<any>) => any
```

在页面 DOM 内容处理**之前**调用。适用于：
- 设置全局事件监听器
- 渲染前修改 DOM
- 加载外部资源

### afterLoading

```ts
afterLoading?: (pagename: string, loadPage: (name: string) => Promise<any>) => any
```

在页面 DOM 内容可用**之后**调用。适用于：
- 为 DOM 元素绑定事件处理器
- 初始化 UI 组件
- 获取数据并更新页面

### 嵌套加载

传递给回调的 `loadPage` 参数支持递归页面加载：

```ts
new NamedPage('problem_edit', async (pagename, loadPage) => {
  // 按模块名加载另一个页面的钩子
  await loadPage('editor');
}, async (pagename, loadPage) => {
  await loadPage('editor');
});
```

深度上限为 32，防止无限递归。

## 用法示例

### 带生命周期钩子的 NamedPage

```ts
import { NamedPage } from '@hydrooj/ui-default';

export default new NamedPage('user_detail', async (pagename, loadPage) => {
  // beforeLoading — 准备数据
  console.log('Loading user page...');
}, async (pagename, loadPage) => {
  // afterLoading — 绑定 DOM
  document.querySelector('.avatar')?.addEventListener('click', handleAvatarClick);
});
```

### 匹配多个路由的 NamedPage

```ts
new NamedPage(['contest_detail', 'contest_scoreboard'], () => {
  // contest_detail 和 contest_scoreboard 页面的 beforeLoading
}, () => {
  // 两个页面的 afterLoading
});
```

### 用于全局行为的 AutoloadPage

```ts
import { AutoloadPage } from '@hydrooj/ui-default';

export default new AutoloadPage('tooltips', () => {
  // 在每个页面上运行 — 初始化提示框库
}, () => {
  // DOM 就绪后绑定提示框元素
});
```

### 通过 addPage 注册

```ts
import { addPage, AutoloadPage } from '@hydrooj/ui-default';

addPage(new AutoloadPage('my-plugin-init', () => {
  // beforeLoading — 在每个页面上运行
}, () => {
  // afterLoading — 在每个页面上运行
}));

// 或者注册一个纯初始化函数
addPage(() => {
  console.log('Plugin initialized');
});
```

### Socket (Sock)

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/components/socket/index.ts

```ts
import { Socket } from '@hydrooj/ui-default'
```

# Socket (Sock)

源码：[`packages/ui-default/components/socket/index.ts`](https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/components/socket/index.ts)

支持自动重连、心跳及可选 Shorty 压缩的 WebSocket 客户端。

---

## Sock

```ts
class Sock
```

封装 `ReconnectingWebSocket`，提供 ping/pong 心跳、Shorty 解压及基于会话的认证。

### 构造函数

**`new Sock(url: string, nocookie?: boolean, shorty?: boolean)`**

创建到 `url` 的 WebSocket 连接。URL 协议会自动从 `http`/`https` 转换为 `ws`/`wss`。如果目标主机与当前页面不同且存在 `sid` cookie，则会将会话 ID 作为查询参数附加（除非 `nocookie` 为 `true`）。如果 `shorty` 为 `true`，则发送 `shorty=on` 查询参数以请求压缩消息。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `url` | `string` | — | WebSocket 端点 URL（http/https 协议自动转换为 ws/wss） |
| `nocookie` | `boolean` | `false` | 跳过向跨域主机自动转发会话 ID |
| `shorty` | `boolean` | `false` | 请求服务器发送 Shorty 压缩消息 |

### 属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `url` | `string` | 解析后的 WebSocket URL（公开属性，通过构造函数设置） |
| `sock` | `ReconnectingWebSocket` | 底层 WebSocket 实例（自动重连，最大重试 100 次，最大延迟 10s） |
| `interval` | `NodeJS.Timeout` | 心跳定时器句柄（连接期间每 30s 发送 `"ping"`） |

### 事件回调

可赋值的函数属性 — 直接设置或通过 `on()` 设置。

| 回调 | 签名 | 说明 |
|------|------|------|
| `onopen` | `(sock: ReconnectingWebSocket) => void` | 连接建立时触发。 |
| `onclose` | `(code: number, reason: string) => void` | 连接关闭时触发。code >= 4000 会触发自动 `close()`。 |
| `onmessage` | `(message: MessageEvent, data: string) => void` | 应用层消息到达时触发（ping/pong/shorty 握手已过滤）。 |

### 方法

| 方法 | 签名 | 说明 |
|------|------|------|
| `on` | `(event: 'message' \| 'close' \| 'open', callback: (...args: any[]) => void) => void` | 注册事件回调（设置 `onmessage`、`onclose` 或 `onopen`）。 |
| `send` | `(data: any) => void` | 通过 WebSocket 发送数据。 |
| `close` | `() => void` | 关闭连接（可安全多次调用）。 |

### 内部消息处理

底层 socket 的 `onmessage` 处理器在分发给用户回调之前会处理多种协议级消息：

| 收到的消息 | 行为 |
|------------|------|
| `"pong"` | 静默消费（心跳响应）。 |
| `"ping"` | 回复 `"pong"`（服务端发起的心跳）。 |
| `"shorty"` | 为后续消息启用 Shorty 解压。 |
| `PermissionError` / `PrivilegeError` JSON | 调用 `close()` — 认证错误时终止连接。 |
| 其他所有消息 | 若 Shorty 已激活，先解压再解析为 JSON；分发给 `this.onmessage`。 |

### 第三方库重新导出

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/api.ts

```ts
import { $, _, React, ReactDOM, redux, AnsiUp } from '@hydrooj/ui-default'
```

# 第三方库重新导出

源码：[`packages/ui-default/api.ts:17-29`](https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/api.ts#L17-L29)

预打包的第三方库，由 `@hydrooj/ui-default` 重新导出，供前端插件直接使用。这些是简单的重新导出 — 没有 Hydro 特定的封装或修改。

## 导出

### $

```ts
import { $ } from '@hydrooj/ui-default';
```

重新导出 [jQuery](https://jquery.com/)（`jquery` 的默认导出）。同时注册为全局变量 `window.$` 和 `window.jQuery`（api.ts 第 59-61 行）。

### _

```ts
import { _ } from '@hydrooj/ui-default';
```

重新导出 [Lodash](https://lodash.com/)（`lodash` 的默认导出）。

### React

```ts
import { React } from '@hydrooj/ui-default';
```

重新导出 [React](https://react.dev/)（`react` 的默认导出）。

### ReactDOM

```ts
import { ReactDOM } from '@hydrooj/ui-default';
```

合并重新导出，结合 `react-dom` 和 `react-dom/client`。通过 `Object.assign` 将 `react-dom/client` 的所有导出合并到主 `react-dom` 模块上，在单个对象中同时提供旧版（`render`、`unmountComponentAtNode`）和现代（`createRoot`、`hydrateRoot`）API。

### jsxRuntime

```ts
import { jsxRuntime } from '@hydrooj/ui-default';
```

重新导出 `react/jsx-runtime` — React 使用的 JSX 转换运行时。提供 `jsx`、`jsxs` 和 `Fragment` 用于 JSX 编译。

### redux

```ts
import { redux } from '@hydrooj/ui-default';
```

通过 `export * as redux` 对 [react-redux](https://react-redux.js.org/) 进行命名空间重新导出。包含所有 react-redux 导出：`Provider`、`connect`、`useSelector`、`useDispatch`、`createSelectorHook`、`createDispatchHook` 等。

### AnsiUp

```ts
import { AnsiUp } from '@hydrooj/ui-default';
```

重新导出来自 `ansi_up` 包的 [AnsiUp](https://github.com/drudru/ansi_up)。将 ANSI 终端转义序列转换为 HTML 以便在浏览器中显示。

### uploadFiles

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/components/upload.tsx

```ts
import { uploadFiles } from '@hydrooj/ui-default'
```

# uploadFiles

源码：[`packages/ui-default/components/upload.tsx`](https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/components/upload.tsx)

将文件上传到服务器端点，带有进度对话框、浏览器关闭防护和逐文件回调。

## 函数

### uploadFiles

```ts
async function uploadFiles(
  endpoint?: string,
  files?: File[] | FileList,
  options?: UploadOptions
): Promise<void>
```

通过 `request.postFile` 将文件顺序上传到 `endpoint`。显示带有两个 `Progress` 条（总体 + 单文件）的 `Dialog`。成功或失败时显示 Toast 通知。通过 `beforeunload` 在上传期间阻止浏览器导航。

**参数：**
- `endpoint`（默认 `''`）— 接收文件 POST 请求的服务器 URL。
- `files`（默认 `[]`）— 要上传的文件。接受 `File[]` 或 `FileList`（来自 `<input>`）。
- `options` — 参见下方 `UploadOptions`。

**行为：**
1. 显示信息 Toast "Uploading files..." 并打开进度对话框。
2. 顺序遍历文件。对每个文件：
   - 构建 `FormData`，包含 `filename`、`file`、`type`（如已设置）和 `operation: 'upload_file'`。
   - POST 到端点，带有 XHR 进度跟踪（更新两个进度条）。
   - 每个文件上传成功后调用 `singleFileUploadCallback(file)`。
3. 成功时：显示成功 Toast，可选通过 PJAX 导航。
4. 出错时：记录到控制台，显示带有消息的错误 Toast。
5. 完成后：等待 500ms，关闭对话框。

## 接口

### UploadOptions

```ts
interface UploadOptions {
  type?: string;                          // 作为 'type' 附加到 FormData 中
  pjax?: boolean;                         // 上传后通过 PJAX 导航
  sidebar?: boolean;                      // 在 PJAX URL 中附加 'sidebar=true'
  singleFileUploadCallback?: (file: File) => any;  // 每个文件成功后调用
  filenameCallback?: (file: File) => string;       // 自定义文件名覆盖
}
```

- `type` — 作为表单字段传递；用于在服务端对上传进行分类。
- `pjax` — 为 `true` 时，所有上传完成后执行 PJAX 导航到 `endpoint`（`type` 值作为查询参数 `d` 传递，`sidebar` 作为 `sidebar=true` 传递；使用 `push: false` 不产生历史记录）。
- `sidebar` — 在 PJAX URL 中添加 `sidebar=true`。
- `singleFileUploadCallback` — 每个单独文件上传成功后调用的异步回调。
- `filenameCallback` — 覆盖发送到服务器的文件名；默认为 `file.name`。

---

## 工具 (UI)

### @hydrooj/utils/lib/common

> Source: https://github.com/hydro-dev/Hydro/blob/master/framework/utils/lib/common.ts

```ts
import { randomstring, formatDate, formatSeconds } from '@hydrooj/ui-default'
```

# @hydrooj/utils/lib/common

所有前端插件可通过 `import { ... } from '@hydrooj/ui-default'` 使用的通用工具函数。

## 函数

### 字符串工具

| API | 说明 |
|-----|------|
| `randomstring(digit?, dict?)` | 生成 `digit` 长度（默认 32）的随机字符串，使用 `dict` 中的字符（默认字母数字）。 |
| `formatDate(date, fmt?)` | 使用 printf 风格占位符（`%Y`、`%m`、`%d`、`%H`、`%M`、`%S`）格式化 `Date` 对象。默认格式：`'%Y-%m-%d %H:%M:%S'`。 |
| `formatSeconds(seconds?, showSeconds?)` | 将以秒为单位的时长格式化为 `HH:MM:SS`（当 `showSeconds` 为 false 时为 `H:MM`）。 |
| `getAlphabeticId(i)` | 将零基索引转换为字母 ID（`A`、`B`、... `Z`、`AA`、`AB`、...）。缓存至 `ZZ` 以提升性能。 |

### 解析

| API | 说明 |
|-----|------|
| `parseTimeMS(str, throwOnError?)` | 将时间字符串（如 `"1s"`、`"500ms"`、`"100us"`）解析为毫秒。纯数字原样返回。解析失败默认抛出异常；当 `throwOnError` 为 `false` 时返回 `1000`。 |
| `parseMemoryMB(str, throwOnError?)` | 将内存字符串（如 `"256mb"`、`"1gb"`、`"512kb"`）解析为 MiB。纯数字原样返回。解析失败默认抛出异常；当 `throwOnError` 为 `false` 时返回 `256`。 |

### 大小写转换

| API | 说明 |
|-----|------|
| `camelCase(source)` | 深度转换对象键或字符串，从 `snake_case`/`kebab-case` 转为 `camelCase`。递归处理嵌套对象和数组。 |
| `paramCase(source)` | 深度转换对象键或字符串为 `param-case`（将 `_` 和大写字母替换为 `-lowercase`）。 |
| `snakeCase(source)` | 深度转换对象键或字符串为 `snake_case`（将 `-` 和大写字母替换为 `_lowercase`）。 |

### 数组与集合

| API | 说明 |
|-----|------|
| `diffArray(a, b)` | 按排序内容比较两个数组；内容不同时返回 `true`。 |
| `sortFiles(files, key?)` | 对字符串或对象数组按 `_id`（或指定键）进行自然排序。数字段按数值比较。 |
| `randomPick(arr)` | 从数组中随机返回一个元素。 |

### 异步与杂项

| API | 说明 |
|-----|------|
| `sleep(timeout)` | 基于 Promise 的延迟 — 在 `timeout` 毫秒后 resolve `true`。 |
| `size(s, base?)` | 将字节数格式化为人类可读字符串（如 `"1.5 GiB"`）。格式化前应用 `base` 乘数。 |
| `noop()` | 空函数 — 适合用作默认回调。 |

## 类型

| API | 说明 |
|-----|------|
| `StringKeys<O>` | 工具类型，提取 `O` 中值类型扩展 `string` 的键。 |

## 全局原型扩展

导入此模块会在内置原型上安装以下扩展：

| 扩展 | 说明 |
|------|------|
| `String.prototype.format(...args)` | 使用 `{key}` 占位符（对象参数）或 `{0}`、`{1}` 位置占位符（数组参数）格式化字符串。 |
| `String.prototype.formatFromArray(args)` | 使用数组中的位置 `{0}`、`{1}`、... 占位符格式化字符串。 |
| `String.prototype.rawformat(object)` | 按 `{@}` 分割字符串并用提供的对象拼接 — 简单模板插值。 |
| `Math.sum(...args)` | 求和所有参数，展平嵌套数组。 |
| `Set.isSuperset(set, subset)` | 检查 `set` 是否包含 `subset` 的所有元素。 |
| `Set.union(setA, setB)` | 返回包含两个输入元素的新 `Set`。 |
| `Set.intersection(setA, setB)` | 返回仅包含两个输入共有元素的新 `Set`。 |

### DOM & 异步 & 其他工具函数

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/utils/base.ts

```ts
import { slideDown, slideUp, mongoId, zIndexManager, delay } from '@hydrooj/ui-default'
```

# DOM & 异步 & 其他工具函数

> 源码: [`packages/ui-default/utils/base.ts`](https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/utils/base.ts), [`packages/ui-default/utils/index.ts`](https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/utils/index.ts)

前端 DOM 操作、异步控制、流处理及其他零散工具集。

---

## zIndexManager

全局 z-index 管理器，用于为弹窗等浮层元素分配递增的 z-index 值。

```ts
const zIndexManager: {
  getCurrent(): number;  // 获取当前 z-index（初始值 1000）
  getNext(): number;     // 递增并返回下一个 z-index
};
```

---

## emulateAnchorClick()

模拟锚点点击行为，根据修饰键决定在当前窗口跳转还是新窗口打开。

```ts
function emulateAnchorClick(ev: KeyboardEvent, targetUrl: string, alwaysOpenInNewWindow?: boolean): void;
```

- 检测 `ctrlKey` / `shiftKey` / `metaKey` 修饰键，按下时调用 `window.open()` 在新窗口打开
- `alwaysOpenInNewWindow = true` 时始终在新窗口打开
- 否则在当前窗口通过 `window.location.href` 跳转

---

## addSpeculationRules()

向页面注入 [Speculation Rules](https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API)，用于浏览器预取/预渲染。

```ts
function addSpeculationRules(rules: object): void;
```

- 先检测 `HTMLScriptElement.supports('speculationrules')` 是否可用
- 可用时创建 `<script type="speculationrules">` 并将 `rules` 序列化为 JSON 写入

---

## getTheme()

获取当前用户主题模式。

```ts
function getTheme(): 'dark' | 'light';
```

- 读取 `UserContext.theme`，仅在值为 `'light'` 或 `'dark'` 时返回，否则回退为 `'light'`

---

## delay()

简单的 Promise 延时工具，等待指定毫秒数后 resolve。

```ts
function delay(ms: number): Promise<void>;
```

---

## withTransitionCallback()

使用 [View Transition API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API) 包裹回调函数，实现页面过渡动画。

```ts
async function withTransitionCallback(callback: () => Promise<void> | void): Promise<void>;
```

- 浏览器不支持或页面不可见时（`visibilityState === 'hidden'`）直接执行回调，跳过过渡动画
- 连续调用时会 `skipTransition()` 跳过前一个未完成的过渡
- 等待 `transition.finished` 完成后清除内部引用

---

## setTemporaryViewTransitionNames()

为指定元素临时设置 `view-transition-name` CSS 属性，在过渡完成后自动清除。

```ts
async function setTemporaryViewTransitionNames(
  entries: [HTMLElement, string][],
  vtPromise: Promise<void>,
): Promise<void>;
```

- `entries` 为 `[元素, 过渡名称]` 二元组数组
- 设置名称后等待 `vtPromise` 完成，再将所有元素的 `viewTransitionName` 恢复为空字符串

---

## secureRandomString()

使用浏览器 `crypto.getRandomValues()` 生成密码学安全的随机字符串。

```ts
function secureRandomString(digit?: number, dict?: string): string;
```

- `digit`：生成字符数，默认 `32`
- `dict`：可选字符集，默认 `a-zA-Z0-9`
- 不支持 `crypto.getRandomValues` 时抛出错误

---

## mongoId()

解析 MongoDB ObjectId 字符串，提取其中的时间戳、机器 ID、进程 ID 和序列号。

```ts
function mongoId(idstring: string): {
  timestamp: number;
  machineid: number;
  pid: number;
  sequence: number;
};
```

- 将 24 位十六进制字符串拆分为 4 段并解析为十进制整数

---

## slideDown() / slideUp()

基于 jQuery 的滑动动画工具，用于元素的展开和收起过渡效果。

```ts
async function slideDown($element: JQuery, duration: number, fromCss?: Record<string, any>, toCss?: Record<string, any>): Promise<void>;
async function slideUp($element: JQuery, duration: number, fromCss?: Record<string, any>, toCss?: Record<string, any>): Promise<void>;
```

- `slideDown`：将元素从高度 0 展开，使用 `easeOutCubic` 缓动
- `slideUp`：将元素从当前高度收起至 0，完成后设置 `display: none`
- 两个函数都会保存并恢复元素原始的 `style` 属性
- 可通过 `fromCss` / `toCss` 自定义过渡的起始和结束 CSS 属性

---

## createZipStream

ZIP 流构造器，指向 `window.ZIP`（由 `streamsaver` 的 `zip-stream` polyfill 提供）。

```ts
const createZipStream: any; // window.ZIP
```

---

## createZipBlob()

基于 `createZipStream` 创建 ZIP Blob，将流式输出转换为完整的 Blob 对象。

```ts
function createZipBlob(underlyingSource: any): Promise<Blob>;
```

- 内部通过 `new Response(createZipStream(source)).blob()` 实现

---

## pipeStream()

将可读流连接到可写流，支持中止控制。

```ts
async function pipeStream(read: ReadableStream, write: WritableStream, abort?: { abort: Function }): Promise<void>;
```

- 浏览器原生支持 `WritableStream` 且 `read.pipeTo` 可用时，使用 `pipeTo()` + `AbortController`
- 否则回退到手动 `reader/writer` 循环逐块读写
- `abort` 对象的 `abort` 方法会被绑定到对应的中止控制器上

---

## base64

Base64 编解码工具对象。

```ts
const base64: {
  encode(input: string): string;
  decode(input: string): string;
};
```

- `encode()`：先进行 UTF-8 编码，再转为 Base64 字符串
- `decode()`：先去除非法字符，解码 Base64 后再进行 UTF-8 解码
- 内部使用 `_utf8Encode` / `_utf8Decode` 处理多字节字符

---

## pjax

PJAX (PushState + AJAX) 页面导航模块，实现无刷新页面切换。

```ts
const pjax: {
  request(opt: string | { url: string; method?: string; push?: boolean; ... }): Promise<void>;
};
```

- `pjax.request()` — 发起 PJAX 请求：
  - 向 URL 追加 `?pjax=1` 查询参数
  - 服务端返回 `{ fragments: [{ html }] }` 格式的响应
  - 通过 `data-fragment-id` 属性匹配并替换页面中的 DOM 片段
  - 自动管理 `history.pushState` / `replaceState` 和 `popstate` 事件
  - 使用 `withTransitionCallback` 包裹 DOM 替换操作以支持过渡动画
  - 替换前触发 `vjContentRemove` 事件，替换后触发 `vjContentNew` 事件
  - 使用 `NProgress` 显示顶部加载进度条
  - 连续请求会自动中止前一个未完成的 XHR

---

## mediaQuery

响应式媒体查询工具，提供视口宽度判断。

```ts
namespace mediaQuery {
  function isAbove(width: number): boolean;  // 视口宽度 >= width
  function isBelow(width: number): boolean;  // 视口宽度 <= width
}
```

- 优先使用 `window.matchMedia` API，不支持时回退到 `window.innerWidth` 比较

---

## loadReactRedux()

异步加载 React + Redux 全家桶，返回创建好的 Redux store 和相关依赖。

```ts
async function loadReactRedux<S, A extends Action = UnknownAction>(
  storeReducer: Reducer<S, A>,
): Promise<{
  React: typeof React;
  createRoot: typeof createRoot;
  Provider: React.ComponentType<{ store: Store<S, A> }>;
  store: Store<S, A>;
}>;
```

- 动态导入 `react-redux`、`redux`、`redux-thunk`、`redux-promise-middleware`（并行加载）
- 开发环境下额外加载 `redux-logger`（折叠模式 + 显示耗时）
- 使用 `applyMiddleware(thunk, promise)` 创建 store
- 返回 `React`、`createRoot`、`Provider` 和已创建的 `store`

---

### api() & request 工具

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/utils/index.ts

```ts
import { api, request } from '@hydrooj/ui-default'
```

# api() & request 工具

源码：[`packages/ui-default/utils/index.ts`](https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/utils/index.ts)、[`packages/ui-default/utils/base.ts`](https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/utils/base.ts)

面向插件开发者的前端 HTTP 请求工具和语言辅助函数。

---

## api()

```ts
function api(method: string, args: Record<string, any>, projection: any): Promise<any>
```

通过 `/d/{domainId}/api/{method}` 端点调用 Hydro 后端 API 方法。将 `args` 和可选 `projection` 作为 JSON 正文通过 POST 发送。如果响应包含 `error` 字段则抛出异常。

| 参数 | 类型 | 说明 |
|------|------|------|
| `method` | `string` | 后端 API 方法名（如 `"contest.add"`） |
| `args` | `Record<string, any>` | 转发到后端方法的参数 |
| `projection` | `any` | 可选，响应字段投影 |

---

## request

```ts
const request: { ajax, post, get, postFile }
```

基于 jQuery 的 HTTP 客户端对象，具有结构化错误处理。

### request.ajax()

```ts
function ajax(options: Record<string, any>): Promise<any>
```

`$.ajax` 的底层封装，默认 JSON 配置和统一错误处理。默认设置 `dataType: 'json'` 和 `Accept: application/json`。出错时保留原始调用栈。

**错误处理：**

| 条件 | 行为 |
|------|------|
| 请求被中止 | 以 `err.aborted = true` 的 `Error` 拒绝 |
| 网络故障（`readyState === 0`） | 以 "Network error" 拒绝 |
| 服务端 JSON 错误（带参数） | 对 `error.message` 使用 `error.params` 应用 i18n |
| 服务端 JSON 错误（无参数） | 以 `error.message` 拒绝 |
| 其他失败 | 以状态文本或抛出的错误拒绝 |

### request.post()

```ts
function post(url: string, dataOrForm?: JQueryStatic | Node | string | Record<string, any>, options?: Record<string, any>): Promise<any>
```

发送 POST 请求。`dataOrForm` 参数接受多种输入类型：

| 输入类型 | 行为 |
|----------|------|
| jQuery 表单（`$(form)`） | 通过 `.serialize()` 序列化 |
| DOM 表单元素 | 通过 `$().serialize()` 序列化 |
| 字符串 | 作为原始查询字符串正文发送 |
| 纯对象 | 以 `Content-Type: application/json` JSON 序列化 |

### request.get()

```ts
function get(url: string, qs?: Record<string, any>, options?: Record<string, any>): Promise<any>
```

发送带查询字符串参数的 GET 请求。

### request.postFile()

```ts
function postFile(url: string, form: FormData, options?: Record<string, any>): Promise<any>
```

通过 `FormData` 上传文件。设置 `processData: false` 和 `contentType: false`，使 jQuery 原样传递 FormData（浏览器会设置正确的 multipart 边界）。

---

## getAvailableLangs()

```ts
function getAvailableLangs(langsList?: string[]): Record<string, any>
```

过滤 `window.LANGS`，仅返回可用的语言条目。排除作为其他键前缀的条目（如存在 `"en.section"` 时的 `"en"`）、标记为 `disabled` 的条目。当提供 `langsList` 时，它作为完整白名单——仅返回列表中包含的键（同时覆盖 `hidden` 检查）。

| 参数 | 类型 | 说明 |
|------|------|------|
| `langsList` | `string[]` | 可选，语言键白名单（提供时仅返回列表中的键，同时覆盖 `hidden` 检查） |

### 模板 & 国际化工具

> Source: https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/utils/base.ts

```ts
import { tpl, i18n, substitute } from '@hydrooj/ui-default'
```

# 模板 & 国际化工具

> 源码: [`packages/ui-default/utils/base.ts`](https://github.com/hydro-dev/Hydro/blob/master/packages/ui-default/utils/base.ts)

前端模板渲染与国际化工具集。提供 HTML 模板构建、字符串插值和语言翻译功能。

---

## tpl()

模板标签函数，支持两种调用方式：

**标签模板字面量** — 自动对插值进行 HTML 转义，返回拼接后的 HTML 字符串：

```ts
function tpl(pieces: TemplateStringsArray, ...substitutions: Substitution[]): string;
```

- 插值类型为 `string | number | { templateRaw: true, html: string }`
- 普通插值通过 `_.escape()` 转义；使用 `rawHtml()` 包裹可跳过转义

**React 节点渲染** — 将 React 元素渲染为 HTML 字符串（默认）或挂载到 DOM 节点：

```ts
function tpl(node: React.ReactNode, reactive?: true): HTMLDivElement;
function tpl(node: React.ReactNode, reactive?: false): string;
```

- `reactive = false`（默认）：调用 `ReactDOMServer.renderToStaticMarkup()` 返回 HTML 字符串
- `reactive = true`：调用 `ReactDOM.createRoot()` 挂载到新 `<div>` 并返回该 DOM 节点

---

## tpl.typoMsg()

`tpl` 上的静态方法，生成 Hydro `typo` 样式容器包裹的 HTML 段落。

```ts
tpl.typoMsg(msg: string, raw?: boolean): string;
```

- `raw = true`：直接将 `msg` 包裹在 `<div class="typo"><p>...</p></div>` 中，不做转义
- `raw = false`（默认）：按换行符拆分，每行用 `<p>` 包裹并对内容做 `_.escape()` 转义

---

## rawHtml()

创建一个跳过 HTML 转义的插值对象，供 `tpl()` 标签模板使用。

```ts
function rawHtml(html: string): { templateRaw: true; html: string };
```

- 返回对象被 `tpl()` 识别后直接插入，不经过 `_.escape()` 处理

---

## substitute()

简单的字符串模板插值，将 `{key}` 占位符替换为对象中对应的值。

```ts
function substitute(str: string, obj: any): string;
```

- 匹配 `{key}` 模式（不支持嵌套花括号）
- 值不为 `undefined`/`null` 时调用 `.toString()` 替换；否则保留原始占位符

---

## i18n()

国际化翻译函数，从 `window.LOCALES` 查找翻译文本并插值。

```ts
function i18n(str: string, ...params: any[]): string;
```

- 通过 `window.LOCALES[str]` 查找翻译；未找到时回退到原始字符串
- 找到翻译后调用 `substitute()` 将剩余参数替换 `{0}`, `{1}` 等占位符
- 传入空值（`null`/`undefined`/`''`）时返回空字符串