# feat(agency): 加 visible 小程序展示开关字段

**日期**: 2026-05-06 20:00
**通知对象**: @mmg (前端)
**关联 PR**: wx/HL #1756 (已 merge dev, 测试服部署中)
**关联 Issue**: #1749

---

## 一、用户需求

后台「旅行社公司管理 → 基础信息」tab 需要新增「**是否在小程序展示**」开关字段，与现有「状态(启用/停用)」解耦：
- **状态(status)**: 业务启停 — 停用则不能下单/办合同
- **是否展示(visible)**: 仅控制小程序端展示 — 关闭后业务不受影响，仅前端不渲染

---

## 二、改动 (后端)

### DB

新增列 `travel_agency.visible TINYINT(1) NOT NULL DEFAULT 1`，与 `status` 解耦。Flyway migration `V20260507_001` 自动 apply，历史 4 行 visible=1。

### VO 字段

| VO | 字段 | 类型 | 说明 |
|---|---|---|---|
| `AgencySaveReqVO` | `visible` | `Integer` | admin 编辑表单可选, 默认后端补 1 |
| `AgencyRespVO` | `visible` | `Integer` | admin 详情/列表响应 |
| `MpAgencyRespVO` | `visible` | `Integer` | mp `/primary` 响应携带 |
| `AgencyInternalDTO` | `visible` | `Integer` | 服务间 Feign 透传 |

### 渲染策略 (前端约定)

- `/mp/agency/primary` 仍按 `isPrimary=1` 返回主体公司（**不强制按 visible 过滤**, 避免主体一关全站无主体）
- 响应携带 `visible` 字段，**前端按此自行决定是否渲染对应 UI 区块**
- `visible=0` 时小程序的主体公司展示位（首页/我的页/客服/分享卡片/协议页落款）按需隐藏

---

## 三、前端建议

### admin 端 - 「基础信息」tab 加开关

```vue
<!-- 在「状态(启用/停用)」下方加一行 -->
<NFormItem label="是否在小程序展示" path="visible">
  <NSwitch
    :value="form.visible === 1"
    @update:value="(v) => form.visible = v ? 1 : 0"
    checked-value
    unchecked-value
  />
</NFormItem>
```

POST/PUT body 透传 `visible: 0/1`（不传时后端默认 1）。

### 小程序端 - 按 visible 渲染主体公司块

```js
// /mp/agency/primary 响应
const { data } = await api.get('/mp/agency/primary')
if (data.visible === 0) {
  // 隐藏主体公司展示位 (首页/我的页/协议页落款 等)
  return null
}
// 正常渲染 data.agencyName / data.complaintPhone / data.qualifications ...
```

---

## 四、API round-trip (测试服, dev 部署后验证)

```bash
TOK=$(curl -sk -X POST "https://api.test.1814.love:9443/admin/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"Admin@123456"}' \
  | python -c "import json,sys; print(json.load(sys.stdin)['data']['token'])")

# admin 端: 详情含 visible
curl -sk "https://api.test.1814.love:9443/admin/travel-agency/3" \
  -H "Authorization: Bearer $TOK"

# admin 端: 编辑 visible=0
curl -sk -X PUT "https://api.test.1814.love:9443/admin/travel-agency/3" \
  -H "Authorization: Bearer $TOK" \
  -H "Content-Type: application/json" \
  -d '{"code":"hulai-wenlu","agencyName":"...","businessLicenseNumber":"...","visible":0}'

# mp 端: /primary 响应含 visible
curl -sk "https://api.test.1814.love:9443/mp/agency/primary" \
  -H "Authorization: Bearer $MP_TOKEN"
```

---

## 五、agency 模块 PR 清单 (5/6)

| PR | 内容 |
|---|---|
| #1715 | admin path 纠回 `/admin/travel-agency` |
| #1717 | 资质附件分类 + 合同平台字典 |
| #1718 | nacos 完整字段同步 DB |
| #1719 | payment 加 name + appId |
| #1720 | supportedPlatforms 中文 label 字段 |
| #1721 | DB 单一真相源, nacos.agencies 弃用 |
| #1722 | 产品详情回显 agencyId/agencyName |
| #1728 | 删除「分公司名称」字段 |
| #1734 | 经营许可证号改非必填 |
| #1738 | mp/agency/primary 返资质附件列表 |
| **#1756** | **本 PR — 加 visible 小程序展示开关** |

---

cc @mmg