mjava-ai/openspec/changes/add-mjava-com/spec.md

baas-gateway

REQ-GW-001 统一入口

• 路由规则：POST /api/com/{vendor}/{action}
• vendor ∈ {dingtalk, aliwork, beisen, teambition, feishu, fxiaoke, h3yun, ...}（以 mjava/service/ 下 vendor 包实际存在为准）
• action 为显式注册的 key，形如 user.get / form.save / attendance.listRecord（命名对应官方 API 文档语义）
• 请求体 JSON；字段名必须与基座 Client 对应方法参数一致

REQ-GW-002 签名校验

• Header 必含 X-Caller-Id X-Signature X-Timestamp
• 校验顺序：timestamp 窗口 5 分钟 → callerId 查注册表 → HMAC-SHA256 比对 → 调用方启用状态
• 任一失败：401 { code: "AUTH_FAILED", reason: "..." }（reason 不暴露具体环节，避免用户猜测）

REQ-GW-003 动作白名单

• action 必须先在 ActionRegistry 代码显式注册（反射调基座 Client 方法）
• 同时必须在 application.yml 的 com.actions.enabled 列表启用
• 调用方在宜搭权限表单的 allowedActions 包含该 action 才允许访问
• 三层校验任一不过：403 { code: "ACTION_FORBIDDEN" }

REQ-GW-004 响应格式

• 返回 McR<T>（基座已有）：{ success, code, message, data }
• 第三方原始响应放在 data 字段，保留全部原始结构（不做字段转义）
• 第三方错误统一映射为 McR.fail()，data 含 vendor 原始错误码

REQ-GW-005 限流

• 按 callerId 本地 RateLimiter，阈值取宜搭权限表单 rateLimit 字段
• 超限返回 429 { code: "RATE_LIMITED", retryAfter: 1 }

REQ-GW-006 审计扩展

• 日志字段在 mjava-baseline §3.5 基础上追加 callerId / vendorAction / signatureValid
• 日志文件按 callerId 分片

caller-registry

REQ-CR-001 注册源

• 调用方白名单维护于宜搭"权限表单"（formUuid 配置在 com.caller.registry.formUuid）
• 字段约定见 design.md

REQ-CR-002 加载与刷新

• 启动时全量拉取 enabled=on 的调用方到内存 Map<callerId, CallerProfile>
• 默认 TTL 300 秒，可配 com.caller.registry.ttlSeconds
• 失效后 stale-while-revalidate

REQ-CR-003 密钥轮换

• 调用方申请新密钥 → 运营在宜搭表单更新 callerSecret → 下次拉取后生效
• 宜搭表单不保留历史版本（如需双密钥轮换，未来提案支持）

REQ-CR-004 调用方停用

• enabled=off 后，注册表下次刷新移除
• 停用期间返回 401 CALLER_DISABLED

非目标明示

• 不做签名算法可插拔（固定 HMAC-SHA256；将来如需支持国密再提案）
• 不做 mTLS / API Gateway 前置
• 不做请求体加密（HTTPS + HMAC 完整性足够）
• 不做响应缓存（每次都直调基座 Client；幂等缓存由调用方自行做）