huang
7e613a0d2b
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
63 lines
3.1 KiB
Markdown
63 lines
3.1 KiB
Markdown
## Context
|
||
|
||
项目全局约定 `0=禁用, 1=启用`，定义在 `pkg/constants/constants.go`：
|
||
|
||
```go
|
||
StatusDisabled = 0 // 禁用
|
||
StatusEnabled = 1 // 启用
|
||
```
|
||
|
||
但有 6 个 model 的 GORM comment 标签写的是 `1-启用 2-禁用`，与约定相反。
|
||
经过排查，service 层代码已经使用正确的 `constants.StatusDisabled = 0`，**数据库里也不存在 status=2 的行**，因此本次变更属于纯文档/注释层面修正，无需数据迁移。
|
||
|
||
受影响的模块和当前状态：
|
||
|
||
| 文件 | 结构体 | 表名 | DB 行数 | status 现有值 |
|
||
|------|--------|------|---------|--------------|
|
||
| model/package.go | PackageSeries | tb_package_series | 7 | 全=1 |
|
||
| model/package.go | Package | tb_package | 9 | 全=1 |
|
||
| model/shop_package_allocation.go | ShopPackageAllocation | tb_shop_package_allocation | 6 | 全=1 |
|
||
| model/shop_series_allocation.go | ShopSeriesAllocation | tb_shop_series_allocation | 6 | 全=1 |
|
||
| model/system.go | DevCapabilityConfig | tb_dev_capability_config | 0 | — |
|
||
| model/financial.go | PaymentMerchantSetting | tb_payment_merchant_setting | 0 | — |
|
||
|
||
另外，`pkg/constants/iot.go` 中有专为 DevCapabilityConfig 设计的僵尸常量：
|
||
```go
|
||
DevCapabilityStatusEnabled = 1 // 未被 service 调用
|
||
DevCapabilityStatusDisabled = 2 // 未被 service 调用
|
||
```
|
||
|
||
## Goals / Non-Goals
|
||
|
||
**Goals:**
|
||
- 让 model GORM comment 与全局约定保持一致（`0=禁用 1=启用`）
|
||
- 删除未使用的 `DevCapabilityStatusEnabled/Disabled` 常量
|
||
- 修正 DTO description 中对 status 的错误枚举说明
|
||
- 修正一处语义混用：`ShelfStatus: constants.StatusEnabled` → `constants.ShelfStatusOn`
|
||
- 通过编译检查，确认没有代码依赖被删除的常量
|
||
|
||
**Non-Goals:**
|
||
- 不涉及任何数据库迁移
|
||
- 不变更 API 接口行为或响应结构
|
||
- 不修改 `ShelfStatus 1=上架 2=下架` 约定（这是业务刻意区分的双维度设计，与启用/禁用独立）
|
||
- 不重构 service 层逻辑（已经正确）
|
||
|
||
## Decisions
|
||
|
||
### 决策1：只改注释，不加数据库迁移
|
||
|
||
**理由**：service 代码已经用 `StatusDisabled=0`，DB 里没有 status=2 的行。如果加迁移反而制造风险（空操作 UPDATE 会锁表、影响上线流程）。
|
||
|
||
### 决策2：删除 DevCapabilityStatusEnabled/Disabled，不替换
|
||
|
||
**理由**：这两个常量未被任何 service 调用（仅在 openspec 历史归档文档中出现）。删除即可，未来如果 DevCapabilityConfig 的 service 有状态判断，直接用全局 `StatusEnabled/StatusDisabled` 即可。
|
||
|
||
### 决策3：DTO description 同步修正
|
||
|
||
DTO description 是 OpenAPI 文档的来源，如果注释说 `1:启用, 2:禁用`，生成的 API 文档就会误导前端开发者。必须一并修正。
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- **[低风险] 前端如果对 status=2 有判断逻辑** → 但实际 API 从来没有返回过 status=2（service 代码从未写入2），此风险理论上不存在。如有疑虑，可先搜索前端代码。
|
||
- **[极低风险] 将来添加 DevCapabilityConfig service 时忘记用全局常量** → 已在 AGENTS.md 中有规范约束（0=禁用 1=启用），删除僵尸常量反而消除了歧义。
|