（4464期）CompanyCam – 承包商照片文档一站式管理中枢

承包商照片文档一站式管理中枢 专为承包商设计的照片文档管理接口，支持项目、照片、用户等全生命周期管理，写入操作需用户显式授权 使用说明 核心用法 CompanyCam Skill 是 Maton 平台提供的托管式 OAuth 集成方案，让用户能够通过统一接口访问 CompanyCam API，实现承包商照片文档管理的核心业务场景。 主要功能模块 | 资源类型 | 支持操作 | 关键端点示例 ||---------|---------|------------|| Projects | CRUD、归档/恢复 | GET/POST /projects, PATCH /projects/{id}/archive || Photos | 查询、更新、删除、添加标签/评论 | GET /photos, POST /projects/{id}/photos || Users | CRUD、角色管理(admin/standard/limited) | GET /users, POST /users || Groups | 团队分组管理 | GET/POST /groups || Tags & Labels | 照片/项目分类标记 | GET /tags, POST /projects/{id}/labels || Documents | 合同文档上传管理 | GET/POST /projects/{id}/documents || Checklists | 基于模板创建检查清单 | GET/POST /checklists || Webhooks | 事件订阅(project/photo created等) | GET/POST /webhooks | 认证与连接管理 采用双层认证架构： Maton API Key: 所有请求需携带 Authorization: Bearer $MATONAPIKEY CompanyCam OAuth: 通过 Maton 托管的连接服务完成授权，支持多账户场景下通过 Maton-Connection 头部指定连接 连接管理流程：创建连接 → 浏览器完成 OAuth → 获取 connection_id → 常规 API 调用（多账户场景需指定头部） 关键限制 读请求限流：240/分钟 写请求限流：100/分钟 超限时返回 429，需实现指数退避重试 显著优点 托管式 OAuth 简化集成：开发者无需处理 CompanyCam 原生的 OAuth 流程，Maton 自动管理令牌生命周期 统一的代理层：所有请求通过 api.maton.ai/companycam/v2 路由，自动注入有效令牌，降低接入门槛 完整业务覆盖：涵盖从项目创建、照片上传到团队协作、文档管理的端到端工作流 多账户支持：通过 Maton-Connection 头部可在单一 API Key 下管理多个 CompanyCam 账户 事件驱动架构：Webhook 支持 9 种事件类型(project/photo/document/label 等)，便于构建实时同步场景 潜在缺点与局限性 强制的用户确认机制：所有写入操作(create/update/delete/webhook 创建)必须显式获得用户批准，自动化脚本场景下交互成本较高 Webhook 安全风险：文档明确警告"创建 webhook 会导致项目/照片事件数据被发送到指定 URL"，需严格确认目标地址，存在数据泄露风险 功能代理限制：作为代理层，受限于 CompanyCam API 本身的能力边界，不支持平台原生未开放的功能 环境变量依赖：强制要求 MATONAPIKEY 环境变量，容器化部署需额外配置管理 地理定位数据：照片坐标上传需自行处理格式转换，无内置地址解析 适合人群 中小型承包商：需要快速搭建项目照片管理系统，无专职开发团队 现有 CompanyCam 用户：希望将数据同步到内部系统或 BI 平台的 IT 管理员 集成开发者：为建筑、装修、保险定损等行业构建解决方案的 SaaS 开发商 多租户场景：需要统一管理多个 CompanyCam 账户的物业管理或连锁企业 常规风险 | 风险类别 | 具体描述 | 缓解建议 ||---------|---------|---------|| 数据泄露 | Webhook 配置错误导致敏感项目/照片数据发送至未授权端点 | 创建前严格审核 URL，使用 HTTPS 验证端点所有权 || 误操作 | 用户管理、项目删除等操作影响团队协作 | 利用强制确认机制，实施操作前二次校验 || 令牌泄露 | MATONAPIKEY 泄露导致账户完全失控 | 密钥轮转策略、最小权限原则、日志审计 || 速率限制 | 批量操作触发 429 导致业务中断 | 实现指数退避、请求队列、监控告警 || 供应商锁定 | 深度依赖 Maton 代理层，迁移成本高 | 抽象 API 调用层，保留直接集成 CompanyCam 的能力 | 原始说明 CompanyCam API integration with managed OAuth. Manage projects, photos, users, tags, groups, documents, checklists, labels, collaborators, webhooks, and comp...