feat: 支持 prefix 和 name 两种命名模式

- 添加 nameMode 字段（prefix/name），控制是否添加时间戳
- 添加时间戳生成和名称清理工具函数
- prefix 模式：自动添加时间戳，清理时需使用输出文件
- name 模式：使用固定名称，可直接使用配置文件清理
- 创建 examples 目录存放示例配置文件
- 更新文档说明使用方式

Author: [email protected]

.gitignore

@@ -38,3 +38,8 @@ my-users.yaml
 dev-users.yaml
 ci-users.yaml
 test-users.yaml
+user.yaml
+
+# Output files
+output.yaml
+*.output.yaml

README.md

@@ -67,16 +67,47 @@ export GITLAB_TOKEN=your-personal-access-token
   --host https://your-gitlab.com \
   --token your-token \
   -f config.yaml
+
+# ⚠️ 注意：prefix 模式下的清理
+# 如果使用 nameMode: prefix（添加时间戳），清理时需要使用创建时输出的文件
+# 因为实际的用户名、组名、项目名都带有时间戳
+
+# 1. 创建时保存输出文件
+./bin/gitlab-cli user create \
+  -f config.yaml \
+  -o output.yaml
+
+# 2. 清理时使用输出文件
+./bin/gitlab-cli user cleanup \
+  -f output.yaml
 ```
 
 ## 📖 配置文件示例
 
+### 命名模式说明
+
+配置文件支持两种命名模式：
+
+**1. prefix 模式（默认）**
+- 自动在 username、email、group path、project path 后添加时间戳
+- 示例：`tektoncd` → `tektoncd-20251030150000`
+- 适用场景：测试环境、需要创建多个相似资源
+- ⚠️ 清理时必须使用创建时输出的文件
+
+**2. name 模式**
+- 不添加时间戳，直接使用配置文件中的名称
+- 示例：`test-user-001` → `test-user-001`（不变）
+- 适用场景：生产环境、固定名称的资源
+- 可直接使用配置文件清理
+
 ### 基本配置
 
 ```yaml
 # test-users.yaml
 users:
-  - username: tektoncd
+  # 使用 prefix 模式（默认）
+  - nameMode: prefix  # 可选，默认为 prefix
+    username: tektoncd
     email: [email protected]
     name: tektoncd-test
     password: "MyStr0ng!Pass2024"

examples/template-example.yaml

@@ -0,0 +1,46 @@
+# GitLab CLI 输出模板示例
+# 支持 Go template 语法，可以访问 OutputConfig 结构中的所有数据
+# 数据结构: .Endpoint (完整 URL), .Scheme (http/https), .Host (主机名) 是 GitLab 服务器配置
+# 数据结构: .Users[0] 包含 Username, Email, Name, UserID, Token, Groups
+
+{{- range .Users }}
+# ========================================
+# 用户: {{ .Username }}
+# ========================================
+
+toolchains:
+  gitlab:
+    # endpoint is the full endpoint of the server
+    endpoint: {{ $.Endpoint }}
+    host: {{ $.Host }}
+    # scheme, http or https
+    scheme: {{ $.Scheme }}
+    # username, the user name of the login account
+    username: {{ .Username }}
+    # email
+    email: {{ .Email }}
+    {{- if .Token }}
+    # Personal Access Token
+    token:
+      value: {{ .Token.Value }}
+      scope: {{ range $i, $s := .Token.Scope }}{{ if $i }}, {{ end }}{{ $s }}{{ end }}
+      expires_at: {{ .Token.ExpiresAt }}
+    {{- end }}
+    {{- if .Groups }}
+    # Groups and Projects
+    TestGroups:
+      default: {{ .Username }}
+      {{- range .Groups }}
+      - name: {{ .Name }}
+        path: {{ .Path }}
+        group_id: {{ .GroupID }}
+        visibility: {{ .Visibility }}
+        {{- if .Projects }}
+        projects:
+          {{- range .Projects }}
+          - name: {{ .Name }}
+          {{- end }}
+        {{- end }}
+      {{- end }}
+    {{- end }}
+{{- end }}

examples/user.yaml

@@ -0,0 +1,51 @@
+users:
+  # 示例 1: prefix 模式（添加时间戳）- 默认模式
+  # ⚠️ 注意：prefix 模式下，清理时需要使用创建时输出的文件
+  # 使用方法：
+  #   1. 创建：./bin/gitlab-cli user create -f user.yaml -o output.yaml
+  #   2. 清理：./bin/gitlab-cli user cleanup -f output.yaml
+  - nameMode: prefix  # 可选，默认为 prefix
+    username: tektoncd
+    email: [email protected]
+    name: tektoncd-test
+    password: "MyStr0ng!Pass2024"
+    # Personal Access Token 配置（可选）
+    token:
+      scope:
+        - api
+        - read_user
+        - read_repository
+        - write_repository
+        - read_api
+        - create_runner
+      # expires_at: 2026-01-01  # 可选，不指定则默认为第2天
+
+    # 组和项目配置
+    groups:
+      - name: backend-group
+        path: backend-group
+        visibility: private
+        projects:
+          - name: demo
+            path: demo
+            description: demo project
+            visibility: private
+
+  # 示例 2: name 模式（不添加时间戳）
+  # 使用方法：
+  #   1. 创建：./bin/gitlab-cli user create -f user.yaml
+  #   2. 清理：./bin/gitlab-cli user cleanup -f user.yaml  # 可直接使用同一配置文件
+  # - nameMode: name
+  #   username: test-user-001
+  #   email: [email protected]
+  #   name: Test User 001
+  #   password: "MyStr0ng!Pass2024"
+  #   groups:
+  #     - name: test-group
+  #       path: test-group
+  #       visibility: private
+  #       projects:
+  #         - name: test-project
+  #           path: test-project
+  #           description: Test project
+  #           visibility: private

internal/utils/utils.go

@@ -1,9 +1,101 @@
 package utils
 
+import (
+	"fmt"
+	"regexp"
+	"strings"
+	"time"
+)
+
 // GetVisibility 获取可见性设置，默认为 private
 func GetVisibility(v string) string {
 	if v == "" {
 		return "private"
 	}
 	return v
 }
+
+// GenerateTimestampSuffix 生成时间戳后缀（格式：20060102150405）
+func GenerateTimestampSuffix() string {
+	return time.Now().Format("20060102150405")
+}
+
+// GenerateUsernameWithTimestamp 基于前缀生成符合 GitLab 要求的 username
+// 格式：prefix-timestamp
+func GenerateUsernameWithTimestamp(prefix string) string {
+	timestamp := GenerateTimestampSuffix()
+	username := fmt.Sprintf("%s-%s", prefix, timestamp)
+	// 确保符合 GitLab username 规则：只能包含字母、数字、下划线、点号、破折号
+	username = sanitizeUsername(username)
+	// 限制长度为 255
+	if len(username) > 255 {
+		username = username[:255]
+	}
+	return username
+}
+
+// GenerateEmailWithTimestamp 基于前缀生成唯一的 email
+// 格式：prefix-timestamp@domain
+func GenerateEmailWithTimestamp(emailPrefix string) string {
+	// 解析邮箱前缀和域名
+	parts := strings.Split(emailPrefix, "@")
+	if len(parts) != 2 {
+		// 如果不是有效的邮箱格式，使用默认域名
+		return fmt.Sprintf("%s-%[email protected]", emailPrefix, GenerateTimestampSuffix())
+	}
+
+	localPart := parts[0]
+	domain := parts[1]
+	timestamp := GenerateTimestampSuffix()
+
+	return fmt.Sprintf("%s-%s@%s", localPart, timestamp, domain)
+}
+
+// GenerateGroupPathWithTimestamp 基于前缀生成符合 GitLab 要求的 group path
+// 格式：prefix-timestamp
+func GenerateGroupPathWithTimestamp(prefix string) string {
+	timestamp := GenerateTimestampSuffix()
+	path := fmt.Sprintf("%s-%s", prefix, timestamp)
+	// 确保符合 GitLab group path 规则：只能包含小写字母、数字、下划线、破折号
+	path = sanitizeGroupPath(path)
+	// 限制长度为 255
+	if len(path) > 255 {
+		path = path[:255]
+	}
+	return path
+}
+
+// GenerateProjectPathWithTimestamp 基于前缀生成符合 GitLab 要求的 project path
+// 格式：prefix-timestamp（项目 path 规则与组 path 相同）
+func GenerateProjectPathWithTimestamp(prefix string) string {
+	return GenerateGroupPathWithTimestamp(prefix)
+}
+
+// sanitizeUsername 清理 username，确保符合 GitLab 规则
+// 允许：字母、数字、下划线、点号、破折号
+func sanitizeUsername(username string) string {
+	// 移除不允许的字符
+	reg := regexp.MustCompile(`[^a-zA-Z0-9_.-]`)
+	username = reg.ReplaceAllString(username, "")
+
+	// 确保不以破折号或点号开头/结尾
+	username = strings.Trim(username, "-.")
+
+	return username
+}
+
+// sanitizeGroupPath 清理 group path，确保符合 GitLab 规则
+// 允许：小写字母、数字、下划线、破折号
+func sanitizeGroupPath(path string) string {
+	// 转换为小写
+	path = strings.ToLower(path)
+
+	// 移除不允许的字符
+	reg := regexp.MustCompile(`[^a-z0-9_-]`)
+	path = reg.ReplaceAllString(path, "")
+
+	// 确保不以破折号开头/结尾
+	path = strings.Trim(path, "-")
+
+	return path
+}

pkg/types/types.go

@@ -7,12 +7,13 @@ type UserConfig struct {
 
 // UserSpec 用户规格定义
 type UserSpec struct {
+	NameMode string      `yaml:"nameMode,omitempty"` // 命名模式: "prefix" (添加时间戳) 或 "name" (不添加时间戳)，默认为 "prefix"
 	Username string      `yaml:"username"`
 	Email    string      `yaml:"email"`
 	Name     string      `yaml:"name"`
 	Password string      `yaml:"password"`
-	Token    *TokenSpec  `yaml:"token"`    // Personal Access Token 配置
-	Groups   []GroupSpec `yaml:"groups"`   // 支持多个组
+	Token    *TokenSpec  `yaml:"token"`  // Personal Access Token 配置
+	Groups   []GroupSpec `yaml:"groups"` // 支持多个组
 }
 
 // TokenSpec Personal Access Token 规格定义
@@ -23,6 +24,7 @@ type TokenSpec struct {
 
 // GroupSpec 组规格定义
 type GroupSpec struct {
+	NameMode   string        `yaml:"nameMode,omitempty"` // 命名模式: "prefix" (添加时间戳) 或 "name" (不添加时间戳)，继承 UserSpec.NameMode
 	Name       string        `yaml:"name"`
 	Path       string        `yaml:"path"`
 	Visibility string        `yaml:"visibility"`
@@ -31,6 +33,7 @@ type GroupSpec struct {
 
 // ProjectSpec 项目规格定义
 type ProjectSpec struct {
+	NameMode    string `yaml:"nameMode,omitempty"` // 命名模式: "prefix" (添加时间戳) 或 "name" (不添加时间戳)，继承 GroupSpec.NameMode
 	Name        string `yaml:"name"`
 	Path        string `yaml:"path"`
 	Description string `yaml:"description"`