# 服务商业务范围下拉 & 企业万里汇uid 实现计划

> **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:** 1) 服务商新增/编辑弹窗的业务范围从输入框改为国内/国外下拉；2) 企业表单选国外服务商时出现万里汇uid输入框并落库回显

**Architecture:** 前后端改动：DB新增 `pay_enterprise.wanlihui_uid` 列 → Java Entity/DTO/VO 补充字段 → Service 处理映射 → 前端服务商表单改下拉、企业表单条件显隐万里汇uid、详情回显

**Tech Stack:** Vue3 + Element Plus, Java Spring Boot + MyBatis-Plus, PostgreSQL

---

### Task 1: 数据库迁移 — pay_enterprise 新增 wanlihui_uid 列

**Files:**
- Create: `java/sql/007_enterprise_wanlihui_uid.sql`

- [ ] **Step 1: 创建 SQL 迁移文件**

```sql
-- 企业表新增万里汇uid字段
ALTER TABLE pay_enterprise ADD COLUMN IF NOT EXISTS wanlihui_uid VARCHAR(128);
```

- [ ] **Step 2: 执行迁移**

Run: `psql -h <host> -U <user> -d <database> -f java/sql/007_enterprise_wanlihui_uid.sql`

- [ ] **Step 3: 验证列已存在**

```sql
SELECT column_name, data_type FROM information_schema.columns
WHERE table_name = 'pay_enterprise' AND column_name = 'wanlihui_uid';
```

Expected: 一行结果，`wanlihui_uid | character varying`

- [ ] **Step 4: Commit**

```bash
git add java/sql/007_enterprise_wanlihui_uid.sql
git commit -m "feat: pay_enterprise 新增 wanlihui_uid 列"
```

---

### Task 2: Backend — Entity + DTO + VO 补充 wanlihuiUid 字段

**Files:**
- Modify: `java/src/main/java/com/payment/platform/module/payment/enterprise/entity/EnterpriseEntity.java`
- Modify: `java/src/main/java/com/payment/platform/module/payment/enterprise/dto/EnterpriseCreateDTO.java`
- Modify: `java/src/main/java/com/payment/platform/module/payment/enterprise/dto/EnterpriseUpdateDTO.java`
- Modify: `java/src/main/java/com/payment/platform/module/payment/enterprise/dto/EnterpriseVO.java`

- [ ] **Step 1: EnterpriseEntity.java — 在 `scopeLabel` 字段后添加 `wanlihuiUid`**

```java
// 位置: scopeLabel 字段后（line 34 之后）

/** 万里汇uid（国外服务商必填） */
private String wanlihuiUid;
```

- [ ] **Step 2: EnterpriseCreateDTO.java — 添加 `wanlihuiUid`**

```java
// 位置: legalRepIdPhoto 字段后（line 42 之后）

@Schema(description = "万里汇uid")
private String wanlihuiUid;
```

- [ ] **Step 3: EnterpriseUpdateDTO.java — 添加 `wanlihuiUid`**

```java
// 位置: legalRepIdPhoto 字段后（line 43 之后）

@Schema(description = "万里汇uid")
private String wanlihuiUid;
```

- [ ] **Step 4: EnterpriseVO.java — 添加 `wanlihuiUid`**

```java
// 位置: legalRepIdPhoto 字段后（line 91 之后）

@Schema(description = "万里汇uid")
@com.fasterxml.jackson.annotation.JsonProperty("wanlihui_uid")
private String wanlihuiUid;
```

- [ ] **Step 5: 编译验证**

Run: `cd java && mvn compile -q`

Expected: BUILD SUCCESS

- [ ] **Step 6: Commit**

```bash
git add java/src/main/java/com/payment/platform/module/payment/enterprise/entity/EnterpriseEntity.java \
        java/src/main/java/com/payment/platform/module/payment/enterprise/dto/EnterpriseCreateDTO.java \
        java/src/main/java/com/payment/platform/module/payment/enterprise/dto/EnterpriseUpdateDTO.java \
        java/src/main/java/com/payment/platform/module/payment/enterprise/dto/EnterpriseVO.java
git commit -m "feat: Enterprise Entity/DTO/VO 补充 wanlihuiUid 字段"
```

---

### Task 3: Backend — Service 处理 wanlihuiUid 映射

**Files:**
- Modify: `java/src/main/java/com/payment/platform/module/payment/enterprise/service/EnterpriseService.java`
- Modify: `java/src/main/java/com/payment/platform/module/payment/enterprise/service/AlipayEnterpriseService.java`

- [ ] **Step 1: EnterpriseService.create() — 添加 wanlihuiUid 映射**

在方法 `create()` 中 `e.setLegalRepIdPhoto(dto.getLegalRepIdPhoto());` 之后添加：

```java
e.setWanlihuiUid(dto.getWanlihuiUid());
```

- [ ] **Step 2: EnterpriseService.update() — 添加 wanlihuiUid 映射**

在方法 `update()` 中 `if (dto.getLegalRepIdPhoto() != null) e.setLegalRepIdPhoto(dto.getLegalRepIdPhoto());` 之后添加：

```java
if (dto.getWanlihuiUid() != null) e.setWanlihuiUid(dto.getWanlihuiUid());
```

- [ ] **Step 3: EnterpriseService.toListVO() — 添加 wanlihuiUid 映射**

在 `vo.setLegalRepIdPhoto(e.getLegalRepIdPhoto());` 之后添加：

```java
vo.setWanlihuiUid(e.getWanlihuiUid());
```

- [ ] **Step 4: EnterpriseService.toVO() — 添加 wanlihuiUid 映射**

在 `vo.setLegalRepIdPhoto(e.getLegalRepIdPhoto());` 之后添加：

```java
vo.setWanlihuiUid(e.getWanlihuiUid());
```

- [ ] **Step 5: AlipayEnterpriseService.applyInvite() — 保存 wanlihuiUid**

在 `pending.setLegalRepIdPhoto(...)` 之后添加：

```java
pending.setWanlihuiUid((String) data.get("wanlihui_uid"));
```

- [ ] **Step 6: 编译验证**

Run: `cd java && mvn compile -q`

Expected: BUILD SUCCESS

- [ ] **Step 7: Commit**

```bash
git add java/src/main/java/com/payment/platform/module/payment/enterprise/service/EnterpriseService.java \
        java/src/main/java/com/payment/platform/module/payment/enterprise/service/AlipayEnterpriseService.java
git commit -m "feat: EnterpriseService/AlipayEnterpriseService 处理 wanlihuiUid 字段映射"
```

---

### Task 4: Frontend — API 类型 & Schema 补充 wanlihui_uid

**Files:**
- Modify: `frontend/src/api/module_payment/enterprise.ts`
- Modify: `frontend/src/api/module_payment/enterprise/schema.ts`

- [ ] **Step 1: enterprise.ts EnterpriseDetail 接口 — 添加 `wanlihui_uid`**

在 `EnterpriseDetail` 接口末尾（`legal_rep_id_photo` 之后）添加：

```ts
/** 万里汇uid */
wanlihui_uid?: string;
```

- [ ] **Step 2: schema.ts EnterpriseOutSchema — 添加 `wanlihui_uid`**

在 `EnterpriseOutSchema` 接口末尾添加：

```ts
/**
 * 万里汇uid
 */
wanlihui_uid?: string;
```

- [ ] **Step 3: 验证前端编译**

Run: `cd frontend && npx vue-tsc --noEmit 2>&1 | Select-Object -Last 10`

Expected: No new type errors

- [ ] **Step 4: Commit**

```bash
git add frontend/src/api/module_payment/enterprise.ts \
        frontend/src/api/module_payment/enterprise/schema.ts
git commit -m "feat: 前端 enterprise API 类型补充 wanlihui_uid"
```

---

### Task 5: Frontend — 服务商表单 scope_label 改为下拉框

**Files:**
- Modify: `frontend/src/views/module_system/service_provider/index.vue`

- [ ] **Step 1: 修改"新增"弹窗中的 scope_label 输入框（约 line 117-118）**

Before:
```html
<el-form-item label="业务范围标签" prop="scope_label">
  <el-input v-model="formData.scope_label" placeholder="如 DOMESTIC / OVERSEAS" :maxlength="64" />
</el-form-item>
```

After:
```html
<el-form-item label="业务范围" prop="scope_label">
  <el-select v-model="formData.scope_label" placeholder="请选择业务范围" style="width: 100%">
    <el-option label="国内" value="DOMESTIC" />
    <el-option label="国外" value="OVERSEAS" />
  </el-select>
</el-form-item>
```

- [ ] **Step 2: 修改"编辑"弹窗中的 scope_label 输入框（约 line 150-151）**

Before:
```html
<el-form-item label="业务范围标签" prop="scope_label">
  <el-input v-model="formData.scope_label" placeholder="如 DOMESTIC / OVERSEAS" :maxlength="64" />
</el-form-item>
```

After:
```html
<el-form-item label="业务范围" prop="scope_label">
  <el-select v-model="formData.scope_label" placeholder="请选择业务范围" style="width: 100%">
    <el-option label="国内" value="DOMESTIC" />
    <el-option label="国外" value="OVERSEAS" />
  </el-select>
</el-form-item>
```

- [ ] **Step 3: 修改验证规则文案（约 line 252, 260）**

将 `"请输入业务范围"` 改为 `"请选择业务范围"`（两处：`rules.scope_label` 和 `updateRules.scope_label`）

- [ ] **Step 4: 验证编译**

Run: `cd frontend && npx vue-tsc --noEmit 2>&1 | Select-Object -Last 10`

Expected: No new type errors

- [ ] **Step 5: Commit**

```bash
git add frontend/src/views/module_system/service_provider/index.vue
git commit -m "feat: 服务商表单业务范围改为国内/国外下拉框"
```

---

### Task 6: Frontend — EnterpriseForm 万里汇uid 条件显隐 + 提交

**Files:**
- Modify: `frontend/src/views/module_payment/enterprise/components/EnterpriseForm.vue`

- [ ] **Step 1: 在 `initialFormData` 中添加 `wanlihui_uid` 字段（约 line 201-208）**

```ts
const initialFormData = {
  identity_type: "ALIPAY_USER_ID",
  alipay_id_type: "uid",
  identity: undefined,
  identity_open_id: undefined,
  service_provider_id: null as number | null,
  scope_label: "",
  wanlihui_uid: "",
};
```

- [ ] **Step 2: 在 `handleProviderChange` 中添加切换时清空逻辑（约 line 214-217）**

```ts
function handleProviderChange(val: number) {
  const provider = providerOptions.value.find(p => p.id === val);
  formData.scope_label = provider?.scope_label || "";
  // 切换服务商时若不再是国外，清空万里汇uid
  if (formData.scope_label !== "OVERSEAS") {
    formData.wanlihui_uid = "";
  }
}
```

- [ ] **Step 3: 在模板中添加万里汇uid输入框 — 放在"身份类型"行之前，选择国外服务商后显示**

在服务商选择器 `</el-row>` 之后、身份类型 `<el-row>` 之前插入：

```html
      <!-- 万里汇uid：仅国外服务商显示 -->
      <el-row v-if="formData.scope_label === 'OVERSEAS'" :gutter="20">
        <el-col :span="12">
          <el-form-item label="万里汇uid" prop="wanlihui_uid">
            <el-input v-model="formData.wanlihui_uid" placeholder="请输入万里汇uid" :maxlength="128" />
          </el-form-item>
        </el-col>
      </el-row>
```

- [ ] **Step 4: 在 `submitForm` 的 `submitData` 中添加 `wanlihui_uid`（约 line 430 后）**

在 `scope_label: formData.scope_label,` 之后添加：

```ts
wanlihui_uid: formData.wanlihui_uid || undefined,
```

- [ ] **Step 5: 在 `update` 类型的 watch 回显中添加 `wanlihui_uid`（约 line 253 后）**

在 `materialForm.legal_rep_id_photo = data.legal_rep_id_photo || "";` 之后添加：

```ts
formData.wanlihui_uid = data.wanlihui_uid || "";
```

- [ ] **Step 6: 在 `resetForm` 中添加重置逻辑（约 line 477-488）**

确保 `resetForm` 使用的 `JSON.parse(JSON.stringify(initialFormData))` 自动包含 `wanlihui_uid: ""`（无需额外改动，Step 1 已覆盖）

- [ ] **Step 7: 验证编译**

Run: `cd frontend && npx vue-tsc --noEmit 2>&1 | Select-Object -Last 10`

Expected: No new type errors

- [ ] **Step 8: Commit**

```bash
git add frontend/src/views/module_payment/enterprise/components/EnterpriseForm.vue
git commit -m "feat: 企业表单选国外服务商时显示万里汇uid输入框"
```

---

### Task 7: Frontend — EnterpriseDetail 回显万里汇uid

**Files:**
- Modify: `frontend/src/views/module_payment/enterprise/components/EnterpriseDetail.vue`

- [ ] **Step 1: 在详情模板的"签约信息"区块中添加万里汇uid显示**

在"账号ID"描述项之后（约 line 40 后）添加：

```html
      <el-descriptions-item v-if="detailData.wanlihui_uid" label="万里汇uid" :span="1">
        {{ detailData.wanlihui_uid }}
      </el-descriptions-item>
```

- [ ] **Step 2: 验证编译**

Run: `cd frontend && npx vue-tsc --noEmit 2>&1 | Select-Object -Last 10`

Expected: No new type errors

- [ ] **Step 3: Commit**

```bash
git add frontend/src/views/module_payment/enterprise/components/EnterpriseDetail.vue
git commit -m "feat: 企业详情回显万里汇uid"
```

---

### 验证汇总

完成后运行完整构建确认所有层级通过：

```bash
# 后端
cd java && mvn compile

# 前端
cd frontend && npm run build
```

### 手动测试要点

1. 服务商管理 → 新增/编辑弹窗 → 业务范围为下拉框，选项为"国内"/"国外"
2. 企业入驻 → 先选"国内"服务商 → 无万里汇uid输入框
3. 企业入驻 → 切换到"国外"服务商 → 出现万里汇uid输入框
4. 填写万里汇uid → 提交 → 数据库 `pay_enterprise.wanlihui_uid` 有值
5. 企业详情 → 万里汇uid正确回显