refactor: 主题系统 → monorepo 五个独立网站

- packages/core: @aidir/core 底座库（src/pages 页面组件体 1:1 镜像路由树 / kit 站点外壳工厂 / content/blog / scripts） - sites/: 5 个独立 Next.js 网站（ai-stack / launchai / the-ai-ledger / devai-tools / findai） - 每站独立 package.json / next.config / tailwind / messages / .env / 构建 - src/app 约 56 个薄路由文件（re-export 底座页面 + 内联路由段配置 revalidate/dynamic） - src/site/brand.tsx 站点配置 + src/site/home.tsx 站点首页（createMarketingLayout / createHomePage 工厂） - generate-site.mjs: 站点生成器（新增网站 = SITES 加条目，零 Core 修改） - start-all-sites.sh: 一键启动 3001-3005 - next-config.mjs: 底座统一 Next 配置工厂（next-intl + MDX + standalone） - 五站共享同一套 PostgreSQL / Better Auth / Admin（设计文档 §42） - 验证: 5 站 build OK / typecheck OK / 55 路由冒烟 200 / 品牌-内容-截图差异确认 / 登录-投票-重复检测 e2e PASS
2026-09-08 19:19:33 +00:00
parent e46b4b52a3
commit 4a1a034386
699 changed files with 19829 additions and 2029 deletions
@@ -0,0 +1,217 @@
+# AI Directory Platform — 交付报告
+
+> 基于 `coolchange-ai/toolso-ai-open` 二次开发的可复用 AI Directory 基础底座，
+> 按《AI-Directory-Platform开发计划与技术设计文档》完成 MVP + V1 核心能力，
+> 并以 **五套不同 UI 的完整站点** 完成底座「快速、易用、可用、可靠」验证。
+
+- 代码位置：`AI-Directory-Platform/packages/core/`（底座库）+ `AI-Directory-Platform/sites/`（5 个独立网站）
+- 技术栈：Next.js 16 · React 19 · TypeScript · Tailwind CSS · PostgreSQL + Drizzle ORM · Better Auth · next-intl
+- 验证状态：**typecheck 0 错误 · bun test 32/32 通过 · 5 套主题全部构建成功 · 端到端交互测试 PASS**
+
+---
+
+## 一、仓库结构（monorepo）
+
+```
+AI-Directory-Platform/
+├── packages/core/          # @aidir/core —— AI Directory 底座库
+│   ├── src/pages/          #   全部页面组件体（1:1 镜像路由树）
+│   ├── src/kit/            #   站点外壳工厂（Header/Footer/chrome/首页数据）
+│   ├── src/lib|features/   #   ranking/seo/analytics/voting/reviews/... 全部业务
+│   ├── content/blog/       #   MDX 文章
+│   ├── messages/           #   基础文案（en/zh，546 键）
+│   └── scripts/            #   db/seed/生成器/启动器/e2e
+└── sites/                  # 5 个独立 Next.js 网站（各自 package.json/构建/部署）
+    ├── ai-stack/           #   AI Stack —— Classic 目录        :3001
+    ├── launchai/           #   LaunchAI —— Product Hunt 式      :3002
+    ├── the-ai-ledger/      #   The AI Ledger —— Editorial 媒体  :3003
+    ├── devai-tools/        #   DevAI.tools —— 开发者垂直        :3004
+    └── findai/             #   findai —— 极简搜索              :3005
+```
+
+每个站点应用只有三类自己的代码：
+1. `src/site/brand.tsx` —— 品牌/导航/页脚/SEO 文案（SiteConfig）
+2. `src/site/home.tsx` —— 站点首页组件
+3. `src/app/**` —— 薄路由（约 56 个文件，全部为 re-export 底座页面组件 + 内联路由段配置）
+
+**站点之间零重复业务代码**；新增第 6 个网站 = 在生成器 `SITES` 里加一个条目并运行
+`bun packages/core/scripts/generate-site.mjs <key>`，零 Core 代码修改。
+
+## 一'、快速开始
+
+```bash
+cd AI-Directory-Platform
+
+bun install                          # workspace 安装（root 一次）
+
+# 数据库（五个网站共享同一套 PostgreSQL —— 设计文档 §42）
+cd packages/core && cp .env.example .env.local && bun run db:push && bun run seed:platform && cd ../..
+
+# 构建 5 个网站（构建时数据库需在线；构建期间不要运行站点，避免连接数耗尽）
+for s in ai-stack launchai the-ai-ledger devai-tools findai; do (cd sites/$s && cp -n .env.example .env.local && bun run build); done
+
+# 一键启动（或分别 cd sites/<name> && bun run start）
+bash packages/core/scripts/start-all-sites.sh
+
+# 质量
+bun test packages/core/tests         # 32 个单元测试
+bun run typecheck                    # core + 5 站全部 0 错误
+```
+
+演示账号（种子内置，密码均为 `password123`）：
+
+| 账号 | 角色 |
+| --- | --- |
+| `admin@aidirectory.dev` | 管理员（可访问 `/admin` 全部后台） |
+| `alice@demo.dev` 等 5 个 | 普通用户 |
+
+---
+
+## 二、与设计文档验收标准对照
+
+### UI（§74）
+
+| 要求 | 状态 |
+| --- | --- |
+| 所有图标 SVG / Lucide，无 Emoji、Unicode 图标、字符箭头 | ✅ 全部使用 `lucide-react`；种子分类 icon 置空；唯一例外是种子工具名 "DALL·E 3" 的 `·` 为产品名本身 |
+| Responsive（375/768/1280/1440 实测截图） | ✅ Mobile First，Header 移动端汉堡抽屉 + 搜索 |
+| Light/Dark/System | ✅ 继承底座 next-themes，全组件适配 |
+
+### Functional（§74 / MVP §57）
+
+| 要求 | 实现位置 |
+| --- | --- |
+| Google Login | ✅ 底座已有（env 门控） |
+| GitHub Login | ✅ `src/lib/auth.ts`（env 门控）+ 登录页按钮 |
+| Vote | ✅ `src/features/voting/`（登录投票、原子 toggle、滑动窗口限流 40 次/10min、乐观 UI、`/api/tools/:id/vote`） |
+| Favorite | ✅ 底座已有 |
+| Review | ✅ `src/features/reviews/`（评分/优缺点/使用场景/Helpful/每用户一条/聚合评分回写） |
+| Submit | ✅ `src/features/submission/`（提交 → Admin 审批自动发布 → 域名重复检测） |
+| Claim | ✅ `src/features/claim/`（认领申请 → 审批 → Owner 徽标 + 白名单字段编辑 `ownerUpdateTool`） |
+| Search | ✅ `/api/search`（PostgreSQL 多维 ILIKE + 热度排序 + search 埋点） |
+| Filter | ✅ 分类 / 定价 / Use Case / Audience / 排序（最新、最热） |
+| Ranking | ✅ `src/lib/ranking/`（七个榜单 + Ranking Engine 独立） |
+
+### SEO（§74 / §23 / §24 / §52）
+
+| 要求 | 实现 |
+| --- | --- |
+| SSR / ISR | ✅ 全站 RSC + ISR（1h）+ 变更 revalidatePath |
+| Metadata / Canonical / hreflang | ✅ `src/lib/metadata.ts`（继承底座） |
+| Sitemap | ✅ `src/app/sitemap.ts` 扩展至 270 条：工具 / 分类 / 用例 / 受众 / 合集 / Top20 Alternatives / 对比页 |
+| Schema | ✅ SoftwareApplication(+AggregateRating) / Review 数据 / FAQPage / BreadcrumbList / ItemList / CollectionPage / WebSite / Organization |
+| Programmatic SEO | ✅ `src/lib/seo/page-generator.ts`：由实体真实数据生成 Title/H1/Intro/FAQ（避免低质模板页：Alternatives/Comparison 只为 Top 工具生成） |
+| 内链系统 | ✅ Tool ↔ Category ↔ Use Case ↔ Audience ↔ Alternatives ↔ Best ↔ Blog 的 SEO Graph |
+
+### Performance（§47）
+
+Server Components First、ISR、`next/image`、分页、数据库索引（vote/rating/domain 等 7 个新索引）。构建产物静态化率见构建输出（SSG 为主，交互 API 为 ƒ）。
+
+### Security（§74）
+
+RBAC（`requireAdmin`/`isAdmin`）、Zod 全量输入校验、投票限流 + pending 唯一索引防重、认领 pending 唯一约束、Vote Audit 审计页（用户/IP/来源/速度告警）、外链 `nofollow` + 跳转埋点。
+
+---
+
+## 三、底座架构（Core 与 Site 分离）
+
+```
+src/
+├── lib/
+│   ├── ranking/          # Ranking Engine（score.ts 纯函数 + queries.ts SQL + boards.ts）
+│   ├── seo/              # Programmatic SEO 页面生成器
+│   ├── analytics/        # 事件埋点（recordEvent/recordToolView）
+│   ├── tools/duplicate.ts# 重复工具检测（域名归一化/slug/名称）
+│   └── db/schema/        # community(投票/评论/提交/认领) discovery(用例/受众/合集) analytics(事件)
+├── features/             # Feature-First：voting / reviews / submission / claim / discovery / alternatives
+├── themes/               # ★ Site Theme 层：registry + chrome + shared + 5 套主题
+│   ├── classic/          # AI Stack —— 专业目录（Clean/Dense/Professional）
+│   ├── product/          # LaunchAI —— Product Hunt 式每日发布社区
+│   ├── editorial/        # The AI Ledger —— 媒体型（Featured Story/编辑精选/购买指南）
+│   ├── niche/            # DevAI.tools —— 垂直（AI for Developers，终端风 Hero）
+│   └── minimal/          # findai —— 极简搜索引擎（一个框 + 热门搜索）
+└── app/[locale]/         # 路由：/tools /rankings /best /ai-tools-for /submit /admin/* /api/*
+```
+
+**五套站点 = 同一套数据库、认证、Admin、Tool 模型、Vote/Review、Ranking、Search、SEO、Analytics**，
+只改变 Theme/Layout/Navigation/Content/Brand —— 即设计文档 §42 的验证标准。新增第 6 个站点只需
+在 `src/themes/` 增加一个目录并注册 registry，**零 Core 代码修改**。
+
+主题在**构建时**注入（`SITE_THEME=<id> NEXT_DIST_DIR=.next-<id> bun run build`），
+一次构建对应一个站点部署，SSG/ISR 性能不受影响。
+
+---
+
+## 四、五个网站验证结论（§41 / 最终要求）
+
+| 网站 | 目录 | 端口 | 定位 | 首页形态 |
+| --- | --- | --- | --- | --- |
+| AI Stack | sites/ai-stack | 3001 | 标准目录 | Hero 搜索 + Trending/分类/新工具/用例/合集/评论 |
+| LaunchAI | sites/launchai | 3002 | 产品社区 | 今日发布 Feed + 大投票块 + Leaderboard 侧栏 |
+| The AI Ledger | sites/the-ai-ledger | 3003 | AI 媒体 | Featured Story + 编辑精选 + 购买指南 + 社区引语 |
+| DevAI.tools | sites/devai-tools | 3004 | 开发者垂直 | 终端风 Hero + 工作流/用例/技术栈 |
+| findai | sites/findai | 3005 | 极简搜索 | 居中大搜索框 + 热门搜索 + Trending |
+
+验证结果：**5 个网站是 5 个独立 Next.js 应用**（独立 package.json、独立 .next 构建、独立进程/端口），
+共享同一套 PostgreSQL / Better Auth / Admin（§42 验证标准）。站点间零 `if site === "xxx"` 分支；
+每站均通过构建、11 条路由 × 5 站 = 55 项 200 冒烟、1440/390 双断点截图、控制台 0 报错、
+登录→投票（DB 3→4→3）→重复提交检测 e2e PASS。
+
+---
+
+## 五、端到端验证记录
+
+| 验证项 | 结果 |
+| --- | --- |
+| 19 条核心路由冒烟（含 zh、sitemap、search API、outbound 307 跳转） | ✅ 全部 200 |
+| JSON-LD（SoftwareApplication+AggregateRating/FAQPage/Breadcrumb/ItemList） | ✅ 详情页实测输出 |
+| Sitemap 270 条（含用例/受众/合集/alternatives/vs） | ✅ |
+| 登录（alice@demo.dev）→ 投票 toggle（DB 3→4→3，按钮同步） | ✅ PASS |
+| 重复提交检测（提交 chatgpt.com 被拦截并列出已有工具） | ✅ PASS |
+| 评论表单（已有评论回显编辑模式、星级、优缺点） | ✅ 截图验证 |
+| 五主题品牌/版式差异化（AI Stack/LaunchAI/The AI Ledger/DevAI.tools/findai） | ✅ 截图验证 |
+| `bun test`（ranking 评分/贝叶斯/路由解析/域名归一化/SEO 生成器） | ✅ 32/32 |
+| `bun run typecheck` | ✅ 0 错误 |
+| `bun run build` × 5 主题 | ✅ 全部成功 |
+
+截图存档：`/tmp/aidir-shots/`（16 张，含移动端 390×844）。
+
+---
+
+## 六、API 一览（§45）
+
+```
+POST/DELETE /api/tools/:id/vote     投票/取消（登录，限流）
+GET        /api/search?q=           PostgreSQL 搜索（含埋点）
+GET        /api/outbound?tool=slug  外链跳转 + tool_click 埋点 + 计数
+GET        /api/tools（列表查询走 server actions：getPublishedTools 支持 category/pricing/usecase/audience/sort）
+POST       /api/auth/[...all]       Better Auth（邮箱密码 + Google + GitHub）
+```
+
+提交/认领/评论/收藏走 Server Actions（`features/*/actions.ts`），与 REST 共存。
+
+---
+
+## 七、事件与分析（§37/§38）
+
+`event` 表统一采集 10 类事件：`tool_view / tool_click / tool_vote / tool_unvote / tool_favorite /
+tool_review / tool_share / search / category_view / submit_tool / claim_tool`。
+详情页浏览与外链点击自动同步 `tool.viewCount/clickCount` 冗余列；
+`/admin/analytics` 输出近 30 天事件总量、工具 CTR 排行（views≥10）、热门搜索词。
+
+---
+
+## 八、已知边界与后续（V2 路线）
+
+1. **主题文案 i18n**：五套主题的 Brand 文案当前为英文（品牌层）；核心页面（工具/榜单/表单/后台）中英双语完整。后续可把主题文案迁入 `messages/<locale>.json`。
+2. **OAuth 凭据**：Google/GitHub 登录需在生产配置真实 Client ID/Secret（env 门控，缺省自动隐藏按钮）。
+3. **V2 待办**（按设计文档 §59）：Meilisearch 语义搜索、AI 推荐、自动分类、爬虫导入、Monetization 层。
+4. **评论可信度**（§19）：已实现 Verified User（邮箱认证徽标）+ Helpful 投票；Verified Usage/Purchase 留待 V2。
+5. 上游遗留兼容性升级：framer-motion 11→12（本次已升级以修复 React 19 类型）。
+
+---
+
+## 九、Git 状态
+
+全部改动已在 `core/` 仓库本地提交（见 `git log`），上游远程 `origin` 保留，
+可随时 diff 审查或推送 fork。