226 lines
12 KiB
Markdown
226 lines
12 KiB
Markdown
# 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。
|