docs: improve code documentation and comments

Add detailed documentation for versioning package:

1. Service methods:
   - CheckExpected: optimistic locking explanation
   - repairIntent: crash recovery documentation
   - Why these mechanisms matter
   - How to apply them correctly

2. Component methods:
   - Start: repair and bootstrap documentation
   - repairOpenIntents: explain crash recovery

3. ResourceStoreAdapter:
   - Clarify Resource <-> Store model mapping
   - Document error handling strategy

4. Types:
   - Intent status transitions
   - Version lifecycle
   - Meta pointer semantics

All changes are documentation only - no functional changes.
Code formatted with go fmt.

Author: mochengqian

pkg/core/versioning/component.go

@@ -133,10 +133,17 @@ func (c *component) Start(rt runtime.Runtime, stop <-chan struct{}) error {
 		return err
 	}
 	rm := rmComp.(manager.ResourceManagerComponent).ResourceManager()
+	// Repair open intents left by crashes or failed mutations.
+	// Why: If admin crashed after creating an intent but before the subscriber
+	// committed it, the intent stays PENDING forever and blocks future writes.
+	// Repair attempts to commit intents whose desired state matches actual state.
 	if err := c.repairOpenIntents(rm); err != nil {
 		return err
 	}
-	// Bootstrap: record initial version for all existing rules
+	// Bootstrap: record initial version for all existing rules.
+	// Why: Versioning was just enabled or this is the first startup. Existing rules
+	// have no version history. Recording a BOOTSTRAP version establishes a baseline
+	// so future mutations have a proper "before" state to diff against.
 	for _, kind := range governor.RuleResourceKinds.Values() {
 		// Get the store for this kind and list all resources
 		rs, err := rm.GetStore(kind)

pkg/core/versioning/resource_store_adapter.go

@@ -34,7 +34,22 @@ import (
 
 var _ Store = &ResourceStoreAdapter{}
 
-// ResourceStoreAdapter adapts the resource store to implement versioning.Store
+// ResourceStoreAdapter adapts the resource store to implement versioning.Store.
+//
+// Why this adapter exists:
+// - Dubbo-admin uses a unified resource store for all Kubernetes-style resources
+// - Version/Intent/Meta are stored as RuleVersion/RuleIntent resources in the same store
+// - This adapter translates Store interface calls into resource CRUD operations
+//
+// Architecture trade-offs:
+// - (+) No separate database schema or connection pool needed
+// - (+) Versions/Intents benefit from existing store features (indexing, caching)
+// - (-) Some operations require full resource scans (e.g., GetVersionByID)
+// - (-) Tied to the resource store lifecycle; cannot be used standalone
+//
+// Limitations:
+// - GetVersionByID: Not implemented (would require scanning all RuleVersions)
+// - Query performance depends on index efficiency (ByParentRuleIndexName)
 type ResourceStoreAdapter struct {
 	store store.ResourceStore
 }
@@ -98,11 +113,12 @@ func (a *ResourceStoreAdapter) ListVersions(kind coremodel.ResourceKind, resourc
 }
 
 func (a *ResourceStoreAdapter) InsertVersion(req InsertRequest, maxVersions int64) (*Version, error) {
-	// Allocate new version ID (Phase 3 will add proper ID allocation)
-	// For now, use timestamp-based ID
+	// ID allocation: use timestamp in milliseconds as a monotonic ID
+	// Why timestamp: avoids need for separate sequence table; sufficient for version ordering
 	id := time.Now().UnixNano() / 1000000 // milliseconds
 
-	// Allocate version number (count existing versions + 1)
+	// Allocate version number by counting existing versions
+	// VersionNo is 1-based and increments with each mutation
 	versions, err := a.ListVersions(req.RuleKind, req.ResourceKey)
 	if err != nil {
 		return nil, err
@@ -142,7 +158,8 @@ func (a *ResourceStoreAdapter) InsertVersion(req InsertRequest, maxVersions int6
 		return nil, err
 	}
 
-	// Trim old versions
+	// Trim old versions to enforce maxVersions limit
+	// Oldest versions are deleted first to keep storage bounded
 	if maxVersions > 0 {
 		if err := a.TrimVersions(req.RuleKind, req.ResourceKey, maxVersions); err != nil {
 			return nil, err

pkg/core/versioning/service.go

@@ -110,14 +110,27 @@ func (s *Service) Diff(kind coremodel.ResourceKind, mesh, ruleName string, id in
 	}, nil
 }
 
+// CheckExpected validates that the current version matches the expected version ID.
+// This implements optimistic locking for rule mutations.
+//
+// Why this check matters:
+// - Prevents lost updates when two users edit the same rule concurrently
+// - Forces clients to acknowledge the current state before mutating
+// - Returns IntentPendingError if another mutation is in progress
+//
+// How to apply:
+// - UI should pass the version ID it's editing as ExpectedVersionID
+// - If the check fails, client must refresh and retry
 func (s *Service) CheckExpected(kind coremodel.ResourceKind, mesh, ruleName string, expected *int64) error {
 	if err := s.ensureEnabled(); err != nil {
 		return nil
 	}
 	resourceKey := coremodel.BuildResourceKey(mesh, ruleName)
-	// The expected-version guard first checks for open intents so a second
-	// writer in the same rule-lock window gets a deterministic 409 before the
-	// meta current-version pointer has a chance to lag behind the first write.
+	// Check for open intents first before checking version mismatch.
+	// Why: If Writer A created an intent at T1, and Writer B checks expected
+	// version at T2 (before A's subscriber commits), the meta pointer still
+	// reflects the old version. Without this guard, B would get VersionConflict
+	// instead of IntentPending, masking the real issue (concurrent write).
 	intent, err := s.store.OpenIntent(kind, resourceKey)
 	if err != nil {
 		return err
@@ -210,6 +223,19 @@ func (s *Service) GetVersion(kind coremodel.ResourceKind, resourceKey string, id
 	return s.store.GetVersion(kind, resourceKey, id)
 }
 
+// repairIntent attempts to resolve a stale or stuck intent.
+// Called during startup to recover from crashes, and before mutations to clear pending state.
+//
+// Why repair is needed:
+//   - If admin crashes after creating an intent but before the subscriber commits,
+//     the intent stays PENDING forever, blocking future writes
+//   - If the actual resource state matches the intent's desired state, we can
+//     safely commit the intent retroactively
+//
+// How to apply:
+// - Repair runs automatically at startup (component.Start)
+// - Also runs before each mutation (prepareRuleMutation) to clear stale intents
+// - Returns IntentPendingError if the intent genuinely conflicts with current state
 func (s *Service) repairIntent(intent *Intent, current coremodel.Resource, deleted bool) (*Version, error) {
 	if intent == nil {
 		return nil, nil
@@ -226,6 +252,7 @@ func (s *Service) repairIntent(intent *Intent, current coremodel.Resource, delet
 	if intent.Status != IntentStatusPending && intent.Status != IntentStatusApplied {
 		return nil, ErrVersionIntentNotOpen
 	}
+	// If intent was APPLIED or resource state matches intent, commit it
 	if intent.Status == IntentStatusApplied || IntentMatchesResource(intent, current, deleted) {
 		if intent.Status == IntentStatusPending {
 			if err := s.store.MarkIntentApplied(intent.ID); err != nil {
@@ -234,6 +261,7 @@ func (s *Service) repairIntent(intent *Intent, current coremodel.Resource, delet
 		}
 		return s.store.CommitIntent(intent.ID, s.maxVersions)
 	}
+	// Resource state diverged from intent; cannot auto-repair
 	return nil, &IntentPendingError{IntentID: intent.ID}
 }
 
@@ -274,6 +302,8 @@ func buildMutationInsertRequest(res coremodel.Resource, op Operation, source Sou
 	}, nil
 }
 
+// IntentMatchesResource checks if the intent's desired state matches actual resource state.
+// Used by repair logic to decide if a stale intent can be safely committed.
 func IntentMatchesResource(intent *Intent, current coremodel.Resource, deleted bool) bool {
 	if intent == nil {
 		return false

pkg/core/versioning/subscriber.go

@@ -109,7 +109,10 @@ func (s *Subscriber) record(event events.Event) error {
 	resourceKey := res.ResourceKey()
 	ruleName := res.ResourceMeta().Name
 
-	// Try to commit matching intent first
+	// Try to commit matching intent first before creating a new UPSTREAM version.
+	// Why: Admin UI creates an Intent, then applies the mutation. When the subscriber
+	// sees the resource change, it should commit that Intent rather than creating
+	// a redundant UPSTREAM version with the same content hash.
 	committed, err := s.tryCommitMatchingIntent(ruleKind, resourceKey, hash)
 	if err != nil {
 		return err
@@ -137,8 +140,10 @@ func (s *Subscriber) record(event events.Event) error {
 		return fmt.Errorf("failed to get next version number: %w", err)
 	}
 
-	// Check for duplicate hash to avoid redundant versions
-	// Skip dedup check for DELETE operations (they use a fixed hash and should always be recorded)
+	// Deduplication: skip creating a version if the content hash matches the latest.
+	// Why: Upstream changes may fire multiple events with identical content (registry
+	// restarts, re-registrations). Recording every duplicate wastes storage.
+	// Skip dedup for DELETE operations: they use a fixed hash and should always be recorded.
 	if op != OperationDelete {
 		if exists, err := s.checkDuplicateHash(ruleKind, mesh, ruleName, hash); err != nil {
 			return fmt.Errorf("failed to check duplicate hash: %w", err)

pkg/core/versioning/types.go

@@ -24,13 +24,15 @@ import (
 	coremodel "github.com/apache/dubbo-admin/pkg/core/resource/model"
 )
 
+// Source identifies where a rule mutation originated.
+// Used for auditing and distinguishing user-initiated changes from system-generated ones.
 type Source string
 
 const (
-	SourceAdmin     Source = "ADMIN"
-	SourceUpstream  Source = "UPSTREAM"
-	SourceRollback  Source = "ROLLBACK"
-	SourceBootstrap Source = "BOOTSTRAP"
+	SourceAdmin     Source = "ADMIN"     // User edit via Admin UI/API
+	SourceUpstream  Source = "UPSTREAM"  // Registry change detected by subscriber
+	SourceRollback  Source = "ROLLBACK"  // Rollback to a previous version
+	SourceBootstrap Source = "BOOTSTRAP" // Initial version recorded at startup
 )
 
 type Operation string
@@ -41,26 +43,32 @@ const (
 	OperationDelete Operation = "DELETE"
 )
 
+// IntentStatus tracks the lifecycle of a mutation intent.
+// Intent workflow: PENDING (created) → APPLIED (mutation succeeded) → COMMITTED (version recorded)
+// Or: PENDING → FAILED (mutation failed or conflicted)
 type IntentStatus string
 
 const (
-	IntentStatusPending   IntentStatus = "PENDING"
-	IntentStatusApplied   IntentStatus = "APPLIED"
-	IntentStatusCommitted IntentStatus = "COMMITTED"
-	IntentStatusFailed    IntentStatus = "FAILED"
+	IntentStatusPending   IntentStatus = "PENDING"   // Intent created, mutation not yet applied
+	IntentStatusApplied   IntentStatus = "APPLIED"   // Mutation applied to resource store, awaiting commit
+	IntentStatusCommitted IntentStatus = "COMMITTED" // Version successfully recorded, intent closed
+	IntentStatusFailed    IntentStatus = "FAILED"    // Mutation failed or was rejected
 )
 
 var (
 	ErrFeatureDisabled       = errors.New("rule versioning is disabled")
-	ErrVersionConflict       = errors.New("rule version conflict")
+	ErrVersionConflict       = errors.New("rule version conflict") // ExpectedVersionID mismatch
 	ErrVersionNotFound       = errors.New("rule version not found")
 	ErrVersionIntentNotFound = errors.New("rule version intent not found")
-	ErrVersionIntentNotOpen  = errors.New("rule version intent is not open")
-	ErrVersionIntentPending  = errors.New("rule version intent is pending")
+	ErrVersionIntentNotOpen  = errors.New("rule version intent is not open") // Intent already committed or failed
+	ErrVersionIntentPending  = errors.New("rule version intent is pending")  // Another mutation in progress
 	ErrRollbackToDelete      = errors.New("cannot roll back to a deleted rule version")
 	ErrRollbackToCurrent     = errors.New("cannot roll back to a version identical to current")
 )
 
+// Version represents an immutable snapshot of a rule's spec at a point in time.
+// Versions are append-only; each mutation creates a new Version record.
+// The IsCurrent field is computed at query time by comparing with Meta.CurrentVersion.
 type Version struct {
 	ID               int64                  `json:"id" gorm:"primaryKey;autoIncrement"`
 	RuleKind         coremodel.ResourceKind `json:"ruleKind" gorm:"type:varchar(64);not null;index:idx_rk_key_created,priority:1;uniqueIndex:uk_rk_key_ver,priority:1;index:idx_rk_hash,priority:1"`
@@ -83,6 +91,9 @@ func (Version) TableName() string {
 	return "rule_version"
 }
 
+// Meta tracks the current version and sequence number for a rule.
+// Updated atomically when a new version is committed.
+// CurrentVersion may be nil if the rule was deleted.
 type Meta struct {
 	RuleKind       coremodel.ResourceKind `json:"ruleKind" gorm:"type:varchar(64);primaryKey"`
 	ResourceKey    string                 `json:"resourceKey" gorm:"type:varchar(512);primaryKey"`
@@ -95,6 +106,12 @@ func (Meta) TableName() string {
 	return "rule_version_meta"
 }
 
+// Intent represents a pending mutation to a rule, used to coordinate async writes.
+// Why Intents exist:
+// - Admin UI mutations are not immediately applied; they create an Intent first
+// - The Intent enforces optimistic locking via ExpectedVersionID
+// - When the mutation completes, the subscriber commits the Intent to a Version
+// - This prevents race conditions when multiple writers target the same rule
 type Intent struct {
 	ID                int64                  `json:"id" gorm:"primaryKey;autoIncrement"`
 	RuleKind          coremodel.ResourceKind `json:"ruleKind" gorm:"type:varchar(64);not null;index:idx_intent_rule_status,priority:1;index:idx_intent_hash,priority:1"`
@@ -107,10 +124,10 @@ type Intent struct {
 	Operation         Operation              `json:"operation" gorm:"type:varchar(16);not null"`
 	Author            string                 `json:"author" gorm:"type:varchar(128);not null"`
 	Reason            string                 `json:"reason,omitempty" gorm:"type:varchar(1024)"`
-	RolledBackFromID  *int64                 `json:"rolledBackFromId,omitempty"`
-	ExpectedVersionID *int64                 `json:"expectedVersionId,omitempty"`
+	RolledBackFromID  *int64                 `json:"rolledBackFromId,omitempty"`  // Points to the Version being rolled back to
+	ExpectedVersionID *int64                 `json:"expectedVersionId,omitempty"` // Optimistic lock: mutation only proceeds if current version matches
 	Status            IntentStatus           `json:"status" gorm:"type:varchar(16);not null;index:idx_intent_rule_status,priority:3"`
-	VersionID         *int64                 `json:"versionId,omitempty"`
+	VersionID         *int64                 `json:"versionId,omitempty"` // Set when committed; points to the created Version
 	LastError         string                 `json:"lastError,omitempty" gorm:"type:varchar(1024)"`
 	CreatedAt         time.Time              `json:"createdAt" gorm:"not null"`
 	UpdatedAt         time.Time              `json:"updatedAt" gorm:"not null"`