Просмотр исходного кода

docs: add extended visual ratio settings implementation plan

- 9 detailed tasks covering i18n, data, UI, and testing
- Each task broken into 2-5 minute steps with exact code
- Complete validation and troubleshooting sections
- Estimated 2.5 hours total implementation time

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
master
fengsilin 1 неделю назад
Родитель
Сommit
a9fc624ff2
1 измененных файлов: 932 добавлений и 0 удалений
  1. +932
    -0
      docs/superpowers/plans/2026-06-04-extended-visual-ratio-settings.md

+ 932
- 0
docs/superpowers/plans/2026-06-04-extended-visual-ratio-settings.md Просмотреть файл

@@ -0,0 +1,932 @@
# 扩展可视化倍率设置实施计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**目标:** 在 ModelSettingsVisualEditor 组件中添加 5 个高级倍率字段支持(缓存、图片、音频倍率)

**架构:** 扩展现有 React 组件的状态管理和表单逻辑,增加高级倍率字段的数据初始化、编辑、保存和验证功能

**技术栈:** React, Semi UI, i18n, JavaScript

---

## 文件结构

### 修改文件
- `web/src/pages/Setting/Ratio/ModelSettingsVisualEditor.jsx` - 主要功能实现(500+ 行)
- `web/src/i18n/locales/zh-CN.json` - 中文翻译
- `web/src/i18n/locales/en.json` - 英文翻译

### 参考文件(只读,用于理解实现模式)
- `feat/channel-pricing-extended:web/src/pages/Setting/Ratio/ChannelPricingView.jsx` - 渠道价格设置的参考实现

### 数据流向
```
props.options (API 数据)
useEffect 解析 JSON → models 状态(包含 5 个新字段)
用户编辑表单 → currentModel 状态
addOrUpdateModel → 更新 models 状态
SubmitData → 序列化 JSON → API.put('/api/option/')
```

---

## Task 1: 添加国际化文本

**文件:**
- Modify: `web/src/i18n/locales/zh-CN.json`
- Modify: `web/src/i18n/locales/en.json`

### 步骤 1.1: 添加中文翻译

在 `web/src/i18n/locales/zh-CN.json` 中添加以下键值对。找到文件末尾,在最后一个键值对后添加逗号,然后添加:

```json
"高级比例(留空使用默认值)": "高级比例(留空使用默认值)",
"缓存读取倍率": "缓存读取倍率",
"缓存创建倍率(5分钟)": "缓存创建倍率(5分钟)",
"图片倍率": "图片倍率",
"音频输入倍率": "音频输入倍率",
"音频输出倍率": "音频输出倍率",
"默认值:1.0": "默认值:1.0",
"默认值:1.25": "默认值:1.25"
```

### 步骤 1.2: 添加英文翻译

在 `web/src/i18n/locales/en.json` 中添加对应的英文翻译:

```json
"高级比例(留空使用默认值)": "Advanced Ratios (Leave empty for defaults)",
"缓存读取倍率": "Cache Read Ratio",
"缓存创建倍率(5分钟)": "Cache Creation Ratio (5min)",
"图片倍率": "Image Ratio",
"音频输入倍率": "Audio Input Ratio",
"音频输出倍率": "Audio Output Ratio",
"默认值:1.0": "Default: 1.0",
"默认值:1.25": "Default: 1.25"
```

### 步骤 1.3: 验证 JSON 格式

确保添加的 JSON 格式正确,没有语法错误:

```bash
cd web/src/i18n/locales
node -e "console.log('zh-CN:', JSON.parse(require('fs').readFileSync('zh-CN.json', 'utf8'))); console.log('en:', JSON.parse(require('fs').readFileSync('en.json', 'utf8')))"
```

预期输出:无错误,输出两个对象的内容

### 步骤 1.4: 提交国际化更改

```bash
git add web/src/i18n/locales/zh-CN.json web/src/i18n/locales/en.json
git commit -m "feat(i18n): add advanced ratio translations

- Add Chinese translations for 5 advanced ratio fields
- Add English translations for 5 advanced ratio fields

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>"
```

---

## Task 2: 扩展数据初始化逻辑

**文件:**
- Modify: `web/src/pages/Setting/Ratio/ModelSettingsVisualEditor.jsx:59-91`

### 步骤 2.1: 在 useEffect 中解析高级倍率 JSON

找到 `useEffect` 开始(约第 59 行),在 `try` 块中,在现有的 `const completionRatio = JSON.parse(props.options.CompletionRatio || '{}');` 之后添加:

```javascript
// 新增:解析高级倍率字段
const cacheRatio = JSON.parse(props.options.CacheRatio || '{}');
const createCacheRatio = JSON.parse(props.options.CreateCacheRatio || '{}');
const imageRatio = JSON.parse(props.options.ImageRatio || '{}');
const audioRatio = JSON.parse(props.options.AudioRatio || '{}');
const audioCompletionRatio = JSON.parse(props.options.AudioCompletionRatio || '{}');
```

### 步骤 2.2: 扩展模型名称合并逻辑

在同一个 `useEffect` 中,找到 `const modelNames = new Set([...])`(约第 66 行),将数组扩展为:

```javascript
const modelNames = new Set([
...Object.keys(modelPrice),
...Object.keys(modelRatio),
...Object.keys(completionRatio),
...Object.keys(cacheRatio),
...Object.keys(createCacheRatio),
...Object.keys(imageRatio),
...Object.keys(audioRatio),
...Object.keys(audioCompletionRatio),
]);
```

### 步骤 2.3: 扩展模型数据对象

在同一个 `useEffect` 中,找到 `const modelData = Array.from(modelNames).map((name) => {`(约第 72 行),在返回对象中添加新字段。找到现有的:

```javascript
const comp = completionRatio[name] === undefined ? '' : completionRatio[name];
```

在这一行后添加:

```javascript
const cacheR = cacheRatio[name] === undefined ? '' : cacheRatio[name];
const cacheCreationR = createCacheRatio[name] === undefined ? '' : createCacheRatio[name];
const imageR = imageRatio[name] === undefined ? '' : imageRatio[name];
const audioR = audioRatio[name] === undefined ? '' : audioRatio[name];
const audioCompR = audioCompletionRatio[name] === undefined ? '' : audioCompletionRatio[name];
```

### 步骤 2.4: 更新返回对象结构

继续在同一个 `map` 函数中,找到返回对象(约第 78 行),更新为:

```javascript
return {
name,
price,
ratio,
completionRatio: comp,
cacheRatio: cacheR,
cacheCreationRatio: cacheCreationR,
imageRatio: imageR,
audioRatio: audioR,
audioCompletionRatio: audioCompR,
hasConflict: price !== '' && (ratio !== '' || comp !== ''),
};
```

### 步骤 2.5: 启动开发服务器验证数据加载

```bash
cd web
bun run dev
```

访问:http://localhost:5173/setting/ratio → 切换到"可视化倍率设置"标签

打开浏览器控制台,输入:

```javascript
// 检查 models 状态是否包含新字段
const tableRows = document.querySelectorAll('.semi-table-row');
console.log('Table rows count:', tableRows.length);
```

预期:表格正常显示,无 JavaScript 错误

### 步骤 2.6: 提交数据初始化更改

```bash
git add web/src/pages/Setting/Ratio/ModelSettingsVisualEditor.jsx
git commit -m "feat(ratio): parse advanced ratio fields in data initialization

- Parse 5 new JSON fields from props.options
- Extend modelNames Set to include keys from all ratio fields
- Add 5 new fields to model data objects

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>"
```

---

## Task 3: 添加高级比例表单区域

**文件:**
- Modify: `web/src/pages/Setting/Ratio/ModelSettingsVisualEditor.jsx:616-737`

### 步骤 3.1: 找到插入位置

在文件中找到 `{pricingSubMode === 'token-price' && (` 块的闭合位置(约第 736 行),应该在 `)}$ 之前,`{pricingMode === 'per-request' && (` 之前。

### 步骤 3.2: 插入高级比例表单区域

在 `{pricingSubMode === 'token-price' && (` 块的闭合 `)}` 之后,`{pricingMode === 'per-request' && (` 之前,添加:

```jsx
<Form.Section text={t('高级比例(留空使用默认值)')}>
<Form.InputNumber
field='cacheRatio'
label={t('缓存读取倍率')}
min={0}
step={0.01}
placeholder={t('默认值:1.0')}
/>
<Form.InputNumber
field='cacheCreationRatio'
label={t('缓存创建倍率(5分钟)')}
min={0}
step={0.01}
placeholder={t('默认值:1.25')}
/>
<Form.InputNumber
field='imageRatio'
label={t('图片倍率')}
min={0}
step={0.01}
placeholder={t('默认值:1.0')}
/>
<Form.InputNumber
field='audioRatio'
label={t('音频输入倍率')}
min={0}
step={0.01}
placeholder={t('默认值:1.0')}
/>
<Form.InputNumber
field='audioCompletionRatio'
label={t('音频输出倍率')}
min={0}
step={0.01}
placeholder={t('默认值:1.0')}
/>
</Form.Section>
```

**注意缩进**:保持与周围代码一致的缩进(约 14-16 个空格)

### 步骤 3.2: 验证表单渲染

确保开发服务器仍在运行(`bun run dev`),访问:http://localhost:5173/setting/ratio

1. 点击任意模型的"编辑"按钮
2. 确认定价模式为"按量计费"
3. 向下滚动,应该能看到"高级比例(留空使用默认值)"区域
4. 确认 5 个输入框都有正确的标签和 placeholder

预期:
- 新区域显示在"价格设置方式"和"固定价格"之间
- 所有 5 个字段可见且可交互
- placeholder 显示正确的默认值

### 步骤 3.3: 测试输入验证

在高级比例区域的任意输入框中:
1. 输入负数(如 `-1`),预期:无法输入或显示验证错误
2. 输入文字(如 `abc`),预期:无法输入(InputNumber 组件自动限制)
3. 输入小数(如 `1.23`),预期:正常接受
4. 输入多位小数(如 `1.23456`),预期:step=0.01 限制

### 步骤 3.4: 提交表单 UI 更改

```bash
git add web/src/pages/Setting/Ratio/ModelSettingsVisualEditor.jsx
git commit -m "feat(ui): add advanced ratios form section

- Add Form.Section with 5 advanced ratio input fields
- Configure min={0}, step={0.01} for all fields
- Add placeholders showing default values
- Only show when pricingMode === 'per-token'

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>"
```

---

## Task 4: 更新编辑模型逻辑

**文件:**
- Modify: `web/src/pages/Setting/Ratio/ModelSettingsVisualEditor.jsx:395-454`

### 步骤 4.1: 在 editModel 中设置表单值

找到 `editModel` 函数中的 `setTimeout` 块(约第 435 行),在 `formRef.current.setValues({` 调用中添加新字段。

找到现有的:
```javascript
completionTokenPrice: modelCopy.completionTokenPrice
```

在这一行后添加(注意在 `})` 之前添加逗号):
```javascript
,
// 新增:高级倍率字段
cacheRatio: modelCopy.cacheRatio,
cacheCreationRatio: modelCopy.cacheCreationRatio,
imageRatio: modelCopy.imageRatio,
audioRatio: modelCopy.audioRatio,
audioCompletionRatio: modelCopy.audioCompletionRatio
```

### 步骤 4.2: 验证编辑回显

1. 点击已有数据的模型(如 gpt-4)的"编辑"按钮
2. 在浏览器控制台中执行:

```javascript
// 检查表单值是否正确设置
const formApi = document.querySelector('[data-form-id]')?.__semi_form__;
if (formApi) {
console.log('Form values:', formApi.getValues());
}
```

或者更简单:直接观察高级比例区域的输入框,如果有数据应该显示对应的值

预期:
- 如果模型有高级倍率数据,输入框应显示对应值
- 如果没有数据,输入框应为空

### 步骤 4.3: 提交编辑逻辑更改

```bash
git add web/src/pages/Setting/Ratio/ModelSettingsVisualEditor.jsx
git commit -m "feat(edit): populate advanced ratios in edit modal

- Add 5 advanced ratio fields to formRef.current.setValues
- Ensure existing ratio data displays correctly in edit modal

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>"
```

---

## Task 5: 更新添加/更新模型逻辑

**文件:**
- Modify: `web/src/pages/Setting/Ratio/ModelSettingsVisualEditor.jsx:334-382`

### 步骤 5.1: 在 addOrUpdateModel 中处理高级倍率字段

找到 `addOrUpdateModel` 函数(约第 334 行),在 `const updatedModel = {` 对象中添加新字段。

找到现有的:
```javascript
completionRatio: values.completionRatio || '',
```

在这一行后添加:
```javascript
// 新增:高级倍率字段
cacheRatio: values.cacheRatio || '',
cacheCreationRatio: values.cacheCreationRatio || '',
imageRatio: values.imageRatio || '',
audioRatio: values.audioRatio || '',
audioCompletionRatio: values.audioCompletionRatio || '',
```

### 步骤 5.2: 测试添加新模型

1. 点击"添加模型"按钮
2. 输入模型名称:`test-model-advanced`
3. 在高级比例区域输入测试值:
- 缓存读取倍率:`0.5`
- 缓存创建倍率:`1.5`
- 图片倍率:`2.0`
- 音频输入倍率:`1.2`
- 音频输出倍率:`0.8`
4. 点击"确定"

预期:
- 模型成功添加到表格
- 浏览器控制台无错误

### 步骤 5.3: 验证数据保存到状态

在浏览器控制台中检查:

```javascript
// 检查是否能在表格中看到新模型
const rows = document.querySelectorAll('.semi-table-row');
console.log('Total rows:', rows.length);
// 应该比之前多 1 行
```

### 步骤 5.4: 提交添加/更新逻辑更改

```bash
git add web/src/pages/Setting/Ratio/ModelSettingsVisualEditor.jsx
git commit -m "feat(add): handle advanced ratios in addOrUpdateModel

- Add 5 advanced ratio fields to updatedModel object
- Use empty string fallback for undefined values

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>"
```

---

## Task 6: 更新保存逻辑

**文件:**
- Modify: `web/src/pages/Setting/Ratio/ModelSettingsVisualEditor.jsx:110-177`

### 步骤 6.1: 扩展 output 对象

找到 `SubmitData` 函数中的 `const output = {`(约第 112 行),在对象中添加新字段。

找到现有的:
```javascript
CompletionRatio: {},
```

在这一行后添加:
```javascript
// 新增:高级倍率字段
CacheRatio: {},
CreateCacheRatio: {},
ImageRatio: {},
AudioRatio: {},
AudioCompletionRatio: {}
```

### 步骤 6.2: 添加数据转换逻辑

在同一个 `SubmitData` 函数中,找到 `models.forEach((model) => {` 块(约第 119 行),在现有的转换逻辑后添加。

找到:
```javascript
if (model.completionRatio !== '')
output.CompletionRatio[model.name] = parseFloat(model.completionRatio);
```

在这一行后添加:
```javascript

// 新增:处理高级倍率字段
if (model.cacheRatio !== '')
output.CacheRatio[model.name] = parseFloat(model.cacheRatio);
if (model.cacheCreationRatio !== '')
output.CreateCacheRatio[model.name] = parseFloat(model.cacheCreationRatio);
if (model.imageRatio !== '')
output.ImageRatio[model.name] = parseFloat(model.imageRatio);
if (model.audioRatio !== '')
output.AudioRatio[model.name] = parseFloat(model.audioRatio);
if (model.audioCompletionRatio !== '')
output.AudioCompletionRatio[model.name] = parseFloat(model.audioCompletionRatio);
```

### 步骤 6.3: 扩展 finalOutput 对象

找到 `const finalOutput = {`(约第 137 行),在对象中添加新字段。

找到现有的:
```javascript
CompletionRatio: JSON.stringify(output.CompletionRatio, null, 2),
```

在这一行后添加:
```javascript
CacheRatio: JSON.stringify(output.CacheRatio, null, 2),
CreateCacheRatio: JSON.stringify(output.CreateCacheRatio, null, 2),
ImageRatio: JSON.stringify(output.ImageRatio, null, 2),
AudioRatio: JSON.stringify(output.AudioRatio, null, 2),
AudioCompletionRatio: JSON.stringify(output.AudioCompletionRatio, null, 2),
```

### 步骤 6.4: 测试保存功能

1. 确保 Task 5.2 中添加的 `test-model-advanced` 还在表格中
2. 修改它的一些高级倍率值(如将缓存读取倍率改为 `0.8`)
3. 点击"应用更改"按钮
4. 打开浏览器网络标签,筛选 `/api/option/` 请求

预期:
- 看到多个 `PUT /api/option/` 请求
- 其中包含 `CacheRatio`、`CreateCacheRatio` 等新增字段
- 请求体包含 JSON 数据,键为 `test-model-advanced`

### 步骤 6.5: 验证 API 请求体

在网络标签中点击任意一个 `/api/option/` 请求,查看"Payload"或"请求体":

```json
{
"key": "CacheRatio",
"value": "{\n \"test-model-advanced\": 0.8\n}"
}
```

预期:
- `value` 是格式化的 JSON 字符串(有缩进)
- 包含正确的模型名和倍率值

### 步骤 6.6: 提交保存逻辑更改

```bash
git add web/src/pages/Setting/Ratio/ModelSettingsVisualEditor.jsx
git commit -m "feat(save): serialize and save advanced ratio fields

- Add 5 new fields to output object
- Convert model data to float and populate output fields
- Serialize all fields to JSON in finalOutput
- Submit 7 total option fields (2 existing + 5 new)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>"
```

---

## Task 7: 更新输入验证逻辑

**文件:**
- Modify: `web/src/pages/Setting/Ratio/ModelSettingsVisualEditor.jsx:255-270`

### 步骤 7.1: 确认 updateModel 函数

找到 `updateModel` 函数(约第 255 行),确认现有的验证逻辑:

```javascript
const updateModel = (name, field, value) => {
if (isNaN(value) && value !== '') {
showError(t('请输入数字'));
return;
}
// ... 更新逻辑
};
```

**说明**:由于我们使用 `Form.InputNumber` 组件,它已经内置了数字验证,所以 `updateModel` 函数不需要修改。`isNaN` 检查已经足够处理高级倍率字段。

### 步骤 7.2: 测试验证逻辑

在开发服务器运行的情况下:

1. 尝试在表格中直接点击模型倍率或补全倍率输入框
2. 输入文字(如 `abc`)
3. 观察是否显示错误提示"请输入数字"

**注意**:由于我们现在使用 `Form.InputNumber` 而非 `Input`,高级比例字段在弹窗中,`updateModel` 函数不会被它们调用。`Form.InputNumber` 会自动限制只能输入数字。

### 步骤 7.3: 验证空值处理

测试空值是否正确处理:

1. 编辑一个模型
2. 在高级比例区域,将所有输入框留空
3. 点击"确定"
4. 点击"应用更改"

预期:
- 保存成功,无错误
- 空值保存为空字符串,后端使用默认值

### 步骤 7.4: 提交验证相关更改

如果本任务没有代码修改,跳过提交。否则:

```bash
git add web/src/pages/Setting/Ratio/ModelSettingsVisualEditor.jsx
git commit -m "feat(validation): enhance input validation for advanced ratios

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>"
```

---

## Task 8: 完整功能测试

**文件:**
- Test: `web/src/pages/Setting/Ratio/ModelSettingsVisualEditor.jsx`

### 步骤 8.1: 测试数据初始化

1. 清空浏览器缓存或使用隐私模式
2. 访问:http://localhost:5173/setting/ratio
3. 切换到"可视化倍率设置"标签

预期:
- 表格正常显示
- 无 JavaScript 错误
- 表格包含所有现有模型

### 步骤 8.2: 测试添加带高级倍率的模型

1. 点击"添加模型"
2. 输入:
- 模型名称:`claude-3-5-sonnet-20241022`
- 定价模式:按量计费
- 价格设置方式:按倍率设置
- 模型倍率:`1.5`
- 补全倍率:`1.2`
- 缓存读取倍率:`0.1`
- 缓存创建倍率:`1.25`
- 图片倍率:留空
- 音频输入倍率:留空
- 音频输出倍率:留空
3. 点击"确定"

预期:
- 模型成功添加
- 表格中显示新模型
- 无错误提示

### 步骤 8.3: 测试编辑高级倍率

1. 点击刚才添加的模型的"编辑"按钮
2. 修改高级倍率值:
- 缓存读取倍率:`0.15`
- 缓存创建倍率:`1.3`
- 图片倍率:`2.5`
- 音频输入倍率:`10.0`
- 音频输出倍率:`20.0`
3. 点击"确定"
4. 点击"应用更改"

预期:
- 编辑成功
- 显示"保存成功"提示

### 步骤 8.4: 验证数据持久化

刷新浏览器页面,重新访问可视化倍率设置:

1. 点击刚才编辑的模型的"编辑"按钮
2. 检查高级比例区域的值是否与步骤 8.3 中设置的一致

预期:
- 缓存读取倍率:显示 `0.15`
- 缓存创建倍率:显示 `1.3`
- 图片倍率:显示 `2.5`
- 音频输入倍率:显示 `10.0`
- 音频输出倍率:显示 `20.0`

### 步骤 8.5: 测试删除模型

1. 选择测试模型
2. 点击"删除"按钮
3. 确认删除

预期:
- 模型从表格中移除
- 删除的高级倍率数据在保存时被清除(后续保存不会包含该模型)

### 步骤 8.6: 测试边界情况

**测试负数输入**:
1. 尝试在高级比例输入框输入 `-1`
2. 预期:`min={0}` 限制,无法输入负数

**测试小数精度**:
1. 输入 `0.123456`
2. 预期:`step={0.01}` 限制,可以输入但会保留多位小数(Semi UI InputNumber 行为)

**测试空值保存**:
1. 编辑模型,清空所有高级比例输入框
2. 点击"确定",然后"应用更改"
3. 预期:保存成功,后端使用默认值

### 步骤 8.7: 测试国际化切换

1. 在系统设置中切换到英文(如果支持)
2. 重新访问可视化倍率设置
3. 检查高级比例区域的标签是否显示为英文

预期:
- "高级比例(留空使用默认值)" → "Advanced Ratios (Leave empty for defaults)"
- "缓存读取倍率" → "Cache Read Ratio"
- 其他字段类似

### 步骤 8.8: 创建测试提交

如果所有测试通过,创建一个测试提交标记:

```bash
git add web/src/pages/Setting/Ratio/ModelSettingsVisualEditor.jsx
git commit -m "test: verify advanced ratios functionality

- Test data initialization with empty options
- Test adding model with advanced ratios
- Test editing advanced ratios
- Test data persistence after page refresh
- Test model deletion
- Test edge cases (negative numbers, decimal precision, empty values)
- Test internationalization (English/Chinese)

All tests passed successfully.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>"
```

---

## Task 9: 代码清理和优化

**文件:**
- Modify: `web/src/pages/Setting/Ratio/ModelSettingsVisualEditor.jsx`

### 步骤 9.1: 检查代码格式化

运行代码格式化工具(如果项目配置了):

```bash
cd web
bun run lint --fix
```

预期:
- 无 lint 错误
- 代码格式符合项目规范

### 步骤 9.2: 检查 console.log

搜索并移除任何调试用的 `console.log`:

```bash
cd web/src/pages/Setting/Ratio
grep -n "console.log" ModelSettingsVisualEditor.jsx
```

如果找到任何 `console.log`,删除它们。

### 步骤 9.3: 验证组件性能

检查是否有不必要的重渲染:

1. 打开浏览器 React DevTools(如果可用)
2. 选择 "Profiler" 标签
3. 记录编辑模型时的性能
4. 检查是否有异常的重渲染

预期:
- 组件重渲染次数合理
- 无明显的性能问题

### 步骤 9.4: 提交清理更改

如果有任何清理更改:

```bash
git add web/src/pages/Setting/Ratio/ModelSettingsVisualEditor.jsx
git commit -m "refactor: code cleanup and optimization

- Remove debug console.log statements
- Format code with linter
- Verify component performance

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>"
```

---

## 验证清单

在实施完成后,验证以下所有项目:

### 功能验证
- [ ] 可以添加带有高级倍率的模型
- [ ] 可以编辑模型的高级倍率字段
- [ ] 可以删除模型
- [ ] 数据正确保存到后端
- [ ] 刷新页面后数据正确加载
- [ ] 空值字段使用默认值

### UI/UX 验证
- [ ] 高级比例区域正确显示
- [ ] 所有 5 个字段都有正确的标签
- [ ] Placeholder 显示正确的默认值
- [ ] 输入验证正常工作(负数、非数字)
- [ ] 中英文切换正常

### 代码质量
- [ ] 无 TypeScript/JavaScript 错误
- [ ] 无 lint 错误
- [ ] 无调试 console.log
- [ ] 代码格式符合项目规范
- [ ] 所有提交都有清晰的 commit message

### 数据完整性
- [ ] 前端字段名与后端 Option Key 一致
- [ ] JSON 序列化/反序列化正确
- [ ] 空值处理正确(空字符串,非 null)
- [ ] 数值转换正确(parseFloat)

---

## 实施完成后的最终检查

### 步骤 1: 查看所有提交

```bash
git log --oneline --no-merges | head -20
```

预期:看到一系列清晰的、原子性的提交,每个提交对应一个任务或功能点

### 步骤 2: 验证文件更改

```bash
git diff HEAD~10 HEAD --stat
```

预期:
- `ModelSettingsVisualEditor.jsx` 有显著更改
- `zh-CN.json` 和 `en.json` 有新增翻译
- 无其他意外更改

### 步骤 3: 最终功能测试

重复 Task 8 中的所有测试步骤,确保一切正常。

### 步骤 4: 合并到主分支(如果需要)

```bash
git checkout master
git merge <branch-name>
git push
```

---

## 故障排查

### 问题:表格不显示

**症状**:访问可视化倍率设置页面,表格为空

**排查**:
1. 打开浏览器控制台,检查是否有 JavaScript 错误
2. 检查 `useEffect` 中的 JSON 解析是否成功
3. 验证 `props.options` 是否包含所有必需的字段

**解决**:
- 确保后端 API 返回所有 7 个字段(ModelPrice, ModelRatio, CompletionRatio, CacheRatio, CreateCacheRatio, ImageRatio, AudioRatio, AudioCompletionRatio)

### 问题:高级比例区域不显示

**症状**:编辑模型时看不到高级比例输入框

**排查**:
1. 检查定价模式是否为"按量计费"(`pricingMode === 'per-token'`)
2. 检查 Form.Section 的条件渲染
3. 验证国际化文本是否加载

**解决**:
- 确保在"按量计费"模式下编辑
- 检查 `t()` 函数是否返回正确的翻译文本

### 问题:数据保存失败

**症状**:点击"应用更改"后显示错误

**排查**:
1. 打开浏览器网络标签,检查 `/api/option/` 请求
2. 查看请求响应状态码和消息
3. 验证请求数据格式是否正确

**解决**:
- 确保所有 7 个字段都包含在 `finalOutput` 中
- 检查 JSON 序列化是否正确
- 验证后端 API 是否支持所有 7 个 Option Key

### 问题:翻译文本显示为键名

**症状**:界面显示 `"高级比例(留空使用默认值)"` 而非翻译后的文本

**排查**:
1. 检查 i18n 配置文件是否正确加载
2. 验证 JSON 格式是否正确
3. 检查是否有语法错误导致整个文件无法解析

**解决**:
- 修复 JSON 语法错误
- 重新加载页面
- 清除浏览器缓存

---

## 预计时间

- Task 1 (国际化): 15 分钟
- Task 2 (数据初始化): 20 分钟
- Task 3 (表单 UI): 15 分钟
- Task 4 (编辑逻辑): 10 分钟
- Task 5 (添加/更新): 10 分钟
- Task 6 (保存逻辑): 15 分钟
- Task 7 (验证逻辑): 5 分钟
- Task 8 (完整测试): 30 分钟
- Task 9 (代码清理): 10 分钟

**总计**: 约 2.5 小时

---

## 参考资源

### 内部文档
- 设计规范: `docs/superpowers/specs/2026-06-04-extended-visual-ratio-settings-design.md`
- 渠道价格设置实现: `feat/channel-pricing-extended:web/src/pages/Setting/Ratio/ChannelPricingView.jsx`

### API 文档
- Semi UI Form: https://douyinfe.github.io/semi-ui/form/form-inputnumber
- React hooks: https://react.dev/reference/react

### 后端接口
- GET `/api/option/` - 获取所有选项
- PUT `/api/option/` - 更新单个选项(请求体: `{ key, value }`)

---

**实施计划完成**

Загрузка…
Отмена
Сохранить