## 任务目标
在当前 Java + Vue 工程中完成统计指标与报表数据链路开发，使用真实数据库和既有业务接口，打通指标计算、汇总卡片、图表、可复算明细与报表导出。先查清当前实现和口径依据，再实际修改代码、运行验证；不能只交付评审意见、静态页面或带模拟数字的演示。
优先完成一组业务含义明确、能够查到来源并验证结果的指标。沿用实际数据库、框架版本、权限模型和界面规范，不为本次需求改造全站或建设通用数据平台。
## 输入信息（选填）
统计业务：
工程与口径资料：
两项均可留空，也可直接说明想查看的业务结果。版本、接口、数据库字段、图表库和运行命令由执行者从工程查找。
## 信息不完整时
先只读确认目标目录、未提交改动、相关页面路由、后端入口、Mapper、表结构与测试，保留现有行为基线。追踪已有报表、业务明细、状态字典和权限过滤，区分业务确认的规则、当前代码行为及尚无依据的推测；代码存在不等于口径正确。
没有新说明时沿用已有口径、时间范围、精度和交互方式，但发现彼此矛盾时不能任意挑选。资料留空、写“暂无”或保留输入标记，都按缺失处理，不当作实际参数。可读取的信息自行补齐，不要求用户先整理完整指标清单。
无法确认统计对象、分子分母、状态范围、金额含义或归属时区时，只暂停依赖该缺口的指标，集中说明少量关键问题并继续实现已确认指标及共用查询、权限、页面和测试。未确认指标不得填零或猜公式；确需保留入口时显示“口径待确认”。权限来源无法确认时不得开放数据，先完成受保护的接口结构与隔离测试。
只有表结构或接口资料时，先完成有依据的查询、接口映射、图表接入及固定样本断言；没有可访问工程时交付与已知资料对应的核心实现和可独立运行的测试样例，写清接入位置。完全缺少业务证据时，仅可制作明确标为合成场景的计算与权限测试样例，不能把它当成实际业务指标，也不能用空文件或待办清单冒充实现完成。
## 执行要求
1. 建立能追到数据的指标字典。每项写清稳定编码、名称、用途、事实表与明细主键、记录粒度、统计对象、计算式、单位、维度、去重键、有效状态、时间字段、空值处理和口径依据；比率补充分子分母，金额补充币种和精度。说明它是期间发生量、时点存量还是累计值，能否跨时间、组织或分类相加。复用已有配置或代码定义，不为展示字典额外建表；业务定义不能由字段名称推断。
2. 先确定事实粒度，再写关联与聚合。检查主从表、一对多和多对多的关联前后行数，避免金额或次数随子表记录被重复累计。按实际关系采用先聚合再关联、存在性过滤等方案；COUNT(DISTINCT 业务键) 只用于确需对象去重的口径，不能用 SUM(DISTINCT 金额) 掩盖关联放大，因为不同业务记录可能金额相同。检查过滤放在 JOIN 条件还是 WHERE 中的差异，不能意外丢掉没有子记录的对象。
3. 实现可复算明细。每项指标给出对应筛选条件、参与计算的业务键及必要贡献字段；比率提供分子、分母所属记录及计算方法。明细必须能解释排除项和去重结果，不能只跳到一个条件不全的通用列表。非可加指标应按其原公式复算，不能强求分类去重人数之和等于全局去重人数，或将各组百分比直接平均。汇总从完整授权结果计算，不从当前页行数据累加。
4. 分清无数据、未知、零与异常。核对 COUNT(*)、COUNT(字段) 和 SUM 的实际 SQL 语义；只有业务规定“没有发生即为零”时才把相应空结果转零。缺失数据、分母为零和查询失败不能混成 0%，也不能静默丢弃异常记录。金额在数据库和 Java 中使用符合现有精度的精确类型，如 DECIMAL 与 BigDecimal；舍入阶段、精度及方式须有依据。跨币种不直接相加，缺换算口径则暂停对应合计。接口保留精确金额和大整数标识，避免前端数值转换丢失精度。
5. 将时间边界落实到查询。核对浏览器、Java、数据库字段与连接配置的时区及日期含义，区分发生时间、创建时间、更新时间和业务归属日期。新增期间查询优先用起点包含、终点不包含的范围，并保持现有业务契约；日、周、月、跨年和同环比使用明确的日历口径，不能用固定毫秒数替代业务周期。缺失时间桶仅在数据覆盖完整且无记录确实代表零时补零。历史状态被修改、迟到记录或补录是否重算历史，必须沿用可追溯规则。
6. 让权限贯穿整个数据链路。身份、租户、组织及数据范围由后端可信上下文确定，客户端筛选只能缩小允许范围。卡片、曲线、分组名称、明细、总数和导出使用一致的权限条件；空权限集合不能退化为不加条件。下钻参数重新校验，不能仅靠隐藏按钮。若使用缓存或异步导出，结果须绑定相应查询及授权范围，下载时重新检查权限；历史报表快照也不能绕过当前授权。
7. 按现有分层完成后端。Controller 负责请求与响应，Service 组织指标与权限规则，Mapper 执行查询，区分 DTO、DO 和 VO。本次 Java SQL 全部放入 MyBatis XML Mapper，禁止在业务层、Mapper 注解、Provider 或 Java 字符串中编写、拼接 SQL；工程持久层不同则先说明适配影响，不擅自改造全站。值参数使用 #{参数} 绑定，动态维度、列和排序采用服务端白名单映射，不接收前端 SQL 或直接使用美元符文本替换拼入用户输入。提取真实共用的过滤和映射，领域规则留在 Service，不创建万能 Util。稳定业务编码采用明确 code 的 enum，不持久化 ordinal；可配置字典以数据库为唯一来源，不重复维护两套值表，并兼容未知旧编码。
8. 明确分页、汇总与导出的数据一致性。规范化查询条件并区分当前页数量、全量记录数和业务指标；稳定排序补齐唯一键。筛选变化重置分页，导出按明确的全查询或选择范围执行，不能把当前页冒充全量。响应说明查询条件、生成时间和实际数据口径；生成时间或一个截止时间条件不等于数据库快照，历史记录仍可能被修改。需要单次响应内多个查询一致时，按实际数据库、事务隔离和连接路由实现有限范围的一致读取，不假定 READ COMMITTED 与 REPEATABLE READ 相同。需要跨请求复现相同结果时，使用工程已有的稳定版本、不可变事实或保存明细贡献值的报表快照，并验证快照生成本身的一致性；仅保存可变记录 ID 不足以冻结金额和状态。没有严格快照约定时如实说明各次查询可能随数据变化，不声称导出与先前页面绝对一致；不得把数据库事务一直挂到用户翻页或下载完成。
9. 让查询成本与业务规模匹配。按权限、时间、分组和排序条件检查索引复用及执行计划，避免在循环中逐维度查库或逐行远程补字段。使用适当批量查询、分页或分块读取，限定单次加载内存；导出复用已有组件与分块能力。时间跨度、维度数量、返回上限按工程约束确定，超限明确提示，不静默截断后仍显示“全部”。用有代表性的参数比较结果与查询成本；EXPLAIN ANALYZE 会实际执行语句，仅在可控测试条件下使用。没有测量就不承诺性能收益，缓存、汇总表和预计算只在确有需要且刷新口径明确时引入。确需新增表或字段时，所有字段均补详细中文注释，说明含义、单位、编码、空值与默认值，不只写字段名译文。
10. 接入真实 Vue 页面与图表。沿用现有 UI 和图表库，以筛选区、指标摘要、趋势或分类图、明细表组织页面，中文名称、单位、图例和表格保持一致，采用清晰克制的商务界面。ECharts 项目明确数据维度与 series.encode 映射，其他图表库按实际版本实现；不为了凑组件新增图表库。图表使用真实接口数据，Tooltip 展示正确单位、期间和精确原值；若绘图必须转换为数值，只转换显示副本，不据此反算业务指标。按需求实现日期、组织和维度切换、图表点击下钻、返回保留筛选、分页及导出。图例隐藏系列默认只改变展示，不擅自重算业务分母；缩放展示范围与业务查询范围要有明确区分。
11. 完成界面状态与代码收尾。快速切换筛选时取消失效请求或校验请求序号，旧响应及其结束回调不能覆盖新结果或加载状态；按实际 Vue 版本清理侦听副作用。加载、刷新、无数据、口径待确认、失败和无权限分别处理，失败时不把旧数据伪装成新条件结果。检查图表容器尺寸变化、隐藏后显示和离开页面的资源释放，防止重复监听。删除确认无用的重复代码，保留框架约定与实际引用；业务注释说明计算原因和边界，公开方法按既有要求补 Javadoc，空格、换行、导入使用项目现有单一格式规则，禁止无关整仓格式化。
## 交付与验收
交付实际修改的 XML、Java 接口与实现、Vue 页面和路由接入、必要数据库变更及测试。指标字典、数据链路和口径结论优先写入已有位置或直接在答复给出，不随意新增 MD。逐项标明已实现指标、暂缓指标及其具体缺口，不能因一个口径未定而让已知部分永久停留在方案。
建立小而可人工复核的固定数据集，隔离于真实业务数据。依据已确认规则预先列出参与记录、贡献值和期望结果，再验证 SQL、接口、页面与导出；不能把待测 SQL 的输出直接当作期望值。至少覆盖：正常多维查询；空结果与全空字段；真实零值与零分母；一对多关联、同金额不同记录和去重对象跨分组；起止时刻与跨月跨年；不允许参与的状态；分页前后合计；越权组织及空权限；查询期间数据变化；接口异常和快速切换条件。仅对相关业务增加负值、退款、汇率或补录样本，不凭模板创造业务规则。
在真实项目支持的测试数据库运行 Mapper 与接口集成验证，断言明细复算、汇总、图表数据和导出在约定口径及快照范围内一致。通过浏览器实际操作筛选、图表下钻、返回、分页与导出，核对请求、返回值、文件内容和异常状态，不能仅凭截图或构建成功验收统计正确性。
最终列出文件与入口、已确认指标及复算样本、关键结果断言、必要性能证据和未完成项。写清依赖准备、配置来源、开发数据库变更、Java 与 Vue 启动及报表访问入口，命令和文件位置必须与实际工程一致。提供本次实际执行的后端测试、前端检查或构建、接口验证命令及工作目录、结果；从工程脚本推导可复现命令，不写不存在的脚本。未运行的命令单列并说明缺少条件，缺测试环境不宣称已通过，合成样本通过不代表真实业务数据已经核验。
## 参考资料与适用边界
以下官方资料于 2026-09-08 核验，支持对应技术语义，不提供本项目的业务指标定义：
- [MySQL 8.4 聚合函数](https://dev.mysql.com/doc/refman/8.4/en/aggregate-functions.html)：COUNT、SUM、NULL、DISTINCT 和精确数值聚合的行为。
- [MySQL 8.4 InnoDB 一致性非锁定读](https://dev.mysql.com/doc/refman/8.4/en/innodb-consistent-read.html)：同一事务中两种隔离级别的快照差异；跨请求报表一致性仍需工程实现。
- [MySQL 8.4 EXPLAIN](https://dev.mysql.com/doc/refman/8.4/en/explain.html)：执行计划与 EXPLAIN ANALYZE 的实际执行信息，具体能力按安装版本核对。
- [MyBatis Mapper XML](https://mybatis.org/mybatis-3/sqlmap-xml.html)：参数绑定、结果映射及文本替换边界。本条限定 SQL 放 XML 是项目要求，不能据此声称 MyBatis 不支持注解等其他方式。
- [Vue 侦听器](https://cn.vuejs.org/guide/essentials/watchers)：异步副作用清理；onWatcherCleanup 仅适用于 Vue 3.5+，且须在同步执行期间注册，不能无条件复制到旧版本。
- [Apache ECharts 数据集](https://echarts.apache.org/handbook/zh/concepts/dataset/)：dataset、dimensions 与 encode 的数据映射；不代表业务汇总或权限已由图表库保证。
本条是原创工程要求，未验证未来生成代码，不是国家标准、企业内部制度或官方认证。默认 Java + Vue；数据库、依赖及语法必须以工程实际版本为准，不能因引用 MySQL 8.4 文档就升级现有数据库。适用于业务统计报表开发。
