go_blog/.claude/plans/nav_links_management.md

# Navigation Links Management - Implementation Plan

## Overview
Add a navigation links management feature that allows admins to configure custom links in the header navigation, with support for controlling whether links open in new windows.

## Requirements Analysis
Based on exploration:
- User wants to add additional URLs next to "Home" in the header navigation
- Backend admin interface to manage these URLs
- Control over whether links open in new windows (target="_blank")
- The site uses a multi-language system (zh/en)

## Current Architecture Patterns

### Database Models
- Models are in `/models/` directory
- Settings tables follow singleton pattern (ID=1) like `SiteSetting`, `CommentConfig`
- Support for multi-language via `*Zh` and `*En` fields
- Use GORM with auto-migration in `models/db.go`
- Config cache system exists (`models/config_cache.go`, `models.LoadConfigCache()`, `models.RefreshConfigCache()`)

### Handlers
- Settings handlers in `handlers/settings.go`
- Pattern: `{Feature}SettingsPage()` for GET, `{Feature}SettingsSave()` for POST
- Uses `DefaultData(c)` helper for common template data
- Multi-action POST pattern with `action` form field (see upload/download settings)
- Session-based user ID tracking via `userIDFromSession()`

### Templates
- Admin templates in `templates/admin/`
- Settings pages follow consistent UI pattern (tabs, success messages)
- Header navigation in `templates/layouts/base.html` (lines 24-89)
- Current navigation shows: Logo/Title, Home link, Login/User dropdown

### Routing
- Admin routes under `/admin` group with auth + admin middleware
- Settings routes: `/admin/settings/site`, `/admin/settings/upload`, etc.

### i18n
- Translation keys in `i18n/i18n.go`
- Follows pattern: `"feature_field_lang"` or `"feature_action"`
- Both EN and ZH translations required

## Proposed Implementation

### 1. Database Model: `NavLink`
Create `models/nav_link.go`:
```go
type NavLink struct {
    ID        uint      `gorm:"primarykey"`
    TitleZh   string    `gorm:"size:100;not null"`     // Link text (Chinese)
    TitleEn   string    `gorm:"size:100;not null"`     // Link text (English)
    URL       string    `gorm:"size:512;not null"`     // Target URL
    OpenNew   bool      `gorm:"default:false"`         // Open in new window
    Enabled   bool      `gorm:"default:true"`          // Show/hide link
    Sort      int       `gorm:"default:0;index"`       // Display order
    CreatedAt time.Time
    UpdatedAt time.Time
    UpdatedBy uint      `gorm:"index"`
}

// Helper methods
func (n *NavLink) Title(lang string) string {
    // Return title for language with fallback
}
```

### 2. Database Migration
Add to `models/db.go` `AutoMigrate()`:
- Add `&NavLink{}` to the migration list

### 3. Config Cache Integration
Update `models/config_cache.go`:
- Add `NavLinks []NavLink` field to cache struct
- Load nav links in `LoadConfigCache()`
- Make available to all handlers via middleware

### 4. Backend Handler
Add to `handlers/settings.go`:

```go
// NavLinksSettingsPage - render nav links management page
func NavLinksSettingsPage(db *gorm.DB) gin.HandlerFunc

// NavLinksSettingsSave - handle actions: add, toggle, delete, reorder
func NavLinksSettingsSave(db *gorm.DB) gin.HandlerFunc

// Helper functions:
// - addNavLink()
// - toggleNavLink()
// - deleteNavLink()
// - reorderNavLink()
```

Actions via POST form field:
- `action=add` - create new link
- `action=toggle` - enable/disable link
- `action=delete` - remove link
- `action=edit` - update link details

### 5. Admin Template
Create `templates/admin/settings_navlinks.html`:
- Settings page with tab navigation matching existing pattern
- Form to add new links (Title ZH/EN, URL, Open in new window checkbox)
- List of existing links with:
  - Enable/disable toggle
  - Edit inline or modal
  - Delete button
  - Sort order controls (up/down arrows or drag)
- Success message display
- Consistent styling with other settings pages

### 6. Frontend Template Updates
Update `templates/layouts/base.html`:
- Modify navigation section (around line 36-42) to render nav links
- Loop through cached nav links after "Home" link
- Apply language-specific titles
- Add `target="_blank"` when `OpenNew` is true
- Maintain consistent styling with existing nav items

### 7. Routing
Add to `main.go` settings group (around line 110-121):
```go
settings.GET("/navlinks", handlers.NavLinksSettingsPage(db))
settings.POST("/navlinks", handlers.NavLinksSettingsSave(db))
```

### 8. i18n Translations
Add to `i18n/i18n.go` for both EN and ZH:
```
"settings_navlinks_title": "Navigation Links"
"settings_navlinks_desc": "Manage custom links in the header navigation"
"navlinks_add": "Add Link"
"navlinks_title_zh": "Link Text (Chinese)"
"navlinks_title_en": "Link Text (English)"
"navlinks_url": "URL"
"navlinks_open_new": "Open in new window"
"navlinks_enabled": "Enabled"
"navlinks_edit": "Edit"
"navlinks_delete": "Delete"
"navlinks_confirm_delete": "Are you sure you want to delete this link?"
"navlinks_no_links": "No navigation links configured yet."
```

## Implementation Order

1. **Create database model** (`models/nav_link.go`)
2. **Update database migration** (`models/db.go`)
3. **Update config cache** (`models/config_cache.go`)
4. **Add i18n translations** (`i18n/i18n.go`)
5. **Create backend handlers** (`handlers/settings.go`)
6. **Create admin template** (`templates/admin/settings_navlinks.html`)
7. **Update frontend header** (`templates/layouts/base.html`)
8. **Add routes** (`main.go`)
9. **Test the feature**

## Design Decisions

### Why not singleton table?
- Multiple nav links needed (vs single config)
- Better suited for a regular table with multiple rows
- Easier to add/remove/reorder individual links

### Sort order implementation
- Use integer `Sort` field
- Lower numbers appear first
- Admin can adjust via up/down buttons or explicit number input

### Cache integration
- Nav links loaded into cache at startup and on refresh
- Avoids DB query on every page load
- Consistent with existing upload/comment config pattern

### Open in new window
- Boolean field `OpenNew`
- Renders as `target="_blank" rel="noopener noreferrer"` when true
- Security: always include `rel="noopener noreferrer"` with `target="_blank"`

## Testing Checklist

- [ ] Create new nav link via admin
- [ ] Nav link appears in header navigation
- [ ] Correct language displayed based on user preference
- [ ] "Open in new window" works correctly
- [ ] Enable/disable toggle works
- [ ] Delete link works
- [ ] Sort order affects display order
- [ ] Links render correctly for logged-in and anonymous users
- [ ] Multiple links display properly
- [ ] External and internal URLs both work
- [ ] Mobile responsive layout maintained