更新日志

本页记录 ATKONBASE 对集成方可感知的对外能力变更——新增 / 调整的 V1 与公开分享端点、SDK 用法变化、契约调整、行为修正等。纯内部重构、构建基建调整等对集成方不可见的变更不在此列。

条目按日期倒序排列。标注 Breaking 的条目表示对已对接代码可能造成不兼容影响，升级前请重点关注。

2026-06-12

新增

• 文档列表与详情接口新增索引可观测能力：indexStatus 新增「未索引」（NOT_INDEXED）取值（未发布或无可检索内容的文档），并新增 indexFailReason 字段——索引失败时直接返回失败原因摘要（仅失败状态填充），便于集成方排查某文档为何未进入全文检索结果。

2026-06-11

新增

• 全文检索（POST /v1/search/query）结果条目新增携带命中文档的元数据字段：按调用方身份的字段级权限投影——有字段权限的主体可看到受控字段值，无权限时该值自动隐藏，与详情 / 列表读取的可见性口径一致。

变更

• Breaking 租户管理员不再默认获得内容下载权限：下载改为需对其主体显式授予下载权限后方可放行。原依赖租户管理员身份直接下载内容的集成，需为相应主体补授下载权限。
• 安全加固：声明为「可搜索 + 访问受控」的字段，其值不进入全文索引——全文检索不会命中或回显受控字段值，受控字段值的可见性一律由字段级权限决定。

修复

• 修复用户上传文档后、本人立即检索不到自己刚上传文档的问题：现资源创建者自创建起即持有该资源的完整权限（即便所在容器无显式授权、或仅以较小权限授予本人），可检索命中并管理自己创建的内容。
• 修复两类导致「已发布文档按正文检索不到」的健壮性问题：上传与系统内已有内容相同的文件时，偶发正文不进入全文检索、内容下载失败（现自动校验并修复）；文档重新建立索引时，正文偶发从检索结果中暂时丢失（现保留原有可检索正文并自动恢复）。
• 修复文档切换内容类型后，其全文检索结果仍停留在旧类型口径的问题：现切换后该文档的可检索内容自动同步到新类型（含类型编码与元数据）；内容类型的能力声明（如是否进入全文检索、是否受字段级权限管控）调整后，关联文档的检索口径同样自动同步刷新。

2026-06-10

修复

• 修复 RAG 检索（POST /v1/rag/retrieve）在部分请求下偶发失败或返回空结果的问题，检索可用性显著提升。

2026-06-08

新增

• 上传 / 新建文档时目标容器改为可选：未指定 containerId 时，文档自动归入当前租户的「默认容器」（首次需要时由系统自动创建并维护），无需先创建或选定容器即可上传。默认容器不可删除 / 改名 / 移动（操作返回错误码 175031 DEFAULT_CONTAINER_PROTECTED），确保上传落点始终稳定可用。
• 新增系统维护模式的对外契约：平台进入维护窗口期间，除鉴权令牌签发、公开分享访问与健康检查外的 V1 端点统一返回错误码 178004 MAINTENANCE_MODE_ACTIVE（msg 携带维护原因文案），便于集成方识别维护窗口并优雅降级；维护结束后原请求原样重发即可。含义与处理建议见错误码参考。

2026-06-07

修复

• 修复中文密集长文档的部分内容在 RAG 检索中无法被召回的问题：现长文档可完整参与语义召回。

2026-06-06

新增

• 新增 RAG 检索接口 POST /v1/rag/retrieve：按查询文本召回调用方有权访问的内容片段（chunk），返回片段正文、定位坐标（span）与源文档 / 版本标识，可回链原文，供集成方构建 RAG（检索增强生成）应用。支持按容器限定检索范围（containerId），并可指定返回条数（topK，默认 10、上限 100）。
• 新增「RAG 检索」授权范围 client:rag:retrieve：与全文检索独立授权，默认不预授任何客户端，需显式授权后方可调用。
• 全文检索新增周期性一致性自愈：个别文档的更新如因瞬时故障漏同步、或索引内容与已发布版本出现偏差，后台对账会自动补齐纠正，使检索结果最终与已发布内容保持一致。

变更

• Breaking 全文检索（关键词 / 混合检索）的结果范围调整为「仅已发布版本」：文档的可检索内容随其发布版本更新；未发布 / 草稿状态、以及无任何可检索正文与元数据的文档不再进入全文检索结果。
• Breaking 全文检索索引改为最终一致刷新：文档发布、内容 / 元数据 / 权限变更后，其检索可见性在下一次索引同步周期生效，不再保证修改后即时可检索。依赖「写入后立即可检索」的集成需调整预期或在业务侧做短暂重试。

修复

• 修复已到期但尚未被系统回收的分享在状态查询中仍显示「有效」的问题：现实时返回「已过期」，与分享的真实可用状态一致。

2026-06-02

变更

• Breaking 字段「敏感等级」（公开 / 内部 / 受限三档）模型下线，收敛为「访问受控」单一开关 + 字段级授权：
  • 字段能力声明中的 FIELD_SENSITIVITY（取值 PUBLIC / INTERNAL / RESTRICTED）已移除，由布尔能力 ACCESS_CONTROLLED（访问受控）取代；读取字段定义与模型 Schema 导出的集成方需改按 ACCESS_CONTROLLED 处理。
  • 原两个敏感字段可见性授权范围 client:storage:metadata:sensitive:internal / client:storage:metadata:sensitive:restricted 同步下线；受控字段值的访问改由客户端「所代表用户」获得的字段级读 / 写授权决定。
  • 迁移采用『默认拒绝』口径：原「内部 / 受限」字段一律转为「访问受控」且默认对所有人不可见，需由管理方对相应主体重新授予字段级读 / 写权限后方可恢复访问；原「公开」字段保持透传、不受影响。
• 受控字段在详情查看、列表、结构化检索与写入各场景下，一致地按字段级权限管控；对受控字段无查看权限的用户，按该字段值筛选不再命中相关内容，避免经检索结果反推受控字段取值。「访问受控」既可对单个字段声明，也可对内容类型声明（后者使该类型及其子类型下的字段统一受控）。

修复

• 修复创建内容时携带「必填 + 访问受控」字段值被错误拒绝的问题：现创建者可正常携带受控字段值完成创建（创建容器与上传新建文档两条路径），创建完成后该字段的读写仍按字段级权限管控。
• 请求体格式错误（字段取值非法、JSON 语法错误等）现返回指明出错字段或位置的可读提示，不再笼统返回「服务器内部错误」，便于调用方区分请求问题与服务端故障。

2026-05-31

新增

• V1 接口错误码大幅扩充，并同步至 Java / TypeScript SDK 的错误码常量。覆盖文件上传 / 下载（/v1/versions/*）、服务端摄入（/v1/ingest/*）、元数据值读写与列表筛选（/v1/metadata/values/*、资源表单 Schema、字段定义查询、模型 Schema 导出）、内容类型（/v1/contentTypes/*）、文档生命周期（/v1/documents/*）、容器生命周期（/v1/containers/*）、站内分享与分享链接（/v1/share-grants/*、/v1/share-links/*）、内容 ACL（/v1/acl/*）以及资源访问前置校验等链路。集成方可据具体业务 code 区分上传冲突 / 会话状态 / 配额超限 / 元数据校验失败 / 资源状态不允许此操作 / 作用域不足等失败原因，而非笼统错误。各码含义、典型触发条件与处理建议见错误码参考。
• 新增「V1 ACL 端点需委派用户身份」错误码：调用 /v1/acl/* 时若会话仅有客户端凭证、未下发用户身份（用户 token 或 act-as 委派头），返回明确错误码而非通用错误。
• 新增「检索入参不足」错误码：调用 /v1/search/query 时 keyword 与 fields 至少需提供其一，否则返回明确错误码。

变更

• 至此全部 V1 接口的错误响应均携带稳定业务错误码（此前部分场景仅返回通用错误 code=1）。集成方可对全部 V1 接口按响应体 code 做统一识别与处理。注意通用 code=1 兜底分支仍需保留——少数未指定具体错误码的业务异常、参数缺失 / 类型不匹配等仍以 code=1 + msg 返回，集成方不应假设错误码集合封闭，请保留通用兜底分支处理未指定码。

修复

• 修复通过外部 URL 异步摄入（大文件 / 大小未知场景）建立的文档与版本「创建者」信息缺失的问题：现与同步上传一致，可正确追溯创建者。

2026-05-30

新增

• TypeScript SDK 新增错误码常量集合 errorCodes，与 Java SDK 同口径对齐。集成方可直接引用具名常量（如 errorCodes.PERMISSION_DENIED）识别和处理 V1 接口错误，无需直接写死数字码。

2026-05-29

新增

• V1 字段定义查询与模型 Schema 导出接口新增字段敏感性保护：默认未获授权的集成方仅能读到「公开」字段，「内部 / 受限」字段不再返回。新增两个授权 scope client:storage:metadata:sensitive:internal 与 client:storage:metadata:sensitive:restricted，可按客户端单独授予；获授后方可在上述接口中读到对应敏感级别的字段。

变更

• Breaking V1 字段定义查询与模型 Schema 导出接口的字段结构调整：原先各自独立返回的「是否可搜索 / 是否可筛选 / 敏感等级」三个字段，现统一并入字段的 capabilities（能力声明）对象一并返回；已对接这些字段的集成方需改按 capabilities 结构读取。

2026-05-28

新增

• 公开分享消费侧错误码纳入对外契约与 SDK 常量：SHARE_LINK_UNAVAILABLE (174001)、SHARE_LINK_QUOTA_EXCEEDED (174008)、PASSWORD_REQUIRED (174009)、PASSWORD_INVALID (174010)、PASSWORD_NOT_REQUIRED (174011)、IP_NOT_ALLOWED (174013)、SHARE_LINK_PATH_INVALID (174014)。集成方消费 /public/s/{tenantCode}/{token}/... 公开分享链路时，可直接用这些错误码（及 Java SDK 中对应常量）识别失败原因；错误码参考的《Share 错误码》同步补齐了各码含义、典型触发条件与处理建议。

变更

• Breaking 权限不足 / Scope 不足的接口响应统一为 HTTP 200 + 业务错误码（102001 权限不足、102002 Scope 不足），不再以 HTTP 403 区分。集成方应按响应体 code 判定失败原因；原依赖 403 状态码判断权限 / Scope 失败的代码需相应调整。

2026-05-27

新增

• 新增服务端摄入能力：在客户端直传之外，提供两条由服务端把内容引入系统的入口（适用于迁移、批量灌库与外部系统同步），建立的版本与上传路径共享一致的版本链、权限继承、元数据、配额与 Webhook 治理。
  • POST /v1/ingest/from-url：提交外部 URL 与目标容器 / 文档，服务端拉取内容并建立正式版本。小文件同步返回结果版本；大文件或大小未知时自动转为异步任务，先返回受理回执，完成后通过 document.updated Webhook 通知。
  • POST /v1/ingest/register-object：对已通过预签名直传或带外迁移放入存储的对象，仅登记为正式版本而不重新搬运字节，按存储中对象的真实大小计入配额。
  • GET /v1/ingest/task：查询「从 URL 异步拉取」任务的处理状态，成功时返回结果文档与版本标识，失败时返回失败原因。

修复

• 修复本地存储部署形态下 POST /v1/versions/signed-url 签发的一次性直读链接无法下载文件的问题：此前消费该链接始终返回签名无效，导致单机 / 本地部署的签名直读链路不可用，现已可在链接有效期内正常取得文件字节。

2026-05-26

新增

• 新增 V1 端点 POST /v1/versions/presign-upload：客户端声明文件元信息（originalFilename / sizeBytes / mimeType）与上传目标（已有文档传 docId，新建文档传 containerId + title）后，服务端完成鉴权与存储配额预检，返回一个限时的预签名 PUT URL（presignedUrl + expiresAt）；客户端据此将文件字节直接 PUT 至对象存储，适合大附件与高并发上传。响应 mode=presigned 表示已签发直传 URL；当存储后端不支持预签名时返回 mode=fallback，并在 fallbackEndpoint 指明改用既有 /v1/versions/upload，保持单一上传代码路径。PUT 时必须按 signedHeaders 携带与签名一致的请求头（首版为 Content-Type）。
• 新增 V1 端点 POST /v1/versions/finalize-upload：客户端完成直传后以 presign 返回的 uploadId 回调本端点，服务端校验对象已就位、实测大小与声明一致、配额未超限且具备资源访问权限，通过后才创建新版本并完成版本链衔接、ACL 继承、元数据写入、配额计量与 document.created 事件触发；任一校验失败均拒绝建版。响应结构与 /v1/versions/upload 一致（docId / versionId / versionNo 等）。未在有效期内 finalize 的会话及其残留对象由平台自动回收。
• 新增 V1 端点 POST /v1/versions/signed-url：以 versionId 请求一个短时直读 URL，服务端鉴权后签发，客户端拿到 url 后直接 GET 即可取得文件字节，无需再经上传 / 下载端点中转。有效期由 expiresInSec 指定，缺省 300 秒、上限 3600 秒。
• /v1/versions/signed-url 支持 mode=preview：签发的 URL 以 Content-Disposition: inline + 实际 MIME 类型响应，浏览器无需下载即可在新标签页直接渲染图片 / PDF / 纯文本 / 音视频；mode=download 则以 attachment 形态触发下载。预览模式实施 MIME 白名单（image/*、application/pdf、text/plain、audio/*、video/*），出于安全考虑 image/svg+xml 不在白名单内；命中白名单之外的类型时端点返回错误并提示改用 mode=download。

修复

• 修复 /v1/containers/update 在请求体未携带 containerId 时返回「资源不存在: null」这类误导性信息的问题：现明确返回「请求体必须指定 containerId」（业务码 CONTAINER_ID_REQUIRED），便于客户端识别参数缺失场景。

2026-05-25

新增

• 新增 /v1/metadata/values/getBatch 批量查询元数据端点：传入单一 resourceType 与一组 resourceId（上限 200），一次返回各资源的元数据值，替代逐资源调用 values/get。逐资源做 READ 鉴权——无权或不存在的资源不出现在结果中（二者不作区分），可读但无值的资源以空值列表返回，按 resourceId 匹配即可。
• Webhook 事件投递能力正式上线：此前订阅可创建但平台不实际推送，现在业务操作提交后会异步向订阅 URL 投递事件（至少一次送达、失败按指数退避重试），event-types 列出的 8 类事件（document.created / document.updated / document.deleted / document.archived、container.created / container.updated / container.deleted、acl.changed）均已接入真实触发点。投递以明文 JSON 传输、暂不携带签名。
• Webhook 订阅新增可选的出站投递授权 token（请求字段 deliveryToken）：配置后，平台投递本订阅的事件时以 Authorization: Bearer <token> 请求头携带，供接收端校验推送确实来自本平台。该字段为只写凭据，不在订阅详情、列表或保存响应中回显；保存时显式传值即覆盖、传空字符串即清除、不传则保持原值。

变更

• /v1/containers/update 改用 containerId 定位目标容器，不再要求传入内部 id（与 get / delete / move 等端点一致），无需再先调 containers/get 取主键后才能更新。
• /v1/containers/update 明确 metadataColumns 为只读输出字段：更新容器时该字段写时忽略，容器元数据的修改请走 /v1/metadata/values/set。注意 create 仍会写入 metadataColumns，与 update 语义不同。
• 明确 V1 通道错误约定并纳入接口契约：HTTP 200 不代表业务成功，需校验响应体 code（0 成功 / 1 业务失败）；仅认证失败、权限不足、资源不存在、请求头校验失败与服务端内部错误返回非 2xx，且 401 / 403 / 404 / 500 的错误响应信封已统一为标准 ResponseDTO。约定与各端点错误响应已在契约中显式建模，据此生成的 SDK 可直接消费。
• 使用委派（act-as）请求头调用 V1 端点时，请求头组合非法现明确返回 HTTP 400 并纳入接口契约：互斥头 X-Atk-User-Token 与 X-Atk-Act-As-Source / X-Atk-Act-As-Source-Id 同时携带返回业务码 INVALID_DELEGATION_HEADERS；X-Atk-Act-As-Source 与 X-Atk-Act-As-Source-Id 未成对携带返回 INCOMPLETE_ACT_AS_HEADERS。
• /v1/documents/update 不再受理 state 字段：内容状态变更请改用归档 / 删除 / 恢复等专用接口，更新时传入任意状态值将被拒绝（此前字段描述误示可设置 ACTIVE / ARCHIVED，与实际行为不符，现已更正）。

修复

• 修复 /v1/containers/get 与 /v1/containers/create 返回体中 metadataColumns 恒为空的问题：现返回该容器的全量元数据（含未在列表展示的字段，如颜色），值形态与分页列表一致。
• 修复某些情况下创建或更新 Webhook 订阅失败、导致 Webhook 功能不可用的问题。
• 修复仅更新容器名称 / 描述、或切换容器 ACL 继承开关时，订阅方收不到 container.updated 事件推送的问题：现在容器的任意属性更新都会触发一次该事件（容器类型变更的既有推送行为不变）。

2026-05-24

文档

• 开发者门户「指南」补齐四篇能力模式篇：认证与身份双通道、ACL 与继承、文件上传链路均提供可复制的完整示例；Webhook 页如实说明「订阅可配、投递推送 / 签名 / 重试尚未上线」，提示勿据此对接投递。

2026-05-22

新增

• V1 通道响应统一携带服务端生成的 X-Request-Id 响应头与响应体 rid 字段，拿到错误响应时可凭该 ID 联系支持团队精确定位单次调用。
• 模型 Schema 导出响应顶层新增 enumDefinitions 枚举字典，可直接消费各字段合法枚举值列表。
• 模型 Schema 导出（V1）新增 includeSystem 查询参数：V1 默认仅返回业务可见类型。

变更

• 文件上传端点（V1 upload 与 uploadChunk）请求契约升级为规范 multipart/form-data：业务字段统一打包进 metadata JSON part，不再以 URL query 承载；长 title 或大 metadata 不再触发 URL 长度限制，用户输入也不再出现在访问日志；据此生成的 SDK 可直接使用。
• Breaking：字段定义与模板的「适用目标」由 DOCUMENT / CONTAINER / ALL 三值单选改为 DOCUMENT / CONTAINER 多选集合；对应 targetType 字段统一替换为 applicableTargets（数组）。原 ALL 模板继承后等价于同时适用文档与容器，行为与历史一致。
• 系统类型 code 由 document-root / container-root 改名为 document_root / container_root，与自定义类型命名形态对齐。

2026-05-08

新增

• V1 版本下载接口（/v1/versions/download）支持 HTTP Range 请求：HTML5 <video> 可任意 seek、PDF.js 可范围加载、超大文件断点续传；响应头新增 Accept-Ranges: bytes。
• V1 版本接口新增分片上传三端点（initChunkedUpload / uploadChunk / completeChunkedUpload），可在 V1 通道断点续传与并发分片上传大文件。
• V1 文档 / 容器各新增 4 个批量端点（batchDelete / batchMove / 回收站 batchRestore / batchPurge），单批最多 100 条，支持部分失败语义；统一返回 BatchResultDTO（{ success: [...], failed: [{id, code, msg}] }）。
• 回收站超期文档 / 容器自动彻底清除（默认 30 天）；支持租户级「回收站保留天数」覆盖；V1 列表返回 purgeAt 倒计时字段；新增 GET /v1/system/getTrashRetention 查询当前生效保留天数。
• V1 文档列表 DTO 新增 mimeType、originalFilename、currentVersionNo；当前用户接口 DTO 新增 tenantCode、tenantName、displayName；新增 GET /v1/contentTypes/getByCode。

2026-05-07

新增

• v1 SDK 新增按容器 / 按文档获取实例级表单 Schema 的接口，返回含资源级模板叠加字段、遗留字段与当前值，并标注每个字段来源类型。
• v1 SDK 新增按容器查祖先链接口（GET /v1/containers/getAncestors），可在容器树 UI 实现「展开到指定节点 / 反显已选目标」。
• atkonbase-sdk 新增公开分享通路（独立 AtkonbasePublicClient）：覆盖匿名分享链接元信息查询、密码校验、下载 URL 拼接与文件夹浏览（list / buildDownloadUrl），与 V1 client 类型层物理隔离。
• 公开分享支持「文件夹分享」：可对整个文件夹生成公开链接，外部访问者逐层浏览与按需下载；元信息接口新增 shareKind（FILE / FOLDER）与 rootName。
• 新增「读取当前租户存储用量」接口（GET /v1/tenants/me/storage，scope client:storage:tenant:read）：默认返回逻辑用量，可选物理用量；返回值带约 5 分钟缓存延迟，应视为采样值。

变更

• v1 容器子查询接口（GET /v1/containers/getChildren）支持 containerId 留空返回根容器列表，每条新增 hasChildren 字段，作为容器树懒加载起点。

移除

• Breaking：v1 容器全树查询接口 GET /v1/containers/getTree 下线，统一切到懒加载（getChildren 取子层 + getAncestors 取祖先链）；SDK 方法 containerGetTree 同步移除，旧调用返回 404。

2026-05-06

新增

• 创建 Webhook 时事件类型由服务端统一校验，传入未支持或已废弃的类型会被拒绝并提示具体值。
• TypeScript / Java SDK 新增查询 Webhook 事件类型清单的方法（webhookListEventTypes）。
• 创建文档后会自动为订阅 document.created（或通配 *）的活跃 Webhook 生成投递记录，可在投递列表查看。

修复

• 修复账密 / SSO / V1 代账密登录及刷新接口返回的登录用户 ID 与展示名为空的问题；SDK 接入方现可稳定取到登录用户标识（纯应用模式 client_credentials 仍按设计不返回这两字段）。

2026-05-05

新增

• 集成方现可通过 V1 接口为本地账密用户颁发 user token，无需让用户跳转到控制台登录页。

变更

• V1 SDK（TypeScript / Java）按 17 个业务域拆分为独立 API 类，方法定位更直观；Java SDK 新增 act-as 三 header 透传支持，可调用 V1 强通道接口。

2026-05-03

新增

• OpenAPI / Swagger UI / SDK codegen 产物标题与描述统一为 ATKONBASE API 品牌名。
• V1 集成接口的 OpenAPI 文档显式声明三个「代表用户」请求头（强通道用户 Token、弱通道来源 + 来源 ID），SDK codegen 时即可在 V1 端点方法签名上看到对应可选参数，并明确强弱通道互斥与弱通道双头成对规则及错误码。
• TypeScript SDK 在构造 Client 与每次请求时即时校验互斥 / 成对约束，配置错误立即抛错。

变更

• TypeScript SDK 鉴权配置由「clientToken / session 双模式」简化为单一 V1 形态：clientToken 必填，按需可选 userToken 或 actAs。

移除

• Breaking：旧版手写 Java SDK 模块整体下线，老 import 不再可用；后续 Java SDK 由 OpenAPI codegen 路线独立发布并随其提供迁移指南。
• TypeScript SDK 移除旧的会话令牌鉴权模式与对应类型导出。

2026-05-01

新增

• API Client 可按 Client 显式启用 / 关闭「允许代表用户调用」（弱通道，请求头主张代表用户身份），默认关闭。
• V1 集成接口支持以请求头携带「代表用户」身份调用：用户已通过 ATKONBASE 登录时走强通道（用户会话 Token），用户身份由集成方系统侧已认证时走弱通道（来源 + 来源 ID，需 Client 已显式获授权）。
• 用户角色 / 部门 / 状态变更后，下一次 V1 调用即时反映新权限范围，收回权限不再需要等待 Token 过期。

变更

• 安全加固：收紧 V1 跨租户调用的身份与权限校验；SSO 登录回调的租户归属处理一并加固。

移除

• Breaking：V1 集成接口 /v1/auth/token-exchange 端点下线，grant_type=jwt-bearer 协议不再支持；集成方今后仅通过 client_credentials 经 /v1/auth/token 获取 Token。
• Breaking：Java SDK 移除 asUser() 派生客户端入口与 AssertionProvider 配置项；SDK 仅承载 APP_ONLY 服务间调用，「代表用户」语义改由 V1 请求头双通道承接。

2026-04-30

变更

• Breaking：V1 用户类响应（/v1/users/me/detail 等）移除 name 字段，用户昵称统一以 nickname 返回。面向不通过官方 SDK 直接对接 V1 的消费方：原依赖 name 的代码需切换为 nickname。

2026-04-29

变更

• ACL 授权主体从单一「Principal」抽象升级为多态模型（用户 / 角色 / 部门）：授权时分别选择三类主体可分别授权，granteeType 取值为 USER / ROLE / DEPARTMENT。

2026-04-26

新增

• SSO 单点登录首次登录由系统自动建档：通过 OIDC 协议（CAS / 标准 OIDC IdP）首次登录的用户无需事先在控制台手工同步即可直接登录，系统按 IdP 返回标识自动落库，登录后默认无菜单权限由管理员后续按需绑定（钉钉协议仍要求先经全量同步）。
• 业务方 V1 接口新增「当前用户自服务」入口（/v1/users/me，6 个端点）：覆盖基本信息、详情（主部门 / 所有部门 / 所有角色 / 权限码并集）、资料更新、改密、部门归属、角色归属；改密接口对外部身份源接管的用户直接拒绝并提示联系来源管理员。
• 业务方 V1 部门接口补齐祖先链与下级查询端点（/v1/departments/listAncestors、/v1/departments/listDescendants）。

移除

• Breaking：业务终端用户接入通道（/portal/*）整族下线，相关应用配置入口一并移除；业务用户场景统一通过 V1 接口（含强 / 弱双通道）承接。
• Breaking：principal 抽象的同步与解析端点整族（/v1/principals 同步 / 解析）下线，统一改用 /v1/users/*、/v1/roles/*、/v1/departments/* 或 /v1/principals/resolve。

2026-04-25

移除

• Breaking：审计与元数据变更历史能力下线——Console / V1 元数据历史端点移除；SDK 移除审计与元数据历史相关类（PageAuditRequest、GetAuditRequest、AuditEventResult、PageMetadataHistoryRequest、MetadataHistoryResult）。元数据当前值仍可读写，但不再记录历史轨迹。

2026-04-24

新增

• V1 业务身份 API 新增「用户部门归属」与「用户持有角色」读端点：一次请求拿到某用户的主部门 + 全部归属部门、全部业务角色，无需从部门 / 角色反查。
• V1 部门 / 角色 API 新增「批量加成员 / 批量移成员」端点：批内任意一条违反「本地部门只接受本地来源用户 / 外部来源部门只接受同源用户」规则会整批回滚。
• V1 业务用户更新接口扩展「主部门 / 归属部门 / 持有角色」字段，一次请求完成用户归属完整调整（主部门必须出现在归属部门列表内）。

变更

• 跨来源成员关系写入做后端硬校验：把外部来源用户加入本地部门、或把本地用户加入外部来源部门的请求会被直接拒绝。

2026-04-23

新增

• 新增 V1 业务身份 API：/v1/users/*、/v1/roles/*、/v1/departments/* 覆盖业务用户 / 角色 / 部门的分页、详情、按部门 / 角色查成员、创建、更新、禁用、设凭据、删除；/v1/principals/resolve 提供按 principal_id 反查业务主体的统一能力。
• 新增 6 条 client scope：client:identity:{user|role|department}:{read|write}。

变更

• 外部身份源同步单条失败不再导致整批回滚，按成功 / 失败条数汇报。

移除

• Breaking：旧 V1 /v1/principals/* 业务 API 路径整族（getPage / get / save / batchSave / update / upsert / relations/* 等）下线，集成方须改用 /v1/users/*、/v1/roles/*、/v1/departments/* 或 /v1/principals/resolve。

2026-04-22

新增

• 新增「站内分享」：资源所有者可把容器或文档分享给系统内其他用户 / 角色 / 部门，接收方登录后自动获得相应访问权限；支持 VIEW / EDIT 两档预设、过期时间（最长 90 天）、撤销、附言。

2026-04-21

新增

• 容器支持按容器关闭 ACL 继承，配合新建文档时给创建者自动授全位权限，实现「同一容器内每人只见自己文件」的个人空间场景。

2026-04-20

新增

• ACL Policy 支持一条规则同时授权给多个主体、匹配多个容器类型，无需重复建规则；自定义授权方式提供 6 个权限位（READ / DOWNLOAD / WRITE / DELETE / SHARE / MANAGE）。

变更

• ACL Policy 不再需要手工填写「Policy 编码」，由系统自动生成唯一 ID。

移除

• ACL Policy 的 policyCode 字段从 API 中移除。

2026-04-19

新增

• 新增外链分享下载：资源管理员可为文档或版本生成带 token 的公开下载链接，支持有效期、访问密码、最大访问次数、IP 白名单；匿名用户凭链接即可下载，无需登录。创建者可查看每条链接的访问记录，管理员可强制撤销。

2026-04-18

新增

• 新增业务终端用户接入通道（/portal/*）：第三方前端可服务业务用户，支持账密、OIDC 单点登录、钉钉免登三种登录方式，并可访问文档 / 容器 / 版本 / 元数据 / 搜索 / ACL 等核心能力。

注：该通道已于 2026-04-26 整族下线，业务用户场景改由 V1 强 / 弱双通道承接。

2026-04-16

新增

• API Client 容器访问策略支持「全租户」选项，可一键授权访问当前租户全部容器；容器访问策略提供「禁止访问 / 白名单 / 全租户」三档，默认禁止访问。
• 内容类型支持「直接字段」：无需创建模板即可给类型挂字段，并可覆盖必填与默认值。

变更

• 创建容器 / 上传文档时「类型」改为可选，不选择时自动使用默认类型并应用其必填字段。

修复

• 归档状态的文档可正常取消归档、移入回收站；容器移动接口不再因省略目标父容器参数返回 500。

2026-04-13

新增

• Java SDK 新增 TRUSTED_DELEGATED 认证模式，支持通过 client.asUser() 代用户调用 API，并提供 AssertionProvider 回调接口自定义 assertion 签名；APP_ONLY 与 TRUSTED_DELEGATED 可在同一客户端内共存。（注：该用法已于 2026-05-01 改由 V1 请求头双通道承接。）

修复

• 文件上传时多值元数据字段填写单个值、布尔类型字段写入不再校验失败；布尔字段在分页筛选中查询结果正确。

2026-04-12

新增

• 新增 Deny 类型 ACL Policy（拒绝权限策略）；新增 Policy Dry Run 预览（创建前预估影响资源数量与样本）；新增已有 Policy 更新条件的 Diff 预览。

变更

• Policy 分页查询支持按授权类型（ALLOW / DENY）筛选；ACL 条目区分手动 / 继承 / Policy 自动生成三类来源。

2026-04-11

新增

• 创建子容器时自动继承父容器的元数据模板和字段值。

修复

• 容器反归档此前未检查祖先容器是否已归档，可能导致状态不一致，现已补齐祖先链拦截。

2026-04-10

新增

• ACL 设置接口支持通过角色名（viewer / editor / manager）设置权限，检查接口支持通过权限名称（READ / WRITE 等）检查；ACL 列表与有效权限响应新增角色标签与 Principal 名称、来源类型。SDK 新增角色常量与强类型权限检查响应。
• 新增 ACL Policy 引擎：支持创建 / 查询 / 更新 / 删除 / 启停 Policy 规则、声明式权限自动化、存量资源回溯扫描、影响查询，并提供全套 Java SDK 支持。手动设置的权限不受 Policy 自动化影响。
• 钉钉集成新增角色同步，SSO 登录用户不再需要管理员手工分配角色。

变更

• 权限拒绝响应从 HTTP 200 + 错误码改为 HTTP 403 + 结构化错误体，错误体包含人类可读消息与机器可读详情；权限码校验失败同样返回 HTTP 403。

2026-04-07

修复

• 安全加固：收紧敏感（RESTRICTED）元数据字段的写入权限校验。

2026-04-06

新增

• 新增 V1 搜索接口（TRUSTED_DELEGATED 模式）：支持按标题 / 正文 / 文件名 / 元数据跨字段搜索文档，可按类型、时间范围与自定义元数据字段精确过滤；支持 PDF / Word / Excel / PPT / 纯文本 / HTML 正文检索；搜索结果严格遵循 ACL，用户只能搜到有读权限的文档。
• 元数据字段敏感性分级：支持 PUBLIC / INTERNAL / RESTRICTED 三级可见性控制，统一覆盖所有元数据读写路径（V1 按敏感级跳过无权字段）。
• 新增文档类型级版本保留策略（最大版本数、保留天数），系统定时自动清理超出策略的历史版本。

修复

• 安全加固：收紧 ACL 端点对 APP_ONLY / TRUSTED_DELEGATED 调用方的访问控制。

2026-04-05

新增

• 新增容器统计 API（GET /v1/containers/stats），返回容器下文档数、子容器数、存储量。
• 新增批量 ACL 权限查询（POST /v1/acl/batchCheck）；SDK 新增对应请求 / 结果类。
• 新增元数据变更历史能力（V1 metadata/history/getPage 端点 + SDK MetadataHistoryResult），记录字段值 old/new 快照。（注：该能力已于 2026-04-25 完全下线。）

修复

• 用户创建的顶层容器可正常删除 / 归档 / 取消归档 / 恢复 / 清除；系统根容器不可执行生命周期操作。

2026-04-04

新增

• 容器元数据继承（Copy-on-Create）：文档创建时自动继承容器的可继承模板绑定和元数据值。

变更

• 容器现可绑定 targetType=DOCUMENT 的模板（资源级与类型级同步放宽）。

修复

• 字段默认值清空（defaultValue=""）未生效的问题；受信委派模式下列表端点补齐容器范围过滤，权限收敛正确。

2026-04-03

变更

• 创建文档 / 容器时类型处于 DEPRECATED / DISABLED 状态给出区分的错误提示。

修复

• 多值元数据字段传入纯非法操作符（不含 $add/$remove）时返回「不支持的增量操作符」而非「多值字段必须提供数组」。