# 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

# 注意：构建期间数据库需在线，且不要同时运行站点（Next 构建 worker 会占满 PG 连接）
# 注意：修改 .env 后需 rm -rf .next 再构建（Turbopack 构建缓存不感知 env 变化）

# 质量
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 | https://ai-stack.opentest.cc | 3001 | 标准目录 | Hero 搜索 + Trending/分类/新工具/用例/合集/评论 |
| LaunchAI | sites/launchai | https://launchai.opentest.cc | 3002 | 产品社区 | 今日发布 Feed + 大投票块 + Leaderboard 侧栏 |
| The AI Ledger | sites/the-ai-ledger | https://the-ai-ledger.opentest.cc | 3003 | AI 媒体 | Featured Story + 编辑精选 + 购买指南 + 社区引语 |
| DevAI.tools | sites/devai-tools | https://devai-tools.opentest.cc | 3004 | 开发者垂直 | 终端风 Hero + 工作流/用例/技术栈 |
| findai | sites/findai | https://findai.opentest.cc | 3005 | 极简搜索 | 居中大搜索框 + 热门搜索 + Trending |

**域名与部署**：五个子域名经 `ldns` 配置 Cloudflare DNS（Proxied）+ Nginx 反向代理
（`/etc/nginx/conf.d/<site>.conf` → 127.0.0.1:300X）；各站点 `.env.local` 的
`NEXT_PUBLIC_APP_URL` / `BETTER_AUTH_URL` 指向各自 https 域名，
canonical / sitemap / JSON-LD / OAuth 回调输出均为线上域名。

验证结果：**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。