writeOff/docs/租户域模板管理模块优化方案清单.md

# 租户域模板管理模块优化方案清单

## 1. 适用范围

- 本清单仅针对**租户域模板管理模块**。
- 不包含平台域统一模板治理、跨租户模板审计、平台级模板库等能力。
- 目标是把租户域模板管理从“能上传、能发布”升级为“可治理、可检索、可追踪、可联动”。

## 2. 优化目标

- 提升模板管理页面的信息架构与使用效率。
- 提升模板生命周期治理能力，包括草稿、发布、停用、归档、回滚。
- 提升模板与会议、审核、结算等业务场景的联动准确性。
- 提升模板下载留痕、权限控制、时效控制和风险控制能力。
- 提升后端接口一致性、可扩展性和并发安全。
- 提升数据库模型的多租户适配性与查询性能。

## 3. 现状问题归纳

### 3.1 前端页面布局

- 一个页面同时承载模板类型开关、模板列表、流程绑定、版本回滚、版本差异、上传建版，信息密度过高。
- 缺少统一筛选区，用户只能翻表找模板。
- 创建模板时需要手填 `projectId`、`meetingId`、`objectKey`，使用门槛高。
- 模板列表缺少关键治理字段展示，例如生效时间、水印开关、下载限制、最近更新时间、维护人。

### 3.2 显示内容

- 当前列表更偏“技术字段展示”，不够业务化。
- 版本信息展示不完整，无法快速判断“当前发布版”和“历史草稿版”差异。
- 下载日志页展示维度少，问题排查效率低。

### 3.3 用户操作

- 缺少按业务对象选择模板适用范围的交互。
- 流程绑定操作没有足够的场景提示和影响提示。
- 水印下载、普通下载、发布、回滚等高风险操作缺少确认与说明。
- 缺少预览、复制模板、批量筛选、快速查看版本历史等高频能力。

### 3.4 后端逻辑

- 模板流程绑定与业务消费链路没有完全闭环。
- 模板创建和新增版本存在并发安全风险。
- 有效期、水印、下载限流等字段虽然存在，但未完整落地到业务逻辑。
- 下载日志缺少标准分页、标准筛选和关联名称字段返回。

### 3.5 数据库设计

- 模板类型配置表的主键设计与多租户语义不完全一致。
- 日志和版本表索引偏弱，后续数据量上来后容易退化。
- 模板主表、版本表、流程绑定表的约束还不够完整。

## 4. 租户域模板管理优化方案

## 4.1 前端页面布局优化

### 4.1.1 页面结构重构

- 将当前单页改为“三级结构”：
  - 一级：模板管理首页
  - 二级：模板详情页
  - 二级：模板下载日志页
- 模板管理首页仅保留：
  - 查询筛选区
  - 模板列表区
  - 快捷操作区
- 版本历史、版本差异、流程绑定改为详情抽屉或详情页的子区块，不与主列表混排。

### 4.1.2 首页布局建议

- 顶部操作栏：
  - 新建模板
  - 刷新
  - 导出模板清单
- 查询筛选区：
  - 模板名称
  - 模板类型
  - 模板状态
  - 适用范围
  - 业务场景
  - 是否启用水印
  - 生效状态
  - 最近更新时间范围
- 列表区：
  - 默认按“最近更新时间倒序”
  - 支持分页
  - 支持空态提示

### 4.1.3 详情页布局建议

- 基本信息卡片：
  - 模板名称、类型、状态、业务场景、适用范围、生效时间、水印、下载限制
- 当前版本卡片：
  - 当前版本号、对象文件、变更说明、创建时间、创建人
- 版本历史区：
  - 版本号、状态、是否生效、变更说明、回滚原因、创建时间
- 流程联动区：
  - 当前已绑定场景
  - 是否允许绑定
  - 绑定影响说明
- 下载记录区：
  - 最近下载记录摘要

## 4.2 显示内容优化

### 4.2.1 模板列表字段建议

- 模板名称
- 模板类型
- 业务场景
- 适用范围
- 关联项目/会议名称
- 当前版本号
- 当前状态
- 生效开始时间
- 生效结束时间
- 水印开关
- 下载限流
- 最近更新时间
- 更新人

### 4.2.2 版本列表字段建议

- 版本号
- 版本状态
- 是否当前生效
- 文件名
- 对象存储路径
- 变更说明
- 回滚原因
- 创建人
- 创建时间

### 4.2.3 下载日志字段建议

- 模板名称
- 模板版本号
- 下载人姓名
- 下载人账号/手机号
- 下载时间
- IP
- User-Agent
- 下载方式
  - 普通下载
  - 水印下载
- 水印文案
- 关联项目/会议

## 4.3 用户操作优化

### 4.3.1 新建模板

- 取消手填 `objectKey` 为主的方式，改为：
  - 选择模板类型
  - 选择业务场景
  - 选择适用范围
  - 若为项目级，选择项目
  - 若为会议级，选择会议
  - 上传文件
  - 填写变更说明
  - 配置生效时间、水印、下载限流
- 上传成功后由系统自动回填对象存储路径。

### 4.3.2 模板列表操作

- 为每条模板提供分层操作：
  - 查看详情
  - 新增版本
  - 发布
  - 停用
  - 归档
  - 下载
  - 水印下载
  - 查看版本差异
  - 查看下载记录
  - 复制模板
- 对危险操作增加二次确认：
  - 发布
  - 回滚
  - 停用
  - 归档

### 4.3.3 版本管理

- 新增版本时默认继承模板基础配置，不重复填写范围与场景。
- 增加“与当前发布版对比”快捷入口。
- 回滚时必须填写回滚原因。
- 已归档模板不可新增版本。

### 4.3.4 流程联动

- 流程绑定独立为一个区块或独立弹窗。
- 绑定时只允许选择：
  - 已发布
  - 未停用
  - 场景一致
  - 当前生效
  的模板。
- 显示绑定影响提示，例如：
  - 绑定后将用于会议推荐
  - 绑定后将用于审核通知
  - 绑定后将用于结算材料

### 4.3.5 下载日志

- 支持按以下条件筛选：
  - 模板名称
  - 模板 ID
  - 下载人
  - 版本号
  - 下载时间范围
  - IP
  - 下载方式
- 支持跳转查看“该模板全部下载记录”。

## 4.4 后端逻辑优化

### 4.4.1 查询接口

- 模板列表接口增加标准分页与筛选参数：
  - `templateName`
  - `templateType`
  - `status`
  - `scopeType`
  - `bizScene`
  - `watermarkEnabled`
  - `effectiveStatus`
  - `pageNo`
  - `pageSize`
- 下载日志接口增加标准分页与筛选参数，并返回关联名称字段，不再依赖前端二次查用户和模板列表补名。

### 4.4.2 模板生命周期校验

- 发布校验：
  - 当前版本文件存在
  - 模板类型已启用
  - 若配置有效期，开始时间不能晚于结束时间
- 停用校验：
  - 若被流程联动使用，需提示影响
- 归档校验：
  - 已归档模板不可再发布、不可新增版本
- 回滚校验：
  - 只能回滚到本模板已有版本
  - 回滚原因必填

### 4.4.3 流程联动闭环

- 流程绑定时增加强校验：
  - `sceneCode` 必须与模板 `bizScene` 一致
  - 模板必须为 `PUBLISHED`
  - 模板必须在生效期内
- 业务消费链路按联动关系读模板，不允许页面配置和实际业务读取脱节。
- 会议推荐、审核通知、结算模板获取逻辑统一经过模板服务，不各自散落实现。

### 4.4.4 下载能力治理

- 普通下载与水印下载分开记录下载类型。
- 若模板启用下载限流，则下载前校验单位时间内下载次数。
- 若模板配置有效期，则过期后禁止下载。
- 若模板启用水印下载，则需要真正生成带水印文件或带水印预签名资源，而不是只回传文案。

### 4.4.5 并发与事务安全

- 创建模板后获取主键不要再用 `MAX(id)`，改为标准主键回填。
- 新增版本号不要再用 `MAX(version_no)+1` 裸算，改为：
  - 悲观锁
  - 或唯一约束重试
  - 或独立版本号分配策略
- 发布、回滚、建版操作保持事务一致性，避免主表状态和版本表状态不一致。

### 4.4.6 可测试性

- 增加自动化测试覆盖：
  - 创建模板
  - 并发新增版本
  - 发布/停用/归档/回滚
  - 流程绑定场景校验
  - 有效期校验
  - 下载限流
  - 日志分页与筛选

## 4.5 数据库设计优化

### 4.5.1 `template`

- 建议补充或强化约束：
  - `tenant_id + template_name + scope_type + scope_id + biz_scene` 可考虑唯一性策略
  - 状态字段增加明确枚举约束
- 建议补充索引：
  - `(tenant_id, status, updated_at)`
  - `(tenant_id, template_type, status)`
  - `(tenant_id, biz_scene, status)`
  - `(tenant_id, scope_type, scope_id)`

### 4.5.2 `template_version`

- 建议保留唯一约束：
  - `(tenant_id, template_id, version_no)`
- 建议新增索引：
  - `(tenant_id, template_id, is_effective)`
  - `(tenant_id, template_id, created_at)`
- 建议增加字段：
  - `file_name`
  - `file_size`
  - `content_type`
  - `checksum`

### 4.5.3 `template_download_log`

- 建议新增字段：
  - `download_type`
  - `watermark_text`
  - `project_id`
  - `meeting_id`
- 建议新增索引：
  - `(tenant_id, template_id, downloaded_at)`
  - `(tenant_id, user_id, downloaded_at)`
  - `(tenant_id, downloaded_at)`

### 4.5.4 `template_type_option`

- 现有主键建议调整为适合多租户的联合唯一约束：
  - 主键独立 `id`
  - 唯一键 `(tenant_id, type_code)`
- 避免 `type_code` 全局唯一导致多租户扩展受限。

### 4.5.5 `template_flow_link`

- 建议保留：
  - `(tenant_id, scene_code)` 唯一
- 建议增加：
  - 绑定来源
  - 绑定说明
  - 最近绑定人
  - 最近绑定时间

## 4.6 权限与风控优化

- 继续保留租户域权限拆分：
  - 查询
  - 创建
  - 发布
  - 停用
  - 归档
  - 回滚
  - 下载
  - 流程绑定
- 补充细粒度操作审计：
  - 模板创建
  - 版本新增
  - 发布
  - 回滚
  - 流程绑定
  - 普通下载
  - 水印下载
- 对高风险操作输出审计原因字段：
  - 回滚原因
  - 归档原因
  - 水印下载说明

## 4.7 交互与体验优化

- 统一中文文案，避免技术字段直接暴露给业务用户。
- 统一状态文案与颜色：
  - 草稿
  - 已发布
  - 已停用
  - 已归档
- 对空数据场景增加引导：
  - 暂无模板，请先创建
  - 暂无下载记录
- 对失败场景返回可理解提示：
  - 模板已归档，不能新增版本
  - 模板未在生效期内，不能绑定流程
  - 当前小时下载次数已达上限

## 5. 分期实施建议

## 5.1 P0：必须先做

- 模板列表筛选与标准分页
- 下载日志标准分页与筛选
- 创建模板交互优化，取消手填 `objectKey`
- 流程绑定强校验
- 模板创建/新增版本并发安全修复
- 发布/停用/归档/回滚状态机校验补齐

## 5.2 P1：强烈建议做

- 模板详情页与版本历史重构
- 有效期控制落地
- 水印下载真实落地
- 下载限流落地
- 下载日志返回关联名称，去掉前端补查
- 复制模板能力

## 5.3 P2：体验增强

- 模板预览
- 模板变更摘要对比优化
- 关联业务影响提示
- 模板清单导出
- 模板治理仪表盘

## 6. 验收标准建议

- 用户可以在 3 步内完成模板创建，不需要手填对象存储路径。
- 用户可以在列表中快速筛出“某场景、某状态、某范围”的模板。
- 流程绑定后，业务读取到的模板与绑定配置一致。
- 并发建版不会出现版本号冲突或串模板。
- 下载日志可分页、可筛选、可定位到具体用户与版本。
- 有效期、水印、下载限流配置能被真实执行，而不是只存库不生效。

## 7. 推荐实施顺序

1. 先改后端查询、状态机、并发安全、日志接口。
2. 再改前端页面结构与创建流程。
3. 再补流程联动闭环、水印、限流、有效期。
4. 最后补预览、复制、导出、治理报表等增强能力。