主题
数据报表 PRD
文档信息
| 项目 | 内容 |
|---|---|
| 产品名称 | PMForge - 数据报表 |
| 文档版本 | v2.0 |
| 创建日期 | 2026-09-24 |
| 最后更新 | 2026-09-24 |
| 文档状态 | 评审中 |
| 优先级 | P1 |
一、功能概述
1.1 功能定位
数据报表模块是 PMForge 平台的数据分析与可视化中心。如果把平台各模块产生的数据比作"原材料"，那报表模块就是"加工厂"——把散落在项目、任务、商城、CRM 等各处的原始数据，经过查询、汇总、排版，变成管理者看得懂、用得上的报表和大屏。
通俗理解： 想象你开了一家公司，每天产生大量销售单据、考勤记录、项目进度。报表模块就像一个"数据翻译官 + 可视化画板"——翻译官把数据库里的数字翻译成人类可读的表格，画板把这些表格拼成漂亮的数据大屏挂在办公室墙上。基于积木报表（JimuReport）实现，后台拖拽设计、前台一键查看。
核心能力矩阵：
| 能力 | 说明 | 使用频率 |
|---|---|---|
| 报表设计器 | 类 Excel 拖拽设计报表布局，绑定 SQL 数据源 | 中（设计一次，反复使用） |
| 报表管理 | 报表全生命周期：创建→发布→禁用→删除 | 中 |
| 数据源管理 | 接入多种数据库（MySQL/PostgreSQL/Oracle/SQL Server） | 低（配置一次，持续使用） |
| 数据大屏 | 拖拽式设计全屏数据看板，支持 20+ 图表组件 | 中 |
| 报表导出 | Excel / PDF 导出 + 打印，支持异步大数据量导出 | 高（日常高频操作） |
| 报表查看与筛选 | 前台用户查看报表、动态筛选、分页浏览 | 高（日常高频操作） |
| 报表统计 | 报表访问量、活跃用户、使用排行等运营数据 | 低 |
1.2 目标用户
| 用户类型 | 使用场景 | 典型操作 |
|---|---|---|
| 数据分析师 | 设计复杂业务报表、构建数据大屏 | 报表设计器、数据源管理、大屏设计 |
| 项目管理人员 | 查看项目进度报表、任务统计报表 | 报表查看、筛选、导出 |
| 团队负责人 | 查看团队绩效报表、周报/月报 | 报表查看、导出 Excel |
| 高层管理者 | 通过数据大屏查看全局数据概览 | 大屏全屏展示 |
| 系统管理员 | 管理数据源、配置报表权限 | 数据源管理、权限配置 |
1.3 业务价值
| 价值维度 | 当前痛点 | 解决方案 | 量化预期 |
|---|---|---|---|
| 降低报表开发门槛 | 每次新报表都需开发写代码，排期长 | 拖拽式设计器，业务人员自助完成 | 报表交付周期从 3-5 天→0.5 天 |
| 统一数据展示入口 | 各系统数据分散，需登录多个平台 | 多数据源接入，一个平台看全部 | 减少 70% 跨系统查询操作 |
| 数据驱动决策 | 管理层缺少实时数据看板 | 数据大屏实时展示关键指标 | 决策响应速度提升 50% |
| 线下分享与存档 | 数据只在系统中，无法离线流转 | Excel / PDF 导出 + 打印 | 满足 100% 线下汇报场景 |
| 数据安全 | 报表缺乏权限管控，敏感数据裸露 | 角色/部门/用户三级权限控制 | 权限覆盖率 100% |
1.4 功能范围
| 功能分类 | 后台管理端 | 前台用户端 | 说明 |
|---|---|---|---|
| 报表设计器 | ✅ | — | 拖拽式可视化设计 |
| 报表管理 | ✅ | ✅（查看） | 全生命周期管理 |
| 数据大屏设计 | ✅ | ✅（展示） | 20+ 图表组件 |
| 报表导出 | ✅ | ✅ | Excel / PDF / 打印 |
| 报表统计 | ✅ | — | 使用量与趋势分析 |
| 数据源管理 | ✅ | — | 多数据库接入 |
| 报表分类管理 | ✅ | — | 树形分类组织 |
| 报表权限配置 | ✅ | — | 细粒度访问控制 |
| 报表查看与筛选 | — | ✅ | 动态参数筛选 |
| 数据大屏展示 | — | ✅ | 全屏自适应展示 |
二、用户场景
2.1 用户角色
| 角色 | 描述 | 核心诉求 | 使用频率 |
|---|---|---|---|
| 报表设计者 | 数据分析师 / 开发人员 | 快速设计复杂报表、灵活配置数据源 | 每周 2-3 次 |
| 报表查看者 | 项目管理人员 / 团队负责人 | 方便查看报表数据、快速筛选和导出 | 每天 3-5 次 |
| 大屏观众 | 高层管理者 / 来访客户 | 直观展示关键数据指标、视觉效果好 | 每天 1-2 次 |
| 系统管理员 | 运维管理人员 | 管理数据源、配置权限、监控使用情况 | 每周 1-2 次 |
2.2 使用场景
场景1：数据分析师小李设计项目进度报表
故事线： 产品经理需要一份"各项目进度统计报表"，包含项目名称、计划完成日期、实际进度、延期天数。小李进入报表设计器 → 选择内置数据源 → 编写 SQL 查询项目进度数据 → 拖拽设计表头和单元格布局 → 设置延期天数 > 0 的单元格标红 → 预览确认 → 发布报表。
验收标准（AC）：
| # | 验收条件 | 验证方式 |
|---|---|---|
| 1 | SQL 编辑器中输入 SELECT 后自动提示表名，输入表名后提示字段名 | 操作验证 |
| 2 | 设置条件格式"延期天数 > 0 标红"后，预览中延期行确实显示红色背景 | 效果验证 |
| 3 | 报表发布后，前台用户可在报表列表中看到并打开查看 | 流程验证 |
| 4 | 设计过程中断网 60 秒内恢复，重新打开设计器可看到自动保存的草稿 | 异常验证 |
| 5 | 从新建到发布，一个简单报表设计耗时不超过 15 分钟 | 效率验证 |
场景2：高层管理者张总的数据大屏展示
故事线： 公司接待客户参观，张总打开"经营数据大屏"→ 大屏全屏展示：左侧项目总数（数字翻牌器滚动）、中间收入趋势折线图、右侧团队分布地图 → 数据每 30 秒自动刷新 → 客户对实时数据可视化效果印象深刻。
验收标准（AC）：
| # | 验收条件 | 验证方式 |
|---|---|---|
| 1 | 大屏在 1920×1080 分辨率下全屏展示，无滚动条、无留白 | UI 验证 |
| 2 | 数字翻牌器从 0 滚动到目标值，动画时长 1.5 秒 | 效果验证 |
| 3 | 数据按 30 秒间隔自动刷新，刷新过程中图表无闪烁 | 功能验证 |
| 4 | 在 1366×768 分辨率下等比缩放，所有组件完整可见 | 兼容性验证 |
| 5 | 大屏访问链接可直接发给客户，客户无需登录即可查看（配置免登录时） | 流程验证 |
场景3：项目经理小王导出月度报表
故事线： 月底小王需要提交项目月报 → 打开"项目月度统计报表" → 筛选日期为本月、选择所属部门 → 点击"导出 Excel" → 浏览器自动下载 项目月度统计报表_202609241530.xlsx → 小王附上分析说明后发送给领导。
验收标准（AC）：
| # | 验收条件 | 验证方式 |
|---|---|---|
| 1 | 导出的 Excel 数据与页面筛选条件一致，行数相同 | 数据验证 |
| 2 | Excel 文件包含表头行，列名与报表列名一致 | 格式验证 |
| 3 | 导出 1 万条数据以内，文件在 5 秒内开始下载 | 性能验证 |
| 4 | 导出超过 10 万条时，系统提示"已提交异步导出，完成后通知" | 边界验证 |
| 5 | 导出的 PDF 文件保留报表样式（合并单元格、背景色等） | 格式验证 |
场景4：系统管理员配置新数据源
故事线： 公司新上线了 CRM 系统，管理员需要将 CRM 数据库接入报表平台 → 进入数据源管理 → 新建数据源，选择 MySQL → 填写连接地址、端口、数据库名、用户名、密码 → 点击"测试连接"→ 显示"连接成功" → 保存。此后在报表设计器中即可选择该数据源查询 CRM 数据。
验收标准（AC）：
| # | 验收条件 | 验证方式 |
|---|---|---|
| 1 | 填写正确连接信息后，"测试连接"在 5 秒内返回成功 | 功能验证 |
| 2 | 填写错误密码时，"测试连接"返回明确错误提示"认证失败" | 异常验证 |
| 3 | 数据源保存后，密码以加密形式存储，后台页面脱敏显示（如 ****） | 安全验证 |
| 4 | 被报表引用的数据源点击删除时，提示"该数据源已被 X 个报表使用，无法删除" | 约束验证 |
| 5 | 内置数据源的"编辑"和"删除"按钮置灰不可操作 | UI 验证 |
场景5：系统管理员配置报表权限
故事线： 财务报表包含敏感薪资数据，管理员设置"仅财务部角色可查看" → 配置权限：选择"财务部"角色 → 权限类型"查看" → 保存。其他部门用户尝试访问该报表时，页面提示"无权限访问"。
验收标准（AC）：
| # | 验收条件 | 验证方式 |
|---|---|---|
| 1 | 配置财务部角色"查看"权限后，财务部用户可正常打开报表 | 正向验证 |
| 2 | 非财务部用户访问该报表，页面显示"暂无权限，请联系管理员" | 反向验证 |
| 3 | 未配置任何权限的报表，仅管理员和设计者可访问 | 默认策略验证 |
| 4 | 权限配置保存后即时生效，无需用户重新登录 | 即时性验证 |
| 5 | 支持同时配置角色权限和部门权限，取并集 | 组合验证 |
场景6：团队负责人查看报表并筛选数据
故事线： 团队负责人打开"任务统计报表" → 顶部筛选区域显示：部门（下拉选择）、日期范围（日期选择器）、任务状态（多选下拉） → 选择"研发部" + "本月" + "进行中" → 点击"查询" → 报表数据实时刷新 → 发现某项目延期率异常 → 点击"导出 Excel"下载详细记录排查。
验收标准（AC）：
| # | 验收条件 | 验证方式 |
|---|---|---|
| 1 | 筛选条件改变后点击"查询"，报表数据在 3 秒内刷新 | 性能验证 |
| 2 | 点击"重置"按钮，所有筛选条件恢复默认值，报表重新加载 | 功能验证 |
| 3 | 下拉选择控件的选项来自数据字典，修改字典后筛选项同步更新 | 联动验证 |
| 4 | 报表数据超过 50 条时自动分页，页码栏显示总数和翻页按钮 | UI 验证 |
| 5 | 导出的 Excel 数据与当前筛选结果完全一致（不多不少） | 数据验证 |
三、功能需求
3.1 后台管理端
3.1.1 功能清单
| 功能 | 优先级 | 说明 | 预计开发工时 |
|---|---|---|---|
| 报表设计器 | P0 | 基于积木报表的可视化报表设计 | 5 人日 |
| 报表管理 | P0 | 报表 CRUD、分类、权限配置 | 3 人日 |
| 数据源管理 | P0 | 多数据源接入与管理 | 3 人日 |
| 报表导出 | P0 | Excel / PDF 导出、打印 | 3 人日 |
| 数据大屏 | P1 | 大屏设计与发布 | 5 人日 |
| 报表分类管理 | P1 | 报表分类 CRUD | 1 人日 |
| 报表统计 | P2 | 使用统计、访问量分析 | 2 人日 |
3.1.2 报表设计器
页面结构（ASCII 线框）：
操作流程：
- 管理员进入报表管理页面，点击"新建报表"
- 选择报表类型（普通报表 / 分组报表 / 主从报表 / 卡片报表）
- 配置数据源：选择已有数据源或新建
- 编写 SQL 查询语句，配置参数（
${param}占位符） - 在编辑区域拖拽设计报表布局
- 设置单元格样式（字体、颜色、边框、对齐方式等）
- 绑定数据字段到单元格
- 设置条件格式、合计行等高级功能
- 点击"预览"查看报表效果
- 确认无误后保存并发布
业务规则：
| 规则编号 | 规则描述 | 设计原因 |
|---|---|---|
| R-01 | 报表设计器基于积木报表（JimuReport）组件实现 | 复用成熟开源方案，避免重复造轮子 |
| R-02 | 支持类 Excel 操作体验：合并单元格、设置行高列宽 | 业务人员熟悉 Excel，降低学习成本 |
| R-03 | SQL 中可使用 ${param} 占位符实现参数化查询 | 让同一报表服务不同筛选条件的用户 |
| R-04 | 支持字典翻译：字段值自动映射为中文显示 | 数据库存 code（如 status=1），报表显示"进行中" |
| R-05 | 支持条件格式：根据数据值动态设置单元格样式 | 让异常数据一眼可见（如延期标红） |
| R-06 | 报表设计自动保存（每 60 秒） | 防止设计过程中意外丢失内容 |
| R-07 | SQL 编辑器支持语法高亮、自动补全、一键格式化 | 提升 SQL 编写效率和准确性 |
| R-08 | 支持报表模板：可保存为模板供复用 | 相似报表无需从零设计 |
| R-09 | 支持报表导入/导出（JimuReport 格式） | 跨环境迁移报表配置 |
| R-10 | 报表设计支持撤销/重做操作（最多 50 步） | 误操作可快速回退 |
SQL 编辑器功能明细：
| 功能 | 说明 | 交互方式 |
|---|---|---|
| 语法高亮 | SQL 关键字、函数、字符串不同颜色 | 自动生效 |
| 自动补全 | 输入表名/字段名时弹出候选列表 | Ctrl + Space 触发 |
| 格式化 | SQL 语句一键美化排版 | 点击"格式化"按钮 |
| 执行测试 | 直接执行 SQL 查看数据结果（限 100 行） | 点击"执行"按钮 |
| 参数提取 | 自动识别 ${param} 并生成参数表单 | 保存时自动解析 |
| 全屏编辑 | SQL 编辑区域全屏展示 | 点击"全屏"图标 |
接口设计：
| 接口名称 | 请求方式 | 接口路径 | 说明 |
|---|---|---|---|
| 保存报表设计 | POST | /admin-api/jmreport/save | 保存报表设计内容 |
| 预览报表 | POST | /admin-api/jmreport/preview | 预览报表效果 |
| 执行 SQL 测试 | POST | /admin-api/jmreport/sql/test | 测试 SQL 查询（限 100 行） |
| 获取表字段列表 | GET | /admin-api/jmreport/datasource/fields | 获取数据表字段 |
| 导入报表模板 | POST | /admin-api/jmreport/import | 导入报表模板文件 |
| 导出报表模板 | GET | /admin-api/jmreport/export | 导出报表模板文件 |
请求参数（保存报表设计）：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | String | 是 | 报表名称，1-100 字符 |
| code | String | 是 | 报表编码，全局唯一，创建后不可修改 |
| category | Long | 否 | 分类 ID |
| type | Integer | 是 | 报表类型（1-普通 2-分组 3-主从 4-卡片） |
| content | String | 是 | 报表设计内容（JSON） |
| dataSource | Long | 否 | 数据源 ID |
| sqlContent | String | 否 | SQL 查询语句 |
| description | String | 否 | 报表描述，最多 500 字符 |
3.1.3 报表管理
页面结构（ASCII 线框）：
报表状态机：
业务规则：
| 规则编号 | 规则描述 | 设计原因 |
|---|---|---|
| R-01 | 报表编码全局唯一，创建后不可修改 | 编码是前台访问报表的唯一标识，变更会导致链接失效 |
| R-02 | 报表状态流转：草稿→已发布→已禁用，已禁用可重新发布 | 发布前可反复修改，发布后需先禁用才能编辑 |
| R-03 | 草稿状态报表仅设计者和管理员可预览 | 避免未完成报表被普通用户看到 |
| R-04 | 已发布报表需先禁用再删除 | 防止误删正在使用的报表 |
| R-05 | 复制报表生成新编码（原编码 + _copy） | 快速基于已有报表创建新报表 |
| R-06 | 报表列表默认按更新时间倒序排列 | 最近修改的报表最常用 |
| R-07 | 支持按报表名称、编码模糊搜索 | 快速定位目标报表 |
| R-08 | 报表权限可配置到角色/部门/用户三级 | 满足不同粒度的访问控制需求 |
接口设计：
| 接口名称 | 请求方式 | 接口路径 | 说明 |
|---|---|---|---|
| 获取报表分页列表 | GET | /admin-api/jmreport/report/page | 分页查询 |
| 获取报表详情 | GET | /admin-api/jmreport/report/get | 单个详情 |
| 创建报表 | POST | /admin-api/jmreport/report/create | 新建 |
| 更新报表 | PUT | /admin-api/jmreport/report/update | 编辑 |
| 删除报表 | DELETE | /admin-api/jmreport/report/delete | 删除 |
| 复制报表 | POST | /admin-api/jmreport/report/copy | 复制 |
| 发布报表 | PUT | /admin-api/jmreport/report/publish | 发布 |
| 禁用报表 | PUT | /admin-api/jmreport/report/disable | 禁用 |
| 配置报表权限 | PUT | /admin-api/jmreport/report/permission | 权限配置 |
| 批量删除 | DELETE | /admin-api/jmreport/report/batch-delete | 批量删除 |
| 批量移动分类 | PUT | /admin-api/jmreport/report/batch-move | 批量移动 |
请求参数（分页查询）：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | String | 否 | 报表名称（模糊匹配） |
| code | String | 否 | 报表编码（模糊匹配） |
| category | Long | 否 | 分类 ID |
| type | Integer | 否 | 报表类型 |
| status | Integer | 否 | 状态（0-草稿 1-已发布 2-已禁用） |
| createTime | DateTime[] | 否 | 创建时间范围 |
| pageNo | Integer | 是 | 页码 |
| pageSize | Integer | 是 | 每页条数，默认 20 |
返回结果（报表列表项）：
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | Long | 报表 ID |
| name | String | 报表名称 |
| code | String | 报表编码 |
| category | Long | 分类 ID |
| categoryName | String | 分类名称 |
| type | Integer | 报表类型 |
| typeName | String | 类型名称 |
| status | Integer | 状态 |
| statusName | String | 状态名称 |
| viewCount | Long | 访问量 |
| description | String | 描述 |
| creator | String | 创建者 |
| createTime | DateTime | 创建时间 |
| updateTime | DateTime | 更新时间 |
3.1.4 数据源管理
页面结构（ASCII 线框）：
支持的数据源类型：
| 数据源类型 | 说明 | 驱动类 | 使用场景 |
|---|---|---|---|
| MySQL | MySQL 数据库 | com.mysql.cj.jdbc.Driver | 最常用，PMForge 默认 |
| PostgreSQL | PostgreSQL 数据库 | org.postgresql.Driver | 开源场景 |
| Oracle | Oracle 数据库 | oracle.jdbc.OracleDriver | 企业级财务/ERP 系统 |
| SQL Server | SQL Server 数据库 | com.microsoft.sqlserver.jdbc.SQLServerDriver | Windows 生态 |
| 内置数据源 | PMForge 自身数据库 | 系统默认 | 查询平台本身数据 |
业务规则：
| 规则编号 | 规则描述 | 设计原因 |
|---|---|---|
| R-01 | 数据源名称不能重复 | 避免设计器中选错数据源 |
| R-02 | 数据库密码使用 AES 加密存储 | 防止数据库密码泄露 |
| R-03 | 新建数据源必须通过连接测试才可保存 | 确保数据源可用，避免保存无效配置 |
| R-04 | 数据源被报表引用时不可删除 | 防止正在使用的报表查询失败 |
| R-05 | 内置数据源不可编辑和删除 | 平台基础能力，不允许误操作 |
| R-06 | 支持连接池配置（最大连接数、超时时间） | 不同数据源负载不同，需独立配置 |
| R-07 | 数据源状态定期自动检测（每 5 分钟） | 及时发现连接异常，通知管理员 |
接口设计：
| 接口名称 | 请求方式 | 接口路径 | 说明 |
|---|---|---|---|
| 获取数据源列表 | GET | /admin-api/jmreport/datasource/list | 列表查询 |
| 获取数据源详情 | GET | /admin-api/jmreport/datasource/get | 单个详情 |
| 创建数据源 | POST | /admin-api/jmreport/datasource/create | 新建 |
| 更新数据源 | PUT | /admin-api/jmreport/datasource/update | 编辑 |
| 删除数据源 | DELETE | /admin-api/jmreport/datasource/delete | 删除 |
| 测试数据源连接 | POST | /admin-api/jmreport/datasource/test | 连接测试 |
| 获取数据库表列表 | GET | /admin-api/jmreport/datasource/tables | 获取表列表 |
请求参数（创建数据源）：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | String | 是 | 数据源名称 |
| type | String | 是 | 类型（mysql/postgresql/oracle/sqlserver/builtin） |
| url | String | 是 | 连接 URL |
| username | String | 是 | 用户名 |
| password | String | 是 | 密码 |
| maxPoolSize | Integer | 否 | 最大连接池大小（默认 10） |
| connectionTimeout | Integer | 否 | 连接超时（毫秒，默认 30000） |
| description | String | 否 | 描述 |
返回结果（数据源详情）：
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | Long | 数据源 ID |
| name | String | 数据源名称 |
| type | String | 数据源类型 |
| url | String | 连接 URL |
| username | String | 用户名 |
| password | String | 密码（脱敏：****） |
| maxPoolSize | Integer | 最大连接池大小 |
| connectionTimeout | Integer | 连接超时时间 |
| status | Integer | 状态（0-正常 1-异常） |
| lastTestTime | DateTime | 最后测试时间 |
| description | String | 描述 |
| createTime | DateTime | 创建时间 |
3.1.5 数据大屏
页面结构（ASCII 线框）：
支持的图表组件（20 种）：
| 组件类别 | 组件名称 | 典型用途 |
|---|---|---|
| 图表（10 种） | 折线图 | 展示数据趋势变化（如月度收入走势） |
| 柱状图 | 对比不同类别数据（如各部门任务数） | |
| 饼图 | 展示数据占比（如项目状态分布） | |
| 环形图 | 类似饼图，中间可显示总数 | |
| 仪表盘 | 展示百分比/进度（如任务完成率） | |
| 雷达图 | 多维度数据对比（如团队能力画像） | |
| 散点图 | 展示数据分布关系 | |
| 漏斗图 | 展示转化流程（如销售漏斗） | |
| 地图 | 地理数据可视化（如客户分布） | |
| 热力图 | 数据密度展示 | |
| 文本（3 种） | 文本组件 | 标题、说明文字 |
| 数字翻牌器 | 动态数字滚动（如今日订单数） | |
| 跑马灯 | 滚动文字通知 | |
| 媒体（3 种） | 图片 | 静态图片展示 |
| 视频 | 视频播放 | |
| 时钟 | 实时时钟显示 | |
| 装饰（4 种） | 边框 | 装饰性边框 |
| 背景 | 大屏背景设置 | |
| 分割线 | 区域分割线 | |
| 图标 | 装饰性图标 |
业务规则：
| 规则编号 | 规则描述 | 设计原因 |
|---|---|---|
| R-01 | 大屏默认分辨率 1920×1080，支持自定义 | 1080p 是当前主流显示器分辨率 |
| R-02 | 组件支持自由拖拽、缩放、对齐、图层调整 | 大屏设计需要灵活的布局能力 |
| R-03 | 数据刷新间隔可配置（默认 30 秒，最小 5 秒） | 平衡数据实时性和服务器压力 |
| R-04 | 大屏支持全屏展示模式（F11 适配） | 展示场景通常需要全屏 |
| R-05 | 发布后生成访问链接，可配置免登录访问 | 方便分享给外部访客 |
| R-06 | 支持大屏模板：保存为模板、从模板创建 | 同类大屏无需从零搭建 |
| R-07 | 组件数据支持静态数据和动态数据源两种模式 | 静态用于固定文字，动态用于实时数据 |
| R-08 | 画布支持网格吸附、辅助线对齐 | 帮助设计者快速对齐组件 |
| R-09 | 大屏支持多页面轮播展示 | 一块屏幕展示更多内容 |
| R-10 | 支持组件复制、粘贴、快捷键操作 | 提升设计效率 |
接口设计：
| 接口名称 | 请求方式 | 接口路径 | 说明 |
|---|---|---|---|
| 获取大屏分页列表 | GET | /admin-api/jmreport/screen/page | 分页查询 |
| 获取大屏详情 | GET | /admin-api/jmreport/screen/get | 单个详情 |
| 创建大屏 | POST | /admin-api/jmreport/screen/create | 新建 |
| 更新大屏 | PUT | /admin-api/jmreport/screen/update | 编辑 |
| 删除大屏 | DELETE | /admin-api/jmreport/screen/delete | 删除 |
| 发布大屏 | PUT | /admin-api/jmreport/screen/publish | 发布 |
| 获取访问链接 | GET | /admin-api/jmreport/screen/link | 访问链接 |
| 保存大屏模板 | POST | /admin-api/jmreport/screen/template/save | 保存模板 |
| 获取模板列表 | GET | /admin-api/jmreport/screen/template/list | 模板列表 |
请求参数（创建大屏）：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | String | 是 | 大屏名称 |
| width | Integer | 是 | 画布宽度（默认 1920） |
| height | Integer | 是 | 画布高度（默认 1080） |
| background | String | 否 | 背景设置（颜色/图片 URL） |
| components | JSON | 否 | 组件配置列表 |
| description | String | 否 | 大屏描述 |
返回结果（大屏详情）：
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | Long | 大屏 ID |
| name | String | 大屏名称 |
| width | Integer | 画布宽度 |
| height | Integer | 画布高度 |
| background | String | 背景设置 |
| components | JSON | 组件配置列表 |
| status | Integer | 状态（0-草稿 1-已发布 2-已禁用） |
| viewCount | Long | 访问量 |
| accessUrl | String | 访问链接 |
| refreshInterval | Integer | 刷新间隔（秒） |
| description | String | 描述 |
| creator | String | 创建者 |
| createTime | DateTime | 创建时间 |
| updateTime | DateTime | 更新时间 |
3.1.6 报表导出
导出状态机：
业务规则：
| 规则编号 | 规则描述 | 设计原因 |
|---|---|---|
| R-01 | Excel 导出使用 .xlsx 格式 | 兼容主流 Office 软件 |
| R-02 | PDF 导出保留报表样式和布局 | 确保打印效果与设计一致 |
| R-03 | 同步导出数据量上限 10 万条 | 防止大数据量同步导出导致请求超时 |
| R-04 | 超过 10 万条自动切换异步导出 | 大数据量后台生成，完成后通知下载 |
| R-05 | 导出文件名格式：报表名称_yyyyMMddHHmmss | 避免多次导出文件同名覆盖 |
| R-06 | 打印支持自定义纸张大小和方向 | 适配不同打印需求 |
| R-07 | 导出权限受报表独立权限控制 | 有查看权不一定有导出权 |
| R-08 | 导出时带入当前筛选条件 | 确保导出数据与用户看到的一致 |
| R-09 | 异步导出任务可在"导出记录"中查看进度和下载 | 用户不需要一直等待 |
接口设计：
| 接口名称 | 请求方式 | 接口路径 | 说明 |
|---|---|---|---|
| 导出 Excel | POST | /admin-api/jmreport/export/excel | 同步导出 |
| 导出 PDF | POST | /admin-api/jmreport/export/pdf | 同步导出 |
| 打印报表 | POST | /admin-api/jmreport/export/print | 打印 |
| 异步导出 | POST | /admin-api/jmreport/export/async | 提交异步任务 |
| 获取导出记录 | GET | /admin-api/jmreport/export/records | 任务列表 |
| 下载导出文件 | GET | /admin-api/jmreport/export/download | 下载文件 |
请求参数（导出 Excel）：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| reportId | Long | 是 | 报表 ID |
| params | Map | 否 | 报表参数 |
| exportRange | String | 否 | 导出范围（all/page/selected，默认 all） |
| includeHeader | Boolean | 否 | 是否包含表头（默认 true） |
返回结果（异步导出）：
| 字段名 | 类型 | 说明 |
|---|---|---|
| taskId | String | 导出任务 ID |
| status | String | 任务状态（processing/completed/failed） |
| message | String | 提示信息 |
3.1.7 报表统计
页面结构（ASCII 线框）：
业务规则：
| 规则编号 | 规则描述 | 设计原因 |
|---|---|---|
| R-01 | 统计数据每小时更新一次 | 避免频繁统计消耗数据库资源 |
| R-02 | 访问量统计包含查看和导出操作 | 全面反映报表使用情况 |
| R-03 | 支持按日/周/月粒度查看趋势 | 不同管理场景需要不同时间粒度 |
| R-04 | 统计时间范围最长 90 天 | 防止查询范围过大导致性能问题 |
| R-05 | 支持统计数据导出为 Excel | 满足线下汇报需求 |
接口设计：
| 接口名称 | 请求方式 | 接口路径 | 说明 |
|---|---|---|---|
| 获取统计概览 | GET | /admin-api/jmreport/statistics/overview | 概览数据 |
| 获取访问趋势 | GET | /admin-api/jmreport/statistics/trend | 趋势图 |
| 获取报表使用排行 | GET | /admin-api/jmreport/statistics/report-rank | Top10 |
| 获取用户访问排行 | GET | /admin-api/jmreport/statistics/user-rank | 用户排行 |
| 导出统计数据 | GET | /admin-api/jmreport/statistics/export | 导出 |
请求参数（访问趋势）：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| startTime | Date | 是 | 开始日期 |
| endTime | Date | 是 | 结束日期 |
| granularity | String | 是 | 统计粒度（day/week/month） |
| reportId | Long | 否 | 指定报表 ID（不传则统计全部） |
返回结果（统计概览）：
| 字段名 | 类型 | 说明 |
|---|---|---|
| totalReports | Integer | 报表总数 |
| totalScreens | Integer | 大屏总数 |
| todayViewCount | Long | 今日访问量 |
| todayActiveUsers | Integer | 今日活跃用户数 |
| totalViewCount | Long | 累计访问量 |
| totalDataSources | Integer | 数据源总数 |
3.1.8 报表分类管理
业务规则：
| 规则编号 | 规则描述 | 设计原因 |
|---|---|---|
| R-01 | 分类支持多级树形结构（最多 3 级） | 满足不同组织维度的分类需求 |
| R-02 | 分类名称同级不可重复 | 避免分类混淆 |
| R-03 | 分类下有报表时不可删除 | 防止报表变成"无分类"状态 |
| R-04 | 支持拖拽调整排序和层级 | 直观的分类管理体验 |
接口设计：
| 接口名称 | 请求方式 | 接口路径 | 说明 |
|---|---|---|---|
| 获取分类树 | GET | /admin-api/jmreport/category/tree | 树形列表 |
| 创建分类 | POST | /admin-api/jmreport/category/create | 新建 |
| 更新分类 | PUT | /admin-api/jmreport/category/update | 编辑 |
| 删除分类 | DELETE | /admin-api/jmreport/category/delete | 删除 |
| 排序分类 | PUT | /admin-api/jmreport/category/sort | 调整排序 |
请求参数（创建分类）：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | String | 是 | 分类名称，1-50 字符 |
| parentId | Long | 否 | 父分类 ID（空则顶级） |
| sort | Integer | 否 | 排序值 |
| description | String | 否 | 分类描述 |
3.2 前台用户端
3.2.1 功能清单
| 功能 | 优先级 | 说明 | 预计开发工时 |
|---|---|---|---|
| 报表查看 | P0 | 查看已发布的报表 | 3 人日 |
| 报表筛选 | P0 | 通过参数筛选报表数据 | 2 人日 |
| 报表导出 | P1 | 导出报表为 Excel / PDF | 2 人日 |
| 数据大屏展示 | P1 | 全屏查看数据大屏 | 2 人日 |
3.2.2 报表查看
页面结构（ASCII 线框）：
业务规则：
| 规则编号 | 规则描述 | 设计原因 |
|---|---|---|
| R-01 | 仅展示已发布状态的报表 | 草稿和禁用报表不应被普通用户看到 |
| R-02 | 报表数据根据用户权限进行过滤 | 不同角色看到不同范围的数据 |
| R-03 | 报表参数表单根据 SQL 参数自动生成 | 设计器配好参数，前台自动渲染筛选表单 |
| R-04 | 支持参数默认值配置 | 打开报表即显示最常用数据，减少操作 |
| R-05 | 报表数据支持自动刷新（可配置间隔） | 实时性要求高的报表需定时刷新 |
| R-06 | 表格支持列排序、列宽调整 | 用户自定义查看习惯 |
| R-07 | 大数据量报表默认分页展示（每页 50 条） | 避免一次加载过多数据导致页面卡顿 |
| R-08 | 支持报表全屏展示模式 | 专注查看数据，排除干扰 |
接口设计：
| 接口名称 | 请求方式 | 接口路径 | 说明 |
|---|---|---|---|
| 查看报表 | GET | /app-api/jmreport/view | 报表页面 |
| 获取报表数据 | POST | /app-api/jmreport/data | 数据查询 |
| 获取报表参数 | GET | /app-api/jmreport/params | 参数定义 |
请求参数（获取报表数据）：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| reportCode | String | 是 | 报表编码 |
| params | Map | 否 | 报表查询参数 |
| pageNo | Integer | 否 | 页码（默认 1） |
| pageSize | Integer | 否 | 每页条数（默认 50） |
返回结果（报表数据）：
| 字段名 | 类型 | 说明 |
|---|---|---|
| columns | Column[] | 列定义（字段名、类型、标题） |
| rows | Map[] | 数据行列表 |
| total | Long | 总记录数 |
| pageNo | Integer | 当前页码 |
| pageSize | Integer | 每页条数 |
3.2.3 报表筛选
支持的筛选控件类型：
| 控件类型 | 说明 | 参数格式 | 适用场景 |
|---|---|---|---|
| 输入框 | 文本输入 | 字符串 | 名称、编号等模糊搜索 |
| 下拉选择 | 单选下拉 | 单个值 | 状态、类型等固定选项 |
| 多选下拉 | 多选下拉框 | 值数组 | 同时选择多个部门/角色 |
| 日期选择 | 单个日期 | 日期字符串 | 指定某一天 |
| 日期范围 | 起止日期 | [start, end] | 按月/周筛选 |
| 级联选择 | 多级联动 | 值数组 | 省/市/区等多级分类 |
| 数字范围 | 起止数值 | [min, max] | 金额、数量范围 |
业务规则：
| 规则编号 | 规则描述 | 设计原因 |
|---|---|---|
| R-01 | 筛选控件类型根据参数类型自动匹配 | 减少设计器配置工作量 |
| R-02 | 下拉控件支持数据字典和 SQL 数据源两种数据来源 | 字典用于固定选项，SQL 用于动态数据 |
| R-03 | 支持必填参数和可选参数 | 必填参数确保报表数据有意义 |
| R-04 | 支持参数默认值 | 打开报表即显示常用数据 |
| R-05 | 支持参数联动（选 A 后自动筛选 B 的可选值） | 如选"部门"后，"员工"下拉只显示该部门员工 |
| R-06 | 筛选条件区域可折叠/展开 | 报表内容区域最大化 |
接口设计：
| 接口名称 | 请求方式 | 接口路径 | 说明 |
|---|---|---|---|
| 获取筛选参数定义 | GET | /app-api/jmreport/filter/params | 参数定义 |
| 获取下拉数据 | GET | /app-api/jmreport/filter/options | 下拉选项 |
返回结果（筛选参数定义）：
| 字段名 | 类型 | 说明 |
|---|---|---|
| paramName | String | 参数名 |
| paramLabel | String | 参数标签 |
| controlType | String | 控件类型 |
| required | Boolean | 是否必填 |
| defaultValue | Object | 默认值 |
| options | Option[] | 选项列表 |
| dataSource | String | 数据来源（dict/sql/static） |
3.2.4 报表导出
业务规则：
| 规则编号 | 规则描述 | 设计原因 |
|---|---|---|
| R-01 | 导出数据受报表权限控制 | 有查看权不一定有导出权 |
| R-02 | 导出数据与当前筛选条件一致 | 用户看到什么就导出什么 |
| R-03 | Excel 导出包含表头和所有数据行 | 确保文件可独立使用 |
| R-04 | PDF 导出保留报表样式 | 确保打印效果 |
| R-05 | 数据量超过上限时提示使用异步导出 | 避免浏览器超时 |
| R-06 | 打印功能调用浏览器原生打印 | 无需额外组件，兼容性好 |
接口设计：
| 接口名称 | 请求方式 | 接口路径 | 说明 |
|---|---|---|---|
| 导出 Excel | POST | /app-api/jmreport/export/excel | 导出 |
| 导出 PDF | POST | /app-api/jmreport/export/pdf | 导出 |
| 打印报表 | POST | /app-api/jmreport/export/print | 打印 |
请求参数（导出 Excel）：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| reportCode | String | 是 | 报表编码 |
| params | Map | 否 | 当前筛选参数 |
| includeHeader | Boolean | 否 | 是否包含表头（默认 true） |
3.2.5 数据大屏展示
业务规则：
| 规则编号 | 规则描述 | 设计原因 |
|---|---|---|
| R-01 | 大屏自动适配屏幕分辨率（等比缩放） | 不同会议室显示器分辨率可能不同 |
| R-02 | 数据按配置的间隔自动刷新 | 保持数据实时性 |
| R-03 | 数字翻牌器组件支持动态滚动效果 | 视觉冲击力更强 |
| R-04 | 图表组件支持数据加载动画 | 刷新时不突兀 |
| R-05 | 大屏支持多页轮播（可配置间隔） | 一块屏展示多组数据 |
| R-06 | 访问大屏可配置免登录 | 展厅/前台场景方便展示 |
| R-07 | 支持通过 URL 参数传入动态过滤条件 | 从其他系统跳转时带入筛选条件 |
接口设计：
| 接口名称 | 请求方式 | 接口路径 | 说明 |
|---|---|---|---|
| 查看大屏 | GET | /app-api/jmreport/screen/view | 大屏页面 |
| 获取大屏数据 | GET | /app-api/jmreport/screen/data | 组件数据 |
| 获取大屏配置 | GET | /app-api/jmreport/screen/config | 配置信息 |
请求参数（获取大屏数据）：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| screenId | Long | 是 | 大屏 ID |
| params | Map | 否 | 动态过滤参数 |
返回结果（大屏数据）：
| 字段名 | 类型 | 说明 |
|---|---|---|
| components | ComponentData[] | 各组件的数据列表 |
| refreshInterval | Integer | 建议刷新间隔（秒） |
| lastUpdateTime | DateTime | 数据最后更新时间 |
四、非功能需求
4.1 性能要求
| 指标 | 要求 | 实现策略 |
|---|---|---|
| 报表查询响应时间 | < 3 秒（10 万条数据以内） | SQL 优化 + 数据库索引 + 结果缓存 |
| 报表设计器加载时间 | < 2 秒 | 懒加载组件面板，设计内容按需渲染 |
| 数据大屏加载时间 | < 3 秒 | 组件数据并行加载，骨架屏过渡 |
| Excel 导出速度 | 10 万条 < 30 秒 | 流式写入（SXSSFWorkbook），避免内存溢出 |
| PDF 导出速度 | 100 页以内 < 15 秒 | 异步生成 + 进度回调 |
| 报表并发访问量 | 500 并发用户 | 读写分离 + 连接池 + 结果缓存 |
| 数据大屏并发访问量 | 200 并发用户 | 数据缓存 + 定时预计算 |
| SQL 查询超时 | 默认 30 秒，可配置 | Statement.setQueryTimeout() |
| 数据库连接池 | 每个数据源最大 10 个连接 | HikariCP 连接池管理 |
4.2 安全要求
| 要求 | 说明 | 实现方式 |
|---|---|---|
| 报表权限控制 | 基于角色/部门/用户的细粒度权限 | 拦截器校验 report_permission 表 |
| SQL 注入防护 | 参数化查询，禁止拼接 SQL | PreparedStatement + 参数校验 |
| 数据源密码加密 | AES 加密存储 | AES-256-GCM 加密，密钥从配置中心获取 |
| 导出权限 | 报表导出受独立权限控制 | 导出接口单独校验 jmreport:report:export |
| 数据脱敏 | 敏感字段支持配置脱敏规则 | 手机号/身份证等字段中间位替换为 * |
| 访问日志 | 记录所有报表访问和导出操作 | AOP 切面写入 report_access_log |
| 数据源隔离 | 不同租户的数据源严格隔离 | tenant_id 过滤 + 数据源连接隔离 |
| XSS 防护 | 报表内容 HTML 标签过滤 | Jsoup.clean() 白名单过滤 |
4.3 错误码定义
| 错误码 | 说明 | 触发场景 | 用户提示 |
|---|---|---|---|
| JMREPORT_001 | 报表编码已存在 | 创建报表时编码重复 | "报表编码已存在，请更换" |
| JMREPORT_002 | 报表不存在 | 查看/编辑不存在的报表 | "报表不存在" |
| JMREPORT_003 | 报表未发布 | 前台查看草稿状态报表 | "报表尚未发布，请联系管理员" |
| JMREPORT_004 | 无报表访问权限 | 用户无权查看该报表 | "暂无权限，请联系管理员" |
| JMREPORT_005 | 数据源名称重复 | 创建数据源时名称重复 | "数据源名称已存在" |
| JMREPORT_006 | 数据源连接失败 | 测试连接不通 | "连接失败：{具体原因}" |
| JMREPORT_007 | 数据源被引用无法删除 | 删除被报表使用的数据源 | "该数据源已被 {N} 个报表使用，无法删除" |
| JMREPORT_008 | SQL 执行超时 | SQL 查询超过 30 秒 | "查询超时，请优化 SQL 或缩小数据范围" |
| JMREPORT_009 | 导出数据量超限 | 同步导出数据超过 10 万条 | "数据量较大，已提交异步导出，完成后通知" |
| JMREPORT_010 | 报表已发布不可直接删除 | 删除已发布报表 | "已发布报表需先禁用再删除" |
| JMREPORT_011 | 分类下存在报表不可删除 | 删除非空分类 | "该分类下还有报表，请先移动报表" |
| JMREPORT_012 | 内置数据源不可操作 | 编辑/删除内置数据源 | "内置数据源不可修改" |
| JMREPORT_013 | 大屏名称重复 | 创建大屏时名称重复 | "大屏名称已存在" |
4.4 兼容性要求
| 端 | 要求 |
|---|---|
| PC 浏览器 | Chrome 80+、Firefox 75+、Safari 13+、Edge 80+ |
| 数据大屏展示 | 推荐 Chrome 全屏模式，分辨率 1920×1080 |
| 报表导出 | Excel 兼容 Office 2016+、WPS 2019+ |
| PDF 查看 | 兼容主流 PDF 阅读器 |
| 打印 | 兼容浏览器原生打印功能 |
| 移动端 | 支持移动端浏览器查看简单报表（响应式布局） |
五、数据设计
5.1 数据表概览
| 表名 | 说明 | 核心字段 | 预计数据量 |
|---|---|---|---|
| report | 报表主表 | name, code, type, status, sql_content | 百级 |
| report_category | 报表分类 | name, parent_id, sort | 十级 |
| report_data_source | 数据源 | name, type, url, password(加密) | 个位数 |
| report_screen | 数据大屏 | name, width, height, components | 十级 |
| report_permission | 报表权限 | report_id, target_type, target_id, permission | 百级 |
| report_export_record | 导出记录 | report_id, export_type, file_url, status | 千级/月 |
| report_access_log | 访问日志 | report_id, user_id, access_type, duration | 万级/月 |
5.2 表关系图
5.3 缓存策略
| 缓存 Key | 缓存内容 | 过期时间 | 更新策略 |
|---|---|---|---|
jmreport:config:{reportId} | 报表配置信息（设计内容、SQL 等） | 30 分钟 | 报表保存时主动失效 |
jmreport:screen:config:{screenId} | 大屏配置信息 | 30 分钟 | 大屏保存时主动失效 |
jmreport:datasource:list | 数据源列表 | 10 分钟 | 数据源变更时主动失效 |
jmreport:category:tree | 分类树 | 1 小时 | 分类变更时主动失效 |
jmreport:stats:overview | 统计概览数据 | 1 小时 | 定时刷新 |
5.4 数据表结构
5.4.1 报表表（report）
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | BIGINT | 是 | 报表 ID（主键） |
| name | VARCHAR(100) | 是 | 报表名称 |
| code | VARCHAR(100) | 是 | 报表编码（唯一） |
| category | BIGINT | 否 | 分类 ID |
| type | TINYINT | 是 | 报表类型（1-普通 2-分组 3-主从 4-卡片） |
| content | LONGTEXT | 否 | 报表设计内容（JSON） |
| data_source | BIGINT | 否 | 数据源 ID |
| sql_content | LONGTEXT | 否 | SQL 查询语句 |
| api_url | VARCHAR(512) | 否 | API 数据源 URL |
| status | TINYINT | 是 | 状态（0-草稿 1-已发布 2-已禁用） |
| view_count | BIGINT | 是 | 访问量（默认 0） |
| description | VARCHAR(500) | 否 | 报表描述 |
| sort | INT | 是 | 排序值（默认 0） |
| creator | VARCHAR(64) | 否 | 创建者 |
| create_time | DATETIME | 是 | 创建时间 |
| updater | VARCHAR(64) | 否 | 更新者 |
| update_time | DATETIME | 是 | 更新时间 |
| deleted | BIT | 是 | 删除标记（0-未删除 1-已删除） |
| tenant_id | BIGINT | 是 | 租户 ID |
5.4.2 报表分类表（report_category）
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | BIGINT | 是 | 分类 ID（主键） |
| name | VARCHAR(50) | 是 | 分类名称 |
| parent_id | BIGINT | 是 | 父分类 ID（0 为顶级） |
| sort | INT | 是 | 排序值 |
| description | VARCHAR(200) | 否 | 分类描述 |
| status | TINYINT | 是 | 状态（0-正常 1-禁用） |
| creator | VARCHAR(64) | 否 | 创建者 |
| create_time | DATETIME | 是 | 创建时间 |
| updater | VARCHAR(64) | 否 | 更新者 |
| update_time | DATETIME | 是 | 更新时间 |
| deleted | BIT | 是 | 删除标记 |
| tenant_id | BIGINT | 是 | 租户 ID |
5.4.3 报表数据源表（report_data_source）
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | BIGINT | 是 | 数据源 ID（主键） |
| name | VARCHAR(100) | 是 | 数据源名称 |
| type | VARCHAR(20) | 是 | 类型（mysql/postgresql/oracle/sqlserver/builtin） |
| url | VARCHAR(512) | 是 | 连接 URL |
| username | VARCHAR(100) | 是 | 用户名 |
| password | VARCHAR(255) | 是 | 密码（AES 加密存储） |
| max_pool_size | INT | 否 | 最大连接池大小（默认 10） |
| connection_timeout | INT | 否 | 连接超时（毫秒，默认 30000） |
| status | TINYINT | 是 | 状态（0-正常 1-异常） |
| last_test_time | DATETIME | 否 | 最后测试时间 |
| description | VARCHAR(200) | 否 | 描述 |
| creator | VARCHAR(64) | 否 | 创建者 |
| create_time | DATETIME | 是 | 创建时间 |
| updater | VARCHAR(64) | 否 | 更新者 |
| update_time | DATETIME | 是 | 更新时间 |
| deleted | BIT | 是 | 删除标记 |
| tenant_id | BIGINT | 是 | 租户 ID |
5.4.4 数据大屏表（report_screen）
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | BIGINT | 是 | 大屏 ID（主键） |
| name | VARCHAR(100) | 是 | 大屏名称 |
| width | INT | 是 | 画布宽度（默认 1920） |
| height | INT | 是 | 画布高度（默认 1080） |
| background | VARCHAR(512) | 否 | 背景设置（JSON） |
| components | LONGTEXT | 否 | 组件配置（JSON） |
| status | TINYINT | 是 | 状态（0-草稿 1-已发布 2-已禁用） |
| view_count | BIGINT | 是 | 访问量（默认 0） |
| access_url | VARCHAR(255) | 否 | 访问链接标识 |
| refresh_interval | INT | 否 | 刷新间隔（秒，默认 30） |
| enable_auth | BIT | 是 | 是否需要认证（默认 1） |
| description | VARCHAR(500) | 否 | 描述 |
| creator | VARCHAR(64) | 否 | 创建者 |
| create_time | DATETIME | 是 | 创建时间 |
| updater | VARCHAR(64) | 否 | 更新者 |
| update_time | DATETIME | 是 | 更新时间 |
| deleted | BIT | 是 | 删除标记 |
| tenant_id | BIGINT | 是 | 租户 ID |
5.4.5 报表权限表（report_permission）
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | BIGINT | 是 | 主键 ID |
| report_id | BIGINT | 否 | 报表 ID（与 screen_id 二选一） |
| screen_id | BIGINT | 否 | 大屏 ID |
| target_type | TINYINT | 是 | 授权对象类型（1-角色 2-部门 3-用户） |
| target_id | BIGINT | 是 | 授权对象 ID |
| permission | TINYINT | 是 | 权限类型（1-查看 2-导出 3-管理） |
| creator | VARCHAR(64) | 否 | 创建者 |
| create_time | DATETIME | 是 | 创建时间 |
| updater | VARCHAR(64) | 否 | 更新者 |
| update_time | DATETIME | 是 | 更新时间 |
| deleted | BIT | 是 | 删除标记 |
| tenant_id | BIGINT | 是 | 租户 ID |
5.4.6 报表导出记录表（report_export_record）
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | BIGINT | 是 | 主键 ID |
| report_id | BIGINT | 否 | 报表 ID |
| screen_id | BIGINT | 否 | 大屏 ID |
| user_id | BIGINT | 是 | 操作用户 ID |
| export_type | TINYINT | 是 | 导出类型（1-Excel 2-PDF 3-打印） |
| file_name | VARCHAR(255) | 否 | 文件名 |
| file_url | VARCHAR(512) | 否 | 文件 URL |
| file_size | BIGINT | 否 | 文件大小（字节） |
| status | TINYINT | 是 | 状态（0-处理中 1-已完成 2-失败） |
| params | JSON | 否 | 导出参数 |
| error_msg | VARCHAR(500) | 否 | 错误信息 |
| creator | VARCHAR(64) | 否 | 创建者 |
| create_time | DATETIME | 是 | 创建时间 |
| updater | VARCHAR(64) | 否 | 更新者 |
| update_time | DATETIME | 是 | 更新时间 |
| deleted | BIT | 是 | 删除标记 |
| tenant_id | BIGINT | 是 | 租户 ID |
5.4.7 报表访问日志表（report_access_log）
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | BIGINT | 是 | 主键 ID |
| report_id | BIGINT | 否 | 报表 ID |
| screen_id | BIGINT | 否 | 大屏 ID |
| user_id | BIGINT | 是 | 访问用户 ID |
| access_type | TINYINT | 是 | 访问类型（1-查看 2-导出 3-打印） |
| user_ip | VARCHAR(50) | 否 | 用户 IP |
| user_agent | VARCHAR(512) | 否 | 浏览器 UA |
| duration | INT | 否 | 访问时长（毫秒） |
| params | JSON | 否 | 访问参数 |
| creator | VARCHAR(64) | 否 | 创建者 |
| create_time | DATETIME | 是 | 创建时间 |
| updater | VARCHAR(64) | 否 | 更新者 |
| update_time | DATETIME | 是 | 更新时间 |
| deleted | BIT | 是 | 删除标记 |
| tenant_id | BIGINT | 是 | 租户 ID |
5.5 数据字典
| 字典类型 | 字典值 | 说明 |
|---|---|---|
| report_type | 1-普通报表 2-分组报表 3-主从报表 4-卡片报表 | 报表类型 |
| report_status | 0-草稿 1-已发布 2-已禁用 | 报表/大屏状态 |
| report_datasource_type | mysql / postgresql / oracle / sqlserver / builtin | 数据源类型 |
| report_datasource_status | 0-正常 1-异常 | 数据源状态 |
| report_permission_type | 1-角色 2-部门 3-用户 | 权限授权对象类型 |
| report_permission_action | 1-查看 2-导出 3-管理 | 权限操作类型 |
| report_export_type | 1-Excel 2-PDF 3-打印 | 导出类型 |
| report_export_status | 0-处理中 1-已完成 2-失败 | 导出任务状态 |
| report_access_type | 1-查看 2-导出 3-打印 | 访问类型 |
六、跨模块联动
6.1 联动关系总览
| 联动模块 | 联动方向 | 联动内容 | 触发方式 |
|---|---|---|---|
| 认证授权（01-01） | 报表 → 认证 | 报表访问需登录态校验 | 拦截器 |
| 角色权限（01-03） | 报表 → 权限 | 报表权限基于角色体系 | 接口调用 |
| 用户管理（01-05） | 报表 → 用户 | 报表权限可绑定到用户/部门 | 接口调用 |
| 消息通知（02-03） | 报表 → 通知 | 异步导出完成后推送通知 | 事件驱动 |
| 文件存储（02-02） | 报表 → 存储 | 导出文件存储到文件服务 | 接口调用 |
| 日志审计（01-08） | 报表 → 审计 | 报表设计变更操作记录审计日志 | AOP 切面 |
6.2 详细联动设计
6.2.1 报表 ↔ 认证授权（01-01）
| 联动场景 | 触发条件 | 联动行为 | 数据流向 |
|---|---|---|---|
| 报表访问鉴权 | 用户访问报表页面 | 校验用户登录态和 Token 有效性 | 报表 → 认证模块 |
| 大屏免登录访问 | 大屏配置 enable_auth=0 | 跳过登录校验，允许匿名访问 | 报表 → 认证模块 |
| 前台接口鉴权 | 调用 /app-api/jmreport/* | Token 校验 + 用户身份解析 | 报表 → 认证模块 |
6.2.2 报表 ↔ 角色权限（01-03）
| 联动场景 | 触发条件 | 联动行为 | 数据流向 |
|---|---|---|---|
| 后台菜单权限 | 用户登录加载菜单 | 根据 jmreport:* 权限标识过滤菜单 | 权限模块 → 报表 |
| 报表访问权限 | 用户打开报表 | 查询 report_permission 表，校验角色/部门/用户权限 | 报表 → 权限模块 |
| 导出权限校验 | 用户点击导出 | 校验 jmreport:report:export 权限 + 报表独立导出权限 | 报表 → 权限模块 |
| 权限对象关联 | 配置报表权限 | 授权对象从角色列表/部门列表中选择 | 报表 → 权限模块 |
6.2.3 报表 ↔ 用户管理（01-05）
| 联动场景 | 触发条件 | 联动行为 | 数据流向 |
|---|---|---|---|
| 用户权限查询 | 校验报表访问权限 | 获取用户所属角色和部门，匹配权限记录 | 报表 → 用户模块 |
| 用户离职处理 | 用户状态变为禁用 | 该用户创建的报表标记为禁用，转移给管理员 | 用户模块 → 报表 |
| 部门筛选 | 报表 SQL 中使用部门参数 | 从部门树获取部门 ID 传入报表参数 | 用户模块 → 报表 |
6.2.4 报表 ↔ 消息通知（02-03）
| 联动场景 | 触发条件 | 联动行为 | 数据流向 |
|---|---|---|---|
| 异步导出完成 | 导出任务状态变为 completed | 向用户发送站内通知"您的报表已导出完成，点击下载" | 报表 → 通知模块 |
| 异步导出失败 | 导出任务状态变为 failed | 向用户发送站内通知"报表导出失败：{原因}" | 报表 → 通知模块 |
| 数据源异常 | 数据源自动检测失败 | 向管理员发送告警通知"数据源 {name} 连接异常" | 报表 → 通知模块 |
6.2.5 报表 ↔ 文件存储（02-02）
| 联动场景 | 触发条件 | 联动行为 | 数据流向 |
|---|---|---|---|
| 导出文件存储 | Excel/PDF 导出完成 | 将生成的文件上传到文件存储服务，获取 file_url | 报表 → 文件存储 |
| 导出文件下载 | 用户点击下载 | 通过 file_url 从文件存储服务获取文件 | 报表 → 文件存储 |
| 报表模板导入 | 用户上传报表模板文件 | 模板文件上传到临时存储，设计器读取解析 | 报表 → 文件存储 |
| 导出文件清理 | 导出记录超过 30 天 | 定时任务清理过期导出文件 | 报表 → 文件存储 |
6.2.6 报表 ↔ 日志审计（01-08）
| 联动场景 | 触发条件 | 联动行为 | 数据流向 |
|---|---|---|---|
| 报表设计变更 | 保存报表设计内容 | 记录操作日志：操作人、报表名称、变更时间 | 报表 → 审计模块 |
| 数据源配置变更 | 创建/编辑/删除数据源 | 记录操作日志（含数据源名称、操作类型） | 报表 → 审计模块 |
| 权限配置变更 | 修改报表访问权限 | 记录操作日志（含报表名称、权限变更内容） | 报表 → 审计模块 |
| 报表发布/禁用 | 发布或禁用报表 | 记录状态变更日志 | 报表 → 审计模块 |
七、附录
7.1 名词解释
| 术语 | 全称 | 通俗理解 |
|---|---|---|
| 积木报表 | JimuReport | 一款开源的可视化报表工具，像搭积木一样拼出报表 |
| 数据源 | Data Source | 报表连接的数据库，就像水管的水源地，报表从这取数据 |
| 报表设计器 | Report Designer | 可视化报表编辑工具，类似 Excel 但能绑定数据库 |
| 数据大屏 | Data Screen | 把多个图表拼成一张全屏"数据海报"，挂在大屏幕上 |
| 分组报表 | Group Report | 按某个字段分组展示，如"按部门分组看任务数" |
| 主从报表 | Master-Detail Report | 上面看主表（如订单列表），下面看子表（如订单明细） |
| 参数化查询 | Parameterized Query | SQL 里留"填空位"，用户填什么就查什么 |
| 条件格式 | Conditional Formatting | 数据满足某条件时自动变色，如"延期>0 标红" |
| 数据字典 | Data Dictionary | 系统预定义的"翻译对照表"，如 1=进行中 2=已完成 |
| 连接池 | Connection Pool | 数据库连接的"共享单车"，用完放回，下个人继续用 |
| 数字翻牌器 | Number Flipper | 大屏上从 0 滚动到目标数字的动画效果 |
| 异步导出 | Async Export | 数据太多时后台慢慢生成文件，完成后通知你下载 |
| 报表编码 | Report Code | 报表的唯一身份证号，创建后不能改 |
| 报表模板 | Report Template | 保存好的报表设计，可以复制给新报表用 |
| 网格吸附 | Grid Snap | 拖拽组件时自动对齐到网格线，让布局整齐 |
| 辅助线 | Guide Line | 设计器中的对齐参考线，帮助精确排列组件 |
| SQL 注入 | SQL Injection | 黑客通过拼接恶意 SQL 攻击数据库，需用参数化查询防范 |
| 等比缩放 | Proportional Scale | 大屏在不同分辨率下按比例缩放，不变形不留白 |
| 数据脱敏 | Data Masking | 把手机号中间 4 位变成 ****，防止隐私泄露 |
| 多租户 | Multi-Tenant | 一套系统服务多家公司，各家公司数据互相看不到 |
| 报表权限 | Report Permission | 控制谁能看/导出/管理某个报表的安全机制 |
7.2 权限标识汇总
| 权限标识 | 说明 | 所属功能 |
|---|---|---|
| jmreport:report:list | 查看报表列表 | 报表管理 |
| jmreport:report:query | 查询报表详情 | 报表管理 |
| jmreport:report:create | 创建报表 | 报表管理 |
| jmreport:report:update | 编辑报表 | 报表管理 |
| jmreport:report:delete | 删除报表 | 报表管理 |
| jmreport:report:publish | 发布报表 | 报表管理 |
| jmreport:report:export | 导出报表 | 报表管理 |
| jmreport:report:permission | 配置报表权限 | 报表管理 |
| jmreport:designer:use | 使用报表设计器 | 报表设计器 |
| jmreport:datasource:list | 查看数据源列表 | 数据源管理 |
| jmreport:datasource:create | 创建数据源 | 数据源管理 |
| jmreport:datasource:update | 编辑数据源 | 数据源管理 |
| jmreport:datasource:delete | 删除数据源 | 数据源管理 |
| jmreport:datasource:test | 测试数据源连接 | 数据源管理 |
| jmreport:screen:list | 查看大屏列表 | 数据大屏 |
| jmreport:screen:create | 创建大屏 | 数据大屏 |
| jmreport:screen:update | 编辑大屏 | 数据大屏 |
| jmreport:screen:delete | 删除大屏 | 数据大屏 |
| jmreport:screen:publish | 发布大屏 | 数据大屏 |
| jmreport:category:list | 查看分类列表 | 分类管理 |
| jmreport:category:create | 创建分类 | 分类管理 |
| jmreport:category:update | 编辑分类 | 分类管理 |
| jmreport:category:delete | 删除分类 | 分类管理 |
| jmreport:statistics:view | 查看报表统计 | 报表统计 |
| jmreport:statistics:export | 导出统计数据 | 报表统计 |
7.3 积木报表集成说明
| 项目 | 说明 |
|---|---|
| 集成方式 | 通过 JimuReport Starter 集成到 Spring Boot |
| 版本要求 | JimuReport >= 1.6.0 |
| 路由前缀 | /jmreport（设计器）、/admin-api/jmreport（后台接口）、/app-api/jmreport（前台接口） |
| 权限对接 | 自定义权限拦截器对接 PMForge 权限体系 |
| 数据源对接 | 扩展 JimuReport 数据源接口支持多租户 |
| 主题适配 | 报表设计器样式与 PMForge 后台主题保持一致 |
7.4 变更记录
| 版本 | 日期 | 修改内容 | 修改人 |
|---|---|---|---|
| v1.0 | 2026-09-24 | 初始版本 | PM Team |
| v2.0 | 2026-09-24 | 增强版：补充验收标准、状态机、ASCII 线框、跨模块联动、名词解释 | PM Team |
本文档为数据报表模块 PRD v2.0，如有问题请联系产品负责人。