Files
Enterprise-Knowledge-Base/WIKI_CONFIG_TRACE_SUMMARY.md
T
wizardchen d4d005422d feat: Implement wiki_config updates in knowledge base management
Added functionality to enable updates for the `wiki_config` field in the `KnowledgeBaseConfig` struct. This includes:

1. **Type Definition Update**: Added `WikiConfig` field to `KnowledgeBaseConfig` to allow JSON unmarshaling during update requests.
2. **Service Layer Enhancement**: Updated the `UpdateKnowledgeBase` method to persist changes to `wiki_config` when provided in the request.
3. **Frontend TypeScript Adjustments**: Enhanced type definitions in the frontend to support `wiki_config`, improving IDE autocomplete and type checking.

This fix addresses the critical issue where `wiki_config` was not being updated due to its absence in the `KnowledgeBaseConfig` struct, ensuring proper handling of wiki configurations during knowledge base updates.
2026-04-22 21:17:21 +08:00

10 KiB

Wiki Config Flow - Trace Summary

📋 Executive Summary

I've completed a comprehensive trace of how wiki_config flows from the frontend through the backend to the database in the WeKnora codebase.

Key Finding: ❌ Wiki config UPDATE is broken - can only be set during creation, not updated afterward.


🎯 Three Documents Generated

1. WIKI_CONFIG_FLOW_ANALYSIS.md (16 KB)

Comprehensive technical analysis with all file paths, struct definitions, and code snippets.

Sections:

  • Database layer (SQL migration)
  • Type definitions (WikiConfig, KnowledgeBase, KnowledgeBaseConfig)
  • Handler layer (create vs update)
  • Service layer implementation
  • Repository layer
  • Frontend API
  • Flow diagrams (works vs broken)
  • Required fixes with code examples
  • Summary table

Best for: Full understanding of the system architecture

2. WIKI_CONFIG_QUICK_REFERENCE.md (5.3 KB)

Quick lookup guide for developers implementing the fix.

Sections:

  • Critical finding summary
  • Why it's broken (struct diagram)
  • Files that need changes
  • Database path info
  • Request/response flows
  • Handler/Service code locations
  • Frontend integration
  • Test cases

Best for: Quick reference during implementation

3. WIKI_CONFIG_FIX.md (8.5 KB)

Complete implementation guide with exact code changes.

Sections:

  • Problem statement
  • Change 1: Type definition (code diff)
  • Change 2: Service layer (code diff)
  • Change 3: Frontend types (code diff)
  • Testing procedures (curl examples)
  • Verification checklist
  • Code review checklist
  • Rollback plan
  • Impact analysis

Best for: Actually implementing the fix


🔍 Findings at a Glance

Database Layer ✅

CREATE TABLE knowledge_bases (
    ...
    wiki_config JSONB  ← EXISTS and properly typed
)

File: migrations/versioned/000032_wiki_pages.up.sql (Line 7)

Type Definitions

WikiConfig Struct ✅

type WikiConfig struct {
    Enabled           bool
    AutoIngest        bool
    SynthesisModelID  string
    WikiLanguage      string
    MaxPagesPerIngest int
}

File: internal/types/wiki_page.go (Lines 89-120)

KnowledgeBase Struct ✅

type KnowledgeBase struct {
    // ...
    WikiConfig *WikiConfig `json:"wiki_config" gorm:"column:wiki_config;type:json"`
    // ...
}

File: internal/types/knowledgebase.go (Line 76)

KnowledgeBaseConfig Struct ❌

type KnowledgeBaseConfig struct {
    ChunkingConfig        ChunkingConfig
    ImageProcessingConfig ImageProcessingConfig
    FAQConfig            *FAQConfig
    // ❌ MISSING: WikiConfig *WikiConfig
}

File: internal/types/knowledgebase.go (Lines 99-107)

This is the root cause!

Handler Layer

CreateKnowledgeBase ✅

  • File: internal/handler/knowledgebase.go (Lines 114-147)
  • Accepts full types.KnowledgeBase struct
  • wiki_config can be sent: { name, wiki_config: {...} }
  • Status: Works perfectly

UpdateKnowledgeBase ❌

  • File: internal/handler/knowledgebase.go (Lines 446-488)
  • Accepts UpdateKnowledgeBaseRequest with Config: KnowledgeBaseConfig
  • wiki_config in request: { name, config: { wiki_config: {...} } }
  • Problem: KnowledgeBaseConfig doesn't have WikiConfig field
  • Status: Silently ignores wiki_config

Service Layer

CreateKnowledgeBase ✅

  • File: internal/application/service/knowledgebase.go (Lines 73-98)
  • Receives full KnowledgeBase
  • Calls EnsureDefaults() which validates wiki_config
  • Status: Works

UpdateKnowledgeBase ❌

  • File: internal/application/service/knowledgebase.go (Lines 265-311)
  • Receives config *KnowledgeBaseConfig
  • No code to update kb.WikiConfig
  • Status: Cannot persist updates

Repository Layer ✅

  • File: internal/application/repository/knowledgebase.go
  • CreateKnowledgeBase(): Line 26 - Uses GORM.Create()
  • UpdateKnowledgeBase(): Line 116 - Uses GORM.Save()
  • Status: Both correctly handle wiki_config if it's set

Frontend API ⚠️

  • File: frontend/src/api/knowledge-base/index.ts
  • createKnowledgeBase(): Lines 11-33 - accepts any data ✅
  • updateKnowledgeBase(): Lines 42-44 - accepts any config ✅
  • Issue: Type hints don't include wiki_config (but data is sent)

🔄 Flow Diagram

✅ CREATION FLOW (Works)

Frontend sends:
  POST /api/v1/knowledge-bases
  { name, type, wiki_config: {...} }
  
  ↓
Handler: CreateKnowledgeBase
  Parses as types.KnowledgeBase ✅
  
  ↓
Service: CreateKnowledgeBase
  Receives KB with wiki_config ✅
  Calls EnsureDefaults() ✅
  
  ↓
Repository: CreateKnowledgeBase
  GORM.Create(kb) serializes all fields ✅
  
  ↓
Database: wiki_config column populated ✅

❌ UPDATE FLOW (Broken)

Frontend sends:
  PUT /api/v1/knowledge-bases/{id}
  { name, config: { wiki_config: {...} } }
  
  ↓
Handler: UpdateKnowledgeBase
  Parses as UpdateKnowledgeBaseRequest ❌
  Config is KnowledgeBaseConfig (no WikiConfig!) ❌
  
  ↓
JSON Unmarshaling:
  wiki_config field ignored ❌
  
  ↓
Service: UpdateKnowledgeBase
  Receives config without wiki_config ❌
  Never updates kb.WikiConfig ❌
  
  ↓
Repository: UpdateKnowledgeBase
  GORM.Save(kb) persists OLD wiki_config ❌
  
  ↓
Database: wiki_config NOT updated ❌

🛠️ The Fix (3 Changes)

Change 1: Add WikiConfig to KnowledgeBaseConfig

File: internal/types/knowledgebase.go (After line 106)

// Wiki configuration (for document type knowledge bases with wiki feature enabled)
WikiConfig *WikiConfig `yaml:"wiki_config" json:"wiki_config"`

Change 2: Update Service to Persist WikiConfig

File: internal/application/service/knowledgebase.go (After line 296)

if config.WikiConfig != nil {
    kb.WikiConfig = config.WikiConfig
}

Change 3: Update Frontend Type Hints

File: frontend/src/api/knowledge-base/index.ts (In createKnowledgeBase)

wiki_config?: {
  enabled: boolean;
  auto_ingest?: boolean;
  synthesis_model_id?: string;
  wiki_language?: string;
  max_pages_per_ingest?: number;
};

📊 Component Status Matrix

Component File Lines Current Status Issue
Database Column 000032_wiki_pages.up.sql 7 ✅ Exists None
WikiConfig Type wiki_page.go 89-120 ✅ Defined None
KnowledgeBase Field knowledgebase.go 76 ✅ Has field None
KnowledgeBaseConfig Field knowledgebase.go 99-107 ❌ Missing ROOT CAUSE
CreateKB Handler knowledgebase.go 114-147 ✅ Works None
UpdateKB Handler knowledgebase.go 446-488 ⚠️ Limited Uses KnowledgeBaseConfig
CreateKB Service knowledgebase.go 73-98 ✅ Works None
UpdateKB Service knowledgebase.go 265-311 ❌ Broken No WikiConfig update
Repository repository/knowledgebase.go 26-118 ✅ Works None
Frontend API api/knowledge-base/index.ts Various ⚠️ Partial Missing types

🧪 Test Verification

Before Fix

  • ✅ Create KB with wiki_config → Works
  • ❌ Update wiki_config → Fails (not persisted)
  • ❌ Fetch KB after update → Old value still there

After Fix

  • ✅ Create KB with wiki_config → Works
  • ✅ Update wiki_config → Works
  • ✅ Fetch KB after update → New value correctly persisted

📁 Document Files Location

All documents saved in WeKnora root:

/Users/wizard/code/go/src/git.woa.com/wxg-prc/WeKnora/
├── WIKI_CONFIG_TRACE_SUMMARY.md          ← You are here
├── WIKI_CONFIG_FLOW_ANALYSIS.md          ← Full technical analysis
├── WIKI_CONFIG_QUICK_REFERENCE.md        ← Developer quick reference
└── WIKI_CONFIG_FIX.md                    ← Implementation guide

🎓 Key Learnings

Architecture Pattern

WeKnora uses a layered architecture:

  1. Frontend API - TypeScript functions that call HTTP endpoints
  2. Handler Layer - Gin HTTP handlers that parse requests
  3. Service Layer - Business logic
  4. Repository Layer - Database operations using GORM
  5. Database - PostgreSQL with JSON columns

Request Structure Design

  • Creation: Uses full struct (KnowledgeBase) - more flexible
  • Update: Uses limited struct (KnowledgeBaseConfig) - more controlled
  • Issue: Limited struct was too limited for wiki_config

GORM Behavior

  • GORM automatically serializes/deserializes JSON fields using Value() and Scan() methods
  • All config structs implement these interfaces
  • The repository layer is "dumb" - it trusts what the service gives it

✨ Recommendations

  1. Implement the fix immediately - Very low risk, high impact
  2. Add integration tests - Test both creation and update flows
  3. Update API documentation - Document wiki_config in API docs
  4. Consider using base struct for all config updates - Currently inconsistent between handlers

📞 Questions Answered

1. How does wiki_config get saved during KB creation?

Via full KnowledgeBase struct → Service → Repository → GORM.Create()

2. How does it get updated after creation?

It doesn't - that's the bug! KnowledgeBaseConfig is missing the field.

3. Where is it stored in the database?

knowledge_bases.wiki_config JSONB column

4. What struct definitions are involved?

  • WikiConfig (source)
  • KnowledgeBase (has WikiConfig field)
  • KnowledgeBaseConfig (missing WikiConfig field - THE BUG)

5. What's the exact code path from frontend to database?

  • Frontend sends HTTP request
  • Handler parses request into struct
  • Service updates the struct
  • Repository calls GORM.Save()
  • GORM serializes struct to SQL using Value() method
  • Database receives JSON in wiki_config column

6. How to fix it?

Add WikiConfig field to KnowledgeBaseConfig + update service layer (2 code changes)


📝 Next Steps

  1. Review the three generated documents
  2. Implement the changes using WIKI_CONFIG_FIX.md
  3. Test using the provided test cases
  4. Deploy and verify in production

Generated: April 7, 2026 Analysis Depth: Complete code trace with exact file locations and line numbers