uw-analyze-service 是 nearform/unwind 中的服务层分析技能,适用于分析业务逻辑、用例、服务编排,以及包括 DTO 和映射器在内的数据转换。
输出位置 分析结果写入 docs/unwind/layers/service-layer/,该目录包含 index.md 和若干分节文件。遵循 analysis-principles.md 所述原则:完整、机器可读、链接到源码、不加评论、增量写入。
输出结构 默认结构包括:index.md(概览、服务数量、依赖图)、services.md(服务类定义)、dtos.md(数据传输对象)、mappers.md(映射逻辑)、formulas.md(业务计算,标注为 MUST)、clients.md(外部客户端集成)。对于包含 20 个以上服务的大型代码库,可按领域拆分,例如 users-domain.md、orders-domain.md 等。
使用方式(增量写入流程) 第 1 步:创建目录,写入初始 index.md,列出各分节并标记为 pending。 第 2 步:查找所有服务类,记录方法签名与事务边界,立即写入 services.md 并更新 index.md。 第 3 步:查找所有 DTO(请求/响应),记录校验注解,立即写入 dtos.md 并更新索引。 第 4 步:查找所有映射器,写入 mappers.md 并更新索引。 第 5 步:提取全部业务计算,记录常量与边界情况,写入 formulas.md 并更新索引。 第 6 步:如存在外部客户端集成,写入 clients.md 并更新索引。 第 7 步:在 index.md 中补充依赖图和最终统计。
输出格式 文档按服务、DTO、映射器、外部客户端等分节组织,每项附带指向源码文件的链接和相应代码片段,最后给出服务依赖图(Mermaid graph TD)以及 Unknowns 清单,用于列出不明确之处。
公式文档要求(MUST) 每个计算或业务公式需提供精确源码引用(如 snapshot-operations.ts:186);完整记录边界情况和条件逻辑(如按小时/天/周/月/年的费率区间差异);记录硬编码常量及其位置;记录回退与解析链路(如费率解析的主选、回退、缺失处理)。事务边界标注为 SHOULD,说明事务起止位置及批处理模式。
强制标签 每个服务、函数和公式标题须标注 [MUST]、[SHOULD] 或 [DON'T]。服务层默认分类:[MUST] 用于业务逻辑、计算、公式、常量、解析链;[SHOULD] 用于日志、缓存模式、事务边界;[DON'T] 用于框架特定模式、依赖注入语法。
刷新模式 若 docs/unwind/layers/service-layer/ 已存在,则比较当前状态,并在 index.md 中新增“## Changes Since Last Review”一节。
适用场景与限制 适用于对 Java 等服务层代码库进行结构化梳理与文档化,便于追踪业务逻辑、数据转换和外部依赖。技能文档未提供安装命令、平台支持、收费方式或效果指标,这些信息暂未提供。