{ "openapi": "3.1.0", "info": { "title": "NeoZQYY API", "description": "台球门店运营助手 — 后端 API（管理后台 + 微信小程序）", "version": "0.1.0" }, "paths": { "/api/auth/login": { "post": { "tags": [ "认证" ], "summary": "Login", "description": "用户登录。\n\n查询 admin_users 表验证用户名密码，成功后返回 JWT 令牌对。\n- 用户不存在或密码错误：401\n- 账号已禁用（is_active=false）：401", "operationId": "login_api_auth_login_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/auth/refresh": { "post": { "tags": [ "认证" ], "summary": "Refresh", "description": "刷新访问令牌。\n\n验证 refresh_token 有效性，成功后仅返回新的 access_token\n（refresh_token 保持不变，由客户端继续持有）。", "operationId": "refresh_api_auth_refresh_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/tasks/registry": { "get": { "tags": [ "任务配置" ], "summary": "Get Task Registry", "description": "返回按业务域分组的任务列表", "operationId": "get_task_registry_api_tasks_registry_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRegistryResponse" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/tasks/dwd-tables": { "get": { "tags": [ "任务配置" ], "summary": "Get Dwd Tables", "description": "返回按业务域分组的 DWD 表定义", "operationId": "get_dwd_tables_api_tasks_dwd_tables_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DwdTablesResponse" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/tasks/flows": { "get": { "tags": [ "任务配置" ], "summary": "Get Flows", "description": "返回 7 种 Flow 定义和 4 种处理模式定义", "operationId": "get_flows_api_tasks_flows_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowsResponse" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/tasks/validate": { "post": { "tags": [ "任务配置" ], "summary": "Validate Task Config", "description": "验证 TaskConfig 并返回生成的 CLI 命令预览\n\n从 JWT 注入 store_id，前端无需传递。", "operationId": "validate_task_config_api_tasks_validate_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/tasks/sync-check": { "get": { "tags": [ "任务配置" ], "summary": "Sync Check", "description": "对比后端硬编码任务列表与 ETL 真实注册表，返回差异。\n\n通过子进程调用 ETL CLI 获取真实任务列表，避免直接导入 ETL 代码。", "operationId": "sync_check_api_tasks_sync_check_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncCheckResponse" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/execution/run": { "post": { "tags": [ "任务执行" ], "summary": "Run Task", "description": "直接执行任务（不经过队列）。\n\n从 JWT 注入 store_id，创建 execution_id 后异步启动子进程。", "operationId": "run_task_api_execution_run_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskConfigSchema" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionRunResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/execution/queue": { "get": { "tags": [ "任务执行" ], "summary": "Get Queue", "description": "获取当前门店的待执行队列。", "operationId": "get_queue_api_execution_queue_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/QueueTaskResponse" }, "type": "array", "title": "Response Get Queue Api Execution Queue Get" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "post": { "tags": [ "任务执行" ], "summary": "Enqueue Task", "description": "将任务配置添加到执行队列。", "operationId": "enqueue_task_api_execution_queue_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskConfigSchema" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueTaskResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/execution/queue/reorder": { "put": { "tags": [ "任务执行" ], "summary": "Reorder Queue", "description": "调整队列中任务的执行顺序。", "operationId": "reorder_queue_api_execution_queue_reorder_put", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Reorder Queue Api Execution Queue Reorder Put" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/execution/queue/{task_id}": { "delete": { "tags": [ "任务执行" ], "summary": "Delete Queue Task", "description": "从队列中删除待执行任务。仅允许删除 pending 状态的任务。", "operationId": "delete_queue_task_api_execution_queue__task_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Delete Queue Task Api Execution Queue Task Id Delete" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/execution/{execution_id}/cancel": { "post": { "tags": [ "任务执行" ], "summary": "Cancel Execution", "description": "取消正在执行的任务。", "operationId": "cancel_execution_api_execution__execution_id__cancel_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "execution_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Execution Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Cancel Execution Api Execution Execution Id Cancel Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/execution/history": { "get": { "tags": [ "任务执行" ], "summary": "Get Execution History", "description": "获取执行历史记录，按 started_at 降序排列。", "operationId": "get_execution_history_api_execution_history_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExecutionHistoryItem" }, "title": "Response Get Execution History Api Execution History Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/execution/{execution_id}/logs": { "get": { "tags": [ "任务执行" ], "summary": "Get Execution Logs", "description": "获取指定执行的完整日志。\n\n优先从内存缓冲区读取（执行中），否则从数据库读取（已完成）。", "operationId": "get_execution_logs_api_execution__execution_id__logs_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "execution_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Execution Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionLogsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/schedules": { "get": { "tags": [ "调度管理" ], "summary": "List Schedules", "description": "获取当前门店的所有调度任务。", "operationId": "list_schedules_api_schedules_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ScheduleResponse" }, "type": "array", "title": "Response List Schedules Api Schedules Get" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "post": { "tags": [ "调度管理" ], "summary": "Create Schedule", "description": "创建调度任务，自动计算 next_run_at。", "operationId": "create_schedule_api_schedules_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScheduleRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/schedules/{schedule_id}": { "put": { "tags": [ "调度管理" ], "summary": "Update Schedule", "description": "更新调度任务，仅更新请求中提供的字段。", "operationId": "update_schedule_api_schedules__schedule_id__put", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "schedule_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Schedule Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScheduleRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "调度管理" ], "summary": "Delete Schedule", "description": "删除调度任务。", "operationId": "delete_schedule_api_schedules__schedule_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "schedule_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Schedule Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Delete Schedule Api Schedules Schedule Id Delete" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/schedules/{schedule_id}/toggle": { "patch": { "tags": [ "调度管理" ], "summary": "Toggle Schedule", "description": "切换调度任务的启用/禁用状态。\n\n禁用时 next_run_at 置 NULL；启用时重新计算 next_run_at。", "operationId": "toggle_schedule_api_schedules__schedule_id__toggle_patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "schedule_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Schedule Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/env-config": { "get": { "tags": [ "环境配置" ], "summary": "Get Env Config", "description": "读取 .env 文件，敏感值以掩码展示。", "operationId": "get_env_config_api_env_config_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvConfigResponse" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "put": { "tags": [ "环境配置" ], "summary": "Update Env Config", "description": "验证并写入 .env 文件。\n\n保留原文件中的注释行和空行。对于已有键，更新值；\n对于新键，追加到文件末尾。掩码值（****）的键跳过更新，保留原值。", "operationId": "update_env_config_api_env_config_put", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvConfigUpdateRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvConfigResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/env-config/export": { "get": { "tags": [ "环境配置" ], "summary": "Export Env Config", "description": "导出去除敏感值的配置文件（作为文件下载）。", "operationId": "export_env_config_api_env_config_export_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/db/schemas": { "get": { "tags": [ "数据库查看器" ], "summary": "List Schemas", "description": "返回 ETL 数据库中的 Schema 列表。", "operationId": "list_schemas_api_db_schemas_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/SchemaInfo" }, "type": "array", "title": "Response List Schemas Api Db Schemas Get" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/db/schemas/{name}/tables": { "get": { "tags": [ "数据库查看器" ], "summary": "List Tables", "description": "返回指定 Schema 下所有表的名称和行数统计。", "operationId": "list_tables_api_db_schemas__name__tables_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "title": "Name" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TableInfo" }, "title": "Response List Tables Api Db Schemas Name Tables Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/db/tables/{schema}/{table}/columns": { "get": { "tags": [ "数据库查看器" ], "summary": "List Columns", "description": "返回指定表的列定义。", "operationId": "list_columns_api_db_tables__schema___table__columns_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "schema", "in": "path", "required": true, "schema": { "type": "string", "title": "Schema" } }, { "name": "table", "in": "path", "required": true, "schema": { "type": "string", "title": "Table" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ColumnInfo" }, "title": "Response List Columns Api Db Tables Schema Table Columns Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/db/query": { "post": { "tags": [ "数据库查看器" ], "summary": "Execute Query", "description": "只读 SQL 执行。\n\n安全措施：\n1. 拦截写操作关键词（INSERT / UPDATE / DELETE / DROP / TRUNCATE）\n2. 限制返回行数上限 1000 行\n3. 设置查询超时 30 秒", "operationId": "execute_query_api_db_query_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/etl-status/cursors": { "get": { "tags": [ "ETL 状态" ], "summary": "List Cursors", "description": "返回各 ODS 表的最新数据游标。\n\n查询 ETL 数据库中的 meta.etl_cursor 表。\n如果该表不存在，返回空列表而非报错。", "operationId": "list_cursors_api_etl_status_cursors_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/CursorInfo" }, "type": "array", "title": "Response List Cursors Api Etl Status Cursors Get" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/etl-status/recent-runs": { "get": { "tags": [ "ETL 状态" ], "summary": "List Recent Runs", "description": "返回最近 50 条任务执行记录。\n\n查询 zqyy_app 数据库中的 task_execution_log 表，\n按 site_id 过滤，按 started_at DESC 排序。", "operationId": "list_recent_runs_api_etl_status_recent_runs_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/RecentRun" }, "type": "array", "title": "Response List Recent Runs Api Etl Status Recent Runs Get" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/xcx-test": { "get": { "tags": [ "小程序MVP" ], "summary": "Get Xcx Test", "description": "读取 test.\"xcx-test\" 表 ti 列第一行。\n\n用于小程序 MVP 全链路验证：小程序 → API → DB → 返回数据。", "operationId": "get_xcx_test_api_xcx_test_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/wx/callback": { "get": { "tags": [ "微信回调" ], "summary": "Verify", "description": "微信服务器验证接口。\n\n配置消息推送时微信会发 GET 请求，验签通过后原样返回 echostr。", "operationId": "verify_api_wx_callback_get", "parameters": [ { "name": "signature", "in": "query", "required": true, "schema": { "type": "string", "title": "Signature" } }, { "name": "timestamp", "in": "query", "required": true, "schema": { "type": "string", "title": "Timestamp" } }, { "name": "nonce", "in": "query", "required": true, "schema": { "type": "string", "title": "Nonce" } }, { "name": "echostr", "in": "query", "required": true, "schema": { "type": "string", "title": "Echostr" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "微信回调" ], "summary": "Receive Message", "description": "接收微信推送的消息/事件。\n\n当前为明文模式，直接解析 JSON 包体。\n后续切安全模式时需增加 AES 解密逻辑。", "operationId": "receive_message_api_wx_callback_post", "parameters": [ { "name": "signature", "in": "query", "required": false, "schema": { "type": "string", "default": "", "title": "Signature" } }, { "name": "timestamp", "in": "query", "required": false, "schema": { "type": "string", "default": "", "title": "Timestamp" } }, { "name": "nonce", "in": "query", "required": false, "schema": { "type": "string", "default": "", "title": "Nonce" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/retention-clue": { "post": { "tags": [ "维客线索" ], "summary": "Submit Retention Clue", "description": "提交维客线索（INSERT）。\n\n同一会员可有多条不同大类的线索。", "operationId": "submit_retention_clue_api_retention_clue_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionClueSubmit" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/retention-clue/{member_id}": { "get": { "tags": [ "维客线索" ], "summary": "Get Retention Clues", "description": "查询某会员的全部维客线索，按录入时间倒序。", "operationId": "get_retention_clues_api_retention_clue__member_id__get", "parameters": [ { "name": "member_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Member Id" } }, { "name": "site_id", "in": "query", "required": true, "schema": { "type": "integer", "title": "Site Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RetentionClueOut" }, "title": "Response Get Retention Clues Api Retention Clue Member Id Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/retention-clue/{clue_id}": { "delete": { "tags": [ "维客线索" ], "summary": "Delete Retention Clue", "description": "删除单条维客线索。", "operationId": "delete_retention_clue_api_retention_clue__clue_id__delete", "parameters": [ { "name": "clue_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Clue Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/ops/system": { "get": { "tags": [ "运维面板" ], "summary": "Get System Info", "description": "获取服务器系统资源概况。", "operationId": "get_system_info_api_ops_system_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemInfo" } } } } } } }, "/api/ops/services": { "get": { "tags": [ "运维面板" ], "summary": "Get Services Status", "description": "获取所有环境的服务运行状态。", "operationId": "get_services_status_api_ops_services_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ServiceStatus" }, "type": "array", "title": "Response Get Services Status Api Ops Services Get" } } } } } } }, "/api/ops/services/{env}/start": { "post": { "tags": [ "运维面板" ], "summary": "Start Service", "description": "启动指定环境的后端服务。", "operationId": "start_service_api_ops_services__env__start_post", "parameters": [ { "name": "env", "in": "path", "required": true, "schema": { "type": "string", "title": "Env" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceActionResult" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/ops/services/{env}/stop": { "post": { "tags": [ "运维面板" ], "summary": "Stop Service", "description": "停止指定环境的后端服务。", "operationId": "stop_service_api_ops_services__env__stop_post", "parameters": [ { "name": "env", "in": "path", "required": true, "schema": { "type": "string", "title": "Env" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceActionResult" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/ops/services/{env}/restart": { "post": { "tags": [ "运维面板" ], "summary": "Restart Service", "description": "重启指定环境的后端服务。", "operationId": "restart_service_api_ops_services__env__restart_post", "parameters": [ { "name": "env", "in": "path", "required": true, "schema": { "type": "string", "title": "Env" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceActionResult" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/ops/git": { "get": { "tags": [ "运维面板" ], "summary": "Get Git Info", "description": "获取所有环境的 Git 状态。", "operationId": "get_git_info_api_ops_git_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/GitInfo" }, "type": "array", "title": "Response Get Git Info Api Ops Git Get" } } } } } } }, "/api/ops/git/{env}/pull": { "post": { "tags": [ "运维面板" ], "summary": "Git Pull", "description": "对指定环境执行 git pull。", "operationId": "git_pull_api_ops_git__env__pull_post", "parameters": [ { "name": "env", "in": "path", "required": true, "schema": { "type": "string", "title": "Env" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitPullResult" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/ops/git/{env}/sync-deps": { "post": { "tags": [ "运维面板" ], "summary": "Sync Deps", "description": "对指定环境执行 uv sync --all-packages。", "operationId": "sync_deps_api_ops_git__env__sync_deps_post", "parameters": [ { "name": "env", "in": "path", "required": true, "schema": { "type": "string", "title": "Env" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceActionResult" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/ops/env-file/{env}": { "get": { "tags": [ "运维面板" ], "summary": "Get Env File", "description": "读取指定环境的 .env 文件（敏感值脱敏）。", "operationId": "get_env_file_api_ops_env_file__env__get", "parameters": [ { "name": "env", "in": "path", "required": true, "schema": { "type": "string", "title": "Env" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/xcx/login": { "post": { "tags": [ "小程序认证" ], "summary": "Wx Login", "description": "微信登录。\n\n流程：code → code2session(openid) → 查找/创建 auth.users → 签发 JWT。\n- disabled 用户返回 403\n- 新用户自动创建（status=new），前端引导至申请页\n- approved 用户签发包含 site_id + roles 的完整令牌\n- new/pending/rejected 用户签发受限令牌", "operationId": "wx_login_api_xcx_login_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WxLoginRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WxLoginResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/xcx/apply": { "post": { "tags": [ "小程序认证" ], "summary": "Submit Application", "description": "提交入驻申请。\n\n委托 application service 处理：\n检查重复 pending → site_code 映射 → 创建记录 → 更新 nickname。", "operationId": "submit_application_api_xcx_apply_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/xcx/me": { "get": { "tags": [ "小程序认证" ], "summary": "Get My Status", "description": "查询自身状态 + 所有申请记录。\n\npending / approved / rejected 用户均可访问。", "operationId": "get_my_status_api_xcx_me_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserStatusResponse" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/xcx/me/sites": { "get": { "tags": [ "小程序认证" ], "summary": "Get My Sites", "description": "查询当前用户关联的所有店铺及对应角色。\n\n仅 approved 用户可访问（通过 get_current_user 依赖保证）。", "operationId": "get_my_sites_api_xcx_me_sites_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/SiteInfo" }, "type": "array", "title": "Response Get My Sites Api Xcx Me Sites Get" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/xcx/switch-site": { "post": { "tags": [ "小程序认证" ], "summary": "Switch Site", "description": "切换当前店铺。\n\n验证用户在目标 site_id 下有角色绑定，然后签发包含新 site_id 的 JWT。", "operationId": "switch_site_api_xcx_switch_site_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwitchSiteRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WxLoginResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/xcx/refresh": { "post": { "tags": [ "小程序认证" ], "summary": "Refresh Token", "description": "刷新令牌。\n\n解码 refresh_token → 根据用户当前状态签发新的令牌对。\n- 受限 refresh_token（limited=True）→ 签发新的受限令牌对\n- 完整 refresh_token → 签发新的完整令牌对（保持原 site_id）", "operationId": "refresh_token_api_xcx_refresh_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshTokenRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WxLoginResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/xcx/dev-login": { "post": { "tags": [ "小程序认证" ], "summary": "Dev Login", "description": "开发模式 mock 登录。\n\n直接根据 openid 查找/创建用户，跳过微信 code2Session。\n- 已有用户：status 参数为空时保留当前状态，非空时覆盖\n- 新用户：status 参数为空时默认 new，非空时使用指定值\n仅在 WX_DEV_MODE=true 时注册。", "operationId": "dev_login_api_xcx_dev_login_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevLoginRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WxLoginResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/admin/applications": { "get": { "tags": [ "管理端审核" ], "summary": "List Applications", "description": "查询申请列表，可按 status 过滤。", "operationId": "list_applications_api_admin_applications_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "按状态过滤：pending / approved / rejected", "title": "Status" }, "description": "按状态过滤：pending / approved / rejected" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationResponse" }, "title": "Response List Applications Api Admin Applications Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/admin/applications/{application_id}": { "get": { "tags": [ "管理端审核" ], "summary": "Get Application Detail", "description": "查询申请详情 + 候选匹配。", "operationId": "get_application_detail_api_admin_applications__application_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "application_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Application Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/admin/applications/{application_id}/approve": { "post": { "tags": [ "管理端审核" ], "summary": "Approve", "description": "批准申请：分配角色 + 可选绑定。", "operationId": "approve_api_admin_applications__application_id__approve_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "application_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Application Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/admin/applications/{application_id}/reject": { "post": { "tags": [ "管理端审核" ], "summary": "Reject", "description": "拒绝申请：记录拒绝原因。", "operationId": "reject_api_admin_applications__application_id__reject_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "application_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Application Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/config/business-day": { "get": { "tags": [ "业务配置" ], "summary": "Get Business Day Config", "description": "返回当前营业日分割点配置。\n\n无需认证（公开配置），前端启动时调用一次缓存。", "operationId": "get_business_day_config_api_config_business_day_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/xcx/tasks": { "get": { "tags": [ "小程序任务" ], "summary": "Get Tasks V2", "description": "获取任务列表 + 绩效概览（TASK-1 扩展版）。\n\n返回分页任务列表，每个任务含扩展字段（lastVisitDays/balance/aiSuggestion），\n以及当月绩效概览（档位/收入/工时）。", "operationId": "get_tasks_v2_api_xcx_tasks_get", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": ["pending", "completed", "abandoned"], "default": "pending", "title": "Status" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/xcx/tasks/{task_id}": { "get": { "tags": [ "小程序任务" ], "summary": "Get Task Detail", "description": "获取任务详情完整版（TASK-2）。\n\n包含维客线索、话术、服务记录、AI 分析、备注等模块。", "operationId": "get_task_detail_api_xcx_tasks__task_id__get", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskDetailResponse" } } } }, "403": { "description": "无权访问该任务" }, "404": { "description": "任务不存在" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/xcx/tasks/{task_id}/pin": { "post": { "tags": [ "小程序任务" ], "summary": "Pin Task", "description": "置顶任务。", "operationId": "pin_task_api_xcx_tasks__task_id__pin_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/xcx/tasks/{task_id}/unpin": { "post": { "tags": [ "小程序任务" ], "summary": "Unpin Task", "description": "取消置顶。", "operationId": "unpin_task_api_xcx_tasks__task_id__unpin_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/xcx/tasks/{task_id}/abandon": { "post": { "tags": [ "小程序任务" ], "summary": "Abandon Task", "description": "放弃任务（需填写原因）。", "operationId": "abandon_task_api_xcx_tasks__task_id__abandon_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AbandonRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/xcx/tasks/{task_id}/restore": { "post": { "tags": [ "小程序任务" ], "summary": "Restore Task", "description": "取消放弃，恢复为活跃状态。", "operationId": "restore_task_api_xcx_tasks__task_id__restore_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/xcx/notes": { "post": { "tags": [ "小程序备注" ], "summary": "Create Note", "description": "创建备注（含星星评分，可选关联任务）。", "operationId": "create_note_api_xcx_notes_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteCreateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "小程序备注" ], "summary": "Get Notes", "description": "查询某目标的备注列表（按创建时间倒序）。", "operationId": "get_notes_api_xcx_notes_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "target_type", "in": "query", "required": false, "schema": { "type": "string", "description": "目标类型", "default": "member", "title": "Target Type" }, "description": "目标类型" }, { "name": "target_id", "in": "query", "required": true, "schema": { "type": "integer", "description": "目标 ID", "title": "Target Id" }, "description": "目标 ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/xcx/notes/{note_id}": { "delete": { "tags": [ "小程序备注" ], "summary": "Delete Note", "description": "删除备注（验证归属后硬删除）。", "operationId": "delete_note_api_xcx_notes__note_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "note_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Note Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/xcx/performance": { "get": { "tags": [ "小程序绩效" ], "summary": "Get Performance Overview", "description": "绩效概览（PERF-1）。\n\n返回指定月份的收入档位、DateGroup 分组记录、新客/常客列表。", "operationId": "get_performance_overview_api_xcx_performance_get", "parameters": [ { "name": "year", "in": "query", "required": true, "schema": { "type": "integer", "title": "Year" } }, { "name": "month", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 12, "title": "Month" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PerformanceOverviewResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/xcx/performance/records": { "get": { "tags": [ "小程序绩效" ], "summary": "Get Performance Records", "description": "绩效明细（PERF-2）。\n\n返回指定月份的服务记录明细，按日期分组，支持分页。", "operationId": "get_performance_records_api_xcx_performance_records_get", "parameters": [ { "name": "year", "in": "query", "required": true, "schema": { "type": "integer", "title": "Year" } }, { "name": "month", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 12, "title": "Month" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PerformanceRecordsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/xcx/customers/{customer_id}": { "get": { "tags": [ "小程序客户" ], "summary": "Get Customer Detail", "description": "客户详情（CUST-1）。\n\n返回客户完整详情：Banner 概览、AI 洞察、关联助教任务、最亲密助教、维客线索、消费记录（嵌套结构）、备注列表。\n所有金额使用 items_sum 口径（DWD-DOC 规则 1），助教费用使用 assistant_pd_money + assistant_cx_money 拆分（DWD-DOC 规则 2）。", "operationId": "get_customer_detail_api_xcx_customers__customer_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Customer Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerDetailResponse" } } } }, "403": { "description": "用户未通过审核", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 403 }, "message": { "type": "string", "example": "用户未通过审核，无法访问此资源" } } } } } }, "404": { "description": "客户不存在", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 404 }, "message": { "type": "string", "example": "客户不存在" } } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/xcx/customers/{customer_id}/records": { "get": { "tags": [ "小程序客户" ], "summary": "Get Customer Records", "description": "客户服务记录（CUST-2）。\n\n按月查询客户服务记录，支持台桌筛选和分页。返回月度统计汇总（monthCount/monthHours）和累计服务总次数。", "operationId": "get_customer_records_api_xcx_customers__customer_id__records_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Customer Id" } }, { "name": "year", "in": "query", "required": true, "schema": { "type": "integer", "title": "Year" } }, { "name": "month", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 12, "title": "Month" } }, { "name": "table", "in": "query", "required": false, "schema": { "type": "string", "title": "Table", "description": "台桌筛选（可选）" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerRecordsResponse" } } } }, "403": { "description": "用户未通过审核", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 403 }, "message": { "type": "string", "example": "用户未通过审核，无法访问此资源" } } } } } }, "404": { "description": "客户不存在", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 404 }, "message": { "type": "string", "example": "客户不存在" } } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/xcx/coaches/{coach_id}": { "get": { "tags": [ "小程序助教" ], "summary": "Get Coach Detail", "description": "助教详情（COACH-1）。\n\n返回助教完整详情：基本信息、绩效指标、收入明细（本月/上月）、档位节点、任务分组（进行中/已过期/已放弃）、TOP 客户、近期服务记录、历史月份统计、备注列表。\n所有金额使用 items_sum 口径（DWD-DOC 规则 1），助教费用使用 assistant_pd_money + assistant_cx_money 拆分（DWD-DOC 规则 2）。", "operationId": "get_coach_detail_api_xcx_coaches__coach_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "coach_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Coach Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoachDetailResponse" } } } }, "403": { "description": "用户未通过审核", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 403 }, "message": { "type": "string", "example": "用户未通过审核，无法访问此资源" } } } } } }, "404": { "description": "助教不存在", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 404 }, "message": { "type": "string", "example": "助教不存在" } } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/health": { "get": { "tags": [ "系统" ], "summary": "Health Check", "description": "健康检查端点，用于探活和监控。", "operationId": "health_check_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/xcx/board/coaches": { "get": { "tags": [ "看板" ], "summary": "Get Coach Board", "description": "助教排行看板（BOARD-1）。支持排序×技能×时间三重筛选，4 种维度卡片。time=last_6m + sort=sv_desc 互斥返回 400。", "operationId": "get_coach_board_api_xcx_board_coaches_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": ["perf_desc", "perf_asc", "salary_desc", "salary_asc", "sv_desc", "task_desc"], "default": "perf_desc", "title": "Sort" } }, { "name": "skill", "in": "query", "required": false, "schema": { "type": "string", "enum": ["all", "chinese", "snooker", "both", "none"], "default": "all", "title": "Skill" } }, { "name": "time", "in": "query", "required": false, "schema": { "type": "string", "enum": ["month", "quarter", "last_month", "last_3m", "last_quarter", "last_6m"], "default": "month", "title": "Time" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoachBoardResponse" } } } }, "400": { "description": "参数互斥错误（time=last_6m + sort=sv_desc）" }, "401": { "description": "未认证" }, "403": { "description": "无权限" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/xcx/board/customers": { "get": { "tags": [ "看板" ], "summary": "Get Customer Board", "description": "客户排行看板（BOARD-2）。8 个维度查看客户排行，支持分页。", "operationId": "get_customer_board_api_xcx_board_customers_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "dimension", "in": "query", "required": false, "schema": { "type": "string", "enum": ["recall", "potential", "balance", "recharge", "recent", "spend60", "freq60", "loyal"], "default": "recall", "title": "Dimension" } }, { "name": "project", "in": "query", "required": false, "schema": { "type": "string", "enum": ["all", "chinese", "snooker", "both", "none"], "default": "all", "title": "Project" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerBoardResponse" } } } }, "401": { "description": "未认证" }, "403": { "description": "无权限" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/xcx/board/finance": { "get": { "tags": [ "看板" ], "summary": "Get Finance Board", "description": "财务看板（BOARD-3）。6 个独立板块：经营一览/预收资产/应计收入/现金流入/现金流出/助教分析。area≠all 时 recharge 为 null。compare=1 时包含环比数据。", "operationId": "get_finance_board_api_xcx_board_finance_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "time", "in": "query", "required": false, "schema": { "type": "string", "enum": ["month", "lastMonth", "week", "lastWeek", "quarter3", "quarter", "lastQuarter", "half6"], "default": "month", "title": "Time" } }, { "name": "area", "in": "query", "required": false, "schema": { "type": "string", "enum": ["all", "hall", "hallA", "hallB", "mahjong", "snooker", "other"], "default": "all", "title": "Area" } }, { "name": "compare", "in": "query", "required": false, "schema": { "type": "integer", "enum": [0, 1], "default": 0, "title": "Compare" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinanceBoardResponse" } } } }, "401": { "description": "未认证" }, "403": { "description": "无权限" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/xcx/config/skill-types": { "get": { "tags": [ "配置" ], "summary": "Get Skill Types", "description": "技能类型配置（CONFIG-1）。返回技能类型列表，查询失败降级返回空数组。", "operationId": "get_skill_types_api_xcx_config_skill_types_get", "security": [ { "HTTPBearer": [] } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkillTypeItem" }, "title": "Response Get Skill Types Api Xcx Config Skill Types Get" } } } }, "401": { "description": "未认证" }, "403": { "description": "无权限" } } } } }, "components": { "schemas": { "AbandonRequest": { "properties": { "reason": { "type": "string", "minLength": 1, "title": "Reason", "description": "放弃原因（必填）" } }, "type": "object", "required": [ "reason" ], "title": "AbandonRequest", "description": "放弃任务请求（reason 必填）。" }, "ApplicationRequest": { "properties": { "site_code": { "type": "string", "pattern": "^[A-Za-z]{2}\\d{3}$", "title": "Site Code", "description": "球房ID" }, "applied_role_text": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Applied Role Text", "description": "申请身份" }, "phone": { "type": "string", "pattern": "^\\d{11}$", "title": "Phone", "description": "手机号" }, "employee_number": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ], "title": "Employee Number", "description": "员工编号" }, "nickname": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ], "title": "Nickname", "description": "昵称" } }, "type": "object", "required": [ "site_code", "applied_role_text", "phone" ], "title": "ApplicationRequest", "description": "用户申请提交请求。" }, "ApplicationResponse": { "properties": { "id": { "type": "integer", "title": "Id" }, "site_code": { "type": "string", "title": "Site Code" }, "applied_role_text": { "type": "string", "title": "Applied Role Text" }, "status": { "type": "string", "title": "Status" }, "review_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Review Note" }, "created_at": { "type": "string", "title": "Created At" }, "reviewed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reviewed At" } }, "type": "object", "required": [ "id", "site_code", "applied_role_text", "status", "created_at" ], "title": "ApplicationResponse", "description": "申请记录响应。" }, "ApproveRequest": { "properties": { "role_id": { "type": "integer", "title": "Role Id" }, "binding": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Binding" }, "review_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Review Note" } }, "type": "object", "required": [ "role_id" ], "title": "ApproveRequest", "description": "批准申请请求。" }, "ClueCategory": { "type": "string", "enum": [ "客户基础信息", "消费习惯", "玩法偏好", "促销偏好", "社交关系", "重要反馈" ], "title": "ClueCategory", "description": "维客线索大类枚举" }, "ClueSource": { "type": "string", "enum": [ "manual", "ai_consumption", "ai_note" ], "title": "ClueSource", "description": "维客线索来源枚举" }, "ColumnInfo": { "properties": { "name": { "type": "string", "title": "Name" }, "data_type": { "type": "string", "title": "Data Type" }, "is_nullable": { "type": "boolean", "title": "Is Nullable" }, "column_default": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Column Default" } }, "type": "object", "required": [ "name", "data_type", "is_nullable" ], "title": "ColumnInfo", "description": "列定义。" }, "CreateScheduleRequest": { "properties": { "name": { "type": "string", "title": "Name" }, "task_codes": { "items": { "type": "string" }, "type": "array", "title": "Task Codes" }, "task_config": { "additionalProperties": true, "type": "object", "title": "Task Config" }, "schedule_config": { "$ref": "#/components/schemas/ScheduleConfigSchema" } }, "type": "object", "required": [ "name", "task_codes", "task_config", "schedule_config" ], "title": "CreateScheduleRequest", "description": "创建调度任务请求" }, "CursorInfo": { "properties": { "task_code": { "type": "string", "title": "Task Code" }, "last_fetch_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Fetch Time" }, "record_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Record Count" } }, "type": "object", "required": [ "task_code" ], "title": "CursorInfo", "description": "ETL 游标信息（单条任务的最后抓取状态）。" }, "DevLoginRequest": { "properties": { "openid": { "type": "string", "minLength": 1, "title": "Openid", "description": "模拟的微信 openid" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status", "description": "模拟的用户状态；为空时保留已有用户的当前状态，新用户默认 new" } }, "type": "object", "required": [ "openid" ], "title": "DevLoginRequest", "description": "开发模式 mock 登录请求（仅 WX_DEV_MODE=true 时可用）。" }, "DwdTableItem": { "properties": { "table_name": { "type": "string", "title": "Table Name" }, "display_name": { "type": "string", "title": "Display Name" }, "domain": { "type": "string", "title": "Domain" }, "ods_source": { "type": "string", "title": "Ods Source" }, "is_dimension": { "type": "boolean", "title": "Is Dimension" } }, "type": "object", "required": [ "table_name", "display_name", "domain", "ods_source", "is_dimension" ], "title": "DwdTableItem" }, "DwdTablesResponse": { "properties": { "groups": { "additionalProperties": { "items": { "$ref": "#/components/schemas/DwdTableItem" }, "type": "array" }, "type": "object", "title": "Groups" } }, "type": "object", "required": [ "groups" ], "title": "DwdTablesResponse", "description": "按业务域分组的 DWD 表定义" }, "EnvConfigResponse": { "properties": { "entries": { "items": { "$ref": "#/components/schemas/EnvEntry" }, "type": "array", "title": "Entries" } }, "type": "object", "required": [ "entries" ], "title": "EnvConfigResponse", "description": "GET 响应：键值对列表。" }, "EnvConfigUpdateRequest": { "properties": { "entries": { "items": { "$ref": "#/components/schemas/EnvEntry" }, "type": "array", "title": "Entries" } }, "type": "object", "required": [ "entries" ], "title": "EnvConfigUpdateRequest", "description": "PUT 请求体：键值对列表。" }, "EnvEntry": { "properties": { "key": { "type": "string", "title": "Key" }, "value": { "type": "string", "title": "Value" } }, "type": "object", "required": [ "key", "value" ], "title": "EnvEntry", "description": "单条环境变量键值对。" }, "ExecutionHistoryItem": { "properties": { "id": { "type": "string", "title": "Id" }, "site_id": { "type": "integer", "title": "Site Id" }, "task_codes": { "items": { "type": "string" }, "type": "array", "title": "Task Codes" }, "status": { "type": "string", "title": "Status" }, "started_at": { "type": "string", "format": "date-time", "title": "Started At" }, "finished_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Finished At" }, "exit_code": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Exit Code" }, "duration_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration Ms" }, "command": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Command" }, "summary": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Summary" } }, "type": "object", "required": [ "id", "site_id", "task_codes", "status", "started_at" ], "title": "ExecutionHistoryItem", "description": "执行历史记录" }, "ExecutionLogsResponse": { "properties": { "execution_id": { "type": "string", "title": "Execution Id" }, "output_log": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Output Log" }, "error_log": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Log" } }, "type": "object", "required": [ "execution_id" ], "title": "ExecutionLogsResponse", "description": "执行日志响应" }, "ExecutionRunResponse": { "properties": { "execution_id": { "type": "string", "title": "Execution Id" }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "execution_id", "message" ], "title": "ExecutionRunResponse", "description": "直接执行任务的响应" }, "FlowDefinition": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "layers": { "items": { "type": "string" }, "type": "array", "title": "Layers" } }, "type": "object", "required": [ "id", "name", "layers" ], "title": "FlowDefinition", "description": "执行流程（Flow）定义" }, "FlowsResponse": { "properties": { "flows": { "items": { "$ref": "#/components/schemas/FlowDefinition" }, "type": "array", "title": "Flows" }, "processing_modes": { "items": { "$ref": "#/components/schemas/ProcessingModeDefinition" }, "type": "array", "title": "Processing Modes" } }, "type": "object", "required": [ "flows", "processing_modes" ], "title": "FlowsResponse", "description": "Flow 定义 + 处理模式定义" }, "GitInfo": { "properties": { "env": { "type": "string", "title": "Env" }, "branch": { "type": "string", "title": "Branch" }, "last_commit_hash": { "type": "string", "title": "Last Commit Hash" }, "last_commit_message": { "type": "string", "title": "Last Commit Message" }, "last_commit_time": { "type": "string", "title": "Last Commit Time" }, "has_local_changes": { "type": "boolean", "title": "Has Local Changes" } }, "type": "object", "required": [ "env", "branch", "last_commit_hash", "last_commit_message", "last_commit_time", "has_local_changes" ], "title": "GitInfo" }, "GitPullResult": { "properties": { "env": { "type": "string", "title": "Env" }, "success": { "type": "boolean", "title": "Success" }, "output": { "type": "string", "title": "Output" } }, "type": "object", "required": [ "env", "success", "output" ], "title": "GitPullResult" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "LoginRequest": { "properties": { "username": { "type": "string", "maxLength": 64, "minLength": 1, "title": "Username", "description": "用户名" }, "password": { "type": "string", "minLength": 1, "title": "Password", "description": "密码" } }, "type": "object", "required": [ "username", "password" ], "title": "LoginRequest", "description": "登录请求。" }, "NoteCreateRequest": { "properties": { "target_type": { "type": "string", "title": "Target Type", "default": "member" }, "target_id": { "type": "integer", "title": "Target Id" }, "content": { "type": "string", "minLength": 1, "title": "Content" }, "task_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Task Id" }, "rating_service_willingness": { "anyOf": [ { "type": "integer", "maximum": 5.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Rating Service Willingness" }, "rating_revisit_likelihood": { "anyOf": [ { "type": "integer", "maximum": 5.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Rating Revisit Likelihood" } }, "type": "object", "required": [ "target_id", "content" ], "title": "NoteCreateRequest", "description": "创建备注请求（含星星评分，评分 1-5 范围约束）。" }, "NoteOut": { "properties": { "id": { "type": "integer", "title": "Id" }, "type": { "type": "string", "title": "Type" }, "content": { "type": "string", "title": "Content" }, "rating_service_willingness": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Rating Service Willingness" }, "rating_revisit_likelihood": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Rating Revisit Likelihood" }, "ai_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Ai Score" }, "ai_analysis": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ai Analysis" }, "task_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Task Id" }, "created_at": { "type": "string", "title": "Created At" }, "updated_at": { "type": "string", "title": "Updated At" } }, "type": "object", "required": [ "id", "type", "content", "rating_service_willingness", "rating_revisit_likelihood", "ai_score", "ai_analysis", "task_id", "created_at", "updated_at" ], "title": "NoteOut", "description": "备注输出模型（含评分 + AI 评分）。" }, "ProcessingModeDefinition": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "description": { "type": "string", "title": "Description" } }, "type": "object", "required": [ "id", "name", "description" ], "title": "ProcessingModeDefinition", "description": "处理模式定义" }, "QueryRequest": { "properties": { "sql": { "type": "string", "title": "Sql" } }, "type": "object", "required": [ "sql" ], "title": "QueryRequest", "description": "SQL 查询请求。" }, "QueryResponse": { "properties": { "columns": { "items": { "type": "string" }, "type": "array", "title": "Columns" }, "rows": { "items": { "items": {}, "type": "array" }, "type": "array", "title": "Rows" }, "row_count": { "type": "integer", "title": "Row Count" } }, "type": "object", "required": [ "columns", "rows", "row_count" ], "title": "QueryResponse", "description": "SQL 查询响应。" }, "QueueTaskResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "site_id": { "type": "integer", "title": "Site Id" }, "config": { "additionalProperties": true, "type": "object", "title": "Config" }, "status": { "type": "string", "title": "Status" }, "position": { "type": "integer", "title": "Position" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At" }, "finished_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Finished At" }, "exit_code": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Exit Code" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Message" } }, "type": "object", "required": [ "id", "site_id", "config", "status", "position" ], "title": "QueueTaskResponse", "description": "队列任务响应" }, "RecentRun": { "properties": { "id": { "type": "string", "title": "Id" }, "task_codes": { "items": { "type": "string" }, "type": "array", "title": "Task Codes" }, "status": { "type": "string", "title": "Status" }, "started_at": { "type": "string", "title": "Started At" }, "finished_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Finished At" }, "duration_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration Ms" }, "exit_code": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Exit Code" } }, "type": "object", "required": [ "id", "task_codes", "status", "started_at" ], "title": "RecentRun", "description": "最近执行记录。" }, "RefreshRequest": { "properties": { "refresh_token": { "type": "string", "minLength": 1, "title": "Refresh Token", "description": "刷新令牌" } }, "type": "object", "required": [ "refresh_token" ], "title": "RefreshRequest", "description": "刷新令牌请求。" }, "RefreshTokenRequest": { "properties": { "refresh_token": { "type": "string", "minLength": 1, "title": "Refresh Token", "description": "刷新令牌" } }, "type": "object", "required": [ "refresh_token" ], "title": "RefreshTokenRequest", "description": "刷新令牌请求。" }, "RejectRequest": { "properties": { "review_note": { "type": "string", "minLength": 1, "title": "Review Note", "description": "拒绝原因" } }, "type": "object", "required": [ "review_note" ], "title": "RejectRequest", "description": "拒绝申请请求。" }, "ReorderRequest": { "properties": { "task_id": { "type": "string", "title": "Task Id" }, "new_position": { "type": "integer", "title": "New Position" } }, "type": "object", "required": [ "task_id", "new_position" ], "title": "ReorderRequest", "description": "队列重排请求" }, "RetentionClueOut": { "properties": { "id": { "type": "integer", "title": "Id" }, "member_id": { "type": "integer", "title": "Member Id" }, "category": { "$ref": "#/components/schemas/ClueCategory" }, "summary": { "type": "string", "title": "Summary" }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Detail" }, "recorded_by_assistant_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Recorded By Assistant Id" }, "recorded_by_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recorded By Name" }, "recorded_at": { "type": "string", "format": "date-time", "title": "Recorded At" }, "site_id": { "type": "integer", "title": "Site Id" }, "source": { "$ref": "#/components/schemas/ClueSource", "default": "manual" } }, "type": "object", "required": [ "id", "member_id", "category", "summary", "detail", "recorded_by_assistant_id", "recorded_by_name", "recorded_at", "site_id" ], "title": "RetentionClueOut", "description": "维客线索返回模型。" }, "RetentionClueSubmit": { "properties": { "member_id": { "type": "integer", "exclusiveMinimum": 0.0, "title": "Member Id", "description": "会员 ID" }, "category": { "$ref": "#/components/schemas/ClueCategory", "description": "线索大类" }, "summary": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Summary", "description": "摘要：重点信息" }, "detail": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Detail", "description": "详情：分析及扩展说明，可为空" }, "recorded_by_assistant_id": { "type": "integer", "exclusiveMinimum": 0.0, "title": "Recorded By Assistant Id", "description": "记录助教 ID" }, "recorded_by_name": { "type": "string", "maxLength": 50, "minLength": 1, "title": "Recorded By Name", "description": "记录助教姓名" }, "site_id": { "type": "integer", "exclusiveMinimum": 0.0, "title": "Site Id", "description": "门店 ID" }, "source": { "$ref": "#/components/schemas/ClueSource", "description": "线索来源", "default": "manual" } }, "type": "object", "required": [ "member_id", "category", "summary", "recorded_by_assistant_id", "recorded_by_name", "site_id" ], "title": "RetentionClueSubmit", "description": "提交维客线索请求。" }, "ScheduleConfigSchema": { "properties": { "schedule_type": { "type": "string", "enum": [ "once", "interval", "daily", "weekly", "cron" ], "title": "Schedule Type" }, "interval_value": { "type": "integer", "title": "Interval Value", "default": 1 }, "interval_unit": { "type": "string", "enum": [ "minutes", "hours", "days" ], "title": "Interval Unit", "default": "hours" }, "daily_time": { "type": "string", "title": "Daily Time", "default": "04:00" }, "weekly_days": { "items": { "type": "integer" }, "type": "array", "title": "Weekly Days", "default": [ 1 ] }, "weekly_time": { "type": "string", "title": "Weekly Time", "default": "04:00" }, "cron_expression": { "type": "string", "title": "Cron Expression", "default": "0 4 * * *" }, "enabled": { "type": "boolean", "title": "Enabled", "default": true }, "start_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start Date" }, "end_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End Date" } }, "type": "object", "required": [ "schedule_type" ], "title": "ScheduleConfigSchema", "description": "调度配置 — 支持 5 种调度类型" }, "ScheduleResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "site_id": { "type": "integer", "title": "Site Id" }, "name": { "type": "string", "title": "Name" }, "task_codes": { "items": { "type": "string" }, "type": "array", "title": "Task Codes" }, "task_config": { "additionalProperties": true, "type": "object", "title": "Task Config" }, "schedule_config": { "additionalProperties": true, "type": "object", "title": "Schedule Config" }, "enabled": { "type": "boolean", "title": "Enabled" }, "last_run_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Run At" }, "next_run_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Next Run At" }, "run_count": { "type": "integer", "title": "Run Count" }, "last_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Status" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" } }, "type": "object", "required": [ "id", "site_id", "name", "task_codes", "task_config", "schedule_config", "enabled", "run_count", "created_at", "updated_at" ], "title": "ScheduleResponse", "description": "调度任务响应" }, "SchemaInfo": { "properties": { "name": { "type": "string", "title": "Name" } }, "type": "object", "required": [ "name" ], "title": "SchemaInfo", "description": "Schema 信息。" }, "ServiceActionResult": { "properties": { "env": { "type": "string", "title": "Env" }, "action": { "type": "string", "title": "Action" }, "success": { "type": "boolean", "title": "Success" }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "env", "action", "success", "message" ], "title": "ServiceActionResult" }, "ServiceStatus": { "properties": { "env": { "type": "string", "title": "Env" }, "label": { "type": "string", "title": "Label" }, "running": { "type": "boolean", "title": "Running" }, "pid": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Pid" }, "port": { "type": "integer", "title": "Port" }, "uptime_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Uptime Seconds" }, "memory_mb": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Memory Mb" }, "cpu_percent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Cpu Percent" } }, "type": "object", "required": [ "env", "label", "running", "port" ], "title": "ServiceStatus" }, "SiteInfo": { "properties": { "site_id": { "type": "integer", "title": "Site Id" }, "site_name": { "type": "string", "title": "Site Name" }, "roles": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Roles", "default": [] } }, "type": "object", "required": [ "site_id", "site_name" ], "title": "SiteInfo", "description": "店铺信息。" }, "SwitchSiteRequest": { "properties": { "site_id": { "type": "integer", "title": "Site Id" } }, "type": "object", "required": [ "site_id" ], "title": "SwitchSiteRequest", "description": "切换店铺请求。" }, "SyncCheckResponse": { "properties": { "in_sync": { "type": "boolean", "title": "In Sync" }, "backend_only": { "items": { "type": "string" }, "type": "array", "title": "Backend Only" }, "etl_only": { "items": { "type": "string" }, "type": "array", "title": "Etl Only" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" } }, "type": "object", "required": [ "in_sync", "backend_only", "etl_only" ], "title": "SyncCheckResponse", "description": "同步检查结果" }, "SystemInfo": { "properties": { "cpu_percent": { "type": "number", "title": "Cpu Percent" }, "memory_total_gb": { "type": "number", "title": "Memory Total Gb" }, "memory_used_gb": { "type": "number", "title": "Memory Used Gb" }, "memory_percent": { "type": "number", "title": "Memory Percent" }, "disk_total_gb": { "type": "number", "title": "Disk Total Gb" }, "disk_used_gb": { "type": "number", "title": "Disk Used Gb" }, "disk_percent": { "type": "number", "title": "Disk Percent" }, "boot_time": { "type": "string", "title": "Boot Time" } }, "type": "object", "required": [ "cpu_percent", "memory_total_gb", "memory_used_gb", "memory_percent", "disk_total_gb", "disk_used_gb", "disk_percent", "boot_time" ], "title": "SystemInfo" }, "TableInfo": { "properties": { "name": { "type": "string", "title": "Name" }, "row_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Row Count" } }, "type": "object", "required": [ "name" ], "title": "TableInfo", "description": "表信息（含行数统计）。" }, "TaskConfigSchema": { "properties": { "tasks": { "items": { "type": "string" }, "type": "array", "title": "Tasks" }, "flow": { "type": "string", "title": "Flow", "default": "api_ods_dwd" }, "processing_mode": { "type": "string", "title": "Processing Mode", "default": "increment_only" }, "dry_run": { "type": "boolean", "title": "Dry Run", "default": false }, "window_mode": { "type": "string", "title": "Window Mode", "default": "lookback" }, "window_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Window Start" }, "window_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Window End" }, "window_split": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Window Split" }, "window_split_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Window Split Days" }, "lookback_hours": { "type": "integer", "title": "Lookback Hours", "default": 24 }, "overlap_seconds": { "type": "integer", "title": "Overlap Seconds", "default": 600 }, "fetch_before_verify": { "type": "boolean", "title": "Fetch Before Verify", "default": false }, "skip_ods_when_fetch_before_verify": { "type": "boolean", "title": "Skip Ods When Fetch Before Verify", "default": false }, "ods_use_local_json": { "type": "boolean", "title": "Ods Use Local Json", "default": false }, "store_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Store Id" }, "dwd_only_tables": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Dwd Only Tables" }, "force_full": { "type": "boolean", "title": "Force Full", "default": false }, "extra_args": { "additionalProperties": true, "type": "object", "title": "Extra Args", "default": {} } }, "type": "object", "required": [ "tasks" ], "title": "TaskConfigSchema", "description": "任务配置 — 前后端传输格式\n\n字段与 CLI 参数的映射关系：\n- flow → --flow（Flow ID，7 种之一）\n- processing_mode → --processing-mode（4 种处理模式）\n- tasks → --tasks（逗号分隔）\n- dry_run → --dry-run（布尔标志）\n- window_mode → 决定使用 lookback 还是 custom 时间窗口（仅前端逻辑，不直接映射 CLI 参数）\n- window_start → --window-start\n- window_end → --window-end\n- window_split → --window-split\n- window_split_days → --window-split-days\n- lookback_hours → --lookback-hours\n- overlap_seconds → --overlap-seconds\n- fetch_before_verify → --fetch-before-verify（布尔标志）\n- store_id → --store-id（由后端从 JWT 注入，前端不传）\n- dwd_only_tables → 传入 extra_args 或未来扩展" }, "TaskItem": { "properties": { "code": { "type": "string", "title": "Code" }, "name": { "type": "string", "title": "Name" }, "description": { "type": "string", "title": "Description" }, "domain": { "type": "string", "title": "Domain" }, "layer": { "type": "string", "title": "Layer" }, "requires_window": { "type": "boolean", "title": "Requires Window" }, "is_ods": { "type": "boolean", "title": "Is Ods" }, "is_dimension": { "type": "boolean", "title": "Is Dimension" }, "default_enabled": { "type": "boolean", "title": "Default Enabled" }, "is_common": { "type": "boolean", "title": "Is Common" } }, "type": "object", "required": [ "code", "name", "description", "domain", "layer", "requires_window", "is_ods", "is_dimension", "default_enabled", "is_common" ], "title": "TaskItem" }, "TaskListItem": { "properties": { "id": { "type": "integer", "title": "Id" }, "task_type": { "type": "string", "title": "Task Type" }, "status": { "type": "string", "title": "Status" }, "priority_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Priority Score" }, "is_pinned": { "type": "boolean", "title": "Is Pinned" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "created_at": { "type": "string", "title": "Created At" }, "member_id": { "type": "integer", "title": "Member Id" }, "member_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Member Name" }, "member_phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Member Phone" }, "rs_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Rs Score" }, "heart_icon": { "type": "string", "title": "Heart Icon" } }, "type": "object", "required": [ "id", "task_type", "status", "priority_score", "is_pinned", "expires_at", "created_at", "member_id", "member_name", "member_phone", "rs_score", "heart_icon" ], "title": "TaskListItem", "description": "任务列表项（含客户信息 + RS 指数 + 爱心 icon）。" }, "TaskListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/TaskListItem" }, "type": "array", "title": "Items", "description": "任务列表" }, "total": { "type": "integer", "title": "Total" }, "page": { "type": "integer", "title": "Page" }, "page_size": { "type": "integer", "title": "Page Size" }, "performance": { "$ref": "#/components/schemas/PerformanceSummary" } }, "type": "object", "required": ["items", "total", "page", "page_size", "performance"], "title": "TaskListResponse", "description": "TASK-1 响应：任务列表 + 绩效概览。" }, "PerformanceSummary": { "properties": { "total_hours": { "type": "number", "title": "Total Hours" }, "total_income": { "type": "number", "title": "Total Income" }, "total_customers": { "type": "integer", "title": "Total Customers" }, "month_label": { "type": "string", "title": "Month Label" }, "tier_nodes": { "items": { "type": "number" }, "type": "array", "title": "Tier Nodes" }, "basic_hours": { "type": "number", "title": "Basic Hours" }, "bonus_hours": { "type": "number", "title": "Bonus Hours" }, "current_tier": { "type": "integer", "title": "Current Tier" }, "next_tier_hours": { "type": "number", "title": "Next Tier Hours" }, "tier_completed": { "type": "boolean", "title": "Tier Completed" }, "bonus_money": { "type": "number", "title": "Bonus Money" }, "income_trend": { "type": "string", "title": "Income Trend" }, "income_trend_dir": { "type": "string", "enum": ["up", "down"], "title": "Income Trend Dir" }, "prev_month": { "type": "string", "title": "Prev Month" }, "current_tier_label": { "type": "string", "title": "Current Tier Label" } }, "type": "object", "required": ["total_hours", "total_income", "total_customers", "month_label", "current_tier", "income_trend", "income_trend_dir"], "title": "PerformanceSummary", "description": "绩效概览（附带在任务列表响应中）。" }, "TaskDetailResponse": { "properties": { "id": { "type": "integer", "title": "Id" }, "customer_name": { "type": "string", "title": "Customer Name" }, "customer_avatar": { "type": "string", "title": "Customer Avatar" }, "task_type": { "type": "string", "title": "Task Type" }, "task_type_label": { "type": "string", "title": "Task Type Label" }, "deadline": { "anyOf": [{ "type": "string" }, { "type": "null" }], "title": "Deadline" }, "heart_score": { "type": "number", "title": "Heart Score" }, "hobbies": { "items": { "type": "string" }, "type": "array", "title": "Hobbies" }, "is_pinned": { "type": "boolean", "title": "Is Pinned" }, "has_note": { "type": "boolean", "title": "Has Note" }, "status": { "type": "string", "title": "Status" }, "customer_id": { "type": "integer", "title": "Customer Id" }, "retention_clues": { "items": { "$ref": "#/components/schemas/RetentionClue" }, "type": "array", "title": "Retention Clues" }, "talking_points": { "items": { "type": "string" }, "type": "array", "title": "Talking Points" }, "service_summary": { "$ref": "#/components/schemas/ServiceSummary" }, "service_records": { "items": { "$ref": "#/components/schemas/ServiceRecord" }, "type": "array", "title": "Service Records" }, "ai_analysis": { "$ref": "#/components/schemas/AiAnalysis" }, "notes": { "items": { "$ref": "#/components/schemas/NoteItem" }, "type": "array", "title": "Notes" } }, "type": "object", "required": ["id", "customer_name", "task_type", "status", "customer_id", "retention_clues", "talking_points", "service_summary", "service_records", "ai_analysis", "notes"], "title": "TaskDetailResponse", "description": "TASK-2 响应：任务详情完整版。" }, "RetentionClue": { "properties": { "tag": { "type": "string", "title": "Tag" }, "tag_color": { "type": "string", "title": "Tag Color" }, "emoji": { "type": "string", "title": "Emoji" }, "text": { "type": "string", "title": "Text" }, "source": { "type": "string", "enum": ["manual", "ai_consumption", "ai_note"], "title": "Source" }, "desc": { "anyOf": [{ "type": "string" }, { "type": "null" }], "title": "Desc" } }, "type": "object", "required": ["tag", "tag_color", "emoji", "text", "source"], "title": "RetentionClue", "description": "维客线索。" }, "ServiceSummary": { "properties": { "total_hours": { "type": "number", "title": "Total Hours" }, "total_income": { "type": "number", "title": "Total Income" }, "avg_income": { "type": "number", "title": "Avg Income" } }, "type": "object", "required": ["total_hours", "total_income", "avg_income"], "title": "ServiceSummary", "description": "服务汇总。" }, "ServiceRecord": { "properties": { "table": { "anyOf": [{ "type": "string" }, { "type": "null" }], "title": "Table" }, "type": { "type": "string", "title": "Type" }, "type_class": { "type": "string", "enum": ["basic", "vip", "tip", "recharge", "incentive"], "title": "Type Class" }, "duration": { "type": "number", "title": "Duration" }, "duration_raw": { "anyOf": [{ "type": "number" }, { "type": "null" }], "title": "Duration Raw" }, "income": { "type": "number", "title": "Income" }, "is_estimate": { "anyOf": [{ "type": "boolean" }, { "type": "null" }], "title": "Is Estimate" }, "date": { "type": "string", "title": "Date" } }, "type": "object", "required": ["type", "type_class", "duration", "income", "date"], "title": "ServiceRecord", "description": "服务记录。" }, "AiAnalysis": { "properties": { "summary": { "type": "string", "title": "Summary" }, "suggestions": { "items": { "type": "string" }, "type": "array", "title": "Suggestions" } }, "type": "object", "required": ["summary", "suggestions"], "title": "AiAnalysis", "description": "AI 分析结果。" }, "NoteItem": { "properties": { "id": { "type": "integer", "title": "Id" }, "content": { "type": "string", "title": "Content" }, "tag_type": { "type": "string", "title": "Tag Type" }, "tag_label": { "type": "string", "title": "Tag Label" }, "created_at": { "type": "string", "title": "Created At" }, "ai_score": { "anyOf": [{ "type": "integer", "minimum": 1, "maximum": 10 }, { "type": "null" }], "title": "Ai Score", "description": "AI 应用 6 评分（1-10），星数 = ai_score ÷ 2" }, "rating_service_willingness": { "anyOf": [{ "type": "integer", "minimum": 1, "maximum": 5 }, { "type": "null" }], "title": "Rating Service Willingness", "description": "再次服务意愿（1-5）" }, "rating_revisit_likelihood": { "anyOf": [{ "type": "integer", "minimum": 1, "maximum": 5 }, { "type": "null" }], "title": "Rating Revisit Likelihood", "description": "再来店可能性（1-5）" } }, "type": "object", "required": ["id", "content", "tag_type", "tag_label", "created_at"], "title": "NoteItem", "description": "备注项。" }, "PerformanceOverviewResponse": { "properties": { "coach_name": { "type": "string", "title": "Coach Name" }, "coach_role": { "type": "string", "title": "Coach Role" }, "store_name": { "type": "string", "title": "Store Name" }, "monthly_income": { "type": "string", "title": "Monthly Income" }, "last_month_income": { "type": "string", "title": "Last Month Income" }, "current_tier": { "$ref": "#/components/schemas/TierInfo" }, "next_tier": { "$ref": "#/components/schemas/TierInfo" }, "upgrade_hours_needed": { "type": "number", "title": "Upgrade Hours Needed" }, "upgrade_bonus": { "type": "number", "title": "Upgrade Bonus" }, "income_items": { "items": { "$ref": "#/components/schemas/IncomeItem" }, "type": "array", "title": "Income Items" }, "monthly_total": { "type": "string", "title": "Monthly Total" }, "this_month_records": { "items": { "$ref": "#/components/schemas/DateGroup" }, "type": "array", "title": "This Month Records" }, "new_customers": { "items": { "$ref": "#/components/schemas/NewCustomer" }, "type": "array", "title": "New Customers" }, "regular_customers": { "items": { "$ref": "#/components/schemas/RegularCustomer" }, "type": "array", "title": "Regular Customers" } }, "type": "object", "required": ["coach_name", "coach_role", "store_name", "monthly_income", "last_month_income", "current_tier", "next_tier", "income_items", "monthly_total", "this_month_records", "new_customers", "regular_customers"], "title": "PerformanceOverviewResponse", "description": "PERF-1 响应：绩效概览。" }, "TierInfo": { "properties": { "basic_rate": { "type": "number", "title": "Basic Rate" }, "incentive_rate": { "type": "number", "title": "Incentive Rate" } }, "type": "object", "required": ["basic_rate", "incentive_rate"], "title": "TierInfo" }, "IncomeItem": { "properties": { "icon": { "type": "string", "title": "Icon" }, "label": { "type": "string", "title": "Label" }, "desc": { "type": "string", "title": "Desc" }, "value": { "type": "string", "title": "Value" } }, "type": "object", "required": ["icon", "label", "desc", "value"], "title": "IncomeItem" }, "DateGroup": { "properties": { "date": { "type": "string", "title": "Date" }, "total_hours": { "type": "string", "title": "Total Hours" }, "total_income": { "type": "string", "title": "Total Income" }, "records": { "items": { "$ref": "#/components/schemas/DateGroupRecord" }, "type": "array", "title": "Records" } }, "type": "object", "required": ["date", "total_hours", "total_income", "records"], "title": "DateGroup" }, "DateGroupRecord": { "properties": { "customer_name": { "type": "string", "title": "Customer Name" }, "avatar_char": { "anyOf": [{ "type": "string" }, { "type": "null" }], "title": "Avatar Char" }, "avatar_color": { "anyOf": [{ "type": "string" }, { "type": "null" }], "title": "Avatar Color" }, "time_range": { "type": "string", "title": "Time Range" }, "hours": { "type": "string", "title": "Hours" }, "course_type": { "type": "string", "title": "Course Type" }, "course_type_class": { "type": "string", "enum": ["basic", "vip", "tip", "recharge", "incentive"], "title": "Course Type Class" }, "location": { "type": "string", "title": "Location" }, "income": { "type": "string", "title": "Income" } }, "type": "object", "required": ["customer_name", "time_range", "hours", "course_type", "course_type_class", "location", "income"], "title": "DateGroupRecord" }, "NewCustomer": { "properties": { "name": { "type": "string", "title": "Name" }, "avatar_char": { "type": "string", "title": "Avatar Char" }, "avatar_color": { "type": "string", "title": "Avatar Color" }, "last_service": { "type": "string", "title": "Last Service" }, "count": { "type": "integer", "title": "Count" } }, "type": "object", "required": ["name", "avatar_char", "avatar_color", "last_service", "count"], "title": "NewCustomer" }, "RegularCustomer": { "properties": { "name": { "type": "string", "title": "Name" }, "avatar_char": { "type": "string", "title": "Avatar Char" }, "avatar_color": { "type": "string", "title": "Avatar Color" }, "hours": { "type": "number", "title": "Hours" }, "income": { "type": "string", "title": "Income" }, "count": { "type": "integer", "title": "Count" } }, "type": "object", "required": ["name", "avatar_char", "avatar_color", "hours", "income", "count"], "title": "RegularCustomer" }, "PerformanceRecordsResponse": { "properties": { "summary": { "$ref": "#/components/schemas/RecordsSummary" }, "date_groups": { "items": { "$ref": "#/components/schemas/DateGroup" }, "type": "array", "title": "Date Groups" }, "has_more": { "type": "boolean", "title": "Has More" } }, "type": "object", "required": ["summary", "date_groups", "has_more"], "title": "PerformanceRecordsResponse", "description": "PERF-2 响应：绩效明细。" }, "RecordsSummary": { "properties": { "total_count": { "type": "integer", "title": "Total Count" }, "total_hours": { "type": "number", "title": "Total Hours" }, "total_hours_raw": { "type": "number", "title": "Total Hours Raw" }, "total_income": { "type": "number", "title": "Total Income" } }, "type": "object", "required": ["total_count", "total_hours", "total_hours_raw", "total_income"], "title": "RecordsSummary" }, "TaskRegistryResponse": { "properties": { "groups": { "additionalProperties": { "items": { "$ref": "#/components/schemas/TaskItem" }, "type": "array" }, "type": "object", "title": "Groups" } }, "type": "object", "required": [ "groups" ], "title": "TaskRegistryResponse", "description": "按业务域分组的任务列表" }, "TokenResponse": { "properties": { "access_token": { "type": "string", "title": "Access Token" }, "refresh_token": { "type": "string", "title": "Refresh Token" }, "token_type": { "type": "string", "title": "Token Type", "default": "bearer" } }, "type": "object", "required": [ "access_token", "refresh_token" ], "title": "TokenResponse", "description": "令牌响应。" }, "UpdateScheduleRequest": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "task_codes": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Task Codes" }, "task_config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Task Config" }, "schedule_config": { "anyOf": [ { "$ref": "#/components/schemas/ScheduleConfigSchema" }, { "type": "null" } ] } }, "type": "object", "title": "UpdateScheduleRequest", "description": "更新调度任务请求（所有字段可选）" }, "UserStatusResponse": { "properties": { "user_id": { "type": "integer", "title": "User Id" }, "status": { "type": "string", "title": "Status" }, "nickname": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nickname" }, "applications": { "items": { "$ref": "#/components/schemas/ApplicationResponse" }, "type": "array", "title": "Applications", "default": [] } }, "type": "object", "required": [ "user_id", "status" ], "title": "UserStatusResponse", "description": "用户状态查询响应。" }, "ValidateRequest": { "properties": { "config": { "$ref": "#/components/schemas/TaskConfigSchema" } }, "type": "object", "required": [ "config" ], "title": "ValidateRequest", "description": "验证请求体 — 复用 TaskConfigSchema，但 store_id 由后端注入" }, "ValidateResponse": { "properties": { "valid": { "type": "boolean", "title": "Valid" }, "command": { "type": "string", "title": "Command" }, "command_args": { "items": { "type": "string" }, "type": "array", "title": "Command Args" }, "errors": { "items": { "type": "string" }, "type": "array", "title": "Errors" } }, "type": "object", "required": [ "valid", "command", "command_args", "errors" ], "title": "ValidateResponse", "description": "验证结果 + CLI 命令预览" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "CustomerDetailResponse": { "type": "object", "title": "CustomerDetailResponse", "description": "CUST-1 客户详情响应。包含基础信息、Banner 概览、AI 洞察、关联助教任务、最亲密助教、维客线索、消费记录、备注。", "required": ["id", "name", "phone", "phoneFull", "avatar", "memberLevel", "relationIndex"], "properties": { "id": { "type": "integer", "description": "客户唯一 ID" }, "name": { "type": "string", "description": "客户姓名（DQ-6: JOIN v_dim_member）" }, "phone": { "type": "string", "description": "脱敏手机号" }, "phoneFull": { "type": "string", "description": "完整手机号" }, "avatar": { "type": "string", "description": "头像 URL" }, "memberLevel": { "type": "string", "description": "会员等级（DQ-7: JOIN v_dim_member_card_account）" }, "relationIndex": { "type": "string", "description": "关系指数" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "客户标签" }, "balance": { "type": "number", "nullable": true, "description": "客户余额（元，items_sum 口径）" }, "consumption60d": { "type": "number", "nullable": true, "description": "近 60 天消费（元）" }, "idealInterval": { "type": "integer", "nullable": true, "description": "理想到店间隔（天）" }, "daysSinceVisit": { "type": "integer", "nullable": true, "description": "距上次到店天数" }, "aiInsight": { "type": "object", "description": "AI 洞察" }, "coachTasks": { "type": "array", "items": { "type": "object" }, "description": "关联助教任务" }, "favoriteCoaches": { "type": "array", "items": { "type": "object" }, "description": "最亲密助教" }, "retentionClues": { "type": "array", "items": { "type": "object" }, "description": "维客线索" }, "consumptionRecords": { "type": "array", "items": { "type": "object" }, "description": "消费记录（嵌套结构）" }, "notes": { "type": "array", "items": { "type": "object" }, "description": "备注列表（最多 20 条）" } } }, "CustomerRecordsResponse": { "type": "object", "title": "CustomerRecordsResponse", "description": "CUST-2 客户服务记录响应。按月查询，含月度统计汇总。", "required": ["customerName", "customerPhone", "customerPhoneFull", "relationIndex", "totalServiceCount", "monthCount", "monthHours"], "properties": { "customerName": { "type": "string", "description": "客户姓名" }, "customerPhone": { "type": "string", "description": "脱敏手机号" }, "customerPhoneFull": { "type": "string", "description": "完整手机号" }, "relationIndex": { "type": "string", "description": "关系指数" }, "tables": { "type": "array", "items": { "type": "object" }, "description": "可选台桌列表" }, "totalServiceCount": { "type": "integer", "description": "累计服务总次数（跨月）" }, "monthCount": { "type": "integer", "description": "当月服务次数" }, "monthHours": { "type": "number", "description": "当月总工时" }, "records": { "type": "array", "items": { "type": "object" }, "description": "服务记录列表" }, "hasMore": { "type": "boolean", "description": "是否有更多数据" } } }, "CoachDetailResponse": { "type": "object", "title": "CoachDetailResponse", "description": "COACH-1 助教详情响应。包含基本信息、绩效、收入明细、档位节点、任务分组、TOP 客户、服务记录、历史月份、备注。", "required": ["id", "name", "avatar", "level", "performance", "income"], "properties": { "id": { "type": "integer", "description": "助教 ID" }, "name": { "type": "string", "description": "助教姓名" }, "avatar": { "type": "string", "description": "头像 URL" }, "level": { "type": "string", "description": "等级（初级/中级/高级/星级）" }, "skills": { "type": "array", "items": { "type": "string" }, "description": "技能标签" }, "workYears": { "type": "number", "description": "工龄（年）" }, "customerCount": { "type": "integer", "description": "客户数" }, "hireDate": { "type": "string", "nullable": true, "description": "入职日期" }, "performance": { "type": "object", "description": "绩效指标（6 项）" }, "income": { "type": "object", "description": "收入明细（thisMonth/lastMonth）" }, "tierNodes": { "type": "array", "items": { "type": "number" }, "description": "档位节点数组" }, "visibleTasks": { "type": "array", "items": { "type": "object" }, "description": "进行中任务" }, "hiddenTasks": { "type": "array", "items": { "type": "object" }, "description": "已过期任务" }, "abandonedTasks": { "type": "array", "items": { "type": "object" }, "description": "已放弃任务" }, "topCustomers": { "type": "array", "items": { "type": "object" }, "description": "TOP 客户（最多 20 条）" }, "serviceRecords": { "type": "array", "items": { "type": "object" }, "description": "近期服务记录" }, "historyMonths": { "type": "array", "items": { "type": "object" }, "description": "历史月份统计" }, "notes": { "type": "array", "items": { "type": "object" }, "description": "备注列表（最多 20 条）" } } }, "WxLoginRequest": { "properties": { "code": { "type": "string", "minLength": 1, "title": "Code", "description": "微信临时登录凭证" } }, "type": "object", "required": [ "code" ], "title": "WxLoginRequest", "description": "微信登录请求。" }, "WxLoginResponse": { "properties": { "access_token": { "type": "string", "title": "Access Token" }, "refresh_token": { "type": "string", "title": "Refresh Token" }, "token_type": { "type": "string", "title": "Token Type", "default": "bearer" }, "user_status": { "type": "string", "title": "User Status" }, "user_id": { "type": "integer", "title": "User Id" } }, "type": "object", "required": [ "access_token", "refresh_token", "user_status", "user_id" ], "title": "WxLoginResponse", "description": "微信登录响应。" }, "CoachBoardResponse": { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CoachBoardItem" }, "title": "Items" }, "dimType": { "type": "string", "title": "Dim Type" } }, "type": "object", "required": [ "items", "dimType" ], "title": "CoachBoardResponse", "description": "助教看板响应（BOARD-1）。" }, "CoachBoardItem": { "properties": { "id": { "type": "integer", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "initial": { "type": "string", "title": "Initial" }, "avatarGradient": { "type": "string", "title": "Avatar Gradient" }, "level": { "type": "string", "title": "Level" }, "skills": { "type": "array", "items": { "type": "string" }, "title": "Skills" }, "topCustomers": { "type": "array", "items": { "type": "object" }, "title": "Top Customers" }, "perfHours": { "type": "number", "title": "Perf Hours" }, "salary": { "type": "number", "title": "Salary" }, "svAmount": { "type": "number", "title": "Sv Amount" }, "taskRecall": { "type": "object", "title": "Task Recall" } }, "type": "object", "required": [ "id", "name" ], "title": "CoachBoardItem", "description": "助教看板卡片项。" }, "CustomerBoardResponse": { "properties": { "items": { "type": "array", "items": { "type": "object" }, "title": "Items" }, "total": { "type": "integer", "title": "Total" }, "page": { "type": "integer", "title": "Page" }, "pageSize": { "type": "integer", "title": "Page Size" } }, "type": "object", "required": [ "items", "total", "page", "pageSize" ], "title": "CustomerBoardResponse", "description": "客户看板响应（BOARD-2）。" }, "FinanceBoardResponse": { "properties": { "overview": { "type": "object", "title": "Overview" }, "recharge": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Recharge" }, "revenue": { "type": "object", "title": "Revenue" }, "cashflow": { "type": "object", "title": "Cashflow" }, "expense": { "type": "object", "title": "Expense" }, "coachAnalysis": { "type": "object", "title": "Coach Analysis" } }, "type": "object", "required": [ "overview", "revenue", "cashflow", "expense", "coachAnalysis" ], "title": "FinanceBoardResponse", "description": "财务看板响应（BOARD-3）。area≠all 时 recharge 为 null。" }, "SkillTypeItem": { "properties": { "key": { "type": "string", "title": "Key" }, "label": { "type": "string", "title": "Label" }, "emoji": { "type": "string", "title": "Emoji" }, "cls": { "type": "string", "title": "Cls" } }, "type": "object", "required": [ "key", "label", "emoji", "cls" ], "title": "SkillTypeItem", "description": "技能类型配置项（CONFIG-1）。" } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer" } } } }