website-docs/04-api/02-api-infra.md
路由注册：internal/router/router.go 的 RegisterVectorStoreRoutes、RegisterStorageBackendRoutes、RegisterWebSearchRoutes、RegisterWebSearchProviderRoutes、RegisterDataSourceRoutes。Handler：internal/handler/vectorstore.go、internal/handler/storagebackend.go、internal/handler/web_search.go、internal/handler/web_search_provider.go、internal/handler/web_search_provider_credentials.go、internal/handler/datasource.go、internal/handler/datasource_credentials.go。
统一约定：读 Viewer+，写/连接测试 Admin+（凭证探测外部系统）。API key capability：向量库 manage_vector_stores、存储后端 manage_storage_backends、Web 搜索 manage_web_search、数据源 manage_datasources（均可 full-access）。
用途：可用引擎类型与配置 schema。权限：Viewer+。
响应：200 {"success":true,"data":[类型定义]}
curl $BASE/api/v1/vector-stores/types -H "Authorization: Bearer $TOKEN"
用途：用原始配置测试连接（不落库）。权限：Admin+。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
engine_type | string | 是（binding:"required"） | 引擎类型 |
connection_config | object | 是（binding:"required"） | 连接配置 |
响应：200 {"success":true|false,"version":"...","error":"..."}
curl -X POST $BASE/api/v1/vector-stores/test -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"engine_type":"qdrant","connection_config":{"addr":"qdrant:6334"}}'
用途：创建向量库配置。权限：Admin+。字段：name（必填）、engine_type（必填）、connection_config（必填）、index_config（可选）。
响应：201 {"success":true,"data":{VectorStoreResponse}}（id,tenant_id,name,engine_type,connection_config,index_config,...）
curl -X POST $BASE/api/v1/vector-stores -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"name":"qdrant-main","engine_type":"qdrant","connection_config":{"addr":"qdrant:6334"}}'
用途：向量库列表（环境变量注入的 __env_* store 在前）。权限：Viewer+。
响应：200 {"success":true,"data":[VectorStoreResponse]}
curl $BASE/api/v1/vector-stores -H "Authorization: Bearer $TOKEN"
用途：向量库详情（支持 __env_* ID）。权限：Viewer+。
响应：200 {"success":true,"data":{VectorStoreResponse}}
curl $BASE/api/v1/vector-stores/vs-1 -H "Authorization: Bearer $TOKEN"
用途：更新（仅重命名；env store 不可改）。权限：Admin+。请求体：{"name":"..."}（binding:"required"）。
响应：200 {"success":true,"data":{VectorStoreResponse}}
curl -X PUT $BASE/api/v1/vector-stores/vs-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"name":"qdrant-prod"}'
用途：删除（env store 不可删）。权限：Admin+。
响应：200 {"success":true}
curl -X DELETE $BASE/api/v1/vector-stores/vs-1 -H "Authorization: Bearer $TOKEN"
用途：测试已保存/env 向量库。权限：Admin+。
响应：200 {"success":true|false,"version","error"}
curl -X POST $BASE/api/v1/vector-stores/vs-1/test -H "Authorization: Bearer $TOKEN"
请求体（Create/Update/TestRaw 共用 storageBackendRequest）：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | 是（binding:"required"） | 名称 |
provider | string | 是（binding:"required"） | 提供方（minio/cos/tos/s3/oss/ks3/obs…） |
config | object | 否 | 提供方配置（响应中凭证掩码） |
status | string | 否 | 状态 |
用途：允许的存储类型。权限：Viewer+。响应：200 {"success":true,"data":[...]}
curl $BASE/api/v1/storage-backends/types -H "Authorization: Bearer $TOKEN"
用途：原始配置连接测试。权限：Admin+。响应：200 {"success":bool,"error"}
curl -X POST $BASE/api/v1/storage-backends/test -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"name":"t","provider":"minio","config":{"endpoint":"minio:9000"}}'
用途：创建存储后端。权限：Admin+。响应：201 {"success":true,"data":{StorageBackend}}
curl -X POST $BASE/api/v1/storage-backends -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"name":"minio-main","provider":"minio","config":{"endpoint":"minio:9000"}}'
用途：列表（含 default_storage_backend_id）。权限：Viewer+。响应：200 {"success":true,"data":[...],"default_storage_backend_id":"..."}
curl $BASE/api/v1/storage-backends -H "Authorization: Bearer $TOKEN"
用途：详情（凭证掩码）。权限：Viewer+。响应：200 {"success":true,"data":{StorageBackend}}
curl $BASE/api/v1/storage-backends/sb-1 -H "Authorization: Bearer $TOKEN"
用途：更新。权限：Admin+。响应：200 {"success":true,"data":{StorageBackend}}
curl -X PUT $BASE/api/v1/storage-backends/sb-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"name":"minio-prod","provider":"minio"}'
用途：删除。权限：Admin+。响应：200 {"success":true}
curl -X DELETE $BASE/api/v1/storage-backends/sb-1 -H "Authorization: Bearer $TOKEN"
用途：测试已保存后端。权限：Admin+。响应：200 {"success":bool,"error"}
curl -X POST $BASE/api/v1/storage-backends/sb-1/test -H "Authorization: Bearer $TOKEN"
用途：设为默认后端。权限：Admin+。响应：200 {"success":true}
curl -X PUT $BASE/api/v1/storage-backends/sb-1/default -H "Authorization: Bearer $TOKEN"
用途：内置搜索提供方目录（只读）。权限：Viewer+，仅 JWT（未声明 API key 策略）。Handler: internal/handler/web_search.go
响应：200 {"success":true,"data":[...]}
curl $BASE/api/v1/web-search/providers -H "Authorization: Bearer $TOKEN"
用途：提供方类型与参数 schema。权限：Viewer+。Handler: internal/handler/web_search_provider.go
响应：200 {"success":true,"data":[...]}
curl $BASE/api/v1/web-search-providers/types -H "Authorization: Bearer $TOKEN"
用途：原始凭证测试（不落库）。权限：Admin+。请求体：provider（binding:"required"）、parameters（可选）。
响应：200 {"success":bool,"error"}
curl -X POST $BASE/api/v1/web-search-providers/test -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"provider":"tavily","parameters":{"api_key":"tvly-..."}}'
用途：创建提供方配置。权限：Admin+。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | 是（binding:"required"） | 名称 |
provider | string | 是（binding:"required"） | 类型（bing/tavily/google…） |
description | string | 否 | 描述 |
parameters | object | 否 | 参数（api_key 建议走 credentials 子资源） |
is_default | bool | 否 | 默认提供方 |
响应：201 {"success":true,"data":{WebSearchProviderResponse}}
curl -X POST $BASE/api/v1/web-search-providers -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"name":"tavily-main","provider":"tavily"}'
用途：提供方列表。权限：Viewer+。响应：200 {"success":true,"data":[...]}
curl $BASE/api/v1/web-search-providers -H "Authorization: Bearer $TOKEN"
用途：详情。权限：Viewer+。响应：200 {"success":true,"data":{...}}
curl $BASE/api/v1/web-search-providers/wsp-1 -H "Authorization: Bearer $TOKEN"
用途：更新（空字段保留原值；APIKey 保留）。权限：Admin+。请求体：name/description/parameters/is_default（均可选）。
响应：200 {"success":true,"data":{...}}
curl -X PUT $BASE/api/v1/web-search-providers/wsp-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"is_default":true}'
用途：删除。权限：Admin+。响应：200 {"success":true}
curl -X DELETE $BASE/api/v1/web-search-providers/wsp-1 -H "Authorization: Bearer $TOKEN"
用途：设置 API key（{"api_key":"..."}，省略时返回状态）。权限：Admin+。Handler: internal/handler/web_search_provider_credentials.go
响应：200 {"success":true,"data":{"fields":{"api_key":{"configured":bool}}}}
curl -X PUT $BASE/api/v1/web-search-providers/wsp-1/credentials -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"api_key":"tvly-..."}'
用途：删除凭证字段（field 仅 api_key）。权限：Admin+。响应：204。
curl -X DELETE $BASE/api/v1/web-search-providers/wsp-1/credentials/api_key -H "Authorization: Bearer $TOKEN"
用途：测试已保存提供方。权限：Admin+。响应：200 {"success":bool,"error"}
curl -X POST $BASE/api/v1/web-search-providers/wsp-1/test -H "Authorization: Bearer $TOKEN"
外部内容连接器（Feishu/Notion/语雀等），同步任务会写入 KB。Handler: internal/handler/datasource.go。本组多数响应为原始对象/数组（无 success 包装）。
用途：可用连接器目录。权限：Viewer+。
响应：200 [{type,name,description,icon,priority,auth_type,capabilities}]
curl $BASE/api/v1/datasource/types -H "Authorization: Bearer $TOKEN"
用途：校验原始凭证（“测试连接”按钮，不落库）。权限：Admin+。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
type | string | 是（binding:"required"） | 连接器类型 |
credentials | map | 是（binding:"required"） | 凭证 |
响应：200 {"status":"connected"}；失败 400 {"error":"..."}
curl -X POST $BASE/api/v1/datasource/validate-credentials -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"type":"notion","credentials":{"token":"secret"}}'
用途：创建数据源。权限：Admin+。请求体（types.DataSource）：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
knowledge_base_id | string | 是 | 目标 KB（须归属本空间） |
name | string | 是 | 名称 |
type | string | 是 | 连接器类型 |
config | object | 是 | 凭证（加密存储）+资源选择+设置 |
sync_schedule | string | 否 | cron 表达式 |
sync_mode | string | 否 | incremental（默认）/full |
conflict_strategy | string | 否 | overwrite（默认）/skip |
sync_deletions | bool | 否 | 默认 true |
sync_log_retention_days | int | 否 | 默认 30 |
响应：201 DataSourceResponse（凭证剥离，见 internal/handler/dto/datasource.go）。
curl -X POST $BASE/api/v1/datasource -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"knowledge_base_id":"kb-1","name":"notion 同步","type":"notion","config":{}}'
用途：数据源列表。权限：Viewer+。查询参数：kb_id（必填）。
响应：200 [DataSourceResponse]
curl "$BASE/api/v1/datasource?kb_id=kb-1" -H "Authorization: Bearer $TOKEN"
用途：详情。权限：Viewer+。响应：200 DataSourceResponse；404 {"error":"data source not found"}
curl $BASE/api/v1/datasource/ds-1 -H "Authorization: Bearer $TOKEN"
用途：更新（id/tenant_id/knowledge_base_id 锁定为原值）。权限：Admin+。请求体同创建。
响应：200 DataSourceResponse
curl -X PUT $BASE/api/v1/datasource/ds-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"name":"notion 同步 v2","type":"notion","knowledge_base_id":"kb-1","config":{}}'
用途：删除。权限：Admin+。响应：204。
curl -X DELETE $BASE/api/v1/datasource/ds-1 -H "Authorization: Bearer $TOKEN"
用途：整体替换凭证（数据源凭证为“单一逻辑字段 credentials”的原子 map）。权限：Admin+。请求体：{"credentials":{...}}（非空 map 必填）。Handler: internal/handler/datasource_credentials.go
响应：200 {"success":true,"data":{"fields":{"credentials":{"configured":bool}}}}
curl -X PUT $BASE/api/v1/datasource/ds-1/credentials -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"credentials":{"token":"secret"}}'
用途：清空凭证（field 必须为 credentials）。权限：Admin+。响应：204。
curl -X DELETE $BASE/api/v1/datasource/ds-1/credentials/credentials -H "Authorization: Bearer $TOKEN"
用途：校验已保存数据源连接。权限：Admin+。响应：200 {"status":"connected"}
curl -X POST $BASE/api/v1/datasource/ds-1/validate -H "Authorization: Bearer $TOKEN"
用途：浏览外部资源树（懒加载）。权限：Admin+。查询参数：parent_id（可选，空=顶层）。
响应：200 [{external_id,name,type,description,url,modified_at,parent_id,has_children,metadata}]
curl "$BASE/api/v1/datasource/ds-1/resources?parent_id=" -H "Authorization: Bearer $TOKEN"
用途：解析资源祖先链（选择器展开）。权限：Admin+。请求体：{"resource_ids":["..."]}（必填）。
响应：200 {"ancestors":[...]}
curl -X POST $BASE/api/v1/datasource/ds-1/resource-ancestors -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"resource_ids":["page-1"]}'
用途：手动触发同步。权限：Admin+。响应：200 SyncLog（id,status,started_at,items_total,items_created,items_updated,items_deleted,items_failed,...）
curl -X POST $BASE/api/v1/datasource/ds-1/sync -H "Authorization: Bearer $TOKEN"
用途：暂停 / 恢复定时同步。权限：Admin+。
响应：200 {"status":"paused"} / {"status":"active"}
curl -X POST $BASE/api/v1/datasource/ds-1/pause -H "Authorization: Bearer $TOKEN"
用途：同步日志列表。权限：Viewer+。查询参数：limit（默认 10，上限 100）、offset（默认 0）。
响应：200 [SyncLog]
curl "$BASE/api/v1/datasource/ds-1/logs?limit=10" -H "Authorization: Bearer $TOKEN"
用途：单条同步日志。权限：Viewer+。响应：200 SyncLog；404 {"error":"sync log not found"}
curl $BASE/api/v1/datasource/logs/log-1 -H "Authorization: Bearer $TOKEN"