@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/core/apidocs/assets/scalar-api-reference.metadata.json

@@ -0,0 +1,10 @@
+{
+  "license": "MIT",
+  "locale": "zh-CN",
+  "localization_revision": "onex-zh-CN-v1",
+  "package": "@scalar/api-reference",
+  "sha256": "8c516fadf66bc384a8246da6f2c2e05dd8496c912b2885f247e77a8b05b38ad8",
+  "source": "dist/browser/standalone.js",
+  "source_sha256": "6c7d50afc5612d05e7f7d3bfe6a858c2e518a269823bfe83760f94fd133e4815",
+  "version": "1.62.6"
+}

package/dist/resources/templates/go-backend/internal/core/apidocs/route.go

@@ -0,0 +1,107 @@
+package apidocs
+
+import (
+	"crypto/sha256"
+	_ "embed" // 支持下方 go:embed 指令。
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+
+	"{{module}}/internal/core/apicontract"
+)
+
+const (
+	docsContentSecurityPolicy  = "default-src 'none'; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self'; img-src 'self' data:; font-src 'none'; base-uri 'none'; form-action 'self'; frame-ancestors 'none'"
+	scalarAssetPath            = "/docs/assets/scalar-api-reference.js"
+	scalarAssetVersion         = "1.62.6"
+	scalarAssetLocale          = "zh-CN"
+	scalarLocalizationRevision = "onex-zh-CN-v1"
+	scalarAssetSourceSHA256    = "6c7d50afc5612d05e7f7d3bfe6a858c2e518a269823bfe83760f94fd133e4815"
+)
+
+//go:embed assets/scalar-api-reference.js
+var scalarBrowserAsset []byte
+
+//go:embed assets/scalar-api-reference.metadata.json
+var scalarBrowserAssetMetadata []byte
+
+type scalarAssetMetadata struct {
+	License              string `json:"license"`
+	Locale               string `json:"locale"`
+	LocalizationRevision string `json:"localization_revision"`
+	Package              string `json:"package"`
+	SHA256               string `json:"sha256"`
+	Source               string `json:"source"`
+	SourceSHA256         string `json:"source_sha256"`
+	Version              string `json:"version"`
+}
+
+// RegisterRoutes 注册单服务同源 API Reference 路由。
+func RegisterRoutes(router *gin.Engine, document apicontract.Document) error {
+	assetMetadata, err := validatedScalarAssetMetadata()
+	if err != nil {
+		return err
+	}
+	metadata := document.Metadata()
+	page, err := ScalarHTML(metadata.DisplayName, metadata.Service, scalarAssetURL(assetMetadata.SHA256))
+	if err != nil {
+		return err
+	}
+
+	servePage := func(c *gin.Context) {
+		setReferenceHeaders(c)
+		c.Header("Cache-Control", "no-store")
+		c.Data(http.StatusOK, "text/html; charset=utf-8", []byte(page))
+	}
+	for _, path := range []string{"/docs", "/docs/", "/docs/index.html"} {
+		router.GET(path, servePage)
+	}
+	router.GET("/docs/openapi.json", func(c *gin.Context) {
+		setReferenceHeaders(c)
+		c.Header("Cache-Control", "no-store")
+		c.Data(http.StatusOK, "application/json; charset=utf-8", document.JSON())
+	})
+	router.GET(scalarAssetPath, func(c *gin.Context) {
+		setReferenceHeaders(c)
+		if c.Query("v") != assetMetadata.SHA256 {
+			c.Header("Cache-Control", "no-store")
+			c.Status(http.StatusNotFound)
+			return
+		}
+		c.Header("Cache-Control", "public, max-age=31536000, immutable")
+		c.Data(http.StatusOK, "text/javascript; charset=utf-8", scalarBrowserAsset)
+	})
+	return nil
+}
+
+func validatedScalarAssetMetadata() (scalarAssetMetadata, error) {
+	return validateScalarAssetMetadata(scalarBrowserAsset, scalarBrowserAssetMetadata)
+}
+
+func validateScalarAssetMetadata(asset, encodedMetadata []byte) (scalarAssetMetadata, error) {
+	var metadata scalarAssetMetadata
+	if err := json.Unmarshal(encodedMetadata, &metadata); err != nil {
+		return scalarAssetMetadata{}, fmt.Errorf("decode Scalar asset metadata: %w", err)
+	}
+	digest := sha256.Sum256(asset)
+	if metadata.Package != "@scalar/api-reference" || metadata.Version != scalarAssetVersion || metadata.License != "MIT" ||
+		metadata.Source != "dist/browser/standalone.js" || metadata.SourceSHA256 != scalarAssetSourceSHA256 ||
+		metadata.Locale != scalarAssetLocale || metadata.LocalizationRevision != scalarLocalizationRevision ||
+		metadata.SHA256 != hex.EncodeToString(digest[:]) {
+		return scalarAssetMetadata{}, fmt.Errorf("Scalar browser asset metadata is invalid")
+	}
+	return metadata, nil
+}
+
+func scalarAssetURL(digest string) string {
+	return scalarAssetPath + "?v=" + digest
+}
+
+func setReferenceHeaders(c *gin.Context) {
+	c.Header("Content-Security-Policy", docsContentSecurityPolicy)
+	c.Header("Referrer-Policy", "no-referrer")
+	c.Header("X-Content-Type-Options", "nosniff")
+}

package/dist/resources/templates/go-backend/internal/core/apidocs/route_test.go

@@ -0,0 +1,200 @@
+package apidocs
+
+import (
+	"bytes"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+
+	"{{module}}/internal/core/apicontract"
+)
+
+func TestRegisterRoutesServesSameOriginReferenceArtifacts(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	document := referenceFixtureDocument(t)
+	router := gin.New()
+	if err := RegisterRoutes(router, document); err != nil {
+		t.Fatalf("RegisterRoutes() error = %v", err)
+	}
+
+	assetMetadata, err := validatedScalarAssetMetadata()
+	if err != nil {
+		t.Fatalf("validatedScalarAssetMetadata() error = %v", err)
+	}
+	versionedAssetURL := scalarAssetURL(assetMetadata.SHA256)
+
+	for _, path := range []string{"/docs", "/docs/", "/docs/index.html"} {
+		response := performReferenceRequest(router, path)
+		if response.Code != http.StatusOK || !strings.Contains(response.Body.String(), versionedAssetURL) {
+			t.Fatalf("GET %s status/body = %d/%q", path, response.Code, response.Body.String())
+		}
+		if response.Header().Get("Content-Security-Policy") != docsContentSecurityPolicy {
+			t.Fatalf("GET %s has unexpected CSP", path)
+		}
+	}
+
+	spec := performReferenceRequest(router, "/docs/openapi.json")
+	if spec.Code != http.StatusOK || spec.Body.String() != string(document.JSON()) {
+		t.Fatalf("OpenAPI response status/body = %d/%q", spec.Code, spec.Body.String())
+	}
+	asset := performReferenceRequest(router, versionedAssetURL)
+	if asset.Code != http.StatusOK || !bytes.Equal(asset.Body.Bytes(), scalarBrowserAsset) {
+		t.Fatalf("Scalar asset response status/content = %d/%d bytes", asset.Code, asset.Body.Len())
+	}
+	if asset.Header().Get("Cache-Control") != "public, max-age=31536000, immutable" {
+		t.Fatalf("Scalar asset cache policy = %q", asset.Header().Get("Cache-Control"))
+	}
+	for _, path := range []string{scalarAssetPath, scalarAssetPath + "?v=stale-digest"} {
+		response := performReferenceRequest(router, path)
+		if response.Code != http.StatusNotFound {
+			t.Fatalf("GET %s status = %d", path, response.Code)
+		}
+		if response.Header().Get("Cache-Control") != "no-store" {
+			t.Fatalf("GET %s cache policy = %q", path, response.Header().Get("Cache-Control"))
+		}
+	}
+}
+
+func TestRegisterRoutesRejectsInvalidAssetMetadataBeforeRegistration(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	originalMetadata := scalarBrowserAssetMetadata
+	scalarBrowserAssetMetadata = []byte("{")
+	t.Cleanup(func() {
+		scalarBrowserAssetMetadata = originalMetadata
+	})
+
+	router := gin.New()
+	if err := RegisterRoutes(router, referenceFixtureDocument(t)); err == nil {
+		t.Fatal("RegisterRoutes() error = nil, want invalid metadata error")
+	}
+	if routes := router.Routes(); len(routes) != 0 {
+		t.Fatalf("registered routes = %d, want 0", len(routes))
+	}
+	if response := performReferenceRequest(router, "/docs"); response.Code != http.StatusNotFound {
+		t.Fatalf("GET /docs status = %d, want %d", response.Code, http.StatusNotFound)
+	}
+}
+
+func TestValidateScalarAssetAcceptsPinnedGeneratedAsset(t *testing.T) {
+	metadata, err := validatedScalarAssetMetadata()
+	if err != nil {
+		t.Fatalf("validatedScalarAssetMetadata() error = %v", err)
+	}
+	if metadata.SHA256 == "" || scalarAssetURL(metadata.SHA256) == scalarAssetPath {
+		t.Fatal("Scalar asset URL is not content-addressed")
+	}
+	if metadata.Locale != scalarAssetLocale || metadata.LocalizationRevision != scalarLocalizationRevision ||
+		metadata.SourceSHA256 != scalarAssetSourceSHA256 {
+		t.Fatalf("Scalar localization metadata = %#v", metadata)
+	}
+	asset := string(scalarBrowserAsset)
+	for _, expected := range []string{"未选择身份验证方式", "API 调试客户端", "发送请求"} {
+		if !strings.Contains(asset, expected) {
+			t.Fatalf("Scalar asset does not contain %q", expected)
+		}
+	}
+	for _, forbidden := range []string{"` No authentication selected `", "`Request Example for`", "` Send Request `"} {
+		if strings.Contains(asset, forbidden) {
+			t.Fatalf("Scalar asset contains untranslated text %q", forbidden)
+		}
+	}
+}
+
+func TestValidateScalarAssetMetadataRejectsDrift(t *testing.T) {
+	var base scalarAssetMetadata
+	if err := json.Unmarshal(scalarBrowserAssetMetadata, &base); err != nil {
+		t.Fatalf("decode fixture metadata: %v", err)
+	}
+
+	metadataDriftCases := []struct {
+		name   string
+		mutate func(*scalarAssetMetadata)
+	}{
+		{name: "package", mutate: func(metadata *scalarAssetMetadata) { metadata.Package = "invalid" }},
+		{name: "version", mutate: func(metadata *scalarAssetMetadata) { metadata.Version = "0.0.0" }},
+		{name: "license", mutate: func(metadata *scalarAssetMetadata) { metadata.License = "invalid" }},
+		{name: "source", mutate: func(metadata *scalarAssetMetadata) { metadata.Source = "invalid" }},
+		{name: "source digest", mutate: func(metadata *scalarAssetMetadata) { metadata.SourceSHA256 = "invalid" }},
+		{name: "locale", mutate: func(metadata *scalarAssetMetadata) { metadata.Locale = "en-US" }},
+		{name: "localization revision", mutate: func(metadata *scalarAssetMetadata) { metadata.LocalizationRevision = "invalid" }},
+		{name: "output digest", mutate: func(metadata *scalarAssetMetadata) { metadata.SHA256 = "invalid" }},
+	}
+	for _, testCase := range metadataDriftCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			metadata := base
+			testCase.mutate(&metadata)
+			encodedMetadata, err := json.Marshal(metadata)
+			if err != nil {
+				t.Fatalf("encode metadata: %v", err)
+			}
+			if _, err := validateScalarAssetMetadata(scalarBrowserAsset, encodedMetadata); err == nil {
+				t.Fatal("validateScalarAssetMetadata() error = nil, want metadata drift error")
+			}
+		})
+	}
+
+	t.Run("malformed metadata", func(t *testing.T) {
+		if _, err := validateScalarAssetMetadata(scalarBrowserAsset, []byte("{")); err == nil {
+			t.Fatal("validateScalarAssetMetadata() error = nil, want decode error")
+		}
+	})
+
+	t.Run("mutated asset", func(t *testing.T) {
+		mutatedAsset := append([]byte(nil), scalarBrowserAsset...)
+		mutatedAsset[0] ^= 0xff
+		if _, err := validateScalarAssetMetadata(mutatedAsset, scalarBrowserAssetMetadata); err == nil {
+			t.Fatal("validateScalarAssetMetadata() error = nil, want asset drift error")
+		}
+	})
+}
+
+func referenceFixtureDocument(t *testing.T) apicontract.Document {
+	t.Helper()
+	// OpenAPI 测试夹具需要表达异构 JSON 对象，any 仅用于序列化边界。
+	spec, err := json.Marshal(map[string]any{
+		"info":              map[string]any{"title": "Fixture", "version": "1.0.0"},
+		"jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
+		"openapi":           "3.1.1",
+		"paths": map[string]any{
+			"/api/v1/widgets": map[string]any{"get": map[string]any{"operationId": "getWidgets"}},
+		},
+	})
+	if err != nil {
+		t.Fatalf("marshal fixture spec: %v", err)
+	}
+	digest := sha256.Sum256(spec)
+	// 运行时契约测试夹具需要表达异构 JSON 对象，any 仅用于序列化边界。
+	runtime, err := json.Marshal(map[string]any{
+		"api_version":            "1.0.0",
+		"delegated_contracts":    []any{},
+		"display_name":           "Fixture API",
+		"media_type":             "application/vnd.onex.runtime-contract+json;version=2",
+		"native_operation_count": 1,
+		"operation_count":        1,
+		"route_exclusions":       []string{"/docs", "/docs/", "/docs/assets/scalar-api-reference.js", "/docs/index.html", "/docs/openapi.json"},
+		"routes":                 []any{map[string]any{"method": "GET", "path": "/api/v1/widgets"}},
+		"schema_version":         2,
+		"service":                "fixture-api",
+		"sha256":                 hex.EncodeToString(digest[:]),
+	})
+	if err != nil {
+		t.Fatalf("marshal fixture runtime contract: %v", err)
+	}
+	document, err := apicontract.NewDocument(spec, runtime)
+	if err != nil {
+		t.Fatalf("NewDocument() error = %v", err)
+	}
+	return document
+}
+
+func performReferenceRequest(router http.Handler, path string) *httptest.ResponseRecorder {
+	response := httptest.NewRecorder()
+	router.ServeHTTP(response, httptest.NewRequest(http.MethodGet, path, nil))
+	return response
+}

package/dist/resources/templates/go-backend/internal/core/apidocs/scalar.go

@@ -0,0 +1,117 @@
+package apidocs
+
+import (
+	"encoding/json"
+	"fmt"
+	"html"
+)
+
+const scalarDocumentURL = "/docs/openapi.json"
+
+type scalarAgentConfig struct {
+	Disabled bool `json:"disabled"`
+}
+
+type scalarLocalizationConfig struct {
+	Direction string `json:"direction"`
+	Locale    string `json:"locale"`
+}
+
+type scalarConfig struct {
+	URL                          string                   `json:"url"`
+	Theme                        string                   `json:"theme"`
+	Layout                       string                   `json:"layout"`
+	DefaultOpenAllTags           bool                     `json:"defaultOpenAllTags"`
+	ExpandAllModelSections       bool                     `json:"expandAllModelSections"`
+	ExpandAllResponses           bool                     `json:"expandAllResponses"`
+	ShowOperationID              bool                     `json:"showOperationId"`
+	HideClientButton             bool                     `json:"hideClientButton"`
+	ShowSidebar                  bool                     `json:"showSidebar"`
+	ShowDeveloperTools           string                   `json:"showDeveloperTools"`
+	ShowToolbar                  string                   `json:"showToolbar"`
+	OperationTitleSource         string                   `json:"operationTitleSource"`
+	PersistAuth                  bool                     `json:"persistAuth"`
+	Telemetry                    bool                     `json:"telemetry"`
+	Agent                        scalarAgentConfig        `json:"agent"`
+	Default                      bool                     `json:"default"`
+	IsEditable                   bool                     `json:"isEditable"`
+	HideModels                   bool                     `json:"hideModels"`
+	DocumentDownloadType         string                   `json:"documentDownloadType"`
+	HideTestRequestButton        bool                     `json:"hideTestRequestButton"`
+	HideSearch                   bool                     `json:"hideSearch"`
+	HideDarkModeToggle           bool                     `json:"hideDarkModeToggle"`
+	WithDefaultFonts             bool                     `json:"withDefaultFonts"`
+	DefaultOpenFirstTag          bool                     `json:"defaultOpenFirstTag"`
+	ExpandAllSchemaProperties    bool                     `json:"expandAllSchemaProperties"`
+	OrderSchemaPropertiesBy      string                   `json:"orderSchemaPropertiesBy"`
+	OrderRequiredPropertiesFirst bool                     `json:"orderRequiredPropertiesFirst"`
+	SearchHotKey                 string                   `json:"searchHotKey"`
+	Integration                  string                   `json:"_integration"`
+	ModelsSectionLabel           string                   `json:"modelsSectionLabel"`
+	Localization                 scalarLocalizationConfig `json:"localization"`
+	DarkMode                     bool                     `json:"darkMode"`
+	Slug                         string                   `json:"slug"`
+	Title                        string                   `json:"title"`
+}
+
+// ScalarHTML 生成只读取同源内嵌制品的 Scalar API Reference 页面。
+func ScalarHTML(title string, slug string, assetURL string) (string, error) {
+	configJSON, err := json.Marshal(defaultScalarConfig(title, slug))
+	if err != nil {
+		return "", fmt.Errorf("marshal Scalar config: %w", err)
+	}
+
+	return fmt.Sprintf(`<!DOCTYPE html>
+<html lang="zh-CN">
+  <head>
+    <title>%s</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="icon" href="data:," />
+  </head>
+  <body>
+    <script id="api-reference" type="application/json" data-configuration="%s"></script>
+    <script src="%s"></script>
+  </body>
+</html>
+`, html.EscapeString(title), html.EscapeString(string(configJSON)), html.EscapeString(assetURL)), nil
+}
+
+func defaultScalarConfig(title string, slug string) scalarConfig {
+	return scalarConfig{
+		URL:                          scalarDocumentURL,
+		Theme:                        "default",
+		Layout:                       "modern",
+		DefaultOpenAllTags:           true,
+		ExpandAllModelSections:       true,
+		ExpandAllResponses:           true,
+		ShowOperationID:              true,
+		HideClientButton:             false,
+		ShowSidebar:                  true,
+		ShowDeveloperTools:           "localhost",
+		ShowToolbar:                  "localhost",
+		OperationTitleSource:         "summary",
+		PersistAuth:                  false,
+		Telemetry:                    false,
+		Agent:                        scalarAgentConfig{Disabled: true},
+		Default:                      false,
+		IsEditable:                   false,
+		HideModels:                   true,
+		DocumentDownloadType:         "both",
+		HideTestRequestButton:        false,
+		HideSearch:                   false,
+		HideDarkModeToggle:           false,
+		WithDefaultFonts:             false,
+		DefaultOpenFirstTag:          true,
+		ExpandAllSchemaProperties:    false,
+		OrderSchemaPropertiesBy:      "alpha",
+		OrderRequiredPropertiesFirst: true,
+		SearchHotKey:                 "k",
+		Integration:                  "html",
+		ModelsSectionLabel:           "模型",
+		Localization:                 scalarLocalizationConfig{Direction: "ltr", Locale: "zh-CN"},
+		DarkMode:                     true,
+		Slug:                         slug,
+		Title:                        title,
+	}
+}

package/dist/resources/templates/go-backend/internal/core/apidocs/scalar_test.go

@@ -0,0 +1,99 @@
+package apidocs
+
+import (
+	"encoding/json"
+	htmlpkg "html"
+	"strings"
+	"testing"
+)
+
+func TestScalarHTMLUsesLocalHardenedReferenceOptions(t *testing.T) {
+	page, err := ScalarHTML("OneX 平台 API", "platform-api", scalarAssetURL("asset-digest"))
+	if err != nil {
+		t.Fatalf("ScalarHTML() error = %v", err)
+	}
+
+	config := scalarConfigFromHTML(t, page)
+	assertEqual(t, config["url"], "/docs/openapi.json", "url")
+	assertEqual(t, config["theme"], "default", "theme")
+	assertEqual(t, config["layout"], "modern", "layout")
+	assertEqual(t, config["defaultOpenAllTags"], true, "defaultOpenAllTags")
+	assertEqual(t, config["expandAllModelSections"], true, "expandAllModelSections")
+	assertEqual(t, config["expandAllResponses"], true, "expandAllResponses")
+	assertEqual(t, config["showOperationId"], true, "showOperationId")
+	assertEqual(t, config["hideClientButton"], false, "hideClientButton")
+	assertEqual(t, config["showSidebar"], true, "showSidebar")
+	assertEqual(t, config["showDeveloperTools"], "localhost", "showDeveloperTools")
+	assertEqual(t, config["showToolbar"], "localhost", "showToolbar")
+	assertEqual(t, config["operationTitleSource"], "summary", "operationTitleSource")
+	assertEqual(t, config["persistAuth"], false, "persistAuth")
+	assertEqual(t, config["telemetry"], false, "telemetry")
+	assertEqual(t, config["withDefaultFonts"], false, "withDefaultFonts")
+	assertEqual(t, config["modelsSectionLabel"], "模型", "modelsSectionLabel")
+	assertEqual(t, config["title"], "OneX 平台 API", "title")
+	assertEqual(t, config["slug"], "platform-api", "slug")
+	if _, exists := config["externalUrls"]; exists {
+		t.Fatal("Scalar config exposed external URLs")
+	}
+	agent, ok := config["agent"].(map[string]any)
+	if !ok {
+		t.Fatalf("agent type = %T, want map[string]any", config["agent"])
+	}
+	assertEqual(t, agent["disabled"], true, "agent.disabled")
+	localization, ok := config["localization"].(map[string]any)
+	if !ok {
+		t.Fatalf("localization type = %T, want map[string]any", config["localization"])
+	}
+	assertEqual(t, localization["locale"], "zh-CN", "localization.locale")
+	assertEqual(t, localization["direction"], "ltr", "localization.direction")
+	if !strings.Contains(page, `src="/docs/assets/scalar-api-reference.js?v=asset-digest"`) {
+		t.Fatal("ScalarHTML() did not use the same-origin browser asset")
+	}
+	if !strings.Contains(page, `rel="icon" href="data:,"`) {
+		t.Fatal("ScalarHTML() did not suppress implicit favicon requests")
+	}
+	for _, forbidden := range []string{"dashboard.scalar.com", "registry.scalar.com", "proxy.scalar.com", "api.scalar.com", "cdn.jsdelivr.net"} {
+		if strings.Contains(page, forbidden) {
+			t.Fatalf("ScalarHTML() contains forbidden external endpoint %s", forbidden)
+		}
+	}
+}
+
+func TestScalarHTMLEscapesDocumentIdentity(t *testing.T) {
+	page, err := ScalarHTML(`</title><script>alert("x")</script>`, `service&quot;`, scalarAssetURL("asset-digest"))
+	if err != nil {
+		t.Fatalf("ScalarHTML() error = %v", err)
+	}
+	if strings.Contains(page, `</title><script>alert`) {
+		t.Fatal("ScalarHTML() left raw document identity markup")
+	}
+	config := scalarConfigFromHTML(t, page)
+	assertEqual(t, config["slug"], `service&quot;`, "slug")
+}
+
+func scalarConfigFromHTML(t *testing.T, page string) map[string]any {
+	t.Helper()
+	const marker = `data-configuration="`
+	start := strings.Index(page, marker)
+	if start == -1 {
+		t.Fatal("data-configuration attribute not found")
+	}
+	start += len(marker)
+	end := strings.Index(page[start:], `"`)
+	if end == -1 {
+		t.Fatal("data-configuration attribute is not closed")
+	}
+	raw := htmlpkg.UnescapeString(page[start : start+end])
+	var config map[string]any
+	if err := json.Unmarshal([]byte(raw), &config); err != nil {
+		t.Fatalf("unmarshal data-configuration: %v", err)
+	}
+	return config
+}
+
+func assertEqual(t *testing.T, got, want any, field string) {
+	t.Helper()
+	if got != want {
+		t.Fatalf("%s = %#v, want %#v", field, got, want)
+	}
+}

package/dist/resources/templates/go-backend/internal/core/audit/access_log_policy.go

@@ -0,0 +1,91 @@
+package audit
+
+import (
+	"hash/fnv"
+	"strings"
+	"time"
+
+	"{{module}}/internal/core/config"
+)
+
+// AccessLogPolicy 控制高频 HTTP 访问日志写入：写请求、失败请求、慢请求保真，普通读请求降采样。
+type AccessLogPolicy struct {
+	enabled               bool
+	successReadSampleRate float64
+	slowRequestThreshold  time.Duration
+	recordWriteMethods    bool
+	recordClientErrors    bool
+}
+
+// NewAccessLogPolicy 从平台配置构建访问日志治理策略。
+func NewAccessLogPolicy(cfg *config.Config) AccessLogPolicy {
+	if cfg == nil {
+		return AccessLogPolicy{
+			enabled:               true,
+			successReadSampleRate: 0.05,
+			slowRequestThreshold:  2 * time.Second,
+			recordWriteMethods:    true,
+			recordClientErrors:    true,
+		}
+	}
+	accessCfg := cfg.Audit.AccessLog
+	return AccessLogPolicy{
+		enabled:               accessCfg.Enabled,
+		successReadSampleRate: clampAccessLogRate(accessCfg.SuccessReadSampleRate),
+		slowRequestThreshold:  accessCfg.SlowRequestThreshold,
+		recordWriteMethods:    accessCfg.RecordWriteMethods,
+		recordClientErrors:    accessCfg.RecordClientErrors,
+	}
+}
+
+func (p AccessLogPolicy) ShouldRecord(entry AccessEntry) bool {
+	if !p.enabled {
+		return false
+	}
+	switch {
+	case entry.HTTPStatus >= 500:
+		return true
+	case p.recordClientErrors && entry.HTTPStatus >= 400:
+		return true
+	case p.recordWriteMethods && isWriteAccessMethod(entry.HTTPMethod):
+		return true
+	case p.slowRequestThreshold > 0 && time.Duration(entry.DurationMS)*time.Millisecond >= p.slowRequestThreshold:
+		return true
+	case p.successReadSampleRate >= 1:
+		return true
+	case p.successReadSampleRate <= 0:
+		return false
+	default:
+		return sampleAccessLog(entry, p.successReadSampleRate)
+	}
+}
+
+func isWriteAccessMethod(method string) bool {
+	switch strings.ToUpper(method) {
+	case "POST", "PUT", "PATCH", "DELETE":
+		return true
+	default:
+		return false
+	}
+}
+
+func sampleAccessLog(entry AccessEntry, rate float64) bool {
+	key := entry.RequestID
+	if key == "" {
+		key = entry.HTTPMethod + "|" + entry.HTTPPath + "|" + entry.ResourceType + "|" + entry.ResourceID
+	}
+	h := fnv.New32a()
+	_, _ = h.Write([]byte(key))
+	return float64(h.Sum32())/float64(^uint32(0)) < rate
+}
+
+func clampAccessLogRate(rate float64) float64 {
+	switch {
+	case rate < 0:
+		return 0
+	case rate > 1:
+		return 1
+	default:
+		return rate
+	}
+}

package/dist/resources/templates/go-backend/internal/core/audit/access_log_policy_test.go

@@ -0,0 +1,51 @@
+package audit
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+
+	"{{module}}/internal/core/config"
+)
+
+func TestAccessLogPolicyKeepsOperationalSignals(t *testing.T) {
+	policy := NewAccessLogPolicy(&config.Config{Audit: config.AuditConfig{AccessLog: config.AccessLogConfig{
+		Enabled:               true,
+		SuccessReadSampleRate: 0,
+		SlowRequestThreshold:  2 * time.Second,
+		RecordWriteMethods:    true,
+		RecordClientErrors:    true,
+	}}})
+
+	assert.True(t, policy.ShouldRecord(AccessEntry{HTTPMethod: "POST", HTTPStatus: 201}))
+	assert.True(t, policy.ShouldRecord(AccessEntry{HTTPMethod: "GET", HTTPStatus: 404}))
+	assert.True(t, policy.ShouldRecord(AccessEntry{HTTPMethod: "GET", HTTPStatus: 500}))
+	assert.True(t, policy.ShouldRecord(AccessEntry{HTTPMethod: "GET", HTTPStatus: 200, DurationMS: 2_000}))
+	assert.False(t, policy.ShouldRecord(AccessEntry{HTTPMethod: "GET", HTTPStatus: 200, DurationMS: 20}))
+}
+
+func TestAccessLogPolicySamplingIsDeterministic(t *testing.T) {
+	policy := NewAccessLogPolicy(&config.Config{Audit: config.AuditConfig{AccessLog: config.AccessLogConfig{
+		Enabled:               true,
+		SuccessReadSampleRate: 0.5,
+		SlowRequestThreshold:  time.Second,
+		RecordWriteMethods:    true,
+		RecordClientErrors:    true,
+	}}})
+	entry := AccessEntry{RequestID: "req-deterministic", HTTPMethod: "GET", HTTPStatus: 200, HTTPPath: "/api/v1/templates"}
+
+	first := policy.ShouldRecord(entry)
+	for i := 0; i < 20; i++ {
+		assert.Equal(t, first, policy.ShouldRecord(entry))
+	}
+}
+
+func TestAccessLogPolicyCanDisableAccessLogWrites(t *testing.T) {
+	policy := NewAccessLogPolicy(&config.Config{Audit: config.AuditConfig{AccessLog: config.AccessLogConfig{
+		Enabled: false,
+	}}})
+
+	assert.False(t, policy.ShouldRecord(AccessEntry{HTTPMethod: "POST", HTTPStatus: 201}))
+	assert.False(t, policy.ShouldRecord(AccessEntry{HTTPMethod: "GET", HTTPStatus: 500}))
+}