# 新通：在存量系统中逐步明确模块与集成边界

本文依据 2026 年 10 月本地检出的新通工作区代码、构建文件和文档整理，讨论可供新项目或 Agent 借鉴的取舍。仓库同时保留旧代码、新模块和多种前端；文件存在不等于能力已迁移完成或已经部署。这里记录的是渐进演进经验，不推荐新项目复制旧技术版本。

## 技术现状与历史约束

| 部分 | 仓库中可见的选择 | 阅读方式 |
| --- | --- | --- |
| 后端 | Java 17、Spring Boot 3.2、MyBatis-Plus、MySQL、Redis／Redisson、RabbitMQ、Maven 多模块 | 以当前启动模块和依赖为准，不把每个声明的模块都当成独立服务。 |
| 既有 Web 与管理端 | Vue 2、Vue CLI、Element UI 等旧生态 | 本地构建受 Node 14 等历史依赖约束；这是存量兼容条件，不是新项目默认选型。 |
| 其他入口 | 仓库另有 Nuxt 资讯站和小程序代码 | 按实际用户任务分别核对，不能从工作区目录推断它们共用同一发布链路。 |

公司新项目从[四仓技术基线](../../engineering/scaffolds/technology-selections.md)起步。维护本篇所述旧产品时，先确认现有依赖和运行入口，再选择最小可交付改动，不因“技术较旧”就同时重写多个前端。

## 模块目录不等于已经完成拆分

后端根工程同时包含 `monolith-core` 和按学习、交易、营销、内容等知识划分的 `module-*`。当前 `module-server` 是可执行入口，既依赖旧的 `xintong-admin`，也装配新的营销与平台模块。这是一个过渡中的模块化单体：新旧代码仍在同一进程协作，不是多个微服务。

对 Agent 的启发是先沿真实调用链找业务规则的所有者，再把相关规则、数据访问与外部协议逐步收拢到对应模块。不要仅凭目录名宣称“完成领域拆分”，也不要为了迁移而给每个模块增设网络 API。判断是否改善，要看一次规则变化还需修改多少处、调用方是否仍要理解旧实现。

## 对外 CRM 集成要隐藏平台格式

当前代码可见一个 CRM 推送编排入口：它收集用户画像，由路由决定目标平台，再交给平台专属的字段、标签转换和推送实现。RabbitMQ 消费者将异步事件交给这条业务链路。业务含义先形成画像，平台 ID、标签格式和请求结构留在各自适配处，避免每个注册、导入或问卷入口都懂外部接口。

但“经过消息队列”本身不等于可靠交付。现有发布入口会捕获并记录部分发送异常；新项目若要求必达，应明确持久化待发送事实、失败回执、重试与幂等的所有者，并区分“本地业务完成”“消息已发出”“外部系统已接受”。只有真实异步或跨系统隔离需求成立时再引入队列。

## 给存量数据指定当前权威

项目约定当前会员明细以 `user_vip` 为准，历史 `vip_user` 不再充当会员权益或时长的依据，聚合展示表也不自动成为写入权威。这比单纯改字段名重要：多代数据共存时，先说明每张表负责什么，再决定读取、同步与迁移顺序。Agent 修复会员逻辑时不能因为历史表名称相似就任选一个来源。

## 区分代码、测试环境和生产效果

主站仓库包含按页面清单生成静态 HTML、sitemap 和 robots 的脚本，也包含构建产物校验。相关 SEO 文档明确要求区分代码已存在、测试环境已部署与生产环境已发布；不能只凭脚本或本地构建宣称搜索引擎已经能抓取正确页面。

这条经验适用于任何公开 Web 产品：发布验收要核对实际 URL 的状态码、初始 HTML、规范地址和资源响应；搜索收录或性能收益还需独立证据。对纯后台系统则无须预建 SEO 流程。

## 核对入口

本篇主要核对 `xintong-java/pom.xml`、`module-server/pom.xml`、`module-marketing/marketing-biz` 中的 CRM 编排与消费者、`monolith-core/xintong-api` 中的消息发布器、`xintong-java/AGENTS.md`，以及 `xintong-smarter-web/package.json`、`scripts/generate-seo-pages.js`、`scripts/verify-seo-build.js` 和 `docs/seo/README.md`。历史方案文档只帮助理解演进动机；当前代码与已部署环境需要分别核实。