APJ-B2B 前端开发者上手指南

专为明日即将开始前端画面开发的新成员设计的系统性文档导航和快速入门指南

📋 指南使用说明

核心价值：本指南将分散在 docs/、frontend/docs/ 等多个目录下的文档系统化整理，帮助你：

快速理解项目全貌和技术标准
精准定位所需的设计规范和实现教程
高效执行首日开发任务
建立检索思维模型，后续可自主查找

建议阅读顺序：

先浏览 项目文档全景图，建立整体认知
按照 前端开发者阅读路线图 的优先级顺序阅读
开发过程中遇到具体问题，查阅 快速决策指南
按照 第一天行动计划 实际动手

🗺️ 项目文档全景图（分类与位置）

将项目文档体系归纳为三大支柱，每类文档都有明确的位置和用途：

1. 标准规范类（`docs/` 目录）

定位：项目级的设计原则、架构标准、实现规范

docs/
├── README.md                          # 📍 文档总入口（必读起点）
├── guidelines/                        # 📚 核心标准库
│   ├── design/                       # 🏗️ 设计标准（11个文件）
│   │   ├── 01_architecture-spec.md              # 架构规范
│   │   ├── 02_validation-guidelines.md          # 验证指南
│   │   ├── 03_frontend-design-guidelines.md     # 前端设计指南 ★
│   │   ├── 10_naming-conventions-guidelines.md  # 命名规范指南 ★
│   │   └── 11_frontend-component-design-guidelines.md # 组件设计指南 ★
│   ├── implementation/                # 💻 实现标准
│   │   ├── frontend.md               # 📖 前端实现标准（架构圣经）★★★
│   │   └── backend.md                # 后端实现标准
│   ├── testing/                      # 🧪 测试指南
│   │   └── frontend-unittest-guidelines.md # 前端单元测试指南
│   └── code-review/                  # 🔍 代码审查
│       └── frontend-review-checklist.md # 前端代码审查清单
└── repository/                       # 🔄 Git工作流
    └── repository-operations.md      # 仓库操作规范

2. 前端指南类（`frontend/docs/` 目录）

定位：具体的实现教程、配置说明、编码规范

frontend/docs/
├── README.md                         # 前端文档入口
├── getting-started/                  # 🚀 环境搭建
│   └── installation.md              # 安装指南（含Mock设置）
├── guides/                          # 📖 实现教程（逐步指南）
│   ├── validation.md               # 表单验证实现教程
│   ├── i18n.md                     # 国际化实现教程
│   └── mock-implementation.md      # Mock数据实现教程（MSW）
└── standards/                       # ⚖️ 编码规范
    ├── README.md                   # 标准文档索引（日文）
    └── code-quality.md             # 代码质量管理（ESLint/Prettier）

3. 基础设施类（`infrastructure/docs/` 目录）

定位：AWS环境配置、部署流程（前端开发初期可暂缓）

infrastructure/docs/
└── aws-dev-environment-setup.md    # AWS开发环境设置

🧭 前端开发者阅读路线图（按优先级排序）

黄金法则：优先阅读带 ★ 标记的文档，它们是项目开发的“宪法”

🟢 第一优先级（必读，1-2小时）

目标：掌握项目核心架构和设计原则

docs/README.md - 文档总地图（5分钟）
docs/guidelines/implementation/frontend.md - 前端实现标准（30分钟）
- 这是项目的“架构圣经”，定义了目录结构、组件设计、状态管理、API调用等所有核心规范
docs/guidelines/design/11_frontend-component-design-guidelines.md - 组件设计指南（15分钟）
- 基于Atomic Design原则（atoms/molecules/organisms/templates/domains）
docs/guidelines/design/10_naming-conventions-guidelines.md - 命名规范指南（15分钟）
- 文件、组件、变量、函数等所有命名规则

🟡 第二优先级（推荐，1小时）

目标：了解具体实现标准和开发流程

docs/guidelines/design/03_frontend-design-guidelines.md - 前端设计指南（15分钟）
- 整体设计理念和约束条件
frontend/docs/standards/code-quality.md - 代码质量管理（15分钟）
- ESLint、Prettier、TypeCheck配置和使用方法
docs/repository/repository-operations.md - Git工作流程（15分钟）
- 分支策略、提交规范、PR流程
frontend/docs/getting-started/installation.md - 环境搭建指南（15分钟）
- 包含Mock环境设置步骤

🔵 第三优先级（按需，随时查阅）

目标：解决具体开发问题

frontend/docs/guides/validation.md - 表单验证实现教程
frontend/docs/guides/i18n.md - 国际化实现教程
frontend/docs/guides/mock-implementation.md - Mock数据实现教程
docs/guidelines/code-review/frontend-review-checklist.md - 代码审查清单
docs/guidelines/testing/frontend-unittest-guidelines.md - 前端单元测试指南

🔍 快速决策指南（按问题索引）

遇到以下问题时，直接查阅对应文档：

问题场景	查阅文档	关键收获
“这个组件应该放在哪个目录？”	`docs/guidelines/implementation/frontend.md` + `docs/guidelines/design/11_frontend-component-design-guidelines.md`	Atomic Design目录结构：atoms/molecules/organisms/templates/domains
“这个文件/变量该怎么命名？”	`docs/guidelines/design/10_naming-conventions-guidelines.md`	统一的命名规范（kebab-case、camelCase、PascalCase）
“API该怎么调用？状态怎么管理？”	`docs/guidelines/implementation/frontend.md`	API调用集中在`composables/`，状态管理使用Pinia（`stores/`）
“代码格式不对，怎么修复？”	`frontend/docs/standards/code-quality.md`	ESLint检查、Prettier格式化命令
“表单验证该怎么实现？”	`frontend/docs/guides/validation.md`	基于Zod的验证方案，包含示例代码
“多语言支持怎么添加？”	`frontend/docs/guides/i18n.md`	Vue I18n配置和使用方法
“后端没ready，怎么mock数据？”	`frontend/docs/guides/mock-implementation.md`	MSW(Mock Service Worker)设置教程
“代码审查要注意什么？”	`docs/guidelines/code-review/frontend-review-checklist.md`	前端代码审查的检查清单
“该怎么写单元测试？”	`docs/guidelines/testing/frontend-unittest-guidelines.md`	前端单元测试的规范和示例
“Git分支和提交该怎么操作？”	`docs/repository/repository-operations.md`	分支策略、提交信息规范、PR流程

🚀 第一天行动计划（具体步骤）

阶段一：环境准备（30分钟）

确认Node.js版本：确保已安装Node.js 20.x LTS
安装依赖：进入frontend目录执行 npm install
启动开发服务器：执行 npm run dev，访问 http://localhost:3001 确认运行正常
启动Storybook（可选）：执行 npm run storybook，访问 http://localhost:6006

阶段二：文档阅读（2-3小时）

按照 前端开发者阅读路线图 的顺序阅读文档，重点关注：

理解Atomic Design组件结构
掌握API调用模式（composables/useApi.ts）
熟悉代码质量工具（ESLint、Prettier）

阶段三：动手实践（剩余时间）

创建第一个组件：按照Atomic Design原则在对应目录创建组件
实现API调用：在composables/目录创建对应的use函数
添加表单验证：参考validation.md教程实现表单验证
运行代码检查：执行 npm run lint 和 npm run typecheck 确保代码质量

常用命令速查

# 开发服务器
npm run dev              # 启动开发服务器 (localhost:3001)
npm run build            # 构建生产版本
npm run preview          # 预览生产构建

# 代码质量
npm run lint             # ESLint检查
npm run lint:fix         # ESLint自动修复
npm run format           # Prettier格式化
npm run typecheck        # TypeScript类型检查

# 测试
npm run test             # 单元测试 (Vitest)
npm run test:coverage    # 带覆盖率的测试
npm run test:e2e         # E2E测试 (Playwright)

# 组件文档
npm run storybook        # 启动Storybook (localhost:6006)
npm run build-storybook  # 构建Storybook静态文件

💡 实用提示与最佳实践

1. 组件设计思维

原子性：atoms/是最小UI单元（按钮、输入框）
组合性：molecules/由多个atoms组成（搜索框=输入框+按钮）
功能性：organisms/完成特定功能（表单、卡片）
页面结构：templates/定义页面布局
领域特定：domains/业务领域组件（预约卡片）

2. 代码质量保证

提交前务必运行 npm run lint 和 npm run typecheck
使用Prettier自动格式化，保持代码风格统一
import语句会自动排序，无需手动调整

3. 开发流程建议

先设计组件结构，再实现功能逻辑
API调用统一通过composables/，避免在组件中直接使用$fetch
状态管理优先使用局部状态，跨组件状态才使用Pinia
充分利用TypeScript类型，避免any类型

4. 遇到问题时的解决路径

先查 快速决策指南 找到对应文档
查阅相关文档中的示例代码
查看现有代码库中的类似实现
如仍无法解决，在团队中提问时提供：
- 问题描述
- 已尝试的解决方案
- 相关代码片段

📞 后续支持

完成本指南的阅读和实践后，你应该能够：

✅ 理解项目整体架构和技术栈
✅ 按照规范创建组件和页面
✅ 实现API调用和状态管理
✅ 保证代码质量和规范符合性
✅ 自主查找和解决常见开发问题

如需进一步了解后端接口或基础设施配置，可参考：

docs/guidelines/implementation/backend.md - 后端实现标准
infrastructure/docs/aws-dev-environment-setup.md - AWS环境设置

文档版本: 1.0
最后更新: 2026-02-03
维护者: APJ-B2B开发团队
适用对象: 新加入的前端开发者