fs-lawrisk/docs/DEPLOYMENT_GUIDE.md

# 许可管理单位权限优化 - 部署指南

## 🚀 快速开始

### 第一步：执行数据库迁移

```bash
# 进入项目目录
cd /path/to/市监局-lawRisk-backend

# 执行迁移
python lawrisk/utils/migrate_unit_permission.py

# 验证迁移结果
```

### 第二步：重启应用

```bash
# 停止现有应用
pkill -f "python app.py"

# 启动应用
python app.py
```

### 第三步：验证功能

```bash
# 检查服务状态
curl http://localhost:8000/healthz

# 测试权限控制
curl -X POST http://localhost:8000/fs-ai-asistant/api/workflow/lawrisk/getPermits \
  -d "region=禅城区"
```

## 📋 详细部署步骤

### 1. 环境准备

#### 1.1 检查Python环境
```bash
python --version
# 需要 Python 3.10+
```

#### 1.2 检查依赖
```bash
pip list | grep -E "Flask|pg8000"
```

#### 1.3 检查数据库连接
```bash
# 确认数据库服务可访问
psql -h 8.138.196.105 -U postgres -d licensing_risks -c "SELECT 1;"
```

### 2. 备份数据（生产环境）

```bash
# 创建备份
pg_dump -h 8.138.196.105 -U postgres -d licensing_risks > backup_$(date +%Y%m%d_%H%M%S).sql

# 备份fs_law_risk数据库
pg_dump -h 8.138.196.105 -U postgres -d fs_law_risk > backup_fs_law_risk_$(date +%Y%m%d_%H%M%S).sql
```

### 3. 执行数据库迁移

#### 3.1 检查迁移状态
```bash
python lawrisk/utils/migrate_unit_permission.py
```

输出示例：
```
============================================================
许可管理单位权限优化 - 数据库迁移工具
============================================================

检查当前迁移状态...

迁移状态: 未完成

service_departments表字段数量: 8
permit_sources表字段数量: 7

单位级别分布:
  - admin: 1 个
  - district: 5 个
  - unit: 0 个

============================================================
数据库尚未完全迁移，是否执行迁移？(y/N):
```

#### 3.2 执行迁移
```bash
# 输入 'y' 执行迁移
```

#### 3.3 验证迁移结果
```bash
python -c "
from lawrisk.utils.migrate_unit_permission import check_migration_status
status = check_migration_status()
print(f\"迁移完成: {status['migration_complete']}\")
print(f\"单位级别分布: {status['unit_level_distribution']}\")
"
```

### 4. 验证功能

#### 4.1 检查表结构
```sql
-- 连接到数据库
psql -h 8.138.196.105 -U postgres -d licensing_risks

-- 检查service_departments表是否包含unit_level字段
\d service_departments

-- 检查permit_sources表是否包含uploader_department_id和bound_department_id字段
\d permit_sources

-- 检查索引
\di | grep -E "unit_level|bound_dept|uploader"
```

#### 4.2 检查数据迁移
```sql
-- 检查现有单位的unit_level设置
SELECT id, name, code, unit_level, grade
FROM service_departments
ORDER BY unit_level, grade;

-- 预期结果：
-- unit_level = 'admin' 对应 grade >= 90
-- unit_level = 'district' 对应 parent_id IS NULL AND grade < 90
-- unit_level = 'unit' 对应 parent_id IS NOT NULL AND grade < 90
```

#### 4.3 测试API
```bash
# 测试健康检查
curl -s http://localhost:8000/healthz | jq

# 测试获取许可列表（向后兼容）
curl -X POST http://localhost:8000/fs-ai-asistant/api/workflow/lawrisk/getPermits \
  -d "region=禅城区" \
  | jq

# 测试获取服务部门列表
curl -X GET http://localhost:8000/fs-ai-asistant/api/workflow/lawrisk/admin/departments \
  | jq '.data[] | {id, name, unit_level}'
```

## 🔧 配置说明

### 单位级别说明

| 级别 | 创建方式 | 示例 | 权限范围 |
|------|---------|------|----------|
| admin | 自动设置（市局账号） | FSSJSJ | 全部许可 |
| municipal | 手动创建 | 市监局、卫健局 | 自身 + 下属区级单位 |
| district | 自动设置（区局账号） | 禅城区、南海区 | 下属所有单位 |
| unit | 手动创建 | 具体科室 | 仅自身 |

### 创建市级单位

```python
from lawrisk.services.licensing_repo import create_service_department

# 创建市级单位
municipal_unit = create_service_department(
    name="佛山市市场监督管理局",
    code="FS_AMR",
    unit_level="municipal",
    region_id="市级区域ID",
    description="市级市场监督管理局"
)
```

### 创建区级单位

```python
from lawrisk.services.licensing_repo import create_service_department

# 创建区级单位（绑定到市级单位）
district_unit = create_service_department(
    name="禅城区市场监督管理局",
    code="CC_AMR",
    unit_level="unit",
    parent_id="市级单位ID",
    region_id="禅城区ID",
    description="禅城区市场监督管理局"
)
```

## 📊 监控和维护

### 检查权限配置

```bash
# 检查所有单位的unit_level配置
psql -h 8.138.196.105 -U postgres -d licensing_risks -c "
SELECT
    unit_level,
    COUNT(*) as count,
    STRING_AGG(name, ', ') as departments
FROM service_departments
GROUP BY unit_level
ORDER BY unit_level;
```

### 检查索引使用情况

```bash
# 检查索引使用
psql -h 8.138.196.105 -U postgres -d licensing_risks -c "
SELECT
    schemaname,
    tablename,
    indexname,
    idx_scan
FROM pg_stat_user_indexes
WHERE indexname LIKE '%unit_level%' OR indexname LIKE '%bound_dept%'
ORDER BY idx_scan DESC;
```

### 查看权限日志

```bash
# 查看应用日志中的权限相关记录
tail -f /tmp/flask.log | grep -i "permission\|unit_level"
```

## ❗ 故障排除

### 问题1：迁移失败

**症状**：
```
Error: column "unit_level" does not exist
```

**解决方案**：
```bash
# 手动执行迁移SQL
psql -h 8.138.196.105 -U postgres -d licensing_risks -f docs/sql/006_add_unit_level_and_binding_fields.sql
```

### 问题2：权限验证失败

**症状**：
```
Permission denied: User has no valid department assignment
```

**解决方案**：
```sql
-- 检查用户是否有有效的department_id
SELECT au.username, au.service_department_id, sd.unit_level
FROM auth_users au
LEFT JOIN service_departments sd ON sd.id = au.service_department_id
WHERE au.username = '用户名';
```

### 问题3：API返回空结果

**症状**：
```json
{
  "data": {
    "permits": []
  }
}
```

**解决方案**：
1. 检查用户unit_level配置
2. 检查用户region_id设置
3. 查看应用日志中的权限日志

### 问题4：数据库连接错误

**症状**：
```
pg8000.dbapi.Error: connection failed
```

**解决方案**：
```bash
# 检查数据库服务状态
psql -h 8.138.196.105 -U postgres -c "SELECT version();"

# 检查.env配置
cat .env | grep -E "PG_|LIC_PG_"
```

## 🔄 回滚方案

如果迁移后发现问题，可以执行回滚：

### 回滚数据库变更

```sql
-- 注意：这会丢失数据，请在测试环境充分验证

-- 删除新增的列
ALTER TABLE service_departments DROP COLUMN IF EXISTS unit_level;
ALTER TABLE service_departments DROP COLUMN IF EXISTS allowed_regions;

ALTER TABLE permit_sources DROP COLUMN IF EXISTS uploader_department_id;
ALTER TABLE permit_sources DROP COLUMN IF EXISTS bound_department_id;

-- 删除索引
DROP INDEX IF EXISTS idx_service_dept_unit_level;
DROP INDEX IF EXISTS idx_service_dept_parent_level;
DROP INDEX IF EXISTS idx_permit_sources_bound_dept;
DROP INDEX IF EXISTS idx_permit_sources_uploader;
```

### 恢复备份

```bash
# 恢复数据备份
psql -h 8.138.196.105 -U postgres -d licensing_risks < backup_YYYYMMDD_HHMMSS.sql
```

## 📞 支持

如果遇到问题，请：

1. 查看应用日志：`/tmp/flask.log`
2. 检查数据库日志
3. 运行诊断脚本：`python lawrisk/utils/migrate_unit_permission.py`
4. 联系技术支持团队

---

**文档版本**: v1.0
**更新日期**: 2025-11-19