xiangyuan-app/村社名片换肤等功能需增加接口.md

村社名片换肤等功能需增加接口

本文档仅供后端参阅，仅列出接口名称和输入输出参数，不涉及数据库设计。本文档的接口URL为建议值，实际实现时可根据情况调整。

---

功能界面参考

一、皮肤模块

提示：皮肤需要能在后台管理系统中进行增删改查（含皮肤图片上传、主题JSON配置等）。

1.1 获取皮肤列表（皮肤中心）

用途：分页获取所有可购买的皮肤列表（皮肤中心页面）。

项目	说明
方法	POST
路径	/village/skin/list

输入参数：

参数	类型	必填	说明
page	int	否	页码，默认1
pageSize	int	否	每页数量，默认20

输出：

{
  "total": 10,
  "list": [
    {
      "id": 1,
      "title": "默认皮肤",
      "desc": "默认的村社名片",
      "image": "https://xxx/thumb.jpg",
      "images": [ ... ],
      "price": 0
    }
  ]
}

字段	类型	说明
total	int	总数
list[].id	int	皮肤ID
list[].title	string	标题
list[].desc	string	描述
list[].image	string	封面缩略图URL
list[].images	string[]	皮肤预览图列表（多张可左右滑动）
list[].price	int	价格（乡源果），0=免费

---

1.2 获取推荐/热门皮肤

用途：主页换肤页顶部"热门皮肤"展示，仅展示少量推荐皮肤。

项目	说明
方法	POST
路径	/village/skin/recommend

输入参数：无

输出：

{
  "list": [
    {
      "id": 1,
      "title": "默认皮肤",
      "desc": "默认的村社名片",
      "price": 99,
      "image": "https://xxx/thumb.jpg",
      "images": [ ... ]
    }
  ]
}

字段	类型	说明
list[].id	int	皮肤ID
list[].title	string	标题
list[].desc	string	描述
list[].image	string	封面缩略图URL
list[].images	string[]	皮肤预览图列表（多张可左右滑动）

---

1.3 获取皮肤详情

用途：皮肤详情页，展示皮肤预览图和购买/使用按钮。需判断当前用户是否已购买。

项目	说明
方法	POST
路径	/village/skin/detail

输入参数：

参数	类型	必填	说明
id	int	是	皮肤ID
villageId	int	是	村社ID（用于判断是否已购买）

输出：

{
  "id": 1,
  "title": "默认皮肤",
  "desc": "默认的村社名片",
  "image": "https://xxx/thumb.jpg",
  "images": [
    "https://xxx/preview1.jpg",
    "https://xxx/preview2.jpg"
  ],
  "price": 99,
  "isBought": false
}

字段	类型	说明
id	int	皮肤ID
title	string	标题
desc	string	描述
image	string	封面缩略图URL
images	string[]	皮肤预览图列表（多张可左右滑动）
price	int	价格（乡源果）
isBought	bool	当前用户在当前村社是否已购买该皮肤

---

1.4 购买皮肤

用途：下单购买皮肤，返回订单信息和微信支付参数。

项目	说明
方法	POST
路径	/village/skin/buy

输入参数：

参数	类型	必填	说明
skinId	int	是	皮肤ID
villageId	int	是	村社ID

输出：

{
  "order": {
    "id": 100,
    "orderNo": "SK202501010001",
    "skinId": 1,
    "villageId": 10,
    "price": 99,
    "status": 0,
    "createtime": "2025-01-01 12:00:00"
  },
  "pay": {
    "appId": "wxXXX",
    "timeStamp": "1704096000",
    "nonceStr": "abc123",
    "package": "prepay_id=xxx",
    "signType": "MD5",
    "paySign": "signature"
  }
}

字段	类型	说明
order.id	int	订单ID
order.orderNo	string	订单号
order.price	int	支付金额
order.status	int	状态：0=待支付，1=已支付
pay	object	微信支付参数（若price=0则为null，直接购买成功）

---

1.5 使用皮肤

用途：将已购买的皮肤应用到指定村社。

项目	说明
方法	POST
路径	/village/skin/apply

输入参数：

参数	类型	必填	说明
skinId	int	是	皮肤ID
villageId	int	是	村社ID

输出：无特殊数据。

---

1.6 获取我的已购皮肤

用途：获取当前用户在指定村社下已购买的皮肤列表。

项目	说明
方法	POST
路径	/village/skin/myPurchased

输入参数：

参数	类型	必填	说明
villageId	int	是	村社ID

输出：

{
  "list": [
    {
      "id": 1,
      "title": "默认皮肤",
      "desc": "默认的村社名片",
      "image": "https://xxx/thumb.jpg",
      "price": 0
    }
  ]
}

---

1.7 获取皮肤订单列表

用途：分页获取皮肤购买订单记录。

项目	说明
方法	POST
路径	/village/skin/orderList

输入参数：

参数	类型	必填	说明
page	int	否	页码，默认1
pageSize	int	否	每页数量，默认20
villageId	int	否	村社ID（筛选）
userId	int	否	用户ID（筛选）

输出：

{
  "total": 5,
  "list": [
    {
      "id": 100,
      "skinTitle": "古风主题",
      "villageName": "大庆村",
      "price": 99,
      "status": 1,
      "statusText": "已支付",
      "createtime": "2025-01-01 12:00:00"
    }
  ]
}

字段	类型	说明
total	int	总数
list[].id	int	订单ID
list[].skinTitle	string	皮肤标题
list[].villageName	string	村社名称
list[].price	int	金额
list[].status	int	状态
list[].statusText	string	状态文本
list[].createtime	string	创建时间

---

1.8 获取村社当前皮肤数据

用途：获取村社当前使用的名片主题/皮肤完整数据（JSON 结构）。

该接口在进入村社名片主页时调用。

项目	说明
方法	POST
路径	/village/skin/current

输入参数：

参数	类型	必填	说明
villageId	int	是	村社ID

输出：返回一个 DynamicXPage JSON 对象，结构参考 src/pages/home/village/introd/data/DefaultCard.json。该 JSON 描述名片页面的布局、组件类型、颜色、按钮行为等。示例如下：

{
  "name": "VILLAGE",
  "type": "page",
  "props": {},
  "nodes": [
    {
      "name": "VILLAGE:CONTENT",
      "type": "flex",
      "props": {
        "direction": "column",
        "padding": [30, 30, 0, 30],
        "gap": "gap.lg"
      },
      "nodes": [
        {
          "type": "BackgroundBox",
          "props": {
            "color1": "#eecaa0",
            "color2": "white",
            "color2Position": "85%",
            "radius": "radius.lg",
            "direction": "column",
            "padding": [35, 30],
            "gap": "gap.lg"
          },
          "nodes": [
            { "type": "Card:Basic" },
            { "type": "Card:Level" },
            { "type": "Card:Gallery" },
            { "type": "Card:AddressAndMap" },
            {
              "type": "flex",
              "props": { "direction": "row", "justify": "center", "gap": "gap.md" },
              "nodes": [
                { "type": "button", "props": { "text": "村社相册" }, "events": { "click": "globalContext.handleGoGallery()" } },
                { "type": "button", "props": { "text": "编辑简介" }, "events": { "click": "globalContext.handleGoEdit()" } },
                { "type": "button", "props": { "text": "主页换肤" }, "events": { "click": "globalContext.handleGoSkin()" } }
              ]
            },
            { "type": "Card:Static" }
          ]
        },
        { "type": "Block:Rank", "props": { "title": "排行榜" } },
        { "type": "Block:Collect", "props": { "title": "魅力乡源" } },
        { "type": "Block:Games", "props": { "title": "活力乡源", "items": [...] } },
        { "type": "Block:Official", "props": { "title": "文脉乡源" } }
      ]
    }
  ]
}

每个皮肤需要存储一份这样的 JSON，村社使用某皮肤时即返回该皮肤对应的 JSON。后台管理系统创建/编辑皮肤时需要能编辑此 JSON 配置。

---

二、管理主页栏目显示与顺序

2.1 获取村社栏目配置

用途：获取村社名片主页的栏目配置（栏目显示/隐藏、排列顺序）。

项目	说明
方法	POST
路径	/village/column/getConfig

输入参数：

参数	类型	必填	说明
villageId	int	是	村社ID

输出：返回栏目配置 JSON。具体结构由前端确定，每项包含栏目标识，栏目数据和顺序，后端只需要保存JSON即可。

与采集栏目关联：待后端 采集栏目 相关接口设计完成后，此处下方 Block:Collect 与后端 采集栏目 管理并合并成最终列表。

{
  "columns": [
    { "type": "Card:Basic", "visible": true, "sort": 1 },
    { "type": "Card:Level", "visible": true, "sort": 2 },
    { "type": "Card:Gallery", "visible": true, "sort": 3 },
    { "type": "Block:Rank", "visible": true, "sort": 4 },
    { 
      "type": "Block:Collect", "visible": true, "sort": 5,
      "props": { 
        "title": "文脉乡源",
        "items": [ ... ]
      }
    },
    { 
      "type": "Block:Games", "visible": true, "sort": 6,
      "props": { 
        "title": "魅力乡源" ,
        "items": [ ... ]
      } 
    },
    { 
      "type": "Block:Official", "visible": true, "sort": 7,
      "props": { 
        "title": "文脉乡源" 
      }
    }
  ]
}

字段	类型	说明
*	？	由前端确定

---

2.2 保存村社栏目配置

用途：保存编辑后的村社名片栏目配置。

项目	说明
方法	POST
路径	/village/column/saveConfig

输入参数：

参数	类型	必填	说明
villageId	int	是	村社ID
data	json	是	栏目配置 JSON，结构同 2.1 输出

输出：无特殊数据。

---

三、管理贴图话题列表

3.1 获取村社话题列表

用途：获取村社贴图话题列表（用于话题标签展示和管理）。若未配置则使用默认话题。

项目	说明
方法	POST
路径	/village/topic/getTopicTags

输入参数：

参数	类型	必填	说明
villageId	int	是	村社ID

输出：

{
  "tags": [
    { "title": "广场", "icon": "", "disabled": false, "sort": 1 },
    { "title": "美食", "icon": "", "disabled": false, "sort": 2 },
    { "title": "美景", "icon": "", "disabled": false, "sort": 3 }
  ]
}

字段	类型	说明
tags[].title	string	话题名称
tags[].icon	string	话题图标URL（可空）
tags[].disabled	bool	是否禁用
tags[].sort	int	排序序号

若村社未配置话题，返回空数组，前端将使用默认话题列表：['广场', '美食', '美景', '故事', '老技艺', '老物件']

---

3.2 保存村社话题列表

用途：保存编辑后的村社贴图话题列表（含排序和新增/删除）。

项目	说明
方法	POST
路径	/village/topic/saveTopicTags

输入参数：

参数	类型	必填	说明
villageId	int	是	村社ID
tags	array	是	话题标签数组，结构同 3.1 输出

输出：无特殊数据。

---

四、接口汇总清单

序号	模块	接口名称	方法	路径
1.1	皮肤	获取皮肤列表	POST	/village/skin/list
1.2	皮肤	获取推荐皮肤	POST	/village/skin/recommend
1.3	皮肤	获取皮肤详情	POST	/village/skin/detail
1.4	皮肤	购买皮肤	POST	/village/skin/buy
1.5	皮肤	使用皮肤	POST	/village/skin/apply
1.6	皮肤	获取已购皮肤	POST	/village/skin/myPurchased
1.7	皮肤	获取皮肤订单	POST	/village/skin/orderList
1.8	皮肤	获取村社当前皮肤	POST	/village/skin/current
2.1	栏目	获取栏目配置	POST	/village/column/getConfig
2.2	栏目	保存栏目配置	POST	/village/column/saveConfig
3.1	话题	获取话题列表	POST	/village/topic/getTopicTags
3.2	话题	保存话题列表	POST	/village/topic/saveTopicTags

---

五、前端 TODO 对照说明

文件	TODO 标记	对应接口
card.vue:709	//TODO: 加载村社主题	1.8 获取村社当前皮肤
card.vue:713	//TODO: 加载村社话题	3.1 获取话题列表
config.vue:62-76	recommendLoader 静态数据	1.2 获取推荐皮肤
skin/skin.vue:42	//TODO: 缺少接口	1.1 获取皮肤列表
skin/details.vue:57	//TODO: 缺少接口	1.3 获取皮肤详情
skin/details.vue:74	//TODO (handleBuy)	1.4 购买皮肤
skin/details.vue:78	//TODO (handleUse)	1.5 使用皮肤
skin/buied.vue:29	//TODO: 缺少接口	1.6 获取已购皮肤
skin/orders.vue:73	//TODO: 更换为获取皮肤订单接口	1.7 获取皮肤订单
config/config-tags.vue:79	//TODO: saveTags()	3.2 保存话题列表
config/config-tags.vue:87	//TODO: getTags()	3.1 获取话题列表