# @faiber/faiber-profile 中文文档

规范地址：https://npmcn.com/package/%40faiber/faiber-profile/

版本：2\.7\.0
npm 元数据更新时间：2026-11-04T16:47:59.450Z
中文译文更新时间：2026-11-14T09:10:36.271Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40faiber/faiber-profile
原文对照：https://npmcn.com/package/%40faiber/faiber-profile/?lang=original

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

- 包体积（解压后）：869 kB，36 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-07-18T14:29:20.652Z
- 最新版本发布：2026-11-04T16:47:59.277Z
- 近 30 天下载量：3864（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：65（近 12 个月 65 个）

## 中文简介

剖面,原子部分更新,动态属性,地理记录,关系,媒体,搜索,可信赖的服务,和剖面日志.

## 安装

```sh
npm install @faiber/faiber-profile
```

也可以使用：`pnpm add @faiber/faiber-profile`、`yarn add @faiber/faiber-profile`、`bun add @faiber/faiber-profile`

## README

# @faiber/ faiber- profile

剖面,原子部分更新,动态属性,地理记录,关系,媒体,搜索,可信赖的服务,和剖面日志.

## 安装

```bash
npm install @faiber/faiber-profile
```

## 配置

```ts
import { FaiberClient, MemoryTokenProvider } from "@faiber/sdk-core";
import { ProfileApi } from "@faiber/faiber-profile";

const tokens = new MemoryTokenProvider();
const client = new FaiberClient("profile", {
  domains: { profile: process.env.FAIBER_PROFILE_URL! },
  tokenProvider: tokens,
  axios: { timeout: 15_000, withCredentials: true },
});
const api = new ProfileApi(client);

const updated = await api.updateProfile(userId, {
  first_name: { en: "Ava", fa: "آوا" },
  phone: "+989121234567",
  properties: { workout_plan: plan, membership },
});
console.log(updated.data.data.profile);
```

## 完全能力

这个软件包从配置服务中暴露出239个已注册的操作. 通用工作流程有简洁的方法 `api`;每个已注册后端路由在 `api.operations`。生成的操作输入、查询、响应、路径、动词和许可合同从 `operations.types`。 。 。 .

| 区域 | 业务 | HTTP 方法 |
| --- | --: | --- |
| `ai-summary` | 20国 | `GET`, (中文(简体) ), `PATCH`, (中文(简体) ), `POST`, (中文(简体) ), `PUT` |
| `campaign` | 页:1 | `GET`, (中文(简体) ), `POST` |
| `city` | 第8条 | `DELETE`, (中文(简体) ), `GET`, (中文(简体) ), `PATCH`, (中文(简体) ), `POST`, (中文(简体) ), `PUT` |
| `country` | 第8条 | `DELETE`, (中文(简体) ), `GET`, (中文(简体) ), `PATCH`, (中文(简体) ), `POST`, (中文(简体) ), `PUT` |
| `custom-type` | 页:1 | `DELETE`, (中文(简体) ), `GET`, (中文(简体) ), `PATCH`, (中文(简体) ), `POST` |
| `education` | 页:1 | `GET`, (中文(简体) ), `POST`, (中文(简体) ), `PUT` |
| `fitness` | 第32条 | `GET`, (中文(简体) ), `POST`, (中文(简体) ), `PUT` |
| `integration` | 2个 | `GET` |
| `lifecycle` | 24个 | `DELETE`, (中文(简体) ), `GET`, (中文(简体) ), `POST`, (中文(简体) ), `PUT` |
| `log-action` | 3个 | `POST` |
| `logger` | 2个 | `GET` |
| `option` | 页:1 | `GET`, (中文(简体) ), `POST` |
| `profile` | 59国 | `DELETE`, (中文(简体) ), `GET`, (中文(简体) ), `PATCH`, (中文(简体) ), `POST`, (中文(简体) ), `PUT` |
| `profile-property` | 第8条 | `DELETE`, (中文(简体) ), `GET`, (中文(简体) ), `PATCH`, (中文(简体) ), `POST`, (中文(简体) ), `PUT` |
| `profile-search` | 3个 | `POST` |
| `province` | 第8条 | `DELETE`, (中文(简体) ), `GET`, (中文(简体) ), `PATCH`, (中文(简体) ), `POST`, (中文(简体) ), `PUT` |
| `referral` | 第7条 | `DELETE`, (中文(简体) ), `GET`, (中文(简体) ), `POST`, (中文(简体) ), `PUT` |
| `relation` | 10个 | `DELETE`, (中文(简体) ), `GET`, (中文(简体) ), `POST`, (中文(简体) ), `PUT` |
| `router` | 3个 | `GET` |
| `session` | 页:1 | `GET`, (中文(简体) ), `PATCH`, (中文(简体) ), `PUT` |
| `setting` | 2个 | `GET`, (中文(简体) ), `POST` |
| `survey` | 2个 | `GET`, (中文(简体) ), `POST` |
| `trusted-service` | 第12条 | `DELETE`, (中文(简体) ), `GET`, (中文(简体) ), `PATCH`, (中文(简体) ), `POST`, (中文(简体) ), `PUT` |

`updateProfile` 发送一个原子 `PATCH /api/v1/profile/{uuid}`。输出地保持不变。 在被钉住的一般补丁处理器, `job: null` 清除任务; 其它无效的平面字段清晰地解析 `null` 作为忽略。 使用 `educationInformation` 明确清理其教育/移交/就诊领域。 平衡,入场状态,角色,ID,和外观对象不能大规模指定. 补丁模型确实接受 `status`, (中文(简体) ), `employee_type`,以及 `freemium_session_limit` 下级 `profile:update`启用 `uploadAvatar` 国内流离失所者的作用.

## 学生平衡和教育

简介全文如下: `byRole("student")`,显示顶层 `account_balance` 财务报告和审定财务报表 `wallet_balance` 从办公室同步快照. `null` 表示未知;它不是零。 列表配置文件不会载入财务历史 .

```ts
const educations = (await api.listEducations()).data.data; // EducationOption[]: { id, name }
const dependencies = (await api.educationDependencies()).data.data;
await api.educationInformation(idpUserUuid, {
  education_id: educations[0].id,
  attendance_mode: dependencies.attendance_mode[0].id,
  level: "beginner",
  referral_source: dependencies.referral_source[0]?.id ?? null,
  referrer_uuid: referrerUserId,
  description: "Learner notes",
});
await api.customTypes.create({ name: "job", value_type: "select", options: ["بیکار"] });
```

`educationInformation` 支持和呼叫 `PUT /api/v1/profile/update/education-information/{uuid}`。路径必须是 **IDP 用户 UUID**,而不是配置文件记录ID。 整个更新在保存前被验证. (a) 遗漏未变; `null` 释出. 出席情况 `online` 或者说 `in_person`级别接受非空 **最多64个Unicode字符的字符串**,而不是一个数字或固定音符。 转录源是一个来自依赖响应的活性代码;转录源UUID必须识别一个已经存在的其他用户. 描述仅限于一万个字符. 教育必须是积极的查询身份证.

`GET /api/v1/education` 财务报告和审定财务报表 `/education/dependencies` 需求 `profile:read`教育的创造和更新 `profile:update`。管理员可以用 `api.education.create({name})`。迁移会恢复表格和可撤销的列,但无法恢复被旧迁移删除的行;从备份中恢复任何历史目录,而不是发明ID.

## 认证和授权

使用一个 `TokenProvider` 以转发已签名用户的 Bearer 令牌,或启用 `withCredentials` 用于安全的 Http 唯一的饼干会话。 每个行动的JSDoc都载有已宣布的国内流离失所者许可。 大多数 CRUD 路由会使用由可信任的 IDP 网关提供的身份头; 权限说明导出元数据, 并且不会执行处理器内部的权限 。 简要路线还验证了每次接听国内流离失所者的Bearer/cookie证书。 内部健身信贷/礼品业务需要其单独配置的服务 " 熊鼠 " 标志。 SDK不嵌入 API 密钥,证书,本地主机 URL,沙盒主机,或生产主机.

## 投入、询问、答复和运输

所有方法都返回完整的Axios响应,包括状态,头,以及请求ID. 请求机构和查询对象被命名为导出接口. 配置列表页码使用 `page` 财务报告和审定财务报表 `per_page`; 过滤器使用诸如 `filter[role]` 财务报告和审定财务报表 `filter[status]`。摘要页还使用其输出的查询类型。 标准 Axios 请求选项、信头、超时、适配器、拦截器和 `AbortSignal` 取消被支持为最后参数.

一般性的REST资源得到能力保障。 调用未注册的遗留方法 `UnsupportedOperationError` 在发送请求之前, 而不是生成后端 `405`。 。 。 .

## 媒体和指挥部的回应

`api.operations.profileAvatarShowGetApiV1ProfileMediaUuidAvatar(ownerUuid, {key})`, (中文(简体) ), `profileAvatarShowGetApiV1ProfileUuidAvatar`, (中文(简体) ), `profileImageShowGet`,以及 `profileMediaShowGet` 返回原始二进制字节( e)`ArrayBuffer | Uint8Array`),与 axios 响应头的服务内容类型和缓存策略。 他们 `key` 查询 需要时间。 形象和内容是公开的;私营媒体需要国内流离失所者 认证。 无效的所有者前缀或 traversal return 403; 缺少的对象 返回 404 键.

上传接受多部分 `file` 字段,包含 JPEG、PNG 或 WebP 最多 5 MiB. 呼叫者必须拥有目标用户 UUID 或者有 `profile:update`上传成功 返回时 `{url, key}`; 不支持的类型返回 415, 缺少/ 空文件 422, 超大小 和未配置的存储 503 .

财产更新返回 `updated_keys` 财务报告和审定财务报表 `array_item_changes` (增加/删除的身份证) 而不是完整的简介。 地址、父链接、删除和 以空对象恢复命令一般确认成功。 散装父 查找返回存储的链接行, 并同时使用 IDP 用户 UUID; 块地址解析 用于划出 `profile_id` 是一个单独的配置 UUID.

## 错误和取消

```ts
try {
  await api.client.get("/health", undefined, { signal: AbortSignal.timeout(5_000) });
} catch (error) {
  // Axios errors retain response.status and the service error body.
}
```

使用 `@faiber/faiber-ts-sdk` 当一个应用程序需要多个具有一个配置的Faiber服务时.

### 当前空间成员名称

在从任务中获取合格成员ID后, 请拨打 `profile.resolvePeople({ user_ids })` 每批1至200个UUID。 反应中包含有活性沙盒剖面图,有英文/波斯文名称和克通克文 `user_id`;电子邮件和电话被扣。 任何匹配或重复的名字在指派前都无需澄清。 要求数 `profile:lookup` 和标准认证客户端; 无效批次返回 Axios 400 响应。 请求选项支持取消和超时 .

个人资料包括 `job`,一个无效的职称。 过 `{ job: "Software engineer" }` 改为 `sdk.profile.personalInformation(userId, ...)`; 通过 `{ job: null }` 来清理它。 选择 `job` 保存已保存的值。 概况细节和清单答复还包括: `job`,则一般配置补丁操作接受.

### 动态剖面过滤器

简介清单曝光 `birthday`, (中文(简体) ), `created_at`,以及 `referrer_uuid`裁判员 字段持有推荐用户的 IDP UUID 。 要设置它,打电话 `api.educationInformation(userId, { referrer_uuid: referrerUserId })`。通过 `null` 以清除裁判.

使用 `api.operations.profileSearchSearchPost({ search: "Ava", include: ["properties"] })` 对于合并搜索终点。 每一次袭击都包括 `core`,包括三个 列出上面的字段。 这个 `include` 数组选择可选 `properties` 财务报告和审定财务报表 `services` 节。 把它还给我.

`listProfiles` 和所有角色列表操作查询,包括 `ProfileStudentIndexGetQuery`,接受括号过滤器,重复日期范围 `sort`. 偏爱 `filterProfiles` 用于输入的运算符和 JSON 值:

```ts
const response = await api.filterProfiles({
  filters: [
    { path: 'role', op: 'in', value: ['student', 'customer'] },
    { path: 'core.account_balance', op: 'lt', value: 0 },
    { path: 'properties.owner', op: 'in', value: ['supporter-user-uuid'] },
    { path: 'services.office.sync-user.enrollments.freemium_sessions', op: 'gte', value: 1 },
  ],
  sort: [{ path: 'core.created_at', dir: 'desc' }],
  page: 1,
  per_page: 20,
});
const profiles = response.data.data.profiles;
```

这种方法需要 `profile:read` 并使用正常认证的 Faiber 客户端。 它返回Axios的全部响应 并接受取消信号, 标题和超时作为第二个参数. 无效条款、日期或无法使用 配置包含 HTTP 400 的 Axios 错误的字段拒绝 .

使用 `role` (或 `core.role`以过滤配置文件-作用名称: `eq` 匹配一个角色, `in` 匹配任何提供的角色,以及 `neq` 不包括带有这种作用的简介. 分开 `role` 投入仍然接受一个单一的作用;如果结合条款, 所有限制都一起适用。 角色名称不限于学生使用的案例.

使用 `core.<column>`, (中文(简体) ), `properties.<key>[.<nested-field>]`,或 `services.<service-key>.<event-name>.<nested-field>` 路径。 属性必须是 列表中的活动、可过滤和可见; 信任的服务必须是活动的及其 列表中可见的事件。 嵌入式有效载荷阵列匹配候选元素. 条款 已安放; 使用 `json_contains` 带有数组/对象结构的字段 必须匹配同一嵌入式记录。 运算符是 `eq`, (中文(简体) ), `neq`, (中文(简体) ), `gt`, (中文(简体) ), `gte`, (中文(简体) ), `lt`, (中文(简体) ), `lte`, (中文(简体) ), `in`, (中文(简体) ), `contains`, (中文(简体) ), `exists` 财务报告和审定财务报表 `json_contains`。缺失数据得到满足 `neq`; 数组排序使用最小的 JSON 候选 .

```ts
await api.operations.profileStudentIndexGet({
  'filter[birthday][]': ['2000-01-01', '2010-12-31'],
  'filter[created_at][]': ['2026-01-01', '2026-10-07'],
  'filter[gender]': 'female',
  sort: '-core.created_at',
});
```

范围需要两个被命令的终点;一个空字符串会留下绑定的开口. 只约会创建时间的上限包括了整个一天. `sort` 接受 逗号分隔路径,与 `-` 为下降。 应用概念,例如: `double_debt`,支持者 `owner` 财务报告和审定财务报表 `work_id` 需要存储配置 属性或它们实际信任的服务路径; SDK 不计算它们. 这些能力需要支持动态列表过滤器的服务版本.

### 健身辅导

这个 `operations.fitness*` 方法包括接收草稿、产品报价、付费订单、教练任务、计划修订、目录、设置、通知和审判救赎。 导出 `FitnessIntake`, (中文(简体) ), `FitnessPlan`, (中文(简体) ), `FitnessOrder`, (中文(简体) ), `FitnessRevision` 和礼物类型 描述电线模型.

```ts
const self = await api.operations.fitnessMeGet();
const saved = await api.operations.fitnessSaveSettingsPut({
  model_ref: modelRef, stt_model_ref: speechInputRef, tts_model_ref: speechOutputRef,
  expected_version: currentVersion,
});
```

该服务授权体育馆会员,管理者,被分配的教练员和订单所有权独立于配置编辑. 需要提供/进口行政服务 `fitness:admin`。设置和草稿使用乐观的版本; stale changes return 409. 采购要求稳定 `idempotency_key`,以及计划任务/建议书的使用 `base_revision_id`受托的礼品管理和聊天-信用储备/套接字操作是服务器专用的,需要专门的无记名证书。 用户代币不提供薄荷信用或内部礼品。 目录 `workspaceResolvePeople` 继续解决 1 - 200 个明确的UUID `profile:lookup`;其结果不给予合作者资格.

## 角色简介

角色摘要配置和持续成果属于概况。 经认证的呼叫者需要 `profile:ai_summary:read_own` 为自己的结果或 `profile:ai_summary:read_all` 其他主题 在同一部署中。 父母关系不允许进入。 配置( E)`configure`和 队列管理( e)`manage`)是单独的权限.

```ts
const response = await api.summaries.latest({ role_id: canonicalRoleId }, { signal });
console.log(response.status, response.data.data.freshness, response.data.data.summary);
```

用 `api.summaries.roles()`,然后创建/编辑结构化草案, 校验, 预览一个合格的主题, 公布, 并启用它 `setStatus(id, { enabled: true })`。 。 。 . 在预览前必须启用全局生成;全局 kill switch 也用 HTTP 409 屏蔽了明确的预览 . 角色在预览其草稿时仍可被禁用. 预览结果仍与已公布结果相区别,从未发布配置. 请求只读取存储的数据 。 接受更新和预览请求返回 HTTP 202; 民意调查运行/工作状态 . 一个失败的刷新会留下一个旧的结果 。 禁用配置隐藏最新 内容,但有明确授权的历史可查。 十进制测量值可能是 字符串以保持财务精度。 标准 Axios 错误、 响应头和取消 选项被保留。 这些行动也可提供: `api.operations.aiSummary…` 方法。 。 .

## 配置文件短ID和搜索

```ts
const controller = new AbortController();
const matches = await profile.searchProfiles({
  search: "GDCN7L", // email, name, phone, national code, or six-character short ID
  role: "student",
  page: 1,
  per_page: 20,
}, { signal: controller.signal });
for (const person of matches.data.data.profiles) {
  console.log(person.short_id, person.id, person.user_id);
}
```

使用您的配置 `ProfileApi` 实例和实例 `AbortController`此包装 需求 `profile:read` 返回全部 Axios 响应; 错误和取消 被保留下来. `listProfiles({ "filter[search]": text })`,角色列表,以及 `filterProfiles` 使用相同的现场匹配。 生成的 `operations.profileSearchSearchPost({ search: text })` 并匹配短ID和 返回时 `short_id` 每次攻击,即使 `include` 不包括核心领域 操作需要 `profile:search`。最小的人目录接受相同的 在下面寻找 `profile:lookup` 不返回国家代码.

代码来源于配置行 `id`, (中文(简体) ), **没有** `user_id`,没有新的数据库 栏。 匹配忽略了大小写,使波斯/阿拉伯数字正常化. 输入完整 6-字符代码;相撞返回所有相匹配的结果. 使用它的其他细节选择要配置文件,然后使用它 `user_id` 页:1 配置读取/更新路由. `shortIdFromUuid` 用于离线显示. 在使用这些搜索之前先部署服务短ID迁移.

## 常见问题

### @faiber/faiber-profile 是什么？

剖面,原子部分更新,动态属性,地理记录,关系,媒体,搜索,可信赖的服务,和剖面日志\.

### 如何安装 @faiber/faiber-profile？

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

### @faiber/faiber-profile 支持 TypeScript 吗？

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

### @faiber/faiber-profile 支持 ESM 还是 CommonJS？

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

### @faiber/faiber-profile 可以商用吗？

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

### @faiber/faiber-profile 的下载量有多少？

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

### @faiber/faiber-profile 还在维护吗？

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