@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/core/config/contract/contract_test.go

@@ -0,0 +1,388 @@
+package configcontract
+
+import (
+	"bytes"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"{{module}}/internal/core/config"
+)
+
+func TestRenderDocumentationIsDeterministic(t *testing.T) {
+	metadata := config.DocumentationEnvironmentVariables()
+	first := renderDocumentation(metadata)
+	second := renderDocumentation(metadata)
+	require.Equal(t, first, second)
+	assert.Contains(t, string(first), "`DOCUMENTATION_BUILD_TIMEOUT`")
+	assert.Contains(t, string(first), "`API_CONTRACT_COMPATIBILITY_EVALUATOR_EXECUTABLE`")
+	assert.NotContains(t, string(first), "documentation-privacy-hmac-key-min-32-chars")
+}
+
+func TestRunDocsWritesAndChecksGeneratedDocument(t *testing.T) {
+	output := filepath.Join(t.TempDir(), "runtime-config.md")
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+
+	exitCode := Run([]string{"docs", "--output", output}, &stdout, &stderr)
+	require.Equal(t, 0, exitCode, stderr.String())
+	exitCode = Run([]string{"docs", "--check", "--output", output}, &stdout, &stderr)
+	require.Equal(t, 0, exitCode, stderr.String())
+
+	require.NoError(t, os.WriteFile(output, []byte("stale\n"), 0o644))
+	stderr.Reset()
+	exitCode = Run([]string{"docs", "--check", "--output", output}, &stdout, &stderr)
+	require.Equal(t, 1, exitCode)
+	assert.Contains(t, stderr.String(), "generated documentation is stale")
+}
+
+func TestVerifyContractAcceptsCompleteProductionContract(t *testing.T) {
+	metadata := config.DocumentationEnvironmentVariables()
+	environment := validEnvironment()
+	resolved := validCompose(metadata, environment)
+
+	violations := verifyContract(metadata, config.DeploymentSurfaceProd, environment, resolved)
+	require.Empty(t, violations)
+}
+
+func TestRunVerifyAcceptsResolvedProductionContract(t *testing.T) {
+	metadata := config.DocumentationEnvironmentVariables()
+	environment := validEnvironment()
+	resolved := validCompose(metadata, environment)
+	directory := t.TempDir()
+	envPath := filepath.Join(directory, ".env.prod.example")
+	composePath := filepath.Join(directory, "compose.json")
+
+	names := make([]string, 0, len(environment))
+	for name := range environment {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	var envBody strings.Builder
+	for _, name := range names {
+		envBody.WriteString(name + "=" + environment[name] + "\n")
+	}
+	require.NoError(t, os.WriteFile(envPath, []byte(envBody.String()), 0o644))
+	composeBody, err := json.Marshal(resolved)
+	require.NoError(t, err)
+	require.NoError(t, os.WriteFile(composePath, composeBody, 0o644))
+
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	exitCode := Run([]string{
+		"verify",
+		"--surface", "prod",
+		"--env-example", envPath,
+		"--compose-json", composePath,
+	}, &stdout, &stderr)
+	require.Equal(t, 0, exitCode, stderr.String())
+	assert.Contains(t, stdout.String(), "prod: configuration contract passed")
+}
+
+func TestVerifyContractRejectsContractDrift(t *testing.T) {
+	metadata := config.DocumentationEnvironmentVariables()
+
+	t.Run("missing required value", func(t *testing.T) {
+		environment := validEnvironment()
+		delete(environment, "DOCUMENTATION_BUILD_TIMEOUT")
+		violations := verifyContract(metadata, config.DeploymentSurfaceProd, environment, validCompose(metadata, environment))
+		assert.Contains(t, strings.Join(violations, "\n"), "DOCUMENTATION_BUILD_TIMEOUT is required")
+	})
+
+	t.Run("invalid duration", func(t *testing.T) {
+		environment := validEnvironment()
+		environment["DOCUMENTATION_BUILD_TIMEOUT"] = "forever"
+		violations := verifyContract(metadata, config.DeploymentSurfaceProd, environment, validCompose(metadata, environment))
+		assert.Contains(t, strings.Join(violations, "\n"), "positive Go duration")
+	})
+
+	t.Run("production secret literal", func(t *testing.T) {
+		environment := validEnvironment()
+		environment["DOCUMENTATION_PRIVACY_HMAC_KEY"] = "live-documentation-secret-value-with-32-characters"
+		violations := verifyContract(metadata, config.DeploymentSurfaceProd, environment, validCompose(metadata, environment))
+		assert.Contains(t, strings.Join(violations, "\n"), "descriptive redacted marker")
+	})
+
+	t.Run("unauthorized consumer", func(t *testing.T) {
+		environment := validEnvironment()
+		resolved := validCompose(metadata, environment)
+		resolved.Services["sample-product-bff"] = composeService{Environment: composeEnvironment{
+			"DOCUMENTATION_PRIVACY_HMAC_KEY": newComposeEnvironmentValue(environment["DOCUMENTATION_PRIVACY_HMAC_KEY"]),
+		}}
+		violations := verifyContract(metadata, config.DeploymentSurfaceProd, environment, resolved)
+		assert.Contains(t, strings.Join(violations, "\n"), "unauthorized service sample-product-bff")
+	})
+
+	t.Run("missing replica consumer", func(t *testing.T) {
+		environment := validEnvironment()
+		resolved := validCompose(metadata, environment)
+		resolved.Services["platform-api-2"] = composeService{Environment: composeEnvironment{}}
+		violations := verifyContract(metadata, config.DeploymentSurfaceProd, environment, resolved)
+		assert.Contains(t, strings.Join(violations, "\n"), "INTERNAL_SERVICE_DOCUMENTATION_BASE_URL is missing from required consumer platform-api-2")
+	})
+
+	t.Run("missing referenced secret material", func(t *testing.T) {
+		environment := validEnvironment()
+		resolved := validCompose(metadata, environment)
+		delete(resolved.Services["worker"].Environment, "APISIX_ADMIN_API_KEY")
+		violations := verifyContract(metadata, config.DeploymentSurfaceProd, environment, resolved)
+		assert.Contains(
+			t,
+			strings.Join(violations, "\n"),
+			"APISIX_ADMIN_API_KEY referenced by DOCUMENTATION_DOMAIN_GATEWAY_ADMIN_KEY_REF is missing from required consumer worker",
+		)
+	})
+
+	t.Run("empty referenced secret in environment example", func(t *testing.T) {
+		environment := validEnvironment()
+		environment["APISIX_ADMIN_API_KEY"] = ""
+		violations := verifyContract(metadata, config.DeploymentSurfaceProd, environment, validCompose(metadata, environment))
+		assert.Contains(t, strings.Join(violations, "\n"), "DOCUMENTATION_DOMAIN_GATEWAY_ADMIN_KEY_REF references missing environment variable APISIX_ADMIN_API_KEY")
+	})
+
+	t.Run("empty referenced secret material", func(t *testing.T) {
+		environment := validEnvironment()
+		resolved := validCompose(metadata, environment)
+		resolved.Services["worker"].Environment["APISIX_ADMIN_API_KEY"] = composeEnvironmentValue{null: true}
+		violations := verifyContract(metadata, config.DeploymentSurfaceProd, environment, resolved)
+		assert.Contains(t, strings.Join(violations, "\n"), "APISIX_ADMIN_API_KEY referenced by DOCUMENTATION_DOMAIN_GATEWAY_ADMIN_KEY_REF is missing")
+	})
+
+	t.Run("mismatched referenced secret material", func(t *testing.T) {
+		environment := validEnvironment()
+		resolved := validCompose(metadata, environment)
+		resolved.Services["worker"].Environment["APISIX_ADMIN_API_KEY"] = newComposeEnvironmentValue("<different-apisix-admin-key>")
+		violations := verifyContract(metadata, config.DeploymentSurfaceProd, environment, resolved)
+		assert.Contains(t, strings.Join(violations, "\n"), "APISIX_ADMIN_API_KEY referenced by DOCUMENTATION_DOMAIN_GATEWAY_ADMIN_KEY_REF differs")
+	})
+
+	t.Run("mismatched referenced secret in replica", func(t *testing.T) {
+		environment := validEnvironment()
+		resolved := validCompose(metadata, environment)
+		worker := resolved.Services["worker"]
+		replica := composeService{
+			Environment: cloneComposeEnvironment(worker.Environment),
+			Volumes:     append([]composeVolume(nil), worker.Volumes...),
+		}
+		replica.Environment["APISIX_ADMIN_API_KEY"] = newComposeEnvironmentValue("<different-apisix-admin-key>")
+		resolved.Services["worker-2"] = replica
+		violations := verifyContract(metadata, config.DeploymentSurfaceProd, environment, resolved)
+		assert.Contains(t, strings.Join(violations, "\n"), "APISIX_ADMIN_API_KEY referenced by DOCUMENTATION_DOMAIN_GATEWAY_ADMIN_KEY_REF differs in required consumer worker-2")
+	})
+
+	t.Run("production referenced secret literal", func(t *testing.T) {
+		environment := validEnvironment()
+		environment["APISIX_ADMIN_API_KEY"] = "live-apisix-admin-key-value-with-32-characters"
+		violations := verifyContract(metadata, config.DeploymentSurfaceProd, environment, validCompose(metadata, environment))
+		assert.Contains(t, strings.Join(violations, "\n"), "APISIX_ADMIN_API_KEY must use a descriptive redacted marker")
+	})
+}
+
+func TestValidateEnvironmentValueRejectsEveryInvalidType(t *testing.T) {
+	metadata := config.DocumentationEnvironmentVariables()
+	byName := make(map[string]*config.EnvironmentVariableMetadata, len(metadata))
+	registeredVariables := make(map[string]struct{}, len(metadata))
+	for index := range metadata {
+		byName[metadata[index].Name] = &metadata[index]
+		registeredVariables[metadata[index].Name] = struct{}{}
+	}
+	environment := validEnvironment()
+	tests := []struct {
+		name     string
+		variable string
+		surface  config.DeploymentSurface
+		value    string
+		want     string
+	}{
+		{name: "string", variable: "DOCUMENTATION_DOMAIN_BINDING_PROVIDER_KEY", surface: config.DeploymentSurfaceProd, value: "", want: "must not be empty"},
+		{name: "executable", variable: "DOCUMENTATION_NODE_EXECUTABLE", surface: config.DeploymentSurfaceProd, value: "../node", want: "bare executable name"},
+		{name: "integer", variable: "DOCUMENTATION_DOMAIN_ROUTE_PRIORITY", surface: config.DeploymentSurfaceProd, value: "0", want: "positive integer"},
+		{name: "duration", variable: "DOCUMENTATION_BUILD_TIMEOUT", surface: config.DeploymentSurfaceProd, value: "forever", want: "positive Go duration"},
+		{name: "http url", variable: "DOCUMENTATION_DOMAIN_GATEWAY_ADMIN_URL", surface: config.DeploymentSurfaceProd, value: "ftp://apisix:9180", want: "absolute HTTP URL"},
+		{name: "path", variable: "DOCUMENTATION_SITE_ROOT", surface: config.DeploymentSurfaceProd, value: "relative/docs-site", want: "absolute non-root path"},
+		{name: "secret reference", variable: "DOCUMENTATION_DOMAIN_GATEWAY_ADMIN_KEY_REF", surface: config.DeploymentSurfaceProd, value: "env://MISSING_GATEWAY_KEY", want: "references missing environment variable"},
+		{name: "secret", variable: "DOCUMENTATION_PRIVACY_HMAC_KEY", surface: config.DeploymentSurfaceDev, value: "local-secret", want: "explicit non-production value"},
+		{name: "endpoint list", variable: "DOCUMENTATION_API_UPSTREAMS", surface: config.DeploymentSurfaceProd, value: "documentation-api", want: "host:port list"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			err := validateEnvironmentValue(byName[test.variable], test.surface, test.value, environment, registeredVariables)
+			require.Error(t, err)
+			assert.Contains(t, err.Error(), test.want)
+		})
+	}
+}
+
+func TestDeploymentValidationMatchesRuntimeFieldConstraints(t *testing.T) {
+	metadata := config.DocumentationEnvironmentVariables()
+	byName := make(map[string]*config.EnvironmentVariableMetadata, len(metadata))
+	registeredVariables := make(map[string]struct{}, len(metadata))
+	for index := range metadata {
+		byName[metadata[index].Name] = &metadata[index]
+		registeredVariables[metadata[index].Name] = struct{}{}
+	}
+	environment := validEnvironment()
+	tests := []struct {
+		name     string
+		variable string
+		value    string
+		want     string
+	}{
+		{name: "timeout ceiling", variable: "DOCUMENTATION_BUILD_TIMEOUT", value: "3h", want: "at most 2h0m0s"},
+		{name: "evaluator timeout ceiling", variable: "API_CONTRACT_COMPATIBILITY_EVALUATOR_TIMEOUT", value: "11m", want: "at most 10m0s"},
+		{name: "evaluator executable", variable: "API_CONTRACT_COMPATIBILITY_EVALUATOR_EXECUTABLE", value: "../oasdiff", want: "bare executable name"},
+		{name: "compiler suffix", variable: "DOCUMENTATION_COMPILER_SCRIPT", value: "/docs-site/scripts/compiler.js", want: "must end in .mjs"},
+		{name: "provider pattern", variable: "DOCUMENTATION_DOMAIN_BINDING_PROVIDER_KEY", value: "APISIX", want: "invalid value"},
+		{name: "gateway path", variable: "DOCUMENTATION_DOMAIN_GATEWAY_ADMIN_URL", value: "https://gateway.example.com/admin", want: "must end at /apisix/admin"},
+		{name: "upstream identifier", variable: "DOCUMENTATION_DOMAIN_ORIGIN_UPSTREAM_ID", value: "invalid upstream", want: "invalid value"},
+		{name: "route priority ceiling", variable: "DOCUMENTATION_DOMAIN_ROUTE_PRIORITY", value: "1000001", want: "at most 1000000"},
+		{name: "documentation API path", variable: "INTERNAL_SERVICE_DOCUMENTATION_BASE_URL", value: "https://documentation.example.com/api", want: "must end at /api/v1/documentation"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			err := validateEnvironmentValue(
+				byName[test.variable],
+				config.DeploymentSurfaceProd,
+				test.value,
+				environment,
+				registeredVariables,
+			)
+			require.Error(t, err)
+			assert.Contains(t, err.Error(), test.want)
+		})
+	}
+}
+
+func TestVerifyContractRejectsCertificateMountDrift(t *testing.T) {
+	metadata := config.DocumentationEnvironmentVariables()
+	environment := validEnvironment()
+
+	t.Run("missing mount", func(t *testing.T) {
+		resolved := validCompose(metadata, environment)
+		service := resolved.Services["worker"]
+		service.Volumes = nil
+		resolved.Services["worker"] = service
+		violations := verifyContract(metadata, config.DeploymentSurfaceProd, environment, resolved)
+		assert.Contains(t, strings.Join(violations, "\n"), "mount target /run/secrets/documentation-domains is missing from required consumer worker")
+	})
+
+	t.Run("wrong source", func(t *testing.T) {
+		resolved := validCompose(metadata, environment)
+		service := resolved.Services["worker"]
+		service.Volumes[0].Source = "/wrong/source"
+		resolved.Services["worker"] = service
+		violations := verifyContract(metadata, config.DeploymentSurfaceProd, environment, resolved)
+		assert.Contains(t, strings.Join(violations, "\n"), "mount source in worker differs")
+	})
+
+	t.Run("wrong target", func(t *testing.T) {
+		resolved := validCompose(metadata, environment)
+		service := resolved.Services["worker"]
+		service.Volumes[0].Target = "/wrong/target"
+		resolved.Services["worker"] = service
+		violations := verifyContract(metadata, config.DeploymentSurfaceProd, environment, resolved)
+		assert.Contains(t, strings.Join(violations, "\n"), "mount target /run/secrets/documentation-domains is missing")
+	})
+
+	t.Run("writable mount", func(t *testing.T) {
+		resolved := validCompose(metadata, environment)
+		service := resolved.Services["worker"]
+		service.Volumes[0].ReadOnly = false
+		resolved.Services["worker"] = service
+		violations := verifyContract(metadata, config.DeploymentSurfaceProd, environment, resolved)
+		assert.Contains(t, strings.Join(violations, "\n"), "mount in worker must be read-only")
+	})
+
+	t.Run("missing replica mount", func(t *testing.T) {
+		resolved := validCompose(metadata, environment)
+		worker := resolved.Services["worker"]
+		resolved.Services["worker-2"] = composeService{Environment: cloneComposeEnvironment(worker.Environment)}
+		violations := verifyContract(metadata, config.DeploymentSurfaceProd, environment, resolved)
+		assert.Contains(t, strings.Join(violations, "\n"), "mount target /run/secrets/documentation-domains is missing from required consumer worker-2")
+	})
+}
+
+func TestValidateMetadataRejectsDuplicateNames(t *testing.T) {
+	metadata := config.DocumentationEnvironmentVariables()
+	metadata = append(metadata, metadata[0])
+	err := validateMetadata(metadata)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "duplicated")
+}
+
+func TestValidateEnvironmentExampleKeysRejectsDuplicates(t *testing.T) {
+	err := validateEnvironmentExampleKeys([]byte("DOCUMENTATION_BUILD_TIMEOUT=30m\nDOCUMENTATION_BUILD_TIMEOUT=45m\n"))
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "duplicated")
+}
+
+func validEnvironment() map[string]string {
+	return map[string]string{
+		"API_CONTRACT_COMPATIBILITY_EVALUATOR_EXECUTABLE": "oasdiff",
+		"API_CONTRACT_COMPATIBILITY_EVALUATOR_TIMEOUT":    "2m",
+		"DOCUMENTATION_NODE_EXECUTABLE":                   "node",
+		"DOCUMENTATION_SITE_ROOT":                         "/docs-site",
+		"DOCUMENTATION_COMPILER_SCRIPT":                   "/docs-site/scripts/compiler.mjs",
+		"DOCUMENTATION_BUILD_TIMEOUT":                     "30m",
+		"DOCUMENTATION_PRIVACY_HMAC_KEY_REF":              "env://DOCUMENTATION_PRIVACY_HMAC_KEY",
+		"DOCUMENTATION_DOMAIN_BINDING_PROVIDER_KEY":       "apisix",
+		"DOCUMENTATION_DOMAIN_GATEWAY_ADMIN_URL":          "http://apisix:9180/apisix/admin",
+		"DOCUMENTATION_DOMAIN_GATEWAY_ADMIN_KEY_REF":      "env://APISIX_ADMIN_API_KEY",
+		"DOCUMENTATION_DOMAIN_ORIGIN_UPSTREAM_ID":         "12",
+		"DOCUMENTATION_DOMAIN_CERTIFICATE_ROOT":           "/run/secrets/documentation-domains",
+		"DOCUMENTATION_DOMAIN_ROUTE_PRIORITY":             "20",
+		"INTERNAL_SERVICE_DOCUMENTATION_BASE_URL":         "http://documentation-api:3010/api/v1/documentation",
+		"DOCUMENTATION_PRIVACY_HMAC_KEY":                  "<documentation-privacy-hmac-key-min-32-chars>",
+		"DOCUMENTATION_DOMAIN_CERTIFICATE_ROOT_HOST":      "/etc/onex/documentation-domains",
+		"DOCUMENTATION_API_UPSTREAMS":                     "documentation-api:3010,documentation-api-2:3010",
+		"APISIX_ADMIN_API_KEY":                            "<apisix-admin-api-key>",
+	}
+}
+
+func validCompose(
+	metadata []config.EnvironmentVariableMetadata,
+	environment map[string]string,
+) composeConfig {
+	resolved := composeConfig{Services: map[string]composeService{
+		"admin-api":         {Environment: composeEnvironment{}},
+		"documentation-api": {Environment: composeEnvironment{}},
+		"gateway-sync":      {Environment: composeEnvironment{}},
+		"init-apisix":       {Environment: composeEnvironment{}},
+		"platform-api":      {Environment: composeEnvironment{}},
+		"worker":            {Environment: composeEnvironment{}},
+	}}
+	for index := range metadata {
+		variable := &metadata[index]
+		for _, consumer := range variable.RequiredConsumers {
+			service := resolved.Services[consumer]
+			service.Environment[variable.Name] = newComposeEnvironmentValue(environment[variable.Name])
+			if target := environmentReferenceTarget(variable, environment[variable.Name]); target != "" {
+				service.Environment[target] = newComposeEnvironmentValue(environment[target])
+			}
+			if variable.MountSourceVariable != "" {
+				service.Volumes = append(service.Volumes, composeVolume{
+					Type:     "bind",
+					Source:   environment[variable.MountSourceVariable],
+					Target:   environment[variable.Name],
+					ReadOnly: variable.MountReadOnly,
+				})
+			}
+			resolved.Services[consumer] = service
+		}
+	}
+	return resolved
+}
+
+func cloneComposeEnvironment(environment composeEnvironment) composeEnvironment {
+	cloned := make(composeEnvironment, len(environment))
+	for name, value := range environment {
+		cloned[name] = value
+	}
+	return cloned
+}

package/dist/resources/templates/go-backend/internal/core/config/contract/docs.go

@@ -0,0 +1,198 @@
+package configcontract
+
+import (
+	"bytes"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"{{module}}/internal/core/config"
+)
+
+const defaultDocumentationOutput = "../docs/development/backend-runtime-configuration.md"
+
+// Run 执行配置契约的文档生成与部署校验命令。
+func Run(args []string, stdout, stderr io.Writer) int {
+	if len(args) == 0 {
+		_, _ = fmt.Fprintln(stderr, "usage: config-contract <docs|verify> [options]")
+		return 2
+	}
+
+	var err error
+	switch args[0] {
+	case "docs":
+		err = runDocs(args[1:], stdout, stderr)
+	case "verify":
+		err = runVerify(args[1:], stdout, stderr)
+	default:
+		_, _ = fmt.Fprintf(stderr, "unsupported command %q\n", args[0])
+		return 2
+	}
+	if err != nil {
+		_, _ = fmt.Fprintln(stderr, err)
+		return 1
+	}
+	return 0
+}
+
+func runDocs(args []string, stdout, stderr io.Writer) error {
+	flags := flag.NewFlagSet("config-contract docs", flag.ContinueOnError)
+	flags.SetOutput(stderr)
+	output := flags.String("output", defaultDocumentationOutput, "generated Markdown output path")
+	check := flags.Bool("check", false, "fail when the tracked document differs")
+	if err := flags.Parse(args); err != nil {
+		return err
+	}
+	if flags.NArg() != 0 {
+		return fmt.Errorf("docs command does not accept positional arguments")
+	}
+
+	metadata := config.DocumentationEnvironmentVariables()
+	if err := validateMetadata(metadata); err != nil {
+		return err
+	}
+	body := renderDocumentation(metadata)
+	if *check {
+		tracked, err := os.ReadFile(*output)
+		if err != nil {
+			return fmt.Errorf("read generated documentation %s: %w", *output, err)
+		}
+		if !bytes.Equal(tracked, body) {
+			return fmt.Errorf("generated documentation is stale: %s", *output)
+		}
+	} else {
+		if err := os.MkdirAll(filepath.Dir(*output), 0o755); err != nil {
+			return fmt.Errorf("create documentation directory: %w", err)
+		}
+		if err := os.WriteFile(*output, body, 0o644); err != nil { //nolint:gosec // 生成文档不含密钥，需保持仓库文档可读。
+			return fmt.Errorf("write generated documentation %s: %w", *output, err)
+		}
+	}
+	_, _ = fmt.Fprintln(stdout, *output)
+	return nil
+}
+
+func renderDocumentation(metadata []config.EnvironmentVariableMetadata) []byte {
+	ordered := append([]config.EnvironmentVariableMetadata(nil), metadata...)
+	sort.Slice(ordered, func(i, j int) bool { return ordered[i].Name < ordered[j].Name })
+	var body strings.Builder
+	body.WriteString("# 后端文档运行时配置\n\n")
+	body.WriteString("本文档由 `backend/internal/core/config/metadata.go` 中的配置契约确定性生成。")
+	body.WriteString("运行时优先级为环境变量、环境配置文件、基础配置文件、代码默认值。\n\n")
+	body.WriteString("## 配置目录\n\n")
+	body.WriteString("| 环境变量 | 配置键 | 类型 | 默认值 | 必需部署面 | 必需消费者 | 允许消费者 | 约束 | 说明 |\n")
+	body.WriteString("|---|---|---|---|---|---|---|---|---|\n")
+	for index := range ordered {
+		variable := &ordered[index]
+		body.WriteString("| `" + variable.Name + "` | ")
+		body.WriteString(markdownCodeOrDash(variable.ConfigKey) + " | ")
+		body.WriteString("`" + string(variable.ValueType) + "` | ")
+		body.WriteString(markdownDefault(variable) + " | ")
+		body.WriteString(markdownList(deploymentSurfaceStrings(variable.RequiredSurfaces)) + " | ")
+		body.WriteString(markdownList(variable.RequiredConsumers) + " | ")
+		body.WriteString(markdownList(variable.AllowedConsumers) + " | ")
+		body.WriteString(markdownConstraints(variable) + " | ")
+		body.WriteString(strings.ReplaceAll(variable.Description, "|", "\\|") + " |\n")
+	}
+	body.WriteString("\n## 类型规则\n\n")
+	body.WriteString("- `string` 必须非空；`executable` 必须为 PATH 可解析名称或绝对路径。\n")
+	body.WriteString("- `integer` 必须为正整数；`duration` 必须为正数 Go duration。\n")
+	body.WriteString("- `http_url` 必须为不含凭据、查询参数和片段的绝对 HTTP(S) URL。\n")
+	body.WriteString("- 部署样例中的 `path` 必须为绝对非根路径；代码默认值可以使用仓库内相对路径。\n")
+	body.WriteString("- `secret_reference` 只允许 `env://` 或绝对 `file://`，且 `env://` 目标必须存在。\n")
+	body.WriteString("- `endpoint_list` 是逗号分隔的 `host:port` 列表。\n")
+	body.WriteString("\n## 密钥边界\n\n")
+	body.WriteString("敏感变量的提交样例不得包含生产值。`prod` 只允许描述性占位符；")
+	body.WriteString("运行时配置只保存 `env://` 或 `file://` 引用，密钥材料不进入 `Config`。\n\n")
+	body.WriteString("## 契约校验\n\n")
+	body.WriteString("```bash\n")
+	body.WriteString("docker compose --profile gateway-readiness --env-file deployments/.env.dev.example \\\n")
+	body.WriteString("  -f deployments/docker-compose.yml -f deployments/docker-compose.dev.yml \\\n")
+	body.WriteString("  config --format json > /tmp/compose-dev.json\n")
+	body.WriteString("cd backend\n")
+	body.WriteString("go run ./cmd/tools/config-contract docs --check --output ../docs/development/backend-runtime-configuration.md\n")
+	body.WriteString("go run ./cmd/tools/config-contract verify --surface dev --env-example ../deployments/.env.dev.example --compose-json /tmp/compose-dev.json\n")
+	body.WriteString("```\n")
+	return []byte(body.String())
+}
+
+func markdownCodeOrDash(value string) string {
+	if value == "" {
+		return "-"
+	}
+	return "`" + value + "`"
+}
+
+func markdownDefault(variable *config.EnvironmentVariableMetadata) string {
+	if variable.Sensitive {
+		return "-"
+	}
+	value, exists := variable.DefaultValue.DisplayValue()
+	if !exists {
+		return "-"
+	}
+	return "`" + value + "`"
+}
+
+func markdownConstraints(variable *config.EnvironmentVariableMetadata) string {
+	constraints := make([]string, 0, 8)
+	if variable.ValuePattern != "" {
+		constraints = append(constraints, "pattern="+variable.ValuePattern)
+	}
+	if variable.RequiredSuffix != "" {
+		constraints = append(constraints, "suffix="+variable.RequiredSuffix)
+	}
+	if variable.RequiredURLPath != "" {
+		constraints = append(constraints, "url_path="+variable.RequiredURLPath)
+	}
+	if variable.MaximumInteger > 0 {
+		constraints = append(constraints, fmt.Sprintf("max=%d", variable.MaximumInteger))
+	}
+	if variable.MaximumDuration > 0 {
+		constraints = append(constraints, "max="+variable.MaximumDuration.String())
+	}
+	if variable.RequireAbsoluteRuntimePath {
+		constraints = append(constraints, "runtime_absolute_path")
+	}
+	if variable.RequireAbsoluteDeploymentPath {
+		constraints = append(constraints, "deployment_absolute_path")
+	}
+	if variable.MountSourceVariable != "" {
+		mount := "bind=" + variable.MountSourceVariable
+		if variable.MountReadOnly {
+			mount += ",read_only"
+		}
+		constraints = append(constraints, mount)
+	}
+	if len(constraints) == 0 {
+		return "-"
+	}
+	for index := range constraints {
+		constraints[index] = "`" + strings.ReplaceAll(constraints[index], "|", "\\|") + "`"
+	}
+	return strings.Join(constraints, ", ")
+}
+
+func markdownList(values []string) string {
+	if len(values) == 0 {
+		return "-"
+	}
+	ordered := append([]string(nil), values...)
+	sort.Strings(ordered)
+	for index := range ordered {
+		ordered[index] = "`" + ordered[index] + "`"
+	}
+	return strings.Join(ordered, ", ")
+}
+
+func deploymentSurfaceStrings(surfaces []config.DeploymentSurface) []string {
+	result := make([]string, len(surfaces))
+	for index, surface := range surfaces {
+		result[index] = string(surface)
+	}
+	return result
+}