diff --git a/docs/CI集成说明.md b/docs/CI集成说明.md index 8157012..e449f4d 100644 --- a/docs/CI集成说明.md +++ b/docs/CI集成说明.md @@ -15,7 +15,7 @@ Gitea Actions 触发 ↓ java -jar 执行(对比 before → after,累计 diff) ↓ -有结构变更 → 企微通知(按 Key 骨架;删除橙/新增绿) +有结构变更 → 企微通知(按 Key 骨架;删除橙/新增绿/修改灰) ↓ mode=block 且含任意结构变更 → exit 1(流水线失败) ``` @@ -94,19 +94,19 @@ java -jar serialization-schema-checker-1.0.0.jar \ ## 5. 与现有流水线的关系 -| 流水线 | 作用 | 关系 | -|--------|------|------| +| 流水线 | 作用 | 关系 | +|--------|----------------|------| | `demo.yaml` (AI代码质量分析) | AI Code Review | 并行,互不影响 | -| `code-check` (CodeChecker) | 通用变更检测 | **同模式**,可并列执行 | -| `serialization-schema-check` | 缓存结构检测 | 新增 | +| `code-check` (CodeChecker) | 通用变更检测 | **同模式**,可并列执行 | +| `serialization-schema-check` | 序列化结构检测 | 新增 | --- -## 6. 工具发布流程(redisCheck 仓库) +## 6. 工具发布流程(schemaCheck 仓库) ```bash -# 在 redisCheck 仓库根目录 +# 在 schemaCheck 仓库根目录 mvn clean package -DskipTests # 发布到 Nexus(需配置 settings.xml) @@ -177,6 +177,6 @@ java -jar /path/to/serialization-schema-checker-1.0.0.jar \ | 文档 | 说明 | |------|------| -| [实施方案.md](./实施方案.md) | 缓存检测总体方案 | +| [实施方案.md](redis序列化结构检测实施方案.md) | 缓存检测总体方案 | | [配置说明.md](./配置说明.md) | YAML 配置项 | -| [MQ序列化结构检测方案.md](./MQ序列化结构检测方案.md) | MQ 消息体 Schema(RocketMQ + Kafka,方案已落地) | +| [MQ序列化结构检测方案.md](MQ序列化结构检测实施方案.md) | MQ 消息体 Schema(RocketMQ + Kafka,方案已落地) | diff --git a/docs/MQ序列化结构检测方案.md b/docs/MQ序列化结构检测实施方案.md similarity index 96% rename from docs/MQ序列化结构检测方案.md rename to docs/MQ序列化结构检测实施方案.md index ea5f350..23914fb 100644 --- a/docs/MQ序列化结构检测方案.md +++ b/docs/MQ序列化结构检测实施方案.md @@ -69,7 +69,7 @@ rocketMQTemplate.syncSend(CapitalMqConstants.TOPIC + ":" + tag, req); // WalletD public class WalletDeductConsumer implements RocketMQListener { ... } ``` -### 2.2 Kafka(已确认需纳入) +### 2.2 Kafka | 写法 | 出现情况 | 策略 | |------|----------|------| @@ -105,7 +105,7 @@ public void handleMessage(String message) { 动态 Topic(如按租户拼接)静态推断结果形如 `patrol-store-topic:*`,与 Redis key `*` 规则一致。 -### 2.3 「Key」等价物(destination) +### 2.3 「Key」等价物 | 中间件 | 聚合键形态 | 来源 | |--------|------------|------| @@ -114,7 +114,7 @@ public void handleMessage(String message) { 无法解析时:展示表达式 + `(destination 未解析)`。 -### 2.4 读侧补强(类比 W06) +### 2.4 读侧补强 | 中间件 | 补强来源 | |--------|----------| @@ -319,7 +319,6 @@ manual_mappings: | 生产/消费跨模块对不齐 | 同仓索引 + destination 对齐;失败则仅写侧 | | Jackson / Fastjson / Kafka JsonSerializer 细节差 | 首版字段名;必要时方言或 mapping | | 只改消费未改生产类型 | 不告警(工具职责是消息体 Schema) | -| `include_modules` 过窄 | 观察期扩大模块或置空全仓 | --- @@ -327,10 +326,8 @@ manual_mappings: | 项 | 结论 | |----|------| -| 中间件范围 | **RocketMQ + Kafka**(本仓已确认);Rabbit 暂不纳入 | +| 中间件范围 | **RocketMQ + Kafka**| | 对比区间 | `gitea.event.before` → `gitea.sha` | -| 阻断 | 与现网 `mode` 共用 | -| 级别 | 不引入 P0/P1/P2 产品展示 | | 交付 | 同一 jar;patterns 区分 Redis / MQ(含 MQ-K*) | --- @@ -340,4 +337,3 @@ manual_mappings: 1. ~~按 Phase M1 开发~~ **已完成**(MQ01/02 + MQ-K01/K02) 2. ~~按 Phase M2 开发~~ **已完成**(MQ03~05、MQ-K03/K04、MQ-R) 3. 业务仓验收:`MessageBuilder` IM Topic、巡店/值班 Kafka、`capital-topic:WALLET_DEDUCT` -4. 观察期按需扩大 `include_modules` diff --git a/docs/实施方案.md b/docs/redis序列化结构检测实施方案.md similarity index 94% rename from docs/实施方案.md rename to docs/redis序列化结构检测实施方案.md index f69293d..a2c223a 100644 --- a/docs/实施方案.md +++ b/docs/redis序列化结构检测实施方案.md @@ -4,7 +4,7 @@ > 日期:2026-07-15 > 技术栈:Java 11 + Maven + JavaParser > 目标仓库:`schemaCheck`(工具) / `jnpf-java-cloud`(被检测业务仓库) -> 当前阶段:**Phase 1 + Phase 2 已完成**;Phase 3 运营待做;**MQ 扩展方案已文档落地**(见 `docs/MQ序列化结构检测方案.md`) +> 当前阶段:**Phase 1 + Phase 2 已完成**;**MQ 扩展方案已文档落地**(见 `docs/MQ序列化结构检测方案.md`) --- @@ -161,13 +161,11 @@ flowchart TB | 报告 | Jackson | 2.15.x | JSON/Markdown 报告序列化 | | 测试 | JUnit 5 | 5.10.x | 单元测试 + 夹具样本 | -**不采用** Spoon / Eclipse JDT 的原因:JavaParser 足够覆盖第一版需求,依赖更轻,CLI 启动更快。 - **Lombok 处理策略**:基于源码字段 + `@Data` 等注解推断序列化字段;对 `@Builder`、`@SuperBuilder` 等复杂场景标记为低置信度提示。后续可选集成 `lombok.ast` 或 delombok 预处理。 --- -## 5. 工程结构(redisCheck 仓库) +## 5. 工程结构(schemaCheck 仓库) ```text schemaCheck/ @@ -527,31 +525,6 @@ notify: | 企微高亮 | 删除橙 `warning` / 新增绿 `info`;位置+类型通用项 | ✅ | | W06 读侧辅助 | `parseObject`/`parseArray` 等补强写入 value 类型 | ✅ | -### Phase 3 — 运营 - -| 任务 | 说明 | -|------|------| -| 报告落盘 | 可选输出 JSON 报告文件 | -| 误报反馈 | `suppressions` 按写入点 / change_types 精细忽略 | -| 更多业务场景覆盖 | 考勤、文件下载进度等 | - -### Phase 4 — MQ 消息体结构检测(已落地,含 Kafka) - -业务仓同时存在: - -- **RocketMQ**:`RocketMQTemplate.syncSend` / `asyncSend` / `MessageBuilder` / `RocketMQListener` -- **Kafka**:`KafkaTemplate.send(topic|ProducerRecord, …)` / `@KafkaListener` + `parseObject` - -消息体字段变更会导致积压旧消息反序列化失败,风险模型与 Redis 同类。 - -| 任务 | 说明 | 状态 | -|------|------|------| -| 方案文档 | RocketMQ + Kafka 模式、destination、复用 Schema Diff/企微 | ✅ | -| Phase M1 | RocketMQ sync/async + Kafka send + 骨架通知 + 夹具 | ✅ | -| Phase M2 | MessageBuilder / convertAndSend / ProducerRecord / JSON 字符串 + MQ-R | ✅ | - -**专用方案:** [`docs/MQ序列化结构检测方案.md`](./MQ序列化结构检测方案.md) - --- ## 11. 测试策略 @@ -611,7 +584,7 @@ notify: | 4 | 上线策略 | 先 `notify` ,稳定后手动切 `block` | | 5 | 检测范围 | **仅 `src/main/java`**,不扫描测试代码 | -以上决策已纳入实施方案;**Phase 1 / Phase 2 已交付**。缓存侧可进入 Phase 3;MQ 侧以 [`MQ序列化结构检测方案.md`](./MQ序列化结构检测方案.md) 为准评审后开发。 +以上决策已纳入实施方案;**Phase 1 / Phase 2 已交付**。缓存侧可进入 Phase 3;MQ 侧以 [`MQ序列化结构检测方案.md`](MQ序列化结构检测实施方案.md) 为准评审后开发。 相关文档: diff --git a/docs/配置说明.md b/docs/配置说明.md index 275d3ce..f9352ed 100644 --- a/docs/配置说明.md +++ b/docs/配置说明.md @@ -264,7 +264,7 @@ detection: 企微 MQ 块:`- Topic --> ...`,并带 `> **通道**: RocketMQ|Kafka`。 -详见:[MQ序列化结构检测方案.md](./MQ序列化结构检测方案.md) +详见:[MQ序列化结构检测方案.md](MQ序列化结构检测实施方案.md) ### 3.6 manual_mappings @@ -378,12 +378,4 @@ notify: include_modules: [] # 全仓 ``` ---- - -## 7. MQ 消息体检测(Phase M1 + M2 已落地) - -同一 jar 默认启用 RocketMQ / Kafka **生产侧**投递检测(`detection.mq_patterns`)与 **MQ-R** 读侧补强,与 Redis 共用 Diff、骨架与企微模板。 - -- 配置说明见 §3.5.2 -- 含 `MessageBuilder` / `convertAndSend` / `ProducerRecord` / JSON 字符串发送、Listener/`parseObject` 补强 -- 完整设计:[MQ序列化结构检测方案.md](./MQ序列化结构检测方案.md) \ No newline at end of file +--- \ No newline at end of file