留家族谱 · 微信小程序

留氏族谱数字化项目的移动端前端，面向宗亲提供成员录入、世系查询、个人录入管理等功能。数据与后台管理系统共用同一套 MySQL 数据库，通过 Flask 后端提供的 REST API 交互。

配套后台： genealogy_app（Flask + Jinja2 管理端）
生产 API： https://familial.yunzhixue.cn/manager
AppID： wx98f5cf1c60f793b8

一、技术栈

类别	技术
框架	微信小程序原生（WXML / WXSS / JS）
基础库	3.8.12（见 `project.private.config.json`）
导航	自定义 Tab Bar（`custom-tab-bar/`）
模板辅助	WXS 模块（`utils/helpers.wxs`）
后端	Flask REST API（Bearer Token 鉴权）

二、目录结构

genealogy-min-program/
├── app.js                  # 全局逻辑：登录态、baseUrl、token 持久化
├── app.json                # 页面路由、Tab Bar、窗口样式
├── project.config.json     # 小程序工程配置（AppID 等）
├── project.private.config.json  # 本地私有配置（基础库版本、urlCheck 等）
├── sitemap.json
│
├── custom-tab-bar/         # 自定义底部导航（首页 / 世系查询 / 我的录入 / 家族圈）
├── utils/
│   └── helpers.wxs         # WXS 工具：关系文案、字辈排序、姓名展示
│
└── pages/
    ├── index/              # 首页（功能入口、修谱委员会信息）
    ├── lineage/            # 世系查询（搜索 + 多代祖先 / 同辈 / 子女）
    ├── my_entries/         # 我的录入（列表、查看、编辑、删除）
    ├── add_member/         # 成员录入（关联成员搜索、同名检测）
    ├── login/              # 微信登录（手机号授权 + 用户协议）
    ├── policy/             # 用户服务协议 / 隐私政策
    ├── member_detail/      # 成员详情（独立页）
    ├── family_circle/      # 家族圈（静态展示，部分功能预留）
    └── test/               # 开发调试页

三、功能模块

3.1 底部 Tab（4 项）

Tab	页面	说明
首页	`pages/index`	录入信息、我的录入、家族相册/文化（预留）
世系查询	`pages/lineage`	按姓名搜索，展示祖先链、同辈、子女
我的录入	`pages/my_entries`	当前用户通过小程序录入的成员
家族圈	`pages/family_circle`	家族动态与活动（当前为静态数据）

3.2 核心页面

首页 index
水墨风格 UI，提供「录入信息」「我的录入」快捷入口；未登录时引导至登录页。

世系查询 lineage

调用 GET /api/members/search 搜索成员
调用 GET /api/lineage/<id> 加载完整世系
横向滚动展示：多代祖先（含同辈兄弟）、查询人物行、子女行
按 child_order（长幼序）排序，自动滚动至查询人物/祖先位置

录入信息 add_member

填写姓名、简繁名、性别、生日、字辈、婚姻状况等
关联已有成员（父/母/配偶等），支持弹层搜索与详情预览
提交前 GET /api/members/check_duplicate 检测同名
提交 POST /api/members/add，data_source=miniprogram

我的录入 my_entries

GET /api/members/my 拉取当前用户录入列表
PUT /api/member/<id> 编辑
DELETE /api/members/<id> 删除

登录 login

按钮 open-type="getRealtimePhoneNumber" 获取手机号
wx.login 获取 code，一并 POST 至 /api/wechat/login
须勾选用户协议与隐私政策（pages/policy）

四、API 对接

所有需鉴权接口在请求头携带：

Authorization: Bearer <token>

方法	路径	用途	使用页面
POST	`/api/wechat/login`	微信登录，返回 token 与用户信息	login
GET	`/api/members/search?keyword=`	成员搜索	lineage, add_member
GET	`/api/members/check_duplicate?name=`	同名检测	add_member
GET	`/api/members/<id>`	成员详情	member_detail
POST	`/api/members/add`	新增成员	add_member
GET	`/api/members/my`	当前用户录入列表	my_entries
PUT	`/api/member/<id>`	编辑成员	my_entries
DELETE	`/api/members/<id>`	删除成员	my_entries
GET	`/api/lineage/<id>`	世系树（祖先、同辈、子女）	lineage

完整后台路由与数据库说明见 genealogy_app/README.md。

五、快速启动

1. 启动后端

cd ../genealogy_app
pip install -r requirements.txt
python3 app.py
# 默认监听 0.0.0.0:5001

2. 配置 API 地址

编辑 app.js 中的 globalData.baseUrl：

// 生产环境
baseUrl: 'https://familial.yunzhixue.cn/manager'

// 本地真机调试（使用电脑局域网 IP，勿用 127.0.0.1 或 USB 虚拟网卡 198.18.x.x）
baseUrl: 'http://192.168.x.x:5001/manager'

3. 微信开发者工具

导入本项目目录
AppID 使用 wx98f5cf1c60f793b8（或与后台 WECHAT_APP_ID 一致的小程序）
详情 → 本地设置：开发阶段可关闭「校验合法域名」；project.private.config.json 中已设 urlCheck: false
建议使用基础库 3.8.12，避免灰度版本兼容问题

4. 真机调试注意

手机与电脑须在同一 WiFi
baseUrl 必须为电脑局域网 IP（如 192.168.124.37）
macOS 需允许 Python 接受入站连接（系统防火墙）
修改 baseUrl 后可在开发者工具「清缓存 → 全部清除」避免旧地址残留

六、登录与鉴权

用户点击登录
  → wx.login() 获取 code
  → getRealtimePhoneNumber 获取 phoneCode
  → POST /api/wechat/login { code, phoneCode }
  → 服务端 jscode2session + 解密手机号，写入 mp_users，返回 token
  → 小程序 wx.setStorageSync('token' / 'userInfo')
  → 后续请求 Header: Authorization: Bearer <token>

app.js 在 onLaunch 时从本地存储恢复登录态。退出登录调用 app.logout() 清除 token。

微信手机号授权后的短信验证码为平台安全策略，无法在应用层关闭。

七、UI 与样式

整体色调：米白 #f5f2e9、古铜 #8b6e4e，与后台首页设计统一
自定义 Tab Bar：custom-tab-bar/index.wxss
世系卡片：固定宽 200rpx，横向滚动区左右 padding 275rpx
WXS 模块负责关系类型、长幼序（长子/次子…）、简繁名并列展示

八、页面路由一览

路径	类型	导航栏标题
`pages/index/index`	Tab	留家族谱
`pages/lineage/lineage`	Tab	世系查询
`pages/my_entries/my_entries`	Tab	我的录入
`pages/family_circle/family_circle`	Tab	家族圈
`pages/add_member/add_member`	普通页	录入信息
`pages/login/login`	普通页	登录
`pages/member_detail/member_detail`	普通页	成员详情
`pages/policy/policy`	普通页	协议
`pages/test/test`	普通页	测试

九、数据字段约定

成员录入与后台 family_member_info 对齐，主要字段：

字段	说明
`name` / `simplified_name`	繁体名 / 简体名
`sex`	1=男，2=女
`birthday`	日期字符串 `YYYY-MM-DD`（服务端转 Unix 时间戳）
`name_word_generation`	字辈
`family_rank`	排行
`is_pass_away`	0=健在，1=已故，2=未知
`marital_status`	0~3
`relation_type` / `sub_relation_type`	与关联成员的关系类型
`parent_mid`	关联成员 ID（录入页 `selectedMemberId`）
`data_source`	固定为 `miniprogram`（服务端写入）

十、开发与发布

开发中功能（Toast「功能开发中」）

首页：家族相册、家族文化
家族圈：动态详情、活动详情、相册、联系方式

上线前检查

app.js 中 baseUrl 指向生产域名
微信公众平台配置 request 合法域名为 https://familial.yunzhixue.cn
关闭开发者工具「不校验合法域名」
确认用户协议、隐私政策内容完整（pages/policy）
真机全流程：登录 → 录入 → 我的录入 → 世系查询

十一、常见问题

现象	处理
真机请求失败 / timeout	检查 `baseUrl` 是否为局域网 IP；防火墙是否放行 5001
登录成功但搜索 401	确认请求头携带 `Authorization: Bearer`
世系图左侧被裁切	横向 scroll 勿用 `justify-content: center`（已在 `lineage.wxss` 修复）
WXS 报错	WXS 对象键须为字符串，见 `helpers.wxs`
编译基础库异常	固定使用 3.8.12，勿跟随灰度 3.16.x

十二、项目关系

┌─────────────────────┐         HTTPS/HTTP          ┌─────────────────────┐
│  genealogy-min-program │  ── Bearer Token API ──▶  │    genealogy_app     │
│  （微信小程序）          │                           │  Flask @ :5001       │
└─────────────────────┘                               └──────────┬──────────┘
                                                                   │
                                                                   ▼
                                                        MySQL (csqz-client)
                                                        family_member_info
                                                        family_relation_info
                                                        mp_users

最后更新：2026-07-07

README.md 9.8 KB История Исходник