web-nextjs 模板

基于 Next.js 16 的生产级 Web 应用模板，内置 Supabase Auth、shadcn/ui 和国际化支持。

这是什么？

web-nextjs 是基于 AgentDock 四层架构的全栈 Web 应用脚手架。它提供：

• 认证 — 通过 Supabase Auth 实现邮箱/密码 + GitHub OAuth 登录
• UI 组件 — 基于 shadcn/ui，支持深色模式
• 国际化 — 使用 next-intl 实现多语言应用（en/zh）
• 表单处理 — react-hook-form + Zod 验证
• 四层架构 — 职责清晰分离（features → core → infra → app）

它解决了什么问题？

从零开始构建现代 Web 应用需要做出许多重复性决策：

为什么选择这个模板？

对于个人开发者

• 立即开始构建功能 —— 无需处理样板代码
• 认证、国际化和 UI 已预先集成
• Layer 2 规则防止架构错误

对于团队

• 跨项目保持一致的代码结构
• 轻松上手 —— 新开发者只需学习一种模式
• AI 助手可以可靠地浏览代码库

对于 AI 编程助手

• AGENTS.md 定义执行边界
• 目录契约告诉 AI 助手代码应该放在哪里
• OpenSpec 变更提供结构化的规划

技术栈

架构

src/
├── app/                    # App 层 - 路由、布局、页面
│   ├── [locale]/          # 基于语言区域的路由
│   │   ├── (auth)/        # 公开认证路由（登录、注册）
│   │   └── (protected)/   # 受保护路由（仪表盘、设置）
│   └── auth/              # 认证回调处理器
├── components/            # 共享 UI 组件
│   ├── ui/               # shadcn/ui 基础组件
│   ├── dashboard/         # 仪表盘专用组件
│   └── profile/           # 个人资料表单组件
├── core/                  # Core 层 - 类型、接口、领域逻辑
│   ├── types/            # TypeScript 类型（AuthUser, ActionResult 等）
│   └── repositories/     # 仓库接口（IAuthRepository）
├── features/             # Feature 层 - 用例、Server Actions
│   └── auth/             # 认证功能（actions, contract, index）
├── infra/                # Infrastructure 层 - 外部服务
│   ├── db/              # Supabase 客户端与仓库实现
│   └── providers.ts     # DI 工厂（getAuthRepository）
└── lib/                  # 共享工具函数
    └── validations/      # Zod 模式

四层数据流

用户请求
    ↓
app/（路由处理器 / 页面）
    ↓
features/（Server Action - 用例编排）
    ↓
core/（仓库接口 - 契约）
    ↓
infra/（仓库实现 - Supabase SDK）

Layer 2 约束

该模板通过 ESLint 强制实施一条关键规则：

功能层（Features）不得直接从 @/infra/* 导入。

这确保了业务逻辑与基础设施细节保持独立。请改用 core/repositories 中的仓库接口。

已完成的功能

认证

• 邮箱/密码登录
• 邮箱/密码注册及验证流程
• GitHub OAuth 集成
• 密码重置（忘记密码 → 邮件 → 重置密码）
• 会话管理（getCurrentUser 辅助函数）
• 受保护路由组（(protected) 布局）
• 认证中间件（会话刷新 + 语言区域检测）

用户账户

• 带头像展示的个人资料页面
• 显示名称更新
• 邮箱显示（只读）
• 修改密码入口（重定向至忘记密码页面）

导航

• 可折叠侧边栏，带用户菜单
• 设置导航（个人资料、帮助、隐私、关于）
• 清晰的用户导航下拉菜单（账户链接、退出登录）
• 无占位符 # 链接

页面

• 登录页面
• 带邮箱验证状态的注册页面
• 仪表盘页面
• 忘记密码页面
• 重置密码页面
• 个人资料设置页面
• 帮助页面（占位符）
• 隐私政策页面（占位符）
• 关于页面（占位符）

国际化

• 英文（en）和中文（zh）语言区域
• 基于语言区域的 URL 路由（/[locale]/...）
• next-intl 翻译钩子
• 翻译文件位于 messages/ 目录
• 支持 i18n 的导航 — 请参阅 i18n 导航指南

接下来

• 模板开发和使用 →
• 部署 →
• 数据层：Supabase →
• 数据层：Drizzle →
• 支付宝支付 →
• 微信支付 →
• Stripe 支付 →
• 故障排查 →