unis_crm/docs/首页相关能力SQL发布说明.md

# 首页相关能力 SQL 发布说明

本文档用于指导已有生产环境执行本次首页相关能力升级 SQL。

对应正式脚本：

- `sql/upgrade_dashboard_analytics_prod_pg17.sql`

## 1. 适用范围

适用于以下场景：

- 已存在业务数据的老环境
- 需要补齐首页经营分析配置能力
- 需要补齐首页卡片权限
- 需要补齐商机快照字段

不适用于以下场景：

- 全新初始化数据库

全新环境请直接执行：

```bash
psql -d your_database -f sql/init_full_pg17.sql
```

## 2. 本次变更内容

主升级脚本 `sql/upgrade_dashboard_analytics_prod_pg17.sql` 会补齐：

- 新建 `dashboard_analytics_panel_config`
- 新建 `dashboard_analytics_card_config`
- 补齐首页权限分组与卡片权限：
  - `menu:frontend-home`
  - `dashboard_todo_card:view`
  - `dashboard_activity_card:view`
  - `dashboard_stats_card:view`
  - `dashboard_analytics_card:view`
  - `menu:dashboard-analytics-settings`
  - `dashboard_analytics_config:view`
  - `dashboard_analytics_config:update`
  - `dashboard_analytics_config:preview`
- 给 `crm_opportunity` 增加字段：
  - `latest_progress`
  - `next_plan`
- 修正 `crm_channel_expansion.certification_level` 字段注释为“汇智内部认证级别”
- 修复平台菜单权限串租户问题，并补齐 `system` 父目录权限

这份脚本不会做的事情：

- 不插入默认经营分析业务卡片
- 不创建目标值业务表
- 不导入业务数据

## 3. 上线执行顺序

### 3.1 执行前准备

建议先完成以下检查：

- 确认当前数据库为 PostgreSQL 17 兼容环境
- 确认业务高峰期外执行
- 备份本次涉及表的结构和关键权限数据：
  - `crm_opportunity`
  - `crm_channel_expansion`
  - `sys_permission`
  - `sys_role_permission`
  - `dashboard_analytics_panel_config`
  - `dashboard_analytics_card_config`

建议至少保留一份备份：

```bash
pg_dump -d your_database -t crm_opportunity -t crm_channel_expansion -t sys_permission -t sys_role_permission > pre_dashboard_upgrade.sql
```

如果环境里还没有经营分析表，`pg_dump` 忽略这两张新表即可。

### 3.2 正常执行顺序

生产环境标准执行顺序如下：

1. 执行正式升级脚本

```bash
psql -d your_database -f sql/upgrade_dashboard_analytics_prod_pg17.sql
```

2. 执行完成后做结构校验

```sql
select column_name
from information_schema.columns
where table_name = 'crm_opportunity'
  and column_name in ('latest_progress', 'next_plan');
```

```sql
select table_name
from information_schema.tables
where table_name in ('dashboard_analytics_panel_config', 'dashboard_analytics_card_config');
```

3. 做权限校验

```sql
select code, name, is_deleted
from sys_permission
where code in (
  'menu:frontend-home',
  'dashboard_todo_card:view',
  'dashboard_activity_card:view',
  'dashboard_stats_card:view',
  'dashboard_analytics_card:view',
  'menu:dashboard-analytics-settings',
  'dashboard_analytics_config:view',
  'dashboard_analytics_config:update',
  'dashboard_analytics_config:preview'
)
order by code, perm_id;
```

4. 做页面冒烟验证

- 首页正常打开
- 待办卡片正常显示
- 最新动态卡片正常显示
- 指标卡正常显示
- 有权限账号能进入“首页经营分析配置”页面
- 商机新增/编辑页面可正常保存“项目最新进展”“下一步销售计划”

## 4. 验收重点

上线后建议重点验收以下内容：

- `crm_opportunity` 能正常读写 `latest_progress`、`next_plan`
- 老商机详情能正常打开，不因新字段为空报错
- 首页待办、动态、指标、经营分析卡片权限符合预期
- 管理员角色拥有首页经营分析配置菜单与按钮权限
- 普通租户角色不会误拿平台菜单权限
- 经营分析配置页能打开，但若未配置卡片，页面为空属于预期现象

## 5. 风险说明

### 5.1 权限可见性变化风险

本次脚本会创建、修复并去重首页相关权限，同时会给管理员类角色补权限。

风险点：

- 某些历史脏数据环境中，原来依赖重复权限记录的角色可见性可能发生变化
- 若角色本身不属于管理员类，脚本不会自动补齐首页经营分析配置权限

建议：

- 上线后用管理员账号和普通业务账号各验证一次首页与系统管理菜单

### 5.2 经营分析页“空白”风险

本次只补配置表和权限，不会写默认卡片配置。

风险点：

- 脚本执行成功后，经营分析区域可能为空

这不是故障，表示表结构已就绪，但后台尚未配置业务卡片。

### 5.3 商机字段新增后的数据回填预期

`latest_progress` 和 `next_plan` 为新增字段，历史数据不会被批量回填。

风险点：

- 旧商机初次查看时，这两个字段可能为空

当前代码已经保留从历史跟进记录兜底读取的兼容逻辑，因此一般不会影响旧数据查看。

### 5.4 平台菜单权限纠偏风险

本次正式升级脚本已包含平台菜单权限纠偏逻辑。

风险点：

- 若某些环境历史上错误发放了平台菜单权限，执行后这些错误权限会被收回

建议：

- 执行前备份 `sys_role_permission`
- 执行后重点验证租户管理员、平台管理员两类账号的菜单可见性

## 6. 回滚建议

本次脚本以“新增字段、建表、权限修复”为主，不建议直接无审查回滚。

建议回滚策略：

1. 若只是经营分析权限异常，优先人工修复 `sys_permission` / `sys_role_permission`
2. 若只是经营分析配置有误，清理 `dashboard_analytics_panel_config` / `dashboard_analytics_card_config` 即可
3. 若必须整体回退，请基于执行前备份恢复，不建议直接手写反向 SQL 在线回滚

## 7. 推荐发布口径

可向实施或运维同事同步以下结论：

- 本次生产升级主入口只有一份：`sql/upgrade_dashboard_analytics_prod_pg17.sql`
- 旧的重复升级脚本已删除，不需要再单独执行首页卡片权限历史脚本