fix(architecture): 改善边界构图并检测近轴折线 (#74)

[qzhqzh]

Problem and value

关联 Issue：#74。

Architecture 图在以下两类构图中会出现“机器校验通过，但最终图仍不够干净”的情况：

1. 嵌套或部分重叠的 boundary 可能共用边线、标题带过窄，视觉上难以分辨层级；自动连线也可能贴近并平行于 boundary。
2. 两个 facing ports 几乎同轴时，自动路由仍可能生成很短的折线（near-axis dogleg），形成没有语义价值的轻微扭折。

这会让 showcase 级架构图需要反复手工增大 pad 或微调坐标，而现有 validator 仍可能返回通过。Issue 中提供了脱敏的最小 JSON、命令、环境和验证回执。

Scope

• What changed:
  • Architecture boundary 自动保留标题带。
  • 根据严格的 wraps 子集关系推断最近父 boundary，并为嵌套 boundary 保留间距。
  • 分离部分重叠 boundary 的重合边，并让自动 boundary 边线避开附近的平行自动连线。
  • 在 showcase 下新增结构化诊断 composition/near-axis-dogleg，提示作者对齐组件中心或重新分配真实端口。
  • 增加 renderer/CLI 回归测试，并同步 authoring contract、示例、Gallery、README proof 和发布包。
• What deliberately did not change:
  • 不改 schema，不重写用户输入 JSON，不修改节点/连接拓扑。
  • 不自动改写作者明确设置的 via、channelX、channelY、labelAt 或非 auto route。
  • 不改变 standard profile 对 near-axis dogleg 的兼容行为。
  • 不定义 2.15 或其他发布版本；版本号和发布节奏由维护者判断。
• No unrelated changes: 已确认；diff 仅覆盖本 Issue 的 renderer、validator、contract、回归测试及其要求的生成物/对比证据。

Stability impact

• Compatibility and migration risk:
  • schema 与 typed JSON 格式不变，无迁移步骤。
  • showcase 对 near-axis dogleg 新增一个失败诊断；standard 不受影响。
  • boundary 的最终 SVG 几何会获得更明确的标题带和间距，这是本 Issue 预期的可见变化。
  • 显式路由继续使用旧 boundary 几何进行 border-run 校验，避免因自动扩边改变既有显式路由的校验结论。
• Renderer, validator, package, or generated-artifact risk:
  • 风险集中在 Architecture boundary 几何和 showcase composition validation。
  • 新增测试覆盖标题带、嵌套 containment、平行 route clearance、重合边分离、near-axis 阈值、显式 routing 豁免及 CLI 结构化诊断。
• Failure behavior and rollback path:
  • validator 以稳定 code、subject、evidence、supportedFixes 返回可操作错误，不静默改写拓扑或端口。
  • 如维护者认为阈值或自动扩边策略不合适，可整体回退提交 4ac857b9a3ef30a4db5724cbefa93376ddc71f12；无数据或 schema 回滚成本。

Tests run

• node --test archify/test/architecture-boundary-layout.test.mjs archify/test/near-axis-dogleg.test.mjs archify/test/layout-rules.test.mjs
  • 结果：78 tests，78 pass，0 fail。
• cd archify && npm test
  • 结果：release identity 2.14.0；golden/schema/template/version checks 全部通过；634 tests，634 pass，0 fail。
• ./scripts/build-zip.sh archify.zip
  • 结果：成功生成 archify.zip，78 files。
• git diff --check
  • 结果：通过，无 whitespace error。

Visual evidence

对比使用同一份公开示例 JSON，输入字节未改动；SHA-256：b39f35841008e538167b3f8a5e8c343486570c90d4f82f1215b517af6881293b。

Before（upstream main / 2.14.0）：嵌套框顶部边线和标题区域贴合，层级边界不够清楚。

After（本 PR candidate）：输入 JSON 不变，父子 boundary 的标题带和边线获得可辨识间距。

• visual-check containment：1440×900、1600×1000、1920×1080、2048×1320 均通过，无横向或纵向 overflow。
• light/dark endpoint captures：全部通过。
• 人工视觉复核：passed。

Generated artifacts

• examples/web-app-rendered.html
• archify/examples/web-app-rendered.html
• docs/gallery.html
• docs/gallery/artifacts/production-deployment.architecture.html
• docs/gallery/artifacts/web-app.architecture.html
• docs/gallery/manifest.json
• docs/assets/archify-live-proof.gif
• docs/assets/archify-live-proof.json
• archify.zip
• docs/assets/issue-74-boundary-before.png
• docs/assets/issue-74-boundary-after.png

Checklist

• I used a minimal focused change and preserved existing typed JSON behavior unless the issue requires a contract change.
• I ran the relevant targeted tests and npm test in archify/.
• I added or updated a regression test for behavioral changes.
• I checked generated artifacts and package freshness when their sources changed.
• I removed secrets, private repository content, and customer data from fixtures and screenshots.

Closes #74

[tt-a1i]

感谢修复 #74，边界标题留白、嵌套边界间距和重合边缘分离这几个方向都挺有价值。不过 near-axis-dogleg 这里现在会有误报，建议合并前再处理一下。

目前 collectNearAxisDoglegs 只根据两端是否错开不足 24px、路径是否存在折点来判断，没有确认直线路径是否真的可用。我本地复现的结构是：API 位于 [500, 340]、Database 位于 [510, 100]，中间放一个位于 [520, 180]、尺寸为 [40, 50] 的组件。自动路由为了绕开中间组件生成了合法折线，其他 Clean Flow 校验均通过，但 Showcase 最终仍只报 composition/near-axis-dogleg，并建议改成直线；这样修改反而会穿过障碍物。

建议只有在直线或直接对齐后的路径确认不会穿过任何非端点组件时，才报告 near-axis-dogleg；同时增加一个“近轴但中间存在障碍物，自动绕行不应报错”的回归测试。

另外这个 PR 目前基于较早的 main，已经存在合并冲突，建议先更新到最新主分支后再跑一次完整测试。除现有单测外，也建议实际让 DeepSeek V4 Flash、GPT-5.6 Luna 这类较小模型分别生成几张复杂架构图做回归。这个规则最终是给模型生成结果兜底的，小模型更容易暴露误报、修复提示无法执行，以及边界自动扩张后语义不准确等问题。

[tt-a1i]

感谢你处理 #74。我们结合最新的 main 又完整评估了一遍这个 PR。

边界构图这部分目前已经被 #96 的新实现覆盖了，包括标题可读性、嵌套标题轨道、遮罩碰撞和桌面投影检查。两套实现都改了 Architecture renderer，继续在当前分支上 rebase，实际上需要重写大部分代码和生成物，直接叠加的风险比较大。

near-axis-dogleg 这个方向还有价值，但现在作为 showcase 的硬错误仍然会误伤合法路线。除了之前提到的障碍物绕行，我又用最新主分支的 checkout-platform.head.architecture.json 做了回归：它目前可以通过 showcase，queue -> worker 是一条清晰的 2-bend 路线，最短内部线段为 20px；加入这里的规则后，会因为两端相差 20px 被直接判为失败。这说明当前判断范围比原 Issue 中的“4 段无意义折线”更宽。

因此不建议继续在这个 PR 上修改。后续如果你还愿意推进 near-axis，可以从最新 main 新开一个更小的 PR，只处理这一条规则：确认直接对齐后的路径确实没有障碍，区分端口分流和显式 sides，并避免把正常的 2-bend 路线判死。测试里最好同时保留障碍物、共享端口、现有 checkout 示例和旧输入兼容性。

感谢你这次提供的实现和测试，它帮助我们把这个问题的边界看清楚了。

[YunyueLi]

感谢你在 #74 上投入的实现和验证工作。我们基于当前最新的 main 再次评估后，结论是：不建议继续在这个 Draft PR 上 rebase 或追加修改，也不建议按当前形态合并。

主要原因有两点：

1. 这个 PR 中关于边界标题、嵌套边界间距、遮罩和桌面可读性的主要改动，已经由 fix(renderers): keep automatic routes clear and boundary composition readable #96 在主分支中以另一套实现完成。当前分支与 main 存在冲突，继续合并两套 Architecture renderer 改动会产生较高的回归风险，也需要重做大部分生成物。

2. near-axis-dogleg 的思路仍然有价值，但当前判定范围过宽，会把必要的绕障路线和正常的两折线路线判为错误。它不仅会误伤“中间有组件、必须绕行”的场景，也会使当前主分支中已经通过 Showcase 的 checkout-platform.head.architecture.json 失败。因此，这条规则目前还不适合作为 Showcase 的硬性门槛。

建议将当前 PR 作为探索记录保留或关闭；如果你愿意继续推进，请从最新 main 新建一个范围更小的 PR，只处理 near-axis 路线识别，不再携带已被 #96 覆盖的边界构图实现和旧生成物。

后续 PR 建议满足以下验收条件：

• 只有在直接对齐后的路线确实可用、且不会穿过任何非端点组件或边界时，才报告 near-axis 问题；
• 不误判为绕开障碍物而产生的合法折线；
• 区分共享端口、自动端口分流、显式 sides 和用户编写的 via；
• 保证现有 checkout 示例、现有 Showcase 图和 schema-v1 旧输入继续通过；
• 同时提供正向案例与反向案例，包括障碍物、共享端口、正常两折线和确实可以简化的冗余路线；
• 先提交规则和测试，待实现稳定后再统一更新必要的生成物。

这次实现帮助我们明确了原问题的边界，相关工作是有价值的。后续如果按上述范围提交一个干净的小 PR，我们会继续审核。