1）核心概念（培训先讲这 3 点）

• 系统三层结构：项目（Project）→ 患者（patient_code）→ 随访/化验/用药/事件
• 入口：管理端 /staff（需要登录），录入端 /p/<token>（无需登录）。
• 合并键：多中心最终按 center_code + patient_code 合并。

2）Token 随访令牌 — 新手必读

Token 是什么？

Token（令牌）是一串随机字母数字，充当患者随访页面的「钥匙」。长相类似：

包含 token 的链接格式：

患者（或随访护士）打开链接 → 填写随访数据 → 提交，全程不需要账号。

• 每条 token 只绑定一个患者，不会串联到其他人
• Token 本身不含任何个人信息，泄露了也可以立即撤销
• 泄露或发错：点「立即撤销此 token」，链接瞬间失效，已提交数据不受影响

Token 的四种状态

状态	颜色	含义	能否提交随访
有效	🟢 绿	正常可用	✅ 能
已使用	🔵 蓝	单次 token 已提交过一次	❌ 不能，需重新生成
已撤销	🔴 红	管理员手动撤销	❌ 不能
已过期	⚫ 灰	超过有效期	❌ 不能，需重新生成

两种 Token 类型

类型	适合场景	设置方法
可多次使用（默认）	长期随访，每次复诊用同一链接	不勾选「单次使用」
单次使用	一次性问卷、防止重复提交	勾选「单次使用」

3）PII（个人身份信息）保护 — 必须了解

什么是 PII？

PII（Personally Identifiable Information）是指任何能识别出具体自然人的信息。

PII 类型	举例	系统处理
手机号	13812345678	❌ 前端+后端双重拦截
身份证号	110101199001011234	❌ 拦截
住院号/病案号/MRN	住院号:20240012345、MRN: 789	❌ 拦截
姓名	患者:张三、姓名：李四	❌ 拦截
邮箱	patient@qq.com	❌ 拦截
8位以上连续数字	20240012345678	❌ 拦截

正确 vs 错误 — 备注填写示例

前后端双重拦截机制

• 前端（即时）：输入时实时扫描，输入框变红并提示 ⚠ 检测到疑似PII
• 后端（兜底）：数据库触发器再次校验，命中即拒绝写入，返回 400 错误

即使绕过前端，数据库层也会阻止 PII 落库，实现双重保险。

4）上线准备（⚙️ 仅系统管理员/IT 需要，医生和护士可跳过）

私有化部署或自行搭建请联系技术支持获取部署文档：china@kidneysphere.com。SaaS 版用户无需任何部署操作，注册后即可使用。

5）标准操作流程（SOP）

步骤 1：管理员创建项目

• 进入 /staff，使用邮箱和密码登录；忘记密码可点击「忘记密码」通过邮件重置。
• 创建项目并填写：项目名、center_code、module。

步骤 2：录入患者基线

• 必填：patient_code（如 0001，中心内唯一即可）
• IGAN 可选填 Oxford MEST-C

步骤 3：生成 token 并分发

• 在患者行点击“生成随访 token”。
• 将 /p/<token> 链接发给随访录入人员。

步骤 4：随访人员录入访视

• 录入核心四项：日期、BP、Scr、UPCR。

步骤 5：管理员质控与导出

• 检查缺失值/异常值。
• 生成 Snapshot。
• 导出论文包 ZIP 并进行统计分析。

6）实战演示模板（15 分钟培训）

1. 创建项目：IgAN-BJ-2026（center_code: BJ01）。
2. 新增患者：0123，MEST-C: M1 E0 S1 T0 C1。
3. 发送 token 给护士 A。
4. 完成两次随访录入并核查时间递增、数值合理。

7）填写规范

• patient_code 为中心内唯一编号（如 0001）。多中心合并键为 center_code + patient_code，无需在编号中重复中心前缀。
• 日期统一 YYYY-MM-DD。
• 缺失值留空，不要用 0 代替。
• 统一单位，异常值先复核再提交。

⚙️ 常见问题

Q：登录遇到问题？
A：当前登录方式为邮箱 + 密码。如忘记密码，请在登录页点击"忘记密码"重置。如仍有问题请联系 china@kidneysphere.com。

Q：可以录入姓名电话吗？
A：不可以，只能用研究编号。

Q：如何保证论文复现？
A：先生成 Snapshot，再基于 Snapshot 导出论文包并引用 snapshot ID。

8）化验数据录入

化验录入支持两种路径：字典化录入（自动单位换算，跨中心一致）和自定义录入（任意化验均可添加，自动保存到项目目录）。

路径一：字典化录入（有标准换算）

1. 下拉选择化验项目（按模块分组，如 GENERAL / MN / KTX）
2. 选择单位（根据项目自动过滤允许的单位）
3. 填写数值 → 标准值框自动实时显示换算结果
4. 点「添加化验记录」

路径二：自定义化验录入（列表外的指标）

1. 下拉选择"＋ 新增自定义化验（保存到本项目目录）"
2. 输入化验名称（如：补体因子H）和单位（如：mg/L）
3. 填写数值 → 点「添加化验记录」
4. 系统自动将该化验保存到本项目目录，同项目所有患者后续可在"本项目自定义"分组中直接选用

常用换算示例

化验项目	录入值	录入单位	标准值（自动显示）	标准单位
血肌酐（CREAT）	88.4	μmol/L	1.0000	mg/dL
血肌酐（CREAT）	1.2	mg/dL	1.2000	mg/dL（已是标准单位）
尿蛋白/肌酐比（UPCR）	2000	mg/g	2.0000	g/g
血红蛋白（HGB）	120	g/L	12.0000	g/dL
总胆固醇（TCHOL）	200	mg/dL	5.1720	mmol/L
抗PLA2R抗体（PLA2R）	28	RU/mL	28.0000	RU/mL（MN专项）
BK病毒载量（BKV）	5000	copies/mL	5000.0000	copies/mL（KTX专项）
糖化血红蛋白（HBA1C）	53	mmol/mol	7.0000	%（NGSP，自动换算）
尿白蛋白/肌酐比（UACR）	35	mg/mmol	309.5000	mg/g（欧洲单位自动换算）

同日重复化验的处理

同患者同日同项目已有记录 → 系统显示警告，「留痕原因」框出现（必填）：

9）质控 Issue 系统

每当系统检测到数据问题，自动生成一个 Issue（工单），状态为 OPEN，直到问题解决才关闭。
类比：就像 GitHub Issues 管理 bug，这里管理数据质量问题。

Issue 严重度

严重度	颜色	例子	对分析的影响
严重（critical）	🔴 红	随访日期早于基线日期	数据无法用于时序分析
警告（warning）	🟡 黄	血肌酐较上次增加 3 倍	数据可疑，需研究者确认
提示（info）	🔵 蓝	缺性别导致无法算 eGFR	建议补充，不影响其他分析

Issue 处理流程

1. 后台「质控 Issue」区域查看汇总
2. 点「查看所有 Issue」展开列表
3. 修正数据 → 对应 Issue 自动关闭（RESOLVED）
4. 确实无法修正 → 点「标记不修复」→ 填写原因（必填）

10）导出数据 & 论文包（v2 新增三件套）

点「一键生成论文包」，生成 zip 文件，v2 新增三个顶刊必备文件：

文件	内容	用途
data_dictionary.json	字段定义、单位、eGFR 公式版本、换算规则、化验字典摘要	审稿人/合作者理解数据口径
qc_report.csv	各中心缺失率（SCR/UPCR/SBP）、Issue 统计、关闭率	投稿数据质量报告
snapshot_manifest.json	快照 ID、生成时间、各表行数、QC 汇总	论文 Methods 引用，确保可复现

eGFR 公式版本说明（egfr_formula_version 字段）

值	含义
CKD-EPI-2021-Cr	系统自动计算（引用：Inker et al., NEJM 2021;385:1737-1749）
manual	研究者手动填写（来自实验室报告）
missing_inputs	缺性别或出生年，无法计算

快照 ID 在论文中的引用格式

11）国际标准对接（LOINC / HGVS / 病理）

① LOINC 编码 — 化验项目的"国际身份证"

LOINC 是全球通用的化验项目标准编码，每个检查都有唯一编号，避免不同医院因叫法不同造成合并错误。

不懂没关系：常见项目的编码已经内置，录入时系统会自动带入，一般不需要手填。如需查询：loinc.org/search（输入中文检查名即可）。

② HGVS 格式 — 基因变异的标准写法

HGVS（Human Genome Variation Society）是基因变异的国际规范写法，避免同一个突变被写成多种格式。

什么时候需要填？只有在录入基因检测结果时才需要，普通肾功能随访不涉及。

③ 病理结构化评分 — IgAN / 狼疮肾炎 / 移植肾

后台已提供 IgAN（Oxford MEST-C）和狼疮肾炎（ISN/RPS 2003/2018 分型 + NIH AI/CI）的专用结构化录入界面，在创建患者基线时直接选择评分即可，无需手动拼字符串。

12）FAQ 常见问题

Q：token_expired — 随访链接过期了怎么办？
A：管理员重新生成链接（后台 → 患者列表 → 生成链接），发新链接给患者。

Q：token_already_used — 单次 token 已使用，患者要重填怎么办？
A：重新生成一条新 token，发给患者。

Q：pii_detected_blocked — 备注无法保存怎么办？
A：删除备注中的个人信息（手机号/身份证/住院号/姓名），只保留临床描述。
✅ 正确：血压控制满意，无明显不良反应
❌ 错误：患者张三，13812345678，住院号20240001

Q：unit_not_allowed — 单位不允许怎么办？
A：对于字典化化验项目，从单位下拉列表选择即可。如果是标准列表中没有的化验项目，请在下拉中选"＋ 新增自定义化验"，自由填写名称和单位，不受列表限制。

Q：血肌酐跳变警告，需要填留痕原因怎么办？
A：如果值是真实的（如 AKI），在「留痕原因」框填写说明，例如：
患者因感染住院发生急性肾损伤，值经主治医生确认属实
然后点保存，数据正常入库，原因被永久记录。

Q：eGFR 没有自动计算？
A：检查患者基线信息中是否填了性别和出生年。补填后，下次录入随访时 eGFR 会自动计算。

Q：可以录入姓名电话吗？
A：不可以，本系统只用研究编号，任何 PII 都会被前后端双重拦截。

Q：如何保证论文复现？
A：生成 Snapshot（得到 KS-YYYY-XXXXXXXX 格式 ID）→ 导出论文包 → 在 Methods 中引用 snapshot_id。