完成焦点等开发

docs/插件功能概览.md

@@ -0,0 +1,333 @@
+# Nanami-UI 插件功能概览
+
+本文基于当前仓库代码结构整理，目标是快速回答两个问题：
+
+1. 这个乌龟服插件当前做了什么。
+2. 每块功能主要落在哪些代码文件里。
+
+## 1. 插件定位
+
+`Nanami-UI` 是一个面向 Turtle WoW 1.12 环境的大型整合型 UI 插件。整体风格以 `SFrames` 为统一命名空间，核心能力主要包括：
+
+- 自定义单位框体：玩家、宠物、目标、目标的目标、队伍、团队、焦点、天赋树。
+- 动作条与按键：动作条重排、绑定管理、绑定导入导出。
+- 地图与导航：小地图/世界地图换肤、地图迷雾揭示、区域等级、队友图标、暗月马戏团辅助。
+- 聊天与社交：聊天框接管、私聊容器、社交面板重做。
+- 背包与交易：背包/银行整合、离线库存、商人、交易、邮件、拾取窗口。
+- 任务与书籍：任务对话、任务日志皮肤、书籍阅读界面。
+- 职业与养成：角色面板、装备统计、观察面板、法术书、训练师、专业/制造、野兽训练。
+- 辅助与增强：Tooltip、Tweaks、AFK 屏保、Setup Wizard、配置面板等。
+
+## 2. 加载主线
+
+### 2.1 入口文件
+
+- [Nanami-UI.toc](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Nanami-UI.toc)
+  负责定义加载顺序、依赖和 SavedVariables。
+- [Core.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Core.lua)
+  定义全局表 `SFrames`、事件分发、初始化总流程、角色配置快照、斜杠命令。
+- [Config.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Config.lua)
+  提供默认配置、主题预设、颜色与样式生成逻辑。
+
+### 2.2 初始化方式
+
+当前插件的模块大致分成两种启动方式：
+
+- `Core.lua` 集中初始化
+  通过 `SFrames:DoFullInitialize()` 分批启动关键模块与延迟模块，避免登录瞬间内存尖峰。
+- 模块自举初始化
+  一部分界面文件自己监听 `PLAYER_LOGIN` / `ADDON_LOADED` / 专用事件，在对应窗口可用时初始化。
+
+### 2.3 Core 直接管理的模块
+
+`Core.lua` 当前显式初始化的模块包括：
+
+- 立即加载：`Player`、`Pet`、`Target`、`ToT`、`Party`、`FloatingTooltip`、`ActionBars`
+- 延迟批量加载：`Raid`、`Bags`、`Focus`、`TalentTree`、`Minimap`、`MinimapBuffs`、`MinimapButton`、`Chat`、`MapReveal`、`WorldMap`、`ZoneLevelRange`、`MapIcons`、`Tweaks`、`AFKScreen`、`LootDisplay`
+
+### 2.4 自举型模块
+
+这类文件通常在自身内部注册事件并完成初始化：
+
+- [QuestUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\QuestUI.lua)
+- [TrainerUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\TrainerUI.lua)
+- [TradeSkillUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\TradeSkillUI.lua)
+- [BeastTrainingUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\BeastTrainingUI.lua)
+- [BookUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\BookUI.lua)
+- [Merchant.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Merchant.lua)
+- [Mail.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Mail.lua)
+- [SocialUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\SocialUI.lua)
+- [SpellBookUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\SpellBookUI.lua)
+- [FlightMap.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\FlightMap.lua)
+- [QuestLogSkin.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\QuestLogSkin.lua)
+
+## 3. 核心框架与基础设施
+
+### 3.1 核心与公共能力
+
+- [Core.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Core.lua)
+  事件总线、统一初始化、角色配置快照、斜杠命令、若干兼容性保护。
+- [Config.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Config.lua)
+  默认配置、主题生成、颜色方案、类职业主题映射。
+- [Media.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Media.lua)
+  字体与状态条材质列表，兼容 LibSharedMedia。
+- [Factory.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Factory.lua)
+  通用边框、背景、按钮、下拉、输入框等 UI 工厂方法。
+- [Movers.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Movers.lua)
+  布局模式、拖拽锚点、网格吸附、统一解锁/锁定框体。
+- [IconMap.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\IconMap.lua)
+  `img/icon.tga` 的图标坐标表，供多个界面复用。
+- [Bindings.xml](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Bindings.xml)
+  插件按键绑定入口。
+- [ConfigUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\ConfigUI.lua)
+  综合配置面板，覆盖 UI、背包、动作条、小地图、角色等多页设置。
+- [SetupWizard.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\SetupWizard.lua)
+  首次安装向导，也可作为二次配置入口。
+- [GameMenu.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\GameMenu.lua)
+  游戏菜单增强，提供 Nanami-UI 相关入口。
+- [MinimapButton.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\MinimapButton.lua)
+  小地图按钮，用于打开主要面板或功能入口。
+
+### 3.2 斜杠命令
+
+[Core.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Core.lua) 中已确认的主命令入口为：
+
+- `/nanami`
+- `/nui`
+
+从当前代码可见，至少包含以下子命令：
+
+- `unlock` / `move`
+- `lock`
+- `chatreset`
+- `test`
+- `partyh`
+- `partyv`
+- `partylayout`
+- `focus`
+- `clearfocus`
+- `targetfocus`
+- `fcast`
+- `focushelp`
+
+此外还有若干模块自己的调试或快捷命令：
+
+- [DarkmoonGuide.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\DarkmoonGuide.lua)：`/dmf`、`/darkmoon`
+- [FlightMap.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\FlightMap.lua)：`/ftcdebug`、`/ftcexport`
+- [GearScore.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\GearScore.lua)：`/gsdebug`
+- [BeastTrainingUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\BeastTrainingUI.lua)：`/btdebug`
+
+## 4. 功能与代码文件对应
+
+### 4.1 单位框体与战斗信息
+
+- [Units\Player.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Units\Player.lua)
+  玩家框体，包含血量/能量、头像、施法条、buff/debuff、移动锚点等。
+- [Units\Pet.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Units\Pet.lua)
+  宠物框体。
+- [Units\Target.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Units\Target.lua)
+  目标框体，含施法识别与法术图标映射。
+- [Units\ToT.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Units\ToT.lua)
+  目标的目标框体。
+- [Units\Party.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Units\Party.lua)
+  队伍框体，支持布局切换、拖拽物品到队友等逻辑。
+- [Units\Raid.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Units\Raid.lua)
+  团队框体。
+- [Focus.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Focus.lua)
+  焦点系统，支持设置焦点、目标焦点、对焦点施法。
+- [Tooltip.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Tooltip.lua)
+  浮动 Tooltip、单位信息扩展。
+- [MinimapBuffs.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\MinimapBuffs.lua)
+  小地图附近的 buff/debuff 重新排布。
+- [ActionBars.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\ActionBars.lua)
+  主动作条、姿态条、宠物条、键位显示、范围检测、布局修正。
+- [KeyBindManager.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\KeyBindManager.lua)
+  按键绑定查看、导入导出、编辑。
+
+### 4.2 地图与导航
+
+- [Minimap.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Minimap.lua)
+  小地图换肤，支持不同边框样式与职业主题皮肤。
+- [WorldMap.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\WorldMap.lua)
+  世界地图整体重绘与窗口化，是地图类功能的主要承载文件。
+- [MapReveal.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\MapReveal.lua)
+  迷雾揭示与 overlay 数据补丁。
+- [ZoneLevelRange.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\ZoneLevelRange.lua)
+  世界地图区域等级、阵营归属、副本/团队本信息提示。
+- [MapIcons.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\MapIcons.lua)
+  世界地图、小地图、战场地图上的队伍/团队职业图标显示。
+- [DarkmoonGuide.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\DarkmoonGuide.lua)
+  暗月马戏团 Sayge Buff 指引面板。
+- [DarkmoonMapMarker.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\DarkmoonMapMarker.lua)
+  现在只保留兼容占位，实际标记逻辑已并入 `WorldMap.lua`。
+- [FlightMap.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\FlightMap.lua)
+  飞行点目的地列表、飞行进度条与路径可视化。
+- [FlightData.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\FlightData.lua)
+  飞行路线耗时数据库。
+
+### 4.3 聊天与社交
+
+- [Chat.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Chat.lua)
+  聊天框全面换肤与接管，保留原生聊天后端。
+- [Whisper.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Whisper.lua)
+  私聊联系人和聊天记录容器。
+- [SocialUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\SocialUI.lua)
+  好友、忽略、Who、公会、团队管理界面重做。
+
+### 4.4 背包、银行、商人、交易、邮件、拾取
+
+- [Bags\Offline.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Bags\Offline.lua)
+  跨角色离线背包/银行数据采集。
+- [Bags\Core.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Bags\Core.lua)
+  背包模块总入口。
+- [Bags\Container.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Bags\Container.lua)
+  背包容器 UI 与交互。
+- [Bags\Bank.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Bags\Bank.lua)
+  银行界面与银行容器管理。
+- [Bags\Sort.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Bags\Sort.lua)
+  背包整理逻辑。
+- [Bags\Features.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Bags\Features.lua)
+  自动卖灰、自动开包等附加功能。
+- [Merchant.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Merchant.lua)
+  商人面板重做，含回购、批量购买、修理。
+- [Trade.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Trade.lua)
+  交易窗口重做。
+- [Mail.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Mail.lua)
+  邮件面板重做，支持收件管理与多物品发送队列。
+- [LootDisplay.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\LootDisplay.lua)
+  接管原生拾取窗口视觉层，同时尽量保留原生按钮交互。
+- [SellPriceDB.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\SellPriceDB.lua)
+  物品售卖价格数据库，服务于商人/背包场景。
+
+### 4.5 任务、书籍、日志
+
+- [QuestUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\QuestUI.lua)
+  NPC 任务对话、详情、进度、奖励等流程界面。
+- [QuestLogSkin.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\QuestLogSkin.lua)
+  任务日志窗口换肤。
+- [BookUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\BookUI.lua)
+  书籍/卷轴阅读窗口重做。
+
+### 4.6 角色、法术、训练、专业
+
+- [CharacterPanel.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\CharacterPanel.lua)
+  角色面板核心文件，体量很大，集成装备、属性、模型、称号、套装等内容。
+- [StatSummary.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\StatSummary.lua)
+  装备统计摘要与独立统计面板。
+- [InspectPanel.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\InspectPanel.lua)
+  观察面板与目标装备信息展示。
+- [SpellBookUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\SpellBookUI.lua)
+  法术书重做。
+- [TrainerUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\TrainerUI.lua)
+  职业训练师界面重做。
+- [TradeSkillUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\TradeSkillUI.lua)
+  专业制造/制作界面重做。
+- [BeastTrainingUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\BeastTrainingUI.lua)
+  猎人宠物训练界面重做。
+- [PetStableSkin.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\PetStableSkin.lua)
+  宠物管理员/兽栏界面皮肤化。
+- [Units\TalentTree.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Units\TalentTree.lua)
+  天赋树显示模块。
+- [TalentDefaultDB.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\TalentDefaultDB.lua)
+  默认天赋数据库。
+- [TradeSkillDB.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\TradeSkillDB.lua)
+  专业/配方静态数据库。
+- [ClassSkillData.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\ClassSkillData.lua)
+  职业训练技能数据。
+- [GearScore.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\GearScore.lua)
+  装等/装备评分能力。
+
+### 4.7 其他增强
+
+- [Tweaks.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Tweaks.lua)
+  各种杂项增强，当前能看到包括自动下马/取消变形、冷却文本、世界地图 Tooltip 处理、战斗提示等。
+- [AFKScreen.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\AFKScreen.lua)
+  AFK 全屏界面，显示模型、时间、世界 Buff 等信息。
+- [Roll.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Roll.lua)
+  与掷骰/需求贪婪相关的界面或逻辑扩展。
+
+## 5. 数据、资源与文档文件
+
+### 5.1 图片与材质资源
+
+- `img/`
+  存放小地图底图、职业风格贴图、动作条材质、图标图集等资源。
+- [IconMap.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\IconMap.lua)
+  对 `img/icon.tga` 提供图标索引。
+
+### 5.2 现有文档
+
+- [docs\LootDisplay-技术要点.md](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\docs\LootDisplay-技术要点.md)
+  记录接管拾取窗口时的关键实现思路。
+- [docs\AutoDismount-技术总结.md](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\docs\AutoDismount-技术总结.md)
+  记录自动下马/取消变形的实现方案。
+
+### 5.3 辅助脚本与研究资料
+
+- `agent-tools/`
+  看起来用于生成或整理职业训练相关数据。
+- `*.pdf`
+  当前仓库中包含乌龟服属性收益研究资料，更偏设计/数值参考，不属于插件运行时代码。
+
+## 6. SavedVariables 与依赖
+
+### 6.1 SavedVariables
+
+根据 [Nanami-UI.toc](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Nanami-UI.toc)：
+
+- `SFramesDB`
+  角色级配置。
+- `SFramesGlobalDB`
+  全局配置和跨角色数据。
+
+### 6.2 可选依赖
+
+`toc` 中声明的可选依赖包括：
+
+- `ShaguTweaks`
+- `Blizzard_CombatLog`
+- `HealComm-1.0`
+- `DruidManaLib-1.0`
+- `!Libs`
+- `pfQuest`
+- `RDbItems`
+
+从代码上看，这些依赖主要用于：
+
+- 治疗预测、Debuff/Overlay 数据读取。
+- 地图尺寸与覆盖层补全。
+- 额外物品/任务数据支持。
+
+## 7. 维护视角下的重点文件
+
+如果后续要继续分析或改功能，优先关注下面这些“枢纽文件”：
+
+- [Core.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Core.lua)
+  初始化顺序、模块开关、斜杠命令、配置快照。
+- [Config.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Config.lua)
+  默认值和主题系统。
+- [ConfigUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\ConfigUI.lua)
+  用户可见设置入口。
+- [CharacterPanel.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\CharacterPanel.lua)
+  当前仓库里体量最大、耦合也较高的角色面板核心。
+- [Chat.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Chat.lua)
+  体量大、接管深，聊天相关问题通常会从这里开始查。
+- [WorldMap.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\WorldMap.lua)
+  地图增强的主要承载点。
+- [Bags\Container.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Bags\Container.lua)
+  背包显示与交互核心。
+
+## 8. 当前文档的边界
+
+这份文档是“基础概览版”，目前更偏结构和职责映射，尚未逐项展开：
+
+- 每个模块的详细事件流。
+- 每个配置项对应的具体字段。
+- 模块之间的调用关系图。
+- Turtle WoW 私有 API 或兼容处理的逐点说明。
+
+如果继续往下做，比较自然的下一步是：
+
+1. 补一份“初始化时序图”。
+2. 补一份“配置字段与模块对应表”。
+3. 针对地图、角色面板、聊天三个大模块分别拆详细设计文档。