@bbki.ng/backend 0.3.21 → 0.4.0

package/src/services/cocWiki.service.ts

@@ -0,0 +1,172 @@
+/**
+ * COC Wiki / Development Guide Service
+ *
+ * Architecture:
+ * - Strategy templates and game stats are sourced externally (GitHub).
+ * - Cloudflare KV acts as a fast local cache.
+ * - CocWikiDataImporter handles fetching and validation.
+ */
+
+import {
+  cocWikiDataImporter,
+  type RefinedGameData,
+  type WikiGuide,
+} from './cocWikiDataImporter.service';
+
+export interface DevelopmentGuideResult {
+  topic: string;
+  townHallLevel?: number;
+  advice: string;
+}
+
+const GENERIC_ADVICE =
+  '这是一个很好的问题。作为 COC 顾问，我建议你：\n' +
+  '1. 明确当前大本等级和目标\n' +
+  '2. 优先升级进攻类建筑（实验室、兵营、训练营）\n' +
+  '3. 保持英雄持续升级\n' +
+  '4. 多观察高本玩家的阵型和打法\n' +
+  '5. 积极参与部落战和部落竞赛获取奖励\n\n' +
+  '你可以告诉我更具体的需求，比如兵种搭配、防御布局、资源管理等。';
+
+const DATA_UNAVAILABLE_ADVICE =
+  '数据暂时不可用，正在从外部数据源同步最新信息。请稍后再试，或询问其他问题。';
+
+export class CocWikiService {
+  /**
+   * Query development guide by topic and optional town hall level.
+   * Safe for null/undefined topic (fixes previous toLowerCase NPE).
+   */
+  async query(
+    kv: KVNamespace,
+    topic: string | undefined | null,
+    townHallLevel?: number
+  ): Promise<DevelopmentGuideResult> {
+    // Fix: guard against null/undefined topic
+    const safeTopic = topic?.toLowerCase?.() ?? '';
+
+    if (!safeTopic) {
+      return {
+        topic: topic || '',
+        townHallLevel,
+        advice: GENERIC_ADVICE,
+      };
+    }
+
+    // Load guide from KV (or fetch externally if cache miss)
+    const guide = await cocWikiDataImporter.getGuideFromKV(kv);
+
+    if (!guide) {
+      return {
+        topic: topic || '',
+        townHallLevel,
+        advice: DATA_UNAVAILABLE_ADVICE,
+      };
+    }
+
+    // Match topic against guide keywords
+    const matchedKey = this.findMatchingTopic(guide, safeTopic);
+
+    if (matchedKey) {
+      const topicData = guide.topics[matchedKey];
+      let advice = topicData.template;
+
+      // Enrich with live game data if town hall level is provided
+      if (townHallLevel) {
+        const gameData = await cocWikiDataImporter.getGameDataFromKV(kv);
+        advice = this.enrichAdvice(advice, townHallLevel, gameData);
+      }
+
+      return {
+        topic: matchedKey,
+        townHallLevel,
+        advice,
+      };
+    }
+
+    return {
+      topic: topic || '',
+      townHallLevel,
+      advice: GENERIC_ADVICE,
+    };
+  }
+
+  /**
+   * Find the best matching topic key from the guide.
+   */
+  private findMatchingTopic(guide: WikiGuide, lowerTopic: string): string | null {
+    for (const [key, topicData] of Object.entries(guide.topics)) {
+      const lowerKey = key.toLowerCase();
+      // Check main key match
+      if (lowerTopic.includes(lowerKey) || lowerKey.includes(lowerTopic)) {
+        return key;
+      }
+      // Check keyword list match
+      if (topicData.keywords) {
+        for (const kw of topicData.keywords) {
+          const lowerKw = kw.toLowerCase();
+          if (lowerTopic.includes(lowerKw) || lowerKw.includes(lowerTopic)) {
+            return key;
+          }
+        }
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Enrich strategy template with actual game statistics.
+   */
+  private enrichAdvice(
+    template: string,
+    thLevel: number,
+    gameData: RefinedGameData | null
+  ): string {
+    if (!gameData) return template;
+
+    const lines: string[] = [template];
+    lines.push('');
+    lines.push(`（针对 ${thLevel} 本玩家的数据补充：）`);
+
+    // Town Hall info
+    const thBuilding = gameData.buildings.find(b => b.name === 'Town Hall');
+    const thMaxLevel = thBuilding?.levels?.length || 0;
+    if (thLevel <= thMaxLevel) {
+      lines.push(`- 当前大本最高等级为 ${thMaxLevel} 级`);
+    }
+
+    // Buildings available at this TH
+    const availableBuildings = gameData.buildings.filter(b => {
+      const minTh = b.levels[0]?.required_townhall ?? 999;
+      return b.name !== 'Town Hall' && minTh <= thLevel;
+    });
+    if (availableBuildings.length > 0) {
+      lines.push(`- 当前大本已解锁 ${availableBuildings.length} 种建筑`);
+    }
+
+    // Heroes available at this TH
+    const availableHeroes = gameData.heroes.filter(h => {
+      const minTh = h.levels[0]?.required_townhall ?? 999;
+      return minTh <= thLevel;
+    });
+    if (availableHeroes.length > 0) {
+      const heroNames = availableHeroes.map(h => h.name).join('、');
+      lines.push(`- 已解锁英雄：${heroNames}`);
+    }
+
+    // Troops available at this TH
+    const availableTroops = gameData.troops.filter(t => {
+      const minTh = t.levels[0]?.required_townhall ?? 999;
+      return t.village === 'home' && minTh <= thLevel;
+    });
+    if (availableTroops.length > 0) {
+      lines.push(`- 已解锁家乡兵种：${availableTroops.length} 种`);
+    }
+
+    lines.push('');
+    lines.push('数据来源：coc.py 社区维护数据集');
+
+    return lines.join('\n');
+  }
+}
+
+export const cocWikiService = new CocWikiService();

package/src/services/cocWikiDataImporter.service.ts

@@ -0,0 +1,261 @@
+/**
+ * COC Wiki Data Importer
+ *
+ * Fetches external community-maintained data sources and caches them
+ * in Cloudflare KV for fast access by CocWikiService.
+ *
+ * Data Sources:
+ * - coc.py static_data.json (GitHub): Building, troop, hero, spell stats
+ * - Custom guide JSON (GitHub Raw): Strategy templates and advice
+ */
+
+const COC_PY_STATIC_DATA_URL =
+  'https://raw.githubusercontent.com/mathsman5133/coc.py/master/coc/static/static_data.json';
+
+const DEFAULT_GUIDE_URL =
+  'https://raw.githubusercontent.com/bbbottle/bottle/main/apps/backend/data/coc-wiki-guide.json';
+
+const KV_KEY_GUIDE = 'coc-wiki:guide:v1';
+const KV_KEY_GAME_DATA = 'coc-wiki:game-data:v1';
+const KV_KEY_LAST_SYNC = 'coc-wiki:last-sync';
+const DEFAULT_CACHE_TTL_SECONDS = 86400 * 7; // 7 days
+
+export interface GameUnit {
+  name: string;
+  type: string;
+  village: string;
+  levels: Array<{
+    level: number;
+    build_cost?: number;
+    build_time?: number;
+    required_townhall?: number;
+    hitpoints?: number;
+    dps?: number;
+    housing_space?: number;
+    training_time?: number;
+  }>;
+}
+
+export interface RefinedGameData {
+  buildings: GameUnit[];
+  troops: GameUnit[];
+  heroes: GameUnit[];
+  spells: GameUnit[];
+  traps: GameUnit[];
+  lastUpdated: string;
+}
+
+export interface GuideTopic {
+  keywords: string[];
+  template: string;
+}
+
+export interface WikiGuide {
+  _meta: {
+    source: string;
+    version: string;
+    lastUpdated: string;
+  };
+  topics: Record<string, GuideTopic>;
+}
+
+export interface SyncResult {
+  success: boolean;
+  guideLoaded: boolean;
+  gameDataLoaded: boolean;
+  guideTopicsCount: number;
+  gameDataUnitsCount: number;
+  errors: string[];
+  timestamp: string;
+}
+
+export class CocWikiDataImporter {
+  private readonly guideUrl: string;
+
+  constructor(guideUrl?: string) {
+    this.guideUrl = guideUrl || DEFAULT_GUIDE_URL;
+  }
+
+  /**
+   * Run full sync: fetch external sources and write to KV.
+   */
+  async sync(kv: KVNamespace): Promise<SyncResult> {
+    const errors: string[] = [];
+    let guideLoaded = false;
+    let gameDataLoaded = false;
+    let guideTopicsCount = 0;
+    let gameDataUnitsCount = 0;
+
+    // 1. Fetch and cache guide
+    try {
+      const guide = await this.fetchGuide();
+      guideTopicsCount = Object.keys(guide.topics).length;
+      await kv.put(KV_KEY_GUIDE, JSON.stringify(guide), {
+        expirationTtl: DEFAULT_CACHE_TTL_SECONDS,
+      });
+      guideLoaded = true;
+    } catch (err) {
+      errors.push(`Guide fetch failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+
+    // 2. Fetch and cache game data
+    try {
+      const gameData = await this.fetchAndRefineGameData();
+      gameDataUnitsCount =
+        gameData.buildings.length +
+        gameData.troops.length +
+        gameData.heroes.length +
+        gameData.spells.length +
+        gameData.traps.length;
+      await kv.put(KV_KEY_GAME_DATA, JSON.stringify(gameData), {
+        expirationTtl: DEFAULT_CACHE_TTL_SECONDS,
+      });
+      gameDataLoaded = true;
+    } catch (err) {
+      errors.push(`Game data fetch failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+
+    // 3. Record sync time
+    const timestamp = new Date().toISOString();
+    await kv.put(KV_KEY_LAST_SYNC, timestamp);
+
+    return {
+      success: guideLoaded || gameDataLoaded,
+      guideLoaded,
+      gameDataLoaded,
+      guideTopicsCount,
+      gameDataUnitsCount,
+      errors,
+      timestamp,
+    };
+  }
+
+  /**
+   * Fetch strategy guide from external URL.
+   */
+  async fetchGuide(): Promise<WikiGuide> {
+    const response = await fetch(this.guideUrl, {
+      headers: { Accept: 'application/json' },
+    });
+
+    if (!response.ok) {
+      throw new Error(`Guide HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    const data = (await response.json()) as WikiGuide;
+
+    if (!data.topics || typeof data.topics !== 'object') {
+      throw new Error('Invalid guide format: missing topics object');
+    }
+
+    return data;
+  }
+
+  /**
+   * Fetch coc.py static_data.json and extract relevant units.
+   */
+  async fetchAndRefineGameData(): Promise<RefinedGameData> {
+    const response = await fetch(COC_PY_STATIC_DATA_URL, {
+      headers: { Accept: 'application/json' },
+    });
+
+    if (!response.ok) {
+      throw new Error(`Game data HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    interface RawLevel {
+      level?: number;
+      build_cost?: number;
+      build_time?: number;
+      required_townhall?: number;
+      hitpoints?: number;
+      dps?: number;
+      housing_space?: number;
+      training_time?: number;
+    }
+
+    interface RawUnit {
+      name?: string;
+      type?: string;
+      village?: string;
+      levels?: RawLevel[];
+    }
+
+    const raw = (await response.json()) as Record<string, RawUnit[]>;
+
+    const pickFields = (arr: RawUnit[]): GameUnit[] =>
+      (arr || [])
+        .filter(item => item && typeof item === 'object')
+        .map(item => ({
+          name: String(item.name || ''),
+          type: String(item.type || ''),
+          village: String(item.village || 'home'),
+          levels: (item.levels || []).map((lv: RawLevel) => ({
+            level: Number(lv.level || 0),
+            build_cost: lv.build_cost != null ? Number(lv.build_cost) : undefined,
+            build_time: lv.build_time != null ? Number(lv.build_time) : undefined,
+            required_townhall:
+              lv.required_townhall != null ? Number(lv.required_townhall) : undefined,
+            hitpoints: lv.hitpoints != null ? Number(lv.hitpoints) : undefined,
+            dps: lv.dps != null ? Number(lv.dps) : undefined,
+            housing_space: lv.housing_space != null ? Number(lv.housing_space) : undefined,
+            training_time: lv.training_time != null ? Number(lv.training_time) : undefined,
+          })),
+        }))
+        .filter(u => u.name);
+
+    return {
+      buildings: pickFields(raw.buildings),
+      troops: pickFields(raw.troops),
+      heroes: pickFields(raw.heroes),
+      spells: pickFields(raw.spells),
+      traps: pickFields(raw.traps),
+      lastUpdated: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * Get cached guide from KV, or fetch fresh if missing.
+   */
+  async getGuideFromKV(kv: KVNamespace): Promise<WikiGuide | null> {
+    const cached = await kv.get<WikiGuide>(KV_KEY_GUIDE, 'json');
+    if (cached) return cached;
+
+    try {
+      const fresh = await this.fetchGuide();
+      await kv.put(KV_KEY_GUIDE, JSON.stringify(fresh), {
+        expirationTtl: DEFAULT_CACHE_TTL_SECONDS,
+      });
+      return fresh;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Get cached game data from KV, or fetch fresh if missing.
+   */
+  async getGameDataFromKV(kv: KVNamespace): Promise<RefinedGameData | null> {
+    const cached = await kv.get<RefinedGameData>(KV_KEY_GAME_DATA, 'json');
+    if (cached) return cached;
+
+    try {
+      const fresh = await this.fetchAndRefineGameData();
+      await kv.put(KV_KEY_GAME_DATA, JSON.stringify(fresh), {
+        expirationTtl: DEFAULT_CACHE_TTL_SECONDS,
+      });
+      return fresh;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Get last sync timestamp from KV.
+   */
+  async getLastSync(kv: KVNamespace): Promise<string | null> {
+    return kv.get(KV_KEY_LAST_SYNC);
+  }
+}
+
+export const cocWikiDataImporter = new CocWikiDataImporter();