docs: record remote preview acceptance and verify example error logging

2026-09-23 17:37:53 +08:00
parent 0ce3efb6fc
commit ab8eac5fc4
5 changed files with 214 additions and 4 deletions
--- a/database/README.md
+++ b/database/README.md
@@ -56,3 +56,11 @@ python3 scripts/verifyDatabase.py --version v0.2.0
 脚本仅操作本次创建的独立容器与数据库，验证 HTTP CRUD、服务重启持久化、事务提交与
 错误/panic/取消回滚、连接池关闭、缺少表结构时启动失败，以及停库后的 readiness 503 和恢复后的 200。
 结束时清理容器、匿名数据卷和临时项目。常规 `go test ./...` 不依赖 Docker。
+
+
+## 项目配置叠加
+
+`database.ApplyEnv(cfg, prefix)` 在已有文件/默认配置上覆盖非空环境变量，保留未覆盖的池参数。
+`Config` 的 JSON/YAML 字段使用 lowerCamelCase，`DSN` 使用 `json:"-"`，连接密钥从环境变量加载。
+API 脚手架 `--database mysql` 使用此流程，并要求正的 `maxOpenConns`，提供数据库 readiness 与幂等清理。
+具体表结构、迁移和 Repository 留在业务项目，参考 `examples/userService`。
--- a/examples/userService/internal/service/user/errors_test.go
+++ b/examples/userService/internal/service/user/errors_test.go
@@ -0,0 +1,36 @@
+package user
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"strings"
+	"testing"
+
+	"example.com/userService/internal/servicecontext"
+	apierrors "git.yuntuo.hk/k2safe/go-omni/errors"
+	"git.yuntuo.hk/k2safe/go-omni/logx"
+)
+
+func TestDriverMessageDoesNotReachAccessOrBusinessLogs(t *testing.T) {
+	var output bytes.Buffer
+	cfg := logx.Default()
+	cfg.Writer = &output
+	logger, err := logx.New(cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer logger.Close()
+	service := New(&servicecontext.Context{Logger: logger})
+	secret := "private-user-input-in-driver-error"
+	got := service.failure(context.Background(), errors.New(secret))
+	if apierrors.From(got).Status != 500 {
+		t.Fatal("wrong error mapping")
+	}
+	if strings.Contains(got.Error(), secret) || strings.Contains(output.String(), secret) {
+		t.Fatal("driver detail leaked into logging path")
+	}
+	if !strings.Contains(output.String(), "user.operationFailed") {
+		t.Fatal("failure event missing")
+	}
+}
--- a/examples/userService/internal/service/user/service.go
+++ b/examples/userService/internal/service/user/service.go
@@ -44,7 +44,9 @@ func (s *Service) failure(ctx context.Context, err error) error {
 	default:
 		// Do not log SQL/DSN or user input; requestId correlates the failed operation.
 		s.deps.Logger.ErrorContext(ctx, "user.operationFailed", "category", "persistence")
-		return apierrors.Internal(err)
+		// HTTP access logging also sees the returned error. Keep raw driver
+		// errors out of that path because their messages may contain input.
+		return apierrors.New(500, "INTERNAL_ERROR", "internal server error")
 	}
 }
 func (s *Service) mutate(ctx context.Context, operation string, fn func(repo.UserRepository) (model.User, error)) (*types.UserResp, error) {
--- a/performance/apiWorkflowAcceptance.md
+++ b/performance/apiWorkflowAcceptance.md
@@ -12,7 +12,7 @@
 - 独立用户示例：nethttp/native 共 30 项业务、存储和生命周期检查通过。
 - MySQL 真实事务：提交、错误回滚、panic 回滚、context 取消回滚；业务增/改/删在审计写入失败时整体回滚。
 - 通过 CLI 显式应用数据库迁移；数据库停机 readiness=503，恢复后重新就绪；进程重启数据仍在。
- 28 份开发者拥有的文件在重生成后保持原字节，包括业务实现、配置、迁移和测试。
+- 本地初轮 28 份开发者拥有的文件在重生成后保持原字节，包括业务实现、配置、迁移和测试。
 - 存储初始化失败关闭此前打开的数据库连接，Close 可重复调用，关闭后不能重开存储。

 数据库容器只绑定 localhost，限制 1 CPU / 768 MiB，使用随机临时密钥，退出删除容器及卷。
@@ -27,5 +27,17 @@

 ## 远程版本验收

-发布标签后执行 `python3 scripts/verifyAPIWorkflow.py --version v0.7.0-preview --report performance/apiWorkflowRemote.json`。
-结果完成后记录于同目录 remote 报告；该检查从空 module cache 安装 CLI，并要求业务依赖没有本地 replace。
+已发布 `v0.7.0-preview`，标签指向 `0ce3efb6fca77951e7ae3046128f82afc28446d1`。
+
+执行 `python3 scripts/verifyAPIWorkflow.py --version v0.7.0-preview --report performance/apiWorkflowRemote.json` 通过：
+
+- 从空 module cache 下载并安装远程 CLI，未使用源码构建的 CLI。
+- 在全新目录生成 MySQL + local 项目；go.mod 固定 `v0.7.0-preview`，无本地 replace，实际编译通过。
+- 独立用户示例的框架依赖从远程下载，module checksum 为 `h1:aHdKHoegW2C7sjkq5D8ls2sxDJ+fWbiZ2UnWDers1yg=`。
+- nethttp/native 共 30 项业务、存储、日志与生命周期检查通过；真实数据库迁移、事务和启动清理测试通过。
+- 最终示例补充了数据库错误日志边界：原始 driver 错误可能含业务输入，因此返回到 HTTP 访问日志的 500 不携带原文；用单元测试和远程全流程验证。
+- 框架发布标签保持不变；示例是独立 module，后续示例和验收报告维护在 main。报告记录了实际测试示例与生成器源码哈希。
+
+[远程验收报告](apiWorkflowRemote.json) 包含准确的文件保护数量、sourceHashes 和各项检查结果。
+
+所有验收已结束，临时服务、数据库容器和测试目录由脚本清理。
--- a/performance/apiWorkflowRemote.json
+++ b/performance/apiWorkflowRemote.json
@@ -0,0 +1,152 @@
+{
+  "passed": true,
+  "frameworkVersion": "v0.7.0-preview",
+  "noLocalReplace": true,
+  "durationSeconds": 33.0,
+  "regenerationPreservedHandwrittenFiles": 29,
+  "groups": [
+    {
+      "transport": "nethttp",
+      "checks": [
+        "authBeforeService",
+        "emptyPageAndQueryDefaults",
+        "contractValidation",
+        "createReadNormalize",
+        "uniqueEmailConflict",
+        "updateAndPagination",
+        "createUpdateDeleteRollbackOnAuditFailure",
+        "storageUploadAndSignedDownload",
+        "signedDownloadTamperRejected",
+        "openAPIMatchesContract",
+        "readinessOutageAndRecovery",
+        "persistenceAfterServiceRestart",
+        "deleteAndTransactionalAudit",
+        "gracefulStopAndListenerRelease",
+        "businessFileLogsAndSecretExclusion"
+      ]
+    },
+    {
+      "transport": "native",
+      "checks": [
+        "authBeforeService",
+        "emptyPageAndQueryDefaults",
+        "contractValidation",
+        "createReadNormalize",
+        "uniqueEmailConflict",
+        "updateAndPagination",
+        "createUpdateDeleteRollbackOnAuditFailure",
+        "storageUploadAndSignedDownload",
+        "signedDownloadTamperRejected",
+        "openAPIMatchesContract",
+        "readinessOutageAndRecovery",
+        "persistenceAfterServiceRestart",
+        "deleteAndTransactionalAudit",
+        "gracefulStopAndListenerRelease",
+        "businessFileLogsAndSecretExclusion"
+      ]
+    }
+  ],
+  "transactionTests": [
+    "commit",
+    "errorRollback",
+    "panicRollback",
+    "cancellationRollback"
+  ],
+  "startupTests": [
+    "storageFailureClosesDatabase",
+    "idempotentClose",
+    "closedContextCannotReopen"
+  ],
+  "migrationCLI": true,
+  "frameworkSum": "h1:aHdKHoegW2C7sjkq5D8ls2sxDJ+fWbiZ2UnWDers1yg=",
+  "sourceHashes": {
+    "cmd/go-omni/api.go": "59f3b8b45497a9f560d649ac5e7b622362f5f20edd81251d7dc76f21605fc90a",
+    "cmd/go-omni/api_test.go": "ee68b4b8b0155f4d123135b0706c6d17d8fc90e2bcfc1312aa4f9e7a9da2454b",
+    "cmd/go-omni/apigen/apigen_test.go": "8e7c94795ffbc3ee062756a77cfeb274f3cd1a78f1dbc3b51ec4ceb14f478518",
+    "cmd/go-omni/apigen/compile.go": "6709da0b69e8d10d49a874447e00c93d0a819d8367b2188e9626bd0c7b3baef2",
+    "cmd/go-omni/apigen/generate.go": "373ec9834aa4ed71a5311c1ef40b78dc6c303aa884d7bb16a680058ca751b2bc",
+    "cmd/go-omni/apigen/parse.go": "e85fe261fdec2e3487851e265babd7af8c7f6153694ad6fb73177aac33f8ef95",
+    "cmd/go-omni/apigen/profile.go": "877939398384c44316e5e052d92c4a93fb3b74a6742df2414a0054913f3fca27",
+    "cmd/go-omni/apigen/profile_test.go": "5f3c091da241fe0f8b99ac19e9efd2c3177aea72e63a346f99fecc0f548aad1a",
+    "cmd/go-omni/apigen/templates.go": "9303a2fafe44cb7e763a2c5beb193c16fa0dc0c2dbde4cb6e14f2ba533d3e56e",
+    "cmd/go-omni/apigen/write.go": "1ce3871fd92f638d097c576583c169daa0ce2fa8010dbcd34a8cd7faa314a1a2",
+    "cmd/go-omni/main.go": "6f851d21792a9eb9fcbc5095e8cacb3dcee1c715a3980650c75381f0e46f51a9",
+    "cmd/go-omni/main_test.go": "b8040d2b19a1c86672fe1b1be7fa1bf7f885aece79ded6ffa0cc670887b7136f",
+    "cmd/go-omni/migrate.go": "f1ce89fbe419205eb82172da2b90e8888905d2b85d1a9db2a72b568bcf849a70",
+    "cmd/go-omni/migrate_test.go": "15d9a4aaebf9f899e523e908f1fa3c2282eb1e6c8cadbefae6b68f1ae4e00e6e",
+    "cmd/go-omni/scaffold/addModule.go": "8f43bd68c2b3820cf1d036c4f2c5f9d06d1c7c8e5114f5081597d905f8d8cdcc",
+    "cmd/go-omni/scaffold/addModule_test.go": "667c45312f628f0fb5b8206ddef7ccc02a75f33b72f73fd6a17b03da0cb62e91",
+    "cmd/go-omni/scaffold/apiInfrastructure.go": "f493364448254cae2d8e658bf5c69e96a3264c2bf3fa50fd48a5ebdb20edabd8",
+    "cmd/go-omni/scaffold/moduleProfiles_test.go": "ae9790e5d3549d32fc72739a10a31ea858e5a8f8189cf1f5c1840bf80b3f8ad6",
+    "cmd/go-omni/scaffold/moduleTemplates/README.md.tmpl": "9d3bfc46cac5618bcff7d8a6b2cc9f123e818aeb3dee9bcdfe0f91db584994bd",
+    "cmd/go-omni/scaffold/moduleTemplates/handler-handler.go.tmpl": "729cd0f6faba53d5d2c1492935e12ac2adcefde4490748e25c18be7ccb3f7139",
+    "cmd/go-omni/scaffold/moduleTemplates/model-model.go.tmpl": "a005611f6b455d4d8469e316bc26fa571043b2da1834db2b3dd14a96d66221d7",
+    "cmd/go-omni/scaffold/moduleTemplates/module.go.tmpl": "fb0be7fd571ba2c0edb01d70d68cdbbfe53561caab98346bf1ac7cd8df07205a",
+    "cmd/go-omni/scaffold/moduleTemplates/repository-repository.go.tmpl": "902da3d9f12395fb226178c4428ff547e1c2fce3261882dba98d1400d8c90747",
+    "cmd/go-omni/scaffold/moduleTemplates/service-service.go.tmpl": "49d26044a69a43e983aa5ba4b5b2399b26b77898b23e230751ad1372c2af3178",
+    "cmd/go-omni/scaffold/scaffold.go": "71b3091b83c3e45ac1981164e8c819c997ad96607d535f1492333370f4872548",
+    "cmd/go-omni/scaffold/scaffold_test.go": "58aab9251b01e394bbc90aeb538ff035dd32c73c0d4815132ac6cbc086527cda",
+    "cmd/go-omni/scaffold/templates/README.md.tmpl": "8ec215775fcafd437480022307fffd2ffe43685bc2b5d328b0c1d58402986e0a",
+    "cmd/go-omni/scaffold/templates/api-context.go.tmpl": "d2d67c3d235c4b1c965364f40f49c441d92764ad7ab8fd6848f56b1028e93b1b",
+    "cmd/go-omni/scaffold/templates/cmd-server-main.go.tmpl": "07c4f81109ece43fcf15bb807ada5ae6dc7e732babc7293269514a21cd389955",
+    "cmd/go-omni/scaffold/templates/databaseIntegration_test.go.tmpl": "81c4f7fbc919d74b738d3a7338248cbd83cfa0803b2058e8ee184e3ce51e7e9b",
+    "cmd/go-omni/scaffold/templates/go.mod.tmpl": "7d3bb15d2292e36939cc1905258d2800aeaf0e37d7d041b2ff8cfdb6fc84c57a",
+    "cmd/go-omni/scaffold/templates/internal-handler-user.go.tmpl": "7f8dbcd2f9b0129a90160d6059e47d19d4758274060a1a3e5160055d0592d34f",
+    "cmd/go-omni/scaffold/templates/internal-model-errors.go.tmpl": "f123eace52952321b0665a92a2923514c52c8c3bf13df1065710e9675750f837",
+    "cmd/go-omni/scaffold/templates/internal-model-user.go.tmpl": "b391143e7386e169b53e7fed25de1146e8c52f3fa287b12728e8d22b33f386de",
+    "cmd/go-omni/scaffold/templates/internal-repository-memory.go.tmpl": "148abc273c1fab3f28536706792762ae41e8687dfe9986c374372f162600feac",
+    "cmd/go-omni/scaffold/templates/internal-repository-mysql.go.tmpl": "34bd333e29211a0025ff6ebaea18c7f142f18f1cc451d692f9d360e8c8f6f635",
+    "cmd/go-omni/scaffold/templates/internal-repository-users.go.tmpl": "6d7dd80f34a9c215daeb4a86bfbe11e845e7ff7e9864c8af43e1c2ec3a8b28ec",
+    "cmd/go-omni/scaffold/templates/internal-service-user.go.tmpl": "33fdee3a2c3d98e7ca6a323b5e888a73582f94e327b6c24a34c09bf180db7b3d",
+    "cmd/go-omni/scaffold/templates/internal-servicecontext-context.go.tmpl": "de70ecc4194db8a2da5d65297f452a40b453652cb814cd228ce03d465761c856",
+    "cmd/go-omni/scaffold/templates/modules-README.md.tmpl": "4b84fbc2310b856d86c6fcd9a47d97d2261019c74ea8e0cdbc41229086aa3527",
+    "cmd/go-omni/scaffold/templates/modules-config.yaml.tmpl": "b8734080ae6d533a175bcad946ce2cb55d8bac1729918291753b9ca03064910f",
+    "cmd/go-omni/scaffold/templates/modules-filesHandler.go.tmpl": "426867fbef5b99a85394fa4457dd38b9a194adf4bdfb293384b2fbbc799091da",
+    "cmd/go-omni/scaffold/templates/modules-filesHandler_test.go.tmpl": "9571e39bd0a330739eb1fd7e636cd58961b41b44772b2b49162e41deda98547f",
+    "cmd/go-omni/scaffold/templates/modules-filesService.go.tmpl": "6460ee9a873af45ca6cec779bf53302acfce21499610425a4704c2f179eddb8f",
+    "cmd/go-omni/scaffold/templates/modules-gitignore.tmpl": "2579f2a63ff2962239b92dd841b0d0d26e783d85c9d0100011936c8bcbf5d0d3",
+    "cmd/go-omni/scaffold/templates/modules-main.go.tmpl": "cb8daddd4e12afd238540be7022187c74a548d9e409b3a7f1eaf84a9139218bf",
+    "cmd/go-omni/scaffold/templates/modules-settings.go.tmpl": "91084caaa1fd994dde714f52b242d23e41adb731383b12d74399247c87ac5597",
+    "cmd/go-omni/scaffold/templates/modules-settings_test.go.tmpl": "76e55f8954b7606d7146eb1e965065c521a2b81234a47742ed69a93aac300406",
+    "cmd/go-omni/scaffold/templates/modules-storage.go.tmpl": "a775acf2d2490288a8e5482bb0a8769be6b0a8c9cfcc9bb10b62aabbd05fa0c7",
+    "cmd/go-omni/scaffold/templates/modules-storage_test.go.tmpl": "dacca42d228bd9352948054eb2d071829a8a61d8c6fa24d95ff00fc39a74309e",
+    "cmd/go-omni/scaffold/templates/schema.sql.tmpl": "7c5108f18fc7d8ff75c97afd96fcaa9f8ed026c79c71c5612f55572d73354abb",
+    "cmd/go-omni/scaffold/version.go": "2ae216e676082a26e5778045e20964eb4f9e99a58d4f9a9ff4b559b286837d7a",
+    "database/configOverlay_test.go": "01c9b44fded226494ca12f7d0f41a9ff417d8135d263a5833727c1c028b6b8e3",
+    "database/database.go": "3d8615e1bf58ecdae21558591e745c241e499ba6e85fc07acfa2344e04ce95db",
+    "database/database_test.go": "18eac1e4c6dbd6a09216168839ba3511aac8a38c2ddf6fdd5267f35435b09f67",
+    "database/lifecycle_test.go": "e141b52edfb9867184dedac0e79feed56a5b137acbe64280ad69647653bbea21",
+    "database/migrate/migrate.go": "fd6cd27d2dce5b35ffe80eb5442c47c657b93ffc6545bbcc1ee4651a70a4f80b",
+    "database/migrate/migrate_test.go": "d7ba91eed8cfd97e4ef0741d582f493dd411b65ad3192f05b167f75d9b9dcf90",
+    "examples/userService/api/user.api": "cdbc7f356f336b6265e9c3fc9974952e05cf14001c58b330a826b4bb32f02712",
+    "examples/userService/cmd/server/main.go": "80ba4721f677947b7f2ece21d5f3e89ee0c4d2cc653412d83aef2b3a45bd3ccb",
+    "examples/userService/etc/config.yaml": "f50df3cddbc3c23f233405e7a9d8895b9d83d2a0607ccf001261fcd4b8978ee9",
+    "examples/userService/internal/handler/openapiGen.go": "8ddc60c338630db915b9f074ade776f526eabf60fc99b33e425359fd415c4926",
+    "examples/userService/internal/handler/routesGen.go": "7f45030e7eb9f055c4b4d2ff12ad855d7c726aad4aee63c5b3c3f97559a64257",
+    "examples/userService/internal/handler/user/handlersGen.go": "06f3c2798ff323812ff3eb2d8b933a569af3ce1b86a67b66036374add98c0d7e",
+    "examples/userService/internal/middleware/auth.go": "f12197d01da155ad56a8a44f951c83739cbfca48c3224bd52a7bc25357f05c9f",
+    "examples/userService/internal/middleware/auth_test.go": "6ffdd7c7b2ede7e5791eec0eb1d9105ea45b3a52cc3140fe7a94fdc9b6fb3ec6",
+    "examples/userService/internal/middleware/registryGen.go": "a6122a5453dedc6a4415860108814c50e155128cfe5412b39dd33ce2d01b4b00",
+    "examples/userService/internal/model/errors.go": "f123eace52952321b0665a92a2923514c52c8c3bf13df1065710e9675750f837",
+    "examples/userService/internal/model/user.go": "b391143e7386e169b53e7fed25de1146e8c52f3fa287b12728e8d22b33f386de",
+    "examples/userService/internal/repository/user/mysql.go": "924cae233a68e506e9b0b953529e0ccb13a0e71d24723309383c464e1852b833",
+    "examples/userService/internal/repository/user/repository.go": "2aca07788d8d59831b10ac665882ca8157b20f384115bb90742f235f8352a69d",
+    "examples/userService/internal/repository/user/store.go": "f776832e4f3b26fb889dad53b65742833ddb7f43b7dddc72915ad3fe47ec4d3e",
+    "examples/userService/internal/repository/user/transaction_test.go": "9af4cb3a03b71026b80aa5078ddda4e3c4f72a7ab14bed6c87603a4db2cc2a22",
+    "examples/userService/internal/service/user/createUser.go": "53d0ea7371e10a0bd3f32f57b9bff9b48b5f9a3315218f95a258fa45b81d9368",
+    "examples/userService/internal/service/user/deleteUser.go": "0cd0b038d5a11429de438311980ef19a8f6e28ea0d7cf5ebaaf78858daf3a124",
+    "examples/userService/internal/service/user/errors_test.go": "c0193bdc674cbe15c4871a91e288323a99193d19ba8fd874f9bf17c390917e5c",
+    "examples/userService/internal/service/user/exportUser.go": "dac2adb0c9ea43a4af15511ae488afaa6d9c9b351e68e9b8a54f4014d29de14d",
+    "examples/userService/internal/service/user/getUser.go": "a307fa716c70286a2a6c5d5c0a6c35ec6d258c3278e2a7fe86b74b324d7b7283",
+    "examples/userService/internal/service/user/listUsers.go": "f0bf8b9c3a4c4a699112e3493b7fe611e2dd4f6e8a4437106396c47d484f1383",
+    "examples/userService/internal/service/user/service.go": "fabaac1e330364f899f5c580454051054c715c56f37983155108c185fe7f2637",
+    "examples/userService/internal/service/user/updateUser.go": "9b0e3e4296c0e0df98956961a928612d9203c0fa09aa71bb0683e430e1133ff0",
+    "examples/userService/internal/servicecontext/context.go": "5527ca07049f5c5f5deffa65e5759494b2e0a77804b629b3ecb1705e7557ee25",
+    "examples/userService/internal/servicecontext/context_test.go": "04d008b6cf5b7894752bc5222abb8f4120f1ebe060034ac55ec9663c1f7bc613",
+    "examples/userService/internal/servicecontext/storage.go": "9402e1ee7a258b2db4b6dbf38fcb0674ad8907fb2a948d47dd8374f78bec444d",
+    "examples/userService/internal/settings/config.go": "721c3744a61a2d2807edcdfa190336901368966a0fb952561d0e00da5730cd3a",
+    "examples/userService/internal/types/typesGen.go": "3ab2ce9ffe467c3ea53ac3d1fec283ecebc87cef57fd592d08dca991fd964876",
+    "examples/userService/migrations/000001_users.down.sql": "64b47d3d2644745a2ba1197b73760e63fe0f2c1d12c193888c4417b3d5abb75e",
+    "examples/userService/migrations/000001_users.up.sql": "c6ea5cb92ee53fe20e43373d084ff360d49921b785602145e55380e4adbee1dc"
+  }
+}