# GUJIV

**Repository Path**: skylonng_admin_admin/GUJIV

## Basic Information

- **Project Name**: GUJIV
- **Description**: 古籍排版
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-13
- **Last Updated**: 2026-10-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 雲章譜局 · 古籍家谱 / 门派宗谱编纂一条龙平台

> **Copyright © 2026 晟唐科技（ShengTang Technology）** · 专有软件，许可条款见 [LICENSE](LICENSE) 与文末「版权与许可」

一个纯前端（零依赖、离线可用）的家谱编纂平台，覆盖 **录谱 → 缮录 → 排谱 → 印谱 → 交付** 全流程，
并内置 **書稿**（古籍竖排）排版台，可独立成书。
双击 `index.html` 即可运行；数据自动保存在浏览器 localStorage。

除传统宗谱外，本平台亦支持 **门派宗谱**（技艺传承谱系）——同一套世系树可切换记录师徒相授、
技艺品阶与支脉诀要；版式一路通行 **宋 / 明 / 清 / 仿竹简 / 木活字**，并可叠加 **仿古做旧** 与 **朱笔批注**。

> 改平台名只需改 `js/data.js` 顶部的 `MP.BRAND` 一处（名称 / 印章字 / 副题 / 扩展名描述）。

```
mopu-platform/
├─ index.html      六大工作台：谱籍 / 录谱 / 缮录 / 排谱 / 印谱 / 書稿
├─ styles.css      界面 + 古籍版式样式表
├─ sw.js           PWA 离线缓存（升级请递增顶部 CACHE_VERSION）
├─ manifest.webmanifest / server.js   网页版清单 / 局域网分发服务（零依赖）
├─ assets/
│  ├─ menu-bg.svg      顶栏与菜单栏的水墨横幅背景（矢量，离线）
│  └─ icon-512.png / icon-256.png / icon.ico / icon-src.html   应用图标与源稿
├─ js/
│  ├─ data.js        数据模型、繁简字表、谱类双模术语、文本解析、示例谱（宗谱 / 门派谱）
│  ├─ layout.js      家谱排版引擎：古籍竖排筒子叶 / 欧式世系表 / 苏式垂珠图 / 技艺谱
│  ├─ app.js         应用逻辑、缮录编辑器、成本核算、导入导出
│  ├─ songban.js     古籍版式排版引擎：一版双半叶 / 版心 / 界行 / 破栏（纯计算）
│  ├─ guji.js        版式效果引擎：时代规制 / 仿竹简 / 墨韵 / 做旧 / 朱批（确定性随机）
│  ├─ classic.js     書稿应用层：标记与自动解析、docx 读取、简转繁校正、.yzp 文档
│  ├─ classic-ui.js  書稿工作台界面（含叶面校勘、手写批注）
│  ├─ cloud.js       云端接入：登录、谱库、分享、服务端导出、支付闸门
│  └─ qrcode.js      零依赖二维码编码器（服务端渲染收款码 / 订单码）
├─ cloud/           云端多用户版（Node，零依赖）
│  ├─ server.js       鉴权 / 文档 / 额度 / 支付 / 静态分发 / 服务端导出
│  ├─ pdfbook.js      家谱古籍 PDF 渲染（复用网页引擎）
│  ├─ pdfclassic.js   書稿 PDF 渲染（图元流转 PDF，所见即所得）
│  ├─ pdf.js          零依赖 PDF 写入器（Type3 逐字嵌字）
│  ├─ ttf.js          TrueType / TTC 解析（取字形轮廓）
│  ├─ DEPLOY.md       腾讯云轻量服务器部署指南
│  └─ test-*.js       服务端回归测试（结算 / 导出 / 書稿导出）
├─ desktop/         Electron 桌面版外壳（preload.js / main.js / build.js）
├─ android/         Android WebView 壳工程（build_apk.py 手工组包，无需 Gradle）
├─ test-pdf/        排版回归与体检脚本、出片样张
├─ docs/            设计留档（含宋版原型 ikas Python 版源码档案）
└─ pack.py / build_apk.py / push-gitee.*   打包与源码同步工具
```

## 一 · 谱籍
谱名、堂号、郡望、卷次、始迁祖、修次、主修人、年份、序跋凡例。
自动统计入谱人数、世代数、配氏人数、预估叶数，并生成自动目录。

## 二 · 录谱
- 左侧 **世系树**，逐级展开，点选即编辑；树顶有**检索框**，输入即按名讳／字／号／行第／事略／支脈等字段过滤并高亮命中，Esc 清空。
- 右侧表单：名讳、字、号、行第、世次、父、生、卒、葬地、出身功名、配氏、子嗣、女、出继入继、事略、备注。
- **世次自动推演**：子嗣 = 父 + 1，改父即整支重排。
- **批量录入（三式）**：顶栏「文本批量导入」，弹窗内可切换，**边贴边出识别结果**，确认无误再落谱；看错了也就是多点一下。
  · **表格粘贴**（推荐）——从 Excel 或旧谱表格复制一整片，**连首行列名一起**贴进来。认得的列名有名讳／父（或师父）／字／号／行第／世／生／卒／葬／功名／配氏／子／女／出继／事略／备注等，繁简与英文都收，认不出的列会列在旁边提示、绝不乱填。
    **只要有「父」这一列就够了**：抄到谁写谁，填上他爹（或师父）是谁，树枝由程序自己接。
  · **缩进式**——老式记法，靠缩进阶梯判世次；单次上限 20000 行，缩进跳级会收敛为「上一层 + 1」，不会因为一个笔误多出一批假始祖。行内关键字：`字 號 行 生 卒 葬 配 繼配 側室 子 女 出繼 嗣 螟蛉 事略`。
  · **名单式**——每行一个名字，整批作为当前选中成员的**子嗣**录入，适合照着旧谱「某人子三：甲、乙、丙」一口气添完一房。
- **成员保存校验**：名讳为空不予保存；不许把后代选作自己的父／师（会成环）；同名会提示但允许通过（古人同名常见）。
- **撤销 / 重做**：顶栏 ↶ ↷ 或 Ctrl+Z / Ctrl+Shift+Z，快照式回滚，最多 40 步（总量超 24MB 自动裁剪，不会反过来把存储撑爆）。
- **谱系体检**：打开他人谱籍或旧文档时，自动检查重复编号 / 父系缺失 / 世系成环 / 自指，发现即提示「立即修复」——去重编号、断开环状世系、把孤儿提升为独立一支，**一个人都不丢**。
- 修改父节点时，其原有子孙自动上升一级，不丢数据。

### 录入效率（v1.16.0）

| 项目 | 说明 |
|---|---|
| 表格粘贴 | 从 Excel 复制一整片（含列名）直接贴，列名自动映射到字段；认不出的列只提示不填 |
| **按父名接树** | 有「父／师父」一列即可建树，**抄录时不必数缩进**。父名查无此人 → 提为独立一支；同名多人 → 接子嗣最少的那位并标记待核；首尾成环 → 自动断开 |
| 名单式录入 | 每行一个名字，整批挂到当前选中成员名下，一房人一口气添完 |
| 实时识别预览 | 粘贴后立刻显示「几位／几世／几支」、列名映射与接树提示，确认后再落谱 |
| **谱籍体检** | 一次挑出：空名、同名、**世次与父不衔接**、卒年早于生年、父子年龄差离谱（<12 或 >70 岁）、父指针悬空、孤支。点「定位」直接跳到那位改；「重算全部世次」「悬空者提为独立一支」可一键修 |
| 详略模板 | 简录（4 项）/ 标准（9 项）/ 详录（16 项）/ 門派（12 项），只留当次用得上的格子；名讳与父任何档位都保留；选择会记住 |
| 常用值历史 | 葬地、支脈、功名、师承、技艺这类重复率高的取值自动记下，下次录入点一下即填（每字段留最近 8 条） |

> 体检只报不动手，所有修复都要你确认；断环、提升孤儿等动作一律「人不丢」，宁可多出一支独立支系，也不让任何一位族人凭空消失。

### 基础功能加固（稳定性）

| 项目 | 现况 |
|---|---|
| 全局异常兜底 | `window.onerror` / `unhandledrejection` 统一兜住，页面顶部给出含堆栈摘要的诊断条（可复制、可关闭），**不再白屏** |
| 世系算法 | `sorted` / `recalcGen` / `subtreeHas` 全带 visited 保护，脏数据成环也不会栈溢出或假死 |
| 本地存储容错 | 写入失败按配额不足／隐私模式分别给不同处置建议；占用超 4MB 主动提醒归档 |
| 离页保护 | 仅在「确有未存盘改动 + 用户已交互」时才提示，避免无谓打扰（浏览器策略也只会拦下有交互的场合） |
| 防连点 | 「保存文档 / 另存为 / 打开文档」加一次性执行锁（`onceRun`），异步操作不会被连点跑两遍 |
| 数据校验 | 名讳必填、禁止成环、同名提醒、体重超限提示 |

## 三 · 缮录（古籍直书编辑）
在竖排稿纸上直接写谱文，一格一字、右起直书：

- **稿纸**：朱丝栏竖列，可点格子定位光标；输入法、方向键、退格照常（由隐藏输入框接管）。
- **提行**：回车即另起一列——古籍条目各起一行即由此而来。
- **小字夹注**：选中文字点「小字夹注」（或输入全角括号），括内文字排版作**双行小字、占半格**，括号本身不印出。
- **句读圈点**：、。「」『』《》· ○ △ 与空字、提行，一键插入。
- **谱牒套语**：字／號／行／生／卒／葬／配／繼配／側室／出繼／嗣／螟蛉／誥封／邑庠生……一键插入。
- **古籍异体**：塟（葬）、甯（宁）、廼（乃）、邨（村）、槨（椁）、殤、耄……
- **用字转换**：整稿繁 ↔ 简互转。
- **与世系互转**：「由世系生成」按世系数据生成谱文初稿，改完字点「解析入谱」回写世系（依缩定世次）。
- **原稿优先**：世系稿非空时，排谱以原稿为准；清空则回到按「录谱」数据自动生成。
- 编辑区实时统计字数、稿纸列数，并按当前版口折合版面列数与叶数。

## 四 · 排谱
三种版式，实时预览：

| 版式 | 说明 |
|---|---|
| **古籍竖排 · 筒子叶** | 版框、界栏、**双鱼尾**版心、书耳、书衣题签；字距行距由开本与「行数 × 字数」自动推导 |
| **欧式世系表** | 横行表格：世次/名讳/字号/行第/生卒葬/配氏/子嗣/事略，可加框线、隔世底色 |
| **苏式世系图** | 垂珠式 SVG 世系图，**长房居右**，按世代分层 |

**界栏（竖线）三态**
- **乌丝栏** — 黑界行（刻本常见）
- **朱丝栏** — 朱界行（稿本、誊清本常见）
- **白文** — 无界行，素纸直书

**边栏（版框）三态**：四周双边 ／ 四周单边 ／ 无版框（素纸）。
其余参数：每半叶行数、每行字数、字体（宋/楷/仿宋/黑）、字面大小、双鱼尾、宣纸底纹、卷口文字、繁体输出、保留标点、内容范围（序跋/书衣/目次/世系录）。

## 五 · 印谱
- 规格：开本（8开/大16开/16开/大32开/32开/线装半叶）、用纸（宣纸仿古/净皮/毛边/仿古胶版/铜版）、装帧（线装/胶装/精装/包背装/经折装）、书衣用色、印数、每部册数。
- **印制工单**自动核算：成书叶数、正文字数、总用纸、纸张费/装订费/书衣费/函套费/制版开机费/校勘费、装帧系数、总价与每部单价。工价可逐项改写。
- 交付导出：
  - **生成 PDF**（调用打印，`@page` 自动匹配开本尺寸，无需缩放）
  - 独立 HTML 版（样式内联，可直接发给印厂）
  - 苏式世系图 PNG / SVG
  - 世系表 CSV、谱籍 JSON

## 六 · 書稿（古籍版式排版台）
面向文集、典籍、谱牒类书稿的古籍排版：一版双半叶、四周双边、版心居中
（书名 + 鱼尾 + 叶次 + 篇名）、界行、大字正文、双行小字注疏、
阴文题标、大题独占一版（破栏）、封面题签、目次点线。

- **文稿录入**：直接粘贴，或导入 `.txt / .md / .docx`（零依赖解析 docx，本地完成）。
- **两种写法**：
  - 标记写法　`# 书名` / `@ 撰者｜纪年` / `## 节`（前言·序·凡例·附錄）/ `### 章` / `#### 题标` / `> 小字`
  - 无标记自动识别　`前言`、`序一`、`凡例`、`附錄一` 识别为节，`第N章` 识别为章，
    `原文 / 疏字 / 疏義 / 章義` 识别为题标（原文大字，余为小字）；空行分段
- **简转繁**：内置约 420 组对照 + 史学用字校正（余/雲/台/后/里/沖/欲 等字头疏证常见误转），付印前仍请人工校勘。
- **版式预设**：宋版通行式 / 大開本 / 巾箱本 / 單邊簡淨 / 單半葉一頁 /
  **明式黑口文武邊** / **明式粗黑口** / **清式白口書耳** / **木活字印本** / **仿竹簡**。
  列数·字数·字号·边栏·鱼尾·出血角线皆可调；详见下节。
- **叶面校勘**：开启后在叶面上直接点选文字，浮条可改字、转大字/小字、加题标、提行、拆段、删字删段，
  改动即时重排并同步回源码区。
- **版面体检**：逐字计算墨迹到界行 / 版心线 / 版框的最小净距与越界字数，压线即提示。
- **导出**：
  - 云端版：`出印刷 PDF` 由服务器**逐字嵌字**生成（Type3 字形，只嵌用到的字），与预览同源几何，可直接付印；
  - 单机 / PWA：走浏览器打印（`@page` 自动匹配一版尺寸），或导出独立 HTML。

## 七 · 古籍版式：时代规制 · 墨韵 · 做旧 · 批注

由 `js/guji.js`（MPG）提供效果层，`js/songban.js`（MPS）按规制落版。所有效果为**确定性随机**（同一随机种子出同一版面），
SVG 预览与服务端 PDF **几何完全同源**。

### 时代规制

| 规制 | 版框 | 版心 | 鱼尾 | 备注 |
|---|---|---|---|---|
| **宋** `song` | 四周双边 | 白口 | 双鱼尾 | 大字疏行，浙本风范 |
| **明** `ming` | 外粗内细（文武边） | **上下黑口** | 双黑鱼尾 | 明代中期通行式 |
| **清** `qing` | 左右双边 | 白口 | 单鱼尾 | 版框外置**书耳**，内题篇名卷次 |
| **仿竹簡** `jian` | 简片竹丝 | 无版心 | 无 | 两道编绳结勒，每简一列，叶次书于简末 |

完整预设十套：`song` 宋版通行式、`daben` 宋版大開本、`jinxiang` 巾箱本、`danbian` 單邊簡淨、
`ban` 單半葉一頁、`ming` 明式黑口文武邊、`mingcu` 明式粗黑口、`qing` 清式白口書耳、
`huozi` 木活字印本、`jian` 仿竹簡編繩。

### 墨韵（印本肌理）

| 选项 | 效果 |
|---|---|
| **洁净** `clean` | 不抖不晕，宜现代影印稿 |
| **仿版刻** `carve` | 刀痕微抖、墨色浓淡不匀，偶见墨重发糊与缺墨 |
| **木活字** `moveable` | 字位高低不齐、字面大小参差、墨色深浅悬殊，**界行被字顶断**（活字本特征） |

**不压线硬约束**：抖动幅度由 `jitterBudget()` 按该版式的水平/垂直余量自动限幅（预留 0.45mm 安全距），
因此无论墨韵多强，字都**不会压界行、不会出版框**。各版式 × 两墨韵 × 三级做旧均已通过体检。

### 做旧（背景仿古）

- 四级强度（0–3）：**纸纤维** → **黄斑（三层渐变）** → **水渍 / 霉点** → **虫蛀 / 折痕**
- 纸色六款：`su` 素纸 / `xuan` 仿宣纸 / `ma` 宋版麻纸 / `jiu` 旧纸泛黄 / `pi` 皮纸褐 / `zhu` 竹青（简）
- 随机种子可换纹理：同种子必得同版面，便于多人核验与重印
- 做旧图层位于版框与文字之下，只改纸不伤字，不影响可读性

### 手写批注（朱批）

批注模式下点叶面即落朱笔，笔迹为行楷朱色，位置按落点自动判别：

| 批式 | 触发位置 | 呈现 |
|---|---|---|
| **眉批** `mei` | 天头 | 版框外上方竖排小字 |
| **夹批** `jia` | 行间 | 双行小字夹于正文之间 |
| **旁批** `pang` | 版框外左右 | 侧栏竖排小字 |
| **圈点** `quan` | 字上 | 朱圈 |
| **顿点** `dian` | 字右 | 朱点 |
| **涂抹** `mo` | 字上 | 墨块涂乙 |

批注列表可定位、可删除，随 `.yzp` 保存，并随服务端 PDF 一同出片。

## 八 · 门派宗谱（技艺传承谱系）

同一套世系结构，切换「谱类」即可从宗谱转为门派谱：

| | 宗譜 `clan` | 門派宗譜 `school` |
|---|---|---|
| 层级单位 | 世次（第X世） | 代次（第X代） |
| 亲缘称谓 | 父 / 子嗣 / 女 | 师承 / 弟子 |
| 始祖 | 始祖 | 開山祖師 |
| 统计项 | 入谱人数 / 世代数 / 配氏 | 入谱人数 / **传代数** / 同门 |

- **师承字段**：技艺、品阶（初授 · 登堂 · 入室 · 嫡傳 · 掌宗…）、支脉、诀要、师承，随谱类自动显隐。
- **技艺谱章节**：新增「技艺谱」章节类型，按技艺分组生成传承名录初稿。
- **文本解析**：（`藝` `階` `脈` `訣` `師` `弟子` 前缀），与宗谱沿用的 `字 號 行 生 卒 葬 配 子 女` 并行不悖。
- **内置示例**：「雲章鑄劍門宗譜」——冶之公張鳧掌宗开山，五代十二位传人，冶 / 鍛 / 淬 / 銘 四脉分支。

## 九 · 云端多用户版

`cloud/server.js`（Node 零依赖）提供：注册登录、云端谱库、三级权限（viewer / admin / creator）、
分享与共同编修、积分扣费与收款、**服务端出片**。完整部署步骤见 [`cloud/DEPLOY.md`](cloud/DEPLOY.md)。

- **用户分仓存储**：`cloud/data/users/<用户名>/{account.json, docs/*.json}`，用户名作目录名已做字符白名单校验
- **服务端导出**：`POST /api/docs/<id>/export?fmt=pdf|html|csv|json|svg`，5 种格式全部服务端生成，
  额度在服务端结算（浏览器只收到成品，**无法绕过**提取整份数据）
- **批量导出**（`export.batch`，高级管理人员 / 单项授权）：`POST /api/batch/export?fmt=…` 传多个谱籍 id，
  服务端一次生成并打成 **ZIP**（内含每部一份成品 + `导出清单.txt`），额度按「需计费部数」一次结算，
  单部失败只退该部；单次上限 20 部（`YZP_BATCH_MAX` 可调）。ZIP 为自研零依赖打包（deflate + CRC32 + UTF-8 条目名）
- **零依赖 PDF 链**：自研 TTF 解析 → Type3 逐字嵌字，字体只嵌用到的字（十万字谱约 1–2 MB）
- **收款**：支持人工确认与网关回调两种模式；收款码内容与图片只存服务端，二维码服务端渲染下发，
  公开接口**绝不下发收款码原文**

### 服务端安全与健壮性加固

| 项目 | 做法 |
|---|---|
| 支付回调强制验签 | 网关模式下**未配置 `gateway.secret` 一律拒绝回调**（503），杜绝伪造「已到账」刷积分／刷会员；密钥即配即生效 |
| 登录撞库防护 | 同一「来源 + 账号」连续 8 次密码错误，锁定 10 分钟并提示剩余秒数；只锁这一个组合，不牵连同 IP 的其他账号 |
| 频率限制 | 按来源 IP 滑动窗口（60 秒）分桶：常规 / 登录注册 / 计算密集 / 支付；重接口（排版、出片、导出）单独更严配额，超限返回 429 |
| 计算密集接口需登录 | 書稿解析、排版预览原为匿名可用，现已要求登录，避免被匿名刷爆单线程 |
| 资源上限 | 请求体 20MB、单份谱籍 8MB / 30000 人、单账号 300 部谱籍、账号总数上限（均可环境变量覆盖） |
| 进程级兜底 | 注册 `uncaughtException` / `unhandledRejection`，单个请求出错不再整站退服 |
| 错误脱敏 | 出片 / 导出 / 排版失败对外只给可行动的提示，详细异常写服务端日志 |
| 缓存治理 | 鉴权结果 3 秒短缓存（任何写账户操作立即清空），Blob 图片缓存上限 32 条 LRU，索引全量重建 10 秒节流 |
| 超限回包 | 请求体超限时不再直接断开连接，而是读完请求后正常返回 413（浏览器端表现为清晰提示而非「无响应」） |

**可调环境变量**（不设则用默认值）：`YZP_RATE_MAX`、`YZP_LOGIN_MAX`、`YZP_HEAVY_MAX`、`YZP_PAY_MAX`、
`YZP_MAX_DOC_BYTES`、`YZP_MAX_MEMBERS`、`YZP_MAX_DOCS`、`YZP_MAX_USERS`

### 会员等级与功能权限

古籍**常规版式（宋版标准）**与**氏族宗谱**人人可用；时代规制、墨韵、做旧、朱批、门派宗谱等
**高级功能按会员等级开放**（服务端按最终生效样式强制校验，前端无法绕过）。

| 等级 | 参考价 | 可用功能 |
|---|---|---|
| **常客** free | 注册即得 | 宋版标准版式、氏族宗谱；导出按积分计量 |
| **会员** vip | 30 元 / 30 天 | 增：时代规制（明 / 清 / 仿竹简）、墨韵（仿版刻 / 木活字）、纸色做旧、手写朱批、**门派宗谱**、导出免积分 |
| **高级管理人员** master | 99 元 / 30 天 | 增：批量导出、平台管理（也可由管理员直接授予） |

能力码（服务端权威定义，配置里只能改价格与周期）：
`guji.basic` `guji.era` `guji.ink` `guji.aged` `guji.ann` `school.mode` `export.free` `export.batch` `admin.platform`

**开通方式**（三选一，到账即生效）
1. 平台管理员直接授予：`平台管理 → 用户管理 → 等级`（可设天数；可单项授权某个功能）
2. 会员码：管理员在「充值码」下发 `YZM…` 会员码，用户在会员中心兑换
3. 扫码下单：会员中心选方案与周期 → 扫码支付 → 人工确认或网关回调后自动开通

- 到期自动回落为常客，能力随之收回；已编修的门派谱仍可继续保存
- **离线不受限**：本机打开、桌面版、APK、未连云端时全部功能照旧可用

## 十 · 存储与文档

**三层存储**

| 层 | 说明 |
|---|---|
| **本机谱库** | 浏览器 localStorage，可同时存多部谱籍；修改**自动保存**（含 30 秒兜底与关页前保存），刷新/重开浏览器不丢 |
| **谱籍文档（.yzp）** | 自有格式 JSON（`mopu.genealogy`），含谱籍信息、世系、**缮录原稿**、版式与印制参数；旧版 `.mopu` 文件可直接打开 |
| **磁盘关联** | 在 Chrome/Edge 中，「保存文档」后即与磁盘文件建立关联，此后 `Ctrl + S` 直接覆盖写回，不再弹窗 |

**顶栏操作**
- `保存文档` — 写入磁盘：已关联则覆盖，未关联则弹出「另存为」（默认扩展名 `.yzp`）
- `另存为` — 强制另存一份新文件
- `打开文档` — 从磁盘打开 `.yzp` / `.mopu` / `.json`；也支持**直接把文件拖进窗口**
- `谱库 (N)` — 本机文档管理：打开、另存副本、重命名、导出、删除，并显示人数/世代/存入时间/占用空间
- 顶栏左侧徽章显示当前文档名与「未存盘」状态

**快捷键**：`Ctrl/⌘ + S` 保存文档 · `Ctrl/⌘ + Shift + S` 另存为 · `Ctrl/⌘ + O` 打开文档

**兼容性**：Chrome / Edge 86+ 走 File System Access API；其他浏览器自动回退为「下载文件 + 选择文件」，功能等价。旧版直接导出的裸 JSON、旧版布尔界行设置均自动兼容迁移。

## 十一 · 三端分工：手机录入 · 电脑出片

同一份代码跑在网页、Windows 桌面版与 Android APK 上，但**各按所长分工**：

| 设备 | 默认模式 | 能做什么 | 不做 |
|---|---|---|---|
| **电脑**（桌面版 / PC 浏览器） | 完整模式 | 录入 · 编辑 · 浏览 · **排版 · 出片 · 付印 · 导出** | — |
| **手机 / 平板**（APK / 移动浏览器） | 录入模式 | **录入 · 编辑 · 浏览** | 出片付印、本机文件读写 |

**手机上（录入模式）**
- 页签只留：谱籍 / 录谱 / 缮录 / 预览——「印谱」「書稿」收起，「排谱」退化为「预览」
- **「保存并录下一位」**：存好当前这位，立刻接着录同父的兄弟（始祖则接着录其子），手指不必离开键盘
- 顶栏「⇱ 排版出片」随时可切到完整模式：排版与导出都能做，仍建议回电脑付印
- 点「生成 PDF」会明确指出去路：上传云端 → 电脑端接着出片（不再是点了没反应）
- **已打开云端谱籍时，「印谱」页签自动回来**，按钮改称「下载 PDF（服务端生成）」：
  PDF 由服务器排版生成后直接下载，**手机上不必再等电脑**（出片入口随云端谱籍联动，未连云端时照旧收起）

**手机直接出片**：手机录入 → 顶栏「云端」上传（或打开已有云端谱籍）→ 「印谱」→ 下载 PDF。
本机谱籍未上传时，点出片会先问一句「上传并出片」，确认后自动上传再由服务器生成。

**接力链路**（需要付印 / 大批印制时）：手机录入 → 云端上传 → 电脑端登录同一账号打开同一部谱籍 → 排版出片付印。
手机不做本机文件读写（Android WebView 无下载与选文件通道），数据存本机谱库自动保存，靠云端与电脑互换。

**电脑上**：恒为完整模式，不显示模式切换按钮；所有页签与文件操作照旧。

> 判定依据：`js/env.js` 依据 UA（APK 注入 `YZP-Android/1.0`）、`file://` 协议、指针类型与视口宽度识别；
> 模式记在本机 `yzp.device.mode.v1`，可手动切换并记住。

## 十二 · 常用操作
- 顶栏一键：保存文档 / 另存为 / 打开文档 / 谱库 / 文本导入 / 清空
- 「载入示例谱」：清河张氏 · 百忍堂，4 世 12 人，含序跋与世系录；门派谱示例为「雲章鑄劍門宗譜」
- 「清空」：只清当前谱籍内容，文档本身仍保留在谱库

## 十三 · 打包与分发（桌面版 / PWA / Android）

**一键打包**（推荐）：本机装好 Node.js 与 Python 后，双击 `pack.bat`（或命令行 `python pack.py`）：
自动重建 exe → 冒烟自检（页面加载验证 + 60 秒超时保护）→ 产出 `release/` 两个分发包：
- `雲章譜局-Windows便携版.zip`（110 MB，解压双击 exe 即用）
- `雲章譜局-网页PWA版.zip`（网页版全量 + 局域网分发脚本）

参数：`python pack.py --skip-smoke`（跳过自检）· `--only-web`（只打网页包）。

同一套代码，四种运行形态：

**1. Windows 桌面版（Electron 免安装便携版）**
- 产物在 `desktop/dist/雲章譜局-win32-x64/`，整个文件夹拷到任何 Windows 10/11 机器，双击 `雲章譜局.exe` 即用，无需安装。
- 菜单：文件（保存谱籍文档 Ctrl+S）/ 编辑 / 视图（缩放、全屏）/ 帮助。
- **帮助 → 「手机访问…」**：桌面版内置局域网分发服务，自动弹出二维码，手机扫码即可把 PWA 安装到手机桌面。
- 重新打包：`desktop/` 下运行 `node build.js`（离线组包，无需联网；需先 `npm install`）。

**2. 手机版（PWA，安装到桌面、离线可用）**
- 安卓 Chrome/Edge：打开平台网址 → 菜单「添加到主屏幕／安装应用」→ 得到独立 App 图标，断网可用。
- iPhone Safari：打开网址 → 分享 → 「添加到主屏幕」。
- 离线由 `sw.js` 全量缓存保证；**升级版本时递增 `sw.js` 顶部 `CACHE_VERSION`**，客户端即自动换新。

**3. 浏览器直开**：双击 `index.html`（原始方式，继续有效）。

**局域网分发（无需桌面版）**：电脑上双击 `start-mobile-server.bat`（或 `node server.js [端口]`），手机连同一 Wi-Fi 访问控制台打印的 `http://本机IP:8080` 地址即可安装。`server.js` 零依赖，装了 Node.js 即可运行。

**4. Android APK**
本机装好 Python 与 Node 后执行 `python build_apk.py`：`android/` 下的 WebView 壳工程经
aapt2 → javac → d8 → zipalign → apksigner 手工组包（无需 Gradle / Android Studio），
产出约 0.5 MB 的签名 APK（`android/build/*.apk`）。网页资源由 `desktop/build.js` 同步进 `assets/www`，**与桌面版同源**。
签名密钥为 `*.keystore`，已列入 `.gitignore`，**切勿入库**。

**APK 扫码下载安装**

仓库内置官方下载镜像（`download/` 目录），手机浏览器/微信扫一扫即可获取安装包：

| 项 | 值 |
|---|---|
| 当前版本 | v1.16.0（对应 `sw.js` `CACHE_VERSION`；含录入效率模块与谱籍体检） |
| 安装包 | `download/yunzhangpu-v1.16.0.apk`（签名版） |
| 固定直链 | <https://gitee.com/skylonng_admin_admin/GUJIV/raw/master/download/latest.apk> |
| 下载二维码 | `download/qrcode-apk.png`（见下） |
| SHA-256 | `ed879dfaea1790ec99e1ba1cca6965cd8f60d0e1c667b8384cdcb94b8c087151` |

<div align="center"><img src="download/qrcode-apk.png" alt="APK 下载二维码" width="220" /></div>

> 二维码指向 `latest.apk` 固定文件名——以后发新版直接覆盖该文件，**二维码无需重印**。

**安装步骤**：手机扫上方二维码 → 浏览器打开下载 → 点击安装（需允许「安装未知应用」）→ 完成。
Android 8+ 会提示来源风险，选择「仍要安装」即可；本 APK 为自签名包，校验指纹可在安装前比对
`apksigner verify --print-certs download/latest.apk` 的输出。

**版本发布流程**（打包 → 上架 → 二维码不变）：

```bash
python build_apk.py                                    # 产出 release/雲章譜局-安卓版.apk
cp "release/雲章譜局-安卓版.apk" download/latest.apk    # 覆盖固定直链文件
cp "release/雲章譜局-安卓版.apk" download/yunzhangpu-vX.Y.Z.apk   # 留版本副本
node test-pdf/gen-qrcode-png.js "https://gitee.com/skylonng_admin_admin/GUJIV/raw/master/download/latest.apk" download/qrcode-apk.png 10   # 仅当直链变更时需要重生成
python push-gitee.ps1 -AutoCommit                      # 提交推送（或双击 push-gitee.bat）
```

**从仓库获取其他分发包**：
- **Windows 便携版 / PWA 版**（110 MB / 400 KB）体积较大，不入 Git；可到 Gitee 仓库
  「发行版（Releases）」页面按 tag 获取，或联系晟唐科技索取。

**打包注意事项**
- 应用图标在 `assets/`（`icon-512.png` / `icon-256.png` / `icon.ico`，源稿 `icon-src.html` 用浏览器渲染）；`manifest.webmanifest` 与 Electron 均引用之。
- `desktop/build.js` 流程：同步网页文件 → `@electron/asar` 封包 → 复制本地 Electron 运行时 → 改名 exe。全程不联网，不依赖 GitHub。
- 已知限制：exe 文件在资源管理器中的静态图标暂为 Electron 默认（写入 PE 资源的工具在本机过慢被移除），**运行后窗口与任务栏图标正常**；如需完美图标可用 Resource Hacker 手动替换。
- APK 内 `window.print()` 为空操作，**手机端出片走云端服务端导出**：打开云端谱籍后「印谱」页签自动出现，
  按钮改称「下载 PDF（服务端生成）」，点一下即由服务器排版生成并下载（见第九、十一节）。

## 十四 · 源码仓库与同步

- 仓库：<https://gitee.com/skylonng_admin_admin/GUJIV>（Gitee，国内平台）
- **提交 / 推送**：双击 `push-gitee.bat`（逻辑在 `push-gitee.ps1`）。
  它会自动探测本机 git（含 WorkBuddy 内置 PortableGit）、检查分支、可先提交改动，
  再以令牌鉴权推送。**直连优先**：某些环境注入的 `http_proxy` 会让 `receive-pack` 挂死，脚本仅在非鉴权失败时才回退代理。
- 首次按提示粘贴 Gitee 私人令牌（需 `projects` + `repo` 权限），询问是否记住时输入 `Y` 即写入本机凭据存储，此后免密。
- `.gitignore` 已排除依赖与产物：`node_modules`、`tools/`（离线 JDK / Android 构建工具链 约 850 MB）、
  `desktop/dist` 与 `app.asar`、`release/`、`android/build/`、`shots/`、`.epicon/`、
  **`cloud/data/`（含用户令牌与口令哈希）**、`ref/`（家谱扫描件）、`*.keystore`。
  > 注意：`.gitignore` 的行尾注释会被 Git 计入匹配模式导致规则静默失效，**注释必须独占一行**。

## 十五 · 回归测试

| 层面 | 脚本 | 覆盖 |
|---|---|---|
| 古籍版式 / 墨韵 / 做旧 / 批注 | `test-pdf/guji-verify.js` | 45 项，含各版式体检、确定性、往返 |
| 门派宗谱数据与成书 | `test-pdf/school-verify.js` | 26 项 |
| 書稿解析与校勘往返 | `test-pdf/classic-edit-roundtrip.js` | 50 项 |
| 云端结算与额度 | `cloud/test-pay.js` | 86 项 |
| 服务端谱籍导出 | `cloud/test-export-server.js` | 27 项 |
| 批量导出（服务端） | `cloud/test-batch-export.js` | 37 项：ZIP 自解析校验 / 同名不覆盖 / 五种格式 / 计费与退款 / 去重与越权 |
| 手机端出片 + 批量导出（浏览器级） | `desktop/test-batch-export.js` | 32 项：出片入口随云端谱籍联动 / 服务端 PDF 下载 / 勾选打包 ZIP / 无权限引导升级 |
| 服务端書稿导出 | `cloud/test-classic-export.js` | 16 项（含会员免积分） |
| 基础功能加固（数据层） | `test-pdf/core-hardening.js` | 33 项：成环不卡死 / 体检与修复 / 导入上限与跳级保护 |
| 录入效率（数据层） | `test-pdf/test-ingest.js` | 65 项：表格与 CSV 解析 / 按父名接树（孤儿·重名·成环·自指）/ 体检七类错处 / 字段模板 |
| 录入效率（浏览器级） | `desktop/test-ingest.js` | 55 项：三式页签与实时预览 / 缺名讳列拦截 / 名单式挂子嗣 / 体检定位与一键修 / 详略显隐与记忆 / 常用值复用 |
| 云端安全与健壮性 | `cloud/test-hardening.js` | 36 项：回调验签 / 撞库锁定 / 令牌即时失效 / 资源上限 / 限流 |
| 会员等级与功能权限（服务端） | `cloud/test-member.js` | 42 项：版式闸门 / 门派谱闸门 / 四种开通途径 / 到期回落 |
| 会员闸门（浏览器级） | `desktop/test-member-gate.js` | 33 项：离线全放开、云端拦截回滚、升级后解锁、管理员授予 |
| 前端基础加固（浏览器级） | `desktop/test-core-ui.js` | 33 项：检索高亮 / 撤销重做 / 空名拦截 / 异常兜底条 |
| 端角色（浏览器级） | `desktop/test-device-mode.js` | 36 项：手机录入模式裁剪 / 连续录入 / 模式切换记忆 / 电脑端完整模式 |
| 三端集成审计 | `test-pdf/audit-integration.js` | 桌面 / PWA / APK 资源同步 |
| 浏览器级 UI | `desktop/shot-guji.js`、`desktop/shot-school.js`、`desktop/shot-core.js` | Electron 真机断言 + 截图 |

## 十六 · 版权与许可

**Copyright © 2026 晟唐科技（ShengTang Technology）. All rights reserved.**

本软件为 proprietary software（专有软件）。

- **权利人**：晟唐科技
- **授权范围**：允许为学习、研究与非商业性评估目的查阅本仓库源码、自行编译运行与修改；
  **未经晟唐科技书面授权，不得用于任何商业目的**，包括但不限于转售、SaaS 服务、
  托管他人使用、二次发行，以及移除或变更版权标识后的任何形式的再分发。
- **保留权利**：本声明未明示授予的任何权利，均由晟唐科技保留。
- **第三方依赖**：本项目整体零第三方运行时依赖（服务端仅 Node 标准库，网页端无任何框架）；
  若后续引入第三方组件，其许可各自独立，以其原始 LICENSE 为准。
- **商标**：「雲章譜局」名称、标识与水印背景图（`assets/menu-bg.svg`、应用图标）归晟唐科技所有，
  不因本仓库的公开而授予任何商标使用许可。
- 完整条款见 [`LICENSE`](LICENSE)。如需商业授权或定制合作，请联系晟唐科技。

## 说明
- 繁简转换与异体字面板是快捷手段，**正式付印前请以人工校勘为准**。
- 所有数据仅存于本机（浏览器 localStorage + 你自己保存的文件），不上传任何服务器。
- 云端数据存于你自行部署的服务器 `cloud/data/` 目录，由部署方自行负责备份与合规。
- 谱库属浏览器本地数据，清理浏览器缓存会丢失；重要谱籍请定期「保存文档」为 `.yzp` 文件归档。