document-management/build

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

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