领域驱动设计 · DDD 实战 · 设备全生命周期 · AI Agent · 2026-08设备管理是船舶PMS系统的基石——所有保养计划、工单、备件关联都围绕设备卡片展开。本文记录我们如何用 Coze AI Agent以 DDD 为方法论将设备管理的需求规格转化为一份可交付开发团队的详细设计文档。22 个功能点4 个聚合根13 张核心表双驱动保养机制1. 设备管理为什么难设备管理看似是设备信息的CRUD实际上它是整个PMS系统的数据锚点。难点不在字段多少而在它与其他模块的耦合密度设备计数器驱动保养计划的到期判断时间计数器双驱动设备部件关联备件库存一个设备由哪些部件组成每个部件需要什么备件应急设备需要独立的检查周期和合规记录设备故障报告需要与工单形成闭环CWBT国标编码体系需要与设备类型映射设备卡片 ──→ 计数器读数 ──→ 到期判断 ──→ 保养工作项目 ──→ 工单 │ │ ├──→ 部件结构 ──→ 备件关联 ├──→ 应急设备 ──→ 定期检查 └──→ 故障报告 ──→ 维修闭环需求文档把这些功能点列清楚了但要变成开发团队可以直接编码的详细设计需要完成领域建模、状态机设计、数据设计和集成设计。2. 领域建模识别四个聚合根我们用 DDD 的聚合识别原则——“删除它时什么必须一起删除”——从实体关系中识别聚合边界。2.1 设备信息聚合Device设备卡片是整个系统的核心主数据包含设备基本属性、层级关系和技术参数。聚合根Device设备包含实体设备参数DeviceParam、设备备件关联DevicePartsMaterial聚合边界设备的基本属性和参数随设备生命周期管理删除设备时其参数和备件关联一并删除。关键设计判断设备的层级结构ParentId/ParentDevice/DeviceLevel是同一聚合内的自引用不是跨聚合引用。子设备不能脱离父设备独立存在于结构树中但子设备本身又是独立的聚合根——这是一个典型的聚合内持有其他聚合根ID引用的模式。2.2 计数器聚合DeviceCounter计数器是触发计划性保养的核心机制它有独立的生命周期和变更历史。聚合根DeviceCounter设备计数器包含实体计数器变更日志DeviceCounterLog聚合边界计数器当前值和变更日志必须强一致——每次读数更新必须同时写入日志不允许只更新值不记日志。这是一个关键的聚合边界决策。计数器和设备是1:1关系但我们没有把计数器放入设备聚合内部原因是计数器的更新频率远高于设备信息变更计数器有独立的修正审批流程将高频更新的计数器与低频变更的设备信息分离可以降低并发冲突2.3 保养工作项目聚合DeviceJob设备上的每个保养工作项目有独立的计划周期、审批状态和执行历史。聚合根DeviceJob保养工作项目聚合边界工作项目的计划参数、周期设置、审批信息和上次/下次执行日期在同一个事务中维护。2.4 应急设备聚合EmergencyEquipment应急设备救生、消防等有独立的检查周期和合规要求与普通设备管理逻辑不同。聚合根EmergencyEquipment应急设备包含实体应急检查记录EmergencyCheck聚合边界应急设备的检查历史是设备定义的一部分删除设备定义时检查记录一并归档。此外设备故障报告DeviceFault作为独立聚合根存在它通过 CardId 与工单核关联形成故障-维修闭环。3. 核心机制时间与计数器双驱动设备管理最有领域特色的设计是双驱动保养触发机制。一个保养工作项目的到期判断不是简单的上次完成日期周期而是同时支持时间驱动和计数器驱动是是否否计数器读数更新计数器增量 ≥ 周期值?定时调度器当前日期 ≥ 下次计划日期?触发生成工单等待下次读数等待日期到达更新下次计划日期/计数器基准代码中体现这一机制的关键字段字段含义设计作用PeriodUnit周期值周期单位定义保养间隔小时/天/月/次LastDoneDate上次完成日期时间驱动基准LastDoneCounter上次完成时计数器读数计数器驱动基准NextPlanDate下次计划日期时间驱动目标SpanLeft/SpanRight提前/延后宽限期天允许的执行窗口PlanType计划类型区分时间驱动/计数器驱动/混合驱动AI 辅助发现的设计细节HourPerDay字段出现在计数器实体上表明系统支持将运行小时按日均运行时间折算为日历天数从而实现计数器驱动与时间驱动的统一计算。这是一个典型的代码中藏着的业务知识——如果只看需求文档的功能列表很难发现这个折算逻辑。4. 状态机设计从代码字段还原业务流转设备卡片需要审批后生效保养工作项目也有审批流程。AI 通过分析 Status 字段、Controller 名称Approve和审批字段ApproveMan/ApproveDate/ApproveMemo推导出两个状态机。4.1 设备卡片状态机创建设备卡片提交审批审批通过审批驳回修改后重新提交设备停用重新启用设备报废草稿审批中已生效已驳回已停用4.2 计数器变更流程计数器有三种变更场景每种场景的业务规则不同场景触发方式是否需要审批是否写日志修正原因日常读数录入船员手工录入否是不需要读数修正发现录入错误是是必填依赖设备联动关联设备计数器更新否是自动标注ReadWay字段标识读数来源方式GrouplogId将同一次批量录入的多条日志关联在一起——这些字段细节帮助我们设计出更精确的应用服务接口。5. 数据设计13张表的字段级映射详细设计的数据设计部分要求每个字段都来自代码实体不允许编造。AI Agent 逐行读取了以下实体文件device.cs28个字段device_counter.cs9个字段device_counter_log.cs8个字段device_job.cs35个字段mat_emergencyequip.cs10个字段mat_emergencycheck.cs11个字段device_parts_material.cs4个字段device_param.cs6个字段dic_device_sys.cs5个字段dic_device_part.cs10个字段dic_cwbt2devtype.cs3个字段hkmw_device_fault.cs24个字段变体独有dic_mat_counter.cs9个字段对每张表设计文档给出了字段名、类型、是否必填、默认值、业务含义和设计说明。例如设备表的关键字段设计字段类型说明设计要点DeviceIdstring设备唯一标识聚合根ID船舶内唯一ShipIdstring船舶标识多租户隔离键ParentIdstring父设备ID自引用构建设备层级树DeviceLevelint设备层级1系统级, 2设备级, 3部件级IfKeyint是否关键设备关键设备保养要求更严格PmsDeviceint是否纳入PMS未纳入的设备不生成保养计划SpareFlagint?备件标识标识该设备是否可作为备件管理Statusint设备状态关联状态机多客户变体处理hkmw_device_fault是 HKMW 变体独有的故障报告实体。设计文档中通过变体标记明确标注在标准产品中为可选模块。6. CWBT 国标集成CWBT船舶维修保养体系是中国船舶行业的国家标准。设备管理需要将企业内部的设备类型与 CWBT 编码体系映射。设计中DicCwbt2devtype作为一个值对象映射关系通过TypeCode设备类型编码和CwbtCodeCWBT编码建立多对多映射。这个映射关系的设计要点是映射是多对多的一个设备类型可能对应多个CWBT编码一个CWBT编码也可能覆盖多个设备类型映射由岸端统一维护同步到船端设备部件字典DicDevicePart也持有 CwbtCode支持按部件维度的CWBT追溯7. 跨域集成设备管理作为PMS的基础数据域与多个其他上下文有集成关系设备ID计数器读数设备ID部件结构设备ID故障信息CWBT编码应急设备状态设备管理上下文维修保养上下文备件管理上下文工单上下文合规检验上下文安全管理上下文每个集成点都设计了防腐层ACL接口确保设备上下文的内部模型变化不直接影响下游。例如保养上下文需要的计数器读数信息通过ICounterReadingProvider接口获取而不是直接访问设备聚合的内部状态。8. AI 做了什么人做了什么AI 完成的工作约80%实体字段提取逐文件读取13个C#实体类提取全部162个字段聚合边界识别分析实体间的引用关系和生命周期提出4个聚合根的划分方案状态机推导从Status字段、审批字段和Controller命名推导出状态流转图时序图生成根据Controller调用链和实体关系绘制核心流程时序字段设计表为每个字段生成类型、约束、业务含义的说明应用服务接口基于用例生成Command/Query和DTO定义仓储接口为每个聚合根生成仓储接口和查询规格ADR记录将关键设计决策结构化记录人需要决策的部分约20%计数器是否独立聚合AI 提出了方案但最终需要人确认高频更新分离的策略设备层级的聚合处理自引用结构是放聚合内还是跨聚合引用需要根据事务一致性要求判断双驱动折算逻辑HourPerDay的业务含义需要领域专家确认变体差异的范围哪些HKMW独有功能应该纳入标准设计需要产品决策CWBT映射的维护策略多对多映射的数据维护责任和同步方向9. 经验总结9.1 代码是最好的需求补充需求文档说支持计数器管理但代码中的HourPerDay、GrouplogId、DependDeviceId三个字段揭示了三个需求文档未提及的业务能力日均折算、批量分组、设备依赖联动。AI 读取代码的价值不仅是获取字段更是发现字段背后隐藏的业务规则。9.2 变体实体需要显式标记多客户变体系统中某些实体只在特定变体中存在如hkmw_device_fault。设计文档需要明确标注变体归属避免将变体特有逻辑误纳入标准设计。9.3 DDD 的聚合划分需要迭代AI 第一次生成的方案把计数器放在设备聚合内部。我们通过分析更新频率和并发冲突将计数器独立为单独聚合。这种迭代是正常的——聚合边界不是一次性确定的需要根据业务场景和技术约束反复权衡。9.4 状态机必须从代码验证需求文档只说设备卡片需审批后生效但审批有几级、驳回后能否重提、停用后能否重启——这些细节只能从代码字段和Controller逻辑中确认。AI 在这方面的表现令人惊喜它通过分析ApproveMan/ApproveDate/ApproveMemo的组合模式准确推导出了审批流程。