frontend-development

前端开发规范

项目架构和设计原则

技术栈和架构

• 核心技术: 原生HTML/CSS/JavaScript (零框架依赖)
• 设计理念: 平台独立、响应式、性能优先
• 支持平台: 桌面端 + 移动端双平台

命名约定

• JavaScript: 驼峰命名法 (camelCase)
• CSS: BEM命名规范或基础类+修饰符模式
• HTML: 语义化标签，kebab-case属性
• 文件命名: 小写字母加连字符，描述性命名

开发原则

• 组件化: 模块化的JavaScript类和CSS组件
• 响应式: 移动端优先的设计
• 性能优化: 懒加载、缓存、最小化DOM操作
• 可访问性: 语义化HTML，键盘导航支持

JavaScript开发模式

应用架构模式

// DetectiveGameApp类 - 主应用架构
class DetectiveGameApp {
    constructor() {
        this.sessionId = null;
        this.gameState = {
            phase: 'case-selection',
            selectedCase: null,
            selectedCharacter: null,
            evidenceFound: [],
            conversationHistory: {},
            rounds: 0
        };
        this.apiHelper = new APIHelper();
        this.themeManager = new ThemeManager();
        this.initializeApp();
    }

    // 状态管理
    updateGameState(newState) {
        this.gameState = { ...this.gameState, ...newState };
        this.saveGameState();
        this.updateUI();
        this.emitStateChange();
    }

    // 屏幕切换管理
    showScreen(screenName) {
        document.querySelectorAll('.screen').forEach(screen => {
            screen.style.display = 'none';
        });
        document.getElementById(screenName).style.display = 'block';
        this.gameState.currentScreen = screenName;
    }

    // 事件系统
    emitStateChange() {
        window.dispatchEvent(new CustomEvent('gameStateChanged', {
            detail: this.gameState
        }));
    }
}

工具类架构

// API工具类
class APIHelper {
    constructor() {
        this.baseURL = '/api';
        this.defaultHeaders = {
            'Content-Type': 'application/json'
        };
    }

    async makeRequest(endpoint, data, options = {}) {
        try {
            const response = await fetch(`${this.baseURL}${endpoint}`, {
                method: 'POST',
                headers: this.defaultHeaders,
                body: JSON.stringify(data),
                ...options
            });
            
            if (!response.ok) {
                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
            }
            
            const result = await response.json();
            if (!result.success) {
                throw new Error(result.error || '请求失败');
            }
            
            return result.data;
        } catch (error) {
            console.error('API请求失败:', error);
            throw error;
        }
    }

    // 流式响应处理
    async handleStreamResponse(url, data, onChunk, onComplete) {
        try {
            const response = await fetch(url, {
                method: 'POST',
                headers: this.defaultHeaders,
                body: JSON.stringify(data)
            });
            
            if (!response.ok) {
                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
            }
            
            const reader = response.body.getReader();
            const decoder = new TextDecoder();
            
            while (true) {
                const { done, value } = await reader.read();
                if (done) break;
                
                const chunk = decoder.decode(value);
                const lines = chunk.split('\n');
                
                for (const line of lines) {
                    if (line.startsWith('data: ')) {
                        try {
                            const data = JSON.parse(line.slice(6));
                            if (data.type === 'chunk') {
                                onChunk(data.content);
                            } else if (data.type === 'complete') {
                                onComplete();
                                return;
                            }
                        } catch (e) {
                            console.warn('解析流数据失败:', e);
                        }
                    }
                }
            }
        } catch (error) {
            console.error('流式请求失败:', error);
            throw error;
        }
    }
}

// 主题管理系统
class ThemeManager {
    constructor() {
        this.currentTheme = localStorage.getItem('theme') || 'default';
        this.themes = {};
        this.init();
    }

    async init() {
        await this.loadThemes();
        this.applyStoredTheme();
        this.setupThemeSelector();
    }

    async loadThemes() {
        try {
            const response = await fetch('/static/themes.json');
            this.themes = await response.json();
        } catch (error) {
            console.error('加载主题失败:', error);
        }
    }

    applyTheme(themeName) {
        const theme = this.themes[themeName];
        if (!theme) return;

        const root = document.documentElement;
        
        // 应用颜色变量
        Object.entries(theme.colors).forEach(([key, value]) => {
            root.style.setProperty(`--color-${key}`, value);
        });

        // 应用字体变量
        if (theme.typography) {
            Object.entries(theme.typography).forEach(([key, value]) => {
                root.style.setProperty(`--font-${key}`, value);
            });
        }

        this.currentTheme = themeName;
        localStorage.setItem('theme', themeName);
        
        // 触发主题切换事件
        window.dispatchEvent(new CustomEvent('themeChanged', { 
            detail: { theme: themeName } 
        }));
    }
}