92 lines
5.7 KiB
Markdown
92 lines
5.7 KiB
Markdown
---
|
||
name: 允许免费额度配置为 0
|
||
overview: 修复新用户免费额度配置无法设为 0 的问题：配置字段改为 *int64 以区分「未配置」与「显式 0」，未配置回落内置默认，显式 0 生效为 0。
|
||
todos:
|
||
- id: change-setting-fields
|
||
content: 将 UserDefaultQuotaSettingS 四字段改为 *int64 并更新注释
|
||
status: completed
|
||
- id: fix-default-quota-value
|
||
content: 改 defaultQuotaValue 为指针判空判据，允许 0 生效
|
||
status: completed
|
||
dependencies:
|
||
- change-setting-fields
|
||
- id: sync-constants-comment
|
||
content: 同步 constants.go 内置默认常量注释语义
|
||
status: completed
|
||
dependencies:
|
||
- fix-default-quota-value
|
||
- id: sync-docs
|
||
content: 同步 README、config.example.yaml 与接口文档说明
|
||
status: completed
|
||
dependencies:
|
||
- fix-default-quota-value
|
||
- id: build-verify
|
||
content: 执行 go build ./... 与 go vet ./... 验证编译
|
||
status: completed
|
||
dependencies:
|
||
- sync-constants-comment
|
||
- sync-docs
|
||
- id: review-config-usage
|
||
content: 用 [subagent:code-explorer] 复核配置消费点与文档无旧语义残留
|
||
status: completed
|
||
dependencies:
|
||
- build-verify
|
||
---
|
||
|
||
## 产品概述
|
||
|
||
修复新用户免费额度初始化的配置语义缺陷：原有实现把「配置为 0」误判为「未配置」而回落内置默认，导致无法将某类免费额度配成 0（例如要求新用户 AI 推荐额度为 0、必须购买后才可用）。
|
||
|
||
## 核心功能
|
||
|
||
- **区分「未配置」与「显式 0」**：`UserDefaultQuota` 四个配置字段改为指针类型，未配置（nil）回落内置默认 20/3/10/5，显式配置 0 则生效为 0
|
||
- **保持兜底能力**：整段配置缺失、单个键缺失、配置为负数三种情况仍回落内置默认，不破坏既有部署
|
||
- **文档同步**：README 配置项说明、config.example.yaml 注释、接口文档额度说明统一为「允许配 0，未配置回落默认」
|
||
- **行为不变**：四类额度的初始化流程、流水记录、唯一索引幂等逻辑完全不动
|
||
|
||
## 技术栈
|
||
|
||
- Go 1.27，模块 `git.lzcwy.cn/zhengchiliu/zt-closet-backend`
|
||
- 配置：`pkg/setting`（viper 只读 `configs/config.yaml`，`ReadSection` 走 `UnmarshalKey`/mapstructure）
|
||
- 消费点唯一：`internal/service/quota.go` 的 `defaultQuotaValue`（grep 已确认无其它引用）
|
||
|
||
## 实现方案
|
||
|
||
采用**指针字段区分三态**：把 `UserDefaultQuotaSettingS` 的 `Cos/AI/OutfitShare/ClosetShare` 由 `int64` 改为 `*int64`。viper 解码时键存在则分配指针（含 0），键不存在则保持 nil，从而在类型层面区分「未配置」与「配置为 0」。
|
||
|
||
取值判据（`defaultQuotaValue`）：
|
||
|
||
- `cfg == nil`（整段缺失）→ 内置默认
|
||
- `cfg.X == nil`（该键缺失）→ 内置默认
|
||
- `*cfg.X >= 0` → 用配置值（**0 生效，本次修复目标**）
|
||
- `*cfg.X < 0` → 内置默认（防御：负数会让 `total` 为负，破坏额度校验）
|
||
|
||
关键决策与取舍：
|
||
|
||
1. **用 `*int64` 而非把判据改成 `>= 0`**：后者能让 0 生效，但「键缺失」解码后同样是 0，会静默把兜底默认值变成 0——对现有未显式配置的环境是破坏性变更。指针方案零歧义，代价仅是多一层判空。
|
||
2. **用指针而非 `viper.IsSet` 逐键查询**：配置结构仍由结构体承载，`ReadSection` 用法与其它配置段一致，不引入第二套读取方式，符合现有架构。
|
||
3. **负数回落而非报错**：保持 best-effort 风格（与额度初始化失败仅告警不阻断一致），不引入启动期配置校验的新失败路径。
|
||
4. **保留内置常量值 20/3/10/5 不变**：只改判据与注释，不动 `ensureDefaultQuota` 的创建+流水事务逻辑。
|
||
|
||
性能与可靠性：该路径仅在首次登录注册时执行 4 次，指针判空为 O(1) 无额外开销；风险点仅为指针解引用，通过判空分支覆盖，并有 `go build`/`go vet` 兜底。
|
||
|
||
## 实现要点（防回归）
|
||
|
||
- 改字段类型后必须全量编译，`global.UserDefaultQuotaSetting` 的其它消费点若有解引用会直接编译报错（当前仅 quota.go 一处）。
|
||
- 判空顺序必须为 `cfg != nil && cfg.X != nil && *cfg.X >= 0`，避免 nil 解引用 panic。
|
||
- 注释需同步：结构体注释「值 <=0 视为未设置」、`constants.go:42`「配置缺省或 <=0 时回落」、`defaultQuotaValue` 函数注释，三处都要改成新语义，否则后续维护者会按旧语义改回去。
|
||
- 不要扩大范围：`Upload.MaxSizeMB`、`MattingModel.MaxRetry` 等其它 `<=0` 兜底语义不同（0 无业务意义），本次不动，仅在结论中提示。
|
||
- 不改动 `configs/config.yaml`（用户本地文件，已被 .gitignore 忽略）。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
pkg/setting/section.go # [MODIFY] UserDefaultQuotaSettingS 四字段 int64 → *int64；
|
||
# 注释改为「nil=未配置回落默认；非 nil 生效，允许 0」
|
||
internal/service/quota.go # [MODIFY] defaultQuotaValue 判据改为指针判空 + >=0 生效；
|
||
# 函数注释同步（未配置/负数回落，0 生效）
|
||
internal/service/constants.go # [MODIFY] 第 42 行注释「配置缺省或 <=0 时回落」→「未配置(nil)或负数时回落」
|
||
README.md # [MODIFY] 第 195 行配置表说明改为「未配置回落内置默认 20/3/10/5；可显式配 0」
|
||
configs/config.example.yaml # [MODIFY] UserDefaultQuota 段注释补充「可为 0 表示不赠送；留空则回落内置默认」
|
||
接口文档.md # [MODIFY] 第 488/1432/1446 行及 5.2 节额度表格补「可由 UserDefaultQuota 配置，允许为 0」
|
||
``` |