# Users + Admins 表合并设计文档

**日期**: 2026-05-13
**状态**: 已定稿，待实施

## 1. 背景

当前系统使用两张独立的认证表：
- `users` — 小程序用户（家长/孩子/规划师），加密算法 `xzyj_salt_` + MD5
- `admins` — Web管理端用户（管理员/规划师），加密算法 `xzyj_admin_salt_` + MD5

规划师需要在小程序端和 Web 管理端同时使用，但两套认证体系导致：
- 规划师审核通过时需同步创建 admins 记录（`AdminController.guide/approve`）
- 密码不同步，规划师需要两套密码
- 扩展新角色需要同时修改两套系统

## 2. 目标

将 admins 表的功能合并到 users 表，统一认证体系，废弃 admins 表。

## 3. 设计方案（4个模块）

### Module 1: 数据模型合并

#### users 表新增字段
```sql
-- 迁移SQL (DatabaseInitializer)
ALTER TABLE users ADD COLUMN username VARCHAR(50) COMMENT '登录用户名（兼容admins迁移）';
ALTER TABLE users ADD COLUMN status VARCHAR(20) DEFAULT 'active' COMMENT '账号状态: active/inactive/actived';
ALTER TABLE users ADD INDEX idx_username (username);

-- status 字段说明:
--   active   - 正常（小程序用户默认）
--   actived  - 已激活（规划师设置密码后）
--   inactive - 已禁用
```

#### User.java 实体新增字段
```java
private String username;  // 登录用户名
private String status;    // 账号状态: active/inactive/actived
```

#### 数据迁移逻辑 (DatabaseInitializer.runMigrations)
```text
遍历 admins 表所有记录：
  1. 按 phone 查询 users 表
  2. 如果 phone 已存在 users 中：
     - 更新 role（如果 admins.role=teacher 且 users 是 parent，添加 teacher 角色）
     - 设置 password（用 xzyj_salt_ + MD5 重新加密）
     - 设置 username = admins.username（如果有）
     - 设置 status = active
  3. 如果 phone 不存在 users 中：
     - 在 users 表创建新用户
     - 设置必要字段（phone, username, password, role, status）
     - 不创建家庭（admins 没有家庭概念）
  4. 跳过没有 phone 的 admins 记录
```

**注意**: admins 表不删除，仅停止使用，保留作为回滚备份。

### Module 2: Web登录重建

#### AdminAuthController 重构
- 将 `AdminMapper` 替换为 `UserMapper`
- 所有查询从 `admins` 表改为 `users` 表
- 加密算法从 `xzyj_admin_salt_` + MD5 改为 `xzyj_salt_` + MD5（与 UserService 一致）
- `loginByPassword` 改为用 phone 查询 users 表，支持 teacher 角色
- 登录时检测 `status = inactive` → 账号被禁用
- 登录时检测 `role=teacher && password 为空/未设置` → 返回特殊标识让前端提示设置密码

#### 删除文件
- `Admin.java` 实体类
- `AdminMapper.java` Mapper 接口

#### AdminController 调整
- 移除 `@Resource AdminMapper` 注入
- `guide/approve` 方法：删除同步创建/更新 admins 表的逻辑，审核通过直接更新 User 即可
- 检查其他引用 `AdminMapper` 或 `Admin` 的地方并清理

#### UserService 修复
- `resetPassword` 方法（第1021行）当前使用 `xzyj_user_` 加密算法，改为统一的 `xzyj_salt_` + MD5

### Module 3: 规划师首次密码创建

#### 触发场景
规划师审核通过后，登录 Web 管理端时：
1. Web 登录页输入手机号 + 密码
2. `AdminAuthController.loginByPassword` 查询 users 表
3. 检测到 `role=teacher && (password==null || password=="")`
4. 返回 `Result.error(400, "请先设置密码")` 附带 `needsSetup: true` 标识

#### 小程序端设置密码
1. 规划师在小程序 teacher-profile 页点击 "设置网页密码"
2. 输入新密码 + 确认密码
3. 调用后端 API `POST /api/auth/set-web-password`
4. 后端执行：
   - `UserService.setPassword(userId, newPassword)` — 用 `xzyj_salt_` + MD5 加密
   - `UserService.updateUserStatus(userId, "actived")` — 设置状态为已激活
5. 成功后规划师可用密码登录 Web 管理端

#### 新增后端 API
```java
// AuthController 或 AdminAuthController 新增
@PostMapping("/api/auth/set-web-password")
public Result<Boolean> setWebPassword(@RequestAttribute("userId") Long userId,
                                       @RequestBody Map<String, String> params) {
    // 1. 校验密码强度 (6位以上)
    // 2. 设置密码 (xzyj_salt_ + MD5)
    // 3. 设置 status = actived
    // 4. 返回成功
}
```

### Module 4: 规划师密码重置

#### 小程序端修改密码
1. 规划师在 teacher-profile 页 "修改网页密码"
2. 输入旧密码 + 新密码 + 确认新密码
3. 调用后端 API `POST /api/auth/reset-web-password`
4. 后端执行：
   - 校验旧密码是否正确
   - 设置新密码（`xzyj_salt_` + MD5 加密）
   - 状态保持不变

#### 新增后端 API
```java
// AuthController 或 AdminAuthController 新增
@PostMapping("/api/auth/reset-web-password")
public Result<Boolean> resetWebPassword(@RequestAttribute("userId") Long userId,
                                         @RequestBody Map<String, String> params) {
    // 1. 校验旧密码
    // 2. 设置新密码
    // 3. 返回成功
}
```

## 4. 加密算法统一

**统一算法**: `DigestUtils.md5DigestAsHex(("xzyj_salt_" + password).getBytes(StandardCharsets.UTF_8))`

| 位置 | 修改前 | 修改后 |
|------|--------|--------|
| AdminAuthController.encryptPassword (L271) | `xzyj_admin_salt_` + MD5 | `xzyj_salt_` + MD5 |
| UserService.encryptPassword (L749) | `xzyj_salt_` + MD5 | ✅ 不变 |
| UserService.resetPassword (L1021) | `xzyj_user_` + MD5 | `xzyj_salt_` + MD5 |

## 5. 影响范围

### 后端文件变更

| 文件 | 变更类型 | 说明 |
|------|----------|------|
| `entity/User.java` | 修改 | 新增 username, status 字段 |
| `entity/Admin.java` | 删除 | 废弃 |
| `mapper/AdminMapper.java` | 删除 | 废弃 |
| `controller/admin/AdminAuthController.java` | 重写 | UserMapper 替代 AdminMapper，统一加密 |
| `controller/admin/AdminController.java` | 修改 | 移除 AdminMapper 引用，清理同步逻辑 |
| `controller/auth/AuthController.java` | 修改 | 新增 set-web-password, reset-web-password 端点 |
| `service/UserService.java` | 修改 | 修复 resetPassword 算法，新增 setStatus 方法 |
| `config/DatabaseInitializer.java` | 修改 | 新增 username/status 迁移 + admins→users 数据迁移 |

### 前端文件变更

| 文件 | 变更类型 | 说明 |
|------|----------|------|
| `zxyj-frontend/pages/teacher/teacher-profile.vue` | 修改 | 拆分密码设置为首次设置和修改密码两个入口 |
| `zxyj-frontend/utils/api.js` | 修改 | 新增 set-web-password, reset-web-password API |

### Web端文件变更

| 文件 | 变更类型 | 说明 |
|------|----------|------|
| `zxyj-web/src/views/Login.vue` | 无需修改 | AdminAuthController 端点不变(logic变化内部处理) |

## 6. 安全考虑

- 所有密码使用 MD5 + 固定 salt 传输（当前系统已有模式，暂不改 BCrypt 以保持兼容）
- 小程序端不存储明文密码
- Web 端密码传输使用 HTTPS（生产环境配置）

## 7. 回滚方案

- admins 表保留不删除，数据完整
- 如果合并后出现问题，可停止使用 users 表的新字段
- 钥匙管理器中有 DatabaseInitializer 中的迁移代码，重新部署会自动跳过