全链路 Feature Flag 的升级顺序：先 backend 还是先 frontend？

// k8s/flagd/configmap.yaml
"member-discount-v2": {
  "state": "ENABLED",
  "variants": {
    "old-algo": "old-algo",
    "new-algo": "new-algo"
  },
  "defaultVariant": "old-algo",
  "targeting": {
    "if": [
      { "and": [
        { "starts_with": [{ "var": "targetingKey" }, "u-vip-"] },
        { "==": [{ "var": "tenant" }, "premium"] }
      ]},
      "new-algo",
      null
    ]
  }
}

// gateway/src/main/java/demo/gateway/flags/FeatureFlagSnapshot.java
public record FeatureFlagSnapshot(
        String orderTier,
        boolean newPricing,
        String fulfillmentMode,
        String homepageBanner,
        boolean memberPerks,
        String memberDiscountVariant   // ← 新增
) {
}

// gateway/src/main/java/demo/gateway/flags/FeatureFlagSnapshotResolver.java
public FeatureFlagSnapshot resolve(String userId, String tenantId) {
    MutableContext ctx = new MutableContext();
    Optional.ofNullable(userId).ifPresent(ctx::setTargetingKey);
    Optional.ofNullable(tenantId).ifPresent(t -> ctx.add("tenant", t));

    return new FeatureFlagSnapshot(
            client.getStringValue("order-tier", "standard", ctx),
            client.getBooleanValue("new-pricing-algo", false, ctx),
            client.getStringValue("ops-fulfillment-mode", "standard", ctx),
            client.getStringValue("ui-homepage-banner", "control", ctx),
            client.getBooleanValue("ui-member-perks", false, ctx),
            client.getStringValue("member-discount-v2", "old-algo", ctx)  // ← 新增，default="old-algo"
    );
}

// gateway/src/main/java/demo/gateway/filter/FeatureFlagFilter.java
return ServerRequest.from(request)
        .header("X-FF-New-Pricing", Boolean.toString(snapshot.newPricing()))
        .header("X-FF-Order-Tier", snapshot.orderTier())
        .header(HEADER_FULFILLMENT_MODE, snapshot.fulfillmentMode())
        .header("X-FF-Member-Discount", snapshot.memberDiscountVariant())  // ← 新增
        .build();

// pricing-service/src/main/java/demo/pricing/flags/FeatureFlags.java
public record FeatureFlags(
        String orderTier,
        boolean newPricing,
        String memberDiscountVariant
) {
    public static final FeatureFlags DEFAULTS =
            new FeatureFlags("standard", false, "old-algo");

    public static final ScopedValue<FeatureFlags> CURRENT = ScopedValue.newInstance();

    public static FeatureFlags current() {
        return CURRENT.orElse(DEFAULTS);
    }
}

// pricing-service/src/main/java/demo/pricing/filter/FeatureFlagFilter.java
static final String H_MEMBER_DISCOUNT = "X-FF-Member-Discount";

private static FeatureFlags parse(HttpServletRequest req) {
    String variant = req.getHeader(H_MEMBER_DISCOUNT);
    return new FeatureFlags(
            req.getHeader("X-FF-Order-Tier") != null ? req.getHeader("X-FF-Order-Tier") : FeatureFlags.DEFAULTS.orderTier(),
            "true".equalsIgnoreCase(req.getHeader("X-FF-New-Pricing")),
            variant != null ? variant : FeatureFlags.DEFAULTS.memberDiscountVariant()
    );
}

// pricing-service/src/main/java/demo/pricing/service/PricingEngine.java
@Service
public class PricingEngine {

    public Price calculate(String sku, double basePrice) {
        FeatureFlags ff = FeatureFlags.current();
        String variant = ff.memberDiscountVariant();

        return switch (variant) {
            case "new-algo" -> calculateWithNewAlgo(sku, basePrice);
            default -> calculateWithOldAlgo(sku, basePrice);  // safe fallback
        };
    }

    private Price calculateWithNewAlgo(String sku, double basePrice) {
        // v2 算法：按用户 tier 和 tenant 做分段折扣
        return new Price(basePrice * 0.85, "V2_SEGMENTED");
    }

    private Price calculateWithOldAlgo(String sku, double basePrice) {
        // 旧算法：统一折扣
        return new Price(basePrice * 0.95, "V1_UNIFIED");
    }
}

$ curl -H 'X-User-Id: u-vip-001' -H 'X-Tenant-Id: premium' \
    http://gateway:8080/experience/shared-flags | jq
{
  "orderTier": "standard",
  "newPricing": false,
  "fulfillmentMode": "express",
  "homepageBanner": "control",
  "memberPerks": false,
  "memberDiscountVariant": "new-algo"
}

// ui/src/api.ts
export async function fetchSharedFlags(
  userId: string | null, tenantId: string | null
): Promise<SharedFlagsResponse & { memberDiscountVariant?: string }> {
  const r = await fetch('/api/experience/shared-flags', {
    headers: headers(userId, tenantId),
  })
  return r.json()
}

// ui/src/App.tsx 新增 section
{shared?.memberDiscountVariant === 'new-algo' && (
  <div style={{ color: '#059669', marginTop: 8 }}>
    ✨ 新折扣算法已启用（v2 segmented）
  </div>
)}

## Feature Flag 分类
- [ ] frontend-only（仅影响 UI 展示，如 banner、卡片显隐）
- [ ] backend-only（仅影响后端业务逻辑，如 fulfillment route）
- [ ] full-stack（前后端共享语义，如 user tier、pricing algo）

## Full-stack flag 升级计划
- [ ] 后端已在主分支合并，gateway resolver 已识别新 flag
- [ ] 共享快照端点 `/experience/shared-flags` 返回正确值
- [ ] 下游服务已兼容新 header，有兜底默认值
- [ ] 前端 PR 已准备好，等待后端部署后可 merge

# 在 CI 脚本中
defaultVariant=$(kubectl get configmap flagd-config \
  -o jsonpath="{.data.flags\.json}" | \
  jq -r ".flags[\"${FLAG_KEY}\"].defaultVariant")

if [[ "${SAFE_DEFAULT}" != "$defaultVariant" ]]; then
  echo "ERROR: ${FLAG_KEY} defaultVariant is '${defaultVariant}' but expected '${SAFE_DEFAULT}'"
  exit 1
fi

## Full-Stack Feature Flag 部署顺序

1. 合并后端代码到主分支（gateway resolver + 下游服务 + flagd configmap）
2. 部署后端服务到目标环境
3. 验证共享快照端点返回正确值
4. 合并前端代码
5. 部署前端
6. 验证前后端行为一致