junhong_cmp_fiber/.planning/phases/01-p0/01-01-SUMMARY.md

phase, plan, subsystem, tags, dependency_graph, tech_stack, key_files, decisions, metrics

phase	plan	subsystem	tags	dependency_graph	tech_stack	key_files	decisions	metrics
01-p0	01	realname-status	bug-fix constants critical realname	requires provides affects CRITICAL-01 CRITICAL-02 polling_handler client_order scheduler iot_card_service asset_dto	added patterns constants-over-magic-numbers	created modified internal/task/polling_handler.go internal/model/iot_card.go internal/model/dto/asset_dto.go internal/polling/scheduler.go internal/service/iot_card/service.go internal/service/client_order/service.go internal/handler/app/client_realname.go	统一使用 constants.RealNameStatusVerified(=1) 替代所有硬编码 1、2 的实名状态判断 scheduler.go 中 0/1/2 三态判断简化为已实名/未实名两态（符合常量设计）	duration_minutes completed_date tasks_completed files_modified 15 2026-03-27 2 7

Phase 01 Plan 01: 统一实名状态常量 Summary

一句话总结： 将全链路 7 处硬编码实名状态值（包括错误的 return 2）统一改为 constants.RealNameStatusVerified(=1) / constants.RealNameStatusNotVerified(=0)，修复 CRITICAL-01 和 CRITICAL-02。

---

Objective Achieved

统一实名状态常量（CRITICAL-01），并修复 C 端实名校验（CRITICAL-02）。

实名链路三处不一致（轮询写入 2、常量定义 1、C 端校验 1）造成实名状态链路全面断裂，修复后全链路统一为 0=未实名、1=已实名。

---

Tasks Completed

Task	Name	Commit	Files
1	修复 polling_handler.go 实名状态写入值（CRITICAL-01）	1fd0072	polling_handler.go, iot_card.go, asset_dto.go, scheduler.go, iot_card/service.go
2	修复 C 端实名校验（CRITICAL-02）	da50a35	client_order/service.go, client_realname.go

---

Key Changes

Task 1 — CRITICAL-01 核心修复

① internal/task/polling_handler.go — parseRealnameStatus

// 修改前（错误：写入 2 到数据库）
func (h *PollingHandler) parseRealnameStatus(realStatus bool) int {
    if realStatus {
        return 2 // 已实名
    }
    return 0 // 未实名
}

// 修改后（正确：写入常量值 1）
func (h *PollingHandler) parseRealnameStatus(realStatus bool) int {
    if realStatus {
        return constants.RealNameStatusVerified // = 1，已实名
    }
    return constants.RealNameStatusNotVerified // = 0，未实名
}

② internal/task/polling_handler.go — isFirstRealname

// 修改前（错误：硬编码 == 2 判断）
isFirstRealname := (card.RealNameStatus == 0 || card.RealNameStatus == 1) && newRealnameStatus == 2

// 修改后（正确：使用常量比较，逻辑等价但语义清晰）
isFirstRealname := card.RealNameStatus != constants.RealNameStatusVerified &&
    newRealnameStatus == constants.RealNameStatusVerified

③ internal/model/iot_card.go — Model gorm comment

// 修改前
RealNameStatus int `gorm:"...comment:实名状态 0-未实名 1-已实名(行业卡可以保持0)" json:"real_name_status"`

// 修改后（统一注释，去除误导性括号说明）
RealNameStatus int `gorm:"...comment:实名状态 0-未实名 1-已实名" json:"real_name_status"`

④ internal/model/dto/asset_dto.go — DTO description

// 修改前（错误：包含 1实名中 2已实名 的旧三态描述）
RealNameStatus int `json:"real_name_status" description:"实名状态：0未实名 1实名中 2已实名"`

// 修改后（正确：两态）
RealNameStatus int `json:"real_name_status" description:"实名状态：0未实名 1已实名"`

⑤ internal/polling/scheduler.go — getCardCondition

// 修改前（错误：使用硬编码 0/1/2 三态判断）
if card.RealNameStatus == 0 || card.RealNameStatus == 1 {
    return "not_real_name"
}
if card.RealNameStatus == 2 {
    // ...
}

// 修改后（正确：两态常量判断）
if card.RealNameStatus != constants.RealNameStatusVerified {
    return "not_real_name"
}
if card.RealNameStatus == constants.RealNameStatusVerified {
    // ...
}

⑥ internal/service/iot_card/service.go — parseGatewayRealnameStatus

// 修改前（错误：返回硬编码 2）
// true=已实名(2)，false=未实名(0)
func parseGatewayRealnameStatus(realStatus bool) int {
    if realStatus { return 2 }
    return 0
}

// 修改后（正确：返回常量）
// true=已实名(1)，false=未实名(0)
func parseGatewayRealnameStatus(realStatus bool) int {
    if realStatus { return constants.RealNameStatusVerified }
    return constants.RealNameStatusNotVerified
}

---

Task 2 — CRITICAL-02 修复

① internal/service/client_order/service.go

// 修改前（硬编码 1，语义不清晰）
if packagesNeedRealname(validationResult.Packages) && assetInfo.RealNameStatus != 1 {

// 修改后（常量比较，语义明确）
if packagesNeedRealname(validationResult.Packages) && assetInfo.RealNameStatus != constants.RealNameStatusVerified {

② internal/handler/app/client_realname.go

// 修改前（硬编码 1）
if targetCard.RealNameStatus == 1 {

// 修改后（常量）
if targetCard.RealNameStatus == constants.RealNameStatusVerified {

---

Verification Results

✅ go build ./...      — 编译通过，无错误
✅ return 2 已消除     — polling_handler.go 中不再有 return 2
✅ 常量使用确认        — polling_handler.go 和 client_order/service.go 均使用 constants.RealNameStatusVerified
✅ 无遗漏硬编码        — rg 未发现 newRealnameStatus==2 / RealNameStatus==2 / RealNameStatus!=1

---

Deviations from Plan

Auto-fixed Issues

1. [Rule 2 - 缺失修复] 修复 asset_dto.go DTO description

• Found during: Task 1 全局搜索
• Issue: asset_dto.go 的 RealNameStatus description 仍含旧三态描述 1实名中 2已实名
• Fix: 更新为 0未实名 1已实名
• Files modified: internal/model/dto/asset_dto.go
• Commit: 1fd0072

2. [Rule 2 - 缺失修复] 修复 scheduler.go 硬编码三态判断

• Found during: Task 1 全局搜索
• Issue: scheduler.go:getCardCondition 使用 RealNameStatus == 0 || == 1 || == 2 硬编码
• Fix: 改为 != constants.RealNameStatusVerified / == constants.RealNameStatusVerified
• Files modified: internal/polling/scheduler.go
• Commit: 1fd0072

3. [Rule 2 - 缺失修复] 修复 iot_card/service.go 另一处 return 2

• Found during: Task 1 全局搜索
• Issue: parseGatewayRealnameStatus 函数也返回硬编码 2，与 polling_handler.go 同等问题
• Fix: 改为常量返回
• Files modified: internal/service/iot_card/service.go
• Commit: 1fd0072

4. [Rule 2 - 缺失修复] 修复 client_realname.go Handler 层硬编码

• Found during: Task 2 全局搜索
• Issue: client_realname.go:128 Handler 层 == 1 硬编码实名判断
• Fix: 改为 constants.RealNameStatusVerified
• Files modified: internal/handler/app/client_realname.go
• Commit: da50a35

---

Requirements Completed

• ✅ CRITICAL-01: 实名状态常量统一（DB 写入值 2 vs 常量 1，所有链路断裂）— 已修复
• ✅ CRITICAL-02: C 端实名校验修复（依赖 CRITICAL-01）— 已修复

---

Self-Check: PASSED

• ✅ internal/task/polling_handler.go — 已修改并提交
• ✅ internal/model/iot_card.go — 已修改并提交
• ✅ internal/service/client_order/service.go — 已修改并提交
• ✅ commit 1fd0072 — 存在（Task 1）
• ✅ commit da50a35 — 存在（Task 2）