docs: freeze YuXinGu lexicon, journey, and P1 engineering sources
Establish product language contract, user journey with dual growth engines, ERD/OpenAPI/Go boundaries, and H5 routes (/profile, /portrait, /relation, /membership) before P1 implementation. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
jackyu66git
+266
-10
@@ -1,13 +1,28 @@
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: YuXinGu API
|
||||
version: 0.1.0
|
||||
description: 愈心谷 HTTP API（脚手架）
|
||||
version: 0.2.0
|
||||
description: |
|
||||
愈心谷 P1 API 契约（冻结草案）。
|
||||
用户可见文案遵循 .ai/product/lexicon.md。
|
||||
统一信封：{ code, message, data }；code=0 成功。
|
||||
servers:
|
||||
- url: http://127.0.0.1:8080
|
||||
tags:
|
||||
- name: system
|
||||
- name: profile
|
||||
- name: portrait
|
||||
- name: scale
|
||||
- name: relation
|
||||
- name: report
|
||||
- name: ask
|
||||
- name: companion
|
||||
- name: commerce
|
||||
|
||||
paths:
|
||||
/api/v1/healthz:
|
||||
get:
|
||||
tags: [system]
|
||||
summary: Liveness
|
||||
responses:
|
||||
'200':
|
||||
@@ -16,22 +31,263 @@ paths:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Envelope'
|
||||
|
||||
/api/v1/ping:
|
||||
get:
|
||||
tags: [system]
|
||||
summary: Ping
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
|
||||
/api/v1/profiles:
|
||||
get:
|
||||
tags: [profile]
|
||||
summary: 列出个人档案
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Envelope'
|
||||
post:
|
||||
tags: [profile]
|
||||
summary: 创建个人档案
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CreateProfileRequest'
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
|
||||
/api/v1/profiles/{id}:
|
||||
patch:
|
||||
tags: [profile]
|
||||
summary: 更新个人档案
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/Id'
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
delete:
|
||||
tags: [profile]
|
||||
summary: 删除个人档案
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/Id'
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
|
||||
/api/v1/reports/portrait:
|
||||
post:
|
||||
tags: [portrait]
|
||||
summary: 生成个人画像成长报告
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [profile_id]
|
||||
properties:
|
||||
profile_id: { type: string, format: uuid }
|
||||
responses:
|
||||
'200':
|
||||
description: 返回 GrowthReport（detail 按权益裁剪）
|
||||
|
||||
/api/v1/relation/insight:
|
||||
post:
|
||||
tags: [relation]
|
||||
summary: 生成关系理解
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [profile_a_id, profile_b_id]
|
||||
properties:
|
||||
profile_a_id: { type: string, format: uuid }
|
||||
profile_b_id: { type: string, format: uuid }
|
||||
responses:
|
||||
'200':
|
||||
description: RelationInsight + 可选 report_id
|
||||
|
||||
/api/v1/reports/{id}:
|
||||
get:
|
||||
tags: [report]
|
||||
summary: 获取成长报告（权益裁剪）
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/Id'
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
|
||||
/api/v1/scales:
|
||||
get:
|
||||
tags: [scale]
|
||||
summary: 探索测试列表
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
|
||||
/api/v1/scales/{slug}:
|
||||
get:
|
||||
tags: [scale]
|
||||
summary: 探索测试题目
|
||||
parameters:
|
||||
- name: slug
|
||||
in: path
|
||||
required: true
|
||||
schema: { type: string }
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
|
||||
/api/v1/scales/{slug}/result:
|
||||
post:
|
||||
tags: [scale]
|
||||
summary: 提交探索测试并计分
|
||||
parameters:
|
||||
- name: slug
|
||||
in: path
|
||||
required: true
|
||||
schema: { type: string }
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [profile_id, answers]
|
||||
properties:
|
||||
profile_id: { type: string, format: uuid }
|
||||
answers: { type: object }
|
||||
responses:
|
||||
'200':
|
||||
description: 探索结果
|
||||
|
||||
/api/v1/ask/threads:
|
||||
post:
|
||||
tags: [ask]
|
||||
summary: 创建问答线程（须绑定 profile）
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [profile_id]
|
||||
properties:
|
||||
profile_id: { type: string, format: uuid }
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
|
||||
/api/v1/ask/threads/{id}/messages:
|
||||
post:
|
||||
tags: [ask]
|
||||
summary: 发送消息（扣额度）
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/Id'
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [content]
|
||||
properties:
|
||||
content: { type: string }
|
||||
responses:
|
||||
'200':
|
||||
description: assistant 回复
|
||||
|
||||
/api/v1/solar-terms/today:
|
||||
get:
|
||||
tags: [companion]
|
||||
summary: 今日节气生活建议
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
|
||||
/api/v1/moods:
|
||||
post:
|
||||
tags: [companion]
|
||||
summary: 心情记录（P2 可完善）
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
|
||||
/api/v1/membership/me:
|
||||
get:
|
||||
tags: [commerce]
|
||||
summary: 当前成长会员权益
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
|
||||
/api/v1/orders:
|
||||
post:
|
||||
tags: [commerce]
|
||||
summary: 创建订单（membership | deep_access）
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CreateOrderRequest'
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
|
||||
/api/v1/orders/{id}/pay-mock:
|
||||
post:
|
||||
tags: [commerce]
|
||||
summary: 模拟支付成功
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/Id'
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
|
||||
components:
|
||||
parameters:
|
||||
Id:
|
||||
name: id
|
||||
in: path
|
||||
required: true
|
||||
schema: { type: string, format: uuid }
|
||||
|
||||
schemas:
|
||||
Envelope:
|
||||
type: object
|
||||
required: [code, message]
|
||||
properties:
|
||||
code:
|
||||
type: integer
|
||||
example: 0
|
||||
message:
|
||||
type: string
|
||||
example: success
|
||||
data:
|
||||
type: object
|
||||
code: { type: integer, example: 0 }
|
||||
message: { type: string, example: success }
|
||||
data: { type: object }
|
||||
|
||||
CreateProfileRequest:
|
||||
type: object
|
||||
required: [relation, birth_date]
|
||||
properties:
|
||||
relation: { type: string, enum: [self, other] }
|
||||
display_name: { type: string }
|
||||
birth_date: { type: string, format: date }
|
||||
birth_time: { type: string, nullable: true }
|
||||
birth_place: { type: string, nullable: true }
|
||||
gender: { type: string, nullable: true }
|
||||
relation_type: { type: string, nullable: true }
|
||||
|
||||
CreateOrderRequest:
|
||||
type: object
|
||||
required: [kind]
|
||||
properties:
|
||||
kind: { type: string, enum: [membership, deep_access] }
|
||||
plan: { type: string, description: month|quarter|year when membership }
|
||||
report_id: { type: string, format: uuid, description: when deep_access }
|
||||
|
||||
Reference in New Issue
Block a user