|
|
@@ -0,0 +1,194 @@
|
|
|
+# 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`
|
