From e3e1903d93067b8113154ecaf16559134fb3bb35 Mon Sep 17 00:00:00 2001
From: Peanut <peanut_hzm@163.com>
Date: Mon, 25 May 2026 21:45:43 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=B0=83=E7=94=A8=E6=97=A5=E5=BF=97?=
 =?UTF-8?q?=E5=88=97=E8=A1=A8=E5=A2=9E=E5=8A=A0=E7=94=A8=E6=88=B7=E5=AD=97?=
 =?UTF-8?q?=E6=AE=B5=E5=AE=9E=E7=8E=B0=E8=AE=A1=E5=88=92?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../2026-05-25-call-log-add-user-plan.md      | 330 ++++++++++++++++++
 1 file changed, 330 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-05-25-call-log-add-user-plan.md

diff --git a/docs/superpowers/plans/2026-05-25-call-log-add-user-plan.md b/docs/superpowers/plans/2026-05-25-call-log-add-user-plan.md
new file mode 100644
index 0000000..5f5ecbf
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-25-call-log-add-user-plan.md
@@ -0,0 +1,330 @@
+# 调用日志列表增加用户字段实现计划
+
+> **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:** 在管理后台调用日志列表中增加"调用用户"列，显示格式为 `昵称(ID)`，方便排查用户反馈问题。
+
+**Architecture:** 后端 `AiCallLog` 实体新增 `userName` 字段，两处日志保存逻辑写入该字段；前端列表和详情弹窗统一展示 `昵称(ID)` 格式。
+
+**Tech Stack:** Java (Spring Boot 2.7 + MyBatis-Plus), Vue 3 + TypeScript + Element Plus
+
+**Spec:** `docs/superpowers/specs/2026-05-25-call-log-add-user-design.md`
+
+---
+
+## 文件清单
+
+| 操作 | 文件 | 说明 |
+|------|------|------|
+| Modify | `backend-single/src/main/java/com/emotion/entity/AiCallLog.java` | 实体新增 `userName` 字段 |
+| Create | `backend-single/src/main/resources/db/migration/V20260525__add_user_name_to_ai_call_log.sql` | 数据库迁移脚本 |
+| Modify | `backend-single/src/main/java/com/emotion/service/impl/AiRuntimeServiceImpl.java:68-73` | invokeStream 写入 userName |
+| Modify | `backend-single/src/main/java/com/emotion/service/impl/AiRuntimeServiceImpl.java:219-225` | invokeEndpointStream 写入 userName |
+| Modify | `web-admin/src/types/aiconfig.ts` | AiCallLog 接口新增 userName |
+| Modify | `web-admin/src/views/aiconfig/AiRoutingList.vue` | 列表新增"调用用户"列 + userDisplay 函数 |
+| Modify | `web-admin/src/views/aiconfig/components/AiCallLogDetailDialog.vue` | 详情弹窗"用户 ID"改为"调用用户" |
+
+---
+
+### Task 1: 后端实体 + 数据库迁移
+
+**Files:**
+- Modify: `backend-single/src/main/java/com/emotion/entity/AiCallLog.java:29-31`
+- Create: `backend-single/src/main/resources/db/migration/V20260525__add_user_name_to_ai_call_log.sql`
+- Test: `backend-single/` 目录下执行编译验证
+
+- [ ] **Step 1: 在 AiCallLog 实体中新增 userName 字段**
+
+在 `userId` 字段（第 29-30 行）下方新增：
+
+```java
+// AiCallLog.java — 在 @TableField("user_id") private String userId; 之后新增
+
+@TableField("user_name")
+private String userName;
+```
+
+- [ ] **Step 2: 创建数据库迁移脚本**
+
+创建 `backend-single/src/main/resources/db/migration/V20260525__add_user_name_to_ai_call_log.sql`:
+
+```sql
+-- 调用日志表新增 user_name 字段
+ALTER TABLE t_ai_call_log ADD COLUMN user_name VARCHAR(100) DEFAULT NULL COMMENT '用户昵称' AFTER user_id;
+```
+
+- [ ] **Step 3: 编译验证后端代码**
+
+```bash
+cd backend-single
+mvn clean compile -DskipTests
+```
+
+预期：BUILD SUCCESS
+
+- [ ] **Step 4: 提交**
+
+```bash
+git add backend-single/src/main/java/com/emotion/entity/AiCallLog.java
+git add backend-single/src/main/resources/db/migration/V20260525__add_user_name_to_ai_call_log.sql
+git commit -m "feat: 调用日志实体新增 userName 字段及数据库迁移脚本"
+```
+
+---
+
+### Task 2: 后端日志保存逻辑写入 userName
+
+**Files:**
+- Modify: `backend-single/src/main/java/com/emotion/service/impl/AiRuntimeServiceImpl.java`
+- Test: `backend-single/src/test/java/com/emotion/service/AiRuntimeServiceImplTest.java`
+
+- [ ] **Step 1: 在 invokeStream 方法中写入 userName**
+
+找到第 71 行 `callLog.setUserId(resolveUserId(request));` 之后，第 72 行 `callLog.setInputText(...)` 之前，新增：
+
+```java
+// 在 callLog.setUserId(resolveUserId(request)); 之后新增
+callLog.setUserName(request.getUserName());
+```
+
+修改后的上下文（第 68-74 行）变为：
+
+```java
+        AiCallLog callLog = new AiCallLog();
+        callLog.setRequestId(requestId);
+        callLog.setSceneCode(request.getSceneCode());
+        callLog.setUserId(resolveUserId(request));
+        callLog.setUserName(request.getUserName());
+        callLog.setInputText(JSON.toJSONString(request.getInputs()));
+        callLog.setStatus("running");
+```
+
+- [ ] **Step 2: 在 invokeEndpointStream 方法中写入 userName**
+
+找到第 223 行 `callLog.setUserId(request.getUserId());` 之后，第 224 行 `callLog.setInputText(...)` 之前，新增：
+
+```java
+// 在 callLog.setUserId(request.getUserId()); 之后新增
+callLog.setUserName(request.getUserName());
+```
+
+修改后的上下文（第 219-226 行）变为：
+
+```java
+        AiCallLog callLog = new AiCallLog();
+        callLog.setRequestId(requestId);
+        callLog.setEndpointCode(endpoint.getEndpointCode());
+        callLog.setProviderCode(provider.getProviderCode());
+        callLog.setUserId(request.getUserId());
+        callLog.setUserName(request.getUserName());
+        callLog.setInputText(JSON.toJSONString(request.getInputs()));
+        callLog.setStatus("running");
+```
+
+- [ ] **Step 3: 更新单元测试，验证 userName 被正确写入**
+
+修改 `backend-single/src/test/java/com/emotion/service/AiRuntimeServiceImplTest.java`，在 `invokeStreamRecoversWhenOutputExists` 测试中：
+
+在已有的 `request.setRequestId("client-request-1");` 之后添加 `request.setUserName("测试用户");`，然后在断言部分新增 userName 的验证：
+
+```java
+// 在 request.setRequestId("client-request-1"); 之后添加
+request.setUserName("测试用户");
+
+// 在已有的 assertEquals("完整输出", savedLog.getOutputText()); 之后添加
+assertEquals("测试用户", savedLog.getUserName());
+```
+
+- [ ] **Step 4: 运行测试验证**
+
+```bash
+cd backend-single
+mvn test -Dtest=AiRuntimeServiceImplTest
+```
+
+预期：Tests run: 1, Failures: 0, Errors: 0
+
+- [ ] **Step 5: 编译验证 + 提交**
+
+```bash
+cd backend-single
+mvn clean compile -DskipTests
+```
+
+```bash
+git add backend-single/src/main/java/com/emotion/service/impl/AiRuntimeServiceImpl.java
+git add backend-single/src/test/java/com/emotion/service/AiRuntimeServiceImplTest.java
+git commit -m "feat: 日志保存时写入 userName 字段"
+```
+
+---
+
+### Task 3: 前端类型定义 + 列表新增列
+
+**Files:**
+- Modify: `web-admin/src/types/aiconfig.ts:249-250` (AiCallLog 接口)
+- Modify: `web-admin/src/views/aiconfig/AiRoutingList.vue` (调用日志表格区域)
+
+- [ ] **Step 1: AiCallLog 接口新增 userName**
+
+在 `web-admin/src/types/aiconfig.ts` 的 `AiCallLog` 接口中，找到 `userId?: string` 行（约第 249 行），在其下方新增：
+
+```typescript
+// 在 userId?: string 之后新增
+userName?: string
+```
+
+- [ ] **Step 2: AiRoutingList.vue 新增"调用用户"列**
+
+在调用日志表格中，找到 `调用时间` 列（`<el-table-column prop="createTime" label="调用时间" width="175" />`）之后，`场景` 列之前，新增：
+
+```vue
+<el-table-column label="调用用户" width="180" show-overflow-tooltip>
+  <template #default="{ row }">
+    {{ userDisplay(row) }}
+  </template>
+</el-table-column>
+```
+
+- [ ] **Step 3: AiRoutingList.vue 新增 userDisplay 辅助函数**
+
+在 `<script setup>` 中，找到 `function formatMs(ms?: number)` 函数之后（约第 640 行），新增：
+
+```typescript
+function userDisplay(row: AiCallLog): string {
+  const name = row.userName
+  const id = row.userId
+  if (name && id) return `${name}(${id})`
+  if (name) return name
+  if (id) return `-(ID: ${id})`
+  return '-'
+}
+```
+
+- [ ] **Step 4: 前端类型检查**
+
+```bash
+cd web-admin
+npm run type-check
+```
+
+预期：无错误
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add web-admin/src/types/aiconfig.ts
+git add web-admin/src/views/aiconfig/AiRoutingList.vue
+git commit -m "feat: 调用日志列表新增调用用户列"
+```
+
+---
+
+### Task 4: 前端详情弹窗格式统一
+
+**Files:**
+- Modify: `web-admin/src/views/aiconfig/components/AiCallLogDetailDialog.vue`
+
+- [ ] **Step 1: 替换"用户 ID"行为"调用用户"**
+
+在 `AiCallLogDetailDialog.vue` 中，找到基本信息区域中的"用户 ID"行（约第 50-53 行）：
+
+```vue
+          <div class="info-item">
+            <span class="info-label">用户 ID</span>
+            <span class="info-value">{{ log.userId || '-' }}</span>
+          </div>
+```
+
+替换为：
+
+```vue
+          <div class="info-item">
+            <span class="info-label">调用用户</span>
+            <span class="info-value">{{ userDisplay(log) }}</span>
+          </div>
+```
+
+- [ ] **Step 2: 添加 userDisplay 辅助函数**
+
+在 `<script setup>` 中，找到 `function formatMs(ms?: number)` 函数（约第 111 行）之后，新增：
+
+```typescript
+function userDisplay(log: AiCallLog): string {
+  const name = log.userName
+  const id = log.userId
+  if (name && id) return `${name}(${id})`
+  if (name) return name
+  if (id) return `-(ID: ${id})`
+  return '-'
+}
+```
+
+- [ ] **Step 3: 前端类型检查**
+
+```bash
+cd web-admin
+npm run type-check
+```
+
+预期：无错误
+
+- [ ] **Step 4: 提交**
+
+```bash
+git add web-admin/src/views/aiconfig/components/AiCallLogDetailDialog.vue
+git commit -m "feat: 详情弹窗用户信息改为昵称+ID格式"
+```
+
+---
+
+### Task 5: 浏览器验证
+
+- [ ] **Step 1: 启动管理后台**
+
+```bash
+cd web-admin
+npm run dev
+```
+
+- [ ] **Step 2: 浏览器验证**
+
+1. 打开管理后台页面（通常 `http://localhost:5174`）
+2. 导航至 AI 配置管理页面 (`/aiconfig/list`)
+3. 切换到"调用日志" tab
+4. 验证：列表中出现"调用用户"列，显示格式为 `昵称(ID)` 或 `-(ID: xxx)` 或 `-`
+5. 点击任意日志的"详情"按钮，验证弹窗中"调用用户"行显示格式与列表一致
+6. 打开浏览器 DevTools Console，确认无报错
+
+- [ ] **Step 3: 最终提交（如有必要的小修复）**
+
+```bash
+git add -A
+git commit -m "fix: 调用日志用户列浏览器验证修复"
+```
+
+---
+
+## Self-Review: Spec Coverage Check
+
+| Spec 要求 | 对应 Task |
+|-----------|-----------|
+| AiCallLog 实体新增 userName | Task 1 Step 1 |
+| 数据库新增 user_name 列 | Task 1 Step 2 |
+| invokeStream 写入 userName | Task 2 Step 1 |
+| invokeEndpointStream 写入 userName | Task 2 Step 2 |
+| 前端类型定义新增 userName | Task 3 Step 1 |
+| 列表新增"调用用户"列 | Task 3 Step 2-3 |
+| 详情弹窗改为调用用户格式 | Task 4 Step 1-2 |
+| 兜底策略（历史数据 NULL） | userDisplay 函数已处理 |
+| 不改 AiCallLogQueryRequest | 确认未改 |
+
+## Placeholder Scan
+
+计划中无 "TBD"、"TODO"、"fill in"、"add appropriate error handling" 等占位符。所有步骤包含完整代码和命令。
+
+## Type Consistency Check
+
+- `AiCallLog.userName` → Java `String`，前端 `userName?: string` ✅ 一致
+- `userDisplay` 函数在 AiRoutingList.vue 和 AiCallLogDetailDialog.vue 中实现相同逻辑 ✅ 一致
+- 显示格式统一为 `昵称(ID)` / `-(ID: xxx)` / `-` ✅ 一致