fs-lawrisk/docs/DEPLOYMENT_GUIDE.md

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

🚀 快速开始

第一步：执行数据库迁移

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

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

# 验证迁移结果

第二步：重启应用

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

# 启动应用
python app.py

第三步：验证功能

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

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

📋 详细部署步骤

1. 环境准备

1.1 检查Python环境

python --version
# 需要 Python 3.10+

1.2 检查依赖

pip list | grep -E "Flask|pg8000"

1.3 检查数据库连接

# 确认数据库服务可访问
psql -h 8.138.196.105 -U postgres -d licensing_risks -c "SELECT 1;"

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

# 创建备份
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 检查迁移状态

python lawrisk/utils/migrate_unit_permission.py

输出示例：

============================================================
许可管理单位权限优化 - 数据库迁移工具
============================================================

检查当前迁移状态...

迁移状态: 未完成

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

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

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

3.2 执行迁移

# 输入 'y' 执行迁移

3.3 验证迁移结果

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 检查表结构

-- 连接到数据库
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 检查数据迁移

-- 检查现有单位的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

# 测试健康检查
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	手动创建	具体科室	仅自身

创建市级单位

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="市级市场监督管理局"
)

创建区级单位

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="禅城区市场监督管理局"
)

📊 监控和维护

检查权限配置

# 检查所有单位的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;

检查索引使用情况

# 检查索引使用
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;

查看权限日志

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

❗ 故障排除

问题1：迁移失败

症状：

Error: column "unit_level" does not exist

解决方案：

# 手动执行迁移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

解决方案：

-- 检查用户是否有有效的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返回空结果

症状：

{
  "data": {
    "permits": []
  }
}

解决方案：

1. 检查用户unit_level配置
2. 检查用户region_id设置
3. 查看应用日志中的权限日志

问题4：数据库连接错误

症状：

pg8000.dbapi.Error: connection failed

解决方案：

# 检查数据库服务状态
psql -h 8.138.196.105 -U postgres -c "SELECT version();"

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

🔄 回滚方案

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

回滚数据库变更

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

-- 删除新增的列
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;

恢复备份

# 恢复数据备份
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