# Repository Guidelines

## Agent 工作方式
进入本仓库后，先阅读本文件，再开始分析、修改或输出结论。不要跳过现有文档直接下判断，至少先结合根目录现有说明、`doc/`、`package.json`、目标模块代码和相关配置确认上下文；如果存在 `README.md`，也应一并阅读。

日常交互遵循以下习惯：

- 先整理执行方案，说明目标、涉及模块、预计修改点和验证方式，待用户评审确认后再执行。
- 不要想当然；如果需求存在歧义、前提不清或有多种实现路径，先说清假设与取舍，再继续。
- 默认先确认任务是否位于 `frontend/src/`，再按 `views/`、`components/`、`api/`、`stores/`、`routers/`、`hooks/` 的调用关系向下分析；只有涉及桌面壳层或启动问题时，再继续查看 `electron/`、`scripts/`、`build/`、`public/`。
- 当 `views/**/index.vue` 内容过大时，优先按功能块抽到当前功能目录下的 `components/`，页面入口只保留编排、状态组织和事件分发，不把大段展示结构继续堆在 `index.vue`。
- 涉及 preload 桥接、主进程配置、自动更新、窗口生命周期、端口检测或打包启动链路时，先核对已有实现和 `doc/` 中的说明，避免只看局部代码就下结论。
- 回复风格保持简洁、直接，优先给出可执行结果；如果存在限制、风险或未验证部分，需要明确说明。

## 执行与修改原则
- 简单优先：只做当前需求所需的最小改动，不额外引入新功能、抽象层、配置项或“顺手优化”。
- 外科手术式修改：只改与任务直接相关的文件和代码行，不重构无关模块，不调整无关格式或注释。
- 保持现有风格：遵循仓库已有包结构、分层方式、命名和写法，不按个人偏好重写。
- 只清理自己造成的问题：可以删除因本次修改而产生的未使用 `import`、变量或方法；不要删除仓库中原本就存在的死代码，除非用户明确要求。
- 页面边距约定：业务页面根节点默认跟随布局主内容区 `el-main` 的 `15px` 边距，不再额外叠加页面级外边距；如需特殊边距，必须先有明确的视觉参照页面或业务原因。
- 表格样式约定：业务表格优先复用仓库现有 `table-main`、`card`、`table-header` 结构，参照 `dictdata` 页面；表格卡片内部默认不再额外堆叠页面标题、说明文案或自定义装饰区，表头左侧用于主操作、次操作和危险批量操作，右侧用于刷新、列设置、搜索等工具按钮；不要在单页里重复自定义表格卡片边框、表头按钮布局和表头配色，除非有明确视觉参照或业务原因。
- 按钮样式约定：业务页面按钮参照 `dictdata` 页面；表头主操作使用 `type="primary"`，表头次操作使用 `type="primary" plain`，危险批量操作使用 `type="danger" plain`，表格行内操作统一使用 `link` 风格并优先保持 `primary` 语义与图标一致性；弹窗底部保持“取消”默认按钮、“主确认”使用 `primary`，同级辅助执行按钮使用 `primary plain`。
- 数据字典常量约定：凡是使用后端数据字典类型 code，必须统一维护在 `frontend/src/constants/dictCodes.ts`；页面、组件、store、hook 和工具函数中不得直接硬编码字典 code 字符串，新增字典类型时先补充常量再引用。
- 先定义验证方式：执行方案里要写清楚“改哪里、怎么判断改对了”；默认通过代码路径、配置一致性、界面影响范围和启动链路检查进行验证。
- 除非用户明确要求，否则不执行 `npm run build`、`npm run build-w`、`electron-builder`、加密打包或其他重型构建命令；通常只做静态检查、必要的代码阅读和轻量验证。

## 项目结构与模块组织
本仓库以前端界面开发为主，使用 Vue 3 构建页面，并通过 Electron 提供桌面壳层与本地运行能力。

- `electron/`：主进程入口、preload 桥接层、运行时配置。
- `frontend/src/`：前端源码，按 `api/`、`components/`、`hooks/`、`layouts/`、`routers/`、`stores/`、`styles/`、`utils/`、`views/` 分层组织。
- `scripts/`：桌面启动、端口检测、日志窗口和运行时辅助脚本。
- `public/`：静态 HTML 与应用图片资源。
- `build/`、`cmd/`、`data/`：打包资源、构建配置、运行时附带数据。
- `doc/`：维护说明与打包文档。

不要直接修改生成内容，如 `frontend/dist/`、`out/`、`logs/`、`public/electron/`。

## 前端页面结构归档
`frontend/src/views/tools/mmsMapping/` 作为复杂工具页结构参照。后续 `eventList`、`diskMonitor`、`addData`、`addLedger`、`waveform` 等业务页按同一职责边界维护：

- `index.vue` 只保留页面布局编排、顶层响应式状态、接口调用流程和事件分发；不要继续堆叠大段展示模板、字段归一化、payload 构造、导出拼装或图表计算。
- `components/` 放当前页面专属展示块、弹窗、表格、工具栏和信息面板。组件通过 props / emits 与入口页通信，不直接越级调用页面接口状态。
- `utils/` 放当前页面专属纯函数或弱状态工具，包括请求参数构造、接口返回归一化、树节点/表单模型转换、枚举选项、时间/数值格式化、图表坐标和导出数据拼装等。
- 页面级类型优先复用 `api/**/interface/`；只服务页面内部组件的 UI 类型可放在当前页面 `components/types.ts` 或 `utils/*.ts`，不要扩散到全局类型。
- 页面级 contract 脚本统一放在对应页面目录下的 `contracts/`，用于验证结构拆分后的关键业务约束；不要继续把 `check-*.mjs` 散放在页面根目录。脚本移动到 `contracts/` 后，需要同步修正 `index.vue`、`components/`、`utils/`、`api/**/interface/` 等扫描路径。
- 复杂页面拆分优先顺序：先抽纯数据转换和常量，再抽独立展示块，最后再考虑组合式函数；不要在一次需求中顺手改变视觉、接口字段、交互流程或持久化时机。
- `waveform` 趋势图规则仍以本文件后续“趋势图”章节为准，图表坐标、线宽、多图对齐等计算逻辑拆分后也必须保留对应 contract 检查。

## 代码风格与命名规范
前端格式化规则定义在 `frontend/.prettierrc`：4 空格缩进、单引号、不写分号、单行 120 字符、LF 换行。Lint 规则基于 Vue 3 与 TypeScript。

文件编码规范：所有新增或修改的源码、脚本、配置、文档统一使用 UTF-8 编码（无 BOM）和 LF 换行，不要保存为 GBK、ANSI 或其他本地编码，避免再次出现乱码。

请遵循现有命名方式：
- 页面或路由目录通常使用 `index.vue`，例如 `views/home/`
- 通用组件使用 PascalCase，例如 `HomeToolCard.vue`
- 组合式函数使用 `useX.ts`，例如 `useTheme.ts`
- 状态模块放在 `frontend/src/stores/modules/`

## 执行原则
涉及页面主流程、状态切换、接口适配、preload 通信、启动链路等关键业务节点时，必须补充简洁、准确的中文注释，并统一使用 UTF-8 编码。注释应说明业务目的、关键条件或异常处理原因，避免空泛描述。

## 测试指南
仓库根目录当前未配置自动化测试，也不存在 `*.spec.*` 或 `*.test.*` 文件。提交 PR 前至少执行 `cd frontend; npm run lint`、`cd frontend; npm run type-check`，并手动验证启动、登录和受影响页面。

## 提交与 Pull Request 规范
当前 `main` 分支还没有可用提交历史，建议使用清晰的祈使句提交信息，优先采用 Conventional Commits，例如 `feat: 增加启动端口重试`、`fix: 处理 mysql 路径缺失`。

PR 应包含：
- 问题与方案的简要说明
- 对应的任务单或 issue 链接（如有）
- UI 变更截图
- 打包、启动或 preload 变更的人工验证步骤

## 安全与配置提示
`public/ssl/`、`build/extraResources/` 与 `electron/config/` 包含敏感运行资源。不要硬编码新的密钥或口令；凡是影响打包或启动的本地 `.env`、端口或运行配置调整，都应同步记录到 `doc/`。

## 趋势图纵坐标显示规则
涉及 waveform 或其他趋势图纵坐标时，统一遵循以下规则：

- 必须显示纵坐标最大值和最小值，图表配置中应显式保留 `showMaxLabel` 与 `showMinLabel`。
- 纵坐标刻度值采用均分方式生成，不再使用会改变刻度间隔的“友好刻度”取整逻辑。
- 纵坐标最大值和最小值基于图形内真实最大值、最小值向外留白；当边界值绝对值 `> 1` 时，外扩边界使用 `1.05` 倍，内收边界使用 `0.95` 倍；当边界值绝对值 `<= 1` 时，继续使用 `1.15` / `0.85`，避免小数趋势图范围过窄或坐标轴退化。正数下边界使用内收倍数向下留白，负数上边界使用内收倍数向上留白，避免正数最小值或负数最大值被扩展到数据内侧。
- 当数据整体绝对值 `> 1` 且真实波动范围较窄时，纵坐标可启用紧凑刻度候选：以 `1.015` / `0.985` 作为最小可接受留白边界，允许增加少量均分段数并使用更小的可读步长，优先减少上下空白；紧凑候选的额外分段惩罚应低于普通候选，避免 `200-240` 这类大空白方案因为分段更少而胜出。例如 220V 附近窄幅波动不应被可读步长放大到 `200-240`，更合理时可收敛到类似 `205-235` 的范围。
- 当数据同时包含正负值且正负幅值接近时，纵坐标最大值和最小值应尽量对称，按较大绝对值向外取整后取 `±同一边界`，例如最大值 `178`、最小值 `-177` 时显示为 `180` 与 `-180`。
- 当最大值、最小值相同或数据接近 `0` 时，需要补充兜底范围，避免坐标轴退化为一条线；小于 `1` 的小数范围按实际小数精度保留，不强制取整。
- 当纵坐标区间较小且均分后出现冗长小数时，应优先使用 `1`、`2`、`2.5`、`5` 等可读步长归一化刻度；必要时可少量增加分段，但必须继续保证刻度均分、最大最小值显示、真实数据完整落在坐标范围内。
- 纵坐标标签不能重叠。小高度趋势图应减少均分段数，优先保证最大值、最小值和必要中间值可读；高度足够时再增加分段。

## 多图趋势图对齐规则
涉及 waveform 或其他上下堆叠的多张趋势图时，统一遵循以下规则：

- 同一组多图必须保证绘图区左边界一致，纵向观察时各图的 y 轴线、x 轴 `0` 起点和曲线起始位置应上下对齐。
- 多图不得让 ECharts 按各自纵坐标标签宽度自动改变绘图区起点；应使用统一的 `grid.left`，并显式配置 `grid.containLabel: false` 或等效方案，避免 `150`、`2`、`-100` 等标签宽度差异导致曲线区域错位。
- 纵坐标标签宽度预留应按同组图中最长标签统一评估，必要时增加统一的左侧 `grid.left`，不能为单张图单独调整左边距。
- 横坐标首尾标签、单位文字或底部留白只能影响底部显示空间，不应改变绘图区左边界；调整 `grid.bottom`、`axisLabel.margin`、`nameGap` 时，需要同步检查多图 x=0 起点是否仍然对齐。
- `waveform` 与 `steady` 多图联动时必须保留鼠标悬停竖线，趋势图 tooltip 应使用 `axisPointer.type: 'line'`，同一联动组图表应通过 ECharts `group` 同步 tooltip / axisPointer；T1/T2 等固定标记线属于 `markLine`，不得与悬停联动竖线混淆。
- 验证多图趋势图时，至少检查单通道拆分图和全部通道列表图两种场景；判断标准是多张图左侧坐标轴竖线形成同一条垂直线，底部横坐标标签不遮挡、不贴线。


## 趋势图线宽显示规则
涉及 waveform 或其他线形趋势图时，线宽应按当前可见点数动态计算，避免初始化大数据量时线条糊成一片，也避免放大后线条过细。

- 当前可见点数按横向缩放范围计算：`ceil(seriesDataLength * ((dataZoom.end - dataZoom.start) / 100))`。
- 初始全量展示时，点数越多线越细；横向放大后可见点数减少，线宽可逐步变粗；横向缩小或重置后线宽恢复到对应细线档位。
- Y 轴缩放、测量模式、峰值显示不改变主线线宽，避免状态切换造成额外视觉跳动。
- 主线最大线宽不得超过 `1.3`。
- 线宽分档统一为：`>= 200000` 使用 `0.35`，`100000 - 199999` 使用 `0.45`，`50000 - 99999` 使用 `0.55`，`20000 - 49999` 使用 `0.65`，`10000 - 19999` 使用 `0.75`，`5000 - 9999` 使用 `0.9`，`2000 - 4999` 使用 `1`，`800 - 1999` 使用 `1.1`，`200 - 799` 使用 `1.2`，`< 200` 使用 `1.3`。