ai-directory-platform/docs/交付报告.md

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 代码修改。

一'、快速开始

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。