fix gitea workflow path and runner label

doc/api-version-switch-zh.md

@@ -0,0 +1,74 @@
+# API 版本分流接入指南（`api-header`）
+
+## 目标
+- 通过请求头 `api-header` 动态选择不同 Handler（如 `001Handler` / `002Handler`）。
+- 让旧 App 无需升级仍可走旧逻辑，新 App 通过版本头走新逻辑。
+
+## 当前规则
+- 仅识别请求头：`api-header`
+- 严格版本格式：`x.y.z` 或 `vx.y.z`
+- 仅当 `api-header > 1.0.0` 时走新逻辑（V2）
+- 其余情况（缺失/非法/`<=1.0.0`）走旧逻辑（V1）
+
+相关代码：
+- 版本解析：`pkg/apiversion/version.go`
+- 版本注入中间件：`internal/middleware/apiVersionMiddleware.go`
+- 通用分流器：`internal/middleware/apiVersionSwitchHandler.go`
+
+## 新接口接入步骤（推荐）
+
+### 1) 实现两个 Handler
+```go
+func FooV1Handler(svcCtx *svc.ServiceContext) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		// 旧逻辑（001）
+	}
+}
+
+func FooV2Handler(svcCtx *svc.ServiceContext) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		// 新逻辑（002）
+	}
+}
+```
+
+### 2) 在路由中挂分流器
+```go
+group.POST("/foo", middleware.ApiVersionSwitchHandler(
+	foo.FooV1Handler(serverCtx),
+	foo.FooV2Handler(serverCtx),
+))
+```
+
+完成后，无需在业务代码里手写 `api-header` 判断。
+
+## 客户端调用示例
+
+### 旧逻辑（V1）
+```bash
+curl -X POST 'https://example.com/v1/common/foo' \
+  -H 'Content-Type: application/json' \
+  -d '{"x":1}'
+```
+
+### 新逻辑（V2）
+```bash
+curl -X POST 'https://example.com/v1/common/foo' \
+  -H 'Content-Type: application/json' \
+  -H 'api-header: 1.0.1' \
+  -d '{"x":1}'
+```
+
+## 测试建议（最小集）
+- 无 `api-header`：命中 V1
+- `api-header: 1.0.0`：命中 V1
+- `api-header: 1.0.1`：命中 V2
+- `api-header: abc`：命中 V1
+
+可参考测试：
+- `internal/middleware/apiVersionSwitchHandler_test.go`
+
+## 适用建议
+- 差异较小：优先在 V2 中复用现有逻辑，减少重复代码。
+- 差异较大：拆分 V1/V2 各自逻辑，避免分支污染。
+- 上线顺序：先发后端分流能力，再逐步让客户端加 `api-header`。