fix: 校验独立站公开快照并补充自托管说明

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## 2026-08-17
 
+### 更新时间字段与自托管交接
+
+- 修正公开 JSON 快照把 `generated_at` 固定为 `2026-08-17T00:00:00Z` 的问题，恢复为真实 UTC 生成时刻；`as_of_date` 继续只表示北京时间业务日期。
+- 增加 `verify_public_snapshot.py` 发布后快照校验：若 IIS、Nginx、Pages 或 CDN 仍返回旧 `generated_at`，流水线明确失败，不把构建成功误当成线上部署成功。
+- 补充 Java/C# 脱离 GitHub Actions 与 Pages 的完整交接方案，覆盖公司 Git/Gitea、自托管 Runner、内地网络代理/VPN、Windows/IIS、Linux/Nginx、制品发布、原子切换和回滚。
+- 明确更新节点与 Web 节点分离，生产访问端只提供最终静态目录，不需要 Python、Node、数据库或模型服务。
+
 ### 日历数据规则与旧快照修复
 
 - 按当前 UTC 日期重建公开日历快照，过滤已结束事件并保留未来事件的可用排序。

README.md

@@ -309,3 +309,4 @@ python scripts\build_site.py --site-url http://127.0.0.1:8765
 - [C# 后端与前端交接](docs/CSHARP-NODE-HANDOFF.md)
 - [SEO/GEO 规范](docs/SEO-GEO.md)
 - [运维手册](docs/OPERATIONS.md)
+- [Java/C# 脱离 GitHub 与 Pages 的自托管方案](docs/SELF_HOSTING_JAVA_CSHARP.md)

data/textile-intelligence.json

@@ -1,6 +1,6 @@
 {
   "version": 2,
-  "generated_at": "2026-08-17T00:00:00Z",
+  "generated_at": "2026-08-17T12:30:21Z",
   "as_of_date": "2026-08-17",
   "horizon_date": "2028-12-31",
   "source_target": 59,

docs/SELF_HOSTING_JAVA_CSHARP.md

@@ -0,0 +1,196 @@
+# 脱离 GitHub 与 Pages 的 Java/C# 自托管方案
+
+本文是给公司 Java/C# 后端、运维和测试人员的交接说明。GitHub Actions 和 GitHub Pages 只是当前演示环境，不是系统运行时依赖。生产环境可以完全不使用 GitHub、Pages、Python 常驻进程、数据库或大模型服务。
+
+## 一、先区分两个节点
+
+不要让对外 Web 服务器负责抓取外网：
+
+```text
+更新节点（可访问外网）
+  -> 抓取官方源、解析、去重、翻译、校验
+  -> 生成 JSON、HTML、Sitemap、JSON-LD、robots.txt、llms.txt
+  -> 生成完整 dist/ 发布包
+  -> 原子推送到 Web 节点
+
+Web 节点（只提供静态文件）
+  -> IIS / Nginx / 对象存储 / CDN
+  -> 不运行 Python、Java、C#、Node、数据库或模型
+```
+
+更新节点可以是公司内网 Windows Server、Linux Server、公司 CI Runner 或一台具备外网出口的云主机。Web 节点即使完全不能访问外网也没有问题。
+
+## 二、时间字段不能混用
+
+- `generated_at`：本次 JSON 生成完成的 UTC 时刻，例如 `2026-08-17T12:30:21Z`。页面“更新时间”应展示它，并按访问者时区格式化。
+- `as_of_date`：业务判断日期，当前按 `Asia/Shanghai` 计算，例如 `2026-08-17`。它用于日历过滤、备货窗口和“今日必看”，不是精确更新时间。
+- `verified_at` / `checked_at`：单条来源最近一次核验时间。
+
+更新程序禁止把 `generated_at` 固定为当天 `00:00:00Z`，也不能用 `as_of_date` 代替它。生成失败时保留上一版完整 JSON，不能把时间改新但把内容留空。
+
+### GitHub Actions 成功不等于线上版本成功
+
+资源检查绿色只代表 `dist/` 可以构建，不代表 Cloudflare Pages、IIS 或 Nginx 已经切到这次制品。发布后必须核对公开 JSON 的 `generated_at`、`as_of_date` 和本次构建日志；本仓库提供 `scripts/verify_public_snapshot.py`，可在 Gitea Runner 或 Windows/Linux 更新节点复用。
+
+## 三、Java/C# 要复刻的最小流水线
+
+### 独立站实际命令
+
+```text
+python scripts/update_all.py --site-url https://intel.example.com
+```
+
+`update_all.py` 会先抓取、清洗、翻译并生成公开 JSON，再调用 `build_site.py` 生成静态 SEO 页面；稳定版可以用 Java `ScheduledExecutorService` 或 .NET `BackgroundService` 编排同样的阶段，但不要让 Web 服务器承担抓取任务。
+
+### 1. 抓取层
+
+- Java：`java.net.http.HttpClient`、OkHttp 或公司统一 HTTP 客户端。
+- C#：`HttpClientFactory` + `HttpClient`。
+- 每个源独立超时、有限重试、User-Agent、响应大小上限和内容类型检查。
+- HTML 解析使用 Java Jsoup 或 C# AngleSharp；JSON 使用 Jackson 或 `System.Text.Json`。
+- 记录最终 URL、HTTP 状态、抓取时间、正文哈希、证据词和错误原因。
+
+### 2. 规范化与去重层
+
+必须保留以下字段语义：
+
+```text
+stable id
+source_id / source / authority
+url / source_url
+title / title_original / title_english
+source_language
+published_at / verified_at
+content_hash
+start_date / end_date / as_of_date
+needs_translation / translation_url / translation_fallback_url
+```
+
+日历至少按“规范化节日名 + 日期 + 国家/地区 + 来源类型”去重；跨天假期合并为一张卡，在 `related_dates` 或 `date_variants` 保存不同国家日期。不要用标题模糊相似度把不同国家的“独立日”“国庆日”强行合并。
+
+### 3. 翻译层
+
+当前项目没有 LLM、多模态理解、生图或提示词链路。翻译只是普通 HTTP 适配器：
+
+```text
+原文 -> 内容指纹缓存 -> Google 公共翻译（可用时）
+                     -> Yandex 网页翻译入口（Google 不可用时）
+                     -> 保留上一版中文或原文
+```
+
+中文官网、中文报名页、中文平台页不生成翻译按钮。CPSC、ZATCA 等 Google 不稳定域名可以保留 Yandex 回退；两边都不支持的域名隐藏按钮。翻译失败不得清空已验证的中文内容。
+
+### 4. 校验与发布层
+
+在替换正式目录前必须检查：
+
+- 权威源成功数等于目标数；核心栏目非空。
+- JSON 可解析、数据结构版本正确、`generated_at` 是合法 UTC ISO 8601。
+- 所有公开 URL 为 `http/https`，没有内部缓存、日志、代理凭据或抓取状态文件。
+- `sitemap.xml`、canonical、JSON-LD、robots.txt 和 `llms.txt` 与本次 `site_url` 一致。
+- 任何一个关键步骤失败，都不替换旧版 `dist/`。
+
+## 四、中国内地网络的三种部署方案
+
+### 方案 A：公司外网更新节点，内网 Web 节点
+
+更新节点放在具备合规外网出口的云主机或公司代理网络中。它运行定时任务，成功后把 `dist/` 和公开 JSON 作为制品上传到内网 Web 节点。Web 节点只需要访问内网制品仓库，不需要 VPN。
+
+适合：抓取源较多、公司有统一代理或云主机、希望 Web 服务器最稳定的情况。
+
+### 方案 B：公司 Gitea + Runner，不使用 Pages
+
+1. 代码放在公司 Gitea。
+2. 在有外网出口的 Windows/Linux 机器安装 Gitea Runner。
+3. Runner 执行更新、测试、构建和制品上传。
+4. IIS/Nginx 服务器只接收成功的 `dist/` 压缩包并原子解压切换。
+
+Gitea 只负责代码和流水线，不要求启用 Pages。Runner 可以部署在外网可访问区，Web 服务器部署在内网。
+
+### 方案 C：公司 GitHub 账号 + 自托管 Runner
+
+可以使用公司 GitHub 账号保存代码，但不要依赖 Pages。自托管 Runner 在具备外网访问能力的服务器上执行：
+
+```text
+git checkout
+更新数据
+运行测试
+构建 dist/
+上传制品
+部署到 IIS/Nginx
+```
+
+GitHub 只作为 Git 和 CI 控制面；真正的静态文件部署到公司服务器、对象存储或 CDN。
+
+## 五、没有 VPN 时怎么办
+
+不要把“所有服务器必须安装 VPN”当成唯一方案，按网络边界选择：
+
+- **HTTPS 代理**：为更新节点配置 `HTTP_PROXY/HTTPS_PROXY`，代理凭据放在系统密钥库或 CI Secret，不写入仓库。
+- **统一出口网关**：由网络团队提供固定出口、域名白名单和审计日志，应用只访问允许的官方域名。
+- **远程更新 Worker**：在可访问外网的云主机执行抓取，向内网制品仓库上传构建包；内网服务器只下载制品。
+- **分源策略**：国内可直连源由内网更新；境外源交给外网 Worker；两边通过 JSON 制品合并。
+- **人工制品交接**：极端情况下由外网机器生成带 SHA-256 的 `dist.zip`，通过公司文件系统或制品库转入内网，部署端验证哈希后发布。
+
+抓取节点无法访问某个源时，应保留上一版条目并记录源失败；不能因为单个国外站点不可达而清空整站数据。
+
+## 六、Windows Server 部署
+
+### 更新任务
+
+- 使用 Windows Task Scheduler 或 Windows Service/Worker Service，每日固定时间运行 `update_all`。
+- 工作目录使用独立服务账号；代理、翻译和 Git 凭据使用系统环境变量或凭据管理器。
+- 更新过程先写 `runtime/update-*` 临时目录，成功构建后再替换正式目录。
+
+### IIS 静态发布
+
+推荐目录结构：
+
+```text
+D:\sites\sansheng\releases\20260817-123021\dist\
+D:\sites\sansheng\current -> 当前发布目录
+```
+
+部署步骤：解压到新版本目录、验证 `index.html/data/*.json/sitemap.xml`、切换 IIS 站点物理路径或目录联接、保留最近 3-5 个版本。不要在 IIS 正在读取时直接覆盖正在服务的 `dist/`。
+
+## 七、Linux Server 部署
+
+- 使用 `systemd timer`、容器 CronJob 或公司 CI 调度更新节点。
+- Web 节点使用 Nginx，静态根目录指向版本目录；通过软链接原子切换 `current`。
+- 用 `rsync --delete` 或制品仓库同步完整目录，不要只复制部分 JSON。
+- 发布后执行 HTTP 冒烟检查：首页、JSON、Sitemap、robots、一个详情页和一个图片资源。
+- 保留最近 3-5 个版本目录，回滚只需把软链接切回上一版本并 reload Nginx。
+
+## 八、Git 与无 Git 运行方式
+
+生产更新不要求服务器执行 `git pull`。推荐顺序：
+
+1. GitHub/Gitea/公司 Git 只保存源代码。
+2. Runner 或更新服务构建不可变制品 `dist-YYYYMMDD-HHMMSS.zip`。
+3. 制品库保存 SHA-256、构建日志和版本号。
+4. Web 节点只接收已验证制品。
+
+如果公司不允许生产服务器连接 Git，使用制品上传即可；如果公司需要审计，保留提交 SHA、数据 `generated_at`、构建日志和部署人。
+
+## 九、回滚与故障处理
+
+- 抓取失败：保留上一版 JSON 和 HTML，标记源失败，不发布半成品。
+- 翻译服务失败：保留上一版中文，仍提供官方原文链接。
+- 构建失败：不切换 `current`，继续服务上一版。
+- 发布后发现问题：切回上一版本目录，随后用固定快照重建。
+- 代码回滚必须连同公开 JSON、翻译缓存契约和前端构建结果一起回滚，避免字段版本不匹配。
+
+## 十、交接验收
+
+Java/C# 重构完成后至少通过：
+
+```text
+同一份输入快照 -> 输出 JSON 字段和数量稳定
+相同内容指纹 -> 不重复翻译
+单源失败 -> 旧内容保留
+构建失败 -> dist 不替换
+Windows/Linux -> 可定时运行、可查看日志、可回滚
+无 VPN Web 节点 -> 仍能提供完整静态站
+generated_at -> 精确 UTC 时刻，不是当天 00:00 的占位值
+as_of_date -> 按 Asia/Shanghai 的业务日期计算
+```

public/assets/js/app.js

@@ -1,4 +1,4 @@
-import { getIntelligenceSection, renderIntelligence, setIntelligenceSection, shareIntelligence } from "./render-intelligence.js?v=20260815a";
+import { getIntelligenceSection, renderIntelligence, setIntelligenceSection, shareIntelligence } from "./render-intelligence.js?v=20260817a";
 
 const DATA_ROOT = "./data";
 

public/assets/js/render-intelligence-core.js

@@ -309,7 +309,16 @@ function formatDate(item) {
 function formatVerified(value) {
   const raw = String(value || "");
   if (!raw) return "";
-  return raw.slice(0, 16).replace("T", " ");
+  const parsed = new Date(raw);
+  if (Number.isNaN(parsed.getTime())) return raw.slice(0, 16).replace("T", " ");
+  const parts = new Intl.DateTimeFormat(undefined, {
+    year: "numeric", month: "2-digit", day: "2-digit",
+    hour: "2-digit", minute: "2-digit", hour12: false, hourCycle: "h23",
+  }).formatToParts(parsed).reduce((result, part) => {
+    result[part.type] = part.value;
+    return result;
+  }, {});
+  return `${parts.year}-${parts.month}-${parts.day} ${parts.hour}:${parts.minute}`;
 }
 
 function sectionOf(item) {

public/assets/js/render-intelligence-platforms.js

@@ -1,5 +1,5 @@
 import { state } from "./render-intelligence-state.js?v=20260814e";
-import { create, normalized, matchesFilters, makeBadge, makeExternalLink, makePlatformActionGroup, appendTags, compactList } from "./render-intelligence-core.js?v=20260815a";
+import { create, normalized, matchesFilters, makeBadge, makeExternalLink, makePlatformActionGroup, appendTags, compactList } from "./render-intelligence-core.js?v=20260817a";
 
 function makePlatformCard(item) {
   const card = create("article", "platform-card");

public/assets/js/render-intelligence-scenes.js

@@ -1,5 +1,5 @@
 import { state } from "./render-intelligence-state.js?v=20260814e";
-import { TEXT, create, openLightbox, normalized, matchesFilters, makeVisual, makeBadge, makeExternalLink, sourceLinkLabel, currentTranslationProvider, appendTranslationLinks, appendTags, formatDate, formatVerified, makeShareButton } from "./render-intelligence-core.js?v=20260815a";
+import { TEXT, create, openLightbox, normalized, matchesFilters, makeVisual, makeBadge, makeExternalLink, sourceLinkLabel, currentTranslationProvider, appendTranslationLinks, appendTags, formatDate, formatVerified, makeShareButton } from "./render-intelligence-core.js?v=20260817a";
 
 function makeExhibitionCard(item) {
   const article = create("article", "exhibition-card");

public/assets/js/render-intelligence.js

@@ -1,8 +1,8 @@
 import { state } from "./render-intelligence-state.js?v=20260814e";
-import { TEXT, create, detectViewerCountry, currentTranslationProvider, formatVerified, sectionItems, matchesFilters, makeCard, renderCalendar } from "./render-intelligence-core.js?v=20260815a";
+import { TEXT, create, detectViewerCountry, currentTranslationProvider, formatVerified, sectionItems, matchesFilters, makeCard, renderCalendar } from "./render-intelligence-core.js?v=20260817a";
 import { renderExhibitions, renderPolicies, renderStandards, renderTrendNews, renderTrendSearchHub, trendItems } from "./render-intelligence-scenes.js?v=20260814i";
 import { renderActivities } from "./render-intelligence-activities.js?v=20260814h";
-import { renderPlatforms } from "./render-intelligence-platforms.js?v=20260815a";
+import { renderPlatforms } from "./render-intelligence-platforms.js?v=20260817a";
 
 function renderStats(data, container) {
   if (!container) return;

public/index.html

@@ -25,7 +25,7 @@
   <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Noto+Sans+SC:wght@400;500;600;700&family=Noto+Serif+SC:wght@400;700&display=swap" rel="stylesheet" />
   <link href="./assets/fonts/dongguan-bold/result.css?v=20260814a" rel="stylesheet" />
   <link rel="stylesheet" href="./assets/css/base.css?v=20260814h" />
-  <link rel="stylesheet" href="./assets/css/intelligence.css?v=20260815a" />
+  <link rel="stylesheet" href="./assets/css/intelligence.css?v=20260817a" />
   <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"WebSite","name":"三笙AI情报局","inLanguage":"zh-CN","description":"面向家纺跨境经营团队的备货、展会、政策、平台、活动与趋势情报站"},{"@type":"Organization","name":"三笙AI情报局","alternateName":["三笙AI","家纺AI"],"url":"./"}]}</script>
 </head>
 <body>
@@ -78,6 +78,6 @@
   </main>
 
   <div id="toast" class="toast" role="status" aria-live="polite"></div>
-  <script type="module" src="./assets/js/app.js?v=20260815a"></script>
+  <script type="module" src="./assets/js/app.js?v=20260817a"></script>
 </body>
 </html>

scripts/verify_public_snapshot.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+"""确认公开静态站已经提供本次生成的情报快照。"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+from urllib.request import Request, urlopen
+
+
+def check_url(base_url: str, path: str, expected_file: Path, timeout: int = 20) -> tuple[str, str]:
+    expected = json.loads(expected_file.read_text(encoding="utf-8"))
+    expected_generated = str(expected.get("generated_at") or "")
+    expected_as_of = str(expected.get("as_of_date") or "")
+    if not expected_generated:
+        raise ValueError("本地快照缺少 generated_at")
+    parts = urlsplit(base_url.rstrip("/") + "/" + path.lstrip("/"))
+    query = dict(parse_qsl(parts.query, keep_blank_values=True))
+    query["deploy-check"] = datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S")
+    url = urlunsplit((parts.scheme, parts.netloc, parts.path, urlencode(query), ""))
+    request = Request(url, headers={
+        "Accept": "application/json",
+        "Cache-Control": "no-cache",
+        "User-Agent": "Sansheng-Intelligence-Deploy-Check/1.0",
+    })
+    with urlopen(request, timeout=timeout) as response:
+        remote = json.load(response)
+    remote_generated = str(remote.get("generated_at") or "")
+    remote_as_of = str(remote.get("as_of_date") or "")
+    if remote_generated != expected_generated or remote_as_of != expected_as_of:
+        raise RuntimeError(
+            f"公开快照仍不是本次版本：expected generated_at={expected_generated}, as_of_date={expected_as_of}; "
+            f"remote generated_at={remote_generated}, as_of_date={remote_as_of}"
+        )
+    return remote_generated, remote_as_of
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="校验公开静态站是否已切换到指定情报快照")
+    parser.add_argument("--base-url", required=True, help="公开站点根地址")
+    parser.add_argument("--expected-file", default="data/textile-intelligence.json", help="本地情报快照")
+    parser.add_argument("--path", default="/data/textile-intelligence.json", help="公开 JSON 路径")
+    parser.add_argument("--retries", type=int, default=12, help="失败后重试次数")
+    parser.add_argument("--interval", type=int, default=30, help="重试间隔秒数")
+    args = parser.parse_args()
+    expected_file = Path(args.expected_file)
+    for attempt in range(max(0, args.retries) + 1):
+        try:
+            generated, as_of = check_url(args.base_url, args.path, expected_file)
+            print(f"公开快照已生效：generated_at={generated} as_of_date={as_of}")
+            return 0
+        except (HTTPError, URLError, TimeoutError, ValueError, RuntimeError) as exc:
+            if attempt >= max(0, args.retries):
+                print(f"公开快照校验失败：{exc}", file=sys.stderr)
+                return 1
+            print(f"公开快照尚未切换（{attempt + 1}/{args.retries}）：{exc}")
+            time.sleep(max(1, args.interval))
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tests/test_frontend.mjs

@@ -10,9 +10,9 @@ test("独立首页只展示家纺情报并加载独立入口", async () => {
   const dongguanCss = await text("public/assets/fonts/dongguan-bold/result.css");
   assert.match(html, /三笙AI情报局/);
   assert.match(html, /assets\/js\/app\.js/);
-  assert.match(html, /assets\/js\/app\.js\?v=20260815a/);
+  assert.match(html, /assets\/js\/app\.js\?v=20260817a/);
   assert.match(html, /assets\/css\/base\.css\?v=20260814h/);
-  assert.match(html, /assets\/css\/intelligence\.css\?v=20260815a/);
+  assert.match(html, /assets\/css\/intelligence\.css\?v=20260817a/);
   assert.match(html, /<details[^>]+class="intelligence-metrics"/);
   assert.match(html, /<summary[^>]+class="intelligence-utility-row"/);
   assert.doesNotMatch(html, /id="intelligenceShareBtn"/);

tests/test_verify_public_snapshot.py

@@ -0,0 +1,31 @@
+import json
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+from scripts.verify_public_snapshot import check_url
+
+
+class VerifyPublicSnapshotTests(unittest.TestCase):
+    def test_public_snapshot_must_match_generated_at_and_as_of_date(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "textile-intelligence.json"
+            path.write_text(json.dumps({"generated_at": "2026-08-17T12:30:21Z", "as_of_date": "2026-08-17"}), encoding="utf-8")
+
+            class Response:
+                def __enter__(self):
+                    return self
+
+                def __exit__(self, *args):
+                    return False
+
+                def read(self):
+                    return b'{"generated_at":"2026-08-17T12:30:21Z","as_of_date":"2026-08-17"}'
+
+            with patch("scripts.verify_public_snapshot.urlopen", return_value=Response()):
+                self.assertEqual(check_url("https://example.test", "/data/textile-intelligence.json", path), ("2026-08-17T12:30:21Z", "2026-08-17"))
+
+
+if __name__ == "__main__":
+    unittest.main()