CleanDDD Kotlin Coding（only-danmuku）
必读参考
- •若仓库存在
代码实现规约.md，先阅读并以其为准；此技能用于补足执行步骤与易错点。 - •需要新增命令/查询/事件/校验器/Client 时，先更新
design/*_gen.json，再执行./gradlew genDesign。
前置输入
- •已有 cleanddd-modeling 交付：
iterate/<feature>/*_gen.json与*_update.sql。 - •已确认聚合边界、不变式、命令/查询清单与事件链路。
快速检查
- •遵循 CQRS：命令不依赖查询、查询不依赖仓储；命令内禁止使用读端
sqlClient。 - •聚合边界：仅聚合根发布领域事件；命令/事件不以子实体 ID 作为入参。
- •持久化：命令通过仓储整体加载聚合并使用领域方法变更，禁止直接改字段。
- •防腐层：仅做外部系统/文件交互，不包含数据库 ID 概念。
- •规范：DTO 使用
Request/Response后缀；JSR-303 校验 +KnownException处理业务错误。 - •Kotlin 风格：4 空格缩进；简单返回用表达式体；避免通配符导入。
推荐流程
- •补设计元素：在
design/*_gen.json中补命令/查询/事件/校验器/Client，执行./gradlew genDesign。 - •实现 domain：聚合/实体/值对象/领域方法/领域事件。
- •实现 application：命令/查询契约、校验器、Handler、订阅者。
- •实现 adapter：Controller、QueryHandler、ClientHandler。
- •补配置与日志：关键路径配置化，关键行为打点。
分层职责
- •adapter 层：仅做编排与入参校验，调用
Mediator.commands.send(...)或Mediator.queries.send(...)；不写业务分支、不操作聚合、不访问仓储/事务。 - •application 层：组织用例流程与事务边界；命令写端、查询读端分离。
- •domain 层：聚合根/实体/领域方法/领域事件；不关注 Web 与持久化细节。
API 端点（Controller）
- •位置：
only-danmuku-adapter/.../portal/api，按业务拆分文件，统一@PostMapping。 - •使用
RequestDTO + JSR-303 注解；必要时配合自定义校验器。 - •只做上下文解析与调用 Mediator，不直接操作聚合或仓储。
命令（Command）
- •位置：
only-danmuku-application/.../commands。 - •单命令只修改一个聚合根；跨聚合通过领域事件 + 额外命令解耦。
- •从仓储加载聚合，调用领域方法完成变更，
Mediator.uow.save()提交。 - •复杂校验用“校验器 + 查询”承担；缺查询先在 design 中定义并生成。
查询（Query）
- •契约：
only-danmuku-application/.../queries。 - •实现：
only-danmuku-adapter/.../application/queries，依赖KSqlClient而非仓储。 - •返回 DTO 或投影模型；在查询层完成过滤/分页/排序/拼装。
聚合与领域方法
- •聚合/实体可变字段统一
internal set；禁止在命令中直接赋值。 - •通过领域方法封装状态变更、约束检查与事件触发。
- •生命周期使用
onCreate/onUpdate/onDelete框架回调，禁止业务代码手动调用。
领域事件与订阅
- •命名：
实体 + 过去式动作，如VideoPostTranscodingRequiredDomainEvent。 - •监听器只做编排并触发命令；同一事件多动作时拆分监听方法。
- •事件定义缺失时，先在 design 中补齐并
genDesign生成骨架。
防腐层 Client
- •契约：
only-danmuku-application/.../distributed/clients。 - •Handler：
only-danmuku-adapter/.../application/distributed/clients，仅做外部调用与结果映射。 - •设计元素使用
cli（或别名client）；先在 design 中定义再生成。
校验器
- •位置：
only-danmuku-application/.../validater（以仓库实际目录为准）。 - •依赖查询、不依赖仓储；尽早失败并抛
KnownException。
代码生成与设计文件
- •设计文件位于
only-danmuku/design/*_gen.json，支持标签别名（如cmd/command、qry/query、cli/client）。 - •执行
./gradlew genDesign生成命令/查询/事件/校验器/Client 骨架。
其他通用约定
- •日志：只记录关键行为（转码、外部调用），包含关键标识（videoId、uploadId 等）。
- •配置：路径、阈值用配置类管理，避免硬编码。
- •规模限制：列表/数量等限制放在命令或聚合内统一收敛。
提交前自检
- •领域事件发布完整，监听器不直接跨聚合改数据。
- •命令未混入查询逻辑，查询未依赖仓储。
- •相关新增元素已落入 design 并通过
genDesign生成骨架。