zkxw/docs/superpowers/plans/2026-10-13-mobile-protocol-customer-search.md

移动端协议单客户档案检索 + 身份证联动 Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 移动端协议单母亲/父亲姓名可检索客户档案并回填字段；母亲身份证自动推导出生年月。不改挂客户主档 id（遵守现有 _assert_customer_link_policy）。

Architecture: 市场协议菜单权限下新增只读 protocols/customers 检索；前端纯函数处理回填与身份证规则；customerSearch 字段类型 + 弹层远程搜索 UI。

Tech Stack: FastAPI + SQLAlchemy；Vue 3 + Vant（mobile-oa-h5）；Node test runner

Design: docs/superpowers/specs/2026-10-13-mobile-protocol-customer-search-design.md

---

File map

File	Responsibility
backend/app/api/market_mobile.py	GET .../protocols/customers
backend/tests/test_market_protocol_api.py	检索 API 测试
mobile-oa-h5/src/api/market.js	fetchMarketProtocolCustomers
mobile-oa-h5/src/market/protocol-customer-link.js	纯函数
mobile-oa-h5/src/market/protocol-customer-link.test.js	单测
mobile-oa-h5/src/market/components/ProtocolCustomerSearchField.vue	远程检索 UI
mobile-oa-h5/src/market/components/MarketFormField.vue	支持 customerSearch
mobile-oa-h5/src/market/modules/protocol.js	字段类型；payload 关联 id
mobile-oa-h5/src/views/market/MarketModuleForm.vue	选中回填、身份证 → 出生年月

---

Task 1: 纯函数 + 测试

• Create protocol-customer-link.js + failing tests for calcBirthYmFromIdCard / applyCustomerSelect
• Implement until green

Task 2: 后端客户检索 API

• Failing test: empty keyword → empty list; keyword hit
• Implement route + data_scope + _row_to_dict
• Green

Task 3: API client + form field type

• fetchMarketProtocolCustomers
• ProtocolCustomerSearchField.vue
• Wire customerSearch in MarketFormField / protocol formSections

Task 4: Form integration

• MarketModuleForm: select fill + idCard → birthYm
• Contract/parity tests update

Task 5: Verify

• pytest market protocol tests; node --test customer-link + related
• Manual smoke checklist in design §5