diff --git a/docs/superpowers/specs/2026-10-13-mobile-protocol-payment-parity-design.md b/docs/superpowers/specs/2026-10-13-mobile-protocol-payment-parity-design.md new file mode 100644 index 00000000..0578bd97 --- /dev/null +++ b/docs/superpowers/specs/2026-10-13-mobile-protocol-payment-parity-design.md @@ -0,0 +1,114 @@ +# 小程序协议单 · 缴费能力对齐 web(P1) + +**日期:** 2026-10-13 +**状态:** 已确认设计,待写实现计划 +**分支:** 当前工作分支(与 web 尾期自动算同一迭代线) + +## 1. 背景与产品原则 + +- 小程序(`mobile-oa-h5` 承载的市场【协议单】)业务能力须与 web-admin 对齐。 +- **信息元素**对齐 web;**展示方式**采用移动端(卡片、分区、Vant 控件、底部栏),不复刻 PC 弹窗宽表。 +- 本文件为 **方案 1 分阶段交付的 P1**:以缴费闭环为第一刀。 +- 管理动作(审核、作废、退款、财务确认)**仍不开放**给市场移动端。 + +### 阶段规划 + +| 阶段 | 内容 | +|------|------| +| **P1(本文)** | 细胞存储协议新建/编辑可配按样本缴费;模式切换并期;尾期自动算;趸交截止日同步;读写落库;详情按样本展示缴费 | +| **P2** | 对照 `ProtocolFormDialog` 补齐其它业务字段、联动与校验 | +| **P3** | 列表/详情信息元素全面对齐 | + +## 2. 已确认决策 + +| 项 | 决策 | +|----|------| +| 对齐范围 | 新建/编辑/详情/列表的业务字段与缴费能力;审核等管理动作不开放 | +| 缴费深度 | 完整对齐 web `SamplePaymentPanel`(趸交/分期/分改趸 + 模式切换确认与并期/拆期) | +| 自动计算 | 与 `2026-10-13-protocol-payment-last-period-autofill-design.md` 相同 | +| 科研捐赠 | 本阶段不配缴费(与 web 细胞存储缴费一致) | +| 缴费独立菜单 | 不开放「修改应缴计划」;计划仍在协议单内编辑 | + +## 3. P1 目标 + +小程序【协议单】`source=cell_storage`: + +1. 新建、编辑可配置并保存按样本缴费方案(`paymentModelVersion=2`)。 +2. 信息元素与 web 一致(见 §4)。 +3. 交互与布局为移动端形态(见 §5)。 +4. 详情可按样本只读展示缴费方案与各期。 + +## 4. 信息元素(对齐 web) + +每个有效样本一张缴费方案: + +| 元素 | 说明 | +|------|------| +| 缴费模式 | `dj` 趸交 / `fq` 分期 / `fgd` 分改趸;可选集合与切换规则同 web | +| 样本合同金额 | 可手改;优惠价联动策略对齐 web | +| 趸交截止时间 | 仅趸交;有值/清空时同步最后一期应缴费时间(锁定跳过) | +| 分期期数 / 间隔 / 开始日 / 提前催缴天数 | 分期、分改趸 | +| 各期应缴费金额、应缴费时间 | 可编辑;存在 `yjf` 转账的期次锁定 | +| 分期尾期金额 | 前 N−1 期变更时自动 = 合同 − Σ前 N−1;尾期可手改覆盖,前几期再变后重算 | +| 模式切换 | 确认弹窗 + 并期/拆期,规则对齐 web `SamplePaymentPanel` | + +## 5. 移动端展示 + +- 样本缴费:卡片列表(每样本一卡),期次为卡内子列表/折叠项。 +- 确认:`van-dialog`;日期/金额:Vant 字段。 +- 挂载点:协议 `MarketModuleForm` 在样本区之后渲染专用面板(不沿用当前只读三字段)。 +- 新建亦可配置缴费(去掉 `editOnly` + `readOnly` 限制)。 + +## 6. 前端结构 + +| 项 | 说明 | +|----|------| +| 组件 | `mobile-oa-h5/src/market/components/ProtocolSamplePaymentPanel.vue` | +| 逻辑 | `mobile-oa-h5/src/market/protocol-sample-payment.js` — 复用/移植 web 纯函数(尾期计算、截止日同步、并期拆期、校验 hint、可选模式) | +| 状态 | `formData.samplePayments[]` 与 `samples[]` 按 `sampleCode` 同步 | +| 保存 | payload 含 `samplePayments`;协议总金额与样本合同合计弱提示同 web | +| 回填 | 详情 `samplePayments`;无方案时按样本生成默认趸交草稿 | + +## 7. 后端契约 + +### 7.1 写 + +- `MarketProtocolBody` 增加可选 `samplePayments`(camelCase,结构对齐 web 保存体)。 +- 仅 `cell_storage` 持久化;科研捐赠不得写入缴费方案。 +- create/update 在样本保存后调用 `save_sample_payments_for_protocol`。 +- 新建默认 `paymentModelVersion=2`。 +- 校验口径与 web 一致;失败返回明确业务错误。 +- 继续 `extra=forbid`:拒绝审核/作废/退款/财务状态字段。 + +### 7.2 读 + +- `_cell_detail` 返回 `samplePayments`(及 `paymentModelVersion`)。 +- 可保留旧 `payment` 兼容;前端以 `samplePayments` 为准。 + +## 8. 测试与验收 + +**自动化** + +- 前端:纯函数与 payload 组装 Node 单测。 +- 后端:create/update 携带 `samplePayments` 的 API 测。 + +**手工** + +1. 新建:样本 + 分期/趸交/分改趸 → 保存 → 详情可见各期。 +2. 编辑:前几期金额变化 → 尾期自动补齐;手改尾期不被立刻覆盖。 +3. 趸交:截止时间填/清 → 应缴费时间同步。 +4. 分期→分改趸:确认并并期;锁定期不可改应缴。 +5. 移动端仍无审核/作废入口。 + +## 9. 非目标(P1) + +- P2/P3 全量字段与列表对齐 +- 科研捐赠缴费 +- 缴费独立菜单改应缴计划 +- 嵌入 web-admin 页面 +- 开放审核/作废/退款/财务确认 + +## 10. 相关文档 + +- `docs/superpowers/specs/2026-10-13-protocol-payment-last-period-autofill-design.md`(web 自动算规则,移动端同规则) +- `docs/superpowers/specs/2026-10-10-market-miniapp-role-features-implementation-summary.md`(移动角色边界;P1 在协议单内扩展缴费编辑,不改变「缴费菜单不改应缴计划」)