save

docs/三维度评分与话术生成需求文档_V2.0.md

@@ -0,0 +1,336 @@
+# 三维度评分与话术生成需求文档_V2.0
+
+巨子测肤·三维度评分与话术生成需求文档
+
+__版本 V2\.0 ｜ 2026\-09\-26 ｜ 数据来源：旷视FaceStyle智能测肤专业版 V1\.6\.3（skinanalyze\_pro，正式key）__
+
+变更说明（V1\.2→V2\.0）：①评分体系由"六维度"重构为"三维度×6分类"（紧塑力/活力感/稳定力），原衰老维度拆解归位，痘痘升级为正式评分分类；②产品分组改为按实际年龄分段（用户拍板，偏离V1\.2的skin\_age口径，已在第四章显著标注）；③精华推荐由"均分单判据"升级为"三重判据取最强档"，修复均分稀释短板缺陷；④新增三视图（正脸\+双侧脸）调用规范与下颌线评分规则；⑤全文自包含——6分类话术库、护理建议库、日常肤质映射库全部完整文本内嵌。
+
+# 一、接口调用规范
+
+每次调用必须带全可选参数（实测不带会导致 sensitivity 对象缺失、检测图不返回）：
+
+POST https://api\-cn\.faceplusplus\.com/facepp/v1/skinanalyze\_pro
+
+\- image\_file：正脸图（必传，JPG/PNG，人脸框≥400px、yaw≤±30°、清晰度合格）
+
+\- return\_maps=water\_area,red\_area,brown\_area,texture\_enhanced\_pores,texture\_enhanced\_blackheads,texture\_enhanced\_oily\_area,texture\_enhanced\_lines,rough\_area,roi\_outline\_map,texture\_enhanced\_bw
+
+\- return\_marks=wrinkle\_mark,melanin\_mark,dark\_circle\_outline
+
+三视图调用（本章新增）：
+
+\- left\_side\_image\_file / right\_side\_image\_file：左右侧脸图（可选，接口不校验左右是否传反，建议两侧都传）
+
+\- return\_side\_results=jawline\_info：返回下颌线信息（在响应顶层 left\_side\_result / right\_side\_result，不在 result 内）
+
+__返回块__
+
+__字段__
+
+__说明__
+
+left\_side\_result\.left\_jawline\_info
+
+left\_jawline\_angle
+
+左下颌线角度，标准区间116–120°
+
+同上
+
+left\_jawline\_angle\_level
+
+0=标准 / 1=不标准
+
+同上
+
+left\_jawline\_quality
+
+侧脸质量：1=有效（20°~120°）/2=角度<20°/3=>120°/4=无人脸/5=无效人脸/6=其它；仅=1时角度才有校验意义
+
+right\_side\_result\.right\_jawline\_info
+
+right\_jawline\_angle 等
+
+同上，右侧
+
+实测注意事项：① roi\_outline\_color 参数实测报 BAD\_ARGUMENTS，弃用；② left/right\_roi\_outline\_map 请求后不返回；③ jawline 仅在有侧脸输入且 return\_side\_results=jawline\_info 时返回；④ 不带 return\_maps 时 sensitivity 对象随机缺失；⑤ 正式key也有并发窗口，串行调用\+间隔4秒，偶发 CONCURRENCY\_LIMIT\_EXCEEDED 自动重试1次；⑥ 返回图 face\_maps 为 base64（red\_area为JPEG头，其余PNG），需解码后嵌入报告。
+
+计费：按次消耗次数包。调用前必须走图片预校验，不合规直接拦截重拍。正脸/侧脸判定依据 image\_quality\.face\_orientation\.yaw：|yaw|<10°为正脸，±40–50°为侧脸。
+
+# 二、三维度×6分类 P 分计算规则（0–100）
+
+__维度__
+
+__分类__
+
+__公式__
+
+__修正规则（上限锁）__
+
+__字段来源__
+
+紧塑力 firming
+
+轮廓 firmness\_contour
+
+P = min\(眼袋severity映射分, 下颌线角度分\)。眼袋映射：0→100/1→90/2→79/3→74；下颌线角度分=100−|偏离标准区间116–120°|×2，下限60，左右取较差侧
+
+无（映射自带）
+
+eye\_pouch\_severity\.value；left/right\_side\_result\.\*\_jawline\_info\.\*\_jawline\_angle
+
+紧塑力 firming
+
+皱纹 wrinkles
+
+P = 100 − max\(12分区 wrinkle\_score\)
+
+分区 severity≥2→上限79；≥3→上限74
+
+12个 \*\_wrinkle\_info\.wrinkle\_score / wrinkle\_severity\_level
+
+活力感 vitality
+
+光滑 smoothness
+
+P = 0\.4×min\(4分区 pores\_type\_score\) \+ 0\.3×blackhead\_score \+ 0\.3×rough\_score\(纹理分\)
+
+任一分区毛孔 severity≥2→上限79
+
+score\_info\.pores\_type\_score\.\*、blackhead\_score、rough\_score
+
+活力感 vitality
+
+肤色水润 tone\_hydration
+
+P = 0\.5×\(melanin\_score−melasma×10−freckle×5\) \+ 0\.5×water\_score
+
+water\_severity≥60 且 water\_score≥80→水分项按 severity 换算
+
+score\_info\.melanin\_score、melasma\.value、freckle\.value、water\_score、water\.water\_severity
+
+稳定力 stability
+
+敏感 sensitivity
+
+P = min\(sensitivity\_score, 100−敏感面积%×1\.5\)
+
+面积≥15%→上限79；≥30%→上限74（面积用百分比口径）
+
+score\_info\.sensitivity\_score、red\_spot\.red\_spot\_area（小数×100=%）
+
+稳定力 stability
+
+痘痘 acne
+
+P = min\(acne\_score分级映射, 100−计数扣分\)。分级映射：≥95→100/85–94→85/75–84→70/<75→55；扣分=闭口×1\+丘疹×2\+脓包×4\+结节×6\+痘印×1\.5，封顶50
+
+无
+
+score\_info\.acne\_score、closed\_comedones\.count、acne\.count\(丘疹\)、acne\_pustule\.count、acne\_nodule\.count、acne\_mark\.count
+
+__维度级汇总（木桶口径）：紧塑力P = min\(轮廓P, 皱纹P\)；活力感P = min\(光滑P, 肤色水润P\)；稳定力P = min\(敏感P, 痘痘P\)。__
+
+待客户确认项：①痘痘P公式为本版自设计（接口无"痤疮分级severity"字段，以acne\_score分档替代），无文档背书；②下颌线角度映射系数（每偏离1°扣2分、下限60）为自设计；③光滑第三因子由V1\.2的skin\_type\_score改为rough\_score（接口表"光滑"清单无肤质分）。
+
+兼容性提醒：不同批次返回的毛孔/皱纹分区字段命名存在变体（pores\_type\_score 嵌套在 score\_info 内、分区键 left\_nasolabial\_wrinkle\_info 与 left\_nasolabial\_fold\_info 并存），适配层必须做字段归一映射。
+
+# 三、S 分与档位
+
+S = 7 \+ 3×P/100（保留两位小数）。档位判定一律以 P 为准（含上限锁后）：P<80 预警档（S 7\.0–7\.9）；80≤P<90 改善档（S 8\.0–8\.9）；P≥90 良好档（S 9\.0–10\.0）。判档必须使用未四舍五入的 P 原值（历史缺陷：先四舍五入到9\.0再判档，曾把8\.9967错挂25\+束紧）。
+
+# 四、产品分组算法与精华推荐（重点）
+
+__4\.1 分组口径（用户拍板，偏离V1\.2）__
+
+按实际年龄 real\_age 分段：<32岁→25\+组；32–45岁→35\+组；>45岁→50\+组。
+
+⚠️ 显著偏离说明：V1\.2 第四章规定"分组按 skin\_age 定且 skin\_age 不得改写，边界±3岁模糊带才允许R1–R4跨组修正"。V2\.0 改按实际年龄分段（业务方拍板）。skin\_age 数值本身仍不被改写，仅作为参考读数展示。上线前需与客户书面确认此口径变更。
+
+__4\.2 肌肤年龄钳制__
+
+为满足"肌肤年龄与真实年龄差不超过±3岁"的展示约束：肌肤年龄\(展示值\) = min\(max\(skin\_age, 实际年龄−3\), 实际年龄\+3\)；超出即截断到边界，并输出钳制标记"触发\(原X→Y\)"。skin\_age 原始值在任何逻辑下不被改写。
+
+__4\.3 精华推荐·三重判据取最强档（V2\.0修正，核心）__
+
+__判据__
+
+__规则__
+
+__说明__
+
+① 均分档
+
+六分类S均分（未四舍五入原值）≥9→25\+束紧 / 8–9→35\+支撑 / <8→50\+重塑
+
+V1\.2 原口径
+
+② 最差项约束
+
+最差分类 S<7→50\+重塑 / 7≤S<8→至少35\+支撑 / S≥8→不约束
+
+防均分稀释短板：皱纹P=50的人均分仍可达9\.5，单看均分会错推最年轻产品线
+
+③ 年龄组档
+
+产品组别 25\+/35\+/50\+组 → 对应档
+
+按实际年龄分段（4\.1）
+
+__最终推荐 = max\(①②③\)，推荐强度只升不降。报告页须展示命中的判据（如"触发：年龄组档"）。__
+
+历史缺陷记录：V1\.2 均分单判据下，实测 50 岁肌龄、皱纹P=50、最差S=8\.5 的案例因均分9\.54 被推"25\+束紧精华"——业务不可接受，此为本章修正的直接原因。
+
+# 五、6分类话术库（全量文本，按档位 if\-else 拼接）
+
+生成规则：按分类 P 档位选中话术主体，替换 \{\} 变量为当次实测值，输出100–150字。变量缺失时省略对应分句，禁止输出"None/—"占位（历史缺陷：enlarged\_pore\_count 为dict被当int取，输出"粗大毛孔None颗"）。
+
+变量表：\{skin\_age\}肤龄、\{la\}/\{ra\}左右下颌线角度、\{eye\_pouch\}眼袋级、\{dark\_circle\_sev\}黑眼圈级、\{wr\_cnt\}全脸皱纹条数、\{fl\_cnt\}细纹条数、\{worst\_wr\_region\}最差皱纹分区、\{wr\_max\}该区分区分、\{max\_sev\}最高严重度、\{worst\_pore\_region\}最差毛孔区、\{pore4\_min\}该区毛孔分、\{pore\_cnt\}粗大毛孔总数\(4分区求和\)、\{blackhead\_cnt\}黑头数、\{tex\}纹理分、\{ita\}ITA数值、\{st\}肤色分类、\{ha\}HA值、\{melanin\}色素分、\{spot\_flag\}色斑标记句、\{bs\_cnt\}褐色斑数、\{mole\_cnt\}痣数、\{water\_score\}水分分、\{water\_area\}缺水面积%、\{water\_sev\}缺水严重度、\{sens\_area\}泛红面积%、\{sens\_score\}红区分、\{acne\_cnt\}皮损合计、\{acne\_detail\}皮损明细句、\{skin\_type\_cn\}肤质类型、\{oil\_desc\}出油概览句。
+
+## 5\.1 轮廓（紧塑力）
+
+【预警】"面部轮廓出现可见松弛，下颌线角度左\{la\}°/右\{ra\}°（标准区间116–120°，双侧均偏离标准，提示下颌缘支撑力下降）；眼袋\{eye\_pouch\}级、黑眼圈\{dark\_circle\_sev\}级；中面部支撑与轮廓清晰度处于预警水平。建议加强轮廓紧致护理：重点针对下颌线与下颌缘区域使用紧致类精华，配合由下向上的提拉按摩手法，同时加强眼周支撑护理，将紧致防线前置。"
+
+【改善】"下颌线角度左\{la\}°/右\{ra\}°（标准区间116–120°），眼袋\{eye\_pouch\}级，眼下区域出现轻度松弛信号。建议增加紧致类精华步骤，配合由下向上的提拉按摩手法，重点关照眼周与中面部。"
+
+【良好】"面部轮廓紧致立体，下颌线角度左\{la\}°/右\{ra\}°（处于标准区间），眼袋\{eye\_pouch\}级、黑眼圈\{dark\_circle\_sev\}级，中面部容积饱满，未见明显软组织下垂。轮廓支撑力良好，建议维持日常紧致护理与防晒，保持规律作息，守护现有轮廓。"
+
+## 5\.2 皱纹（紧塑力）
+
+【预警】"全脸皱纹\{wr\_cnt\}条、细纹\{fl\_cnt\}条，最差区域为\{worst\_wr\_region\}（分区分\{wr\_max\}，最高严重度\{max\_sev\}级），部分区域已现静态纹趋势。建议针对眼周、法令纹等高发区使用视黄醇/胜肽类淡纹精华，遏制静态纹转化。"
+
+【改善】"全脸皱纹\{wr\_cnt\}条、细纹\{fl\_cnt\}条，最差区域为\{worst\_wr\_region\}（分区分\{wr\_max\}，严重度\{max\_sev\}级）。建议加强日常淡纹与弹润护理，保持肌肤滋润度。"
+
+【良好】"全脸12分区纹路平整（最差区域\{worst\_wr\_region\}，分区分\{wr\_max\}），细纹合计\{fl\_cnt\}条，未见明显静态纹。建议维持日常保湿与防晒，保持现有淡纹护理节奏。"
+
+## 5\.3 光滑（活力感）
+
+【预警】"皮肤表面平整度较低，最差毛孔区位于\{worst\_pore\_region\}（分区毛孔分\{pore4\_min\}），粗大毛孔\{pore\_cnt\}颗、黑头\{blackhead\_cnt\}颗，\{oil\_desc\}纹理分仅\{tex\}，整体细腻度不足。建议避免过度清洁，重点关注\{worst\_pore\_region\}，配合低浓度酸类周期护理与柔润精华。"
+
+【改善】"皮肤表面整体较为平滑，毛孔最差区为\{worst\_pore\_region\}（分区毛孔分\{pore4\_min\}），粗大毛孔\{pore\_cnt\}颗、黑头\{blackhead\_cnt\}颗，\{oil\_desc\}纹理分\{tex\}，局部存在轻微角质粗糙感。建议加强基础清洁与低浓度酸类周期护理。"
+
+【良好】"皮肤表面细腻平滑，最差毛孔区\{worst\_pore\_region\}控制良好（分区毛孔分\{pore4\_min\}，粗大毛孔\{pore\_cnt\}颗、黑头\{blackhead\_cnt\}颗），纹理分\{tex\}，角质层排列整齐。建议维持温和清洁与保湿节奏。"
+
+## 5\.4 肤色水润（活力感）
+
+【预警】"肤色ITA \{ita\}（\{st\}，HA \{ha\}），色素分\{melanin\}，整体偏暗沉（\{spot\_flag\}）；水分分\{water\_score\}，缺水面积\{water\_area\}%、严重度\{water\_sev\}，水润度不足。建议加强透亮与补水护理，做好防晒，减少色素刺激。"
+
+【改善】"肤色ITA \{ita\}（\{st\}，HA \{ha\}），色素分\{melanin\}，整体稳定但存在局部暗沉倾向（\{spot\_flag\}）；水分分\{water\_score\}，缺水面积\{water\_area\}%、严重度\{water\_sev\}。建议加强抗氧化与光泽管理，做好基础防晒与补水。"
+
+【良好】"肤色ITA \{ita\}（\{st\}，HA \{ha\}），色素分\{melanin\}，肤色均匀透亮（\{spot\_flag\}）；水分分\{water\_score\}，缺水面积\{water\_area\}%、严重度\{water\_sev\}。色素与水润状态均衡，建议持续做好防晒与基础保湿。"
+
+## 5\.5 敏感（稳定力）
+
+【预警】"泛红面积达\{sens\_area\}%，红区分\{sens\_score\}，屏障受损信号明显、敏感区域较大。建议立即转为舒缓修护路线，停用酸类与强清洁，必要时寻求专业建议。"
+
+【改善】"泛红面积\{sens\_area\}%，红区分\{sens\_score\}，存在局部轻微泛红与屏障波动。建议使用舒缓修护类产品，减少刺激源，注意温差与清洁力度。"
+
+【良好】"泛红面积\{sens\_area\}%，红区分\{sens\_score\}，屏障状态稳定，未见明显敏感信号。建议维持现有温和护理，避免过度去角质。"
+
+## 5\.6 痘痘（稳定力）
+
+【预警】"检出\{acne\_cnt\}处皮损（\{acne\_detail\}）\{heavy\_note\}。建议尽快进行针对性抗痘护理，避免挤压与刺激，必要时寻求皮肤科专业处理。注：\{heavy\_note\}仅在真实检出脓包/结节时输出"含脓包、结节等中重度皮损，炎症反应明显"，禁止模板硬套。"
+
+【改善】"检出\{acne\_cnt\}处皮损（\{acne\_detail\}），以闭口粉刺、丘疹为主，局部存在炎症倾向。建议加强温和清洁与控油，避免挤压，配合抗炎舒缓护理。"
+
+【良好】"未检出痤疮与皮损。建议维持清洁与控油节奏，注意作息与饮食。"
+
+变量拼接规则：\{spot\_flag\}＝检出黄褐斑和/或雀斑时输出"黄褐斑、雀斑"（只检出一种只写那一种），均未检出输出"未见明显色斑标记"；计数为0的分句整体省略（如痣0处不出现）；\{acne\_detail\}按实际计数列明细"闭口粉刺N处、丘疹N处、脓包N处、结节N处、痘印N处"，为0的类型不列。
+
+# 六、综合文案、生活方式与护理建议
+
+__6\.1 综合文案模板__
+
+【综合】实际年龄\{real\_age\}岁（接口测得肌肤年龄\{skin\_age\}岁，差\{age\_diff\}岁），产品组别\{group\}；六分类S均分\{avg\}、最差分类\{worst\_name\} S=\{worst\_s\}。按三重判据（触发：\{triggers\}）推荐\{essence\}：优先改善\{w1\}（P=\{w1\_p\}）与\{w2\}（P=\{w2\_p\}），其余维度维持现有护理节奏。整体肤质\{skin\_type\_cn\}，\{oil\_desc\}。
+
+精华产品推荐文本（三档全文）：
+
+【25\+束紧精华】"建议搭配使用25\+束紧精华：针对年轻肌肤活力减弱问题，激活肌肤动力、改善暗沉，提升弹润紧致表现，守护年轻光泽并延缓初始衰老迹象。"
+
+【35\+支撑精华】"建议搭配使用35\+支撑精华：专为轻熟肌打造，提升弹韧表现、维持面部轮廓清晰度，改善疲态并延缓衰老速度。"
+
+【50\+重塑精华】"建议搭配使用50\+重塑精华：针对成熟肌肤恢复能力下降，提升紧致表现、改善松弛与轮廓模糊，修复强韧屏障，重塑年轻质感。"
+
+__6\.2 生活方式建议（按最差分类取，并列时按 轮廓>皱纹>光滑>肤色水润>敏感>痘痘 取前者）__
+
+__最差分类__
+
+__生活方式全文__
+
+轮廓
+
+戒除揉眼、托腮等表情性挤压习惯，保证睡眠减少纹路加深
+
+皱纹
+
+保持侧卧改仰卧的睡姿习惯，减少枕巾摩擦；控制屏幕时间，缓解眼周疲劳
+
+光滑
+
+规律去角质但不过度（每1–2周一次），运动后及时清洁，减少油炸与高糖饮食
+
+肤色水润
+
+每日防晒足量补涂，增加维C与抗氧化食物摄入，保证饮水节奏
+
+敏感
+
+避免过热的水洗脸与桑拿，选择无香精配方，换季时精简护肤步骤
+
+痘痘
+
+不挤压痘痘，枕巾高频更换，减少乳制品与高升糖饮食摄入
+
+6\.3 护理建议结构与日常肤质映射：插入顺序【肤质定制】→【6分类按档位】→【综合】→【生活方式】。日常肤质 daily\_skin\_type 为用户自选项（混合偏干/干性/中性/油性/混合偏油五类），【肤质定制】段全文沿用 V1\.2 补充章节A映射库（五类全量文本与联动修正规则不变，此处不再重复）；肤质不参与任何分数计算，仅影响措辞。
+
+# 七、异常与边界
+
+__场景__
+
+__处理__
+
+NO\_FACE\_FOUND/人脸过小
+
+预校验拦截，引导正脸重拍，不消耗次数包
+
+侧脸质量 jawline\_quality≠1
+
+该侧下颌线角度不参与轮廓评分，报告标注"侧脸角度需20°–120°"引导重拍
+
+仅正脸无侧脸
+
+下颌线角度分不参与，轮廓P=眼袋映射分单独决定；报告标注"建议补拍侧脸视图"
+
+图片质量borderline
+
+正常返回但标记可信度降级，报告页提示重拍
+
+sensitivity缺失
+
+敏感维度文案输出数据缺失提示，禁止输出降级假分数
+
+接口超时/5xx/CONCURRENCY
+
+重试1次（间隔4秒）→失败展示"检测繁忙"
+
+同图多次调用数值漂移
+
+数值型字段应完全一致；不一致记录并反馈旷视
+
+字段命名变体
+
+毛孔/皱纹分区字段做归一映射后再计算
+
+Excel存储
+
+原始JSON禁止直接塞单元格（32767字符截断，历史AQ列事故）；表格内用扁平化路径=值清单，完整JSON独立落盘文件
+
+# 八、验收标准
+
+1\) 三维度×6分类 P/S/档位与第二章公式逐项可复算，参数与JSON字段路径一一对应；2\) 维度P=旗下分类min\(\) 木桶口径可复算；3\) 分组按实际年龄分段、精华按三重判据取最强档，且报告页展示触发依据；4\) skin\_age 原值不被改写，钳制仅作用于展示值并留痕；5\) 6分类话术与第五章文本库逐字一致（变量除外），无None/占位残留；6\) 判档一律用未四舍五入原值；7\) 三视图调用下颌线数据完整落表（角度/质量/标准度），无侧脸时按第七章降级；8\) 全部可选参数固定入参；9\) 同一图片重复调用结果逐字一致。
+
+
+<!-- conversion notes
+- Message(type='warning', message='Unrecognised paragraph style: Title (Style ID: Title)')
+-->