d4d005422d
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.
355 lines
10 KiB
Markdown
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
|