feat: complete API-driven projects with infrastructure and business acceptance

README.md

@@ -5,7 +5,7 @@ GoOmni 是一套面向业务复用的 Go 后端基础框架。当前默认使用
 远程 module 地址是 `git.yuntuo.hk/k2safe/go-omni`。业务项目可以直接引用指定版本：
 
 ```sh
-go get git.yuntuo.hk/k2safe/go-omni@v0.6.0-preview
+go get git.yuntuo.hk/k2safe/go-omni@v0.7.0-preview
 ```
 
 `v0.4.0` 移除了 Gin 和 Gin 专属的 `WithMode` 配置；`omni.New()` 直接使用标准库路由，已有业务 Handler / Service 无需修改。
@@ -13,7 +13,7 @@ go get git.yuntuo.hk/k2safe/go-omni@v0.6.0-preview
 创建新业务项目：
 
 ```sh
-go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.6.0-preview
+go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.7.0-preview
 go-omni new --module example.com/billing ./billing
 cd billing
 go mod tidy
@@ -27,6 +27,17 @@ go run ./cmd/server
 生成项目包含完整用户 CRUD、数据库 Repository、ServiceContext、建表脚本和就绪探针。
 先应用生成的 `schema.sql`，再配置 `GO_OMNI_DB_DSN`；启动时会检查连接与表结构，退出时释放连接池。
 
+## API 定义与项目生成
+
+当前源码新增 **API 定义驱动项目生成**：写 `.api` 定义请求、响应和路由，自动生成项目目录、DTO、Handler、Service 骨架及 OpenAPI。重复生成保留业务代码，支持只读 CI 检查，完整语法和示例见 [API 开发指南](API.md)。
+
+```sh
+go run ./cmd/go-omni api new --framework-dir . \
+  --module example.com/omniDemo ../omniDemo
+```
+
+API 生成支持 `--database mysql --storage local --log-output file` 组合初始化。上面的命令使用本地源码；远程安装见 [发布说明](RELEASE.md)，完整业务案例见 [userService](examples/userService/README.md)。
+
 ## 目录结构
 
 ```text
@@ -41,6 +52,7 @@ go-omni/
 ├── metrics/      # 请求指标与状态统计
 ├── config/       # 配置管理
 ├── validate/     # 参数校验
+├── contract/     # API 字段契约、严格多源绑定与文档约束
 ├── auth/         # 认证和权限接口
 ├── database/     # database/sql 生命周期和事务
 ├── cache/        # 有界内存缓存、Redis 适配与合并回源
@@ -62,7 +74,7 @@ go-omni/
 
 main 分支新增缓存、出站 HTTP、限流/幂等/超时中间件、后台任务和 `go-omni add` 模块脚手架。
 使用方式、默认容量和进程内能力的适用范围见 [业务基础模块](MODULES.md)，
-可以直接运行 [组合示例](examples/modules/README.md)。这些新增能力尚未包含在上面的历史版本标签中。
+可以直接运行 [组合示例](examples/modules/README.md)。这些能力从 `v0.7.0-preview` 提供。
 
 扩展模块还包括 JWT/Session、Policy、文件配置及安全热更新、Redis 共享中间件、持久队列、多平台对象存储、OpenAPI、OpenTelemetry、熔断、迁移、审计和分页。
 使用与边界见 [扩展模块](ADVANCED.md)，可运行 [文件服务组合示例](examples/platform/README.md)。go-omni 不集成 Orbit；需要流程编排的业务项目独立接入。
@@ -167,7 +179,7 @@ app.GET("/metrics", requestMetrics.Handler())
 
 接口返回请求总数、错误数、当前处理中请求、累计耗时和 HTTP 状态分布。它是进程内快照，生产环境可由业务侧定时采集到监控系统。
 
-`WithLogger(true)` 会启用 GoOmni 的统一 HTTP 访问日志；日志内容和业务日志共用 `requestId`。应用启动时可以调用 `logx.Setup` 配置 JSON/文本格式、级别、服务名和输出文件。
+`WithLogger(true)` 会启用 GoOmni 的统一 HTTP 访问日志；日志内容和业务日志共用 `requestId`。应用启动时可以调用 `logx.Setup` 配置 JSON/文本格式、级别、服务名和输出文件。文件轮转、敏感字段脱敏、异常堆栈与慢请求配置见 [logx 文档](logx/README.md)；文件直传与云端分片上传见 [storage 文档](storage/README.md)。 创建新业务项目时可通过 `go-omni new --log-output file --storage local` 按需生成配置、装配代码与可运行示例，当前源码使用方式见 [CLI 文档](cmd/go-omni/README.md)。
 
 应用配置可以统一从 `GO_OMNI_*` 环境变量加载，再交给 `omni.New`：