Azure-Samples/DevOpsEngineerPersona

# 🎁 Zava 礼品交换 使用 React + Vite、Azure Functions 和 Azure Cosmos DB 构建的礼品交换 Web 应用程序。 [](https://github.com/Azure-Samples/DevOpsEngineerPersona/actions/workflows/ci-cd.yml) [](https://codespaces.new/Azure-Samples/DevOpsEngineerPersona?quickstart=1) ## ✨ 功能特性 - 🌍 **多语言支持**：完整支持 9 种语言——英语、西班牙语、葡萄牙语、意大利语、法语、日语、中文、德语和荷兰语 - 🎲 **加密安全分配**：使用 `crypto.randomInt` + Fisher-Yates 算法实现公平循环洗牌 - 🔒 **受保护的游戏**：可选参与者令牌，使用定时安全比较 - 📧 **电子邮件通知**：可选的 Azure Communication Services 集成，支持 13+ 种通知类型 - 🔄 **重新分配**：组织者可单独或批量重新分配；参与者可请求新分配 - 👤 **组织者面板**：完整的游戏管理，包括单独/批量重新分配、参与者编辑和状态跟踪 - 🚫 **排除规则**：防止特定配对匹配（例如情侣）——目前仅限 API；UI 配置计划中 - 📅 **日期验证**：游戏只能在今天或未来日期创建，输入长度有限制 - ⏱️ **活动倒计时**：显示距离活动开始的实时倒计时 - 📅 **日历集成**：下载 `.ics` 文件以将事件添加到任何日历应用 - 📱 **二维码分享**：生成邀请链接的二维码，带有仅邀请标签 - 🌙 **深色模式**：在所有页面切换深色主题，并检测操作系统偏好 - 📱 **PWA 支持**：可作为渐进式 Web 应用安装，支持离线缓存 - 🔐 **API 速率限制**：所有 API 端点均实施基于 IP 的速率限制（游戏创建、检索、更新、邮件） - 🛡️ **强化 CSP 与 HSTS**：严格 CSP、HSTS、`Permissions-Policy`，无 `unsafe-eval`，`frame-ancestors 'none'` - 🧹 **自动清理**：游戏在活动日期后 3 天归档，30 天后永久删除（符合 GDPR） - 📤 **Web Share API**：在支持的移动设备上通过 `navigator.share()` 进行原生分享 - 📊 **应用洞察**：前端和后端监控、错误跟踪和性能遥测 - ♿ **无障碍测试**：通过 axe-core 在 E2E 测试中自动执行 WCAG 2.0 AA 合规性检查 - 🧪 **跨浏览器 E2E**：Playwright 测试支持本地 Chromium、Firefox 和 WebKit；CI 默认运行 Chromium ## 🏗️ 环境策略 | 环境 | 资源组 | 静态 Web 应用 | Cosmos DB | 生命周期 | |------|--------|--------------|-----------|----------| | **PR 预览** | `ZavaGiftExchange-pr-{number}` | 标准 | 服务器无状态 | PR 打开时创建，关闭时删除 | | **QA** | `ZavaGiftExchange-qa` | 标准 | 服务器无状态 | 持续存在（与生产隔离） | | **生产** | `ZavaGiftExchange` | 标准 | 服务器无状态 | 持续存在（无限扩展） | 所有环境均使用 **标准层级静态 Web 应用** 和 **Cosmos DB 服务器无状态**（按请求付费），以最大程度兼容 Azure 订阅。如果您的订阅支持，您可以通过更改参数文件中的 `staticWebAppSku` 将 PR/QA 降级为免费 SWA 层级，并启用 [Cosmos DB 免费层级](https://learn.microsoft.com/azure/cosmos-db/free-tier)，向 `infra/parameters.qa.json` 添加 `"enableFreeTier": { "value": true }`。 每个环境都有其 **独立的静态 Web 应用** 和 **独立的 Cosmos DB**（QA 与生产完全隔离）。 所有环境均**自动配置**以下内容： - Cosmos DB 连接 - 应用洞察 - Azure Communication Services（QA/生产） ## 前提条件 在开始之前，请确保您的系统（macOS、Windows 或 Linux）已安装以下工具： ### 必需 - **Node.js 20+** - [下载](https://nodejs.org/) - 验证：`node --version`（应为 v20 或更高） - **Docker & Docker Compose** - [下载](https://www.docker.com/products/docker-desktop) - 验证：`docker --version` 和 `docker-compose --version` - **Windows 用户**：推荐使用 Docker Desktop for Windows - **Linux 用户**：分别安装 Docker Engine 和 Docker Compose - **macOS 用户**：推荐使用 Docker Desktop for Mac - **Git** - [下载](https://git-scm.com/) - 验证：`git --version` - **VS Code** - [下载](https://code.visualstudio.com/) - 安装扩展：**Azure Functions**（ms-azuretools.vscode-azurefunctions） ### 可选（用于 Azure 部署） - **Azure CLI** - [下载](https://learn.microsoft.com/cli/azure/install-azure-cli) - 仅在部署到 Azure 时需要 - 验证：`az --version` ### 验证所有前提条件 ``` node --version # Should be v20+ docker --version # Docker version docker-compose --version # Docker Compose version git --version # Git version ``` 所有前提条件在 **Windows、macOS 和 Linux** 上的工作方式相同。 ## 🚀 快速开始 ### 选项 1：云端开发（推荐初学者） **GitHub Codespaces** - 无需安装，完全在浏览器中开发： 1. 点击：[](https://codespaces.new/Azure-Samples/DevOpsEngineerPersona?quickstart=1) 2. 等待约 60 秒以构建容器 3. 在 VS Code 中按 **F5**（浏览器版本） 4. 点击通知以在浏览器中打开前端 ✅ **零配置！** 所有内容已预先配置并运行。 [📖 完整 Codespaces 指南](docs/codespaces-setup.md) ### 选项 2：本地开发（需要 Docker） 在本地机器上运行所有内容： ``` # 克隆仓库 git clone https://github.com/Azure-Samples/DevOpsEngineerPersona.git cd DevOpsEngineerPersona # 启动全栈（Docker + API + 前端） npm install cd api && npm install cd .. # 然后在 VS Code 中按 F5 调试，或： docker-compose up -d # Start Docker containers npm run dev # Frontend dev server cd api && npm start # API in separate terminal ``` 打开：http://localhost:5173 [📖 完整本地开发指南](docs/getting-started.md) ### 选项 3：部署到 Azure 1. **分叉此仓库** 2. **配置 GitHub OIDC 身份验证**： # 创建服务主体 az ad sp create-for-rbac --name "ZavaGiftExchange-github" \ --role contributor \ --scopes /subscriptions/{subscription-id} --json-auth 3. **添加 GitHub 密钥**（设置 → 密钥）： - `AZURE_CREDENTIALS` - 粘贴上述命令的完整 JSON 输出 4. **创建生产资源组**： az group create --name ZavaGiftExchange --location eastus2 5. **打开 PR** - 完整基础设施将自动创建！ 请参阅 [docs/github-deployment.md](docs/github-deployment.md) 获取详细设置说明。 ## 📁 项目结构 ``` ├── src/ # React frontend │ ├── components/ # UI components (views, forms, dialogs) │ ├── lib/ # Utilities, types, translations, calendar, sharing │ ├── hooks/ # Custom React hooks (dark mode, localStorage, mobile) │ └── styles/ # CSS theme (light/dark mode) ├── api/ # Azure Functions backend │ └── src/ │ ├── functions/ # HTTP endpoints │ └── shared/ # Cosmos DB, email, telemetry, rate limiter ├── e2e/ # Playwright E2E tests (Chromium, Firefox, WebKit) ├── tests/load/ # Azure Load Testing (JMeter + config) ├── infra/ # Bicep infrastructure templates │ └── modules/ # Monitoring alerts module ├── public/ # PWA manifest, service worker, static assets ├── scripts/ # Utility scripts (type validation, setup) ├── docs/ │ └── runbooks/ # SRE runbooks (error rate, DB outage, rollback) └── .github/ ├── copilot-instructions.md # Global project context ├── copilot-constitution.md # Non-negotiable rules for all agents ├── copilot-memory.md # Architecture decisions & known gotchas ├── agents/ # 6 specialized Copilot agents ├── specs/ # Specification templates & examples ├── prompts/ # Reusable prompt library ├── CODEOWNERS # File ownership mapping └── workflows/ # CI/CD pipelines (5) ``` ### 前端视图 - **HomeView**：带有游戏代码输入和深色模式切换的着陆页 - **CreateGameView**：带有日期验证和排除规则的游戏创建表单 - **GameCreatedView**：包含组织者令牌和二维码分享的成功页面 - **ParticipantSelectionView**：受保护游戏的参与者登录 - **AssignmentView**：显示分配，包含活动倒计时、日历下载和心愿编辑 - **OrganizerPanelView**：完整的游戏管理（包括删除功能） - **PrivacyView**：数据处理和保留策略 - **GameNotFoundView**：删除或无效游戏的错误页面 ## 🔧 配置 ### 环境变量（自动配置在 Azure 中） | 变量 | 描述 | 自动设置 | |------|------|:--------:| | `COSMOS_ENDPOINT` | Cosmos DB 终结点 URL | ✅ | | `COSMOS_KEY` | Cosmos DB 主密钥 | ✅ | | `COSMOS_DATABASE_NAME` | 数据库名称 | ✅ | | `COSMOS_CONTAINER_NAME` | 容器名称 | ✅ | | `APPLICATIONINSIGHTS_CONNECTION_STRING` | 应用洞察连接 | ✅ | | `APPINSIGHTS_INSTRUMENTATIONKEY` | 应用洞察密钥 | ✅ | | `APP_BASE_URL` | 应用 URL | ✅ | | `ACS_CONNECTION` | 邮件服务连接 | ✅* | | `ACS_SENDER_ADDRESS` | 邮件发送地址 | ✅* | | `ENVIRONMENT` | 环境名称（pr/qa/prod） | ✅ | | `BUILD_VERSION` | 构建版本标识符 | ✅ | | `BUILD_DATE` | 部署时间戳 | ✅ | | `CLEANUP_SECRET` | 用于清理端点认证的密钥 | ✅ | *仅在 QA/生产环境中启用邮件功能时 ### GitHub 密钥（必需） | 密钥 | 描述 | |------|------| | `AZURE_CREDENTIALS` | 完整 JSON 输出，来自 `az ad sp create-for-rbac` 命令（包括 appId、tenant、subscriptionId、password） | | `CLEANUP_SECRET` | 用于清理 HTTP 端点的共享密钥。生成强随机值（例如 `openssl rand -base64 32`）。由 GitHub Actions 定时清理作业使用，该作业每天 UTC 时间凌晨 2:00 运行 | ### 无需变量 资源组名称和部署 URL 现在动态生成并从基础设施部署步骤输出。 ## 🧪 测试 ``` # API 单元测试（15 个套件中的 332 个测试） cd api && npm test # 验证前端与 API 之间的共享类型保持同步 npm run validate:types # E2E 测试（在 Chromium、Firefox 和 WebKit 中运行） npm run test:e2e # E2E 带 UI npm run test:e2e:ui ``` E2E 测试包含使用 [axe-core](https://github.com/dequelabs/axe-core) 的自动化无障碍扫描，符合 WCAG 2.0 AA 标准。 ## 🔄 CI/CD 流水线 | 阶段 | 触发条件 | 描述 | |------|----------|------| | 构建与测试 | 所有 PR 和主分支 | 代码检查、构建、单元测试 | | **PR 基础设施** | PR 打开 | 创建资源组和专用 SWA | | 预览 | PR | 部署到 PR 静态 Web 应用 | | **关闭 PR** | PR 关闭 | 删除资源组 | | QA 基础设施 | 主分支合并 | 部署 QA 静态 Web 应用 + 负载测试资源 | | QA | 主分支合并 | 部署到 QA | | E2E（QA） | QA 部署后 | 在 QA 上运行 E2E 测试 | | **负载测试（QA）** | QA E2E 后 | 对 QA API 运行 Azure 负载测试 | | 生产基础设施 | 负载测试后 | 部署生产 SWA | | 生产 | 生产基础设施后 | 需要手动批准 | ## 📊 监控 每个环境均包含应用洞察，用于： - 错误跟踪和诊断 - 性能监控 - 自定义事件日志记录 ### 健康端点 - `GET /api/health` - 完整诊断（版本、运行时间、依赖项） - `GET /api/health/live` - 存活探针 - `GET /api/health/ready` - 就绪探针（检查数据库） ## 🗑️ 数据保留 - **自动删除**：游戏在事件日期后 3 天通过 GitHub Actions 定时工作流自动删除，该工作流每天 UTC 时间凌晨 2:00 调用 `/api/games/cleanup` HTTP 端点。认证通过 `x-cleanup-secret` 请求头，其值必须匹配 `CLEANUP_SECRET` 应用设置。 - **手动删除**：组织者可随时从组织者面板删除游戏 - **隐私**：请参阅应用内隐私页面以了解完整的数据处理详情 - **不共享外部数据**：数据绝不会共享给第三方 ## 🔒 安全要点 - **加密安全随机数**：所有令牌、游戏代码和分配均使用 `crypto.randomInt` / `crypto.randomUUID` 生成，包括客户端离线操作 - **定时安全比较**：所有令牌验证均使用 `crypto.timingSafeEqual`，在长度不匹配时执行虚拟比较以防止定时侧信道攻击 - **输入验证与长度限制**：所有字段均实施最大长度限制（名称：80 字符，备注：2000 字符，最多 100 名参与者） - **速率限制**：所有 API 端点均实施基于 IP 的速率限制——游戏创建（10/分钟）、邮件（20/分钟）、常规（60/分钟） - **内容安全策略**：严格 CSP 配合 HSTS，无 `unsafe-eval`，`frame-ancestors 'none'`，`Permissions-Policy` - **不泄露错误**：API 错误响应从不暴露内部细节或堆栈跟踪 - **HTML 转义邮件**：所有用户内容在嵌入邮件模板前均进行 HTML 转义 - **游戏代码冲突检测**：新游戏代码会检查是否与现有代码冲突以防止重复 - **生产环境 TLS 保护**：阻止 Cosmos DB 模拟器的 TLS 旁路在生产环境中使用 - **符合 GDPR 的数据保留**：归档的游戏在 30 天后永久删除 - **Service Worker 安全**：仅缓存静态资源——从不缓存 API 响应或动态内容 - **localStorage TTL**：旧游戏数据在 30 天后自动清理 请参阅 [SECURITY.md](SECURITY.md) 获取漏洞报告和完整安全策略。 ## 🤖 GitHub Copilot 代理 该项目在 `.github/agents/` 中包含 **6 个专业 Copilot 代理**，演示如何将 AI 助手限定到特定角色并设置适当的访问级别： | 代理 | 角色 | 访问级别 | |------|------|----------| | **文档编写者** | 更新文档、README 和指南 | 仅写入 `.md` 文件 | | **测试工程师** | 编写和维护单元测试与 E2E 测试 | 仅写入测试文件 | | **功能分析师** | 分析功能请求并提出改进建议 | 只读 | | **安全审核员** | OWASP 审计、漏洞分析 | 只读 | | **DevOps 工程师** | CI/CD、Bicep、Docker、部署配置 | 写入基础设施/工作流文件 | | **本地化专家** | 管理 9 种语言的翻译 | 仅写入翻译文件 | 每个代理均具备： - **限定权限**——仅能修改与其角色相关的文件 - **领域上下文**——理解项目架构和约定 - **任务模式**——包含常见任务的模板和示例 ### 代理化 DevOps 框架 除了代理之外，本仓库还演示了完整的 **代理化 DevOps** 方法，如 [DevOps 自动化手册](https://devblogs.microsoft.com/all-things-azure/agentic-devops-practices-principles-strategic-direction/) 中所述： | 资产 | 用途 | 手册章节 | |------|------|----------| | **宪法**（`.github/copilot-constitution.md`） | 所有代理必须遵守的不可变规则 | §4 面向代理的设计 | | **内存**（`.github/copilot-memory.md`） | 架构决策、已知问题、反模式 | §4 仓库作为接口 | | **规范套件**（`.github/specs/`） | 功能、错误、基础设施的结构化规范模板 | §5 从提示到规范 | | **提示库**（`.github/prompts/`） | 可重用的开发任务提示 | §6 构建代理团队 | | **CODEOWNERS**（`.github/CODEOWNERS`） | 文件所有权映射到代理范围 | §6 治理框架 | | **负载测试**（`tests/load/`） | Azure 负载测试配置 + JMeter 计划 | §7 流水线作为主动验证器 | | **SRE 运行手册**（`docs/runbooks/`） | 事件响应流程 | §7 生产就绪 | | **监控告警**（`infra/modules/monitoring.bicep`） | Azure Monitor 告警规则（错误率、延迟、可用性） | §7 主动验证 | ## 📜 许可证 MIT - 请参阅 [LICENSE](LICENSE) ## 🤝 贡献 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取指南。

标签：Azure Cosmos DB, Azure Functions, Crypto API, CSP, Fisher-Yates, HSTS, ICS, IPv6支持, IP 限流, MITM代理, NTLM Relay, PWA, React, Syscalls, Vite, Web 应用, 中文, 中文简体, 主题切换, 二维码, 云函数, 令牌验证, 保护游戏, 倒计时, 公平洗牌, 加密安全, 单页应用, 国际化, 多语言, 安全标准, 安全策略, 德文, 意大利文, 排除规则, 提示词设计, 日历集成, 日文, 日期验证, 法文, 深色模式, 渐进式 Web 应用, 特征检测, 礼品交换, 礼物交换, 离线缓存, 管理面板, 组织者面板, 自动化攻击, 英文, 荷兰文, 葡萄牙文, 西班牙文, 通信服务, 通知发送, 邀请码, 邮箱通知, 重新分配, 防作弊, 随机分配