# 外部服务接入清单

> 编制：2026-05-19 · 从系统待完善清单中提取所有需要接入第三方服务/平台/API 的项目

---

## 一、通知推送（P0 — 阻塞上线）

| 通道 | 所需服务 | 接入方式 | 配置项 | 优先级 |
|------|---------|----------|--------|--------|
| **MQTT** | EMQX / Mosquitto / 阿里云物联网平台 | Spring Integration MQTT 或 Eclipse Paho Java Client | `hss.mqtt.broker-url` `hss.mqtt.username` `hss.mqtt.password` | P0 |
| **微信小程序订阅消息** | 微信开放平台·小程序·订阅消息 | 后端调用 `POST https://api.weixin.qq.com/cgi-bin/message/subscribe/send` | `hss.wechat.app-id` `hss.wechat.app-secret` | P0 |
| **短信** | 阿里云短信 / 腾讯云短信 | 对应 SDK（`aliyun-sms-sdk` / `tencentcloud-sdk-java-sms`） | `hss.sms.access-key` `hss.sms.secret-key` `hss.sms.sign-name` `hss.sms.template-id` | P0 |

**代码位置**：`NotificationSender.java:76-97` — 三个通道的 `doSend()` 方法体目前仅写日志。

---

## 二、文件存储（P1 — 限制可用性）

| 服务 | 接入方式 | 配置项 | 优先级 |
|------|----------|--------|--------|
| **MinIO**（自建） 或 **阿里云 OSS** / **AWS S3** | 对应 Java SDK | `hss.storage.endpoint` `hss.storage.access-key` `hss.storage.secret-key` `hss.storage.bucket` | P1 |

**代码位置**：`EvidenceService.java:28` (presignUpload) + `:60` (getSignedUrl) — 目前返回本地路径，非真实预签名 URL。

---

## 三、地图与定位（P1 — 影响调度精度）

| 服务 | 接入方式 | 配置项 | 优先级 |
|------|----------|--------|--------|
| **高德地图 / 百度地图 API** | HTTP REST API（地理编码 + 驾车距离 + ETA） | `hss.map.provider` `hss.map.api-key` | P1 |

**使用场景**：
- `DispatchAlgorithm.calculateDistanceScore()` — 人员与服务地址真实行车距离（当前用 Haversine 直线距离 + 上次签到位置估算）
- `EtaService.estimateTravelMinutes()` — 区域间路程时间（当前按区域编码前缀估算）
- 申请单地址 → 经纬度地理编码（当前需要手动填写 `address_lat` / `address_lng`）

---

## 四、微信支付（P1 — 已实现 SDK，缺生产配置）

| 配置项 | 说明 | 获取方式 |
|--------|------|----------|
| `WECHAT_APPID` | 小程序 AppId | 微信公众平台 → 开发 → 开发管理 → 开发设置 |
| `WECHAT_MCHID` | 商户号 | 微信支付商户平台 → 账户中心 |
| `WECHAT_APIV3_KEY` | API v3 密钥（32位） | 商户平台 → API 安全 → 设置 APIv3 密钥 |
| `WECHAT_SERIAL_NO` | 商户证书序列号 | 商户平台 → API 安全 → 申请 API 证书 |
| `WECHAT_PRIVATE_KEY_PATH` | 商户私钥文件路径（PEM） | 证书申请时生成的 `apiclient_key.pem` |
| `WECHAT_NOTIFY_URL` | 支付回调地址 | **必须是公网可访问的域名** |

**代码位置**：`WechatPayService.java` — JSAPI 下单、退款、回调验签解密均已实现，缺真实商户号配置。

---

## 五、微信小程序发布（P1 — 阻塞发布）

| 项目 | 说明 | 获取方式 |
|------|------|----------|
| 小程序 AppId | `manifest.json:44` 当前为空 | 微信公众平台 → 开发 → 开发管理 |
| 服务器域名白名单 | `manifest.json:46` `urlCheck` 需改为 true | 小程序后台 → 开发管理 → 服务器域名 |
| request 合法域名 | 后端 API 地址 | 需配置 `https://your-domain.com` |
| uploadFile 合法域名 | 文件上传地址 | 需配置对象存储域名 |

---

## 六、域名与 HTTPS（P1 — 上线必需）

| 项目 | 说明 | 优先级 |
|------|------|--------|
| 域名注册 | 官网 + API 服务域名 | P1 |
| SSL 证书 | Let's Encrypt / 云服务商免费证书 | P1 |
| ICP 备案 | 中国大陆法律要求 | P1 |
| 公安备案 | 部分省市要求 | P2 |

---

## 七、监控与运维（P2）

| 服务 | 接入方式 | 优先级 |
|------|----------|--------|
| **Prometheus + Grafana** | Micrometer + Spring Boot Actuator（已集成 actuator） | P2 |
| **日志集中化** | ELK / 阿里云 SLS / Loki | P2 |
| **APM** | SkyWalking / 阿里云 ARMS | P2 |

---

## 八、无需外部服务，纯代码修复项（已处理）

以下项目已在本次修复中通过代码改动解决，无需外部服务：

| # | 项目 | 修复方式 |
|---|------|----------|
| P0-1 | StateMachine 守卫条件 | `transition()` 增加 `evaluateConstraint()` |
| P0-2 | 验证结果被忽略 | `submit()` 增加 `if (!result.passed()) throw` |
| P0-3 | 审核人空检查 | 改为 `if (equals) throw BusinessException` |
| P0-4 | SQL 注入 | `LeadController` 改为参数化查询 `?` |
| P0-5 | .gitignore 缺失 | 创建 `.gitignore` |
| P0-6 | Dockerfile Maven 镜像 | 改为 `maven:3.9-eclipse-temurin-17`（JRE 镜像当前不可用） |
| P1-1 | 批量作业失败无日志 | `BatchJobService` + `ScheduledTasks` 增加 FAILED 日志 |
| P1-2 | EvidenceService 数组越界 | 增加 try-catch NumberFormatException |
| P1-3 | Nginx 安全头 | HSTS + CSP + Permissions-Policy |
| P1-4 | .dockerignore | `website/.dockerignore` |
| P1-5 | FK 约束 + 索引 V12 | `hss_notification_receipts.outbox_id` 等 FK + 4 个索引 |
| P2-1 | delivery 水印导出 | `api.js` 导出 `addWatermark` |
| P2-2 | execute 离线队列 | catch 块调用 `OfflineQueue.add()` |
| P2-3 | 轨迹启动 | `checkin.vue` 签到成功后 `startTrajectory()` |
| P2-4 | iOS 权限嵌套 | `manifest.json` 修复 JSON 结构 |

---

## 优先级总结

| 级别 | 外部服务数 | 代码修复数 |
|------|----------|-----------|
| P0（阻塞上线） | **3**（MQTT Broker + 微信订阅消息 + 短信 SDK） | 6 |
| P1（影响核心功能） | **3**（对象存储 + 地图 API + 域名证书） | 12 |
| P2（增强完善） | **3**（监控 + CI/CD + 微信配置） | 6 |

**总计：需接入 9 个外部服务/平台，其余已全部通过代码修复解决。**