归档: fix-status-convention-comments

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

openspec/changes/archive/2026-04-11-fix-status-convention-comments/design.md

@@ -0,0 +1,62 @@
+## 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=启用），删除僵尸常量反而消除了歧义。