# Nanami-Plates 姓名板仇恨查询 API 文档

## 快速开始

```lua
-- 检查 Nanami-DPS 是否加载
local TE = NanamiDPS and NanamiDPS.ThreatEngine
if not TE then return end
```

---

## API 1: QueryUnitThreat(unitID)

查询指定单位的仇恨信息（以当前玩家视角）。

### 签名

```lua
local data = NanamiDPS.ThreatEngine:QueryUnitThreat(unitID)
```

### 参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `unitID` | `string` | WoW 单位 ID，如 `"target"`, `"mouseover"`, `"nameplate1"` 等 |

### 返回值

| 字段 | 类型 | 说明 |
|------|------|------|
| `pct` | `number` | 当前玩家的仇恨百分比 (0-100，相对于最高仇恨者) |
| `threat` | `number` | 当前玩家的绝对仇恨值 |
| `tankName` | `string` | 当前坦克（最高仇恨者）名称 |
| `tankThreat` | `number` | 坦克的绝对仇恨值 |
| `isTanking` | `boolean` | 当前玩家是否持有仇恨 |
| `isMelee` | `boolean` | 当前玩家是否在近战范围 |
| `source` | `string` | 数据来源: `"api"` (服务端精确) / `"local"` (本地估算) |
| `secondName` | `string` | 仇恨第二名的名称 |
| `secondPct` | `number` | 第二名的仇恨百分比 |
| `secondThreat` | `number` | 第二名的绝对仇恨值 |

如果非战斗状态、单位不存在或无仇恨数据，返回 `nil`。

### 用法示例

```lua
local function GetNameplateThreatColor(unitID)
    local TE = NanamiDPS and NanamiDPS.ThreatEngine
    if not TE then return nil end

    local data = TE:QueryUnitThreat(unitID)
    if not data then return nil end

    local pct = data.pct
    if pct >= 80 then
        return 1, 0.2, 0      -- 红色: 即将 OT
    elseif pct >= 50 then
        return 1, 1, 0        -- 黄色: 警戒
    else
        return 0.2, 1, 0.2    -- 绿色: 安全
    end
end
```

---

## API 2: QueryNameThreat(targetKey, playerName)

查询指定玩家在指定目标上的仇恨值。用于需要查看任意玩家（而非自己）仇恨的场景。

### 签名

```lua
local threat, isTanking, pct = NanamiDPS.ThreatEngine:QueryNameThreat(targetKey, playerName)
```

### 参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `targetKey` | `string` | 目标唯一键，由 `GetTargetKey(unitID)` 生成 |
| `playerName` | `string` | 玩家名称 |

### 返回值

| 返回 | 类型 | 说明 |
|------|------|------|
| `threat` | `number` | 该玩家的绝对仇恨值 |
| `isTanking` | `boolean` | 该玩家是否持有仇恨 |
| `pct` | `number` | 百分比 (0-100) |

---

## API 3: GetTargetKey(unitID)

生成目标的唯一标识键。

```lua
local key = NanamiDPS.ThreatEngine.GetTargetKey("target")
```

键格式:
- `"G:<GUID>"` — 当 UnitGUID 可用时（最准确）
- `"I:<RaidIcon>"` — 当目标有团队标记时
- `"V:<Name>:<MaxHP>"` — 通过名称+最大生命值虚拟标识

---

## API 4: GetThreatList(targetKey)

获取指定目标的完整仇恨排行榜。

```lua
local list = NanamiDPS.ThreatEngine:GetThreatList(targetKey)
```

返回按仇恨降序排列的数组，每项:

```lua
{
    name = "PlayerName",
    threat = 12345,
    tps = 500.5,
    perc = 85.3,
    isTanking = false,
    isMelee = true,
    relativePercent = 85.3,
}
```

---

## API 5: GetOTStatus(targetKey)

获取当前玩家的 OT 风险分析。

```lua
local status = NanamiDPS.ThreatEngine:GetOTStatus(targetKey)
```

返回:

```lua
{
    safe = false,           -- 是否安全
    pct = 92.5,             -- OT 进度百分比
    threshold = 1.3,        -- OT 阈值倍数 (1.1 近战 / 1.3 远程)
    otPoint = 65000,        -- 触发 OT 的绝对仇恨值
    buffer = 3750,          -- 距离 OT 的缓冲值
    myThreat = 61250,       -- 当前玩家仇恨
    tankThreat = 50000,     -- 坦克仇恨
    tankName = "TankPlayer",
    isMelee = false,
}
```

---

## 回调注册

```lua
-- 仇恨数据更新时触发
NanamiDPS:RegisterCallback("threat_update", "MyAddon", function()
    -- 在此刷新所有姓名板的仇恨显示
end)
```

触发频率: 约每 0.5 秒一次（API 报文到达或本地计算完成时）。

---

## 姓名板集成完整示例

```lua
-- 在姓名板的 OnUpdate 或 threat_update 回调中:

local function RefreshNameplateThreat(frame, unitID)
    local TE = NanamiDPS and NanamiDPS.ThreatEngine
    if not TE or not TE.inCombat then
        frame.threatText:SetText("")
        return
    end

    local data = TE:QueryUnitThreat(unitID)
    if not data then
        frame.threatText:SetText("")
        return
    end

    -- 显示自己的仇恨百分比
    local pct = data.pct
    local r, g, b = 0.2, 1.0, 0.2
    if pct >= 80 then
        r, g, b = 1.0, 0.2, 0.0
    elseif pct >= 50 then
        r, g, b = 1.0, 1.0, 0.0
    end

    frame.threatText:SetTextColor(r, g, b)
    frame.threatText:SetText(string.format("%.0f%%", pct))

    -- Tank Mode: 显示第二名信息
    if data.isTanking and data.secondName then
        frame.secondText:SetText(data.secondName .. " " ..
            string.format("%.0f%%", data.secondPct))
        if data.secondPct >= 80 then
            frame.secondText:SetTextColor(1, 0.2, 0)
        else
            frame.secondText:SetTextColor(0.7, 0.7, 0.7)
        end
    else
        frame.secondText:SetText("")
    end

    -- 数据来源指示
    if data.source == "api" then
        frame.sourceIndicator:SetVertexColor(0, 1, 0)  -- 绿色 = 精确
    else
        frame.sourceIndicator:SetVertexColor(0.5, 0.5, 0.5)  -- 灰色 = 估算
    end
end
```

---

## 注意事项

1. **检查 nil**: 所有 API 在非战斗或无数据时返回 nil/0，调用方必须检查
2. **性能**: 避免在每帧调用查询 API，建议跟随 `threat_update` 回调或自行节流（0.3-0.5秒）
3. **数据来源**: `source == "api"` 表示服务端精确数据，`source == "local"` 表示本地估算
4. **依赖**: 需要 Nanami-DPS >= 1.0.0（含 ThreatEngine）
5. **兼容性**: WoW 1.12.x Lua 5.0 — 使用 `table.getn` 而非 `#`，使用 `mod()` 而非 `%`