# mjava-ai

> Java 后端基座 + 多客户子项目聚合仓库
> 技术栈：Spring Boot 2.2.13 + MySQL + JPA + QueryDSL + Hutool

## 定位

**mjava** 是一套可复用的 Java 后端基座，封装企业办公常见第三方平台（钉钉 / 宜搭 / 飞书 / 北森 等）的统一调用、鉴权、审计、持久化能力。每个客户需求作为独立子项目接入，引用基座 jar，只关注业务逻辑。

**第一阶段约束**：仅 Spring Boot + MySQL，不引入 Redis / Docker / K8s / 消息队列。

## 仓库结构

```
mjava-ai/
├── mjava/                基座 jar（被所有子项目依赖）
├── mjava-mcli/           客户模板 + 最小启动实例
├── mjava-shunfeng/       客户：会议聚合（腾讯会议/Zoom/钉钉日程）
├── mjava-guangming/      客户：钉钉 SSO 邮箱
├── mjava-pro/            专项：多客户单部署（宜搭应用表驱动）
├── mjava-com/            专项：通用能力 BaaS 网关
├── openspec/             规范驱动开发（changes / specs / archive）
├── CLAUDE.md             AI 协作入口（本仓库 opsx 工作流指引）
└── pom.xml               聚合 pom
```

## 基座能力(`mjava/`)

所有子项目通过 `@SpringBootApplication(scanBasePackages = {"com.malk"})` 自动扫到。

### 核心工具 `com.malk.utils`

| 类 | 能力 |
|----|------|
| `UtilHttp` | HTTP 请求统一入口（Hutool 封装，GET/POST/PUT/DELETE/PATCH/UPLOAD/DOWNLOAD/SOAP） |
| `UtilToken` | access_token 内存缓存（TimedCache，自动冗余 -5s） |
| `UtilSignature` | HMAC-SHA256 签名 + SHA256 + 常量时间比较 |
| `UtilMap` / `UtilList` / `UtilString` | 集合/字符串常用辅助 |
| `UtilDateTime` / `UtilNumber` / `UtilMath` | 时间/数值处理 |
| `UtilExcel` | EasyExcel 封装 |
| `UtilFile` / `UtilServlet` / `UtilConvert` | IO / 类型转换 |
| `UtilEnv` / `UtilMc` / `UtilImport` | 环境 / 杂项 |

### 响应与异常 `com.malk.server.common`

| 类 | 能力 |
|----|------|
| `McR<T>` | 统一 Controller 响应（success / code / message / data / source） |
| `VenR` | 第三方原始响应基类（`assertSuccess()`） |
| `McException` | 业务异常（`(code, message)` 构造） |
| `McREnum` | 错误码枚举 |
| `McPage` | 分页封装 |

### 过滤与拦截 `com.malk.filter`

| 类 | 能力 |
|----|------|
| `TraceIdFilter` | 请求 traceId 注入 MDC，X-Trace-Id 响应头回传 |
| `CatchException` | 全局异常处理（`@RestControllerAdvice`） |
| `RequestInterceptor` | 请求日志（point logger） |
| `AuthFilter` + `AuthInterceptor` | 请求鉴权 + 防重放（HMAC + 时间窗 + Nonce），默认关闭 |
| `NoAuth` | 鉴权豁免注解 |

### 持久化 `com.malk.base`

| 类 | 能力 |
|----|------|
| `BasePo` | 实体基类（自动审计 createTime/updateTime/createBy/updateBy） |
| `BaseDto` | DTO 基类 |
| `BaseRepository<PO, ID>` | JPA Repository + QueryDSL 基类 |
| `BaseDao` / `JpaMap` | DAO 辅助 |

### 配置 `com.malk.config`

| 类 | 能力 |
|----|------|
| `WebConfiguration` | MVC 拦截器注册 + CORS |
| `DataSourceConfig` | 多数据源（`spel.multiSource=true` 开启） |
| `JpaConfiguration` | JPA 审计 |
| `OpenApiConfig` | Swagger UI（`swagger.enable=true` 开启） |
| `AsyncConfig` | 线程池 + `MdcTaskDecorator` |
| `AuthConfigProperties` | 基座鉴权配置 |

### 第三方对接 `com.malk.service.{vendor}`

| Vendor | 已覆盖 Domain |
|--------|---------------|
| **dingtalk** | Contacts（v2 对齐 27 方法）/ Attendance / Workflow / Notice / Storage / Group / Schedule / Event / Personnel / Report / Extension / Dedicated |
| **aliwork**（宜搭） | Form（原子 16 方法）/ Process（原子 13 方法）/ 旧聚合 YDClient（保留） |
| **beisen**（北森） | Employee / Attendance |
| **teambition** | Client / Service |
| **fxiaoke**（纷享销客） | Client |
| **h3yun**（氚云） | Client |
| **vika**（维格表） | Client |
| **xbongbong** | Client |
| **ekuaibao**（易快报） | Client |

每个 vendor 遵循 **Client**（原子）+ **Service**（组合）两层分层。

### 其他模块

| 包 | 能力 |
|----|------|
| `core/AsyncConfig` + `MdcTaskDecorator` | @Async 线程池 + MDC 传递 |
| `core/NonceCache` | LRU+TTL Nonce 去重 |
| `delegate/` | DDEvent / TBEvent 委托回调 |
| `schedule/McScheduleTask` | `@Scheduled` 定时任务基类 |
| `repository/dao+entity/{primary,slave}/` | 多数据源示例 |

## 子项目速览

| 子模块 | 端口 | Context | 状态 |
|--------|------|---------|------|
| `mjava-mcli` | 9001 | /api/mcli | 新客户模板 |
| `mjava-shunfeng` | 9002 | /api/sf | 生产客户（顺丰：腾讯会议/Zoom/钉钉日程聚合） |
| `mjava-guangming` | 9003 | /api/gm | 生产客户（光明：钉钉 SSO → 德惠邮箱） |
| `mjava-pro` | 9010 | /api/pro | 专项骨架（多客户单部署，宜搭应用表驱动租户配置） |
| `mjava-com` | 9020 | /api/com | 专项骨架（BaaS 网关，HMAC 签名 + 限流） |

## 核心约定

- Controller 返回 `McR<T>`；业务异常 `throw new McException(code, message)`
- HTTP **禁三方 SDK**，统一 `UtilHttp` / `DDR.doPost` / `DDR_New.doPost`
- Token **禁每请求重取**，走 `UtilToken`（key `{vendor}:{appKey}`）
- 鉴权参数从 `application-{profile}.yml` 读，**禁硬编码**
- JPA + QueryDSL 持久化，**不与 MyBatis 混用**
- 生产配置 `application-prod.yml` 不入 git，`*.yml.example` 入 git

详细规范见**文档中心** `/Users/malk/Desktop/Tech/claude/后端/CLAUDE.md`。

## 快速开始

```bash
# 编译
mvn -pl mjava-mcli -am clean compile

# 打包
mvn -pl mjava-mcli -am clean package -DskipTests

# 启动
java -jar mjava-mcli/target/mjava-mcli.jar --spring.profiles.active=prod
```

## 新客户接入

```bash
cp -r mjava-mcli mjava-{customer}

# 1. pom.xml: artifactId=mjava-{customer}
# 2. Boot.java: package=com.malk.{customer}, 保留 scanBasePackages={"com.malk"}
# 3. application-*.yml: server.port / context-path / datasource / vendor 凭据
# 4. 根 pom.xml <modules> 追加

mvn -pl mjava-{customer} -am clean compile
```

详见文档中心 `/Users/malk/Desktop/Tech/claude/后端/CLAUDE.md` → "子项目接入流程"。

## OpenSpec 扩展

本仓库内 `openspec/` 驱动演进:

```bash
/opsx:propose   # 新 change 提案
/opsx:apply     # 实施 tasks.md
/opsx:archive   # 归档完成的 change + 自动合并稳态 spec
/opsx:explore   # 需求/约束梳理
```

已归档稳态 capability（位于 `openspec/specs/`）:

| capability | 覆盖 |
|-----------|------|
| `project-baseline` | 仓库级基线指针 |
| `crypto-utils` | RSA 加密工具 |
| `yida-form-atomic` | 宜搭表单原子接口（16 方法） |
| `yida-process-atomic` | 宜搭流程原子接口（13 方法） |
| `dingtalk-contacts-v2` | 钉钉通讯录 v2 对齐（27 方法） |
| `request-auth` + `replay-guard` | 基座 HMAC 鉴权 + 防重放 |

## 文档索引

| 文档 | 用途 |
|------|------|
| `./CLAUDE.md` | 本仓库 AI 协作入口（opsx 工作流指引 + change 状态） |
| `/Users/malk/Desktop/Tech/claude/后端/CLAUDE.md` | **后端开发主规范**（必读） |
| `/Users/malk/Desktop/Tech/claude/后端/.claude/docs/yida-serverside.md` | 宜搭 YDClient Java 特化规范 |
| `/Users/malk/Desktop/Tech/claude/.claude/docs/data-structures.md` | 宜搭字段数据结构（前后端通用） |
| `/Users/malk/Desktop/Tech/claude/.claude/docs/search-field-format.md` | 宜搭查询条件格式 |
| `/Users/malk/Desktop/Tech/claude/宜搭/CLAUDE.md` | 宜搭前端 JS/JSX 规范 |

## 远端

`https://mc.cloudpure.cn/vibeCoding/mjava-ai.git`