zlwuandCursor
6d56572f8b
Phased plan to align mini-program protocol payment editing with web SamplePaymentPanel while keeping admin actions closed. Co-authored-by: Cursor <cursoragent@cursor.com>
115 lines
5.2 KiB
Markdown
115 lines
5.2 KiB
Markdown
# 小程序协议单 · 缴费能力对齐 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 在协议单内扩展缴费编辑，不改变「缴费菜单不改应缴计划」）
|