项目结构
代码库布局和关键目录概览。
目录概览
├── app/[locale]/ # 使用 next-intl 语言段的 Next.js App Router 路由
│ ├── (marketing)/ # 首页、定价、博客和法律页面
│ ├── (protected)/ # 登录后页面：设置和积分
│ ├── (admin)/admin/ # 管理后台、用户、订阅和积分账本
│ ├── (tools)/tools/ # 登录后 AI 工具工作区页面
│ └── docs/ # Fumadocs 文档路由
├── app/api/ # Route Handlers
│ ├── auth/ # Firebase session API
│ ├── payments/stripe/ # Stripe checkout、webhook 和重定向 fallback
│ ├── upload/ # 用户上传端点
│ ├── admin/ # 管理员变更 API
│ ├── user/ # 用户资料、积分和管理员状态 API
│ └── cron/ # 订阅积分发放和积分过期定时任务
├── features/ # 产品功能模块
│ ├── admin/ # 管理后台 UI、actions、服务端查询和变更
│ ├── ai-tools/ # AI 工具 actions、UI、历史记录和服务端工作流
│ ├── auth/ # 全局登录弹窗、认证 UI 和 Firebase session 辅助逻辑
│ ├── blog/ # Blog source loader 和 blog 专属组件
│ ├── docs/ # Fumadocs source、metadata、i18n 和布局辅助逻辑
│ ├── landing/ # 营销页区块
│ └── user-console/ # 设置、积分页面、用户资料 API 支撑和查询
├── modules/ # 可复用领域模块
│ ├── analytics/ # 分析组件组合入口
│ ├── ai-tools/ # 共享 AI 工具 schema 和类型化 payload
│ ├── auth/ # Firebase session、用户同步和管理员授权
│ ├── billing/ # 计费展示和订阅积分发放计划辅助逻辑
│ ├── client-api/ # 与浏览器客户端共享的 DTO
│ ├── credits/ # 积分账本变更和失败补偿退款
│ ├── upload/ # 用户文件和图片上传服务端逻辑
│ └── db/ # Drizzle 客户端和 schema
├── extensions/ # 第三方适配器
│ ├── analytics/google/ # Google Analytics 组件
│ ├── ai/volcengine/ # 火山引擎 OpenAI-compatible AI provider adapter
│ ├── auth/firebase/ # Firebase client/admin SDK 适配器
│ ├── email/ # 隐藏 provider 的邮件封装、模板和适配器
│ ├── payment/stripe/ # Stripe checkout 和 webhook 入账逻辑
│ └── storage/ # 隐藏 provider 的存储门面，包含 R2 和 S3 兼容适配器
├── components/ # 全局 UI：品牌、布局、共享内容辅助组件和基础组件
├── constants/ # 计费和网站配置
├── content/blog/ # 博客源内容（MDX）
├── content/docs/ # 文档源内容（MDX）
├── messages/ # UI 和 SEO 翻译（en、zh）
├── public/ # 公共图片、logos、robots.txt 和生成的 docs CSS
├── scripts/ # 本地维护和生成脚本
└── drizzle/ # Drizzle 迁移文件路由分组
| 分组 | 路径 | 访问权限 | 用途 |
|---|---|---|---|
(marketing) | /、/pricing、/blog、法律页面 | 公开 | 营销和 SEO 页面 |
(protected) | /credits、/settings | 需要登录 | 用户控制台 |
(tools) | /tools、/tools/xiaohongshu | 需要登录 | AI 工具工作区 |
(admin) | /admin、/admin/users、/admin/subscriptions、/admin/credits | 管理员 | 管理面板 |
docs | /docs/*、/zh/docs/* | 公开 | 文档 |
边界规则
- App 路由保持轻量：解析参数或请求体，然后调用 feature/server 或 module 代码。
- Client Components 可以导入 feature actions、feature UI、共享组件、共享类型和客户端安全的辅助函数。
- Client Components 不应导入
features/*/server、modules/db、modules/credits、提供商适配器、支付适配器、邮件适配器或存储适配器。 - 后端模块不应导入 React 组件。
- API route 应使用
defineApiHandler(...)，并且必须在modules/auth/api-policy.ts中声明，除非该 route 明确需要自定义协议处理。 - 这些边界由
eslint.config.mjs强制执行；新增模块或例外前请先阅读开发规范。
关键文件
| 文件 | 用途 |
|---|---|
extensions/auth/firebase/client.ts | 浏览器侧 Firebase 初始化 |
extensions/auth/firebase/admin.ts | Firebase provider adapter 使用的底层 Firebase Admin 初始化 |
extensions/auth/firebase/provider.ts | auth provider 接口的 Firebase 实现 |
modules/auth/client.ts | 浏览器侧 Firebase Google 登录和会话辅助函数 |
modules/auth/action-handler.ts | Server Action 的标准 wrapper，统一 user/admin 鉴权 |
modules/auth/access-cache.ts | 本地 auth access 字段的可替换缓存 store |
modules/auth/provider.ts | 应用侧 auth provider 接口和当前 provider 绑定 |
modules/auth/api-handler.ts | API route 的标准 wrapper，统一鉴权、locale 和错误响应 |
modules/auth/api-policy.ts | 每个 app/api route 的显式鉴权策略清单 |
modules/auth/session.ts | Session cookie 解析、本地 access cache 和缓存失效 |
modules/auth/user-sync.ts | Provider 身份到本地用户的同步逻辑 |
modules/auth/index.ts | 服务端认证、会话和管理员导出 |
modules/db/schema.ts | Drizzle schema 的事实来源 |
modules/ai-tools/xiaohongshu.ts | AI 文案生成器的共享输入/输出 schema |
modules/credits/ledger.ts | 积分余额和账本变更 |
modules/credits/compensation.ts | 失败后退款补偿辅助逻辑 |
modules/upload/file.ts | 用户文件和图片上传验证和存储写入 |
constants/billing.ts | 订阅计划 key、价格、积分额度和 Stripe Price ID |
extensions/analytics/google/ | Google Analytics 集成 |
extensions/ai/volcengine/ | AI 工具生成使用的火山引擎 provider adapter |
extensions/payment/stripe/ | Stripe checkout、签名验证、webhook service 和入账逻辑 |
extensions/storage/ | 隐藏 provider 的存储门面，包含 Cloudflare R2 和 S3 兼容适配器 |
features/auth/components/auth-modal-provider.tsx | 全局 Google 登录弹窗和 ?auth=login 处理 |
lib/client-api/use-api-fetch.ts | 浏览器 API fetch hook，统一 locale header 和标准错误 toast |
features/blog/source.ts | 读取 content/blog MDX 文章的 blog manifest loader |
features/blog/components/ | Blog card 和 blog layout 组件 |
features/docs/source.ts | 读取生成的 .source/server 输出的 Fumadocs loader |
source.config.ts | Fumadocs MDX 源配置 |
proxy.ts | 用于语言路由的 Next.js proxy |
i18n.config.ts | 语言区域配置 |