/* 示例 1：自助环境申请的 API 与策略校验（FastAPI + OPA 风格伪代码） */
/* 能力层服务：接收环境创建请求，先过策略引擎，再触发工作流 */
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field
import httpx

app = FastAPI(title="Platform Environments Service")

class EnvironmentRequest(BaseModel):
    service_ref: str = Field(..., pattern=r"^component:default/[a-z0-9-]+$")
    env_type: str = Field(..., pattern="^(preview|staging|production)$")
    ttl_hours: int = Field(default=72, ge=1, le=720)
    size: str = Field(default="small", pattern="^(small|medium|large)$")

async def check_policy(request: EnvironmentRequest, user: str) -> dict:
    """调用 OPA 进行策略校验：配额、权限、变更窗口。"""
    payload = {
        "input": {
            "user": user,
            "service_ref": request.service_ref,
            "env_type": request.env_type,
            "size": request.size,
        }
    }
    async with httpx.AsyncClient() as client:
        resp = await client.post(
            "http://opa.platform.svc:8181/v1/data/platform/env_creation",
            json=payload,
        )
    return resp.json().get("result", {"allowed": False, "reason": "策略服务不可用"})

@app.post("/v1/environments", status_code=202)
async def create_environment(req: EnvironmentRequest, user: str):
    decision = await check_policy(req, user)
    if not decision["allowed"]:
        /* 错误信息包含四要素：发生了什么、为什么、怎么办、找谁 */
        raise HTTPException(
            status_code=403,
            detail={
                "error": decision["reason"],
                "hint": decision.get("remediation", "查看文档或联系平台团队"),
                "docs": "https://platform.acme.internal/docs/environments#quotas",
            },
        )
    workflow_id = await trigger_workflow(req, user)
    return {"workflowId": workflow_id,
            "statusUrl": f"/v1/workflows/{workflow_id}"}

/* 对应的 OPA Rego 策略片段 */
/* package platform.env_creation */
/* default allowed = false */
/* allowed { */
/*   input.env_type == "preview" */
/*   count_existing_envs(input.user) < data.quotas.preview_limit */
/*   is_service_owner(input.user, input.service_ref) */
/* } */

解释：这段代码展示了自助服务能力层的标准请求处理骨架：输入校验 → 策略校验 → 工作流触发 → 异步状态跟踪。Pydantic 模型在入口即实施「枚举而非自由输入」原则——env_type 与 size 用正则限定为固定档位，service_ref 强制使用目录实体引用格式，无效请求在到达策略引擎前就被拒绝（fail fast 的第一层）。策略校验委托给 OPA 而非硬编码在业务逻辑中，这个分离至关重要：配额规则、所有权规则、变更窗口规则由平台/安全团队以 Rego 语言独立维护与版本化，能力服务无需改动即可适应策略演进；Rego 片段中 preview 环境的自动通过条件（配额内 + 是服务所有者）体现了「审批规则代码化」——满足条件即秒批，不满足即拒绝并说明，全程无人工。错误响应的设计是本示例的精髓：detail 中包含 error（为什么被拒）、hint（怎么办）、docs（详细文档链接）三要素，目标是让用户看到错误后能自助修正而非转投工单——错误信息的自助解决率是平台体验的核心指标。202 状态码 + workflowId + statusUrl 的组合是异步长任务的标准 API 模式：环境创建需要 10-20 分钟，同步等待会超时，客户端凭 workflowId 轮询状态或订阅 SSE/WebSocket 事件流，门户 UI 据此渲染实时进度条。这个骨架可以直接复制到所有自助能力（部署、扩缩容、密钥轮换）：变的只是策略包与工作流定义，不变的是「校验→策略→编排→跟踪」的结构。

/* 示例 2：Backstage 脚手架模板的渐进式披露参数设计 */
/* 三层参数：必填最少化、默认可见适中、高级折叠 */
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: create-service-progressive
  title: 创建服务（渐进式披露示例）
spec:
  owner: group:platform-team
  type: service
  parameters:
    /* 第一屏：只问业务必需的问题（2 个必填 + 1 个默认） */
    - title: 基本信息
      required: [name, owner]
      properties:
        name:
          title: 服务名
          type: string
          pattern: "^[a-z][a-z0-9-]{2,40}$"
        owner:
          title: 负责团队
          type: string
          ui:field: OwnerPicker
        runtime:
          title: 运行时
          type: string
          enum: [java17, nodejs20, python312, go122]
          default: java17
          enumNames:
            - Java 17 (Spring Boot)
            - Node.js 20 (Fastify)
            - Python 3.12 (FastAPI)
            - Go 1.22
    /* 第二屏：影响成本与合规的关键选择，附决策辅助信息 */
    - title: 部署配置
      properties:
        tier:
          title: 服务等级
          type: string
          enum: [critical, standard, experimental]
          default: standard
          description: >
            critical: 多可用区 + 99.95% SLO + 24x7 告警（月成本约 +40%）;
            standard: 双副本 + 99.9% SLO（推荐大多数服务）;
            experimental: 单副本，无 SLO 承诺，30 天无流量自动回收
        data_classification:
          title: 数据分类
          type: string
          enum: [public, internal, confidential, restricted]
          default: internal
          description: confidential 及以上将自动启用加密审计与访问审查
    /* 第三屏：Advanced——默认折叠，高级用户定制 */
    - title: 高级选项（可选）
      properties:
        custom_env:
          title: 额外环境变量
          type: object
          additionalProperties:
            type: string
        scheduling:
          title: 调度约束
          type: object
          properties:
            dedicated_node_pool:
              title: 专用节点池（需容量审批）
              type: boolean
              default: false
            gpu:
              title: GPU 资源
              type: boolean
              default: false

解释：这份模板是「渐进式披露」原则的完整示范，其参数组织方式值得逐屏分析。第一屏只包含两个必填项（服务名、负责团队）与一个带智能默认值的单选（运行时）——服务名的正则从源头保证命名规范（小写、连字符、长度限制），运行时的 enumNames 把技术代号翻译为人类可读的框架说明（java17 → Java 17 Spring Boot），减少选择时的认知负荷。第二屏是「影响成本与合规的关键选择」：tier 的 description 为每个档位附上具体后果（多可用区、SLO 承诺、成本增幅），把原本需要咨询架构师的决策信息前置到表单中——这是「决策辅助信息」设计的范例；data_classification 字段尤其巧妙，数据分类本应是安全团队的审批事项，但通过让用户自我声明分类、平台自动施加对应控制（加密、审计、访问审查），审批被转化为自动化策略，用户多填一个字段，组织少一道人工流程。第三屏 Advanced 默认折叠：custom_env 满足特殊配置需求，dedicated_node_pool 与 gpu 这类涉及容量成本的选项标注「需容量审批」——自助流程中嵌入了分级审批的钩子。整体效果：80% 的用户在两屏内、90 秒内完成表单（只面对 5 个字段），高级用户仍有完整的定制空间。对比反面设计——把所有 20 个参数平铺在一屏且全部必填——表单放弃率通常高出 3-5 倍。参数设计的度量方法：埋点统计每屏的停留时间与放弃位置，放弃集中的字段就是需要简化或补充说明的字段。

/* 示例 3：环境 TTL 自动回收的 Kubernetes CronJob 实现 */
/* 防止「自助创建 + 无人删除」的公地悲剧 */
apiVersion: batch/v1
kind: CronJob
metadata:
  name: env-reaper
  namespace: platform-system
spec:
  schedule: "*/30 * * * *"
  jobTemplate:
    spec:
      template:
        spec:
          serviceAccountName: env-reaper
          containers:
            - name: reaper
              image: registry.acme.com/platform/env-reaper:1.4.2
              env:
                - name: DRY_RUN
                  value: "false"
                - name: GRACE_PERIOD_HOURS
                  value: "24"
              command:
                - /bin/sh
                - -c
                - |
                  /* 扫描所有带 platform.acme.com/ttl 注解的 namespace */
                  for ns in $(kubectl get ns -l platform.acme.com/managed=true                     -o jsonpath='{range .items[*]}{.metadata.name}{"\n"}{end}'); do
                    expiry=$(kubectl get ns "$ns"                       -o jsonpath='{.metadata.annotations.platform\.acme\.com/expires-at}')
                    owner=$(kubectl get ns "$ns"                       -o jsonpath='{.metadata.annotations.platform\.acme\.com/owner}')
                    now=$(date -u +%s)
                    if [ "$now" -gt "$(date -u -d "$expiry" +%s)" ]; then
                      /* 到期后先进入宽限期：标记 terminating 并通知，而非立即删除 */
                      kubectl annotate ns "$ns" platform.acme.com/state=expiring --overwrite
                      curl -X POST "$SLACK_WEBHOOK" -d "{\"text\":
                        \"环境 $ns 已到期，将在 ${GRACE_PERIOD_HOURS}h 后回收。
                        延期: https://platform.acme.internal/envs/$ns/extend
                        负责人: $owner\"}"
                    fi
                  done
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: env-reaper
rules:
  - apiGroups: [""]
    resources: ["namespaces"]
    verbs: ["get", "list", "patch"]
  - apiGroups: [""]
    resources: ["namespaces/finalizers"]
    verbs: ["update"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: env-reaper
subjects:
  - kind: ServiceAccount
    name: env-reaper
    namespace: platform-system
roleRef:
  kind: ClusterRole
  name: env-reaper
  apiGroup: rbac.authorization.k8s.io

解释：TTL 自动回收是环境自助化的必要配套——没有回收机制的自助创建等于给组织埋下成本炸弹（开发者创建环境后忘记删除，数月后集群里堆积着数百个僵尸 namespace）。这个 CronJob 实现展示了回收机制的三个设计要点。第一，元数据驱动：环境 namespace 在创建时由平台打上 managed=true 标签与 expires-at、owner 注解，回收器只处理带标签的资源——平台管理的资源与手工资源边界清晰，避免误伤。第二，宽限期而非立即删除：到期后先把状态标记为 expiring 并通过 Slack 通知负责人，附上「一键延期」链接，24 小时宽限期后才真正删除。这个「先警告后执行」的模式平衡了成本治理与用户友好——直接删除会制造「我的环境怎么没了」的信任危机，而通知 + 延期链接把控制权还给用户，同时保证默认行为是回收（opt-out 而非 opt-in 的延期）。第三，最小权限 RBAC：reaper 的 ServiceAccount 只有 namespace 的 get/list/patch 权限，没有 delete——实际删除通过 patch namespace 的 finalizers 或由独立的删除工作流执行，权限分离降低自动化组件被攻破后的爆炸半径。DRY_RUN 环境变量支持「演练模式」：新版本回收器先以 dry-run 运行一周，把「将会回收的环境清单」发到平台频道供人工核对，确认无误伤后切换为实际执行——这是平台自动化组件的标准上线流程。生产级实现还应包括：回收前的数据快照选项（用户可配置「删除前保留数据库快照 7 天」）、回收统计报表（月度回收了多少资源、节约多少成本——这是平台 ROI 的直接证据）、以及延期次数限制（防止「永久延期」架空 TTL 机制）。

/* 示例 4：自助服务覆盖度矩阵——用数据文件追踪「哪些任务已自助化」 */
/* 平台团队每季度更新，作为自助化率指标的数据源与路线图输入 */
self_service_coverage:
  updated: "2024-09-01"
  tasks:
    - name: 创建新服务
      frequency_per_month: 25
      before_platform:
        mode: 工单 + 手工搭建
        median_wait: 5 天
        steps_requiring_others: 4
      current:
        mode: 门户脚手架（Backstage Template）
        median_time: 3 分钟
        self_service_rate: 1.0
        success_rate: 0.97
      status: productized
    - name: 创建预览环境
      frequency_per_month: 320
      before_platform:
        mode: 工单
        median_wait: 3 天
      current:
        mode: PR 触发自动创建 + 门户手动创建
        median_time: 12 分钟
        self_service_rate: 0.95
        success_rate: 0.93
      status: productized
    - name: 申请生产数据库
      frequency_per_month: 8
      before_platform:
        mode: DBA 工单
        median_wait: 7 天
      current:
        mode: Crossplane 复合资源 + 容量审批钩子
        median_time: 4 小时（含审批 SLA）
        self_service_rate: 0.75
        success_rate: 0.99
      status: productized_with_approval
    - name: 生产环境回滚
      frequency_per_month: 15
      current:
        mode: ArgoCD UI 一键回滚
        median_time: 4 分钟
        self_service_rate: 1.0
      status: productized
    - name: 申请 Kafka Topic
      frequency_per_month: 12
      current:
        mode: 工单（尚未自助化）
        median_wait: 2 天
      status: scripted
      roadmap: "2024-Q4 上线自助模板"
    - name: 获取生产数据脱敏样本
      frequency_per_month: 20
      current:
        mode: 找 DBA 手工导数
        median_wait: 4 天
      status: manual
      roadmap: "2025-Q1，依赖脱敏管道建设"
  summary:
    total_high_frequency_tasks: 6
    fully_self_service: 3
    self_service_with_approval: 1
    not_yet: 2
    self_service_coverage: 0.67
    monthly_wait_hours_eliminated: 2860

解释：这份「自助服务覆盖度矩阵」是平台团队最重要的管理工件之一，它把抽象的「自助化程度」转化为可追踪、可汇报、可排期的结构化数据。矩阵的每一行是一个高频开发者任务，列包含四组信息：平台化之前的基线（模式、中位等待时间、需要多少他人介入）——基线数据必须在平台建设前采集，否则事后无法证明改进；当前状态（模式、中位完成时间、自助率、成功率）；成熟度状态（manual → scripted → productized → intent-based 的四阶段标注）；路线图承诺（未自助化任务的计划时间）。summary 部分聚合出两个汇报级指标：self_service_coverage（6 个高频任务中 4 个已自助化 = 0.67）与 monthly_wait_hours_eliminated——后者的计算方法是每个任务的（原等待时长 - 现时长）× 月频率，示例中每月消除 2860 小时的等待，按工程师时薪折算就是平台生产力的直接货币价值，这是向 CFO 汇报时最有说服力的数字。矩阵的运营价值同样重要：（1）路线图排序的依据——「获取脱敏数据样本」月频率 20 次、等待 4 天，痛点总量大于「申请 Kafka Topic」，但依赖脱敏管道建设，排期需要权衡依赖关系；（2）质量回归的预警——success_rate 低于 0.95 的任务（预览环境 0.93）应触发根因分析（哪一步失败最多？错误信息是否可自助解决？）；（3）季度复评的机制——每季度重新测量各任务的中位时间，防止「上线时很快、半年后腐烂」的能力退化。建议把这份 YAML 纳入 Git 管理，用 CI 自动生成趋势图表发布到平台状态页。

/* 示例 5：ChatOps 自助服务——Slack 工作流的平台集成 */
/* 在协作场景中提供自助能力：审批、查询、快捷操作不离开 Slack */
apiVersion: backstage.io/v1alpha1
kind: Location
metadata:
  name: slack-integration-docs
---
/* 平台 Slack App 的命令注册清单（Bolt 框架风格伪代码） */
/* 命令 1: /platform env create payments-api preview */
app.command("/platform", async ({ command, ack, client }) => {
  await ack();
  const [resource, action, serviceRef, envType] = command.text.split(" ");
  /* 身份映射：Slack 用户 ID -> 企业目录 -> 平台 RBAC 主体 */
  const platformUser = await identityResolver.resolve(command.user_id);
  if (resource === "env" && action === "create") {
    /* 复用与门户完全相同的能力层 API——ChatOps 只是另一个入口 */
    const result = await platformApi.post("/v1/environments", {
      service_ref: "component:default/" + serviceRef,
      env_type: envType,
    }, { headers: { "X-On-Behalf-Of": platformUser } });
    await client.chat.postMessage({
      channel: command.channel_id,
      text: ":hammer_and_wrench: 环境创建已受理",
      blocks: [
        { type: "section",
          text: { type: "mrkdwn",
            value: "" } },
        { type: "actions", elements: [
          { type: "button", text: { type: "plain_text", emoji: true,
              text: ":mag: 查看进度" },
            url: "https://platform.acme.internal/workflows/" + result.workflowId },
          { type: "button", text: { type: "plain_text", emoji: true,
              text: ":x: 取消" },
            action_id: "cancel_workflow",
            value: result.workflowId,
            confirm: { title: { type: "plain_text", text: "确认取消？" },
              text: { type: "plain_text",
                text: "环境创建将被终止，已分配的资源会被回收" } } },
        ]},
      ],
    });
  }
});
/* 命令 2: /platform who-owns cart-service —— 目录快速查询 */
/* 命令 3: /platform approve <request-id> —— 审批人在频道内完成审批 */

解释：ChatOps 是自助服务「多入口、一致体验」原则在协作场景的落地。开发者的大量工作发生在 Slack/Teams 频道中——讨论故障、协调发布、接收告警——如果每个平台操作都要求「离开频道、打开门户、登录、导航、操作、回到频道」，摩擦会显著抑制自助能力的使用率。这段代码展示了 ChatOps 集成的四个关键设计。第一，身份映射与授权不降级：Slack user ID 通过 identityResolver 映射到企业目录身份，再映射到平台 RBAC 主体——ChatOps 入口执行与门户完全相同的权限校验，绝不因为「在聊天里操作」而放松授权（X-On-Behalf-Of 头传递真实操作者身份用于审计）。第二，能力层 API 复用：ChatOps 后端调用的是与门户相同的 /v1/environments API——这验证了 API-first 架构的价值，新入口的开发成本仅是「消息解析 + 结果渲染」的薄层。第三，富交互而非纯文本：Slack Block Kit 按钮提供「查看进度」（深链到门户工作流页面——复杂状态展示仍交给 Web UI）与「取消」（带确认对话框的破坏性操作保护），把合适的交互放在合适的媒介中。第四，审批场景的适配：/platform approve 命令让审批人在收到通知的同一频道内完成审批（附上下文卡片：谁申请了什么、影响面分析、批准/拒绝按钮），审批延迟从「小时级」（等审批人打开邮件/门户）降到「分钟级」。ChatOps 的适用边界也应清晰：查询类（who-owns、部署状态）、快捷操作类（创建预览环境、回滚）、审批类操作适合聊天入口；复杂表单（多参数服务创建）、可视化分析（仪表盘、日志检索）仍应引导到 Web 门户——入口分工的原则是「每个任务在其最自然的媒介中完成」。