核心用法
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` |
认证与连接管理
采用双层认证架构：
1. Maton API Key: 所有请求需携带 Authorization: Bearer $MATON_API_KEY
2. CompanyCam OAuth: 通过 Maton 托管的连接服务完成授权，支持多账户场景下通过 Maton-Connection 头部指定连接
连接管理流程：创建连接 → 浏览器完成 OAuth → 获取 connection_id → 常规 API 调用（多账户场景需指定头部）
关键限制
- 读请求限流：240/分钟
- 写请求限流：100/分钟
- 超限时返回 429，需实现指数退避重试
显著优点
1. 托管式 OAuth 简化集成：开发者无需处理 CompanyCam 原生的 OAuth 流程，Maton 自动管理令牌生命周期
2. 统一的代理层：所有请求通过 api.maton.ai/companycam/v2 路由，自动注入有效令牌，降低接入门槛
3. 完整业务覆盖：涵盖从项目创建、照片上传到团队协作、文档管理的端到端工作流
4. 多账户支持：通过 Maton-Connection 头部可在单一 API Key 下管理多个 CompanyCam 账户
5. 事件驱动架构：Webhook 支持 9 种事件类型(project/photo/document/label 等)，便于构建实时同步场景
潜在缺点与局限性
1. 强制的用户确认机制：所有写入操作(create/update/delete/webhook 创建)必须显式获得用户批准，自动化脚本场景下交互成本较高
2. Webhook 安全风险：文档明确警告"创建 webhook 会导致项目/照片事件数据被发送到指定 URL"，需严格确认目标地址，存在数据泄露风险
3. 功能代理限制：作为代理层，受限于 CompanyCam API 本身的能力边界，不支持平台原生未开放的功能
4. 环境变量依赖：强制要求 MATON_API_KEY 环境变量，容器化部署需额外配置管理
5. 地理定位数据：照片坐标上传需自行处理格式转换，无内置地址解析
适合人群
- 中小型承包商：需要快速搭建项目照片管理系统，无专职开发团队
- 现有 CompanyCam 用户：希望将数据同步到内部系统或 BI 平台的 IT 管理员
- 集成开发者：为建筑、装修、保险定损等行业构建解决方案的 SaaS 开发商
- 多租户场景：需要统一管理多个 CompanyCam 账户的物业管理或连锁企业
常规风险
| 风险类别 | 具体描述 | 缓解建议 |
|---------|---------|---------|
| **数据泄露** | Webhook 配置错误导致敏感项目/照片数据发送至未授权端点 | 创建前严格审核 URL，使用 HTTPS 验证端点所有权 |
| **误操作** | 用户管理、项目删除等操作影响团队协作 | 利用强制确认机制，实施操作前二次校验 |
| **令牌泄露** | MATON_API_KEY 泄露导致账户完全失控 | 密钥轮转策略、最小权限原则、日志审计 |
| **速率限制** | 批量操作触发 429 导致业务中断 | 实现指数退避、请求队列、监控告警 |
| **供应商锁定** | 深度依赖 Maton 代理层，迁移成本高 | 抽象 API 调用层，保留直接集成 CompanyCam 的能力 |