---
name: local-browser-acceptance-workflow
type: procedure
when: '本地验收, 浏览器验收, Docker 验收, 本地测试, local acceptance, browser test, docker compose'
scope:
  - backend
  - frontend
  - infrastructure
products:
  - '*'
owner_mechanism_id: mc-local-acceptance
consumed_contracts:
  - local_acceptance_contract_entry
  - coding_readiness_contract_entry
  - detail_discipline_contract
required_sections:
  - 服务运行规格
  - 浏览器验收计划
  - 修复循环策略
  - 最终访问交付
hard_rules:
  - 有可运行前端/全栈服务时，不得只停在单测、静态检查或审查报告
  - 项目已有 docker-compose 时必须优先使用
  - 必须识别 frontend、backend、database、env、ports 和 health checks
  - 服务启动后必须等待 container healthy、backend health、frontend reachable
  - >-
    浏览器验收失败必须 capture → classify → map owner → repair → rebuild → redeploy →
    rerun
  - 最终必须给用户本地可访问 URL、运行状态、启动/停止命令
  - 未给最终本地 URL 不得 delivered
acceptance_checks:
  - requiresLocalAcceptance 判断正确
  - ServiceRuntimeSpec 已识别所有服务
  - 浏览器验收计划覆盖任务相关页面和路由
  - 修复循环策略包含 max_iterations 和 stop_conditions
  - FinalLocalReviewAccess 包含 frontend_urls/backend_urls/docs_or_swagger_urls
  - validateFinalAccess passed
id: ka-procedure-本地浏览器验收工作流
asset_kind: procedure
lifecycle_status: active
authority: supporting
routes:
  - code_change
primary_triggers:
  - 本地浏览器验收工作流
secondary_triggers: []
negative_triggers: []
priority: P1
specificity: 5
consumes:
  - mc-local-acceptance
emits:
  - browser_acceptance_report
  - service_urls
required_evidence:
  - workflow_id
  - required_mechanisms
version: 1.1.0
last_reviewed: '2026-06-01'
stages: ["联调验证"]
---

## 适用场景
含前端/全栈服务的项目完成开发后，必须在本地启动服务并通过浏览器验收。适用于有 docker-compose、npm start 或类似启动方式的项目。

## 步骤
1. **判断是否需要本地验收**: requiresLocalAcceptance 判断
2. **服务运行规格**:
   - 识别 frontend、backend、database/cache、env、ports、health checks
   - docker-compose 优先，否则用项目启动命令
3. **启动服务**:
   - 启动所有服务
   - 等待 container healthy、backend health endpoint、frontend reachable、DB migrated
   - 检查 logs 无关键错误、port open
4. **浏览器验收**:
   - 覆盖任务相关页面、路由、核心交互
   - API 联动、登录/权限、错误提示、空状态/loading
   - 检查控制台关键错误和 network 关键失败
5. **失败处理** (修复循环):
   - capture failure → classify failure → map owner files
   - repair within scope → rebuild → redeploy → rerun
   - retry budget 内循环；超预算 → manual_required
6. **最终交付**:
   - 给用户 frontend/backend/docs/swagger 本地 URL
   - 给用户运行状态、启动/停止命令、测试账号说明、人工查验步骤、未覆盖风险

## 检查点
- [ ] requiresLocalAcceptance 判断正确
- [ ] 所有服务启动且 healthy
- [ ] 浏览器验收覆盖关键页面
- [ ] 修复循环有预算和停止条件
- [ ] 最终 URL 交付完整

## 禁止退化
- 不得只停在单测或审查报告
- 无 URL 不得 delivered
- CI 环境无 Docker 时 not_applicable_with_reason，但不能把 runnable 项目判为 delivered
- retry budget 超出或 scope 不足必须 manual_required
