ljwx-children/TEMPLATE-USAGE-GUIDE.md

📘 Gold Template 使用指南

适用人群： 想要快速启动生产级 Python 项目的开发者 预计时间： 30 分钟从零到生产就绪 难度等级： ⭐⭐ (需要基础 Python 和 Git 知识)

---

🎯 使用此模板的理由

传统方式 vs Gold Template

任务	传统方式	Gold Template	节省时间
项目初始化	2-3 天	30 分钟	~95%
CI/CD 配置	1-2 周	已完成	100%
测试框架	3-5 天	已完成（85+ 测试）	~95%
安全扫描	1 周	已完成（7 工具）	100%
Kubernetes 部署	2-3 周	已完成	~95%
可观测性	2-4 周	已完成	~95%
GitHub Projects	1 周	已完成（SDLC Console）	~95%
文档系统	持续	已完成（模板）	~70%
总计	2-3 个月	30 分钟	~95%

---

🚀 三种使用方式

方式 1: GitHub UI（推荐新手）

最简单的方式，适合不熟悉命令行的用户。

步骤：

1. 访问：https://github.com/BrunoGaoSZ/gold-template
2. 点击绿色的 "Use this template" 按钮
3. 填写新项目名称和描述
4. 选择 Public 或 Private
5. 点击 "Create repository from template"
6. 克隆新仓库到本地：

   git clone https://github.com/YOUR_USERNAME/YOUR_PROJECT.git
   cd YOUR_PROJECT
   

7. 运行初始化脚本：

   ./scripts/init-from-template.sh
   

方式 2: GitHub CLI（推荐开发者）

最快的方式，适合熟悉命令行的用户。

# 一键创建新项目
gh repo create my-awesome-project \
  --template BrunoGaoSZ/gold-template \
  --public \
  --clone

# 进入项目目录
cd my-awesome-project

# 运行初始化向导
./scripts/init-from-template.sh

# 验证设置
./scripts/verify-template-setup.sh

方式 3: 手动克隆（高级用户）

完全控制的方式，适合需要定制化的用户。

# 克隆模板
git clone https://github.com/BrunoGaoSZ/gold-template.git my-project
cd my-project

# 移除 Git 历史（干净起点）
rm -rf .git
git init

# 运行初始化
./scripts/init-from-template.sh

# 创建远程仓库并推送
gh repo create my-project --public --source=.
git remote add origin https://github.com/YOUR_USERNAME/my-project.git
git add .
git commit -m "chore: initialize from gold-template"
git push -u origin main

---

📋 初始化向导详解

运行 ./scripts/init-from-template.sh 后，向导会引导你完成 10 个步骤：

Step 1: 项目信息

Enter your project name: my-awesome-api
Enter your GitHub username/org: myusername
Enter project description: A production-ready FastAPI service
Enter your name/organization: John Doe
Enter your email: [email protected]

Step 2: 更新项目名称

自动替换所有文件中的 "gold-template" 为你的项目名。

影响的文件：

• README.md
• pyproject.toml
• deployment/helm/**/*.yaml
• 所有配置文件

Step 3: 创建 GitHub Project

可选，自动创建 SDLC 控制台。

如果选择 Yes：

• 创建 GitHub Project
• 添加 9 个自定义字段
• 自动配置

Step 4: GitHub Actions Secrets

提示需要手动配置的密钥（AWS、Docker等）。

Step 5: 环境配置

从 .env.example 创建 .env 并生成随机密钥。

Step 6: Git Hooks

安装 pre-commit 和 pre-push hooks。

Step 7: 数据库初始化

运行 Alembic 迁移。

Step 8: 安装依赖

创建虚拟环境并安装 Python 包。

Step 9: 验证安装

运行测试确保一切正常。

Step 10: 初始提交

创建第一个 Git commit。

---

✅ 验证设置

初始化完成后，运行验证脚本：

./scripts/verify-template-setup.sh

预期输出：

╔════════════════════════════════════════════════════════════╗
║   Verification Summary                                     ║
╚════════════════════════════════════════════════════════════╝

✓ Passed:  45 / 50
✗ Failed:  0 / 50
⚠ Warnings: 5 / 50

Overall Status: 90%

╔════════════════════════════════════════════════════════════╗
║   ✅ Setup is good, with some optional improvements       ║
╚════════════════════════════════════════════════════════════╝

如果有失败项：

1. 查看错误信息
2. 运行建议的修复命令
3. 重新运行验证

---

🎨 设置 SDLC 控制台（15 分钟）

初始化后，设置 GitHub Projects 的 6 个专业视图：

快速设置

# 1. 添加 SDLC 字段（自动）
./scripts/setup-sdlc-fields.sh PROJECT_NUMBER YOUR_ORG

# 2. 按照指南创建视图
cat docs/SDLC-DASHBOARD-SETUP.md

手动设置

访问你的 GitHub Project，创建以下视图：

View 1: 📊 SDLC Exec Dashboard

Type: Board
Group by: Phase
Filter: Status != Done
Sort by: Risk (High to Low)

View 2: 🚧 Blocked & High Risk

Type: Table
Filter: Risk = "High" OR Risk = "Critical" OR SDLC Stage = "Blocked"
Sort by: Risk (High to Low)

View 3: 🧠 AI Execution Zone

Type: Board
Group by: SDLC Stage
Filter: Owner Type = "AI" OR Owner Type = "AI + Human Review"

View 4: 🚀 Delivery Radar

Type: Table
Filter: Phase = "Phase 3 - Delivery" OR Phase = "Phase 4 - Stabilization"
Sort by: Health, SDLC Stage

View 5: 🧪 Implementing without PR

Type: Table
Filter: SDLC Stage = "Implementing" AND Linked pull requests is empty
Sort by: Updated (Oldest first)

View 6: 📈 Progress by Phase

Type: Table
Group by: Phase
Sort by: Health, Completion %

详细步骤： 参考 docs/SDLC-DASHBOARD-SETUP.md

---

🔧 定制化配置

1. 重命名项目

如果需要更改项目名称：

./scripts/rename-project.sh "new-project-name" "New Project Description"

2. 更换后端框架

从 FastAPI 切换到 Flask：

# backend/main.py
from flask import Flask

app = Flask(__name__)

@app.route('/')
def hello():
    return {'message': 'Hello World'}

更新 requirements.txt：

flask>=3.0.0

3. 更换数据库

从 PostgreSQL 切换到 MongoDB：

# backend/models/__init__.py
from motor.motor_asyncio import AsyncIOMotorClient

client = AsyncIOMotorClient(os.getenv("MONGODB_URL"))
db = client.get_database("mydb")

更新 requirements.txt：

motor>=3.3.0

4. 移除不需要的组件

# 移除可观测性组件
./scripts/remove-component.sh observability

# 移除性能测试
./scripts/remove-component.sh performance-testing

# 移除 Terraform
./scripts/remove-component.sh terraform

# 移除 Claude Skills
./scripts/remove-component.sh claude-skills

---

📊 GitHub Projects 使用

创建第一个 Issue

# 使用 SDLC 模板
gh issue create --template .github/ISSUE_TEMPLATE/sdlc-task.yml

# 或在 GitHub UI:
# Issues → New Issue → 🎯 SDLC Task

填写字段：

• Phase: Phase 2 - Implementation
• SDLC Stage: Backlog
• Risk: Medium
• Owner Type: AI
• Delivery: Code
• Sprint: Sprint 1
• Effort: 5

每日工作流

早晨（5 分钟）：

1. 打开 🚧 Blocked & High Risk 视图
2. 处理红色/黄色的 issues
3. 打开 📊 SDLC Exec Dashboard 查看整体状态

工作中（实时）：

1. 开始设计 → SDLC Stage = "Designing"
2. 开始编码 → SDLC Stage = "Implementing"
3. 创建 PR → 自动添加 "has-pr" label
4. PR 合并 → 自动建议 "Ready to Deploy"

傍晚（5 分钟）：

1. 打开 🧪 Implementing without PR 视图
2. 如果有自己的任务 → 创建 Draft PR
3. 打开 🚀 Delivery Radar 查看本周交付状态

---

🚢 部署到不同环境

本地开发（OrbStack）

# 一键部署到本地 Kubernetes
./scripts/deploy-orbstack.sh

# 验证
kubectl get all -n gold-template

# 访问服务
kubectl port-forward -n gold-template svc/gold-template 8000:8000
open http://localhost:8000/docs

部署到 AWS EKS（Staging）

# 1. 初始化 Terraform
cd terraform/environments/dev
terraform init

# 2. 规划部署
terraform plan

# 3. 应用基础设施
terraform apply

# 4. 配置 kubectl
aws eks update-kubeconfig --name gold-template-dev

# 5. 部署应用（Argo CD）
kubectl apply -f ../../deployment/argocd/application-dev.yaml

# 6. 验证
kubectl get all -n gold-template

部署到 AWS EKS（Production）

# 使用 GitOps（推荐）
git checkout main
git merge develop
git push origin main

# Argo CD 自动：
# 1. 检测 Git 变更
# 2. 运行 PreSync Hook（数据库迁移）
# 3. 部署新版本
# 4. 健康检查
# 5. 失败自动回滚

---

🧪 运行测试

全部测试

# 运行所有测试 + 覆盖率
./scripts/test.sh

# 或手动
pytest --cov=backend --cov-report=html

特定类型

# 单元测试（快速）
pytest tests/unit/ -v

# 集成测试
pytest tests/integration/ -v

# E2E 测试
pytest tests/e2e/ -v

持续测试（开发中）

# 监视模式（需要 pytest-watch）
pip install pytest-watch
ptw -- --cov=backend

---

🤖 使用 Claude Code Skills

Code Review

# 审查最近的变更
python3 .claude/skills/code-review/review.py

# 审查特定文件
python3 .claude/skills/code-review/review.py --target backend/api.py

# 保存报告
python3 .claude/skills/code-review/review.py --output review-report.txt

测试生成

# 为新代码生成测试
python3 .claude/skills/test-generator/generate.py --target backend/models/user.py

# 生成并运行
python3 .claude/skills/test-generator/generate.py --target backend/api.py --run-tests

重构助手

# 检测代码异味
python3 .claude/skills/refactor-assistant/assistant.py --target backend/

# 自定义复杂度阈值
python3 .claude/skills/refactor-assistant/assistant.py --target backend/main.py --complexity-threshold 15

API 设计器

# 生成 OpenAPI spec
python3 .claude/skills/api-designer/design.py --target backend/main.py --format yaml

# 交互式设计
python3 .claude/skills/api-designer/design.py --interactive

Blueprint 检查器

# 检查项目合规性
python3 .claude/skills/blueprint-checker/checker.py

# 预期：23/23 checks passed

---

📚 学习资源

官方文档

• 快速入门： SDLC-CONSOLE-QUICKSTART.md
• 完整指南： docs/SDLC-DASHBOARD-SETUP.md
• 模板 README： .github/template/README.md

视频教程

1. 30 分钟入门 - 从模板到生产部署
2. SDLC 控制台深度解析 - 6 个视图详解
3. AI 开发工作流 - Claude Code 技能使用

示例项目

• FastAPI 微服务 - 完整的 CRUD API
• Kubernetes 部署 - 多环境配置示例
• 观测性集成 - Grafana 仪表盘示例

---

❓ 常见问题

Q1: 我需要什么前置知识？

A:

• 必须： Python 基础、Git 基础
• 推荐： Docker 基础、Kubernetes 概念
• 可选： FastAPI、Terraform

Q2: 可以用于生产环境吗？

A: 可以！此模板已经过生产验证：

• 7 个安全扫描工具

• 80% 测试覆盖率

• 完整的可观测性
• 自动化 CI/CD
• GitOps 部署

Q3: 如何从上游更新模板？

A:

# 添加上游（一次性）
git remote add upstream https://github.com/BrunoGaoSZ/gold-template.git

# 获取更新
git fetch upstream
git merge upstream/main

Q4: 可以用于非 Python 项目吗？

A: 不推荐。此模板专为 Python/FastAPI 优化。 其他语言请寻找对应模板。

Q5: GitHub Project 是必须的吗？

A: 不是必须的，但强烈推荐。SDLC 控制台是此模板的核心价值之一，提供：

• 态势感知
• 风险雷达
• AI 工作流管理
• 自动化状态同步

---

🎯 检查清单

使用此模板后，确保完成：

初始化

• 运行 ./scripts/init-from-template.sh
• 运行 ./scripts/verify-template-setup.sh
• 所有验证检查通过（>90%）

GitHub Projects

• 创建 GitHub Project
• 添加 9 个 SDLC 字段
• 创建 6 个 dashboard 视图
• 创建第一个 issue

配置

• 更新 .env 文件
• 配置 GitHub Actions secrets (AWS, Docker)
• 更新文档（README, docs/）

测试

• 本地测试通过 (./scripts/test.sh)
• CI/CD pipeline 通过
• 安全扫描通过

部署

• 本地 K8s 部署成功 (./scripts/deploy-orbstack.sh)
• Staging 环境部署成功
• Production 环境配置完成

文档

• 更新 README.md
• 自定义 docs/ 内容
• 团队培训完成

---

🎉 下一步

完成初始化后，你可以：

1. 开始开发

   ./scripts/dev.sh
   

2. 创建第一个功能

   gh issue create --template .github/ISSUE_TEMPLATE/sdlc-task.yml
   

3. 部署到 Kubernetes

   ./scripts/deploy-orbstack.sh
   

4. 邀请团队成员

   • 分享 GitHub repo
   • 培训 SDLC 控制台使用
   • 分配第一批任务

5. 监控项目状态

   • 每日查看 Dashboard
   • 周五查看 Progress by Phase
   • 月底查看 Delivery Radar

---

🚀 祝你用这个模板构建出色的项目！

需要帮助？

• Issues: https://github.com/BrunoGaoSZ/gold-template/issues
• Discussions: https://github.com/BrunoGaoSZ/gold-template/discussions

喜欢这个模板？

• ⭐ Star the repo
• 🍴 Fork and customize
• 📢 Share with others