Merge pull request #14 from vran-dev/feature/readme

feat: update readme

README.md

@@ -1,78 +1,54 @@
 # Databasir
 
-## 规划
+## 文档索引
-项目目前还属于 MVP （可行性验证）阶段，版本功能迭代较快
 
-以下功能尚在开发中
+- [项目简介](#)
-
+- [部署指引](README/deploy.md)
-- [ ] 操作审计日志
+- [构建指引](README/build.md)
-- [ ] 文档导出功能
-- [ ] 数据库动态扩展
-- [ ] 忘记密码
-
-目前已支持 MySQL，Postgresql 两款数据库，文档转换基于 JDBC 开发，理论上支持所有有 JDBC 驱动的数据库。
 
 
 
 ## 简介
 
-**Databasir** 是一款集中式的数据库文档管理工具，提供了自动化、版本化、扁平化的数据库文档管理能力
+**Databasir** 是一款集中式的数据库文档管理工具，提供了自动化、版本化、扁平化的数据库文档管理能力，主要功能如下
 
-1. 自动化：定时、手动同步数据库结构并自动生成文档
+1. 支持多种数据库
-2. 版本化：每一次同步的文档版本皆可回溯
+1. 自动或手动同步数据库 Schema 并生成文档
-3. 扁平化：权限管理兼顾完备与简单，信息传输价值最大化
+2. 项目 Schema 历史版本文档查看
+3. 项目文档导出，提供 markdown、excel（研发中心） 等格式
+4. 团队管理、成员管理一应俱全，扁平化的权限管理模式
+5. 安全系数高：数据库密码加密存储，存储后不会再返回前端
 
 
 
-## 部署
+## 支持数据库
 
-Databasir 采用了前后端分离的模式进行开发和部署，前端和后端可以独立部署
+1. - [x] Mysql
+2. - [x] Postgresql
+3. - [ ] Oracle
+4. - [ ] SqlServer
 
-- 后端应用： https://github.com/vran-dev/databasir
-- 前端应用： https://github.com/vran-dev/databasir-frontend
 
-### JAR 模式部署
 
-注意：
+## 功能规划
 
-1. 使用 JAR 模式部署需要系统环境有 Java 环境，**要求最低版本为 Java11**。
+- [ ] 用户操作审计日志
-2. 应用使用 MYSQL 作为数据存储，需要准备好数据库。
+- [ ] 文档自动同步日志
+- [ ] Excel 文档导出
+- [x] PDF 文档导出
 
-部署：
-1. 在 [Github RELEASE](https://github.com/vran-dev/databasir/releases) 页面下载最新版应用 Databasir.jar (你也可以选择克隆项目后自行构建)
-2. 将 Databasir.jar 上传到服务器
-3. 在 Databasir.jar 所在目录创建 config 目录，并在目录下创建 `application.properties` 配置，配置中配置 MYSQL 的用户名、密码和连接
 
-```properties
-# 端口号，默认8080
-server.port=8080
-# 数据库用户名
-databasir.datasource.username=root
-# 数据库密码
-databasir.datasource.password=123456
-# 数据库地址
-databasir.datasource.url=127.0.0.1:3306
-```
-
-4. 通过 java -jar Databasir.jar 启动应用即可
-
-应用启动后会默认创建 Databasir 管理员用户
-
-- 用户名：databasir
-- 密码：databasir
-
-通过该账号登录应用既可以进行管理
-
-### Docker 部署
-
-TODO
 
 ## 展示
 
-- 分组管理、项目管理
+- 项目中心
 
-![](README/a.jpg)
+![](README/a.png)
 
-- 文档页面、用户管理页面
+- 项目文档
 
-![](README/b.jpg)
+![](README/b.png)
+
+- 用户管理
+
+![](README/c.png)

README/build.md

@@ -0,0 +1,133 @@
+# 构建指引
+
+## 前言
+
+Databasir 采用了前后端分离的模式进行开发和部署，项目仓库地址分别位于
+
+- 后端应用： https://github.com/vran-dev/databasir
+- 前端应用： https://github.com/vran-dev/databasir-frontend
+
+
+
+## 后端
+
+**一、环境要求**
+
+1. Java 11+
+2. Mysql
+3. Intellij IDEA
+
+
+
+**二、主要框架**
+
+1. Gradle：构建工具
+2. Spring-boot：核心框架
+   1. Web
+   2. Security
+3. Quartz：定时任务调度
+4. JOOQ：ORM 框架
+5. Lombok：代码生成
+6. Mapstruct：代码生成
+7. Flyway：数据库脚本管理
+
+
+
+**三、项目结构**
+
+项目结构采用了分层结构
+
+- api：所有的 http 接口、定时任务都在该模块下
+- common：主要包含通用异常定义、加解密算法工具
+- core：包含了所有的业务核心逻辑，包括 service、request/response data、converter 等
+- dao：针对数据库的操作类都在该模块下，其中 generated-src 包含了 jooq 生成的代码，src 主要包含了 dao 的实现类
+- plugin：主要包含了 JDBC 工具类，包括但不限于将数据库的元数据解析为 Java 对象 、PDF 导出等
+
+项目配置都放在 api/src/main/resources 目录下
+
+前端静态文件放在 api/src/main/resources/static 目录下
+
+项目数据库脚本放在 dao/src/main/resources/db/migration 目录下
+
+
+
+**四、项目启动**
+
+1、通过 Java Main 方法启动
+
+修改或创建配置文件 `api/src/main/resources/application-local.properties`
+
+```properties
+server.port=8080
+logging.level.org.jooq=INFO
+
+# 必须：数据库配置
+spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
+spring.datasource.username=root
+spring.datasource.password=123456
+spring.datasource.url=jdbc:mysql://localhost:3306/databasir
+spring.jooq.sql-dialect=mysql
+
+# 可选：flyway 配置
+spring.flyway.enabled=true
+spring.flyway.baseline-on-migrate=true
+spring.flyway.locations=classpath:db/migration
+```
+
+启动 DatabasirApplication（com.databasir.DatabasirApplication） 类，启动时需要加参数 `-Dspring.profiles.active=local`
+
+启动完成后，可以通过 http://localhost:8080 访问
+
+
+
+2、通过 Gradle 启动
+
+与 Java 启动模式一样，首先需要准备配置文件
+
+修改或创建配置文件 `api/src/main/resources/application-local.properties`
+
+```properties
+server.port=8080
+logging.level.org.jooq=INFO
+
+# 必须：数据库配置
+spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
+spring.datasource.username=root
+spring.datasource.password=123456
+spring.datasource.url=jdbc:mysql://localhost:3306/databasir
+spring.jooq.sql-dialect=mysql
+
+# 可选：flyway 配置
+spring.flyway.enabled=true
+spring.flyway.baseline-on-migrate=true
+spring.flyway.locations=classpath:db/migration
+```
+
+执行 Gradle 命令
+
+```shell
+./gradlew bootRun --args='--spring.profiles.active=local'
+```
+
+启动完成后，可以通过 http://localhost:8080 访问
+
+
+
+## 前端
+
+一、依赖
+
+1. vue
+2. vuex
+3. element-plus
+4. axios
+
+
+
+二、运行
+
+```shell
+npm run serve
+```
+
+默认端口为 3000

README/deploy.md

@@ -0,0 +1,59 @@
+# 部署指引
+
+## 前言
+
+Databasir 采用了前后端分离的模式进行开发和部署，项目仓库地址分别位于
+
+- 后端应用： https://github.com/vran-dev/databasir
+- 前端应用： https://github.com/vran-dev/databasir-frontend
+
+当前提供了 Jar 和 Docker 两种部署方式
+
+### JAR 模式部署
+
+**一、环境要求**
+
+1. Java 11+
+2. Mysql
+
+**二、部署流程**
+
+1. 在 [Github RELEASE](https://github.com/vran-dev/databasir/releases) 页面下载最新版应用 Databasir.jar (你也可以选择克隆项目后自行构建)
+2. 将 Databasir.jar 上传到服务器
+3. 在 Databasir.jar 所在目录创建 config 目录，并在目录下创建 `application.properties` 配置，配置中配置 MYSQL 的用户名、密码和连接
+
+```properties
+# 端口号，默认8080
+server.port=8080
+# 数据库用户名
+databasir.datasource.username=root
+# 数据库密码
+databasir.datasource.password=123456
+# 数据库地址
+databasir.datasource.url=127.0.0.1:3306
+```
+
+4. 通过 java -jar Databasir.jar 启动应用即可
+
+**三、系统登陆**
+
+应用启动后会默认创建 Databasir 管理员用户
+
+- 用户名：databasir
+- 密码：databasir
+
+通过该账号登录应用既可以进行管理
+
+
+
+### Docker 部署
+
+TODO
+
+
+
+
+
+## Docker Compose 本地部署
+
+TODO