intehel-yyt-tool

银医通项目前端开发辅助工具，提供三大核心能力：

1. localtest 检测 — 打包前自动扫描本地测试代码，阻止其误入生产环境
2. Prettier 集成 — 一键格式化和统一代码风格
3. 测试指南生成 — 部署前自动生成测试指南 TXT，明确回归范围

目录

• 为什么需要这个工具
• 安装
• 快速开始
• 命令详解
  • setup — 项目初始化
  • check — 本地测试代码检测
  • check:local — 手动检测
  • format — 代码格式化
  • test-guide — 生成测试指南
• localtest 标记规范
• 配置说明
• 更新工具版本
• 常见问题
• 发布新版本（维护者）

为什么需要这个工具

背景问题

开发人员在本地调试时，经常需要临时注释掉一些参数（如医保证校验、正式环境地址等），从而让项目在本地跑通。如果这些临时修改不小心被打包到正式环境，会导致线上服务运行异常。

解决方案

在代码中为临时修改添加 localtest 标记，打包时工具自动扫描并阻断，杜绝误发。

效果对比

| | 没有工具 | 使用工具 | | -------- | -------------------- | --------------------------------------- | | 本地调试 | 正常开发 | 加一行// localtest 标记即可 | | 打包 | 可能把测试代码带出去 | 检测到标记 → 阻断打包，终端清晰提示位置 | | 处理后 | 无感知 | 删除标记 → 打包通过 |

安装

# 在项目的 web-bst 前端目录下执行（每个项目只需安装一次）
cd 你的项目/web-bst/src/main/web
npm install intehel-yyt-tool -D

-D 表示作为开发依赖安装，不会打包到生产产物中。

快速开始

新项目接入只需两步：

# 第一步：安装
cd 你的项目/web-bst/src/main/web
npm install intehel-yyt-tool -D

# 第二步：初始化（自动改 build 脚本、添加格式化和检测命令）
npx intehel-yyt-tool setup

setup 执行后，你会看到以下变化：

项目/web-bst/src/main/web/
├── package.json          ← build 脚本前面加了 intehel-yyt-tool check
├── .prettierrc           ← 统一的 Prettier 格式化配置
└── .prettierignore       ← 格式化时忽略的文件

提示：初始化后原有的 check-local.js 文件（如果存在）会被自动删除，因为它已不再需要。

命令详解

setup — 项目初始化

npx intehel-yyt-tool setup

作用： 一键完成以下配置，无需手动操作：

| 操作 | 说明 | | ------------------------ | ------------------------------------------------------- | | 修改build 脚本 | 在 webpack 打包前注入检测，保证每次打包都自动扫描 | | 添加check:local 命令 | 提供手动检测入口 | | 添加format 命令 | 提供 Prettier 格式化入口 | | 生成.prettierrc | Prettier 格式化配置（如果已存在则保留不动） | | 生成.prettierignore | 指定格式化时跳过的文件（node_modules、dist、vendor 等） | | 删除旧的check-local.js | 新版功能已集成在 npm 包内，不再需要独立文件 |

执行条件： 必须在包含 package.json 的前端目录下执行（即 web-bst/src/main/web/）。

多次执行安全： 重复执行 setup 不会重复添加配置，已存在的配置会被原样保留。

check — 本地测试代码检测

这是工具最重要的命令，已自动嵌入 npm run build，正常情况下你不需要手动执行它。

# 手动执行（一般不需要）
npx intehel-yyt-tool check

流程：

intehel-yyt-tool check
  ↓
扫描 src/ 目录下所有 .js / .vue / .scss / .css / .html 文件
  ↓
逐行查找 localtest 标记（大小写不敏感）
  ↓
  ┌─ 未找到 → 退出码 0 → 继续打包 ✅
  └─ 找到   → 退出码 1 → 打包终止 ❌

检测到标记时的终端输出示例：

  ❌ 检测到 1 处本地测试代码 localtest：

  📄 pages\out_payment\out_payment_list.js
     第 127 行: // localtest

  ══════════════════════════════════
  请处理后删除 localtest 再打包
  ══════════════════════════════════

退出码为 1，npm 收到此退出码后会终止后续 webpack 的执行，打包失败。

check:local — 手动检测

npm run check:local

和 intehel-yyt-tool check 完全一样，只是提供了一条更短的 npm script 入口。适用于：

• 想在打包前单独跑一遍检查
• 不确定自己有没有残留 localtest 标记
• CI/CD 流水线中单独执行检查步骤

format — 代码格式化

npm run format

等价于执行 npx prettier . --write，会格式化当前目录下所有 Prettier 支持的文件。

原理： 通过 npx 调用 Prettier，利用你本地安装的版本（包括 VS Code 插件装的），不需要项目中额外安装 prettier 依赖。

跳过规则： .prettierignore 中列出的目录和文件不会被格式化：

• node_modules — 依赖包目录（Prettier 也会自动跳过）
• dist — 打包输出目录
• *.min.js — 已压缩的 JS 文件
• package-lock.json — npm 锁文件
• vendor — 第三方库目录

格式化配置（.prettierrc）：

{
  "bracketSpacing": true, // 对象花括号前后加空格 { foo: bar }
  "endOfLine": "lf", // 统一使用 LF 换行符
  "printWidth": 120, // 每行最大 120 字符
  "singleQuote": true, // 统一使用单引号
  "semi": true, // 语句末尾加分号
  "tabWidth": 4, // 缩进 4 个空格
  "trailingComma": "es5" // ES5 允许的地方加尾逗号
}

test-guide — 生成测试指南

npm run test-guide

作用： 对比上次部署到现在的所有 Git 改动，自动生成一份 TXT 格式的测试指南。

什么时候用： 打包完成、准备部署时执行。生成的 TEST_GUIDE.txt 可以直接发给测试人员。

原理：

npm run test-guide
  ↓
读取 .last-deploy（上次部署的 commit hash）
  ↓
git log + git diff --stat  对比两次部署间的所有改动
  ↓
自动匹配文件路径 → 识别影响模块（out_payment→门诊缴费, insurance→医保...）
  ↓
按模块优先级（high/medium/low）+ 提交类型（feat/fix）生成测试建议
  ↓
生成 TEST_GUIDE.txt → 更新 .last-deploy

生成文件的存放位置：

• TEST_GUIDE.txt — 当前执行目录（发给测试人员）
• .last-deploy — Git 根目录（工具自动维护，记录本次部署 commit）

生成内容包含：

| 板块 | 内容 | | ------------ | ------------------------ | | 变更概览 | 提交次数、涉及文件数 | | 提交列表 | 每笔 commit 的作者和说明 | | 文件变更清单 | git diff --stat 输出 | | 影响模块分析 | 高/中/低优先级标注 | | 测试建议 | 按模块和提交类型给出方向 | | 重点回归区域 | 高优先级模块列表 | | 签字确认区 | 测试人/日期/通过与否 |

模块匹配规则： 工具根据文件路径自动识别业务模块，内置 20+ 模块映射：

| 路径关键词 | 业务模块 | 优先级 | | 路径关键词 | 业务模块 | 优先级 | | ------------------- | -------- | ------ | --- | ------------ | -------- | ------ | | out_payment | 门诊缴费 | high | | in_payment | 住院缴费 | high | | insurance | 医保 | high | | registration | 挂号 | high | | prescription/recipe | 处方管理 | high | | login | 登录 | high | | wechat | 微信端 | high | | api | 接口层 | high | | department | 科室管理 | medium | | patient | 患者管理 | medium | | pharmacy | 药房 | medium | | report | 报告查询 | medium | | admin | 后台管理 | medium | | config | 配置 | medium | | common/components | 公共模块 | medium | | router | 路由 | medium | | store | 状态管理 | medium | | doctor | 医生 | medium | | schedule | 排班 | low | | queue | 排队叫号 | low | | utils | 工具函数 | low | | | | |

第一次使用： 由于 .last-deploy 不存在，工具默认对比最近一次提交（HEAD~1），并提示这是首次使用。之后每次运行都会记录最新部署 commit。

localtest 标记规范

标记方式

在需要临时注释的代码行上方或同行添加 localtest 字样即可，支持所有常见注释语法：

// JavaScript 单行注释
// localtest 本地测试时启用此参数
// params.mchId = 'test_mch_001';

// CSS / SCSS 注释
// localtest 本地调试样式
// .debug-panel { display: block; }

/* JavaScript 块注释 */
/* localtest 跳过医保校验 */
// validateInsurance();

<!-- HTML 注释 -->
<!-- localtest 本地测试用跳转链接 -->
<!-- <a href="正式地址">去支付</a> -->

# Shell / 配置文件注释
# localtest 本地数据库地址
# DB_HOST=192.168.1.100

规则

| 规则 | 说明 | | ------------ | ---------------------------------------------------------------- | | 大小写 | 不敏感。localtest、LOCALTEST、LocalTest 均可识别 | | 位置 | 在注释行内任意位置均可 | | 扫描范围 | 仅限src/ 目录下的 .js、.vue、.scss、.css、.html 文件 | | 排除目录 | node_modules、dist 默认跳过 |

正确示例

// ✅ 在注释行中标记原因
// localtest 本地开发关闭医保校验
// params.insuranceCheck = true;

// ✅ 标记和代码在同一行
// localtest ← 标记
const debug = true; // 这行不会被检测到，只有注释行才检测

常见使用场景

| 场景 | 代码示例 | | ------------ | ------------------------------- | | 跳过参数校验 | // localtest 本地跳过参数校验 | | 使用测试地址 | // localtest 本地 ws 地址 | | 关闭外部依赖 | // localtest 本地关闭医保接口 | | 显示调试信息 | // localtest 显示调试面板 |

配置说明

package.json 中的脚本

执行 setup 后，package.json 中会新增/修改以下脚本：

{
  "scripts": {
    "build": "intehel-yyt-tool check && webpack ...",
    "check:local": "intehel-yyt-tool check",
    "format": "npx prettier . --write",
    "test-guide": "intehel-yyt-tool test-guide"
  }
}

| 脚本 | 何时执行 | 作用 | | ------------- | -------------------------- | ----------------------------------------- | | build | 每次执行npm run build | 先检测 localtest，通过后才走 webpack 打包 | | check:local | 手动npm run check:local | 仅执行检测，不触发打包 | | format | 手动npm run format | 按 .prettierrc 规则格式化全部代码 | | test-guide | 部署前npm run test-guide | 对比 Git 改动生成测试指南 TXT |

手动修改 Prettier 配置

如果需要调整格式化规则，直接编辑项目中的 .prettierrc 文件即可。Prettier 支持的配置项参考 官方文档。

再次执行 npx intehel-yyt-tool setup 不会覆盖你手动修改过的配置文件。

更新工具版本

当工具发布新版本后，各项目升级只需一条命令：

cd 你的项目/web-bst/src/main/web
npm update intehel-yyt-tool

# 如果 npm update 没生效，可以指定版本号
npm install intehel-yyt-tool@latest -D

不需要重新执行 setup，因为项目内的配置文件（.prettierrc、.prettierignore、package.json 脚本）已经配好了。升级只更新 node_modules 中的执行逻辑。

常见问题

Q: 我在子目录下执行 npm run format，会格式化哪些文件？

A: 格式化 执行命令所在的目录 下的所有文件。所以务必在 web-bst/src/main/web/ 目录下执行。如果在子目录（如 src/pages/）执行，只会格式化该子目录。

Q: localtest 标记必须用 // 开头吗？

A: 不需要。在任何注释中（//、/* */、<!-- -->、#）包含 localtest 字样即可。

Q: 检测到 localtest 后，打包会被彻底阻断吗？

A: 是的，退出码为 1，&& 运算符会阻止后续 webpack 运行。删除标记或将其改为正式代码后重新打包即可。

Q: .prettierrc 在哪里找？

A: 在 web-bst/src/main/web/ 目录下。Prettier 从执行命令的目录开始向上查找，找到离当前目录最近的配置文件就用它。

Q: format 需要安装 prettier 依赖吗？

A: 不需要。npx prettier 会自动找到你本机已有的 Prettier（比如 VS Code 插件自带的版本）。

Q: 同一个项目多次执行 setup 会怎样？

A: 安全。已存在的内容不会被覆盖或重复添加：

• .prettierrc 已存在 → 保留不动
• .prettierignore 已存在 → 保留不动
• build 脚本已有检测 → 跳过不重复添加
• 旧的 check-local.js → 自动识别并删除

Q: 可以在 CI/CD 中使用吗？

A: 可以。构建命令 npm run build 本身就包含检测步骤，不需要额外配置。也可以在流水线中单独运行 npm run check:local。

发布新版本（维护者）

当工具代码发生变更后，按以下流程发布：

# 1. 进入工具目录
cd E:\intehel\intehel-yyt-tool

# 2. 递增版本号（patch: 修复, minor: 新功能, major: 破坏性变更）
npm version patch

# 3. 发布到 npm
npm publish --access public

首次发布前需要做的：

1. 在 npmjs.com 注册账号
2. 终端执行 npm login 登录
3. 如果开启了 2FA，发布时附加 --otp=验证码 参数

添加协作者：

npm owner add 同事的npm用户名 intehel-yyt-tool

添加后同事也能用自己账号发布新版本。

License

ISC