qthwng01/Tool_PPT 使用教程：用 Excel 和图片文件夹生成代理报告 PPT

qthwng01/Tool_PPT 的核心是用 Excel 和图片文件夹生成代理报告 PPT。 它不是通用演示文稿生成器，而是一个 React/Vite 小工具，用 xlsx 读取 Excel，用 pptxgenjs 把代理图片、地区、省份和备注信息合成 region_city.pptx。

它最容易卡住的地方不是依赖安装，而是数据是否对齐：图片文件夹名要能匹配 Excel 第一张表里的 Tên Đại Lý，同时表里还要有 Quận - Huyện 和 GHI CHÚ 字段。主生成页没有温柔的缺失提示，名字对不上时很容易直接报错或只弹出越南语错误。

实际入口在两个路由

源码里确实有 src/pages/Login.jsx、AuthProvider.jsx 和 PrivateRoutes.jsx，但 App.jsx 里这些私有路由被注释掉了。实际可访问的只有两个入口：根路径 / 打开 Tools，/test 打开 CheckExcel。

这点很关键。排查时如果看到登录组件，不要以为必须先做账号系统；当前版本的工作流是直接进工具页，填 Tên vùng、Tên tỉnh，上传图片文件夹和 Excel，然后点 Tạo PowerPoint。

npm install
npm run dev

开发服务跑起来后，先打开根路径看生成页，再打开 /test 做名字检查。README 还停留在 Vite 模板说明，所以入口信息要以源码路由为准。

文件夹结构和代理名匹配

主工具用 webkitdirectory 读取文件夹，并从 file.webkitRelativePath.split("/")[1] 取代理文件夹名。也就是说，推荐结构是选一个总文件夹，里面每个子文件夹代表一个代理，子文件夹里放该代理的图片。

images-root/
  dai-ly-a/
    01.jpg
    02.jpg
  dai-ly-b/
    01.jpg

如果图片直接堆在根目录，代码会把路径第二段当作名字，匹配很容易乱。文件夹名里出现 ( 时，代码会把括号前的部分拿去和 Excel 名称比较；城市、县区名称还会经过 TP、H. 的替换处理。

Excel 读取的是第一张 sheet，并转成 JSON。主生成页查找方式接近精确匹配：x["Tên Đại Lý"].toLowerCase() === checkName。字段名多一个空格、大小写以外的拼写差异、代理名多了括号内容，都可能让生成流程走到错误分支。

/test 用于检查代理名

/test 页面的存在很实用。它同样上传文件夹和 Excel，但目标不是生成 PPT，而是逐个检查文件夹名能否在 Tên Đại Lý 里找到。找不到时会把 Không tìm thấy kết quả phù hợp với tên... 这类消息列出来。

主生成页里的 filterExcel 在没有匹配数据时，后续访问 data["Tên Đại Lý"] 容易出错；测试页则用了更保守的判断，会把缺失名称留在页面上。正式生成前先跑一次 /test，能省掉很多“按钮点了但不知道哪里错”的时间。

生成成功后的下载文件名

主生成页要求 region 和 city 都不为空，也要求已经选择图片文件夹。通过检查后，工具会新建 PptxGenJS 文件，每个代理文件夹生成一页 slide，页标题格式大致是地区、省份、县区和代理名。

图片排版按数量变化：少于 3 张是一行，3 张是一行三列，4 张是两行两列，5 张及以上走两行三列。图片会读取原始宽高并按比例放入指定区域，所以它更适合整理一组现场照片或门店图片，而不是做复杂图表型 PPT。

最终成功信号是浏览器下载 ${region}_${city}.pptx，随后页面清空已选文件夹和 Excel，并触发 confetti。若出现 Có lỗi gòi. Kiểm tra file lại đi cưng.，优先回到 /test 查代理名和 Excel 字段，不要先怀疑 pptxgenjs。

适合拿它做什么

qthwng01/Tool_PPT 适合已有固定字段 Excel、固定图片文件夹结构、固定代理报告格式的内部小团队。它把“每个代理一页、自动放图片、标题带地区省份备注”这件事做成按钮，比手工复制图片到 PowerPoint 更快。

它不适合开放给陌生数据源直接使用。README 没写业务字段，登录页也没有接入主流程，错误提示主要是越南语口语，测试覆盖只有一个示例用例。把它部署给别人前，最好先补一份字段样例 Excel，再把缺失名称、空表、空文件夹和图片读取失败的提示做得更明确。