YuDream DDD 架构规范

先解决什么问题

多人维护的 Spring Boot 项目里，DDD 通常在三个月后退化：controller 里出现 new XxxCmd()，application service 直接返回 interfaces 的 res 对象，DO 泄漏到接口层，Excel 模板拼装散落在各个 Controller 的私有方法里。更隐蔽的是中文文案在 PowerShell 输出里变成 鐢ㄦ埛 这类乱码，有人顺手把整份文件转码，反而破坏了原本正常的 UTF-8 源码。

这个技能的作用是把这些已写进代码库的约定固化成强制前置流程：改后端代码之前先读规则，任务涉及某个限界上下文时，先把 yudream-domain、yudream-application、yudream-infrastructure、yudream-interfaces 四个模块中对应的包全部读一遍，再动手。这样可以避免只看一个模块就下结论，把转换逻辑写错层。

核心约束

技能用 system/user 包作为基线模式，作为聚合根、值对象、仓储、应用命令/查询/DTO、基础设施 dataobj/mapper/impl/service、接口 controller/assembler/request/res 的统一参照。

• Domain：只放业务含义和不变式。aggregate 承载聚合根与实体，valobj 放 RoleID、UserDept 这类类型化标识与复合值，repo 只保留仓储接口，不允许出现持久化实现，框架类与 Web 类不得进入这一层。
• Application：负责用例编排。cmd / query 区分读写用例输入，service 可以构造聚合并调用聚合方法，但不能返回 res 对象、也不能接收 request 对象，持久化相关的查询构造同样排除在外。
• Infrastructure：承担技术适配。dataobj 存放 Mongo DO，mapper 负责 DO 与 domain 的转换，impl 实现 domain 的 repo 接口，S3、Redis、Sa-Token 网关细节、邮件等外部系统收敛在这里，通过 domain/application 契约暴露。
• Interfaces：只做 HTTP/API 边界。controller 负责路由、鉴权注解、参数校验触发与响应包装，所有 request → cmd、domain/app DTO → res、Excel 行映射、模板行生成都交给 assembler。

Controller 的硬规则：禁止 new XxxCmd、new XxxRes、new XxxExcelRow 和 builder() 构造，禁止 toXxx、parseXxx、templateXxx、rowToXxx 这类转换与模板拼装，禁止请求行到命令的流式映射，也禁止放业务不变式。Controller 可以设置分页上限、调用 auth/session 辅助方法、把应用层返回值交给 assembler 转换并返回 Result。

Excel 导入导出使用 EasyExcel，HTTP 文件读写放到 ExcelHttpSupport 这类支持类里，行映射与模板行创建归 interface assembler。导出接口返回 blob，前端统一用 saveExcelResponse、pickExcelFile、excelForm、importResultMessage。新增 v-auth 按钮时需要在菜单种子枚举里补上匹配权限。

中文文案方面，禁止把中文字符串转成 \uXXXX 转义，也不要因为 PowerShell 显示乱码就改文件；真正需要修的是源码里已经损坏的 鐢ㄦ埛、绯荤粺、鍒犻櫎、鏄?、涓嶅瓨鍦? 这类乱码文本。

增量知识与适用边界

references/knowledge.json 是项目级的经验沉淀：遇到重复踩坑、已知工具函数或工具用法时先读它；当用户多次纠正同一类风格或架构问题、出现可复用的 bug 诊断与修复、发现值得复用的 utility 或端点、或某条规则过细不适合塞进核心 SKILL.md 时，通过 scripts/add_knowledge.py 追加。

需要注意，这套约束绑定的是 online.yudream.base 下的 yudream-* 四个模块结构，包名与角色划分是强约定。换到其他项目的 DDD 目录布局时，包路径不能直接照搬，但 domain 不依赖框架、应用层不做边界转换、基础设施隔离外部系统、接口层只做协议适配这条分层主线仍然适用。