From 43ac6c5a613413f7ec2202a4bb707d9d3280d48d Mon Sep 17 00:00:00 2001
From: OpenAI Codex <codex@local>
Date: Tue, 31 Mar 2026 17:10:47 +0800
Subject: [PATCH] Add visible versioning to 20nm compare page

---
 AGENTS.md                                | 12 +++++++++
 STEP_RECORD.md                           |  4 +++
 src/pbf/navsea-compare-karatsu-20nm.html | 31 ++++++++++++++++++++----
 3 files changed, 42 insertions(+), 5 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index b83e0db..595e6ee 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -52,6 +52,9 @@ Rules:
 - do not create additional comparison pages unless explicitly requested
 - prefer improving the current 20nm compare page over replacing it
 - keep the click-pick inspection panel working on both left and right maps
+- every visible compare-page revision must bump a human-readable version string on the page itself
+- show that version near the reload button so visual review can confirm refresh state
+- use the same version string as a cache-busting base for style / tile reloads
 
 ## Working Rules
 
@@ -98,6 +101,15 @@ Key references:
 - [`NavSea_Delivery_Preflight_Audit_Spec.md`](/root/sourceserver/pbf/NavSea_Delivery_Preflight_Audit_Spec.md)
 - [`STEP_RECORD.md`](/root/sourceserver/pbf/STEP_RECORD.md)
 
+### 5. Make Visual Revisions Traceable
+
+When changing the primary compare page:
+
+- bump the compare page version string
+- display it near the reload button
+- redeploy the HTML to `/mnt/sda1/www/newpec/navsea-compare-karatsu-20nm.html`
+- if the visual change depends on style updates, redeploy the corresponding style JSON too
+
 ## Resume Checklist
 
 At the start of a session:
diff --git a/STEP_RECORD.md b/STEP_RECORD.md
index 03a1153..9f27e8b 100644
--- a/STEP_RECORD.md
+++ b/STEP_RECORD.md
@@ -44,6 +44,10 @@ Remote: `ssh://git@nas:2222/tei/pbf.git`
 - 不再新增新的 compare 页面
 - 后续视觉比较统一只看上面这一张固定页面
 - 对比页必须保持左右联动和点击拾取功能可用
+- 对比页每次可见修改都必须 bump 版本号，并显示在“重新加载”按钮附近
+- 当前固定对比页版本号：
+  - `20nm-r3-20260331-1637`
+- 这个版本号同时作为 style / tile reload 的 cache-busting 基准
 
 ## Detail PBF JP Field Inventory
 
diff --git a/src/pbf/navsea-compare-karatsu-20nm.html b/src/pbf/navsea-compare-karatsu-20nm.html
index 03b47c0..d47310a 100644
--- a/src/pbf/navsea-compare-karatsu-20nm.html
+++ b/src/pbf/navsea-compare-karatsu-20nm.html
@@ -68,6 +68,22 @@
       align-items: center;
     }
 
+    .version-chip {
+      display: inline-flex;
+      align-items: center;
+      min-height: 40px;
+      padding: 0 14px;
+      border-radius: 999px;
+      border: 1px solid rgba(23, 35, 43, 0.16);
+      background: rgba(250, 248, 242, 0.9);
+      color: var(--ink);
+      font-size: 12px;
+      font-weight: 700;
+      letter-spacing: 0.01em;
+      white-space: nowrap;
+      box-shadow: 0 10px 22px rgba(23, 35, 43, 0.08);
+    }
+
     button {
       height: 40px;
       padding: 0 14px;
@@ -240,6 +256,7 @@
       <div class="subtitle">左侧是原始版 <code>style.json</code>，右侧是当前交付线使用的 delivery 样式 + 唐津 20 海里 delivery PBF。两边联动同步，点击任一对象可查看属性，适合直接肉眼排差异。</div>
     </div>
     <div class="toolbar-actions">
+      <div id="version-chip" class="version-chip">版本: 加载中</div>
       <button id="reload-btn" type="button">重新加载</button>
       <button id="home-btn" type="button">回到唐津</button>
     </div>
@@ -288,6 +305,7 @@
 
   <script src="https://unpkg.com/maplibre-gl@4.7.1/dist/maplibre-gl.js"></script>
   <script>
+    const COMPARE_VERSION = "20nm-r3-20260331-1637";
     const ORIGINAL_STYLE_URL = "./style.json";
     const DELIVERY_STYLE_URL = "./domain/style.navsea-delivery-karatsu-10nm.json";
     const ORIGINAL_TILE_URL = "http://192.168.200.184/newpec/exported_auto/tile.mapple-on.jp__newpec-mvt-20260106__z___x___y_.pbf/tiles/{z}/{x}/{y}.pbf";
@@ -301,6 +319,7 @@
 
     const reloadBtn = document.getElementById("reload-btn");
     const homeBtn = document.getElementById("home-btn");
+    const versionChip = document.getElementById("version-chip");
     const statusEl = document.getElementById("status");
     const inspectHintEl = document.getElementById("inspect-hint");
     const inspectSideEl = document.getElementById("inspect-side");
@@ -314,7 +333,9 @@
     let originalMap;
     let deliveryMap;
     let syncLock = false;
-    let styleVersion = Date.now().toString();
+    let styleVersion = `${COMPARE_VERSION}-${Date.now()}`;
+
+    versionChip.textContent = `版本: ${COMPARE_VERSION}`;
 
     function setStatus(text) {
       statusEl.textContent = text;
@@ -415,10 +436,10 @@
     }
 
     async function loadMaps() {
-      styleVersion = Date.now().toString();
+      styleVersion = `${COMPARE_VERSION}-${Date.now()}`;
       reloadBtn.disabled = true;
       homeBtn.disabled = true;
-      setStatus("正在加载原始版和 delivery 版样式…");
+      setStatus(`正在加载原始版和 delivery 版样式… 当前版本 ${COMPARE_VERSION}`);
 
       try {
         const [originalStyleRaw, deliveryStyleRaw] = await Promise.all([
@@ -457,7 +478,7 @@
           function markLoaded() {
             loaded += 1;
             if (loaded >= 2) {
-              setStatus("双屏已加载，可直接拖动、缩放、点击对比。");
+              setStatus(`双屏已加载，可直接拖动、缩放、点击对比。当前版本 ${COMPARE_VERSION}`);
             }
           }
           originalMap.on("load", markLoaded);
@@ -475,7 +496,7 @@
             if (loaded >= 2) {
               originalMap.jumpTo(camera);
               deliveryMap.jumpTo(camera);
-              setStatus("双屏样式已重新加载。");
+              setStatus(`双屏样式已重新加载。当前版本 ${COMPARE_VERSION}`);
             }
           }
           originalMap.once("style.load", markLoaded);