企业官网建设流程全解析

• AI 技能
• AI 插件
• 人工智能

本指南以 AAS 插件仓库 app-builder 技能包 中的 scaffolding.md 为骨架，系统讲解 Agent 在生成全新全栈项目时应当遵循的目录结构、文件职责与配置规范。你将掌握：如何用 "薄路由 + Feature 隔离 + 服务端隔离" 三层结构组织 Next.js 项目、如何通过 tsconfig 路径别名消除深层相对导入、以及如何在多 Agent 协作流水线（Project Planner → Database Architect → Backend → Frontend → DevOps）中落地这套脚手架。

一、为什么需要一份"可执行"的脚手架规范

在 AAS（agentic-awesome-skills）的 app-builder 技能体系中，SKILL.md 将应用构建定位为一个"从自然语言请求到完整应用"的编排流程：先由 project-detection.md 通过关键词矩阵判定项目类型（如dashboard, panel, management→ nextjs-fullstack），再由 tech-stack.md 确定技术选型，最后进入 agent-coordination.md 描述的多 Agent 流水线。

在这条流水线中，脚手架（Scaffolding）是 Project Planner 与各专项 Agent 之间事实上的"交接契约"：目录结构决定了数据库表、API 路由、页面与组件各自的落点，文件职责划分决定了每个 Agent 只读自己负责的子目录。因此，本文档不仅仅是"长什么样的目录树"，更是一份保证多 Agent 并行协作不冲突的工程协议。

在仓库内，apps/web-app（AAS 自身的 Web 工作台）同样采用了src/源码根目录 +scripts/+public/的组织形态，README、配置文件（vite.config.ts、tsconfig.json等）置于项目根，与本脚手架规范在"可被工具链直接发现"这一目标上保持一致。

二、Next.js 全栈目录结构（2025 优化版）

scaffolding.md给出的目录树是本文档的核心资产，完整继承如下：

project-name/ ├── src/ │ ├── app/ # Routes only (thin layer) - 只放路由 │ │ ├── layout.tsx │ │ ├── page.tsx │ │ ├── globals.css │ │ ├── (auth)/ # Route group - auth pages（路由组，不影响 URL） │ │ │ ├── login/page.tsx │ │ │ └── register/page.tsx │ │ ├── (dashboard)/ # Route group - dashboard layout │ │ │ ├── layout.tsx │ │ │ └── page.tsx │ │ └── api/ │ │ └── [resource]/route.ts │ │ │ ├── features/ # Feature-based modules - 按业务域聚合 │ │ ├── auth/ │ │ │ ├── components/ │ │ │ ├── hooks/ │ │ │ ├── actions.ts # Server Actions（服务端变更操作） │ │ │ ├── queries.ts # Data fetching（数据读取） │ │ │ └── types.ts # 该特性域的共享类型 │ │ ├── products/ │ │ │ ├── components/ │ │ │ ├── actions.ts │ │ │ └── queries.ts │ │ └── cart/ │ │ └── ... │ │ │ ├── shared/ # Shared utilities - 跨特性共享代码 │ │ ├── components/ui/ # Reusable UI components（按钮、输入框等） │ │ ├── lib/ # Utils, helpers（工具函数） │ │ └── hooks/ # Global hooks（全局钩子） │ │ │ └── server/ # Server-only code - 仅服务端代码 │ ├── db/ # Database client (Prisma) │ ├── auth/ # Auth config │ └── services/ # External API integrations │ ├── prisma/ │ ├── schema.prisma │ ├── migrations/ │ └── seed.ts │ ├── public/ ├── .env.example ├── .env.local ├── package.json ├── tailwind.config.ts ├── tsconfig.json └── README.md

2.1 各目录的核心职责

• src/app/——薄路由层（Thin Layer）：这里只承担 URL 到页面/接口的映射。业务逻辑、数据获取、状态管理一律下沉到features/或server/，避免出现"路由文件里塞满逻辑"的巨型page.tsx。
• src/features/——特性化模块：每个业务域（auth、products、cart……）自成一个目录，聚合该域专属的components/、hooks/、actions.ts（服务端变更）、queries.ts（数据读取）与types.ts。这是"Feature isolation"原则的直接载体。
• src/shared/——共享层：只存放跨特性可复用的 UI 组件、工具函数与全局 hooks。注意区分：features/auth/components/与shared/components/ui/的边界在于"是否只属于某个业务域"。
• src/server/——服务端隔离层：Prisma client、鉴权配置、外部 API 集成全部收拢于此。把server/单独成目录的价值在于：只要代码不从这里 import，就不会在客户端 bundle 中意外打入服务端依赖。

2.2 与仓库内模板的对照印证

该结构并非凭空设计，而是与技能包内置的templates/目录逐一对应。例如 nextjs-fullstack/TEMPLATE.md 给出了精简版全栈骨架（prisma/、src/app/、src/components/ui/、src/lib/db.ts、.env.example、package.json），本规范中的src/features/与src/server/是其在规模增长后的深化形态；而 nextjs-saas/TEMPLATE.md 则用(auth)、(dashboard)、(marketing)三组路由组演示了"布局共享但不污染 URL"的实战用法。仓库 13 个模板（astro-static、chrome-extension、cli-tool、electron-desktop、express-api、flutter-app、monorepo-turborepo、nextjs-fullstack、nextjs-saas、nextjs-static、nuxt-app、python-fastapi、react-native-app）各有独立的目录骨架，脚手架规范则沉淀了它们的共同工程原则。

三、五大结构原则

scaffolding.md将这套结构的指导思想归纳为一张原则表，完整继承并展开如下：

在 agent-coordination.md 描述的流水线中，这些原则直接服务于协作：Project Planner 产出{task-slug}.md计划文件后，Database Architect 只在prisma/与server/db/作业，Backend Specialist 只碰app/api/与server/services/，Frontend Specialist 只写app/、features/*/components/与shared/components/ui/——目录边界即 Agent 职责边界，这就是脚手架规范在 Agent-first 开发模式中的核心价值。

四、核心文件职责清单

项目根的 7 个文件在脚手架中承担固定职责，scaffolding.md的原表如下：

4.1 环境变量：模板与本地分离

.env.example与.env.local成对出现是脚手架硬性约定：前者入库、后者被.gitignore忽略。参考 nextjs-fullstack/TEMPLATE.md 与 nextjs-saas/TEMPLATE.md，全栈项目至少应包含：

4.2 数据库层：Prisma 三件套

prisma/目录固定由schema.prisma（模型定义）、migrations/（版本化迁移记录）与seed.ts（种子数据）组成。结合仓库apps/web-app同样把数据访问与业务入口分离的组织方式，可推断：任何数据库读写都应收敛到src/server/db/，由该目录统一导出 Prisma Client 实例，避免在组件或 action 中直接new PrismaClient()造成连接泄漏。

五、路径别名配置（tsconfig.json）

路径别名是这套结构能够"无痛"运转的前提——没有别名，features/auth/actions.ts想引用shared/lib就得写一长串../../../shared/lib，一旦移动目录即全面破碎。scaffolding.md给出的标准配置如下（完整继承）：

{ "compilerOptions": { "paths": { "@/*": ["./src/*"], "@/features/*": ["./src/features/*"], "@/shared/*": ["./src/shared/*"], "@/server/*": ["./src/server/*"] } } }

配置要点说明：

• @/*指向./src/*：作为兜底别名，覆盖src/下所有未单独声明的子目录（如@/app/*、@/prisma/*之外的任何src内路径）。
• 三个显式子路径别名（@/features/*、@/shared/*、@/server/*）：将三层核心目录固化为稳定 API，即使未来调整目录层级，import 语句也无需改动。
• TypeScript 只负责编译期解析：若使用 Jest/Vitest（参考仓库 apps/web-app/vitest.config.ts 的组织方式）或 Turbopack，还需在对应构建/测试配置中同步声明模块解析映射，否则运行时会报模块找不到。

提示：别名的价值在 monorepo 场景同样成立——monorepo-turborepo/TEMPLATE.md 用workspace:*协议在packages/之间共享 UI、类型与配置包，包内再配合路径别名，即可实现跨应用零相对路径引用。

六、何时用何物：决策速查表

脚手架规范用一张表终结"新代码放哪"的反复纠结，原表完整继承：

判定逻辑拆解：先问"这是页面还是组件？"——页面进app/，组件按"属于某业务域还是全局复用"在features/*/components/与shared/components/ui/二选一；再问"这是读写还是算？"——变更走actions.ts（Server Actions），读取走queries.ts（数据获取）；最后问"触达了什么资源？"——数据库进server/db/，第三方服务进server/services/。这套规则同时是 feature-building.md 中"特性分析"的落位依据（如add payment system会被拆解为orders/payments表 →server/db/、/api/checkout与 Stripe webhook →server/services/、CheckoutForm→features/payments/components/）。

七、从零落地：脚手架实战步骤

将本规范与 nextjs-fullstack/TEMPLATE.md 的 Setup Steps 结合，完整落地流程如下：

# 1. 初始化项目（App Router + TypeScript + Tailwind） npx create-next-app project-name --typescript --tailwind --app # 2. 安装数据库与校验依赖 npm install prisma @prisma/client zod # 3. 初始化 Prisma npx prisma init # 4. 按上一节规划创建目录骨架 # src/features/ src/shared/{components/ui,lib,hooks} src/server/{db,auth,services} prisma/migrations prisma/seed.ts # 5. 在 prisma/schema.prisma 中定义模型，然后同步数据库 npm run db:push # 6. 启动开发服务器 npm run dev

随后按第六节速查表把页面、组件、action、查询逐一归位，并在tsconfig.json写入第五节别名配置。

7.1 在多 Agent 流水线中的位置

根据 agent-coordination.md 的执行顺序表，脚手架阶段发生在流水线的前半程：

注意阶段 1.5 的强制校验：计划文件不存在时，任何专项 Agent 都不得继续。脚手架目录结构的规划正是阶段 1 计划文件的核心内容之一，这也是"先结构、后实现"在 Agent 流水线中被固化为硬性检查点的原因。

八、常见误区与维护建议

• 路由文件长胖：page.tsx里出现业务判断、数据库查询，即违反"Thin routes"原则。应把逻辑迁入features/，路由只负责组合。
• shared/变成垃圾桶：只在单一 feature 使用的组件放在shared/components/ui/会造成假共享。归属判断标准：是否至少被两个 feature 引用。
• 别名未同步到测试/构建配置：TypeScript 编译通过但测试运行失败，多半是 Vitest/Jest 未配置 moduleNameMapper（仓库apps/web-app的 vitest.config.ts 即是配置同步的参考实现）。
• 只建.env.example不写注释：模板变量的用途说明是脚手架文档的一部分，参照第四节的变量表逐项注释，能显著降低协作与审计成本。
• 目录即契约：在多 Agent 场景下，任何对目录结构的调整都应先行更新计划文件，再让相应 Agent 跟进，避免"结构漂移"导致 Agent 找不到落点。

延伸阅读：本指南是 app-builder 技能包的一部分，配套文档还包括 项目类型检测（关键词矩阵）、技术栈选型（2025 默认栈：Next.js + TypeScript 5.7+ + Tailwind v4 + Prisma/Drizzle + Auth.js v5 + Turborepo）、Agent 编排、功能构建 以及 SKILL.md 汇总的 13 个 项目模板。

• AI 技能
• AI 插件
• 人工智能