yunke/docs/superpowers/plans/2026-09-09-management-console-batch-b-api-plan.md

# 云客经营管理后台·批次B（评分/异常/管理API）实施计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 在批次A数据底座之上交付只读管理 API——期聚合查询、五维试算评分、确定性异常规则、指标元数据、6 个 `/api/management/*` 端点，OpenAPI 可验证；前端（批次C）紧随其后。

**Architecture:** 新建 `app/management/` 业务层（metric_definitions / employee_metrics 期聚合 / scoring / anomalies），`app/api/routers/management.py` 只做参数校验与编排（照 analytics 惯例：SessionDep + Annotated 参数 + dict 返回）。**本期只做 6 个只读端点**（dashboard / employees / employee detail / metrics sections / drilldown 白名单 / metric-definitions）；reviews 与 followups 写端点属批次E。依据：[v2 计划](./2026-09-08-yunke-management-console-implementation-v2.md) §1（决策记录）/§6（API 设计）/§8（Task 3-5）；批次A已交付全部数据表与回填。

**Tech Stack:** 同批次A（FastAPI + SQLAlchemy async；测试内存 SQLite；生产 MySQL 8.4）。

---

## 执行者必读：批次A交付物与既定口径

1. **数据表就绪**（迁移 b7c8d9e0f1a2，本地已回填）：`first_reply_fact`（68,476 行，PK 含 reply_msg_id）、`employee_metric_daily`（12,371 行，metric_version='v1'，串类列与 fact 同源）、`employee_call_daily`（1,163 行）、`employee_score_config`（空，本批次 B0 种子）。
2. **复用模块**：`app/storage/first_reply_facts.py`（fact 表直接查询）、`app/analytics/lifecycle.py`（阈值常量）、`app/analytics/metrics.py` 的 `action_counts`（dashboard 行动入口聚合）、`app/analytics/health.py` 的 `data_as_of`。
3. **周期口径**：start/end 为 yyyymmdd 上海自然日（与 analytics custom scope 同校验：缺一 422、日历非法 422、start>end 422、跨度 ≤366 天）；上期=等长紧邻前窗；个人基线=紧邻当前窗之前的 28 天窗。
4. **评分默认（全部标「试算」，config 里可调）**：维度权重 客户经营30/服务25/行动执行20(pending_data)/有效负载15/合规风险10(pending_data)；可用维度归一化 ×100/70；样本门槛 min=30 串/soft=10 串（周期内）；等级 A≥90/B≥80/C≥70/D≥60/E。
5. **鉴权**：app 级 `require_auth` 全局生效，management 路由无需额外处理；`GET` only。
6. **测试命令**：`cd yunke-server && .venv/Scripts/python.exe -m pytest tests/test_management_api.py -v`；提交中文 conventional；master 直提（项目惯例）；仓库有并行会话活动——`git status` 后只 add 自己的文件。
7. **前端不做**（批次C另出计划）；`schemas_management.py` 留批次E写端点用（analytics 惯例 dict 返回，本期一致）；错误响应沿用 analytics 的 `HTTPException(422/404, message)` 风格（v1 §12.4 的稳定 error_code 为有意偏差，前端按 HTTP 状态码分支）。

## 文件地图

| 文件 | 职责 | 动作 |
|---|---|---|
| `yunke-server/app/management/__init__.py` | 包标记（空） | 新建 |
| `yunke-server/app/management/metric_definitions.py` | 指标元数据注册表 + 默认评分配置 DEFAULT_SCORE_CONFIG | 新建 |
| `yunke-server/app/management/employee_metrics.py` | 期聚合查询（宽表 SUM/fact 窗口函数分位/期末生命周期/通话/distinct 活跃/四对比） | 新建 |
| `yunke-server/app/management/scoring.py` | 标准化/维度分/归一化试算/样本保护/等级 | 新建 |
| `yunke-server/app/management/anomalies.py` | 4 条确定性规则 → v1 §5.4 异常卡片 | 新建 |
| `yunke-server/app/sync/cli.py` | `score-config` 种子子命令 | 修改 |
| `yunke-server/app/api/routers/management.py` | 6 只读端点 | 新建 |
| `yunke-server/app/api/main.py` | include_router | 修改 |
| `yunke-server/tests/test_management_scoring.py` 等 4 个测试文件 | 判别测试 | 新建 |
| `docs/superpowers/plans/2026-09-08-management-batch-a-verification.md` | 批次B冒烟数据追加 | 修改（B5） |

---

### Task B0: 指标元数据 + 默认评分配置 + 种子 CLI

**Files:**
- Create: `yunke-server/app/management/__init__.py`（空文件）
- Create: `yunke-server/app/management/metric_definitions.py`
- Modify: `yunke-server/app/sync/cli.py`（`score-config` 子命令）
- Test: `yunke-server/tests/test_management_scoring.py`（本任务先写配置/种子部分）

- [ ] **Step 1: 写测试（先失败）**

`tests/test_management_scoring.py`：

```python
"""管理域评分配置/引擎判别测试(批次B)。"""
import json

import sqlalchemy as sa

from app.db.models import EmployeeScoreConfig
from app.management.metric_definitions import (
    DEFAULT_SCORE_CONFIG,
    METRIC_DEFINITIONS,
    validate_config,
)


def test_config_weights_sum_and_structure():
    dims = DEFAULT_SCORE_CONFIG["dimensions"]
    assert sum(d["weight"] for d in dims.values()) == 100
    # 一期 pending_data 的维度不参与试算
    available = [d for d in dims.values() if d.get("status") != "pending_data"]
    assert sum(d["weight"] for d in available) == 70  # 30+25+15
    assert dims["action"]["status"] == "pending_data"
    assert dims["risk"]["status"] == "pending_data"


def test_config_normalization_declared():
    assert DEFAULT_SCORE_CONFIG["normalization"] == "available_only_rescale"


def test_validate_config_rejects_bad_weight_sum():
    bad = json.loads(json.dumps(DEFAULT_SCORE_CONFIG))  # deep copy
    bad["dimensions"]["service"]["weight"] = 26  # 总和 101
    problems = validate_config(bad)
    assert any("权重" in p for p in problems)


def test_metric_definitions_cover_scored_metrics():
    # 每个参与评分的 metric_code 都有元数据(名称/单位/方向)
    for dim in DEFAULT_SCORE_CONFIG["dimensions"].values():
        for code in dim.get("metrics", {}):
            md = METRIC_DEFINITIONS[code]
            assert md["name"] and md["unit"] and md["direction"] in (1, -1)


async def test_seed_and_idempotent(make_session):
    from app.sync.cli import _seed_score_config  # 纯会话函数(见 Step 3)
    s = make_session
    v1 = await _seed_score_config(s)
    await s.commit()
    assert v1 == "v1.0"
    rows = (await s.execute(sa.select(EmployeeScoreConfig))).scalars().all()
    assert len(rows) == 1 and rows[0].status == "active"
    # 幂等:已存在同版本返回 None 不新建
    assert await _seed_score_config(s) is None
    await s.commit()
    assert len((await s.execute(sa.select(EmployeeScoreConfig))).scalars().all()) == 1
```

- [ ] **Step 2: 跑测试确认失败**（ModuleNotFoundError: app.management）

- [ ] **Step 3: 实现 metric_definitions.py**

```python
"""管理域指标元数据与默认评分配置(批次B,v2 §6/§10)。

METRIC_DEFINITIONS 是 /api/management/metric-definitions 的单一数据源:
名称/单位/方向/口径说明(含与现有看板的三方口径差异标注)。
DEFAULT_SCORE_CONFIG 为 v1.0 试算起点——所有阈值标「试算」,调整走
新配置版本(employee_score_config),不静默改数。
"""
from __future__ import annotations

# direction: +1 越大越好 / -1 越小越好;caliber 注明与看板差异
METRIC_DEFINITIONS: dict[str, dict] = {
    "msg_sent": {"name": "发出消息(1:1)", "unit": "条", "direction": 1,
                 "caliber": "仅私聊;现有看板为私聊+群聊混合"},
    "msg_recv": {"name": "收到消息(1:1)", "unit": "条", "direction": 1,
                 "caliber": "仅私聊"},
    "cust_threads": {"name": "客户消息串", "unit": "串", "direction": 1,
                     "caliber": "跨日精确,按串末条归属日;看板为日切口径(多日串重复计)"},
    "threads_answered": {"name": "被回串数", "unit": "串", "direction": 1,
                         "caliber": "≡first_reply_fact行数(同源)"},
    "fr_avg_ms": {"name": "平均首响", "unit": "ms", "direction": -1,
                  "caliber": "fr_sum_ms/threads_answered"},
    "fr_p50_ms": {"name": "首响中位数", "unit": "ms", "direction": -1,
                  "caliber": "周期内 fact 精确分位(窗口函数)"},
    "fr_p90_ms": {"name": "首响P90", "unit": "ms", "direction": -1,
                  "caliber": "周期内 fact 精确分位;日切口径会丢跨夜长尾"},
    "reply_2h_rate": {"name": "2h回复率", "unit": "0-1", "direction": 1,
                      "formula": "count(fr_ms<=2h)/cust_threads",
                      "caliber": "分子分母同源(fact/宽表同一算法)"},
    "reply_24h_rate": {"name": "24h回复率", "unit": "0-1", "direction": 1,
                       "formula": "count(fr_ms<=24h)/cust_threads"},
    "active_friends": {"name": "活跃客户(周期)", "unit": "人", "direction": 1,
                       "caliber": "期内distinct客户(msg_daily_stats直查),非宽表日值求和"},
    "active_rooms": {"name": "活跃群(日均)", "unit": "个", "direction": 1},
    "new_customer_count": {"name": "新客(期末)", "unit": "人", "direction": 1,
                           "caliber": "期末单日持有状态,非期内求和"},
    "cooling_customer_count": {"name": "降温客户(期末)", "unit": "人", "direction": -1,
                               "caliber": "距今天数口径(7-29天);频次基线口径二期"},
    "dormant_customer_count": {"name": "沉睡客户(期末)", "unit": "人", "direction": -1,
                               "caliber": "≥30天且历史≥5条"},
    "reactivated_customer_count": {"name": "回流客户(期内)", "unit": "人", "direction": 1,
                                   "caliber": "当日回流且前次间隔>30天,期内求和"},
    "call_count": {"name": "通话数", "unit": "通", "direction": 1,
                   "caliber": "语音通话(微信+WA),无消息渠道维度"},
    "answered_rate": {"name": "接通率", "unit": "0-1", "direction": 1,
                      "formula": "answered_call/call_count", "caliber": "接通=duration>0"},
    "call_followup_rate": {"name": "通话后跟进率", "unit": "0-1", "direction": 1,
                           "formula": "call_followup_count/answered_call",
                           "caliber": "接通后24h内任一账号有1:1消息(含客户发来)"},
    "active_share": {"name": "活跃客户占比", "unit": "0-1", "direction": 1,
                     "formula": "期末active_friends/(期末active+cooling+dormant)",
                     "caliber": "试算口径:期末单日存量"},
}

# 阈值全部为试算起点(v2 §0 决议:全默认+试算标记);type 三种:
#   target      : floor..target 线性 0..100(方向已含在 target>floor)
#   reverse     : ≤target_ms 100 分,≥floor_ms 0 分,中间线性降
#   band        : 区间内 80..100,低于下限不评分(None),超上限不再加分
DEFAULT_SCORE_CONFIG: dict = {
    "version": "v1.0",
    "name": "一期试算(3维可用)",
    "normalization": "available_only_rescale",  # 可用维度 100/Σweight 再 ×100
    "trial": True,
    "sample_guards": {"min_threads": 30, "soft_threads": 10, "min_days": 5},
    "grade_bounds": {"A": 90, "B": 80, "C": 70, "D": 60},  # 低于 D 线为 E
    "dimensions": {
        "customer": {"weight": 30, "name": "客户经营", "metrics": {
            "active_share": {"type": "target", "floor": 0.20, "target": 0.60},
        }},
        "service": {"weight": 25, "name": "服务质量", "metrics": {
            "reply_2h_rate": {"type": "target", "floor": 0.40, "target": 0.85},
            "reply_24h_rate": {"type": "target", "floor": 0.75, "target": 0.97},
            "fr_p90_ms": {"type": "reverse", "target_ms": 1_800_000,
                          "floor_ms": 14_400_000},  # 30min..4h
        }},
        "action": {"weight": 20, "name": "行动执行",
                   "status": "pending_data"},  # 批次E 接 followups/任务
        "workload": {"weight": 15, "name": "有效负载", "metrics": {
            "active_friends_band": {"type": "band", "metric": "active_friends",
                                    "low": 5, "high": 80,
                                    "basis": "period_distinct"},
            "call_band": {"type": "band", "metric": "call_count",
                          "low": 1, "high": 200, "basis": "period_total",
                          "note": "通话低不扣分仅提示;band 得分下限 80"},
        }},
        "risk": {"weight": 10, "name": "合规风险",
                 "status": "pending_data"},  # 批次E/三期接风险事件
    },
}


def validate_config(config: dict) -> list[str]:
    """配置校验:权重总和/结构/引用的 metric_code 有元数据。返回问题清单。"""
    problems: list[str] = []
    dims = config.get("dimensions", {})
    total = sum(d.get("weight", 0) for d in dims.values())
    if total != 100:
        problems.append(f"维度权重总和须=100,当前 {total}")
    for key, dim in dims.items():
        if dim.get("status") == "pending_data":
            continue
        for code, spec in dim.get("metrics", {}).items():
            src = spec.get("metric", code)
            if src not in METRIC_DEFINITIONS:
                problems.append(f"{key}.{code} 引用未定义指标 {src}")
    return problems
```

- [ ] **Step 4: cli.py 加 `score-config` 子命令**

parser（sensitive-scan 与 first-reply-facts 之间任意位置）：

```python
    p_score = sub.add_parser(
        "score-config",
        help="Seed the default score config (idempotent).",
        description=(
            "Insert DEFAULT_SCORE_CONFIG (v1.0, trial) into "
            "employee_score_config as active. Skips if the version "
            "already exists. Batch B."
        ),
    )
```

命令函数与分发（照 _cmd_daily_stats 惯例）：

```python
async def _seed_score_config(session) -> str | None:
    """种子默认评分配置;已存在同版本返回 None(幂等)。纯会话函数可测。"""
    from app.db.models import EmployeeScoreConfig
    from app.management.metric_definitions import (
        DEFAULT_SCORE_CONFIG,
        validate_config,
    )

    problems = validate_config(DEFAULT_SCORE_CONFIG)
    if problems:
        raise ValueError(f"score config invalid: {problems}")
    exists = (
        await session.execute(
            sa.select(EmployeeScoreConfig.id).where(
                EmployeeScoreConfig.version == DEFAULT_SCORE_CONFIG["version"]
            )
        )
    ).scalar_one_or_none()
    if exists is not None:
        return None
    session.add(
        EmployeeScoreConfig(
            version=DEFAULT_SCORE_CONFIG["version"],
            name=DEFAULT_SCORE_CONFIG["name"],
            status="active",
            config_json=DEFAULT_SCORE_CONFIG,
            created_by="seed-cli",
        )
    )
    await session.flush()
    return DEFAULT_SCORE_CONFIG["version"]


async def _cmd_score_config(args: argparse.Namespace) -> int:
    settings = get_settings()
    engine, session_maker = await _init_db(settings.db_url)
    try:
        async with session_maker() as session:
            version = await _seed_score_config(session)
            await session.commit()
        print(f"[score-config] {'seeded ' + version if version else 'already present, skipped'}")
        return 0
    finally:
        await engine.dispose()
```

（cli.py 头部补 `import sqlalchemy as sa` 若无。）

- [ ] **Step 5: 测试通过 + 提交**

```bash
cd yunke-server && .venv/Scripts/python.exe -m pytest tests/test_management_scoring.py -v   # 5 passed
cd yunke-server && .venv/Scripts/python.exe -m app.sync.cli score-config   # 真机种子一次
git add yunke-server/app/management/ yunke-server/app/sync/cli.py yunke-server/tests/test_management_scoring.py
git commit -m "feat(management): 指标元数据+试算评分配置v1.0+种子CLI——权重校验/幂等落库"
```

---

### Task B1: 期聚合查询服务

**Files:**
- Create: `yunke-server/app/management/employee_metrics.py`
- Test: `yunke-server/tests/test_management_period_metrics.py`

核心函数（完整实现）：

```python
"""管理域期聚合查询(批次B)——评分/异常/employees API 的单一数据源。

窗口:days=[start_day..end_day] 闭区间 yyyymmdd;上期=等长紧邻前窗;
个人基线=紧邻当前窗之前的 28 天。所有查询走 (day, ...) 索引,不扫消息表
(除 distinct 活跃客户走 msg_daily_stats friend 行)。
"""
from __future__ import annotations

import datetime as dt
from collections import namedtuple
from zoneinfo import ZoneInfo

import sqlalchemy as sa
from sqlalchemy.ext.asyncio import AsyncSession

from app.db.models import (
    EmployeeCallDaily,
    EmployeeMetricDaily,
    FirstReplyFact,
    MsgDailyStats,
    Staff,
)
from app.storage.staff_summary import account_map
from app.storage.summary import day_bounds_ms

_SH = ZoneInfo("Asia/Shanghai")

PeriodMetrics = namedtuple("PeriodMetrics", [
    "user_id", "days_with_data", "msg_sent", "msg_recv", "cust_threads",
    "threads_answered", "fr_sum_ms", "fr_p50_ms", "fr_p90_ms",
    "reply_2h_count", "reply_24h_count",
    "active_friends",          # 期内 distinct(直查,非日值求和)
    "active_rooms_avg",        # 日均
    "new_customer", "cooling_customer", "dormant_customer",  # 期末单日存量
    "reactivated_customer",    # 期内求和
    "call_count", "call_seconds", "answered_call", "call_followup",
])


def _day_range(start: int, end: int) -> list[int]:
    """闭区间日键列表(纯 Python,上海自然日语义由调用方保证)。"""
    def _d(k): return dt.date(k // 10000, k // 100 % 100, k % 100)
    def _k(d): return d.year * 10000 + d.month * 100 + d.day
    out, cur = [], _d(start)
    while cur <= _d(end):
        out.append(_k(cur))
        cur += dt.timedelta(days=1)
    return out


def prev_window(start: int, end: int) -> tuple[int, int]:
    """等长紧邻前窗。"""
    n = len(_day_range(start, end))
    def _d(k): return dt.date(k // 10000, k // 100 % 100, k % 100)
    def _k(d): return d.year * 10000 + d.month * 100 + d.day
    pe = _d(start) - dt.timedelta(days=1)
    ps = pe - dt.timedelta(days=n - 1)
    return _k(ps), _k(pe)


def baseline_window(start: int) -> tuple[int, int]:
    """个人基线:紧邻当前窗之前的 28 天。"""
    def _d(k): return dt.date(k // 10000, k // 100 % 100, k % 100)
    def _k(d): return d.year * 10000 + d.month * 100 + d.day
    be = _d(start) - dt.timedelta(days=1)
    bs = be - dt.timedelta(days=27)
    return _k(bs), _k(be)
```

`period_metrics(session, start, end, channel, user_ids=None) -> dict[str, PeriodMetrics]` 实现要点（写全代码进计划）：

1. **宽表 SUM**（`WHERE day BETWEEN s AND e AND channel=? AND metric_version='v1' AND user_id IN (...)` GROUP BY user_id）：msg_sent/msg_recv/cust_threads/threads_answered/fr_sum_ms/active_rooms（SUM→avg=SUM/天数）、reactivated（SUM）、`days_with_data=COUNT(*)`；**期末存量**：另查 `day=(SELECT MAX(day)≤e 同 user/channel)` 的 new/cooling/dormant 行（ correlated 或两段查询——用 `sa.select(...).where(day<=end).order_by(day.desc())` per user 取首行，员工 41 人循环可接受；或一次查询取 (user, MAX(day)) 再 join）。
2. **fact 分位与回复计数**（单条 SQL，窗口函数，双方言）：
```python
sub = (
    sa.select(
        FirstReplyFact.owner_account_id.label("owner"),
        FirstReplyFact.fr_ms.label("fr"),
        sa.func.row_number().over(
            partition_by=FirstReplyFact.owner_account_id,   # 列表达式,非别名——MySQL 窗口规范不认 SELECT 别名
            order_by=FirstReplyFact.fr_ms,
        ).label("rn"),
        sa.func.count().over(
            partition_by=FirstReplyFact.owner_account_id
        ).label("n"),
    ).where(FirstReplyFact.day.between(start, end),
            FirstReplyFact.channel == channel)
    .subquery()
)
# 每 owner:rn=ceil(0.5*n) 行的 fr 即 p50;rn=ceil(0.9*n) 即 p90;
# 回复计数:SUM(fr<=2h)/SUM(fr<=24h) 另用条件聚合直查(不用窗口)。
```
   owner→user 经 account_map(channel)。p50/p90 取最接近秩（`rn == (n+1)//2` 与 `rn == max(1, (9*n+9)//10)`——**用「最接近秩」公式并在测试里锁死**：ceil(q·n) 最近邻，与批次A `_percentile` 口径一致）。
3. **reply 计数**：`SELECT owner, SUM(fr_ms<=7200000), SUM(fr_ms<=86400000) FROM first_reply_fact WHERE day BETWEEN ... GROUP BY owner`（MySQL 布尔求和；SQLite 同义 `SUM(CASE WHEN ...)`——用 case 写法双方言安全）。
4. **distinct 活跃客户**：msg_daily_stats friend 行 in window → peer 集合按 account_map 归并到 user → len。
5. **通话**：employee_call_daily SUM（无渠道维；channel 参数只影响消息侧——**通话四列在 channel 查询里也返回全渠道值，响应里标注**）。
6. `team_median`：对每指标取全体 user 的中位数（scoring 层用）。
7. **channel=all**：router 层把 "all" 翻译成 None 传入（照 analytics 惯例，哨兵字符串不进 SQL）；channel=None 时两条渠道的 account_map 合并、宽表/fact 查询去渠道过滤、分位与活跃跨渠道合并到同一 user。

**测试**（seed 宽表/fact/通话行 + Staff/account，构造已知分位数集合断言 p50/p90 精确值、期末存量取 ≤e 最近行、distinct 活跃跨日去重、prev/baseline 窗口日期算术含月末）——完整测试代码进计划（约 6 个用例）。

- [ ] Steps: 测试先失败 → 实现 → 通过 → 全量回归 → 提交
  `feat(management): 期聚合查询——fact窗口函数精确分位/期末生命周期存量/distinct活跃/前窗基线窗口`

---

### Task B2: 评分引擎 scoring.py

**Files:**
- Create: `yunke-server/app/management/scoring.py`
- Test: 追加 `tests/test_management_scoring.py`

核心（完整代码进计划）：

```python
def normalize(spec: dict, value: float | None) -> float | None:
    """单指标 0..100;样本不足/数据缺 → None(不评分,不默认 0/100)。"""
    t = spec["type"]
    if value is None:
        return None
    if t == "target":
        if value <= spec["floor"]:
            return 0.0
        if value >= spec["target"]:
            return 100.0
        return (value - spec["floor"]) / (spec["target"] - spec["floor"]) * 100
    if t == "reverse":
        if value <= spec["target_ms"]:
            return 100.0
        if value >= spec["floor_ms"]:
            return 0.0
        return (spec["floor_ms"] - value) / (spec["floor_ms"] - spec["target_ms"]) * 100
    if t == "band":
        if value < spec["low"]:
            return None  # 负载不足→不评分(样本保护语义)
        return 100.0 if value <= spec["high"] else 80.0  # 超上限 80 不再加
    raise ValueError(t)


def score_employee(config, current: PeriodMetrics, baseline: PeriodMetrics | None,
                   team: dict[str, float]) -> dict:
    """返回 {total_score, grade, score_status, trial, dimensions{...},
    metrics{code: {value, prev, baseline, median, sample_size,
    sample_status, score, formula_note}}}。"""
```

规则（写死进测试）：
- 周期值派生：`reply_2h_rate = reply_2h_count/cust_threads`（threads=0 → None）；`fr_p90_ms` 直取；`active_share` **分子=期末该渠道最近一行(≤end)的 active_friends，分母=同一行的 active_friends+cooling_customer+dormant_customer**（分母 0 → None；宽表无生命周期 active 存量列，active 以 active_friends 列充当）；band 用 active_friends 周期 distinct（B2 决议:抗单日噪声,与 B1 口径一致）与 call_count 总量。
- 样本保护：`cust_threads < min_threads(30)` → 该 service/customer 指标 sample_status="insufficient"，不评分；soft(10)~min 之间 "low_confidence"（评分但标注）。
- 维度分 = 各指标得分的均值（等权）；任一指标 None 时该指标剔除并按剩余归一；**全部 None → 维度 pending**。
- 总分 = Σ(可用维度 weight×dim_score)/Σ(可用维度 weight)×100；可用=pending_data 以外且维度分非 None；全 None → score_status="insufficient_sample"（total None）。
- grade 按 grade_bounds；insufficient → grade None + status。
- `trial=True` 恒返（一期 3 维）。

**测试**（≥8 用例，完整代码进计划）：target 边界（floor/target/中点 50）、reverse 两端与中间、band 三段、threads=0 → None 非 0、insufficient_sample 整员工、pending 维度不参与（100/70 归一后 A 线仍可达）、试算标记、全部指标有明细含四对比位。

- [ ] Steps: TDD → 提交 `feat(management): 评分引擎——三类标准化/维度归一/样本保护/等级/完整明细`

---

### Task B3: 异常规则 anomalies.py

**Files:**
- Create: `yunke-server/app/management/anomalies.py`
- Test: `yunke-server/tests/test_management_anomalies.py`

4 条确定性规则（输入=period_metrics 当前+基线+团队中位数；输出=v1 §5.4 卡片列表，完整代码进计划）：

| rule_code | 触发 | severity | drilldown |
|---|---|---|---|
| reply_p90_worsened | p90 > 基线p90×1.5 且样本≥soft；×2.5 升 critical | warning/critical | metric_code=first_reply_p90 |
| reply_rate_dropped | reply_2h_rate < 基线×0.7 且当前≥soft 样本 | warning | metric_code=unreplied |
| activity_drop | 日均 msg_total < 基线日均×0.5 且基线≥min_days | warning | 员工详情 |
| workload_overload | active_friends 周期 distinct > band 上限 80 | warning | 员工详情 |

卡片字段照 v1 §5.4 JSON（rule_code/severity/employee_user_id/title/current_value/baseline_value/unit/sample_size/**affected_count**/reason[纯数据事实]/drilldown/suggested_action——文案固定模板，不用 LLM）。`affected_count` 按规则定义：reply_p90_worsened 与 reply_rate_dropped=期内未回串数（cust_threads−threads_answered）；activity_drop=当前期活跃客户数；workload_overload=active_friends 日均。

**测试**（≥6 用例）：每规则触发/不触发边界、基线 None 不触发、severity 升级阈值、卡片结构字段齐全。

- [ ] Steps: TDD → 提交 `feat(management): 确定性异常规则×4——P90恶化/回复率骤降/活动骤降/过载`

---

### Task B4: 管理 API 6 端点

**Files:**
- Create: `yunke-server/app/api/routers/management.py`
- Modify: `yunke-server/app/api/main.py`（import + include_router(management.router)）
- Test: `yunke-server/tests/test_management_api.py`

路由骨架（完整代码进计划，照 analytics 惯例）：

```python
router = APIRouter(prefix="/api/management", tags=["management"])
SessionDep = Annotated[AsyncSession, Depends(get_session)]
AllChannelParam = Annotated[Literal["all", "wechat", "whatsapp"], Query()]
YmdParam = Annotated[int, Query(ge=20000101, le=29991231)]
```

| 端点 | 行为要点 |
|---|---|
| `GET /dashboard` | 参数 channel/start/end/compare(previous\|personal_baseline\|team_median,默认 previous)。组装：kpis（活跃客户/活跃员工/待回复[复用 analytics unreplied total]/通话量/生命周期期末分布）+ communication_trend（宽表按日 SUM msg+distinct friends 近 trend 天）+ service_trend（fr 日值 p50/p90 宽表列按日 + reply_2h_rate 派生）+ lifecycle（期末存量分布）+ dimension_summary（全员 3 维分布计数）+ anomalies（B3 全员）+ action_summary（复用 analytics action_counts）+ data_as_of（复用 health）。单次响应聚合，内部并发可用 asyncio.gather |
| `GET /employees` | 参数 channel/start/end/view/keyword/status/sort_by/sort_order/page/page_size(≤100 默认 20)。行=staff 身份(name/is_on_job) + PeriodMetrics + 四对比 + score_employee 结果摘要(total/grade/sample_status/trial) + anomaly_count + anomaly_weight。默认排序=**anomaly_severity**（权重和 critical=2/warning=1 desc，同分再比 count desc——对应 v2 §6「按异常严重度排序」，非单纯计数）；keyword 匹配 staff.name/user_id |
| `GET /employees/{user_id}` | 404 校验（staff 无此 user_id）；头部身份+账号清单(wechat/whatsapp account 表)+宽表总览+评分明细+异常+基线摘要 |
| `GET /employees/{user_id}/metrics?section=` | section ∈ overview\|service\|customer\|workload\|calls（一期 5 个，v2 §6）；每 section 返回该域 PeriodMetrics 明细+四对比+trend（宽表按日序列） |
| `GET /employees/{user_id}/drilldown?metric_code=&start=&end=&channel=&page=&page_size=` | **白名单**：`first_reply_p90|first_reply_p50`→fact 逐串明细（含 thread_end/reply ts/fr_ms+跳聊天参数 owner/talker）；`unreplied`→调 analytics unreplied(user 过滤)；`cooling_customers|dormant_customers`→customer 表 owner 归属+lifecycle 判定列清单；`call_followup`→phone_call 行清单。白名单外 422 |
| `GET /metric-definitions` | METRIC_DEFINITIONS + DEFAULT_SCORE_CONFIG 摘要（权重/试算标记/样本门槛）+ 三方口径差异说明 |

**API 测试**（完整代码进计划，make_client fixture，≥12 用例）：参数默认值/422（custom 缺参、跨度>366、metric_code 白名单外、page_size>100）/404（员工不存在）/响应结构关键字段（data_as_of、metric_version、sample_status、trial 标记）/employees 分页排序/dashboard 各段齐全/渠道过滤生效。

- [ ] Steps: TDD → main.py 注册 → OpenAPI 冒烟（`/docs` 可见 6 端点）→ 全量回归 → 提交
  `feat(management): 只读管理API六端点——dashboard/employees/detail/sections/drilldown白名单/指标定义`

---

### Task B5: 真机冒烟 + 性能初测 + 记录

- [ ] 本地起后端（先 `docker stop yunke-backend-1 yunke-frontend-1` 若在跑；`cd yunke-server && .venv/Scripts/python.exe -m uvicorn app.api.main:app --port 8000` 后台）；
- [ ] curl 六端点（带 token，从 .env API_TOKEN；无 token 模式则直接）真机各一次，记录响应体积与耗时（目标：dashboard p95≤1.5s、employees≤1.5s——v2 §9 性能线）；
- [ ] 抽查：某回测员工（王云青 369D257E…）30 天窗 employees 行——P90/回复率/维度分人工合理性检查（对照核实文档对账数字）；
- [ ] 结果（耗时表+抽查截图级数字）追加到批次A核实文档「批次B冒烟」小节；
- [ ] 提交 `docs(management): 批次B真机冒烟——六端点耗时/回测员工抽查/记录`

---

## 批次B验收清单

- [ ] `score-config` 种子幂等，配置过校验，v1.0 active；
- [ ] 期聚合：p50/p90 精确分位（窗口函数）与期末存量口径有判别测试；
- [ ] 评分：三类标准化边界/样本保护/100-70 归一/试算标记全锁测试；
- [ ] 异常：4 规则触发边界 + 卡片结构完整；
- [ ] 6 端点：OpenAPI 可见、参数校验 422/404 齐全、白名单生效、dict 返回含 data_as_of/metric_version/sample_status；
- [ ] 全量测试绿（653 + 新增 ~30）；
- [ ] 真机冒烟耗时达标并记录；
- [ ] 未动批次A任何存储层代码（宽表/fact 生成零改动）。

## 批次C-F

批次C：前端（api/management.ts + useManagementFilters + components/management/* + ManagementDashboardView + 路由/导航「经营管理」分组）——批次B合入后出计划，消费真实 API 形态。D：员工总览/详情页。E：followups+快照（写端点+schemas）。F：调度接入（analytics_tick 第三步/full_sync 13-14 步/scheduler 镜像重建）+回测试运行。