## 1. 常量与错误码

- [x] 1.1 在 `pkg/constants/constants.go` 增加 `auto_purchase_status` 状态常量（pending/success/failed）
- [x] 1.2 在 `pkg/errors/codes.go` 增加 `NEED_REALNAME` 与 `OPENID_NOT_FOUND` 错误码并补充中文消息
- [x] 1.3 在 `pkg/constants/redis.go` 增加客户端购买幂等键与锁键生成函数

## 2. DTO 定义

- [x] 2.1 新增资产模块 DTO：B1/B2/B3/B4 请求与响应结构（含 description/validate 标签）
- [x] 2.2 新增钱包充值模块 DTO：C1~C5 请求与响应结构（含支付返回 `pay_config`）
- [x] 2.3 新增订单模块 DTO：D1~D3 请求与响应结构（含 `order_type` 分流结构）
- [x] 2.4 新增实名与设备模块 DTO：E1、F1~F5 请求与响应结构

## 3. 模型变更与迁移

- [x] 3.1 在 `internal/model/asset_recharge_record.go` 增加 `auto_purchase_status` 字段与中文注释
- [x] 3.2 创建迁移文件为 `tb_asset_recharge_record` 添加 `auto_purchase_status` 字段（up/down）
- [x] 3.3 执行迁移并确认版本状态正常（非 dirty）

## 4. 资产信息模块（B1~B4）

- [x] 4.1 新建 `internal/handler/app/client_asset.go` 并实现 B1~B4 路由处理
- [x] 4.2 抽取公共方法 `resolveAssetFromIdentifier`（解析标识符 + 归属校验 + 权限绕过上下文）
- [x] 4.3 实现 B2 渠道价格计算、加油包前置校验、上下架过滤与价格升序
- [x] 4.4 实现 B4 刷新分流：卡走 Gateway、设备走 Redis 冷却 + 批量刷新

## 5. 钱包与充值模块（C1~C5）

- [x] 5.1 新建 `internal/handler/app/client_wallet.go` 并实现 C1~C5 路由处理
- [x] 5.2 实现 C1 钱包不存在自动创建逻辑与 C2 wallet_id 隔离查询
- [x] 5.3 复用并接入 C3 强充预检返回结构
- [x] 5.4 实现 C4 创建充值订单：根据 `app_type` 查 PersonalCustomerOpenID 获取 openid → 根据 `app_type` 选择 AppID（`official_account` 用 `oa_app_id`，`miniapp` 用 `miniapp_app_id`）→ 调用提案 1 新增的 `wechat.NewPaymentAppFromConfig(config, appID)` 创建支付实例 → 调用现有 `PaymentService.CreateJSAPIOrder(orderNo, desc, openID, amount)` 拉起支付 → 设置 `operator_type=personal_customer`、写入 `generation` 快照
- [x] 5.5 实现 C5 充值记录 generation 过滤查询

## 6. 套餐购买模块（D1~D3）

- [x] 6.1 新建 `internal/handler/app/client_order.go` 并实现 D1~D3 路由处理
- [x] 6.2 新建 `internal/service/client_order/service.go` 编排 D1 全流程（归属/套餐/实名/OpenID/幂等/强充分流）。支付调用链：根据 `app_type` 选择 AppID → `wechat.NewPaymentAppFromConfig(config, appID)` → `PaymentService.CreateJSAPIOrder()` → 返回 `pay_config` 给前端。**客户端一律走 JSAPI 支付（微信内环境），不使用 H5 支付**
- [x] 6.3 实现强充两阶段：同步入账 + 异步自动购买（Asynq 入队）。注意第二阶段自动购买创建的订单使用 `payment_method=wallet`（钱包扣款），不涉及微信支付
- [x] 6.4 新增 `AutoPurchaseAfterRecharge` 任务处理器（钱包扣款→创建订单→激活套餐，失败重试 3 次）
- [x] 6.5 实现 D1 `order_type` 双结构返回（package/recharge）
- [x] 6.6 实现 D2/D3 generation 与归属校验约束

## 7. 实名跳转（E1）

- [x] 7.1 新建 `internal/handler/app/client_realname.go` 并实现 E1 接口
- [x] 7.2 实现目标卡定位三路径（直接卡/设备+iccid/设备活跃卡）
- [x] 7.3 实现实名模式三分支（none/template/gateway）与模板占位符替换

## 8. 设备能力（F1~F5）

- [x] 8.1 新建 `internal/handler/app/client_device.go` 并实现 F1~F5 路由处理
- [x] 8.2 实现通用前置校验（必须设备类型且 IMEI 非空）
- [x] 8.3 对接 Gateway：`RebootDevice`、`ResetDevice`、`SetWiFi`、`SwitchCard`
- [x] 8.4 实现 F4 特殊映射：`WiFiReq.cardNo = 设备IMEI`

## 9. 路由注册与文档

- [x] 9.1 在 `internal/bootstrap/types.go` 增加客户端业务 Handler 字段
- [x] 9.2 在 `internal/bootstrap/handlers.go` 完成客户端业务 Handler 实例化
- [x] 9.3 在 `internal/routes/personal.go` 注册 `/api/c/v1/` 18 个端点（使用 `Register()`）
- [x] 9.4 在 `cmd/api/docs.go` 注册新增 Handler 供文档生成器使用
- [x] 9.5 在 `cmd/gendocs/main.go` 注册新增 Handler 并生成 OpenAPI 文档

## 10. 验证

- [x] 10.1 运行 `go build ./...` 确认构建通过
- [x] 10.2 运行 LSP diagnostics，确保改动文件无错误
- [x] 10.3 使用数据库验证流程确认 `auto_purchase_status` 字段已生效
- [x] 10.4 补充 `docs/client-core-business-api/功能总结.md` 并更新相关索引文档
