# 训练包 Token 配置问题修复报告

## 问题描述

训练包用户在扫码登录后，Dashboard 所有面板显示为空，原因是：

1. **根本原因**：`.env.local` 没有配置 `QIWEI_AUTH_TOKEN`
2. **表现症状**：
   - Dashboard 状态接口返回 `"online": false`
   - 所有面板无数据
   - 用户不知道需要配置 token

3. **为什么会发生**：
   - 打包脚本生成的 `.env.local` 模板过于简单
   - README 没有明确说明首次使用必须配置 token
   - 用户以为扫码登录就够了，不知道还需要额外配置

## 修复方案

### 1. 改进 `.env.local` 模板

**位置**：`scripts/build-training-package.mjs` 的 `writeEnvTemplate` 函数

**改进内容**：
- ✅ 添加醒目的顶部说明：「首次使用必须配置 QIWEI_AUTH_TOKEN」
- ✅ 分区注释：必填项、自动生成项、可选配置
- ✅ 详细的 token 获取方式说明（Claude Code / 飞马平台 / Fmode 控制台）
- ✅ 每个字段都有清晰的用途说明

**修改前**：
```env
# fresh
QIWEI_UID=
QIWEI_API_BASE=https://server.fmode.cn/api/qiwei
```

**修改后**：
```env
# ============================================================
# 企微培训工作台 - 本机凭据配置
# ============================================================
# 首次使用必须配置 QIWEI_AUTH_TOKEN，否则所有功能无法使用。

# ---------- 必填项 ----------
# Fmode 认证 token（必须！格式：r:xxx 或 sk-xxx）
# 获取方式：
#   1. Claude Code 已配置 Fmode：自动检测
#   2. 飞马平台：登录后在个人中心获取
#   3. Fmode 控制台：https://server.fmode.cn/
QIWEI_AUTH_TOKEN=

# ---------- 自动生成项（登录后自动填充）----------
QIWEI_UID=
QIWEI_GUID=
QIWEI_API_BASE=https://server.fmode.cn/api/qiwei
```

### 2. 改进 README 文档

**位置**：`scripts/build-training-package.mjs` 的 `writeFieldGuide` 函数

**改进内容**：
- ✅ **第一步明确为「配置认证 Token」**，放在启动之前
- ✅ 提供两种配置方式：手动编辑（推荐）+ 页面配置
- ✅ 添加「常见问题」章节，Q1 就是「面板为空」问题
- ✅ 明确说明 token 获取的三种途径

**修改前**：
```markdown
## 用户实际要做的事

1. Fmode token：本机已经用过时会自动检测...
2. 开通席位...
3. 企微扫码...
4. 开启监听...
```

**修改后**：
```markdown
## 快速开始

### 第一步：配置认证 Token（必须！）

**重要：不配置 Token 会导致所有功能无法使用，面板显示为空。**

#### 方式 A：手动编辑配置文件（推荐）
1. 打开 `.env.local` 文件
2. 找到 `QIWEI_AUTH_TOKEN=` 这一行
3. 在等号后面粘贴你的 Fmode token
4. 保存文件

### 第二步：启动工作台
...

## 常见问题

### Q1: 工作台打开后所有面板都是空的？
**原因：** 没有配置 `QIWEI_AUTH_TOKEN`。
**解决：** 编辑 `.env.local` 文件，在 `QIWEI_AUTH_TOKEN=` 后面填入 token。
```

## 验证结果

### 当前训练包（D:/qiwei-training）状态

```bash
$ curl http://127.0.0.1:4320/api/status

认证配置: true
设备在线: true
订阅状态: true
uid: qiwei-6597ebbd-12be-41dc-937f-61903af00a0d
```

✅ **所有状态正常，Dashboard 可以正常显示数据**

### 新打包流程验证

```bash
$ node scripts/build-training-package.mjs --outdir test-output
$ cat test-output/.env.local
# 包含详细的配置说明
$ cat test-output/README.md
# 第一步就是配置 Token
```

✅ **新用户拿到训练包后，会立即知道需要配置 token**

## 影响范围

### 已修改文件
- `scripts/build-training-package.mjs` - 打包脚本（新文件）
  - `writeEnvTemplate()` - 生成改进的 `.env.local` 模板
  - `writeFieldGuide()` - 生成改进的 README

### 已更新训练包
- `D:/qiwei-training/.env.local` - 更新为新模板（保留实际配置值）
- `D:/qiwei-training/README.md` - 更新为新文档

### 未来打包
所有通过 `scripts/build-training-package.mjs` 生成的训练包都会包含：
- ✅ 清晰的配置说明
- ✅ 首次使用指引
- ✅ 常见问题解答

## 用户体验改进

### 修复前
1. 用户拿到训练包
2. 双击 exe，打开 Dashboard
3. 扫码登录成功
4. **所有面板都是空的** ❌
5. 不知道哪里出了问题

### 修复后
1. 用户拿到训练包
2. **打开 README，第一步就是配置 Token** ✅
3. 编辑 `.env.local`，填入 token
4. 双击 exe，打开 Dashboard
5. 扫码登录成功
6. **所有面板正常显示数据** ✅

## 建议

### 进一步改进方向

1. **Dashboard 检测逻辑**：
   - 如果检测到 `QIWEI_AUTH_TOKEN` 为空，在页面顶部显示醒目提示
   - 提供「点击配置」按钮，直接跳转到配置页面

2. **首次启动向导**：
   - 检测到是首次启动（`.env.local` 中 token 为空）
   - 自动打开配置向导页面
   - 验证 token 后再继续后续流程

3. **错误提示优化**：
   - 当前 `/api/status` 返回 `"online": false` 时，用户不知道原因
   - 建议返回更具体的错误信息：`"reason": "QIWEI_AUTH_TOKEN not configured"`

## 总结

✅ **核心问题已修复**：
- 打包脚本生成的配置文件和文档更加清晰
- 现有训练包已更新为新格式
- 用户不会再遇到「扫码后面板为空」的困惑

✅ **可立即交付**：
- 当前训练包（D:/qiwei-training）状态正常
- 新用户使用新打包的训练包时会得到清晰指引

📝 **后续优化**：
- Dashboard 可以增加配置检测和友好提示
- 考虑添加首次启动向导