junhong_cmp_fiber/openspec/changes/archive/2026-04-10-order-buyer-snapshot/tasks.md

1. 数据库迁移

• 1.1 新建迁移文件，ALTER TABLE tb_order 新增 buyer_phone VARCHAR(20) NULL、buyer_nickname VARCHAR(100) NULL，为 buyer_phone 建普通索引
• 1.2 同一迁移文件中 ALTER TABLE tb_order_item 新增 package_type VARCHAR(20) NULL
• 1.3 执行迁移，运行 migrate up 确认迁移成功，验证三列已存在于数据库
• 1.4 执行历史数据回填 SQL：UPDATE tb_order_item SET package_type = p.package_type FROM tb_package p WHERE oi.package_id = p.id AND oi.package_type IS NULL

2. Model 层

• 2.1 在 internal/model/order.go 的 Order struct 中新增 BuyerPhone、BuyerNickname 字段（gorm tag 含 column/type/comment）
• 2.2 在 internal/model/order.go 的 OrderItem struct 中新增 PackageType 字段（gorm tag 含 column/type/comment）
• 2.3 运行 lsp_diagnostics 确认 model 层无编译错误

3. DTO 层

• 3.1 在 internal/model/dto/order_dto.go 的 OrderListRequest 中新增 BuyerPhone string 字段（query tag + validate omitempty + description）
• 3.2 在 internal/model/dto/order_dto.go 的 OrderResponse 中新增 BuyerPhone、BuyerNickname string 字段（json tag + description）
• 3.3 在 internal/model/dto/order_dto.go 的 OrderItemResponse 中新增 PackageType string 字段（json tag + description）
• 3.4 运行 lsp_diagnostics 确认 DTO 层无编译错误

4. Store 层

• 4.1 在 internal/store/postgres/order_store.go 的 List 方法过滤逻辑中新增 buyer_phone 精确匹配条件（仿照 identifier 过滤写法）
• 4.2 运行 lsp_diagnostics 确认 Store 层无编译错误

5. C 端下单 Service 填充快照

• 5.1 在 internal/service/client_order/service.go 的 Service struct 和 New() 函数中注入 personalCustomerStore *postgres.PersonalCustomerStore、personalCustomerPhoneStore *postgres.PersonalCustomerPhoneStore
• 5.2 在 internal/service/client_order/service.go 中新增私有方法 fetchBuyerSnapshot(ctx, customerID uint) (phone, nickname string)，内部调用两个 Store，任一失败时记录 warn 日志并返回空字符串
• 5.3 在 buildPendingOrder 或其调用处调用 fetchBuyerSnapshot，将返回值赋给 Order.BuyerPhone、Order.BuyerNickname
• 5.4 在 buildOrderItems 中从 pkg.PackageType 读取值赋给 OrderItem.PackageType
• 5.5 更新 internal/bootstrap/services.go（或对应的初始化文件）中 client_order.New() 调用，传入新增的两个 Store 参数
• 5.6 运行 lsp_diagnostics 确认 C 端 Service 无编译错误

6. 后台下单 Service 填充快照

• 6.1 在 internal/service/order/service.go 的 Service struct 中确认或注入 personalCustomerStore、personalCustomerPhoneStore（若已有则跳过注入步骤）
• 6.2 在 orderBuyerType == BuyerTypePersonal 的个人客户场景分支（约 line 465 附近）调用 fetchBuyerSnapshot 逻辑，填充 Order.BuyerPhone、Order.BuyerNickname
• 6.3 在 buildOrderItems 中从 pkg.PackageType 读取值赋给 OrderItem.PackageType
• 6.4 运行 lsp_diagnostics 确认后台 Service 无编译错误

7. Handler / Service 响应映射

• 7.1 确认后台订单列表 Handler 已将 OrderListRequest.BuyerPhone 传入 filters map（key="buyer_phone"）
• 7.2 确认订单 DTO 映射函数（toOrderResponse 或类似函数）已将 Order.BuyerPhone、Order.BuyerNickname 映射到 OrderResponse
• 7.3 确认 OrderItem 映射函数已将 OrderItem.PackageType 映射到 OrderItemResponse.PackageType
• 7.4 运行 lsp_diagnostics 确认 Handler 层无编译错误

8. 验证

• 8.1 运行 go build ./... 确认整个项目编译通过
• 8.2 使用数据库工具查询 tb_order 确认新列存在，buyer_phone 索引已创建
• 8.3 使用数据库工具查询 tb_order_item 确认 package_type 列存在，历史数据回填记录数符合预期
• 8.4 调用 C 端下单接口创建一个新订单，查询 tb_order 验证 buyer_phone/buyer_nickname 已填充
• 8.5 调用后台订单列表接口，传入 buyer_phone 参数，验证返回结果正确过滤