# TFGEO 产品需求文档（PRD）

**产品名称**：TFGEO · 天府皇冠假日酒店 GEO 项目看板
**文档版本**：v1.0
**发布日期**：2026-09-17
**访问地址**：https://www.caohepeng.com/tfgeo/
**代码规模**：后端 Python（FastAPI）约 5 个模块 / 前端原生 HTML+CSS+JS 约 3 个文件 + 6 张场景页
**文档状态**：正式版（随交付包发布）

---

## 1. 项目背景

酒店在传统搜索引擎之外，正快速进入「AI 搜索」入口：用户会直接问豆包、千问、DeepSeek、Kimi"世纪城会展中心附近住哪家酒店""成都适合带娃住的酒店"，大模型给出的答案取决于它对酒店的**事实认知**。

天府皇冠假日酒店面临三个具体问题：

1. **事实噪声**：公开信源存在冲突口径（开业日期、星级、亲子房数量、宴会厅面积、泳池/健身面积、接驳政策），大模型吸收后被污染。
2. **过程不可见**：GEO 工作分散在文档、聊天、Excel 里，酒店方无法看到"谁在改什么、哪条事实可对外说"。
3. **内容不可控**：对外发布的场景页与自媒体稿件缺少统一口径，容易写出未核实数字。

TFGEO 的目标是把 GEO 工作**产品化**：一个承载「介绍 → 规划 → 进度 → 待办 → 任务 → 文件 → 已上线 → 待发布」全链路的项目看板，让事实、素材、内容、监测在同一处治理。

## 2. 产品目标

| 目标 | 可验证口径 |
|---|---|
| 单一事实源 | 全部对外内容引用「已确认可对外引用」事实；未核验数字由系统拦截 |
| 过程可追溯 | 文件有版本历史与操作日志；文章有完整状态流转日志 |
| 交付可复用 | 六大场景页 + 多平台内容稿池可在看板内编辑、审核、发布 |
| 效果可衡量 | 采样指标按平台可视化，可对比投放前后 |
| 对外可交付 | 源码 + PRD 可打包分发，支持二次部署 |

**非目标（v1.0 不做）**：OTA 后台直连、自动化多渠道一键发布、实时流量归因（仅做最小归因）。

## 3. 名词与口径

| 术语 | 定义 |
|---|---|
| GEO | Generative Engine Optimization，让生成式 AI 正确理解并推荐品牌 |
| 事实卡 | 酒店结构化事实集合，按证据等级标注，是写作的唯一事实来源 |
| A 级事实 | 酒店方确认可公开，可直接对外引用 |
| H 级事实 | 酒店提供但数字待复核，**确认前禁止对外** |
| 场景页 | 针对一类搜索意图（会展/商务/品牌/亲子/餐饮/交通）打造的落地页 |
| 事实门禁 | 后端扫描内容中的敏感数字模式，命中则强制「⚠ 待确认」并禁止标绿 |
| 三色状态 | 🟢 已确认可对外引用 / 🟡 待酒店确认 / ⚪ 仅内部参考 / 🔴 已废弃 |

## 4. 用户与角色

| 角色 | 关注点 | 系统权限 |
|---|---|---|
| 酒店市场部 | 事实裁决、素材上传、对外文案取用 | 文件中心读写、状态变更 |
| 内容团队 | 写作、编辑、送审 | 文件与文章读写 |
| 项目经理 | 进度、风险、待办认领 | 全部只读 + 任务管理 |
| 酒店管理层 | 待确认清单、授权发布 | 状态变更（授权） |
| 匿名访客 | 查看已上线场景页与项目概况 | 只读 |

**权限实现**：请求头 `X-FC-Role` 携带角色；敏感文件（营业执照/信用代码/法人信息）仅管理员可见，对外接口不返回。

## 5. 系统总览

```
浏览器
  │  https://www.caohepeng.com/tfgeo/
  ▼
Nginx（caohepeng.com）
  ├── /tfgeo/            → 静态前端  /var/www/tfgeo/frontend/
  ├── /tfgeo/uploads/    → 上传文件  /var/www/tfgeo/uploads/
  ├── /tfgeo/api/        → 反向代理  http://127.0.0.1:8055/api/
  └── /tfgeo/downloads/  → 交付下载  /var/www/tfgeo/frontend/downloads/
          ▼
   FastAPI 应用（systemd: tfgeo-api.service, :8055）
     ├── main.py       项目数据 API（介绍/规划/进度/任务/上传）
     ├── fc.py         文件中心 API（分类/版本/上传/导出/门禁）
     └── articles.py   待发布文章 API（多平台稿池 + 状态机）
          ▼
   数据层（文件系统 JSON/Markdown）
     ├── /var/www/tfgeo/filestore/  文件中心（files/versions/exports/sensitive）
     ├── /var/www/tfgeo/articles/   文章库 articles.json
     └── /opt/geolook/work/tianfu-crown/ 采样与指标（只读引用）
```

**技术选型理由**：数据量小、以文档为主 → 用文件系统 + JSON 而非数据库，便于版本管理与人工干预；前端不引入框架，保证在酒店内网/低配设备可打开。

## 6. 功能需求（八大板块）

### ① GEO 介绍
- 说明 GEO 概念、对本酒店的价值、AI 搜索与传统 SEO 的差异。
- 数据来源：`GET /api/intro`。

### ② 项目规划
- 90 天执行方案、阶段目标、交付物清单。
- 数据来源：`GET /api/plan`。

### ③ 进度看板
- 关键指标卡（采样平台可见度、事实卡确认进度、场景页上线数、内容稿池规模）。
- 数据来源：`GET /api/overview`（合并 `/opt/geolook/work/tianfu-crown/metrics/*.json`，各平台取最新值）。

### ④ 待你处理
- 需要酒店方/项目经理决策的事项清单（action items），支持勾选完成。
- 数据来源：`GET /api/action-items`。

### ⑤ 任务详情（ARTC）
- 以 ARTC（Action / Result / Timeline / Check）结构呈现任务，支持模板查看。
- 数据来源：`GET /api/tasks`、`GET /api/templates`。

### ⑥ 文件中心
**目标**：项目全部资料按 7 大类归档，带事实等级与发布状态，支持在线编辑、版本管理、导出与门禁。

**7 大分类**：00-项目管理 / 01-品牌与事实 / 02-公开信源与平台 / 03-写作与发布 / 04-图片与素材 / 05-监测与归因 / 06-交付物。

**核心功能**
1. 目录树与筛选：按分类、发布状态（全部/待确认/可对外引用/写作资料）过滤。
2. 在线编辑：保存即生成新版本，历史版本可下载与恢复。
3. 预览：md/txt/json/html 文本渲染；图片大图；pdf/doc/xls 提示下载。
4. 上传：拖拽单文件上传；ZIP 批量导入（先返回清单供确认，再入库）。
5. 导出：单文件下载、分类 ZIP、写作资料包 ZIP、事实库（md/docx/pdf）、待确认清单（xlsx/csv）。
6. **事实门禁**：内容命中敏感数字模式时，自动挂「⚠ 待确认」，且禁止标「已确认可对外引用」（返回 403 并列出命中项）。
7. 敏感隔离：`filestore/sensitive/` 不对静态暴露，仅管理员经 `/api/fc/file/{id}/download` 取用。

**接口**

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/fc/guide` | 使用说明 |
| GET | `/api/fc/tree` | 分类目录树 |
| GET | `/api/fc/files` | 文件列表（支持筛选） |
| GET | `/api/fc/file/{id}` | 文件元数据 |
| GET | `/api/fc/file/{id}/content` | 文本内容预览 |
| POST | `/api/fc/file/{id}/edit` | 在线编辑（生成新版本） |
| POST | `/api/fc/create` | 新建条目 |
| POST | `/api/fc/suggest` | 生成占位/建议条目 |
| POST | `/api/fc/upload` | 单文件上传 |
| POST | `/api/fc/upload/zip` | ZIP 批量导入（返回清单） |
| POST | `/api/fc/upload/zip/confirm` | 确认入库 |
| GET | `/api/fc/file/{id}/download` | 下载（计数） |
| POST | `/api/fc/file/{id}/restore` | 恢复历史版本 |
| DELETE | `/api/fc/file/{id}` | 删除（进回收站） |
| POST | `/api/fc/file/{id}/status` | 变更发布状态（含门禁校验） |
| GET | `/api/fc/export/folder` | 按分类导出 ZIP |
| GET | `/api/fc/export/package` | 写作资料包 ZIP |
| GET | `/api/fc/export/facts` | 已确认事实库（md/docx/pdf） |
| GET | `/api/fc/export/todo` | 待确认清单（xlsx/csv） |

### ⑦ 已上线页面
- 展示已发布的 6 张 GEO 场景页，可直接打开：
  ① 会展住宿（mice-convention）② 高新商务（business-gaoxin）③ 品牌辨识（brand-ihg）
  ④ 亲子家庭（family-kids）⑤ 餐饮（dining）⑥ 交通接驳（transport）。
- 每页须标注意图定位、支撑事实版本（当前事实卡 v6）与上线日期。

### ⑧ 待发布文章（多平台稿池）
**目标**：家庭亲子客群内容稿池，覆盖多平台差异化表达，支持在线编辑与「提交审核 → 审核 → 发布」流程。发布永远人工确认。

**规模**：103 篇 / 9 平台
- 携程旅拍 20 篇（基线稿：北京 4 / 上海 4 / 重庆 3 / 西安 3 / 广州 3 / 深圳 3）
- 知乎 / 小红书 / 抖音 / 抖音精选 / 百家号 / 搜狐网 / 博客园 / 头条 各 10 篇
- 小红书额外长文 3 篇（ART-XHS-11/12/13，分别覆盖全维深挖、三代同游＋会务空间、餐饮专题）

**平台表达规范**

| 平台 | 体裁 | 字数 | 记忆点设计 |
|---|---|---|---|
| 携程旅拍 | 图文游记 | 300–500 | 家庭场景动线 |
| 知乎 | 回答体/经验分享（含 Q&A） | 800–1300 | 取舍与避坑 |
| 小红书 | 第一人称短句 + emoji + 话题标签 | 250–450（长文 800–3000） | 痛点开头 |
| 抖音 | 15–60s 口播脚本（钩子/痛点/方案/行动） | 300–600 | 前 3 秒钩子 |
| 抖音精选 | 60–180s 中长视频脚本/深度图文 | 500–900 | 一天动线 + 3 条经验 |
| 百家号 | 图文资讯（导语 + 小标题 + Q&A） | 700–1100 | 信息前置 |
| 搜狐网 | 媒体观察稿（第三人称客观） | 800–1200 | 案例叙述 |
| 博客园 | 出行配置手册 + FAQ + Checklist | 900–1400 | 条目化可复现 |
| 头条 | 资讯流短段落 + 互动引导 | 500–900 | 信息缺口开头 |

**状态机**

```
draft(草稿) --submit--> pending(待审核) --approve--> approved(审核通过) --publish--> published(已发布)
     ^                        \--reject(必须填意见)--> rejected(已驳回) --reopen--/
     └---- 编辑保存（pending/approved 改动自动回 draft） <---- reopen <---- published
```

**接口**

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/arts/list` | 列表（摘要）+ 状态统计 + 城市 + 平台统计 |
| GET | `/api/arts/meta` | 状态字典 + 平台清单 |
| GET | `/api/arts/{id}` | 单篇全文 |
| PUT | `/api/arts/{id}` | 在线编辑（标题/正文/标签/配图/卖点） |
| POST | `/api/arts/{id}/submit` | 提交审核 |
| POST | `/api/arts/{id}/approve` | 审核通过 |
| POST | `/api/arts/{id}/reject` | 驳回（comment 必填） |
| POST | `/api/arts/{id}/publish` | 发布 |
| POST | `/api/arts/{id}/reopen` | 撤回重编 |
| POST | `/api/arts/reset` | 开发用：按种子重建 |

## 7. 数据模型

### 7.1 文章对象 `articles/articles.json`

```json
{
  "articles": [
    {
      "id": "ART-XHS-11",
      "platform": "小红书",
      "title": "……",
      "city": "上海",
      "persona": "一家四口（两大两小）",
      "route": "上海直飞成都 · 约3小时",
      "days": "5天4晚",
      "tags": ["#成都亲子游"],
      "images": ["配图建议，每行一条"],
      "highlights": ["空间大", "早餐种类丰富", "停车便利"],
      "body": "正文（\\n\\n 分段）",
      "source_id": "ART-SH-01",
      "status": "draft",
      "review_comment": "",
      "created_at": "2026-09-17 13:20:00",
      "updated_at": "2026-09-17 13:20:00",
      "updated_by": "内容团队",
      "logs": [{"at": "…", "action": "生成初稿", "actor": "内容团队", "from": null, "to": "draft", "comment": "…"}]
    }
  ],
  "updated_at": "2026-09-17 13:40:00"
}
```

### 7.2 文件中心 `filestore/`

| 目录 | 用途 |
|---|---|
| `files/<file_id>/` | 当前版本内容 |
| `versions/<file_id>/` | 历史版本 |
| `exports/` | 导出产物 |
| `sensitive/` | 敏感文件（不对静态暴露） |
| `trash/` | 删除回收站 |

文件元数据包含：来源、责任部门、发布状态、事实等级、关联页面、版本历史、操作日志。

## 8. 非功能需求

| 类别 | 要求 |
|---|---|
| 性能 | 列表接口 P95 < 500ms（本地文件读取）；前端首屏 < 1.5s |
| 兼容 | 桌面 1440px 与移动 390px 均无横向溢出 |
| 缓存 | 开发阶段前端禁缓存（`no-cache, no-store`），避免页面与脚本错配 |
| 上传 | 单文件 ≤ 20MB（业务） / 25MB（Nginx 限制）；扩展名白名单 |
| 安全 | 敏感目录静态不暴露；CORS 白名单方法（GET/POST/DELETE/OPTIONS）；无 SQL 注入面（无数据库） |
| 合规 | 未核验数字不得对外（门禁强制）；发布永远人工确认 |
| 可维护 | 数据为纯文本 JSON/Markdown，可 Git 化；服务 systemd 托管自动重启 |
| 可访问性 | 语义化标签、按钮有可见文案、状态有文字标签（不依赖颜色） |

## 9. 合规红线（内容层）

**禁止写入对外内容**：客房总数、星级/钻级、亲子房主题数与间数、泳池/健身/宴会厅面积、房价、开业日期、OTA 评分、停车位数量、接机服务承诺。

**统一表述**：亲子房细节与儿童早餐政策 → 「以酒店实时确认为准」；无接机 → 明确写「无接机服务」并给替代方案（叫车/送站用车规则）。

**依据**：酒店方《结构化事实卡》（A 级可公开 / H 级待复核），文件中心按事实等级分发。

## 10. 验收标准

| 项 | 方法 | 结果（2026-09-17） |
|---|---|---|
| 文章模块端到端 | `python3 backend/verify_articles_ext.py`（Playwright） | ALL_PASS（103 篇加载、平台筛选 知乎10/小红书13/抖音精选10/头条10/携程旅拍20、组合筛选、抽屉平台口径、状态流转 submit→approve→publish→reopen、移动端 overflow=0、0 console error） |
| 基线流程 | `python3 backend/verify_articles.py` | PASS |
| 文件中心 | `backend/FC_ACCEPTANCE.md` 验收用例 | PASS |
| 内容质量 | 平台规范自检 `arts_ext/check_ext.py` | 8 个平台文件全 PASS（字数/城市分布/禁词/合规表述） |

## 11. 部署与运维

```bash
# 依赖
pip install fastapi uvicorn pydantic          # 运行
pip install playwright && playwright install chromium   # 验证脚本

# 服务
systemctl restart tfgeo-api.service           # 重启
systemctl status  tfgeo-api.service           # 状态（127.0.0.1:8055）

# Nginx
/etc/nginx/config-management/projects/tfgeo.conf
nginx -t && systemctl reload nginx
```

**目录约定**

| 路径 | 说明 |
|---|---|
| `/var/www/tfgeo/backend` | FastAPI 源码 |
| `/var/www/tfgeo/frontend` | 静态前端（含 `pages/` 场景页、`downloads/` 交付下载） |
| `/var/www/tfgeo/articles` | 文章库 JSON |
| `/var/www/tfgeo/filestore` | 文件中心数据 |
| `/var/www/tfgeo/uploads` | 上传文件 |

## 12. 版本历史

| 版本 | 日期 | 内容 |
|---|---|---|
| v0.1 | 2026-08-19 | 看板骨架：介绍/规划/进度/待办/任务 五板块上线 |
| v0.5 | 2026-08-21 | ⑥ 文件中心上线（7 分类 + 版本 + 门禁 + 导出） |
| v0.8 | 2026-08-22 | ⑦ 六大场景页上线（会展/商务/品牌 + 亲子/餐饮/交通） |
| v0.9 | 2026-09-16 | ⑧ 待发布文章上线（携程旅拍 20 篇 + 审核状态机） |
| **v1.0** | **2026-09-17** | ⑧ 扩展为 9 平台 103 篇；新增平台筛选/平台口径；PRD 与源码交付包 |

## 13. 后续规划（Roadmap）

1. **监测闭环**：采样指标与场景页上线时间自动关联，输出前后对比报表。
2. **一键导出投放包**：按平台导出带标签的稿件包（含配图清单），对接人工发布。
3. **事实卡在线裁决**：把「待确认与冲突台账」做成可勾选裁决流，确认后自动升级为 A 级并刷新门禁。
4. **素材授权台账联动**：配图引用自动校验授权状态。
5. **多酒店复用**：抽出品牌事实层，支持同品牌多门店部署。

---

**附录 A · 交付物清单**
- `TFGEO-PRD-v1.0.md` / `.pdf`：本文档
- `tfgeo-source-<日期>.zip`：项目源码（后端 + 前端 + 内容数据 + 部署配置 + 文档）
- 在线地址：https://www.caohepeng.com/tfgeo/

**附录 B · 源码包说明**
源码包不含：`filestore/sensitive/`（敏感资质）、生产环境历史数据备份、运行截图。首次部署时后端会按种子数据自动初始化文件中心与文章库。