jackyu66gitandCursor
93227d3316
新增 ask_quality_feedback、运营/C端评分 API 与 admin-h5 问答反馈区；禁改消息/UGC/真支付。 Co-authored-by: Cursor <cursoragent@cursor.com>
1552 lines
40 KiB
YAML
1552 lines
40 KiB
YAML
openapi: 3.0.3
|
||
info:
|
||
title: YuXinGu 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
|
||
- name: admin
|
||
|
||
paths:
|
||
/api/v1/healthz:
|
||
get:
|
||
tags: [system]
|
||
summary: Liveness
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/Envelope'
|
||
|
||
/api/v1/ping:
|
||
get:
|
||
tags: [system]
|
||
summary: Ping
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
|
||
/api/v1/admin/auth/login:
|
||
post:
|
||
tags: [admin]
|
||
summary: Admin login
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [username, password]
|
||
properties:
|
||
username: { type: string }
|
||
password: { type: string }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/Envelope'
|
||
|
||
/api/v1/admin/auth/logout:
|
||
post:
|
||
tags: [admin]
|
||
summary: Admin logout
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
|
||
/api/v1/admin/me:
|
||
get:
|
||
tags: [admin]
|
||
summary: Current admin (role + permissions[])
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '#/components/schemas/Envelope'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/AdminMe'
|
||
|
||
/api/v1/admin/roles:
|
||
get:
|
||
tags: [admin]
|
||
summary: List admin roles
|
||
description: Requires admin.roles.read
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
'403':
|
||
description: Forbidden
|
||
|
||
/api/v1/admin/roles/{id}:
|
||
get:
|
||
tags: [admin]
|
||
summary: Role detail with permissions
|
||
description: Requires admin.roles.read
|
||
parameters:
|
||
- $ref: '#/components/parameters/Id'
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
'403':
|
||
description: Forbidden
|
||
'404':
|
||
description: Not found
|
||
|
||
/api/v1/admin/roles/{id}/permissions:
|
||
put:
|
||
tags: [admin]
|
||
summary: Replace role permission set
|
||
description: Requires admin.roles.write; writes AuditLog
|
||
parameters:
|
||
- $ref: '#/components/parameters/Id'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [permissions]
|
||
properties:
|
||
permissions:
|
||
type: array
|
||
items: { type: string }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
'400':
|
||
description: Invalid permission code
|
||
'403':
|
||
description: Forbidden
|
||
'404':
|
||
description: Not found
|
||
|
||
/api/v1/admin/users:
|
||
get:
|
||
tags: [admin]
|
||
summary: List users
|
||
parameters:
|
||
- in: query
|
||
name: q
|
||
schema: { type: string }
|
||
- in: query
|
||
name: limit
|
||
schema: { type: integer }
|
||
- in: query
|
||
name: offset
|
||
schema: { type: integer }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
|
||
/api/v1/admin/users/{id}:
|
||
get:
|
||
tags: [admin]
|
||
summary: User detail
|
||
parameters:
|
||
- in: path
|
||
name: id
|
||
required: true
|
||
schema: { type: string, format: uuid }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
|
||
/api/v1/admin/users/{id}/membership/grant:
|
||
post:
|
||
tags: [admin]
|
||
summary: Grant or extend membership
|
||
parameters:
|
||
- in: path
|
||
name: id
|
||
required: true
|
||
schema: { type: string, format: uuid }
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [plan]
|
||
properties:
|
||
plan: { type: string, enum: [month, quarter, year] }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
|
||
/api/v1/admin/users/{id}/status:
|
||
post:
|
||
tags: [admin]
|
||
summary: Transition UserStatus
|
||
description: Requires admin.users.status.write; writes transition + AuditLog
|
||
parameters:
|
||
- in: path
|
||
name: id
|
||
required: true
|
||
schema: { type: string, format: uuid }
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [status, reason]
|
||
properties:
|
||
status: { type: string, enum: [active, disabled, banned, suspended] }
|
||
reason: { type: string }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
'400':
|
||
description: Invalid edge or missing reason
|
||
'403':
|
||
description: Forbidden
|
||
|
||
/api/v1/admin/users/{id}/status-transitions:
|
||
get:
|
||
tags: [admin]
|
||
summary: List UserStatus transitions
|
||
description: Requires admin.users.read
|
||
parameters:
|
||
- in: path
|
||
name: id
|
||
required: true
|
||
schema: { type: string, format: uuid }
|
||
- in: query
|
||
name: limit
|
||
schema: { type: integer }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
'401':
|
||
description: Unauthorized
|
||
|
||
/api/v1/admin/users/{id}/insight:
|
||
get:
|
||
tags: [admin]
|
||
summary: UserIntelligence insight (read-only aggregate)
|
||
description: Requires admin.users.read; no schema write
|
||
parameters:
|
||
- in: path
|
||
name: id
|
||
required: true
|
||
schema: { type: string, format: uuid }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
'401':
|
||
description: Unauthorized
|
||
'403':
|
||
description: Forbidden
|
||
'404':
|
||
description: User not found
|
||
|
||
/api/v1/admin/users/{id}/entitlements:
|
||
get:
|
||
tags: [admin]
|
||
summary: User Entitlement aggregate (read-only)
|
||
description: Requires admin.users.read; Membership ∪ DeepAccess ∪ ask quotas
|
||
parameters:
|
||
- in: path
|
||
name: id
|
||
required: true
|
||
schema: { type: string, format: uuid }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
'401':
|
||
description: Unauthorized
|
||
'404':
|
||
description: User not found
|
||
|
||
/api/v1/admin/membership-plans:
|
||
get:
|
||
tags: [admin]
|
||
summary: List membership plans
|
||
description: Requires admin.membership.plans.read
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
'403':
|
||
description: Forbidden
|
||
|
||
/api/v1/admin/membership-plans/{code}:
|
||
get:
|
||
tags: [admin]
|
||
summary: Get membership plan
|
||
parameters:
|
||
- in: path
|
||
name: code
|
||
required: true
|
||
schema: { type: string }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
'404':
|
||
description: Not found
|
||
put:
|
||
tags: [admin]
|
||
summary: Update membership plan
|
||
description: Requires admin.membership.plans.write
|
||
parameters:
|
||
- in: path
|
||
name: code
|
||
required: true
|
||
schema: { type: string }
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [title, duration_days, amount_cents]
|
||
properties:
|
||
title: { type: string }
|
||
duration_days: { type: integer }
|
||
amount_cents: { type: integer }
|
||
active: { type: boolean }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
'400':
|
||
description: Invalid
|
||
'403':
|
||
description: Forbidden
|
||
|
||
/api/v1/admin/redemption-batches:
|
||
get:
|
||
tags: [admin]
|
||
summary: List redemption batches
|
||
responses: { '200': { description: OK } }
|
||
post:
|
||
tags: [admin]
|
||
summary: Create redemption batch
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [label, plan_code, quantity]
|
||
properties:
|
||
label: { type: string }
|
||
plan_code: { type: string }
|
||
quantity: { type: integer, minimum: 1, maximum: 100 }
|
||
responses: { '200': { description: OK } }
|
||
|
||
/api/v1/admin/redemption-batches/{id}/codes:
|
||
get:
|
||
tags: [admin]
|
||
summary: List codes in batch
|
||
parameters:
|
||
- in: path
|
||
name: id
|
||
required: true
|
||
schema: { type: string, format: uuid }
|
||
responses: { '200': { description: OK } }
|
||
|
||
/api/v1/admin/redemption-codes/{id}/disable:
|
||
post:
|
||
tags: [admin]
|
||
summary: Disable unused code
|
||
parameters:
|
||
- in: path
|
||
name: id
|
||
required: true
|
||
schema: { type: string, format: uuid }
|
||
responses: { '200': { description: OK } }
|
||
|
||
/api/v1/admin/ask/threads:
|
||
get:
|
||
tags: [admin]
|
||
summary: List AskSessionView (read-only)
|
||
description: Requires admin.ask.read
|
||
parameters:
|
||
- in: query
|
||
name: user_id
|
||
schema: { type: string, format: uuid }
|
||
- in: query
|
||
name: limit
|
||
schema: { type: integer }
|
||
- in: query
|
||
name: offset
|
||
schema: { type: integer }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
'401':
|
||
description: Unauthorized
|
||
'403':
|
||
description: Forbidden
|
||
|
||
/api/v1/admin/ask/threads/{id}:
|
||
get:
|
||
tags: [admin]
|
||
summary: Ask session detail with messages
|
||
description: Requires admin.ask.read; no message mutation
|
||
parameters:
|
||
- in: path
|
||
name: id
|
||
required: true
|
||
schema: { type: string, format: uuid }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
'404':
|
||
description: Not found
|
||
|
||
/api/v1/admin/content-safety/filter-rules:
|
||
get:
|
||
tags: [admin]
|
||
summary: List FilterRule
|
||
description: Requires admin.content_safety.read
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
'401':
|
||
description: Unauthorized
|
||
'403':
|
||
description: Forbidden
|
||
|
||
/api/v1/admin/content-safety/filter-rules/{id}:
|
||
get:
|
||
tags: [admin]
|
||
summary: Get FilterRule
|
||
parameters:
|
||
- in: path
|
||
name: id
|
||
required: true
|
||
schema: { type: string, format: uuid }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
'404':
|
||
description: Not found
|
||
|
||
/api/v1/admin/content-safety/evaluate:
|
||
post:
|
||
tags: [admin]
|
||
summary: Preview FilterRule matches (no ModerationCase write)
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [text]
|
||
properties:
|
||
text: { type: string }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
|
||
/api/v1/admin/ask/feedback:
|
||
get:
|
||
tags: [admin]
|
||
summary: List QualityFeedback
|
||
description: Requires admin.ask.read
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
'401':
|
||
description: Unauthorized
|
||
|
||
/api/v1/admin/ask/threads/{id}/feedback:
|
||
post:
|
||
tags: [admin]
|
||
summary: Create QualityFeedback (ops)
|
||
description: Requires admin.ask.feedback.write; writes AuditLog
|
||
parameters:
|
||
- in: path
|
||
name: id
|
||
required: true
|
||
schema: { type: string, format: uuid }
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [rating]
|
||
properties:
|
||
rating: { type: integer, minimum: 1, maximum: 5 }
|
||
tag: { type: string, enum: [helpful, off_topic, unsafe, other] }
|
||
note: { type: string }
|
||
message_id: { type: string, format: uuid }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
'400':
|
||
description: Invalid
|
||
'403':
|
||
description: Forbidden
|
||
|
||
/api/v1/ask/threads/{id}/feedback:
|
||
post:
|
||
tags: [ask]
|
||
summary: User QualityFeedback on owned thread
|
||
parameters:
|
||
- in: path
|
||
name: id
|
||
required: true
|
||
schema: { type: string, format: uuid }
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [rating]
|
||
properties:
|
||
rating: { type: integer, minimum: 1, maximum: 5 }
|
||
tag: { type: string }
|
||
note: { type: string }
|
||
message_id: { type: string, format: uuid }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
|
||
/api/v1/admin/orders:
|
||
get:
|
||
tags: [admin]
|
||
summary: List orders
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
|
||
/api/v1/admin/audit-logs:
|
||
get:
|
||
tags: [admin]
|
||
summary: List audit logs
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
|
||
/api/v1/admin/analytics/overview:
|
||
get:
|
||
tags: [admin]
|
||
summary: Behavior analytics overview (DAU / sessions)
|
||
parameters:
|
||
- in: query
|
||
name: from
|
||
schema: { type: string, format: date }
|
||
- in: query
|
||
name: to
|
||
schema: { type: string, format: date }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
|
||
/api/v1/admin/analytics/pages:
|
||
get:
|
||
tags: [admin]
|
||
summary: Page PV/UV/dwell/exit aggregates
|
||
parameters:
|
||
- in: query
|
||
name: from
|
||
schema: { type: string, format: date }
|
||
- in: query
|
||
name: to
|
||
schema: { type: string, format: date }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
|
||
/api/v1/admin/analytics/exits:
|
||
get:
|
||
tags: [admin]
|
||
summary: Exit page ranking
|
||
parameters:
|
||
- in: query
|
||
name: from
|
||
schema: { type: string, format: date }
|
||
- in: query
|
||
name: to
|
||
schema: { type: string, format: date }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
|
||
/api/v1/admin/analytics/clicks:
|
||
get:
|
||
tags: [admin]
|
||
summary: UI click ranking
|
||
parameters:
|
||
- in: query
|
||
name: from
|
||
schema: { type: string, format: date }
|
||
- in: query
|
||
name: to
|
||
schema: { type: string, format: date }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
|
||
/api/v1/admin/analytics/funnel:
|
||
get:
|
||
tags: [admin]
|
||
summary: Core funnel step counts
|
||
parameters:
|
||
- in: query
|
||
name: from
|
||
schema: { type: string, format: date }
|
||
- in: query
|
||
name: to
|
||
schema: { type: string, format: date }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
|
||
/api/v1/analytics/events:
|
||
post:
|
||
tags: [system]
|
||
summary: Batch ingest behavior events (DeviceAuth)
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [items]
|
||
properties:
|
||
items:
|
||
type: array
|
||
maxItems: 100
|
||
items:
|
||
type: object
|
||
required: [name, session_id, client_ts]
|
||
properties:
|
||
name: { type: string }
|
||
session_id: { type: string }
|
||
page_path: { type: string }
|
||
client_ts: {}
|
||
props: { type: object }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/Envelope'
|
||
|
||
/api/v1/home/tools:
|
||
get:
|
||
tags: [system]
|
||
summary: Homepage grid tools (enabled only)
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
|
||
/api/v1/admin/home/tools:
|
||
get:
|
||
tags: [admin]
|
||
summary: List all homepage tools
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
put:
|
||
tags: [admin]
|
||
summary: Replace homepage tools
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [items]
|
||
properties:
|
||
items: { type: array }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
|
||
/api/v1/admin/scales:
|
||
get:
|
||
tags: [admin]
|
||
summary: List all scales (incl. draft)
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
|
||
/api/v1/admin/scales/{id}:
|
||
patch:
|
||
tags: [admin]
|
||
summary: Set scale status published|draft
|
||
parameters:
|
||
- in: path
|
||
name: id
|
||
required: true
|
||
schema: { type: string, format: uuid }
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [status]
|
||
properties:
|
||
status: { type: string, enum: [published, draft] }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
|
||
/api/v1/profiles:
|
||
get:
|
||
tags: [profile]
|
||
summary: 列出个人档案
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvelopeProfileList'
|
||
post:
|
||
tags: [profile]
|
||
summary: 创建个人档案
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/CreateProfileRequest'
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '#/components/schemas/Envelope'
|
||
- type: object
|
||
properties:
|
||
data: { $ref: '#/components/schemas/Profile' }
|
||
|
||
/api/v1/profiles/{id}:
|
||
patch:
|
||
tags: [profile]
|
||
summary: 更新个人档案
|
||
parameters:
|
||
- $ref: '#/components/parameters/Id'
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '#/components/schemas/Envelope'
|
||
- type: object
|
||
properties:
|
||
data: { $ref: '#/components/schemas/Profile' }
|
||
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 按权益裁剪）
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvelopeGrowthReport'
|
||
|
||
/api/v1/explore/catalog:
|
||
get:
|
||
tags: [explore]
|
||
summary: 探索三级目录（L1 分类 → L3 工具）
|
||
responses:
|
||
'200':
|
||
description: categories[]
|
||
|
||
/api/v1/explore/catalog/{key}:
|
||
get:
|
||
tags: [explore]
|
||
summary: 单个探索分类
|
||
parameters:
|
||
- name: key
|
||
in: path
|
||
required: true
|
||
schema: { type: string }
|
||
responses:
|
||
'200':
|
||
description: Category
|
||
'404':
|
||
description: not found
|
||
|
||
/api/v1/growth/plans:
|
||
get:
|
||
tags: [growth]
|
||
summary: 成长计划列表
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
post:
|
||
tags: [growth]
|
||
summary: 创建成长计划
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
|
||
/api/v1/growth/plans/{id}/checkin:
|
||
post:
|
||
tags: [growth]
|
||
summary: 今日打卡
|
||
parameters:
|
||
- $ref: '#/components/parameters/Id'
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
|
||
/api/v1/growth/plans/{id}/checkins:
|
||
get:
|
||
tags: [growth]
|
||
summary: 打卡记录
|
||
parameters:
|
||
- $ref: '#/components/parameters/Id'
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
|
||
/api/v1/moods/recent:
|
||
get:
|
||
tags: [companion]
|
||
summary: 近七日心情轨迹
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
|
||
/api/v1/reports/star:
|
||
post:
|
||
tags: [star]
|
||
summary: 生成本命排盘 / 运势成长报告
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [profile_id]
|
||
properties:
|
||
profile_id: { type: string, format: uuid }
|
||
responses:
|
||
'200':
|
||
description: GrowthReport type=star；summary 含 chart/planets/aspects_preview/outlook(日周月年一生)/transits；无 fortune/lucky 键；detail 按权益裁剪
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvelopeGrowthReport'
|
||
|
||
/api/v1/reports/synastry:
|
||
post:
|
||
tags: [star]
|
||
summary: 生成双人合盘报告（五主盘 + 次限推运）
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [profile_id_a, profile_id_b]
|
||
properties:
|
||
profile_id_a: { type: string, format: uuid }
|
||
profile_id_b: { type: string, format: uuid }
|
||
as_of: { type: string, format: date, description: 次限推运日期 YYYY-MM-DD }
|
||
responses:
|
||
'200':
|
||
description: GrowthReport type=synastry（三指数 + charts 五主盘/推运）
|
||
|
||
/api/v1/synastry/nearby:
|
||
get:
|
||
tags: [star]
|
||
summary: 附近可合盘档案
|
||
parameters:
|
||
- in: query
|
||
name: lat
|
||
required: true
|
||
schema: { type: number }
|
||
- in: query
|
||
name: lng
|
||
required: true
|
||
schema: { type: number }
|
||
- in: query
|
||
name: radius_km
|
||
schema: { type: number, default: 50 }
|
||
responses:
|
||
'200':
|
||
description: items[{profile, distance_km}]
|
||
|
||
/api/v1/synastry/invites:
|
||
post:
|
||
tags: [star]
|
||
summary: 创建合盘邀请
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [profile_id]
|
||
properties:
|
||
profile_id: { type: string, format: uuid }
|
||
responses:
|
||
'200':
|
||
description: token / path / expires_at
|
||
|
||
/api/v1/synastry/invites/{token}:
|
||
get:
|
||
tags: [star]
|
||
summary: 邀请元数据
|
||
parameters:
|
||
- in: path
|
||
name: token
|
||
required: true
|
||
schema: { type: string }
|
||
responses:
|
||
'200':
|
||
description: host_name / expires_at / already_accepted
|
||
|
||
/api/v1/synastry/invites/{token}/accept:
|
||
post:
|
||
tags: [star]
|
||
summary: 接受合盘邀请并生成报告
|
||
parameters:
|
||
- in: path
|
||
name: token
|
||
required: true
|
||
schema: { type: string }
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [birth_date]
|
||
properties:
|
||
display_name: { type: string }
|
||
birth_date: { type: string, format: date }
|
||
birth_time: { type: string }
|
||
birth_place: { type: string }
|
||
responses:
|
||
'200':
|
||
description: GrowthReport type=synastry
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvelopeGrowthReport'
|
||
|
||
/api/v1/reports/rhythm:
|
||
post:
|
||
tags: [rhythm]
|
||
summary: 生成身心节律成长报告
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [profile_id]
|
||
properties:
|
||
profile_id: { type: string, format: uuid }
|
||
responses:
|
||
'200':
|
||
description: GrowthReport type=rhythm
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvelopeGrowthReport'
|
||
|
||
/api/v1/image-cards/scenes:
|
||
get:
|
||
tags: [image-card]
|
||
summary: 意象卡片场景列表
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvelopeImageCardScenes'
|
||
|
||
/api/v1/image-cards/quota:
|
||
get:
|
||
tags: [image-card]
|
||
summary: 今日抽卡剩余次数
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvelopeImageCardQuota'
|
||
|
||
/api/v1/image-cards/draw:
|
||
post:
|
||
tags: [image-card]
|
||
summary: 抽意象卡片（沉淀为 GrowthReport type=image_card）
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [profile_id]
|
||
properties:
|
||
profile_id: { type: string, format: uuid }
|
||
scene: { type: string }
|
||
depth: { type: boolean, description: 请求三卡组合（无权益则 detail 剥离） }
|
||
responses:
|
||
'200':
|
||
description: report + cards + quota_left
|
||
'402':
|
||
description: 免费次数用尽
|
||
|
||
/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:
|
||
get:
|
||
tags: [report]
|
||
summary: 列出当前用户成长报告
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvelopeReportList'
|
||
|
||
/api/v1/reports/{id}:
|
||
get:
|
||
tags: [report]
|
||
summary: 获取成长报告（权益裁剪）
|
||
parameters:
|
||
- $ref: '#/components/parameters/Id'
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvelopeGrowthReport'
|
||
|
||
/api/v1/scales:
|
||
get:
|
||
tags: [scale]
|
||
summary: 探索测试列表
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvelopeScaleList'
|
||
|
||
/api/v1/scales/{slug}:
|
||
get:
|
||
tags: [scale]
|
||
summary: 探索测试题目
|
||
parameters:
|
||
- name: slug
|
||
in: path
|
||
required: true
|
||
schema: { type: string }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvelopeScaleDetail'
|
||
|
||
/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/quota:
|
||
get:
|
||
tags: [ask]
|
||
summary: 当前问答剩余次数（免费额度或成长会员）
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvelopeAskQuota'
|
||
|
||
/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 }
|
||
scene: { type: string, description: self|relation|career|emotion|life }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
|
||
/api/v1/ask/threads/{id}/messages:
|
||
get:
|
||
tags: [ask]
|
||
summary: 拉取线程消息历史
|
||
parameters:
|
||
- $ref: '#/components/parameters/Id'
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
post:
|
||
tags: [ask]
|
||
summary: 发送消息（扣额度；P1 规则引擎回复）
|
||
parameters:
|
||
- $ref: '#/components/parameters/Id'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [content]
|
||
properties:
|
||
content: { type: string }
|
||
responses:
|
||
'200':
|
||
description: user + assistant + quota
|
||
'402':
|
||
description: 额度用尽
|
||
|
||
/api/v1/solar-terms/today:
|
||
get:
|
||
tags: [companion]
|
||
summary: 今日节气生活建议
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
|
||
/api/v1/moods:
|
||
post:
|
||
tags: [companion]
|
||
summary: 记录/更新当日心情
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
score: { type: integer, minimum: 1, maximum: 5 }
|
||
note: { type: string, maxLength: 200 }
|
||
day: { type: string, format: date }
|
||
responses:
|
||
'200':
|
||
description: Mood
|
||
|
||
/api/v1/moods/today:
|
||
get:
|
||
tags: [companion]
|
||
summary: 今日心情
|
||
responses:
|
||
'200':
|
||
description: '{ mood: Mood | null }'
|
||
|
||
/api/v1/membership/me:
|
||
get:
|
||
tags: [commerce]
|
||
summary: 当前成长会员权益
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvelopeMembershipMe'
|
||
|
||
/api/v1/membership/redeem:
|
||
post:
|
||
tags: [commerce]
|
||
summary: 兑换会员码
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [code]
|
||
properties:
|
||
code: { type: string }
|
||
responses:
|
||
'200':
|
||
description: OK
|
||
'400':
|
||
description: Invalid or used code
|
||
'401':
|
||
description: Unauthorized
|
||
|
||
/api/v1/orders:
|
||
post:
|
||
tags: [commerce]
|
||
summary: 创建订单（membership | deep_access | ask_pack）
|
||
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 }
|
||
|
||
AdminMe:
|
||
type: object
|
||
required: [id, username, permissions]
|
||
properties:
|
||
id: { type: string, format: uuid }
|
||
username: { type: string }
|
||
role: { type: string }
|
||
permissions:
|
||
type: array
|
||
items: { type: string }
|
||
|
||
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, ask_pack] }
|
||
plan: { type: string, description: month|quarter|year when membership; pack10|pack30|pack100 when ask_pack }
|
||
report_id: { type: string, format: uuid, description: when deep_access }
|
||
|
||
# --- Aligned with packages/types (ECR-004) ---
|
||
Profile:
|
||
type: object
|
||
required: [id, user_id, relation, display_name, birth_date, created_at]
|
||
properties:
|
||
id: { type: string, format: uuid }
|
||
user_id: { type: string, format: uuid }
|
||
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 }
|
||
relation_type: { type: string, nullable: true }
|
||
geo_lat: { type: number, nullable: true }
|
||
geo_lng: { type: number, nullable: true }
|
||
geo_visible: { type: boolean }
|
||
created_at: { type: string, format: date-time }
|
||
|
||
GrowthReport:
|
||
type: object
|
||
required: [id, user_id, profile_id, type, summary, has_deep_access, created_at]
|
||
properties:
|
||
id: { type: string, format: uuid }
|
||
user_id: { type: string, format: uuid }
|
||
profile_id: { type: string, format: uuid }
|
||
type: { type: string }
|
||
summary: { type: object, additionalProperties: true }
|
||
detail: { type: object, nullable: true, additionalProperties: true }
|
||
has_deep_access: { type: boolean }
|
||
created_at: { type: string, format: date-time }
|
||
|
||
MembershipMe:
|
||
type: object
|
||
required: [active, status]
|
||
properties:
|
||
active: { type: boolean }
|
||
plan: { type: string }
|
||
status: { type: string }
|
||
expires_at: { type: string, format: date-time, nullable: true }
|
||
ask_quota_left: { type: integer }
|
||
|
||
ScaleSummary:
|
||
type: object
|
||
required: [slug, title, description]
|
||
properties:
|
||
slug: { type: string }
|
||
title: { type: string }
|
||
description: { type: string }
|
||
|
||
ScaleQuestionOption:
|
||
type: object
|
||
required: [key, text]
|
||
properties:
|
||
key: { type: string }
|
||
text: { type: string }
|
||
|
||
ScaleQuestion:
|
||
type: object
|
||
required: [id, sort, body]
|
||
properties:
|
||
id: { type: string, format: uuid }
|
||
sort: { type: integer }
|
||
body:
|
||
type: object
|
||
required: [prompt, options]
|
||
properties:
|
||
prompt: { type: string }
|
||
options:
|
||
type: array
|
||
items: { $ref: '#/components/schemas/ScaleQuestionOption' }
|
||
|
||
ScaleDetail:
|
||
type: object
|
||
required: [slug, title, description, questions]
|
||
properties:
|
||
slug: { type: string }
|
||
title: { type: string }
|
||
description: { type: string }
|
||
questions:
|
||
type: array
|
||
items: { $ref: '#/components/schemas/ScaleQuestion' }
|
||
|
||
ScaleSubmitResult:
|
||
type: object
|
||
required: [id, result]
|
||
properties:
|
||
id: { type: string, format: uuid }
|
||
result: { type: object, additionalProperties: true }
|
||
|
||
AskQuota:
|
||
type: object
|
||
required: [active_membership, remaining, free_limit, source]
|
||
properties:
|
||
active_membership: { type: boolean }
|
||
remaining: { type: integer }
|
||
free_limit: { type: integer }
|
||
source: { type: string }
|
||
|
||
AskThread:
|
||
type: object
|
||
required: [id, user_id, profile_id, created_at]
|
||
properties:
|
||
id: { type: string, format: uuid }
|
||
user_id: { type: string, format: uuid }
|
||
profile_id: { type: string, format: uuid }
|
||
scene: { type: string, nullable: true }
|
||
created_at: { type: string, format: date-time }
|
||
|
||
AskMessage:
|
||
type: object
|
||
required: [id, thread_id, role, content, created_at]
|
||
properties:
|
||
id: { type: string, format: uuid }
|
||
thread_id: { type: string, format: uuid }
|
||
role: { type: string, enum: [user, assistant] }
|
||
content: { type: string }
|
||
created_at: { type: string, format: date-time }
|
||
|
||
ImageCardScene:
|
||
type: object
|
||
required: [key, label]
|
||
properties:
|
||
key: { type: string }
|
||
label: { type: string }
|
||
|
||
ImageCardQuota:
|
||
type: object
|
||
required: [remaining, daily_free, unlimited]
|
||
properties:
|
||
remaining: { type: integer }
|
||
daily_free: { type: integer }
|
||
unlimited: { type: boolean }
|
||
|
||
EnvelopeProfileList:
|
||
allOf:
|
||
- $ref: '#/components/schemas/Envelope'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
items:
|
||
type: array
|
||
items: { $ref: '#/components/schemas/Profile' }
|
||
|
||
EnvelopeGrowthReport:
|
||
allOf:
|
||
- $ref: '#/components/schemas/Envelope'
|
||
- type: object
|
||
properties:
|
||
data: { $ref: '#/components/schemas/GrowthReport' }
|
||
|
||
EnvelopeMembershipMe:
|
||
allOf:
|
||
- $ref: '#/components/schemas/Envelope'
|
||
- type: object
|
||
properties:
|
||
data: { $ref: '#/components/schemas/MembershipMe' }
|
||
|
||
EnvelopeScaleList:
|
||
allOf:
|
||
- $ref: '#/components/schemas/Envelope'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
items:
|
||
type: array
|
||
items: { $ref: '#/components/schemas/ScaleSummary' }
|
||
|
||
EnvelopeAskQuota:
|
||
allOf:
|
||
- $ref: '#/components/schemas/Envelope'
|
||
- type: object
|
||
properties:
|
||
data: { $ref: '#/components/schemas/AskQuota' }
|
||
|
||
EnvelopeReportList:
|
||
allOf:
|
||
- $ref: '#/components/schemas/Envelope'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
items:
|
||
type: array
|
||
items: { $ref: '#/components/schemas/GrowthReport' }
|
||
|
||
EnvelopeScaleDetail:
|
||
allOf:
|
||
- $ref: '#/components/schemas/Envelope'
|
||
- type: object
|
||
properties:
|
||
data: { $ref: '#/components/schemas/ScaleDetail' }
|
||
|
||
EnvelopeImageCardScenes:
|
||
allOf:
|
||
- $ref: '#/components/schemas/Envelope'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
items:
|
||
type: array
|
||
items: { $ref: '#/components/schemas/ImageCardScene' }
|
||
|
||
EnvelopeImageCardQuota:
|
||
allOf:
|
||
- $ref: '#/components/schemas/Envelope'
|
||
- type: object
|
||
properties:
|
||
data: { $ref: '#/components/schemas/ImageCardQuota' }
|