# hy-app-monitor Agent Guide

## 项目目标

- 这是部署在 `deploy` 机器上的轻量监控面板。
- 页面端口固定走 `2026`，不要再改回 `6666` 一类浏览器 unsafe port。
- 服务健康检查直接走各业务机器的 HTTP 接口。
- 主机 `CPU / 内存 / 磁盘 / 进程数` 统一走 `TAT` 远程采集，不额外安装 agent。
- `Nacos` 和 `MongoDB` 指标优先走 deploy 机直连，不需要额外 agent。

## 配置约定

- 项目根目录 `.env` 是运行时唯一配置源。
- `.env` 必须保留在本地和远端项目目录里，但不能提交到 Git。
- `.env.example` 只作为模板，不能写真实密钥。
- `TENCENT_SECRET_ID` / `TENCENT_SECRET_KEY` / `DEPLOY_REGION` 从 `.env` 读取。
- `NACOS_BASE_URL` / `NACOS_NAMESPACE_ID` / `MONGO_URI` 也从 `.env` 读取。
- `config/targets.json` 里的 `instanceId` 不能删，`TAT` 主机采集依赖它。

## 运行约定

- 正式运行优先使用 `systemd`。
- `scripts/install_systemd.sh` 负责安装 unit 并启用开机自启。
- `scripts/start.sh` / `stop.sh` / `restart.sh` / `status.sh` 在检测到 unit 后应直接转调 `systemctl`。
- `scripts/run_foreground.sh` 只给 `systemd` 用，不要把它改成后台模式。

## 部署约定

- 远端路径固定为 `/opt/hy-app-monitor`。
- 部署入口是 `ops/deploy_via_tat.py`。
- 该脚本需要把本地项目根目录 `.env` 同步到远端项目根目录 `.env`。
- 远端 Python 运行时优先使用项目内 `.venv`。
- `requirements-ops.txt` 里的依赖既服务于部署脚本，也服务于运行时 `TAT` 指标采集。
- Python 代码按模块维护，核心目录是 `monitor/`，`server.py` 只保留入口。

## 修改原则

- 不要把 `TAT` 采集替换成 agent 方案，除非用户明确要求。
- 不要把密钥写进版本库。
- 不要删除页面里的主机指标区块。
- Python 文件保持高注释密度，优先写清楚每个步骤在做什么。
- Python 文件顶部的 `import` 区域不写包用途注释。

## 视觉约定

- 前端默认视觉风格固定为“浅色工业控制台”。
- 设计上下文以项目根目录 `.impeccable.md` 为准，后续前端对话和改动先读取它。
- 页面保持冷静、可靠、可操作，不回退到玻璃拟态、霓虹渐变、大 Hero 的 demo 风。
- 页面文案只保留必要标签和动作，不添加无意义描述。
- 首页默认是状态总览，不把配置编辑和发布表单继续堆在同一条长页面里。
- 服务视图优先使用状态矩阵，主机视图优先使用紧凑条带，基础设施视图承接 Nacos / Mongo 详情。
- 首页首屏默认收敛为顶部导航、工具条、紧凑摘要条、服务矩阵，不额外插入大块最近异常横幅。
- 最近异常进入可折叠详情侧栏顶部，不独立占据首页主宽度。
- 服务矩阵按业务分组切成子矩阵，异常排序前置，表头和第一列保持 sticky。
- 首页异常摘要优先使用分段状态带，不回退到零散大卡。
- 服务矩阵的业务分组要做成独立分组卡，分组头直接给服务数、节点数、异常数。
- 首页网关 / 应用 / 支付分组可以用轻微色温差异和导向线区分，但保持低饱和，不做装饰性大色块。
- 首页主机区只展示业务主机；基础设施主机放到基础设施或主机视图承接。
- 主机指标使用单行短文本，正常态降饱和，红橙色保留给异常和告警。
- 首页没有异常主机时不渲染大空态，正常主机直接用紧凑卡栅格展示。
- 主机指标缺失时直接显示采集状态芯片，不渲染空圆环和占位短横。
- 监控筛选条只属于 `总览 / 服务 / 主机`；`发布 / 配置 / 基础设施` 必须使用各自专用工具条和页内导航。
- `发布` 页按“构建参数 -> 更新目标 -> 执行日志 -> 滚动重启”组织，更新与重启目标都优先用紧凑表格，不再回退到大卡片流。
- `配置` 页按 `Nacos / Go Env / 历史版本` tabs 组织，编辑器必须提供 sticky 工具条、metadata strip 和 `源码 / Diff` 切换。
- `基础设施` 页按 `状态总览 / Nacos 服务 / Mongo 指标 / TAT` 二级导航组织，Nacos 服务默认折叠实例，Mongo 次要指标默认折叠。
- 长文本默认缩写并提供复制或展开，不直接在主列表铺完整 digest、路径、长 ID 或长连接串。
- `发布` 页主动作集中到单独 action bar，区块内部避免重复放刷新、预检查、执行类按钮。
- 高权重动作必须少于次动作；只有 `保存 / 执行 / 立即刷新` 这类核心操作保留高权重按钮，其余动作降为 ghost 或轻量控件。
- `执行日志` 和 `服务日志` 默认通过统一弹层查看；主页面只保留摘要和上下文，不铺大块日志窗口。
- `配置` 页左侧使用 explorer 式树状导航，避免大卡片式配置清单；当前项高亮、组折叠、上下项跳转必须可用。
- `配置` 页左侧 explorer 不重复展示已经在 workbench head 里出现的 baseUrl、组数、环境信息。
- `配置` 页不要重复堆叠大标题和当前文件卡片；当前文件信息应并入工具条和 metadata strip，左侧文件树保持高密度。
- `任务型页面` 优先使用紧凑任务头，不再额外堆一张信息价值低的说明卡。
- 主机视图中的百分比指标优先使用小圆环 + 数值标签，不回退到纯文本百分比堆叠。
- 主机行中部优先展示服务摘要，避免重复出现“全部正常”这类低信息密度文案。
- 主机分组标题需要同时给出主机数、服务数、异常主机数，确保高密度下仍然易扫读。
- 总览页全正常时不继续渲染空异常区；正常主机和 `Nacos / Mongo / TAT` 统一收成紧凑摘要。
- `发布` 页更新目标和滚动重启默认使用多列紧凑卡片，避免一项一整行的浪费布局。
- 可选择条目优先使用胶囊式勾选控件，已选态必须明显强于未选态，不能只靠原生 checkbox 提示。
- 首页侧栏卡、基础设施小卡、任务工作区尽量复用同一套顶部导向线和轻表面语言，避免跨页设计语言漂移。
- `数据库` 视图使用统一的工作台入口，`MySQL / MongoDB` 通过同一层引擎切换承接，不再把数据库操作散落在不同页面角落。
- `MongoDB / MySQL` 操作页统一采用 `左侧 explorer + 右侧 workbench` 结构；概览指标保持紧凑，危险操作集中在单独分区，不把删除类动作和普通查询动作混在一起。