# Formulation_Generator

**Repository Path**: Star-air/formulation_generator

## Basic Information

- **Project Name**: Formulation_Generator
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-11
- **Last Updated**: 2026-05-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 配方生成器 / Formula Generator

这是一个零依赖的本地网页工具，用来：

- 编辑配方模板
- 导入 `CSV / BIN`
- 在浏览器里查看和修改配方
- 导出 `BIN + CSV`

当前工程主要用于洗衣机配方场景，已经包含两套实际模板：

- [templates/WaterWasher_100kg_121C_V2.json](./templates/WaterWasher_100kg_121C_V2.json)
- [templates/WetWasher_25kg_121C.json](./templates/WetWasher_25kg_121C.json)

## 工程目标

这个工具的目标，是把设备里的固定结构配方变成一个可视化、可校验、可导入导出的本地工作台。

核心思路：

- `模板 JSON` 描述配方结构、字段类型、步骤类型、偏移与 BIN 规则
- `CSV` 作为网页内部的数据载体
- `BIN` 作为设备侧文件格式导入和导出

网页本身不硬编码某一种配方结构，而是通过模板去解释配方。

## 当前目录

- [index.html](./index.html): 页面入口
- [app.js](./app.js): 主逻辑，包含模板编辑、CSV/BIN 解析和导出
- [styles.css](./styles.css): 页面样式
- [templates/](./templates): 模板目录
- [reference/](./reference): 参考头文件和结构资料
- [bin/](./bin): 示例或已整理 BIN 文件

当前重点模板和 BIN：

- [templates/WetWasher_25kg_121C.json](./templates/WetWasher_25kg_121C.json)
- [bin/WetWasher_25kg_121C/FLASH.bin](./bin/WetWasher_25kg_121C/FLASH.bin)
- [templates/WaterWasher_100kg_121C_V2.json](./templates/WaterWasher_100kg_121C_V2.json)
- [bin/WaterWasher_100kg_121C_V2/FLASH.BIN](./bin/WaterWasher_100kg_121C_V2/FLASH.BIN)

## 当前能力

### 1. 模板编辑器

- 编辑模板基础信息
- 编辑配方头字段、尾字段、步骤公共字段
- 新增、删除、排序步骤类型和参数字段
- 自动计算字段 `offsetWord`
- 实时校验模板结构
- 实时预览模板布局
- 导入 / 导出模板 JSON

### 2. 配方编辑器

- 按模板生成固定数量的配方
- 编辑配方头字段
- 编辑每个步骤槽位
- 根据步骤类型显示对应参数字段
- 汇总有效步骤数与步骤时间

### 3. CSV 会话

- 导入既有 `CSV`
- 新建空白 `CSV`
- 自动生成 CSV 载体
- 读取和写出模板元信息：
  - `templateId`
  - `templateVersion`
  - `endianness`
  - `formulaStartOffsetWords`

### 4. BIN 会话

- 导入既有 `BIN`
- 手动指定模板解析
- 按模板解析配方区
- 导出时保留非配方区原始内容
- 非空步骤只覆盖模板定义字段
- 空步骤会清零整个步骤槽位

### 5. BIN 对比工具

- 新增独立的 `BIN 对比` 子界面
- 可直接选择两个 `BIN`
- 可单独选择用于解析的模板
- 按模板把差异标注到：
  - 配方头
  - 步骤
  - 配方尾
  - 字段名 / 字段类型 / 字节偏移
- 可复制或导出带注释的差异报告

## 当前会话流程

页面启动后，必须先完成一次配方会话初始化，主界面才会开放。

流程如下：

1. 打开网页。
2. 在启动弹窗中选择：
   - 导入既有 `CSV`
   - 导入既有 `BIN`
   - 新建 `CSV`
3. 如果导入 `CSV`，程序会根据文件头中的模板元信息尝试匹配本地模板。
4. 如果导入 `BIN`，或 `CSV` 找不到模板，则进入模板确认弹窗。
5. 在模板确认弹窗中，从本地模板列表里选择对应模板。
6. 进入配方编辑器后，即可查看、修改并导出。

## 模板目录加载

网页不会自动扫描本地 `templates/` 目录。

如果要在浏览器里使用本地模板目录，请在“确认配方模板”弹窗中点击“选择/刷新模板目录”，然后手动选择 `templates/` 文件夹。

页面会读取其中的模板 JSON，并刷新模板列表。

## 已实现的 WetWasher 规则

围绕 `WetWasher_25kg_121C`，当前工程已经完成以下整理：

- 模板名称、显示名和 BIN 样本已整理
- 配方整体结构已经对齐：
  - 配方头 `16 word`
  - 单步 `30 word`
  - 每配方 `12` 步
  - 单配方总长 `376 word = 752 byte`
- `BIN` 配方起始偏移已按十六进制显示为 `0x3000`
- `soap_select` 已建模为 `flags`
- `water_select` 已建模为 `enum`
- `wash_water_line` 已建模为 `enum`
- 多个步骤布尔项已建模为 `bool`

## BIN 导出规则

当前 BIN 导出行为采用下面这套规则：

- 非配方区不修改
- 非空步骤：
  - 只覆盖模板定义过的字段
  - 未定义空间保留原始值
- 空步骤：
  - 视为真正空槽
  - 整个步骤槽位清零

这意味着：

- 如果原始 BIN 里的空步骤还残留名字或旧参数，导出后这些残留会被清掉
- 如果一个步骤是有效步骤，则未建模的 union 空间会尽量保留

## 如何使用

直接用浏览器打开 [index.html](./index.html) 即可。

如果你更习惯本地服务，也可以用任意静态文件服务启动当前目录；这个工程没有后端依赖。

## BIN 对比使用方式

1. 先正常进入主界面。
2. 点击顶部的 `BIN 对比`。
3. 选择一套本地模板。
4. 分别载入左侧和右侧 `BIN`。
5. 点击 `开始对比`。
6. 在右侧查看按配方字段注释过的差异，必要时导出 `diff.report.txt`。

## 导出目录行为

如果浏览器支持 `showDirectoryPicker`，导出时可以选择一个目录，程序会尝试写入：

- `csv/`
- `bin/`

如果浏览器不支持该能力，则会退化为普通文件下载。

## 数据设计

### 模板

模板负责描述：

- 配方头字段
- 配方尾字段
- 步骤公共字段
- 步骤类型和参数字段
- 每个字段的 `offsetWord / wordLength`
- 字段类型：`u16 / enum / bool / flags / reserved / array`
- BIN 起始偏移和字节序

### CSV

CSV 是网页工作流中的主数据载体。

当前格式由两部分组成：

- 以 `#` 开头的元信息行
- 扁平化数据列

### BIN

BIN 用于和设备文件格式对接。

当前实现支持：

- 从模板定义偏移读取配方区
- 按模板解释配方头和步骤数据
- 在导出时尽量保留原始 BIN 中未管理区域

## 文档

除了本 README，另有一份偏操作视角的中文使用说明：

- [使用说明.md](./使用说明.md)

## 当前已知约束

- 模板仍然依赖人工维护，没有自动从 C 结构体生成
- 某些数值字段虽然底层是 `u16`，但业务上实际是档位枚举，需要继续逐项核实
- `formula_name / step_name` 当前仍以 `reserved` 方式承载，没有拆成真正可编辑的字符串字段

## 参考文件

- [reference/formula_page.h](./reference/formula_page.h)
- [reference/mw_formula_manage.h](./reference/mw_formula_manage.h)
- [templates/WetWasher_25kg_121C.json](./templates/WetWasher_25kg_121C.json)
- [templates/WaterWasher_100kg_121C_V2.json](./templates/WaterWasher_100kg_121C_V2.json)