2.4 KiB
2.4 KiB
Context
- 仓库当前没有归档的
openspec/specs/，既有变更统一使用## ADDED Requirements的 delta，本次沿用。 - OCR 能力由
POST /api/admin/agent-recharges/payment-voucher-ocr提供，语义为「凭证图片对象键 →external_transaction_no预填」，员工代收款核销申请直接复用，不新增后端接口。 - 注册接口
POST /api/c/v1/agent-distribution-registrations契约中的shop_code仍为必填，改为前端生成后提交。
Goals / Non-Goals
- Goals: 注册者自主填写店铺信息、店铺编号自动生成、用户名长度校验、免登录页不被存储检查登出、H5 可滚动；两处付款凭证支持上传后自动识别并保留手动识别。
- Non-Goals: 不新增或修改后端接口契约；不做店铺编号前端唯一性保证（由后端唯一性校验兜底）；不改变 OCR 结果只预填交易流水号的约束。
Decisions
- Decision: 店铺编号生成规则为
S+yyyyMMddHHmmss+ 3 位随机数，长度不超过后端字段上限（50）。- Rationale: 时间戳 + 随机数在客户端生成后碰撞概率低，且保持可读性；唯一性最终由后端校验。
- Decision: 核销申请复用代理充值的 OCR 接口
POST /api/admin/agent-recharges/payment-voucher-ocr。- Rationale: 该接口本质是通用凭证识别，仅返回交易流水号；避免为同一能力重复定义接口。
- Decision: 自动识别以「凭证上传成功」为触发点，取首个已上传凭证对象键，并用
ocrLoading防重复触发；手动按钮逻辑不变。- Rationale: 首个凭证即用户主凭证，与手动识别取键规则一致，避免自动/手动结果不一致。
- Decision: 存储兼容性检查在免登录路由上直接跳过，不执行登出。
- Rationale: 全新浏览器无任何本地存储时，
validateStorageData()会判定需要重新登录并跳转登录页，破坏免登录页。
- Rationale: 全新浏览器无任何本地存储时，
Risks / Trade-offs
- 前端生成店铺编号可能撞号 → 采用时间戳 + 随机，后端唯一性校验兜底。
- 复用
agent-recharges路径的 OCR 接口语义略有偏差 → 接口本身为通用凭证识别，后续若后端提供独立接口可平滑替换。 - 上传后自动识别会多一次网络请求 → 仅上传成功时触发一次，识别期间 loading 且禁止重复触发。
Open Questions
- 无。