129 lines
16 KiB
Markdown
129 lines
16 KiB
Markdown
## 2026-11-03 正式包开发入口清理
|
||
|
||
正式路由仅保留登录、主页、档案、拍照、报告和历史六页。`pages/mvp`、`pages/camtest`、`pages/camnative` 已从 app.json 移除，并同时加入编译和上传排除项；开发测试源码保留供离线回归，不随正式包注册或上传。登录和主页的开发入口、诊断弹层、对应处理方法与样式已清理。主拍照页 `?debug=local-face` 还必须显式启用 cameraDebug，当前配置为 false。
|
||
|
||
“重新开启相机”是实际失败后的恢复入口，不是测试按钮：只在真实错误／权限提示下显示，登录校验、初次启动、预览、拍摄完成过渡和报告处理中隐藏；点击重试时先清除旧错误，失败再恢复提示。没有增加自动重试，也没有改变相机方向、角度、识别后端、照片顺序、亮度门限或 1.5 秒新鲜度限制。
|
||
|
||
# 淘宝小程序开发说明
|
||
|
||
用户已确认自动三连拍在当前手机通过，正式业务配置已恢复 `photoInputMode: 'camera'`，使用与测试页相同的识别和自动拍照逻辑；原相册入口保留。UI 和交互保持原样，不新增上传面板。若需独立排查选图上传，仍可临时设为 `'upload'` 跳过实时识别。淘宝专用 Node 已备份并更新新版游客及幂等接口，云服务访问异常及实际手机三图报告仍需验收。
|
||
|
||
正式入口：登录／游客 → 开始检测 → 原隐私弹窗 → 档案 → 拍照引导的“开始” → 自动三连拍 → 上传及报告。首次使用时衔接平台相机授权，无需先进入开发测试页。游客和正式账号的多页面集成回归均已覆盖，测试服务响应不代表真实云网关已通过。
|
||
|
||
页面按 H5 还原：报告检测图区域支持左右跟手滑动切换页卡，标签和高度同步；点检测图可放大，再点关闭；档案肤质卡支持跟手横滑、箭头和圆点联动。正常页面隐藏开发诊断入口，主页保留“开始检测／我的报告”，报告页不附加额外按钮。专项诊断时可在开发环境临时启用 `cameraDebug:true` 显示测试入口。
|
||
|
||
当前适配：独立登录首屏（淘宝账号／游客）→ 基础档案 → 正／右／左三步拍摄或相册选图 → 检测等待 → 七项报告 → 对应商品。正式淘宝账号保留最近 5 份历史；游客会话、档案和报告仅本次内存使用。商品 I／II／III 统一打开 `1090510453077`，推荐规则沿用 H5。
|
||
|
||
**首版要求实时识别抓拍。** 当前默认采用普通 `camera` 前置取景及连续帧，在本机运行人脸定位和轻量 68 点模型，复用 H5 姿态及稳定性判断，倒计时后用原生 `takePhoto` 获取 JPEG。用户已验证普通相机默认前置、帧数增加、可以拍照出图；手机已识别人脸并通过正脸姿态，但优化后的 CPU 单帧仍约 4.25 秒。当前候选改用原生 WebGL 加速，需通过数值自测、预热后再处理真实帧；手机兼容性、速度和自动三连拍仍待验收。AR 路线保留为显式开发对照，其默认自拍修正尚未通过真机验证。诊断页面保留在开发源码中，已移出正式路由及上传包。诊断不登录、不上传、不产生检测费用。
|
||
|
||
本轮实施状态、验收和部署顺序见 [适配交接](../docs/TAOBAO-ADAPTATION-2026-11-02.md)。
|
||
|
||
开发版“相机测试（开发版）”现直接进入 `CAM-NATIVE-20261102-04`，点顶部“开始自动三连拍测试”可进入 `LOCAL-FACE-20261102-09`。该页复用正式取景、实时识别、正／右／左自动拍摄及 JPEG 压缩，最后只展示本页临时照片，不要求账号或档案、不上传照片、不创建检测任务。卡住时点“复制识别诊断”，只复制模型阶段、耗时、帧尺寸、计数、安全错误代码及固定合成输入的图形自测指标，不复制图像或人脸坐标。测试页不播放语音；应用自身已有的静态资源加载及账号恢复不受这个页内模式控制。
|
||
|
||
手机在旧版 `LOCAL-FACE-20261102-01` 已识别 1 脸并通过姿态，CPU 优化版 `02` 从约 10.7 秒降至 4.25 秒，仍因结果过期停止，尚未完成自动抓拍。版本 `03` 明确请求原生 WebGL1，并按淘宝官方文档开启 `window.enableSkia:"true"`；手机矩阵自测执行 4 次绘制后报 `MATMUL_FAILED`。版本 `04` 依次验证 `default`、`packed_byte`（禁用浮点下载）和 `unpacked_byte`（再禁用打包 shader），真机三档均失败。最后一档记录 5 次绘制、1 次字节读回，矩阵校验和 0／预期 2786、244 项不匹配、最大误差 22，呈现全零特征；这些聚合指标尚不能单独证明全部元素为零或确定根因，仍未处理真实相机帧。
|
||
|
||
版本 `05` 按[淘宝官方说明](https://developer.alibaba.com/docs/doc.htm?articleId=121761&docType=1&treeId=829)关闭 `readPixels` 的宿主额外翻转，并增加 2×2 原生图形检查。手机清屏读回通过，非对称 shader 有 3 项不匹配，预期校验和 2244／实际 2040；实际值与此前清屏校验和相同。这与绘制未覆盖的情况一致，也可能来自坐标、缓冲区上传或绘制状态，尚不能唯一确定根因，仍未处理真实相机帧。
|
||
|
||
版本 `06` 显式规范化 GL 绘制状态，每次绘制前清黑，先分别验证恒色 `drawArrays`／索引绘制，再验证原非对称 shader 和字节／浮点纹理。原生兼容候选按 `standard` → `buffer_copy`（将视图字节紧密拷贝为标准 `bufferData` ArrayBuffer）→ `framebuffer_y`（仅补偿已绑定 FBO 的 viewport／scissor Y 坐标）→ `combined` 自测；仅 `VALUE_MISMATCH` 允许换路，其他错误停止。四路使用同一上下文，每路结束清理自己的检查对象；TF 三档选择最多创建 3 个上下文。每条可用路径都须通过全部原生检查及后续严格矩阵／卷积自测、真实模型预热，不能按机型硬开，也不放宽 1.5 秒源帧新鲜度或回退 CPU。诊断保留原始失败阶段／代码、最终 `nativeStrategy`、固定合成的四像素及缓冲区字节数，仅初始化时缓存；真实人脸结果不能覆盖。手机实际选路、识别速度和三连拍仍待验收。
|
||
|
||
当前候选 `07` 针对真机 `06` 的 `nativeInitialStage=constant_indexed`：标准路径普通恒色绘制已通过，索引绘制失败；最后的坐标兼容黑屏不代表原始根因。原生索引调用前先重新绑定索引缓冲。若仍然是普通绘制通过而索引数值失败，则验证等价的四顶点 `TRIANGLE_STRIP` 路径；通过非对称图案、纹理、原矩阵／卷积和模型预热后才使用。仅把自有固定索引 `[0,1,2,2,1,3]`、`TRIANGLES/6/UNSIGNED_SHORT/offset0` 转换，未知签名、缓冲未确认或部分修改时明确拒绝。诊断新增 `drawStrategy=quad_strip`、实际绘制计数和 `constantQuad`；此时 `constantIndexed=not_run`，不宣称原生索引已通过。原生候选最多 8 次、仍使用同一上下文，手机效果与速度待验收。
|
||
|
||
此入口仅在 `environment: 'development'`、`captureMode: 'native-face'`、`nativeCamera: true` 时开放，允许当前 cloud 配置；`debug=local-face` 参数不能在生产环境绕过登录。原来的 `debug=camera` 手动验收仍要求显式 `cameraDebug` 开关及本机直连，不变更其范围。
|
||
|
||
## 本地启动
|
||
|
||
在本目录运行：
|
||
|
||
```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` 默认是 `cloud`／`tower`／`test`，使用聚石塔云网关。仅做本机样本联调时手动切换到 `transport: 'direct'`、`baseUrl: 'http://127.0.0.1:18180'`；结束后恢复云配置。代理为正式和游客会话签名，不绕过后端校验。手机上的 127.0.0.1 指向手机自身。
|
||
|
||
## 文件职责
|
||
|
||
首页右上角“开发调试 · 相机验收”可直接进入相机页，不依赖淘宝登录、本地后端或网络。也可在IDE启动参数中指定页面 `pages/camera/camera`、参数 `debug=camera`。入口需要同时满足 `config.js` 中 `environment: 'development'`、`cameraDebug: true`、本机直连配置；改为正式/cloud配置后入口关闭，单独拼参数也不能绕过登录。
|
||
|
||
验收时先开启相机，按正脸→右脸→左脸拍摄/确认，第三张完成后仅在本页验证JPEG压缩并展示三张原始预览与压缩尺寸，不发检测请求、不生成报告、不播放远程语音，也不会写入正式档案/报告状态。临时预览用于检查前置照片方向；页面不判断拍摄姿态是否合格。退出时清空本页照片引用。
|
||
|
||
依次检查：首次授权、拒绝后相册仍可使用、授权设置恢复、前后镜头、三张方向、切后台恢复、压缩最长边≤1280。真实系统权限和相机画面仍需淘宝IDE/手机验收，自动测试仅验证代码流程。
|
||
|
||
- `pages/login`：淘宝／游客登录、协议、登录恢复，以及仅开发版显示的 AR 测试入口。
|
||
- `pages/splash`：品牌首页、开始检测、历史、退出／结束游客体验。
|
||
- `pages/profile`：账号隔离的基础信息缓存、出生年月和省市滚轮、肤质选择。
|
||
- `pages/camera`：普通前置相机本地实时识别、正／右／左三步引导、H5 轮廓及定位线、自动倒计时和原生 JPEG 拍摄；保留 AR 开发对照、完成卡与扫描等待页。相册路径拍后直接推进；单画布顺序压缩最长边 1280 的 JPEG；暂停后复用原分析任务，不重新收费。
|
||
- `pages/report`：服务端返回的当前评分/话术、七项分析、护理选三、精华、真实图层和坐标标注；侧脸图层异步加载。
|
||
- `pages/history`：本人最近5份完整报告。
|
||
- `utils/transport.js`：本机代理或淘宝云 SDK 传输，保留反代子路径配置。
|
||
- `utils/api.js`：账号凭据、64KiB照片分片、检测任务提交与轮询、历史报告。
|
||
- `vendor/`：从 H5 同步的评分、报告呈现、拍照规则及哈希清单；`native-face/` 为从 H5 原始模型生成的小程序 CPU 副本，含来源记录。分别使用共享同步脚本和 `node scripts/build-native-face.cjs` 重建，不手工改生成文件。
|
||
- `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 取景轮廓及实时姿态自动拍摄已接入本地代码，仍需在手机验证定位、左右转头提示、识别耗时和完整三连拍。
|
||
- 商品目标已确认：`1090510453077`（1'me以我自在有势挺括双仓精华液）。仍需验证平台能力、游客／新报告／历史报告跳转及返回状态。
|
||
|
||
以上是待真实平台验收的范围，不影响已通过的本地接口与H5回归结论。
|