document-management/build/java-templates

========================================
DMS 文档管理系统 - 使用说明（Java 版）
========================================

【系统要求】
- JDK 17+（或 JRE 17+）：需在 PATH 中可用 java 命令
- MySQL 8.x（自备，需自行安装并初始化数据库）
-（可选）LibreOffice：用于 Word 文档转 PDF 预览

------------------------------------------------------------------------
【首次启动步骤】
------------------------------------------------------------------------

■ 步骤 1：准备 MySQL 数据库
1) 安装 MySQL 8（如已安装可跳过）
2) 创建数据库（utf8mb4 字符集）：
CREATE DATABASE dms CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
3) 如果发行包内附带 database-init.sql，则导入它：
mysql -u root -p dms < database-init.sql
这会同时创建表结构并写入示例数据。
若没有该文件，请向分发者索取。

■ 步骤 2：修改配置文件
1) 用记事本（或 VSCode）打开本目录下的 .env 文件
（首次启动会自动从 .env.example 生成）
2) 修改以下关键项：
DMS_DATABASE_URL=mysql+pymysql://用户名:密码@主机:3306/dms?charset=utf8mb4
DMS_JWT_SECRET=请改成一串随机字符（建议 32 位以上）

■ 步骤 3：启动服务
双击 run.bat
看到控制台输出 Tomcat 启动于端口 9345 即启动成功

■ 步骤 4：访问系统
在浏览器打开：http://localhost:9345
（前端已内置在 dms-server.jar 中，无需额外部署）

■ 可选：初始化最小开发账号（未导入示例数据时）
在本目录打开命令行，执行（密码自行指定）：
set DMS_SEED_ADMIN_PASSWORD=Admin@1234
set DMS_SEED_USER_PASSWORD=User@1234
java -jar dms-server.jar seed
生成 admin（管理员）/ user（普通用户）两个账号与三个示例组织。
幂等可重复执行；如需覆盖已有密码，另加 set DMS_SEED_OVERWRITE_PASSWORDS=true

------------------------------------------------------------------------
【老版本升级（已有数据时使用，不会删除已有数据）】
------------------------------------------------------------------------

适用场景：旧版发行包已运行过、数据库中已有真实数据，更换新版发行包后，
新功能所需的表/索引由数据库升级自动补齐。

■ 步骤 1：备份数据库（强烈建议）
mysqldump -u root -p --single-transaction dms > dms-backup.sql

■ 步骤 2：替换程序文件
用新版发行包的 dms-server.jar 覆盖旧版同名文件；
保留旧版已有的 .env 和 dms-storage/ 目录（配置与文件不动）。

■ 步骤 3：执行数据库升级
双击 upgrade-db.bat（或命令行执行 java -jar dms-server.jar upgrade-db）。
程序会显示当前版本、目标版本与待执行迁移清单，确认 y 后执行。
迁移仅新增表/索引/约束，不删除、不修改既有业务数据。
提示"数据库已是最新版本"则无需处理。

■ 步骤 4：启动新版服务
双击 run.bat 正常启动。

------------------------------------------------------------------------
【默认登录账号】（仅当导入了示例数据或执行了 seed）
------------------------------------------------------------------------
管理员：admin / Admin@1234
普通用户：user / User@1234
（密码来源于示例数据，可在登录后修改）

------------------------------------------------------------------------
【常见问题】
------------------------------------------------------------------------

Q: 启动后浏览器无法访问？
A: 1) 检查控制台是否有错误信息（特别是数据库连接错误）
2) 确认 .env 中的 DMS_DATABASE_URL 配置正确
3) 确认 MySQL 服务已启动
4) 确认已执行步骤 1 的 SQL 导入

Q: 提示找不到 java 命令？
A: 安装 JDK 17+ 并将其 bin 目录加入系统 PATH，
或修改 run.bat，把 java 替换为完整路径（如 C:\jdk17\bin\java.exe）。

Q: 端口冲突？
A: 编辑 .env，添加一行：
DMS_PORT=9350（或其他端口），重启服务

Q: Word 文档预览失败？
A: 安装 LibreOffice，并确认 .env 中 DMS_LIBREOFFICE_EXECUTABLE
路径正确（默认 C:\Program Files\LibreOffice\program\soffice.exe）
或在 .env 中设置 DMS_OFFICE_PREVIEW_ENABLED=false 关闭该功能。

Q: 上传的文件存储在哪？
A: 程序同级目录的 dms-storage/ 下，请勿删除。

Q: 如何停止服务？
A: 在 run.bat 的控制台窗口按 Ctrl+C，或直接关闭窗口。

------------------------------------------------------------------------
【目录结构】
------------------------------------------------------------------------
dms-server.jar 主程序（前端已内置）
run.bat / run.sh 启动脚本
upgrade-db.bat / .sh 数据库升级脚本（老版本数据升级用）
.env 配置文件（首次启动生成）
.env.example 配置模板
database-init.sql 数据库初始化脚本（如已导出）
dms-storage/ 运行时文件存储目录（自动生成）
README.txt 本说明文件

========================================