名称：入职文档描述：开发者入职文档和学习路径允许工具：读取、全局搜索、grep、写入、编辑

入职文档技能

何时使用此技能

在以下情况下使用此技能：

入职文档任务 - 处理开发者入职文档和学习路径
规划或设计 - 需要入职文档方法的指导
最佳实践 - 希望遵循既定模式和标准

概述

创建全面的开发者入职文档，以加速生产力。

强制：文档优先方法

在创建入职文档之前：

调用 docs-management 技能 获取入职模式
通过 MCP 服务器（perplexity）验证开发者体验最佳实践
基于行业入职标准提供指导

入职文档框架

入职文档层次：

┌─────────────────────────────────────────────────────────────────────────────┐
│  第1天：环境设置                                                             │
│  • 开发环境安装                                                              │
│  • 访问权限配置和凭证                                                         │
│  • 工具配置                                                                  │
├─────────────────────────────────────────────────────────────────────────────┤
│  第1周：核心概念                                                              │
│  • 架构概述                                                                  │
│  • 代码库导航                                                                │
│  • 开发工作流程                                                              │
├─────────────────────────────────────────────────────────────────────────────┤
│  第1个月：深入学习                                                             │
│  • 领域知识                                                                  │
│  • 系统内部                                                                  │
│  • 高级工作流程                                                              │
├─────────────────────────────────────────────────────────────────────────────┤
│  持续：参考材料                                                                │
│  • API 文档                                                                  │
│  • 运行手册和流程                                                             │
│  • 最佳实践和标准                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

入职指南模板

# 开发者入职指南

欢迎来到 [项目/团队名称]！本指南将帮助您快速上手。

---

## 快速链接

| 资源 | 链接 | 目的 |
|----------|------|---------|
| 代码库 | [GitHub 仓库] | 源代码 |
| 文档 | [文档网站] | 技术文档 |
| 问题跟踪 | [Jira/GitHub] | 任务和错误 |
| CI/CD | [Azure DevOps/GitHub Actions] | 构建管道 |
| 监控 | [Grafana/DataDog] | 指标和警报 |
| 聊天 | [Slack/Teams] | 团队沟通 |

---

## 第1天清单

### 访问设置

- [ ] 接受 GitHub 组织邀请
- [ ] 授予 Azure 订阅访问权限
- [ ] 加入 Slack/Teams 工作区
- [ ] 配置 VPN（如适用）
- [ ] 设置密码管理器
- [ ] 在所有账户上启用 MFA

### 开发环境

- [ ] 安装并配置 IDE
- [ ] 安装所需 SDK
- [ ] 克隆仓库
- [ ] 项目本地构建
- [ ] 测试运行成功

### 第一步

- [ ] 阅读本入职指南
- [ ] 查看团队约定
- [ ] 与入职伙伴会面
- [ ] 安排与团队负责人的一对一会议

---

## 环境设置

### 先决条件

| 工具 | 版本 | 安装 |
|------|---------|--------------|
| .NET SDK | 10.0+ | [下载](https://dot.net) |
| Node.js | 22 LTS | [下载](https://nodejs.org) |
| Docker Desktop | 最新 | [下载](https://docker.com) |
| Git | 2.40+ | [下载](https://git-scm.com) |
| VS Code / Rider | 最新 | 首选 IDE |

### 分步设置

#### 1. 安装先决条件

**Windows (winget):**
```powershell
winget install Microsoft.DotNet.SDK.10
winget install OpenJS.NodeJS.LTS
winget install Docker.DockerDesktop
winget install Git.Git
winget install Microsoft.VisualStudioCode
```

**macOS (Homebrew):**

```bash
brew install --cask dotnet-sdk
brew install node@22
brew install --cask docker
brew install git
brew install --cask visual-studio-code
```

#### 2. 克隆仓库

```bash
# 克隆主仓库
git clone https://github.com/org/project.git
cd project

# 安装依赖
dotnet restore
npm install
```

#### 3. 配置环境

```bash
# 复制环境模板
cp .env.example .env.local

# 编辑您的值
code .env.local
```

**必需的环境变量：**

| 变量 | 描述 | 如何获取 |
|----------|-------------|------------|
| `DATABASE_URL` | PostgreSQL 连接 | 使用本地 Docker 或开发数据库 |
| `AZURE_CLIENT_ID` | Azure 服务主体 | 向团队负责人请求 |
| `API_KEY` | 外部 API 密钥 | 1Password 保险库 |

#### 4. 启动开发环境

```bash
# 启动基础设施（数据库、缓存等）
docker compose up -d

# 运行数据库迁移
dotnet ef database update

# 启动应用程序
dotnet run
```

#### 5. 验证设置

```bash
# 运行测试
dotnet test

# 检查 API 健康状态
curl http://localhost:5000/health
```

**预期输出：**

```json
{
  "status": "健康",
  "checks": {
    "database": "健康",
    "cache": "健康"
  }
}
```

---

## 架构概述

### 系统上下文

[包含 C4 上下文图]

### 高层架构

```text
┌─────────────────────────────────────────────────────────────────────────────┐
│                              负载均衡器                                      │
└─────────────────────────────────────────────────────────────────────────────┘
                                     │
                    ┌────────────────┼────────────────┐
                    ▼                ▼                ▼
            ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
            │    Web 应用   │ │    API       │ │    工作器     │
            │   (Blazor)   │ │   (.NET)     │ │    服务      │
            └──────────────┘ └──────────────┘ └──────────────┘
                    │                │                │
                    └────────────────┼────────────────┘
                                     ▼
                         ┌─────────────────────┐
                         │     PostgreSQL      │
                         └─────────────────────┘
```

### 关键组件

| 组件 | 目的 | 技术栈 |
|-----------|---------|------------|
| Web 应用 | 用户界面 | Blazor, Tailwind CSS |
| API | 后端服务 | .NET 10, Minimal APIs |
| 工作器 | 后台作业 | .NET Worker Service |
| 数据库 | 数据持久化 | PostgreSQL 16 |
| 缓存 | 性能 | Redis |
| 队列 | 异步消息 | Azure Service Bus |

---

## 代码库导航

### 仓库结构

```text
project/
├── src/
│   ├── Web/                    # Blazor 前端
│   ├── Api/                    # 后端 API
│   ├── Worker/                 # 后台服务
│   └── SharedKernel/           # 共享代码
├── tests/
│   ├── Unit/                   # 单元测试
│   ├── Integration/            # 集成测试
│   └── E2E/                    # 端到端测试
├── docs/                       # 文档
├── scripts/                    # 工具脚本
├── .github/                    # GitHub 工作流
└── docker-compose.yml          # 本地开发
```

### 关键文件回顾

| 文件 | 目的 | 优先级 |
|------|---------|----------|
| `README.md` | 项目概述 | 第1天 |
| `CONTRIBUTING.md` | 贡献指南 | 第1天 |
| `src/Api/Program.cs` | API 入口点 | 第1周 |
| `src/SharedKernel/Domain/` | 领域模型 | 第1周 |
| `docs/architecture/` | 架构文档 | 第1周 |

### 代码约定

**命名：**

- 类：`PascalCase`
- 方法：`PascalCase`
- 变量：`camelCase`
- 常量：`UPPER_SNAKE_CASE`
- 文件：匹配类名

**项目结构：**

- 垂直切片架构
- 功能文件夹优先于层级文件夹
- 每个文件一个类（记录类型除外）

---

## 开发工作流程

### Git 工作流程

```text
main ────────────────────────────────────────────────────────►
       │                                          │
       └── feature/ABC-123-add-user-auth ─────────┘
             │     │     │
             ▼     ▼     ▼
          提交   提交   提交
```

**分支命名：**

- `feature/TICKET-描述` - 新功能
- `fix/TICKET-描述` - 错误修复
- `chore/描述` - 维护任务

**提交消息：**

```text
类型(范围): 描述

feat(auth): 添加 Azure AD 的 OAuth2 支持
fix(api): 解决用户服务中的空引用
docs(readme): 更新安装说明
```

### 代码审查流程

1. 从 `main` 创建功能分支
2. 进行有意义的更改并提交
3. 推送并创建拉取请求
4. 请求团队成员审查
5. 处理反馈
6. 批准后合并（压缩合并）

### 测试要求

- 所有新代码必须有测试
- 新功能最低 80% 代码覆盖率
- API 端点的集成测试
- 关键用户流程的端到端测试

```bash
# 运行所有测试
dotnet test

# 运行覆盖率测试
dotnet test --collect:"XPlat Code Coverage"

# 运行特定测试项目
dotnet test tests/Unit/
```

---

## 常见任务

### 添加新 API 端点

1. 在 `src/Api/Features/` 中创建功能文件夹
2. 添加请求/响应模型
3. 实现端点处理程序
4. 添加验证
5. 编写测试
6. 更新 OpenAPI 文档

**示例：**

```csharp
// src/Api/Features/Users/GetUser.cs
public static class GetUser
{
    public sealed record Response(Guid Id, string Name, string Email);

    public static void Map(IEndpointRouteBuilder app) =>
        app.MapGet("/api/users/{id:guid}", HandleAsync)
           .WithName("GetUser")
           .WithTags("Users")
           .Produces<Response>()
           .ProducesProblem(StatusCodes.Status404NotFound);

    private static async Task<IResult> HandleAsync(
        Guid id,
        IUserRepository repository,
        CancellationToken ct)
    {
        var user = await repository.GetByIdAsync(id, ct);
        return user is null
            ? Results.NotFound()
            : Results.Ok(new Response(user.Id, user.Name, user.Email));
    }
}
```

### 运行数据库迁移

```bash
# 添加新迁移
dotnet ef migrations add AddUserTable -p src/Api -s src/Api

# 应用迁移
dotnet ef database update -p src/Api -s src/Api

# 生成 SQL 脚本
dotnet ef migrations script -p src/Api -s src/Api -o migration.sql
```

### 调试

**VS Code：**

1. 设置断点（F9）
2. 启动调试（F5）
3. 使用调试控制台进行评估

**Rider：**

1. 设置断点
2. 调试（Shift+F9）
3. 使用评估表达式

**日志记录：**

```csharp
_logger.LogInformation("处理请求 {RequestId}", requestId);
_logger.LogError(exception, "处理 {RequestId} 失败", requestId);
```

---

## 学习路径

### 第1周：基础

| 天 | 主题 | 资源 |
|-----|-------|-----------|
| 1 | 环境设置 | 本指南 |
| 2 | 架构概述 | `/docs/architecture/` |
| 3 | 代码库漫游 | 与伙伴配对 |
| 4 | 第一个错误修复 | 分配的入门问题 |
| 5 | 代码审查 | 审查队友的 PR |

### 第2-4周：能力建设

- [ ] 完成一个端到端的小功能
- [ ] 编写集成测试
- [ ] 参与冲刺规划
- [ ] 在团队站会中发言
- [ ] 影子随叫随到轮换

### 第2-3个月：独立

- [ ] 负责中等规模功能
- [ ] 指导新团队成员
- [ ] 贡献文档
- [ ] 加入随叫随到轮换
- [ ] 向团队展示技术主题

---

## 获取帮助

### 入职伙伴

您的入职伙伴是：**[姓名]**

- Slack：@[句柄]
- 邮箱：[邮箱]

他们是您提问的第一联系人！

### 团队频道

| 频道 | 目的 |
|---------|---------|
| #team-[名称] | 一般团队讨论 |
| #team-[名称]-dev | 技术问题 |
| #incidents | 生产问题 |
| #random | 非工作聊天 |

### 升级

如果遇到阻碍：

1. **先尝试自助**：搜索文档、Slack 历史、Stack Overflow
2. **在团队频道提问**：其他人可能有相同问题
3. **直接消息伙伴**：快速问题
4. **安排一对一**：较长讨论

---

## 常见问题

**问：如何获取访问 [系统] 的权限？**
答：在 #access-requests 频道请求，并附上经理的批准。

**问：在哪里找到 [文档]？**
答：从 [文档网站网址] 开始。使用搜索或在 #team-dev 中提问。

**问：如果测试在 CI 上失败，我该怎么办？**
答：先检查 CI 日志。如果不清楚，在 #team-dev 中提问，并附上失败构建的链接。

**问：如何部署到暂存环境？**
答：合并到 `main` 会自动部署到暂存。查看 #deployments 频道。

---

## 反馈

我们持续改进入职流程。请分享您的体验：

- 什么做得很好？
- 什么令人困惑？
- 缺少什么？

发送反馈至：[邮箱/表单/频道]

---

**下次审查：**[日期]

学习路径模板

# 学习路径：[角色/技术]

## 概述

本学习路径帮助您精通 [主题]。

**预计时长：** [X] 周
**先决条件：** [列表]

---

## 级别1：基础（第1周）

### 目标

- [ ] 理解核心概念
- [ ] 设置开发环境
- [ ] 完成“Hello World”教程

### 资源

| 类型 | 资源 | 时间 |
|------|----------|------|
| 视频 | [X 介绍] | 30 分钟 |
| 教程 | [入门] | 2 小时 |
| 文档 | [核心概念] | 1 小时 |

### 练习

1. [练习 1]
2. [练习 2]

### 检查点

- 您能用自己的话解释 [概念] 吗？
- 您构建了 [工件] 吗？

---

## 级别2：中级（第2-3周）

### 目标

- [ ] 构建完整功能
- [ ] 理解 [高级主题]
- [ ] 编写测试

### 资源

| 类型 | 资源 | 时间 |
|------|----------|------|
| 课程 | [X 深度探索] | 4 小时 |
| 书籍 | [推荐阅读] 第1-5章 | 3 小时 |
| 实践 | [动手实验] | 2 小时 |

### 项目

构建 [项目描述]，展示：
- [技能 1]
- [技能 2]
- [技能 3]

### 检查点

- 您能 [任务] 而不参考文档吗？
- 您完成 [项目] 了吗？

---

## 级别3：高级（第4周+）

### 目标

- [ ] 优化性能
- [ ] 处理边缘情况
- [ ] 指导他人

### 资源

| 类型 | 资源 | 时间 |
|------|----------|------|
| 高级 | [性能优化] | 2 小时 |
| 案例研究 | [真实世界示例] | 1 小时 |
| 社区 | [贡献给 OSS] | 持续 |

### 里程碑

当您能够：
- [ ] 独立设计解决方案
- [ ] 自信地审查他人代码
- [ ] 向利益相关者解释权衡时，您已达到熟练水平

最佳实践

内容原则

原则	描述
渐进式	从简单开始，增加复杂性
实用	注重实践，不仅仅是阅读
最新	与系统变化保持同步
可访问	易于查找和导航
反馈驱动	基于新员工反馈迭代

避免的反模式

第1天信息过多
未经验证就假设先前知识
过时的设置说明
没有检查点/验证步骤
缺少“获取帮助”信息

工作流程

创建入职文档时：

审核当前状态：存在什么？什么过时？
采访最近入职者：什么令人困惑？缺少什么？
定义学习目标：每个阶段他们应该知道什么？
创建渐进式内容：第1天 → 第1周 → 第1个月
添加验证步骤：他们如何知道成功？
真实用户测试：让某人跟随指南
迭代：基于反馈更新

参考

详细指导：

最后更新： 2025-12-26

名称：入职文档 描述：开发者入职文档和学习路径 允许工具：读取、全局搜索、grep、写入、编辑

入职文档技能

何时使用此技能

概述

强制：文档优先方法

入职文档框架

入职指南模板

学习路径模板

最佳实践

内容原则

避免的反模式

工作流程

参考

名称：入职文档描述：开发者入职文档和学习路径允许工具：读取、全局搜索、grep、写入、编辑