feat: add dependency shutdown and configurable service endpoints

PROJECT.md

@@ -1,6 +1,6 @@
 # 生成项目与文件维护边界
 
-v0.12.0-preview 提供受管理的生成项目。安装同版远程 CLI，生成的项目直接引用该版本，无需本地 replace。根目录入口支持 `go run .` 和 `go build .`；框架本身仍然是可直接引用的库。安装和私有仓库访问见 [README](README.md#准备环境与安装)。
+v0.13.0-preview 提供受管理的生成项目。安装同版远程 CLI，生成的项目直接引用该版本，无需本地 replace。根目录入口支持 `go run .` 和 `go build .`；框架本身仍然是可直接引用的库。安装和私有仓库访问见 [README](README.md#准备环境与安装)。
 
 ## 创建和日常开发
 
@@ -95,6 +95,62 @@ func (c *ServiceContext) AppOptions() []omni.Option {
 
 日志在 AppOptions 前初始化，其配置应放在 Config 中。退出信号先触发 HTTP 排空；达到 shutdownTimeout 后按框架规则强制关闭连接。请求仍依赖的后台任务/客户端不能直接绑定信号 context 提前关闭，应持有独立生命周期，在 OnClose 中取消。业务必须响应请求 context 取消；忽略取消的 goroutine 无法保证在超时前结束。
 
+## 依赖主动申请退出
+
+从 v0.13.0-preview 起，生成的 svc 提供 `RequestShutdown(err)`。数据库客户端、节点租约、后台任务等发现不可恢复故障时，由项目决定是否退出：
+
+```go
+// 在 svc 的依赖监控回调中调用；err 是实际故障原因。
+c.RequestShutdown(err)
+```
+
+这只是通知，立即返回，不等待 HTTP 排空，也不直接关闭数据库。生成入口停止接收新请求，等待在途请求完成；超过 `shutdownTimeout` 后取消请求并关闭连接，再执行 svc.Close，最后关闭日志。非空故障原因保留在返回错误链中，进程退出码为 1；`RequestShutdown(nil)` 或正常 SIGINT/SIGTERM 在没有其他故障时退出码为 0。
+
+多个依赖可并发通知，关闭流程仅执行一次，首个非空故障原因保留。正常信号已开始排空时收到的故障也不会被清理动作覆盖。初始化期间的通知同样有效，不依赖 HTTP 监听已经启动。业务应在 Close/OnClose 中停止并等待自己启动的监控任务，再结束资源清理；关闭完成以后才报告的故障无法参与已经结束的进程结果。
+
+`Lifecycle *lifecycle.Controller` 是 svc 持有的通用控制器，初始化时创建，生成入口使用它的 Context。该 Context 表示服务正在停止，不代表数据库已经关闭。不能把它当作在途请求的 Context，也不要在它取消时立刻关闭请求仍依赖的资源。发号器失去租约后拒绝发号等业务安全规则仍由项目实现。
+
+## 配置内置接口
+
+生成项目在 `etc/config.yaml` 明确列出以下默认配置；可以独立关闭、修改路径，或让健康接口返回原始 JSON：
+
+```yaml
+server:
+  endpoints:
+    liveness:
+      enabled: true
+      path: /health/live
+      responseMode: app
+    readiness:
+      enabled: true
+      path: /health/ready
+      responseMode: app
+    openapi:
+      enabled: true
+      path: /openapi.json
+```
+
+`responseMode: app` 使用项目 App 的响应模板/自定义 Encoder。健康成功使用项目成功码和成功提示；未就绪的 `NOT_READY` 可在项目 Go 错误目录配置业务码和公开提示，无需在 `.api` 再声明。
+
+健康探针的 HTTP 状态固定遵循探针语义：存活/就绪为 200，未就绪为 503；项目错误目录或自定义编码器不能把未就绪改为 HTTP 200。响应模板 `${status}` 同样使用探针状态。失败继续进入业务失败日志/指标，探针底层原因保留在错误链供日志使用，不直接返回给调用方。
+
+`responseMode: raw` 返回 `{"status":"ready"}` 等健康数据，有依赖时包含检查名称、结果与耗时；不包装公共体。存活检查不执行依赖探针；服务开始退出后，就绪检查返回 503，存活仍可返回 200，直到监听关闭。OpenAPI 始终输出规范文档本身，不使用业务响应包装；关闭 HTTP 文档端点不影响生成 `docs/openapi.json`。
+
+环境变量覆盖配置文件，例如 `GO_OMNI_ENDPOINTS_READINESS_PATH=/readyz`、`GO_OMNI_ENDPOINTS_READINESS_RESPONSE_MODE=raw`、`GO_OMNI_ENDPOINTS_OPENAPI_ENABLED=false`；liveness/readiness/openapi 都支持对应的 ENABLED 和 PATH。Config/AppOptions 的最终有效配置决定是否注册。
+
+关闭或改名后，旧路径不再由框架保留，项目可以在 `.api` 自己声明。启用的内置 GET 路由与业务路由相同或被业务参数/通配路径覆盖时，在创建 App、开始监听之前报错；不会覆盖业务路由。内置接口仍经过全局中间件；项目在鉴权中间件中明确决定这些路径的访问规则，框架不自动绕过鉴权。
+
+## 从 v0.12 生成项目升级
+
+manifest v2 和现有目录保留。升级同版 CLI 与框架依赖后执行 `api generate`，生成器自动更新 main 和 Handler；`svc`、配置与业务文件仍按字节保留，所以需要在项目拥有的 svc 文件补入以下扩展：
+
+1. `serviceContext.go` 导入 `git.yuntuo.hk/k2safe/go-omni/lifecycle`，给 ServiceContext 增加 `Lifecycle *lifecycle.Controller`；创建 c 时用 `lifecycle.New(ctx)` 初始化，并在后续依赖初始化前设置 `ctx = c.Lifecycle.Context()`。
+2. 增加 `func (c *ServiceContext) RequestShutdown(err error) { c.Lifecycle.RequestShutdown(err) }`。
+3. 构造失败的 defer 在 `c.Close()` 后保留 `c.Lifecycle.Err()`；Close 的 `closeOnce.Do` 开头调用 `c.Lifecycle.RequestShutdown(nil)`，重复关闭仍由已有 once 保护。
+4. 配置默认值若来自 `config.Default()`，自动具有默认端点配置；如需禁用或改路径，在 YAML 或项目 Config 中显式设置。手动拼 Config 的项目需要自行填写要启用的端点。
+
+精确实现可对照 [示例 svc](examples/managedService/internal/svc/serviceContext.go) 和 [关闭逻辑](examples/managedService/internal/svc/close.go)，也可在临时目录用新版 CLI 生成参考。不要覆盖原有数据库/客户端初始化；不需要手改 main、Handler 或引入另一套启动器。最后执行 `api generate --check`、`go test ./...`、`go build .`，并验证故障退出。
+
 ## App 默认响应格式
 
 在 **入口** `.api` 声明一次：
@@ -157,7 +213,7 @@ get /download (DownloadReq)
 
 ## 已有服务接入步骤
 
-每个独立服务生成一个项目，module 名称、上层目录和共享业务包由项目选择。接入时固定 CLI 与框架版本为 v0.12.0-preview：
+每个独立服务生成一个项目，module 名称、上层目录和共享业务包由项目选择。接入时固定 CLI 与框架版本为 v0.13.0-preview：
 
 1. 先保留旧服务，整理实际路由及现有响应、鉴权和超时要求。在新目录执行 `go-omni new --api /path/to/service.api --module example.com/service ./service`；不对旧入口强制覆盖。
 2. 在 `.api` 中选择 `@app(defaultResponse: ...)`，显式保留原项目的字段、成功码、错误码和 `dataMode`。需要独立回执的路由单独声明 raw/produces。普通路由、404/405 和提前返回的中间件一起验收。