{"openapi":"3.1.0","info":{"title":"观衡确定性排盘 API","version":"2.0.0","description":"为私人自定义 GPT 提供八字、紫微斗数、六爻和奇门遁甲固定计算。接口不输出医疗内容，排盘事实与文化解读必须分开。"},"servers":[{"url":"http://guanheng.net"}],"paths":{"/api/v1/bazi-ziwei":{"post":{"operationId":"calculateBaziZiwei","summary":"计算八字与紫微斗数命盘","description":"出生信息齐全后调用。必须明确 timeBasis；用户说输入时间已经是真太阳时时，必须选择 true_solar_time 并原样使用，绝不再次校正。不要自行推算四柱。","security":[{"bearerAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaziZiweiRequest"}}}},"responses":{"200":{"description":"排盘成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/liuyao":{"post":{"operationId":"castLiuyao","summary":"六爻装卦与纳甲","description":"仅用于一个明确问题。手工起卦时 lineValues 必须按初爻到上爻排列，每项为 6、7、8、9。","security":[{"bearerAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiuyaoRequest"}}}},"responses":{"200":{"description":"装卦成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/qimen":{"post":{"operationId":"calculateQimen","summary":"时家转盘奇门起局","description":"结构化访谈完成后调用。必须给出问题类型、目标和当前城市；固定使用 mainline-cn-v1，不混用其他流派。","security":[{"bearerAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QimenRequest"}}}},"responses":{"200":{"description":"起局成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/interpret":{"post":{"operationId":"interpretVerifiedChart","summary":"解读已经由本服务计算的命盘或卦盘","description":"必须先调用对应排盘接口，再把其 data 原样放入 chartData。网站用户按报告档位扣除积分；服务密钥调用不走个人积分账户。","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InterpretRequest"}}}},"responses":{"200":{"description":"解读成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/intake":{"post":{"operationId":"classifyMingliIntake","summary":"理解用户自然语言需求并分流","description":"把自然语言问题归入八字、六爻、奇门或古籍检索。未配置 OPENAI_API_KEY 时自动使用本地确定性规则。","security":[{"bearerAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntakeRequest"}}}},"responses":{"200":{"description":"分类成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"description":"请求频率超过限制","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/library-search":{"get":{"operationId":"searchMingliLibrary","summary":"检索古籍全文库","description":"按不含空白的标准化文本检索32部本地文献；最多返回60条上下文片段，不把命中自动视为完成版本校勘。","security":[{"bearerAuth":[]},{}],"parameters":[{"in":"query","name":"q","required":true,"schema":{"type":"string","minLength":2,"maxLength":80}},{"in":"query","name":"category","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"检索结果","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/capabilities":{"get":{"operationId":"getMingliCapabilities","summary":"查询当前服务器可用能力","security":[],"responses":{"200":{"description":"能力与配置状态","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}}}}},"/api/v1/account":{"get":{"operationId":"getMingliAccount","summary":"查询游客、手机号或托管账户状态","security":[],"responses":{"200":{"description":"账户模式与托管身份","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}}}}},"/api/v1/auth/phone/request":{"post":{"operationId":"requestPhoneOtp","summary":"发送注册、找回密码或风险复核验证码","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneOtpRequest"}}}},"responses":{"200":{"description":"验证码已发送","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"description":"验证码请求频率超过限制","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/auth/phone/verify":{"post":{"operationId":"verifyPhoneOtp","summary":"校验短信验证码并建立登录会话","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneOtpVerify"}}}},"responses":{"200":{"description":"登录成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/api/v1/auth/phone/logout":{"post":{"operationId":"logoutPhoneSession","summary":"退出手机号账户","security":[],"responses":{"200":{"description":"退出成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}}}}},"/api/v1/auth/password/login":{"post":{"operationId":"loginWithPhonePassword","summary":"使用手机号和密码登录","description":"可信设备直接建立会话；新设备或异常地区返回 requiresOtp，需短信复核。","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhonePasswordLogin"}}}},"responses":{"200":{"description":"登录成功，或需要短信风险复核","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"description":"登录尝试过多，账户或来源暂时受限","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/auth/password/setup":{"post":{"operationId":"setupPhonePassword","summary":"首次设置或短信复核后重置密码","description":"仅接受最近 10 分钟内完成短信验证的手机号会话。","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhonePasswordSetup"}}}},"responses":{"200":{"description":"密码已设置或重置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/records":{"get":{"operationId":"listMingliRecords","summary":"读取当前登录用户的跨设备档案","description":"需要手机号验证码身份或托管身份，以及 D1 数据库绑定。","security":[],"responses":{"200":{"description":"最多 50 条用户档案","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"operationId":"saveMingliRecord","summary":"保存当前登录用户的命理档案","description":"所有权由服务端托管身份决定，客户端不能指定 owner。","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedRecord"}}}},"responses":{"200":{"description":"保存成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"delete":{"operationId":"deleteMingliRecord","summary":"删除当前登录用户的一条或全部档案","description":"传 id 删除单条；传 all=1 删除当前登录用户的全部云端档案。两者任选其一。","security":[],"parameters":[{"in":"query","name":"id","required":false,"schema":{"type":"string"}},{"in":"query","name":"all","required":false,"schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"删除成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/billing":{"get":{"operationId":"getBillingReadiness","summary":"查询真实收款接入状态","security":[],"responses":{"200":{"description":"支付服务商与商户配置状态","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"BaziZiweiRequest":{"type":"object","additionalProperties":false,"required":["year","month","day","hour","minute","gender","timeBasis"],"properties":{"year":{"type":"integer","minimum":1900,"maximum":2100},"month":{"type":"integer","minimum":1,"maximum":12},"day":{"type":"integer","minimum":1,"maximum":31},"hour":{"type":"integer","minimum":0,"maximum":23},"minute":{"type":"integer","minimum":0,"maximum":59},"gender":{"type":"string","enum":["male","female","男","女"]},"calendarType":{"type":"string","enum":["solar","lunar"],"default":"solar"},"isLeapMonth":{"type":"boolean","default":false},"utcOffset":{"type":"number","minimum":-12,"maximum":14,"default":8},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"只有 timeBasis=clock_time_convert_to_true_solar 时必填。"},"timeBasis":{"type":"string","enum":["clock_time","true_solar_time","clock_time_convert_to_true_solar"],"description":"clock_time=输入是钟表时间，原样排盘；true_solar_time=输入已经是真太阳时，原样排盘且绝不再次校正；clock_time_convert_to_true_solar=明确要求把钟表时间换算后再排盘。"},"birthplace":{"type":"string","maxLength":120}}},"LiuyaoRequest":{"type":"object","additionalProperties":false,"required":["question","questionType","castTime","timezone","method"],"properties":{"question":{"type":"string","minLength":4,"maxLength":240},"questionType":{"type":"string","enum":["wealth","career","exam","relationship_male_asks_female","relationship_female_asks_male","relationship_same_sex","travel","lost_item","housing","family","lawsuit","project","other"]},"castTime":{"type":"string","description":"YYYY-MM-DD HH:mm"},"timezone":{"type":"string","default":"Asia/Shanghai"},"method":{"type":"string","enum":["manual","auto"]},"lineValues":{"type":"array","minItems":6,"maxItems":6,"description":"由初爻到上爻；manual 时必填。","items":{"type":"integer","enum":[6,7,8,9]}}}},"QimenRequest":{"type":"object","additionalProperties":false,"required":["questionType","questionGoal","calendarType","location"],"properties":{"questionType":{"type":"string","minLength":1,"maxLength":80},"questionGoal":{"type":"string","minLength":1,"maxLength":240},"timeInput":{"oneOf":[{"type":"string","description":"YYYY-MM-DD HH:mm"},{"type":"object","additionalProperties":false,"required":["year","month","day"],"properties":{"year":{"type":"integer"},"month":{"type":"integer"},"day":{"type":"integer"},"hour":{"type":"integer","default":0},"minute":{"type":"integer","default":0},"second":{"type":"integer","default":0}}}]},"calendarType":{"type":"string","enum":["solar","lunar","now"]},"isLeapMonth":{"type":"boolean","default":false},"location":{"type":"object","additionalProperties":false,"required":["city","timezone"],"properties":{"country":{"type":"string","default":"中国"},"city":{"type":"string"},"timezone":{"type":"string","description":"IANA 时区，例如 Asia/Shanghai。"}}},"ruleset":{"type":"string","enum":["mainline-cn-v1"],"default":"mainline-cn-v1"}}},"InterpretRequest":{"type":"object","additionalProperties":false,"required":["module","chartData"],"properties":{"module":{"type":"string","enum":["bazi","liuyao","qimen"]},"chartData":{"type":"object","additionalProperties":true,"description":"对应排盘接口返回的 data，必须保持算法事实不变。"},"focus":{"type":"string","enum":["overview","career","wealth","relationship","timing","classics"],"default":"overview"},"detailLevel":{"type":"string","enum":["standard","deep"],"default":"standard","deprecated":true,"description":"兼容旧调用；新调用请使用 reportTier。"},"reportTier":{"type":"string","enum":["regular","formal","multi","deep"],"default":"regular","description":"普通回答、正式解读、多体系论证或深度报告。网站端分别扣 1、5、10、30 积分。"},"requestId":{"type":"string","pattern":"^rpt_[A-Za-z0-9_-]{12,90}$","description":"网站计费幂等编号；服务密钥调用可不提供。"},"question":{"type":"string","maxLength":300},"targetYear":{"type":"integer","minimum":1900,"maximum":2100,"description":"八字阶段分析的目标公历年份；不填写时仅给出岁运方法提示。"},"targetDate":{"type":"string","format":"date","description":"八字阶段分析的具体公历日期；提供后补充该日的流月、流日历法坐标，并自动锁定对应年份。"},"useAi":{"type":"boolean","default":false,"description":"仅供服务密钥调用选择增强方式；网站端由 reportTier 决定。"}}},"IntakeRequest":{"type":"object","additionalProperties":false,"required":["message"],"properties":{"message":{"type":"string","minLength":2,"maxLength":500,"description":"用户本轮最想咨询的自然语言问题。"}}},"PhoneOtpRequest":{"type":"object","additionalProperties":false,"required":["phone"],"properties":{"phone":{"type":"string","description":"中国大陆手机号，可带 +86。"},"purpose":{"type":"string","enum":["login","password_reset","risk_login"],"default":"login"}}},"PhoneOtpVerify":{"type":"object","additionalProperties":false,"required":["phone","challengeId","code"],"properties":{"phone":{"type":"string"},"challengeId":{"type":"string"},"code":{"type":"string","pattern":"^\\d{6}$"}}},"PhonePasswordLogin":{"type":"object","additionalProperties":false,"required":["phone","password"],"properties":{"phone":{"type":"string","description":"中国大陆手机号。"},"password":{"type":"string","minLength":1,"maxLength":64,"format":"password"}}},"PhonePasswordSetup":{"type":"object","additionalProperties":false,"required":["password"],"properties":{"password":{"type":"string","minLength":8,"maxLength":64,"format":"password","description":"至少包含一个字母和一个数字。"}}},"SavedRecord":{"type":"object","additionalProperties":false,"required":["id","module","moduleLabel","title","savedAt","chart"],"properties":{"id":{"type":"string"},"module":{"type":"string","enum":["bazi","liuyao","qimen"]},"moduleLabel":{"type":"string","maxLength":40},"title":{"type":"string","maxLength":120},"savedAt":{"type":"string","format":"date-time"},"chart":{"type":"object","additionalProperties":true},"report":{"type":"object","additionalProperties":true}}},"ApiSuccess":{"type":"object","required":["ok","data","disclaimer"],"properties":{"ok":{"type":"boolean"},"data":{"type":"object","additionalProperties":true},"disclaimer":{"type":"string"}}},"ApiError":{"type":"object","required":["ok","error","disclaimer"],"properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"details":{},"disclaimer":{"type":"string"}}}},"responses":{"BadRequest":{"description":"输入不完整或格式错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Unauthorized":{"description":"访问密钥无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}