Sansheng-Intelligence/README.md

# 三笙AI情报局独立版

三笙AI情报局是面向家纺、服装和跨境电商经营者的静态情报站参考实现。本仓库从 `AI-News-Radar` 主项目中独立出来，供公司 C# 后端研发、前端研发、测试和运维人员理解现有业务，再重构为长期稳定版本。

> 先明确边界：仓库名称中包含“AI”，但当前版本 **没有调用任何 LLM、多模态理解模型或生图模型**。没有 Qwen、Gemini、OpenAI 等模型请求，没有提示词模板，也没有“先让文本模型理解用户输入，再调用生图模型”的两阶段链路。现有智能能力来自一手信源抓取、规则解析、结构化计算、去重排序、公共机器翻译和静态 SEO/GEO 生成。

## 当前基线

当前提交数据以 `data/*.json` 为准，业务基准日为 **2026-08-14**：

| 指标 | 当前值 |
|---|---:|
| 严格权威源 | 59/59 |
| 日历原始事件 / 聚合机会 | 1270 / 673 |
| 今日必看 | 23 |
| 展会 | 79 |
| 政策与召回 | 48 |
| 标准事实 | 4 |
| 跨境平台 | 28 |
| 跨境活动 | 48 |
| 趋势与灵感内容 | 206 |

这些数字是可回归的仓库快照，不是写死在页面里的宣传数字。每次数据更新后，应以 `textile-intelligence.json.summary`、`source_target/source_success` 和 `textile-trends.json.total_items` 重新核对。

## 五分钟理解系统

```mermaid
flowchart LR
  A[政府/平台/展会/博物馆等公开来源] --> B[Python 定时抓取]
  B --> C[证据词、状态码、语种和结构校验]
  C --> D[规则解析、规范化、聚合、去重和排序]
  D --> E[命中缓存或调用 Google 公共翻译接口]
  E --> F[生成两份公开 JSON]
  F --> G[生成首页、详情页、栏目页、Sitemap、JSON-LD、llms.txt]
  G --> H[原子替换 dist]
  H --> I[IIS/Nginx/对象存储/CDN 只提供静态文件]
```

生产访问端不需要 Python、Node、数据库、模型服务或 GitHub Pages。Python 只运行在更新节点；最终仅发布 `dist/`。

## 核心功能

| 功能 | 用户看到的结果 | 当前实现 |
|---|---|---|
| 今日必看 | 混合展示备货、展会、政策、活动和趋势任务 | 规则评分、截止日期、经营相关度和风险排序 |
| 备货日历 | 节日、国家、备货窗口、产品建议、平台动作 | 多来源日历规范化后按日期、名称和地区聚合 |
| 展会通 | 展期、城市、主办方、官方报名和译文入口 | 固定官方源与动态目录合并，优先保留官方报名页 |
| 政策预警 | 关税、召回、标签、知识产权和平台规则 | 权威来源证据校验，事实与经营建议分区 |
| 跨境活动 | 线上/线下活动、倒计时、报名入口和筛选 | 官方活动优先，行业媒体只承担发现作用 |
| 平台渠道 | 市场、品类、卖家准入和官方入驻入口 | 静态核验目录与信源状态组合 |
| 趋势雷达 | 趋势文章、灵感图库、时装趋势和原图查看 | RSS/HTML/博物馆公开 API，URL 与标题规则去重 |
| SEO/GEO | 可直接索引的中文正文和稳定实体页面 | 静态 HTML、canonical、JSON-LD、Sitemap、robots、llms.txt |

## AI、模型与渠道清单

### 当前没有的模型链路

| 能力 | 当前状态 | 说明 |
|---|---|---|
| LLM 文本理解 | 未接入 | 不调用 Qwen、Gemini、OpenAI 或其他大语言模型 |
| 多模态图片理解 | 未接入 | 不把用户图片或源站图片发送给视觉模型 |
| 文生图/图生图 | 未接入 | 灵感图库图片来自公开博物馆或来源站；活动无图时使用 CSS 文字海报 |
| 提示词拼接 | 不存在 | 没有 system/user prompt、提示词变量或模型输出 JSON |
| 用户内容实时模型审核 | 不存在 | 当前站点没有用户投稿、聊天或生图输入 |

因此，C# 重构时不要创建“模型编排服务”、提示词数据库或生图任务队列来复刻当前功能。以后若产品明确加入模型能力，应作为独立版本设计，不能把未来方案写成当前依赖。

### 当前唯一的机器翻译请求

构建节点会对部分外文标题和摘要执行一次普通 HTTP 翻译请求。它不是 LLM，也不是生图模型：

```text
GET https://translate.googleapis.com/translate_a/single
client=gtx
sl=auto
tl=zh-CN
dt=t
q={规范化后的原文标题或摘要}
```

变量只有 `q`；`sl` 固定为自动识别，`tl` 固定为简体中文。返回数组中每个翻译片段的首字段会按顺序拼接为中文。调用前先以完整原文字符串查询 `data/textile-zh-cache.json`，命中则不请求；未命中才请求，并限制每次任务的新翻译数量：

| 内容 | 单次最多新增翻译 |
|---|---:|
| 趋势标题与摘要 | 250 |
| 日历标题 | 260 |
| 展会标题与摘要 | 200 |
| 政策标题/摘要 | 72 |
| 活动标题 | 72 |

请求失败时保留缓存中的上一版中文或官方原文，不会把线上字段清空。该 `client=gtx` 公共端点没有项目 API Key 和商业 SLA；稳定版若要求服务等级、配额和合规审计，应由公司统一替换为正式采购的翻译服务，但必须保持“缓存优先、失败保留上一版、官方原文可访问”的语义。

### 网页译文入口

网页翻译按钮只生成跳转 URL，不抓取也不保存整页译文：

```text
Google: https://translate.google.com/translate?sl=auto&tl=zh-CN&u={URL 编码后的官网地址}
Yandex: https://translate.yandex.com/translate?url={URL 编码后的官网地址}&lang={源语种}-zh
```

处理规则：

- 简体中文正文、`.cn` 域名、`bizevent.ccpit.org` 等已知中文页面不显示译文按钮。
- 中国大陆 IP 默认使用 Yandex；明确的非中国 IP 默认使用 Google，并以另一渠道为备用。
- IP 依次通过 Cloudflare trace、`country.is`、`ipwho.is` 判断；全部失败后再参考浏览器语种和时区。
- `cpsc.gov`、`zatca.gov.sa` 等已验证不支持 Google 网页代理的域名只提供 Yandex。
- `abai.kgd.gov.kz` 已验证两边都不可用，只保留本站中文摘要和官方原文。
- 官方来源/报名按钮始终优先于译文按钮；报名、付款、验证码和资料提交必须回官方域名。

## 数据请求与处理流程

### 1. 输入

系统输入不是用户提示词，而是以下公开数据：

- 政府、海关、监管机构和标准组织的 HTML、JSON、RSS。
- 平台、展会和主办方官网的页面与公开接口。
- Met、V&A 等博物馆的公开藏品信息和图片地址。
- 已人工登记的信源元数据：ID、栏目、地区、URL、证据词、中文说明和经营动作。

### 2. 抓取前处理

- 固定浏览器 User-Agent、语言头、连接/读取超时和有限重试。
- 规范化 URL、文本空白、日期、地区、平台和节日名称。
- 对已知证书兼容问题只在指定域名使用兼容适配器，禁止全局关闭 TLS 校验。
- 动态 API Key 只从目标官网公开前端配置中提取并立即用于同站请求，不在仓库保存密钥。

### 3. 抓取后校验

- 同时检查 HTTP 状态、内容类型、最终 URL、正文长度和登记的证据词；HTTP 200 不等于成功。
- 为响应正文计算内容指纹，记录 `verified_at`、`content_hash` 和变更状态。
- 严格源任一失败时，`--strict` 更新直接退出，正式 JSON 和 `dist/` 不被半成品覆盖。
- 活动发现源必须回到主办方或平台官方报名页；行业媒体页不能冒充官方来源。

### 4. 结构化、去重和排序

- 日历：规范化节日名、日期和地区后聚合；当地名称折叠为辅助信息。
- 展会：规范化展名、开始日和城市；官方固定源覆盖动态目录的弱字段。
- 活动：以真实报名 URL、标题、日期和地区去重；中文站不生成翻译入口。
- 趋势：先按 URL 去重，再按稳定 ID、标题和来源处理；V&A 泛化标题会加入藏品编号，避免多个 `Hanging/Pattern` 被误认为相同内容。
- 今日必看：从各栏目混合选取可行动事项，按截止日期、经营相关性、影响和风险排序。

### 5. 发布

`scripts/update_all.py` 在 `runtime/update-*` 临时目录完成抓取、翻译、JSON 校验和站点预构建。只有全部成功后才替换正式数据，并把旧四份 JSON 压缩到 `runtime/snapshots/`。快照最多 14 份、总计不超过 120 MiB。

`scripts/build_site.py` 仅把以下运行数据复制到公开目录：

- `dist/data/textile-intelligence.json`
- `dist/data/textile-trends.json`

翻译缓存、源状态、日志和快照不会进入 `dist/`。

## 审核、预处理和后处理边界

当前没有用户生成内容，所以没有实时内容安全审核接口。现有“审核”是数据质量审核，不是模型审核：

- 信源必须预登记并通过证据词和权威层级验证。
- 页面语种、日期、URL、地区和栏目在进入正式 JSON 前规范化。
- 付费墙、失效站点、二次转载和无来源图片按规则排除。
- 机器翻译、官方事实和本站经营建议分别标注，不能混写成官方结论。
- 前端不自行补造事实；缺字段时隐藏对应控件，不显示伪数据或占位按钮。

未来若加入搜索框自由文本、用户评论、文件上传或模型生图，才需要在 API 边界增加长度、格式、恶意 URL、版权、隐私和内容安全审核。该能力不属于当前版本。

## 前端必须保留的职责

即使后端改写为 C#，以下工作仍必须由前端完成：

- 七个业务入口、趋势子分类、搜索和地区/平台/参与方式筛选。
- IP 结果返回后选择 Google/Yandex 译文按钮；检测完成前不展示错误渠道。
- 官方来源和官方报名链接在译文入口左侧，所有外链新窗口打开并隔离 opener。
- 日历倒计时、活动状态、移动端单列布局和触控尺寸。
- 灵感图库原图浮层、三笙 Logo 加载动画、关闭/下载/键盘操作。
- 主题切换、分享、折叠的更新时间与源状态详情。
- 只消费公开 JSON；不得请求 `textile-zh-cache.json` 或源状态文件。

事实聚合、内容指纹、去重、业务评分和翻译缓存应留在更新服务或后端，不能散落到 UI 组件里。

## 目录与入口

```text
public/     独立 HTML、CSS、ES Modules、本地字体、Logo 和平台图标
data/       正式 JSON、源状态与中文翻译缓存
scripts/    抓取、翻译、聚合、去重、SEO 和原子发布
docs/       数据契约、信源、流水线、C# 交接、SEO/GEO 和运维说明
runtime/    计划任务、临时目录和本地快照；不参与公开发布
dist/       可直接部署的静态产物；构建生成，不提交版本库
tests/      Python 数据契约测试与 Node 前端契约测试
```

主要入口：

| 文件 | 职责 |
|---|---|
| `scripts/update_all.py` | 完整更新事务和原子发布入口 |
| `scripts/update_textile_intelligence.py` | 日历、展会、政策、平台、活动、今日必看主聚合 |
| `scripts/update_textile_trends.py` | 趋势文章、图库和时装趋势抓取 |
| `scripts/intelligence_sources.py` | 严格权威源注册表 |
| `scripts/intelligence_web_translation.py` | 页面语种和 Google/Yandex 链接策略 |
| `scripts/build_site.py` | 复制公开资产和数据、调用 SEO 构建、替换 `dist/` |
| `scripts/build_seo.py` | 栏目页、详情页、年份页和结构化数据 |
| `public/assets/js/render-intelligence-core.js` | 情报站核心 UI、筛选和翻译按钮 |

## 本地运行

Windows 11 可直接双击：

1. `start.bat`：缺少 `dist/` 时先构建，再自动寻找从 `8765` 开始的空闲端口。
2. `update.bat`：首次创建 `.venv`，从清华 PyPI 镜像安装依赖，严格更新并构建。
3. `install-schedule.bat`：安装每天 09:30 的 Windows 计划任务。

命令行：

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt
.\.venv\Scripts\python.exe scripts\update_all.py
.\.venv\Scripts\python.exe scripts\serve.py
```

只基于仓库快照构建，不联网更新数据：

```powershell
$env:SANSHENG_SITE_URL='https://intel.example.com'
.\.venv\Scripts\python.exe scripts\build_site.py --site-url $env:SANSHENG_SITE_URL
```

## C# 稳定版重构建议

最低风险的迁移顺序：

1. 冻结 `docs/DATA-CONTRACT.md` 描述的 JSON v2，C# 先读取当前两份公开 JSON。
2. 用 Worker Service 或独立计划任务承载采集，禁止在 ASP.NET Web 请求中同步抓取 59 个源。
3. 使用 `HttpClient`、`System.Text.Json` 和正式 HTML 解析器逐个迁移稳定源；每迁移一个源，与 Python 对同一 URL 双跑比对。
4. 将 `Source`、`FetchRun`、`IntelligenceItem`、`ItemSource`、`UserPreference`、`UserTask` 分表保存；自动事实与人工结论分离。
5. API 稳定后再迁移前端；服务端渲染静态正文，客户端仅增强筛选、收藏、任务和翻译渠道选择。
6. 最后切换正式域名 canonical，并为旧 URL 建立 301 映射。

C# 实现必须保留以下语义：稳定 ID、UTC `generated_at`、业务 `as_of_date`、内容指纹、源证据、严格失败不发布、缓存翻译失败不清空、官方事实/机器翻译/经营分析分区、原子发布和可回滚快照。

不要一次性重写全部抓取器，也不要先引入 LLM。先让 C# 后端稳定消费现有 JSON，再按源逐步替换，最容易定位数据差异和回滚。

## 不依赖 GitHub Pages 的自动部署

公司 Gitea 没有 Pages 不影响部署。推荐由 Gitea Runner、Windows 计划任务或公司 CI 执行：

```text
检出仓库
  -> 创建 Python 虚拟环境并安装 requirements.txt
  -> 运行 Python 与 Node 契约测试
  -> 设置唯一 SANSHENG_SITE_URL
  -> 运行 update_all.py（需要联网更新）或 build_site.py（只发布已提交快照）
  -> 把 dist/ 作为构建制品
  -> 同步到 IIS/Nginx 新版本目录
  -> 健康检查通过后切换目录/发布槽
```

Web 节点只接收 `dist/`。不要把仓库、`.venv`、`data/textile-zh-cache.json`、`data/textile-intelligence-source-status.json`、`runtime/` 或抓取日志放进网站目录。IIS/Nginx 必须优先返回真实静态文件，不能让 `/data/*.json` 被 SPA fallback 替换成首页 HTML。

仓库没有预置绑定具体服务器账号的 Gitea workflow，因为 Runner 标签、发布协议、IIS 路径和密钥名尚未确定。确定这些公司环境参数后，只需把上面的命令接入现有流水线，不需要 Pages。

## SEO/GEO 基线

- 品牌实体统一为“三笙AI情报局”，简称“三笙AI”；“家纺AI”是能力词，不替代品牌。
- 核心主题覆盖家纺AI、三笙AI、家纺情报、跨境家纺平台、家纺跨境平台。
- `SANSHENG_SITE_URL` 是 canonical、Open Graph、Sitemap 和 `llms.txt` 的唯一域名来源。
- 独立版不覆盖 `https://www.sanshengai.net/` 根目录，未确定正式域名前不要修改线上 canonical。
- 每条静态详情包含可直接索引的中文正文，不要求搜索引擎执行 JavaScript。
- 页面区分官方事实、机器翻译和本站经营建议，结构化数据不把分析冒充官方原文。

## 测试与发布门槛

```powershell
python -m unittest discover -s tests -p 'test_*.py'
node tests\test_frontend.mjs
python scripts\build_site.py --site-url http://127.0.0.1:8765
```

发布前至少确认：

- Python 与 Node 契约测试全部通过。
- `source_target == source_success`，核心栏目非空。
- `dist/index.html`、`robots.txt`、`sitemap.xml`、`llms.txt` 和两份公开 JSON 存在。
- 桌面、390px 和 375px 移动端无横向溢出，七个入口可发现。
- 中文站不出现译文按钮，已知 Google/Yandex 阻断域名选择正确。
- 随机抽查 canonical、JSON-LD、官方链接、报名链接、日期和图库原图。

## 提交与更新日志规范

每次影响代码、数据结构、业务规则、信源、部署或 UI 的提交，都必须先在 [CHANGELOG.md](CHANGELOG.md) 顶部增加日期条目，至少写明：

- 改了什么、为什么改、影响哪些目录或数据字段。
- 修复了什么可观察问题，是否有兼容性变化。
- 实际运行过的测试和构建命令。
- 回滚该提交后需要同步回滚的数据、缓存或静态目录。

提交信息正文应与日志条目一致，禁止只写“update”“fix”或“优化”。普通回滚使用 `git revert <commit>`，不要重写共享分支历史。

## 进一步文档

- [更新日志](CHANGELOG.md)
- [信源手册](docs/SOURCES.md)
- [数据契约](docs/DATA-CONTRACT.md)
- [更新流水线](docs/PIPELINE.md)
- [C# 后端与前端交接](docs/CSHARP-NODE-HANDOFF.md)
- [SEO/GEO 规范](docs/SEO-GEO.md)
- [运维手册](docs/OPERATIONS.md)