> 状态（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
<!-- 基座 Client 层保持不变，com 作为 facade 层向外暴露 -->

## 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 等）
- ❌ 不做请求录制回放（可测性工作，独立专项）