# StaffList 交互补全 + customer 后端基础 Implementation Plan

> **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:** 把 StaffList（员工列表）的交互对齐云客——统计数字点击弹明细 modal、操作按钮跳转按员工筛选的列表、昵称跳聊天——并补齐所需后端能力（customer `add_time` 列 + 筛选参数），抽通用明细 modal 组件供后续页面复用。

**Architecture:** 后端先 TDD 扩展（Customer.add_time 列 + Alembic 迁移 + scraper 映射 + 回填脚本 + router 三个筛选参数），再前端：通用 `YkStaffDetailModal` 组件 + StaffList 三类交互接入 + CustomerList/GroupList 读 query 预筛。

**Tech Stack:** FastAPI + SQLAlchemy 2.0 async + Alembic（后端）；Vue3 + TS + Element Plus + Pinia（前端）。

**Spec:** `docs/superpowers/specs/2026-08-05-yunke-ui-alignment-design.md`

**已采集事实（WhatsApp 员工表交互，Playwright 验证）：**
- 添加人数/沟通人数（数字）→ modal（明细表）
- 操作「好友列表」→ `/waBusiness/friendlist/0/{userId}`；「群聊」→ `friendlist/1/{userId}`
- WA 昵称 → 新 tab 聊天记录（`wschatroom`，会话列表+消息流，只读）

**运行命令（验证用）：**
- 后端：`cd yunke-server && DB_URL="sqlite+aiosqlite:///./smoke.db" .venv/Scripts/python.exe -m uvicorn app.api.main:app --port 8000 --log-level warning`
- 前端：`cd yunkes && npm run dev`
- 后端测试：`cd yunke-server && .venv/Scripts/python.exe -m pytest tests/ -x -q`
- 前端类型：`cd yunkes && npx vue-tsc -b`

---

## File Map

**后端（yunke-server/）：**
- Modify `app/db/models.py` — `Customer` 加 `add_time` 列
- Modify `app/api/schemas.py` — `CustomerOut` 加 `add_time`
- Create `migrations/versions/<rev>_customer_add_time.py` — Alembic 迁移
- Modify `app/scraper/wechat.py` — customer 映射加 `add_time`
- Modify `app/scraper/whatsapp.py` — customer 映射加 `add_time`
- Create `scripts/backfill_customer_add_time.py` — 解析 raw_json 回填历史
- Modify `app/api/routers/customer.py` — 加 `user_id`/`add_time_since`/`last_chat_since`
- Modify `tests/test_api_customer.py` — 新筛选参数测试
- Modify `tests/test_scrape_wechat_friends.py` / `test_scrape_whatsapp_friends.py` — add_time 映射测试

**前端（yunkes/src/）：**
- Modify `api/types.ts` — `Customer` 加 `add_time`
- Modify `api/index.ts` — `CustomerQuery` + `getCustomers` 加三参数
- Create `components/YkStaffDetailModal.vue` — 通用明细 modal
- Modify `views/StaffList.vue` — 数字→modal、操作→跳转、昵称→聊天
- Modify `views/CustomerList.vue` / `views/GroupList.vue` — 读 `route.query` owner/user 预筛

---

## Task 0: 探测微信员工表交互（产出目标映射）

> WhatsApp 员工表交互已采集（见上）。微信员工表（`/cms/wechat/wechatlist`）列结构已采，但**数字是否可点击未探测**。本 task 用同一探测脚本补齐。

**Files:** 无代码改动，产出记录写入本 plan 末尾「探测结果」。

- [ ] **Step 1: 浏览器登录云客 + 打开微信员工列表**（Playwright；若已登录复用会话）
  导航到 `https://crm2.yunkecn.com/cms/wechat/wechatlist`。

- [ ] **Step 2: 跑探测脚本**（参照 spec「交互探测方法」）：对第一行每个可点元素（button/a）点击，记录 URL 变化 / modal title / popup，每次点前回列表页、关残留 modal/tab。

- [ ] **Step 3: 把结果填到本 plan 末尾「微信员工表探测结果」**，据此调整 Task 7/8 的数字→维度映射（微信表的"好友数/消息数/沟通数/及时回复"哪些可点、点出什么 modal）。

- [ ] **Step 4: Commit** 探测结论（更新本 plan）。
  ```bash
  git add docs/superpowers/plans/2026-08-05-yunke-stafflist-interaction.md
  git commit -m "docs: record wechat staff-list interaction probe results"
  ```

---

## Task 1: Customer.add_time 列 + schema + Alembic 迁移

**Files:**
- Modify: `yunke-server/app/db/models.py:235`（`Customer`，`last_chat_time` 下方加 `add_time`）
- Modify: `yunke-server/app/api/schemas.py`（`CustomerOut`）
- Create: `yunke-server/migrations/versions/<rev>_customer_add_time.py`

- [ ] **Step 1: 加模型列**（`app/db/models.py`，`Customer` 类内，紧跟 `last_chat_time`）：
  ```python
      last_chat_time: Mapped[int | None] = mapped_column(BigInteger, nullable=True)
      add_time: Mapped[int | None] = mapped_column(BigInteger, nullable=True)  # ms epoch; from raw_json.addTime
  ```

- [ ] **Step 2: 加 schema 字段**（`app/api/schemas.py`，`CustomerOut`，紧跟 `last_chat_time`）：
  ```python
      last_chat_time: int | None = None
      add_time: int | None = None
  ```

- [ ] **Step 3: 生成 Alembic 迁移**
  ```bash
  cd yunke-server && DB_URL="sqlite+aiosqlite:///./_autogen.db" .venv/Scripts/python.exe -m alembic revision --autogenerate -m "customer add_time"
  ```
  预期：`migrations/versions/<hash>_customer_add_time.py` 生成，内含 `op.add_column('customer', sa.Column('add_time', sa.BigInteger(), nullable=True))`。

- [ ] **Step 4: 应用迁移到 smoke.db 验证**
  ```bash
  cd yunke-server && DB_URL="sqlite+aiosqlite:///./smoke.db" .venv/Scripts/python.exe -m alembic upgrade head
  ```
  预期：`Running upgrade ... -> <hash>, customer add_time`。验证：`sqlite3 smoke.db "PRAGMA table_info(customer)"` 含 `add_time`。

- [ ] **Step 5: 跑模型测试确认不破坏**
  ```bash
  cd yunke-server && .venv/Scripts/python.exe -m pytest tests/test_models.py tests/test_api_customer.py -x -q
  ```
  预期：全 PASS。

- [ ] **Step 6: Commit**
  ```bash
  git add yunke-server/app/db/models.py yunke-server/app/api/schemas.py yunke-server/migrations/versions/
  git commit -m "feat(db): add Customer.add_time column + migration"
  ```

---

## Task 2: scraper 映射 add_time（wechat + whatsapp）

> wechat `addTime` 实测为字符串 `"YYYY-MM-DD HH:mm:ss"`（见 smoke.db）；whatsapp `lastUpdate` 已用 `parse_datetime_to_ms`。`add_time` 要支持字符串与 epoch 两种输入。复用 `parse_datetime_to_ms`（`app/scraper/whatsapp.py` 已定义；若 wechat.py 未 import，提到 `app/scraper/_datetime.py` 共享或直接 import）。

**Files:**
- Modify: `yunke-server/app/scraper/wechat.py`（customer 映射函数，~line 164-192）
- Modify: `yunke-server/app/scraper/whatsapp.py`（customer 映射函数，~line 252-264）
- Test: `yunke-server/tests/test_scrape_wechat_friends.py`, `test_scrape_whatsapp_friends.py`

- [ ] **Step 1: 写失败测试**（`tests/test_scrape_wechat_friends.py`，加一个 case）。
  函数名是 `_normalize`（`app/scraper/wechat.py:157`，**不是** `_normalize_friend`）：
  ```python
  from app.scraper.wechat import _normalize

  def test_normalize_maps_add_time_string_to_epoch():
      record = {"friendWxId": "x", "addTime": "2026-04-28 16:24:39", "lastChatTime": 1700000000000}
      out = _normalize(record)
      # parse_datetime_to_ms 按 naive UTC 解析；断言是合理的近期 epoch，不写死值（避免 tz/算术陷阱）。
      # 2026 年任意时刻 > 1.76e12。
      assert isinstance(out["add_time"], int) and out["add_time"] > 1_760_000_000_000
  ```

- [ ] **Step 2: 跑测试确认 FAIL**
  ```bash
  cd yunke-server && .venv/Scripts/python.exe -m pytest tests/test_scrape_wechat_friends.py::test_normalize_friend_maps_add_time_string_to_epoch -x -q
  ```
  预期：KeyError 或 None（add_time 未映射）。

- [ ] **Step 3: wechat 映射加 add_time**（`app/scraper/wechat.py`，customer 映射 return dict 内，紧跟 `last_chat_time`）：
  ```python
      "last_chat_time": record.get("lastChatTime"),
      "add_time": _parse_add_time(record.get("addTime")),
  ```
  在文件 helper 区加（处理字符串+epoch）。`parse_datetime_to_ms` 实际定义在 `app/scraper/parsers.py`（`whatsapp.py` 仅 re-import），按 **naive UTC** 解析：
  ```python
  from app.scraper.parsers import parse_datetime_to_ms

  _ADD_TIME_FORMATS = ("%Y-%m-%d %H:%M:%S", "%Y-%m-%d %H:%M")

  def _parse_add_time(v):
      """addTime: ms-epoch int 或 'YYYY-MM-DD HH:mm[:ss]' 字符串 → ms epoch (naive UTC)。"""
      if v is None or v == "":
          return None
      if isinstance(v, (int, float)):
          return int(v)
      return parse_datetime_to_ms(v, _ADD_TIME_FORMATS)
  ```
  > 先读 `app/scraper/parsers.py` 的 `parse_datetime_to_ms` 确认它接受 format tuple 且返回 ms epoch（naive UTC）。若签名不同，改为内联：`int(dt.datetime.strptime(v, fmt).replace(tzinfo=dt.UTC).timestamp() * 1000)`（遍历 `_ADD_TIME_FORMATS` 容错）。

- [ ] **Step 4: 跑 wechat 测试确认 PASS**。然后处理 whatsapp（`app/scraper/whatsapp.py` 的 `_normalize_whatsapp_friend`，~line 252）。

  **先 dump 确认 WA customer 有无 customer-side add-time 字段**：
  ```bash
  cd yunke-server && .venv/Scripts/python.exe -c "import sqlite3,json; c=sqlite3.connect('smoke.db'); r=c.execute(\"SELECT raw_json FROM customer WHERE channel='whatsapp' LIMIT 1\").fetchone(); print(list(json.loads(r[0]).keys()) if r else 'none')"
  ```
  ⚠️ 关键：whatsapp `raw_json` 里的 `createTime` 是 **owner-staff** 字段（见 `_normalize_whatsapp_friend` docstring line 246-251），**不是** customer 的添加时间。若 dump 确认 WA customer 无独立的 add-time 字段，则 **WA 的 add_time 留 None**，不要强行用 createTime（会语义错误）。仅 wechat add_time 可靠填充；WA"添加人数"modal 届时按 wechat 路径或降级处理。

- [ ] **Step 5: 跑全部 scraper 测试**
  ```bash
  cd yunke-server && .venv/Scripts/python.exe -m pytest tests/test_scrape_wechat_friends.py tests/test_scrape_whatsapp_friends.py -x -q
  ```
  预期：PASS。

- [ ] **Step 6: Commit**
  ```bash
  git add yunke-server/app/scraper/ yunke-server/tests/test_scrape_wechat_friends.py yunke-server/tests/test_scrape_whatsapp_friends.py
  git commit -m "feat(scraper): map customer add_time from raw_json"
  ```

---

## Task 3: add_time 回填脚本（历史数据）

> 解析现有 customer 行的 `raw_json.addTime` → `add_time` 列。不重抓（区别于 `backfill_customers.py`）。参照其 async sessionmaker + batch commit 模式。

**Files:**
- Create: `yunke-server/scripts/backfill_customer_add_time.py`

- [ ] **Step 1: 写脚本**（参照 `scripts/backfill_customers.py` 的 engine/sessionmaker 设置）：
  ```python
  """Backfill Customer.add_time from raw_json.addTime (no re-scrape).

  Iterates existing customer rows, parses raw_json.addTime (str or epoch) →
  add_time ms-epoch, updates in batches. Idempotent: skips rows already set.
  """
  import asyncio
  import json

  from sqlalchemy import select, update
  from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine

  from app.db import models  # noqa: F401
  from app.db.models import Customer
  from app.scraper.wechat import _parse_add_time  # reuse the parser

  BATCH = 200


  async def main(db_url: str = "sqlite+aiosqlite:///./smoke.db") -> None:
      engine = create_async_engine(db_url)
      sm = async_sessionmaker(engine, expire_on_commit=False)
      done = 0
      async with sm() as s:
          rows = (await s.execute(select(Customer.friend_id, Customer.raw_json, Customer.add_time))).all()
          for i, (fid, raw, existing) in enumerate(rows):
              if existing or not raw:
                  continue
              val = _parse_add_time(raw.get("addTime"))
              if val is None:
                  continue
              await s.execute(update(Customer).where(Customer.friend_id == fid).values(add_time=val))
              done += 1
              if done % BATCH == 0:
                  await s.commit()
                  print(f"[{time.strftime('%H:%M:%S')}] {done} updated...")
          await s.commit()
      print(f"DONE — {done} customers got add_time")
      await engine.dispose()


  if __name__ == "__main__":
      import time
      asyncio.run(main())
  ```
  > 补 `import time` 到顶部（plan 内为可读性放底部，实际放顶部）。

- [ ] **Step 2: 跑回填（smoke.db）**
  ```bash
  cd yunke-server && .venv/Scripts/python.exe -m scripts.backfill_customer_add_time
  ```
  预期：`DONE — N customers got add_time`。

- [ ] **Step 3: 验证** —— query smoke.db 确认 add_time 非空：
  ```bash
  cd yunke-server && .venv/Scripts/python.exe -c "import sqlite3;c=sqlite3.connect('smoke.db');print('with add_time:', c.execute('SELECT COUNT(*) FROM customer WHERE add_time IS NOT NULL').fetchone()[0]); print('total:', c.execute('SELECT COUNT(*) FROM customer').fetchone()[0])"
  ```

- [ ] **Step 4: Commit**
  ```bash
  git add yunke-server/scripts/backfill_customer_add_time.py
  git commit -m "feat(scripts): backfill Customer.add_time from raw_json"
  ```

---

## Task 4: customer router 加 user_id / add_time_since / last_chat_since（TDD）

**Files:**
- Modify: `yunke-server/app/api/routers/customer.py`（`list_customers` 签名 + conditions）
- Test: `yunke-server/tests/test_api_customer.py`

- [ ] **Step 1: 写失败测试**（`tests/test_api_customer.py`）。
  ⚠️ **不要扩展共享 `client` fixture**——它内联 seed 3 行，且 4 个现有测试断言 `total == 3`（`test_list_default_page_returns_all` 等），加行会破坏它们。**新建独立 fixture**（参照 `tests/test_api_customer.py:47-93` 的导入与 app/client 构造方式，对齐 `conftest.py` 的 `async_engine`）：
  ```python
  @pytest_asyncio.fixture
  async def filter_client(async_engine):
      async with async_engine.connect() as conn:
          await conn.run_sync(Base.metadata.create_all)
      Session = async_sessionmaker(async_engine, expire_on_commit=False)
      async with Session() as s:
          s.add_all([
              Customer(friend_id="u1_a", channel="wechat", user_id="U1", add_time=1000, last_chat_time=500),
              Customer(friend_id="u1_b", channel="wechat", user_id="U1", add_time=2000, last_chat_time=2000),
              Customer(friend_id="u2_a", channel="wechat", user_id="U2", add_time=3000, last_chat_time=3000),
          ])
          await s.commit()
      async with AsyncClient(app=app, base_url="http://test") as c:
          yield c

  async def test_filter_by_user_id(filter_client):
      r = await filter_client.get("/api/customers", params={"user_id": "U1"})
      assert {c["friend_id"] for c in r.json()["items"]} == {"u1_a", "u1_b"}

  async def test_filter_by_add_time_since(filter_client):
      r = await filter_client.get("/api/customers", params={"add_time_since": 1500})
      ids = [c["friend_id"] for c in r.json()["items"]]
      assert "u1_a" not in ids and "u1_b" in ids and "u2_a" in ids

  async def test_filter_by_last_chat_since(filter_client):
      r = await filter_client.get("/api/customers", params={"last_chat_since": 1500})
      assert "u1_a" not in [c["friend_id"] for c in r.json()["items"]]
  ```

- [ ] **Step 2: 跑测试确认 FAIL**
  ```bash
  cd yunke-server && .venv/Scripts/python.exe -m pytest tests/test_api_customer.py -k "user_id or add_time_since or last_chat_since" -x -q
  ```
  预期：FAIL（参数未识别 / 无筛选）。

- [ ] **Step 3: 实现筛选**（`app/api/routers/customer.py`）：
  签名加：
  ```python
      user_id: Annotated[str | None, Query()] = None,
      add_time_since: Annotated[int | None, Query(ge=0)] = None,
      last_chat_since: Annotated[int | None, Query(ge=0)] = None,
  ```
  conditions 加：
  ```python
      if user_id is not None:
          conditions.append(Customer.user_id == user_id)
      if add_time_since is not None:
          conditions.append(Customer.add_time >= add_time_since)
      if last_chat_since is not None:
          conditions.append(Customer.last_chat_time >= last_chat_since)
  ```

- [ ] **Step 4: 跑测试确认 PASS**
  ```bash
  cd yunke-server && .venv/Scripts/python.exe -m pytest tests/test_api_customer.py -x -q
  ```

- [ ] **Step 5: 全量回归**
  ```bash
  cd yunke-server && .venv/Scripts/python.exe -m pytest tests/ -x -q
  ```
  预期：全 PASS（≥323）。

- [ ] **Step 6: Commit**
  ```bash
  git add yunke-server/app/api/routers/customer.py yunke-server/tests/test_api_customer.py
  git commit -m "feat(api): customer filters user_id / add_time_since / last_chat_since"
  ```

---

## Task 5: 前端 api/types 加 customer 参数与字段

**Files:**
- Modify: `yunkes/src/api/types.ts`（`Customer`）
- Modify: `yunkes/src/api/index.ts`（`CustomerQuery` + `getCustomers`）

- [ ] **Step 1: `types.ts` `Customer` 加字段**（紧跟 `last_chat_time`）：
  ```ts
    last_chat_time?: number | null
    /** ms epoch of friend add time (from raw_json.addTime). */
    add_time?: number | null
  ```

- [ ] **Step 2: `api/index.ts` `CustomerQuery` 加三参数 + `getCustomers` 透传**：
  ```ts
  export interface CustomerQuery {
    channel?: Channel | 'all'
    page?: number
    page_size?: number
    owner_account_id?: string
    user_id?: string
    department_id?: string
    add_time_since?: number
    last_chat_since?: number
  }

  export function getCustomers(query: CustomerQuery = {}): Promise<Page<Customer>> {
    return getJson<Page<Customer>>(
      '/customers',
      clean({
        page: query.page ?? 1,
        page_size: query.page_size ?? 20,
        channel: query.channel === 'all' ? undefined : query.channel,
        owner_account_id: query.owner_account_id,
        user_id: query.user_id,
        department_id: query.department_id,
        add_time_since: query.add_time_since,
        last_chat_since: query.last_chat_since,
      }),
    )
  }
  ```

- [ ] **Step 3: 类型检查**
  ```bash
  cd yunkes && npx vue-tsc -b
  ```
  预期：exit 0。

- [ ] **Step 4: Commit**
  ```bash
  git add yunkes/src/api/types.ts yunkes/src/api/index.ts
  git commit -m "feat(api): customer query params user_id/add_time_since/last_chat_since"
  ```

---

## Task 6: YkStaffDetailModal 通用组件

> 云客"统计数字→明细 modal"的通用复用件。Props：标题、API 函数、查询参数、列定义。内部 `el-dialog` + `el-table` + `el-pagination`。

**Files:**
- Create: `yunkes/src/components/YkStaffDetailModal.vue`

- [ ] **Step 1: 写组件**：
  ```vue
  <script setup lang="ts">
  import { ref, watch } from 'vue'
  import type { Page } from '@/api/types'

  /**
   * 通用明细 modal —— 复刻云客"统计数字点击弹明细表"。
   * 调用方传 fetcher（返回 Page<T>）+ 列定义；组件负责 dialog/table/pagination。
   */
  interface Col {
    prop: string
    label: string
    width?: number | string
    minWidth?: number | string
    align?: 'left' | 'center' | 'right'
  }
  const props = defineProps<{
    modelValue: boolean
    title: string
    cols: Col[]
    /** fetcher(page, page_size) → Page<T>。宽松 Page<any>：Customer 无 index signature，
     *  不可直接赋 Page<Record<string,unknown>>，故用 any 接纳 Page<Customer> 等。 */
    fetcher: (page: number, page_size: number) => Promise<Page<any>>
    pageSizes?: number[]
  }>()
  const emit = defineEmits<{ 'update:modelValue': [boolean] }>()

  const loading = ref(false)
  const items = ref<any[]>([])
  const total = ref(0)
  const page = ref(1)
  const pageSize = ref(props.pageSizes?.[0] ?? 10)

  async function load() {
    loading.value = true
    try {
      const res = await props.fetcher(page.value, pageSize.value)
      items.value = res.items
      total.value = res.total
    } finally {
      loading.value = false
    }
  }

  watch(
    () => props.modelValue,
    (open) => {
      if (open) {
        page.value = 1
        load()
      }
    },
  )
  </script>

  <template>
    <el-dialog
      :model-value="modelValue"
      :title="title"
      width="900px"
      @update:model-value="emit('update:modelValue', $event)"
    >
      <el-table v-loading="loading" :data="items" border style="width: 100%" size="small">
        <el-table-column
          v-for="c in cols"
          :key="c.prop"
          :prop="c.prop"
          :label="c.label"
          :width="c.width"
          :min-width="c.minWidth"
          :align="c.align"
          show-overflow-tooltip
        />
      </el-table>
      <div style="margin-top: 10px; display: flex; justify-content: flex-end">
        <el-pagination
          :current-page="page"
          :page-size="pageSize"
          :page-sizes="pageSizes ?? [10, 20, 50]"
          :total="total"
          layout="total, sizes, prev, pager, next"
          background
          size="small"
          @current-change="(p: number) => { page = p; load() }"
          @size-change="(s: number) => { pageSize = s; page = 1; load() }"
        />
      </div>
    </el-dialog>
  </template>
  ```

- [ ] **Step 2: 类型检查**
  ```bash
  cd yunkes && npx vue-tsc -b
  ```
  预期：exit 0。

- [ ] **Step 3: Commit**
  ```bash
  git add yunkes/src/components/YkStaffDetailModal.vue
  git commit -m "feat(ui): YkStaffDetailModal shared detail-modal component"
  ```

---

## Task 7: StaffList WhatsApp 数字→modal（添加人数 / 沟通人数）

> 云客 WhatsApp 员工表：点「添加人数」→ modal 列 `序号/员工信息/员工WhatsApp/客户WhatsApp/添加时间/最后沟通时间`；点「沟通人数」→ 类似（沟通客户）。我们用 customer 端点 + `user_id` + `add_time_since`/`last_chat_since` 筛选近似。

**Files:**
- Modify: `yunkes/src/views/StaffList.vue`

- [ ] **Step 1: import 组件 + getCustomers**
  StaffList `<script setup>` 顶部加：
  ```ts
  import { getCustomers } from '@/api'
  import YkStaffDetailModal from '@/components/YkStaffDetailModal.vue'
  ```
  加 modal 状态 + fetcher（script 内）：
  ```ts
  // ---- detail modal (stat-number click → 明细) ----
  const detailOpen = ref(false)
  const detailTitle = ref('')
  const detailFetcher = ref<(p: number, s: number) => Promise<any>>(async () => ({ items: [], total: 0 }))
  const detailCols = ref<any[]>([])

  const baseCustomerCols = [
    { prop: 'friend_nickname', label: '客户', minWidth: 140 },
    { prop: 'phone', label: '客户号码', width: 130 },
    { prop: 'add_time', label: '添加时间', width: 150 },
    { prop: 'last_chat_time', label: '最后沟通', width: 150 },
  ]

  function openAddedModal(row: Account) {
    // 添加人数 = 该员工最近新增好友（add_time 近 N 天；N 待 Task 0 确认，默认 7）
    const since = Date.now() - 7 * 86400000
    detailTitle.value = `添加人数 · ${row.user_name ?? row.account_id}`
    detailCols.value = baseCustomerCols
    detailFetcher.value = (p, s) =>
      getCustomers({ user_id: row.user_id!, channel: 'whatsapp', add_time_since: since, page: p, page_size: s })
    detailOpen.value = true
  }
  function openTalkedModal(row: Account) {
    const since = Date.now() - 7 * 86400000
    detailTitle.value = `沟通人数 · ${row.user_name ?? row.account_id}`
    detailCols.value = baseCustomerCols
    detailFetcher.value = (p, s) =>
      getCustomers({ user_id: row.user_id!, channel: 'whatsapp', last_chat_since: since, page: p, page_size: s })
    detailOpen.value = true
  }
  ```
  > `Date.now()` 在 StaffList 浏览器运行时可用（非 workflow 脚本）。

- [ ] **Step 2: 模板——把 WhatsApp 的「添加人数」「沟通人数」列从纯数字改为可点 link**
  找到 WhatsApp tab 的：
  ```html
  <el-table-column label="添加人数" width="100" align="right">
    <template #default="{ row }">{{ cellNum(row, 'friendAddNum') }}</template>
  </el-table-column>
  ```
  改为：
  ```html
  <el-table-column label="添加人数" width="100" align="right">
    <template #default="{ row }">
      <el-button link type="primary" size="small" @click.stop="openAddedModal(row)">
        {{ cellNum(row, 'friendAddNum') }}
      </el-button>
    </template>
  </el-table-column>
  ```
  「沟通人数」同理用 `openTalkedModal`。

- [ ] **Step 3: 模板末尾挂 modal**（在 `</el-tabs>` 后、`yk-staff__hint` 前）：
  ```html
  <YkStaffDetailModal v-model="detailOpen" :title="detailTitle" :cols="detailCols" :fetcher="detailFetcher" />
  ```

- [ ] **Step 4: 类型检查 + 浏览器验证**
  ```bash
  cd yunkes && npx vue-tsc -b
  ```
  浏览器打开 `http://localhost:5173/staff` → WhatsApp tab → 点「添加人数」数字 → 确认弹 modal 且有数据。

- [ ] **Step 5: Commit**
  ```bash
  git add yunkes/src/views/StaffList.vue
  git commit -m "feat(staff): WhatsApp stat-number click → detail modal"
  ```

---

## Task 8: StaffList 微信交互（跳转类，无 modal）

> ⚠️ **在 Task 9、10 之后执行**（复用 `viewCustomers`/`viewGroups`/`viewChat`）。
> Task 0 探测结论：微信员工表数字点击是**跳转**（非 modal），与 WhatsApp 不同。微信 tab 全部交互复用 Task 9/10 的跳转函数。

**Files:** Modify `yunkes/src/views/StaffList.vue`

- [ ] **Step 1: 微信 tab「好友数」列**——把复合单元格里「好友数」的值包成可点 link → `viewCustomers(row)`（`row.channel` 自动是 wechat，owner=wxId=`row.account_id`）；「微信群数」值 → `viewGroups(row)`。
  例（在微信 tab「好友数」`el-table-column` 的 `yk-pair` 里）：
  ```html
  <el-button link type="primary" size="small" @click.stop="viewCustomers(row)">{{ cellNum(row, 'contactsNum') }}</el-button>
  ```

- [ ] **Step 2: 微信 tab 昵称**（员工信息列 `cellText(row, 'nickName')`）→ `viewChat(row)`（复用 Task 10）。

- [ ] **Step 3: 手机号**——云客跳员工详情，我们暂无此页 → **降级**：不接入（标注：降级，后续员工详情页再做）。

- [ ] **Step 4: 浏览器验证微信 tab**：点好友数→客户列表(wechat, owner=wxId)、群数→群列表、昵称→聊天。

- [ ] **Step 5: 类型检查 + Commit**
  ```bash
  cd yunkes && npx vue-tsc -b
  git add yunkes/src/views/StaffList.vue
  git commit -m "feat(staff): wechat stat-number/nickname → navigation"
  ```

---

## Task 9: 操作按钮跳转 + CustomerList/GroupList 读 query（含后端 groups `user_id` TDD）

> ⚠️ 本 task 含一个**后端 TDD 子任务**（Step 1：groups router 加 `user_id`，独立于前端改动，等同 Task 4 的规模，不要跳过测试）。

> 云客「好友列表」→ 该员工客户列表；「群聊」→ 该员工群列表。我们 `router.push('/customers') + setChannel + ?user_id=`；目标页读 query 预筛。

**Files:**
- Modify: `yunkes/src/views/StaffList.vue`（已有 `viewCustomers`/`viewGroups`，改为带 query + 按 row）
- Modify: `yunkes/src/views/CustomerList.vue`（读 `route.query.user_id`）
- Modify: `yunkes/src/views/GroupList.vue`（读 `route.query.user_id`，调 `/api/groups` 待加 `user_id`——见下注）

> **注**：groups router 加 `user_id` 不在本 plan（spec 列了但属通用基础，可在此顺带加，参照 Task 4 模式：`ChatGroup.owner_user_id == user_id`）。本 task 顺带加。

- [ ] **Step 1: groups router 加 user_id**（`app/api/routers/groups.py`，参照 customer.py）：
  签名加 `user_id: Annotated[str | None, Query()] = None`，conditions 加 `if user_id is not None: conditions.append(ChatGroup.owner_user_id == user_id)`。加测试 `tests/test_api_groups.py::test_filter_by_user_id`。跑测试 PASS。

- [ ] **Step 2: 前端 GroupQuery + getGroups 加 user_id**（`api/index.ts`）。

- [ ] **Step 3: StaffList `viewCustomers`/`viewGroups` 改为按 row + 带 query**。用 `owner_account_id`（= `row.account_id`：微信 wxId / WhatsApp uid 都成立），CustomerList/GroupList **已支持** `owner_account_id` 筛选，无需等 user_id：
  ```ts
  function viewCustomers(row: Account) {
    channelStore.setChannel(row.channel)
    router.push({ path: '/customers', query: { owner_account_id: row.account_id } })
  }
  function viewGroups(row: Account) {
    channelStore.setChannel(row.channel)
    router.push({ path: '/groups', query: { owner_account_id: row.account_id } })
  }
  ```
  模板（两个 tab 的操作列）改为 `@click.stop="viewCustomers(row)"` / `@click.stop="viewGroups(row)"`。

- [ ] **Step 4: CustomerList 读 `owner_account_id` query**（参照它已读 `department_id` 的模式，~line 33）：
  ```ts
  const ownerId = route.query.owner_account_id ? String(route.query.owner_account_id) : null
  ```
  `getCustomers` 调用加 `owner_account_id: ownerId`；watch 响应 `ownerId` 变化；顶部加 chip「筛选自员工」+ 清除（清除时 `router.replace({ query: {} })`）。

- [ ] **Step 5: GroupList 同理读 `owner_account_id` query**。

- [ ] **Step 6: 浏览器验证** —— StaffList WhatsApp → 点「好友列表」→ 跳客户列表，只显示该员工客户 + 顶部 chip；点「群聊」同理。

- [ ] **Step 7: 类型检查 + 全后端回归 + Commit**
  ```bash
  cd yunkes && npx vue-tsc -b
  cd ../yunke-server && .venv/Scripts/python.exe -m pytest tests/ -x -q
  git add ...
  git commit -m "feat(staff): action buttons → filtered customer/group list"
  ```

---

## Task 10: 昵称→聊天（ChatTimeline）

> 云客点 WA 昵称开聊天记录页（会话列表+消息流）。我们 ChatTimeline 当前是消息流，需具体 talkerId。点员工昵称跳"该账号聊天"——暂降级为跳 ChatTimeline 用该账号最近一条会话（spec 风险章节已记）。

**Files:** Modify `yunkes/src/views/StaffList.vue`

- [ ] **Step 1: 加 `viewChat` 函数**（取该 owner 最近一条 message 的 talker_id，跳 ChatTimeline）：
  ```ts
  import { getMessages } from '@/api'
  async function viewChat(row: Account) {
    // 最近一条会话的 talker
    const res = await getMessages({ channel: row.channel, owner_account_id: row.account_id, page: 1, page_size: 1 })
    const m = res.items[0]
    if (!m) { ElMessage.info('该账号暂无聊天记录'); return }
    const path = m.room_id
      ? `/group/${row.channel}/${row.account_id}/${m.room_id}`
      : `/chat/${row.channel}/${row.account_id}/${m.talker_id}`
    router.push(path)
  }
  ```

- [ ] **Step 2: 模板——WhatsApp「员工WhatsApp」列昵称可点**：
  找到 `<span class="yk-staffinfo__nick" :title=...">{{ cellText(row, 'nickName') }}</span>`，包一层 `@click.stop="viewChat(row)"` + `class="yk-link"`，加 `.yk-link { color: var(--el-color-primary); cursor: pointer; }` 样式。

- [ ] **Step 3: 浏览器验证** —— 点 WhatsApp 昵称 → 跳 ChatTimeline 该账号聊天。

- [ ] **Step 4: 类型检查 + Commit**
  ```bash
  cd yunkes && npx vue-tsc -b
  git add yunkes/src/views/StaffList.vue
  git commit -m "feat(staff): WhatsApp nickname → chat timeline"
  ```

---

## 收尾验证

- [ ] 全后端测试绿：`cd yunke-server && .venv/Scripts/python.exe -m pytest tests/ -q`（≥323）
- [ ] 前端类型：`cd yunkes && npx vue-tsc -b` exit 0
- [ ] 浏览器 `http://localhost:5173/staff`：微信+WhatsApp 两 tab，数字点击、操作跳转、昵称跳聊天全部对照云客验证，截图留档。
- [ ] `/api/customers?user_id=X&add_time_since=Y` 返回正确筛选项（curl 验证）。

---

## 微信员工表探测结果（Task 0 已执行，2026-08-05）

微信员工表的交互与 WhatsApp **不同**——以**跳转**为主，**无数字→modal**：

| 元素 | 行为 | 目标 |
|---|---|---|
| 好友数(数字) | 跳转 | `/wechatdetail/1/{wxId}` —— 该微信号客户列表（owner=wxId） |
| 群数(数字) | 跳转 | `/wechatdetail/2/{wxId}` —— 该微信号群列表 |
| 昵称 | 新 tab | `salewechat/message/wechat-window/...` 微信聊天记录 |
| 手机号 | 新 tab | `customer/userDetailNew?userId=...` 员工详情 |
| 主/副标记 | 无明显效果 | — |
| 消息数/沟通数/及时回复 | **不可点** | — |

**关键差异**：WhatsApp 用 modal（添加人数/沟通人数）；微信用跳转（好友数/群数）。故 Task 7（WhatsApp modal）和 Task 8（微信跳转）实现方式不同。

---

## 后续 Plan（不在本 plan 范围）

- Plan 2: CustomerList 列+交互对齐（phase 0 采集后写）
- Plan 3: GroupList / CallList / SmsList
- Plan 4: ChatTimeline 会话列表 + `/api/sessions` 聚合端点
- Plan 5: SearchView + AccountList 删除