在线修谱（xiupu）插件使用说明

版本：1.0.0 作者：kuakeba.cn 分类：社区

一、插件简介

在线修谱（xiupu） 是一个让家族关系可记录、可传承、可协作的在线族谱编修系统。核心能力包括：

• 家族树可视化：世代分层排布，支持缩放拖拽、祖先后裔高亮、按世代与地域筛选。
• 世系与字辈：支系大宗小宗分房编修，自定义字辈诗，录入时自动提示当前辈分用字。
• 复杂关系建模：父子、配偶、兄弟姐妹，兼顾过继、兼祧、离异再婚，自动检测循环与性别冲突。
• 多人协作审核：族长、支系管理员、编辑员、成员、访客五级权限，修改留痕可追溯。
• 一姓一谱：同姓宗亲共修一谱，全站按主姓氏统一展示。

二、安装与启用

2.1 安装

1. 进入后台 插件管理，找到「在线修谱」插件，点击 安装。
2. 安装过程会自动执行 install.sql，创建 8 张数据表，并注册后台菜单（家族、族员、支系、字辈、申请、日志、配置）。
3. 安装完成后，插件的静态资源会从 plugins/xiupu/static/ 复制到 public/static/xiupu/。

2.2 启用与基础配置

进入后台 在线修谱 → 修谱配置（admin/xiupu_config），配置以下 9 项参数：

配置保存后即时生效。

三、前台使用

前台入口地址：/xiupu（例如 http://admin.zz/xiupu）。

3.1 首页（家族列表）

• 展示主姓氏徽章（如「张氏宗谱 · 一姓一谱」）。
• 统计卡片：家族数、族员数、最大世代、已故先人数。
• 若无族谱且开放了建谱权限，显示「创建族谱」按钮。
• 已有族谱时点击「浏览家族谱系」进入家族列表。

3.2 创建族谱

路径：/xiupu/family/create（需登录，且配置项 allowcreatefamily 开启）。

填写字段：

• 家族名称：如「清河张氏宗谱」
• 主姓氏：自动预填配置中的主姓氏
• 始祖名：本族可追溯的一世祖
• 祖籍/起源地：郡望或发祥地
• 家训/堂号：如「百忍堂」
• 家族简介：家族历史与修谱说明
• 封面图

提交后进入 待审核 状态，需管理员在后台审核通过后才对前台公开。

3.3 家族详情

路径：/xiupu/family/detail?id=家族ID

展示家族简介、始祖、祖籍、家训、封面，以及「查看家族树」「族员列表」「我要入谱」等操作入口。

3.4 族员管理

#### 新增族员

路径：/xiupu/person/add?family_id=家族ID（需 edit 及以上权限）

核心字段：

• 姓名、字号、性别
• 所属支系、第几世、字辈用字
• 出生日期（公历/农历）、逝世日期
• 民族、籍贯、现居地、学历、职业、职务
• 电话、微信、邮箱、身份证（敏感字段加密存储）
• 头像、生平简介（富文本）
• 可见范围：公开 / 私密 / 仅本支
• 已故者隐藏敏感信息开关

#### 编辑族员

路径：/xiupu/person/edit?id=族员ID

#### 族员详情

路径：/xiupu/person/detail?id=族员ID

展示完整档案、亲属关系（父母、配偶、子女、兄弟姐妹）、多媒体档案。已故者按配置自动隐藏联系方式。

#### 搜索族员

路径：/xiupu/person/search?keyword=姓名

3.5 关系管理

在族员详情页可添加亲属关系，支持以下类型：

接口：

• 保存关系：POST /xiupu/relationship/save
• 删除关系：POST /xiupu/relationship/delete
• 关系列表：GET /xiupu/relationship/list

3.6 支系浏览

路径：/xiupu/branch?family_id=家族ID

以树形展示大宗、小宗及各房支结构。

3.7 入谱申请

路径：/xiupu/invite/apply?familyid=家族ID（需配置项 allowapply_family 开启）

访客/登录用户填写：

• 自述关系（如「张三的曾孙」）
• 关系证明图片

提交后进入 待审核，管理员在后台「入谱申请」中审核通过后，用户即成为该家族成员。

四、家族树操作指南

路径：/xiupu/tree?family_id=家族ID

家族树是本插件的核心可视化模块，基于自研的 XiupuFamilyTree 渲染器（SVG 连线 + DOM 节点）。

4.1 视图操作

4.2 布局样式

工具栏下拉切换：

• 树状图（tree，默认）：自上而下的宝塔式布局
• 宝塔式（ba）

后台配置 defaulttreetype 可设置默认样式（tree / eu / su / ba）。

4.3 根节点切换

工具栏「自动(始祖)」下拉框会列出世代最小的前 15 位先人，选择后以该人为根重新绘制子树，便于聚焦某一房支。

4.4 搜索与筛选

搜索框输入姓名可高亮匹配节点。下方筛选标签：

• 全部世代
• 仅男性 / 仅女性
• 在世 / 已故

点击画布空白处可取消高亮。

4.5 导出

点击「📥 导出 JSON」，下载当前家族树的完整节点与关系数据（/xiupu/tree/export?family_id=家族ID），可用于备份或二次开发。

4.6 数据接口

家族树数据由后端 FamilyTreeService::build() 构建，接口为：

GET /xiupu/tree/data?family_id=家族ID[&root_id=根节点ID]

返回结构：

{
  "code": 0,
  "data": {
    "nodes": [
      { "id": 1, "name": "张三", "gender": 1, "gen": 1, "deceased": 1,
        "avatar": "", "birth": "1900-01-01", "death": "1980-01-01",
        "native": "河北清河", "branch_id": 0,
        "detail_url": "/xiupu/person/detail?id=1" }
    ],
    "edges": [
      { "source": 1, "target": 2, "type": "parent_child" },
      { "source": 1, "target": 3, "type": "spouse" }
    ],
    "root_id": 1,
    "generations": []
  }
}

五、后台管理

后台入口：/admin/xiupu_family（菜单「在线修谱」）。

5.1 家族管理 xiupu_family

• 家族列表：查看所有家族，按状态筛选（正常/禁用）。
• 新增/编辑：后台可直接创建或编辑家族，无需审核。
• 审核：前台用户提交的建谱申请在此审核通过/驳回。
• 删除：删除家族会级联清理关联数据。

5.2 族员管理 xiupu_person

• 族员列表：按家族、支系、世代、姓名筛选。
• 新增/编辑：直接录入或修改族员档案。
• 审核：当配置 personauditrequired 开启时，新录入族员在此审核。
• 批量操作：批量调整支系、世代、可见性等。
• 删除：软删除（status = -1）。

5.3 支系管理 xiupu_branch

• 管理家族的大宗/小宗/各房支，支持 parent_id 树形层级。
• 字段：支系名称（如「长房」「二房」）、本支始祖人物、排序、说明。

5.4 字辈管理 xiupu_generation

• 维护家族的字辈诗与世代称谓。
• 字段：第几世、字辈用字、世系称谓（如「世祖」「二世祖」）。
• 同一（家族, 支系, 世代）唯一，录入族员时自动提示当前辈分用字。

5.5 入谱申请 xiupu_invite

• 审核用户的加入申请，分配角色（member / edit / branch_admin / admin）。
• 可限定支系管理员的管辖支系（branch_id）。

5.6 编辑日志 xiupu_log

• 记录所有 create / update / delete / relationshipadd / relationshipdel / branch_add 等操作。
• 含操作人、IP、字段新旧值、审核状态，便于追溯与版本回滚参考。

5.7 修谱配置 xiupu_config

即第二章所述的 9 项配置。

六、角色与权限

系统采用 5 级角色 权限模型，角色判定顺序如下：

1. 族长（admin）：xiupufamily.adminuser_id 等于当前用户 ID。
2. 邀请/认证角色：xiupuinvite 表中 status=1 记录的 role 字段（member / edit / branchadmin / admin）。
3. 关联族员（member）：xiupuperson 表中 userid 等于当前用户且 status=1。
4. 访客（guest）：以上都不满足。

权限矩阵

支系管理员范围限制

支系管理员（branchadmin）在 xiupuinvite.branchid 字段限定的支系内行使权限；若 branchid = 0，则为全局支系管理员，可管理所有支系。具体由 PermissionService::canEditBranch() 校验。

七、数据表结构

插件共使用 8 张数据表（表名由框架自动加前缀）：

7.1 xiupu_family 家族主表

7.2 xiupu_branch 家族支系

7.3 xiupu_generation 字辈世代

唯一键：(familyid, branchid, generation_no)。

7.4 xiupu_person 族员（核心表）

7.5 xiupu_relationship 族员关系（邻接表）

唯一键：(personida, personidb, type, direction)。

7.6 xiupu_invite 成员邀请/认证

7.7 xiupueditlog 编辑日志

7.8 xiupu_media 人物多媒体档案

八、前台公共模板变量

前台控制器基类 FrontBase::assignCommon() 会向所有模板注入以下变量：

九、常见问题

9.1 修改了 CSS/JS 但前台没变化？

框架的 PluginService::copyStaticAssets 只在插件安装时 将 plugins/xiupu/static/ 复制到 public/static/xiupu/。开发阶段修改静态资源后，需手动同步：

Copy-Item -Path "plugins\xiupu\static\*" -Destination "public\static\xiupu\" -Recurse -Force

此外，Nginx 对 css/js/png/jpg 等静态文件配置了 Cache-Control: public, max-age=2592000, immutable（强缓存 30 天），修改后必须 升级版本号 query string（如 xiupu.css?v=12）才能强制浏览器刷新。

9.2 前台访问 /xiupu 返回 404？

请检查后台 修谱配置 中「启用在线修谱」开关是否打开。关闭时前台所有路由返回 404，仅后台可操作。

9.3 访客看不到族谱？

检查配置项「允许访客浏览」（allowvisitorview）。关闭后未登录用户访问会返回 403「请先登录」。

9.4 新建的族谱前台不显示？

前台用户提交的建谱申请默认进入 待审核 状态，需管理员在后台「在线修谱 → 家族管理」中审核通过后才公开。

9.5 家族树节点点击后跳转 404？

节点的 detail_url 由 FamilyTreeService::build() 生成，格式为 /xiupu/person/detail?id=族员ID。请确认路由 xiupu/person/detail$ 已注册（见 routes.php）。

9.6 拖拽家族树后第一次点击节点没反应？

此问题已在 xiupu-tree.js 中修复：mousedown 事件中 moved = false 的重置已提前到节点判断之前，确保拖拽结束后首次点击节点不会被误判为移动操作。

十、路由速查

前台路由

后台路由

文档基于插件源码（XiupuPlugin.php / routes.php / install.sql / PermissionService.php / FamilyTreeService.php / FrontBase.php）整理，若插件升级请以实际代码为准。