docs: 新增 status-convention 主规范
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 7m20s

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

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
This commit is contained in:
2026-04-11 12:21:07 +08:00
parent 7e613a0d2b
commit 246ae5e123

View File

@@ -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`