docs(gateway): 补充客户端鉴权与42/52/72接入示例

static/integration.html

@@ -3,7 +3,7 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<title>旷视五接口 — 前端接入说明</title>
+<title>旷视接口 — 客户端接入说明</title>
 <style>
   * { box-sizing: border-box; margin: 0; padding: 0; }
   body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; background: #f8f9fb; color: #1e293b; line-height: 1.6; }
@@ -33,6 +33,10 @@
   .endpoint .url { font-size: 15px; font-weight: 700; margin-bottom: 6px; }
   .endpoint .desc { color: #64748b; font-size: 13px; margin-bottom: 10px; }
   .endpoint .params { font-size: 12px; color: #94a3b8; margin-bottom: 8px; }
+  .guide-step { margin-top: 18px; }
+  .guide-step h3 { font-size: 15px; margin-bottom: 5px; }
+  .guide-step p, .guide-step pre { margin-bottom: 8px; }
+  .guide-list { padding-left: 22px; margin-top: 8px; }
 
   .link { color: #2563eb; text-decoration: none; font-size: 13px; }
   .link:hover { text-decoration: underline; }
@@ -46,18 +50,21 @@
 </head>
 <body>
 <div class="wrap">
-  <h1>📡 旷视五接口 — 前端接入说明</h1>
+  <h1>📡 旷视接口 — 客户端接入说明</h1>
   <p class="subtitle">Base URL: <code>https://hair.xiangsilian.com</code> &nbsp;|&nbsp; 在线文档: <a href="/docs" class="link">/docs</a> &nbsp;|&nbsp; 在线测试页见底部</p>
 
   <div class="toc">
     <a href="#overview">通用约定</a>
+    <a href="#client-auth">42／52／72 鉴权</a>
     <a href="#if1">接口1</a>
     <a href="#if2">接口2</a>
     <a href="#if3">接口3</a>
     <a href="#if4">接口4</a>
+    <a href="#if42">接口42</a>
     <a href="#if5">接口5</a>
     <a href="#if52">接口52</a>
     <a href="#if6">接口6</a>
+    <a href="#if72">接口72</a>
     <a href="#errors">错误码</a>
     <a href="#test">在线测试</a>
   </div>
@@ -68,9 +75,10 @@
     <div class="card-body">
       <table>
         <tr><td>协议</td><td>HTTPS</td></tr>
-        <tr><td>请求方式</td><td>全部 <span class="badge post">POST</span></td></tr>
+        <tr><td>请求方式</td><td>业务接口使用 POST。验证令牌使用 GET。</td></tr>
         <tr><td>编码</td><td>UTF-8</td></tr>
-        <tr><td>Content-Type</td><td><code>multipart/form-data</code></td></tr>
+        <tr><td>Content-Type</td><td>传图使用 <code>multipart/form-data</code>，登录和刷新使用 <code>application/json</code></td></tr>
+        <tr><td>客户端鉴权</td><td>仅 42、52、72 需要 <a class="link" href="#client-auth">Bearer 访问令牌</a>。其他原有业务接口沿用现有接入方式。</td></tr>
         <tr><td>图片参数</td><td>三选一：<code>image_file</code>（文件上传）/ <code>image_url</code>（URL）/ <code>image_base64</code>（base64 + 前缀）</td></tr>
         <tr><td>图片格式</td><td>JPG / PNG，单人正面照</td></tr>
         <tr><td>请求体上限</td><td><strong>2MB</strong>（nginx 层限制）。超限直接返回 HTTP <strong>413</strong>，不会进入业务逻辑。建议图片文件 ≤1MB；<code>image_base64</code> 传图会膨胀约 33%，编码前原图建议 ≤1.4MB。手机直拍照片通常 3~8MB，<strong>上传前务必先压缩</strong>（如最长边缩到 1500px、JPEG 质量 80）。<code>image_url</code> 方式图片在远端，不受此限制</td></tr>
@@ -86,6 +94,50 @@
     </div>
   </div>
 
+  <div class="card" id="client-auth">
+    <h2>42／52／72 客户端鉴权</h2>
+    <div class="card-body">
+      <p>使用同一个访问令牌调用 <a href="#if42">42</a>、<a href="#if52">52</a> 和 <a href="#if72">72</a>。账号为 <code>yonghe</code>，密码由对接人员提供。客户端请求只需发送 <code>Authorization: Bearer &lt;access_token&gt;</code>。</p>
+
+      <div class="guide-step">
+        <h3>1. 登录获取令牌</h3>
+        <pre>BASE_URL=https://hair.xiangsilian.com
+curl -sS -X POST "$BASE_URL/api/v1/auth/login" \
+  -H 'Content-Type: application/json' \
+  -d '{"username":"yonghe","password":"&lt;对接密码&gt;"}'</pre>
+        <p>成功返回 HTTP 200 且 <code>code=0</code>，<code>data</code> 的结构如下：</p>
+        <pre>{
+  "access_token": "&lt;访问令牌&gt;",
+  "token_type": "Bearer",
+  "expires_in": 900,
+  "refresh_token": "&lt;刷新令牌&gt;",
+  "refresh_expires_in": 604800
+}</pre>
+        <p>有效期以秒为单位，访问令牌 15 分钟，刷新令牌 7 天。将响应里的令牌分别赋值给下方示例的 <code>ACCESS_TOKEN</code> 和 <code>REFRESH_TOKEN</code>。</p>
+      </div>
+
+      <div class="guide-step">
+        <h3>2. 验证令牌并发起业务请求</h3>
+        <pre>curl -i "$BASE_URL/api/v1/auth/check" \
+  -H "Authorization: Bearer $ACCESS_TOKEN"</pre>
+        <p>有效时返回 HTTP 200 和 <code>code=0</code>。缺少令牌、令牌无效或已过期时返回 HTTP 401 和 <code>code=1009</code>。业务请求使用同一个请求头，图片字段在 <code>image_file</code>、<code>image_url</code>、<code>image_base64</code> 中三选一。</p>
+      </div>
+
+      <div class="guide-step">
+        <h3>3. 刷新并重试</h3>
+        <pre>curl -sS -X POST "$BASE_URL/api/v1/auth/refresh" \
+  -H 'Content-Type: application/json' \
+  -d "{\"refresh_token\":\"$REFRESH_TOKEN\"}"</pre>
+        <ol class="guide-list">
+          <li>访问令牌到期前可主动刷新。业务请求返回 HTTP 401 且 <code>code=1009</code> 时，也可刷新一次。</li>
+          <li>刷新成功后，用返回的 <code>data.access_token</code> 和 <code>data.expires_in</code> 更新本地状态，再用新令牌重试原请求一次。</li>
+          <li>刷新响应不含新刷新令牌，继续使用登录时的 <code>refresh_token</code>，直到它的原有效期结束。刷新返回 401 时，清除令牌并重新登录。</li>
+        </ol>
+        <p>登录或刷新返回 HTTP 503 且 <code>code=1007</code> 时，请联系网关维护人员检查令牌服务配置。</p>
+      </div>
+    </div>
+  </div>
+
   <!-- ======== 接口1 ======== -->
   <div class="card" id="if1">
     <h2>1. 四庭七眼测量 &nbsp;<span class="badge post">POST</span> &nbsp;<code>/api/v1/face/measure</code></h2>
@@ -224,6 +276,26 @@ console.log(features.gene_style);   // "自然型"</pre>
     </div>
   </div>
 
+  <div class="card" id="if42">
+    <h2>42. 用户特征与两项判定 <span class="badge post">POST</span> <code>/api/v1/face/features-42</code></h2>
+    <div class="card-body">
+      <p class="desc">接收一张照片。先检查人脸是否完整及俯拍角度，再扶正裁切，返回接口 4 的特征与两项判定。需要 <a href="#client-auth">访问令牌</a>。</p>
+      <pre>curl -sS "$BASE_URL/api/v1/face/features-42" \
+  -H "Authorization: Bearer $ACCESS_TOKEN" \
+  -F 'image_file=@portrait.jpg'</pre>
+      <p><code>data.features</code> 是 JSON 字符串。成功后先执行 <code>JSON.parse(response.data.features)</code>，再读取以下字段：</p>
+      <table>
+        <tr><th>字段</th><th>说明</th></tr>
+        <tr><td><code>face_shape</code>、<code>eyebrow_shape</code>、<code>facial_age</code>、<code>dynamic_static_type</code>、<code>gender</code>、<code>gene_style</code>、<code>contour_type</code></td><td>沿用接口 4 的面部特征</td></tr>
+        <tr><td><code>zygoma_expansion</code></td><td>颧弓外扩</td></tr>
+        <tr><td><code>temple_hollowing</code></td><td>太阳穴凹陷</td></tr>
+      </table>
+      <p>新增字段均为 <code>true</code>（命中）、<code>false</code>（未命中）或 <code>null</code>（无法测量）。两项在 <code>Ft ÷ Zy &lt; 0.8</code> 时同时命中。</p>
+      <p>未检测到人脸返回 <code>1001</code>。脸部不完整、俯拍过大或无法扶正裁切均返回 <code>1003</code>，具体重拍提示见 <code>message</code>。质检不通过时 <code>data</code> 为 <code>null</code>。</p>
+      <p><a href="/static/test_interface42.html" class="link">42 号登录与特征测试页</a></p>
+    </div>
+  </div>
+
   <!-- ======== 接口5 ======== -->
   <div class="card" id="if5">
     <h2>5. 发际线 PNG 生成 &nbsp;<span class="badge post">POST</span> &nbsp;<code>/api/v1/hairline/generate</code></h2>
@@ -270,12 +342,28 @@ console.log(features.gene_style);   // "自然型"</pre>
   <div class="card" id="if52">
     <h2>52. 发际线新规则与裁切 &nbsp;<span class="badge post">POST</span> &nbsp;<code>/api/v1/hairline/generate-52</code></h2>
     <div class="card-body">
-      <p>42、52、72 统一使用 <code>Authorization: Bearer &lt;access_token&gt;</code>。通过 <code>POST /api/v1/auth/login</code> 登录，访问令牌有效 15 分钟，可通过 <code>POST /api/v1/auth/refresh</code> 刷新。缺少或无效时返回 HTTP 401、code 1009。</p>
-      <p><a href="/static/test_interface42.html" class="link">42 号特征测试</a> · <a href="/static/test_interface72.html" class="link">72 号关键点测试</a></p>
-      <p class="desc">网关透传至GPU worker执行。中下庭均值定位 middle，支持9→152扶正、人像裁切和矩形发际线预览。接口5保留原有三档实现；新功能使用此独立接口。</p>
-      <p>基础图片参数、<code>gender</code>、<code>hair_style</code>、<code>use_mask</code>、<code>prompt</code>、<code>generate_grow_image</code>沿用接口5。新增可选<code>normalize_image</code>，默认false，传true开启扶正与裁切；测试页显式开启。</p>
-      <p style="margin-top:12px">非空图片返回<code>*_url</code>，空图片沿用<code>*_base64: null</code>。另有<code>height_rule</code>、<code>framing</code>、<code>guide_landmarks</code>、原图及处理后底图。middle和坐标使用当前底图，high/low字段为null。标准裁切高约3.3333L、宽2.5L；长图在保留人脸的前提下裁为3:4。</p>
-      <p style="margin-top:12px"><a href="/static/test_interface52.html" class="link">52号规则测试页</a></p>
+      <p class="desc">中下庭均值定位 middle，支持扶正裁切与生发。需要 <a href="#client-auth">访问令牌</a>。以下示例开启扶正裁切，只获取预览：</p>
+      <pre>curl -sS "$BASE_URL/api/v1/hairline/generate-52" \
+  -H "Authorization: Bearer $ACCESS_TOKEN" \
+  -F 'image_file=@portrait.jpg' \
+  -F 'gender=female' \
+  -F 'hair_style=1,3' \
+  -F 'normalize_image=true' \
+  -F 'generate_grow_image=false'</pre>
+      <table>
+        <tr><th>参数</th><th>说明</th></tr>
+        <tr><td>图片字段</td><td>三选一，见通用约定。</td></tr>
+        <tr><td><code>gender</code>、<code>hair_style</code></td><td>必填。性别为 <code>female</code> 或 <code>male</code>，发型序号为 1–7，支持逗号分隔。</td></tr>
+        <tr><td><code>normalize_image</code></td><td>可选，默认 <code>false</code>。传 <code>true</code> 启用扶正裁切。</td></tr>
+        <tr><td><code>generate_grow_image</code></td><td>可选，默认 <code>true</code>。只看设计曲线时传 <code>false</code>。</td></tr>
+        <tr><td><code>use_mask</code>、<code>prompt</code></td><td>可选，沿用接口 5 的遮罩和提示词参数。</td></tr>
+      </table>
+      <ul class="guide-list">
+        <li>用 <code>data.input_image_url</code> 显示当前底图，将每个发型的 <code>data.hairline_images[].image_middle_url</code> 按同尺寸叠加。中心点和 <code>guide_landmarks</code> 也使用当前底图坐标。</li>
+        <li><code>original_image_url</code> 是处理前图片。需要映射坐标时，使用 <code>framing</code> 中的双向矩阵。</li>
+        <li>生发成功时直接显示 <code>grown_image_url</code>。空图片保留为 <code>*_base64: null</code>，high／low 已停用。</li>
+      </ul>
+      <p style="margin-top:12px"><a href="/static/test_interface52.html" class="link">52 号登录与发际线测试页</a></p>
     </div>
   </div>
 
@@ -311,6 +399,24 @@ console.log(features.gene_style);   // "自然型"</pre>
     </div>
   </div>
 
+  <div class="card" id="if72">
+    <h2>72. B 端五个关键点 <span class="badge post">POST</span> <code>/api/v1/face/b-end-points</code></h2>
+    <div class="card-body">
+      <p class="desc">接收一张正面照，返回扶正底图和透明标注层。标注包含 6 个白点、4 条虚线和 4 段厘米数。需要 <a href="#client-auth">访问令牌</a>。</p>
+      <pre>curl -sS "$BASE_URL/api/v1/face/b-end-points" \
+  -H "Authorization: Bearer $ACCESS_TOKEN" \
+  -F 'image_file=@portrait.jpg'</pre>
+      <table>
+        <tr><th>data 字段</th><th>客户端用法</th></tr>
+        <tr><td><code>input_image_url</code>、<code>annotated_image_url</code></td><td>分别为扶正裁切后的底图和透明 PNG 标注层。两图使用同一个容器、相同缩放和位置进行叠加。</td></tr>
+        <tr><td><code>points</code></td><td>键为 <code>"1"</code> 到 <code>"6"</code>，值为 <code>{x, y}</code>。使用 <code>image_size.width</code> 和 <code>image_size.height</code> 缩放至显示尺寸。</td></tr>
+        <tr><td><code>measurements_cm</code></td><td>键为 <code>2-1</code>、<code>2-3</code>、<code>4-6</code>、<code>5-6</code>。值为厘米数，界面使用一位小数。</td></tr>
+        <tr><td><code>coordinate_space</code>、<code>px_per_cm</code></td><td>坐标系为 <code>processed_image</code>，<code>px_per_cm</code> 为每厘米估算像素数。</td></tr>
+      </table>
+      <p style="margin-top:12px"><a href="/static/test_interface72.html" class="link">72 号登录与标注测试页</a></p>
+    </div>
+  </div>
+
   <!-- ======== 错误码 ======== -->
   <div class="card" id="errors">
     <h2>⚠ 错误码</h2>
@@ -325,10 +431,10 @@ console.log(features.gene_style);   // "自然型"</pre>
 
         <tr><td>1007</td><td>图片参数错误 / 后端不可用</td><td>参数传错 / 服务繁忙请稍后重试</td></tr>
         <tr><td>1008</td><td>图片格式不支持</td><td>非 JPG/PNG / base64 解码失败</td></tr>
-        <tr><td>1009</td><td>未授权</td><td>缺少或错误的 <code>X-Internal-Token</code>（<code>/api/*</code> 路径鉴权）</td></tr>
+        <tr><td>1009</td><td>未授权</td><td>HTTP 401。登录凭据错误，或 42／52／72 所需的令牌缺失、无效或过期。按 <a href="#client-auth">鉴权流程</a> 处理。</td></tr>
       </table>
       <p style="font-size:12px;color:#94a3b8;margin-top:8px">注：1004 仍在使用（接口2/5 的 gender 校验）；接口7（grow-v2）已弃用，请改用接口2。</p>
-      <p style="font-size:12px;color:#dc2626;margin-top:8px">⚠ <strong>HTTP 层错误不是业务 JSON</strong>：业务错误（code≠0）一律返回 HTTP 200；但请求体超 2MB 时 nginx 直接返回 <strong>413</strong>（HTML 错误页）、网关不可用时返回 502/504。客户端务必先判断 HTTP 状态码，非 200 时不要 <code>res.json()</code>，否则会报 <code>Unexpected token '&lt;'</code>（把 HTML 当 JSON 解析）。</p>
+      <p style="font-size:12px;color:#dc2626;margin-top:8px">先检查 HTTP 状态和 <code>Content-Type</code>，再解析 JSON。HTTP 200 仍需检查 <code>code</code>，只有 <code>0</code> 表示成功。HTTP 401 的 JSON 用于鉴权提示与刷新。上传超限可能返回 HTTP 413，网关异常可能返回 502／504，这些响应可能是 HTML。</p>
     </div>
   </div>
 
@@ -342,8 +448,10 @@ console.log(features.gene_style);   // "自然型"</pre>
         <tr><td>2. C端生发</td><td><a href="/static/test_interface2.html" class="link">/static/test_interface2.html</a></td><td>上传+性别 → 方案一覧（原图/叠加/生发），双图对比</td></tr>
         <tr><td>3. B端生发</td><td><a href="/static/test_interface3.html" class="link">/static/test_interface3.html</a></td><td>划线图上传 → 生发效果图</td></tr>
         <tr><td>4. 用户特征</td><td><a href="/static/test_interface4.html" class="link">/static/test_interface4.html</a></td><td>上传照片 → 7项面部特征 + 原始JSON</td></tr>
+        <tr><td>42. 用户特征与两项判定</td><td><a href="/static/test_interface42.html" class="link">/static/test_interface42.html</a></td><td>登录、测试鉴权、刷新令牌、上传照片</td></tr>
         <tr><td>5. 发际线PNG</td><td><a href="/static/test_interface5.html" class="link">/static/test_interface5.html</a></td><td>上传+性别 → 发际线方案+中心点坐标</td></tr>
-        <tr><td>52. 发际线新规则</td><td><a href="/static/test_interface52.html" class="link">/static/test_interface52.html</a></td><td>中下庭定位、扶正裁切、矩形叠加与生发</td></tr>
+        <tr><td>52. 发际线新规则</td><td><a href="/static/test_interface52.html" class="link">/static/test_interface52.html</a></td><td>登录、测试鉴权、刷新令牌、发际线预览与生发</td></tr>
+        <tr><td>72. B 端五个关键点</td><td><a href="/static/test_interface72.html" class="link">/static/test_interface72.html</a></td><td>登录、测试鉴权、刷新令牌、关键点和虚线标注</td></tr>
         <tr><td>6. 四庭七眼 v2</td><td><a href="/static/test_interface6.html" class="link">/static/test_interface6.html</a></td><td>同接口1，去顶庭 · 竖线发际线→下巴 · 无头部端线</td></tr>
         <tr><td>9. 头发遮罩</td><td><a href="/static/test_interface9.html" class="link">/static/test_interface9.html</a></td><td>上传照片 → 头发遮罩 + 分步可视化</td></tr>
         <tr><td>10. 外缘膨胀带</td><td><a href="/static/test_interface10.html" class="link">/static/test_interface10.html</a></td><td>上传照片 → 头部外缘带状遮罩 + 分步可视化</td></tr>