pqs-9100_client/doc/开发者指南_自己动手修改.md

开发者指南 - 自己动手修改代码

本指南说明我帮您创建的所有文件、它们的作用，以及如何自己修改和调试。

---

📁 我创建的文件清单

1. 核心脚本（scripts/ 目录）

scripts/port-checker.js - 端口检测工具

作用：检测端口是否可用，找到可用端口 关键方法：

PortChecker.checkPort(3306)           // 检查单个端口
PortChecker.findAvailablePort(3306)   // 从3306开始找可用端口
PortChecker.waitForPort(3306)         // 等待端口开始监听

如何修改：

• 修改端口检测范围：改 maxAttempts 参数（默认100）
• 修改超时时间：改 waitForPort 的 timeout 参数（默认30秒）

调试方法：

// 单独测试
const PortChecker = require('./port-checker');
PortChecker.checkPort(3306).then(console.log);

---

scripts/startup-manager.js - 启动状态管理器

作用：管理Loading窗口，显示启动进度 关键方法：

startupManager.createLoadingWindow()       // 创建Loading窗口
startupManager.updateProgress('init')      // 更新进度
startupManager.showError('错误信息')       // 显示错误
startupManager.closeLoadingWindow()        // 关闭Loading窗口

如何修改启动步骤： 在构造函数中修改 this.steps 数组：

this.steps = [
  { id: 'init', label: '正在初始化应用...', progress: 0 },
  { id: 'check-mysql-port', label: '正在检测MySQL端口...', progress: 15 },
  // ... 添加或修改步骤
];

调试方法：

// 在 lifecycle.js 中添加日志
console.log('[StartupManager] Current step:', this.getCurrentStep());

---

scripts/config-generator.js - 配置文件生成器

作用：根据实际路径和端口生成Spring Boot配置文件 关键方法：

configGenerator.generateConfig({
  mysqlPort: 3306,
  javaPort: 18092
})

如何修改数据目录位置： 修改 getDataPath 方法：

getDataPath(baseDir) {
  const driveLetter = path.parse(baseDir).root;
  // 改成你想要的路径
  return path.join(driveLetter, 'YourCustomPath');
}

如何添加更多占位符：

1. 在 application.yml.template 中添加占位符：{{YOUR_PLACEHOLDER}}
2. 在 generateConfig 方法中添加替换逻辑：

template = template.replace(/{{YOUR_PLACEHOLDER}}/g, yourValue);

调试方法：

// 单独测试
const ConfigGenerator = require('./scripts/config-generator');
const gen = new ConfigGenerator();
gen.generateConfig({ mysqlPort: 3307 }).then(console.log);

---

scripts/mysql-service-manager.js - MySQL 进程管理器（绿色包 - 进程模式）

作用：以进程模式管理 MySQL，无需管理员权限，随应用启动/关闭 核心方法：

// 主要方法：
ensureServiceRunning()              // 确保 MySQL 运行（主流程）
startMySQLProcess(port)             // 启动 MySQL 进程
stopMySQLProcess()                  // 停止 MySQL 进程
checkAndKillOrphanProcess()         // 清理残留进程
isMySQLRunning()                    // 检查进程是否运行

如何修改 my.ini 配置： 在 generateMyIni 方法中修改配置模板：

generateMyIni(port) {
  const config = `[mysqld]
basedir=${basedir}
datadir=${datadir}
port=${port}
bind-address=0.0.0.0
character-set-server=utf8mb4
max_connections=500              # 修改最大连接数
innodb_buffer_pool_size=256M     # 修改缓冲池大小
`;
  // ...
}

如何修改启动参数： 在 startMySQLProcess 方法中修改 spawn 参数：

this.mysqlProcess = spawn(mysqldPath, [
  `--defaults-file=${this.configFile}`,
  '--console',
  '--skip-grant-tables',  // 添加跳过权限检查（仅用于调试）
], {
  cwd: this.binPath,
  stdio: ['ignore', 'pipe', 'pipe']
});

调试方法：

// 单独测试
const MySQLServiceManager = require('./scripts/mysql-service-manager');
const mysql = new MySQLServiceManager();
mysql.ensureServiceRunning(
  (startPort, maxAttempts) => startPort,  // Mock port checker
  (port, timeout) => Promise.resolve(true)
).then(port => {
  console.log('MySQL started on port:', port);
});

---

scripts/java-runner.js - Java 运行器

作用：运行Spring Boot JAR文件 关键修改：

// 我添加的：
runSpringBoot(jarPath, configPath)   // 运行Spring Boot
stopSpringBoot()                      // 停止Spring Boot

如何添加JVM参数： 在 runSpringBoot 方法中修改 javaArgs：

const javaArgs = [
  '-Xms512m',                    // 最小堆内存
  '-Xmx1024m',                   // 最大堆内存
  '-Dfile.encoding=UTF-8',       // 文件编码
  '-jar',
  jarPath,
  `--spring.config.location=${configPath}`
];

调试方法：

// 单独测试
const JavaRunner = require('./scripts/java-runner');
const runner = new JavaRunner();
runner.runSpringBoot('path/to/jar', 'path/to/config');

---

2. 生命周期管理

electron/preload/lifecycle.js - 核心启动流程

作用：协调整个启动流程 关键流程：

ready() -> startApplication() -> {
  1. 检测MySQL端口
  2. 启动MySQL
  3. 检测Java端口
  4. 生成配置文件
  5. 启动Spring Boot
}

如何修改启动顺序： 在 startApplication 方法中调整步骤顺序或添加新步骤：

async startApplication() {
  // 步骤1: 初始化
  this.startupManager.updateProgress('init');
  
  // 添加你的自定义步骤
  this.startupManager.updateProgress('custom-step');
  await this.yourCustomFunction();
  
  // 继续原有步骤...
}

如何修改超时时间：

// MySQL等待超时
const mysqlReady = await PortChecker.waitForPort(actualPort, 30000); // 改这里

// Java等待超时
const javaReady = await PortChecker.waitForPort(this.javaPort, 60000); // 改这里

调试方法： 在关键位置添加日志：

logger.info('[lifecycle] 当前步骤:', stepName);
console.log('[DEBUG] 端口:', this.mysqlPort, this.javaPort);

---

3. UI 界面

public/html/loading.html - Loading 界面

作用：显示启动进度的美观界面

如何修改样式： 修改 <style> 标签内的CSS：

/* 修改背景颜色 */
.loading-container {
  background: linear-gradient(135deg, #your-color-1 0%, #your-color-2 100%);
}

/* 修改进度条颜色 */
.progress-bar {
  background: linear-gradient(90deg, #your-color 0%, #your-color 100%);
}

如何修改文字内容： 修改 <div> 标签内的文字：

<div class="logo">您的应用名称</div>
<div class="subtitle">您的公司名称</div>

如何添加更多显示信息：

1. 在HTML中添加元素：

<div class="custom-info" id="customInfo"></div>

2. 在JavaScript中更新：

ipcRenderer.on('startup-progress', (event, data) => {
  if (data.customData) {
    document.getElementById('customInfo').textContent = data.customData;
  }
});

---

4. 配置文件

build/extraResources/java/application.yml.template - 配置模板

作用：Spring Boot配置文件模板，运行时生成实际配置

占位符说明：

• {{APP_DATA_PATH}} - 会被替换为实际数据目录路径
• localhost:3306 - 会被替换为实际MySQL端口
• port: 18092 - 会被替换为实际Java端口

如何添加新的配置项：

1. 在模板中添加配置：

your-config:
  value: {{YOUR_VALUE}}

2. 在 config-generator.js 中添加替换：

template = template.replace(/{{YOUR_VALUE}}/g, yourActualValue);

---

🔧 常见修改场景

场景1：修改端口检测起始值

文件：electron/preload/lifecycle.js

修改：

// 原代码
this.mysqlPort = await PortChecker.findAvailablePort(3306, 100);

// 改为从3310开始
this.mysqlPort = await PortChecker.findAvailablePort(3310, 100);

---

场景2：修改数据目录位置

文件：scripts/config-generator.js

修改：

getDataPath(baseDir) {
  // 原代码：使用盘符根目录
  // const driveLetter = path.parse(baseDir).root;
  // return path.join(driveLetter, 'NPQS9100_Data');
  
  // 改为：使用应用同级目录
  return path.join(baseDir, 'Data');
  
  // 或者：使用固定路径
  return 'C:\\MyCustomPath\\Data';
}

---

场景3：修改Loading步骤

文件：scripts/startup-manager.js

修改：

this.steps = [
  { id: 'init', label: '正在初始化应用...', progress: 0 },
  { id: 'check-env', label: '正在检测环境...', progress: 10 },  // 新增
  { id: 'check-mysql-port', label: '正在检测MySQL端口...', progress: 20 },
  // ... 调整其他步骤的进度值
];

然后在 lifecycle.js 中调用：

this.startupManager.updateProgress('check-env');
await this.checkEnvironment();  // 你的自定义方法

---

场景4：修改MySQL进程配置（绿色包 - 进程模式）

文件：scripts/mysql-service-manager.js

修改 my.ini 配置（推荐方式）：

generateMyIni(port) {
  const config = `[mysqld]
basedir=${basedir}
datadir=${datadir}
port=${port}

# 网络配置
bind-address=0.0.0.0
max_connections=1000              # 增加最大连接数

# 性能优化
innodb_buffer_pool_size=256M      # 设置缓冲池大小
innodb_log_file_size=128M         # 增加日志文件大小

# 日志配置
log-error=mysql_error.log         # 错误日志
slow_query_log=1                  # 开启慢查询日志
slow_query_log_file=slow.log
long_query_time=2                 # 慢查询阈值2秒
`;
  // ...
}

注意：不要直接修改 spawn 参数，而是通过 my.ini 配置文件控制 MySQL 行为

---

场景5：修改JVM内存

文件：scripts/java-runner.js

修改：

runSpringBoot(jarPath, configPath, options = {}) {
  const javaArgs = [
    '-Xms1024m',        // 最小堆内存 1GB
    '-Xmx2048m',        // 最大堆内存 2GB
    '-XX:+UseG1GC',     // 使用G1垃圾回收器
    '-jar',
    jarPath,
    `--spring.config.location=${configPath}`
  ];
  // ... rest of code
}

---

🐛 调试技巧

1. 查看日志

日志位置：

C:\Users\[用户名]\AppData\Roaming\NQPS9100\logs\
├── 9100-YYYYMMDD.log          # 应用日志
├── 9100-core-YYYYMMDD.log     # 核心日志
└── 9100-error-YYYYMMDD.log    # 错误日志

如何添加日志：

const { logger } = require('ee-core/log');

logger.info('[YourModule] 信息日志');
logger.warn('[YourModule] 警告日志');
logger.error('[YourModule] 错误日志');

---

2. 开发环境测试

启动开发模式：

npm run dev

这样修改代码后可以立即看到效果，无需打包。

---

3. 单独测试模块

创建测试文件 test-my-module.js：

const PortChecker = require('./scripts/port-checker');

async function test() {
  console.log('测试端口检测...');
  const port = await PortChecker.findAvailablePort(3306);
  console.log('可用端口:', port);
}

test();

运行测试：

node test-my-module.js

---

4. 调试Loading界面

单独打开Loading页面：

# 在浏览器中直接打开
start public/html/loading.html

模拟进度更新： 在浏览器控制台中：

// 模拟进度更新
const event = new CustomEvent('startup-progress');
const data = { progress: 50, label: '测试进度...' };
// 需要调整代码来测试

---

📚 文件依赖关系

electron/preload/lifecycle.js (启动入口)
    ↓ 调用
├── scripts/startup-manager.js (显示Loading)
│       ↓ 使用
│   public/html/loading.html (Loading界面)
│
├── scripts/port-checker.js (检测端口)
│
├── scripts/mysql-service-manager.js (MySQL服务管理)
│
├── scripts/config-generator.js (生成配置)
│       ↓ 读取
│   build/extraResources/java/application.yml.template
│
└── scripts/java-runner.js (启动Java)

---

🎯 快速修改检查清单

修改代码后，检查这些点：

• 语法是否正确（运行 npm run dev 检查）
• 路径是否正确（注意 Windows 反斜杠）
• 日志是否添加（方便调试）
• 错误处理是否完善（try-catch）
• 注释是否清晰（方便后续维护）

---

💡 开发建议

1. 先在开发模式测试

   • 修改代码 → npm run dev → 测试
   • 确认没问题后再打包

2. 保留备份

   • 修改前备份原文件
   • 使用 Git 版本控制

3. 逐步修改

   • 一次只改一个功能
   • 改完测试，确认无误再继续

4. 参考现有代码

   • 我写的代码都有详细注释
   • 可以参考修改

5. 善用日志

   • 关键位置都加日志
   • 出问题时方便定位

---

📞 代码位置速查

功能	文件	行数范围
端口检测	scripts/port-checker.js	全文
启动管理	scripts/startup-manager.js	全文
MySQL服务管理	scripts/mysql-service-manager.js	核心方法 ensureServiceRunning
Java启动	scripts/java-runner.js	152-198
配置生成	scripts/config-generator.js	38-83
启动流程	electron/preload/lifecycle.js	27-159
Loading界面	public/html/loading.html	全文

---

南京灿能电气自动化有限公司 2025-10-15