合并账户库为单表

2026-04-17 10:18:13 +08:00
parent cc1a4538af
commit 4c6ca52e7e
24 changed files with 1285 additions and 377 deletions
--- a/docs/plans/backend/2026-04-14-backend-run-package-conventions-implementation.md
+++ b/docs/plans/backend/2026-04-14-backend-run-package-conventions-implementation.md
@@ -0,0 +1,94 @@
+# 2026-04-14 后端运行与打包约定实施记录
+
+## 1. 改动目标
+
+- 固化本地后端继续走 `ruoyi-admin.jar + 内嵌 Tomcat` 启动链路
+- 固化 `mvn -pl ruoyi-admin -am package -DskipTests` 同时产出 `jar` 与 `war`
+- 固化部署脚本统一消费 `ruoyi-admin.war`
+- 固化 `bin/restart_java_backend.sh` 默认跟随后端日志，并支持 `FOLLOW_LOGS=false`
+
+## 2. 实施内容
+
+### 2.1 Maven 打包链路
+
+涉及文件：
+
+- `ruoyi-admin/pom.xml`
+
+实施内容：
+
+- 保持 `ruoyi-admin` 的 `<packaging>jar</packaging>` 不变，确保本地运行仍使用可执行 `jar`
+- 为 `maven-war-plugin` 增加 `package` 阶段显式执行 `war` 目标，确保执行 `mvn -pl ruoyi-admin -am package -DskipTests` 时额外生成 `ruoyi-admin.war`
+- 保留 `spring-boot-maven-plugin repackage`，继续生成可执行 `ruoyi-admin.jar`
+
+### 2.2 本地后端重启脚本
+
+涉及文件：
+
+- `bin/restart_java_backend.sh`
+
+实施内容：
+
+- 新增 `FOLLOW_LOGS="${FOLLOW_LOGS:-true}"` 默认开关
+- `start`、`restart` 成功后默认执行 `tail -F` 持续输出后端日志
+- 当外部传入 `FOLLOW_LOGS=false` 时，仅启动后端，不进入日志跟随
+
+### 2.3 部署产物切换
+
+涉及文件：
+
+- `deploy/deploy-to-nas.sh`
+- `deploy/deploy.ps1`
+- `docker/backend/Dockerfile`
+
+实施内容：
+
+- 部署目录组装时由复制 `ruoyi-admin.jar` 改为复制 `ruoyi-admin.war`
+- Docker 后端镜像改为消费 `ruoyi-admin.war`
+- 保证部署脚本不再把 `ruoyi-admin.jar` 当作生产部署产物
+
+### 2.4 项目约定同步
+
+涉及文件：
+
+- `AGENTS.md`
+
+实施内容：
+
+- 补充本地运行、双产物打包、部署使用 `war`、`FOLLOW_LOGS` 开关等仓库级约定
+- 在 Build / Run / Test Commands 中补充主应用定向打包命令
+
+## 3. 验证记录
+
+### 3.1 脚本检查
+
+执行：
+
+```bash
+sh docs/tests/scripts/test-restart-java-backend.sh
+sh docs/tests/scripts/test-backend-package-and-deploy-conventions.sh
+```
+
+结果：
+
+- 两个脚本均通过
+
+### 3.2 Maven 双产物验证
+
+执行：
+
+```bash
+mvn -pl ruoyi-admin -am package -DskipTests
+```
+
+结果：
+
+- 构建成功
+- 生成 `ruoyi-admin/target/ruoyi-admin.jar`
+- 生成 `ruoyi-admin/target/ruoyi-admin.war`
+
+## 4. 结论
+
+- 本地开发链路继续保持 `jar + 内嵌 Tomcat`
+- 部署链路统一切换为 `war`
+- 后端重启脚本默认跟日志，且支持显式关闭
--- a/docs/plans/backend/2026-04-14-nas-tongweb-deploy-script-implementation.md
+++ b/docs/plans/backend/2026-04-14-nas-tongweb-deploy-script-implementation.md
@@ -0,0 +1,62 @@
+# 2026-04-14 NAS TongWeb 部署脚本实施记录
+
+## 1. 目标
+
+- 新增一套独立于 Docker 的 NAS 部署脚本
+- 部署链路固定使用 `ruoyi-admin.war`
+- 远端通过 `TongWeb` 自动部署目录发布应用，并使用 `stopserver.sh` / `startservernohup.sh` 重启服务
+
+## 2. 实施内容
+
+### 2.1 新增 TongWeb NAS 部署入口
+
+涉及文件：
+
+- `deploy/deploy-to-nas-tongweb.sh`
+
+实施内容：
+
+- 提供与现有 NAS 脚本一致的 SSH 连接参数风格
+- 默认执行 `mvn -pl ruoyi-admin -am package -DskipTests`
+- 本地仅校验并上传 `ruoyi-admin/target/ruoyi-admin.war`
+- 支持 `--dry-run` 预览参数
+
+### 2.2 新增 TongWeb 远端执行器
+
+涉及文件：
+
+- `deploy/remote-deploy-tongweb.py`
+
+实施内容：
+
+- 通过 SFTP 将 `war` 上传到 NAS 临时目录 `${remoteRoot}/backend/`
+- 远端复制 `war` 到 `${TONGWEB_HOME}/autodeploy/${appName}.war`
+- 清理 `${TONGWEB_HOME}/autodeploy/${appName}` 旧解压目录
+- 依次执行 `stopserver.sh`、`startservernohup.sh`
+
+### 2.3 新增脚本回归测试
+
+涉及文件：
+
+- `tests/deploy/test_deploy_to_nas_tongweb.py`
+
+实施内容：
+
+- 覆盖默认参数 `dry-run`
+- 覆盖自定义参数 `dry-run`
+- 校验部署入口已调用 `remote-deploy-tongweb.py`
+- 校验远端执行器包含 `autodeploy`、`stopserver.sh`、`startservernohup.sh`
+
+## 3. 验证命令
+
+```bash
+python3 -m pytest tests/deploy/test_deploy_to_nas_tongweb.py -q
+bash -n deploy/deploy-to-nas-tongweb.sh
+bash deploy/deploy-to-nas-tongweb.sh --dry-run
+```
+
+## 4. 说明
+
+- 默认 `TongWebHome` 取 `/opt/TongWeb`，可通过第 6 个位置参数或环境变量 `TONGWEB_HOME` 覆盖
+- 默认应用名为 `ruoyi-admin`，可通过第 7 个位置参数或环境变量 `APP_NAME` 覆盖
+- 本次只新增 `TongWeb` 后端部署链路，不改动现有 Docker NAS 部署脚本
--- a/docs/plans/backend/2026-04-15-lsfx-mock-server-ccdi-account-info-abnormal-account-columns-migration-implementation.md
+++ b/docs/plans/backend/2026-04-15-lsfx-mock-server-ccdi-account-info-abnormal-account-columns-migration-implementation.md
@@ -0,0 +1,26 @@
+# LSFX Mock Server `ccdi_account_info` 异常账户字段补迁移后端实施文档
+
+## 背景
+
+- `lsfx-mock-server` 上传接口 `/watson/api/project/remoteUploadSplitFile` 在写入 `ccdi_account_info` 时使用了 `is_self_account`、`trans_risk_level` 字段。
+- 当前开发库中的 `ccdi_account_info` 为历史表结构，不包含这两列，导致 `AbnormalAccountBaselineService.apply(...)` 执行 upsert 时依次抛出 `Unknown column 'is_self_account' in 'field list'`、`Unknown column 'trans_risk_level' in 'field list'`，上传接口直接返回 500。
+
+## 本次修改
+
+- 新增增量脚本 `sql/migration/2026-04-15-sync-ccdi-account-info-abnormal-account-columns.sql`。
+- 脚本以最短路径为已有 `ccdi_account_info` 表补齐异常账户同步当前必需的字段，并保持可重复执行：
+  - 使用 `information_schema.columns` 判断字段是否已存在
+  - 通过 `PREPARE / EXECUTE` 仅在缺列时执行 `ALTER TABLE`
+  - 补齐 `is_self_account` 与 `trans_risk_level`
+  - 列位置与当前写库 SQL 保持一致
+- 新增回归测试 `lsfx-mock-server/tests/test_schema_migration_scripts.py`，锁定该增量脚本必须存在且包含两条补列语句。
+
+## 验证
+
+- `python3 -m pytest /Users/wkc/Desktop/ccdi/ccdi/lsfx-mock-server/tests/test_schema_migration_scripts.py -q`
+- 使用 `bin/mysql_utf8_exec.sh` 执行增量脚本后，复查 `SHOW COLUMNS FROM ccdi_account_info`，确认存在 `is_self_account`、`trans_risk_level` 字段。
+
+## 影响范围
+
+- 仅影响 `lsfx-mock-server` 依赖的 `ccdi_account_info` 历史表结构补齐。
+- 不修改接口协议，不改动前端。
--- a/docs/plans/backend/2026-04-16-account-library-single-table-implementation.md
+++ b/docs/plans/backend/2026-04-16-account-library-single-table-implementation.md
@@ -0,0 +1,53 @@
+# 账户库双表合单表后端实施计划
+
+## 1. 目标
+
+将账户库由 `ccdi_account_info` + `ccdi_account_result` 双表结构收敛为单表 `ccdi_account_info`，迁移完成后删除旧表，同时保持现有账户库接口、字段名和前端交互不变。
+
+## 2. 实施范围
+
+- 数据库增量迁移脚本
+- 账户库后端实体、Mapper XML、服务层
+- 外部场景种子脚本
+- 账户库相关回归测试
+
+本次不调整前端页面、接口路径和接口字段名。
+
+## 3. 实施步骤
+
+### 3.1 数据库迁移
+
+1. 新增 `sql/migration/2026-04-16-merge-ccdi-account-result-into-info.sql`
+2. 在脚本中先校验 `ccdi_account_info.account_no` 无重复
+3. 为 `ccdi_account_info` 补齐分析字段
+4. 按 `account_no` 从 `ccdi_account_result` 回填数据
+5. 回填完成后删除 `ccdi_account_result`
+
+### 3.2 后端代码调整
+
+1. `CcdiAccountInfo` 实体吸收分析字段映射
+2. 删除 `CcdiAccountResult` 实体与 `CcdiAccountResultMapper`
+3. `CcdiAccountInfoMapper.xml` 去掉对 `ccdi_account_result` 的联表
+4. `CcdiAccountInfoServiceImpl` 去掉结果表双写逻辑
+5. 保持原有业务语义：
+   - `bankScope = EXTERNAL` 时补齐默认分析字段
+   - `bankScope != EXTERNAL` 时清空分析字段，避免误写
+
+### 3.3 配套脚本与测试
+
+1. 将 `2026-04-13` 外部账户场景种子脚本改为单表写入
+2. 新增 SQL 脚本文本断言测试
+3. 新增账户库服务层与 Mapper SQL 结构测试
+
+## 4. 验证要点
+
+- 迁移脚本包含“补字段、回填、删旧表”三步
+- 账户库列表/详情/导出查询均只读 `ccdi_account_info`
+- 行外账户保存分析字段
+- 行内账户清空分析字段
+- 外部场景种子脚本不再写入 `ccdi_account_result`
+
+## 5. 风险说明
+
+- 仓库当前 `ccdi-info-collection` 模块存在既有依赖缺失问题，可能影响常规 Maven 全量编译与测试执行
+- 本次需要将“账户库改动验证结果”和“仓库原有构建阻塞”分开记录
--- a/docs/reports/implementation/2026-04-16-account-library-single-table-implementation.md
+++ b/docs/reports/implementation/2026-04-16-account-library-single-table-implementation.md
@@ -0,0 +1,62 @@
+# 账户库双表合单表实施记录
+
+## 1. 本次实施内容
+
+### 1.1 单表模型收敛
+
+- 在 `CcdiAccountInfo` 中补齐以下分析字段映射：
+  - `is_self_account`
+  - `monthly_avg_trans_count`
+  - `monthly_avg_trans_amount`
+  - `trans_freq_type`
+  - `dr_max_single_amount`
+  - `cr_max_single_amount`
+  - `dr_max_daily_amount`
+  - `cr_max_daily_amount`
+  - `trans_risk_level`
+- 删除 `CcdiAccountResult` 实体与 `CcdiAccountResultMapper`
+
+### 1.2 查询与写入逻辑调整
+
+- `CcdiAccountInfoMapper.xml` 已移除 `ccdi_account_result` 联表
+- 账户库列表、详情、导出统一从 `ccdi_account_info` 读取分析字段
+- `CcdiAccountInfoServiceImpl` 已移除结果表双写逻辑
+- 新增单表分析字段处理规则：
+  - 行外账户默认补齐分析字段缺省值
+  - 行内账户统一清空分析字段
+
+### 1.3 数据迁移与种子脚本
+
+- 新增增量脚本：
+  - `sql/migration/2026-04-16-merge-ccdi-account-result-into-info.sql`
+- 更新外部场景种子脚本：
+  - `sql/migration/2026-04-13-seed-ccdi-account-info-external-scenarios.sql`
+- 种子脚本已改为直接写入 `ccdi_account_info`，不再依赖旧表
+
+### 1.4 测试补充
+
+- 新增 `CcdiAccountInfoServiceImplTest`
+- 新增 `CcdiAccountInfoMapperTest`
+- 新增 `CcdiAccountInfoMergeSqlTest`
+
+## 2. 验证记录
+
+### 2.1 已完成验证
+
+- `ccdi-project` 模块执行 `mvn -pl ccdi-project -DskipTests compile` 成功
+- 文件级检查确认：
+  - 账户库主链路代码已无 `CcdiAccountResult` / `accountResultMapper` 引用
+  - `CcdiAccountInfoMapper.xml` 已无 `ccdi_account_result` 联表
+  - 新增迁移脚本包含补字段、按 `account_no` 回填、删除旧表逻辑
+
+### 2.2 现存仓库阻塞
+
+- `ccdi-info-collection` 模块常规编译失败，失败原因为仓库已有依赖/类缺失，与本次账户库改动不直接相关
+- 典型阻塞包括：
+  - `com.ruoyi.common.annotation` 下若干注解类缺失
+  - 多个服务类依赖 `org.springframework.data.redis.core`，当前模块未解析
+  - 既有测试代码与当前依赖版本存在不一致
+
+## 3. 结论
+
+本次账户库已按方案完成“双表合单表”代码与 SQL 收敛，后续若要做完整 Maven 回归，需要先处理仓库当前已有的模块依赖与测试编译问题。
--- a/docs/tests/scripts/test-backend-package-and-deploy-conventions.sh
+++ b/docs/tests/scripts/test-backend-package-and-deploy-conventions.sh
@@ -0,0 +1,70 @@
+#!/bin/sh
+
+set -eu
+
+ROOT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")/../../.." && pwd)
+POM_FILE="$ROOT_DIR/ruoyi-admin/pom.xml"
+DEPLOY_SH="$ROOT_DIR/deploy/deploy-to-nas.sh"
+DEPLOY_PS1="$ROOT_DIR/deploy/deploy.ps1"
+DOCKERFILE="$ROOT_DIR/docker/backend/Dockerfile"
+TARGET_DIR="$ROOT_DIR/ruoyi-admin/target"
+
+echo "[检查] 后端打包必须同时产出 jar 与 war，部署脚本只能使用 war"
+
+if ! grep -Fq '<packaging>jar</packaging>' "$POM_FILE"; then
+    echo "失败: ruoyi-admin 仍需保持 jar 打包类型以支持本地内嵌 Tomcat 运行"
+    exit 1
+fi
+
+if ! grep -Fq '<goal>war</goal>' "$POM_FILE"; then
+    echo "失败: 未显式执行 war 打包目标"
+    exit 1
+fi
+
+if ! grep -Fq 'ruoyi-admin.war' "$DEPLOY_SH"; then
+    echo "失败: deploy-to-nas.sh 未改为使用 ruoyi-admin.war"
+    exit 1
+fi
+
+if grep -Fq 'ruoyi-admin.jar' "$DEPLOY_SH"; then
+    echo "失败: deploy-to-nas.sh 仍引用 ruoyi-admin.jar"
+    exit 1
+fi
+
+if ! grep -Fq 'ruoyi-admin.war' "$DEPLOY_PS1"; then
+    echo "失败: deploy.ps1 未改为使用 ruoyi-admin.war"
+    exit 1
+fi
+
+if grep -Fq 'ruoyi-admin.jar' "$DEPLOY_PS1"; then
+    echo "失败: deploy.ps1 仍引用 ruoyi-admin.jar"
+    exit 1
+fi
+
+if ! grep -Fq 'COPY backend/ruoyi-admin.war /app/ruoyi-admin.war' "$DOCKERFILE"; then
+    echo "失败: Dockerfile 未改为复制 ruoyi-admin.war"
+    exit 1
+fi
+
+if grep -Fq 'ruoyi-admin.jar' "$DOCKERFILE"; then
+    echo "失败: Dockerfile 仍引用 ruoyi-admin.jar"
+    exit 1
+fi
+
+echo "[检查] 执行 Maven 打包产物校验"
+(
+    cd "$ROOT_DIR"
+    mvn -pl ruoyi-admin -am package -DskipTests
+)
+
+if [ ! -f "$TARGET_DIR/ruoyi-admin.jar" ]; then
+    echo "失败: 未生成 $TARGET_DIR/ruoyi-admin.jar"
+    exit 1
+fi
+
+if [ ! -f "$TARGET_DIR/ruoyi-admin.war" ]; then
+    echo "失败: 未生成 $TARGET_DIR/ruoyi-admin.war"
+    exit 1
+fi
+
+echo "通过"