32 lines
2.4 KiB
Markdown
32 lines
2.4 KiB
Markdown
## 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()` 会判定需要重新登录并跳转登录页，破坏免登录页。
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- 前端生成店铺编号可能撞号 → 采用时间戳 + 随机，后端唯一性校验兜底。
|
||
- 复用 `agent-recharges` 路径的 OCR 接口语义略有偏差 → 接口本身为通用凭证识别，后续若后端提供独立接口可平滑替换。
|
||
- 上传后自动识别会多一次网络请求 → 仅上传成功时触发一次，识别期间 loading 且禁止重复触发。
|
||
|
||
## Open Questions
|
||
|
||
- 无。
|