Example: LLM Multi-Provider Config Refactoring PRD

This PRD demonstrates the pattern for refactoring a single-config settings page into a multi-profile/multi-provider management system. Useful as a reference for similar settings refactoring tasks.

Key Design Patterns

1. Profile-based storage without new tables

Store multiple config profiles as a JSON array in existing key-value settings table. One key for the profiles array, one key for the active profile ID.

settings.active_profile_id  →  "prof_xxx"
settings.profiles           →  '[{...}, {...}]'

2. Protocol/behavior follows the item, not the group

When a group (provider) can contain items with different behaviors (protocols), put the behavior field on the item level, not the group level. This allows mixing.

3. Global defaults with optional per-profile overrides

Keep common parameters (temperature, timeout, etc.) at the global level. Profiles can optionally override, but empty = use global. This reduces config complexity.

4. Migration from old format

Detect old keys → convert to new JSON format → delete old keys. Make migration idempotent (INSERT OR IGNORE pattern).

5. Isolate backend changes

Refactor the config reader's return format to match what the caller expects. This way downstream consumers (LLM call layer, rate limiter) need zero changes.

PRD Structure for Settings Refactoring

Background: current state table + missing capabilities table
User stories focused on the switching/management pain point
ASCII wireframe of new UI layout
API design with JSON payload (not flat form fields for complex nested data)
Data model: JSON in existing table + migration script
Security & limits table
Architecture change diagram (before/after)
File change inventory with impact level (不动/小/中/大)
Decision record table
Risk table

Pitfalls Found During This Session

Don't make parameters per-profile by default — most users don't need it, adds UI complexity
Test connection endpoint should be AJAX, not form submit, for better UX
Migration must handle the case where both old and new keys exist (already migrated)

2.1 KiB Raw Permalink Blame History