# @12-apps/shift 中文文档

规范地址：https://npmcn.com/package/%4012-apps/shift/

版本：3\.6\.0
npm 元数据更新时间：2026-10-28T01:16:23.855Z
中文译文更新时间：2026-11-05T19:42:48.411Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%4012-apps/shift
原文对照：https://npmcn.com/package/%4012-apps/shift/?lang=original
项目主页：https://github.com/12-apps/shared-packages#readme
源码仓库：https://github.com/12-apps/shared-packages

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：566 kB，61 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：0 个
- peer 依赖：@12-apps/wiring \>=1\.3\.0
- 首次发布：2026-08-05T02:17:43.872Z
- 最新版本发布：2026-10-28T01:16:23.125Z
- 近 30 天下载量：33385（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：42（近 12 个月 42 个）

## 中文简介

无头租户范围的工作有资源约束和审计端口.

## 安装

```sh
npm install @12-apps/shift
```

也可以使用：`pnpm add @12-apps/shift`、`yarn add @12-apps/shift`、`bun add @12-apps/shift`

## README

# @ 12- 应用程序/ 临时

无头、有租户范围的工作轮班:工人可选择申请时间 期限由工人关闭,按 上司,或者扫荡 一经关闭、通过港口审计和 由 Prisma 部分加 PostgreSQL 保证支持 .

包拥有机制. 它不拥有任何词汇.

## 东道国的种类

`kind` 是一个变化中的字段,其价值描述的是企业而不是 一个工作周期,所以没有默认,也没有内置列表——集合是 需要配置 :

```ts
import { createShiftService, defineShiftVocabulary } from '@12-apps/shift';

export const CLINIC_KINDS = ['hygiene', 'surgery', 'reception'] as const;

const service = createShiftService(shiftDb, { kinds: CLINIC_KINDS });
```

通过一个 `as const` tumple 和返回服务上的所有输入都缩小到 准确的这些值,所以主机通过自己的单词不断编译时间安全性:

```ts
await service.openShift({
  clientId, userId, actorUserId,
  kind: 'surgery',              // ✅ declared
  resource: { type: 'operatory-chair', id: 'chair-3', exclusive: true },
});

await service.openShift({ ...input, kind: 'grooming' });
// ✗ compile error, and at runtime a ShiftError('INVALID_SHIFT') naming the
//   kinds this service was constructed with.
```

空的、空白的或重复的条目 `ShiftConfigError` 在建筑方面 在可以辨认的情况下——而不是在没有人可以进来的要求下.

### 背书

`Shift.kind` 是一个 `string`,因为一行持有 任何在栏。 A 类 宿主想要它的联盟 与后卫缩小 `defineShiftVocabulary` 返回时,从同一声明中创建该服务

```ts
const vocabulary = defineShiftVocabulary(CLINIC_KINDS);
const kind = vocabulary.has(shift.kind) ? shift.kind : null;
//    ^? 'hygiene' | 'surgery' | 'reception' | null
```

一个声明,所以一个服务接受的值和一个主机的值缩小 不能分开.

`resourceType` 财务报告和审定财务报表 `resourceId` 一直以这种方式行事:, 与主人拥有他们的意思。 善良只是加入他们.

## 时间表

转变是一个事实:它开始,它可能已经结束。 A 类 **插槽** 计划: 从什么时候到何时,应该用哪种方法 他们住在不同的桌子上 (单位:千美元)`shift_slots` 旁边 `shifts`)和不同的服务,在同一词汇上:

```ts
const schedule = createShiftScheduleService(scheduleDb, { kinds: HOST_KINDS });

await schedule.scheduleSlot({
  clientId, userId, kind: 'ward', actorUserId,
  startsAt, endsAt,
  repeatWeeks: 3, timeZone: 'America/New_York', // this week and the next three
});
```

-   **复有持壁钟.** 每份每周副本在同一当地时间登陆 内 `timeZone`,跨越一时的防日变化: 穿过空隙( 02: 30 变成 03: 30), 重复的时间是第一次 发生。 24小时限时检查每份,所以24小时档 其重复将跨越倒数 重复通话需要已知 区; 单个槽没有.
-   **每个租户的工人没有重叠**整个重复,所有或没有: `SLOT_OVERLAP` 和没有写。 后入无碍. 主持人 `lockUserSchedule` 必须连载同一工人的两个作家(a) postgres 上的交易范围咨询锁定 —— 重复读取仅作为 安全到锁上.
-   **取消保留行** (单位:千美元)`canceledAt`, (中文(简体) ), `canceledByUserId`, (中文(简体) ), `cancelReason`)),所以主持人可以说为什么一个插槽被放出. `scope: 'following'` 也取消同系列后期的活槽. 空档已经结束了 无法取消 .
-   **`slotStanding({ slot, openShift, now })`** 答题 `canceled`, (中文(简体) ), `over`, (中文(简体) ), `on_shift`, (中文(简体) ), `late` (与 `lateMinutes`, (中文(简体) ), `due` (在窗口前) 启动,默认为15分钟)或 `later`。它相信东道主的 `openShift`数字 : 通过工人的开放式轮班 **类型**软件包 不决定哪个档次是哪个档次.
-   **`nextSlots({ clientIds, userId, limit })`** 读取一个人的活槽 横跨租户的HOST允许,在限前过滤. 谁还在工作 宿主的知识在哪里, 所以一个空列表被拒绝 而不是读 像"任何地方"一样.

### 系列规则和滚动视野

重复也可以是一个 **规则** (单位:千美元)`shift_slot_series`而不是N拷贝:

```ts
const { series, slots, change } = await schedule.scheduleSeries({
  clientId, userId, kind: 'ward', actorUserId,
  weekdays: [1, 3], everyWeeks: 1,          // or monthlyNth: 3 with ONE weekday
  startMinutes: 22 * 60, endMinutes: 6 * 60, // an end at or before the start is the next day
  breakOffsetMinutes: 240, breakMinutes: 30, // optional, from the start, both or neither
  timeZone: 'America/New_York', startsOn: '2026-10-26', endsOn: null, // null = no end
});
```

-   **日子的到来** (单位:千美元)`horizonWeeks`,默认 12)作为 携带普通插槽 `seriesId` 财务报告和审定财务报表 `seriesDate`。 。 。 . `extendSeries()` 正在建设 每个租户的每个公开规则的后几天; `materialiseSeries({ until, preview })` 或列出未来的日子. 两者都有天分: 一天已经有一行规则——取消了, 已搬出或已搬出——从未重建。 一个人已经一天了 被跳过,记录在规则上(`skippedDates`)并审计过一次—— 一天的时数倒在日出时空 (单位:千美元)`scheduleSeries`, (中文(简体) ), `editSeries`, (中文(简体) ), `promoteToSeries`)拒绝使用 `WALL_CLOCK_GAP`,作为 `editSlot` 用于一个插槽.
-   **这份工作.** `@12-apps/shift/jobs` 声明 `extend-series` (每日租借). 主机绑定 `extendSeries()` a. 对本会议工作的贡献 `onMaterialised(clientId, slotIds)` 无论它是否与时间表一致.
-   **编辑已经到位.** `editSlot` 移动一行(小时或日期) `detached`或把它交给别人 个人,它从它的系列中取出(`seriesId` 没有, `originSeriesId` 保留); `rejoinSeries: true` 把它放回去,只让规则的人. `editSeries({ from })` 前一天关闭规则 `from` 打开 继任者(`previousSeriesId`;每两周接任一次,任期相同 重复保留旧规则的周数, 已经进行的一行被保留,它的 日出继承人. `promoteToSeries` 转动一个人的单曲 成规而行,复制其时而断其时而拒之`INVALID_SLOT`(单位:千美元) 一日一日一出,不得犯规; `demoteToSlot` 结束规则为 一个分离的单身.
-   **一个规则在它的未来被取消时结束.** `cancelSlot` 与 `following` 在规则的行 结束规则的前一天; `restoreSlot` 这些行 重新打开它. `restoreSlot` 只清除主机通过取消的原因 `restorableReasons` 在尚未结束的档位上,包名没有.
-   **每个规则都写回一个 `ScheduleChange`**简洁的JSON,和 `revertScheduleChange` 在一次交易中撤销,拒绝使用 `SCHEDULE_CHANGED` 当一行或规则 它的名字从此移动。 从来没有 摸一行交给另一个人:那行是他们的,规则是: 背负的背负 离开它的一天. `cancelSlot` 继续返回其槽; 变换在阵列上作为 `.change`。 。 。 .
-   **`allowRunning: true`** 打开 `scheduleSlot` 财务报告和审定财务报表 `editSlot` 输入插槽 已经在执行中(替代);没有它就拒绝过去的开始.

`ShiftScheduleError` 携带自己的代码(`INVALID_SLOT`, (中文(简体) ), `SLOT_OVERLAP`, (中文(简体) ), `SLOT_NOT_FOUND`, (中文(简体) ), `SLOT_CANCELED`, (中文(简体) ), `SLOT_OVER`, (中文(简体) ), `SLOT_NOT_RESTORABLE`, (中文(简体) ), `WALL_CLOCK_GAP`, (中文(简体) ), `SERIES_NOT_FOUND`, (中文(简体) ), `SCHEDULE_CHANGED`和 `SHIFT_SCHEDULE_ERROR_STATUS` 将其映射到 HTTP 状态; `ShiftError`代码 不变,所以一个与它们完全匹配的主机会不断编译.

## 从3.x升级

`createShiftService(db)` 不再编译 : `options.kinds` 需要时间.

1.  在主机代码中宣布您的类型为 `as const` 拖住,通过他们.
2.  替换已删除的类别清单、类型结合和两者的进口 资源类型常数,含有自己的主机常数。 资源类型 值从未被此软件包验证过 比较——所以保留同一字行保留了现有的每行.
3.  迁相. `20260821120000_shift_kind_host_vocabulary` 放弃 CHECK 限制的限制 `shifts.kind` 取出源的2个 值,并替换为非空白检查。 现有行满足,所以 没有回填.

没有其他变化:转移的电线形状、审计端口、排他性 规则,扫描 和每个错误代码是原样.

## 出口

| 导出 | 这是什么 |
| --- | --- |
| `createShiftService(db, options)` | 服务. `options.kinds` 需要时间. |
| `defineShiftVocabulary(kinds)` | 验证主机的种类; 返回它们上面的类型守护 . |
| `createMemoryShiftDb()` | 记忆 `ShiftDb`,用于主机测试. |
| `createShiftScheduleService(db, options)` | 计划档期表. |
| `createMemoryShiftScheduleDb()` | 记忆 `ShiftScheduleDb`,用于主机测试. |
| `ShiftScheduleError` 编号 : `SHIFT_SCHEDULE_ERROR_STATUS` | 时刻表拒绝, 及其 HTTP 状态 . |
| `ShiftError` 编号 : `ShiftConfigError` | 请求结果和线路错误. |
| `@12-apps/shift/jobs` | 自动关闭和扩展系列的蓝图,道克仍然开放. |
| `@12-apps/shift/manifest` | 电线清单及其服务器的一半. |

## 数据库

普里斯马部分`prisma/shift.prisma`和迁移情况 `prisma/migrations` 被贡献给宿主的计策。 租户、用户和 资源标识符按值存储,主机表格中没有外键—— 也就是让东道主清理租户 而不给包裹一个意见.

## 常见问题

### @12-apps/shift 是什么？

无头租户范围的工作有资源约束和审计端口\.

### 如何安装 @12-apps/shift？

在项目目录运行 npm install @12-apps/shift，或使用 pnpm add / yarn add / bun add。

### @12-apps/shift 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @12-apps/shift 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @12-apps/shift 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @12-apps/shift 可以商用吗？

@12-apps/shift 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @12-apps/shift 的下载量有多少？

根据 npm 官方下载统计，@12-apps/shift 在 2026/10/05 – 2026/11/03 这 30 天内被下载 33,385 次，日均约 1,113 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @12-apps/shift 还在维护吗？

最新版本 3\.6\.0 发布于 2026/10/28（10 天前）；至今共发布 42 个版本，其中过去 12 个月发布了 42 个；首次发布于 2026/08/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。