{ "meta": { "projectName": "24 - OpenClaw 能力拓展平台", "projectCode": "occap", "baseUrl": "https://api.example.com", "version": "v0.1", "updatedAt": "2026-04-19", "owner": "项目团队" }, "responseConvention": { "successCode": 1000, "fields": [ { "name": "code", "type": "number", "required": true, "desc": "业务状态码" }, { "name": "message", "type": "string", "required": true, "desc": "结果说明" }, { "name": "data", "type": "object", "required": true, "desc": "业务数据" } ], "traceHeader": "X-Trace-Id", "traceNote": "异常与部分成功响应均应在响应头返回 X-Trace-Id，与 errors 中说明一致，便于日志关联。" }, "modules": [ { "id": "auth", "name": "认证", "interfaces": [ { "id": "admin-auth-login", "name": "管理端登录", "method": "POST", "path": "/admin/base/open/login", "status": "current", "authRequired": false, "summary": "租户/平台管理员登录", "businessPoints": [ "返回 JWT" ], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "username", "type": "string", "required": true, "desc": "账号" }, { "name": "password", "type": "string", "required": true, "desc": "密码" } ] }, "requestExample": { "username": "admin", "password": "******" }, "response": { "fields": [ { "name": "data.token", "type": "string", "required": true, "desc": "访问令牌" }, { "name": "data.user_id", "type": "number", "required": true, "desc": "用户ID" }, { "name": "data.role", "type": "string", "required": true, "desc": "角色" }, { "name": "data.tenant_id", "type": "number", "required": false, "desc": "租户ID（平台超管无）" }, { "name": "data.nickname", "type": "string", "required": false, "desc": "昵称" }, { "name": "data.expires_in", "type": "number", "required": true, "desc": "过期秒数" } ] }, "errors": [ { "httpStatus": 401, "bizCode": 4010, "message": "认证失败", "desc": "账号或密码错误" }, { "httpStatus": 429, "bizCode": 4290, "message": "请求过于频繁", "desc": "登录限流" } ] }, { "id": "auth-refresh-token", "name": "刷新 Token", "method": "POST", "path": "/auth/refresh", "status": "planned", "authRequired": false, "summary": "用 RefreshToken 换新 AccessToken", "businessPoints": [], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "refresh_token", "type": "string", "required": true, "desc": "RefreshToken" } ] }, "requestExample": { "refresh_token": "eyJ..." }, "response": { "fields": [ { "name": "data.access_token", "type": "string", "required": true, "desc": "JWT AccessToken" }, { "name": "data.refresh_token", "type": "string", "required": true, "desc": "新的 RefreshToken" }, { "name": "data.expires_in", "type": "number", "required": true, "desc": "过期秒数" } ] }, "errors": [ { "httpStatus": 401, "bizCode": 4012, "message": "RefreshToken 无效或已过期", "desc": "" } ] }, { "id": "auth-logout", "name": "登出", "method": "POST", "path": "/auth/logout", "status": "planned", "authRequired": true, "summary": "清除本地 Session 和 Redis 中的会话", "businessPoints": [], "request": { "headers": [], "pathParams": [], "query": [], "body": [] }, "requestExample": {}, "response": { "fields": [ { "name": "data.ok", "type": "boolean", "required": true, "desc": "是否成功" } ] }, "errors": [] }, { "id": "auth-current-user", "name": "当前登录用户", "method": "GET", "path": "/auth/current-user", "status": "planned", "authRequired": true, "summary": "获取当前登录用户信息及权限", "businessPoints": [], "request": { "headers": [], "pathParams": [], "query": [], "body": [] }, "requestExample": {}, "response": { "fields": [ { "name": "data.id", "type": "number", "required": true, "desc": "用户ID" }, { "name": "data.username", "type": "string", "required": true, "desc": "用户名" }, { "name": "data.nickname", "type": "string", "required": false, "desc": "昵称" }, { "name": "data.role", "type": "string", "required": true, "desc": "角色" }, { "name": "data.tenant_id", "type": "number", "required": false, "desc": "租户ID" }, { "name": "data.email", "type": "string", "required": false, "desc": "邮箱" }, { "name": "data.phone", "type": "string", "required": false, "desc": "手机号" }, { "name": "data.status", "type": "string", "required": true, "desc": "账号状态 active|disabled" }, { "name": "data.permissions", "type": "array", "required": true, "desc": "权限列表" } ] }, "errors": [] }, { "id": "admin-user-page", "name": "用户分页列表", "method": "POST", "path": "/admin/occapUser/page", "status": "planned", "authRequired": true, "summary": "平台运营/租户管理员查看用户列表", "businessPoints": [ "平台超管可指定 tenant_id 筛选" ], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "page", "type": "number", "required": true, "desc": "页码" }, { "name": "size", "type": "number", "required": true, "desc": "每页条数" }, { "name": "tenant_id", "type": "number", "required": false, "desc": "平台超管可指定租户筛选" }, { "name": "role", "type": "string", "required": false, "desc": "角色筛选" }, { "name": "status", "type": "string", "required": false, "desc": "账号状态 active|disabled" }, { "name": "keyword", "type": "string", "required": false, "desc": "用户名/手机号关键词" } ] }, "requestExample": { "page": 1, "size": 20 }, "response": { "fields": [ { "name": "data.list", "type": "array", "required": true, "desc": "用户列表" }, { "name": "data.pagination.total", "type": "number", "required": true, "desc": "总条数" }, { "name": "data.pagination.page", "type": "number", "required": true, "desc": "当前页" }, { "name": "data.pagination.size", "type": "number", "required": true, "desc": "每页条数" } ] }, "errors": [ { "httpStatus": 401, "bizCode": 4010, "message": "未授权", "desc": "JWT 无效" }, { "httpStatus": 403, "bizCode": 4030, "message": "无权限", "desc": "非平台运营或租户管理员" } ] }, { "id": "admin-user-create", "name": "创建用户", "method": "POST", "path": "/admin/occapUser", "status": "planned", "authRequired": true, "summary": "平台运营或租户管理员创建用户", "businessPoints": [], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "username", "type": "string", "required": true, "desc": "用户名" }, { "name": "password", "type": "string", "required": true, "desc": "初始密码（6-32位）" }, { "name": "role", "type": "string", "required": true, "desc": "platform_ops|tenant_admin|tenant_member|isv|audit_readonly" }, { "name": "tenant_id", "type": "number", "required": false, "desc": "租户ID（platform_super 外必填）" }, { "name": "email", "type": "string", "required": false, "desc": "邮箱" }, { "name": "phone", "type": "string", "required": false, "desc": "手机号" }, { "name": "nickname", "type": "string", "required": false, "desc": "昵称" } ] }, "requestExample": { "username": "zhangsan", "password": "******", "role": "tenant_member", "tenant_id": 1 }, "response": { "fields": [ { "name": "data.id", "type": "number", "required": true, "desc": "用户ID" } ] }, "errors": [ { "httpStatus": 400, "bizCode": 4001, "message": "用户名已存在", "desc": "" }, { "httpStatus": 400, "bizCode": 4000, "message": "参数错误", "desc": "角色与租户不匹配" } ] }, { "id": "admin-user-update", "name": "更新用户", "method": "PUT", "path": "/admin/occapUser/{id}", "status": "planned", "authRequired": true, "summary": "更新用户信息（角色/状态/手机）", "businessPoints": [], "request": { "headers": [], "pathParams": [ { "name": "id", "type": "number", "required": true, "desc": "用户ID" } ], "query": [], "body": [ { "name": "role", "type": "string", "required": false, "desc": "角色 platform_ops|tenant_admin|tenant_member|isv|audit_readonly" }, { "name": "status", "type": "string", "required": false, "desc": "账号状态 active|disabled" }, { "name": "phone", "type": "string", "required": false, "desc": "手机号" }, { "name": "email", "type": "string", "required": false, "desc": "邮箱" }, { "name": "nickname", "type": "string", "required": false, "desc": "昵称" } ] }, "requestExample": { "id": 1, "status": "disabled" }, "response": { "fields": [ { "name": "data.ok", "type": "boolean", "required": true, "desc": "是否成功" } ] }, "errors": [ { "httpStatus": 404, "bizCode": 4040, "message": "用户不存在", "desc": "" }, { "httpStatus": 403, "bizCode": 4030, "message": "无权限", "desc": "不可修改比自己权限高的用户" } ] }, { "id": "admin-user-delete", "name": "删除用户", "method": "DELETE", "path": "/admin/occapUser/{id}", "status": "planned", "authRequired": true, "summary": "删除用户（软删除）", "businessPoints": [], "request": { "headers": [], "pathParams": [ { "name": "id", "type": "number", "required": true, "desc": "用户ID" } ], "query": [], "body": [] }, "requestExample": {}, "response": { "fields": [ { "name": "data.ok", "type": "boolean", "required": true, "desc": "是否成功" } ] }, "errors": [ { "httpStatus": 404, "bizCode": 4040, "message": "用户不存在", "desc": "" }, { "httpStatus": 403, "bizCode": 4030, "message": "无权限", "desc": "不可删除比自己权限高的用户" } ] }, { "id": "admin-user-reset-password", "name": "重置密码", "method": "POST", "path": "/admin/occapUser/{id}/reset-password", "status": "planned", "authRequired": true, "summary": "管理员重置用户密码", "businessPoints": [], "request": { "headers": [], "pathParams": [ { "name": "id", "type": "number", "required": true, "desc": "用户ID" } ], "query": [], "body": [] }, "requestExample": {}, "response": { "fields": [ { "name": "data.temp_password", "type": "string", "required": true, "desc": "临时密码（首次登录须修改）" } ] }, "errors": [ { "httpStatus": 404, "bizCode": 4040, "message": "用户不存在", "desc": "" } ] }, { "id": "admin-role-list", "name": "角色列表", "method": "GET", "path": "/admin/occapRole/list", "status": "planned", "authRequired": true, "summary": "获取全部角色定义（平台超管/运营可见）", "businessPoints": [], "request": { "headers": [], "pathParams": [], "query": [], "body": [] }, "requestExample": {}, "response": { "fields": [ { "name": "data.list", "type": "array", "required": true, "desc": "角色列表" }, { "name": "data.list[].code", "type": "string", "required": true, "desc": "角色编码" }, { "name": "data.list[].name", "type": "string", "required": true, "desc": "角色名称" }, { "name": "data.list[].description", "type": "string", "required": false, "desc": "描述" }, { "name": "data.list[].level", "type": "number", "required": true, "desc": "权限级别（数字越小权限越高）" } ] }, "errors": [] }, { "id": "admin-permission-list", "name": "权限列表", "method": "GET", "path": "/admin/occapPermission/list", "status": "planned", "authRequired": true, "summary": "获取全部权限点列表", "businessPoints": [], "request": { "headers": [], "pathParams": [], "query": [], "body": [] }, "requestExample": {}, "response": { "fields": [ { "name": "data.list", "type": "array", "required": true, "desc": "权限列表" }, { "name": "data.list[].code", "type": "string", "required": true, "desc": "权限编码" }, { "name": "data.list[].name", "type": "string", "required": true, "desc": "权限名称" }, { "name": "data.list[].group", "type": "string", "required": true, "desc": "所属分组" } ] }, "errors": [] } ] }, { "id": "tenant", "name": "租户", "interfaces": [ { "id": "admin-tenant-page", "name": "租户分页", "method": "POST", "path": "/admin/occapTenant/page", "status": "current", "authRequired": true, "summary": "运营侧租户列表", "businessPoints": [ "支持 keyword、状态筛选" ], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "page", "type": "number", "required": true, "desc": "页码" }, { "name": "size", "type": "number", "required": true, "desc": "每页条数" }, { "name": "keyword", "type": "string", "required": false, "desc": "名称/code 关键词" }, { "name": "status", "type": "string", "required": false, "desc": "active|frozen" }, { "name": "plan_id", "type": "number", "required": false, "desc": "套餐ID筛选" } ] }, "requestExample": { "page": 1, "size": 20 }, "response": { "fields": [ { "name": "data.list", "type": "array", "required": true, "desc": "租户列表" }, { "name": "data.pagination.total", "type": "number", "required": true, "desc": "总条数" }, { "name": "data.pagination.page", "type": "number", "required": true, "desc": "当前页" }, { "name": "data.pagination.size", "type": "number", "required": true, "desc": "每页条数" } ] }, "errors": [ { "httpStatus": 401, "bizCode": 4010, "message": "未授权", "desc": "JWT 无效" }, { "httpStatus": 403, "bizCode": 4030, "message": "无权限", "desc": "非 platform_ops" } ] }, { "id": "admin-tenant-create", "name": "创建租户", "method": "POST", "path": "/admin/occapTenant", "status": "planned", "authRequired": true, "summary": "平台运营创建新租户", "businessPoints": [], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "name", "type": "string", "required": true, "desc": "租户名称" }, { "name": "code", "type": "string", "required": true, "desc": "租户编码（唯一）" }, { "name": "plan_id", "type": "number", "required": true, "desc": "初始套餐ID" }, { "name": "contact_name", "type": "string", "required": false, "desc": "联系人姓名" }, { "name": "contact_email", "type": "string", "required": false, "desc": "联系人邮箱" }, { "name": "contact_phone", "type": "string", "required": false, "desc": "联系人手机" }, { "name": "expire_time", "type": "string", "required": false, "desc": "到期时间 ISO8601" } ] }, "requestExample": { "name": "测试租户", "code": "test_tenant", "plan_id": 1 }, "response": { "fields": [ { "name": "data.id", "type": "number", "required": true, "desc": "租户ID" } ] }, "errors": [ { "httpStatus": 400, "bizCode": 4001, "message": "租户编码已存在", "desc": "" } ] }, { "id": "admin-tenant-update", "name": "租户更新", "method": "POST", "path": "/admin/occapTenant/update", "status": "current", "authRequired": true, "summary": "冻结、套餐绑定等", "businessPoints": [ "乐观锁 version 可选" ], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "id", "type": "number", "required": true, "desc": "租户 ID" }, { "name": "plan_id", "type": "number", "required": false, "desc": "套餐" }, { "name": "status", "type": "string", "required": false, "desc": "active|frozen" }, { "name": "contact_name", "type": "string", "required": false, "desc": "联系人姓名" }, { "name": "contact_email", "type": "string", "required": false, "desc": "联系人邮箱" }, { "name": "contact_phone", "type": "string", "required": false, "desc": "联系人手机" }, { "name": "expire_time", "type": "string", "required": false, "desc": "到期时间 ISO8601" }, { "name": "version", "type": "number", "required": false, "desc": "乐观锁版本号" } ] }, "requestExample": { "id": 1, "status": "frozen" }, "response": { "fields": [ { "name": "data.id", "type": "number", "required": true, "desc": "租户 ID" } ] }, "errors": [ { "httpStatus": 404, "bizCode": 4040, "message": "资源不存在", "desc": "租户不存在" }, { "httpStatus": 409, "bizCode": 4090, "message": "并发冲突", "desc": "版本冲突请重试" } ] }, { "id": "admin-tenant-detail", "name": "租户详情", "method": "GET", "path": "/admin/occapTenant/{id}", "status": "planned", "authRequired": true, "summary": "获取租户详细信息", "businessPoints": [], "request": { "headers": [], "pathParams": [ { "name": "id", "type": "number", "required": true, "desc": "租户ID" } ], "query": [], "body": [] }, "requestExample": {}, "response": { "fields": [ { "name": "data.id", "type": "number", "required": true, "desc": "租户ID" }, { "name": "data.name", "type": "string", "required": true, "desc": "租户名称" }, { "name": "data.code", "type": "string", "required": true, "desc": "租户编码" }, { "name": "data.status", "type": "string", "required": true, "desc": "状态 active|frozen" }, { "name": "data.plan_id", "type": "number", "required": true, "desc": "当前套餐ID" }, { "name": "data.plan_name", "type": "string", "required": false, "desc": "当前套餐名称" }, { "name": "data.expire_time", "type": "string", "required": false, "desc": "到期时间 ISO8601" }, { "name": "data.contact_name", "type": "string", "required": false, "desc": "联系人姓名" }, { "name": "data.contact_email", "type": "string", "required": false, "desc": "联系人邮箱" }, { "name": "data.contact_phone", "type": "string", "required": false, "desc": "联系人手机" }, { "name": "data.user_count", "type": "number", "required": true, "desc": "用户数量" }, { "name": "data.created_at", "type": "string", "required": true, "desc": "创建时间 ISO8601" }, { "name": "data.updated_at", "type": "string", "required": true, "desc": "更新时间 ISO8601" } ] }, "errors": [ { "httpStatus": 404, "bizCode": 4040, "message": "租户不存在", "desc": "" } ] }, { "id": "admin-plan-list", "name": "套餐列表", "method": "GET", "path": "/admin/occapPlan/list", "status": "planned", "authRequired": true, "summary": "获取所有可用套餐", "businessPoints": [], "request": { "headers": [], "pathParams": [], "query": [], "body": [] }, "requestExample": {}, "response": { "fields": [ { "name": "data.list", "type": "array", "required": true, "desc": "套餐列表" }, { "name": "data.list[].id", "type": "number", "required": true, "desc": "套餐ID" }, { "name": "data.list[].name", "type": "string", "required": true, "desc": "套餐名称" }, { "name": "data.list[].code", "type": "string", "required": true, "desc": "套餐编码" }, { "name": "data.list[].price", "type": "number", "required": true, "desc": "价格（元/月）" }, { "name": "data.list[].period", "type": "string", "required": true, "desc": "计费周期 month|year" }, { "name": "data.list[].entitlements", "type": "array", "required": true, "desc": "套餐包含的授权项" }, { "name": "data.list[].user_limit", "type": "number", "required": true, "desc": "用户数量上限" }, { "name": "data.list[].status", "type": "string", "required": true, "desc": "状态 active|inactive" } ] }, "errors": [] }, { "id": "admin-plan-create", "name": "创建套餐", "method": "POST", "path": "/admin/occapPlan", "status": "planned", "authRequired": true, "summary": "平台运营创建新套餐", "businessPoints": [], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "name", "type": "string", "required": true, "desc": "套餐名称" }, { "name": "code", "type": "string", "required": true, "desc": "套餐编码" }, { "name": "price", "type": "number", "required": true, "desc": "价格（元）" }, { "name": "period", "type": "string", "required": true, "desc": "计费周期 month|year" }, { "name": "entitlements", "type": "array", "required": true, "desc": "授权项列表" }, { "name": "user_limit", "type": "number", "required": true, "desc": "用户数量上限" }, { "name": "description", "type": "string", "required": false, "desc": "套餐描述" } ] }, "requestExample": { "name": "基础版", "code": "basic", "price": 99, "period": "month", "entitlements": [], "user_limit": 5 }, "response": { "fields": [ { "name": "data.id", "type": "number", "required": true, "desc": "套餐ID" } ] }, "errors": [ { "httpStatus": 400, "bizCode": 4001, "message": "套餐编码已存在", "desc": "" } ] } ] }, { "id": "asset", "name": "能力资产", "interfaces": [ { "id": "admin-asset-page", "name": "资产分页列表", "method": "POST", "path": "/admin/occapAsset/page", "status": "current", "authRequired": true, "summary": "按类型/状态筛选资产", "businessPoints": [ "支持 keyword 全文" ], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "page", "type": "number", "required": true, "desc": "页码" }, { "name": "size", "type": "number", "required": true, "desc": "每页条数" }, { "name": "type", "type": "string", "required": false, "desc": "skill|mcp_bundle|memory_policy" }, { "name": "status", "type": "string", "required": false, "desc": "draft|in_review|approved|rejected|archived" }, { "name": "keyword", "type": "string", "required": false, "desc": "标题/slug 关键词" }, { "name": "isv_id", "type": "number", "required": false, "desc": "ISV 筛选" } ] }, "requestExample": { "page": 1, "size": 20, "type": "skill" }, "response": { "fields": [ { "name": "data.list", "type": "array", "required": true, "desc": "资产列表" }, { "name": "data.pagination.total", "type": "number", "required": true, "desc": "总条数" }, { "name": "data.pagination.page", "type": "number", "required": true, "desc": "当前页" }, { "name": "data.pagination.size", "type": "number", "required": true, "desc": "每页条数" } ] }, "errors": [ { "httpStatus": 401, "bizCode": 4010, "message": "未授权", "desc": "JWT 无效" } ] }, { "id": "admin-asset-detail", "name": "资产详情", "method": "GET", "path": "/admin/occapAsset/{id}", "status": "planned", "authRequired": true, "summary": "获取资产完整信息", "businessPoints": [], "request": { "headers": [], "pathParams": [ { "name": "id", "type": "number", "required": true, "desc": "资产ID" } ], "query": [], "body": [] }, "requestExample": {}, "response": { "fields": [ { "name": "data.id", "type": "number", "required": true, "desc": "资产ID" }, { "name": "data.name", "type": "string", "required": true, "desc": "资产名称" }, { "name": "data.slug", "type": "string", "required": true, "desc": "资产slug（唯一标识）" }, { "name": "data.type", "type": "string", "required": true, "desc": "skill|mcp_bundle|memory_policy" }, { "name": "data.status", "type": "string", "required": true, "desc": "draft|in_review|approved|rejected|archived" }, { "name": "data.isv_id", "type": "number", "required": true, "desc": "ISV 用户ID" }, { "name": "data.isv_name", "type": "string", "required": false, "desc": "ISV 名称" }, { "name": "data.description", "type": "string", "required": false, "desc": "资产描述" }, { "name": "data.icon", "type": "string", "required": false, "desc": "图标 URL" }, { "name": "data.tags", "type": "array", "required": false, "desc": "标签列表" }, { "name": "data.current_version_id", "type": "number", "required": false, "desc": "当前版本ID" }, { "name": "data.current_version", "type": "string", "required": false, "desc": "当前版本号" }, { "name": "data.manifest", "type": "object", "required": false, "desc": "Manifest 内容" }, { "name": "data.created_at", "type": "string", "required": true, "desc": "创建时间 ISO8601" }, { "name": "data.updated_at", "type": "string", "required": true, "desc": "更新时间 ISO8601" } ] }, "errors": [ { "httpStatus": 404, "bizCode": 4040, "message": "资产不存在", "desc": "" } ] }, { "id": "admin-asset-review", "name": "资产评审", "method": "POST", "path": "/admin/occapAsset/review", "status": "current", "authRequired": true, "summary": "通过/驳回", "businessPoints": [ "写 AuditEvent" ], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "assetId", "type": "number", "required": true, "desc": "资产 ID" }, { "name": "action", "type": "string", "required": true, "desc": "approve|reject" }, { "name": "comment", "type": "string", "required": false, "desc": "驳回原因（reject 时必填）" } ] }, "requestExample": { "assetId": 10, "action": "approve", "comment": "" }, "response": { "fields": [ { "name": "data.ok", "type": "boolean", "required": true, "desc": "是否成功" } ] }, "errors": [ { "httpStatus": 400, "bizCode": 4000, "message": "参数错误", "desc": "reject 缺 comment" }, { "httpStatus": 404, "bizCode": 4040, "message": "资源不存在", "desc": "资产不存在" }, { "httpStatus": 409, "bizCode": 4090, "message": "状态不允许", "desc": "非 in_review 状态" } ] }, { "id": "admin-asset-version-page", "name": "资产版本分页", "method": "POST", "path": "/admin/occapAssetVersion/page", "status": "planned", "authRequired": true, "summary": "查看某资产的全部版本", "businessPoints": [], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "asset_id", "type": "number", "required": true, "desc": "资产ID" }, { "name": "page", "type": "number", "required": true, "desc": "页码" }, { "name": "size", "type": "number", "required": true, "desc": "每页条数" } ] }, "requestExample": { "asset_id": 1, "page": 1, "size": 20 }, "response": { "fields": [ { "name": "data.list", "type": "array", "required": true, "desc": "版本列表" }, { "name": "data.pagination.total", "type": "number", "required": true, "desc": "总条数" }, { "name": "data.pagination.page", "type": "number", "required": true, "desc": "当前页" }, { "name": "data.pagination.size", "type": "number", "required": true, "desc": "每页条数" } ] }, "errors": [] }, { "id": "admin-asset-version-detail", "name": "资产版本详情", "method": "GET", "path": "/admin/occapAssetVersion/{id}", "status": "planned", "authRequired": true, "summary": "获取版本详细信息", "businessPoints": [], "request": { "headers": [], "pathParams": [ { "name": "id", "type": "number", "required": true, "desc": "版本ID" } ], "query": [], "body": [] }, "requestExample": {}, "response": { "fields": [ { "name": "data.id", "type": "number", "required": true, "desc": "版本ID" }, { "name": "data.asset_id", "type": "number", "required": true, "desc": "资产ID" }, { "name": "data.version", "type": "string", "required": true, "desc": "语义化版本号" }, { "name": "data.status", "type": "string", "required": true, "desc": "draft|in_review|approved|rejected|archived" }, { "name": "data.upload_id", "type": "string", "required": false, "desc": "上传会话ID" }, { "name": "data.checksum", "type": "string", "required": false, "desc": "文件校验和 SHA256" }, { "name": "data.byte_size", "type": "number", "required": false, "desc": "文件大小（字节）" }, { "name": "data.manifest", "type": "object", "required": false, "desc": "Manifest 内容" }, { "name": "data.created_at", "type": "string", "required": true, "desc": "创建时间 ISO8601" }, { "name": "data.review_comment", "type": "string", "required": false, "desc": "评审意见" } ] }, "errors": [ { "httpStatus": 404, "bizCode": 4040, "message": "版本不存在", "desc": "" } ] }, { "id": "admin-asset-archive", "name": "归档资产", "method": "POST", "path": "/admin/occapAsset/{id}/archive", "status": "planned", "authRequired": true, "summary": "将资产标记为归档状态", "businessPoints": [], "request": { "headers": [], "pathParams": [ { "name": "id", "type": "number", "required": true, "desc": "资产ID" } ], "query": [], "body": [] }, "requestExample": {}, "response": { "fields": [ { "name": "data.ok", "type": "boolean", "required": true, "desc": "是否成功" } ] }, "errors": [ { "httpStatus": 404, "bizCode": 4040, "message": "资产不存在", "desc": "" }, { "httpStatus": 409, "bizCode": 4090, "message": "状态不允许", "desc": "已归档的资产不可再归档" } ] } ] }, { "id": "entitlement", "name": "授权", "interfaces": [ { "id": "admin-entitlement-page", "name": "授权分页", "method": "POST", "path": "/admin/occapEntitlement/page", "status": "current", "authRequired": true, "summary": "租户授权管理", "businessPoints": [ "Entitlement 与套餐联动" ], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "page", "type": "number", "required": true, "desc": "页码" }, { "name": "size", "type": "number", "required": true, "desc": "每页条数" }, { "name": "tenantId", "type": "number", "required": false, "desc": "筛选租户" }, { "name": "asset_id", "type": "number", "required": false, "desc": "筛选资产" }, { "name": "status", "type": "string", "required": false, "desc": "active|expired|revoked" } ] }, "requestExample": { "page": 1, "size": 20 }, "response": { "fields": [ { "name": "data.list", "type": "array", "required": true, "desc": "授权列表" }, { "name": "data.pagination.total", "type": "number", "required": true, "desc": "总条数" }, { "name": "data.pagination.page", "type": "number", "required": true, "desc": "当前页" }, { "name": "data.pagination.size", "type": "number", "required": true, "desc": "每页条数" } ] }, "errors": [ { "httpStatus": 400, "bizCode": 4000, "message": "参数错误", "desc": "" }, { "httpStatus": 500, "bizCode": 5000, "message": "服务器错误", "desc": "" } ] }, { "id": "admin-entitlement-grant", "name": "授予授权", "method": "POST", "path": "/admin/occapEntitlement", "status": "planned", "authRequired": true, "summary": "给租户授予某资产的授权", "businessPoints": [], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "tenant_id", "type": "number", "required": true, "desc": "租户ID" }, { "name": "asset_id", "type": "number", "required": true, "desc": "资产ID" }, { "name": "asset_version_id", "type": "number", "required": false, "desc": "资产版本ID（不填则为最新）" }, { "name": "source", "type": "string", "required": true, "desc": "plan_addon|plan_included|trial|purchase" }, { "name": "expire_time", "type": "string", "required": false, "desc": "到期时间 ISO8601（永久为空）" }, { "name": "max_users", "type": "number", "required": false, "desc": "最大用户数（空表示不限制）" } ] }, "requestExample": { "tenant_id": 1, "asset_id": 10, "source": "purchase", "expire_time": "2027-01-01T00:00:00Z" }, "response": { "fields": [ { "name": "data.id", "type": "number", "required": true, "desc": "授权ID" } ] }, "errors": [ { "httpStatus": 400, "bizCode": 4000, "message": "参数错误", "desc": "资产或租户不存在" }, { "httpStatus": 409, "bizCode": 4091, "message": "授权已存在", "desc": "不可重复授权" } ] }, { "id": "admin-entitlement-revoke", "name": "撤销授权", "method": "POST", "path": "/admin/occapEntitlement/revoke", "status": "planned", "authRequired": true, "summary": "撤销租户的某项授权", "businessPoints": [ "写 AuditEvent" ], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "id", "type": "number", "required": true, "desc": "授权ID" }, { "name": "reason", "type": "string", "required": false, "desc": "撤销原因" } ] }, "requestExample": { "id": 1, "reason": "退款" }, "response": { "fields": [ { "name": "data.ok", "type": "boolean", "required": true, "desc": "是否成功" } ] }, "errors": [ { "httpStatus": 404, "bizCode": 4040, "message": "授权不存在", "desc": "" }, { "httpStatus": 409, "bizCode": 4092, "message": "授权已撤销", "desc": "不可重复撤销" } ] }, { "id": "admin-entitlement-update", "name": "更新授权", "method": "POST", "path": "/admin/occapEntitlement/update", "status": "planned", "authRequired": true, "summary": "更新授权属性（到期时间、最大用户数）", "businessPoints": [], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "id", "type": "number", "required": true, "desc": "授权ID" }, { "name": "expire_time", "type": "string", "required": false, "desc": "到期时间 ISO8601（永久为空）" }, { "name": "max_users", "type": "number", "required": false, "desc": "最大用户数" } ] }, "requestExample": { "id": 1, "expire_time": "2028-01-01T00:00:00Z" }, "response": { "fields": [ { "name": "data.ok", "type": "boolean", "required": true, "desc": "是否成功" } ] }, "errors": [ { "httpStatus": 404, "bizCode": 4040, "message": "授权不存在", "desc": "" } ] }, { "id": "admin-entitlement-detail", "name": "授权详情", "method": "GET", "path": "/admin/occapEntitlement/{id}", "status": "planned", "authRequired": true, "summary": "获取授权详细信息", "businessPoints": [], "request": { "headers": [], "pathParams": [ { "name": "id", "type": "number", "required": true, "desc": "授权ID" } ], "query": [], "body": [] }, "requestExample": {}, "response": { "fields": [ { "name": "data.id", "type": "number", "required": true, "desc": "授权ID" }, { "name": "data.tenant_id", "type": "number", "required": true, "desc": "租户ID" }, { "name": "data.tenant_name", "type": "string", "required": false, "desc": "租户名称" }, { "name": "data.asset_id", "type": "number", "required": true, "desc": "资产ID" }, { "name": "data.asset_name", "type": "string", "required": false, "desc": "资产名称" }, { "name": "data.asset_type", "type": "string", "required": false, "desc": "资产类型" }, { "name": "data.asset_version_id", "type": "number", "required": false, "desc": "授权版本ID" }, { "name": "data.asset_version", "type": "string", "required": false, "desc": "授权版本号" }, { "name": "data.source", "type": "string", "required": true, "desc": "plan_addon|plan_included|trial|purchase" }, { "name": "data.status", "type": "string", "required": true, "desc": "active|expired|revoked" }, { "name": "data.max_users", "type": "number", "required": false, "desc": "最大用户数" }, { "name": "data.used_users", "type": "number", "required": true, "desc": "已使用用户数" }, { "name": "data.expire_time", "type": "string", "required": false, "desc": "到期时间 ISO8601" }, { "name": "data.created_at", "type": "string", "required": true, "desc": "创建时间 ISO8601" }, { "name": "data.updated_at", "type": "string", "required": true, "desc": "更新时间 ISO8601" } ] }, "errors": [ { "httpStatus": 404, "bizCode": 4040, "message": "授权不存在", "desc": "" } ] }, { "id": "open-entitlements-list", "name": "授权列表（开放）", "method": "GET", "path": "/open/v1/entitlements", "status": "planned", "authRequired": true, "summary": "当前租户可见资产授权摘要", "businessPoints": [ "门户市场数据源" ], "request": { "headers": [], "pathParams": [], "query": [ { "name": "page", "type": "number", "required": false, "desc": "页码" }, { "name": "size", "type": "number", "required": false, "desc": "每页条数" } ], "body": [] }, "requestExample": {}, "response": { "fields": [ { "name": "data.items", "type": "array", "required": true, "desc": "授权项" }, { "name": "data.pagination.total", "type": "number", "required": true, "desc": "总条数" } ] }, "errors": [ { "httpStatus": 401, "bizCode": 4010, "message": "未授权", "desc": "令牌无效" } ] } ] }, { "id": "search", "name": "搜索与开放读", "interfaces": [ { "id": "open-search-hybrid", "name": "混合搜索（规划）", "method": "POST", "path": "/open/v1/search", "status": "planned", "authRequired": true, "summary": "关键字 + 可选向量（租户隔离）", "businessPoints": [ "写入 occap_search_audit" ], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "q", "type": "string", "required": false, "desc": "关键词" }, { "name": "vector", "type": "boolean", "required": false, "desc": "是否启用语义" } ] }, "requestExample": { "q": "MCP 审批", "vector": true }, "response": { "fields": [ { "name": "data.items", "type": "array", "required": true, "desc": "命中资产摘要" } ] }, "errors": [ { "httpStatus": 400, "bizCode": 4000, "message": "参数错误", "desc": "查询过长或非法；traceId 见响应头 X-Trace-Id" }, { "httpStatus": 401, "bizCode": 4010, "message": "未授权", "desc": "API Key/JWT 无效；traceId 见响应头 X-Trace-Id" }, { "httpStatus": 429, "bizCode": 4290, "message": "请求过于频繁", "desc": "搜索限流；traceId 见响应头 X-Trace-Id" }, { "httpStatus": 503, "bizCode": 5030, "message": "向量服务不可用", "desc": "降级为关键字；traceId 见响应头 X-Trace-Id" } ], "testCases": { "postman": { "name": "混合搜索成功", "preRequest": "pm.environment.set('baseUrl', 'https://api.example.com');", "tests": [ "pm.test('status is 200', function () { pm.response.to.have.status(200); });", "pm.test('code is success', function () { var jsonData = pm.response.json(); pm.expect(jsonData.code).to.eql(1000); });" ], "variables": [ { "name": "baseUrl", "example": "https://api.example.com", "desc": "接口域名" } ] }, "apifox": { "name": "混合搜索成功", "steps": [ "携带租户 API Key 或 JWT", "发送 POST /open/v1/search", "断言 response.code == 1000" ] } } }, { "id": "open-entitlements-list", "name": "授权列表（开放）", "method": "GET", "path": "/open/v1/entitlements", "status": "planned", "authRequired": true, "summary": "当前租户可见资产授权摘要", "businessPoints": [ "门户市场数据源" ], "request": { "headers": [], "pathParams": [], "query": [ { "name": "page", "type": "number", "required": false, "desc": "页码" } ], "body": [] }, "requestExample": {}, "response": { "fields": [ { "name": "data.items", "type": "array", "required": true, "desc": "授权项" } ] }, "errors": [ { "httpStatus": 401, "bizCode": 4010, "message": "未授权", "desc": "令牌无效；traceId 见响应头 X-Trace-Id" }, { "httpStatus": 500, "bizCode": 5000, "message": "服务器错误", "desc": "内部异常；traceId 见响应头 X-Trace-Id" } ], "testCases": { "postman": { "name": "授权列表成功", "preRequest": "pm.environment.set('baseUrl', 'https://api.example.com');", "tests": [ "pm.test('status is 200', function () { pm.response.to.have.status(200); });", "pm.test('code is success', function () { var jsonData = pm.response.json(); pm.expect(jsonData.code).to.eql(1000); });" ], "variables": [ { "name": "baseUrl", "example": "https://api.example.com", "desc": "接口域名" } ] }, "apifox": { "name": "授权列表成功", "steps": [ "携带租户凭证", "发送 GET /open/v1/entitlements", "断言 response.code == 1000" ] } } } ] }, { "id": "subscription", "name": "订阅与授权", "interfaces": [ { "id": "open-subscription-list", "name": "订阅与购买项列表", "method": "GET", "path": "/open/v1/subscriptions", "status": "planned", "authRequired": true, "summary": "当前租户套餐、加购项、到期时间", "businessPoints": [ "门户订阅页数据源" ], "request": { "headers": [], "pathParams": [], "query": [], "body": [] }, "requestExample": {}, "response": { "fields": [ { "name": "data.items", "type": "array", "required": true, "desc": "订阅项" } ] }, "errors": [ { "httpStatus": 401, "bizCode": 4010, "message": "未授权", "desc": "traceId 见响应头 X-Trace-Id" }, { "httpStatus": 500, "bizCode": 5000, "message": "服务器错误", "desc": "traceId 见响应头 X-Trace-Id" } ], "testCases": { "postman": { "name": "订阅列表", "preRequest": "pm.environment.set('baseUrl', 'https://api.example.com');", "tests": [ "pm.test('status is 200', function () { pm.response.to.have.status(200); });" ], "variables": [ { "name": "baseUrl", "example": "https://api.example.com", "desc": "域名" } ] }, "apifox": { "name": "订阅列表", "steps": [ "GET /open/v1/subscriptions", "断言 code=1000" ] } } }, { "id": "admin-entitlement-page", "name": "授权分页", "method": "POST", "path": "/admin/occapEntitlement/page", "status": "planned", "authRequired": true, "summary": "租户授权管理", "businessPoints": [ "Entitlement 与套餐联动" ], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "page", "type": "number", "required": true, "desc": "页码" }, { "name": "size", "type": "number", "required": true, "desc": "每页条数" }, { "name": "tenantId", "type": "number", "required": false, "desc": "筛选租户" } ] }, "requestExample": { "page": 1, "size": 20 }, "response": { "fields": [ { "name": "data.list", "type": "array", "required": true, "desc": "列表" } ] }, "errors": [ { "httpStatus": 400, "bizCode": 4000, "message": "参数错误", "desc": "traceId 见响应头 X-Trace-Id" }, { "httpStatus": 500, "bizCode": 5000, "message": "服务器错误", "desc": "traceId 见响应头 X-Trace-Id" } ], "testCases": { "postman": { "name": "授权分页", "preRequest": "pm.environment.set('baseUrl', 'https://api.example.com');", "tests": [ "pm.test('status is 200', function () { pm.response.to.have.status(200); });" ], "variables": [ { "name": "baseUrl", "example": "https://api.example.com", "desc": "域名" } ] }, "apifox": { "name": "授权分页", "steps": [ "POST /admin/occapEntitlement/page", "断言 code=1000" ] } } } ] }, { "id": "upload", "name": "上传", "interfaces": [ { "id": "open-upload-init", "name": "初始化直传", "method": "POST", "path": "/open/v1/upload/init", "status": "planned", "authRequired": true, "summary": "返回预签名 URL / uploadId", "businessPoints": [ "门户与 ISV 共用" ], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "filename", "type": "string", "required": true, "desc": "文件名" }, { "name": "contentType", "type": "string", "required": true, "desc": "MIME" }, { "name": "byteSize", "type": "number", "required": true, "desc": "大小" } ] }, "requestExample": { "filename": "skill.zip", "contentType": "application/zip", "byteSize": 1024 }, "response": { "fields": [ { "name": "data.uploadUrl", "type": "string", "required": true, "desc": "预签名 URL" } ] }, "errors": [ { "httpStatus": 400, "bizCode": 4000, "message": "参数错误", "desc": "traceId 见响应头 X-Trace-Id" }, { "httpStatus": 500, "bizCode": 5000, "message": "服务器错误", "desc": "traceId 见响应头 X-Trace-Id" } ], "testCases": { "postman": { "name": "上传初始化", "preRequest": "pm.environment.set('baseUrl', 'https://api.example.com');", "tests": [ "pm.test('status is 200', function () { pm.response.to.have.status(200); });" ], "variables": [ { "name": "baseUrl", "example": "https://api.example.com", "desc": "域名" } ] }, "apifox": { "name": "上传初始化", "steps": [ "POST /open/v1/upload/init", "断言 code=1000" ] } } } ] }, { "id": "delivery", "name": "交付与下载", "interfaces": [ { "id": "open-delivery-bundles-list", "name": "已授权交付包列表", "method": "GET", "path": "/open/v1/delivery/bundles", "status": "planned", "authRequired": true, "summary": "当前租户可下载的 DeliveryBundle 元数据（须 Entitlement 有效，不含直链）", "businessPoints": [ "门户下载中心数据源", "与 occap_delivery_bundle 对应" ], "request": { "headers": [], "pathParams": [], "query": [ { "name": "page", "type": "number", "required": false, "desc": "页码" } ], "body": [] }, "requestExample": {}, "response": { "fields": [ { "name": "data.list", "type": "array", "required": true, "desc": "bundleId、assetVersion、checksum、byteSize、signedAt" } ] }, "errors": [ { "httpStatus": 401, "bizCode": 4010, "message": "未授权", "desc": "traceId 见响应头 X-Trace-Id" }, { "httpStatus": 500, "bizCode": 5000, "message": "服务器错误", "desc": "traceId 见响应头 X-Trace-Id" } ], "testCases": { "postman": { "name": "交付包列表", "preRequest": "pm.environment.set('baseUrl', 'https://api.example.com');", "tests": [ "pm.test('status is 200', function () { pm.response.to.have.status(200); });" ], "variables": [ { "name": "baseUrl", "example": "https://api.example.com", "desc": "域名" } ] }, "apifox": { "name": "交付包列表", "steps": [ "GET /open/v1/delivery/bundles", "断言 code=1000" ] } } }, { "id": "open-delivery-sign", "name": "获取下载预签名 URL", "method": "POST", "path": "/open/v1/delivery/sign", "status": "planned", "authRequired": true, "summary": "校验 Entitlement 后返回短时有效的对象存储 GET URL，并写审计", "businessPoints": [ "短 TTL", "防直链盗刷" ], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "bundleId", "type": "string", "required": true, "desc": "交付包 ID" } ] }, "requestExample": { "bundleId": "bdl_xxx" }, "response": { "fields": [ { "name": "data.downloadUrl", "type": "string", "required": true, "desc": "预签名 GET" }, { "name": "data.expiresAt", "type": "string", "required": true, "desc": "ISO8601 过期时间" } ] }, "errors": [ { "httpStatus": 403, "bizCode": 4030, "message": "无下载权限", "desc": "bundle 与租户授权不匹配；traceId 见响应头 X-Trace-Id" }, { "httpStatus": 500, "bizCode": 5000, "message": "服务器错误", "desc": "traceId 见响应头 X-Trace-Id" } ], "testCases": { "postman": { "name": "下载预签名", "preRequest": "pm.environment.set('baseUrl', 'https://api.example.com');", "tests": [ "pm.test('status is 200', function () { pm.response.to.have.status(200); });" ], "variables": [ { "name": "baseUrl", "example": "https://api.example.com", "desc": "域名" } ] }, "apifox": { "name": "下载预签名", "steps": [ "POST /open/v1/delivery/sign", "断言 code=1000 且含 downloadUrl" ] } } } ] }, { "id": "isv", "name": "ISV", "interfaces": [ { "id": "isv-asset-submit", "name": "ISV 提交资产评审", "method": "POST", "path": "/admin/occapIsv/asset/submit", "status": "planned", "authRequired": true, "summary": "绑定 uploadId + manifest", "businessPoints": [ "进入 in_review" ], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "uploadId", "type": "string", "required": true, "desc": "上传会话" }, { "name": "manifestYaml", "type": "string", "required": true, "desc": "清单" } ] }, "requestExample": { "uploadId": "upl_1", "manifestYaml": "name: demo" }, "response": { "fields": [ { "name": "data.assetId", "type": "number", "required": true, "desc": "资产 ID" } ] }, "errors": [ { "httpStatus": 400, "bizCode": 4000, "message": "参数错误", "desc": "traceId 见响应头 X-Trace-Id" }, { "httpStatus": 500, "bizCode": 5000, "message": "服务器错误", "desc": "traceId 见响应头 X-Trace-Id" } ], "testCases": { "postman": { "name": "ISV 提交", "preRequest": "pm.environment.set('baseUrl', 'https://api.example.com');", "tests": [ "pm.test('status is 200', function () { pm.response.to.have.status(200); });" ], "variables": [ { "name": "baseUrl", "example": "https://api.example.com", "desc": "域名" } ] }, "apifox": { "name": "ISV 提交", "steps": [ "POST /admin/occapIsv/asset/submit", "断言 code=1000" ] } } } ] }, { "id": "platform_catalog", "name": "套餐与分发", "interfaces": [ { "id": "admin-plan-page", "name": "套餐分页", "method": "POST", "path": "/admin/occapPlan/page", "status": "planned", "authRequired": true, "summary": "套餐模板列表", "businessPoints": [], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "page", "type": "number", "required": true, "desc": "页码" }, { "name": "size", "type": "number", "required": true, "desc": "每页条数" } ] }, "requestExample": { "page": 1, "size": 20 }, "response": { "fields": [ { "name": "data.list", "type": "array", "required": true, "desc": "列表" } ] }, "errors": [ { "httpStatus": 500, "bizCode": 5000, "message": "服务器错误", "desc": "traceId 见响应头 X-Trace-Id" } ], "testCases": { "postman": { "name": "套餐分页", "preRequest": "pm.environment.set('baseUrl', 'https://api.example.com');", "tests": [ "pm.test('status is 200', function () { pm.response.to.have.status(200); });" ], "variables": [ { "name": "baseUrl", "example": "https://api.example.com", "desc": "域名" } ] }, "apifox": { "name": "套餐分页", "steps": [ "POST /admin/occapPlan/page", "断言 code=1000" ] } } }, { "id": "admin-distribution-get", "name": "分发配置", "method": "GET", "path": "/admin/occapDistribution/config", "status": "planned", "authRequired": true, "summary": "渠道、灰度策略 JSON", "businessPoints": [], "request": { "headers": [], "pathParams": [], "query": [], "body": [] }, "requestExample": {}, "response": { "fields": [ { "name": "data.config", "type": "object", "required": true, "desc": "配置" } ] }, "errors": [ { "httpStatus": 500, "bizCode": 5000, "message": "服务器错误", "desc": "traceId 见响应头 X-Trace-Id" } ], "testCases": { "postman": { "name": "分发配置", "preRequest": "pm.environment.set('baseUrl', 'https://api.example.com');", "tests": [ "pm.test('status is 200', function () { pm.response.to.have.status(200); });" ], "variables": [ { "name": "baseUrl", "example": "https://api.example.com", "desc": "域名" } ] }, "apifox": { "name": "分发配置", "steps": [ "GET /admin/occapDistribution/config", "断言 code=1000" ] } } } ] }, { "id": "workflow", "name": "定制与任务", "interfaces": [ { "id": "admin-custom-order-page", "name": "定制工单分页", "method": "POST", "path": "/admin/occapCustomOrder/page", "status": "planned", "authRequired": true, "summary": "定制需求列表", "businessPoints": [], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "page", "type": "number", "required": true, "desc": "页码" }, { "name": "size", "type": "number", "required": true, "desc": "每页条数" } ] }, "requestExample": { "page": 1, "size": 20 }, "response": { "fields": [ { "name": "data.list", "type": "array", "required": true, "desc": "列表" } ] }, "errors": [ { "httpStatus": 500, "bizCode": 5000, "message": "服务器错误", "desc": "traceId 见响应头 X-Trace-Id" } ], "testCases": { "postman": { "name": "定制工单", "preRequest": "pm.environment.set('baseUrl', 'https://api.example.com');", "tests": [ "pm.test('status is 200', function () { pm.response.to.have.status(200); });" ], "variables": [ { "name": "baseUrl", "example": "https://api.example.com", "desc": "域名" } ] }, "apifox": { "name": "定制工单", "steps": [ "POST /admin/occapCustomOrder/page", "断言 code=1000" ] } } }, { "id": "admin-task-page", "name": "任务分页", "method": "POST", "path": "/admin/occapTask/page", "status": "planned", "authRequired": true, "summary": "任务 inbox", "businessPoints": [], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "page", "type": "number", "required": true, "desc": "页码" }, { "name": "size", "type": "number", "required": true, "desc": "每页条数" }, { "name": "status", "type": "string", "required": false, "desc": "open|done" } ] }, "requestExample": { "page": 1, "size": 20 }, "response": { "fields": [ { "name": "data.list", "type": "array", "required": true, "desc": "列表" } ] }, "errors": [ { "httpStatus": 500, "bizCode": 5000, "message": "服务器错误", "desc": "traceId 见响应头 X-Trace-Id" } ], "testCases": { "postman": { "name": "任务分页", "preRequest": "pm.environment.set('baseUrl', 'https://api.example.com');", "tests": [ "pm.test('status is 200', function () { pm.response.to.have.status(200); });" ], "variables": [ { "name": "baseUrl", "example": "https://api.example.com", "desc": "域名" } ] }, "apifox": { "name": "任务分页", "steps": [ "POST /admin/occapTask/page", "断言 code=1000" ] } } }, { "id": "admin-custom-order-create", "name": "创建工单", "method": "POST", "path": "/admin/occapCustomOrder", "status": "planned", "authRequired": true, "summary": "创建定制工单草稿", "businessPoints": [], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "tenant_id", "type": "number", "required": true, "desc": "租户ID" }, { "name": "title", "type": "string", "required": true, "desc": "工单标题" }, { "name": "type", "type": "string", "required": true, "desc": "skill定制|mcp定制|记忆策略|组合包|咨询" }, { "name": "priority", "type": "string", "required": false, "desc": "low|normal|high|urgent，默认 normal" }, { "name": "openclaw_version_range", "type": "string", "required": false, "desc": "目标 OpenClaw 版本，如 >=1.5.0" }, { "name": "compliance_requirements", "type": "string", "required": false, "desc": "JSON 数组，合规约束" }, { "name": "initial_requirement", "type": "string", "required": true, "desc": "原始需求描述" } ] }, "requestExample": { "title": "定制一个风控 SKILL", "type": "skill定制", "priority": "normal", "initial_requirement": "需求：..." }, "response": { "fields": [ { "name": "data.id", "type": "number", "required": true, "desc": "工单ID" }, { "name": "data.order_no", "type": "string", "required": true, "desc": "工单编号" } ] }, "errors": [ { "httpStatus": 400, "bizCode": 4001, "message": "参数校验失败", "desc": "" }, { "httpStatus": 500, "bizCode": 5000, "message": "服务器错误", "desc": "" } ] }, { "id": "admin-custom-order-detail", "name": "工单详情", "method": "GET", "path": "/admin/occapCustomOrder/{id}", "status": "planned", "authRequired": true, "summary": "工单详情（含里程碑、沟通记录）", "businessPoints": [], "request": { "headers": [], "pathParams": [ { "name": "id", "type": "number", "required": true, "desc": "工单ID" } ], "query": [], "body": [] }, "requestExample": {}, "response": { "fields": [ { "name": "data.id", "type": "number", "required": true, "desc": "" }, { "name": "data.order_no", "type": "string", "required": true, "desc": "" }, { "name": "data.status", "type": "string", "required": true, "desc": "" }, { "name": "data.milestones", "type": "array", "required": true, "desc": "里程碑列表" }, { "name": "data.messages", "type": "array", "required": true, "desc": "沟通记录" } ] }, "errors": [ { "httpStatus": 404, "bizCode": 4041, "message": "工单不存在", "desc": "" } ] }, { "id": "admin-custom-order-submit", "name": "提交工单", "method": "POST", "path": "/admin/occapCustomOrder/{id}/submit", "status": "planned", "authRequired": true, "summary": "提交工单进入运营评审队列", "businessPoints": [], "request": { "headers": [], "pathParams": [ { "name": "id", "type": "number", "required": true, "desc": "工单ID" } ], "query": [], "body": [] }, "requestExample": {}, "response": { "fields": [ { "name": "data.status", "type": "string", "required": true, "desc": "新状态 pending_review" } ] }, "errors": [ { "httpStatus": 400, "bizCode": 4002, "message": "状态不允许提交", "desc": "只有 draft 可提交" } ] }, { "id": "admin-custom-order-quote", "name": "填写报价", "method": "POST", "path": "/admin/occapCustomOrder/{id}/quote", "status": "planned", "authRequired": true, "summary": "运营填写报价工时与金额", "businessPoints": [], "request": { "headers": [], "pathParams": [ { "name": "id", "type": "number", "required": true, "desc": "工单ID" } ], "query": [], "body": [ { "name": "quoted_workdays", "type": "number", "required": true, "desc": "报价工时（人天）" }, { "name": "quoted_price", "type": "number", "required": true, "desc": "报价金额（元）" }, { "name": "currency", "type": "string", "required": false, "desc": "币种，默认 CNY" }, { "name": "expire_at", "type": "string", "required": false, "desc": "报价过期时间，ISO 格式，默认 7 天后" } ] }, "requestExample": { "quoted_workdays": 5, "quoted_price": 25000 }, "response": { "fields": [ { "name": "data.status", "type": "string", "required": true, "desc": "新状态 quoted" } ] }, "errors": [ { "httpStatus": 400, "bizCode": 4003, "message": "状态不允许报价", "desc": "只有 pending_review 可报价" } ] }, { "id": "admin-custom-order-confirm", "name": "确认工单", "method": "POST", "path": "/admin/occapCustomOrder/{id}/confirm", "status": "planned", "authRequired": true, "summary": "租户确认报价（Portal 侧调用）", "businessPoints": [], "request": { "headers": [], "pathParams": [ { "name": "id", "type": "number", "required": true, "desc": "工单ID" } ], "query": [], "body": [ { "name": "isv_id", "type": "number", "required": false, "desc": "接单 ISV 的 user_id，可在此指定或由运营指派" } ] }, "requestExample": { "isv_id": 102 }, "response": { "fields": [ { "name": "data.status", "type": "string", "required": true, "desc": "新状态 confirmed" } ] }, "errors": [ { "httpStatus": 400, "bizCode": 4004, "message": "状态不允许确认", "desc": "只有 quoted 可确认" } ] }, { "id": "admin-custom-order-cancel", "name": "取消工单", "method": "POST", "path": "/admin/occapCustomOrder/{id}/cancel", "status": "planned", "authRequired": true, "summary": "取消工单", "businessPoints": [], "request": { "headers": [], "pathParams": [ { "name": "id", "type": "number", "required": true, "desc": "工单ID" } ], "query": [], "body": [ { "name": "reason", "type": "string", "required": true, "desc": "取消原因" } ] }, "requestExample": { "reason": "需求变更" }, "response": { "fields": [ { "name": "data.status", "type": "string", "required": true, "desc": "新状态 cancelled" } ] } }, { "id": "admin-custom-order-assign-isv", "name": "指派 ISV", "method": "POST", "path": "/admin/occapCustomOrder/{id}/assign-isv", "status": "planned", "authRequired": true, "summary": "运营指派 ISV 接单", "businessPoints": [], "request": { "headers": [], "pathParams": [ { "name": "id", "type": "number", "required": true, "desc": "工单ID" } ], "query": [], "body": [ { "name": "isv_id", "type": "number", "required": true, "desc": "ISV user_id" } ] }, "requestExample": { "isv_id": 102 }, "response": { "fields": [] }, "errors": [ { "httpStatus": 400, "bizCode": 4005, "message": "ISV 不存在或非 ISV 角色", "desc": "" } ] }, { "id": "admin-milestone-list", "name": "里程碑列表", "method": "GET", "path": "/admin/occapCustomOrder/{orderId}/milestones", "status": "planned", "authRequired": true, "summary": "查询工单下所有里程碑", "businessPoints": [], "request": { "headers": [], "pathParams": [ { "name": "orderId", "type": "number", "required": true, "desc": "工单ID" } ], "query": [], "body": [] }, "requestExample": {}, "response": { "fields": [ { "name": "data[]", "type": "array", "required": true, "desc": "里程碑列表，按 sequence 排序" } ] }, "errors": [] }, { "id": "admin-milestone-create", "name": "创建里程碑", "method": "POST", "path": "/admin/occapCustomOrder/{orderId}/milestones", "status": "planned", "authRequired": true, "summary": "在工单下创建里程碑", "businessPoints": [], "request": { "headers": [], "pathParams": [ { "name": "orderId", "type": "number", "required": true, "desc": "工单ID" } ], "query": [], "body": [ { "name": "title", "type": "string", "required": true, "desc": "里程碑标题" }, { "name": "description", "type": "string", "required": false, "desc": "交付标准" }, { "name": "workdays", "type": "number", "required": true, "desc": "工时（人天）" }, { "name": "due_date", "type": "string", "required": true, "desc": "截止日期 YYYY-MM-DD" } ] }, "requestExample": { "title": "需求分析交付", "description": "输出需求文档v1", "workdays": 2, "due_date": "2026-05-01" }, "response": { "fields": [ { "name": "data.id", "type": "number", "required": true, "desc": "里程碑ID" } ] }, "errors": [ { "httpStatus": 400, "bizCode": 4006, "message": "状态不允许创建里程碑", "desc": "confirmed/in_progress 才能创建" } ] }, { "id": "admin-milestone-review", "name": "里程碑验收", "method": "POST", "path": "/admin/occapCustomOrder/{orderId}/milestones/{id}/review", "status": "planned", "authRequired": true, "summary": "运营或租户验收里程碑，ISV 提交交付物", "businessPoints": [], "request": { "headers": [], "pathParams": [ { "name": "orderId", "type": "number", "required": true, "desc": "工单ID" }, { "name": "id", "type": "number", "required": true, "desc": "里程碑ID" } ], "query": [], "body": [ { "name": "action", "type": "string", "required": true, "desc": "pass | reject" }, { "name": "reject_reason", "type": "string", "required": false, "desc": "驳回原因（action=reject 时必填）" }, { "name": "delivery_attachment_ids", "type": "string", "required": false, "desc": "JSON 数组，交付物附件ID列表（action=pass 时填写）" } ] }, "requestExample": { "action": "pass", "delivery_attachment_ids": "[10, 11]" }, "response": { "fields": [ { "name": "data.status", "type": "string", "required": true, "desc": "新状态 passed/rejected" } ] }, "errors": [ { "httpStatus": 400, "bizCode": 4007, "message": "状态不允许验收", "desc": "只有 review 状态可验收" } ] }, { "id": "admin-order-message-list", "name": "沟通记录列表", "method": "GET", "path": "/admin/occapCustomOrder/{orderId}/messages", "status": "planned", "authRequired": true, "summary": "工单沟通记录（不含 is_internal=true 的运营内部消息）", "businessPoints": [], "request": { "headers": [], "pathParams": [ { "name": "orderId", "type": "number", "required": true, "desc": "工单ID" } ], "query": [ { "name": "include_internal", "type": "boolean", "required": false, "desc": "运营角色可设为 true 查看内部消息" } ], "body": [] }, "requestExample": {}, "response": { "fields": [ { "name": "data[]", "type": "array", "required": true, "desc": "消息列表" } ] }, "errors": [] }, { "id": "admin-order-message-send", "name": "发送消息", "method": "POST", "path": "/admin/occapCustomOrder/{orderId}/messages", "status": "planned", "authRequired": true, "summary": "工单内发送沟通消息", "businessPoints": [], "request": { "headers": [], "pathParams": [ { "name": "orderId", "type": "number", "required": true, "desc": "工单ID" } ], "query": [], "body": [ { "name": "content", "type": "string", "required": true, "desc": "消息内容（Markdown）" }, { "name": "attachment_ids", "type": "string", "required": false, "desc": "JSON 数组，附件ID" }, { "name": "is_internal", "type": "boolean", "required": false, "desc": "是否运营内部消息，默认 false" } ] }, "requestExample": { "content": "请补充风控规则说明", "is_internal": false }, "response": { "fields": [ { "name": "data.id", "type": "number", "required": true, "desc": "消息ID" } ] }, "errors": [] }, { "id": "admin-order-attachment-upload", "name": "上传附件", "method": "POST", "path": "/admin/occapCustomOrder/attachment", "status": "planned", "authRequired": true, "summary": "工单附件上传（直传对象存储）", "businessPoints": [], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "order_id", "type": "number", "required": false, "desc": "关联工单ID" }, { "name": "milestone_id", "type": "number", "required": false, "desc": "关联里程碑ID" }, { "name": "category", "type": "string", "required": true, "desc": "requirement|draft|delivery|approval_doc|other" } ] }, "requestExample": { "order_id": 1, "category": "requirement" }, "response": { "fields": [ { "name": "data.attachment_id", "type": "number", "required": true, "desc": "附件ID" }, { "name": "data.upload_url", "type": "string", "required": true, "desc": "预签名上传 URL" } ] }, "errors": [] }, { "id": "isv-order-page", "name": "ISV 工单列表", "method": "POST", "path": "/isv/occapCustomOrder/page", "status": "planned", "authRequired": true, "summary": "ISV 查看已指派给自己的工单", "businessPoints": [], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "page", "type": "number", "required": true, "desc": "" }, { "name": "size", "type": "number", "required": true, "desc": "" }, { "name": "status", "type": "string", "required": false, "desc": "筛选状态" } ] }, "requestExample": { "page": 1, "size": 20 }, "response": { "fields": [ { "name": "data.list", "type": "array", "required": true, "desc": "" } ] }, "errors": [] }, { "id": "isv-milestone-submit", "name": "ISV 提交交付物", "method": "POST", "path": "/isv/occapCustomOrder/{orderId}/milestones/{id}/submit", "status": "planned", "authRequired": true, "summary": "ISV 提交里程碑交付物，进入 review 状态", "businessPoints": [], "request": { "headers": [], "pathParams": [ { "name": "orderId", "type": "number", "required": true, "desc": "" }, { "name": "id", "type": "number", "required": true, "desc": "里程碑ID" } ], "query": [], "body": [ { "name": "delivery_attachment_ids", "type": "string", "required": true, "desc": "JSON 数组，交付物附件ID" }, { "name": "notes", "type": "string", "required": false, "desc": "提交备注" } ] }, "requestExample": { "delivery_attachment_ids": "[10, 11]", "notes": "V1 版本已完成" }, "response": { "fields": [ { "name": "data.status", "type": "string", "required": true, "desc": "review" } ] }, "errors": [ { "httpStatus": 400, "bizCode": 4008, "message": "状态不允许提交", "desc": "只有 in_progress 可提交" } ] }, { "id": "portal-custom-order-page", "name": "租户工单列表", "method": "POST", "path": "/portal/occapCustomOrder/page", "status": "planned", "authRequired": true, "summary": "租户视角工单列表", "businessPoints": [], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "page", "type": "number", "required": true, "desc": "" }, { "name": "size", "type": "number", "required": true, "desc": "" }, { "name": "status", "type": "string", "required": false, "desc": "" } ] }, "requestExample": { "page": 1, "size": 20 }, "response": { "fields": [ { "name": "data.list", "type": "array", "required": true, "desc": "" } ] }, "errors": [] }, { "id": "portal-custom-order-confirm", "name": "租户确认报价", "method": "POST", "path": "/portal/occapCustomOrder/{id}/confirm", "status": "planned", "authRequired": true, "summary": "租户管理员确认报价并签约", "businessPoints": [], "request": { "headers": [], "pathParams": [ { "name": "id", "type": "number", "required": true, "desc": "工单ID" } ], "query": [], "body": [] }, "requestExample": {}, "response": { "fields": [ { "name": "data.status", "type": "string", "required": true, "desc": "confirmed" } ] }, "errors": [ { "httpStatus": 400, "bizCode": 4004, "message": "状态不允许确认", "desc": "" } ] }, { "id": "portal-custom-order-rate", "name": "客户评分", "method": "POST", "path": "/portal/occapCustomOrder/{id}/rate", "status": "planned", "authRequired": true, "summary": "工单完成后客户评分与反馈", "businessPoints": [], "request": { "headers": [], "pathParams": [ { "name": "id", "type": "number", "required": true, "desc": "工单ID" } ], "query": [], "body": [ { "name": "rating", "type": "number", "required": true, "desc": "评分 1-5" }, { "name": "feedback", "type": "string", "required": false, "desc": "反馈文字" } ] }, "requestExample": { "rating": 5, "feedback": "交付及时，质量满意" }, "response": { "fields": [] }, "errors": [ { "httpStatus": 400, "bizCode": 4009, "message": "状态不允许评分", "desc": "只有 delivered/completed 可评分" } ] } ] }, { "id": "agent_exchange", "name": "Agent 交换", "interfaces": [ { "id": "agent-skill-publish", "name": "Agent 发布 Skill", "method": "POST", "path": "/open/v1/agent/skill/publish", "status": "planned", "authRequired": true, "summary": "机器身份发布草稿/待审", "businessPoints": [ "Agent API Key" ], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "uploadId", "type": "string", "required": true, "desc": "上传" }, { "name": "manifestJson", "type": "string", "required": true, "desc": "清单" }, { "name": "workspaceFingerprint", "type": "string", "required": false, "desc": "工作区指纹" } ] }, "requestExample": { "uploadId": "upl_a", "manifestJson": "{}" }, "response": { "fields": [ { "name": "data.assetId", "type": "number", "required": true, "desc": "资产 ID" } ] }, "errors": [ { "httpStatus": 401, "bizCode": 4010, "message": "未授权", "desc": "traceId 见响应头 X-Trace-Id" }, { "httpStatus": 500, "bizCode": 5000, "message": "服务器错误", "desc": "traceId 见响应头 X-Trace-Id" } ], "testCases": { "postman": { "name": "Agent 发布", "preRequest": "pm.environment.set('baseUrl', 'https://api.example.com');", "tests": [ "pm.test('status is 200', function () { pm.response.to.have.status(200); });" ], "variables": [ { "name": "baseUrl", "example": "https://api.example.com", "desc": "域名" } ] }, "apifox": { "name": "Agent 发布", "steps": [ "POST /open/v1/agent/skill/publish", "断言 code=1000" ] } } }, { "id": "agent-skill-subscribe", "name": "Agent 订阅能力槽", "method": "POST", "path": "/open/v1/agent/skill/subscribe", "status": "planned", "authRequired": true, "summary": "绑定 slot + assetVersion", "businessPoints": [], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "slotId", "type": "string", "required": true, "desc": "槽位" }, { "name": "assetVersionId", "type": "number", "required": true, "desc": "版本" } ] }, "requestExample": { "slotId": "slot_1", "assetVersionId": 9 }, "response": { "fields": [ { "name": "data.ok", "type": "boolean", "required": true, "desc": "成功" } ] }, "errors": [ { "httpStatus": 400, "bizCode": 4000, "message": "参数错误", "desc": "traceId 见响应头 X-Trace-Id" }, { "httpStatus": 500, "bizCode": 5000, "message": "服务器错误", "desc": "traceId 见响应头 X-Trace-Id" } ], "testCases": { "postman": { "name": "Agent 订阅", "preRequest": "pm.environment.set('baseUrl', 'https://api.example.com');", "tests": [ "pm.test('status is 200', function () { pm.response.to.have.status(200); });" ], "variables": [ { "name": "baseUrl", "example": "https://api.example.com", "desc": "域名" } ] }, "apifox": { "name": "Agent 订阅", "steps": [ "POST /open/v1/agent/skill/subscribe", "断言 code=1000" ] } } } ] }, { "id": "settlement", "name": "贡献结算", "interfaces": [ { "id": "admin-settlement-ledger", "name": "贡献账本分页", "method": "POST", "path": "/admin/occapSettlement/ledger/page", "status": "planned", "authRequired": true, "summary": "CP 流水", "businessPoints": [ "Merkle 批次关联" ], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "page", "type": "number", "required": true, "desc": "页码" }, { "name": "size", "type": "number", "required": true, "desc": "每页条数" } ] }, "requestExample": { "page": 1, "size": 20 }, "response": { "fields": [ { "name": "data.list", "type": "array", "required": true, "desc": "流水" } ] }, "errors": [ { "httpStatus": 500, "bizCode": 5000, "message": "服务器错误", "desc": "traceId 见响应头 X-Trace-Id" } ], "testCases": { "postman": { "name": "账本分页", "preRequest": "pm.environment.set('baseUrl', 'https://api.example.com');", "tests": [ "pm.test('status is 200', function () { pm.response.to.have.status(200); });" ], "variables": [ { "name": "baseUrl", "example": "https://api.example.com", "desc": "域名" } ] }, "apifox": { "name": "账本分页", "steps": [ "POST /admin/occapSettlement/ledger/page", "断言 code=1000" ] } } }, { "id": "admin-settlement-close", "name": "关闭结算批次", "method": "POST", "path": "/admin/occapSettlement/batchClose", "status": "planned", "authRequired": true, "summary": "生成 MerkleRoot、冻结批次", "businessPoints": [], "request": { "headers": [], "pathParams": [], "query": [], "body": [ { "name": "batchId", "type": "string", "required": true, "desc": "批次" } ] }, "requestExample": { "batchId": "b_202604201200" }, "response": { "fields": [ { "name": "data.merkleRoot", "type": "string", "required": true, "desc": "根" } ] }, "errors": [ { "httpStatus": 400, "bizCode": 4000, "message": "参数错误", "desc": "traceId 见响应头 X-Trace-Id" }, { "httpStatus": 500, "bizCode": 5000, "message": "服务器错误", "desc": "traceId 见响应头 X-Trace-Id" } ], "testCases": { "postman": { "name": "批次关闭", "preRequest": "pm.environment.set('baseUrl', 'https://api.example.com');", "tests": [ "pm.test('status is 200', function () { pm.response.to.have.status(200); });" ], "variables": [ { "name": "baseUrl", "example": "https://api.example.com", "desc": "域名" } ] }, "apifox": { "name": "批次关闭", "steps": [ "POST /admin/occapSettlement/batchClose", "断言 code=1000" ] } } } ] } ] }