فهرست منبع

docs: design payment list card period collapse for mobile market H5

Spec and interactive demo for collapsing payment installments on list cards (summary row + expand details).

Co-authored-by: Cursor <cursoragent@cursor.com>
zlwu 2 هفته پیش
والد
کامیت
42dde4b0bc

+ 564 - 0
docs/demos/2026-10-14-payment-card-period-collapse-demo.html

@@ -0,0 +1,564 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1" />
+  <title>缴费信息 · 列表卡片期数折叠 Demo</title>
+  <style>
+    :root {
+      --primary: #0a9f6d;
+      --primary-dark: #087f57;
+      --primary-soft: #e9f9f2;
+      --text: #18332a;
+      --muted: #6b7c74;
+      --border: #dce8e2;
+      --surface: #fff;
+      --page: #f3f6f5;
+      --money: #c98312;
+    }
+
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      font-family: -apple-system, BlinkMacSystemFont, "PingFang SC", "Helvetica Neue", sans-serif;
+      font-size: 14px;
+      line-height: 1.5;
+      color: var(--text);
+      background: var(--page);
+    }
+
+    .page {
+      max-width: 420px;
+      margin: 0 auto;
+      padding: 20px 14px 48px;
+    }
+
+    .hero { margin-bottom: 18px; }
+    .hero h1 {
+      margin: 0 0 6px;
+      font-size: 20px;
+      font-weight: 700;
+    }
+    .hero p {
+      margin: 0;
+      color: var(--muted);
+      font-size: 13px;
+    }
+
+    .section-label {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      margin: 18px 0 8px;
+      color: var(--muted);
+      font-size: 12px;
+      font-weight: 600;
+    }
+    .section-label em {
+      font-style: normal;
+      color: var(--primary-dark);
+      background: var(--primary-soft);
+      padding: 2px 8px;
+      border-radius: 999px;
+    }
+    .section-label .bad {
+      color: #b45309;
+      background: #fff7e8;
+    }
+
+    .card {
+      padding: 14px;
+      border: 1px solid var(--border);
+      border-radius: 16px;
+      background: var(--surface);
+      box-shadow: 0 6px 20px rgb(8 127 87 / 7%);
+    }
+    .card + .card { margin-top: 12px; }
+
+    .head {
+      display: flex;
+      align-items: center;
+      gap: 10px;
+      padding-bottom: 12px;
+      border-bottom: 1px solid #eef4f1;
+    }
+    .index {
+      display: grid;
+      width: 30px;
+      height: 30px;
+      flex: 0 0 30px;
+      place-items: center;
+      border-radius: 50%;
+      background: var(--primary-soft);
+      color: var(--primary-dark);
+      font-size: 13px;
+      font-weight: 700;
+    }
+    .identity {
+      min-width: 0;
+      flex: 1;
+      display: flex;
+      flex-direction: column;
+      gap: 3px;
+    }
+    .title {
+      overflow: hidden;
+      font-size: 16px;
+      font-weight: 700;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    }
+    .subtitle {
+      overflow: hidden;
+      color: var(--muted);
+      font-size: 12px;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    }
+    .tag {
+      display: inline-flex;
+      max-width: 128px;
+      align-self: center;
+      padding: 5px 12px;
+      overflow: hidden;
+      border-radius: 999px;
+      background: #fff7e8;
+      color: #b45309;
+      font-size: 12px;
+      line-height: 1.3;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    }
+    .tag.ok {
+      background: var(--primary-soft);
+      color: var(--primary-dark);
+    }
+    .tag.mode {
+      background: #eef2ff;
+      color: #4338ca;
+    }
+
+    .fields {
+      display: grid;
+      grid-template-columns: repeat(2, minmax(0, 1fr));
+      gap: 12px 16px;
+      padding: 14px 0;
+    }
+    .field {
+      display: flex;
+      min-width: 0;
+      flex-direction: column;
+      gap: 4px;
+      color: var(--muted);
+      font-size: 12px;
+    }
+    .field.wide { grid-column: 1 / -1; }
+    .field b {
+      color: var(--text);
+      font-weight: 500;
+      overflow-wrap: anywhere;
+    }
+    .field b.money {
+      color: var(--money);
+      font-size: 15px;
+      font-weight: 700;
+    }
+
+    /* —— 期数折叠区 —— */
+    .periods {
+      margin: 0 0 12px;
+      border: 1px solid #eef4f1;
+      border-radius: 12px;
+      background: #fafcfb;
+      overflow: hidden;
+    }
+    .period {
+      border-top: 1px solid #eef4f1;
+    }
+    .period:first-child { border-top: 0; }
+
+    .period__toggle {
+      display: grid;
+      width: 100%;
+      min-height: 48px;
+      grid-template-columns: 64px 1fr 1fr 20px;
+      align-items: center;
+      gap: 8px;
+      padding: 10px 12px;
+      border: 0;
+      background: transparent;
+      color: var(--text);
+      font: inherit;
+      text-align: left;
+      cursor: pointer;
+    }
+    .period__toggle:active { background: #f0f7f3; }
+
+    .period__no {
+      font-size: 13px;
+      font-weight: 700;
+      color: var(--primary-dark);
+    }
+    .period__col {
+      min-width: 0;
+      display: flex;
+      flex-direction: column;
+      gap: 2px;
+    }
+    .period__col span {
+      color: var(--muted);
+      font-size: 11px;
+    }
+    .period__col b {
+      color: var(--money);
+      font-size: 13px;
+      font-weight: 700;
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    }
+    .period__chevron {
+      color: var(--muted);
+      font-size: 12px;
+      text-align: center;
+      transition: transform 0.2s ease;
+    }
+    .period.is-open .period__chevron {
+      transform: rotate(180deg);
+    }
+
+    .period__body {
+      display: none;
+      padding: 0 12px 12px;
+      border-top: 1px dashed #eef4f1;
+    }
+    .period.is-open .period__body { display: block; }
+    .period__body .fields {
+      padding: 10px 0 0;
+      gap: 10px 12px;
+    }
+
+    .actions {
+      display: flex;
+      flex-wrap: wrap;
+      justify-content: flex-end;
+      gap: 8px;
+      padding-top: 12px;
+      border-top: 1px solid #eef4f1;
+    }
+    .btn {
+      min-width: 76px;
+      min-height: 44px;
+      padding: 0 14px;
+      border-radius: 9px;
+      border: 1px solid var(--border);
+      background: #fff;
+      color: var(--text);
+      font-size: 13px;
+      cursor: pointer;
+    }
+    .btn.primary {
+      border-color: var(--primary);
+      background: var(--primary);
+      color: #fff;
+    }
+
+    .hint {
+      margin-top: 16px;
+      padding: 12px 14px;
+      border-radius: 12px;
+      background: #fff;
+      border: 1px dashed var(--border);
+      color: var(--muted);
+      font-size: 12px;
+    }
+    .hint strong { color: var(--text); }
+    .hint code {
+      display: inline-block;
+      margin-top: 4px;
+      font-size: 11px;
+      word-break: break-all;
+    }
+
+    .before-note {
+      margin: 0 0 10px;
+      color: #b45309;
+      font-size: 12px;
+    }
+  </style>
+</head>
+<body>
+  <div class="page">
+    <header class="hero">
+      <h1>缴费信息 · 期数折叠</h1>
+      <p>列表卡片按期折叠:默认只显示「第几期 / 应缴 / 已缴」,点击展开明细。</p>
+    </header>
+
+    <!-- ========== 改后(推荐) ========== -->
+    <div class="section-label">
+      <span>改后(默认折叠)</span>
+      <em>推荐</em>
+    </div>
+
+    <article class="card">
+      <header class="head">
+        <span class="index">1</span>
+        <span class="identity">
+          <strong class="title">周雨桐</strong>
+          <small class="subtitle">S-10021</small>
+        </span>
+        <span class="tag">部分已缴</span>
+      </header>
+
+      <div class="fields">
+        <div class="field wide"><span>协议号</span><b>XY20261008012</b></div>
+        <div class="field"><span>姓名</span><b>周雨桐</b></div>
+        <div class="field"><span>手机号</span><b>138****6621</b></div>
+        <div class="field wide"><span>样本编码</span><b>S-10021</b></div>
+        <div class="field"><span>签署日期</span><b>2026-10-01</b></div>
+        <div class="field"><span>存储年限</span><b>20</b></div>
+        <div class="field wide"><span>存储项目</span><b>脐带血</b></div>
+        <div class="field"><span>合同总额</span><b class="money">¥10,000.00</b></div>
+        <div class="field"><span>缴费方式</span><span class="tag mode">分期</span></div>
+        <div class="field"><span>优惠金额</span><b class="money">¥1,000.00</b></div>
+        <div class="field"><span>应收总额</span><b class="money">¥9,000.00</b></div>
+      </div>
+
+      <div class="periods" data-periods>
+        <!-- 第1期 -->
+        <div class="period" data-period>
+          <button type="button" class="period__toggle" aria-expanded="false">
+            <span class="period__no">第1期</span>
+            <span class="period__col">
+              <span>应缴费金额</span>
+              <b>¥3,000.00</b>
+            </span>
+            <span class="period__col">
+              <span>已缴费金额</span>
+              <b>¥3,000.00</b>
+            </span>
+            <span class="period__chevron">▾</span>
+          </button>
+          <div class="period__body">
+            <div class="fields">
+              <div class="field"><span>应缴费时间</span><b>2026-10-10</b></div>
+              <div class="field"><span>已缴费时间</span><b>2026-10-11</b></div>
+              <div class="field wide"><span>欠缴费金额</span><b class="money">¥0.00</b></div>
+            </div>
+          </div>
+        </div>
+
+        <!-- 第2期 -->
+        <div class="period" data-period>
+          <button type="button" class="period__toggle" aria-expanded="false">
+            <span class="period__no">第2期</span>
+            <span class="period__col">
+              <span>应缴费金额</span>
+              <b>¥2,000.00</b>
+            </span>
+            <span class="period__col">
+              <span>已缴费金额</span>
+              <b>¥0.00</b>
+            </span>
+            <span class="period__chevron">▾</span>
+          </button>
+          <div class="period__body">
+            <div class="fields">
+              <div class="field"><span>应缴费时间</span><b>2027-04-10</b></div>
+              <div class="field"><span>已缴费时间</span><b>—</b></div>
+              <div class="field wide"><span>欠缴费金额</span><b class="money">¥2,000.00</b></div>
+            </div>
+          </div>
+        </div>
+
+        <!-- 第3期 -->
+        <div class="period" data-period>
+          <button type="button" class="period__toggle" aria-expanded="false">
+            <span class="period__no">第3期</span>
+            <span class="period__col">
+              <span>应缴费金额</span>
+              <b>¥2,000.00</b>
+            </span>
+            <span class="period__col">
+              <span>已缴费金额</span>
+              <b>¥0.00</b>
+            </span>
+            <span class="period__chevron">▾</span>
+          </button>
+          <div class="period__body">
+            <div class="fields">
+              <div class="field"><span>应缴费时间</span><b>2027-10-10</b></div>
+              <div class="field"><span>已缴费时间</span><b>—</b></div>
+              <div class="field wide"><span>欠缴费金额</span><b class="money">¥2,000.00</b></div>
+            </div>
+          </div>
+        </div>
+
+        <!-- 第4期 -->
+        <div class="period" data-period>
+          <button type="button" class="period__toggle" aria-expanded="false">
+            <span class="period__no">第4期</span>
+            <span class="period__col">
+              <span>应缴费金额</span>
+              <b>¥2,000.00</b>
+            </span>
+            <span class="period__col">
+              <span>已缴费金额</span>
+              <b>¥0.00</b>
+            </span>
+            <span class="period__chevron">▾</span>
+          </button>
+          <div class="period__body">
+            <div class="fields">
+              <div class="field"><span>应缴费时间</span><b>2028-04-10</b></div>
+              <div class="field"><span>已缴费时间</span><b>—</b></div>
+              <div class="field wide"><span>欠缴费金额</span><b class="money">¥2,000.00</b></div>
+            </div>
+          </div>
+        </div>
+
+      </div>
+
+      <div class="fields" style="padding-top: 0;">
+        <div class="field"><span>累计实缴</span><b class="money">¥3,000.00</b></div>
+        <div class="field"><span>待缴金额</span><b class="money">¥6,000.00</b></div>
+        <div class="field wide"><span>备注</span><b>首期已缴</b></div>
+      </div>
+
+      <footer class="actions">
+        <button type="button" class="btn">查看协议</button>
+        <button type="button" class="btn primary">缴费明细</button>
+      </footer>
+    </article>
+
+    <!-- ========== 展开态示意 ========== -->
+    <div class="section-label">
+      <span>展开态示意(第1、2期已展开)</span>
+      <em>可点击切换</em>
+    </div>
+
+    <article class="card">
+      <header class="head">
+        <span class="index">2</span>
+        <span class="identity">
+          <strong class="title">李婷</strong>
+          <small class="subtitle">S-10022</small>
+        </span>
+        <span class="tag ok">已缴清</span>
+      </header>
+
+      <div class="fields">
+        <div class="field wide"><span>协议号</span><b>XY20261008018</b></div>
+        <div class="field"><span>合同总额</span><b class="money">¥6,000.00</b></div>
+        <div class="field"><span>缴费方式</span><span class="tag mode">分期</span></div>
+      </div>
+
+      <div class="periods" data-periods>
+        <div class="period is-open" data-period>
+          <button type="button" class="period__toggle" aria-expanded="true">
+            <span class="period__no">第1期</span>
+            <span class="period__col">
+              <span>应缴费金额</span>
+              <b>¥3,000.00</b>
+            </span>
+            <span class="period__col">
+              <span>已缴费金额</span>
+              <b>¥3,000.00</b>
+            </span>
+            <span class="period__chevron">▾</span>
+          </button>
+          <div class="period__body">
+            <div class="fields">
+              <div class="field"><span>应缴费时间</span><b>2026-09-01</b></div>
+              <div class="field"><span>已缴费时间</span><b>2026-09-02</b></div>
+              <div class="field wide"><span>欠缴费金额</span><b class="money">¥0.00</b></div>
+            </div>
+          </div>
+        </div>
+        <div class="period is-open" data-period>
+          <button type="button" class="period__toggle" aria-expanded="true">
+            <span class="period__no">第2期</span>
+            <span class="period__col">
+              <span>应缴费金额</span>
+              <b>¥3,000.00</b>
+            </span>
+            <span class="period__col">
+              <span>已缴费金额</span>
+              <b>¥3,000.00</b>
+            </span>
+            <span class="period__chevron">▾</span>
+          </button>
+          <div class="period__body">
+            <div class="fields">
+              <div class="field"><span>应缴费时间</span><b>2027-03-01</b></div>
+              <div class="field"><span>已缴费时间</span><b>2027-03-01</b></div>
+              <div class="field wide"><span>欠缴费金额</span><b class="money">¥0.00</b></div>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <footer class="actions">
+        <button type="button" class="btn">查看协议</button>
+        <button type="button" class="btn primary">缴费明细</button>
+      </footer>
+    </article>
+
+    <!-- ========== 改前对比 ========== -->
+    <div class="section-label">
+      <span>改前(全部平铺)</span>
+      <em class="bad">卡片过高</em>
+    </div>
+    <p class="before-note">当前实现:固定 6 期 × 5 个字段 = 约 30 行期次字段,列表扫读困难。</p>
+
+    <article class="card">
+      <header class="head">
+        <span class="index">3</span>
+        <span class="identity">
+          <strong class="title">周雨桐</strong>
+          <small class="subtitle">S-10021</small>
+        </span>
+        <span class="tag">部分已缴</span>
+      </header>
+      <div class="fields">
+        <div class="field wide"><span>协议号</span><b>XY20261008012</b></div>
+        <div class="field"><span>合同总额</span><b class="money">¥10,000.00</b></div>
+        <div class="field"><span>缴费方式</span><span class="tag mode">分期</span></div>
+        <div class="field"><span>第1期·应缴费金额(元)</span><b class="money">¥3,000.00</b></div>
+        <div class="field"><span>第1期·应缴费时间</span><b>2026-10-10</b></div>
+        <div class="field"><span>第1期·已缴费金额</span><b class="money">¥3,000.00</b></div>
+        <div class="field"><span>第1期·已缴费时间</span><b>2026-10-11</b></div>
+        <div class="field wide"><span>第1期·欠缴费金额</span><b class="money">¥0.00</b></div>
+        <div class="field"><span>第2期·应缴费金额(元)</span><b class="money">¥2,000.00</b></div>
+        <div class="field"><span>第2期·应缴费时间</span><b>2027-04-10</b></div>
+        <div class="field"><span>第2期·已缴费金额</span><b class="money">¥0.00</b></div>
+        <div class="field"><span>第2期·已缴费时间</span><b>—</b></div>
+        <div class="field wide"><span>第2期·欠缴费金额</span><b class="money">¥2,000.00</b></div>
+        <div class="field wide"><span>…第3~6期同样平铺…</span><b>卡片继续变高</b></div>
+        <div class="field"><span>累计实缴</span><b class="money">¥3,000.00</b></div>
+        <div class="field"><span>待缴金额</span><b class="money">¥6,000.00</b></div>
+      </div>
+      <footer class="actions">
+        <button type="button" class="btn">查看协议</button>
+        <button type="button" class="btn primary">缴费明细</button>
+      </footer>
+    </article>
+
+    <div class="hint">
+      <strong>交互说明:</strong>只渲染有数据的期次;每期独立一行摘要(第N期 · 应缴 · 已缴),默认折叠;点击展开应缴时间 / 已缴时间 / 欠缴金额;多期可同时展开。
+      <br />
+      <code>docs/demos/2026-10-14-payment-card-period-collapse-demo.html</code>
+    </div>
+  </div>
+
+  <script>
+    document.querySelectorAll('[data-period]').forEach((row) => {
+      const btn = row.querySelector('.period__toggle')
+      btn.addEventListener('click', () => {
+        const open = row.classList.toggle('is-open')
+        btn.setAttribute('aria-expanded', open ? 'true' : 'false')
+      })
+    })
+  </script>
+</body>
+</html>

+ 106 - 0
docs/superpowers/specs/2026-10-14-payment-card-period-collapse-design.md

@@ -0,0 +1,106 @@
+# 缴费信息列表卡片 · 期数折叠
+
+**日期:** 2026-10-14  
+**状态:** 已确认设计,待写实现计划  
+**Demo:** `docs/demos/2026-10-14-payment-card-period-collapse-demo.html`
+
+## 1. 背景
+
+市场专员 / 地区经理在 `mobile-oa-h5`【缴费信息】列表中,单张卡片会把最多 6 期 × 5 个字段全部平铺进 `fields`,卡片过高、扫读困难。
+
+运费列表已用 `sampleBlocks` + 默认折叠解决同类问题;缴费期次采用同一模式。
+
+## 2. 已确认决策
+
+| 项 | 决策 |
+|----|------|
+| 交互形态 | 按期折叠:折叠行展示「第几期、应缴费金额、已缴费金额」;展开后展示应缴时间 / 已缴时间 / 欠缴费金额 |
+| 默认状态 | 全部折叠 |
+| 展开规则 | 每期独立展开/收起,可同时展开多期 |
+| 空期 | 只渲染有数据的期次,不再固定 pad 到 6 |
+| 实现路径 | 方案 1:`periodBlocks` 对齐运费 `sampleBlocks` |
+| 范围 | 仅缴费信息列表卡片(`module === 'payment'`) |
+| 非范围 | 催缴列表、协议详情缴费区、后端 API、`mobile-h5` WebView 壳、金额语义变更 |
+
+## 3. 目标
+
+1. 列表默认高度显著下降:期次区折叠时每期只占一行摘要。
+2. 需要时点开单期查看时间与欠缴。
+3. 无数据期次不占位。
+
+## 4. 数据结构
+
+`paymentCard`(`list-presenter.js`)不再将期次 `flatMap` 进 `fields`,改为输出 `periodBlocks`:
+
+```js
+{
+  title, subtitle, status,
+  fields: [ /* 协议号、姓名、合同总额… 不含期次 */ ],
+  periodBlocks: [
+    {
+      key: 'period-1',          // 稳定 key,优先 scheduleNo / id
+      scheduleNo: 1,            // 摘要:第几期
+      dueAmount: '¥3,000.00',   // 摘要:应缴费金额(money 格式)
+      paidAmount: '¥3,000.00',  // 摘要:已缴费金额(displayPaidAmount ?? paidAmount)
+      fields: [
+        field('应缴费时间', dueDate),
+        field('已缴费时间', payDate),
+        field('欠缴费金额', arrearsAmount, { money: true })
+      ]
+    }
+  ],
+  actions: ['view-protocol', 'view-payment-detail']
+}
+```
+
+主体 `fields` 顺序保持现有非期次字段,并在卡片底部(期次区之后)保留:
+
+- 累计实缴、待缴金额、备注
+
+即视觉顺序:头信息 → 主体字段(至应收总额)→ **期次折叠区** → 累计实缴 / 待缴 / 备注 → 操作按钮。与 Demo 一致。
+
+### 4.1 有数据期次判定
+
+遍历 `item.periods`(数组),保留满足任一条件的项:
+
+- `dueAmount` / `displayPaidAmount` / `paidAmount` / `arrearsAmount` 有可展示数值(含 0)
+- 或 `dueDate` / `payDate` 非空
+- 或存在有效 `scheduleNo`
+
+空对象 `{}`、全空字符串的占位项丢弃。不再 `Array.from({ length: 6 }, …)`。
+
+期次标题:`第${scheduleNo || index + 1}期`。
+
+## 5. UI(MarketListCard)
+
+- 当 `card.periodBlocks?.length` 时渲染期次区(样式类建议 `market-list-card__periods`)。
+- 每期一行可点击摘要(`min-height ≥ 44px`),布局约:`第N期 | 应缴 | 已缴 | chevron`。
+- 默认 `openKeys` 为空 Set / 全部 false;点击 toggling 单期;卡片 `item.id` / `index` 变化时重置为全部折叠。
+- 展开区复用现有 `market-list-card__fields` 紧凑网格展示 `block.fields`。
+- 金额摘要用现有 money 色(`--market-money` / 与卡片一致)。
+
+视觉权威:`docs/demos/2026-10-14-payment-card-period-collapse-demo.html`。
+
+## 6. 改动文件
+
+| 文件 | 职责 |
+|------|------|
+| `mobile-oa-h5/src/market/list-presenter.js` | `paymentCard` 产出 `periodBlocks`;去掉期次平铺 fields |
+| `mobile-oa-h5/src/market/components/MarketListCard.vue` | 渲染期次折叠行与展开明细 |
+| `mobile-oa-h5/src/styles/market.css` | 期次折叠样式 |
+| `mobile-oa-h5/src/market/list-presenter.test.js` | presenter:有/无空期、摘要字段、不再出现 `第N期·应缴费金额` 平铺 |
+| `mobile-oa-h5/src/market/mobile-parity-ui.test.js` | 组件/样式存在折叠结构与默认折叠 |
+
+## 7. 测试要点
+
+1. 仅 1 条有效期次 → `periodBlocks.length === 1`,无第 2~6 期。
+2. 摘要含 scheduleNo / dueAmount / paidAmount;展开 fields 含三时间/欠缴字段。
+3. `fields` 中不再含 `第1期·应缴费金额(元)` 这类平铺 label。
+4. `MarketListCard` 模板含 `periodBlocks`、默认折叠、可切换 `aria-expanded`。
+5. 触控行 `min-height: 44px`。
+
+## 8. 非目标
+
+- 不做「全部展开 / 全部收起」总开关。
+- 不改缴费进度、金额计算、后端列表契约。
+- 不改催缴(`payment-chase`)卡片。