docs(gateway): 完善接口22前端接入说明

static/integration.html

@@ -223,12 +223,54 @@ const { code, data } = await res.json();
   <div class="card" id="if22">
     <h2>22. 生发密度与发际线高度 &nbsp;<span class="badge post">POST</span> &nbsp;<code>/api/v1/hair/grow-22</code></h2>
     <div class="card-body">
-      <p>使用 <a href="#client-auth">Bearer 访问令牌</a>。图片字段三选一，发型序号男女均为 1–7。</p>
-      <pre>curl -sS "$BASE_URL/api/v1/hair/grow-22" \
-  -H "Authorization: Bearer $ACCESS_TOKEN" \
-  -F "image_file=@./portrait.jpg" -F "gender=female" -F "hair_style=1,3" \
-  -F "hair_density=sparse" -F "hair_density=dense" -F "hairline_height=0"</pre>
-      <p>至少选择一档密度，多选时重复提交 <code>hair_density</code>。高度在 −1 到 +1 之间，API 的负值上移、正值下移。每个发型与密度组合返回一项，图片按网关规则转成 URL。</p>
+      <p>使用现有对接账号的 <a href="#client-auth">Bearer 访问令牌</a>，以 <code>multipart/form-data</code> 提交。</p>
+      <table>
+        <tr><th>字段</th><th>说明</th></tr>
+        <tr><td><code>image_file</code> / <code>image_url</code> / <code>image_base64</code></td><td>图片三选一。</td></tr>
+        <tr><td><code>gender</code></td><td>必填，<code>female</code> 或 <code>male</code>。</td></tr>
+        <tr><td><code>hair_style</code></td><td>必填，序号 1–7，多选用逗号分隔，如 <code>1,3</code>。</td></tr>
+        <tr><td><code>hair_density</code></td><td>至少一档，<code>sparse</code> 稀疏、<code>normal</code> 正常、<code>dense</code> 浓密。多选时重复提交同名字段。</td></tr>
+        <tr><td><code>hairline_height</code></td><td>默认 <code>0</code>，范围 <code>[-1, 1]</code>。API 负值上移，正值下移。端点移动眉心到下巴垂直像素距离的 10%。</td></tr>
+      </table>
+      <p>女性 1–7 依次为椭圆、花瓣、心形、直线、波浪、大花瓣、古典花瓣。男性 1–7 依次为椭圆、倒弧、M 形、直线、心形、柔和花瓣、波浪。</p>
+
+      <h3>前端请求示例</h3>
+      <p>以下示例使用网关测试页的滑块约定，正值向上，所以提交时取反。<code>Content-Type</code> 由浏览器根据 <code>FormData</code> 自动设置。</p>
+      <pre id="if22-js-example">async function grow22({ file, gender, styles, densities, slider = 0, accessToken }) {
+  const body = new FormData();
+  body.append("image_file", file);
+  body.append("gender", gender);
+  body.append("hair_style", styles.join(","));
+  for (const density of densities) body.append("hair_density", density);
+  body.append("hairline_height", String(-slider));
+
+  const response = await fetch("/api/v1/hair/grow-22", {
+    method: "POST",
+    headers: { Authorization: `Bearer ${accessToken}` },
+    body,
+  });
+  const result = await response.json();
+  if (!response.ok || result.code !== 0) {
+    throw new Error(result.message || `HTTP ${response.status}`);
+  }
+  return result.data.results;
+}
+
+// 已登录后调用。选择 2 个发型和 2 档密度，共返回 4 项。
+// const results = await grow22({
+//   file: input.files[0], gender: "female", styles: [1, 3],
+//   densities: ["sparse", "dense"], slider: 0.5, accessToken,
+// });</pre>
+      <p>请求返回 <code>401 / 1009</code> 时，按<a href="#client-auth">鉴权章节</a>刷新令牌后重试一次。多选高度时，按高度分别发起请求。</p>
+
+      <h3>展示结果与发际线预览</h3>
+      <table>
+        <tr><th><code>data.results[]</code> 字段</th><th>展示方式</th></tr>
+        <tr><td><code>order</code>、<code>hairline_type</code>、<code>hair_density</code></td><td>标注发型和密度。多高度结果另外记录每次请求所用的高度。</td></tr>
+        <tr><td><code>image_url</code></td><td>与输入照片同尺寸的透明发际线 PNG，可叠加在原图坐标的底图上。</td></tr>
+        <tr><td><code>grown_image_url</code></td><td>生发图 URL。单项生成失败时返回 <code>grown_image_base64: null</code>，这一项仍保留发型和密度信息。</td></tr>
+      </table>
+      <p>如需复刻测试页，首次以高度 <code>0</code> 生图，出图后再用同一个 Bearer 令牌请求<a href="#if52">接口 52</a>，传 <code>normalize_image=true</code> 和 <code>generate_grow_image=false</code>。将各发型的 <code>image_middle_url</code> 叠在接口 52 的 <code>input_image_url</code> 上；如果底图改用首次生发图，先用 <code>framing.source_to_processed</code> 做同样的扶正裁切，再叠加。预览白线是设计参考线，实际出图边界以生发图为准。</p>
       <p><a href="/static/test_interface22.html" class="link">打开接口 22 测试页</a></p>
     </div>
   </div>
@@ -356,7 +398,7 @@ 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 class="desc">中下庭均值定位 middle，支持扶正裁切与生发。需要 <a href="#client-auth">访问令牌</a>。以下示例开启扶正裁切，只获取预览：</p>
+      <p class="desc">按中庭与下庭总高度的 45% 定位 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' \