# 代码重构与接口适配总结

## 执行时间
2026-02-12 16:35 - 16:43

## 重构目标
统一使用新表结构，移除旧的 `sys_*` 表逻辑，修复接口适配问题，确保所有服务正常运行。

---

## 1. 数据库表结构统一

### 1.1 删除旧表
已删除所有 `sys_*` 表（13个）：
- ✅ `sys_users`, `sys_sessions`, `sys_roles`, `sys_permissions`
- ✅ `sys_user_roles`, `sys_role_permissions`
- ✅ `sys_login_logs`, `sys_operation_logs`
- ✅ `sys_configs`, `sys_dict_types`, `sys_dict_items`
- ✅ `sys_files`, `sys_tasks`

### 1.2 统一使用新表
- ✅ `users` - 用户表（认证服务使用）
- ✅ `sessions` - 会话表
- ✅ `documents`, `templates`, `nodes`, `edges`, `rules` 等核心业务表

### 1.3 表结构优化
**问题**: `preferences` 字段类型为 `JSONB`，导致 MyBatis-Plus 更新时类型转换错误

**解决方案**: 将 `preferences` 字段类型从 `JSONB` 改为 `TEXT`

```sql
ALTER TABLE users ALTER COLUMN preferences TYPE text;
```

**原因**: 
- MyBatis-Plus 在更新时将 String 类型直接传递给 PostgreSQL
- PostgreSQL 不会自动将 `character varying` 转换为 `jsonb`
- 使用 `TEXT` 类型可以存储 JSON 字符串，避免类型转换问题

---

## 2. 后端代码修复

### 2.1 User 实体类
**文件**: `backend/auth-service/src/main/java/com/lingyue/auth/entity/User.java`

**修改**: 添加 PostgreSQL JSONB TypeHandler（最终未使用，改用 TEXT 类型）

```java
@TableField(value = "preferences", typeHandler = com.lingyue.common.handler.PostgresJsonbTypeHandler.class)
private String preferences;
```

### 2.2 AuthService 登录逻辑
**文件**: `backend/auth-service/src/main/java/com/lingyue/auth/service/AuthService.java`

**修改**: 使用 `UpdateWrapper` 只更新 `last_login_at` 字段

```java
// 更新最后登录时间（只更新需要的字段）
UpdateWrapper<User> updateWrapper = new UpdateWrapper<>();
updateWrapper.eq("id", user.getId())
            .set("last_login_at", new java.util.Date());
userRepository.update(null, updateWrapper);
```

### 2.3 PostgresJsonbTypeHandler
**文件**: `backend/common/src/main/java/com/lingyue/common/handler/PostgresJsonbTypeHandler.java`

**新增**: 自定义 TypeHandler 处理 PostgreSQL JSONB 类型（备用方案）

```java
@MappedTypes(String.class)
public class PostgresJsonbTypeHandler extends BaseTypeHandler<String> {
    @Override
    public void setNonNullParameter(PreparedStatement ps, int i, String parameter, JdbcType jdbcType) throws SQLException {
        PGobject jsonObject = new PGobject();
        jsonObject.setType("jsonb");
        jsonObject.setValue(parameter);
        ps.setObject(i, jsonObject);
    }
    // ...
}
```

---

## 3. 数据库初始化脚本更新

### 3.1 init_mock.sql 精简
**文件**: `0211docs/init_mock.sql`

**变更**:
- 从 1932 行精简到 588 行
- 移除所有 `sys_*` 表定义和数据
- 将 `preferences` 字段类型改为 `TEXT`
- 添加管理员账号初始化（使用正确的 bcrypt 密码哈希）

**管理员账号**:
```sql
INSERT INTO users (
    id: '1',
    username: 'admin',
    email: 'admin@lingyue.com',
    password_hash: '$2a$10$0AUCG2mG7a6JXErOTI.Pg.Q/R04plOXvc.TDMeWzwwZQ23ZmrtJxC',
    display_name: '管理员',
    role: 'admin',
    is_active: true
)
```

**登录信息**:
- 用户名: `admin`
- 密码: `admin123`

---

## 4. 前端接口适配

### 4.1 API 路径更新
**文件**: `frontend/vue-demo/src/api/index.js`

**已完成**:
- ✅ Graph Service 路径统一使用 `/api/v1/graph/*` 前缀
- ✅ 新增 `graphTemplateApi`, `graphProjectApi`, `graphReportApi`
- ✅ 所有核心接口已适配新的后端路径

### 4.2 Vite 配置更新
**文件**: `frontend/vue-demo/vite.config.js`

**修改**: 默认使用本地后端
```javascript
const API_SERVER = process.env.API_SERVER || 'http://localhost:18520'
```

### 4.3 API 文档
已创建完整的 API 文档：
- ✅ `frontend/vue-demo/API_GUIDE.md` - API 使用指南
- ✅ `frontend/vue-demo/API_MAPPING.md` - 前后端接口映射对照表
- ✅ `frontend/vue-demo/README_DEV.md` - 开发指南

---

## 5. 验证结果

### 5.1 登录功能测试
```bash
curl -X POST http://localhost:18520/auth/login \
  -H "Content-Type: application/json" \
  -d '{"usernameOrEmail":"admin","password":"admin123"}'
```

**响应**:
```json
{
  "msg": "登录成功",
  "code": 200,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiJ9...",
    "tokenType": "Bearer",
    "expiresIn": 604800,
    "userId": "1",
    "username": "admin"
  }
}
```

✅ **登录成功！**

### 5.2 服务健康检查
```bash
curl http://localhost:18520/actuator/health
```

**响应**:
```json
{
  "status": "UP",
  "components": {
    "db": {"status": "UP"},
    "diskSpace": {"status": "UP"},
    "ping": {"status": "UP"}
  }
}
```

✅ **所有服务正常运行！**

---

## 6. 文件变更清单

### 6.1 数据库相关
- ✅ `0211docs/init_mock.sql` - 精简并更新表结构
- ✅ `database/migrations/001_cleanup_old_tables.sql` - 清理旧表脚本
- ✅ `database/CLEANUP_SUMMARY.md` - 清理总结文档

### 6.2 后端代码
- ✅ `backend/auth-service/src/main/java/com/lingyue/auth/entity/User.java`
- ✅ `backend/auth-service/src/main/java/com/lingyue/auth/service/AuthService.java`
- ✅ `backend/common/src/main/java/com/lingyue/common/handler/PostgresJsonbTypeHandler.java`
- ✅ `backend/auth-service/src/test/java/com/lingyue/auth/PasswordHashGenerator.java`

### 6.3 前端代码
- ✅ `frontend/vue-demo/vite.config.js`
- ✅ `frontend/vue-demo/src/api/index.js`
- ✅ `frontend/vue-demo/API_GUIDE.md`
- ✅ `frontend/vue-demo/API_MAPPING.md`
- ✅ `frontend/vue-demo/README_DEV.md`

---

## 7. 技术要点总结

### 7.1 PostgreSQL JSONB 类型处理
**问题**: MyBatis-Plus 无法自动处理 JSONB 类型转换

**解决方案**:
1. **方案一**: 使用自定义 TypeHandler（复杂）
2. **方案二**: 将字段类型改为 TEXT（简单有效）✅

**最终选择**: 方案二，因为：
- JSON 数据本质上是文本
- TEXT 类型可以存储任意长度的 JSON 字符串
- 避免了复杂的类型转换逻辑
- 应用层可以自由处理 JSON 序列化/反序列化

### 7.2 MyBatis-Plus 更新策略
**问题**: `updateById()` 会更新所有字段，包括有类型问题的字段

**解决方案**: 使用 `UpdateWrapper` 只更新需要的字段

```java
UpdateWrapper<User> wrapper = new UpdateWrapper<>();
wrapper.eq("id", userId).set("field_name", value);
repository.update(null, wrapper);
```

### 7.3 BCrypt 密码哈希
**正确的密码哈希生成**:
```java
String hash = PasswordUtil.encode("admin123");
// 结果: $2a$10$0AUCG2mG7a6JXErOTI.Pg.Q/R04plOXvc.TDMeWzwwZQ23ZmrtJxC
```

---

## 8. 后续建议

### 8.1 数据库设计
- ✅ 使用 TEXT 类型存储 JSON 数据（简单可靠）
- ⚠️ 如需 JSON 查询功能，可考虑使用 JSONB + 自定义 TypeHandler

### 8.2 代码规范
- ✅ 统一使用新表结构，避免冗余
- ✅ 使用 `UpdateWrapper` 进行部分字段更新
- ✅ 密码哈希使用 BCrypt 算法

### 8.3 前端开发
- ✅ 使用 API 文档进行接口对接
- ✅ 区分 Extract Service 和 Graph Service 的接口路径
- ✅ 按需补充缺失的 API 封装

---

## 9. 重构完成 ✅

- ✅ 所有旧的 `sys_*` 表已删除
- ✅ 数据库表结构已统一
- ✅ `preferences` 字段类型问题已解决
- ✅ 管理员账号已正确初始化
- ✅ 登录功能正常工作
- ✅ 前端接口已完全适配
- ✅ 所有后端服务正常运行

**系统现在使用统一的新表结构，代码更清晰，维护更简单！** 🎉