fix: pin scaffold dependencies and handle graceful shutdown

README.md

@@ -5,9 +5,22 @@ GoOmni 是一套面向业务复用的 Go 后端基础框架。当前默认用 Gi
 远程 module 地址是 `git.yuntuo.hk/k2safe/go-omni`。业务项目可以直接引用指定版本：
 
 ```sh
-go get git.yuntuo.hk/k2safe/go-omni@v0.1.0
+go get git.yuntuo.hk/k2safe/go-omni@v0.1.1
 ```
 
+创建新业务项目：
+
+```sh
+go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.1.1
+go-omni new --module example.com/billing ./billing
+cd billing
+go mod tidy
+go run ./cmd/server
+```
+
+远程安装的 CLI 默认引用自身版本，生成的项目不需要本地 `replace`。
+具体版本和本地开发选项见 [CLI 文档](cmd/go-omni/README.md)。
+
 ## 目录结构
 
 ```text
@@ -25,7 +38,7 @@ go-omni/
 ├── database/     # database/sql 生命周期和事务
 ├── transport/gin/ # Gin 网络适配器，可替换
 ├── examples/     # 示例项目
-└── cmd/          # 后续 CLI
+└── cmd/          # go-omni 项目脚手架
 ```
 
 ## 快速开始
@@ -104,7 +117,8 @@ application.OnShutdown(logger.Close)
 `GO_OMNI_ENVIRONMENT`、`GO_OMNI_HTTP_ADDR` 和 `GO_OMNI_SHUTDOWN_TIMEOUT`。数据库连接仍由
 `database.ConfigFromEnv` 从 `GO_OMNI_DB_*` 加载。
 
-`App` 同时实现标准 `http.Handler`，并提供 `RunContext`：收到 `SIGINT` / `SIGTERM` 后可以先停止接收新请求，再在超时时间内等待活跃请求完成。数据库连接池由 `database.Open` 创建，在服务退出时调用 `Close`。
+`App` 同时实现标准 `http.Handler`。`Run` 监听 `SIGINT` / `SIGTERM`；`RunContext` 则由调用方的 context 控制退出，生成项目已使用 `signal.NotifyContext` 接好信号。
+退出时先停止接收新请求，等待活跃请求完成，再执行资源清理。超过 `ShutdownTimeout` 时强制关闭连接、取消请求 context，并返回超时错误。业务代码应响应 context 取消；框架无法强制结束忽略取消的业务 goroutine。数据库连接池由 `database.Open` 创建，在服务退出时调用 `Close`。
 
 应用资源可以直接挂到 `omni.New` 返回的生命周期上：
 
@@ -154,4 +168,6 @@ go run ./examples/reference
 
 ## 当前边界
 
-缓存、消息队列、定时任务和 CLI 暂时作为后续可选模块。认证层只定义 `Authenticator`、`Principal` 和路由保护中间件，具体 JWT、Session 或 OAuth 由项目实现。核心数据库层只依赖 `database/sql`，具体驱动、迁移和表结构由项目选择。
+缓存、消息队列和定时任务暂时作为后续可选模块。认证层只定义 `Authenticator`、`Principal` 和路由保护中间件，具体 JWT、Session 或 OAuth 由项目实现。核心数据库层只依赖 `database/sql`，具体驱动、迁移和表结构由项目选择。
+
+当前成熟度与后续验收标准见 [ROADMAP.md](ROADMAP.md)，版本变更见 [CHANGELOG.md](CHANGELOG.md)。