# 留家族谱 · 微信小程序

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

**配套后台：** [`genealogy_app`](../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`](../genealogy_app/README.md)。

---

## 五、快速启动

### 1. 启动后端

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

### 2. 配置 API 地址

编辑 `app.js` 中的 `globalData.baseUrl`：

```javascript
// 生产环境
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. 微信开发者工具

1. 导入本项目目录  
2. AppID 使用 `wx98f5cf1c60f793b8`（或与后台 `WECHAT_APP_ID` 一致的小程序）  
3. **详情 → 本地设置**：开发阶段可关闭「校验合法域名」；`project.private.config.json` 中已设 `urlCheck: false`  
4. 建议使用基础库 **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*