docs: update DEPLOY.md for automated one-step build process

2026-04-29 13:28:03 +08:00 · 2026-04-29 13:28:03 +08:00 · b0de930324
commit b0de930324
parent f83dde78f9
1 changed files with 83 additions and 175 deletions
--- a/DEPLOY.md
+++ b/DEPLOY.md
@ -2,120 +2,79 @@

 ## 1. 环境准备

-### 1.1 系统要求
 - Python 3.10+
- MySQL 5.7+
+- MySQL 5.7+（需有 CREATE DATABASE 权限的管理员账号）
 - Git

-### 1.2 克隆所有仓库
+## 2. 一键部署
+
+只需克隆主应用并运行 build.sh，其余模块自动克隆、数据库自动配置：

 ```bash
-mkdir -p ~/repos && cd ~/repos
-
-# 引用模块（5个，绝对不能修改）
-git clone git@git.opencomputing.cn:yumoqing/apppublic.git
-git clone git@git.opencomputing.cn:yumoqing/sqlor.git
-git clone git@git.opencomputing.cn:yumoqing/ahserver.git
-git clone git@git.opencomputing.cn:yumoqing/appbase.git
-git clone git@git.opencomputing.cn:yumoqing/rbac.git
-
-# CRM业务模块（6个）
-git clone git@git.opencomputing.cn:yumoqing/customer_management.git
-git clone git@git.opencomputing.cn:yumoqing/opportunity_management.git
-git clone git@git.opencomputing.cn:yumoqing/contract_management.git
-git clone git@git.opencomputing.cn:yumoqing/financial_management.git
-git clone git@git.opencomputing.cn:yumoqing/workflow_approval.git
-git clone git@git.opencomputing.cn:yumoqing/unified_dashboard.git
-
-# 主应用
 git clone git@git.opencomputing.cn:yumoqing/integrated_crm_app.git
-```
-
-## 2. 构建应用
-
-```bash
-cd ~/repos/integrated_crm_app
+cd integrated_crm_app
 chmod +x build.sh
 ./build.sh
 ```

-构建脚本会完成：
+构建脚本会自动完成：
 1. 创建虚拟环境（py3/）
-2. 安装核心依赖（apppublic、sqlor、ahserver）
-3. 链接本地业务模块到 pkgs/
-4. 生成数据库 DDL（integrated_crm_app_schema.sql）
+2. 安装核心依赖
+3. 克隆所有 11 个模块到 pkgs/（5个引用模块 + 6个业务模块）
+4. 生成数据库 DDL 和 CRUD UI
 5. 创建 wwwroot 符号链接
-6. 生成 start.sh / stop.sh
+6. **交互式配置数据库**（host、port、用户名、密码）
+7. 自动创建数据库、导入表结构
+8. 生成 config.json（密码自动 AES 加密）
+9. 自动初始化权限（角色 + 权限映射）
+10. 生成 start.sh / stop.sh

-## 3. 数据库初始化
+### 2.1 数据库配置提示
+
+运行 build.sh 时会依次询问：
+
+```
+MySQL host [localhost]:          # 直接回车用默认
+MySQL port [3306]:               # 直接回车用默认
+MySQL admin user [root]:          # 有CREATE DATABASE权限的管理员
+MySQL admin password:             # 管理员密码（不显示）
+CRM database name [crm_db]:       # 直接回车用默认
+CRM database user [hermes]:       # 应用使用的数据库用户
+CRM database password:            # 该用户密码（不显示）
+```
+
+> rbac 和所有业务模块共用同一个数据库，不会创建独立数据库。
+
+## 3. 启动应用

-### 3.1 创建数据库
 ```bash
-mysql -u root -p -e "CREATE DATABASE crm_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
-mysql -u root -p -e "CREATE DATABASE rbac CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
+./start.sh          # 默认端口 8080
+./start.sh 9999     # 指定端口
 ```

-### 3.2 导入表结构
+访问：`http://localhost:8080/main/login.ui`
+
+## 4. 创建管理员用户
+
+首次使用需注册并分配超级管理员角色：
+
+1. 访问 `http://localhost:8080/user/register.ui` 注册第一个用户
+2. 为该用户分配 `admin_superuser` 角色：
+
+```sql
+mysql -u crm_user -p crm_db
+INSERT INTO userroles (userid, roleid) VALUES ('你的用户ID', 'admin_superuser');
+```
+
+## 5. 停止应用
+
 ```bash
-# CRM业务表
-mysql -u root -p crm_db < ~/repos/integrated_crm_app/integrated_crm_app_schema.sql
-
-# RBAC表（rbac模块自带）
-cd ~/repos/rbac
-source ~/repos/integrated_crm_app/py3/bin/activate
-python -c "
-from appPublic.jsonConfig import getConfig
-from appPublic.dictObject import DictObject
-from sqlor.dbpools import DBPools
-from rbac import load_rbac
-import os
-os.chdir(os.path.expanduser('~/repos/rbac'))
-config = getConfig('.', {'workdir': '.'})
-db_config = {}
-for k, v in config.databases.items():
-    db_config[k] = DictObject(driver=v['driver'], kwargs=DictObject(**v['kwargs']))
-DBPools(db_config)
-from rbac.rbac_tables import init_database
-init_database()
-"
+./stop.sh
 ```

-### 3.3 创建RBAC默认数据
-RBAC模块需要在数据库中初始化：
- 一个超级管理员用户
- 初始机构（orgtype）
+## 6. 权限体系

-可通过 rbac 自带的注册功能完成，或运行 RBAC 的初始化脚本。
-
-## 4. 配置数据库连接
-
-编辑 `~/repos/integrated_crm_app/conf/config.json`：
-
-```json
-{
-  "password_key": "!@#$%^&*(*&^%$QWERTYUIqwertyui234567",
-  "databases": {
-    "crm_db": {
-      "driver": "mysql",
-      "kwargs": {
-        "host": "localhost",
-        "port": 3306,
-        "user": "你的MySQL用户名",
-        "password": "加密后的密码",
-        "db": "crm_db",
-        "charset": "utf8mb4"
-      }
-    }
-  }
-}
-```
-
-> 注意：password 需要使用 apppublic 的加密工具加密，格式为 `apppublic.aes.encrypt(明文密码)`
-
-## 5. 权限初始化
-
-### 5.1 角色定义
-CRM是**单业主机构**系统，所有角色属于同一机构内部：
+### 6.1 角色定义（单业主机构）

 | 角色ID | 名称 | 说明 |
 |--------|------|------|
@ -127,85 +86,20 @@ CRM是**单业主机构**系统，所有角色属于同一机构内部：
 | finance_clerk | 财务出纳 | 收款登记、付款处理 |
 | admin_superuser | 超级用户 | 全部权限 |

-### 5.2 执行权限初始化
+### 6.2 注意事项

-```bash
-cd ~/repos/integrated_crm_app
-source py3/bin/activate
-python app/init_permissions.py
-```
+- 角色 ID 使用**下划线**（如 `sales_manager`），**不能用点号**，因为前端显示格式为 `机构类型.角色名称`（如 `sales.manager`）
+- `any`、`logined` 是约定角色，rbac 模块硬编码检查，必须用固定 ID
+- rbac 自带完整登录注册功能（`pkgs/rbac/wwwroot/user/`），不要创建冗余文件

-该脚本会：
-1. 创建约定角色（any、logined）
-2. 创建定义的角色（sales_manager 等）
-3. 扫描各模块 wwwroot 注册路径权限
-4. 根据 `app/perm_config.py` 中的 PERMISSION_MATRIX 授予角色权限
-5. 注册 CRUD 路径
-
-### 5.3 约定角色说明
-
-rbac 模块的 `userperm.py` 硬编码检查特殊角色 ID：
-```python
-if r.id == 'anonymous': k = 'anonymous'
-elif r.id == 'any': k = 'any'
-elif r.id == 'logined': k = 'logined'
-```
-
-因此 `any`、`logined` 必须使用固定字符串作为 ID，**不能用 getID() 随机生成**。
-
-### 5.4 业务角色ID命名
-
-业务角色 ID 使用**下划线**（如 `sales_manager`），**不能用点号**，因为前端显示格式为 `机构类型.角色名称`（如 `sales.manager`）。
-
-## 6. 创建初始用户
-
-通过 rbac 自带的注册功能创建用户：
-
-```
-访问 http://localhost:8080/user/register.ui
-```
-
-创建第一个用户后，通过数据库或 rbac 管理界面为其分配角色：
-
-```sql
-- 将用户分配给 admin_superuser 角色
-INSERT INTO userroles (userid, roleid) 
-VALUES ('你的用户ID', 'admin_superuser');
-```
-
-## 7. 启动应用
-
-```bash
-cd ~/repos/integrated_crm_app
-./start.sh
-```
-
-默认端口 8080，可通过参数修改：
-
-```bash
-python app/integrated_crm_app.py --port 9999 --root wwwroot/
-```
-
-访问：`http://localhost:8080/main/login.ui`
-
-## 8. 停止应用
-
-```bash
-./stop.sh
-# 或
-pkill -f "integrated_crm_app.py"
-```
-
-## 9. 模块引用规则
+## 7. 模块引用规则

 | 类别 | 模块 | 规则 |
 |------|------|------|
 | 引用模块 | apppublic, sqlor, ahserver, appbase, rbac | **绝对不能修改** |
 | 业务模块 | customer_management 等 6 个 | 遵循 module-development-spec |

-rbac 自带完整的登录注册功能（`rbac/wwwroot/user/`），开发时直接引用，**不要创建冗余的登录注册文件**。
-
-## 10. 目录结构
+## 8. 目录结构

 ```
 integrated_crm_app/
@ -214,10 +108,10 @@ integrated_crm_app/
 │   ├── perm_config.py           # 权限配置（角色+权限矩阵）
 │   └── init_permissions.py      # 权限初始化脚本
 ├── conf/
-│   └── config.json              # 应用配置
+│   └── config.json              # 应用配置（build.sh 自动生成）
 ├── wwwroot/
 │   ├── main/                    # 主页面
-│   ├── rbac/                    # 用户管理（symlink）
+│   ├── rbac/                    # 用户管理（symlink → pkgs/rbac/wwwroot）
 │   ├── customer_management/     # 客户管理（symlink）
 │   ├── opportunity_management/  # 商机管理（symlink）
 │   ├── contract_management/     # 合同管理（symlink）
@ -225,14 +119,27 @@ integrated_crm_app/
 │   ├── workflow_approval/       # 审批管理（symlink）
 │   ├── unified_dashboard/       # 仪表盘（symlink）
 │   └── bricks/                  # 前端框架（symlink）
-├── pkgs/                        # 模块链接
-├── py3/                         # 虚拟环境
+├── pkgs/                        # 模块目录（build.sh 自动克隆）
+│   ├── apppublic/
+│   ├── sqlor/
+│   ├── ahserver/
+│   ├── appbase/
+│   ├── rbac/
+│   ├── customer_management/
+│   ├── opportunity_management/
+│   ├── contract_management/
+│   ├── financial_management/
+│   ├── workflow_approval/
+│   └── unified_dashboard/
+├── py3/                         # 虚拟环境（build.sh 自动创建）
 ├── logs/                        # 日志
 ├── files/                       # 文件存储
-└── build.sh                     # 构建脚本
+├── build.sh                     # 一键构建脚本
+├── start.sh                     # 启动脚本（build.sh 自动生成）
+└── stop.sh                      # 停止脚本（build.sh 自动生成）
 ```

-## 11. 故障排查
+## 9. 故障排查

 ### 端口被占用
 ```bash
@ -241,10 +148,11 @@ kill -9 <PID>
 ```

 ### 数据库连接失败
-```bash
-cd ~/repos/integrated_crm_app
-python test_db_conn.py
-```
+检查 `conf/config.json` 中的数据库配置是否正确。

 ### 权限初始化失败
-检查 rbac 数据库中的 role、permission、rolepermission 表是否正确创建。
+重新运行：
+```bash
+source py3/bin/activate
+python app/init_permissions.py
+```