From 735a06e330b039142e3d5940e238853c6654f5ee Mon Sep 17 00:00:00 2001 From: rain <982766701@qq.com> Date: Mon, 27 Jul 2026 19:46:35 +0800 Subject: [PATCH] 1 --- PC.openapi.json | 8604 ++++++++++++++++++++++++++++++++++++++++ docs/PC接口对接规划.md | 1335 ++++--- docs/交接文档.md | 2 +- docs/规划.md | 2 +- 4 files changed, 9355 insertions(+), 588 deletions(-) create mode 100644 PC.openapi.json diff --git a/PC.openapi.json b/PC.openapi.json new file mode 100644 index 0000000..8b80861 --- /dev/null +++ b/PC.openapi.json @@ -0,0 +1,8604 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "PC", + "description": "家谱业务 APP/PC 用户侧接口文档，用于 Apifox 导入。\n\n导入方式：Apifox -> 导入 API 数据 -> OpenAPI/Swagger -> 选择本文件。\n\n约定：\n- APP 路径前缀为 `/genealogy/app`\n- PC/H5 路径前缀为 `/genealogy/pc`\n- 后台管理接口不包含在本文件内\n- 登录后接口需要携带 token，且请求 Header 需携带 `clientid`\n", + "version": "1.0.0" + }, + "tags": [ + { + "name": "验证中心" + }, + { + "name": "认证登录" + }, + { + "name": "文件上传" + }, + { + "name": "家谱" + }, + { + "name": "家族圈" + }, + { + "name": "行政区划" + }, + { + "name": "字辈谱" + }, + { + "name": "世系人物" + }, + { + "name": "内容文章" + }, + { + "name": "相册" + }, + { + "name": "视频" + }, + { + "name": "贺礼邀约" + }, + { + "name": "祭祀" + }, + { + "name": "族务记录" + }, + { + "name": "消息通知" + } + ], + "paths": { + "/genealogy/pc/auth/verification/{operationCode}/require": { + "get": { + "summary": "查询 PC 认证动作是否需要验证", + "deprecated": false, + "description": "服务端按 operationCode 对应 PC 路由的当前激活绑定解析验证场景，前端不得提交 sceneCode。", + "tags": [ + "验证中心" + ], + "parameters": [ + { + "name": "operationCode", + "in": "path", + "description": "PC 认证业务动作", + "required": true, + "example": "", + "schema": { + "type": "string", + "enum": [ + "password-login", + "sms-login", + "register", + "forgot-password", + "phone-change", + "account-deactivate" + ] + } + }, + { + "name": "tenantId", + "in": "query", + "description": "租户ID，用于区分不同租户的数据和验证策略", + "required": true, + "example": "000000", + "schema": { + "type": "string" + } + }, + { + "name": "subject", + "in": "query", + "description": "验证主体，通常为手机号、用户ID或登录账号", + "required": false, + "example": "13800000000", + "schema": { + "type": "string" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/VerificationRequireResult", + "description": "验证需求查询结果" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/auth/verification/{operationCode}/challenge": { + "post": { + "summary": "生成 PC 认证动作验证挑战", + "deprecated": false, + "description": "服务端按 operationCode 的激活绑定解析场景。tenantId、subject 必须完整提交；clientid 仅从 Header 读取，前端不得提交 clientId 或 sceneCode。", + "tags": [ + "验证中心" + ], + "parameters": [ + { + "name": "operationCode", + "in": "path", + "description": "PC 认证业务动作", + "required": true, + "example": "", + "schema": { + "type": "string", + "enum": [ + "password-login", + "sms-login", + "register", + "forgot-password", + "phone-change", + "account-deactivate" + ] + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VerificationChallengeBody" + }, + "example": { + "tenantId": "000000", + "subject": "13800000000" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/VerificationChallengeResult", + "description": "验证挑战生成结果" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/auth/verification/{operationCode}/verify": { + "post": { + "summary": "校验 PC 认证动作验证结果并换取 validToken", + "deprecated": false, + "description": "必须使用生成挑战时相同的 operationCode、tenantId、subject 和 challengeId。clientid 仅从 Header 读取；服务端重新解析同一路由的激活场景，前端不得提交 clientId 或 sceneCode。", + "tags": [ + "验证中心" + ], + "parameters": [ + { + "name": "operationCode", + "in": "path", + "description": "PC 认证业务动作", + "required": true, + "example": "", + "schema": { + "type": "string", + "enum": [ + "password-login", + "sms-login", + "register", + "forgot-password", + "phone-change", + "account-deactivate" + ] + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VerificationCheckBody" + }, + "examples": { + "tianai_behavior": { + "value": { + "tenantId": "000000", + "subject": "13800000000", + "challengeId": "CAPTCHA_CHALLENGE_ID", + "providerCode": "tianai", + "captchaType": "SLIDER", + "payload": { + "track": { + "bgImageWidth": 340, + "bgImageHeight": 180, + "templateImageWidth": 50, + "templateImageHeight": 50, + "startTime": 1720000000000, + "stopTime": 1720000001500, + "left": 120, + "top": 0, + "trackList": [ + { + "x": 0, + "y": 0, + "t": 0, + "type": "down" + }, + { + "x": 120, + "y": 0, + "t": 650, + "type": "move" + }, + { + "x": 120, + "y": 0, + "t": 700, + "type": "up" + } + ] + } + } + }, + "summary": "天爱滑块/旋转/滑动还原/文字点选验证" + }, + "system_image": { + "value": { + "tenantId": "000000", + "subject": "13800000000", + "challengeId": "CAPTCHA_CHALLENGE_ID", + "providerCode": "ruoyi_image", + "captchaType": "math", + "payload": { + "uuid": "captcha-uuid", + "code": "6" + } + }, + "summary": "系统图形验证码" + } + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/VerificationCheckResult", + "description": "验证校验结果" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/auth/register": { + "post": { + "summary": "PC 用户注册", + "deprecated": false, + "description": "", + "tags": [ + "认证登录" + ], + "parameters": [ + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PasswordRegisterBody" + }, + "example": { + "grantType": "password", + "tenantId": "000000", + "phone": "13800000000", + "password": "e10adc3949ba59abbe56e057f20f883e", + "nickName": "测试用户", + "registerSource": "app", + "smsCode": "1234" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/LoginResult", + "description": "登录结果" + }, + "400": { + "description": "短信验证码必须为 4 位数字；验证码错误、过期、重复使用，或租户、客户端、场景不匹配时拒绝；携带 validToken、code、uuid、供应商配置等旧字段返回 HTTP 400。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RVoid" + } + } + }, + "headers": {} + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/auth/login": { + "post": { + "summary": "PC 密码登录", + "deprecated": false, + "description": "", + "tags": [ + "认证登录" + ], + "parameters": [ + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PasswordLoginBody" + }, + "example": { + "grantType": "password", + "tenantId": "000000", + "phone": "13800000000", + "password": "e10adc3949ba59abbe56e057f20f883e", + "validToken": "valid-token-from-captcha-verify" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/LoginResult", + "description": "登录结果" + }, + "400": { + "description": "后端按 PC_PASSWORD_LOGIN 路由的当前激活绑定解析场景；该场景策略要求验证时必须提交匹配的 validToken，不要求验证时 validToken 可为空；请求携带已废弃的 sceneCode 或其他未知字段返回 HTTP 400。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RVoid" + } + } + }, + "headers": {} + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/auth/login/sms": { + "post": { + "summary": "PC 短信登录", + "deprecated": false, + "description": "", + "tags": [ + "认证登录" + ], + "parameters": [ + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SmsLoginBody" + }, + "example": { + "grantType": "sms", + "tenantId": "000000", + "phone": "13800000000", + "smsCode": "1234" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/LoginResult", + "description": "登录结果" + }, + "400": { + "description": "短信验证码必须为 4 位数字；验证码错误、过期、重复使用，或租户、客户端、场景不匹配时拒绝；携带 validToken、code、uuid、供应商配置等旧字段返回 HTTP 400。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RVoid" + } + } + }, + "headers": {} + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/auth/sms/{operationCode}/code": { + "post": { + "summary": "PC 发送短信验证码", + "deprecated": false, + "description": "operationCode 决定短信业务动作，服务端按对应 PC 路由的激活绑定解析验证场景。策略开启时需提交 validToken，关闭时可为空；前端不得提交 sceneCode 或短信供应商配置 ID。", + "tags": [ + "认证登录" + ], + "parameters": [ + { + "name": "operationCode", + "in": "path", + "description": "支持发送短信验证码的 PC 认证业务动作", + "required": true, + "example": "", + "schema": { + "type": "string", + "enum": [ + "sms-login", + "register", + "forgot-password", + "phone-change", + "account-deactivate" + ] + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SmsCodeBody" + }, + "example": { + "tenantId": "000000", + "phone": "13800000000", + "grantType": "sms", + "validToken": "captcha-ticket" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/VoidResult", + "description": "通用成功响应" + }, + "400": { + "description": "拒绝原因：票据缺失；票据与租户不匹配（错租户）；票据与客户端不匹配（错客户端）；票据与场景不匹配（错场景）；票据过期；票据已被使用（重复使用）；手机号主体不匹配；请求携带供应商配置或历史字段。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RVoid" + } + } + }, + "headers": {} + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/auth/profile": { + "get": { + "summary": "PC 当前用户资料", + "deprecated": false, + "description": "", + "tags": [ + "认证登录" + ], + "parameters": [ + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/ObjectResult", + "description": "通用对象响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + }, + "put": { + "summary": "PC 修改用户资料", + "deprecated": false, + "description": "", + "tags": [ + "认证登录" + ], + "parameters": [ + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProfileUpdateBody" + }, + "example": { + "nickName": "张三", + "realName": "张三", + "avatar": "2060000000000000000", + "sex": "0", + "birthday": "1990-01-01", + "email": "zhangsan@example.com" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/ObjectResult", + "description": "通用对象响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/auth/password": { + "put": { + "summary": "PC 修改密码", + "deprecated": false, + "description": "", + "tags": [ + "认证登录" + ], + "parameters": [ + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PasswordChangeBody" + }, + "example": { + "oldPassword": "e10adc3949ba59abbe56e057f20f883e", + "newPassword": "25d55ad283aa400af464c76d713c07ad" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/VoidResult", + "description": "通用成功响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/auth/password/reset": { + "put": { + "summary": "PC 找回密码", + "deprecated": false, + "description": "", + "tags": [ + "认证登录" + ], + "parameters": [ + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PasswordResetBody" + }, + "example": { + "grantType": "password", + "tenantId": "000000", + "phone": "13800000000", + "smsCode": "1234", + "newPassword": "25d55ad283aa400af464c76d713c07ad" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/VoidResult", + "description": "通用成功响应" + }, + "400": { + "description": "短信验证码必须为 4 位数字；验证码错误、过期、重复使用，或租户、客户端、场景不匹配时拒绝；携带 validToken、code、uuid、供应商配置等旧字段返回 HTTP 400。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RVoid" + } + } + }, + "headers": {} + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/auth/phone": { + "put": { + "summary": "PC 换绑手机号", + "deprecated": false, + "description": "", + "tags": [ + "认证登录" + ], + "parameters": [ + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PhoneChangeBody" + }, + "example": { + "phone": "13900000000", + "smsCode": "1234" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/ObjectResult", + "description": "通用对象响应" + }, + "400": { + "description": "短信验证码必须为 4 位数字；验证码错误、过期、重复使用，或租户、客户端、场景不匹配时拒绝；携带 validToken、code、uuid、供应商配置等旧字段返回 HTTP 400。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RVoid" + } + } + }, + "headers": {} + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/auth/account/deactivate": { + "post": { + "summary": "PC 注销账号", + "deprecated": false, + "description": "", + "tags": [ + "认证登录" + ], + "parameters": [ + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccountDeactivateBody" + }, + "example": { + "smsCode": "1234" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/VoidResult", + "description": "通用成功响应" + }, + "400": { + "description": "短信验证码必须为 4 位数字；验证码错误、过期、重复使用，或租户、客户端、场景不匹配时拒绝；携带 validToken、code、uuid、供应商配置等旧字段返回 HTTP 400。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RVoid" + } + } + }, + "headers": {} + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/auth/logout": { + "delete": { + "summary": "PC 退出登录", + "deprecated": false, + "description": "", + "tags": [ + "认证登录" + ], + "parameters": [ + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/VoidResult", + "description": "通用成功响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/files/resumable/init": { + "post": { + "summary": "PC 分片上传初始化", + "deprecated": false, + "description": "所有文件统一使用分片上传；普通小文件可设置为一个分片。返回 instant=true 时直接使用返回的 OSS 信息，跳过分片上传和合并。", + "tags": [ + "文件上传" + ], + "parameters": [ + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResumableInitBody" + }, + "example": { + "uploadId": "UPLOAD202607090001", + "fileName": "cover.jpg", + "fileMd5": "d41d8cd98f00b204e9800998ecf8427e", + "totalSize": 9532, + "totalChunks": 1, + "chunkSize": 4194304, + "contentType": "image/jpeg" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/ObjectResult", + "description": "通用对象响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/files/resumable/chunk": { + "post": { + "summary": "PC 上传分片", + "deprecated": false, + "description": "uploadId 已绑定初始化契约。除最后一片外，分片实际大小必须等于 chunkSize；最后一片必须等于剩余字节数。", + "tags": [ + "文件上传" + ], + "parameters": [ + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "uploadId": { + "type": "string", + "example": "" + }, + "chunkIndex": { + "type": "integer", + "examples": [ + 0 + ], + "example": 0 + }, + "chunkMd5": { + "type": "string", + "examples": [ + "d41d8cd98f00b204e9800998ecf8427e" + ], + "example": "d41d8cd98f00b204e9800998ecf8427e" + }, + "file": { + "type": "string", + "format": "binary", + "example": "" + } + }, + "required": [ + "uploadId", + "chunkIndex", + "chunkMd5", + "file" + ] + }, + "example": { + "uploadId": "", + "chunkIndex": 0, + "chunkMd5": "d41d8cd98f00b204e9800998ecf8427e", + "file": "" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/VoidResult", + "description": "通用成功响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/files/resumable/complete": { + "post": { + "summary": "PC 完成分片上传", + "deprecated": false, + "description": "", + "tags": [ + "文件上传" + ], + "parameters": [ + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResumableCompleteBody" + }, + "example": { + "uploadId": "UPLOAD202607090001", + "fileName": "cover.jpg", + "fileMd5": "d41d8cd98f00b204e9800998ecf8427e", + "totalSize": 9532, + "totalChunks": 1 + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/FileUploadResult", + "description": "文件上传结果" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/quota": { + "get": { + "summary": "PC 查询当前用户家谱配额", + "deprecated": false, + "description": "查询已创建和已加入的家谱数量、上限、剩余额度及是否还能继续操作。加入总数包含自己创建的家谱；limit 和 remaining 为 -1 时表示不限。", + "tags": [ + "家谱" + ], + "parameters": [ + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/GenealogyQuotaResult", + "description": "当前业务用户家谱配额响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/feeds": { + "get": { + "summary": "PC 家族圈动态列表", + "deprecated": false, + "description": "", + "tags": [ + "家族圈" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/FamilyFeedListResult", + "description": "家族圈动态列表响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + }, + "post": { + "summary": "PC 发布家族圈动态", + "deprecated": false, + "description": "", + "tags": [ + "家族圈" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FamilyFeedBody" + }, + "example": { + "feedType": "text", + "feedContent": "今天上传一张老照片。", + "mediaOssIds": "2060000000000000001,2060000000000000002", + "sortOrder": 0, + "status": "0" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/FamilyFeedResult", + "description": "家族圈动态对象响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/feeds/page": { + "get": { + "summary": "PC 家族圈动态分页", + "deprecated": false, + "description": "", + "tags": [ + "家族圈" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "pageNum", + "in": "query", + "description": "页码，从1开始", + "required": false, + "schema": { + "type": "integer", + "default": 1 + } + }, + { + "name": "pageSize", + "in": "query", + "description": "每页条数", + "required": false, + "schema": { + "type": "integer", + "default": 10 + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/FamilyFeedPageResult", + "description": "家族圈动态分页响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/feeds/{feedId}": { + "get": { + "summary": "PC 家族圈动态详情", + "deprecated": false, + "description": "", + "tags": [ + "家族圈" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "feedId", + "in": "path", + "description": "家族动态ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/FamilyFeedResult", + "description": "家族圈动态对象响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + }, + "put": { + "summary": "PC 修改家族圈动态", + "deprecated": false, + "description": "", + "tags": [ + "家族圈" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "feedId", + "in": "path", + "description": "家族动态ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FamilyFeedBody" + }, + "example": { + "feedType": "text", + "feedContent": "今天上传一张老照片。", + "mediaOssIds": "2060000000000000001,2060000000000000002", + "sortOrder": 0, + "status": "0" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/FamilyFeedResult", + "description": "家族圈动态对象响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + }, + "delete": { + "summary": "PC 删除家族圈动态", + "deprecated": false, + "description": "", + "tags": [ + "家族圈" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "feedId", + "in": "path", + "description": "家族动态ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/VoidResult", + "description": "通用成功响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/feeds/{feedId}/likes": { + "post": { + "summary": "PC 点赞动态", + "deprecated": false, + "description": "", + "tags": [ + "家族圈" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "feedId", + "in": "path", + "description": "家族动态ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/VoidResult", + "description": "通用成功响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + }, + "delete": { + "summary": "PC 取消点赞动态", + "deprecated": false, + "description": "", + "tags": [ + "家族圈" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "feedId", + "in": "path", + "description": "家族动态ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/VoidResult", + "description": "通用成功响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/feeds/{feedId}/comments": { + "get": { + "summary": "PC 动态一级评论列表", + "deprecated": false, + "description": "仅返回正常展示的一级评论；每条评论的 replyCount 为正常展示的直接回复数量。", + "tags": [ + "家族圈" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "feedId", + "in": "path", + "description": "家族动态ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/FamilyFeedCommentListResult", + "description": "家族圈评论列表响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + }, + "post": { + "summary": "PC 评论动态", + "deprecated": false, + "description": "", + "tags": [ + "家族圈" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "feedId", + "in": "path", + "description": "家族动态ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FamilyFeedCommentBody" + }, + "example": { + "parentCommentId": null, + "commentContent": "这张照片很有年代感。" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/FamilyFeedCommentResult", + "description": "家族圈评论对象响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/feeds/{feedId}/comments/page": { + "get": { + "summary": "PC 动态一级评论分页", + "deprecated": false, + "description": "仅返回正常展示的一级评论；展开回复时请调用 replies 接口。", + "tags": [ + "家族圈" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "feedId", + "in": "path", + "description": "家族动态ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "pageNum", + "in": "query", + "description": "页码，从1开始", + "required": false, + "schema": { + "type": "integer", + "default": 1 + } + }, + { + "name": "pageSize", + "in": "query", + "description": "每页条数", + "required": false, + "schema": { + "type": "integer", + "default": 10 + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/FamilyFeedCommentPageResult", + "description": "家族圈评论分页响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/feeds/{feedId}/comments/{commentId}/replies": { + "get": { + "summary": "PC 获取评论的直接回复列表", + "deprecated": false, + "description": "仅返回指定正常评论的正常展示直接回复；回复的 replyCount 可用于继续按需展开下一层。", + "tags": [ + "家族圈" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "feedId", + "in": "path", + "description": "家族动态ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "commentId", + "in": "path", + "description": "父评论 ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/FamilyFeedCommentListResult", + "description": "家族圈评论列表响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/feeds/{feedId}/comments/{commentId}/replies/page": { + "get": { + "summary": "PC 分页获取评论的直接回复", + "deprecated": false, + "description": "", + "tags": [ + "家族圈" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "feedId", + "in": "path", + "description": "家族动态ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "commentId", + "in": "path", + "description": "父评论 ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "pageNum", + "in": "query", + "description": "页码，从1开始", + "required": false, + "schema": { + "type": "integer", + "default": 1 + } + }, + { + "name": "pageSize", + "in": "query", + "description": "每页条数", + "required": false, + "schema": { + "type": "integer", + "default": 10 + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/FamilyFeedCommentPageResult", + "description": "家族圈评论分页响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/feeds/{feedId}/comments/{commentId}": { + "delete": { + "summary": "PC 删除本人动态评论；有回复时保留删除占位", + "deprecated": false, + "description": "", + "tags": [ + "家族圈" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "feedId", + "in": "path", + "description": "家族动态ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "commentId", + "in": "path", + "description": "评论ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/VoidResult", + "description": "通用成功响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/region/children": { + "get": { + "summary": "查询下级行政区划", + "deprecated": false, + "description": "", + "tags": [ + "行政区划" + ], + "parameters": [ + { + "name": "parentCode", + "in": "query", + "description": "父级行政区划编码，不传或传0查省级", + "required": false, + "example": "51", + "schema": { + "type": "string" + } + }, + { + "name": "clientid", + "in": "header", + "description": "客户端ID", + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string", + "default": "ced7e5f0498645c6ec642dcf450b036f" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/ListResult", + "description": "通用列表响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/region/path/{regionCode}": { + "get": { + "summary": "查询行政区划路径", + "deprecated": false, + "description": "", + "tags": [ + "行政区划" + ], + "parameters": [ + { + "name": "regionCode", + "in": "path", + "description": "行政区划编码", + "required": true, + "example": "510000", + "schema": { + "type": "string" + } + }, + { + "name": "clientid", + "in": "header", + "description": "客户端ID", + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string", + "default": "ced7e5f0498645c6ec642dcf450b036f" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/ListResult", + "description": "通用列表响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/region/search": { + "get": { + "summary": "搜索行政区划", + "deprecated": false, + "description": "", + "tags": [ + "行政区划" + ], + "parameters": [ + { + "name": "keyword", + "in": "query", + "description": "搜索关键词，支持地区名称或编码模糊查询", + "required": true, + "example": "北京", + "schema": { + "type": "string" + } + }, + { + "name": "level", + "in": "query", + "description": "行政区划级别，1省、2市、3区县、4乡镇街道、5村社区", + "required": false, + "example": 3, + "schema": { + "type": "integer" + } + }, + { + "name": "limit", + "in": "query", + "description": "返回数量上限", + "required": false, + "example": 20, + "schema": { + "type": "integer" + } + }, + { + "name": "clientid", + "in": "header", + "description": "客户端ID", + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string", + "default": "ced7e5f0498645c6ec642dcf450b036f" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/ListResult", + "description": "通用列表响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/region/{regionCode}": { + "get": { + "summary": "查询行政区划详情", + "deprecated": false, + "description": "", + "tags": [ + "行政区划" + ], + "parameters": [ + { + "name": "regionCode", + "in": "path", + "description": "行政区划编码", + "required": true, + "example": "510000", + "schema": { + "type": "string" + } + }, + { + "name": "clientid", + "in": "header", + "description": "客户端ID", + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string", + "default": "ced7e5f0498645c6ec642dcf450b036f" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/ObjectResult", + "description": "通用对象响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/region/children": { + "get": { + "summary": "查询下级行政区划", + "deprecated": false, + "description": "", + "tags": [ + "行政区划" + ], + "parameters": [ + { + "name": "parentCode", + "in": "query", + "description": "父级行政区划编码，不传或传0查省级", + "required": false, + "example": "51", + "schema": { + "type": "string" + } + }, + { + "name": "clientid", + "in": "header", + "description": "客户端ID", + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string", + "default": "ced7e5f0498645c6ec642dcf450b036f" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/ListResult", + "description": "通用列表响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/region/path/{regionCode}": { + "get": { + "summary": "查询行政区划路径", + "deprecated": false, + "description": "", + "tags": [ + "行政区划" + ], + "parameters": [ + { + "name": "regionCode", + "in": "path", + "description": "行政区划编码", + "required": true, + "example": "510000", + "schema": { + "type": "string" + } + }, + { + "name": "clientid", + "in": "header", + "description": "客户端ID", + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string", + "default": "ced7e5f0498645c6ec642dcf450b036f" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/ListResult", + "description": "通用列表响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/region/search": { + "get": { + "summary": "搜索行政区划", + "deprecated": false, + "description": "", + "tags": [ + "行政区划" + ], + "parameters": [ + { + "name": "keyword", + "in": "query", + "description": "搜索关键词，支持地区名称或编码模糊查询", + "required": true, + "example": "北京", + "schema": { + "type": "string" + } + }, + { + "name": "level", + "in": "query", + "description": "行政区划级别，1省、2市、3区县、4乡镇街道、5村社区", + "required": false, + "example": 3, + "schema": { + "type": "integer" + } + }, + { + "name": "limit", + "in": "query", + "description": "返回数量上限", + "required": false, + "example": 20, + "schema": { + "type": "integer" + } + }, + { + "name": "clientid", + "in": "header", + "description": "客户端ID", + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string", + "default": "ced7e5f0498645c6ec642dcf450b036f" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/ListResult", + "description": "通用列表响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/region/{regionCode}": { + "get": { + "summary": "查询行政区划详情", + "deprecated": false, + "description": "", + "tags": [ + "行政区划" + ], + "parameters": [ + { + "name": "regionCode", + "in": "path", + "description": "行政区划编码", + "required": true, + "example": "510000", + "schema": { + "type": "string" + } + }, + { + "name": "clientid", + "in": "header", + "description": "客户端ID", + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string", + "default": "ced7e5f0498645c6ec642dcf450b036f" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/ObjectResult", + "description": "通用对象响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/generation-poems": { + "get": { + "summary": "PC 查询正常字辈谱", + "deprecated": false, + "description": "对可查看家谱的业务用户开放；仅返回正常状态字辈，供世系人物录入和展示使用。", + "tags": [ + "字辈谱" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/GenerationPoemListResult", + "description": "字辈列表响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + }, + "post": { + "summary": "PC 新增字辈", + "deprecated": false, + "description": "", + "tags": [ + "字辈谱" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GenerationPoemBody" + }, + "example": { + "generationNo": 5, + "generationText": "忠", + "description": "第五世字辈", + "sortOrder": 5, + "status": "0" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/GenerationPoemResult", + "description": "字辈详情响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/generation-poems/management": { + "get": { + "summary": "PC 查询字辈维护列表", + "deprecated": false, + "description": "仅家谱内容编辑者可访问，返回正常和停用字辈，用于恢复、纠错和排序调整。", + "tags": [ + "字辈谱" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/GenerationPoemListResult", + "description": "字辈列表响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/generation-poems/batch/preview": { + "post": { + "summary": "PC 批量字辈预览", + "deprecated": false, + "description": "", + "tags": [ + "字辈谱" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GenerationPoemBatchBody" + }, + "example": { + "poemText": "德承家亦\n忠厚传芳", + "disableMissing": false + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/GenerationPoemBatchPreviewResult", + "description": "字辈批量预览响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/generation-poems/batch/save": { + "post": { + "summary": "PC 批量保存字辈", + "deprecated": false, + "description": "保存时会重新按当前数据生成差异；停用不删除历史字辈记录。", + "tags": [ + "字辈谱" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GenerationPoemBatchBody" + }, + "example": { + "poemText": "德承家亦\n忠厚传芳", + "disableMissing": false + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/VoidResult", + "description": "通用成功响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/generation-poems/{poemId}": { + "put": { + "summary": "PC 修改、停用或恢复字辈", + "deprecated": false, + "description": "", + "tags": [ + "字辈谱" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "poemId", + "in": "path", + "description": "字辈记录ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GenerationPoemBody" + }, + "example": { + "generationNo": 5, + "generationText": "忠", + "description": "第五世字辈", + "sortOrder": 5, + "status": "0" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/GenerationPoemResult", + "description": "字辈详情响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/lineage/persons": { + "get": { + "summary": "PC 世系人物列表", + "deprecated": false, + "description": "", + "tags": [ + "世系人物" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/LineagePersonListResult", + "description": "世系人物列表或选项响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + }, + "post": { + "summary": "PC 新增世系人物", + "deprecated": false, + "description": "", + "tags": [ + "世系人物" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LineagePersonBody" + }, + "example": { + "bindingMode": "NONE", + "personNo": "P202607090001", + "name": "彭德明", + "aliasName": "德明", + "sex": "0", + "generation": 1, + "generationName": "德", + "avatarOssId": "2060000000000000001", + "birthDate": "1950-01-01", + "birthLunar": "0", + "birthPlace": "江西吉安", + "personStatus": "0", + "biography": "第一世人物简介", + "sortOrder": 1 + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/LineagePersonResult", + "description": "世系人物详情响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/lineage/persons/page": { + "get": { + "summary": "PC 世系人物分页", + "deprecated": false, + "description": "", + "tags": [ + "世系人物" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "pageNum", + "in": "query", + "description": "页码，从1开始", + "required": false, + "schema": { + "type": "integer", + "default": 1 + } + }, + { + "name": "pageSize", + "in": "query", + "description": "每页条数", + "required": false, + "schema": { + "type": "integer", + "default": 10 + } + }, + { + "name": "keyword", + "in": "query", + "description": "姓名、别名或人物编号关键词", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "generation", + "in": "query", + "description": "世代序号", + "required": false, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "personStatus", + "in": "query", + "description": "字典 gen_lineage_person_status：0=健在，1=已故，2=未知", + "required": false, + "schema": { + "type": "string", + "enum": [ + "0", + "1", + "2" + ], + "x-dict-type": "gen_lineage_person_status", + "examples": [ + "0" + ] + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/LineagePersonPageResult", + "description": "世系人物分页响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/lineage/persons/options": { + "get": { + "summary": "PC 世系人物选项", + "deprecated": false, + "description": "", + "tags": [ + "世系人物" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "keyword", + "in": "query", + "description": "姓名、别名或人物编号关键词", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/LineagePersonListResult", + "description": "世系人物列表或选项响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/lineage/tree": { + "get": { + "summary": "PC 世系树", + "deprecated": false, + "description": "", + "tags": [ + "世系人物" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/LineagePersonTreeResult", + "description": "世系树响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/lineage/persons/{personId}": { + "get": { + "summary": "PC 世系人物详情", + "deprecated": false, + "description": "", + "tags": [ + "世系人物" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "personId", + "in": "path", + "description": "世系人物ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/LineagePersonResult", + "description": "世系人物详情响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + }, + "put": { + "summary": "PC 修改世系人物", + "deprecated": false, + "description": "", + "tags": [ + "世系人物" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "personId", + "in": "path", + "description": "世系人物ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LineagePersonBody" + }, + "example": { + "bindingMode": "NONE", + "personNo": "P202607090001", + "name": "彭德明", + "aliasName": "德明", + "sex": "0", + "generation": 1, + "generationName": "德", + "avatarOssId": "2060000000000000001", + "birthDate": "1950-01-01", + "birthLunar": "0", + "birthPlace": "江西吉安", + "personStatus": "0", + "biography": "第一世人物简介", + "sortOrder": 1 + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/LineagePersonResult", + "description": "世系人物详情响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + }, + "delete": { + "summary": "PC 停用世系人物", + "deprecated": false, + "description": "逻辑停用人物，不执行物理删除；存在正常子女时拒绝停用。", + "tags": [ + "世系人物" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "personId", + "in": "path", + "description": "世系人物ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/VoidResult", + "description": "通用成功响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/lineage/persons/{personId}/children": { + "post": { + "summary": "PC 给人物添加子女", + "deprecated": false, + "description": "", + "tags": [ + "世系人物" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "personId", + "in": "path", + "description": "世系人物ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LineagePersonBody" + }, + "example": { + "bindingMode": "NONE", + "personNo": "P202607090001", + "name": "彭德明", + "aliasName": "德明", + "sex": "0", + "generation": 1, + "generationName": "德", + "avatarOssId": "2060000000000000001", + "birthDate": "1950-01-01", + "birthLunar": "0", + "birthPlace": "江西吉安", + "personStatus": "0", + "biography": "第一世人物简介", + "sortOrder": 1 + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/LineagePersonResult", + "description": "世系人物详情响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/lineage/persons/{personId}/parents": { + "post": { + "summary": "PC 给人物添加父母", + "deprecated": false, + "description": "", + "tags": [ + "世系人物" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "personId", + "in": "path", + "description": "世系人物ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LineagePersonBody" + }, + "example": { + "bindingMode": "NONE", + "personNo": "P202607090001", + "name": "彭德明", + "aliasName": "德明", + "sex": "0", + "generation": 1, + "generationName": "德", + "avatarOssId": "2060000000000000001", + "birthDate": "1950-01-01", + "birthLunar": "0", + "birthPlace": "江西吉安", + "personStatus": "0", + "biography": "第一世人物简介", + "sortOrder": 1 + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/LineagePersonResult", + "description": "世系人物详情响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/lineage/persons/{personId}/siblings": { + "post": { + "summary": "PC 给人物添加兄弟姐妹", + "deprecated": false, + "description": "", + "tags": [ + "世系人物" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "personId", + "in": "path", + "description": "世系人物ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LineagePersonBody" + }, + "example": { + "bindingMode": "NONE", + "personNo": "P202607090001", + "name": "彭德明", + "aliasName": "德明", + "sex": "0", + "generation": 1, + "generationName": "德", + "avatarOssId": "2060000000000000001", + "birthDate": "1950-01-01", + "birthLunar": "0", + "birthPlace": "江西吉安", + "personStatus": "0", + "biography": "第一世人物简介", + "sortOrder": 1 + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/LineagePersonResult", + "description": "世系人物详情响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/lineage/persons/{personId}/spouses": { + "post": { + "summary": "PC 给人物添加配偶", + "deprecated": false, + "description": "", + "tags": [ + "世系人物" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "personId", + "in": "path", + "description": "世系人物ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LineagePersonBody" + }, + "example": { + "bindingMode": "NONE", + "personNo": "P202607090001", + "name": "彭德明", + "aliasName": "德明", + "sex": "0", + "generation": 1, + "generationName": "德", + "avatarOssId": "2060000000000000001", + "birthDate": "1950-01-01", + "birthLunar": "0", + "birthPlace": "江西吉安", + "personStatus": "0", + "biography": "第一世人物简介", + "sortOrder": 1 + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/LineagePersonResult", + "description": "世系人物详情响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/articles/{articleId}": { + "delete": { + "summary": "PC 删除谱文", + "deprecated": false, + "description": "", + "tags": [ + "内容文章" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "articleId", + "in": "path", + "description": "要删除的谱文ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/VoidResult", + "description": "通用成功响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/albums/{albumId}": { + "delete": { + "summary": "PC 删除相册", + "deprecated": false, + "description": "逻辑删除相册及其照片，并释放封面和照片文件引用。", + "tags": [ + "相册" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "albumId", + "in": "path", + "description": "要删除的相册ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/VoidResult", + "description": "通用成功响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/albums/{albumId}/photos/{photoId}": { + "delete": { + "summary": "PC 删除单张相册图片", + "deprecated": false, + "description": "", + "tags": [ + "相册" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "albumId", + "in": "path", + "description": "相册ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "photoId", + "in": "path", + "description": "要删除的相册图片ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/VoidResult", + "description": "通用成功响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/videos/{videoId}": { + "delete": { + "summary": "PC 删除视频", + "deprecated": false, + "description": "逻辑删除视频，并释放视频文件和封面文件引用。", + "tags": [ + "视频" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "videoId", + "in": "path", + "description": "要删除的视频ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/VoidResult", + "description": "通用成功响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + }, + "get": { + "summary": "PC 视频详情", + "deprecated": false, + "description": "", + "tags": [ + "视频" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "videoId", + "in": "path", + "description": "视频ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/ObjectResult", + "description": "通用对象响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + }, + "put": { + "summary": "PC 修改视频", + "deprecated": false, + "description": "", + "tags": [ + "视频" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "videoId", + "in": "path", + "description": "视频ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VideoBody" + }, + "example": { + "videoTitle": "家族活动记录", + "videoDesc": "清明祭祖活动视频", + "coverOssId": "2060000000000000001", + "videoOssId": "2060000000000000002", + "durationSeconds": 180, + "sortOrder": 1, + "status": "0" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/ObjectResult", + "description": "通用对象响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/videos": { + "get": { + "summary": "PC 视频列表", + "deprecated": false, + "description": "", + "tags": [ + "视频" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/ListResult", + "description": "通用列表响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + }, + "post": { + "summary": "PC 新增视频", + "deprecated": false, + "description": "", + "tags": [ + "视频" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VideoBody" + }, + "example": { + "videoTitle": "家族活动记录", + "videoDesc": "清明祭祖活动视频", + "coverOssId": "2060000000000000001", + "videoOssId": "2060000000000000002", + "durationSeconds": 180, + "sortOrder": 1, + "status": "0" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/ObjectResult", + "description": "通用对象响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/ceremonies/{ceremonyId}/invitees": { + "put": { + "summary": "PC 替换活动受邀人", + "deprecated": false, + "description": "使用完整名单替换当前待响应受邀人；仅家谱内容管理员可操作，受邀人必须是同一家谱的正常成员。", + "tags": [ + "贺礼邀约" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "ceremonyId", + "in": "path", + "description": "贺礼活动ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CeremonyInviteesBody" + }, + "example": { + "inviteeUserIds": [ + 900000001, + 900000002 + ] + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/CeremonyInvitationListResult", + "description": "贺礼邀约列表响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/ceremonies/{ceremonyId}/invitations": { + "get": { + "summary": "PC 查询活动邀请名单", + "deprecated": false, + "description": "查询受邀人及其待响应、接受、拒绝或取消状态，仅家谱内容管理员可见。", + "tags": [ + "贺礼邀约" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "ceremonyId", + "in": "path", + "description": "贺礼活动ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/CeremonyInvitationListResult", + "description": "贺礼邀约列表响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/ceremonies/{ceremonyId}/invitations/me": { + "put": { + "summary": "PC 响应当前用户的活动邀请", + "deprecated": false, + "description": "当前登录用户接受或拒绝自己的待响应邀请，不能代替其他用户操作。", + "tags": [ + "贺礼邀约" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "ceremonyId", + "in": "path", + "description": "贺礼活动ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CeremonyInvitationResponseBody" + }, + "example": { + "inviteStatus": "ACCEPTED" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/CeremonyInvitationResult", + "description": "贺礼邀约详情响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/ceremony-invitations/mine": { + "get": { + "summary": "PC 查询我的活动邀请", + "deprecated": false, + "description": "查询当前租户下发给当前业务用户且活动仍正常的邀请。", + "tags": [ + "贺礼邀约" + ], + "parameters": [ + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/CeremonyInvitationListResult", + "description": "贺礼邀约列表响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/ceremonies/{ceremonyId}": { + "delete": { + "summary": "PC 删除祭祀活动", + "deprecated": false, + "description": "逻辑删除祭祀活动及其祭品，并释放活动封面文件引用。", + "tags": [ + "祭祀" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "ceremonyId", + "in": "path", + "description": "要删除的祭祀活动ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/VoidResult", + "description": "通用成功响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/ceremonies/{ceremonyId}/gifts/{giftId}": { + "delete": { + "summary": "PC 删除单条祭品", + "deprecated": false, + "description": "", + "tags": [ + "祭祀" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "ceremonyId", + "in": "path", + "description": "祭祀活动ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "giftId", + "in": "path", + "description": "要删除的祭品ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/VoidResult", + "description": "通用成功响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/growth-records": { + "get": { + "summary": "PC 成长记录列表", + "deprecated": false, + "description": "", + "tags": [ + "族务记录" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/ListResult", + "description": "通用列表响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + }, + "post": { + "summary": "PC 新增成长记录", + "deprecated": false, + "description": "", + "tags": [ + "族务记录" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GrowthRecordBody" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/ObjectResult", + "description": "通用对象响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/growth-records/{recordId}": { + "get": { + "summary": "PC 成长记录详情", + "deprecated": false, + "description": "", + "tags": [ + "族务记录" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "recordId", + "in": "path", + "description": "成长记录ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/ObjectResult", + "description": "通用对象响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + }, + "put": { + "summary": "PC 修改成长记录", + "deprecated": false, + "description": "", + "tags": [ + "族务记录" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "recordId", + "in": "path", + "description": "成长记录ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GrowthRecordBody" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/ObjectResult", + "description": "通用对象响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + }, + "delete": { + "summary": "PC 删除成长记录", + "deprecated": false, + "description": "", + "tags": [ + "族务记录" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "recordId", + "in": "path", + "description": "要删除的成长记录ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/VoidResult", + "description": "通用成功响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/relative-records": { + "get": { + "summary": "PC 亲友记录列表", + "deprecated": false, + "description": "", + "tags": [ + "族务记录" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/ListResult", + "description": "通用列表响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + }, + "post": { + "summary": "PC 新增亲友记录", + "deprecated": false, + "description": "", + "tags": [ + "族务记录" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RelativeRecordBody" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/ObjectResult", + "description": "通用对象响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/relative-records/{relativeId}": { + "get": { + "summary": "PC 亲友记录详情", + "deprecated": false, + "description": "", + "tags": [ + "族务记录" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "relativeId", + "in": "path", + "description": "亲友记录ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/ObjectResult", + "description": "通用对象响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + }, + "put": { + "summary": "PC 修改亲友记录", + "deprecated": false, + "description": "", + "tags": [ + "族务记录" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "relativeId", + "in": "path", + "description": "亲友记录ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RelativeRecordBody" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/ObjectResult", + "description": "通用对象响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + }, + "delete": { + "summary": "PC 删除亲友记录", + "deprecated": false, + "description": "", + "tags": [ + "族务记录" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "relativeId", + "in": "path", + "description": "要删除的亲友记录ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/VoidResult", + "description": "通用成功响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/memos": { + "get": { + "summary": "PC 备忘录列表", + "deprecated": false, + "description": "", + "tags": [ + "族务记录" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/ListResult", + "description": "通用列表响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + }, + "post": { + "summary": "PC 新增备忘录", + "deprecated": false, + "description": "", + "tags": [ + "族务记录" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MemoBody" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/ObjectResult", + "description": "通用对象响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/memos/{memoId}": { + "get": { + "summary": "PC 备忘录详情", + "deprecated": false, + "description": "", + "tags": [ + "族务记录" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "memoId", + "in": "path", + "description": "备忘录ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/ObjectResult", + "description": "通用对象响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + }, + "put": { + "summary": "PC 修改备忘录", + "deprecated": false, + "description": "", + "tags": [ + "族务记录" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "memoId", + "in": "path", + "description": "备忘录ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MemoBody" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/ObjectResult", + "description": "通用对象响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + }, + "delete": { + "summary": "PC 删除备忘录", + "deprecated": false, + "description": "", + "tags": [ + "族务记录" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "memoId", + "in": "path", + "description": "要删除的备忘录ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/VoidResult", + "description": "通用成功响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/merit-records/{meritId}": { + "delete": { + "summary": "PC 删除功德记录", + "deprecated": false, + "description": "", + "tags": [ + "族务记录" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "meritId", + "in": "path", + "description": "要删除的功德记录ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/VoidResult", + "description": "通用成功响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + }, + "get": { + "summary": "PC 功德记录详情", + "deprecated": false, + "description": "", + "tags": [ + "族务记录" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "meritId", + "in": "path", + "description": "功德记录ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/ObjectResult", + "description": "通用对象响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + }, + "put": { + "summary": "PC 修改功德记录", + "deprecated": false, + "description": "", + "tags": [ + "族务记录" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "meritId", + "in": "path", + "description": "功德记录ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MeritRecordBody" + }, + "example": { + "donorName": "张三", + "meritType": "donation", + "meritTitle": "修缮祠堂捐赠", + "meritContent": "用于祠堂修缮", + "amount": 1000, + "meritTime": "2026-07-26 10:00:00", + "sortOrder": 1, + "status": "0" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/ObjectResult", + "description": "通用对象响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/genealogies/{genealogyId}/merit-records": { + "get": { + "summary": "PC 功德记录列表", + "deprecated": false, + "description": "", + "tags": [ + "族务记录" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/ListResult", + "description": "通用列表响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + }, + "post": { + "summary": "PC 新增功德记录", + "deprecated": false, + "description": "", + "tags": [ + "族务记录" + ], + "parameters": [ + { + "name": "genealogyId", + "in": "path", + "description": "家谱ID", + "required": true, + "example": 900001001, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MeritRecordBody" + }, + "example": { + "donorName": "张三", + "meritType": "donation", + "meritTitle": "修缮祠堂捐赠", + "meritContent": "用于祠堂修缮", + "amount": 1000, + "meritTime": "2026-07-26 10:00:00", + "sortOrder": 1, + "status": "0" + } + } + }, + "required": true + }, + "responses": { + "200": { + "$ref": "#/components/responses/ObjectResult", + "description": "通用对象响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/notifications": { + "get": { + "summary": "PC 消息通知列表", + "deprecated": false, + "description": "", + "tags": [ + "消息通知" + ], + "parameters": [ + { + "name": "readStatus", + "in": "query", + "description": "字典 gen_notification_read_status：0=未读，1=已读", + "required": false, + "schema": { + "type": "string", + "enum": [ + "0", + "1" + ], + "x-dict-type": "gen_notification_read_status", + "examples": [ + "0" + ] + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/ListResult", + "description": "通用列表响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/notifications/unread-count": { + "get": { + "summary": "PC 查询未读通知数量", + "deprecated": false, + "description": "", + "tags": [ + "消息通知" + ], + "parameters": [ + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/LongResult", + "description": "长整型数据响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/notifications/{notificationId}/read": { + "post": { + "summary": "PC 标记通知已读", + "deprecated": false, + "description": "", + "tags": [ + "消息通知" + ], + "parameters": [ + { + "name": "notificationId", + "in": "path", + "description": "通知ID", + "required": true, + "example": "", + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/VoidResult", + "description": "通用成功响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + }, + "/genealogy/pc/notifications/read-all": { + "post": { + "summary": "PC 全部标记已读", + "deprecated": false, + "description": "", + "tags": [ + "消息通知" + ], + "parameters": [ + { + "name": "clientid", + "in": "header", + "description": "PC 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 web_pc 并与 PC 路由一致。", + "required": true, + "example": "ced7e5f0498645c6ec642dcf450b036f", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/VoidResult", + "description": "通用成功响应" + } + }, + "security": [ + { + "SaToken1": [] + } + ] + } + } + }, + "webhooks": {}, + "components": { + "schemas": { + "CeremonyInviteesBody": { + "type": "object", + "required": [ + "inviteeUserIds" + ], + "properties": { + "inviteeUserIds": { + "description": "完整受邀业务用户ID列表；空数组表示取消全部尚未响应的邀请", + "type": "array", + "uniqueItems": true, + "items": { + "type": "integer", + "format": "int64" + } + } + }, + "examples": [ + { + "inviteeUserIds": [ + 900000001, + 900000002 + ] + } + ] + }, + "CeremonyInvitationResponseBody": { + "type": "object", + "required": [ + "inviteStatus" + ], + "properties": { + "inviteStatus": { + "description": "当前用户的邀约响应，只允许接受或拒绝", + "type": "string", + "enum": [ + "ACCEPTED", + "DECLINED" + ] + } + }, + "examples": [ + { + "inviteStatus": "ACCEPTED" + } + ] + }, + "GrowthRecordBody": { + "type": "object", + "required": [ + "recordTitle" + ], + "properties": { + "lineagePersonId": { + "description": "绑定的世系人物ID", + "type": "integer", + "format": "int64" + }, + "recordType": { + "description": "记录类型", + "type": "string" + }, + "recordTitle": { + "description": "记录标题", + "type": "string" + }, + "recordContent": { + "description": "记录内容", + "type": "string" + }, + "recordDate": { + "description": "记录日期", + "type": "string" + }, + "remindTime": { + "description": "提醒时间", + "type": "string" + }, + "mediaOssIds": { + "description": "多个正整数 OSS ID 使用英文逗号分隔", + "type": "string", + "pattern": "^$|^[1-9][0-9]*(,[1-9][0-9]*)*$" + }, + "sortOrder": { + "description": "排序值", + "type": "integer", + "format": "int64" + }, + "status": { + "description": "字典 sys_normal_disable：0=正常，1=停用", + "type": "string", + "enum": [ + "0", + "1" + ], + "x-dict-type": "sys_normal_disable", + "examples": [ + "0" + ] + } + } + }, + "RelativeRecordBody": { + "type": "object", + "required": [ + "relativeName" + ], + "properties": { + "relativeName": { + "description": "亲友姓名", + "type": "string" + }, + "relationName": { + "description": "关系名称", + "type": "string" + }, + "eventName": { + "description": "事件名称", + "type": "string" + }, + "eventTime": { + "description": "事件时间", + "type": "string" + }, + "giftAmount": { + "description": "礼金金额", + "type": "number" + }, + "recordContent": { + "description": "记录内容", + "type": "string" + }, + "mediaOssIds": { + "description": "多个正整数 OSS ID 使用英文逗号分隔", + "type": "string", + "pattern": "^$|^[1-9][0-9]*(,[1-9][0-9]*)*$" + }, + "sortOrder": { + "description": "排序值", + "type": "integer", + "format": "int64" + }, + "status": { + "description": "字典 sys_normal_disable：0=正常，1=停用", + "type": "string", + "enum": [ + "0", + "1" + ], + "x-dict-type": "sys_normal_disable", + "examples": [ + "0" + ] + } + } + }, + "MemoBody": { + "type": "object", + "required": [ + "memoTitle" + ], + "properties": { + "memoTitle": { + "description": "备忘标题", + "type": "string" + }, + "memoContent": { + "description": "备忘内容", + "type": "string" + }, + "remindTime": { + "description": "提醒时间", + "type": "string" + }, + "completed": { + "description": "是否已完成", + "type": "string" + }, + "mediaOssIds": { + "description": "多个正整数 OSS ID 使用英文逗号分隔", + "type": "string", + "pattern": "^$|^[1-9][0-9]*(,[1-9][0-9]*)*$" + }, + "sortOrder": { + "description": "排序值", + "type": "integer", + "format": "int64" + }, + "status": { + "description": "字典 sys_normal_disable：0=正常，1=停用", + "type": "string", + "enum": [ + "0", + "1" + ], + "x-dict-type": "sys_normal_disable", + "examples": [ + "0" + ] + } + } + }, + "RVoid": { + "type": "object", + "properties": { + "code": { + "description": "系统图形验证码或响应状态码", + "type": "integer", + "examples": [ + 200 + ] + }, + "msg": { + "description": "响应消息", + "type": "string", + "examples": [ + "操作成功" + ] + }, + "data": { + "description": "响应数据主体", + "type": "null" + } + } + }, + "PasswordRegisterBody": { + "type": "object", + "additionalProperties": false, + "required": [ + "grantType", + "tenantId", + "phone", + "password", + "smsCode" + ], + "properties": { + "grantType": { + "description": "授权类型，例如password、sms、wechat、apple", + "type": "string", + "examples": [ + "password" + ] + }, + "tenantId": { + "description": "租户ID，用于区分不同租户的数据和验证策略", + "type": "string", + "examples": [ + "000000" + ] + }, + "phone": { + "description": "手机号", + "type": "string", + "examples": [ + "13800000000" + ] + }, + "password": { + "type": "string", + "description": "32 位 MD5", + "examples": [ + "e10adc3949ba59abbe56e057f20f883e" + ] + }, + "nickName": { + "description": "用户昵称", + "type": "string" + }, + "registerSource": { + "description": "注册来源，例如APP、PC、H5、MINI_PROGRAM", + "type": "string" + }, + "smsCode": { + "description": "4 位短信验证码", + "type": "string", + "pattern": "^\\d{4}$", + "examples": [ + "1234" + ] + } + } + }, + "PasswordLoginBody": { + "description": "PC 用户密码登录请求；验证场景由后端按 PC_PASSWORD_LOGIN 路由的当前激活绑定解析，前端不得提交 sceneCode；validToken 是否需要由解析后场景的策略决定。", + "type": "object", + "additionalProperties": false, + "required": [ + "grantType", + "tenantId", + "phone", + "password" + ], + "properties": { + "grantType": { + "description": "授权类型，例如password、sms、wechat、apple", + "type": "string", + "examples": [ + "password" + ] + }, + "tenantId": { + "description": "租户ID，用于区分不同租户的数据和验证策略", + "type": "string", + "examples": [ + "000000" + ] + }, + "phone": { + "description": "登录手机号，也是行为验证票据绑定的验证主体。", + "type": "string", + "examples": [ + "13800000000" + ] + }, + "password": { + "type": "string", + "description": "32 位 MD5", + "examples": [ + "e10adc3949ba59abbe56e057f20f883e" + ] + }, + "validToken": { + "description": "验证中心通过后返回的一次性票据；后台验证策略关闭时可为空，开启时必须提交。", + "type": "string" + } + } + }, + "SmsLoginBody": { + "type": "object", + "additionalProperties": false, + "required": [ + "grantType", + "tenantId", + "phone", + "smsCode" + ], + "properties": { + "grantType": { + "description": "授权类型，例如password、sms、wechat、apple", + "type": "string", + "examples": [ + "sms" + ] + }, + "tenantId": { + "description": "租户ID，用于区分不同租户的数据和验证策略", + "type": "string", + "examples": [ + "000000" + ] + }, + "phone": { + "description": "手机号", + "type": "string", + "examples": [ + "13800000000" + ] + }, + "smsCode": { + "description": "4 位短信验证码", + "type": "string", + "pattern": "^\\d{4}$", + "examples": [ + "1234" + ] + } + } + }, + "SmsCodeBody": { + "type": "object", + "additionalProperties": false, + "required": [ + "grantType", + "tenantId", + "phone" + ], + "properties": { + "grantType": { + "description": "授权类型，例如password、sms、wechat、apple", + "type": "string", + "examples": [ + "sms" + ] + }, + "tenantId": { + "description": "租户ID，用于区分不同租户的数据和验证策略", + "type": "string", + "examples": [ + "000000" + ] + }, + "phone": { + "description": "手机号", + "type": "string", + "examples": [ + "13800000000" + ] + }, + "validToken": { + "description": "验证中心通过后返回的票据，仅用于发送短信验证码；后台验证策略关闭时可为空，开启时必填。", + "type": "string" + } + } + }, + "ProfileUpdateBody": { + "type": "object", + "additionalProperties": false, + "properties": { + "nickName": { + "description": "用户昵称", + "type": "string", + "maxLength": 30 + }, + "realName": { + "description": "真实姓名", + "type": "string", + "maxLength": 30 + }, + "avatar": { + "description": "头像文件OSS ID", + "type": "integer", + "format": "int64" + }, + "sex": { + "description": "字典 sys_user_sex：0=男，1=女，2=未知", + "type": "string", + "enum": [ + "0", + "1", + "2" + ], + "x-dict-type": "sys_user_sex", + "examples": [ + "2" + ] + }, + "birthday": { + "description": "生日，格式 yyyy-MM-dd", + "type": "string", + "format": "date" + }, + "email": { + "description": "邮箱", + "type": "string", + "format": "email", + "maxLength": 100 + } + } + }, + "PasswordChangeBody": { + "type": "object", + "required": [ + "oldPassword", + "newPassword" + ], + "properties": { + "oldPassword": { + "type": "string", + "description": "32 位 MD5" + }, + "newPassword": { + "type": "string", + "description": "32 位 MD5" + } + } + }, + "PasswordResetBody": { + "type": "object", + "additionalProperties": false, + "required": [ + "grantType", + "tenantId", + "phone", + "smsCode", + "newPassword" + ], + "properties": { + "grantType": { + "description": "授权类型", + "type": "string", + "examples": [ + "password" + ] + }, + "tenantId": { + "description": "租户ID，用于区分不同租户的数据和验证策略", + "type": "string", + "examples": [ + "000000" + ] + }, + "phone": { + "description": "手机号", + "type": "string" + }, + "smsCode": { + "description": "4 位短信验证码", + "type": "string", + "pattern": "^\\d{4}$", + "examples": [ + "1234" + ] + }, + "newPassword": { + "type": "string", + "description": "32 位 MD5" + } + } + }, + "PhoneChangeBody": { + "type": "object", + "additionalProperties": false, + "required": [ + "phone", + "smsCode" + ], + "properties": { + "phone": { + "description": "新手机号", + "type": "string" + }, + "smsCode": { + "description": "4 位短信验证码", + "type": "string", + "pattern": "^\\d{4}$", + "examples": [ + "1234" + ] + } + } + }, + "AccountDeactivateBody": { + "type": "object", + "additionalProperties": false, + "required": [ + "smsCode" + ], + "properties": { + "smsCode": { + "description": "4 位短信验证码", + "type": "string", + "pattern": "^\\d{4}$", + "examples": [ + "1234" + ] + } + } + }, + "ResumableInitBody": { + "type": "object", + "additionalProperties": false, + "required": [ + "uploadId", + "fileName", + "fileMd5", + "totalSize", + "totalChunks", + "chunkSize" + ], + "properties": { + "uploadId": { + "description": "客户端生成并在整个上传过程保持不变的上传任务ID", + "type": "string" + }, + "fileName": { + "description": "原始文件名", + "type": "string" + }, + "fileMd5": { + "description": "完整文件MD5，用于秒传和完整性校验", + "type": "string", + "pattern": "^[a-fA-F0-9]{32}$" + }, + "totalSize": { + "description": "完整文件大小，单位字节", + "type": "integer", + "format": "int64", + "minimum": 1 + }, + "totalChunks": { + "description": "总分片数", + "type": "integer", + "minimum": 1 + }, + "chunkSize": { + "description": "单个分片大小，单位字节；除最后一片外每片必须严格等于该值", + "type": "integer", + "format": "int64", + "minimum": 1, + "examples": [ + 4194304 + ] + }, + "contentType": { + "description": "文件MIME类型，例如 image/jpeg、video/mp4", + "type": "string" + } + } + }, + "ResumableCompleteBody": { + "type": "object", + "additionalProperties": false, + "required": [ + "uploadId", + "fileName", + "fileMd5", + "totalSize", + "totalChunks" + ], + "properties": { + "uploadId": { + "description": "分片上传任务ID", + "type": "string" + }, + "fileName": { + "description": "原始文件名，必须与初始化请求一致", + "type": "string" + }, + "fileMd5": { + "description": "完整文件MD5，用于秒传和完整性校验", + "type": "string", + "pattern": "^[a-fA-F0-9]{32}$" + }, + "totalSize": { + "description": "完整文件大小，单位字节", + "type": "integer", + "format": "int64", + "minimum": 1 + }, + "totalChunks": { + "description": "总分片数，必须与初始化请求一致", + "type": "integer", + "minimum": 1 + } + } + }, + "GenerationPoemBatchBody": { + "type": "object", + "required": [ + "poemText" + ], + "properties": { + "poemText": { + "description": "字辈文本。无分隔符时按单个字拆分；可用空格、逗号、分号、顿号、斜杠或竖线分隔多个字辈。单个字辈最多50个字符，一次最多500个世代。", + "type": "string", + "maxLength": 26000, + "examples": [ + "德承家亦\n忠厚传芳" + ] + }, + "disableMissing": { + "description": "保存时是否停用未出现在新文本中的后续世代；不会删除历史记录。", + "type": "boolean", + "examples": [ + false + ] + } + } + }, + "GenerationPoemBody": { + "type": "object", + "required": [ + "generationNo", + "generationText" + ], + "properties": { + "generationNo": { + "description": "世代序号", + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 2147483647 + }, + "generationText": { + "description": "当前世代的字辈文字，最长50个字符", + "type": "string", + "maxLength": 50 + }, + "description": { + "description": "字辈说明，最长500个字符", + "type": "string", + "maxLength": 500 + }, + "sortOrder": { + "description": "排序值，数值越小越靠前", + "type": "integer", + "format": "int64", + "minimum": -2147483648, + "maximum": 2147483647 + }, + "status": { + "description": "字典 sys_normal_disable：0=正常，1=停用", + "type": "string", + "enum": [ + "0", + "1" + ], + "x-dict-type": "sys_normal_disable", + "examples": [ + "0" + ] + } + } + }, + "LineagePersonBody": { + "type": "object", + "additionalProperties": false, + "required": [ + "bindingMode", + "name" + ], + "properties": { + "bindingMode": { + "description": "账号绑定方式：NONE=不绑定账号；SELF=绑定当前登录业务用户；SPECIFIED=由有管理权限的操作者指定 appUserId", + "type": "string", + "enum": [ + "NONE", + "SELF", + "SPECIFIED" + ], + "examples": [ + "NONE" + ] + }, + "appUserId": { + "description": "仅 bindingMode=SPECIFIED 时必填；NONE/SELF 时必须不传。指定用户必须属于当前租户、状态正常，且未绑定当前家谱的其他有效世系人物", + "type": "integer", + "format": "int64" + }, + "personNo": { + "description": "人物编号；不传时由服务端生成", + "type": "string" + }, + "name": { + "description": "姓名", + "type": "string" + }, + "aliasName": { + "description": "别名或曾用名", + "type": "string" + }, + "sex": { + "description": "字典 sys_user_sex：0=男，1=女，2=未知", + "type": "string", + "enum": [ + "0", + "1", + "2" + ], + "x-dict-type": "sys_user_sex", + "examples": [ + "0" + ] + }, + "generation": { + "description": "世代序号", + "type": "integer", + "format": "int64" + }, + "generationName": { + "description": "字辈或辈分", + "type": "string" + }, + "fatherId": { + "description": "父亲人物ID，必须属于当前家谱", + "type": "integer", + "format": "int64" + }, + "motherId": { + "description": "母亲人物ID，必须属于当前家谱", + "type": "integer", + "format": "int64" + }, + "avatarOssId": { + "description": "头像文件OSS ID；用户界面应通过统一上传组件获得，不允许手工录入", + "type": [ + "string", + "null" + ], + "pattern": "^[1-9][0-9]*$" + }, + "birthDate": { + "type": [ + "string", + "null" + ], + "format": "date-time" + }, + "birthLunar": { + "description": "字典 gen_number_yes_no：0=否，1=是", + "type": "string", + "enum": [ + "0", + "1" + ], + "x-dict-type": "gen_number_yes_no", + "examples": [ + "0" + ] + }, + "birthPlace": { + "description": "出生地", + "type": "string" + }, + "deathDate": { + "type": [ + "string", + "null" + ], + "format": "date-time" + }, + "deathLunar": { + "description": "字典 gen_number_yes_no：0=否，1=是", + "type": "string", + "enum": [ + "0", + "1" + ], + "x-dict-type": "gen_number_yes_no", + "examples": [ + "0" + ] + }, + "deathPlace": { + "description": "逝世地", + "type": "string" + }, + "burialPlace": { + "description": "安葬地", + "type": "string" + }, + "personStatus": { + "description": "字典 gen_lineage_person_status：0=健在，1=已故，2=未知", + "type": "string", + "enum": [ + "0", + "1", + "2" + ], + "x-dict-type": "gen_lineage_person_status", + "examples": [ + "0" + ] + }, + "biography": { + "description": "人物简介", + "type": "string" + }, + "sortOrder": { + "description": "排序值，数值越小越靠前", + "type": "integer", + "format": "int64" + }, + "remark": { + "description": "备注", + "type": "string" + }, + "relationName": { + "description": "通过添加配偶快捷接口提交时使用的关系显示名称", + "type": "string" + } + } + }, + "FamilyFeedBody": { + "type": "object", + "required": [ + "feedContent" + ], + "properties": { + "feedType": { + "description": "动态类型，未传时默认为 text", + "type": "string", + "examples": [ + "text" + ] + }, + "feedContent": { + "description": "动态内容，不能为空", + "type": "string", + "examples": [ + "今天上传一张老照片。" + ] + }, + "mediaOssIds": { + "description": "媒体文件 OSS ID 列表，多个 ID 使用英文逗号分隔", + "type": "string", + "examples": [ + "2060000000000000001,2060000000000000002" + ] + }, + "sortOrder": { + "description": "排序值，未传时默认为 0", + "type": "integer", + "format": "int64", + "examples": [ + 0 + ] + }, + "status": { + "description": "字典 sys_normal_disable：0=正常，1=停用；未传时默认为0", + "type": "string", + "enum": [ + "0", + "1" + ], + "x-dict-type": "sys_normal_disable", + "examples": [ + "0" + ] + } + } + }, + "FamilyFeedCommentBody": { + "type": "object", + "required": [ + "commentContent" + ], + "properties": { + "parentCommentId": { + "description": "父评论 ID；不传或传 null 表示发布一级评论", + "type": [ + "integer", + "null" + ], + "format": "int64" + }, + "commentContent": { + "description": "评论内容，最多 1000 个字符", + "type": "string" + } + } + }, + "VerificationChallengeBody": { + "type": "object", + "additionalProperties": false, + "required": [ + "tenantId", + "subject" + ], + "properties": { + "tenantId": { + "type": "string", + "description": "租户 ID" + }, + "subject": { + "type": "string", + "description": "验证主体，如手机号/用户名/IP" + } + }, + "examples": [ + { + "tenantId": "000000", + "subject": "13800000000" + } + ] + }, + "VerificationCheckBody": { + "type": "object", + "additionalProperties": false, + "required": [ + "tenantId", + "subject", + "challengeId" + ], + "properties": { + "tenantId": { + "description": "租户ID，用于区分不同租户的数据和验证策略", + "type": "string" + }, + "subject": { + "description": "验证主体，通常为手机号、用户ID或登录账号", + "type": "string" + }, + "challengeId": { + "description": "验证挑战ID，由验证挑战接口返回", + "type": "string" + }, + "providerCode": { + "type": "string", + "description": "验证服务，tianai 或 ruoyi_image" + }, + "captchaType": { + "type": "string", + "description": "SLIDER/ROTATE/CONCAT/WORD_IMAGE_CLICK/math/char" + }, + "payload": { + "description": "验证结果载荷。天爱行为验证码提交 payload.track；系统图形验证码提交 payload.uuid 和 payload.code", + "oneOf": [ + { + "$ref": "#/components/schemas/TianaiVerificationPayload" + }, + { + "$ref": "#/components/schemas/SystemImageVerificationPayload" + } + ] + } + } + }, + "TianaiVerificationPayload": { + "type": "object", + "description": "将天爱 1.5.5 前端验证回调中的 data 原样放入 track；回调 id 不放入 payload，挑战标识统一提交顶层 challengeId", + "required": [ + "track" + ], + "properties": { + "track": { + "$ref": "#/components/schemas/TianaiCaptchaTrack" + } + } + }, + "TianaiCaptchaTrack": { + "type": "object", + "required": [ + "bgImageWidth", + "bgImageHeight", + "startTime", + "stopTime", + "trackList" + ], + "properties": { + "bgImageWidth": { + "type": "integer", + "description": "验证码背景图片在前端实际显示的宽度，单位像素" + }, + "bgImageHeight": { + "type": "integer", + "description": "验证码背景图片在前端实际显示的高度，单位像素" + }, + "templateImageWidth": { + "type": "integer", + "description": "滑块或旋转模板图片在前端实际显示的宽度，单位像素" + }, + "templateImageHeight": { + "type": "integer", + "description": "滑块或旋转模板图片在前端实际显示的高度，单位像素" + }, + "startTime": { + "type": "integer", + "format": "int64", + "description": "用户开始操作的时间戳，单位毫秒" + }, + "stopTime": { + "type": "integer", + "format": "int64", + "description": "用户结束操作的时间戳，单位毫秒" + }, + "left": { + "type": "integer", + "description": "滑块最终水平偏移量，单位像素；由天爱前端控件生成" + }, + "top": { + "type": "integer", + "description": "点选或模板最终垂直偏移量，单位像素；由天爱前端控件生成" + }, + "trackList": { + "type": "array", + "minItems": 1, + "description": "用户操作轨迹，不能为空，必须直接使用天爱前端控件产生的数据", + "items": { + "$ref": "#/components/schemas/TianaiCaptchaTrackPoint" + } + }, + "data": { + "type": [ + "object", + "null" + ], + "additionalProperties": true, + "description": "不同验证码类型附带的扩展数据，由天爱前端控件原样提交", + "properties": {} + } + } + }, + "TianaiCaptchaTrackPoint": { + "type": "object", + "required": [ + "x", + "y", + "t", + "type" + ], + "properties": { + "x": { + "type": "number", + "format": "float", + "description": "当前轨迹点的水平坐标" + }, + "y": { + "type": "number", + "format": "float", + "description": "当前轨迹点的垂直坐标" + }, + "t": { + "type": "number", + "format": "float", + "description": "当前轨迹点相对操作开始时的时间，单位毫秒" + }, + "type": { + "type": "string", + "description": "轨迹事件类型，例如 down、move、up" + } + } + }, + "SystemImageVerificationPayload": { + "type": "object", + "required": [ + "uuid", + "code" + ], + "properties": { + "uuid": { + "type": "string", + "description": "系统图形验证码接口返回的唯一标识" + }, + "code": { + "type": "string", + "description": "用户填写的图形验证码答案" + } + } + }, + "MeritRecordBody": { + "type": "object", + "additionalProperties": false, + "required": [ + "donorName", + "meritTitle" + ], + "properties": { + "donorName": { + "description": "功德人姓名", + "type": "string" + }, + "meritType": { + "description": "字典 gen_merit_type：donation=捐赠，repair=修祠，public=公益，other=其他", + "type": "string", + "enum": [ + "donation", + "repair", + "public", + "other" + ], + "x-dict-type": "gen_merit_type", + "examples": [ + "donation" + ] + }, + "meritTitle": { + "description": "功德标题", + "type": "string" + }, + "meritContent": { + "description": "功德内容", + "type": "string" + }, + "amount": { + "description": "金额", + "type": "number" + }, + "meritTime": { + "description": "功德时间", + "type": "string", + "format": "date-time" + }, + "sortOrder": { + "description": "排序值", + "type": "integer", + "format": "int64" + }, + "status": { + "description": "字典 sys_normal_disable：0=正常，1=停用", + "type": "string", + "enum": [ + "0", + "1" + ], + "x-dict-type": "sys_normal_disable", + "examples": [ + "0" + ] + } + } + }, + "VideoBody": { + "type": "object", + "additionalProperties": false, + "required": [ + "videoTitle", + "videoOssId" + ], + "properties": { + "videoTitle": { + "description": "视频标题", + "type": "string" + }, + "videoDesc": { + "description": "视频说明", + "type": "string" + }, + "coverOssId": { + "description": "封面图片OSS ID，由统一上传接口返回", + "type": "string", + "pattern": "^[1-9][0-9]*$" + }, + "videoOssId": { + "description": "视频文件OSS ID，由统一上传接口返回", + "type": "string", + "pattern": "^[1-9][0-9]*$" + }, + "durationSeconds": { + "description": "视频时长，单位秒", + "type": "integer", + "format": "int64" + }, + "sortOrder": { + "description": "排序值", + "type": "integer", + "format": "int64" + }, + "status": { + "description": "字典 sys_normal_disable：0=正常，1=停用", + "type": "string", + "enum": [ + "0", + "1" + ], + "x-dict-type": "sys_normal_disable", + "examples": [ + "0" + ] + } + } + }, + "RObject": { + "type": "object", + "properties": { + "code": { + "description": "系统图形验证码或响应状态码", + "type": "integer", + "examples": [ + 200 + ] + }, + "msg": { + "description": "响应消息", + "type": "string", + "examples": [ + "操作成功" + ] + }, + "data": { + "description": "响应数据主体", + "type": "object", + "additionalProperties": true, + "properties": {} + } + } + }, + "RGenealogyQuota": { + "type": "object", + "properties": { + "code": { + "description": "响应状态码", + "type": "integer", + "examples": [ + 200 + ] + }, + "msg": { + "description": "响应消息", + "type": "string", + "examples": [ + "操作成功" + ] + }, + "data": { + "$ref": "#/components/schemas/GenealogyQuota" + } + } + }, + "GenealogyQuota": { + "type": "object", + "required": [ + "createUsed", + "createLimit", + "createRemaining", + "canCreate", + "joinUsed", + "joinLimit", + "joinRemaining", + "canJoin" + ], + "properties": { + "createUsed": { + "description": "当前用户已创建的家谱数量", + "type": "integer", + "format": "int64", + "minimum": 0, + "examples": [ + 1 + ] + }, + "createLimit": { + "description": "每用户可创建家谱上限，-1 表示不限，0 表示禁止，正数表示上限", + "type": "integer", + "format": "int64", + "minimum": -1, + "examples": [ + 3 + ] + }, + "createRemaining": { + "description": "还可创建的家谱数量，-1 表示不限", + "type": "integer", + "format": "int64", + "minimum": -1, + "examples": [ + 2 + ] + }, + "canCreate": { + "description": "当前用户是否还能创建家谱", + "type": "boolean", + "examples": [ + true + ] + }, + "joinUsed": { + "description": "已加入的家谱总数，包含自己创建的家谱", + "type": "integer", + "format": "int64", + "minimum": 0, + "examples": [ + 2 + ] + }, + "joinLimit": { + "description": "每用户可加入家谱总数上限，-1 表示不限，0 表示禁止，正数表示上限", + "type": "integer", + "format": "int64", + "minimum": -1, + "examples": [ + 10 + ] + }, + "joinRemaining": { + "description": "还可加入的家谱数量，-1 表示不限", + "type": "integer", + "format": "int64", + "minimum": -1, + "examples": [ + 8 + ] + }, + "canJoin": { + "description": "当前用户是否还能加入其他家谱", + "type": "boolean", + "examples": [ + true + ] + } + } + }, + "RLong": { + "type": "object", + "properties": { + "code": { + "description": "响应状态码", + "type": "integer", + "examples": [ + 200 + ] + }, + "msg": { + "description": "响应消息", + "type": "string", + "examples": [ + "操作成功" + ] + }, + "data": { + "description": "当前业务用户未读通知数量", + "type": "integer", + "format": "int64", + "examples": [ + 3 + ] + } + } + }, + "RList": { + "type": "object", + "properties": { + "code": { + "description": "系统图形验证码或响应状态码", + "type": "integer", + "examples": [ + 200 + ] + }, + "msg": { + "description": "响应消息", + "type": "string", + "examples": [ + "操作成功" + ] + }, + "data": { + "description": "响应数据主体", + "type": "array", + "items": { + "type": "object", + "additionalProperties": true, + "properties": {} + } + } + } + }, + "RCeremonyInvitation": { + "type": "object", + "properties": { + "code": { + "description": "响应状态码", + "type": "integer", + "examples": [ + 200 + ] + }, + "msg": { + "description": "响应消息", + "type": "string", + "examples": [ + "操作成功" + ] + }, + "data": { + "$ref": "#/components/schemas/CeremonyInvitationVo" + } + } + }, + "CeremonyInvitationVo": { + "type": "object", + "properties": { + "invitationId": { + "description": "邀约ID", + "type": "integer", + "format": "int64" + }, + "genealogyId": { + "description": "家谱ID", + "type": "integer", + "format": "int64" + }, + "ceremonyId": { + "description": "贺礼活动ID", + "type": "integer", + "format": "int64" + }, + "inviteeUserId": { + "description": "受邀业务用户ID", + "type": "integer", + "format": "int64" + }, + "inviteStatus": { + "description": "邀约状态", + "type": "string", + "enum": [ + "PENDING", + "ACCEPTED", + "DECLINED", + "CANCELED" + ] + }, + "inviteVersion": { + "description": "邀请版本，取消后重新邀请时递增", + "type": "integer" + }, + "deliveredTime": { + "description": "邀请投递时间", + "type": "string", + "format": "date-time" + }, + "readTime": { + "description": "邀请阅读时间", + "type": "string", + "format": "date-time" + }, + "responseTime": { + "description": "接受或拒绝时间", + "type": "string", + "format": "date-time" + }, + "ceremonyTitle": { + "description": "贺礼活动标题", + "type": "string" + }, + "ceremonyTime": { + "description": "贺礼活动时间", + "type": "string", + "format": "date-time" + }, + "location": { + "description": "地点名称", + "type": "string" + }, + "locationAddress": { + "description": "详细地址", + "type": "string" + }, + "longitude": { + "description": "经度", + "type": "number" + }, + "latitude": { + "description": "纬度", + "type": "number" + } + } + }, + "RCeremonyInvitationList": { + "type": "object", + "properties": { + "code": { + "description": "响应状态码", + "type": "integer", + "examples": [ + 200 + ] + }, + "msg": { + "description": "响应消息", + "type": "string", + "examples": [ + "操作成功" + ] + }, + "data": { + "description": "贺礼邀约列表", + "type": "array", + "items": { + "$ref": "#/components/schemas/CeremonyInvitationVo" + } + } + } + }, + "RGenerationPoem": { + "type": "object", + "properties": { + "code": { + "description": "响应状态码", + "type": "integer", + "examples": [ + 200 + ] + }, + "msg": { + "description": "响应消息", + "type": "string" + }, + "data": { + "$ref": "#/components/schemas/GenerationPoemView" + } + } + }, + "GenerationPoemView": { + "type": "object", + "properties": { + "poemId": { + "description": "字辈记录ID", + "type": "integer", + "format": "int64" + }, + "genealogyId": { + "description": "所属家谱ID", + "type": "integer", + "format": "int64" + }, + "genealogyNo": { + "description": "家谱编号", + "type": "string" + }, + "genealogyName": { + "description": "家谱名称", + "type": "string" + }, + "generationNo": { + "description": "世代序号", + "type": "integer", + "format": "int64" + }, + "generationText": { + "description": "字辈文字", + "type": "string" + }, + "description": { + "description": "字辈说明", + "type": "string" + }, + "sortOrder": { + "description": "排序值，数值越小越靠前", + "type": "integer", + "format": "int64" + }, + "status": { + "description": "字典 sys_normal_disable：0=正常，1=停用", + "type": "string", + "enum": [ + "0", + "1" + ], + "x-dict-type": "sys_normal_disable", + "examples": [ + "0" + ] + } + } + }, + "RGenerationPoemList": { + "type": "object", + "properties": { + "code": { + "description": "响应状态码", + "type": "integer", + "examples": [ + 200 + ] + }, + "msg": { + "description": "响应消息", + "type": "string" + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/GenerationPoemView" + } + } + } + }, + "RGenerationPoemBatchPreview": { + "type": "object", + "properties": { + "code": { + "description": "响应状态码", + "type": "integer", + "examples": [ + 200 + ] + }, + "msg": { + "description": "响应消息", + "type": "string" + }, + "data": { + "$ref": "#/components/schemas/GenerationPoemBatchPreviewView" + } + } + }, + "GenerationPoemBatchPreviewView": { + "type": "object", + "properties": { + "genealogyId": { + "description": "所属家谱ID", + "type": "integer", + "format": "int64" + }, + "genealogyNo": { + "description": "家谱编号", + "type": "string" + }, + "genealogyName": { + "description": "家谱名称", + "type": "string" + }, + "createCount": { + "description": "将新增的字辈数量", + "type": "integer" + }, + "updateCount": { + "description": "将修改或恢复的字辈数量", + "type": "integer" + }, + "keepCount": { + "description": "保持不变的字辈数量", + "type": "integer" + }, + "disableCount": { + "description": "将停用的字辈数量", + "type": "integer" + }, + "items": { + "description": "按世代排序的逐项变更预览", + "type": "array", + "items": { + "$ref": "#/components/schemas/GenerationPoemBatchItemView" + } + } + } + }, + "GenerationPoemBatchItemView": { + "type": "object", + "properties": { + "poemId": { + "description": "现有字辈记录ID；新增时为空", + "type": "integer", + "format": "int64" + }, + "generationNo": { + "description": "世代序号", + "type": "integer", + "format": "int64" + }, + "oldGenerationText": { + "description": "保存前字辈文字", + "type": "string" + }, + "newGenerationText": { + "description": "保存后字辈文字", + "type": "string" + }, + "oldStatus": { + "description": "保存前状态", + "type": "string" + }, + "newStatus": { + "description": "保存后状态", + "type": "string" + }, + "action": { + "description": "预览动作，create、update、keep 或 disable", + "type": "string" + }, + "warning": { + "description": "需要用户确认的变更提示", + "type": "string" + } + } + }, + "RLineagePerson": { + "type": "object", + "properties": { + "code": { + "description": "响应状态码", + "type": "integer", + "examples": [ + 200 + ] + }, + "msg": { + "description": "响应消息", + "type": "string", + "examples": [ + "操作成功" + ] + }, + "data": { + "$ref": "#/components/schemas/LineagePersonView" + } + } + }, + "LineagePersonView": { + "type": "object", + "properties": { + "personId": { + "description": "人物ID", + "type": "integer", + "format": "int64" + }, + "genealogyId": { + "description": "家谱ID", + "type": "integer", + "format": "int64" + }, + "genealogyName": { + "description": "家谱名称", + "type": "string" + }, + "genealogyNo": { + "description": "家谱编号", + "type": "string" + }, + "appUserId": { + "description": "绑定业务用户ID", + "type": [ + "integer", + "null" + ], + "format": "int64" + }, + "appUserNickName": { + "description": "绑定业务用户昵称", + "type": "string" + }, + "personNo": { + "description": "人物编号", + "type": "string" + }, + "name": { + "description": "姓名", + "type": "string" + }, + "aliasName": { + "description": "别名或曾用名", + "type": "string" + }, + "sex": { + "description": "字典 sys_user_sex：0=男，1=女，2=未知", + "type": "string", + "enum": [ + "0", + "1", + "2" + ], + "x-dict-type": "sys_user_sex", + "examples": [ + "2" + ] + }, + "generation": { + "description": "世代序号", + "type": "integer", + "format": "int64" + }, + "generationName": { + "description": "字辈或辈分", + "type": "string" + }, + "fatherId": { + "description": "父亲人物ID", + "type": [ + "integer", + "null" + ], + "format": "int64" + }, + "fatherName": { + "description": "父亲姓名", + "type": "string" + }, + "motherId": { + "description": "母亲人物ID", + "type": [ + "integer", + "null" + ], + "format": "int64" + }, + "motherName": { + "description": "母亲姓名", + "type": "string" + }, + "spouseNames": { + "description": "配偶姓名，多个使用顿号分隔", + "type": "string" + }, + "avatarOssId": { + "description": "头像文件OSS ID", + "type": [ + "string", + "null" + ], + "pattern": "^[1-9][0-9]*$" + }, + "birthDate": { + "description": "出生日期", + "type": [ + "string", + "null" + ], + "format": "date-time" + }, + "birthLunar": { + "description": "字典 gen_number_yes_no：0=否，1=是", + "type": "string", + "enum": [ + "0", + "1" + ], + "x-dict-type": "gen_number_yes_no", + "examples": [ + "0" + ] + }, + "birthPlace": { + "description": "出生地", + "type": "string" + }, + "deathDate": { + "description": "逝世日期", + "type": [ + "string", + "null" + ], + "format": "date-time" + }, + "deathLunar": { + "description": "字典 gen_number_yes_no：0=否，1=是", + "type": "string", + "enum": [ + "0", + "1" + ], + "x-dict-type": "gen_number_yes_no", + "examples": [ + "0" + ] + }, + "deathPlace": { + "description": "逝世地", + "type": "string" + }, + "burialPlace": { + "description": "安葬地", + "type": "string" + }, + "personStatus": { + "description": "字典 gen_lineage_person_status：0=健在，1=已故，2=未知", + "type": "string", + "enum": [ + "0", + "1", + "2" + ], + "x-dict-type": "gen_lineage_person_status", + "examples": [ + "0" + ] + }, + "biography": { + "description": "人物简介", + "type": "string" + }, + "sortOrder": { + "description": "排序值", + "type": "integer", + "format": "int64" + }, + "status": { + "description": "字典 sys_normal_disable：0=正常，1=停用", + "type": "string", + "enum": [ + "0", + "1" + ], + "x-dict-type": "sys_normal_disable", + "examples": [ + "0" + ] + }, + "remark": { + "description": "备注", + "type": "string" + } + } + }, + "RLineagePersonList": { + "type": "object", + "properties": { + "code": { + "description": "响应状态码", + "type": "integer", + "examples": [ + 200 + ] + }, + "msg": { + "description": "响应消息", + "type": "string", + "examples": [ + "操作成功" + ] + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/LineagePersonView" + } + } + } + }, + "RLineagePersonTreeList": { + "type": "object", + "properties": { + "code": { + "description": "响应状态码", + "type": "integer", + "examples": [ + 200 + ] + }, + "msg": { + "description": "响应消息", + "type": "string", + "examples": [ + "操作成功" + ] + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/LineagePersonTreeView" + } + } + } + }, + "LineagePersonTreeView": { + "allOf": [ + { + "$ref": "#/components/schemas/LineagePersonView" + }, + { + "type": "object", + "properties": { + "relationType": { + "description": "字典 gen_lineage_relation_type：father=父亲，mother=母亲，spouse=配偶，child=子女，adoptive=收养", + "type": "string", + "enum": [ + "father", + "mother", + "spouse", + "child", + "adoptive" + ], + "x-dict-type": "gen_lineage_relation_type", + "examples": [ + "spouse" + ] + }, + "relationName": { + "description": "关系显示名称", + "type": "string" + }, + "spouses": { + "description": "配偶节点", + "type": "array", + "items": { + "$ref": "#/components/schemas/LineagePersonTreeView" + } + }, + "children": { + "description": "子女节点", + "type": "array", + "items": { + "$ref": "#/components/schemas/LineagePersonTreeView" + } + } + } + } + ] + }, + "LineagePersonPageResult": { + "type": "object", + "properties": { + "code": { + "description": "响应状态码", + "type": "integer", + "examples": [ + 200 + ] + }, + "msg": { + "description": "响应消息", + "type": "string", + "examples": [ + "操作成功" + ] + }, + "rows": { + "description": "当前页世系人物", + "type": "array", + "items": { + "$ref": "#/components/schemas/LineagePersonView" + } + }, + "total": { + "description": "总记录数", + "type": "integer", + "format": "int64", + "examples": [ + 0 + ] + } + } + }, + "RLogin": { + "type": "object", + "properties": { + "code": { + "description": "系统图形验证码或响应状态码", + "type": "integer", + "examples": [ + 200 + ] + }, + "msg": { + "description": "响应消息", + "type": "string", + "examples": [ + "操作成功" + ] + }, + "data": { + "description": "响应数据主体", + "$ref": "#/components/schemas/LoginVo" + } + } + }, + "LoginVo": { + "type": "object", + "properties": { + "token": { + "type": "string" + }, + "accessToken": { + "type": "string" + }, + "tokenValue": { + "type": "string" + }, + "userId": { + "type": "integer", + "format": "int64" + }, + "tenantId": { + "description": "租户ID，用于区分不同租户的数据和验证策略", + "type": "string" + }, + "clientId": { + "description": "客户端ID，对应后台客户端管理中的APP/PC/小程序等终端", + "type": "string" + }, + "clientKey": { + "type": "string" + } + } + }, + "RFileUpload": { + "type": "object", + "properties": { + "code": { + "description": "系统图形验证码或响应状态码", + "type": "integer", + "examples": [ + 200 + ] + }, + "msg": { + "description": "响应消息", + "type": "string", + "examples": [ + "操作成功" + ] + }, + "data": { + "description": "响应数据主体", + "$ref": "#/components/schemas/FileUploadVo" + } + } + }, + "FileUploadVo": { + "type": "object", + "properties": { + "ossId": { + "description": "OSS文件ID，表单内部使用，用户侧应通过上传组件获取", + "type": "string", + "pattern": "^[1-9][0-9]*$" + }, + "url": { + "type": "string" + }, + "thumbnailUrl": { + "type": [ + "string", + "null" + ] + }, + "fileName": { + "description": "原始文件名", + "type": "string" + }, + "originalName": { + "type": "string" + } + } + }, + "RVerificationRequire": { + "type": "object", + "properties": { + "code": { + "description": "系统图形验证码或响应状态码", + "type": "integer", + "examples": [ + 200 + ] + }, + "msg": { + "description": "响应消息", + "type": "string", + "examples": [ + "操作成功" + ] + }, + "data": { + "description": "响应数据主体", + "$ref": "#/components/schemas/VerificationRequireVo" + } + } + }, + "VerificationRequireVo": { + "type": "object", + "properties": { + "required": { + "description": "当前场景是否需要验证", + "type": "boolean" + }, + "providerCode": { + "description": "第三方服务商编码", + "type": "string" + }, + "captchaType": { + "description": "验证码类型，例如SLIDER、ROTATE、CONCAT、WORD_IMAGE_CLICK", + "type": "string" + }, + "sceneCode": { + "description": "服务端按当前业务动作和激活绑定解析出的实际验证场景编码", + "type": "string" + }, + "ttlSeconds": { + "description": "验证或票据有效秒数", + "type": "integer" + } + }, + "examples": [ + { + "required": true, + "providerCode": "tianai", + "captchaType": "SLIDER", + "sceneCode": "PC_LOGIN_ACTIVE_SCENE", + "ttlSeconds": 300 + } + ] + }, + "RVerificationChallenge": { + "type": "object", + "properties": { + "code": { + "description": "系统图形验证码或响应状态码", + "type": "integer", + "examples": [ + 200 + ] + }, + "msg": { + "description": "响应消息", + "type": "string", + "examples": [ + "操作成功" + ] + }, + "data": { + "description": "响应数据主体", + "$ref": "#/components/schemas/VerificationChallengeVo" + } + } + }, + "VerificationChallengeVo": { + "type": "object", + "properties": { + "required": { + "description": "当前场景是否需要验证", + "type": "boolean" + }, + "providerCode": { + "description": "第三方服务商编码", + "type": "string" + }, + "captchaType": { + "description": "验证码类型，例如SLIDER、ROTATE、CONCAT、WORD_IMAGE_CLICK", + "type": "string" + }, + "challengeId": { + "description": "验证挑战ID，由验证挑战接口返回", + "type": "string" + }, + "uuid": { + "type": "string", + "description": "系统图形验证码 uuid" + }, + "img": { + "type": "string", + "description": "系统图形验证码 base64 图片" + }, + "payload": { + "type": "object", + "additionalProperties": true, + "description": "天爱验证码数据，包括背景图、模板图、尺寸等", + "properties": {} + }, + "expireSeconds": { + "description": "验证挑战过期秒数", + "type": "integer" + } + }, + "examples": [ + { + "required": true, + "providerCode": "tianai", + "captchaType": "SLIDER", + "challengeId": "CAPTCHA_CHALLENGE_ID", + "payload": { + "backgroundImage": "data:image/png;base64,...", + "templateImage": "data:image/png;base64,...", + "backgroundImageWidth": 340, + "backgroundImageHeight": 180 + }, + "expireSeconds": 300 + } + ] + }, + "RVerificationCheck": { + "type": "object", + "properties": { + "code": { + "description": "系统图形验证码或响应状态码", + "type": "integer", + "examples": [ + 200 + ] + }, + "msg": { + "description": "响应消息", + "type": "string", + "examples": [ + "操作成功" + ] + }, + "data": { + "description": "响应数据主体", + "$ref": "#/components/schemas/VerificationCheckVo" + } + } + }, + "VerificationCheckVo": { + "type": "object", + "properties": { + "passed": { + "description": "验证是否通过", + "type": "boolean" + }, + "validToken": { + "type": "string", + "description": "验证通过后交给发送短信验证码接口的票据" + }, + "expireSeconds": { + "description": "验证挑战过期秒数", + "type": "integer" + }, + "message": { + "description": "返回消息", + "type": "string" + } + }, + "examples": [ + { + "passed": true, + "validToken": "captcha-ticket", + "expireSeconds": 300, + "message": "验证通过" + } + ] + }, + "RFamilyFeedComment": { + "type": "object", + "properties": { + "code": { + "description": "响应状态码", + "type": "integer", + "examples": [ + 200 + ] + }, + "msg": { + "description": "响应消息", + "type": "string" + }, + "data": { + "$ref": "#/components/schemas/FamilyFeedCommentView" + } + } + }, + "FamilyFeedCommentView": { + "type": "object", + "properties": { + "commentId": { + "description": "评论 ID", + "type": "integer", + "format": "int64" + }, + "genealogyId": { + "description": "所属家谱 ID", + "type": "integer", + "format": "int64" + }, + "feedId": { + "description": "所属动态 ID", + "type": "integer", + "format": "int64" + }, + "parentCommentId": { + "description": "父评论 ID；null 或 0 表示一级评论", + "type": [ + "integer", + "null" + ], + "format": "int64" + }, + "appUserId": { + "description": "评论业务用户 ID", + "type": "integer", + "format": "int64" + }, + "appUserNickName": { + "description": "评论人昵称", + "type": "string" + }, + "appUserAvatar": { + "description": "评论人头像文件 ID", + "type": [ + "integer", + "null" + ], + "format": "int64" + }, + "parentAppUserId": { + "description": "被直接回复的业务用户 ID", + "type": [ + "integer", + "null" + ], + "format": "int64" + }, + "parentAppUserNickName": { + "description": "被直接回复的用户昵称", + "type": [ + "string", + "null" + ] + }, + "commentContent": { + "description": "评论内容；作者删除后为 null", + "type": [ + "string", + "null" + ] + }, + "userDeleted": { + "description": "作者删除状态，0 未删除，1 已删除并保留占位", + "type": "string", + "enum": [ + "0", + "1" + ], + "examples": [ + "0" + ] + }, + "replyCount": { + "description": "正常展示的直接回复数量", + "type": "integer", + "format": "int64" + }, + "commentLevel": { + "description": "评论层级，root 为一级评论，reply 为回复", + "type": "string", + "enum": [ + "root", + "reply" + ] + }, + "status": { + "description": "字典 sys_normal_disable：0=正常展示，1=停用；会员接口仅返回0", + "type": "string", + "enum": [ + "0", + "1" + ], + "x-dict-type": "sys_normal_disable", + "examples": [ + "0" + ] + }, + "createTime": { + "description": "评论发布时间", + "type": "string", + "format": "date-time" + } + } + }, + "RFamilyFeedCommentList": { + "type": "object", + "properties": { + "code": { + "description": "响应状态码", + "type": "integer", + "examples": [ + 200 + ] + }, + "msg": { + "description": "响应消息", + "type": "string" + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/FamilyFeedCommentView" + } + } + } + }, + "FamilyFeedCommentPageResult": { + "type": "object", + "properties": { + "code": { + "description": "响应状态码", + "type": "integer", + "examples": [ + 200 + ] + }, + "msg": { + "description": "响应消息", + "type": "string" + }, + "rows": { + "description": "评论分页数据", + "type": "array", + "items": { + "$ref": "#/components/schemas/FamilyFeedCommentView" + } + }, + "total": { + "description": "评论总数", + "type": "integer", + "format": "int64" + } + } + }, + "RFamilyFeed": { + "type": "object", + "properties": { + "code": { + "description": "响应状态码", + "type": "integer", + "examples": [ + 200 + ] + }, + "msg": { + "description": "响应消息", + "type": "string", + "examples": [ + "操作成功" + ] + }, + "data": { + "$ref": "#/components/schemas/FamilyFeedView" + } + } + }, + "FamilyFeedView": { + "type": "object", + "properties": { + "feedId": { + "description": "动态ID", + "type": "integer", + "format": "int64" + }, + "genealogyId": { + "description": "所属家谱ID", + "type": "integer", + "format": "int64" + }, + "genealogyNo": { + "description": "家谱编号", + "type": "string" + }, + "genealogyName": { + "description": "家谱名称", + "type": "string" + }, + "publisherUserId": { + "description": "发布业务用户ID", + "type": "integer", + "format": "int64" + }, + "publisherNickName": { + "description": "发布用户昵称", + "type": "string" + }, + "publisherStatus": { + "description": "发布用户状态", + "type": "string" + }, + "feedType": { + "description": "动态类型", + "type": "string" + }, + "feedContent": { + "description": "动态内容", + "type": "string" + }, + "mediaOssIds": { + "description": "媒体文件OSS ID列表，多个ID使用英文逗号分隔", + "type": "string" + }, + "likedByMe": { + "description": "当前登录用户是否已点赞", + "type": "boolean", + "examples": [ + false + ] + }, + "likeCount": { + "description": "点赞数量", + "type": "integer", + "format": "int64" + }, + "commentCount": { + "description": "评论数量", + "type": "integer", + "format": "int64" + }, + "pinned": { + "description": "字典 gen_number_yes_no：0=否，1=是", + "type": "string", + "enum": [ + "0", + "1" + ], + "x-dict-type": "gen_number_yes_no", + "examples": [ + "0" + ] + }, + "pinnedTime": { + "description": "置顶时间", + "type": [ + "string", + "null" + ], + "format": "date-time" + }, + "sortOrder": { + "description": "排序值", + "type": "integer", + "format": "int64" + }, + "status": { + "description": "字典 sys_normal_disable：0=正常，1=停用", + "type": "string", + "enum": [ + "0", + "1" + ], + "x-dict-type": "sys_normal_disable", + "examples": [ + "0" + ] + }, + "remark": { + "description": "备注", + "type": "string" + }, + "createTime": { + "description": "发布时间", + "type": "string", + "format": "date-time" + }, + "updateTime": { + "description": "更新时间", + "type": "string", + "format": "date-time" + } + } + }, + "RFamilyFeedList": { + "type": "object", + "properties": { + "code": { + "description": "响应状态码", + "type": "integer", + "examples": [ + 200 + ] + }, + "msg": { + "description": "响应消息", + "type": "string", + "examples": [ + "操作成功" + ] + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/FamilyFeedView" + } + } + } + }, + "FamilyFeedPageResult": { + "type": "object", + "properties": { + "code": { + "description": "响应状态码", + "type": "integer", + "examples": [ + 200 + ] + }, + "msg": { + "description": "响应消息", + "type": "string", + "examples": [ + "操作成功" + ] + }, + "rows": { + "type": "array", + "items": { + "$ref": "#/components/schemas/FamilyFeedView" + } + }, + "total": { + "description": "总记录数", + "type": "integer", + "format": "int64", + "examples": [ + 0 + ] + } + } + } + }, + "responses": { + "VoidResult": { + "description": "通用成功响应", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RVoid" + } + } + } + }, + "ObjectResult": { + "description": "通用对象响应", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RObject" + } + } + } + }, + "GenealogyQuotaResult": { + "description": "当前业务用户家谱配额响应", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RGenealogyQuota" + } + } + } + }, + "LongResult": { + "description": "长整型数据响应", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RLong" + } + } + } + }, + "ListResult": { + "description": "通用列表响应", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RList" + } + } + } + }, + "CeremonyInvitationResult": { + "description": "贺礼邀约详情响应", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RCeremonyInvitation" + } + } + } + }, + "CeremonyInvitationListResult": { + "description": "贺礼邀约列表响应", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RCeremonyInvitationList" + } + } + } + }, + "GenerationPoemResult": { + "description": "字辈详情响应", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RGenerationPoem" + } + } + } + }, + "GenerationPoemListResult": { + "description": "字辈列表响应", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RGenerationPoemList" + } + } + } + }, + "GenerationPoemBatchPreviewResult": { + "description": "字辈批量预览响应", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RGenerationPoemBatchPreview" + } + } + } + }, + "LineagePersonResult": { + "description": "世系人物详情响应", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RLineagePerson" + } + } + } + }, + "LineagePersonListResult": { + "description": "世系人物列表或选项响应", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RLineagePersonList" + } + } + } + }, + "LineagePersonTreeResult": { + "description": "世系树响应", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RLineagePersonTreeList" + } + } + } + }, + "LineagePersonPageResult": { + "description": "世系人物分页响应", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LineagePersonPageResult" + } + } + } + }, + "LoginResult": { + "description": "登录结果", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RLogin" + } + } + } + }, + "FileUploadResult": { + "description": "文件上传结果", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RFileUpload" + } + } + } + }, + "VerificationRequireResult": { + "description": "验证需求查询结果", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RVerificationRequire" + } + } + } + }, + "VerificationChallengeResult": { + "description": "验证挑战生成结果", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RVerificationChallenge" + } + } + } + }, + "VerificationCheckResult": { + "description": "验证校验结果", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RVerificationCheck" + } + } + } + }, + "FamilyFeedCommentResult": { + "description": "家族圈评论对象响应", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RFamilyFeedComment" + } + } + } + }, + "FamilyFeedCommentListResult": { + "description": "家族圈评论列表响应", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RFamilyFeedCommentList" + } + } + } + }, + "FamilyFeedCommentPageResult": { + "description": "家族圈评论分页响应", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FamilyFeedCommentPageResult" + } + } + } + }, + "FamilyFeedResult": { + "description": "家族圈动态对象响应", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RFamilyFeed" + } + } + } + }, + "FamilyFeedListResult": { + "description": "家族圈动态列表响应", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RFamilyFeedList" + } + } + } + }, + "FamilyFeedPageResult": { + "description": "家族圈动态分页响应", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FamilyFeedPageResult" + } + } + } + } + }, + "securitySchemes": { + "SaToken1": { + "type": "apiKey", + "in": "header", + "name": "Authorization", + "description": "登录后返回的 token。若本地配置使用 sa-token 名称，请按项目实际 token-name 调整。" + } + } + }, + "servers": [], + "security": [ + { + "SaToken1": [] + } + ] +} \ No newline at end of file diff --git a/docs/PC接口对接规划.md b/docs/PC接口对接规划.md index 5c06da0..333b113 100644 --- a/docs/PC接口对接规划.md +++ b/docs/PC接口对接规划.md @@ -1,696 +1,859 @@ -# PC 接口对接规划（Apifox 85 接口版） +# PC 接口字段与页面落地规划（供 AI 执行） -> 状态：当前范围已确认 -> 日期：2026-07-25 -> 当前阶段：桌面版 Apifox 的 PC 目录为 85 条，已逐条在 PC 详情复核并与客户端映射比对。后续仅在该目录出现新增或变更时，按 PC 详情重新核验；不据旧记录猜测施工。 -> 交接入口：[交接文档.md](交接文档.md) +> 文档状态：规划，不代表当前代码已经完成 +> 基线日期：2026-07-27 +> 当前本地快照：根目录 `PC.openapi.json`，OpenAPI 3.1.0 +> 使用对象：另一台电脑上的执行 AI +> 本轮边界：只写规划；执行 AI 才能修改页面、脚本和测试 -## 1. 已确认的基线 +## 0. 强制要求：必须打开 Apifox 查看 -1. **Apifox 的 PC 目录是 PC 前端接口的唯一正式契约源。** -2. 当前 Apifox PC 共 85 个操作： +执行 AI 在修改任何代码前，必须实际登录并打开 Apifox 的“家谱”项目，进入每一个本轮接口的详情页逐项查看。不得只读取 `PC.openapi.json`、Apifox 本地缓存、旧截图或历史文档。 - | 分组 | 数量 | - | --- | ---: | - | 认证登录 | 12 | - | 验证中心 | 3 | - | 文件上传 | 3 | - | 家谱 | 1 | - | 行政区划 | 4 | - | 家族圈 | 14 | - | 字辈谱 | 6 | - | 世系人物 | 12 | - | 内容文章 | 1 | - | 相册 | 2 | - | 视频 | 1 | - | 贺礼邀约 | 4 | - | 祭祀 | 2 | - | 族务记录 | 16 | - | 消息通知 | 4 | - | **合计** | **85** | +每个接口都必须在 Apifox 详情页记录： -3. 仓库中的旧 OpenAPI 文件不再作为新增功能依据。Apifox 客户端中实时的 PC 目录是最终验收源；导出文件最多作为本地自动测试快照，不能替代在 Apifox 中逐项核对。 -4. APP 接口不允许在 PC 页面中直接复用。PC 缺少的能力应先补入 Apifox 的 PC 目录，再开发页面。 -5. 当前不根据 APP 或后端公开 OpenAPI 扩大范围；没有进入 Apifox PC 目录的接口，不视为 PC 已确认接口。 -6. 后端以后新增 PC 接口时，再按新增后的 Apifox PC 契约启动下一轮规划。 +1. method、完整 path、接口状态和所属 PC 目录； +2. Path、Query、Header、Cookie 和 Body 的全部字段； +3. 每个字段的类型、必填/可选/条件必填、默认值、枚举、格式、长度和取值范围； +4. 字段说明、示例值、关联字典和条件显示规则； +5. 请求体中折叠对象、数组元素和嵌套字段的完整结构； +6. 成功响应、失败响应、列表元素、详情对象和分页结构的完整字段； +7. 登录要求、角色权限、业务前置条件和错误码； +8. Apifox 页面有但 OpenAPI 导出遗漏的字段或说明。 -## 2. 当前最重要的结论 +核对结果必须写入本规划对应模块的字段表，并为每个字段标明 U/S/F/A/R/I/V 分类、使用页面、数据来源和提交时机。Apifox 详情没有确认的字段不得进入代码；Apifox 与导出文件不一致时，以现场核对结果形成问题清单，先让接口 owner 修正并重新导出，再实施。 -现有 85 个接口仍不能覆盖整个 PC 管理端闭环，主要问题不是前端页面，而是接口目录不完整： +## 1. 最终目标 -- 没有“我的家谱、家谱详情、创建/加入家谱、家谱成员”接口，PC 无法自行取得真实 `genealogyId`。 -- 内容文章只有删除接口。 -- 相册只有删除相册、删除照片接口。 -- 视频只有删除接口。 -- 祭祀只有删除祭祀、删除献礼接口。 -- 功德记录只有删除接口。 -- 世系关系只有新增父母、配偶、兄弟姐妹、子女，没有解除关系接口。 -- 字辈谱没有删除接口。 +执行 AI 要把 Apifox 中的 PC 接口准确落到现有 PC 页面，最终同时满足： -因此对接分成三类： +1. 请求体中的必填字段、可选字段全部有明确页面归属。 +2. 字段被明确分成： + - 用户输入； + - 用户选择； + - 文件选择后自动生成； + - 页面上下文自动带入； + - 接口响应后只读展示； + - 仅内部保存、不得展示或手工填写； + - 纯前端校验字段、不得发给后端。 +3. ID、Token、`clientid`、`tenantId`、OSS ID、分页参数等系统字段不得让用户手工输入。 +4. 下拉框和选择器必须有真实数据源；没有选项接口时不得改成“请输入 ID”。 +5. Apifox 未展开的响应 DTO、未声明的枚举和互相冲突的路径不得靠前端猜测。 +6. APP 接口不得用于填补 PC 接口缺口。 +7. 所有家谱内业务必须使用真实 `genealogyId`，不得写死示例值。 +8. 每一阶段必须有契约测试、页面行为测试和真实联调结果。 -1. **当前可以形成可用流程：**认证、验证、文件上传、区划、家族圈、字辈谱、世系人物，以及成长记录、亲友往来、备忘录的新增；三类列表仅能按未展开 DTO 原样展示。其中家谱内接口必须先由 PC 运行入口提供真实 `genealogyId`。 -2. **当前只做契约映射、不开放页面操作：**文章、相册、视频、祭祀和功德录目前只有删除接口，不能在没有真实列表和详情数据时单独启用删除。 -3. **后端补充 PC 接口后再规划：**家谱上下文、成员，以及上述资源缺少的读写操作、世系关系解除和字辈删除/停用。 +## 2. 执行 AI 的工作协议 -### 2.1 当前范围规则 +执行 AI 开始前必须按顺序完成： -- 当前只分析和对接 Apifox PC 中已经存在的 85 个操作。 -- 不读取 APP 接口补 PC 缺口，不把 `/genealogy/app` 改前缀后用于 PC。 -- 后端公开文档中存在、但 Apifox PC 当前没有的接口，不进入本轮对接；也不以导出文件缺失为由跳过 Apifox 中已有的接口。 -- PC 当前缺少的业务接口只登记为后端待办，相关页面继续显示待开发状态。 -- 后端新增接口后，必须先进入 Apifox PC 并补齐 DTO，再进入前端对接规划。 +1. 阅读项目根目录 `AGENTS.md`。 +2. 检查工作树，只修改本计划点名的文件；保留用户已有改动。 +3. 登录 Apifox，打开“家谱”项目，逐条核对实时 PC 接口详情。 +4. 从 Apifox 重新导出最新 OpenAPI，和仓库 `PC.openapi.json` 做结构化差异比较。 +5. 完成第 5 节“契约阻断项”；阻断项未解决的模块只保留页面设计，不接真实写操作。 +6. 按第 8 节阶段顺序施工，每完成一阶段立即验证，不能把所有模块一次性混改。 -## 3. 公共契约规则 +遇到以下情况时，停止当前模块并整理成一份待后端确认清单，同时继续其他不受影响的模块： -### 3.1 接口所有权 +- Apifox 页面和导出文件的 method、path、必填性、枚举或类型不一致； +- 响应仍是无属性的 `ObjectResult` / `ListResult`； +- 选择字段没有合法选项来源； +- 更新接口没有说明“字段不传”和“传 null/空串”的区别； +- 页面需要的业务能力在 PC 目录中不存在。 -- Apifox PC 目录拥有 method、path、请求 DTO、响应 DTO、枚举和权限说明。 -- `utils/ApiClient.js` 只负责实现 Apifox 已定义的业务方法，不允许页面自行拼接接口路径。 -- 页面脚本只消费 `ApiClient` 方法，不直接调用 Axios。 -- 新契约确认后，旧字段兼容读取、旧路径和临时 fallback 必须一起删除，不能长期维护两套契约。 +不得通过兼容多个旧字段、读取 APP DTO、保留旧路径 fallback 或展示原始 JSON 绕过阻断。 -### 3.2 家谱上下文 +## 3. 契约依据与优先级 -所有家谱内业务必须使用真实 `genealogyId`： +发生冲突时按以下顺序处理： -1. 当前 85 个接口仍没有“我的家谱”入口；新增的家谱配额接口也不能提供真实 `genealogyId`，本轮不从 APP 获取。 -2. 当前家谱业务页面只接受 PC 运行入口通过 URL 传入的真实 `genealogyId`。 -3. `profile-common.js` 作为 PC 页面家谱上下文的唯一 owner，负责读取、校验和传播 `genealogyId`。 -4. `ApiClient` 负责把 `genealogyId` 放入路径。 +1. Apifox “家谱”项目中当前 PC 接口详情； +2. 从该详情当场重新导出的 OpenAPI 文件； +3. 本规划中的字段和流程分类； +4. 当前仓库代码； +5. 旧规划和历史交接记录。 -当前 `GET /genealogy/pc/genealogies/quota` 已映射为 `genealogyQuota()`；它只返回创建/加入家谱的已用数量、上限、剩余和 `canCreate`/`canJoin`，不能作为家谱列表、详情、创建或加入接口，也不能生成或替代真实 `genealogyId`。 -5. 页面缺少 `genealogyId` 时，统一先跳转 `profile-families.html`；该入口页只读取配额并说明 PC 尚不能选择家谱，阻止业务请求且不使用示例编号。 +Apifox 是 method、path、参数、DTO、枚举、权限和错误码的唯一业务契约 owner。`utils/ApiClient.js` 是前端路径和请求方法的唯一 owner。页面脚本只能调用 `ApiClient` 业务方法，不能直接拼 URL 或调用 Axios。 -个人中心、内容发布和家谱内导航已统一指向该入口页；后端补充 PC 家谱入口接口后，再由入口页实现“我的家谱 → 选择家谱 → 进入业务页面”的完整导航闭环。 +如果 Apifox 在线内容发生变化，先更新本地 OpenAPI、本规划的受影响章节和契约测试，再修改运行时代码。不得让文档、测试和运行时同时保留两套契约。 -### 3.3 请求头与登录状态 +## 4. 当前基线与复核结论 -- 所有 PC 请求统一携带 `clientid`。 -- 登录后接口统一携带 `Authorization: Bearer `。 -- `tenantId`、`clientId` 只在 Apifox DTO 明确要求时进入请求体，页面不得自行添加。 -- 401：清除本地登录态并跳转登录页。 -- 403：保留登录态，展示无权限页或无权限状态。 +### 4.1 当前导出范围 -Apifox 必须为每个操作明确标记“公开”或“需要登录”，不能只依赖接口描述文字。 +当前 `PC.openapi.json` 共 96 个操作、15 个标签、68 个 Schema： -Apifox 还必须正式声明 Bearer security scheme、`Authorization` 和 `clientid`，否则自动生成文档、Mock 和测试时无法还原真实请求。 +| 模块 | 操作数 | 当前主要页面 | +| --- | ---: | --- | +| 验证中心 | 3 | 登录、注册、找回密码、安全设置 | +| 认证登录 | 11 | `login.html`、`register.html`、`forgot-password.html`、个人资料和安全页 | +| 文件上传 | 3 | 所有头像、图片、附件和视频选择控件 | +| 家谱 | 1 | `profile-families.html` | +| 家族圈 | 14 | `profile-feed.html`、`profile-feed-edit.html`、待新增动态详情页 | +| 行政区划 | 8 | 个人资料及以后需要地区的表单 | +| 字辈谱 | 6 | `profile-generation.html` | +| 世系人物 | 12 | `profile-tree.html` | +| 内容文章 | 1 | `profile-article.html`、`profile-article-edit.html` | +| 相册 | 2 | `profile-album.html` | +| 视频 | 5 | `profile-video.html`、待新增视频编辑页 | +| 贺礼邀约 | 4 | `profile-gift.html`、邀约管理面板 | +| 祭祀 | 2 | `profile-gift.html` | +| 族务记录 | 20 | 成长、亲友、备忘录、功德录页面 | +| 消息通知 | 4 | `profile-messages.html` | +| **合计** | **96** | | -### 3.4 响应与分页 +### 4.2 已对照到的 Apifox 现状 -普通响应统一为： +本机 Apifox 缓存中的“家谱”项目包含 APP、PC、共享区划等 246 条接口记录。当前导出的 96 条路径均能在该项目缓存的接口树中找到，但存在以下差异： -```json -{ - "code": 200, - "msg": "操作成功", - "data": {} -} -``` +1. Apifox 缓存同时保留了两条逻辑相同的短信接口： + - 错误旧路径：`genealogy/pc/auth/sms/{operationCode}/code` + - 正确路径：`/genealogy/pc/auth/sms/{operationCode}/code` -分页响应统一为： + 当前导出只保留正确路径。执行前必须在 Apifox 删除或正式废弃缺少 `/` 的旧定义，前端只实现正确路径。 +2. 导出文件同时含 `/genealogy/region/*` 和 `/genealogy/pc/region/*` 两套共 8 个区划操作；两套的参数、响应和描述完全相同。执行前必须由后端选定一套唯一正式路径并删除另一套。选定后实际唯一操作数应从 96 收口为 92。 +3. 旧版“85 接口规划”已经失效。新增范围主要包括 PC 区划 4 条、视频列表/新增/详情/修改 4 条、功德列表/新增/详情/修改 4 条。 +4. 当前 96 个操作全部被声明为需要 `Authorization`，连注册、登录、短信发送和验证中心也不例外。这与未登录流程冲突，必须在 Apifox 逐项修正 security。 +5. 当前有 21 个成功响应使用无业务属性的 `ObjectResult`，12 个使用无元素 Schema 的 `ListResult`；另有 `LineagePersonTreeView` 名义上是专用 DTO，但没有任何属性。 -```json -{ - "code": 200, - "msg": "操作成功", - "rows": [], - "total": 0 -} -``` +## 5. 实施前必须解决的契约阻断项 -分页参数应明确展开为 `pageNum`、`pageSize`、`orderByColumn`、`isAsc`，不把整个 `pageQuery` 声明成一个含义不清的 query object。 +以下事项不是前端自由选择，必须先在 Apifox 明确： -除 200 外，每组接口至少定义适用的 400、401、403、404、409、422 和 429 响应，不能把所有失败都写成 401。 +| 编号 | 问题 | 影响 | 完成条件 | +| --- | --- | --- | --- | +| C01 | 两套区划路径完全重复 | 页面和客户端会形成双路径 | Apifox 只保留一套；导出和客户端只出现一次 | +| C02 | 短信接口有缺少开头 `/` 的旧记录 | 可能生成错误 URL | 删除/废弃旧记录，只保留正确路径 | +| C03 | 所有操作均要求 Authorization | 未登录流程无法成立 | 注册、登录、找回、验证、短信等逐项标明公开；登录后接口明确鉴权 | +| C04 | 33 个操作使用泛型对象/列表响应 | 列表、详情、编辑回填和 ID 来源不确定 | 为每个业务资源增加明确 View/DTO Schema | +| C05 | `LineagePersonTreeView` 没有属性 | 世系树只能猜字段 | 补齐节点 ID、人物资料、配偶、子女和递归结构 | +| C06 | 用户资料响应未展开 | 个人资料无法可靠回填 | 增加 `ProfileView`，明确所有可读字段 | +| C07 | `ProfileUpdateBody` 没有地区字段 | 现居地区无法保存 | 明确增加地区编码字段或删除“保存地区”功能 | +| C08 | 区划响应没有元素 DTO | 下拉选项的 code/name/level 不受契约约束 | 增加 `RegionView` 及列表/路径响应 | +| C09 | 上传初始化响应未展开，却描述了 `instant=true` | 秒传、续传和 `uploadId` 状态不明确 | 增加初始化响应 DTO，明确 `instant`、已传分片和 OSS 信息 | +| C10 | OSS ID 类型冲突 | 可能发生 JS 精度丢失或校验失败 | 所有 `ossId`、`avatar`、`avatarOssId`、视频和附件 ID 统一为 string | +| C11 | `completed` 只有 string 类型，无枚举 | 不能决定复选框提交 `0/1`、true/false 或其他值 | Apifox 增加枚举和中文含义 | +| C12 | `feedType`、`recordType`、`registerSource` 等无枚举 | 无法判断文本输入还是选择项 | 明确为自由文本，或补全枚举 | +| C13 | 多个日期字段没有 format/时区规则 | 页面值和后端解析可能不一致 | 明确 date 或 date-time，并统一时区 | +| C14 | 只有配额，没有我的家谱/成员入口 | 无法取得 `genealogyId`、成员或受邀用户选项 | 增加 PC 家谱列表/选项和成员选项接口，或明确外部上下文契约 | +| C15 | `bindingMode=SPECIFIED` 需要 `appUserId`，但无业务用户选项接口 | 不能提供合法选择器 | 增加家谱成员/业务用户选项接口 | +| C16 | 邀约的 `inviteeUserIds` 没有选项接口 | 不能让管理员选择受邀人 | 增加同一家谱成员选项接口 | +| C17 | 视频、成长、亲友、备忘、功德、通知响应未展开 | 无法安全展示、编辑或单条操作 | 分别增加资源 View 和列表/详情响应 | +| C18 | 更新接口未说明缺省、null、空串语义 | 可选字段可能无法清空 | Apifox 对每个可清空字段写明更新规则 | +| C19 | 多数 View 没有 `canEdit` / `canDelete` 等权限字段 | 页面无法可靠决定按钮可见性 | 增加能力字段，或提供明确且可实现的角色规则 | +| C20 | 文章、相册、祭祀只有删除操作 | 没有真实 ID 来源和完整资源流程 | 补全 PC 列表/详情/新增/修改后才开放页面 | -### 3.5 ID、日期和枚举 +阶段 0 验收标准： -- `genealogyId`、`personId`、`feedId`、`commentId`、`ossId` 等 ID 在浏览器端统一按字符串处理，避免 JavaScript `int64` 精度丢失。 -- Apifox 当前需要统一文件上传响应和业务写入 DTO 中 `ossId` 的类型；不能一处为 string、另一处为 integer。 -- 纯日期使用 `YYYY-MM-DD`。 -- 具体时刻使用带时区的 ISO 8601。 -- 性别、状态、角色、可见性、祭祀类型等必须在 Apifox 中给出固定枚举及中文含义。 +- Apifox 中不存在旧短信路径和双区划路径； +- 重新导出的 OpenAPI 只包含一套正式契约； +- 公开与鉴权接口标记正确； +- 本阶段要实现的每个列表/详情都有明确响应 DTO； +- 所有枚举、日期和 ID 类型已确定； +- 将旧输入发送给后端时会明确失败，前端不保留兼容读取。 -### 3.6 权限 +## 6. 页面字段分类标准 -至少区分： +执行 AI 对每个请求字段都要采用下面一种处理类型： -- 访客 -- 普通家谱成员 -- 内容编辑者 -- 家谱管理员 -- 家谱创建者/所有者 -- 平台管理员 - -列表和详情 DTO 应返回 `canEdit`、`canDelete`、`canManage` 等能力字段。前端据此显示操作，后端仍必须独立鉴权。 - -同一个 PC DTO 不等于所有角色都能看到所有字段。手机号、联系方式、通知目标等敏感字段要按权限裁剪；需要时拆成摘要 DTO 和管理员详情 DTO。 - -前端只使用 Apifox PC 当前声明的 Schema，不从 APP Schema 推导字段。 - -### 3.7 文件生命周期 - -图片、小文件： - -1. 单文件上传。 -2. 获得 `ossId`。 -3. 保存业务对象。 -4. 绑定文件业务引用。 - -视频、大文件： - -1. 初始化分片任务。 -2. 上传所有分片。 -3. 服务端合并。 -4. 保存业务对象。 -5. 绑定文件业务引用。 - -替换或删除业务对象后解除旧文件引用。上传成功但业务保存失败时，也要提供清理策略。 - -## 4. 已完成施工接口与当前迁移 - -### 4.1 认证登录（当前目录 12） - -| 接口 | 使用页面 | 用途 | +| 类型 | 含义 | 页面处理 | | --- | --- | --- | -| `POST /genealogy/pc/auth/register` | `register.html` | 用户注册 | -| `POST /genealogy/pc/auth/login` | `login.html` | 密码登录 | -| `POST /genealogy/pc/auth/login/sms` | `login.html` | 短信登录 | -| `POST /genealogy/pc/auth/sms/{operationCode}/code` | 短信登录、注册、找回密码、换绑手机号、注销账号 | 按认证动作发送短信验证码 | -| `GET /genealogy/pc/auth/profile` | `profile.html`、`profile-data.html`、`profile-security.html` | 获取当前用户资料/已绑定手机号 | -| `PUT /genealogy/pc/auth/profile` | `profile-data.html` | 修改个人资料 | -| `PUT /genealogy/pc/auth/password` | `profile-security.html` | 修改密码 | -| `PUT /genealogy/pc/auth/password/reset` | `forgot-password.html` | 找回密码 | -| `PUT /genealogy/pc/auth/phone` | `profile-security.html` | 换绑手机号 | -| `POST /genealogy/pc/auth/account/deactivate` | `profile-security.html` | 注销账号 | -| `DELETE /genealogy/pc/auth/logout` | 所有登录后页面 | 退出登录 | +| U：用户输入 | 姓名、标题、正文、手机号等 | 可见输入框/文本域，展示必填或选填 | +| S：用户选择 | 枚举、人员、字辈、地区、状态等 | 单选、下拉、多选、日期或开关；选项必须有真实来源 | +| F：文件派生 | OSS ID、文件名、MD5、大小等 | 用户只选文件；值由上传组件生成并隐藏 | +| A：自动填写 | header、租户、上下文 ID、分页、默认值等 | 页面不可编辑，由统一 owner 注入 | +| R：响应只读 | 创建时间、计数、发布人、状态文本等 | 列表、详情、徽标或只读信息 | +| I：内部状态 | token、challengeId、validToken、资源 ID 等 | 仅内存/安全存储/URL 中保存，不显示原值 | +| V：前端校验 | 确认密码、注销确认文字等 | 可见但不得发给后端 | -状态：当前 PC 认证登录目录 12 条已逐条复核：第一轮已接入密码登录、短信登录、注册、找回密码、换绑手机号、注销和退出；本轮已把短信发送迁移到当前 PC 的 `operationCode` 路径。密码登录也先按 `password-login` 查询验证策略，策略要求时完成 TAC 后提交返回的 `validToken`。`ApiClient` 只补 DTO 明确要求的 `grantType`、`tenantId`，`clientid` 仅由请求头统一注入，body 不得传 `clientId`。目录内两条短信发送定义为相同路径和契约。资料响应未给出字段 Schema，页面只读取 PC 页面已使用的明确字段，不增加 APP 字段猜测。 +通用规则： -已在 Apifox 直接核验的认证约束： +1. 必填字段使用明确的必填标识，并在提交前校验。 +2. 可选字段也必须有页面归属；不填写时直接省略，除非 Apifox 明确要求传 null。 +3. 枚举必须使用选择控件，禁止自由文本。 +4. 外键 ID 必须使用搜索/选择控件，禁止“请输入人物 ID”“请输入 OSS ID”。 +5. `sortOrder`、`status` 这类管理字段： + - 有管理权限时放在“高级设置”； + - 普通用户使用隐藏默认值； + - 后端未返回权限时不得自行开放高级设置。 +6. 所有 int64 ID 在浏览器中按字符串保存和比较。 +7. 响应中的 `code`、`msg` 由请求层统一处理；业务页只消费 `data` 或 `rows/total`。 -- 发送短信验证码使用路径 `operationCode`：`sms-login`、`register`、`forgot-password`、`phone-change`、`account-deactivate`。 -- 发送短信码请求体为 `grantType`、`tenantId`、`phone`、`validToken`；`validToken` 来自验证中心且只能单次消费。不得传 `sceneCode` 或 body `clientId`。 -- 换绑手机号请求体为 `phone`、`smsCode`；注销账号请求体为 `smsCode`。二者不附带 `tenantId`，`clientid` 仅通过请求头传递。 -- 密码登录、注册与找回密码使用 `grantType: "password"`；短信登录与发送短信码使用 `grantType: "sms"`；所有密码字段均为 32 位 MD5。密码登录的 `validToken` 由 `password-login` 验证策略决定，有策略要求时随本次登录提交。上述认证 DTO 都禁止 body `clientId`。 +## 7. 字段、页面和流程规划 -第一批页面与接口顺序： +### 7.1 全局自动字段 -| 页面 | 页面流程 | 对接接口 | +| 字段 | 类型 | 唯一来源 | 规则 | +| --- | --- | --- | --- | +| `clientid` | A | `ApiClient` 配置 | 每个需要它的请求自动加 Header，不进入表单或 body | +| `Authorization` | I/A | 登录响应 token | 仅鉴权接口携带；注册登录等公开接口不携带 | +| `tenantId` | A | 环境配置 | 登录、注册、验证等自动带入，不让用户输入 | +| `genealogyId` | I/A | PC 家谱上下文 | `profile-common.js` 读取和传播；缺失时阻止家谱内请求 | +| `feedId`、`commentId`、`personId`、`poemId`、`articleId`、`albumId`、`photoId`、`videoId`、`ceremonyId`、`giftId`、`recordId`、`relativeId`、`memoId`、`meritId`、`notificationId` | I/A | 列表/详情响应或 URL | 由被点击记录带入，禁止文本框输入 | +| `pageNum`、`pageSize` | A/S | 分页组件 | 页码由组件维护；用户只操作翻页/每页条数 | +| `ossId` / `mediaOssIds` | F/I | 文件上传响应 | 页面展示预览和文件名，隐藏保存 ID | +| `sortOrder` | S/A | 高级设置或默认值 | 不得把空字符串转成 0；未填写时省略 | +| `status` | S/A | 权限化状态选择或默认值 | 枚举 0=正常、1=停用；不得把 1 标成“草稿” | + +### 7.2 验证中心与认证登录 + +#### 页面字段矩阵 + +| 字段 | 必填性 | 类型 | 页面/流程 | 处理 | +| --- | --- | --- | --- | --- | +| `operationCode` | 必填 path | A | 所有认证动作 | 页面动作固定为 `password-login`、`sms-login`、`register`、`forgot-password`、`phone-change` 或 `account-deactivate` | +| `clientid` | 必填 header | A | 所有认证请求 | `ApiClient` 自动注入 | +| `tenantId` | 必填 | A | 所有登录/验证表单 | 环境配置自动注入 | +| `subject` | require 可选，challenge/verify 必填 | A | 验证流程 | 从当前手机号/账号派生，用户不重复填写 | +| `grantType` | 必填 | A | 注册、登录、短信、找回 | 密码动作固定 `password`，短信动作固定 `sms` | +| `phone` | 必填 | U | 登录、注册、找回、换绑 | 手机号输入和格式校验 | +| `password` | 必填 | U/A | 密码登录、注册 | 用户输入明文，提交前生成 32 位 MD5；日志不得记录 | +| `oldPassword` | 必填 | U/A | 修改密码 | 同上 | +| `newPassword` | 必填 | U/A | 修改/重置密码 | 同上 | +| `confirmPassword` | 前端字段 | V | 注册、修改、找回 | 只比较一致性，不发送 | +| `smsCode` | 必填 | U | 短信登录、注册、找回、换绑、注销 | 4 位验证码输入 | +| `nickName` | 可选 | U | 注册 | 昵称输入 | +| `registerSource` | 可选 | A | 注册 | 当前端固定 `PC`；Apifox 需确认枚举 | +| `validToken` | 条件必填 | I/A | 密码登录、发送短信 | 验证成功后仅存内存，使用一次即清除 | +| `challengeId` | 必填 | I/A | 验证校验 | 挑战响应自动回填 | +| `providerCode`、`captchaType` | 可选 | A | 验证校验 | 挑战响应决定，用户不可修改 | +| `payload.track` | 条件必填 | A | 天爱验证码 | 控件原样生成轨迹、尺寸和时间 | +| `payload.uuid` | 条件必填 | I/A | 系统图形验证码 | 挑战响应回填 | +| `payload.code` | 条件必填 | U | 系统图形验证码 | 用户输入图片答案 | + +天爱控件产生的嵌套字段全部属于 A，不得另做表单让用户填写： + +- `bgImageWidth`、`bgImageHeight`：控件实际显示尺寸，必填； +- `templateImageWidth`、`templateImageHeight`：模板实际显示尺寸，可选； +- `startTime`、`stopTime`：操作开始和结束毫秒时间戳，必填； +- `left`、`top`：控件最终偏移，可选； +- `trackList`：必填轨迹数组； +- 每个轨迹点的 `x`、`y`、`t`、`type` 均由控件生成； +- `data`：不同验证码类型的扩展数据，原样提交。 + +验证和登录响应字段： + +| 响应字段 | 类型 | 页面处理 | | --- | --- | --- | -| `login.html` | 密码登录 | `POST /genealogy/pc/auth/login` | -| `login.html` | 获取短信码 → 短信登录 | `POST /genealogy/pc/auth/sms/sms-login/code` → `POST /genealogy/pc/auth/login/sms` | -| `register.html` | 获取短信码 → 注册 | `POST /genealogy/pc/auth/sms/register/code` → `POST /genealogy/pc/auth/register` | -| `forgot-password.html` | 获取短信码 → 重设密码 | `POST /genealogy/pc/auth/sms/forgot-password/code` → `PUT /genealogy/pc/auth/password/reset` | -| `profile-security.html` | 修改密码 | `PUT /genealogy/pc/auth/password` | -| `profile-security.html` | 获取短信码 → 换绑手机号 | `POST /genealogy/pc/auth/sms/phone-change/code` → `PUT /genealogy/pc/auth/phone` | -| `profile-security.html` | 读取绑定手机号 → 获取短信码 → 注销 | `GET /genealogy/pc/auth/profile` → `POST /genealogy/pc/auth/sms/account-deactivate/code` → `POST /genealogy/pc/auth/account/deactivate` | -| 所有登录后页面 | 退出登录 | `DELETE /genealogy/pc/auth/logout` | +| `required` | R/A | 决定是否进入挑战流程 | +| `providerCode`、`captchaType` | I/A | 选择正确验证码控件 | +| `sceneCode` | I/R | 服务端解析结果，可用于只读诊断；不得回传 | +| `ttlSeconds`、`expireSeconds` | R/A | 倒计时和过期重试 | +| `challengeId`、`uuid` | I | 只在当前挑战内保存 | +| `img` | R | 系统图形验证码图片 | +| `payload` | I/A | 天爱控件初始化数据 | +| `passed` | R/A | 决定校验成功或失败 | +| `validToken` | I | 一次性票据，不显示、不落长期存储 | +| `message` | R | 安全地显示验证结果 | +| 登录响应的 `token` / `accessToken` / `tokenValue` | I | Apifox 收口为一个正式字段后保存 | +| `userId`、`tenantId`、`clientId`、`clientKey` | I/R | 会话上下文或诊断信息，不作为用户编辑字段 | -### 4.2 验证中心（当前目录 3） +#### 认证业务流程 -| 接口 | 使用位置 | 用途 | +密码登录： + +1. 用户输入手机号和密码。 +2. 以 `password-login + tenantId + phone` 调用 `require`。 +3. 若 `required=false`，直接提交密码登录。 +4. 若需要验证，调用 challenge，展示服务端指定控件，再调用 verify。 +5. 得到 `validToken` 后与 MD5 密码一起登录。 +6. 成功后仅保存一个正式 token 字段；Apifox 必须选定 `token`、`accessToken` 或 `tokenValue` 的唯一字段，不能长期兼容三个别名。 + +短信类动作： + +1. 用户输入手机号。 +2. 按当前动作完成 require → challenge → verify。 +3. 把一次性 `validToken` 提交给发送短信接口。 +4. 用户输入短信码后执行短信登录、注册、找回、换绑或注销。 +5. `validToken` 不进入最终注册、短信登录、换绑或注销 body，除非 Apifox 明确修改契约。 + +#### 个人资料字段 + +`ProfileUpdateBody` 的所有字段必须进入 `profile-data.html`： + +| 字段 | 必填性 | 类型 | 控件 | +| --- | --- | --- | --- | +| `nickName` | 可选 | U | 文本，最长 30 | +| `realName` | 可选 | U | 文本，最长 30 | +| `avatar` | 可选 | F/I | 图片上传、预览、删除；隐藏保存 OSS ID | +| `sex` | 可选 | S | 男 0、女 1、未知 2，三项都要有 | +| `birthday` | 可选 | S | 日期选择器，`yyyy-MM-dd` | +| `email` | 可选 | U | email 输入，最长 100 | + +现有页面整改点： + +- 当前 `avatarOssId` 字段名与请求契约 `avatar` 不一致； +- 缺少 `realName`、`email` 和性别“未知”； +- 页面现居地区、父亲、微信/QQ、学历/职业不在 `ProfileUpdateBody`，不得混入保存请求； +- 在后端增加地区字段前，“保存地区”按钮必须关闭或改成纯查询演示； +- `GET /auth/profile` 必须补齐 `ProfileView` 后才能严格回填。 + +### 7.3 文件上传 + +用户在任何业务页只操作“选择文件、取消、重试”；下面字段全部自动产生： + +| 阶段 | 字段 | 必填性 | 类型 | 来源 | +| --- | --- | --- | --- | --- | +| 初始化 | `uploadId` | 必填 | I/A | 客户端生成一次并贯穿全过程 | +| 初始化 | `fileName` | 必填 | F | `File.name` | +| 初始化 | `fileMd5` | 必填 | F | 文件内容计算 | +| 初始化 | `totalSize` | 必填 | F | `File.size` | +| 初始化 | `totalChunks` | 必填 | F | 根据大小和分片大小计算 | +| 初始化 | `chunkSize` | 必填 | A | 上传组件统一配置，默认示例 4 MiB，最后一片除外 | +| 初始化 | `contentType` | 可选 | F | `File.type` | +| 分片 | `chunkIndex` | 必填 | A | 上传循环生成 | +| 分片 | `chunkMd5` | 必填 | F | 当前分片计算 | +| 分片 | `file` | 必填 | F | 当前 Blob | +| 完成 | `uploadId/fileName/fileMd5/totalSize/totalChunks` | 必填 | I/A/F | 必须与初始化一致 | + +响应处理： + +- `FileUploadVo.ossId`：I，隐藏写入业务表单； +- `url`、`thumbnailUrl`：R，用于预览； +- `fileName`、`originalName`：R，用于文件列表； +- 初始化的 `instant`、已上传分片和秒传 OSS 信息尚未定义，C09 完成前不得猜测； +- 上传成功但业务保存失败时，当前契约没有释放引用接口，必须让后端补充生命周期规则。 + +统一由 `public/js/upload-pages.js` 管理分片、进度、重试、取消、MD5 和隐藏 ID。各业务页面不得复制上传算法，也不得出现“请输入 OSS ID”的可见输入框。 + +### 7.4 家谱上下文与配额 + +`GET /genealogy/pc/genealogies/quota` 只负责在 `profile-families.html` 展示： + +| 响应字段 | 类型 | 页面呈现 | | --- | --- | --- | -| `GET /genealogy/pc/auth/verification/{operationCode}/require` | 密码登录及发送短信登录、注册、找回、换绑、注销短信前 | 判断当前认证动作是否需要验证 | -| `POST /genealogy/pc/auth/verification/{operationCode}/challenge` | 同上 | 获取滑块或图形验证挑战 | -| `POST /genealogy/pc/auth/verification/{operationCode}/verify` | 同上 | 校验挑战并换取 `validToken` | +| `createUsed`、`createLimit`、`createRemaining` | R | 创建额度已用/上限/剩余 | +| `canCreate` | R | 控制“创建家谱”是否可用 | +| `joinUsed`、`joinLimit`、`joinRemaining` | R | 加入额度已用/上限/剩余 | +| `canJoin` | R | 控制“加入家谱”是否可用 | -已在 Apifox 直接核验的验证码约束： +`-1` 显示为“不限”，不能参与普通减法或显示负数。 -- `operationCode` 只允许 `password-login`、`sms-login`、`register`、`forgot-password`、`phone-change`、`account-deactivate`。服务端按它解析激活场景，前端不得传 `sceneCode`。 -- `require` query 为必填 `tenantId` 和可选 `subject`；`challenge` body 为必填 `tenantId`、`subject`；`verify` 增加必填 `challengeId`，可提交 `providerCode`、`captchaType`、`payload`。`clientid` 只从请求头读取，query/body 不得传 `clientId`。 -- `validToken` 与租户、PC 客户端、认证动作、手机号主体、挑战和请求 IP 绑定。它只用于触发它的当前认证动作：发送短信码时随发送请求提交，密码登录被策略要求时随本次登录提交。 +配额响应不包含 `genealogyId`，不能替代“我的家谱”。在 C14 完成前： -规划： +- 所有家谱内页面缺少真实 `genealogyId` 时必须阻止请求； +- 不显示静态家谱卡片作为真实数据； +- 不从 APP 接口获取家谱； +- 不允许用户手工输入家谱 ID。 -- 新流程统一使用 `/genealogy/pc/auth/verification/{operationCode}/*` 三个接口；页面通过 `ApiClient` 的业务方法和 URL helper 驱动 TAC，不拼路径。 -- `validToken` 不长期存储或写日志；发送短信码或密码登录完成后立即从表单清除。页面只会在验证中心对该认证动作明确要求时，将本次返回的值混入对应请求 DTO。 +### 7.5 行政区划 -### 4.3 文件上传（当前目录 3） +先完成 C01，只实现选中的唯一一套路径。 -> 下表是 2026-07-24 的 6 条历史映射。当前桌面版目录只显示 3 条，且三条详情已复核；表中未列的旧单文件上传、文件引用路径已从 `ApiClient` 删除。 +| 字段 | 必填性 | 类型 | 页面处理 | +| --- | --- | --- | --- | +| `parentCode` | 可选 query | A/S | 省级不传；选择上一级后自动查询下级 | +| `regionCode` | 必填 path | I/A | 从被选择的区划记录带入 | +| `keyword` | 必填 query | U | 搜索框 | +| `level` | 可选 query | S | 1 省、2 市、3 区县、4 乡镇街道、5 村社区 | +| `limit` | 可选 query | A | 搜索组件固定合理上限，不让用户自由输入 | +| `clientid` | 可选 header | A | 统一请求层注入 | -| 接口 | 使用位置 | 用途 | +在 `RegionView` 补齐前不能假设响应一定含 `regionCode`、`regionName`、`regionLevel`。个人资料当前也没有可保存的地区字段，因此区划组件只能在有真实消费字段的页面启用提交。 + +### 7.6 家族圈 + +页面归属： + +- `profile-feed.html`：分页列表、点赞、轻量评论； +- `profile-feed-edit.html`：新增和编辑； +- 新增 `profile-feed-detail.html`：详情、完整评论树、回复、通知跳转和分享深链。 + +#### 写入字段 + +| 字段 | 必填性 | 类型 | 页面处理 | +| --- | --- | --- | --- | +| `genealogyId` | 必填 path | I/A | 家谱上下文 | +| `feedId` | 详情/修改/删除必填 | I/A | 列表记录或 URL | +| `feedType` | 可选 | A 或 S | 当前默认隐藏 `text`；Apifox 补枚举后才能改成选择 | +| `feedContent` | 必填 | U | 正文编辑器 | +| `mediaOssIds` | 可选 | F/I | 多文件上传结果拼成英文逗号串，用户只看缩略图 | +| `sortOrder` | 可选 | S/A | 管理员高级设置；普通发布默认省略/0 | +| `status` | 可选 | S/A | 0 正常、1 停用；不得显示为“发布/草稿” | +| `parentCommentId` | 可选 | I/A | 点击“回复”后自动带入；一级评论省略或 null | +| `commentContent` | 必填 | U | 评论输入，最多 1000 字 | +| `pageNum/pageSize` | 可选 | A/S | 分页组件 | + +#### 动态响应字段 + +| 字段 | 页面处理 | +| --- | --- | +| `feedId`、`genealogyId` | I，用于路由和后续操作 | +| `genealogyNo`、`genealogyName` | R，详情来源信息 | +| `publisherUserId` | I，用于权限判断，但不能单独代替后端鉴权 | +| `publisherNickName`、`publisherStatus` | R，发布人和状态 | +| `feedType`、`feedContent` | R，类型和正文 | +| `mediaOssIds` | I/F，解析后通过文件 URL 规则展示，不直接显示 ID | +| `likedByMe` | R，决定点赞按钮状态 | +| `likeCount`、`commentCount` | R，计数 | +| `pinned`、`pinnedTime` | R，置顶徽标和时间 | +| `sortOrder`、`status` | R/管理信息 | +| `remark` | R，仅在产品确认需要时展示，不能当正文 | +| `createTime`、`updateTime` | R，发布时间和编辑时间 | + +评论响应字段： + +- `commentId`、`genealogyId`、`feedId`、`parentCommentId`、`appUserId`、`parentAppUserId`：I； +- `appUserNickName`、`appUserAvatar`、`parentAppUserNickName`：R； +- `commentContent`：R；为 null 且 `userDeleted=1` 时显示“该评论已删除”占位； +- `replyCount`：R，控制“展开回复”； +- `commentLevel`：R，`root` 或 `reply`； +- `status`、`createTime`：R。 + +流程： + +1. 列表首屏调用分页接口，不同时调用非分页接口重复取数。 +2. 点击记录进入详情，以 `genealogyId + feedId` 取详情。 +3. 一级评论调用 comments 分页；回复只调用对应 comment 的 replies 分页。 +4. 点赞、取消、评论、删除成功后以接口返回和重新读取结果校正计数。 +5. 删除有回复的评论后保留占位，不从 DOM 直接移除整棵回复。 + +### 7.7 字辈谱 + +`profile-generation.html` 同时提供“单条维护”和“批量维护”。 + +单条字段： + +| 字段 | 必填性 | 类型 | 控件 | +| --- | --- | --- | --- | +| `generationNo` | 必填 | U/S | 正整数世代序号 | +| `generationText` | 必填 | U | 最长 50 | +| `description` | 可选 | U | 文本域，最长 500 | +| `sortOrder` | 可选 | U/S | 管理员高级数字字段 | +| `status` | 可选 | S | 0 正常、1 停用 | +| `poemId` | 修改必填 path | I/A | 列表记录 | + +批量字段： + +| 字段 | 必填性 | 类型 | 控件 | +| --- | --- | --- | --- | +| `poemText` | 必填 | U | 文本域，最长 26000；支持合同中列出的分隔符 | +| `disableMissing` | 可选 | S | 复选框，必须有“将停用后续世代、不删除历史”的确认说明 | + +批量流程必须是 preview → 用户检查 → save： + +- 预览展示 `createCount`、`updateCount`、`keepCount`、`disableCount`； +- 逐项结果来自 `items`；每项展示 `generationNo`、`oldGenerationText`、`newGenerationText`、`oldStatus`、`newStatus`、`action`、`warning`； +- `poemId`、`genealogyId` 是内部字段； +- 保存前再次确认，因为服务端会基于最新数据重新计算差异。 + +普通展示列表使用正常字辈接口；管理页面使用 management 接口以包含停用项。 + +### 7.8 世系人物 + +全部操作集中在 `profile-tree.html`，详情和编辑可使用抽屉/弹窗，但所有字段都要有明确控件。 + +| 字段 | 必填性 | 类型 | 页面处理 | +| --- | --- | --- | --- | +| `bindingMode` | 必填 | S | NONE 不绑定、SELF 当前账号、SPECIFIED 指定账号 | +| `appUserId` | SPECIFIED 时必填 | S/I | 从真实业务用户选项选择；没有接口时禁用 SPECIFIED，禁止文本 ID | +| `personNo` | 可选 | U/A | 高级设置可填；留空由服务端生成 | +| `name` | 必填 | U | 姓名 | +| `aliasName` | 可选 | U | 别名/曾用名 | +| `sex` | 可选 | S | 0 男、1 女、2 未知 | +| `generation` | 可选 | S/I | 从正常字辈列表选择世代 | +| `generationName` | 可选 | A/R | 随字辈选项自动回填并只读显示 | +| `fatherId` | 可选 | S/I | 世系人物搜索选择器 | +| `motherId` | 可选 | S/I | 世系人物搜索选择器 | +| `avatarOssId` | 可选 | F/I | 上传头像自动回填 | +| `birthDate` | 可选 | S | date-time 选择器 | +| `birthLunar` | 可选 | S | 0 公历、1 农历开关 | +| `birthPlace` | 可选 | U | 出生地文本 | +| `deathDate` | 可选 | S | date-time 选择器 | +| `deathLunar` | 可选 | S | 0 公历、1 农历开关 | +| `deathPlace` | 可选 | U | 逝世地 | +| `burialPlace` | 可选 | U | 安葬地 | +| `personStatus` | 可选 | S | 0 健在、1 已故、2 未知 | +| `biography` | 可选 | U | 人物简介 | +| `sortOrder` | 可选 | U/S | 管理高级设置 | +| `remark` | 可选 | U | 备注 | +| `relationName` | 可选 | U | 仅“添加配偶”快捷流程显示 | + +人物响应字段按以下方式使用： + +- `personId`、`genealogyId`、`appUserId`、`fatherId`、`motherId`、`avatarOssId`：I； +- `genealogyName`、`genealogyNo`：R； +- `appUserNickName`：R，显示绑定账号； +- `personNo`、`name`、`aliasName`、`sex`、`generation`、`generationName`：R/编辑回填； +- `fatherName`、`motherName`、`spouseNames`：R； +- 出生、逝世、安葬、状态、简介、备注、排序字段：R/编辑回填。 + +关系流程： + +1. 先选中一个现有 `personId` 作为关系锚点。 +2. 点击父母、子女、兄弟姐妹或配偶。 +3. 打开完整 `LineagePersonBody` 表单，创建的是一个新人物并建立关系，不是绑定两个现有人物 ID。 +4. 配偶流程才显示 `relationName`。 +5. 当前没有解除关系接口，页面不得伪造“解除关系”。 +6. DELETE 是逻辑停用；存在正常子女时可能失败，确认文案不能写成物理删除。 + +列表筛选： + +- `keyword`：U，搜索姓名、别名或人物编号； +- `generation`：S，从字辈接口选择； +- `personStatus`：S，0/1/2； +- `pageNum/pageSize`：分页组件自动维护。 + +`LineagePersonTreeView` 补全前，不得继续依靠多个字段 fallback 猜树结构。 + +### 7.9 视频 + +计划新增 `profile-video-edit.html`，`profile-video.html` 负责列表。 + +| 字段 | 必填性 | 类型 | 页面处理 | +| --- | --- | --- | --- | +| `videoTitle` | 必填 | U | 标题 | +| `videoDesc` | 可选 | U | 说明文本域 | +| `coverOssId` | 可选 | F/I | 封面上传、预览、隐藏 ID | +| `videoOssId` | 必填 | F/I | 视频文件上传；不得输入 ID | +| `durationSeconds` | 可选 | F/A/R | 从视频元数据读取，只读显示 | +| `sortOrder` | 可选 | U/S | 管理高级设置 | +| `status` | 可选 | S | 0 正常、1 停用 | +| `genealogyId`、`videoId` | path | I/A | 上下文和记录 | + +流程：选视频 → 分片上传 → 得到 `videoOssId` → 可选封面上传 → 填标题说明 → 保存 → 重新读取详情。 + +当前视频列表、详情、新增和修改均返回泛型对象/列表。C17 完成前可以完成静态表单布局和 `ApiClient` 契约测试，但不得把真实 CRUD 页面标记为已完成。 + +### 7.10 贺礼邀约与祭祀 + +邀约字段： + +| 字段 | 必填性 | 类型 | 页面处理 | +| --- | --- | --- | --- | +| `inviteeUserIds` | 必填 | S/I | 家谱成员多选；提交完整名单，空数组表示取消全部未响应邀请 | +| `inviteStatus` | 必填 | S | 当前用户只能选择 ACCEPTED 接受或 DECLINED 拒绝 | +| `genealogyId`、`ceremonyId` | path | I/A | 活动上下文 | + +邀约响应在 `profile-gift.html` 展示： + +- `invitationId`、`genealogyId`、`ceremonyId`、`inviteeUserId`：I； +- `inviteStatus`：R，PENDING/ACCEPTED/DECLINED/CANCELED 徽标； +- `inviteVersion`：I/R，只在管理审计需要时显示； +- `deliveredTime`、`readTime`、`responseTime`：R； +- `ceremonyTitle`、`ceremonyTime`、`location`、`locationAddress`：R； +- `longitude`、`latitude`：地图定位内部值，页面显示地图/地址而非原始数字。 + +“我的邀请”接口有完整响应，可独立实现接受/拒绝流程。管理端替换受邀人依赖 C16，且必须先有真实活动 ID。 + +当前没有祭祀活动列表、详情、新增、修改和献礼列表/新增接口。现有 `profile-gift-edit.html` 中的 `ceremonyType`、`ceremonyTitle`、`ceremonyTime`、`location`、`ceremonyDesc`、`coverOssId` 不属于任何现有 PC 写入 DTO，必须继续保持禁用，不得向猜测路径提交。 + +两条删除接口只能在后端补齐列表和详情、产生稳定 ID 后开放： + +- 删除活动是逻辑删除活动及祭品并释放封面引用； +- 删除祭品只操作被选中的真实 `giftId`； +- 删除确认必须说明影响范围。 + +### 7.11 成长记录 + +页面：`profile-growth.html`、`profile-growth-edit.html`。 + +| 字段 | 必填性 | 类型 | 页面处理 | +| --- | --- | --- | --- | +| `lineagePersonId` | 可选 | S/I | 世系人物搜索选择器，禁止 ID 输入框 | +| `recordType` | 可选 | U 或 S | C12 未解决前按 Apifox 明确结果决定，不能猜枚举 | +| `recordTitle` | 必填 | U | 标题 | +| `recordContent` | 可选 | U | 正文编辑器 | +| `recordDate` | 可选 | S | 日期控件，等待 C13 明确格式 | +| `remindTime` | 可选 | S | 日期时间控件 | +| `mediaOssIds` | 可选 | F/I | 多附件上传 | +| `sortOrder` | 可选 | U/S | 管理高级设置 | +| `status` | 可选 | S | 0 正常、1 停用 | + +列表、详情、新增和修改响应仍是泛型对象。补齐 `GrowthRecordView` 前不得展示原始 JSON，也不得猜 `recordId` 开启编辑和删除。 + +### 7.12 亲友记录 + +页面：`profile-relative.html`、`profile-relative-edit.html`。 + +| 字段 | 必填性 | 类型 | 页面处理 | +| --- | --- | --- | --- | +| `relativeName` | 必填 | U | 亲友姓名 | +| `relationName` | 可选 | U | 关系名称 | +| `eventName` | 可选 | U | 事件名称 | +| `eventTime` | 可选 | S | 日期时间选择器 | +| `giftAmount` | 可选 | U | 金额输入，明确精度和非负规则后校验 | +| `recordContent` | 可选 | U | 内容 | +| `mediaOssIds` | 可选 | F/I | 多附件上传 | +| `sortOrder` | 可选 | U/S | 管理高级设置 | +| `status` | 可选 | S | 0 正常、1 停用 | + +补齐 `RelativeRecordView` 前只完成页面字段布局和请求契约，不开放真实列表、编辑和删除。 + +### 7.13 备忘录 + +页面：`profile-memo.html`、`profile-memo-edit.html`。 + +| 字段 | 必填性 | 类型 | 页面处理 | +| --- | --- | --- | --- | +| `memoTitle` | 必填 | U | 标题 | +| `memoContent` | 可选 | U | 内容 | +| `remindTime` | 可选 | S | 日期时间 | +| `completed` | 可选 | S | 应为开关；C11 明确提交值前保持禁用 | +| `mediaOssIds` | 可选 | F/I | 多附件上传 | +| `sortOrder` | 可选 | U/S | 管理高级设置 | +| `status` | 可选 | S | 0 正常、1 停用 | + +`completed` 表示业务完成状态，`status` 表示记录正常/停用，两者不能合并。补齐 `MemoView` 前不得猜 `memoId` 或响应字段。 + +### 7.14 功德记录 + +页面：`profile-merit.html`、`profile-merit-edit.html`。 + +| 字段 | 必填性 | 类型 | 页面处理 | +| --- | --- | --- | --- | +| `donorName` | 必填 | U | 功德人姓名 | +| `meritType` | 可选 | S | donation 捐赠、repair 修祠、public 公益、other 其他 | +| `meritTitle` | 必填 | U | 标题 | +| `meritContent` | 可选 | U | 内容 | +| `amount` | 可选 | U | 金额 | +| `meritTime` | 可选 | S | date-time | +| `sortOrder` | 可选 | U/S | 管理高级设置 | +| `status` | 可选 | S | 0 正常、1 停用 | + +现有页面错误地使用了 `service`，但契约枚举中不存在该值；必须删除 `service`，增加 `repair` 和 `public`。现有页面还缺少 `sortOrder`、`status`。 + +列表、详情、新增和修改仍是泛型响应。补齐 `MeritRecordView` 后再开放完整 CRUD。 + +### 7.15 消息通知 + +页面：`profile-messages.html`。 + +| 字段 | 必填性 | 类型 | 页面处理 | +| --- | --- | --- | --- | +| `readStatus` | 可选 query | S | 全部=省略、未读=0、已读=1 | +| `notificationId` | 单条已读必填 path | I/A | 从被点击通知记录带入 | +| 未读数量 `data` | 响应 | R | 顶部徽标，int64 按安全数值/字符串处理 | + +通知列表当前是 `ListResult`，没有通知 ID、标题、正文、类型、时间、已读状态和目标深链。补齐 `NotificationView` 前： + +- 可以调用未读数量和全部已读； +- 不得展示原始对象； +- 不得猜 `notificationId` 开放单条已读； +- 不得根据未声明字段拼详情跳转。 + +### 7.16 当前只有删除能力的模块 + +| 模块 | 当前操作 | 页面策略 | | --- | --- | --- | -| `POST /genealogy/pc/files/upload` | 头像、文章封面、相册照片、祭祀封面、记录附件 | 单文件上传 | -| `POST /genealogy/pc/files/resumable/init` | 视频、大文件 | 初始化分片任务 | -| `POST /genealogy/pc/files/resumable/chunk` | 视频、大文件 | 上传单个分片 | -| `POST /genealogy/pc/files/resumable/complete` | 视频、大文件 | 合并分片并返回文件 | -| `POST /genealogy/pc/files/reference` | 所有业务保存成功后 | 绑定业务引用 | -| `DELETE /genealogy/pc/files/reference` | 替换或删除业务文件后 | 解除业务引用 | - -状态：当前三条均为分片初始化、上传分片、完成分片。初始化要求 `fileName`、`fileSize`、`fileMd5`、`chunkSize`、`totalChunks`，可附 `contentType`、`bizType`、`usageScene`；分片为 multipart 的 `uploadId`、`chunkIndex`、`chunkMd5`、`file`；完成要求 `uploadId`、`fileMd5`、`fileSize`。所有文件先初始化，普通小文件可根据 `instant=true` 直接使用 OSS 信息，但初始化响应 Schema 未展开，页面不猜测 `uploadId`/`ossId`/`instant`，头像上传保持阻止。 - -已核验的分片/引用约束： - -- 初始化必填 `fileName`、`fileSize`、`fileMd5`、`chunkSize`、`totalChunks`，可选 `contentType`、`bizType`、`usageScene`；接口说明规定 `instant=true` 时直接使用返回的 OSS 信息。当前响应仍是未展开字段的 `ObjectResult`，因此不开放续传页面流程。 -- 分片上传 multipart 必填 `uploadId`、`chunkIndex`、`chunkMd5`、`file`；完成上传必填 `uploadId`、`fileMd5`、`fileSize`。 -- 绑定引用必填 `bizType`、`bizTable`、`bizId`、`bizField`，可选 `ossId` 或逗号分隔的 `ossIds`、`bizName`、`usageScene`、`usageName`；解除引用只必填 `bizTable`、`bizId`、`bizField`。 -- 具体业务的 `bizType`、`bizTable`、`bizField` 目前没有由对应业务接口声明，不在页面中猜测创建或解除引用规则。 - -### 4.4 行政区划（4） - -| 接口 | 使用页面 | 用途 | -| --- | --- | --- | -| `GET /genealogy/region/children` | 个人资料、创建/编辑家谱 | 获取下级区划 | -| `GET /genealogy/region/path/{regionCode}` | 同上 | 区划编码回显 | -| `GET /genealogy/region/search` | 同上 | 关键词搜索地区 | -| `GET /genealogy/region/{regionCode}` | 同上 | 获取地区详情 | - -状态：四条路径和请求参数已直接核验；个人资料已使用，创建家谱页面待家谱接口补齐后复用同一个区划组件。`children` 的 `parentCode` 可选（不传查省级），`search` 必填 `keyword`、可选 `level` 和 `limit`，路径/详情使用必填 `regionCode`。当前 Apifox 的地区响应仍是未展开属性的通用对象/数组，页面已有的 `regionCode`、`regionName`、`regionLevel` 消费需在联调时以真实响应再确认，不能把导出快照当 Schema。 - -个人资料页当前流程： - -| 页面 | 页面流程 | 对接接口 | -| --- | --- | --- | -| `profile.html` | 读取当前资料、显示昵称/手机/生日/地区 | `GET /genealogy/pc/auth/profile` → `GET /genealogy/region/path/{regionCode}` | -| `profile-data.html` | 回填并保存昵称、性别、生日和头像 OSS ID | `GET /genealogy/pc/auth/profile` → `POST /genealogy/pc/files/upload` → `PUT /genealogy/pc/auth/profile` | -| `profile-data.html` | 回填、搜索、选择并保存现居地区 | `GET /genealogy/region/children` / `path` / `search` / `{regionCode}` → `PUT /genealogy/pc/auth/profile` | +| 内容文章 | 删除文章 | `profile-article*` 保持设计；没有列表/详情时不开放删除 | +| 相册 | 删除相册、删除照片 | `profile-album.html` 保持设计；不使用静态 ID 调删除 | +| 祭祀 | 删除活动、删除祭品 | 活动 CRUD 和礼物列表补齐前保持禁用 | -注意：当前严格使用 Apifox PC 声明的 `/genealogy/region/*`，页面和 `ApiClient` 不再维护其他区划路径。 +删除按钮必须由真实响应中的 ID 和权限字段产生。禁止用 DOM 序号、示例 ID 或 URL 猜测资源 ID。 -### 4.5 家族圈（14） +## 8. 分阶段执行顺序 -| 接口 | 使用页面 | 用途 | -| --- | --- | --- | -| `GET /genealogy/pc/genealogies/{genealogyId}/feeds` | `profile-feed.html` | 非分页动态列表 | -| `GET .../feeds/page` | `profile-feed.html` | 动态分页 | -| `POST .../feeds` | `profile-feed-edit.html` | 发布动态 | -| `GET .../feeds/{feedId}` | 编辑页、动态详情页 | 动态详情 | -| `PUT .../feeds/{feedId}` | `profile-feed-edit.html` | 修改动态 | -| `DELETE .../feeds/{feedId}` | 列表、详情 | 删除动态 | -| `POST .../feeds/{feedId}/likes` | 列表、详情 | 点赞 | -| `DELETE .../feeds/{feedId}/likes` | 列表、详情 | 取消点赞 | -| `GET .../feeds/{feedId}/comments` | 动态详情 | 评论列表 | -| `GET .../feeds/{feedId}/comments/page` | 动态详情 | 评论分页 | -| `POST .../feeds/{feedId}/comments` | 动态详情 | 评论或回复 | -| `DELETE .../feeds/{feedId}/comments/{commentId}` | 动态详情 | 删除评论 | -| `GET .../comments/{commentId}/replies` | 动态详情 | 直接回复列表 | -| `GET .../comments/{commentId}/replies/page` | 动态详情 | 直接回复分页 | +### 阶段 0：冻结契约 -状态：14 个操作已在本轮 Apifox PC 详情中逐条复核，现有 `ApiClient` 路径、分页 query 和页面调用均一致。`profile-feed.html` 已接入动态分页、点赞、一级评论、发表回复和按需展开直接回复；评论及回复 ID 在路径中按字符串传递。 +工作： -已核验的评论约束： +1. 完成第 5 节 C01-C20 的本阶段相关项。 +2. 从 Apifox 重导 OpenAPI。 +3. 写契约快照测试，统计操作、请求字段、required、枚举、response `$ref`。 +4. 确认旧路径和旧字段会失败，不保留兼容代码。 -- 发表评论请求体只有必填 `commentContent`（最多 1000 字）和可选 `parentCommentId`；不传或传 `null` 表示一级评论，不能发送旧字段 `content` 或未声明的 `replyUserId`。 -- 一级评论接口只返回正常展示的一级评论；直接回复使用 `GET .../comments/{commentId}/replies`，分页使用 `GET .../comments/{commentId}/replies/page`。两类分页均为 `pageNum`、`pageSize`。 -- 评论响应字段为 `commentContent`、`commentId`、`parentCommentId`、`appUserNickName`、`replyCount`、`commentLevel`、`userDeleted` 等；作者删除后 `commentContent` 为 `null` 且 `userDeleted` 为 `1`，页面显示占位而非把响应视为异常。 +验证： -页面规划： +- JSON 可被解析； +- 实际接口数与收口后的 Apifox 一致； +- 0 个重复逻辑路径； +- 本轮实现模块不存在泛型业务响应； +- 登录注册等公开接口不带 Authorization。 -- `profile-feed.html` 只负责动态分页和轻量操作。 -- 新增动态详情页，负责完整正文、评论、回复、通知跳转和分享深链。 -- 评论 DTO 必须返回稳定的 `commentId`、`parentCommentId`、`replyCount`、发布人和权限字段。 +### 阶段 1：请求基础设施、验证和认证 -### 4.6 字辈谱（6） +工作： -| 接口 | 使用页面 | 用途 | -| --- | --- | --- | -| `GET .../generation-poems` | 家谱主页、世系展示 | 查询正常字辈谱 | -| `GET .../generation-poems/management` | `profile-generation.html` | 查询字辈维护列表 | -| `POST .../generation-poems` | `profile-generation.html` | 新增字辈 | -| `PUT .../generation-poems/{poemId}` | `profile-generation.html` | 修改字辈 | -| `POST .../generation-poems/batch/preview` | `profile-generation.html` | 批量文本预览 | -| `POST .../generation-poems/batch/save` | `profile-generation.html` | 批量保存 | +1. 收口 `config.js`、`AxiosRequestUtil.js`、`ApiClient.js` 的 header、token、tenant 和错误处理。 +2. 完成验证中心、登录、注册、短信、找回、换绑、注销、退出。 +3. 完成个人资料全部 6 个写入字段。 +4. 为每条认证流程测试 body 中不存在 `clientId`、`sceneCode` 和旧验证码字段。 -状态：6 个操作均已在 Apifox PC 详情中核验并完成客户端路径映射；`profile-generation.html` 已接入管理列表、新增、修改、停用/恢复、批量预览和批量保存。管理列表仅内容编辑者可访问，403 时页面明确显示无权限并禁用写操作；页面缺少真实 `genealogyId` 时不发请求，也不使用示例编号。 +验证： -规划： +- 密码、短信两种登录成功； +- 验证策略开/关两条路径都成功； +- 一次性 `validToken` 不能复用； +- 401 清除登录态，403 保留登录态； +- 确认密码等 V 类字段未进入请求。 -- 页面只提供新增、修改和批量导入。 -- 如果产品要求物理删除，先在 Apifox 增加删除接口；当前修改接口的 `status` 仅按其已声明的正常/停用语义使用，不作为删除替代。 -- 批量预览必须展示解析错误、重复代次、原/新状态和将被覆盖的记录，用户确认后才能保存；前端按 Apifox 限制校验总文本不超过 26000 字符、单个字辈不超过 50 字符、一次最多 500 代。 -- 字辈新增、修改、状态切换、批量预览和批量保存执行期间锁定写入口，避免重复提交；批量输入示例必须使用 Apifox 已声明的分隔符，连续文本视为一个字辈。 +### 阶段 2：文件上传和区划 -### 4.7 世系人物（12） +前提：C01、C08、C09、C10、C13 完成。 -| 接口 | 使用页面 | 用途 | -| --- | --- | --- | -| `GET .../lineage/persons` | `profile-tree.html` | 成员总览 | -| `GET .../lineage/persons/page` | `profile-tree.html` | 人物分页与关键词搜索 | -| `GET .../lineage/persons/options` | 关系选择、成长记录 | 人物下拉选项 | -| `GET .../lineage/tree` | `profile-tree.html` | 世系树 | -| `POST .../lineage/persons` | `profile-tree.html` | 新增人物 | -| `GET .../lineage/persons/{personId}` | 树内详情、人物详情 | 人物详情 | -| `PUT .../lineage/persons/{personId}` | 人物编辑 | 修改人物 | -| `DELETE .../lineage/persons/{personId}` | 人物详情 | 逻辑停用人物 | -| `POST .../persons/{personId}/children` | 关系维护 | 添加子女 | -| `POST .../persons/{personId}/parents` | 关系维护 | 添加父母 | -| `POST .../persons/{personId}/siblings` | 关系维护 | 添加兄弟姐妹 | -| `POST .../persons/{personId}/spouses` | 关系维护 | 添加配偶 | +工作： -状态：12 个操作均已在 Apifox PC 详情中核验并完成客户端路径映射；`profile-tree.html` 已接入成员总览、树、人物分页搜索与翻页、人物选项、详情、新增、修改、逻辑停用，以及新增父母、配偶、兄弟姐妹、子女。写入和停用请求执行期间会锁定操作入口，页面缺少真实 `genealogyId` 时不发请求。 +1. 实现单分片小文件和多分片大文件同一流程。 +2. 实现秒传、进度、重试、重复提交锁。 +3. 只保留一套区划 API，并实现级联、搜索、路径回显。 +4. 所有业务页移除可见 OSS ID 输入框。 -已核验的关键约束： +验证： -- 人物 DTO 使用 `name`、`generation`、`biography`，不是旧页面字段 `personName`、`generationNo`、`introduction`。 -- `DELETE .../persons/{personId}` 的语义是逻辑停用，不物理删除；人物存在正常子女时后端会拒绝停用。 -- 四个关系接口都接收完整的 `LineagePersonBody` 来新建关系人物，并非把两个已有 `personId` 绑定在一起；当前没有解除关系接口。 -- `LineagePersonTreeView` 以 `spouses`、`children` 递归返回关系树；页面避免将不安全的数值型 int64 ID 用于后续写请求。 +- 普通图片、最后一片不足 chunkSize、大视频、秒传分别通过； +- MD5、大小、分片数量与初始化一致； +- 页面刷新后的业务对象能重新显示文件； +- 区划不同时请求两套路径。 -规划： +### 阶段 3：家谱上下文 -- `profile-tree.html` 负责树、搜索、人物详情、快捷新增和关系人物新增。 -- 人物详情可先使用抽屉；消息和分享需要深链时再补独立详情页。 -- Apifox 需补充稳定的关系 ID 与解除关系接口。 -- 删除人物前必须返回影响范围，禁止前端猜测是否级联删除子女或关系。 -- `GenealogyMember` 是账号和权限成员，`LineagePerson` 是谱系人物，两者不能合并。 +前提：C14 完成，或产品正式给出可验证的外部上下文契约。 -### 4.8 内容文章（1） +工作： -现有接口： +1. `profile-common.js` 成为 `genealogyId` 的唯一 owner。 +2. 我的家谱页提供真实选择入口。 +3. 所有家谱内链接传播同一个 ID，切换家谱时清空旧页面状态。 -```text -DELETE /genealogy/pc/genealogies/{genealogyId}/articles/{articleId} -``` +验证： -使用位置：`profile-article.html` 的删除操作。 +- 无 ID 不发请求； +- 切换两个家谱不串数据； +- ID 始终按字符串处理； +- 不存在示例 ID 和 APP 请求。 -当前不能启用真实文章管理，因为缺少： +### 阶段 4：已具备明确 DTO 的家谱模块 -- 文章列表/分页 -- 文章详情 -- 新增文章 -- 修改文章 -- 文章分类 -- 发布、下线和公开可见性 -- 官网公开文章详情 +顺序： -状态：删除操作已核验并映射为 `ApiClient.deleteArticle(genealogyId, articleId)`。两个路径参数均为必填 int64，登录和 `clientid` 必填，响应是 `VoidResult`；没有列表、详情或稳定 `articleId` 来源，页面不开放删除。 +1. 家族圈； +2. 字辈谱； +3. 世系人物； +4. 我的贺礼邀请。 -规划：接口补齐前，`profile-article.html`、`profile-article-edit.html` 和 `article-detail.html` 保持设计预览，不单独接入删除接口。 +每个模块采用同一闭环： -### 4.9 相册（2） +1. `ApiClient` 方法和契约测试； +2. 列表/详情读取； +3. 新增； +4. 修改； +5. 删除/停用； +6. 权限、空状态、错误状态、重复提交； +7. 写入后重新读取验证。 -现有接口： +### 阶段 5：补齐 DTO 后的资源模块 -```text -DELETE /genealogy/pc/genealogies/{genealogyId}/albums/{albumId} -DELETE /genealogy/pc/genealogies/{genealogyId}/albums/{albumId}/photos/{photoId} -``` +顺序： -使用位置：`profile-album.html` 的删除相册、删除照片操作。 +1. 视频； +2. 成长记录； +3. 亲友记录； +4. 备忘录； +5. 功德记录； +6. 消息通知。 -当前缺少相册列表、详情、新增、修改，以及照片列表、新增、修改和文件引用。接口补齐前不启用删除按钮。 +任何模块的 View/List DTO 未补齐时，只完成表单布局和契约测试，不宣称真实功能完成。 -状态：两个删除操作已核验并映射为 `deleteAlbum(genealogyId, albumId)` 与 `deleteAlbumPhoto(genealogyId, albumId, photoId)`。所有路径 ID 是必填 int64，登录和 `clientid` 必填，响应是 `VoidResult`；删除相册会由后端逻辑删除相册及照片，并释放封面和照片文件引用。没有列表/详情或稳定 ID 来源，页面不开放删除。 +### 阶段 6：后端补齐后再开放的模块 -### 4.10 视频（1） - -现有接口： - -```text -DELETE /genealogy/pc/genealogies/{genealogyId}/videos/{videoId} -``` - -使用位置：`profile-video.html` 的删除操作。 - -当前缺少视频列表、详情、新增、修改、发布状态、公开播放详情以及文件引用。本轮只映射删除契约；后端补齐 PC 读写接口后，再结合分片上传实施完整视频流程。 - -状态：删除操作已核验并映射为 `deleteVideo(genealogyId, videoId)`。两个路径参数是必填 int64，登录和 `clientid` 必填，响应是 `VoidResult`；后端逻辑删除视频并释放视频和封面文件引用。没有列表/详情或稳定 ID 来源，页面不开放删除。 - -### 4.11 祭祀/典礼（2） - -现有接口： - -```text -DELETE /genealogy/pc/genealogies/{genealogyId}/ceremonies/{ceremonyId} -DELETE /genealogy/pc/genealogies/{genealogyId}/ceremonies/{ceremonyId}/gifts/{giftId} -``` - -使用位置：`profile-gift.html` 的删除活动、删除献礼操作。 - -当前缺少活动列表、详情、新增、修改，以及献礼列表和新增。接口补齐前不启用删除。 - -状态：两个删除操作已核验并映射为 `deleteCeremony(genealogyId, ceremonyId)` 与 `deleteCeremonyGift(genealogyId, ceremonyId, giftId)`。所有路径 ID 是必填 int64，登录和 `clientid` 必填，响应是 `VoidResult`；删除祭祀活动会由后端逻辑删除活动及祭品，并释放活动封面文件引用。没有列表/详情或稳定 ID 来源，页面不开放删除。 - -命名需先拍板： - -- 如果只处理祖先祭祀，DTO 和页面只保留祭祀类型。 -- 如果还处理婚礼、生日、升学等活动，Apifox 目录应改为“典礼/贺礼”，避免接口名称和产品含义不一致。 - -### 4.12 贺礼邀约（4） - -```text -PUT /genealogy/pc/genealogies/{genealogyId}/ceremonies/{ceremonyId}/invitees -GET /genealogy/pc/genealogies/{genealogyId}/ceremonies/{ceremonyId}/invitations -PUT /genealogy/pc/genealogies/{genealogyId}/ceremonies/{ceremonyId}/invitations/me -GET /genealogy/pc/genealogies/ceremony-invitations/mine -``` - -状态：四条已逐条核验并映射为 `replaceCeremonyInvitees`、`ceremonyInvitations`、`respondCeremonyInvitation`、`myCeremonyInvitations`。替换受邀人只接受必填 `inviteeUserIds`（空数组取消全部待响应邀请）；当前用户响应只接受 `inviteStatus: ACCEPTED|DECLINED`。前三条需要真实 `genealogyId` 和 `ceremonyId`，最后一条只查询当前用户。当前仍没有活动列表、创建、详情或献礼接口，`profile-gift.html` / `profile-gift-edit.html` 不开启操作。 - -### 4.13 消息通知（4） - -```text -GET /genealogy/pc/notifications?readStatus=0|1 -GET /genealogy/pc/notifications/unread-count -POST /genealogy/pc/notifications/{notificationId}/read -POST /genealogy/pc/notifications/read-all -``` - -状态：四条已逐条核验并映射为 `notifications`、`unreadNotificationCount`、`markNotificationRead`、`markAllNotificationsRead`。列表的元素 DTO 在当前 PC 详情未展开，不能假设通知标题、正文、时间或 `notificationId` 的响应字段。`profile-messages.html` 因此只安全展示原始记录，并开放无歧义的未读数、刷新和全部已读；单条已读继续等待列表元素 Schema。 - -### 4.14 族务记录（16） - -#### 成长记录（5） - -```text -GET .../growth-records -POST .../growth-records -GET .../growth-records/{recordId} -PUT .../growth-records/{recordId} -DELETE .../growth-records/{recordId} -``` - -使用页面：`profile-growth.html`、`profile-growth-edit.html`。 - -用途：列表、新增、详情、编辑、删除，可关联世系人物和附件。 - -状态：5 个操作均已在 Apifox PC 详情中逐条核验，`ApiClient` 已映射为 `growthRecords`、`createGrowthRecord`、`growthRecordDetail`、`updateGrowthRecord`、`deleteGrowthRecord`。全部需要登录，使用必填 `clientid` 请求头；`genealogyId` 和 `recordId` 都是 int64 路径参数。 - -已核验的请求/响应约束： - -- 新增和修改使用 `GrowthRecordBody`：`recordTitle` 必填；`lineagePersonId`、`recordType`、`recordContent`、`recordDate`、`remindTime`、`mediaOssIds`、`sortOrder`、`status` 可选。`mediaOssIds` 为英文逗号分隔的正整数 OSS ID。 -- 列表响应是 `ListResult`，但元素 DTO 未在 Apifox 展开；详情、新增和修改是元素 DTO 未展开的 `ObjectResult`，删除是 `VoidResult`。因此不能假设响应含有 `recordId`、标题、权限或文件引用字段。 -- `profile-growth.html` 已请求列表并安全地原样展示数组元素；`profile-growth-edit.html` 已开放新增和写入防重。因为没有可安全使用的响应 ID 或详情字段，详情、编辑和删除入口保持关闭，等待 Apifox 补齐响应 DTO。 - -#### 亲友往来（5） - -```text -GET .../relative-records -POST .../relative-records -GET .../relative-records/{relativeId} -PUT .../relative-records/{relativeId} -DELETE .../relative-records/{relativeId} -``` - -当前没有独立页面。现有 `profile-memo.html` 同时写了“人情往来”和“备忘提醒”，会导致两个资源边界混乱。 - -状态：5 个操作已在 Apifox PC 详情中逐条核验，`ApiClient` 已映射为 `relativeRecords`、`createRelativeRecord`、`relativeRecordDetail`、`updateRelativeRecord`、`deleteRelativeRecord`；全部需要登录和必填 `clientid` 请求头。`RelativeRecordBody` 的 `relativeName` 必填，`relationName`、`eventName`、`eventTime`、`giftAmount`、`recordContent`、`mediaOssIds`、`sortOrder`、`status` 可选。列表/详情元素 DTO 未展开，故新增 `profile-relative.html` / `profile-relative-edit.html` 仅开放原始列表展示和新增，不猜测 `relativeId` 后开放详情、编辑或删除。 - -规划：将“人亲簿/亲友往来”和“备忘录”拆成两个 Tab 或两组页面： - -- 亲友往来：亲友、关系、事项、时间、礼金、说明。 -- 备忘录：待办、提醒时间、完成状态、附件。 - -#### 备忘录（5） - -```text -GET .../memos -POST .../memos -GET .../memos/{memoId} -PUT .../memos/{memoId} -DELETE .../memos/{memoId} -``` - -使用页面：`profile-memo.html`、`profile-memo-edit.html`。 - -用途：家族事务、纪念事项、待办提醒和完成状态。 - -状态：5 个操作已在 Apifox PC 详情中逐条核验，`ApiClient` 已映射为 `memos`、`createMemo`、`memoDetail`、`updateMemo`、`deleteMemo`；全部需要登录、必填 `clientid` 请求头，`genealogyId` 和 `memoId` 都是 int64 路径参数。新增和修改使用已核验的备忘录请求体：`memoTitle` 必填，`memoContent`、`remindTime`、`completed`、`mediaOssIds`、`sortOrder`、`status` 可选；`completed` 是 string，`mediaOssIds` 是英文逗号分隔的正整数 OSS ID。列表响应是元素 DTO 未展开的 `ListResult`，详情/新增/修改是元素 DTO 未展开的 `ObjectResult`，删除是 `VoidResult`，因此 `profile-memo.html` / `profile-memo-edit.html` 仅开放原始列表展示和新增，不猜测 `memoId` 后开放详情、编辑或删除。 - -#### 功德记录（1） - -```text -DELETE .../merit-records/{meritId} -``` - -使用位置：`profile-merit.html` 的删除操作。 - -当前缺少列表、新增、详情和修改。接口补齐前，`profile-merit.html` 与 `profile-merit-edit.html` 保持设计预览。 - -状态：该删除操作已在 Apifox PC 详情中核验，`ApiClient.deleteMeritRecord(genealogyId, meritId)` 映射 `DELETE /genealogy/pc/genealogies/{genealogyId}/merit-records/{meritId}`；`genealogyId`、`meritId` 是必填 int64 路径参数，登录和 `clientid` 必填，响应为 `VoidResult`。没有真实列表、详情或稳定 `meritId` 来源，页面不开放删除。 - -## 5. 后端后续补充清单（当前不对接） - -本节只登记当前 PC 85 个接口之外的业务缺口，不借用 APP 路径、参数或 DTO。后端把新接口正式加入 Apifox PC 后，再更新接口数量和页面对接计划。 - -### 后续优先级 1：家谱上下文与成员 - -这是形成完整 PC 导航闭环的前置能力： - -- 我的家谱列表 -- 家谱下拉选项 -- 公开家谱搜索 -- 家谱详情/概览 -- 创建、修改家谱 -- 申请加入、我的申请、撤销申请 -- 待审核申请、审核申请 -- 家谱成员列表/选项 -- 修改成员角色 -- 移除成员 -- 退出家谱 -- 转让家谱 -- 邀请码/邀请链接的生成、校验和失效 - -### 后续优先级 2：当前只有删除操作的模块 - -- 文章：列表、详情、新增、修改、分类、发布状态。 -- 相册：相册 CRUD、照片列表/新增/修改、文件引用。 -- 视频：列表、详情、新增、修改、发布状态、文件引用。 -- 祭祀/典礼：活动 CRUD、献礼列表/新增。 -- 功德录：列表、详情、新增、修改。 - -### 后续优先级 3：已有主体但缺少的操作 +范围： +- 文章； +- 相册/照片； +- 祭祀活动/祭品； +- 管理员邀约名单； +- 指定账号绑定世系人物； +- 家谱和成员管理； - 世系关系解除。 -- 字辈删除或停用。 -- 家族圈评论回复 DTO 和权限字段。 -- 删除人物、文章、相册、视频、祭祀等操作的引用清理规则。 -- 官网公开内容的无登录只读接口。 -## 6. 页面与接口实施顺序 +这些模块不允许通过 APP 接口或猜测路径提前实现。 -### 阶段 0：锁定当前 PC 契约 +## 9. 文件级施工建议 -目标： +执行 AI 应优先修改现有 owner，避免页面各自复制逻辑： -- 直接在 Apifox 客户端中核对当前 PC 目录。 -- 锁定 15 个目录、85 个操作及各目录数量，作为当前唯一对接清单。 -- 为每个操作在 Apifox 中确认 method、path、请求 DTO、响应 DTO、权限和错误码；可选导出仅用于生成本地契约测试快照。 -- 排除所有未进入 Apifox PC 目录的接口，不引用 APP 或其他公开文档补充本轮范围。 -- 统一 token、ID、`ossId`、分页、日期和枚举。 +| 文件 | 职责 | +| --- | --- | +| `PC.openapi.json` | 当次 Apifox 导出快照，不手工补字段 | +| `config.js` | 环境、API 基础地址、非敏感客户端配置 | +| `utils/ApiClient.js` | 所有正式 PC method/path/query/body | +| `utils/AxiosRequestUtil.js` | header、鉴权、响应解包、401/403 | +| `utils/FormUtil.js` | 表单取值、空可选字段省略、前端校验 | +| `public/js/profile-common.js` | 登录页外的家谱上下文 | +| `public/js/upload-pages.js` | 唯一上传流程 | +| `public/js/auth-pages.js` / `security-pages.js` | 认证业务流程 | +| `public/js/feed-pages.js` | 家族圈 | +| `public/js/generation-pages.js` | 字辈 | +| `public/js/lineage-pages.js` | 世系 | +| `public/js/growth-pages.js`、`relative-pages.js`、`memo-pages.js` | 对应族务记录 | +| 新增专用视频/功德/邀约脚本 | 仅在 DTO 完整后新增 | -验收： +不得创建一个包揽所有业务的巨型页面脚本，也不得为了单一页面引入通用框架。 -- Apifox PC 操作数等于 85，目录数量与第 1 节一致。 -- 第 4 节中的每个接口都能在 Apifox 客户端中找到，且没有 APP 或其他目录的接口混入当前清单。 -- 同一接口只有一套 path 和 DTO。 -- 当前计划不再引用 APP 路径或 APP DTO。 +## 10. 测试与验收 -### 阶段 1：已接模块回归与补齐 +### 10.1 必须新增或更新的测试 -范围： +1. OpenAPI 契约快照： + - operation 数； + - method/path； + - body Schema； + - required； + - enum； + - response `$ref`； + - 公开/鉴权标记。 +2. `ApiClient` 契约测试： + - URL、query、body、header； + - int64 ID 不转 Number； + - 可选空字段被省略； + - 旧路径/旧字段不存在。 +3. 页面字段覆盖测试： + - 每个请求 Schema 字段都能在本规划的 U/S/F/A/I/V 分类中找到； + - 用户可编辑字段有对应 `name`； + - 自动字段没有可见文本输入； + - 枚举选项和值与 Apifox 一致。 +4. 流程测试： + - 验证与短信； + - 上传； + - 家谱上下文； + - 列表 → 详情 → 编辑 → 重读； + - 删除/停用； + - 401/403/404/409/422/429。 +5. 安全测试： + - 富文本经过净化； + - 密码、token、validToken 不写日志； + - 外链和上传文件类型受限； + - 错误消息不直接插入 HTML。 -1. 认证登录 12 个。 -2. 验证中心 3 个。 -3. 行政区划 4 个。 -4. 文件上传 3 个。 -5. 家族圈 14 个。 +### 10.2 建议验证命令 -执行重点： +先跑最小相关测试，再跑全量： -- 先核对现有 `ApiClient` 与当前 PC 契约，保留已正确对接的部分。 -- 补齐文件分片、文件引用，以及家族圈评论回复列表和分页等当前 PC 已有但页面尚未完整使用的能力。 -- 统一 401、403、业务错误、空状态和重复提交处理。 +```powershell +node --test tests/api-client-contract.test.js +node --test tests/auth-pages.test.js tests/captcha-pages-contract.test.js +node --test tests/feed-pages.test.js tests/generation-pages.test.js tests/lineage-pages.test.js +node --test tests/growth-pages.test.js tests/relative-pages.test.js tests/memo-pages.test.js tests/notification-pages.test.js +node --test tests/*.test.js +``` -当前施工进度： +执行 AI 若新增测试文件，应在本节补上精确命令。 -1. 已完成认证、验证码与账号安全流程，包含登录、短信登录、注册、找回密码、换绑、注销和退出；本轮已按当前 PC 契约将验证码与短信发送迁移至 `operationCode` 路径并移除 `sceneCode`/body `clientId`。密码登录已接入 `password-login` 的验证策略和 TAC `validToken` 提交。 -2. 已完成个人资料读取与保存、行政区划三级联动/搜索/回显；资料和区划请求统一携带登录态，`ossId` 在浏览器端保持字符串。头像上传等待当前 PC 分片初始化响应 Schema 补齐后再开放回填。 -3. 当前仅保留文件分片初始化、分片和完成三条客户端契约；旧单文件上传、文件引用路径已删除。待后端补齐初始化响应 Schema 后，再开通头像上传闭环。 -4. 历史 79 条映射不能代替当前 85 条复核。本轮已完成当前 85/85 条的逐项 PC 详情复核：验证中心 3 条、认证登录 12 条、文件上传 3 条、家谱配额、家族圈 14 条、贺礼邀约、族务记录 16 条、消息通知、行政区划 4 条、字辈谱 6 条、世系人物 12 条和文章/相册/视频/祭祀 6 条。成长记录、亲友往来和备忘录的响应 DTO 仍待后端补齐，文章、相册、视频、祭祀和功德记录均只有删除孤岛接口，页面保持关闭。 -5. 已去除个人中心中的示例家谱卡片；所有无上下文的家谱业务入口先进入 `profile-families.html`，实际调用 PC 配额接口并在缺少真实 `genealogyId` 时保持阻止。 +### 10.3 模块完成定义 -验收： +一个模块只有同时满足以下条件才可标记完成： -- 登录、验证码、区划和上传流程只请求当前 PC 路径。 -- 家族圈列表、详情、点赞、评论和回复使用同一套 DTO 与计数字段。 -- 文件上传完成后按业务保存结果创建引用，删除业务数据时按后端规则解除引用。 +1. Apifox 契约无未决冲突。 +2. 所有请求字段已分类并落到页面。 +3. 列表和详情响应有明确 DTO。 +4. `ApiClient` 不存在旧路径或 fallback。 +5. 页面有加载、空、成功、校验失败、无权限和网络失败状态。 +6. 写操作防重复提交。 +7. 成功写入后通过重新读取验证。 +8. 相关测试和全量测试通过。 +9. 没有原始 JSON、手填 ID、示例业务数据或 APP 接口冒充真实能力。 -### 阶段 2：家谱内完整资源 +## 11. 执行完成后的报告格式 -范围与顺序： +执行 AI 每个阶段只报告： -1. 字辈谱 6 个。 -2. 世系人物 12 个。 -3. 成长记录 5 个（已完成契约映射、列表/新增页面；响应 DTO 缺口使详情/编辑/删除保持关闭）。 -4. 亲友往来 5 个（已完成契约映射、列表/新增页面；响应 DTO 缺口使详情/编辑/删除保持关闭）。 -5. 备忘录 5 个（已完成契约映射、列表/新增页面；响应 DTO 缺口使详情/编辑/删除保持关闭）。 +```text +Changed: 修改了哪些 owner、页面和契约。 +Verified: 运行了哪些测试，真实联调覆盖了哪些流程。 +Blocked: 哪些字段或流程仍缺 Apifox/后端契约，具体缺什么。 +Next: 下一阶段可以开始的最小范围。 +``` -执行前提： - -- 页面必须从 PC 的真实入口参数或运行时上下文取得 `genealogyId`。 -- 当前 PC 尚无家谱入口接口；没有真实 `genealogyId` 时只展示缺少上下文状态，不发请求、不写死 ID，也不调用 APP。 -- 只实现当前接口支持的操作；世系关系解除、字辈删除等缺口等待后端补充 PC 接口。 - -验收： - -- 所有请求均携带同一个真实 `genealogyId`，切换上下文后不串数据。 -- 列表、新增、详情、修改和删除严格按当前各资源的实际接口能力开放。 -- 世系树、人物详情和记录关联统一使用当前 PC 世系人物 DTO。 -- 无权限用户看不到写入口，后端 403 能正确呈现。 - -### 阶段 3：当前只有删除能力的模块 - -范围： - -1. 内容文章 1 个（已完成删除契约映射；缺少列表/详情，不开放页面删除）。 -2. 相册与照片 2 个（已完成删除契约映射；缺少列表/详情，不开放页面删除）。 -3. 视频 1 个（已完成删除契约映射；缺少列表/详情，不开放页面删除）。 -4. 祭祀/典礼与献礼 2 个（已完成删除契约映射；缺少列表/详情，不开放页面删除）。 -5. 功德记录 1 个（已完成删除契约映射；缺少列表/详情，不开放页面删除）。 - -处理方式： - -- 先完成删除接口的 `ApiClient` 契约映射和接口测试。 -- 因当前 PC 缺少列表、详情、新增或修改接口，页面继续保持预览状态，不开放孤立的删除按钮。 -- 后端补齐同模块 PC 接口后，再按完整资源流程启用页面。 - -验收： - -- 7 个删除操作的 method、path、路径参数和权限定义均与 Apifox PC 一致。 -- 当前页面不会因静态演示数据触发真实删除。 -- 未补齐的能力不会通过 APP 接口、猜测路径或模拟成功结果实现。 - -### 阶段 4：接收后端新增 PC 接口 - -每次后端新增或调整 PC 接口后： - -1. 先确认接口已正式进入 Apifox PC 目录。 -2. 更新基线数量、第 4 节用途映射和第 5 节缺口。 -3. 再安排相应页面、`ApiClient` 方法、契约测试和联调。 -4. 不因为 APP 已存在同类能力而提前实现。 - -## 7. 联调与测试要求 - -每个接口组按相同顺序验收： - -1. 直接在 Apifox PC 目录确认 method、path、DTO、枚举和权限。 -2. 给 `ApiClient` 增加业务方法。 -3. 增加契约测试，验证 method、path、query 和 body。 -4. 接页面加载、空状态、错误状态和成功状态。 -5. 验证 401、403、404、业务校验失败和重复提交。 -6. 验证写入后重新读取的数据与页面一致。 -7. 删除操作验证关联数据和文件引用处理。 - -禁止以下做法： - -- 页面直接写 Axios 请求。 -- 猜测字段名或同时兼容多个字段。 -- 使用 APP 路径补 PC 缺口。 -- 写死 `genealogyId`。 -- 把静态示例数据当成接口成功结果。 -- 只有删除接口时先开放删除按钮。 - -## 8. 后续业务待确认项（不阻塞当前 85） - -以下问题只影响后端后续新增 PC 接口，不改变本轮范围： - -1. “祭祀”究竟只指祖先祭祀，还是通用典礼/贺礼。 -2. 亲友往来是否从现有备忘录页面拆成独立 Tab，建议拆分。 -3. 字辈是否允许物理删除；建议优先停用。 -4. 删除世系人物是否允许级联删除关系；建议默认禁止并由接口返回影响范围。 -5. `feedback` 只用于意见反馈，还是要承担客服工单；若需要状态、回复和详情，应建立独立 Ticket 契约。 -6. 资料提醒是否只是通知的一种类型；若是，`NotificationDTO` 应提供稳定的通知类型和目标深链。 +不得用“应该可以”“大概完成”代替测试证据。 diff --git a/docs/交接文档.md b/docs/交接文档.md index 38249c7..530a9eb 100644 --- a/docs/交接文档.md +++ b/docs/交接文档.md @@ -1,7 +1,7 @@ # PC 接口对接交接文档 > 更新：2026-07-25 -> 状态：桌面版 Apifox 的 PC 目录现有 85 条接口，已于本轮逐条直接复核并与客户端映射比对。2026-07-24 的 79 条施工记录仅保留为历史；后续只在 PC 目录发生变动时，重新核验受影响的接口后再修改代码。 +> 历史交接记录：本文的 79/85 条接口数量已过期，不再作为 AI 施工依据。当前接口基线、字段分类、阻断项和执行顺序统一以 [PC接口对接规划.md](PC接口对接规划.md) 为准；执行前仍须在 Apifox 实时复核并重新导出。 ## 一、必须遵守的范围 diff --git a/docs/规划.md b/docs/规划.md index 1479825..82333c3 100644 --- a/docs/规划.md +++ b/docs/规划.md @@ -7,7 +7,7 @@ ## 当前基线 - 当前工作区共有 55 个 HTML 页面，现有页面之间没有指向不存在 HTML 页的站内链接。 -- `PC.openapi2.json` 是当前后端正式接口源，包含 37 个操作：认证登录 11、验证中心 4、文件上传 6、行政区划 4、家族圈 12。 +- 本文保留项目级历史规划，不再维护接口数量和字段契约。当前 PC 接口基线、字段页面归属和 AI 执行顺序统一见 [PC接口对接规划.md](PC接口对接规划.md)。 - 已完成真实接口闭环：注册、密码登录、短信登录、找回密码、个人资料、安全设置、头像上传、地区选择、家族圈动态。 - 家谱列表、家谱创建/加入、成员、权限、世系、谱文、相册、视频、贺礼、成长、备忘、功德、消息、反馈等页面已保留设计，但尚无对应正式接口，不得伪造请求或静态数据为真实业务。