18 KiB
三维度评分与话术生成需求文档_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) 同一图片重复调用结果逐字一致。