juzi/taobao/README.md

# 淘宝小程序开发说明

当前完成本地开发闭环：授权登录 → 基础档案 → 正/右/左三步手动拍摄或相册选图 → 服务端检测 → 七项报告 → 最近5份历史报告。真实淘宝授权、云网关、相机和图片组件仍需在关联 AppKey 的淘宝 IDE 与真机中验收。

## 本地启动

在本目录运行：

```powershell
npm ci
npm run dev:backend
```

只监听回环地址：

- `http://127.0.0.1:18180`：本地 H5 与淘宝网关模拟代理。
- `http://127.0.0.1:18181`：实际共享 Node 后端。
- `http://127.0.0.1:18180/dev/health`：确认样本模式。
- `../temp/taobao-local-data/`：隔离的账号、照片、检测记录和报告。不会读写现有 `h5/data/`。

代理使用固定的本地测试身份并模拟淘宝网关签名；Face++ 返回仓库内的固定样本。模拟逻辑仅在开发启动脚本中，正式服务器不会接受客户端自报 `open_id`，也没有免验签的开发登录后门。本地 H5 的微信入口不启用；微信 `/state/` 授权由独立浏览器回归验证。

`config.js` 当前是本地配置：`transport: 'direct'`、端口18180。直连传输只允许 localhost/127.0.0.1；不要把它当成淘宝正式网络方案。IDE 中导入本目录并关联自己的 AppKey。桌面模拟器是否允许访问回环地址需以实际 IDE 为准；手机上的127.0.0.1指向手机自身。

## 文件职责

首页右上角“开发调试 · 相机验收”可直接进入相机页，不依赖淘宝登录、本地后端或网络。也可在IDE启动参数中指定页面 `pages/camera/camera`、参数 `debug=camera`。入口需要同时满足 `config.js` 中 `environment: 'development'`、`cameraDebug: true`、本机直连配置；改为正式/cloud配置后入口关闭，单独拼参数也不能绕过登录。

验收时先开启相机，按正脸→右脸→左脸拍摄/确认，第三张完成后仅在本页验证JPEG压缩并展示三张原始预览与压缩尺寸，不发检测请求、不生成报告、不播放远程语音，也不会写入正式档案/报告状态。临时预览用于检查前置照片方向；页面不判断拍摄姿态是否合格。退出时清空本页照片引用。

依次检查：首次授权、拒绝后相册仍可使用、授权设置恢复、前后镜头、三张方向、切后台恢复、压缩最长边≤1280。真实系统权限和相机画面仍需淘宝IDE/手机验收，自动测试仅验证代码流程。

- `pages/splash`：协议同意、淘宝授权登录、退出和历史入口。
- `pages/profile`：账号隔离的基础信息缓存、出生年月和省市滚轮、肤质选择。
- `pages/camera`：手动三步拍摄/预览确认；离页取消、重复点击保护；单画布顺序压缩成最长边1280的 JPEG。
- `pages/report`：服务端返回的当前评分/话术、七项分析、护理选三、精华、真实图层和坐标标注；侧脸图层异步加载。
- `pages/history`：本人最近5份完整报告。
- `utils/transport.js`：本机代理或淘宝云 SDK 传输，保留反代子路径配置。
- `utils/api.js`：账号凭据、64KiB照片分片、检测任务提交与轮询、历史报告。
- `vendor/`：从 H5 同步的评分、报告呈现、文案及哈希清单，不手工修改。
- `scripts/`、`test/`、`docs/`：开发与回归文件，IDE 配置排除上传。

H5 规则变更后运行 `npm run sync:shared`；`npm run check:shared` 会检查逐字节一致。在线报告优先使用服务端返回的 `vm/presentation`，原始检测分数和展示肌龄分别保存。

## 账号与共享后端

正式淘宝请求走 `cloud.application.httpRequest`。登录分两步：先获取60秒一次性 challenge，再发送经网关签名、含 challenge 与同意标记的登录请求。服务端验证全部查询参数和原始请求体的签名，从网关注入的 `open_id` 建立 `kind: taobao` 的稳定账号；不依赖前端上报身份。账号键保存为 appKey/openId 的哈希。

淘宝使用独立 Bearer 会话，微信继续使用原有 Cookie。两种会话不能互换。共用 `accounts` 存储和报告格式，按服务端身份隔离历史、图片上传、检测任务和侧脸标注。

新检测记录自动标记 `h5` 或 `taobao`，不信任请求体中的 `channel`。历史没有该字段的记录视为 H5。管理 API 支持 `?channel=taobao` 筛选；统计返回 `by_channel`；CSV在末尾追加渠道列，旧列的位置保持不变。后台页面本轮没有改布局。

## 云网关接入准备

这里仅说明未来配置，不会自动部署。

1. 关联淘宝 AppKey 与外部云应用，配置域名与资源域名权限。
2. 只在后端环境配置 `TAOBAO_APP_KEY`、`TAOBAO_APP_SECRET`；Face++ 密钥沿用现有服务端设置。所有 Secret 均不得进入小程序代码。
3. `config.js` 设置 `environment: 'production'`、`cameraDebug: false`、`transport: 'cloud'`、HTTPS `baseUrl`、`cloudAppId`、资源 `assetBase`。如果使用原来的 `/state/` 反代入口，设置 `basePath: '/state'`，资源根同时包含 `/state/assets/`。
4. 外部/空应用 `cloudEnv` 为 `online`，这表示淘宝网关的环境，和本次是否部署生产服务器无关。
5. 真实淘宝授权确认后才能创建账号。当前尚未填入真实 AppKey/Secret/cloudAppId，也没有宣称已完成真实平台联调。

云网关单次请求内容上限128KB、外部服务超时最多10秒。照片按64KiB base64顺序上传，每个用户的照片只可消费一次；检测与侧脸标注均用短请求提交、轮询结果，不能直接把三张大图发进一个45秒请求。中断轮询不会自动重复付费检测，已完成结果可在历史报告中读取。

官方依据：

- [外部/空应用调用标准、128KB、10秒、响应封装](https://developer.alibaba.com/docs/doc.htm?articleId=121864&docType=1&treeId=836)
- [外部服务请求签名算法](https://developer.alibaba.com/docs/doc.htm?articleId=121746&docType=1&treeId=832)
- [服务端获取平台OpenId](https://developer.alibaba.com/docs/doc.htm?articleId=121213&docType=1&treeId=804)
- [淘宝小程序外发请求接入说明](https://developer.alibaba.com/docs/doc.htm?articleId=121954&docType=1&treeId=842)

## 自动验证

```powershell
npm run check:shared
npm test
npx playwright install chromium
npm run test:h5
```

`npm test` 覆盖验签和重放、账号与历史隔离、照片分片与过期、异步检测、渠道筛选/CSV兼容、评分与七项话术、拍摄竞态、图片尺寸和省市联动。检测上游均为固定样本，不消耗线上检测额度。

`npm run test:h5` 运行现有 H5 的四组浏览器测试，覆盖游客不留存、HTTPS `/state/` 微信授权/退出/跨设备、完整报告/后台/CSV，以及异步侧脸图层。使用本地 Playwright，不改写旧测试；Windows上自动使用已安装 Git 附带的 OpenSSL。截图保存至 `../temp/taobao-h5-compatibility/`。

## 待平台验收

开发账号采用独立淘宝账号，由公司主账号管理员将其加入目标小程序的开发成员。公司完成主体认证、开发者入驻及应用创建；开发人员按后台要求完成个人账号认证，获得开发权限后再登录IDE关联应用。不能把店铺子账号的应用使用权限当作小程序开发权限，也不能只添加为体验者。当前账号尚未就绪，以下平台验收未完成。

相机权限单独处理：进入拍摄页先查询 `my.getSetting`；首次使用由用户点击“开启相机”后调用 `my.authorize({ scopes: 'scope.camera' })`，授权后再挂载原生camera组件。拒绝后保留相册路径，并提供用户主动打开 `my.openSetting` 的入口，不循环申请。相册选择使用独立的 `scope.album`；淘宝账号登录的 `scope.userInfo` 不代表相机已获授权。`app.json` 中的用途描述也不代表授权完成。平台控制台仍需确认对应权限包，并在“开发设置-scope授权项管理”填写用途。手机系统对淘宝App的相机/相册权限同样需要真机验证。

参考：[淘宝用户授权、权限范围与拒绝后的设置入口](https://developer.alibaba.com/docs/doc.htm?articleId=119119&docType=1&treeId=776)、[淘宝camera组件与CameraContext API](https://developer.alibaba.com/docs/doc.htm?articleId=120279&docType=1&treeId=776)。

- 真实 AppKey/cloudAppId、签名参数和授权权限包联调。
- 真实网关传输报告大图时的返回体限制与内存占用；已减少小程序 `setData` 中重复照片和非当前Tab图层。
- Android/iOS相机权限、前置相片方向、cover-view覆盖、系统相机降级、后台恢复、原生canvas及大图读取。
- UI真机对齐。当前相机使用椭圆框和左右转头提示，尚未迁移H5精确取景轮廓与实时姿态自动拍摄。
- 商品跳转尚需真实商品ID与平台能力验收；当前报告展示推荐产品，没有伪造商品链接。

以上是待真实平台验收的范围，不影响已通过的本地接口与H5回归结论。