54 lines
7.4 KiB
Markdown
54 lines
7.4 KiB
Markdown
## Why
|
||
|
||
`complete-july-iteration-test-release` 将七月迭代中的字段、筛选和局部缺陷扩大成模块迁移、通用平台和长依赖链，且遗漏或误解了多条 CSV 需求，已经不能作为可靠实施契约。feature-2026-july-confirmed-scope 依据已填写的需求范围确认表重新建立一个可直接上线的最小交付 Change：优先复用现有代码，完成用户可见需求，不借本期工作重构未触碰模块。
|
||
|
||
## What Changes
|
||
|
||
- 新 Change 完整替代 `complete-july-iteration-test-release` 的后续规划；旧 Change 在本 Change 校验通过前保留完成证据，之后归档为被替代，不继续执行其未完成任务。
|
||
- 实施遵循“存量能力优先”：优先修改或复用现有接口、字段、Service、Query、任务和基础设施；只有现有能力确实无法承载已确认需求时，才允许做边界最小、可说明必要性的新增。
|
||
- 本 Change 当前交付不编写或补齐测试代码，不运行单元、集成、验收或业务流程测试，也不执行 `go test`、常规 `go build`、LSP 诊断和实际迁移；只完成生产代码、必要迁移文件和契约文档至可联调状态，修改 API 契约后必须重新生成 OpenAPI 核对，可使用 `gofmt`、只读检查与 `git diff --check` 做静态收口。
|
||
- 将 #189、#181、#57 等缺陷和 #53、#44、#182 等字段/筛选需求收敛为旧 Service、Store 和现有 Query 上的局部修改，不进行 DDD 迁移；#181 的设备退款在创建时固化资产标识快照，列表和详情直接返回快照，不兼容历史空快照。
|
||
- 增加店铺级 C 端登录限制开关；仅阻止该店铺资产发起新登录，不建立代理 API 权限体系，也不强制吊销已登录 Token。
|
||
- 补齐三种实名顺序及卡/设备批量配置，保持既有 `realname_policy` 模型和前后端接口约定。
|
||
- 复用已有站内通知，完成换货单弹窗、固定 100 元钱包余额提醒、套餐 15/7/3 天临期列表和 C 端提醒，不建设通用营销平台。
|
||
- 复用已完成的渠道无关审批核心，交付最小企业微信 Adapter：管理员从通讯录为系统账号绑定 `(corp_id, userid)`，后台创建模板，本系统配置业务场景/模板/控件映射，完成发起、回调、详情查询和轮询补偿；不做扫码绑定、本地流程设计器或未来渠道抽象扩建。
|
||
- **BREAKING**：退款和员工线下代充值的人工审批结果改由企业微信终态驱动；新链路可用后停用原系统内人工通过/驳回入口。代理在线扫码充值后置。
|
||
- 交付单列 CSV 批量订购、六类业务导出、固定档位限速、按资产类型配置支付方式、CSV 批量分配设备等已确认功能，均复用现有导入、导出、Gateway、`system_config` 和任务基础设施；批量订购沿用现有后台认证和入口可见性，不新增“内部员工”账号类型限制；导出仅输出系统现有且有稳定来源的字段，不为原始清单中的缺失字段新增模型或迁移。
|
||
- 冻结已经完成的 #45、#46、#55、#60、#86、#38、#94、#96、#98、#43，仅做接口联调或代码证据核验；#43 前端可复用套餐列表的建议售价/公司成本价与授权详情的已授权套餐 ID 完成展示和区分，无需新增后端接口；冻结行业卡现有复机行为，不按旧提案改写。
|
||
- 明确排除原路退款、聚水潭、跨品类换货、分销佣金提现、代理在线扫码充值、通用营销/ERP、自动限速、本地审批流引擎、全局 Audit Event 专项，以及已关闭且不处理的需求。
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
|
||
- `shop-client-login-control`: 店铺级 C 端新登录开关及资产登录拦截。
|
||
- `wecom-approval-integration`: 企微应用、通讯录账号映射、模板场景绑定、审批发起、回调和轮询补偿。
|
||
- `package-expiration-reminder`: 套餐 15/7/3 天临期列表、站内通知和 C 端弹窗提醒。
|
||
- `asset-package-batch-order`: 单列 CSV、整批统一套餐和支付方式的批量订购。
|
||
- `business-data-export`: lot 卡、钱包流水、套餐、退款、换货和代理充值六类独立导出。
|
||
- `asset-speed-tier-management`: 后台为有权限 IoT 卡手动选择固定限速档位并调用 Gateway；不提供设备限速。
|
||
|
||
### Modified Capabilities
|
||
|
||
- `card-replacement`: 换货前拦截活跃退款，并修复换货套餐在原订单退款后未失效的问题。
|
||
- `exchange-client-notification`: 创建物流换货单后复用站内通知在 C 端弹窗。
|
||
- `order-management`: 修复 C 端订单渠道和订单资产标识返回，并支持从历史订单使用稳定资产/套餐引用发起新的下架套餐续费订单。
|
||
- `refund-api`: 新建退款固化并返回正确设备资产标识快照和提交人，不兼容历史空快照，并将退款审批结果切换为企微驱动。
|
||
- `agent-recharge`: 返回提交人，仅保留员工线下代充值并接入企微审批，代理在线扫码充值后置。
|
||
- `exchange-admin-management`: 换货列表和详情返回提交人。
|
||
- `asset-realname-policy`: 支持三种实名顺序、单资产修改、卡/设备批量修改和 C 端生效策略字段。
|
||
- `asset-queries`: 卡按自身实名状态筛选；设备任意一张有效绑定卡已实名即视为设备已实名。
|
||
- `agent-wallet`: 主钱包低于固定 100 元时向店铺业务员发送一次站内预警。
|
||
- `package-management`: 下架套餐从普通可购列表排除，但允许当前使用者通过续费入口购买。
|
||
- `payment-dynamic-config`: 通过 `system_config` 分别配置卡和设备允许的支付方式；两类资产初始化均全选钱包、微信和支付宝，三项可独立取消，C 端再按强充场景过滤钱包并由订单端复核。
|
||
- `device`: 复用现有导入任务模式，通过单列 CSV 批量分配设备所属代理或套餐系列。
|
||
|
||
## Impact
|
||
|
||
- **后端范围**：局部触及换货、订单、退款、充值、资产、店铺、套餐、钱包、设备导入、导出、通知和 Gateway；只有审批终态与资金处理保留现有 Application/Domain 边界，简单字段、筛选和 Bug 沿用 `Handler → Service → Store → Model` 或既有 Query。
|
||
- **API/前端**：新增店铺登录开关、企微账号选择/绑定、模板场景配置、实名批量配置、批量订购、导出、限速和设备批量分配接口；修改列表/详情字段、C 端初始化与支付方式返回。新增 Handler 必须同步 `cmd/api/docs.go`、`cmd/gendocs/main.go` 和 OpenAPI 文档。
|
||
- **数据与基础设施**：使用 PostgreSQL、Redis/Asynq、现有 Outbox、Integration Log、对象存储、站内通知和 `system_config`；不新增外键或 GORM 关联标签，不引入新依赖。
|
||
- **外部系统**：企业微信自建应用与 Gateway。企微上线需应用 Secret、审批权限、通讯录可见范围、可信 IP、回调 Token/EncodingAESKey 和模板 ID。
|
||
- **性能**：列表保持分页并批量解析提交人/审批人，禁止 N+1；批量实名上限 500 且事务全成全败；CSV/导出沿用异步任务，外部接口设置超时、幂等和补偿。
|
||
- **交付边界**：本 Change 以生产代码、迁移文件、接口契约、联调配置和实施证据齐备为完成标准；API 契约变更需重新生成 OpenAPI 核对。自动化测试、常规构建、LSP、实际迁移执行及真实企微/Gateway 环境验收不在本次执行范围，后续联调或发布流程另行承担。
|