commit 更新README

README.md

@@ -0,0 +1,262 @@
+# 留家族谱 · 微信小程序
+
+留氏族谱数字化项目的移动端前端，面向宗亲提供成员录入、世系查询、个人录入管理等功能。数据与后台管理系统共用同一套 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*