first commit

software-development/prd-writing/references/example-settings-refactor-prd.md

@@ -0,0 +1,44 @@
+# 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
+
+1. Background: current state table + missing capabilities table
+2. User stories focused on the switching/management pain point
+3. ASCII wireframe of new UI layout
+4. API design with JSON payload (not flat form fields for complex nested data)
+5. Data model: JSON in existing table + migration script
+6. Security & limits table
+7. Architecture change diagram (before/after)
+8. File change inventory with impact level (不动/小/中/大)
+9. Decision record table
+10. 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)