mjava-ai

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。

快速开始

# 编译
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

新客户接入

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/ 驱动演进:

/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