# 快速配置 GitHub Project 字段

## 第一步：获取 GitHub Token

1. 访问：https://github.com/settings/tokens/new
2. 勾选权限：
   - ✅ `repo` - 仓库访问
   - ✅ `project` - 项目访问
   - ✅ `write:org` - 组织项目（如果需要）
3. 点击 "Generate token" 并复制 token

## 第二步：设置环境变量

```bash
export GITHUB_TOKEN="your_token_here"
```

## 第三步：预览配置（推荐）

先运行干运行模式，查看会创建哪些字段：

```bash
python3 scripts/setup-project-fields.py \
  --project-number 1 \
  --owner @me \
  --dry-run
```

## 第四步：应用配置

确认无误后，执行实际配置：

```bash
python3 scripts/setup-project-fields.py \
  --project-number 1 \
  --owner @me
```

## 将会创建的字段

| 字段名 | 类型 | 选项/说明 |
|--------|------|-----------|
| **Phase** | 单选 | Requirements, Design, Development, Testing, Deployment, Operations |
| **Doc Type** | 单选 | BRD, PRD, Design, API, Test Case, Test Report, Deployment, Operations |
| **Document Priority** | 单选 | P0-Critical, P1-High, P2-Medium, P3-Low |
| **Document Status** | 单选 | Draft, Review, Approved, Implemented, Archived |
| **Progress** | 数字 | 0-100 的进度百分比 |
| **Blocking** | 文本 | 阻塞因素描述 |
| **Dependencies** | 文本 | 依赖的 Issue 编号 |

## 配置后的使用

1. **打开你的项目**：https://github.com/users/BrunoGao/projects/1

2. **为 Issue 设置字段值**：
   - 在项目看板中点击 Issue 卡片
   - 右侧面板会显示所有自定义字段
   - 选择/输入对应的值

3. **按字段分组查看**：
   - 点击看板上方的 "Group by" 按钮
   - 选择字段（如 "Phase"）
   - 看板会自动按阶段分组显示

## 关于字段作用域的说明

✅ **这些字段对你的项目是通用的！**

- 字段配置是**项目级别**的，不是仓库级别的
- 你的项目 #1 可以包含来自不同仓库的 Issues
- 所有添加到项目 #1 的 Issues 都可以使用这些字段
- 例如：
  ```
  你的 Project #1 (SDLC Management)
  ├── gold-template/issues/1      ✅ 可以使用所有字段
  ├── gold-template/issues/2      ✅ 可以使用所有字段
  ├── another-repo/issues/5       ✅ 可以使用所有字段
  └── third-repo/issues/10        ✅ 可以使用所有字段
  ```

❌ **但不会自动在不同项目间共享**

- 如果你创建了项目 #2，需要重新配置字段
- 可以使用相同的脚本快速配置
- 或使用配置文件模板保证一致性

## 故障排除

### 问题：Token 权限不足
```bash
# 检查 token 权限
gh auth status
```

### 问题：找不到项目
```bash
# 列出所有项目
gh project list --owner @me

# 确认项目编号
```

### 问题：字段已存在
脚本会自动跳过已存在的字段，只添加缺失的字段。

## 更多信息

- 详细文档：`docs/best-practices/project-fields-quickstart.md`
- 配置说明：`docs/best-practices/github-projects-configuration.md`
- 配置模板：`config/project-fields-template.yml`