# 影子系统测试问题记录

> **测试环境**: 影子系统（端口 5320，数据库 `lobechat_stage`）  
> **测试日期**: 2025-12-27  
> **测试目标**: 用户状态管理和组织架构升级

---

## 📋 测试进度

- [ ] 阶段一：用户状态管理
- [ ] 阶段二：部门外键关联
- [ ] 阶段三：部门层级结构
- [ ] 阶段四：角色枚举扩展

---

## 🐛 问题记录

### 问题 #1: 迁移脚本类型错误 - status 字段查询 null

**发现时间**: 2025-12-27  
**测试阶段**: 构建阶段  
**严重程度**: 🟡 中

**问题描述**:
```
构建时 TypeScript 报错：Type 'null' is not assignable to type 'string | StringFilter<"User"> | undefined'
在 scripts/migrate-user-status.ts 和 scripts/verify-migration.ts 中
```

**复现步骤**:
1. 运行 `npm run build`
2. TypeScript 类型检查失败

**错误信息**:
```
Type error: Type 'null' is not assignable to type 'string | StringFilter<"User"> | undefined'.
```

**解决方案**:
```typescript
// 问题原因：status 字段在 Schema 中定义为 String @default("pending")
// Prisma 类型系统不允许查询 null 值，因为字段有默认值

// 修复方法1：在 migrate-user-status-safe.ts 中
// 修改前（错误）：
const nullStatusUsers = await prisma.user.count({ 
  where: { status: null }  // ❌ 类型错误
});

// 修改后（正确）：
const nullStatusUsers = await prisma.user.count({ 
  where: { status: '' }  // ✅ 只检查空字符串
});

// 修复方法2：在 verify-migration.ts 中
// 同样移除 status: null 的查询，改为检查空字符串
// 因为 status 字段有默认值 'pending'，所以不会有 null 值
```

**实施步骤**:
1. 修改 `scripts/migrate-user-status-safe.ts`，移除所有 `status: null` 查询
2. 修改 `scripts/verify-migration.ts`，移除所有 `status: null` 查询
3. 重新运行 `npm run build` 验证类型错误已修复

**正式系统改造注意事项**:
- ✅ 此问题已在代码中修复，正式系统不会遇到
- ✅ 迁移脚本使用 `migrate-user-status-safe.ts`（已修复版本）
- ✅ 验证脚本已更新，不会查询 null 值

**相关文件**:
- `scripts/migrate-user-status-safe.ts` (已修复)
- `scripts/verify-migration.ts` (已修复)

**状态**: ✅ 已解决

---

### 问题 #2: 验证脚本类型错误 - 阶段三和阶段四字段不存在

**发现时间**: 2025-12-27  
**测试阶段**: 构建阶段  
**严重程度**: 🟡 中

**问题描述**:
```
构建时 TypeScript 报错：阶段三的 level 字段和阶段四的 DEPT_ADMIN/SYSTEM_ADMIN 角色不存在
这些是未来阶段的字段，当前 Schema 中还没有
```

**复现步骤**:
1. 运行 `npm run build`
2. TypeScript 类型检查失败

**错误信息**:
```
Type error: Object literal may only specify known properties, and 'level' does not exist
Type error: Type '"DEPT_ADMIN"' is not assignable to type 'Role | EnumRoleFilter<"User"> | undefined'
```

**解决方案**:
```typescript
// 问题原因：阶段三和阶段四的字段（level, DEPT_ADMIN, SYSTEM_ADMIN）尚未添加到 Schema
// 但验证脚本尝试验证这些字段，导致 TypeScript 类型错误

// 修复方法：使用原生 SQL 查询检查字段是否存在
// 如果字段不存在，跳过验证（这是正常的，因为阶段三和阶段四尚未实施）

// 示例代码（verify-migration.ts）：
async function verifyStage3(): Promise<VerificationResult> {
  // 先检查字段是否存在
  const hasLevelField = await prisma.$queryRaw<Array<{column_name: string}>>`
    SELECT column_name 
    FROM information_schema.columns 
    WHERE table_name = 'departments' 
    AND column_name = 'level'
  `.then(result => result.length > 0).catch(() => false);
  
  if (!hasLevelField) {
    // 字段不存在，跳过验证（正常情况）
    return {
      stage: '阶段三：部门层级结构',
      passed: true,
      issues: ['字段尚未实施，跳过验证'],
      stats: {}
    };
  }
  
  // 字段存在，继续验证...
}
```

**实施步骤**:
1. 修改 `scripts/verify-migration.ts` 中的阶段三和阶段四验证函数
2. 使用 `$queryRaw` 检查字段是否存在
3. 如果字段不存在，返回跳过验证的结果（不报错）
4. 重新运行 `npm run build` 验证类型错误已修复

**正式系统改造注意事项**:
- ✅ 此问题已在代码中修复，使用条件检查避免类型错误
- ✅ 当实施阶段三和阶段四时，字段存在后验证会自动生效
- ✅ 不会影响阶段一和阶段二的验证

**相关文件**:
- `scripts/verify-migration.ts` (已修复，使用条件检查)

**状态**: ✅ 已解决

---

### 问题 #3: 构建时 DATABASE_URL 警告（正常现象）

**发现时间**: 2025-12-27  
**测试阶段**: 构建阶段  
**严重程度**: 🟢 低（正常现象）

**问题描述**:
```
构建过程中出现大量 Prisma 错误：Environment variable not found: DATABASE_URL
这些错误出现在静态页面生成阶段（SSG）
```

**复现步骤**:
1. 运行 `npm run build`
2. 看到大量 `prisma:error Invalid prisma.* invocation: Environment variable not found: DATABASE_URL`

**错误信息**:
```
prisma:error Invalid `prisma.systemSettings.findFirst()` invocation:
error: Environment variable not found: DATABASE_URL
```

**解决方案**:
```
这是正常现象，因为：
1. Next.js 在构建时会尝试预渲染所有页面（SSG）
2. 某些页面在构建时调用了需要数据库的 API
3. 构建环境中没有 DATABASE_URL（这是正常的，因为构建时不需要数据库）

不影响运行时功能，因为：
- 运行时容器中会有 DATABASE_URL 环境变量
- 这些 API 路由是动态的（ƒ），不会在构建时执行
- 静态页面生成失败不影响动态路由

无需修复，这是 Next.js 的正常行为
```

**正式系统改造注意事项**:
- ✅ 这是 Next.js 的正常行为，无需担心
- ✅ 构建时的警告不影响运行时功能
- ✅ 生产环境部署时，容器中会有 DATABASE_URL 环境变量
- ✅ 如果希望消除警告，可以：
  1. 在构建时设置一个临时的 DATABASE_URL（不推荐）
  2. 将使用数据库的页面标记为动态渲染（使用 `export const dynamic = 'force-dynamic'`）
  3. 忽略这些警告（推荐，因为不影响功能）

**相关文件**:
- 所有使用 Prisma 的 API 路由和页面组件

**状态**: ✅ 已确认（正常现象，无需修复）

---

## ✅ 已解决问题总结

### 问题 #1: 迁移脚本类型错误 - status 字段查询 null
- **解决时间**: 2025-12-27
- **解决方案**: 移除 `status: null` 查询，改为检查空字符串
- **影响**: 已修复，不影响正式系统

### 问题 #2: 验证脚本类型错误 - 阶段三和阶段四字段不存在
- **解决时间**: 2025-12-27
- **解决方案**: 使用原生 SQL 查询检查字段是否存在，条件跳过验证
- **影响**: 已修复，不影响正式系统

### 问题 #3: 构建时 DATABASE_URL 警告
- **确认时间**: 2025-12-27
- **结论**: 正常现象，无需修复
- **影响**: 不影响功能，可忽略

---

## 📝 测试日志

### 2025-12-27

**测试内容**: 代码更新和部署到影子系统

**测试结果**:
- ✅ Schema 更新成功（阶段一和阶段二）
- ✅ 代码更新成功（双写双读实现）
- ✅ 构建成功（修复了类型错误）
- ✅ 部署成功（镜像已部署到影子系统）
- ⚠️ 构建时的 DATABASE_URL 警告（正常现象，不影响功能）

**下一步**:
1. ✅ 在影子系统运行数据库迁移（`npx prisma db push`）
2. ✅ 运行迁移脚本（阶段一和阶段二）
3. ⏳ 验证功能正常

**迁移执行记录**:
- ✅ 已创建迁移执行脚本：`scripts/run-migration-shadow.ps1`
- ✅ 已创建执行计划文档：`docs/migration-execution-plan.md`
- ✅ 数据库备份完成：`/tmp/lobechat_stage_backup_20251230_191343.dump` (332KB)
- ✅ Schema更新完成（数据库已同步）
- ✅ 阶段一迁移完成（177个用户，160个active，17个pending）
- ✅ 阶段二迁移完成（167个用户部门关联已迁移，18个部门）
- ✅ 所有验证通过

**执行时间**: 2025-12-30 19:13

**部署记录**:
- ✅ 代码已部署到影子系统（容器：youyidian-3d-shadow）
- ✅ 容器运行正常（端口：5320）
- ✅ 应用已启动（Ready in 116ms）
- ✅ 数据库查询正常（日志显示Prisma查询成功）

**访问地址**: http://192.168.58.20:5320

**单元测试记录** (2025-12-30):
- ✅ 镜像版本确认：使用最新镜像（创建时间：2025-12-30 19:18:12）
- ✅ 数据库连接测试：通过
- ✅ 用户状态字段检查：通过（所有用户都有status和isActive字段）
- ✅ 部门外键关联检查：通过（departmentId和departmentRef正确关联）
- ✅ 角色切换功能测试：通过（USER ↔ ADMIN切换正常）
- ✅ 状态切换功能测试：通过（active ↔ suspended切换正常）
- ✅ 双写逻辑验证：通过（status和isActive字段一致性检查通过）
- ✅ 数据统计：正常（177个用户，160个active，17个pending，18个部门）

---

## 🔍 待验证项

- [ ] 用户登录功能正常（需测试）
- [ ] 用户状态切换正常（需测试）
- [ ] 审计字段记录正常（需测试登录后检查lastLoginAt等字段）
- [ ] 部门关联查询正常（需测试用户列表API返回departmentRef字段）
- [ ] 权限检查逻辑正常（需测试权限相关功能）
- [ ] 前端显示正常（需访问影子系统测试UI）

**迁移完成后待测试功能**:
- 访问影子系统：http://192.168.58.20:5320
- 测试用户登录（验证审计字段更新）
- 测试管理员切换用户状态
- 测试用户列表API返回新字段
- 测试部门关联查询功能

---

---

## 📚 正式系统改造参考

### 关键经验总结

1. **类型安全**:
   - Prisma 类型系统严格，查询不存在的字段会报错
   - 使用条件检查或原生 SQL 查询来避免类型错误
   - 字段有默认值时，不会为 null，查询时注意

2. **迁移脚本设计**:
   - 所有迁移脚本都应该是幂等的（可重复执行）
   - 使用 `-safe` 后缀的脚本，包含安全检查
   - 迁移前自动检查 Schema 是否已更新

3. **验证策略**:
   - 分阶段验证，避免验证未实施的字段
   - 使用条件检查，字段不存在时跳过验证
   - 提供详细的验证报告和统计信息

4. **构建警告**:
   - Next.js 构建时的 DATABASE_URL 警告是正常现象
   - 不影响运行时功能，可以安全忽略
   - 如需消除，使用动态渲染标记

### 正式系统执行清单

执行迁移前：
- [ ] 备份生产数据库（必须！）
- [ ] 确认 Schema 已更新到最新版本
- [ ] 确认迁移脚本已修复所有已知问题
- [ ] 在影子系统完成测试验证

执行迁移时：
- [ ] 使用 `scripts/run-migration-shadow.ps1` 或类似脚本
- [ ] 按照 `docs/migration-execution-plan.md` 执行
- [ ] 每个步骤后验证结果

执行迁移后：
- [ ] 运行完整验证脚本
- [ ] 进行功能测试
- [ ] 检查数据一致性
- [ ] 更新本文档记录新问题（如有）

---

**最后更新**: 2025-12-27  
**文档用途**: 记录影子系统测试问题，为正式系统改造提供参考