xianwen-system-impl

name	xianwen-system-impl
description	Implement game systems for Xianwen Online from design docs (docs/redesign/). Covers sect, combat, technique, alchemy, equipment, inventory, world boss, breed/talent systems. Use when implementing new features or fulfilling TODO items from design documents.

Xianwen Game System Implementation

TODO-driven implementation workflow for game systems, extracted from major development sessions.

Design Document Location

All system designs are in docs/redesign/:

System	Design Doc	Backend Service	Frontend Store
Condition (體況/心境)	condition-system-redesign.md	condition_service.rs	condition.ts
Combat (戰鬥)	combat-system-redesign.md	combat_service.rs	combat.ts
Technique (功法/道途)	technique-system-redesign.md	technique_service.rs	technique.ts
Sect (宗門)	sect-system-redesign.md	sect_service.rs	sect.ts
Equipment (裝備)	equipment-system-redesign.md	equipment_service.rs	equipment.ts
Alchemy (煉丹)	alchemy-system-redesign.md	alchemy_service.rs	alchemy.ts
Inventory (背包)	inventory-system-redesign.md	inventory_service.rs	inventory.ts
World Boss	world-boss-redesign.md	world_boss_service.rs	worldBoss.ts
Breed/Talent (品種天賦)	breed-talent-redesign.md	breed_service.rs	breed.ts

Implementation Workflow

Phase 1: Planning

1. Read the design document thoroughly
2. Create a TODO file tracking each implementation item
3. Identify dependencies between systems
4. Break into phases (backend first, then frontend)

Phase 2: Backend Implementation

1. Database migration — Create migration in server/migrations/
2. Models — Define in server/src/models/
3. Repository — Data access in server/src/db/
4. Service — Business logic in server/src/services/
5. Handler — API endpoints in server/src/handlers/
6. WebSocket messages — Real-time events in server/src/ws/

Phase 3: Frontend Implementation

1. Types — TypeScript types in web-client/src/types/
2. Store — Pinia store in web-client/src/stores/
3. API integration — WebSocket/REST calls
4. Components — Vue components in web-client/src/components/
5. HUD integration — Add buttons/entries to the game HUD

Phase 4: Verification

1. cargo check && cargo clippy — No backend errors
2. pnpm run build:web — No frontend type errors
3. Manual testing of the complete flow
4. Update the TODO file marking completed items

Critical Design Decisions

These decisions were made across sessions and MUST be followed:

• No AP system — Replaced by body_condition + mental_condition dual axis
• No player-created sects — Only pre-defined sects (青雲宗, 血煞宗, 天機閣, etc.)
• Dao paths (道途) must be in Chinese — Not English keys
• Intent engine drives gameplay — Player types natural language, server parses intent
• NPC faction boundaries — Righteous NPCs should not wander into demonic territory
• Boss fights should use full combat UI — Not simple click-to-attack

File Size Guidelines

• Services: Keep under 800 lines, split by domain if needed
• Components: Keep under 400 lines, extract sub-components
• game.rs was split into domain-specific files (combat.rs, movement.rs, chat.rs)

Common Pitfalls

Issue	Solution
New columns missing in production	Always create migration, deploy server first
Frontend types out of sync	Regenerate types from backend models
Quest/task not triggerable	Register in intent engine patterns
New feature has no UI entry point	Add HUD button and/or dialog trigger
Existing player data incompatible	Write data migration SQL for existing players