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. 最后补预览、复制、导出、治理报表等增强能力。