juzi/taobao

淘宝小程序开发说明

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

本地启动

在本目录运行：

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秒、响应封装
• 外部服务请求签名算法
• 服务端获取平台OpenId
• 淘宝小程序外发请求接入说明

自动验证

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的相机/相册权限同样需要真机验证。

参考：淘宝用户授权、权限范围与拒绝后的设置入口、淘宝camera组件与CameraContext API。

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

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