归档: 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/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-11

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=启用），删除僵尸常量反而消除了歧义。

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

@@ -0,0 +1,34 @@
+## Why
+
+model 层 6 个结构体的 `status` 字段注释写的是 `1-启用 2-禁用`，与项目全局约定 `0=禁用, 1=启用` 相反。虽然 service 层代码已经在用正确的 `constants.StatusDisabled = 0`，但错误注释会误导开发者，同时 DTO description 和一个僵尸常量也需要同步修正。
+
+## What Changes
+
+- **修正 6 个 model 注释**：将 `comment: "状态 1-启用 2-禁用"` 改为 `comment: "状态 0=禁用 1=启用"`
+  - `internal/model/package.go`（PackageSeries.Status, Package.Status）
+  - `internal/model/shop_package_allocation.go`（ShopPackageAllocation.Status）
+  - `internal/model/shop_series_allocation.go`（ShopSeriesAllocation.Status）
+  - `internal/model/system.go`（DevCapabilityConfig.Status）
+  - `internal/model/financial.go`（PaymentMerchantSetting.Status）
+- **删除僵尸常量**：`pkg/constants/iot.go` 中的 `DevCapabilityStatusEnabled = 1` / `DevCapabilityStatusDisabled = 2` 从未被 service 层调用，直接删除
+- **修正 DTO description**：`internal/model/dto/` 中描述为 `(1:启用, 2:禁用)` 的字段改为 `(0:禁用, 1:启用)`（涉及 `package_series_dto.go`、`shop_series_grant_dto.go`、`my_package.go` 等）
+- **修正语义混用**：`shop_series_grant/service.go` 中 `ShelfStatus: constants.StatusEnabled` 改为 `constants.ShelfStatusOn`（值相同，但语义正确）
+
+**无任何数据库迁移**：所有有数据的表中 status 均为 1，没有 status=2 的行；service 代码已在用 `0=禁用` 约定。
+
+## Capabilities
+
+### New Capabilities
+
+无新能力引入。
+
+### Modified Capabilities
+
+无 spec 级别的行为变更，仅修正文档注释与代码的一致性。
+
+## Impact
+
+- **受影响文件**：`internal/model/`（6 个 model）、`internal/model/dto/`（若干 DTO）、`pkg/constants/iot.go`、`internal/service/shop_series_grant/service.go`
+- **API 行为**：不变。status 字段的实际读写逻辑不变，仅注释和常量修正
+- **数据库**：不变。无需迁移
+- **前端/接口消费方**：接口返回的 status 值本就是 0/1（由 service 代码决定），与注释写什么无关，不受影响

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

@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: model status 字段注释与全局约定一致
+所有 model 结构体的启用/禁用类 `status` 字段，其 GORM comment 标签 SHALL 使用 `0=禁用 1=启用` 格式，与 `pkg/constants/constants.go` 中 `StatusDisabled=0, StatusEnabled=1` 保持一致。
+
+#### Scenario: 查看 model GORM comment
+- **WHEN** 开发者查看任意 model 结构体的 status 字段标签
+- **THEN** comment 中启用/禁用的数值与全局常量 StatusEnabled=1、StatusDisabled=0 一致
+
+### Requirement: DTO description 与全局约定一致
+DTO 中描述启用/禁用状态的 `description` 标签 SHALL 使用 `(0:禁用, 1:启用)` 格式，不得写为 `(1:启用, 2:禁用)`。
+
+#### Scenario: 查看 DTO description
+- **WHEN** 开发者或文档生成器读取 DTO 的 status 字段 description
+- **THEN** 枚举值与全局约定 0=禁用、1=启用 一致
+
+### Requirement: 无未使用的状态常量
+`pkg/constants/` 中不 SHALL 存在与全局约定冲突的、且未被代码引用的状态常量。
+
+#### Scenario: 删除僵尸常量后编译通过
+- **WHEN** 删除 `DevCapabilityStatusEnabled` 和 `DevCapabilityStatusDisabled` 后执行 `go build ./...`
+- **THEN** 编译无报错，证明这两个常量从未被引用
+
+### Requirement: ShelfStatus 使用专用常量
+赋值 `ShelfStatus` 字段时 SHALL 使用 `constants.ShelfStatusOn` 或 `constants.ShelfStatusOff`，不得使用语义不相关的 `constants.StatusEnabled`。
+
+#### Scenario: 初始化分配记录的 ShelfStatus
+- **WHEN** service 创建新的 ShopSeriesAllocation 或 ShopPackageAllocation 记录
+- **THEN** ShelfStatus 字段赋值使用 `constants.ShelfStatusOn`（值=1），而非 `constants.StatusEnabled`

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

@@ -0,0 +1,41 @@
+## 1. 修正 model GORM comment 注释
+
+- [x] 1.1 修改 `internal/model/package.go`：PackageSeries.Status 和 Package.Status 的 comment 从 `1-启用 2-禁用` 改为 `0=禁用 1=启用`
+- [x] 1.2 修改 `internal/model/shop_package_allocation.go`：ShopPackageAllocation.Status 的 comment 从 `1-启用 2-禁用` 改为 `0=禁用 1=启用`
+- [x] 1.3 修改 `internal/model/shop_series_allocation.go`：ShopSeriesAllocation.Status 的 comment 从 `1-启用 2-禁用` 改为 `0=禁用 1=启用`
+- [x] 1.4 修改 `internal/model/system.go`：DevCapabilityConfig.Status 的 comment 从 `1-启用 2-禁用` 改为 `0=禁用 1=启用`
+- [x] 1.5 修改 `internal/model/financial.go`：PaymentMerchantSetting.Status 的 comment 从 `1-启用 2-禁用` 改为 `0=禁用 1=启用`
+- [x] 1.6 验证：`go vet ./internal/model/...` 无报错
+
+## 2. 删除僵尸常量
+
+- [x] 2.1 删除 `pkg/constants/iot.go` 中的 `DevCapabilityStatusEnabled = 1` 和 `DevCapabilityStatusDisabled = 2` 两行
+- [x] 2.2 验证：`go build ./...` 编译通过，证明无代码依赖这两个常量
+
+## 3. 修正 DTO validate 标签和 description（关键：修复 API 层约定冲突）
+
+> 当前 DTO 有 `validate:"oneof=1 2"` 但 service 层用 `StatusDisabled=0`，二者不兼容。
+> 修复方向：将 DTO 对齐到全局约定 `oneof=0 1`。
+
+- [x] 3.1 修改 `internal/model/dto/package_dto.go`：
+  - `UpdatePackageStatusRequest.Status` 的 validate 从 `oneof=1 2` 改为 `oneof=0 1`，description 从 `(1:启用, 2:禁用)` 改为 `(0:禁用, 1:启用)`
+  - `PackageListRequest.Status` 的 description 同步修正
+  - `PackageResponse.Status` 的 description 同步修正
+- [x] 3.2 修改 `internal/model/dto/package_series_dto.go`：
+  - `UpdatePackageSeriesStatusRequest.Status` 的 validate 从 `oneof=1 2` 改为 `oneof=0 1`，description 修正
+  - `PackageSeriesListRequest.Status` 的 description 修正
+  - `PackageSeriesResponse.Status` 的 description 修正
+- [x] 3.3 修改 `internal/model/dto/shop_series_grant_dto.go`：status 相关字段 description 全部修正为 `0=禁用 1=启用`
+- [x] 3.4 修改 `internal/model/dto/my_package.go`：status 相关字段 description 全部修正
+- [x] 3.5 验证：`go vet ./internal/model/dto/...` 无报错
+
+## 4. 修正 service 层语义混用
+
+- [x] 4.1 修改 `internal/service/shop_series_grant/service.go`：将所有 `ShelfStatus: constants.StatusEnabled` 改为 `ShelfStatus: constants.ShelfStatusOn`（两处，行约 342、676）
+- [x] 4.2 验证：`go vet ./internal/service/shop_series_grant/...` 无报错
+
+## 5. 最终验证
+
+- [x] 5.1 执行 `go build ./...` 确认全项目编译通过
+- [x] 5.2 执行 `go vet ./...` 无报错
+- [x] 5.3 执行 `go test ./internal/service/package/... ./internal/service/package_series/... ./internal/service/shop_series_grant/...` 确认测试通过