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

状态（2026-04-18 立项）：提案阶段，未实施 优先级：高。与 add-mjava-pro 并行。

Why

mjava 基座沉淀了大量通用能力：HTTP 请求封装（UtilHttp）、Token 缓存（UtilToken）、JPA + QueryDSL、统一响应体 McR、多数据源、TraceId 链路 等。目前这些能力只能被"引入 mjava 依赖"的 Java 子项目（mcli/shunfeng/guangming）使用。

但实际业务中常遇到：

• 非 Java 系统（Node.js / Python / PHP 宜搭连接器 / 低代码平台）需要调用钉钉/宜搭 API，每个系统重复实现鉴权 + HTTP + token 缓存，浪费且容易出错
• 前端侧业务（宜搭自定义页面 JSX）也希望复用后端对接能力，不想在前端暴露 appSecret
• 实习/新人项目没必要为了调用一次钉钉 API 就起一个完整的 mjava 子项目

需要把 mjava 基座能力"服务化"——通过 mjava-com 子模块对外开放 REST API，外部系统只要通过鉴权就能直接调用钉钉/宜搭/飞书等底层接口，无需引入 mjava 代码。

What Changes

新增子模块 mjava-com/，具备：

• 统一入口 API：/api/com/{vendor}/{action}（如 POST /api/com/dingtalk/user.get）转发到基座 Client 方法
• 调用方鉴权：从宜搭"权限表单"（formUuid 配置在 application.yml）查询被授权的调用方白名单，按 apiKey + signature 验签
• 审计日志：每次调用打完整审计（调用方 ID + vendor + action + latency + success）
• 限流/熔断：按调用方维度做基础限流（避免某个外部系统打爆第三方配额）；Phase 1 用本地 RateLimiter，不引入 Sentinel/Resilience4j
• Vendor 暴露白名单：不是所有 Client 方法都自动开放，需要在 application.yml 显式声明哪些 {vendor}.{action} 可被 com 调用

Capabilities

New Capabilities

• baas-gateway：BaaS 风格的后端即服务网关，把 mjava Client 能力以 REST 开放
• caller-registry：外部调用方注册中心（宜搭权限表单）

Modified Capabilities

Impact

• 新增模块：mjava-com/（独立 jar，默认端口 9020，context-path /api/com）
• 新增代码（预计）：
  • CallerAuthInterceptor.java（apiKey + signature 验签）
  • CallerRegistryService.java（查宜搭权限表单）
  • GatewayController.java（路由 /{vendor}/{action} 到基座 Client）
  • ActionWhitelistConfig.java（vendor.action 白名单）
  • 简单本地限流 CallerRateLimiter.java
• 基座影响：零（com 作为 facade 调基座现有 Client）
• 外部调用方：简化 — 只需 apiKey + signature + JSON body 发 POST 即可

Non-Goals

• ❌ 不做 OpenAPI / Swagger 规范（第一阶段人工维护接口文档；若需要再单独提案）
• ❌ 不做计费 / 配额套餐（Phase 1 固定限流即可）
• ❌ 不做 OAuth2 授权（apiKey + HMAC 签名足够内部场景；跨组织再评估）
• ❌ 不引入 API Gateway 中间件（Kong / APISIX / Spring Cloud Gateway 等）
• ❌ 不做请求录制回放（可测性工作，独立专项）