外观
集成开发指南
受众：把 atkonbase 接入自家业务系统的集成开发者（ISV / 低代码厂商 / 自研业务后端）
阅读路径：先看概念建立领域认知，再看本区「入门篇」跑通第一次 V1 调用；遇到错误响应时去错误码参考查
code字段含义；后续模式篇按需查阅。
这里是什么
atkonbase 是「可编程的内容能力底座」（参见概念总览）——最终用户的 UI、编辑器、工作流由集成方自行实现。本区是集成开发者的官方对接指南锚点，按"先入门、再分主题模式"的节奏组织。
篇章一览
| 篇章 | 内容 | 状态 |
|---|---|---|
| 入门篇 walkthrough | 一条从已开通租户跑通第一次 V1 调用的端到端线索：认证 → 上传 → 元数据查回 → ACL 设置 | ✅ 可用 |
| 认证与身份双通道 | client credentials 取 token + 强通道 X-Atk-User-Token / 弱通道 X-Atk-Act-As-Source* + token 生命周期 + 跨租户规约 | ✅ 可用 |
| 业务身份 | 业务用户 / 角色 / 部门三类对象 + source 与跨源约束 + granteeId 解析 + 当前用户自助查询 | ✅ 可用 |
| ACL 与继承 | 权限位与预设角色 + 容器→文档继承 + 有效权限检查 + AclPolicy 规模化授权与 dry-run | ✅ 可用 |
| 文件上传链路 | multipart 单传 vs 分片三段式选型 + 断点续传 + 限额 + blob 去重与版本关系 | ✅ 可用 |
| 文档与版本 | 版本链生成 / 查询 / 回退 + 保留策略（maxVersionCount / retentionDays）+ 发布 / 归档 / 回收站投影 | ✅ 可用 |
| 容器模型与层级 | 容器层级查询 + 跨层移动 / 重命名 + aclInheritEnabled 断继承入口 + 容器生命周期（归档 / 回收站 / purge） | ✅ 可用 |
| 元数据与 schema | ContentType / Field / Template 模型 + 字段值读写 + 按字段筛选 + FormSchema + 访问受控字段的读写与可见性 | ✅ 可用 |
| Webhook（预览） | 订阅 CRUD 与事件类型查询的现状说明 —— ⚠️ 投递推送 / 签名 / 重试尚未上线，勿据此对接投递 | 🔶 预览（投递未上线） |
| 生命周期 | 发布 / 归档 / 回收站 / 彻底清除 + 批量操作 + trash 保留期 + 各状态可见性投影与级联 | ✅ 可用 |
| 分享 | 站内分享（ShareGrant）+ 公开链接（ShareLink）+ 权限预设、token 契约与公开下载流 | ✅ 可用 |
| 全文搜索 | /v1/search/query 关键词搜索 + 容器 / 类型 / 字段筛选 + 高亮语义 + 与元数据筛选的边界 | ✅ 可用 |
| RAG 检索 | /v1/rag/retrieve 语义片段召回 + 回链坐标（sourceDocId / sourceVersion / span）+ RAG 流程组装 | ✅ 可用 |
| 多租户与用量 | 多租户隔离模型 + 存储用量与配额查询 + 按租户聚合二次计费 | ✅ 可用 |
| 数据导出 | 完整数据导出包的结构、二进制本体清单与预签名下载、manifest 自描述与可移植性声明 | ✅ 可用 |
| 错误码参考 | V1 接口返回的业务 errorCode 清单，按业务域分组（认证 101* / 权限 102* / ... / Share 174*） | ✅ 可用 |
文档约定
- 示例语言：所有端到端示例使用 curl / HTTP 协议层最低公约数，不绑定任何语言 SDK 风格。语言 SDK 的使用方法由 SDK 文档承载
- 错误码引用：示例中出现的 errorCode 通过链接指向错误码参考对应业务域文件 + 章节锚点
- 示例占位符：示例中
${variable}形式的占位符（如${accessToken}、${docId}）需替换为实际值；与环境相关的 base URL 统一示意为https://api.atkonbase.example.com，集成时按部署实际地址替换
反馈
发现示例与实际不符、缺少关键模式篇、文档表述不清等问题，请通过技术支持渠道反馈。