juzi/docs/HANDOFF-2026-11-01.md

# 交接文档：淘宝小程序 + 聚石塔 SAE + Java MVP

> 日期：2026-11-01 凌晨  
> 给下一个 agent：先读「一句话状态」和「明天先做什么」，再按需读后面。

## 一句话状态

**云端链路已经打通**：开放平台服务测试 `POST /api/taobao/ping` 返回：

```json
{
  "success": true,
  "data": {
    "server": "java",
    "signMessage": "verify-sign=false, skipped (local/direct mode)",
    "appKey": "35486228",
    "transport": "gateway",
    "ok": true,
    "pong": true,
    "env": "test",
    "signVerified": false
  },
  "errorCode": null,
  "errorMessage": null
}
```

SAE `nnn` 上跑的是 `0.0.2` JAR，SAE 环境变量已清空，JAR 内置 `verify-sign:false`，所以 `signVerified:false` 是**预期**。  
**还没做** IDE 真机预览；**签名校验尚未启用**（之前的 `signature mismatch` 未解决，先绕过）。

## 明天先做什么

1. **IDE 真机预览**，验证小程序 → 云网关 → 聚石塔云应用 → 私网 CLB → SAE 整条链路（第 5.1 节）。
2. 真机通过后，再决定是否开签名：重置 35486228 的 AppSecret → 更新 `application-local.yml` → `verify-sign:true` → 打 `0.0.3` 上传（第 5.3 节）。
3. 最后提交这轮未提交的代码（**不要提交 `application-local.yml`**）并 push。

## 当前链路

```text
淘宝小程序（taobao/）
  → @tbmp/mp-cloud-sdk（cloudEnv: test）
  → 淘宝云网关（AppKey 35486228）
  → 聚石塔云应用 1me-net（ID 62829，默认云应用）
  → 私网 CLB lb-k2j324dwux1svaf2akwqx / 192.168.65.185:80
  → SAE 应用 nnn（namespace cn-zhangjiakou:my-namespace）
  → Java Spring Boot 0.0.2，容器 8080
```

## 关键资源 / ID

| 资源 | 值 |
|---|---|
| 开放平台应用（当前正确） | `1me 肌肤状态检测`，AppKey **35486228** |
| 旧应用（不再使用） | `1me肌肤检测`，AppKey 35479221；旧 Secret 不要再用 |
| 聚石塔云应用 | `1me-net`，ID **62829**，默认应用；生产/测试 SLB 都是 `192.168.65.185:80` |
| 聚石塔云应用（未用） | `app-new`，ID 62861；没接 SAE/CLB，别用 |
| SAE 应用 | `nnn`，ID `7c9f2d2a-95d0-4879-afad-323d30f85d30` |
| SAE 命名空间 | `cn-zhangjiakou:my-namespace` |
| VPC | `vpc-8vb5mcvenp8jwa1roqcsa`（`JST_cn-zhangjiakou_vpc-new`） |
| vSwitch | `vsw-8vbna5zb2rq03gaeiymch`（可用区 A） |
| 安全组 | `sg-8vbh8c96h0kotpu7y26r`（“聚石塔官方创建ssh”），需放行 8080 |
| 实例规格 | 1 Core 2 GiB |
| 代码包 | `taobao-mvp-backend-0.0.2.jar`，版本号 `1793466846250` |
| SAE 环境变量 | **已清空**（重要，见“不要做什么”） |

## 已验证 / 未验证

### 已验证

- 后端本地：`mvn test` 4/4（0.0.1 时；版本改 0.0.2 后只 `-DskipTests` 打包，未重跑）。
- 前端：`npm test` 17/17；`taobao/scripts/mvp-local-check.cjs` 本地直连 Java 通过。
- JAR 本地启动：`/actuator/health` UP，`/api/taobao/ping` 正常。
- SAE `nnn` 部署 `0.0.2` 成功，服务测试返回上面的 JSON。
- `signVerified:false` 是预期；`signMessage` 是固定文案，不代表直连；`transport:"gateway"` 证明走了网关。

### 未验证

- IDE **真机预览**（云应用 SDK 模拟器不支持，必须真机）。
- 开启签名后的 `signVerified:true`。
- 真实测肤接口（challenge/session/photo/skin-analyze/analysis/reports/logout）仍在 Node，Java 只有 `ping/whoami/echo`。

## 代码 / 配置状态

### Git

- 已推送：`ac0b7ca feat(sae): add Java MVP backend and Taobao connectivity page`（origin/main 同步）。
- 工作区未提交改动（11 个文件，`git diff --stat`）：
  - `.gitignore`（忽略 `application-local.yml`）
  - `README.md`（交接文档入口）
  - `backend-java/README.md`
  - `backend-java/pom.xml`（version `0.0.2`）
  - `backend-java/src/main/resources/application.yml`（`spring.profiles.active: local`）
  - `docs/SAE-Java-MVP-操作步骤.md`（0.0.2 + 4.3.1 更新 JAR）
  - `taobao/config.js`（云端 test）
  - `taobao/pages/mvp/mvp.js`（显示 cloudType）
  - `taobao/pages/splash/splash.js`（云端 test 也显示 MVP 入口）
  - `taobao/test/transport.test.cjs`（tower 测试）
  - `taobao/utils/transport.js`（tower 模式）

**`application-local.yml` 在 `.gitignore` 里，未跟踪，不要提交。** 它包含 AppSecret；JAR 里也包含，临时方案。

### 后端

- `backend-java/`，Spring Boot 3.5.6 / Java 17。
- `application.yml`：`spring.profiles.active: local`。
- `application-local.yml`：
  - `taobao.app-key: "35486228"`
  - `taobao.app-secret: <当前 Secret>`
  - `taobao.verify-sign: false`
- JAR：`backend-java/target/taobao-mvp-backend-0.0.2.jar`（23.6MB），包含 `BOOT-INF/classes/application-local.yml`。
- 云端已上传该 JAR；SAE 环境变量已清空（否则覆盖 JAR 配置）。
- 接口：`GET/POST /api/taobao/ping`、`POST /api/taobao/whoami`、`POST /api/taobao/echo`、`GET /actuator/health`。
- 签名校验：`TaobaoSignatureVerifier`，算法与 `h5/lib/taobao-auth.js` 一致；`verify-sign:false` 时跳过。

### 前端

- `taobao/config.js` 当前是云端 test：
  - `environment: 'development'`
  - `transport: 'cloud'`
  - `cloudType: 'tower'`
  - `cloudEnv: 'test'`
  - `cloudAppId: ''`（默认云应用；若 SDK 报默认不存在，填 `62829`）
  - `mvpLocal: false`
  - `baseUrl: 'https://miniappcloud.taobao.com'`（tower 模式仅占位，不参与请求）
  - `assetBase: 'http://127.0.0.1:18180/assets/'`（真机上底图可能加载失败，不影响 MVP 入口）
- `taobao/utils/transport.js`：`cloudType === 'tower'` 时不传 `domain`、不要求 HTTPS、`cloudAppId` 可空；`cloudType === 'empty'` 保持旧行为（空应用/外部服务）。
- `taobao/pages/mvp/mvp`：MVP 页面；`mvpLocal` 时可强制直连 8080，云端时走 transport cloud。
- `taobao/pages/splash/splash.js`：`showMvpDebug = mvpLocal || (transport === 'cloud' && environment !== 'production')`；当前 development+cloud，入口显示。
- `taobao/app.json` 已注册 `pages/mvp/mvp`。
- `taobao/scripts/mvp-local-check.cjs`：本地直连契约测试（独立配置，不依赖 `config.js`）。
- `taobao/test/transport.test.cjs`：17 个测试含 tower 模式。

### 工具 / 环境

- JDK 17：`D:\juzi\tools\jdk17\jdk-17.0.21.0.2+1`
- Maven 3.9.9：`D:\juzi\tools\maven\apache-maven-3.9.9`
- Node 22.23.2：`C:\Program Files\nodejs`
- PowerShell 执行策略 Restricted；先：

```powershell
Set-ExecutionPolicy -Scope Process Bypass
. D:\juzi\tools\env-java.ps1
```

- Taobao IDE 的 `wmic` 兼容 shim：`C:\Users\youmi\.local\bin\wmic.cmd`；重建脚本 `D:\juzi\tools\fix-taobao-ide-wmic.ps1`。IDE 已能打开。

## 5. 明天详细步骤

### 5.1 IDE 真机预览（第一优先级）

1. 确认 IDE 当前小程序是 **35486228**（`1me 肌肤状态检测`），不是 35479221。
2. 重新编译。
3. 点顶部「预览」，手机淘宝扫码（**不要用模拟器**；`cloud.application.httpRequest` 模拟器不支持）。
4. 启动页右上角点「SAE MVP 连通性」。
5. 页面自动调 `/api/taobao/ping`，预期：
   - `transport: "gateway"`
   - `server: "java"`
   - `signVerified: false`（当前 JAR 配置）
   - `appKey: "35486228"`
6. 如果成功，MVP 链路验收完成；记录截图。

### 5.2 真机常见错误

| 现象 | 排查 |
|---|---|
| `cloud init failed` | IDE 当前 App 不是 35486228；云应用没设默认；`cloudEnv` 不是 test |
| `cloudAppId` 默认不存在 | `taobao/config.js` 的 `cloudAppId` 填 `62829` |
| `Cannot find module '@tbmp/mp-cloud-sdk'` | `npm.cmd ci`，IDE 里「构建 npm」 |
| 模拟器报 SDK 不支持 | 正常，改用真机预览 |
| `请先配置淘宝云应用和 HTTPS 服务地址` | `cloudType` 不是 tower 或 transport 不是 cloud |
| 真机底图不显示 | `assetBase` 是 127.0.0.1，正常；MVP 入口仍可点 |
| `SIGN_INVALID` | 只会在 `verify-sign:true` 时出现；当前 false，不应出现 |

### 5.3 开签名（真机通过后再做）

1. 开放平台打开 **35486228** 的应用，重置 AppSecret，复制新值。
2. 更新 `backend-java/src/main/resources/application-local.yml`：
   - `app-secret: 新值`
   - `verify-sign: true`
3. 改 `pom.xml` 版本为 `0.0.3`，重新打包：

```powershell
Set-ExecutionPolicy -Scope Process Bypass
. D:\juzi\tools\env-java.ps1
cd D:\juzi\backend-java
mvn clean -DskipTests package
```

4. 上传 `target\taobao-mvp-backend-0.0.3.jar` 到 SAE `nnn`，部署。
5. 服务测试 `POST /api/taobao/ping`，期望 `appKey:35486228`、`signVerified:true`。
6. 如果仍 `signature mismatch`：
   - 确认 SAE 没有残留 `TAOBAO_*` 环境变量（它们会覆盖 JAR）；
   - 确认 Secret 是 35486228 的当前值，没有空格/换行；
   - 点服务测试「请求详情」，核对 `sign_method`、URL query、body；
   - 需要时按 `docs/SAE-Java-MVP-操作步骤.md` 第 6 节算法手工复算（仓库里目前没有 `check-gateway-sign.cjs`，之前回答提到过但未创建）。

### 5.4 提交代码

真机通过后：

- 提交这 11 个改动（`pom.xml` 0.0.2、config、transport、splash、mvp、test、docs、两个 README、.gitignore、application.yml），外加本文档 `docs/HANDOFF-2026-11-01.md`。
- **不要** `git add application-local.yml`；它在 `.gitignore` 里。
- push 到 `origin/main`；远端证书已续期（notAfter 2027-01-29），凭据有效。

## 6. 不要做什么 / 已知坑

1. **不要再创建“云托管/新建云应用”**：那是云应用套件，会新建 CPU/容器并要求开通「容器镜像服务个人版」，和现有 SAE `nnn` 不是一回事。用户已提工单确认过。
2. **不要创建聚石塔容器集群/ECS**：入淘引导的「创建集群」是旧经典流程；SAE 不需要。
3. **不要用 `app-new` 62861**：没接 SAE/CLB；用 `1me-net` 62829。
4. **不要用 35479221 的 AppSecret**：当前是 35486228；旧 Secret 不通用。
5. **不要再加 `TAOBAO_VERIFY_SIGN=true` 环境变量**：会覆盖 JAR 的 `verify-sign:false`，回到 `SIGN_INVALID`。要么全删环境变量用 JAR，要么三者都配且 Secret 正确。
6. **不要在模拟器测云应用**：必须真机预览。
7. **不要把 AppSecret 写进小程序代码、git、聊天**：`application-local.yml` 已 gitignore；JAR 里带 Secret 只是临时验证，验证完重置。
8. **主应用其他页面现在不能云测**：Java 只有 ping/whoami/echo；challenge/session/photo/skin-analyze 等还在 Node。只测 MVP 页。
9. **`signMessage:"verify-sign=false..."` 不是直连**：固定文案；看 `transport`。
10. **SAE 应用 `nnn` 的“更多”里没有部署入口时**：用完整 SAE 控制台 `https://saenext.console.aliyun.com/cn-zhangjiakou/app-list/micro`，或应用列表行 `nnn` 的 ⋮；上传走「部署应用 → 代码包部署」。
11. **云托管入淘引导的「关联云应用」灰按钮**：不要按它去创建集群；已经通过「云应用列表 → 关联云应用」关联成功（1me-net 默认）。
12. **`new-new` SAE 应用/自动 VPC**：之前失败的应用，未使用；可删，别拿它当后端。
13. **`application-local.yml` 是临时方案**：正式环境改回环境变量/保密字典，重置 Secret；JAR 不要外发。

## 7. 常用命令

```powershell
# 环境
Set-ExecutionPolicy -Scope Process Bypass
. D:\juzi\tools\env-java.ps1

# 后端构建
cd D:\juzi\backend-java
mvn clean -DskipTests package

# 本地启动
java -jar target\taobao-mvp-backend-0.0.2.jar

# 本地健康/接口
curl.exe http://127.0.0.1:8080/actuator/health
curl.exe -X POST -H "Content-Type: application/json" -d "{}" http://127.0.0.1:8080/api/taobao/ping

# 前端测试
cd D:\juzi\taobao
npm.cmd test
node scripts\mvp-local-check.cjs
```

## 8. 下一阶段（MVP 验收后）

1. 把 `h5/lib/taobao-routes.js` 的接口迁到 Java：
   - `POST /api/taobao/challenge`
   - `POST /api/taobao/session`
   - `POST /api/taobao/me`
   - `POST /api/taobao/photo`（64KiB 分片）
   - `POST /api/taobao/skin-analyze`（异步任务）
   - `POST /api/taobao/analysis`（轮询）
   - `POST /api/taobao/reports`
   - `POST /api/taobao/logout`
2. 所有 `/api/taobao/**` 统一信封 + 签名；128KB/10s 限制。
3. 账号/历史/图片存 RDS/OSS，不放容器本地盘。
4. 保留 H5 Node 路由不变，Java 只接淘宝；以现有 Node 实现为契约。
5. 接 SLS 日志、Actuator 健康检查、告警，再切正式流量。

## 9. 交接检查清单

- [ ] 真机预览 `transport:"gateway"`、`server:"java"`
- [ ] 记录真机截图/返回
- [ ] 决定是否开签名；若开，重置 Secret、0.0.3、`signVerified:true`
- [ ] 提交 10 个改动，push
- [ ] 清理 `new-new`/`app-new`/旧 35479221（确认无用后）
- [ ] 重置 AppSecret，移除 JAR 内 Secret，改回环境变量/保密字典
- [ ] 开始迁移真实接口

---

**给下一个 agent 的第一句话**：当前服务测试已通过（`transport:"gateway"`、`server:"java"`、`signVerified:false`），先做 IDE 真机预览；不要开签名、不要创建云托管/集群，先读第 6 节“不要做什么”。