功能特性

本文档详细列出了 Hex2077 启动模板中已集成的核心功能模块及其实现细节，方便开发者了解系统能力并进行扩展。

认证与安全系统

基于 Better Auth 构建，提供全套用户账号管理功能。

• 多登录方式: 支持 邮箱/密码 登录以及 OAuth (GitHub, Google) 社交登录
• 自动化钩子:
  • Before Hook: 拦截非法的注册请求（如指纹冲突）、校验密码强度、检查登录尝试次数
  • After Hook: 记录登录日志、关联用户指纹、发送欢迎邮件
• 安全特性:
  • 登录失败锁定: 超过配置的失败次数后暂时封禁 IP 或账号
  • 注册指纹保护: 结合浏览器指纹技术，防止恶意机器人批量注册
  • Turnstile 集成: 登录/注册页面支持 Cloudflare Turnstile 验证码

支付与订阅系统

采用策略模式支持多支付网关，对外提供统一的订阅模型。

• 多网关支持: 预集成 Stripe 和 Creem，通过 GatewayFactory 动态切换
• 订阅周期管理:
  • 支持 月付 (Monthly) 和 年付 (Yearly) 计划
  • 自动化处理 订阅创建、更新（升/降级）、取消
• Webhook 归一化: 统一处理各网关的 Webhook 通知，确保数据库状态与支付网关实时同步
• 用户门户: 集成网关原生的客户门户，允许用户自行管理账单、支付方法和订阅

积分系统

一套灵活的虚拟货币模型，支持消费与补给。

• 积分类型:
  • Paid Credits: 通过购买积分包或订阅奖励获得，通常不设有效期
  • Free Credits: 系统赠送或促销获得，支持设置有效期，消费时优先扣除
• 补给模型:
  • 订阅赠送: 用户订阅特定计划后，每月或每年自动发放积分
  • 一次性购买: 独立的积分包购买流程
• 消费逻辑: 接口级原子扣费，支持并发保护

管理后台

为运营人员提供的全功能管理工具。

• 数据概览: 关键业务指标（收入、用户增长、积分消耗）的可视化统计
• 用户与权限管理:
  • 用户列表查询、详情查看、状态封禁
  • 灵活的角色 (Role) 与权限 (Permission) 系统
• 业务操作:
  • 订阅管理: 查看所有用户的订阅详情，手动触发退款或调整
  • 积分干预: 管理员可手动为指定用户增加或扣除积分
• 系统设置:
  • 动态配置 支付网关开关、邮件服务参数、安全校验策略
  • 维护模式开关
• 日志审计: 详细记录所有管理员的敏感操作，支持日志自动清理

AI 能力集成

基于 LangChain 构建的多模态 AI 服务层，支持对话、图像生成和视频生成。

LangChain 服务架构

• 多提供商支持: 统一封装 OpenAI、Anthropic、Google Gemini、OpenRouter 等主流 LLM 提供商
• 模型覆盖:
  • OpenAI: GPT-5 系列、GPT-4.1、o3 推理模型等
  • Anthropic: Claude 4.5 系列（Opus/Sonnet/Haiku）
  • Google: Gemini 3/2.5 系列
  • OpenRouter: 聚合多家提供商，支持 DeepSeek、Meta Llama 4、Mistral 等开源模型
• 核心能力:
  • 流式输出 (Streaming)
  • Token 计数与用量统计
  • 自定义 API Base URL（支持代理）
  • Agent 工具调用与记忆管理
  • 文本嵌入 (Embedding) 与文档分割

AI 对话

AI 图像生成

AI 视频生成

博客系统

基于 MDX 实现的现代化多语言博客系统。

• 内容管理: 支持 MDX 格式，可直接在 Markdown 中嵌入 React 组件
• 多语言支持: 每篇文章可提供 en, zh-CN, ja 等多个语言版本
• 功能特性:
  • 自动生成目录 (TOC) 与标题 ID
  • 语法高亮 (Highlight.js)
  • 阅读时间自动估算
  • 响应式渲染，支持 Tailwind Typography
• 落地页: 提供精美的博客列表页，支持文章卡片展示、分类筛选

文档系统

基于 MDX 的结构化文档系统，专为产品文档和技术手册设计。

• 目录结构:
  • 支持多级分类（如 Introduction、Guides、Deployment、Reference）
  • 通过 _config.json 配置分类顺序、标题和图标
• 多语言支持: 每篇文档可提供多语言版本，自动根据 URL 语言前缀切换
• 阅读体验:
  • 左侧导航栏：分类目录树，支持搜索
  • 右侧目录：自动提取标题生成 TOC，支持滚动高亮
  • 上下篇导航：自动计算相邻文档，方便连续阅读
• 落地页: 文档首页展示所有分类和文档卡片，支持快速跳转
• 移动端适配: 响应式设计，移动端提供抽屉式导航

AI 落地页

为 AI 功能提供的专业营销落地页组件库。

• 统一架构: AIUnifiedPageContent 组件支持三种模式：
  • chat: 仅展示 AI 对话功能
  • image: 仅展示 AI 图像生成功能
  • video: 仅展示 AI 视频生成功能
  • all: Tab 切换展示所有功能
• 组件模块:
  • Hero Section: 功能介绍与 CTA 按钮
  • Social Proof: 用户评价与信任背书
  • Features: 功能特性卡片展示
  • Gallery: 作品展示（图片/视频画廊）
  • How It Works: 使用流程说明
  • FAQ: 常见问题解答

国际化 (i18n)

全站支持多语言切换，基于 i18next。

• 路由集成: 自动根据 URL 前缀（如 /zh, /en）切换语言
• 混合渲染支持: 同时支持 Server Components 和 Client Components 的平滑翻译
• 多语言字典: 结构化的 JSON 配置文件，位于 public/locales/

SEO 与分析

• 动态 Metadata: 每个页面均支持根据当前语言和内容动态生成标题、描述及 OpenGraph 标签
• Sitemap 生成: 自动根据路由及博客文章生成多语言 Sitemap
• 分析插件支持: 系统变量支持动态插入分析脚本（如 Google Analytics, Microsoft Clarity 等）
• 结构化数据: 预置 JSON-LD 支持，提升搜索引擎理解能力

定时任务

系统内置了多种后台自动化任务逻辑，可通过 Cron 服务触发。

• 积分自动补给: 每月/每天定期为符合条件的年订阅用户发放积分奖励
• 系统清理: 自动清理过期的管理员审计日志
• 自动化退款: 处理特定状态下的自动退款流程
• Newsletter 补发: 自动化管理邮件订阅列表

UI 主题与交互

• 深色模式: 支持亮色、暗色、科技、微信绿等多种模式，并内置跟随系统切换功能
• 语义化变量: 基于 Tailwind CSS 4，使用全套 CSS 变量控制颜色（如 bg-main, text-primary），确保自定义主题的一致性
• 动效库: 集成 Framer Motion 和 AOS，提供流畅的页面进入和交互动效

通信与通知

• 邮件服务: 集成 Resend 服务，支持多语言邮件模板
• 站内信: 用户中心集成通知中心，支持系统通知的发布与阅读
• Newsletter: 集成邮件订阅功能

基础设施与工具

• 数据库 ORM: Drizzle ORM，支持多数据库适配 (SQLite/PostgreSQL)
• 存储服务: 支持 R2/S3 兼容对象存储，提供通用的文件上传 API
• 常用 Hooks:
  • useAuth: 全局用户认证状态管理
  • usePermissions: 细粒度的页面/组件级权限校验
  • useAdminFetch: 专为管理后台优化的 API 请求封装
  • useDateFormat: 支持多语言的日期格式化工具
• 工具类与服务:
  • 认证工具: auth-helpers.ts 封装了常用的权限与登录校验逻辑
  • 支付工厂: GatewayFactory 实现了对不同支付网关（Stripe/Creem）的解耦
  • 缓存工具: 统一的 cache-utils.ts 处理服务端缓存逻辑
  • 安全审计: log-cleanup-service.ts 自动化处理敏感操作日志
• 安全性:
  • 内置 Cloudflare Turnstile 防火墙支持
  • 注册指纹追踪与冲突拦截
  • API 级 Zod 参数验证
• 工程化:
  • 统一的 fetch 封装
  • 严谨的管理员审计日志流