feat: expand companion platform, device controls, and memoir workflows

Add customer and operator login, BLE provisioning, device fleet controls, call memory, memoir generation, and refreshed family and maintenance portals. Include API contracts, migrations, firmware sources, tests, assets, and deployment documentation.

openapi/openapi.yaml

@@ -1,12 +1,102 @@
 openapi: 3.1.0
 info:
   title: 数据采集终端—云端系统 API
-  version: 0.78.0
+  version: 0.79.0
   description: 工程框架、SaaS核心业务、设备v2 RTC/VoiceChat兼容链路、设备v3火山硬件对话智能体控制面、每次会话人设与授权记忆冻结、SDK和音频能力门禁、动态配置生效证明、可靠设备事件和终稿补传、通话中受控记忆工具、首次通话就绪与最低固件门禁、背景资料准备失败闭环、活动通话授权撤回安全停止、语音内容闭环、批量设备遥测、录音上传队列、隐私对账、固件、双轨录音、状态事件、具体资源分享、受控运营配置、Agent组合组件引用、质量证据门禁、运营自定义版本族投放、新通话运行时冻结与供应商启动传递、带并发版本校验的配置投放暂停恢复、带严重度和验收证据门禁的联调问题闭环、含阻断告警定位、当前主机健康及生产部署标记、实际应用环境、身份服务模式、异地备份、外部告警与模拟服务强制条件的发布候选技术验收快照、绑定候选版本与构建摘要并按业务时区生成的可审计试点日/周运行证据、可审计且不生成正式告警的接收器联通测试、外部依赖预检台账、证书到期清单，以及带价格版本冻结、供应商用量去重和硬额度控制的费用治理接口。
 servers:
   - url: http://localhost:58080
     description: 本地开发
 paths:
+  /api/v1/ops/login-captcha-policy:
+    $ref: './login-captcha.yaml#/paths/~1api~1v1~1ops~1login-captcha-policy'
+  /api/v1/mini/login/session:
+    $ref: './mini.yaml#/paths/~1api~1v1~1mini~1login~1session'
+  /api/v1/mini/login/captcha:
+    $ref: './mini.yaml#/paths/~1api~1v1~1mini~1login~1captcha'
+  /api/v1/mini/login/password:
+    $ref: './mini.yaml#/paths/~1api~1v1~1mini~1login~1password'
+  /api/v1/mini/login/sms/send:
+    $ref: './mini.yaml#/paths/~1api~1v1~1mini~1login~1sms~1send'
+  /api/v1/mini/login/sms/verify:
+    $ref: './mini.yaml#/paths/~1api~1v1~1mini~1login~1sms~1verify'
+  /api/v1/mini/account:
+    $ref: './mini.yaml#/paths/~1api~1v1~1mini~1account'
+  /api/v1/mini/logout:
+    $ref: './mini.yaml#/paths/~1api~1v1~1mini~1logout'
+  /api/v1/mini/ble-session:
+    $ref: './mini.yaml#/paths/~1api~1v1~1mini~1ble-session'
+  /api/v1/mini/ble-bind-tokens:
+    $ref: './mini.yaml#/paths/~1api~1v1~1mini~1ble-bind-tokens'
+  /api/v1/mini/ble-bind-status:
+    $ref: './mini.yaml#/paths/~1api~1v1~1mini~1ble-bind-status'
+  /api/v1/web/ble-bind-tokens:
+    $ref: './ble-binding.yaml#/paths/~1api~1v1~1web~1ble-bind-tokens'
+  /api/v1/web/ble-bind-status:
+    $ref: './ble-binding.yaml#/paths/~1api~1v1~1web~1ble-bind-status'
+  /api/v1/device/ble-bind:
+    $ref: './ble-binding.yaml#/paths/~1api~1v1~1device~1ble-bind'
+  /api/v1/web/operator/login/session:
+    $ref: './operator-login.yaml#/paths/~1api~1v1~1web~1operator~1login~1session'
+  /api/v1/web/operator/login/captcha:
+    $ref: './operator-login.yaml#/paths/~1api~1v1~1web~1operator~1login~1captcha'
+  /api/v1/web/operator/login/captcha/verify:
+    $ref: './operator-login.yaml#/paths/~1api~1v1~1web~1operator~1login~1captcha~1verify'
+  /api/v1/web/operator/login/password:
+    $ref: './operator-login.yaml#/paths/~1api~1v1~1web~1operator~1login~1password'
+  /api/v1/web/operator/login/sms/send:
+    $ref: './operator-login.yaml#/paths/~1api~1v1~1web~1operator~1login~1sms~1send'
+  /api/v1/web/operator/login/sms/verify:
+    $ref: './operator-login.yaml#/paths/~1api~1v1~1web~1operator~1login~1sms~1verify'
+  /api/v1/web/operator/account/session:
+    $ref: './operator-login.yaml#/paths/~1api~1v1~1web~1operator~1account~1session'
+  /api/v1/web/operator/account/password:
+    $ref: './operator-login.yaml#/paths/~1api~1v1~1web~1operator~1account~1password'
+  /api/v1/web/operator/auth/logout:
+    $ref: './operator-login.yaml#/paths/~1api~1v1~1web~1operator~1auth~1logout'
+  /api/v1/web/login/session:
+    $ref: './customer-login.yaml#/paths/~1api~1v1~1web~1login~1session'
+  /api/v1/web/login/captcha:
+    $ref: './customer-login.yaml#/paths/~1api~1v1~1web~1login~1captcha'
+  /api/v1/web/login/captcha/verify:
+    $ref: './customer-login.yaml#/paths/~1api~1v1~1web~1login~1captcha~1verify'
+  /api/v1/web/login/password:
+    $ref: './customer-login.yaml#/paths/~1api~1v1~1web~1login~1password'
+  /api/v1/web/account/password:
+    $ref: './customer-login.yaml#/paths/~1api~1v1~1web~1account~1password'
+  /api/v1/web/login/sms/send:
+    $ref: './customer-login.yaml#/paths/~1api~1v1~1web~1login~1sms~1send'
+  /api/v1/web/login/sms/verify:
+    $ref: './customer-login.yaml#/paths/~1api~1v1~1web~1login~1sms~1verify'
+  /api/v1/device/calls/command-acks:
+    $ref: './call-memory.yaml#/paths/~1api~1v1~1device~1calls~1command-acks'
+  /api/v1/device/calls/end:
+    $ref: './call-memory.yaml#/paths/~1api~1v1~1device~1calls~1end'
+  /api/v1/device/calls/events:
+    $ref: './call-memory.yaml#/paths/~1api~1v1~1device~1calls~1events'
+  /api/v1/device/calls/heartbeat:
+    $ref: './call-memory.yaml#/paths/~1api~1v1~1device~1calls~1heartbeat'
+  /api/v1/device/calls/prepare:
+    $ref: './call-memory.yaml#/paths/~1api~1v1~1device~1calls~1prepare'
+  /api/v1/device/calls/status:
+    $ref: './call-memory.yaml#/paths/~1api~1v1~1device~1calls~1status'
+  /api/v1/device/calls/warmup:
+    $ref: './call-memory.yaml#/paths/~1api~1v1~1device~1calls~1warmup'
+  /api/v1/memories/access/grant:
+    $ref: './call-memory.yaml#/paths/~1api~1v1~1memories~1access~1grant'
+  /api/v1/memories/access/query:
+    $ref: './call-memory.yaml#/paths/~1api~1v1~1memories~1access~1query'
+  /api/v1/memories/mutations:
+    $ref: './call-memory.yaml#/paths/~1api~1v1~1memories~1mutations'
+  /api/v1/memories/mutations/confirm:
+    $ref: './call-memory.yaml#/paths/~1api~1v1~1memories~1mutations~1confirm'
+  /api/v1/memories/mutations/resolve:
+    $ref: './call-memory.yaml#/paths/~1api~1v1~1memories~1mutations~1resolve'
+  /api/v1/memories/mutations/status:
+    $ref: './call-memory.yaml#/paths/~1api~1v1~1memories~1mutations~1status'
+  /api/v1/memories/query:
+    $ref: './call-memory.yaml#/paths/~1api~1v1~1memories~1query'
+  /api/v1/memories/sync/status:
+    $ref: './call-memory.yaml#/paths/~1api~1v1~1memories~1sync~1status'
   /api/v1/device/time-challenges:
     $ref: './onboarding.yaml#/paths/~1api~1v1~1device~1time-challenges'
   /api/v1/device/register:
@@ -35,6 +125,10 @@ paths:
     $ref: './onboarding.yaml#/paths/~1api~1v1~1web~1setup~1session'
   /api/v1/web/setup/auth-link:
     $ref: './onboarding.yaml#/paths/~1api~1v1~1web~1setup~1auth-link'
+  /api/v1/web/auth/captcha:
+    $ref: './onboarding.yaml#/paths/~1api~1v1~1web~1auth~1captcha'
+  /api/v1/web/auth/captcha/verify:
+    $ref: './onboarding.yaml#/paths/~1api~1v1~1web~1auth~1captcha~1verify'
   /api/v1/web/auth/sms/send:
     $ref: './onboarding.yaml#/paths/~1api~1v1~1web~1auth~1sms~1send'
   /api/v1/web/auth/sms/verify:
@@ -1089,6 +1183,77 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
+  /api/v1/me/profile:
+    patch:
+      operationId: updateCurrentUserDisplayName
+      tags: [identity]
+      summary: 更新当前登录身份的昵称
+      description: 仅更新已认证身份的有效账号；不接受账号 ID。Cookie 登录写入仍需 CSRF token。
+      security: [{ oidcBearer: [] }]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: false
+              required: [display_name]
+              properties:
+                display_name: { type: string, minLength: 1, maxLength: 80 }
+      responses:
+        '200':
+          description: 昵称已保存，响应不缓存
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  ok: { type: boolean }
+                  data:
+                    type: object
+                    required: [display_name]
+                    properties:
+                      display_name: { type: string }
+        '400': { description: 昵称无效或请求包含未知字段 }
+        '401': { $ref: '#/components/responses/AuthenticationError' }
+        '403': { description: 当前身份没有有效账号 }
+  /api/v1/events/history:
+    get:
+      operationId: listFamilyActivityHistory
+      tags: [identity]
+      summary: 最近七天的家庭动态
+      description: 返回仍有有效成员关系的家庭的事件元数据，按事件 ID 倒序，最多 200 条；不含聊天内容；响应不缓存。旧版已过期的事件不回填。
+      security: [{ oidcBearer: [] }]
+      responses:
+        '200':
+          description: 家庭动态列表
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  ok: { type: boolean }
+                  data:
+                    type: object
+                    required: [items, limit, retention_days]
+                    properties:
+                      limit: { type: integer, enum: [200] }
+                      retention_days: { type: integer, enum: [7] }
+                      items:
+                        type: array
+                        items:
+                          type: object
+                          required: [id, type, household_id, resource_type, resource_id, status, occurred_at]
+                          properties:
+                            id: { type: integer, format: int64 }
+                            type: { type: string }
+                            household_id: { type: string, format: uuid }
+                            subject_id: { type: string, format: uuid }
+                            resource_type: { type: string }
+                            resource_id: { type: string, format: uuid }
+                            status: { type: string }
+                            occurred_at: { type: string, format: date-time }
+        '401': { $ref: '#/components/responses/AuthenticationError' }
   /api/v1/households:
     get:
       operationId: listHouseholds
@@ -1341,6 +1506,7 @@ paths:
         '403': { $ref: '#/components/responses/AccessDeniedError' }
     post:
       operationId: createSubject
+      description: 创建长者资料，创建流程逐项展示全部授权；仅为用户明确勾选并确认的项目记录授权。省略 initial_consents 或选择空列表时不开通数据授权，各项授权可独立撤回。
       tags: [subject]
       security: [{ oidcBearer: [] }]
       requestBody:
@@ -1387,6 +1553,28 @@ paths:
         '403': { $ref: '#/components/responses/AccessDeniedError' }
         '412': { $ref: '#/components/responses/VersionConflictError' }
         '428': { $ref: '#/components/responses/PreconditionRequiredError' }
+  /api/v1/subjects/{id}/voice-agent:
+    parameters:
+      - $ref: '#/components/parameters/ResourceID'
+    post:
+      operationId: ensureSubjectVoiceAgent
+      tags: [subject]
+      description: 创建或恢复专属语音智能体；已就绪时重试同步最新档案。活动通话期间延后同步。资料同步失败保留 READY 创建状态，通过 persona_sync_status 返回。
+      security: [{ oidcBearer: [] }]
+      responses:
+        '200':
+          description: 当前创建状态与资料同步状态
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [request_id, data]
+                properties:
+                  request_id: { type: string }
+                  data: { $ref: '#/components/schemas/SubjectVoiceAgent' }
+        '401': { $ref: '#/components/responses/AuthenticationError' }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+        '502': { description: 智能体创建或产品关联失败 }
   /api/v1/subjects/{id}/conversation-readiness:
     parameters:
       - $ref: '#/components/parameters/ResourceID'
@@ -1707,7 +1895,7 @@ paths:
       tags: [device-management]
       security: [{ oidcBearer: [] }]
       parameters: [{ $ref: '#/components/parameters/RequiredTenantSelectionHeader' }]
-      description: 自动生成设备UUID和256位随机HMAC密钥；密钥明文仅在本响应出现一次。
+      description: 直接创建可通过端到端蓝牙实体确认绑定的设备，并生成一次性烧录信息；设备密钥明文仅在本响应出现一次。
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/CreateOpsDeviceRequest' } } } }
       responses:
         '201': { description: 设备及一次性密钥, content: { application/json: { schema: { $ref: '#/components/schemas/CreateOpsDeviceResponse' } } } }
@@ -2438,6 +2626,19 @@ paths:
         '403': { $ref: '#/components/responses/AccessDeniedError' }
         '412': { $ref: '#/components/responses/VersionConflictError' }
         '428': { $ref: '#/components/responses/PreconditionRequiredError' }
+  /api/v1/households/{id}/privacy-requests:
+    parameters: [{ $ref: '#/components/parameters/ResourceID' }]
+    get:
+      operationId: listHouseholdPrivacyRequests
+      tags: [privacy]
+      security: [{ oidcBearer: [] }]
+      description: 需要有效家庭成员身份及 privacy.read 权限；包含正在删除及已删除长者的请求，便于持续查看处理终态。
+      responses:
+        '200':
+          description: 返回当前家庭所有长者的隐私请求及处理结果，按创建时间倒序。
+          content: { application/json: { schema: { $ref: '#/components/schemas/PrivacyRequestListResponse' } } }
+        '401': { $ref: '#/components/responses/AuthenticationError' }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
   /api/v1/subjects/{id}/privacy-requests:
     parameters: [{ $ref: '#/components/parameters/ResourceID' }]
     get:
@@ -2446,7 +2647,7 @@ paths:
       security: [{ oidcBearer: [] }]
       responses:
         '200':
-          description: 返回当前长者的隐私请求及处理结果。
+          description: 返回当前长者的隐私请求及处理结果，包括正在删除或已删除的长者；仍需有效家庭成员身份及 privacy.read 权限。
           content: { application/json: { schema: { $ref: '#/components/schemas/PrivacyRequestListResponse' } } }
         '401': { $ref: '#/components/responses/AuthenticationError' }
         '403': { $ref: '#/components/responses/AccessDeniedError' }
@@ -5131,6 +5332,19 @@ components:
         invitee_hint: { type: string, maxLength: 255 }
         role: { type: string, enum: [admin, editor, viewer] }
         expires_at: { type: string, format: date-time }
+    SubjectVoiceAgent:
+      type: object
+      additionalProperties: false
+      required: [status, personalization_included]
+      properties:
+        bot_id: { type: string }
+        status: { type: string, enum: [PENDING, READY, FAILED] }
+        message: { type: string }
+        persona_sync_status: { type: string, enum: [PENDING, SYNCED, DEFERRED, FAILED] }
+        persona_revision: { type: integer, format: int64, minimum: 1 }
+        persona_synced_revision: { type: integer, format: int64, minimum: 0 }
+        persona_synced_at: { type: string, format: date-time }
+        personalization_included: { type: boolean, description: 已同步配置是否包含授权后的兴趣、背景、陪伴方向和优先话题。 }
     Subject:
       type: object
       additionalProperties: false
@@ -5144,6 +5358,7 @@ components:
         profile_data: { $ref: '#/components/schemas/SubjectProfileData' }
         conversation_preferences: { $ref: '#/components/schemas/SubjectConversationPreferences' }
         status: { type: string, enum: [active, suspended, deleting] }
+        voice_agent: { $ref: '#/components/schemas/SubjectVoiceAgent' }
         version: { type: integer, format: int64, minimum: 1 }
         created_at: { type: string, format: date-time }
         updated_at: { type: string, format: date-time }
@@ -5152,11 +5367,23 @@ components:
       additionalProperties: false
       required: [preferred_name, language, timezone, profile_data, conversation_preferences]
       properties:
+        initial_consents: { $ref: '#/components/schemas/InitialConsentSelection' }
         preferred_name: { type: string, minLength: 1, maxLength: 120 }
         language: { type: string, minLength: 1, maxLength: 32, pattern: '^[A-Za-z0-9-]+$' }
         timezone: { type: string, minLength: 1, maxLength: 64 }
         profile_data: { $ref: '#/components/schemas/SubjectProfileData' }
         conversation_preferences: { $ref: '#/components/schemas/SubjectConversationPreferences' }
+    InitialConsentSelection:
+      type: object
+      additionalProperties: false
+      required: [types, confirmed]
+      properties:
+        types:
+          type: array
+          maxItems: 5
+          uniqueItems: true
+          items: { type: string, enum: [transcript_storage, raw_audio_storage, story_extraction, personalized_memory, family_sharing] }
+        confirmed: { type: boolean, description: 有选中项目时必须为 true，表示用户已确认所选用途 }
     UpdateSubjectRequest:
       type: object
       additionalProperties: false
@@ -5311,10 +5538,11 @@ components:
       additionalProperties: false
       required: [id, binding_id, household_id, subject_id, subject_name, model, status, desired_revision, bound_at, registered_at, version]
       properties:
+        account_binding_id: { type: string, format: uuid, description: 仅已添加到账号且待绑定老人的设备返回；绑定老人时用于归属版本校验。 }
         id: { type: string, format: uuid }
         binding_id: { type: string, format: uuid, description: 当前有效绑定编号；解绑或转移时用于并发校验。 }
-        household_id: { type: string, format: uuid }
-        subject_id: { type: string, format: uuid }
+        household_id: { oneOf: [{ type: string, format: uuid }, { const: '' }], description: 待绑定老人时为空字符串。 }
+        subject_id: { oneOf: [{ type: string, format: uuid }, { const: '' }], description: 待绑定老人时为空字符串。 }
         subject_name: { type: string }
         model: { type: string }
         hardware_revision: { type: string }
@@ -5331,10 +5559,13 @@ components:
     OpsDevice:
       type: object
       additionalProperties: false
-      required: [id, tenant_id, model, status, activation_state, activation_revision, activation_updated_at, credential_status, key_version, registered_at, updated_at, version, voice_runtime]
+      required: [id, tenant_id, factory_id, enrollment_mode, bound, model, status, activation_state, activation_revision, activation_updated_at, credential_status, key_version, registered_at, updated_at, version, voice_runtime]
       properties:
         id: { type: string, format: uuid }
         tenant_id: { type: string, format: uuid }
+        factory_id: { type: string, description: 烧录并用于设备认证的出厂设备编号；历史旧设备可能为空字符串。 }
+        enrollment_mode: { type: string, enum: [legacy, physical_confirm] }
+        bound: { type: boolean, description: 是否已有当前有效的家庭或账号归属。 }
         model: { type: string, minLength: 1, maxLength: 120 }
         hardware_revision: { type: string, maxLength: 80 }
         status: { type: string, enum: [registered, quarantined, revoked] }
@@ -5375,13 +5606,6 @@ components:
       required: [model]
       properties:
         model: { type: string, minLength: 1, maxLength: 120 }
-        hardware_revision: { type: string, maxLength: 80 }
-        minimum_security_version: { type: string, maxLength: 80 }
-        minimum_firmware_version: { type: string, maxLength: 80 }
-        household_id: { type: string, format: uuid }
-        subject_id: { type: string, format: uuid }
-        voice_runtime: { type: string, enum: [legacy_voicechat, volc_hardware_agent] }
-        activation_state: { type: string, enum: [FACTORY, CLAIMABLE, BOUND], description: 可选。未指定时，有归属为BOUND，无归属为CLAIMABLE；FACTORY仅允许未分配设备。 }
     UpdateOpsDeviceRequest:
       type: object
       additionalProperties: false
@@ -5434,12 +5658,13 @@ components:
     DeviceCredentialIssue:
       type: object
       additionalProperties: false
-      required: [device_id, secret, key_version, issued_at]
+      required: [factory_id, model, origin, device_key_hex, key_version]
       properties:
-        device_id: { type: string, format: uuid }
-        secret: { type: string, pattern: '^[0-9a-f]{64}$', description: 仅本响应返回一次。 }
+        factory_id: { type: string, pattern: '^KP01-[0-9A-F]{12}$' }
+        model: { type: string, minLength: 1, maxLength: 120 }
+        origin: { type: string, format: uri }
+        device_key_hex: { type: string, pattern: '^[0-9a-f]{64}$', description: 仅本响应返回一次。 }
         key_version: { type: integer, format: int64, minimum: 1 }
-        issued_at: { type: string, format: date-time }
     DeviceClaimIssue:
       type: object
       additionalProperties: false
@@ -5472,7 +5697,7 @@ components:
       required: [request_id, data]
       properties:
         request_id: { type: string }
-        data: { type: object, required: [device, credential], properties: { device: { $ref: '#/components/schemas/OpsDevice' }, credential: { $ref: '#/components/schemas/DeviceCredentialIssue' }, claim: { $ref: '#/components/schemas/DeviceClaimIssue' } } }
+        data: { type: object, required: [device, credential], properties: { device: { $ref: '#/components/schemas/OpsDevice' }, credential: { $ref: '#/components/schemas/DeviceCredentialIssue' } } }
     DeviceCredentialIssueResponse:
       type: object
       required: [request_id, data]
@@ -5493,8 +5718,8 @@ components:
         device_id: { type: string, format: uuid }
         binding_id: { type: string, format: uuid }
         action: { type: string, enum: [unbind, transfer] }
-        source_household_id: { type: string, format: uuid }
-        source_subject_id: { type: string, format: uuid }
+        source_household_id: { oneOf: [{ type: string, format: uuid }, { const: '' }] }
+        source_subject_id: { oneOf: [{ type: string, format: uuid }, { const: '' }] }
         source_subject_name: { type: string }
         target_household_id: { type: string, format: uuid }
         target_subject_id: { type: string, format: uuid }
@@ -5503,9 +5728,10 @@ components:
         pending_command_count: { type: integer, minimum: 0 }
         active_firmware_task_count: { type: integer, minimum: 0 }
         allowed: { type: boolean }
+        requires_physical_confirmation: { type: boolean, description: 转移需要经蓝牙提交并由设备实体确认，不能直接调用旧版转移接口。 }
         blockers:
           type: array
-          items: { type: string, enum: [target_subject_required, active_conversation, pending_device_commands, active_firmware_task] }
+          items: { type: string, enum: [target_subject_required, active_conversation, active_call, pending_device_commands, active_firmware_task, active_mqtt_ota] }
         evaluated_at: { type: string, format: date-time }
     ChangeDeviceBindingRequest:
       type: object
@@ -5572,6 +5798,24 @@ components:
           type: object
           additionalProperties: false
           properties:
+            power:
+              type: object
+              additionalProperties: false
+              required: [mode]
+              properties:
+                mode:
+                  type: string
+                  enum: [active, standby]
+                  description: 远程唤醒或待机；仅设备已上报支持时可设置，设备空闲后执行。
+            identity:
+              type: object
+              additionalProperties: false
+              required: [display_name]
+              properties:
+                display_name:
+                  type: string
+                  maxLength: 96
+                  description: 设备名称，UTF-8编码最多96字节，不含首尾空白或控制字符；空字符串恢复默认名称。
             volume:
               type: object
               additionalProperties: true
@@ -6168,7 +6412,10 @@ components:
       additionalProperties: false
       required: [turn_id, sequence_no, speaker, text]
       properties:
-        turn_id: { type: string, format: uuid }
+        turn_id: { type: string, description: 原有话轮公开 ID 或设备会话内的原话标识 }
+        call_session_id: { type: string, format: uuid }
+        utterance_id: { type: string }
+        source_revision: { type: integer, format: int64, minimum: 0 }
         sequence_no: { type: integer, format: int64, minimum: 1 }
         speaker: { type: string, enum: [subject, agent] }
         text: { type: string }
@@ -6185,7 +6432,7 @@ components:
         statement_basis: { type: string, enum: [subject_statement, model_inference] }
         confidence: { type: number, minimum: 0, maximum: 1 }
         sensitivity: { type: string, enum: [normal, sensitive, high] }
-        source_turn_ids: { type: array, minItems: 1, items: { type: string, format: uuid } }
+        source_turn_ids: { type: array, minItems: 1, items: { type: string } }
         status: { type: string, enum: [CANDIDATE, CONFIRMED, REJECTED, SUPERSEDED] }
         version: { type: integer, format: int64, minimum: 1 }
     UpdateFactCandidateRequest:
@@ -6203,11 +6450,15 @@ components:
     Story:
       type: object
       additionalProperties: false
-      required: [id, subject_id, conversation_id, title, content, status, sensitivity, generation_version, revision_no, author_type, version, created_at, updated_at, sources, facts]
+      required: [id, subject_id, title, content, status, sensitivity, generation_version, revision_no, author_type, version, created_at, updated_at, sources, facts]
+      oneOf:
+        - required: [conversation_id]
+        - required: [call_session_id]
       properties:
         id: { type: string, format: uuid }
         subject_id: { type: string, format: uuid }
         conversation_id: { type: string, format: uuid }
+        call_session_id: { type: string, format: uuid }
         title: { type: string, minLength: 1, maxLength: 300 }
         content: { type: string, minLength: 1, maxLength: 50000 }
         status: { $ref: '#/components/schemas/StoryStatus' }
@@ -6404,7 +6655,10 @@ components:
         subject_id: { type: string, format: uuid }
         request_type: { type: string, enum: [ACCESS, CORRECTION, CONSENT_WITHDRAWAL, DELETE] }
         scope: { type: object, additionalProperties: true }
-        status: { type: string, enum: [SUBMITTED, VERIFYING, EXECUTING, COMPLETED, PARTIAL_FAILED] }
+        status:
+          type: string
+          enum: [SUBMITTED, VERIFYING, EXECUTING, COMPLETED, PARTIAL_FAILED]
+          description: 非终态请求如有失败子任务，读取时返回 PARTIAL_FAILED；不会因此改写请求记录或触发重试。
         deadline_at: { type: string, format: date-time }
         legal_hold: { type: boolean }
         result_summary: { type: object, additionalProperties: true }