feat: 分析模块、接口管理及其他功能优化

- 后端: WebMvcConfig/拦截器/AnalyticsService/Mapper/测试优化，新增 Knife4jConfig、AnalyticsDictionary、数据库迁移脚本 - 前端: 分析仪表盘 UI 优化、接口管理列表及详情测试面板 - 小程序: analytics 服务优化、request 增强 - 文档: 分析模块中文标签设计文档、品牌重命名设计文档 - 部署: conf 配置优化、deploy.py 脚本更新 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-23 23:52:39 +08:00
parent d1a0018d1b
commit 9838e7626b
20 changed files with 1073 additions and 78 deletions
@@ -0,0 +1,69 @@
+# Analytics Chinese Business Labels 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:** Make the behavior analytics page display Chinese business descriptions for events, pages, buttons, preferences, and API calls.
+
+**Architecture:** Add a backend analytics dictionary that enriches aggregation DTOs with Chinese labels, add request-level API analytics in the mini program, and update web-admin to consume label fields and show an API call panel.
+
+**Tech Stack:** Spring Boot, MyBatis Plus, Vue 3, Element Plus, ECharts, uni-app mini program.
+
+---
+
+### Task 1: Backend Analytics Dictionary
+
+**Files:**
+- Create: `backend-single/src/main/java/com/emotion/service/analytics/AnalyticsDictionary.java`
+- Modify: `backend-single/src/main/java/com/emotion/dto/response/analytics/AnalyticsTopEventItem.java`
+- Modify: `backend-single/src/main/java/com/emotion/dto/response/analytics/AnalyticsTrendItem.java`
+- Modify: `backend-single/src/main/java/com/emotion/dto/response/analytics/AnalyticsPreferenceItem.java`
+
+- [x] Add event, event type, page, dimension, value, and API label maps.
+- [x] Add DTO fields for Chinese labels while keeping original keys.
+- [x] Add helper methods for page and API labels.
+
+### Task 2: Backend Aggregation Enrichment
+
+**Files:**
+- Modify: `backend-single/src/main/java/com/emotion/mapper/AnalyticsEventMapper.java`
+- Modify: `backend-single/src/main/java/com/emotion/service/impl/AnalyticsServiceImpl.java`
+
+- [x] Query `page_path` and `api_path` for top events.
+- [x] Fill `eventLabel`, `eventTypeLabel`, `pageLabel`, `apiLabel` in top events.
+- [x] Fill trend event labels and preference labels.
+- [x] Replace funnel labels with Chinese labels.
+
+### Task 3: Mini Program API Analytics
+
+**Files:**
+- Modify: `mini-program/src/services/request.js`
+
+- [x] Add API label map.
+- [x] Track `api_request_success` and `api_request_fail`.
+- [x] Include path, method, status, label, and duration.
+- [x] Skip `/analytics/events/batch`.
+
+### Task 4: Admin Analytics Page
+
+**Files:**
+- Modify: `web-admin/src/api/analytics.ts`
+- Modify: `web-admin/src/views/analytics/AnalyticsDashboard.vue`
+
+- [x] Add TypeScript fields for backend labels.
+- [x] Render chart legend with `eventLabel`.
+- [x] Replace all visible analytics text with Chinese.
+- [x] Add API call table using top events filtered by `api` type.
+- [x] Show Chinese page and preference labels.
+
+### Task 5: Verification
+
+**Commands:**
+- `cd backend-single && mvn test`
+- `cd web-admin && npm run build`
+- `cd mini-program && npm run build:mp-weixin` or available project build command
+- `git diff --check`
+
+- [x] Backend tests pass.
+- [x] web-admin build passes.
+- [x] mini-program build/check passes.
+- [x] Diff check has no new whitespace errors.
@@ -0,0 +1,57 @@
+# 行为分析中文业务标签设计
+
+## 目标
+
+行为分析页面必须用运营人员能理解的中文展示小程序用户行为，包括用户停留页面、点击操作、创作链路、偏好维度和调用接口。页面不再直接展示 `page_view`、`script_home_view`、`/pages/main/index`、`style/career` 等英文 key。
+
+## 范围
+
+- 后端聚合接口增加中文业务字段，保留原始 key 作为排查依据。
+- 小程序请求层补充 API 调用埋点，记录接口路径、中文接口名、成功/失败、耗时。
+- web-admin 行为分析页全部中文化，并优化表格信息结构。
+- 不迁移历史数据，不改变现有上报字段和存储表结构。
+
+## 后端设计
+
+新增分析字典类，集中维护：
+
+- 事件中文名：如 `page_view` → `浏览页面`、`script_generate_success` → `剧本生成成功`。
+- 事件类型中文名：如 `page` → `页面行为`、`script` → `剧本创作`、`api` → `接口调用`。
+- 页面中文名：如 `/pages/main/index` → `首页`、`/pages/main/ScriptView` → `爽文生成页`。
+- 偏好维度和值：如 `style` → `剧本风格`、`career` → `事业逆袭`。
+- 接口中文名：如 `/ai/runtime/stream` → `AI 流式生成`、`/tts/tasks` → `创建朗读任务`。
+
+DTO 增加中文字段：
+
+- `AnalyticsTopEventItem`: `eventLabel`、`eventTypeLabel`、`pagePath`、`pageLabel`、`apiPath`、`apiLabel`。
+- `AnalyticsTrendItem`: `eventLabel`。
+- `AnalyticsPreferenceItem`: `dimensionLabel`、`valueLabel`。
+- `AnalyticsFunnelItem`: `label` 改为中文来源。
+
+后端服务在聚合结果返回前统一填充这些字段。
+
+## 小程序设计
+
+在 `services/request.js` 中记录接口调用埋点：
+
+- 成功：`api_request_success`
+- 失败：`api_request_fail`
+
+埋点属性包含 `api_path`、`api_label`、`method`、`status_code`、`duration_ms`。跳过 `/analytics/events/batch`，避免上报接口自身造成循环。
+
+## 管理端设计
+
+行为分析页保持现有暗色主题，优化为：
+
+- 指标卡使用中文：页面浏览量、访问用户数、行为事件数、活跃用户数、朗读请求数、平均停留时长。
+- 趋势图图例使用中文事件名。
+- 漏斗步骤使用中文业务动作。
+- 热门行为表展示中文行为、所在页面、类型、次数、用户。
+- 新增接口调用表，展示接口中文名、调用状态、次数、用户。
+- 偏好分布表展示中文维度和值。
+
+## 验证
+
+- 后端 `mvn test` 通过。
+- web-admin `npm run build` 通过。
+- mini-program 执行可用构建或类型检查命令，通过后确认无循环埋点。
@@ -0,0 +1,174 @@
+---
+author: Peanut
+created_at: 2026-05-23
+purpose: 全项目品牌重命名方案，从"情绪博物馆"到"开心星球"
+---
+
+# 情绪博物馆 → 开心星球 品牌重命名方案
+
+> **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:** 将项目中所有"情绪博物馆"相关文案（中文/英文/标识符）替换为"开心星球"对应名称，分层递进执行，保障数据安全和服务可用性。
+
+**Architecture:** 分 4 步递进执行：文档层 → 用户可见层 → 配置层 → 底层标识。每步独立可验证，出问题可回退。
+
+**Tech Stack:** grep/sed 批量替换、mysqldump 数据库迁移、git 版本控制、Spring Boot 配置切换
+
+---
+
+## 命名映射表
+
+| 旧标识 | 新标识 | 使用场景 |
+|---|---|---|
+| `情绪博物馆` | `开心星球` | 中文文案（页面标题、提示语、文档） |
+| `Emotion Museum` | `Happy Planet` | 英文标题 |
+| `emotion-museum` | `happy-planet` | kebab-case（路径、文件名、service 名、jar 名） |
+| `EmotionMuseum` | `HappyPlanet` | PascalCase（类名前缀） |
+| `emotion_museum` | `happy_planet` | snake_case（数据库名、SQL） |
+| `com.emotion` | `com.happyplanet` | Java 包名 |
+| `emotion-museum.conf` | `happy-planet.conf` | nginx 配置名 |
+| `emotion` | `happyplanet` | 包名前缀 |
+
+**保持不变的项**：
+- URL 路径（如 `/emotion-museum-admin/`）— 保持兼容
+- 目录名（`web/`、`web-admin/`、`backend-single/`）— 避免构建断裂
+- 数据库表名前缀（如 `emotion_record` → 保持）— 避免 Entity/Table 映射断裂
+
+## 第 1 步：文档层（无风险）
+
+**影响范围**：纯文档文件，不改任何代码或配置
+
+**文件列表**（约 20 个）：
+- `CLAUDE.md`
+- `README.md`
+- `docs/superpowers/` 下所有 .md
+- 各模块下的 `部署说明.md`、`技术方案.md`、`后端代码规范.md` 等
+- `backend-single/部署说明.md`、`backend-single/后端项目结构.md` 等
+
+**操作**：批量 sed 替换中文 `情绪博物馆` → `开心星球`，英文 `Emotion Museum` → `Happy Planet`，`emotion-museum` → `happy-planet`
+
+**验证**：grep 确认无残留
+
+## 第 2 步：用户可见层（低风险）
+
+**影响范围**：用户实际看到的页面文案和提示信息
+
+**文件列表**：
+- `web/src/` 下 Vue 组件中的中文标题
+- `web-admin/src/` 下 Vue 组件中的中文标题（登录页、布局、各页面）
+- `mini-program/src/` 下页面标题和提示文案
+- `.env.development` 和 `.env.production` 中的 `VITE_APP_TITLE`
+- `package.json` 中的 `name`/`description`
+- 部署脚本中的部署完成提示
+
+**操作**：
+1. `web/src/` 和 `web-admin/src/` 中替换 `情绪博物馆` → `开心星球`
+2. `mini-program/src/` 中替换
+3. `.env` 文件中 `VITE_APP_TITLE` 改为 `开心星球管理后台` / `开心星球`
+
+**验证**：启动前端开发服务器，浏览器验证各页面标题和文案
+
+## 第 3 步：配置层（中等风险，需验证）
+
+**影响范围**：配置文件、部署脚本、nginx、systemd service
+
+### 3.1 应用配置
+- `backend-single/src/main/resources/application.yml` — `spring.application.name`
+- `backend-single/src/main/resources/application-*.yml` — 同上
+- 日志路径、应用描述等配置中的 `emotion-museum`
+
+### 3.2 部署脚本
+- `deploy.sh`、`deploy.py`
+- `backend-single/deploy.py`、`backend-single/deploy.sh`
+- `web/deploy.sh`、`web/deploy.py`
+- `web-admin/deploy.sh`、`web-admin/deploy.py`
+- 各脚本中的路径引用、日志路径、提示文案
+
+### 3.3 nginx 配置
+- `conf/emotion-museum.conf` → 重命名为 `happy-planet.conf`
+- 内部路径 `/emotion-museum-admin/` 保持不变（URL 兼容）
+- `emotion-museum` 路径引用在注释中的改为 `happy-planet`
+- jar 文件名、日志路径引用中的 `emotion-museum`
+
+### 3.4 systemd Service
+- `backend-single/asr-service/emotion-museum-asr.service` → `happy-planet-asr.service`
+- `backend-single/tts-service/emotion-museum-tts.service` → `happy-planet-tts.service`
+- 内部路径和描述中的 `emotion-museum`
+
+### 3.5 工具脚本
+- `tools/service_manager.py`
+- `manage.py`
+- `manage.conf.yaml`
+
+### 数据库迁移
+
+**操作**：
+1. `mysqldump -h ... -u ... -p emotion_museum > emotion_museum_backup.sql`
+2. 创建新库：`CREATE DATABASE happy_planet DEFAULT CHARACTER SET utf8mb4`
+3. `sed -i 's/emotion_museum/happy_planet/g' emotion_museum_backup.sql`
+4. `mysql -h ... -u ... -p happy_planet < emotion_museum_backup.sql`
+5. 更新 `application-prod.yml` 中的 `spring.datasource.url` 为 `happy_planet`
+6. 重启后端服务，验证功能
+7. 保留旧库 `emotion_museum` 备份，确认无误后删除
+
+**回退方案**：改回 `application-prod.yml` 中的数据库名即可恢复
+
+## 第 4 步：底层标识（高风险，最后执行）
+
+### 4.1 Java 包名重命名
+
+**操作**：
+1. 移动目录：`backend-single/src/main/java/com/emotion/` → `backend-single/src/main/java/com/happyplanet/`
+2. 更新 `pom.xml` 中的包名引用
+3. 用 sed 批量替换所有 `.java` 文件中 `package com.emotion` → `package com.happyplanet`
+4. 用 sed 批量替换所有 `.java` 文件中 `import com.emotion` → `import com.happyplanet`
+5. 编译验证：`mvn clean install -DskipTests`
+6. 处理编译错误（可能有遗漏的引用）
+
+**测试目录**：
+- `backend-single/src/test/java/com/emotion/` 同样需要迁移
+- `.java` 文件中的 `package` 和 `import` 语句
+
+### 4.2 SQL 文件
+
+**操作**：
+- `sql/emotion_museum_init.sql` → `happy_planet_init.sql`
+- `sql/emotion_museum_ddl.sql` → `happy_planet_ddl.sql`
+- `sql/emotion_museum.sql` → `happy_planet.sql`
+- 文件内部 `CREATE DATABASE emotion_museum` → `happy_planet`
+- `USE emotion_museum` → `USE happy_planet`
+
+### 4.3 其他底层引用
+- `backend-single/create_api_tables.sql` 中的数据库名
+- `.gitignore` 中的路径引用（如有）
+
+**验证**：
+1. `mvn clean install -DskipTests` 编译通过
+2. 启动后端服务，健康检查通过
+3. 前端页面可正常访问，API 调用正常
+
+## 执行顺序与依赖
+
+```
+步骤 1 (文档) → 步骤 2 (用户可见) → 步骤 3 (配置) → 步骤 4 (底层标识)
+                                          ↓
+                                    数据库迁移 (3.6)
+                                    验证通过后再继续 4
+```
+
+## 回退策略
+
+- 每个步骤完成后立即 git commit
+- 数据库迁移保留旧库
+- URL 路径全部不变，避免 404
+- 如有编译错误，git revert 最近 commit
+
+## 风险点与应对
+
+| 风险 | 应对 |
+|---|---|
+| Java 包名迁移遗漏引用 | 分步编译，逐层修复 |
+| 数据库迁移数据丢失 | 迁移前完整备份 |
+| nginx 配置断裂 | 保留旧配置备份，先 cp 再改 |
+| 部署脚本路径断裂 | 先本地 grep 验证，再上传 |
+| Java 编译内存不足 | 临时增加 `-Xmx2048m` |