# Integrated CRM 部署指南

## 1. 环境准备

- Python 3.10+
- MySQL 5.7+（需有 CREATE DATABASE 权限的管理员账号）
- Git

## 2. 一键部署

只需克隆主应用并运行 build.sh，其余模块自动克隆、数据库自动配置：

```bash
git clone git@git.opencomputing.cn:yumoqing/integrated_crm_app.git
cd integrated_crm_app
chmod +x build.sh
./build.sh
```

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

### 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. 启动应用

```bash
./start.sh          # 默认端口 8080
./start.sh 9999     # 指定端口
```

访问：`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
./stop.sh
```

## 6. 权限体系

### 6.1 角色定义（单业主机构）

| 角色ID | 名称 | 说明 |
|--------|------|------|
| any | 任何人 | 未登录用户（固定ID，不可改） |
| logined | 已登录 | 任意登录用户（固定ID，不可改） |
| sales_manager | 销售经理 | 团队管理、客户分配、审批 |
| sales_rep | 销售代表 | 客户跟进、商机推进 |
| finance_admin | 财务管理员 | 所有财务操作、报表 |
| finance_clerk | 财务出纳 | 收款登记、付款处理 |
| admin_superuser | 超级用户 | 全部权限 |

### 6.2 注意事项

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

## 7. 模块引用规则

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

## 8. 目录结构

```
integrated_crm_app/
├── app/
│   ├── integrated_crm_app.py    # 主入口
│   ├── perm_config.py           # 权限配置（角色+权限矩阵）
│   └── init_permissions.py      # 权限初始化脚本
├── conf/
│   └── config.json              # 应用配置（build.sh 自动生成）
├── wwwroot/
│   ├── main/                    # 主页面
│   ├── rbac/                    # 用户管理（symlink → pkgs/rbac/wwwroot）
│   ├── customer_management/     # 客户管理（symlink）
│   ├── opportunity_management/  # 商机管理（symlink）
│   ├── contract_management/     # 合同管理（symlink）
│   ├── financial_management/    # 财务管理（symlink）
│   ├── workflow_approval/       # 审批管理（symlink）
│   ├── unified_dashboard/       # 仪表盘（symlink）
│   └── bricks/                  # 前端框架（symlink）
├── 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                     # 一键构建脚本
├── start.sh                     # 启动脚本（build.sh 自动生成）
└── stop.sh                      # 停止脚本（build.sh 自动生成）
```

## 9. 故障排查

### 端口被占用
```bash
lsof -i :8080
kill -9 <PID>
```

### 数据库连接失败
检查 `conf/config.json` 中的数据库配置是否正确。

### 权限初始化失败
重新运行：
```bash
source py3/bin/activate
python app/init_permissions.py
```