HTML 报告格式

架构评审渲染为 OS 临时目录下的单个自包含 HTML 文件。Tailwind 和 Mermaid 均来自 CDN。Mermaid 能可靠处理图形化图表；手写的 div 和内联 SVG 负责更偏编辑性的视觉元素（质量图、横截面）。两者混合使用——不要事事依赖 Mermaid，否则会显得千篇一律。

脚手架

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>架构评审 — {{仓库名称}}</title>
    <script src="https://cdn.tailwindcss.com"></script>
    <script type="module">
      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
    </script>
    <style>
      /* 用于 Tailwind 未覆盖场景的小型自定义层：
         虚线接缝线、手绘风格箭头等 */
      .seam { stroke-dasharray: 4 4; }
      .leak { stroke: #dc2626; }
      .deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
    </style>
  </head>
  <body class="bg-stone-50 text-slate-900 font-sans">
    <main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
      <header>...</header>
      <section id="candidates" class="space-y-10">...</section>
      <section id="top-recommendation">...</section>
    </main>
  </body>
</html>

页头

仓库名称、日期，以及一个紧凑图例：实线框 = 模块，虚线 = 接缝，红色箭头 = 泄漏，粗深色框 = 深层模块。无需引言段落——直接进入候选方案。

候选卡片

图表承载主要信息。文字描述应简洁、平实，直接使用词汇表中的术语（参见 LANGUAGE.md），无需额外说明。

每个候选方案为一个 <article>：

标题 —— 简短，指明深化方向（例如"折叠订单接收管道"）。
徽章行 —— 推荐强度（强烈推荐 = 翠绿色，值得探索 = 琥珀色，探索性 = 石板色），外加依赖分类标签（进程内、本地可替代、端口与适配器、模拟）。
文件 —— 等宽字体列表，font-mono text-sm。
改造前/改造后对比图 —— 核心内容。两列并排。具体模式见下文。
问题 —— 一句话。痛点所在。
解决方案 —— 一句话。变更内容。
收益 —— 要点列表，每项不超过 6 个词。例如"测试仅命中一个接口"、"定价逻辑不再泄漏"、"删除 4 个浅层包装器"。
ADR 标注（如适用）—— 琥珀色背景框中的一行文字。

无需解释性段落。如果图表需要一段文字才能理解，请重新绘制图表。

图表模式

根据候选方案选择匹配的模式。可混合使用。不要让每张图表看起来都一样——多样性本身就是目的之一。

Mermaid 图（依赖/调用流的常用方案）

当表达要点是"X 调用 Y，Y 调用 Z，一团乱麻"时，使用 Mermaid 的 flowchart 或 graph。将其包裹在 Tailwind 风格的卡片中，使其不显得突兀。使用 classDef 将泄漏边着色为红色，将深层模块着色为深色。时序图非常适合"改造前：6 次往返；改造后：1 次"的场景。

<div class="rounded-lg border border-slate-200 bg-white p-4">
  <pre class="mermaid">
    flowchart LR
      A[OrderHandler] --> B[OrderValidator]
      B --> C[OrderRepo]
      C -.leak.-> D[PricingClient]
      classDef leak stroke:#dc2626,stroke-width:2px;
      class C,D leak
  </pre>
</div>

手写方框箭头图（当 Mermaid 的布局不合心意时）

模块使用带边框和标签的 <div> 实现。箭头使用内联 SVG <line> 或 <path> 元素，在相对定位的容器上进行绝对定位。当你想让"改造后"图看起来像一个粗边框的深层模块，内部元素变灰显示时，可以使用这种方式——Mermaid 无法以合适的视觉重量渲染这种效果。

横截面图（适用于层次化浅度分析）

堆叠水平条带（h-12 border-l-4）来展示调用经过的层次。改造前：6 个薄层，每层无所作为。改造后：1 个厚条带，标注合并后的职责。

质量图（适用于"接口与实现等宽"）

每个模块两个矩形——一个表示接口表面积，一个表示实现。改造前：接口矩形几乎与实现矩形一样高（浅层）。改造后：接口矩形矮小，实现矩形高大（深层）。

调用图折叠

改造前：以嵌套方框形式呈现的函数调用树。改造后：同一棵树折叠为一个方框，原内部调用在方框内以淡显方式显示。

样式指导

偏编辑风格，而非企业仪表盘风格。留白充足。标题可选衬线字体（font-serif 与 stone/slate 搭配效果良好）。
颜色慎用：一种强调色（翠绿或靛蓝），加上用于泄漏的红色和用于警告的琥珀色。
图表高度保持约 320px，使改造前/改造后能舒适地并排显示，无需滚动。
图表内模块标签使用 text-xs uppercase tracking-wider——它们应呈现为示意图风格，而非 UI 风格。
唯一的脚本是 Tailwind CDN 和 Mermaid ESM 导入。报告其他部分均为静态内容——无应用代码，除 Mermaid 自身渲染外无交互功能。

最佳推荐部分

一张较大的卡片。候选方案名称、一句话说明理由、以及指向其卡片的锚点链接。仅此而已。

语气

简明英语，简洁——但架构名词和动词直接来自 LANGUAGE.md。简洁不是偏离术语的借口。

精确使用： module（模块）、interface（接口）、implementation（实现）、depth（深度）、deep（深层）、shallow（浅层）、seam（接缝）、adapter（适配器）、leverage（杠杆效应）、locality（局部性）。

切勿替换为： component（组件）、service（服务）、unit（单元）代替 module（模块）· API、signature（签名）代替 interface（接口）· boundary（边界）代替 seam（接缝）· layer（层）、wrapper（包装器）代替 module（模块），当你的意思是 module 时。

符合该风格的表述：

"订单接收模块较浅——接口几乎与实现相当。"
"定价逻辑跨越接缝泄漏。"
"深化：一个接口，一个测试点。"
"两个适配器证明了接缝的价值：生产环境用 HTTP，测试环境用内存。"
"收益要点"使用词汇表术语说明收益："局部性：bug 集中在一个模块"、"杠杆效应：一个接口，N 个调用点"、"接口缩小；实现吸收了包装器"。不要写 "更易维护" 或 "代码更整洁"——这些术语不在词汇表中，不应占位。

不要含糊其辞、不要铺垫、不要写"值得一提的是……"。如果一个句子可以写成要点，就写成要点。如果一个要点可以被删除，就删除它。如果某个术语不在 LANGUAGE.md 中，在创造新术语之前，先使用已有的术语。

6.9 KiB Raw Permalink Blame History Unescape Escape