# 本次更新说明（2026-07-03）— 管理端增强 + 登录门控 + 客户管理

## 更新主题

| 项目 | 说明 |
|------|------|
| 打包时间 | 2026-07-03 |
| 适用场景 | **服务器已有旧版查价**，增量更新代码 |
| 是否改库 | **是**，需执行 Prisma 迁移（安装脚本自动执行） |
| 是否改 `.env` | **保留**已有 `.env`；可删除废弃的 `NEXT_PUBLIC_EMBED_DEMO_*` |
| 是否必须清 Redis | **建议**（避免旧报价缓存） |

---

## 本次主要功能

1. **管理端登录**：不再预填/展示演示账号；默认密码改为 `kj123456`（已有库需手动改密）
2. **嵌入演示登录**：客户编号 + 密码 `123456`；按客户展示加价配置并查价（Cookie 会话，无需页面 Token）
3. **宿主 API 多租户**：按 Token 对应 `customer_id` 加价（如 `CUST_002`）
4. **预警中心增强**：中文根本原因、客户、地址、货物信息
5. **查价记录**（原「队列监控」）：最近 1000 条询价流水
6. **客户管理**：管理端新增客户、签发 API Key
7. **加价精度**：支持 0.01% 加价比例

---

## 数据库迁移（必做）

安装脚本会自动执行 `prisma migrate deploy`。本次新增迁移：

| 迁移目录 | 内容 |
|----------|------|
| `20260703100000_markup_percent_two_decimals` | 加价字段支持两位小数 |
| `20260703120000_host_customer_api_keys` | 客户表 + API Key 表 |
| `20260703140000_quote_query_log` | 查价审计流水表（最多 1000 条） |

**注意：不要**重新导入 `数据库/chajia.sql`，否则会清空生产数据。

---

## 零、开发机打包（Windows）

```powershell
cd X:\work\chajia
powershell -ExecutionPolicy Bypass -File deploy\pack-server-upload.ps1
```

生成目录：

```
上传到服务器/
├── README.md
├── RELEASE-NOTES.md       ← 本文件（操作步骤）
├── 辅助脚本/
├── 代码/                  ← 上传此目录全部内容
└── 数据库/                ← 本次更新不必导入
```

将整个 **`上传到服务器`** 打成 zip 上传到服务器。

---

## 一、服务器更新步骤（场景 B：已有旧版）

### 1. 备份（强烈建议）

```bash
cd /home/project/chajia
cp .env .env.backup.$(date +%Y%m%d)
```

### 2. 上传代码

用 zip 解压后的 **`代码/`** 覆盖 `/home/project/chajia/`。

**不要上传或覆盖：**

- `.env`（服务器已有配置）
- `node_modules/`
- `.next/`

### 3. 检查 `.env`（通常无需修改）

确认以下项仍存在且正确即可：

```env
DATABASE_URL=mysql://chajia:密码@host.docker.internal:3306/chajia
JWT_SECRET=...
HOST_SERVICE_TOKENS=...
CUSTOMER_REGISTRY=...
RPA_MOCK_MODE=false
```

**不要**设置 `RPA_BROWSER_CHANNEL=chrome`（Docker Worker 无系统 Chrome）。

本次**无新增必填环境变量**。可删除（已不再使用）：

```env
NEXT_PUBLIC_EMBED_DEMO_SERVICE_TOKEN=...
NEXT_PUBLIC_EMBED_DEMO_CUSTOMER_ID=...
```

可选：自定义嵌入演示密码（默认 `123456`）

```env
EMBED_DEMO_PASSWORD=123456
```

### 已有服务器：管理员改密

若 `admin_demo` 仍为旧密码 `Demo@123`，请在管理端改密，或在 MySQL 更新 `admin_user.password_hash`（新装 seed 默认为 `kj123456`）。

### 4. 执行安装（构建 + 迁移 + 重启）

```bash
cd /home/project/chajia
test -f .env && echo "OK: .env exists" || { echo "ERROR: 缺少 .env"; exit 1; }

chmod +x deploy/install-bt-host-mysql.sh
bash deploy/install-bt-host-mysql.sh
```

约 **5～15 分钟**。脚本会：

1. `docker compose build`（next-app + rpa-worker + scheduler）
2. 启动容器
3. **`npx prisma migrate deploy`**（执行上述 3 条迁移）
4. 健康检查

### 5. 确认服务状态

```bash
COMPOSE="docker compose --env-file .env -f deploy/docker-compose.bt-host-mysql.yml"
$COMPOSE ps
```

应看到 **next-app、rpa-worker、scheduler、redis** 均为 **Up**。

```bash
curl -I http://127.0.0.1:30325
```

### 5. 清空 Redis 缓存（建议）

```bash
COMPOSE="docker compose --env-file .env -f deploy/docker-compose.bt-host-mysql.yml"
$COMPOSE exec redis redis-cli FLUSHDB
```

---

## 二、部署后验收

### 管理端

| 检查项 | 地址 / 操作 |
|--------|-------------|
| 管理端登录 | `/login`，`admin_demo` / `kj123456`（已有库可能仍为旧密码） |
| 嵌入演示 | `/embed-demo`，`CUST_002` / `123456` — 应显示 CUST_002 加价配置 |
| 预警中心 | `/admin/alerts` — 中文根因、客户、地址、货物 |
| 查价记录 | `/admin/queues` — 提交询价后有新行 |
| 客户管理 | `/admin/customers` — 可新增客户、轮换 Key |

### 询价回归

```bash
export CHAJIA_BASE_URL="http://你的IP:端口"
export CHAJIA_SERVICE_TOKEN="你的token"
export CHAJIA_CUSTOMER_ID="CUST_001"
bash 辅助脚本/test-denver-boston.sh
```

或在浏览器打开 `/embed-demo`，用客户编号登录后完成一次询价。

### 迁移是否成功

```bash
COMPOSE="docker compose --env-file .env -f deploy/docker-compose.bt-host-mysql.yml"
$COMPOSE exec next-app npx prisma migrate status
```

应显示 **Database schema is up to date**。

---

## 三、本次变更文件清单（供排查）

| 类别 | 主要路径 |
|------|----------|
| 数据库 | `prisma/schema.prisma`，迁移 `202607031*` |
| 查价审计 | `modules/quote/query-log.ts`，`app/api/admin/query-logs/` |
| 预警展示 | `modules/alert/alert-presentation.ts`，`app/admin/alerts/` |
| 查价记录页 | `app/admin/queues/page.tsx` |
| 导航 | `components/layout/admin-layout.tsx`，`app/dashboard/page.tsx` |
| 客户管理 | `app/admin/customers/`，`modules/customer/` |
| 全链路挂钩 | `orchestrator.ts`，`job-handler.ts`，`fallback-orchestrator.ts`，`timeout-sweeper.ts` |

---

## 四、常见问题

| 现象 | 处理 |
|------|------|
| 构建报 `node:crypto` / `UnhandledSchemeError` | 已修复：middleware 改用 `service-token-env.ts`；请用**本包最新代码**重建 |
| 查价记录为空 | 迁移后**新提交的询价**才会写入；旧数据无回溯 |
| 预警详情仍像 JSON | 确认 next-app 已重建；有 `quote_id` 的预警会关联报价单补全 |
| `prisma migrate` 失败 | 查 MySQL 权限；勿手动改表后与迁移冲突 |
| 嵌入演示登录失败 | 确认客户编号存在于 DB 或 `CUSTOMER_REGISTRY`；密码默认 `123456` |
| 嵌入演示查价 401 | 确认已登录；middleware 使用 `embed_demo_session` Cookie |
| 构建 OOM | 服务器建议 4GB+ 内存；单独 build：`$COMPOSE build next-app` |

---

## 五、回滚

```bash
# 还原代码备份后
bash deploy/install-bt-host-mysql.sh
```

数据库迁移**不建议**回滚；若必须，请在 DBA 协助下操作。