feat: 发布三笙AI情报局独立版公司研发基线
同步家纺情报 v2 数据、59 个严格权威源、趋势图库、移动端交互、Google/Yandex 翻译门控及静态 SEO/GEO 构建。 补充面向 C# 研发的 README，明确当前无 LLM、多模态与生图模型，记录翻译请求参数、缓存与失败策略、数据处理边界、前端职责和无 GitHub Pages 部署流程。 新增按日期倒序维护的 CHANGELOG，记录影响、验证与代码/数据/dist 回滚方法。 验证：11 个 Python 契约测试、13 个 Node 前端测试通过；静态构建生成 1096 个 Sitemap URL。
This commit is contained in:
Jack
@@ -0,0 +1,52 @@
|
||||
# C# 后端与 Node 前端交接
|
||||
|
||||
本仓库是可运行参考实现，不要求研发团队继续使用 Python 前端，也不要求用 C# 重写爬虫。推荐拆分边界如下。
|
||||
|
||||
## C# 后端
|
||||
|
||||
适合负责：用户、企业、角色权限、订阅市场、任务分派、提醒、收藏、人工复核、审计日志和 API。不要把抓取器放进 Web 请求生命周期；通过计划任务或消息队列运行采集作业。
|
||||
|
||||
建议最小实体：
|
||||
|
||||
- `Source`：来源、层级、语言、证据词、抓取策略、启停状态。
|
||||
- `FetchRun`：开始/结束、HTTP 状态、内容指纹、证据、错误。
|
||||
- `IntelligenceItem`：稳定 ID、栏目、事实字段、分析字段、适用地区、来源版本。
|
||||
- `ItemSource`：一条聚合情报与多个来源的多对多关系。
|
||||
- `UserPreference`：企业关注的国家、平台、品类和角色。
|
||||
- `UserTask`：负责人、截止日、提醒、已处理/不相关状态。
|
||||
|
||||
数据库推荐 PostgreSQL；本地单机试运行可用 SQLite。正文去重建立 `normalized_title + start_date + region` 唯一候选键，内容指纹建立普通索引，外部 URL 使用规范化哈希索引。原始 HTML 只在需要审计时对象存储短期保留，不塞入主表。
|
||||
|
||||
API 可直接映射现有 JSON：
|
||||
|
||||
```text
|
||||
GET /api/intelligence/summary
|
||||
GET /api/intelligence/items?section=&market=&platform=&from=&to=&cursor=
|
||||
GET /api/intelligence/items/{id}
|
||||
GET /api/platforms
|
||||
GET /api/sources/{id}/runs
|
||||
POST /api/tasks
|
||||
PATCH /api/tasks/{id}
|
||||
```
|
||||
|
||||
服务端必须再次校验翻译链接和外链协议，仅允许 `http/https`。用户偏好、任务和人工结论与自动抓取事实分表，避免下一轮增量更新覆盖人工数据。
|
||||
|
||||
## Node 前端
|
||||
|
||||
可以迁移到 Next.js 或 React，但不必重写信息架构。保留七个业务入口和趋势四个子类，默认趋势页进入灵感图库。推荐：
|
||||
|
||||
- TypeScript 定义与 `docs/DATA-CONTRACT.md` 一致的模型。
|
||||
- TanStack Query 或框架原生数据缓存处理分页；Zustand 只存筛选、主题和用户偏好，不存整库情报。
|
||||
- 服务端渲染栏目和详情，客户端只增强筛选、收藏、任务和翻译门控。
|
||||
- 图片使用源站或授权地址时保留来源；没有图时继续使用 HTML 文字海报，不生成无来源的假图片。
|
||||
- 触控目标至少 44px，业务正文至少 16px，移动端七分类首屏可发现。
|
||||
|
||||
## 迁移顺序
|
||||
|
||||
1. 先冻结 JSON v2 契约，将当前两份发布 JSON 导入新 API。
|
||||
2. Node 前端改为读 API，逐页对比旧静态站；此时抓取仍由 Python 定时任务运行。
|
||||
3. C# 增加用户偏好、任务和权限，不改自动事实字段。
|
||||
4. 如确有团队维护收益，再逐个把稳定解析器迁移到 .NET；每迁移一个源，用相同 URL、证据词和快照做双跑比对。
|
||||
5. 最后将 SEO canonical 切向新域名，并保留旧 URL 的 301 映射。
|
||||
|
||||
不要一开始重写 57 个源。先把现有采集器当独立批处理服务，C# 和 Node 围绕稳定 JSON 契约开发，风险和交付周期最低。
|
||||
@@ -0,0 +1,50 @@
|
||||
# 数据契约
|
||||
|
||||
## 发布文件
|
||||
|
||||
- `data/textile-intelligence.json`：情报主数据，前端和 SEO 的唯一事实快照。
|
||||
- `data/textile-trends.json`：趋势博客、灵感图库和时装趋势。
|
||||
- `data/textile-intelligence-source-status.json`：生成期源状态，不复制到公开 `dist/data`。
|
||||
- `data/textile-zh-cache.json`：翻译缓存，不复制到公开站点。
|
||||
|
||||
主数据顶层字段：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `version` | number | 数据结构版本 |
|
||||
| `generated_at` | ISO 8601 | 生成时间，UTC |
|
||||
| `as_of_date` | YYYY-MM-DD | 业务判断基准日 |
|
||||
| `source_target/source_success` | number | 严格源目标与成功数 |
|
||||
| `summary` | object | 各栏目数量、去重数、市场数 |
|
||||
| `today` | array | 已排序的今日经营动作 |
|
||||
| `calendar/calendar_insights` | array | 原始日期层与跨源聚合机会层 |
|
||||
| `exhibitions` | array | 展会和报名信息 |
|
||||
| `policies` | array | 政策、召回、平台规则与知识产权 |
|
||||
| `standards` | array | 标准、认证、色彩和材料事实 |
|
||||
| `platforms` | array | 平台目录与中国卖家准入边界 |
|
||||
| `activities` | array | 跨境活动与报名入口 |
|
||||
| `sources` | array | 已通过源的公开核验信息 |
|
||||
|
||||
## 公共字段
|
||||
|
||||
所有可展示条目至少包含稳定 `id`、`title`、`summary`、`source`、`source_url/url`、`verified_at`、`confidence`。外文条目可包含 `title_original`、`summary_original`、`translation_url` 和 `translation_fallback_url`。
|
||||
|
||||
日历聚合条目必须满足：
|
||||
|
||||
- `start_date`、`affected_countries`、`country_details.local_name`
|
||||
- `stocking_start`、`stocking_end`、`planning_stage`
|
||||
- `product_suggestions`、`platforms`、`platform_actions`
|
||||
- `official_sources` 与事实/经营分析边界
|
||||
|
||||
进入“精准机会”的条目必须同时有目标国家、平台、产品、备货窗口，且窗口未在 `as_of_date` 前结束。不满足者只能进入全部节点或观察层。
|
||||
|
||||
展会条目要区分 `registration_url`、`visitor_url`、官网和机器翻译链接。正式报名、付款和验证码不得指向翻译代理。
|
||||
|
||||
平台条目必须包含 `homepage_url`、`official_url`、`seller_url`、`markets`、`access_level`、`access_label`、`cross_border` 和本地 SVG `logo`。不确定的中国主体准入不能标为无条件开放。
|
||||
|
||||
## 兼容策略
|
||||
|
||||
- 新增可选字段不提升 `version`；删除、改名或改变语义必须提升版本。
|
||||
- 消费端忽略未知字段，不依赖数组索引。
|
||||
- C# 反序列化建议启用大小写不敏感和未知字段忽略。
|
||||
- Node/TypeScript 进入数据库前应以 JSON Schema 或 Zod 校验同一契约；不要在 UI 组件内修补脏数据。
|
||||
@@ -0,0 +1,62 @@
|
||||
# 运维手册
|
||||
|
||||
## 环境
|
||||
|
||||
- Windows 11、Linux 或 macOS
|
||||
- Python 3.11+
|
||||
- 可访问目标官方站点的网络
|
||||
- Node 仅用于运行前端契约测试，不是生产运行依赖
|
||||
|
||||
## 日常命令
|
||||
|
||||
```powershell
|
||||
# 更新并构建
|
||||
.\.venv\Scripts\python.exe scripts\update_all.py
|
||||
|
||||
# 固定日期回归，不用于生产快照
|
||||
.\.venv\Scripts\python.exe scripts\update_all.py --now 2026-08-12
|
||||
|
||||
# 仅重新构建
|
||||
.\.venv\Scripts\python.exe scripts\build_site.py --site-url https://intel.example.com
|
||||
|
||||
# 本地访问
|
||||
.\.venv\Scripts\python.exe scripts\serve.py --port 8765
|
||||
```
|
||||
|
||||
## 部署
|
||||
|
||||
`dist/` 是完整静态目录，可交给 IIS、Nginx、对象存储或任何 CDN。运行服务器不需要 Python；Python 只在更新节点运行。IIS 必须将实际静态文件优先于 SPA fallback，否则 `/data/*.json` 会错误返回首页 HTML。
|
||||
|
||||
更新节点和 Web 节点分离时，将成功构建的 `dist/` 整目录同步到新版本目录，再通过目录链接或发布槽切换；不要边复制边对外提供半成品。
|
||||
|
||||
## 监控
|
||||
|
||||
至少监控：
|
||||
|
||||
- 进程退出码和最后成功时间。
|
||||
- `source_target == source_success`。
|
||||
- 核心栏目数量突降超过 30%。
|
||||
- `textile-intelligence-source-status.json` 的失败源、HTTP 状态、证据词缺失和内容指纹变化。
|
||||
- `dist/sitemap.xml`、`dist/llms.txt` 和两份公开 JSON 可访问且 Content-Type 正确。
|
||||
|
||||
## 故障处理
|
||||
|
||||
- 单个官方源失败：先核验 URL、重定向、证书和正文证据；不要直接删证据词或关闭 TLS 验证。
|
||||
- 参考趋势源 403：允许跳过，不影响严格发布；长期失效再从趋势配置删除。
|
||||
- 翻译代理不可用：保留本站中文摘要和官方原文，不阻断发布。
|
||||
- 构建失败：正式 `data/` 与 `dist/` 保持上一版；修复后重跑。
|
||||
- 数据误判：先修共享规范化或分类函数并加最小回归测试，再重新生成，避免只在前端隐藏。
|
||||
|
||||
## 备份和清理
|
||||
|
||||
`runtime/snapshots/` 自动保存旧 JSON 的 gzip 快照，限制为 14 份和 120 MiB。源码库不提交 `dist/`、`.venv/`、临时更新目录和快照。若迁移到数据库，备份策略由数据库负责，仍应保留每日成功 JSON 作为可重放交换快照。
|
||||
|
||||
## 发布清单
|
||||
|
||||
1. Python 与 Node 测试全绿。
|
||||
2. 严格源全部通过，活动源全部通过。
|
||||
3. `SANSHENG_SITE_URL` 是正式唯一域名。
|
||||
4. 桌面、390px 与 375px 检查七入口、日历、展会、平台、活动和趋势图库。
|
||||
5. 抽查外文、简中、`.cn`、繁中页面的翻译按钮门控。
|
||||
6. 抽查 10 条详情页的 canonical、JSON-LD、官方链接和日期。
|
||||
7. 发布后请求 `/data/textile-intelligence.json`，确认不是 SPA HTML。
|
||||
@@ -0,0 +1,41 @@
|
||||
# 更新流水线
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A[官方与参考源] --> B[并发抓取和证据词校验]
|
||||
B --> C[结构化解析与语种识别]
|
||||
C --> D[中文缓存和翻译链接]
|
||||
D --> E[规范化、聚合、排序和去重]
|
||||
E --> F[临时 JSON 校验]
|
||||
F --> G[静态 SEO / GEO 构建]
|
||||
G --> H[原子替换 data 与 dist]
|
||||
H --> I[本地 HTTP 服务或任意静态服务器]
|
||||
```
|
||||
|
||||
## 抓取
|
||||
|
||||
`update_textile_trends.py` 先更新趋势数据，`update_textile_intelligence.py --strict` 再校验权威源并构造全部业务栏目。HTTP 使用超时、有限重试、固定浏览器 UA、内容类型检查和正文证据词，不把“HTTP 200”直接当成功。
|
||||
|
||||
BSMI 官方站证书缺少现代 OpenSSL 严格模式要求的 Subject Key Identifier。`LegacyCertificateAdapter` 只挂载到该域名，并同时作用于代理连接；仍保留 CA 链和主机名验证，禁止全局 `verify=False`。
|
||||
|
||||
## 翻译
|
||||
|
||||
先识别域名、页面语言和正文字符。简体中文或 `.cn` 不创建翻译入口；繁体中文保留原文并提供简体辅助。Google 和 Yandex 只生成访问 URL，不抓取或存储整页翻译。标题和摘要的中文结果进入 `textile-zh-cache.json`，当前使用规范化后的完整原文字符串作为缓存键；内容指纹另用于判断源站是否变化。
|
||||
|
||||
## 排序与去重
|
||||
|
||||
- 日历：规范化节名、日期、适用区域后聚合多个官方来源；同一聚合条目并列展示证据。
|
||||
- 展会：规范化展名、开始日和城市，动态目录与固定官方源相遇时保留官方字段。
|
||||
- 政策：按风险、发布时间、生效时间和适用市场排序；召回与经营政策分类型展示。
|
||||
- 今日必看：只选择可行动的备货、临近展会、重大政策和趋势任务，已过备货窗降级为营销或履约状态。
|
||||
- 趋势：URL、规范化标题和内容指纹去重，优先有图片和较新发布时间的条目。
|
||||
|
||||
## 增量与容量
|
||||
|
||||
`update_all.py` 在 `runtime/update-*` 临时目录完成全部流程。新旧文件 SHA-256 相同则不写正式数据；有变化时先把旧四份 JSON 压缩为单个快照，再使用 `os.replace` 原子更新。快照最多 14 份、总计不超过 120 MiB。
|
||||
|
||||
公开 `dist/data` 只包含两份运行 JSON，不发布源状态和翻译缓存。静态详情页由数据重建，不进入源码版本管理。若以后迁移数据库，建议保留当前 JSON 作为版本化交换契约，而不是让爬虫直接写业务表。
|
||||
|
||||
## 失败语义
|
||||
|
||||
以下任一情况退出非零且不发布：严格源失败、活动源失败、核心栏目为空、JSON 无法解析、SEO 构建失败、目标目录替换失败。日志允许趋势参考源 403 后跳过，因为它们不计入严格权威源；该降级会保留在趋势错误字段中。
|
||||
@@ -0,0 +1,31 @@
|
||||
# 三笙AI情报局 SEO/GEO 规范
|
||||
|
||||
## 实体与域名
|
||||
|
||||
- 品牌实体统一写作“**三笙AI情报局**”，简称“三笙AI”；“家纺AI”是产品能力词，不替代品牌名。
|
||||
- 正式域名只由 `SANSHENG_SITE_URL` 注入，例如 `https://intel.example.com`。独立站不占用 `https://www.sanshengai.net/` 根目录，也不复制主站 canonical。
|
||||
- 页面路径固定为 `/textile/`、`/textile/calendar/`、`/textile/intelligence/<section>/<id>/`；末尾保留 `/`，所有 canonical、Open Graph、JSON-LD、Sitemap 使用同一规范 URL。
|
||||
|
||||
## 关键词与页面意图
|
||||
|
||||
核心词：`家纺AI`、`三笙AI`、`家纺情报`、`跨境家纺平台`、`家纺跨境平台`。任务词：家纺备货日历、家纺展会、家纺政策、家纺平台渠道、家纺趋势。
|
||||
|
||||
每个栏目只服务一个问题：备货日历回答“何时备货与下一步动作”，展会回答“是否值得参加与官方报名”，政策回答“发生了什么与不处理的后果”，平台回答“适合谁与官方入驻入口”，趋势回答“如何转化为产品和打样任务”。标题、首段、H2 和 JSON-LD 只围绕该问题组织，不堆叠同义词。
|
||||
|
||||
## GEO（生成式搜索）
|
||||
|
||||
- 每个集合页和详情页首屏输出一段 `data-answer-first="true"` 的“快速答案/先看结论”，答案先给结论，再给证据与动作。
|
||||
- 官方事实、机器翻译、本站经营分析必须分区；机器翻译只作阅读辅助，不改变原文事实，不替代报名、付款、合规提交。
|
||||
- 详情页 JSON-LD 使用 `Event` 或 `Article`，包含 `inLanguage=zh-CN`、`dateModified`、`publisher`、`keywords`、`isAccessibleForFree`；集合页使用 `CollectionPage` + `ItemList`。
|
||||
- `llms.txt` 说明实体定义、栏目意图、事实与分析边界和稳定入口，便于问答系统引用；它不是隐藏关键词页。
|
||||
|
||||
## 抓取与更新
|
||||
|
||||
- 只有内容指纹变化才重新生成机器翻译和详情页；外部翻译失败时保留上一版中文内容。
|
||||
- Sitemap 只列公开 HTML 入口、详情页和年份页；不列抓取日志、翻译缓存、状态 JSON 或内部分析文件。
|
||||
- 当前只有 `zh-CN` 正文，使用 `hreflang="zh-CN"` 与 `x-default` 指向同一 canonical；未来增加人工校验的原生语言页面后，才建立互指 hreflang。
|
||||
- robots.txt 允许公开静态页面，禁止把内部状态文件当成索引入口。
|
||||
|
||||
## 无 GitHub/Pages 部署
|
||||
|
||||
更新节点运行 `python scripts/update_all.py`，再运行 `python scripts/build_site.py --site-url "$SANSHENG_SITE_URL"`，最终只发布 `dist/`。Gitea Actions、Windows 计划任务或公司 CI 均可执行这两个命令，然后用制品上传、IIS/Nginx 目录同步、对象存储或 CDN 发布 `dist/`；访问端不需要 Python、Node、数据库或大模型，也不依赖 GitHub Pages。
|
||||
@@ -0,0 +1,51 @@
|
||||
# 信源与 Demo 差集
|
||||
|
||||
## 可信层级
|
||||
|
||||
| 层级 | 用途 | 可生成的结论 |
|
||||
|---|---|---|
|
||||
| L1 政府、国际组织、标准机构 | 日期、法规、关税、召回、标准 | 可作为事实层，必须保留原文和核验时间 |
|
||||
| L2 平台、展会和主办方官方 | 入驻、报名、活动、类目、官方新闻 | 可生成平台或参展动作 |
|
||||
| L3 行业媒体、博物馆、品牌公开页 | 趋势、设计灵感、活动发现 | 只能标为观察或参考，不得冒充法规 |
|
||||
| L4 商业数据摘要 | 公开样本和搜索信号 | 不计入权威源成功数，不依赖付费详情 |
|
||||
|
||||
## 当前严格源
|
||||
|
||||
当前注册表位于 `scripts/intelligence_sources.py`，共 59 个严格校验源。核心覆盖：
|
||||
|
||||
- 日历：Nager.Date、GOV.UK、美国 OPM、日本内阁府、香港政府、AlAdhan、NRF、阿里巴巴 11.11 官方活动、NFL、LA28。
|
||||
- 展会：Messe Frankfurt 系列、Première Vision、Texworld、Maison&Objet、High Point、Las Vegas Market、Milano Unica、CIFF、DOMOTEX、INDEX、UFI、Texpertise、CCBEC、HKTDC Home InStyle。
|
||||
- 政策与合规：USTR、CBP、FTC、CPSC、欧盟税务与海关、ECHA、欧盟纺织战略、英国关税、商务部、香港工贸署、Singapore Customs、ASEAN、EEC、哈萨克斯坦、UAE FTA、ZATCA、台湾 BSMI、沙特 SASO、WIPO、EUIPO。
|
||||
- 平台规则：Amazon、eBay、Walmart、TikTok Shop、Mercado Libre。
|
||||
- 标准与趋势事实：Pantone、Textile Exchange、OEKO-TEX、AATCC。
|
||||
|
||||
平台目录另有 28 项，经官方类目、官网与卖家入口核验，已包含 Amazon、eBay、Walmart、Etsy、TikTok Shop、Temu、Shopee、Lazada、Ozon、Wildberries、Mercado Libre、Noon、Wayfair、Rakuten、Coupang、Allegro、OTTO、Cdiscount、bol、Kaufland、Shopify、Alibaba.com、1688、SHEIN 等。
|
||||
|
||||
## 本轮从 Demo 吸收
|
||||
|
||||
Demo 约有 207 个基础域名，与现有注册表的原始差集约 157 个。域名数量不能等同于可信源数量，因为大量条目只是区域商城、旧入口、转载、咨询商、零售货架或付费报告。
|
||||
|
||||
本轮实际新增四个一手源：
|
||||
|
||||
1. 台湾 BSMI 纺织品检验专区：补齐台湾寝具、毛巾、服装的检验与标示。
|
||||
2. 沙特 SASO 纺织产品技术法规：替代 Demo 中咨询公司的二手法规解释。
|
||||
3. CCBEC 深圳跨境电商展：覆盖家居日用、平台、物流、POD 和服务商对接。
|
||||
4. HKTDC Home InStyle：实体展期经官方 Fair at a Glance 核验为 2027-04-27 至 2027-04-30。
|
||||
|
||||
## 用户点名页面的处理结论
|
||||
|
||||
- `tid.gov.hk/en/tradecircular/2026/ci5442026.html`：已作为香港工贸署官方政策源接入。
|
||||
- `asinsight.com/report/US/cooling-duvet-cover`：已作为公开商业趋势参考接入，不计入权威政策源。
|
||||
- `gdtextiles.cn/nd.jsp?groupId=36&id=1966`：不接入。页面转载中国棉花网且 HTTPS 使用自签名证书；同一政策事实已由 USTR、CBP 等一手来源覆盖。
|
||||
- `bhg.com/best-duvet-inserts-6822459`：不接入自动抓取。当前返回 HTTP 402，并属于消费者测评；只有公开访问与自动使用条件明确时才可作为选品参考，不能作为政策或市场事实。
|
||||
|
||||
## 发现源与排除项
|
||||
|
||||
- 雨果跨境用于发现活动，日期、费用、报名状态必须回平台或主办方官方页复核。
|
||||
- ASInsight 只保留无需登录的公开摘要，标为商业数据参考，不计入权威成功数。
|
||||
- Dezeen、Design Milk、Fibre2Fashion、博物馆图库用于趋势和灵感，不生成政策结论。
|
||||
- 本地零售货架适合后续抽样研究尺寸、材质、色彩和价格带，不做高频库存或价格抓取。
|
||||
- 永久排除 POP 趋势网、91 家纺付费快照、已关闭的 Catch、旧 vente-privee 域名、SEO 转载和只有咨询商解释的法规。
|
||||
- 咨询站只用于发现线索，必须回 FTC、CPSC、欧盟、SASO、海关等官方源。
|
||||
|
||||
新增源必须提供：唯一 ID、栏目、地区、官方 URL、正文证据词、权威说明、中文标题和业务动作。抓取成功只代表页面可访问且证据存在，不代表其中每段内容自动成为经营建议。
|
||||
Reference in New Issue
Block a user