document-management/build/README.txt

========================================
  DMS 文档管理系统 - 使用说明
========================================

【系统要求】
  - Windows 10/11 (64 位)
  - 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：启动服务
   双击 dms-server.exe
   看到控制台输出 "Running on http://127.0.0.1:9345" 即启动成功

■ 步骤 4：访问系统
   在浏览器打开：http://localhost:9345

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

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

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

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

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

  ■ 步骤 4：启动新版服务
     双击 dms-server.exe 正常启动。

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

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

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

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

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: 在 dms-server.exe 的控制台窗口按 Ctrl+C，或直接关闭窗口。

------------------------------------------------------------------------
【目录结构】
------------------------------------------------------------------------
  dms-server.exe              主程序
  _internal/                  PyInstaller 运行时依赖（请勿删除）
  upgrade-db.bat              数据库升级脚本（老版本数据升级用）
  .env                        配置文件（首次启动生成）
  .env.example                配置模板
  database-init.sql           数据库初始化脚本（如已导出）
  dms-storage/                运行时文件存储目录
  README.txt                  本说明文件

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