上禾检测后自动生成体重目标方案
版本：V0.4 · 2026-09-08 · 已移除非必要功能开关；本地实现与验证见 implementation-report.html，尚未部署。
核心规则：自动生成等同于用户把同次上禾检测的实际体重、理想体重和检测日期填入现有体重目标设置页，选择 0.5 kg/周，再点击一次“保存”。完整执行现有手动保存业务；已有目标同样被替换。同一检测报告只自动保存一次，不同有效报告分别执行新的保存。
1. 本版确认事项与修订范围
用户明确要求：“自动生成跟手动设置是一样的”。默认速度已确认为 0.5 kg/周。本版以此为业务真源，覆盖 V0.1 的相反建议。
用户进一步明确：自动保存必须按手动保存的完整逻辑处理，保证业务正确；没有接入设备的用户，手工填写、保存及后续使用仍须与之前一致。本条是硬性兼容要求，不能以自动功能通过作为整体功能正常的证明。
V0.1 中“仅建立首个目标”“已有或到期目标不覆盖”“设备流程不删除旧排课”“手动目标始终优先”“自动路径跳过 setWeight”均已撤销，不再作为开发规则。原先自行提出的“仅当日首次检测可生成”也不作为本版既定限制。
本轮只修订方案、HTML、任务索引并解决控制仓库合并冲突，未修改业务代码、数据库、设备或小程序线上版本。执行模式：常规 Codex。方案文档沿用 system-grounded-requirement-analysis 的现有代码证据，并按 output-format-preferences 保持 Markdown 与 HTML 同内容。
2. 自动填写什么
| 表单字段 | 自动填写 | 与现有手动功能的关系 |
|---|---|---|
| 用户与企业 | 已验证的手机号关联或扫码认领确定的 user_id、store_id | 相当于该用户本人操作；必须再次校验企业、设备和报告归属 |
| 初始体重 initial_weight | 同次检测的 weight，单位 kg | 与手动填写实际体重一致 |
| 目标体重 target_weight | 同次检测的 idealWeight，即结构化 weight_target，单位 kg | 与手动填写目标体重一致；不能把检测指标表直接当目标表 |
| 初始日期 start_date | 同次检测 measureTime 的业务日期 | 相当于用户在表单选择检测日期；不用扫码时间或重试日期替换 |
| 调整速度 adjust_speed | 增重/减重默认枚举 2，即 0.5 kg/周 | 与手动选择 0.5 kg/周提交值相同，不能存小数 0.5 |
| 方向 status | 由共享保存逻辑比较目标体重与初始体重得出 | 1 保持、2 增重、3 减重；不由设备自由指定 |
| 保持状态 | 相等时 adjust_speed=0、end_date=0 | 完整沿用现有分支，不强行使用默认速度 |
设备入口只负责取值、格式归一化和身份校验，方向、速度枚举与日期计算使用与手动入口相同的公共业务。两项值需是有效有限正数、单位 kg；不以默认 60 kg 填补缺失值。显示精度及可输入范围按现有页面/接口的最终统一契约核验，不另设一套自动目标算法。
3. 保存时完整执行哪些现有逻辑
| 顺序 | 现有手动保存行为 | 自动生成要求 |
|---|---|---|
| 1 | 校验初始体重、初始日期、目标体重及不等重时的速度 | 执行相同业务校验；非法设备值在入口拒绝，不进入重设事务 |
| 2 | 自动判断增重、减重、保持，计算速度和结束日期 | 完整共用，不能两份实现分别维护 |
| 3 | 查询当前企业、当前用户 delete_flag=0 的旧目标 | 有旧目标继续执行替换，不因来源为手动或已到期而跳过 |
| 4 | 将原目标软删除 | 自动保存同样软删除旧目标 |
| 5 | 将旧目标关联的 user_course 软删除 | 自动保存同样处理；当前手动逻辑包含已完成课程记录的软删除，不擅自缩小范围 |
| 6 | 新增本次体重目标 | 用本次检测值重新建立目标；初始值、起止日期和进度按新目标重新计算 |
| 7 | 在目标事务内调用 setWeight | 自动保存也调用，不能只写目标表；使用已确认的同一用户和企业 |
| 8 | setWeight 写所选日期的实际体重、身高/BMI，处理人员档案 | 与相同参数的手动保存保持一致；同日记录按现有逻辑更新，人员体重仍取最新日期记录 |
| 9 | 处理体重每日积分、推荐能量和餐厅人员同步 | 不省略这些业务；积分按既有日期规则检查，不因重复事件额外加分 |
| 10 | 同库事务提交或回滚，返回成功或失败 | 自动业务失败时与手动保存一样回滚本次旧目标、旧排课、新目标及同库体重变更；成功后才记录该报告已保存 |
“同一次检测只保存一次”是设备事件去重，不改变成功保存的业务内容。不同报告是不同的保存动作：第二次有效检测，即使当前目标由用户手动设置，也按现有重设逻辑替换它，不增加手动来源永久保护规则。
结束日期保留现有公式：总天数 = ceil(abs(初始体重 − 目标体重) ÷ 每周速度 × 7)；结束日期 = 初始日期 +（总天数 − 1）天。开始日计为第 1 天，保持状态不计算结束日期。
软件演算示例：weight=49.4 kg、idealWeight=60.0 kg、检测日期 2026-09-08、速度 0.5 kg/周，生成增重目标，共 149 天，结束日期为 2027-02-03。示例中的 60 kg 是演算数据，不声称来源于用户截图里的设备实测。
4. 触发、补传与事件去重
- 设备上传并完成会话、raw、指标保存，或用户完成扫码认领；先确定本人和企业归属，保留原检测接收/认领事务。
- 读取同一 session 聚合后的 weight 与 weight_target；可来自不同阶段的数据包，不能跨报告拼接，也不能只看最后一个血压数据包。
- 两项不齐时等待该会话后续补传，不创建目标、不删除旧目标或排课；未关联本人的匿名报告也不执行保存。
- 条件满足后，在用户级串行控制下检查该 session 是否已成功自动保存；未成功则构造与手动一致的表单参数，执行完整共享保存流程。
- 同应用库事务同时提交目标业务和该 session 的 SAVED 处理标记；任何一步失败则回滚本次保存，保留原目标/课程，允许重试。
- 已成功的 session 再收到上传、扫码或后台重试时，不再调用保存；已有成功 session 后来补传的测量指标继续走原检测同步，不重新设目标。
- 新 session 的首次有效完整数据再次执行一次保存，替换届时的当前目标；用户也可随时通过原手动入口再保存新目标。
入口覆盖：手机号已匹配上传、匿名上传后扫码认领、已认领报告后续指标补齐、重复上传/扫码、失败补偿。不能把自动目标入口只挂在 syncClaimWeight 的“存在新体重 raw”分支，否则理想体重晚到会漏触发。
不通过“打开页面”“切换历史日期”触发写入，不批量扫描全库补建历史目标；线上旧报告是否追溯属于另行操作范围。正常接收到的不同有效报告首次满足条件时按保存规则执行，不额外添加“仅首个目标”“只有当天”“旧目标到期才允许”等业务门槛。乱序的不同新报告按实际串行保存顺序处理；若要改为检测时间优先，应另行确认，不能混入本版。
已成功旧报告的补偿任务绝不能再次重设目标，包括用户后来手动重设、又有新报告保存、旧目标已被软删除等情况。处理标记保留，不因当前目标被替换而清空。
5. 如何复用代码而不遗漏业务
硬性边界：原手动 HTTP 接口、参数和返回协议保持兼容，登录鉴权、表单填写、速度选择、相等体重的保持分支、保存校验、成功/失败反馈、返回跳转及后续使用均按原流程工作。未接设备用户无需设备登记、二维码、session_id、报告关联或设备侧处理表，即可手动设置目标。
自动入口负责读取设备指标、校验报告归属、等待补传和报告去重，随后调用与手动相同的完整保存业务。手动入口继续从登录态及原表单取得参数后直接调用该业务，不经过设备校验/处理记录分支；不能为手动请求新增必填设备字段，也不能要求已有设备测量记录。推荐服务接口可包含受信任身份参数，但这些内部参数不能扩大外部请求指定他人身份的权限。
0.5 kg/周是自动生成的默认值。手动用户原来可以选择的 0.25、0.5、1 kg/周继续有效，不强制改成 0.5，不改变原页面默认值或自行增设自动覆盖限制。设备入口的严格数值/报告校验只作用于设备数据；如果需要修正公共校验，应另行说明兼容影响，不能顺带改变合法手动输入行为。
设备未启用、设备服务不可用、缺少设备扩展配置或报告字段时，手动保存不访问这些设备依赖并继续正常运行。公共保存只能依赖现有手动功能本身必需的用户、体重、目标、课程等业务依赖。来源追踪和 session 去重由自动适配层承担；自动侧记录与目标保存的同库事务由协调层组织，不把设备表依赖强加给手动入口。
建议将 UserWeight.weightManage 的完整保存业务整理为同一个可复用服务入口，显式接受受信任的 user_id、store_id 和表单参数。原 HTTP 手动入口仍从登录态取得身份并调用它；自动入口从已验证的报告归属取得身份并调用它。不能只抽取方向/日期计算后为设备另写“轻量目标写入”。
共享入口必须覆盖旧目标/关联课程软删除、新目标写入、setWeight、积分、人员同步、推荐触发、错误返回及事务处理。自动入口不能传入“跳过排课删除”“不保存体重”等改变手动语义的开关。向 setWeight 传递目标用户身份，不能让设备回调依赖不存在的前台登录态。
| 工程问题 | 处理方案 |
|---|---|
| 设备原来已经同步过实际体重 | 不以此为由省略完整目标保存；先梳理实际调用顺序，原先分阶段同步可先发生，之后目标保存仍需得到与手动保存相同的结果 |
| 同日积分 | 继续执行 setWeight 中既有日期检查；自动/手动及设备同步并发需通过相同用户/日期串行化或唯一性约束验证，不能只依赖先查后写 |
| 身高/BMI | 使用与手动保存同参数相同的计算和历史日期处理，不擅自用自动目标回写覆盖检测 raw/结构化指标 |
| 已有餐厅同步/推荐请求 | 保存业务不能删掉这些动作；同一成功保存的外部副作用若需补偿，记录独立完成状态，不通过重跑目标替换来补偿 |
| 推荐计算时序 | 新目标提交后必须可被后续推荐读取；检查现有事务内触发的时序问题，如需提交后分发，应同时纳入共享路径，不能只对自动路径采用另一套业务 |
| 手动与自动并发 | 同企业用户采用共同锁顺序，以实际串行提交顺序决定最终目标；不设置“手动永久优先”或“设备永久优先” |
| 跨库/外部系统 | 健康库测量与归属事务保留；应用库目标事务失败回滚本次保存；外部调用不能随数据库回滚，应独立记录并补偿，不宣称跨系统原子事务 |
| 返回兼容 | 手动 HTTP 请求/返回和原页面跳转保持兼容；自动协调用结构化结果记录成功、待数据、失败，不能将处理失败写成已生成 |
建议增加轻量应用库处理记录，仅承担来源追踪与重复事件控制：store_id、user_id、session_id、状态、target_id、冻结后的表单参数、尝试次数、重试时间及脱敏错误。唯一键为 store_id+session_id；写目标与写 SAVED 标记必须使用同一数据库连接和事务。
状态使用 WAITING_DATA、SAVED、INVALID_DATA、RETRY_PENDING；不再设计“已有目标跳过”状态。SAVED 是该报告保存动作完成，不等于该 target_id 永远是当前目标。普通失败重试复用冻结参数；推荐/外部同步失败只补相应副作用，不重复调用目标重设。正式表名、精度与 SQL 版本号在实施时核对实际 schema。
对于分阶段上传，既有体重同步与新的目标保存要核对锁顺序及先后结果；处理目标时不能持有反向的健康库会话锁。若已有体重写入成功、目标事务失败，回滚到目标保存之前的应用库状态，保留已成功的检测数据，不将合法检测上传当作失败撤销。
6. 页面、推荐与课程沿用规则
| 环节 | 本版要求 |
|---|---|
| 小程序操作 | 自动保存无需用户再次点击确认；目标保存成功后刷新已有目标展示，用户仍可手动重设 |
| 健康建议 | 继续从 user.userWeight/info 获取当前目标、进度、速度和起止日期，并读取课程 |
| 运动排课 | 与手动保存一样，旧目标课程已软删除；后续 getTodayPlan 发现新目标没有排课时按原规则生成，最多从起始日期排 28 天并受结束日期限制；不在设备回调中新增即时排课 |
| 推荐能量 | 完整沿用现有目标方向和速度计算；现有大众分支 0.5 对应增重计算项 +392.5、减重 -550，这是代码核对，不是新增健康算法 |
| 营养比例 | 保留手动营养目标优先和职业运动员分支；体重目标替换不意味着删除手动营养配置 |
| 自动提示 | 成功显示目标已自动设置；有旧目标时可明确显示已按本次检测重新设置。缺项或失败不得提示“已保留目标作为最终处理结果” |
| 检测页面读写隔离 | WellandScale/byDate 继续提供检测指标；读取当前体重目标不改变原始检测数据，也不因浏览日期再次保存 |
现有目标设置页默认 60 kg、未完整回显速度，体重档案目标区域 v-if=false 等问题仍记录在方案中。完整回显和新增目标卡属于配套展示建议，可单独评审；不把这些 UI 改进作为改变目标保存语义的理由，也不未经确认新增“编辑不替换、重建才替换”的业务分支。用户点击原保存仍按现有重设处理。
7. 现有边界保持一致
| 原有行为 | 本版处理 |
|---|---|
| status() 在结束日零点与当前时间比较，课程查询却包含结束日 | 记录日期口径差异；自动与手动保持相同表现，不另写自动完成算法 |
| 仅结束后判断完成，增重用 >、减重用 <；相等不算完成，保持目标 end_date=0 | 沿用当前判断，专项修复另行处理 |
| info() 使用人员档案计算进度，可能超过 100% | 同参数对照手动结果；不自动改变达成规则 |
| StaffPower 查询未删除目标时未过滤结束日期 | 到期后不保证自动停止推荐调整；自动保存会像手动一样替换届时旧目标 |
| 课程最多四周，保存会软删除旧目标关联的已完成课程记录 | 两条保存路径一致，不承诺全目标期续排或自动保留旧课程 |
| 手动参数校验存在非空/枚举边界不足 | 单独记录并测试；共同校验改进须兼顾合法旧请求，不为自动设置另做业务例外 |
8. Use Case 与验收矩阵
Use Case ID：UC-SHANGHE-GOAL-001，V0.4。目标：以同次上禾检测数据自动执行一次与本人手动保存等价的体重目标设置。参与者：用户、上禾设备、手机号/扫码关联服务、共享体重目标服务、小程序。权限边界为同企业、同用户、同报告。
主流程 M1–M6：有效上传/本人关联 → 两项指标齐全 → 检查报告未成功保存 → 共享保存事务（替换旧目标及排课、写新目标、setWeight） → 标记 SAVED → 推荐/同步及页面后续读取。
分支 A1–A5：手机号关联；扫码认领；分阶段等待；已有目标替换；同重保持。异常 E1/R1：事务失败回滚并重试；E2/R2：外部副作用失败独立补偿；E3：归属不一致拒绝。
| 验收/测试 | 前置与操作 | 必须满足 |
|---|---|---|
| AC01 / T01 | 无目标，同一表单分别手动与自动保存 | 除来源/标识/操作时间等预期差异，目标字段、体重、积分、同步与推荐触发结果一致 |
| AC02 / T02 | 49.4→60.0，2026-09-08，0.5 kg/周 | 两路径同为增重、adjust_speed=2、结束日期 2027-02-03 |
| AC03 / T03 | 实际体重大于目标，或两项相等 | 减重日期计算一致；相等时保持、速度 0、结束日期 0 |
| AC04 / T04 | 先传 weight，后传 idealWeight，末包血压 | 缺项不执行保存、不删除旧目标；首次齐全后执行一次 |
| AC05 / T05 | 手机号匹配与匿名扫码认领 | 本人关联后两入口执行相同保存；匿名未认领不保存 |
| AC06 / T06 | 已有手动、自动、已到期目标，分别再上传新报告 | 与手动重设相同：旧目标及关联课程软删除，新目标建立；不因来源或到期状态跳过 |
| AC07 / T07 | 同 session 重扫、补传、重试各 10 次 | 只发生一次成功自动保存；目标 ID 不因重复事件改变，不重复删新课程或加积分 |
| AC08 / T08 | 连续两份不同有效 session | 各执行一次保存；第二份替换第一份目标并重新开始对应计划 |
| AC09 / T09 | 手动与自动同时保存 | 共用串行化，结果等于按实际顺序连续两次手动保存；无双当前目标，无跨用户/错目标课表删除 |
| AC10 / T10 | 跨企业、他人二维码、会话身份不符 | 零他人目标写入；不从 URL 推断权限，不伪造登录态 |
| AC11 / T11 | 缺项、零、负数、非数值、无穷或非 kg | 不进入目标替换事务，旧目标及课程保持；记录输入问题，不填默认 60 |
| AC12 / T12 | 删除旧目标后、新目标插入后、setWeight 失败等注入故障 | 与手动同库事务语义相同，旧目标/课程恢复，无半目标或提前 SAVED；可重试 |
| AC13 / T13 | 保存已成功但响应丢失、推荐或外部同步失败 | 不再执行目标重设，只补响应或对应副作用；用户后续目标不被旧重试覆盖 |
| AC14 / T14 | 自动保存后手动重设，再重扫旧码，再扫描新报告 | 旧码不再保存；新报告正常替换手动目标，不存在手动永久保护 |
| AC15 / T15 | 新目标读取今日课程/推荐，重复页面刷新 | 按原规则排课和推荐；手动营养优先；目标重设时的旧课程删除与手动一致 |
| AC16 / T16 | 原设备已同步体重且已记当日积分，再自动保存目标 | 共享 setWeight 仍执行，其最终结果与此时手动保存一致；每天积分最多一次 |
| AC17 / T17 | 结束日当天、刚好到目标、提前达到、保持 | 手动/自动表现一致；不宣称既有完成判定问题已修复 |
| AC18 / T18 | 同日不同检测、历史检测日期、跨日失败重试 | 日期及同日体重处理与相同参数手动保存一致；重试不改日期，不额外增设仅当日限制 |
| AC19 / T19 | 从未接入/绑定设备、没有检测记录的用户，首次手工填写后保存 | 原请求无需任何设备字段；目标、体重、积分、人员同步及后续推荐/课程按原功能运行；设备处理表访问次数为 0 |
| AC20 / T20 | 设备服务异常或设备扩展表未配置；已有手动用户重设目标 | 手动保存不依赖设备服务或扩展表；仍正常替换原目标及关联课程，新目标可正常使用 |
| AC21 / T21 | 无设备用户分别手动选择 0.25、0.5、1 kg/周，测试增重、减重和保持 | 合法输入、速度枚举、结束日期和原反馈不变；保持无需速度；不强制手动使用 0.5，非法原请求仍按原规则反馈 |
| AC22 / T22 | 自动保存成功/失败后继续手动保存，以及纯手动连续保存和故障回滚 | 自动状态不锁死手动入口；手动请求/返回/跳转、旧目标与课程处理、失败回滚及后续页面可用性与改动前一致 |
回归必须建立改动前的手动功能基线：无设备账号与设备账号均覆盖首次设置、再次设置、三种速度、保持状态、异常回滚和后续使用；先证明抽取后的手动入口与改动前一致，再验证自动入口与手动入口等价。任意手动回归失败不得发布；不能只比较两个已经一起改错的入口。
核心验收方式是“同样的用户、企业、初始数据库状态、表单值，手动一次与自动一次分别执行”的结果对照，必须包含旧排课已完成/未完成、旧目标存在/不存在、每日积分存在/不存在等分支。测试覆盖规则单测、共享服务集成、并发/事务故障、上传与认领 HTTP、小程序读取和后续课程/推荐。
以上为待执行测试计划，本次未运行新功能测试。性能建议：按用户/session 索引查询，批次与重试有界；自动新增协调开销 P95 目标 200 ms（不含原有保存/外部同步耗时），同用户锁等待目标上限 2 秒，超时转重试。容量基线与正式门槛在开发前冻结，不能称为已通过。
9. 实施顺序与回退
- 锁定现有手动保存分支的代码与数据库 schema，建立手动业务行为对照测试，特别是 setWeight、积分、旧目标和课程删除。
- 把完整保存流程整理成显式身份的公共入口；手动端先回归，确认事务及外部副作用行为一致。
- 新增设备参数适配、本人归属校验、session 幂等记录，接通手机号、扫码和分阶段补传；自动目标不设置保留已有目标的例外。
- 验证新报告替换旧目标、同报告不重复保存、并发及补偿；核对推荐/同步顺序，页面按现有功能读取。
- 配套回显或目标卡按评审范围落地；完成 22 组验收后再进行测试企业真机验证和发布。
本功能不新增自动入口开关。版本回退按正式发布流程处理，不自动还原被替换的目标和课程；如需恢复历史目标，另行核对并处理，保留来源标识和软删除历史供追踪。
本轮交付状态：方案已按用户“自动与手动一样”的要求修订。开发准备仍需实际 schema、共享入口设计、事务/幂等测试及发布范围确认；云效提交、业务开发和真机验收均未在本轮执行。自动保存等价性、自动默认速度、新报告替换规则和无设备手动兼容要求不再作为未决问题。
10. 代码证据与核查边界
| 来源 | 核查入口 |
|---|---|
| ai_api 版本 | develop_haerbin，0cc1c822；本轮只读 |
| ai_app 版本 | develop_haerbin，bb7a709e；本地有其他登录改动且落后缓存远端 2 个提交，未拉取、覆盖或修改；与当前缓存远端相比，本次目标页/健康建议/扫码目标相关文件无差异 |
| 指标映射 | ai_api/app/api/service/shanghe/V306Mapper.php:15 |
| 认领及后续同步 | ai_api/app/api/service/ShangheClaim.php:57；ShangheV306.php:244、271、339 |
| 保存与副作用 | ai_api/app/api/service/user/UserWeight.php:165、315、366 |
| 初始化与目标状态 | 同文件 :496、600 |
| 目标 HTTP | ai_api/app/api/controller/user/UserWeight.php:52；ai_app/api/weightManage.js:6 |
| 编辑页默认值与提交 | ai_app/pagescourses/weightManage/targetWeight.vue:104、157、194 |
| 体重档案隐藏目标区域及实际请求 | ai_app/pagescourses/weightManage/index.vue:4、689；ai_api/app/api/service/WellandScale.php:346 |
| 健康建议 | ai_app/pagescourses/healthadvice/index.vue:58、436 |
| 课程生成及按需触发 | ai_api/app/api/service/user/UserCourse.php:38、191、276 |
| 推荐能量/营养优先级 | ai_api/app/common/service/StaffPower.php:133、423、438 |
证据等级：用户截图证明当前设置界面；上述业务行为由本地代码直接读取确认，日期示例经独立计算确认。本轮未登录运行中的小程序、未读取生产库、未验证现网部署 SHA，不能把代码能力等同于现网验收。尤其目标区域隐藏、完成判定及推荐到期差异，应在实施前结合目标版本实测复核。
本节代码版本与行号为 V0.1 核查时的基线记录。V0.2 本轮只根据用户澄清修订方案，没有重新宣称业务代码或线上行为已更新。