From 90ed0636f44056fec3a71cb5c1e989a0977a1556 Mon Sep 17 00:00:00 2001 From: "CoolChange.AI" Date: Fri, 31 Jul 2026 19:43:03 -0700 Subject: [PATCH] =?UTF-8?q?docs:=20README=20=E4=B8=8E=20CLAUDE.md=20?= =?UTF-8?q?=E6=9B=B4=E6=96=B0=EF=BC=8C=E4=B8=8E=E5=AE=9E=E9=99=85=E5=AE=9E?= =?UTF-8?q?=E7=8E=B0=E5=AF=B9=E9=BD=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 特性表新增收藏与 Newsletter，数据库架构章节重写为真实表结构 - 脚本清单补 typecheck / i18n:check / seed:tools，部署章节补 Docker Compose 实操步骤 - 国际化章节修正路由前缀说明（en 默认无前缀），如实说明工具数据为双语列 - 新增 Roadmap 章节（工具提交与审核、评分评论、数据采集管线） Co-Authored-By: Claude Fable 5 --- CLAUDE.md | 54 ++++++++++++++++++++++--------------- README.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++++------- 2 files changed, 102 insertions(+), 32 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 04d98f2..22330ad 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,11 +7,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co 这是一个**开源的 AI 工具导航站 (Toolso.AI)**，帮助用户发现和探索各类优秀的 AI 工具。基于 Next.js 16 构建，拥有现代化的响应式界面、强大的搜索和筛选功能、多语言支持。 **核心特性**: -- AI 工具目录 (分类展示、搜索筛选、工具详情) -- 工具提交 (用户可提交新工具，社区驱动) -- 管理后台 (工具审核、用户管理、角色权限) +- AI 工具目录 (分类展示、搜索筛选、定价筛选、工具详情、分类落地页) +- 用户收藏 (工具卡片/详情页收藏，仪表盘查看) +- 管理后台 (工具 CRUD、用户管理、分类/标签管理) - 博客系统 (MDX 驱动，AI 资讯和教程) -- 国际化支持 (中文/英文) +- Newsletter (页脚订阅 + Resend Audience 同步 + 退订) +- 国际化支持 (中文/英文，`pnpm i18n:check` 校验键一致性) - 用户认证 (Better Auth + Google OAuth) ## 技术栈 @@ -82,25 +83,32 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## 数据库架构 -当前包含 6 个核心表： +当前包含 12 个表： ```sql --- 用户表 -user (id, name, email, emailVerified, image, role, banned, banReason, banExpires, createdAt, updatedAt) - --- 认证表 -session (id, expiresAt, token, createdAt, updatedAt, ipAddress, userAgent, userId) +-- 认证模块 (src/lib/db/schema/auth.ts) +user (id, name, email, emailVerified, image, role, banned, banReason, banExpires, ...) +session (id, expiresAt, token, ipAddress, userAgent, userId, ...) account (id, accountId, providerId, userId, accessToken, refreshToken, password, ...) +verification (id, identifier, value, expiresAt, ...) -- 邮箱验证 + 密码重置令牌均存于此 --- 验证表 -verification (id, identifier, value, expiresAt, createdAt, updatedAt) -passwordResetToken (id, userId, token, expiresAt, createdAt) +-- 工具模块 (src/lib/db/schema/tool.ts) +tool (id, slug, domain, websiteUrl, coverImageUrl, logoUrl, nameEn/Zh, descriptionEn/Zh, + pricing, featured, viewCount, status, ...) + -- status: draft | published + -- pricing: free | freemium | paid +category (id, slug, icon, sortOrder, nameEn/Zh, descriptionEn/Zh, ...) +tag (id, slug, nameEn/Zh, ...) +tool_category (toolId, categoryId) -- 多对多 +tool_tag (toolId, tagId) -- 多对多 +favorite (userId, toolId, createdAt) -- 用户收藏，联合主键 --- 其他 -newsletterSubscription (id, email, userId, status, unsubscribeToken, subscribedAt, ...) +-- 营销模块 (src/lib/db/schema/marketing.ts) +newsletter_subscription (id, email, userId, status, unsubscribeToken, subscribedAt, ...) +contact_message (id, name, email, company, message, createdAt) ``` -完整 Schema 定义: `src/lib/db/schema.ts` +Schema 汇出入口: `src/lib/db/schema.ts` ## 常用开发命令 @@ -115,7 +123,9 @@ pnpm build pnpm start # 代码检查 -pnpm lint +pnpm lint # ESLint 9 (flat config) +pnpm typecheck # tsc --noEmit +pnpm i18n:check # 翻译键一致性检查 # 数据库操作 pnpm db:generate # 生成 Drizzle 迁移文件 @@ -125,6 +135,7 @@ pnpm db:studio # 启动 Drizzle Studio 数据库管理界面 # 管理员工具 pnpm admin:setup # 创建管理员账户 +pnpm seed:tools # 导入工具种子数据（50 工具/10 分类/30 标签） # 博客清单生成 pnpm generate:blog-manifest @@ -197,7 +208,7 @@ NEXT_PUBLIC_CLARITY_PROJECT_ID="..." ### 密码重置流程 1. 用户输入邮箱 -2. 生成重置令牌存入 `passwordResetToken` 表 +2. 生成重置令牌存入 `verification` 表（identifier 带 reset 前缀） 3. 发送重置邮件 4. 用户点击链接设置新密码 @@ -206,10 +217,9 @@ NEXT_PUBLIC_CLARITY_PROJECT_ID="..." 管理员权限通过 `user.role = 'admin'` 标识。 **功能**: -- 用户列表和搜索 -- 查看用户详情 -- 修改用户角色 -- 禁用/解禁用户 +- 用户列表和搜索、查看详情、修改角色、禁用/解禁 +- 工具 CRUD、上下架、精选标记 +- 分类与标签管理 **创建管理员账户**: ```bash diff --git a/README.md b/README.md index 4b034e8..96b1c1d 100644 --- a/README.md +++ b/README.md @@ -33,8 +33,9 @@ Toolso.AI is an open-source AI tools directory designed to help users discover t |---------|-------------|----------| | **AI Tools Directory** | Categorized AI tools listing | Easy discovery and exploration | | **Search & Filter** | Powerful search with category filters | Find the right tool quickly | -| **Tool Submission** | User-contributed tool submissions | Community-driven content | -| **Admin Panel** | Tool & user management | Approve submissions, manage content | +| **Admin Panel** | Tool & user management | Manage content with ease | +| **Favorites** | Save tools to your personal collection | Sign in and build your toolbox | +| **Newsletter** | Footer subscription backed by Resend | Grow your audience | | **Blog System** | MDX-powered multilingual blog | SEO-optimized AI insights | | **i18n** | next-intl internationalization | English & Chinese out of the box | | **Authentication** | Better Auth + Google OAuth | User accounts and submissions | @@ -64,6 +65,12 @@ cp .env.example .env.local # Push database schema pnpm db:push +# (Optional) Seed 50 AI tools, 10 categories and 30 tags +pnpm seed:tools + +# (Optional) Create an admin account +pnpm admin:setup + # Start development server pnpm dev ``` @@ -147,13 +154,16 @@ scripts/ # Build & admin scripts pnpm dev # Start development server pnpm build # Build for production pnpm start # Start production server -pnpm lint # Run ESLint +pnpm lint # Run ESLint (flat config) +pnpm typecheck # Run TypeScript type check +pnpm i18n:check # Verify translation key consistency # Database pnpm db:generate # Generate Drizzle migrations pnpm db:migrate # Run migrations pnpm db:push # Push schema to database pnpm db:studio # Open Drizzle Studio +pnpm seed:tools # Seed AI tools data # Admin pnpm admin:setup # Create admin account @@ -171,12 +181,23 @@ pnpm generate:blog-manifest # Generate blog manifest 3. Add environment variables 4. Deploy +### Docker + +```bash +# Start PostgreSQL + app +docker compose up -d --build + +# Initialize database (run from host) +DATABASE_URL=postgresql://toolso:toolso@localhost:5432/toolso pnpm db:push +DATABASE_URL=postgresql://toolso:toolso@localhost:5432/toolso pnpm seed:tools +DATABASE_URL=postgresql://toolso:toolso@localhost:5432/toolso pnpm admin:setup +``` + ### Other Platforms The template works with any platform supporting Node.js: - Railway - Render -- Docker - Self-hosted ### Deployment Checklist @@ -192,8 +213,9 @@ The template works with any platform supporting Node.js: The template supports multiple languages via `next-intl`: - **Supported**: English (`en`), Chinese (`zh`) -- **Route Format**: `/en/...`, `/zh/...` +- **Route Format**: English is the default locale without prefix (`/...`), Chinese uses `/zh/...` (`localePrefix: 'as-needed'`) - **Translation Files**: `messages/en.json`, `messages/zh.json` +- **Consistency Check**: `pnpm i18n:check` ### Adding a New Language @@ -201,6 +223,14 @@ The template supports multiple languages via `next-intl`: 2. Translate the content 3. Update `i18n.config.ts` +> Note: UI copy is fully translatable via JSON files, but tool/category/tag **data** is stored as bilingual columns (`nameEn`/`nameZh`) in the database. Adding a third content language requires extending the schema and queries. + +## Roadmap + +- [ ] User tool submission with review workflow +- [ ] Tool ratings & comments +- [ ] Automated tool data import pipeline + ## Contributing We welcome contributions! Please feel free to submit a Pull Request. @@ -229,8 +259,9 @@ Toolso.AI 是一个开源的 AI 工具导航站，旨在帮助用户发现各类 |------|------|------| | **AI 工具目录** | 分类展示 AI 工具 | 轻松发现和探索 | | **搜索与筛选** | 强大的搜索和分类筛选 | 快速找到合适的工具 | -| **工具提交** | 用户可提交新工具 | 社区驱动内容 | -| **管理后台** | 工具和用户管理 | 审核提交、管理内容 | +| **管理后台** | 工具和用户管理 | 轻松管理内容 | +| **收藏功能** | 登录用户可收藏工具 | 打造个人工具箱 | +| **Newsletter** | 页脚订阅（基于 Resend） | 沉淀你的用户 | | **博客系统** | MDX 驱动的多语言博客 | SEO 优化的 AI 资讯 | | **国际化** | next-intl 国际化 | 中英文开箱即用 | | **身份认证** | Better Auth + Google OAuth | 用户账户和提交功能 | @@ -260,6 +291,12 @@ cp .env.example .env.local # 推送数据库结构 pnpm db:push +# （可选）导入 50 个 AI 工具、10 个分类、30 个标签种子数据 +pnpm seed:tools + +# （可选）创建管理员账户 +pnpm admin:setup + # 启动开发服务器 pnpm dev ``` @@ -343,13 +380,16 @@ scripts/ # 构建和管理脚本 pnpm dev # 启动开发服务器 pnpm build # 构建生产版本 pnpm start # 启动生产服务器 -pnpm lint # 运行 ESLint +pnpm lint # 运行 ESLint（flat config） +pnpm typecheck # TypeScript 类型检查 +pnpm i18n:check # 校验翻译键一致性 # 数据库 pnpm db:generate # 生成 Drizzle 迁移 pnpm db:migrate # 运行迁移 pnpm db:push # 推送 schema 到数据库 pnpm db:studio # 打开 Drizzle Studio +pnpm seed:tools # 导入工具种子数据 # 管理员 pnpm admin:setup # 创建管理员账户 @@ -367,12 +407,23 @@ pnpm generate:blog-manifest # 生成博客清单 3. 添加环境变量 4. 部署 +### Docker + +```bash +# 启动 PostgreSQL + 应用 +docker compose up -d --build + +# 初始化数据库（在宿主机执行） +DATABASE_URL=postgresql://toolso:toolso@localhost:5432/toolso pnpm db:push +DATABASE_URL=postgresql://toolso:toolso@localhost:5432/toolso pnpm seed:tools +DATABASE_URL=postgresql://toolso:toolso@localhost:5432/toolso pnpm admin:setup +``` + ### 其他平台 模板支持任何支持 Node.js 的平台： - Railway - Render -- Docker - 自托管 ### 部署清单 @@ -388,8 +439,9 @@ pnpm generate:blog-manifest # 生成博客清单 模板通过 `next-intl` 支持多语言： - **已支持**: 英文 (`en`)、中文 (`zh`) -- **路由格式**: `/en/...`、`/zh/...` +- **路由格式**: 英文为默认语言不带前缀（`/...`），中文为 `/zh/...`（`localePrefix: 'as-needed'`） - **翻译文件**: `messages/en.json`、`messages/zh.json` +- **一致性检查**: `pnpm i18n:check` ### 添加新语言 @@ -397,6 +449,14 @@ pnpm generate:blog-manifest # 生成博客清单 2. 翻译内容 3. 更新 `i18n.config.ts` +> 注意：UI 文案可完全通过 JSON 文件翻译，但工具/分类/标签的**数据**在数据库中以双语列（`nameEn`/`nameZh`）存储。新增第三种内容语言需要扩展 schema 和查询。 + +## Roadmap + +- [ ] 用户工具提交与审核工作流 +- [ ] 工具评分与评论 +- [ ] 自动化工具数据采集管线 + ## 贡献指南 欢迎贡献！请随时提交 Pull Request。