document-management/build/java-templates/README.txt

========================================
  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                  本说明文件

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