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

355 lines
10 KiB
Markdown

# 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 ✅
```go
type WikiConfig struct {
Enabled bool
AutoIngest bool
SynthesisModelID string
WikiLanguage string
MaxPagesPerIngest int
}
```
**File:** `internal/types/wiki_page.go` (Lines 89-120)
#### KnowledgeBase Struct ✅
```go
type KnowledgeBase struct {
// ...
WikiConfig *WikiConfig `json:"wiki_config" gorm:"column:wiki_config;type:json"`
// ...
}
```
**File:** `internal/types/knowledgebase.go` (Line 76)
#### KnowledgeBaseConfig Struct ❌
```go
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)
```go
// 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)
```go
if config.WikiConfig != nil {
kb.WikiConfig = config.WikiConfig
}
```
### Change 3: Update Frontend Type Hints
**File:** `frontend/src/api/knowledge-base/index.ts` (In createKnowledgeBase)
```typescript
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