A local-first React and FastAPI workbench for GSC, GA4, PageSpeed, CrUX, storage operations, and AI-assisted SEO analysis.
SEO Data Console 是一个面向长期 SEO 运营的本地优先分析工作台。当前主应用采用 React、TypeScript、Vite 和 FastAPI，将搜索表现、站内行为、页面性能、真实用户体验、数据同步和 AI 任务集中在同一个界面中。
规范化 SQLite 最新事实是本地数据真源；原始响应只保留为确定性、可替换的导入证据。Supabase Postgres 使用相同稳定键作为可选云端副本；即使云端未配置或暂时不可用，本地分析仍可继续运行。
| 模块 | 能力 |
|---|---|
| Overview | 为 GSC、GA4、PageSpeed、CrUX 分别展示来源、独立数据范围、新鲜度、缓存语义和 complete/partial/no dataset/stale 状态 |
| GSC Workbench | 直接按请求日期读取合并后的 canonical daily facts，展示覆盖缺口和保留事实；支持可选比较、多指标趋势、Query/Page 下钻、兼容维度、保存视图、注释和带元数据 CSV 导出 |
| GA4 Behavior | 与 GSC 共用“读取缓存 / 查询来源”交互；六个二级视图按同一请求日期和 canonical coverage 隔离，比较默认关闭，并保留保存/导出/URL 状态 |
| Source Sync | GSC/GA4 显式来源操作先显示零副作用预检、覆盖缺口、三天 reconciliation overlap、已知最小/动态调用、持久化目标；确认后显示服务端重规划的 partition 进度，并只重试仍缺失的 failed/interrupted partition |
| PageSpeed | 显式实时 Mobile/Desktop 测试、四类 Lighthouse 分数、latest-only URL/device 保存、完整来源审计、截图、导出和技术任务 |
| CrUX | 展示字段数据；没有覆盖时显示 No dataset，不伪造成通过或失败 |
| AI Tasks | 根据当前筛选范围和证据创建可追踪的 AI 分析任务 |
| Operations | SQLite、原始缓存、Supabase、备份、容量、额度、新鲜度、日志和同步历史 |
| Connections | 仅显示脱敏后的连接配置状态 |
SEO-Project
├─ apps/
│ ├─ web/ React + TypeScript + Vite
│ ├─ api/ FastAPI、分析服务、SQLite 与云同步
│ └─ seo_dashboard/ 冻结的旧版功能参考，不再作为主应用开发
├─ tools/ GSC / GA4 / PageSpeed / CrUX 连接器 CLI
├─ db/migrations/ Supabase/Postgres 数据库迁移
├─ prompts/ 可公开复用的 SEO 提示词模板
└─ docs/ 架构和仓库策略文档
详细设计见 docs/ARCHITECTURE.md。
- Python 3.11 或更新版本
- Node.js 20.19 或更新版本
- Windows 为当前主要启动和验收平台
- Google/Supabase 配置为可选项；没有凭证时仍可使用已有本地缓存
git clone https://github.com/MartinMaaaaa/SEO-Project.git
cd SEO-Project
python -m pip install -r apps/api/requirements.txt
cd apps/web
npm install
npm test
npm run typecheck
npm run build
cd ../..如果所在网络无法访问默认 npm 注册表，可使用可访问的镜像：
npm install --registry=https://registry.npmmirror.comWindows 用户可双击：
启动SEO控制台.bat
或使用英文入口：
start-seo-dashboard.bat前端和后端地址：
React: http://127.0.0.1:5173/
FastAPI: http://127.0.0.1:8787/
停止应用：
stop-seo-dashboard.bat也可以直接启动 FastAPI：
python -m uvicorn apps.api.main:app --host 127.0.0.1 --port 8787根启动器会分别启动 React/Vite 和 FastAPI；Vite 将 /api 请求代理到 FastAPI。
| 工具 | 用途 |
|---|---|
tools/gsc_cli.py |
Google Search Console 同步和导出 |
tools/ga4_cli.py |
GA4 Data API 同步 |
tools/pagespeed_cli.py |
PageSpeed Insights 检测 |
tools/crux_cli.py |
Chrome UX Report 查询 |
tools/google_oauth_cli.py |
Google OAuth 授权辅助 |
连接器应优先遵守缓存新鲜度规则，避免为开发或测试重复消耗 API 配额。
python -m pytest apps/api/tests -q
cd apps/web
npm run typecheck
npm run build后端测试包括：
- 缓存端点和指标语义
- GSC CTR、加权排名和比较覆盖
- PageSpeed URL 安全、四类别、null、失败保留成功、latest-only SQLite/raw、迁移幂等和缓存零源调用
- CrUX page/origin/fallback/
No dataset状态 - AI 任务创建与历史
- 旧版目录不可访问时的独立运行测试
.env、OAuth token、API key 和数据库连接串不会提交到 GitHub。data/、SQLite、本地备份和真实分析导出保持私有。- 状态接口只返回脱敏配置。
- 来源预检只读本地 canonical coverage，不写 job、attempt、facts 或 raw，也不调用 Google/Supabase。
- 成功的来源查询先提交 canonical SQLite facts，再以稳定键执行可选云复制；云端失败不会回滚本地成功。
- 前端不会把必需功能跳转回冻结旧版。
- 保持已验收的覆盖预检、分报告进度和缺失分区重试合同
- 增加决策导向的贡献度与构成图表
- 建立规范化的跨来源页面分析和 URL 匹配质量报告
- 确认 GA4 主要 SEO 转化事件与业务优先级
- 将已验证的 GSC/PageSpeed 证据转成可跟踪的 SEO 工作流
SEO Data Console is a local-first analytics workbench for long-running SEO operations. The active application uses React, TypeScript, Vite, and FastAPI to combine search performance, onsite behavior, page experience, data operations, and AI-assisted workflows.
Normalized canonical SQLite facts are the local source of truth. Raw responses are deterministic, replaceable ingest evidence only. Supabase Postgres uses the same stable keys as an optional cloud replica, so local analysis continues when cloud services are absent or temporarily unavailable.
| Area | Capability |
|---|---|
| Overview | Per-source GSC, GA4, PageSpeed, and CrUX range, freshness, cache semantics, and complete/partial/no-dataset/stale states |
| GSC Workbench | Requested-date reads over merged canonical daily facts, explicit coverage gaps and retained facts, opt-in comparisons, multi-metric trends, query/page drill-down, compatible dimensions, saved views, annotations, and metadata-aware CSV export |
| GA4 Behavior | Shared cached/source-query workflow with GSC, requested-date canonical coverage, opt-in comparison, six isolated subviews, saved/exported/URL state, and explicit source queries |
| Source Sync | Explicit GSC/GA4 actions first show a zero-side-effect preflight with coverage gaps, the three-day reconciliation overlap, known-minimum/dynamic calls, and persistence targets; confirmed jobs expose server-replanned partition progress and retry only failed/interrupted partitions that remain missing |
| PageSpeed | Explicit live Mobile/Desktop tests, four Lighthouse categories, latest-only URL/device persistence, complete source audits, screenshots, exports, and technical tasks |
| CrUX | Field data when available and an honest No dataset state otherwise |
| AI Tasks | Scope-aware task creation with preserved evidence |
| Operations | Local-only cached SQLite/raw/backup/capacity/quota/freshness evidence, current-versus-recovered diagnostics, and explicit sync history |
| Connections | Readiness-only configuration metadata without credential values or fragments |
SEO-Project
├─ apps/
│ ├─ web/ React + TypeScript + Vite
│ ├─ api/ FastAPI, analytics, SQLite, and cloud sync
│ └─ seo_dashboard/ Frozen legacy reference, no longer the active app
├─ tools/ GSC / GA4 / PageSpeed / CrUX connector CLIs
├─ db/migrations/ Supabase/Postgres migrations
├─ prompts/ Public reusable SEO prompt templates
└─ docs/ Architecture and repository policy
See docs/ARCHITECTURE.md for more detail.
- Python 3.11+
- Node.js 20.19+
- Windows is the primary verified launch platform
- Google and Supabase credentials are optional when cached local data already exists
git clone https://github.com/MartinMaaaaa/SEO-Project.git
cd SEO-Project
python -m pip install -r apps/api/requirements.txt
cd apps/web
npm install
npm test
npm run typecheck
npm run build
cd ../..If the default npm registry is unreachable from your network:
npm install --registry=https://registry.npmmirror.comDouble-click 启动SEO控制台.bat, or run:
start-seo-dashboard.batFrontend and backend:
React: http://127.0.0.1:5173/
FastAPI: http://127.0.0.1:8787/
Stop:
stop-seo-dashboard.batDirect FastAPI startup is also supported:
python -m uvicorn apps.api.main:app --host 127.0.0.1 --port 8787The root launcher starts React/Vite and FastAPI as separate processes. Vite proxies /api requests to FastAPI.
python -m pytest apps/api/tests -q
python -m compileall apps/api tools -q
cd apps/web
npm test
npm run typecheck
npm run buildThe backend suite covers canonical overwrite-and-retain semantics, stable source grains, coverage-led gap plus reconciliation planning, cached zero-source-call contracts, comparison/null semantics, PageSpeed URL safety and latest-only persistence, CrUX period/no-data states, readiness-only diagnostics, scoped AI tasks, targeted migration idempotence, and optional Supabase stable-key upserts.
.env, OAuth tokens, API keys, and database URLs are never committed.data/, SQLite, backups, and real analytics exports remain private.- Status responses expose readiness booleans and purposes only; credential values and fragments are not serialized.
- Cached Operations reads stay local and do not contact the optional cloud replica.
- Source preflight reads canonical coverage without writing jobs, attempts, facts, or raw evidence and without contacting Google or Supabase.
- Successful source queries commit canonical SQLite facts before optional stable-key cloud replication; cloud failure does not roll back local success.
- Required functionality never links users back to the frozen dashboard.
- Preserve the accepted canonical coverage preflight, per-report progress, and missing/failed-partition retry contract
- Daily-use analytics table controls and server pagination
- Bounded GSC/GA4 official-web parity packages