cleanddd-kotlin-coding

name	cleanddd-kotlin-coding
description	在 only-danmuku 的 CleanDDD Kotlin 项目中编写或修改聚合/命令/查询/API 端点/事件/防腐层 Client/仓储/配置/测试时使用；遵循 代码实现规约.md 与 design/_gen + genDesign 的生成流程。

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 空格缩进；简单返回用表达式体；避免通配符导入。

推荐流程

1. 补设计元素：在 design/*_gen.json 中补命令/查询/事件/校验器/Client，执行 ./gradlew genDesign。
2. 实现 domain：聚合/实体/值对象/领域方法/领域事件。
3. 实现 application：命令/查询契约、校验器、Handler、订阅者。
4. 实现 adapter：Controller、QueryHandler、ClientHandler。
5. 补配置与日志：关键路径配置化，关键行为打点。

分层职责

• adapter 层：仅做编排与入参校验，调用 Mediator.commands.send(...) 或 Mediator.queries.send(...)；不写业务分支、不操作聚合、不访问仓储/事务。
• application 层：组织用例流程与事务边界；命令写端、查询读端分离。
• domain 层：聚合根/实体/领域方法/领域事件；不关注 Web 与持久化细节。

API 端点（Controller）

• 位置：only-danmuku-adapter/.../portal/api，按业务拆分文件，统一 @PostMapping。
• 使用 Request DTO + 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 生成骨架。