【产品底稿 12】工程架构最终定型：完整模块拆分、分包规范、层级依赖与开发规约全清单
一、前置说明
上篇【产品底稿 11】完成了架构规整理念落地，解决表命名混乱、分包随意、模块边界模糊、清偿技术债务等问题，敲定sys_/ai_/biz_表前缀规范与领域分层思想。
本篇不再赘述理念整改，专注把架构彻底落地固化，输出项目最终版完整工程结构、各模块职责、分包路径、依赖约束、双端隔离规则与后续开发统一规约。从「架构定思路」升级为「架构定骨架」，后续所有业务迭代，严格按这套标准执行，不再随意改动结构、乱分包、随意新建类。
二、模块整体最终结构
plaintext
shangzhuhui ├── shangzhuhui-common # 通用工具层（无业务逻辑） ├── shangzhuhui-api # 跨模块契约层（DTO + 公共Service接口） ├── shangzhuhui-plugin-ai # AI能力插件层（DeepSeek、Milvus、Ollama） ├── shangzhuhui-framework # 业务框架层（核心Service、配置、拦截器） ├── shangzhuhui-admin # 管理端启动层（Controller + 专属配置） └── shangzhuhui-customer # 小程序端启动层（Controller + 配置）三、各模块职责与核心分包明细
1. shangzhuhui-common 通用工具包
定位：全局底层支撑，无业务依赖通用返回体、工具类、全局异常、常量枚举统一收拢存放。
2. shangzhuhui-api 跨模块契约层
定位：只做解耦契约，不写业务实现按领域划分 DTO、VO；仅保留必要跨模块 Service 接口，摒弃过度设计与冗余空接口。
3. shangzhuhui-plugin-ai AI 能力插件层
定位：AI 能力插件化，与业务解耦统一封装大模型、向量库配置与服务能力，方便后续替换底层 AI 组件。
4. shangzhuhui-framework 业务框架核心层
定位：项目业务逻辑核心载体按 system /ai/biz 领域分包承载业务服务；统一收拢权限拦截、Web 配置、文件存储、敏感词过滤、全局通用配置。
5. shangzhuhui-admin 管理端启动层
定位：仅做入口路由，不承载业务逻辑只存放控制器、启动类与专属安全配置，按业务领域划分接口层级。
6. shangzhuhui-customer 小程序端启动层
定位：C 端接口入口，只做请求转发业务逻辑全部下沉 framework，自身仅保留控制器、启动类与独立安全配置。
四、全局核心规范与硬性约定
- 数据库表名规范
sys_：系统管理类数据表ai_：AI 内容与知识库相关数据表biz_：小程序 C 端业务数据表实体类名保持简洁，仅通过@TableName绑定规范表名。
双端 Token 隔离规范管理端与小程序端采用两套独立 Token 体系、独立 Redis 存储规则、独立拦截器校验，两端鉴权完全隔离互不干扰。
模块依赖铁律
- admin /customer 只依赖 api、framework、plugin-ai
- framework 依赖 api、common
- api、common 零业务依赖，仅做定义与通用支撑
- 配置下沉规范跨域、拦截器、Redis、敏感词、加密等通用配置，全部下沉至 framework 统一维护，两端杜绝重复定义。
五、后续业务开发统一规约
- 新增业务：先在 framework 对应领域编写 Service 实现，再在 admin /customer 编写对应 Controller。
- 新增传参 / 返回对象：统一收拢到 api 层 DTO、VO 对应领域包下。
- 新增通用工具：直接下沉到 common.utils，禁止各模块重复造轮子。
- 跨模块调用：按需在 api.service 补充接口，不提前预置、不做过度抽象。
六、个人感悟
架构规整不是一次性修补问题，而是不断收敛、逐步定型的过程。上篇是把混乱的架构梳理干净，本篇是把梳理好的结构固化成标准规矩。
从此，工程结构彻底锁死，后续业务开发直接进入按规约填空的阶段。技术债务清零，项目地基稳固，后续只需要专注业务稳步迭代，不用再为架构混乱内耗。
本文是《产品底稿》系列第 12 篇，承接上篇架构治理整改，完成项目多模块工程结构、领域分包、层级依赖、双端隔离与开发规约的最终定型沉淀。专注商助慧 SaaS 产品从架构清债、分层规整到工程脚手架标准化的全流程落地，后续持续记录业务模块迭代、产品设计与工程化实战心得，欢迎持续关注订阅。