GitHub - Asymmetric-al/core: 面向使命导向的非营利组织的高性能企业级 Next.js 16 应用。为高影响力团队打造。

2026-06-21T01:17:25.394911

GitHub - Asymmetric-al/core: 面向使命导向的非营利组织的高性能企业级 Next.js 16 应用。为高影响力团队打造。

为使命导向组织构建的高性能 Next.js 16.2.6（App Router）Turborepo 单体仓库（monorepo），包含三个应用（apps/admin、apps/donor、apps/missionary）和共享工作区包（packages/*）。

• 安装前置条件：在 PATH 中安装 Bun 和 Git。
• 运行设置（首次运行时会根据需要创建 .env.local，安装依赖项，检查提交的技能镜像是否与 docs/ai/skills/ 匹配，然后运行仓库设置检查）：
• macOS / Linux / Git Bash：bun run setup
• Windows PowerShell：见下方 Windows（.\scripts\setup.ps1）。
• 如果首次运行因“缺少必需的环境变量”而停止，请填写 .env.local 中必需的 Supabase 值，然后再次运行设置。
• 启动开发：bun run dev（或 package.json 中的应用特定脚本）。对于单个界面，通常使用 bun run dev:donor（donor 运行在端口 3000）。
• 可选冒烟测试：bun run verify（在 scripts/verify/index.mjs 中实现；在 Windows 上没有 Bash 垫片时，请在 Git Bash 或 WSL 中运行 bash scripts/verify/index.sh）。

执行 git pull 后，如果技能文件发生更改：运行 bun run skills:verify。如果报告 docs/ai/skills/ 与 .agents/skills/ 和 .cursor/skills/ 下的镜像之间存在差异，请运行 bun run skills:sync 并提交更新后的镜像文件，以便 CI 和团队成员保持一致。

环境变量

必需：NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY
可选：.env.example 中的其他条目（Stripe、演示账户等）

开发

bun run dev 通过 Turbo（turbo run dev）运行所有应用。bun run verify 中的默认 HTTP 检查使用 http://localhost:3000（VERIFY_BASE_URL），因此请使用 bun run dev:donor（或将 VERIFY_BASE_URL 指向你正在运行的应用）。

每个应用的开发命令（从根目录 package.json）：
- bun run dev:donor → donor 应用，端口 3000
- bun run dev:admin → admin 应用，端口 3030
- bun run dev:mission-control → Mission Control 管理应用，端口 3030，带有 Cloud Agent 友好的开发默认值
- bun run dev:missionary → missionary 应用，端口 4000

开发环境的最终依据是仓库根目录的 .env.local。每个应用的 next.config.ts 使用 @next/env 加载该根文件；开发脚本不会将机密信息复制到应用目录中。如果旧工具需要应用本地环境变量文件，请运行 bun run env:link-apps 创建符号链接，或者当文件符号链接权限不可用时创建 Windows 硬链接。除非使用 --force 重新运行，否则该辅助程序会拒绝覆盖现有的应用 .env.local。

Cursor Cloud Agent

对于 Cursor Cloud Agent 运行，请在 Cloud Agent 机密信息设置中设置机密信息，而不是将值提交到仓库文件中。在云环境中设置以下密钥：
- NEXT_PUBLIC_SUPABASE_URL
- NEXT_PUBLIC_SUPABASE_ANON_KEY
- SUPABASE_SERVICE_ROLE_KEY（可选，仅用于服务器端/管理工作流程）

安全规则：
- .env.local 仅保留在本地，并且已被 .gitignore 忽略。
- 切勿在浏览器/客户端代码中暴露 SUPABASE_SERVICE_ROLE_KEY。
- 浏览器登录流程只需要 NEXT_PUBLIC_SUPABASE_URL 和 NEXT_PUBLIC_SUPABASE_ANON_KEY。

Mission Control Cloud Agent 沙盒

当新的 Cursor Cloud Agent，或同一沙盒中的人类需要 Mission Control Dashboard 但没有真实的 Supabase 项目时，使用此命令。

bun run setup:mission-control:cloud
bun run dev:mission-control

然后打开 http://localhost:3030。setup 命令仅会写入已被 .gitignore 忽略的 .env.local 默认值：SKIP_ENV_VALIDATION=1, E2E_AUTH_BYPASS=true，占位符公共 Supabase 值，以及 admin Playwright 基础 URL。现有的显式 E2E_AUTH_BYPASS=false 值会被保留，除非你传递 --force-bypass。在测试实时身份验证或托管数据时，请将占位符替换为真实的 Supabase/演示账户机密信息。

Windows 设置

Windows PowerShell 5.1：

powershell -ExecutionPolicy Bypass -File .\scripts\setup.ps1

PowerShell 7+：

pwsh -File .\scripts\setup.ps1

首次运行会创建 .env.local。填写以下必需值，然后重新运行设置：NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY。

脚本顺序与 Unix 上的 bun run setup 相同：安装依赖项（除非使用 -SkipInstall），运行 bun run skills:verify，然后运行 bun run setup:verify。在拉取涉及技能文件的更改后，运行 bun run skills:verify；如果报告镜像差异，请运行 bun run skills:sync 并提交更新后的镜像文件。

如果已经运行过依赖项安装，请跳过：

pwsh -File .\scripts\setup.ps1 -SkipInstall

本地安装并运行 PSScriptAnalyzer（非必需）：

Install-Module PSScriptAnalyzer -Scope CurrentUser
Invoke-ScriptAnalyzer -Path .\scripts\setup.ps1, .\scripts\lib\*.ps1

技术栈

• 框架：Next.js 16.2.6（App Router，应用配置中启用 Turbopack）—— 针对性能优化
• UI 系统：Tailwind CSS 4 + shadcn/ui（Maia 主题）+ Base UI
• 主题：浅锌色调（Zinc/Zinc），shadcn/ui Maia 主题
• 数据库：Supabase（PostgreSQL）
• 认证：Supabase Auth（在 packages/auth、packages/api 中共享辅助函数）
• 支付：Stripe（捐赠者及相关流程）
• 状态管理：React 19 + TanStack Query v5
• 动画：motion（v12）以及共享 UI 辅助函数，如 MotionPreset（packages/ui）

视觉规范

该平台在桌面和移动端使用以锌色为主的浅色主题（Maia tokens）。

• 字体在每个应用的 app/layout.tsx 中通过 next/font/google 加载：
• 无衬线/正文：Inter
• 展示/标题：Syne
• 等宽：Geist Mono
• 内边距：主要内容通常使用 px-4 py-6 sm:px-6（在布局中应用）。
• 边框：优先使用 Maia 主题 token（border-border, border-border/60, --radius）。
• 动画：MotionPreset 和来自 @asym/lib/motion-presets / @asym/ui 的相关预设。
• 响应式：移动优先模式；侧边栏访问通常使用 Sheet/抽屉式导航。
• Token：Maia 图表的 CSS 变量 --chart-1 … --chart-5（用于 Recharts）。
• 柱状图（如果适用此规范）：顶部圆角半径 [4, 4, 0, 0]，maxBarSize={52}，Y 轴标签宽度和 tickMargin={8}，时间轴密集时使用短月份标签。

应用与端口

每个界面都是一个独立的 Next.js 应用，包含自己的 app/ 树和开发端口（参见快速入门）。

共享认证守卫使用 packages/auth/middleware.ts 中的 createAuthMiddleware，通过每个应用的 apps/*/proxy.ts（导出 proxy）进行连接。

当只需要一个界面时，使用每个应用的 dev:* 脚本；当需要多个应用时，使用 bun run dev / bun run dev:all（参见根 package.json）。

AI Agent 文档

面向 Agent 的文档位于 docs/ai/ 下：

• 入口点：AGENTS.md —— 所有 AI Agent 工作的路由规则
• 技术栈注册表：docs/ai/stack-registry.md —— 规范的技术栈列表
• 工作集：docs/ai/working-set.example.md —— 本地 docs/ai/working-set.md 暂存上下文的模板
• Nia MCP：docs/ai/nia.md —— 仓库范围的 Nia 搜索、MCP 设置和本地同步规则
• 单体仓库架构：docs/ai/monorepo-architecture.md —— 工作区结构
• 规则手册：docs/ai/rules/* —— 领域特定指南（前端、后端、测试等）
• 异步 QA 监工：docs/ai/rules/async-qa-foreman.md —— 操作

查看原文