# @livdot-tech/contracts 中文文档

规范地址：https://npmcn.com/package/%40livdot-tech/contracts/

版本：1\.19\.1
npm 元数据更新时间：2026-11-01T17:25:21.531Z
中文译文更新时间：2026-11-01T18:05:29.072Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40livdot-tech/contracts
原文对照：https://npmcn.com/package/%40livdot-tech/contracts/?lang=original
项目主页：https://github.com/LivDotTech/shared-schemas#readme
源码仓库：https://github.com/LivDotTech/shared-schemas

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

- 包体积（解压后）：2.8 MB，190 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：zod ^4\.4\.3
- 首次发布：2026-04-28T07:53:26.597Z
- 最新版本发布：2026-11-01T17:25:21.326Z
- 已发布版本数：153（近 12 个月 153 个）

## 中文简介

LivDot平台的共享API契约

## 安装

```sh
npm install @livdot-tech/contracts
```

也可以使用：`pnpm add @livdot-tech/contracts`、`yarn add @livdot-tech/contracts`、`bun add @livdot-tech/contracts`

## README

# LivDot共享合同

用于跨LivDot平台使用的模式和面向api的共享类型的中央契约存储库。

## 目的

这个存储库的存在是为了保持后端、前端和移动端在相同的契约表面上对齐，而不需要将代码库耦合到一个单线程中。 它是以下内容的单一共享源：

-   请求和响应模式
-   域枚举和状态常数
-   规范错误码
-   共享dto和验证规则
-   其他api边界定义必须在服务和客户端之间保持一致

## 使用此包的存储库

-   `livdot-backend`
-   `livdot-frontend`
-   `livdot-mobile`

## 属于这里的东西

只有跨堆栈契约工件。 示例：

-   `CreateEventRequest`
-   `BookingState`
-   `EventState`
-   `ApiErrorCode`
-   用于有效负载验证的模式
-   共享的授权/令牌有效负载形状（如适用）

## 这里不能添加什么

这个存储库是 **不** 共享代码的垃圾场。 做。 **不** 添加:

-   后端业务逻辑
-   ORM /数据库模型
-   库/服务/用例
-   前端UI组件
-   特定于移动设备的运行时代码
-   基础设施或部署逻辑
-   不属于跨堆栈契约的实用程序 如果它不是合同边界的一部分，它就不属于这里。

## 所有权

后端仍然是系统行为和API真实性的权威。 这个存储库定义了 **合同的形状**，而不是实现或业务逻辑。

## 版本控制

发布是自动化的。 `semantic-release` 读取常规提交消息 `main` 并决定 他写道： `CHANGELOG.md`，标记，并发布到npm。 **不要编辑 `version` 场 `package.json` 用手** - CI拥有它。

commit前缀决定了bump：

-   `fix:` → **补丁**，向后兼容的修复
-   `feat:` → **小**，向后兼容的添加
-   `feat!:` 或者一个 `BREAKING CHANGE:` 页脚→ **主要的**

因为碰撞是从提交消息而不是从模式差异派生的，所以中断 提交的更改 `fix:` 将作为补丁发布。字段删除和重命名必须带有分隔符 标记。

消费者确定一个符号范围，并通过审查升级。

## 变化的规则

任何契约变更都必须谨慎对待，因为它可能影响多个代码库。 在合并更改之前：

1.  确认更改确实是跨堆栈的
2.  确定它是否断开或不断开
3.  适当更新版本
4.  如果消费者需要更改代码，则记录迁移说明

## 结构

每个域一个文件夹，每个导出 `*.enums.ts`， `*.schemas.ts` 和 `*.types.ts` 通过一个 `index.ts` 桶。

```text
src/
  auth/          user/          event/
  booking/       marketplace/   joblisting/
  host/          moment/        chat/
  payment/       streaming/     dispute/
  notification/  common/        errors/
  index.ts       # master barrel
```

`common/` 持有 `CurrencyEnum`、分页、审计枚举和 `ResponseMessages`； `errors/` 拥有 `ApiErrorCode` 目录; `booking/` 另外拥有 `booking-state-machine.ts` -有效的 转换、每个转换参与者RBAC以及哪些目标状态需要 `reason`.

添加域意味着三次编辑：创建包含其的文件夹 `index.ts`，重新出口 `src/index.ts`， **把它加到 `entry` 数组中 `tsup.config.ts`** -错过了最后一个和 `@livdot-tech/contracts/<domain>` Subpath解析为空。

## 安装与使用

```bash
npm install @livdot-tech/contracts zod
```

`zod` 是一个 **同行的依赖**，而不是捆绑——包没有运行时依赖，并且保持 Zod在消费者端意味着只有一个Zod实例在运行。

```ts
import { BookingState, CurrencyEnum } from '@livdot-tech/contracts';
import { VALID_BOOKING_TRANSITIONS } from '@livdot-tech/contracts/booking';
```

看到 [文档/ README.md](https://npmcn.com/package/%40livdot-tech/contracts/docs/README.md) 有关使用详情，请参阅 [文档/ ONBOARDING.md](https://npmcn.com/package/%40livdot-tech/contracts/docs/ONBOARDING.md) 对于设置，以及 [架构/ SAD.md](https://npmcn.com/package/%40livdot-tech/contracts/architecture/SAD.md) 加上 [架构决策/](https://npmcn.com/package/%40livdot-tech/contracts/architecture/decisions/) 对于设计决策。

## 目标

保持契约明确、版本化和稳定。

这个存储库的存在是为了提高后端、前端和移动端的一致性，同时在独立的LivDot代码库之间保持清晰的所有权界限。

## 常见问题

### @livdot-tech/contracts 是什么？

LivDot平台的共享API契约

### 如何安装 @livdot-tech/contracts？

在项目目录运行 npm install @livdot-tech/contracts，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（^4\.4\.3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @livdot-tech/contracts 支持 TypeScript 吗？

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

### @livdot-tech/contracts 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @livdot-tech/contracts 可以商用吗？

@livdot-tech/contracts 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @livdot-tech/contracts 还在维护吗？

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