feat: Refactor AST generation routes workflow

- Introduced a comprehensive data model for route definitions, parameters, and validation rules.
- Established component interfaces for route parsing, comment parsing, import resolution, route building, validation, and rendering.
- Developed a detailed implementation plan outlining execution flow, user requirements, and compliance with design principles.
- Created a quickstart guide to assist users in utilizing the refactored system effectively.
- Conducted thorough research on existing architecture, identifying key improvements and establishing a refactoring strategy.
- Specified functional requirements and user scenarios to ensure clarity and testability.
- Generated a task list for implementation, emphasizing test-driven development and parallel execution where applicable.

pkg/ast/route/router.go.tpl

@@ -1,10 +1,14 @@
-// Code generated by the atomctl ; DO NOT EDIT.
+// Code generated by atomctl. DO NOT EDIT.
 
+// Package {{.PackageName}} provides HTTP route definitions and registration
+// for the {{.ProjectPackage}} application.
 package {{.PackageName}}
 
 import (
+{{- if .Imports }}
 {{- range .Imports }}
 	{{.}}
+{{- end }}
 {{- end }}
 	. "go.ipao.vip/atom/fen"
 	_ "go.ipao.vip/atom"
@@ -13,34 +17,58 @@ import (
 	log "github.com/sirupsen/logrus"
 )
 
+// Routes implements the HttpRoute contract and provides route registration
+// for all controllers in the {{.PackageName}} module.
+//
 // @provider contracts.HttpRoute atom.GroupRoutes
 type Routes struct {
 	log *log.Entry `inject:"false"`
+{{- if .Controllers }}
+	// Controller instances
 {{- range .Controllers }}
 	{{.}}
 {{- end }}
+{{- end }}
 }
 
+// Prepare initializes the routes provider with logging configuration.
 func (r *Routes) Prepare() error {
 	r.log = log.WithField("module", "routes.{{.PackageName}}")
+	r.log.Info("Initializing routes module")
 	return nil
 }
 
+// Name returns the unique identifier for this routes provider.
 func (r *Routes) Name() string {
 	return "{{.PackageName}}"
 }
 
+// Register registers all HTTP routes with the provided fiber router.
+// Each route is registered with its corresponding controller action and parameter bindings.
 func (r *Routes) Register(router fiber.Router) {
+{{- if .RouteGroups }}
 {{- range $key := .RouteGroups }}
-	// 注册路由组: {{$key}}
+	// Register routes for controller: {{$key}}
 	{{- $value := index $.Routes $key }}
+	{{- if $value }}
 	{{- range $value }}
+	{{- if .Route }}
+	r.log.Debugf("Registering route: {{.Method}} {{.Route}} -> {{.Controller}}.{{.Action}}")
 	router.{{.Method}}("{{.Route}}", {{.Func}}(
 		r.{{.Controller}}.{{.Action}},
-		{{- range .Params}}
+		{{- if .Params }}
+		{{- range .Params }}
 		{{.}},
 		{{- end }}
+		{{- end }}
 	))
-	{{ end }}
+	{{- end }}
+	{{- end }}
+	{{- end }}
 {{- end }}
+{{- else }}
+	r.log.Warn("No routes found to register")
+{{- end }}
+
+	r.log.Info("Successfully registered all routes")
 }