---
name: field-name-sync-from-old-db
overview: 创建可复用的字段名同步服务，从旧库 s_columnLib.col_Caption 同步到新库 s_module_field.b_name，按视图名和字段名匹配，首批执行 v_b_othercompany。
todos:
  - id: fix-old-db-ssl
    content: 修复 g3hd-old.properties：移除 sslProtocol=TLSv1 参数，JDK 21 驱动自动协商 TLSv1.2 即可连通
    status: completed
  - id: create-sync-service
    content: 新建 FieldNameSyncService.java：实现跨库 UPDATE SQL，按 viewName 匹配 s_columnLib，将 col_Caption 写入 s_module_field.b_name，不匹配字段不改动，返回更新行数
    status: completed
    dependencies:
      - fix-old-db-ssl
  - id: create-admin-controller
    content: 新建 AdminController.java，添加 POST /api/admin/sync-field-names 端点，JWT 认证，viewName 参数白名单校验，调用 FieldNameSyncService 并返回 ApiResponse
    status: completed
    dependencies:
      - create-sync-service
  - id: add-sql-migration-ref
    content: 新建 023_sync_field_names.sql 参考脚本，记录跨库同步 SQL 作为纯 SQL 手动执行备选方案
    status: completed
---

## 用户需求

构建一个可复用的工具，将旧库 `G3HY2025.dbo.s_columnLib` 中存储的字段中文名称（`col_Caption`）同步到新库 `fms.dbo.s_module_field.b_name`。

### 匹配规则

- `s_module.b_viewtable` = `s_columnLib.col_TableName`（模块视图名对应旧库表名）
- `s_module_field.b_field` = `s_columnLib.col_FieldName`（字段名精确匹配）
- 匹配不上的字段，`b_name` 保持不变

### 首批同步目标

视图 `v_b_othercompany`

### 可复用要求

以后还有更多视图需要同步，工具须参数化视图名，方便批量复用。

## 技术方案

### 方案选择：跨库 SQL + 管理端点

**核心决策**：新旧库在同一 SQL Server 实例（`118.89.70.199:1433`），使用**跨数据库 SQL** 直接从新库连接执行 `UPDATE ... FROM G3HY2025.dbo.s_columnLib`，无需单独连接旧库。

```sql
UPDATE sf
SET sf.b_name = LTRIM(RTRIM(sc.col_Caption))
FROM dbo.s_module_field sf
JOIN dbo.s_module m ON m.b_id = sf.b_module_id
JOIN G3HY2025.dbo.s_columnLib sc
  ON sc.col_TableName = m.b_viewtable
 AND sc.col_FieldName = sf.b_field
WHERE m.b_viewtable = ?
  AND sc.col_Caption IS NOT NULL
  AND LTRIM(RTRIM(sc.col_Caption)) != '';
```

**为何需要新端点而非复用通用端点**：

- 通用 `saveObjectApi` 只能操作当前 org 数据库的单表 insert/update/delete，无法表达跨库 JOIN 逻辑
- 通用 `loadDataApi` 只能查询当前 org 的表，无法读取旧库 `s_columnLib`
- 此操作为管理类批量数据同步，不在业务 CRUD 范畴内

### 实现架构

```mermaid
flowchart LR
    A[前端/管理员] -->|POST /api/admin/sync-field-names| B[AdminController]
    B -->|校验 viewName 参数| C[FieldNameSyncService]
    C -->|获取新库 Connection| D[OrgRoutingDataSource]
    D -->|fms 连接| E[(SQL Server)]
    E -->|跨库 JOIN| F[G3HY2025.dbo.s_columnLib]
    E -->|UPDATE| G[fms.dbo.s_module_field]
    C -->|返回同步数量| B
    B -->|ApiResponse| A
```

### 模块划分

| 模块 | 文件 | 职责 |
| --- | --- | --- |
| 配置修复 | `config/dbconfigs/g3hd-old.properties` | 移除 `sslProtocol=TLSv1` |
| 同步服务 | `service/FieldNameSyncService.java` | 执行跨库 UPDATE，校验参数，返回影响行数 |
| 管理控制器 | `controller/AdminController.java` | `POST /api/admin/sync-field-names` 端点，JWT 保护 |
| 参考脚本 | `config/migrations/023_sync_field_names.sql` | 纯 SQL 版本供手动执行 |


### 数据流

1. 前端/管理员发送 `POST /api/admin/sync-field-names`，请求体 `{ "viewName": "v_b_othercompany" }`
2. `AdminController` 校验 `viewName` 为合法标识符（字母/下划线/数字，最长128）
3. `FieldNameSyncService` 通过 `@Resource DataSource` 获取新库连接
4. 执行跨库 PreparedStatement UPDATE
5. 返回 `{ "updatedCount": 42, "message": "v_b_othercompany 同步完成，共更新 42 个字段名称" }`

### 安全措施

- `viewName` 参数：白名单正则 `^[A-Za-z_][A-Za-z0-9_]{0,127}，校验后作为 PreparedStatement 参数绑定（非字符串拼接）
- JWT 认证：`AdminController` 路径 `/api/admin/**` 经 `JwtAuthFilter` 保护，仅登录用户可调用
- 失败不影响现有数据：UPDATE 在一条 SQL 内执行，单条匹配失败不阻断其他行

### 执行说明

- **热路径**：单条 UPDATE SQL 跨库 JOIN，性能取决于 `s_module_field` 行数和索引；对单个视图（~50 字段）毫秒级完成
- **日志**：服务层记录同步开始/完成/失败日志，使用 `@Slf4j`，级别 INFO/ERROR
- **事务**：使用 Spring 声明式事务 `@Transactional`，确保整批同步原子提交或回滚
- **向后兼容**：不修改现有 `DataController` 和通用端点，不影响业务数据流

## Agent Extensions

### SubAgent

- **code-explorer**
- 目的：探索旧库连接方式、现有 Service/Controller 模式、参数校验惯例
- 预期结果：确认 `OrgDataSourceManager` 的 API 使用方式和现有异常处理/日志模式