15 KiB

原始文件 Blame 歷史記錄

Channel PublicName 实施计划

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.

Goal: 为 Channel 添加 public_name 字段，让管理员可以为每个渠道设置用户可见的友好名称，替代前端硬编码的"通道一/二/三”。

Architecture: 后端 Channel 模型新增字段 → AutoMigrate 自动建列 → 迁移函数回填数据 → 定价查询和 API 返回公共名称 → 前端表单支持编辑 → 展示层使用公共名称。

Tech Stack: Go (GORM) / React (Semi Design) / SQLite+MySQL+PostgreSQL

Task 1: Channel 模型添加 PublicName 字段

Files:

Modify: model/channel.go:28
Step 1: 在 Channel 结构体 Name 字段后添加 PublicName

当前代码（model/channel.go:28）：

Name               string  `json:"name" gorm:"index"`
Weight             *uint   `json:"weight" gorm:"default:0"`

改为：

Name               string  `json:"name" gorm:"index"`
PublicName         string  `json:"public_name" gorm:"size:255;default:''"`
Weight             *uint   `json:"weight" gorm:"default:0"`

Step 2: 验证编译通过

Run: cd D:/code/new-api && go build ./model/... Expected: 编译成功，无错误

Step 3: Commit

git add model/channel.go
git commit -m "feat: add PublicName field to Channel model"

Task 2: 修改 GetAllChannelsForBinding 查询包含 public_name

Files:

Modify: model/channel.go:282
Step 1: 修改 Select 列

当前代码（model/channel.go:282）：

err := DB.Select("id, name, type, remark").

改为：

err := DB.Select("id, name, public_name, type, remark").

Step 2: 验证编译通过

Run: cd D:/code/new-api && go build ./model/... Expected: 编译成功

Step 3: Commit

git add model/channel.go
git commit -m "feat: include public_name in GetAllChannelsForBinding query"

Task 3: ChannelPricingWithChannel 扩展 + SQL 查询修改

Files:

Modify: model/channel_pricing.go:254 (结构体)
Modify: model/channel_pricing.go:299 (SELECT)
Modify: model/channel_pricing.go:319 (GROUP BY)
Step 1: 结构体添加 ChannelPublicName 字段

当前代码（model/channel_pricing.go:254）：

ChannelName      string        `json:"channel_name"`
ChannelType      int           `json:"channel_type"`

改为：

ChannelName      string        `json:"channel_name"`
ChannelPublicName string       `json:"channel_public_name"`
ChannelType      int           `json:"channel_type"`

Step 2: SELECT 子句添加 channels.public_name

当前代码（model/channel_pricing.go:299）：

Select(`abilities.channel_id, channels.name as channel_name, channels.type as channel_type,

改为：

Select(`abilities.channel_id, channels.name as channel_name, channels.public_name as channel_public_name, channels.type as channel_type,

Step 3: GROUP BY 子句添加 channels.public_name

当前代码（model/channel_pricing.go:319）：

Group("abilities.channel_id, channels.name, channels.type, channel_pricings.quota_type,

改为：

Group("abilities.channel_id, channels.name, channels.public_name, channels.type, channel_pricings.quota_type,

注意：channels.public_name 插入在 channels.name 后面。

Step 4: 验证编译通过

Run: cd D:/code/new-api && go build ./model/... Expected: 编译成功

Step 5: Commit

git add model/channel_pricing.go
git commit -m "feat: add public_name to channel pricing query"

Task 4: pricing.go 默认通道名称使用 public_name

Files:

Modify: model/pricing.go:290-303
Step 1: 扩展匿名结构体

当前代码（model/pricing.go:290-293）：

var allCPs []struct {
    ChannelPricing
    ChannelName string
}

改为：

var allCPs []struct {
    ChannelPricing
    ChannelName       string
    ChannelPublicName string
}

Step 2: 扩展 Select 子句

当前代码（model/pricing.go:295）：

Select("channel_pricings.*, channels.name as channel_name").

改为：

Select("channel_pricings.*, channels.name as channel_name, channels.public_name as channel_public_name").

Step 3: 修改 channelNameMap 构建逻辑

当前代码（model/pricing.go:303）：

channelNameMap[allCPs[i].ChannelId] = allCPs[i].ChannelName

改为：

name := allCPs[i].ChannelPublicName
if name == "" {
    name = allCPs[i].ChannelName
}
channelNameMap[allCPs[i].ChannelId] = name

Step 4: 验证编译通过

Run: cd D:/code/new-api && go build ./model/... Expected: 编译成功

Step 5: Commit

git add model/pricing.go
git commit -m "feat: use public_name as default channel display name"

Task 5: 数据回填迁移函数

Files:

Modify: model/main.go:306-307 (调用位置)
Modify: model/main.go:695 (函数定义位置)
Step 1: 在 migrateDB 的 return nil 之前插入调用

当前代码（model/main.go:304-308）：

// 将现有 sort_order=0 的模型和供应商更新为默认大数
DB.Model(&Model{}).Where("sort_order = 0").Update("sort_order", 999999)
DB.Model(&Vendor{}).Where("sort_order = 0").Update("sort_order", 999999)
return nil
}

改为：

// 将现有 sort_order=0 的模型和供应商更新为默认大数
DB.Model(&Model{}).Where("sort_order = 0").Update("sort_order", 999999)
DB.Model(&Vendor{}).Where("sort_order = 0").Update("sort_order", 999999)

migrateChannelPublicName()

return nil
}

Step 2: 在文件末尾（第 696 行后）添加迁移函数

func migrateChannelPublicName() {
	result := DB.Model(&Channel{}).
		Where("public_name = '' OR public_name IS NULL").
		Update("public_name", gorm.Expr("name"))
	if result.Error != nil {
		common.SysError("[Migration] migrateChannelPublicName failed: " + result.Error.Error())
	} else if result.RowsAffected > 0 {
		common.SysLog(fmt.Sprintf("[Migration] migrateChannelPublicName: backfilled %d channels", result.RowsAffected))
	}
}

说明：

AutoMigrate（migrateDB() 第 262 行 &Channel{}）会先创建列
WHERE 条件保证幂等
gorm.Expr("name") 引用列名，SQLite/MySQL/PostgreSQL 通用
model/main.go 已有 fmt、gorm、common 的 import，无需额外导入
Step 3: 验证编译通过

Run: cd D:/code/new-api && go build ./model/... Expected: 编译成功

Step 4: Commit

git add model/main.go
git commit -m "feat: add migration to backfill public_name from name"

Task 6: controller 层验证 + API 返回

Files:

Modify: controller/channel.go:582-585 (验证)
Modify: controller/channel.go:2110-2115 (API 返回)
Step 1: 在 validateChannel 的 isAdd 块中添加 public_name 校验

当前代码（controller/channel.go:582-585）：

if isAdd {
    if channel == nil || channel.Key == "" {
        return fmt.Errorf("channel cannot be empty")
    }

    // 检查模型名称长度是否超过 255

改为：

if isAdd {
    if channel == nil || channel.Key == "" {
        return fmt.Errorf("channel cannot be empty")
    }

    if strings.TrimSpace(channel.PublicName) == "" {
        return fmt.Errorf("public name cannot be empty")
    }

    // 检查模型名称长度是否超过 255

说明： 保持英文错误消息与现有代码一致。

Step 2: 在 GetUserChannelsForBinding 返回值中添加 public_name

当前代码（controller/channel.go:2110-2115）：

result = append(result, gin.H{
    "id":     ch.Id,
    "name":   ch.Name,
    "type":   ch.Type,
    "remark": ch.Remark,
})

改为：

result = append(result, gin.H{
    "id":          ch.Id,
    "name":        ch.Name,
    "public_name": ch.PublicName,
    "type":        ch.Type,
    "remark":      ch.Remark,
})

Step 3: 验证编译通过

Run: cd D:/code/new-api && go build ./controller/... Expected: 编译成功

Step 4: Commit

git add controller/channel.go
git commit -m "feat: validate public_name on channel creation and return in binding API"

Task 7: 前端 i18n 翻译

Files:

Modify: web/src/i18n/locales/zh-CN.json
Modify: web/src/i18n/locales/en.json
Step 1: zh-CN.json 添加翻译

在 "请为渠道命名" 条目（第 2454 行）之后添加：

"对外名称": "对外名称",
"用户看到的渠道名称，如"标准通道"、"高速通道"": "用户看到的渠道名称，如"标准通道"、"高速通道"",
"请填写对外名称": "请填写对外名称",
"请填写渠道名称、对外名称和渠道密钥！": "请填写渠道名称、对外名称和渠道密钥！",

注意：zh-CN.json 的 key 和 value 相同（中文 → 中文）。

Step 2: en.json 添加翻译

在 "Please name the channel" 条目（第 2473 行）之后添加：

"对外名称": "Public Name",
"用户看到的渠道名称，如"标准通道"、"高速通道"": "User-facing channel name, e.g. \"Standard\", \"Fast\"",
"请填写对外名称": "Please enter a public name",
"请填写渠道名称、对外名称和渠道密钥！": "Please enter channel name, public name and key!",

Step 3: Commit

git add web/src/i18n/locales/zh-CN.json web/src/i18n/locales/en.json
git commit -m "feat: add i18n translations for channel public_name"

Task 8: EditChannelModal 表单添加对外名称字段

Files:

Modify: web/src/components/table/channels/modals/EditChannelModal.jsx:142 (originInputs)
Modify: web/src/components/table/channels/modals/EditChannelModal.jsx:1980 (表单 UI)
Modify: web/src/components/table/channels/modals/EditChannelModal.jsx:1329 (提交校验)
Step 1: originInputs 添加 public_name 默认值

当前代码（第 142-143 行）：

const originInputs = {
    name: '',
    type: 1,

改为：

const originInputs = {
    name: '',
    public_name: '',
    type: 1,

Step 2: 在 name 的 Form.Input 后添加 public_name 输入框

当前代码（第 1972-1980 行）：

<Form.Input
  field='name'
  label={t('名称')}
  placeholder={t('请为渠道命名')}
  rules={[{ required: true, message: t('请为渠道命名') }]}
  showClear
  onChange={(value) => handleInputChange('name', value)}
  autoComplete='new-password'
/>

{inputs.type === 33 && (

在第 1980 行 /> 和第 1982 行 {inputs.type === 33 之间插入：

<Form.Input
  field='name'
  label={t('名称')}
  placeholder={t('请为渠道命名')}
  rules={[{ required: true, message: t('请为渠道命名') }]}
  showClear
  onChange={(value) => handleInputChange('name', value)}
  autoComplete='new-password'
/>
<Form.Input
  field='public_name'
  label={t('对外名称')}
  placeholder={t('用户看到的渠道名称，如"标准通道"、"高速通道"')}
  rules={!isEdit ? [{ required: true, message: t('请填写对外名称') }] : []}
  showClear
  onChange={(value) => handleInputChange('public_name', value)}
  autoComplete='new-password'
/>

{inputs.type === 33 && (

说明： !isEdit 条件确保新建时必填、编辑时允许清空。

Step 3: 修改提交前校验

当前代码（第 1329-1332 行）：

if (!isEdit && (!localInputs.name || !localInputs.key)) {
  showInfo(t('请填写渠道名称和渠道密钥！'));
  return;
}

改为：

if (!isEdit && (!localInputs.name || !localInputs.public_name || !localInputs.key)) {
  showInfo(t('请填写渠道名称、对外名称和渠道密钥！'));
  return;
}

Step 4: Commit

git add web/src/components/table/channels/modals/EditChannelModal.jsx
git commit -m "feat: add public_name field to channel edit form"

Task 9: ChannelPricingCard 展示公共名称

Files:

Modify: web/src/components/table/model-pricing/modal/components/ChannelPricingCard.jsx:107
Step 1: 修改 channelName 赋值逻辑

当前代码（第 104-108 行）：

const tableData = channelPricingData.map((item, index) => ({
    key: item.channel_id || index,
    channelId: item.channel_id,
    channelName: `通道${['一', '二', '三', '四', '五', '六', '七', '八', '九', '十'][index] || ` ${index + 1}`}`,
    channelTags: item.tags || [],

改为：

const tableData = channelPricingData.map((item, index) => ({
    key: item.channel_id || index,
    channelId: item.channel_id,
    channelName: item.channel_public_name || ('通道' + (['一', '二', '三', '四', '五', '六', '七', '八', '九', '十'][index] || (index + 1))),
    channelTags: item.tags || [],

说明： 优先使用后端 channel_public_name，为空时回退到中文数字。同时修复原代码反引号嵌套语法问题。

Step 2: Commit

git add web/src/components/table/model-pricing/modal/components/ChannelPricingCard.jsx
git commit -m "feat: display public_name in ChannelPricingCard"

Task 10: 端到端验证

Files: 无代码修改，纯验证

Step 1: 后端编译

Run: cd D:/code/new-api && go build -o new-api main.go Expected: 编译成功

Step 2: 启动服务

Run: cd D:/code/new-api && go run main.go Expected: 日志中出现 [Migration] migrateChannelPublicName: backfilled N channels

Step 3: 再次重启确认幂等

重启服务后 Expected: 日志中不再出现 backfilled（RowsAffected=0）

Step 4: API 测试 — 创建渠道不带 public_name

Run:

curl -s -X POST http://localhost:3000/api/channel/ \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"single","channel":{"type":1,"name":"测试","key":"sk-test"}}'

Expected: 返回错误 "public name cannot be empty"

Step 5: API 测试 — 创建渠道带 public_name

Run:

curl -s -X POST http://localhost:3000/api/channel/ \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"single","channel":{"type":1,"name":"测试","public_name":"标准通道","key":"sk-test"}}'

Expected: 返回成功

Step 6: API 测试 — 定价接口包含 public_name

Run:

curl -s http://localhost:3000/api/channel-pricing/model/gpt-4

Expected: 响应中包含 channel_public_name 字段

Step 7: 前端验证

在浏览器中依次验证：

渠道管理 → 新建渠道 → 可见"对外名称"输入框
不填"对外名称"提交 → 显示验证错误
填写后提交成功
编辑渠道 → 可见已保存的对外名称
编辑时清空对外名称并保存 → 成功（向后兼容）
模型详情侧边栏 → ChannelPricingCard 显示对外名称
首页定价卡片 → “默认通道"标签显示对外名称
未设 public_name 的渠道 → 显示"通道一/二/三...”

15 KiB 原始文件 Blame 歷史記錄

Channel PublicName 实施计划

Task 1: Channel 模型添加 PublicName 字段

Task 2: 修改 GetAllChannelsForBinding 查询包含 public_name

Task 3: ChannelPricingWithChannel 扩展 + SQL 查询修改

Task 4: pricing.go 默认通道名称使用 public_name

Task 5: 数据回填迁移函数

Task 6: controller 层验证 + API 返回

Task 7: 前端 i18n 翻译

Task 8: EditChannelModal 表单添加对外名称字段

Task 9: ChannelPricingCard 展示公共名称

Task 10: 端到端验证

15 KiB

原始文件 Blame 歷史記錄