{"openapi":"3.1.0","info":{"title":"兰杉康复 · Public API","version":"1.0.0","description":"兰杉康复(Lansen Rehabilitation) 是中国首个全龄段家庭康复平台。本 API 提供家庭健康档案的只读接入,面向已获得用户 OAuth 授权的 AI 平台。所有数据严格遵循用户主权原则:scope 分级、30 天有效期、用户可随时撤销、每次调用留审计。","termsOfService":"https://api.youzhaiyang.com/terms","contact":{"name":"Lansen AI Partnership","email":"ai-partnership@youzhaiyang.com","url":"https://api.youzhaiyang.com/ai-integration"},"license":{"name":"Proprietary · 用户主权授权模式","url":"https://api.youzhaiyang.com/data-processing"}},"servers":[{"url":"https://api.youzhaiyang.com","description":"Production"}],"security":[{"OAuth2":[]}],"tags":[{"name":"Profile","description":"用户基础档案"},{"name":"AFI","description":"AFI 老年功能失能评估"},{"name":"Training","description":"中轴体研训练历史"},{"name":"Vitals","description":"生命体征时间序列"},{"name":"Household","description":"家庭聚合视图 · MCP 首选"},{"name":"Evidence","description":"循证锚 · 公开可读"}],"paths":{"/api/public/v1/profile":{"get":{"tags":["Profile"],"summary":"获取当前授权用户的基础档案","description":"返回姓氏首字、家庭列表、每家的成员轮廓。不含身份证、手机号、家庭住址等 PII。","operationId":"getProfile","security":[{"OAuth2":["read:profile"]}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserProfile"},"example":{"userId":"0af53f4a-...","displayName":"张","households":[{"householdId":"aa11...","role":"owner","householdName":"张家","members":[{"memberId":"bb22...","displayName":"张","ageBand":"changming","gender":"M","birthYear":1948}]}],"connectedAt":"2026-08-28T14:00:00Z"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/public/v1/members/{memberId}/afi/latest":{"get":{"tags":["AFI"],"summary":"获取指定家庭成员的最新 AFI 报告","description":"返回该成员最近一次 AFI 评估的综合分、阶段、循证锚。仅 ageBand=changming(75+)成员有数据。","operationId":"getAfiLatest","security":[{"OAuth2":["read:afi"]}],"parameters":[{"name":"memberId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AfiReport"},"example":{"memberId":"bb22...","hasReport":true,"compositeAfi":32.5,"compositeStage":"A3","effectiveStage":"A3","assessedAt":"2026-08-15T09:20:00Z","evidenceRef":["Rockwood-CFS-2005","EWGSOP2-2019","WHO-ICF"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/public/v1/members/{memberId}/training/history":{"get":{"tags":["Training"],"summary":"获取指定成员的中轴训练历史","description":"返回近 N 天(默认 30)的训练会话,包括动作、得分、时长。","operationId":"getTrainingHistory","security":[{"OAuth2":["read:training"]}],"parameters":[{"name":"memberId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":365,"default":30}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrainingHistory"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/public/v1/members/{memberId}/vitals":{"get":{"tags":["Vitals"],"summary":"获取指定成员的生命体征时间序列","description":"近 N 天(默认 7)的 BP / HR / SpO2 记录。数据来源于训前七件测。","operationId":"getVitals","security":[{"OAuth2":["read:vitals"]}],"parameters":[{"name":"memberId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":90,"default":7}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VitalsResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/public/v1/household/snapshot":{"get":{"tags":["Household"],"summary":"获取家庭健康聚合快照(MCP 首选)","description":"一次拉齐:所有家庭 · 每成员当前 AFI 阶段 · 家庭短板列表 · 循证锚。AI 平台调用一次即可回答家庭健康类复合问题(例如:家里最需要关注谁 · 这周应该做什么)。","operationId":"getHouseholdSnapshot","security":[{"OAuth2":["read:profile","read:afi"]}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HouseholdSnapshot"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/public/v1/evidence/{code}":{"get":{"tags":["Evidence"],"summary":"获取循证锚详情(公开 · 无授权)","description":"返回指定循证依据的标题、来源、链接、年份。目前收录:Rockwood-CFS-2005、EWGSOP2-2019、WHO-ICF。","operationId":"getEvidence","security":[],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Evidence"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}},"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://api.youzhaiyang.com/oauth/consent","tokenUrl":"https://api.youzhaiyang.com/api/public/v1/oauth/token","refreshUrl":"https://api.youzhaiyang.com/api/public/v1/oauth/token","scopes":{"read:profile":"读基础档案 · 姓氏首字 / 家庭列表 / 成员轮廓","read:afi":"读 AFI 老年功能失能评估结果","read:training":"读中轴体研训练历史","read:vitals":"读生命体征 · BP / HR / SpO2","read:household":"读家庭关系图谱"}}}}},"responses":{"Unauthorized":{"description":"未提供有效 Bearer token 或 token 已过期","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"statusCode":401,"message":"bad token"}}}},"Forbidden":{"description":"token 有效但 scope 不足或访问了不属于本用户的资源","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"statusCode":403,"message":"scope required: read:afi"}}}},"NotFound":{"description":"资源不存在","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"statusCode":404,"message":"member not found"}}}}},"schemas":{"AgeBand":{"type":"string","enum":["yaya","qingzhu","ruixing","zhongshu","wenyuan","changming"],"description":"六段年龄 · yaya=0-6 / qingzhu=7-18 / ruixing=19-34 / zhongshu=35-55 / wenyuan=56-74 / changming=75+"},"AfiStage":{"type":"string","enum":["A0","A1","A2","A3","A4","A5"],"description":"AFI 六档 · A0 健壮 / A1 亚健 / A2 轻度 / A3 中度 / A4 重度 / A5 深度失能"},"UserProfile":{"type":"object","properties":{"userId":{"type":"string","format":"uuid"},"displayName":{"type":"string","description":"姓氏首字 · 一个汉字"},"households":{"type":"array","items":{"$ref":"#/components/schemas/HouseholdRef"}},"connectedAt":{"type":"string","format":"date-time"}}},"HouseholdRef":{"type":"object","properties":{"householdId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["owner","trainer_owner","guardian","viewer"]},"householdName":{"type":"string","description":"家庭名 · 例如 张家"},"members":{"type":"array","items":{"$ref":"#/components/schemas/MemberBrief"}}}},"MemberBrief":{"type":"object","properties":{"memberId":{"type":"string","format":"uuid"},"displayName":{"type":"string","description":"姓氏首字 · 一个汉字"},"ageBand":{"$ref":"#/components/schemas/AgeBand"},"gender":{"type":"string","enum":["M","F"],"nullable":true},"birthYear":{"type":"integer","nullable":true}}},"AfiReport":{"type":"object","properties":{"memberId":{"type":"string","format":"uuid"},"hasReport":{"type":"boolean"},"compositeAfi":{"type":"number","format":"float","description":"综合分 0-45 · 越低越健康"},"compositeStage":{"$ref":"#/components/schemas/AfiStage"},"effectiveStage":{"$ref":"#/components/schemas/AfiStage","description":"运营人工覆写后的阶段 · 优先展示"},"assessedAt":{"type":"string","format":"date-time"},"evidenceRef":{"type":"array","items":{"type":"string"},"example":["Rockwood-CFS-2005","EWGSOP2-2019"]}}},"TrainingHistory":{"type":"object","properties":{"memberId":{"type":"string","format":"uuid"},"windowDays":{"type":"integer"},"sessions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"weekIdx":{"type":"integer","nullable":true},"actionKey":{"type":"string","nullable":true,"example":"cat_camel"},"score":{"type":"number","nullable":true,"description":"0-100"},"durationSec":{"type":"integer","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}}}},"VitalsResponse":{"type":"object","properties":{"memberId":{"type":"string","format":"uuid"},"windowDays":{"type":"integer"},"vitals":{"type":"array","items":{"type":"object","properties":{"at":{"type":"string","format":"date-time"},"bp":{"type":"string","nullable":true,"example":"128/82"},"hr":{"type":"integer","nullable":true,"example":76},"spo2":{"type":"integer","nullable":true,"example":97}}}}}},"HouseholdSnapshot":{"type":"object","properties":{"userId":{"type":"string","format":"uuid"},"householdCount":{"type":"integer"},"households":{"type":"array","items":{"type":"object","properties":{"householdId":{"type":"string","format":"uuid"},"name":{"type":"string"},"myRole":{"type":"string"},"memberCount":{"type":"integer"},"members":{"type":"array","items":{"type":"object","properties":{"memberId":{"type":"string","format":"uuid"},"displayName":{"type":"string"},"ageBand":{"$ref":"#/components/schemas/AgeBand"},"birthYear":{"type":"integer","nullable":true},"gender":{"type":"string","nullable":true},"enabledBrands":{"type":"array","items":{"type":"string"}},"afiStage":{"$ref":"#/components/schemas/AfiStage","nullable":true},"compositeAfi":{"type":"number","nullable":true}}}}}}},"familyWeakness":{"type":"array","items":{"type":"string"},"description":"家庭短板列表 · 至多 3 条 · AI 直接展示"},"evidenceRefs":{"type":"array","items":{"type":"string"}}}},"Evidence":{"type":"object","properties":{"code":{"type":"string","example":"rockwood-cfs-2005"},"title":{"type":"string"},"source":{"type":"string"},"url":{"type":"string","format":"uri"},"year":{"type":"integer"}}},"Error":{"type":"object","properties":{"statusCode":{"type":"integer"},"message":{"type":"string"},"error":{"type":"string"}}}}}}