GraphQL Schema 治理与 Registry：破坏性变更检测与 CI 门禁

# 比较两次 Schema 快照
graphql-inspector diff old-schema.graphql new-schema.graphql

# 输出示例
# ✖ Field User.email was removed  (BREAKING)
# ⚠ Enum Role.ADMIN was removed   (BREAKING)
# ✔ Field User.nickname was added (NON_BREAKING)

# 在 CI 中把破坏性变更变为失败
graphql-inspector diff \
  origin/main:schema.graphql \
  schema.graphql \
  --rule suppressRemovalOfDeprecatedField \
  --onComplete failOnBreaking

# 模型 A：schema-publish 显式发布（Apollo 风格）
# CI 中在合并后执行
- name: Publish schema
  run: |
    rover graph publish my-graph@production \
      --schema ./schema.graphql

# 模型 B：check 先校验、合并后自动发布（Hive 风格）
- name: Schema check
  run: |
    hive schema:check schema.graphql \
      --service users \
      --target production

# 从代码导出 SDL（以 Apollo Server 为例）
rover graph introspect http://localhost:4000/graphql > schema.graphql

# 或在代码层直接输出
node ./scripts/print-schema.js > schema.graphql

# 校验快照与实现一致（防止手改 SDL）
graphql-inspector validate ./schema.graphql http://localhost:4000/graphql

// scripts/print-schema.ts —— 保证 SDL 永远来自实现
import { printSchema } from 'graphql';
import { schema } from '../src/schema';
import { writeFileSync } from 'node:fs';

writeFileSync('./schema.graphql', printSchema(schema));
console.log('schema.graphql written');

type User {
  id: ID!
  # 旧字段：保留兼容，注明替代方案与移除计划
  legacyId: String
    @deprecated(reason: "Use `id` instead. Scheduled for removal in 2026-12.")
  id: ID!
}

enum Role {
  ADMIN
  MEMBER
  # 枚举值弃用：客户端需处理未知值
  SUPERUSER @deprecated(reason: "Use ADMIN. Removal 2026-11.")
}

# 在 Schema 中暴露元信息，便于客户端与运维对齐
type Query {
  _schemaInfo: SchemaInfo!
}

type SchemaInfo {
  # Git commit 短哈希
  revision: String!
  # 语义化日期标签
  releasedAt: String!
  # 兼容性等级
  compatibility: CompatibilityLevel!
}

enum CompatibilityLevel {
  BACKWARD
  BACKWARD_TRANSITIVE
  FULL
}

# .github/CODEOWNERS
# 类型与字段归属，PR 自动请求对应 owner 评审
/schema/user.graphql    @team-identity
/schema/order.graphql   @team-commerce
/schema/payment.graphql @team-payments

## Schema 变更 RFC

- **变更内容**：删除 `User.legacyId`
- **变更分类**：BREAKING
- **影响面**：Registry 显示 3 个客户端 / 7 个操作引用
- **替代方案**：`User.id`
- **弃用期**：2026-08 已宣告，观察期 90 天
- **回滚方案**：保留字段定义，仅移除 resolver 逻辑
- **评审人**：@team-identity @team-mobile

# .github/workflows/schema-gate.yml
name: Schema Gate
on: [pull_request]

jobs:
  schema:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Generate SDL
        run: npm run schema:print

      - name: Lint schema
        run: |
          npm run schema:lint   # 命名规范、描述缺失、字段顺序

      - name: Detect breaking changes
        run: |
          npx graphql-inspector diff \
            origin/main:schema.graphql \
            schema.graphql \
            --onComplete failOnBreaking

      - name: Validate operations
        run: |
          npx graphql-inspector validate \
            "src/**/*.graphql" schema.graphql

// 显式豁免，需要在 PR 中说明理由
// graphql-inspector-ignore: Field User.legacyId was removed
// 理由：旧字段已 100% 无流量，见监控面板 dash-1024

// 定期扫描：找出长期弃用未移除的字段，自动开 issue
import { buildSchema, GraphQLField } from 'graphql';

function findStaleDeprecations(schema: ReturnType<typeof buildSchema>) {
  const stale: string[] = [];
  for (const type of Object.values(schema.getTypeMap())) {
    if (type.name.startsWith('__')) continue;
    const fields = (type as any).getFields?.();
    if (!fields) continue;
    for (const [name, field] of Object.entries<GraphQLField<any, any>>(fields)) {
      const reason = field.deprecationReason;
      if (!reason) continue;
      // 约定 reason 中包含 YYYY-MM 的移除计划
      const m = reason.match(/Removal (\d{4})-(\d{2})/);
      if (m && new Date(`${m[1]}-${m[2]}-01`) < new Date()) {
        stale.push(`${type.name}.${name}`);
      }
    }
  }
  return stale;
}