本手册是逐项操作参考。第一次使用请先看使用说明 · 快速上手，并在一个独立的测试项目里用模拟数据演练。引号中的文字与工作台上的按钮或栏目名称一致；如果工作台没有对应入口，请联系技术团队核对部署版本。

1. 项目、研究编号与记录

工作台按“项目 → 研究对象 → 基线、随访及扩展记录”组织数据。一个项目对应一个研究队列，有自己的中心代码和病种模块。多中心研究由各中心分别建项目、分别授权，再汇总；系统没有自动覆盖所有中心的上级权限。

• 研究对象由“项目 + 中心代码 + 研究编号”确定（导出文件中对应 project_id、center_code、patient_code 三列）。同一编号在不同中心或项目中不是同一个人。
• 0001、1 和含字母的编号都按原样保存。不要让电子表格把编号自动转成数字。
• 研究编号与姓名的对照表由医院按规定保管，不上传到工作台。每位研究对象在同一项目内只有一条基线，随访按日期逐条增加。

2. 成员权限与交接

1. 同事用自己的邮箱注册并完成邮箱验证，不共用负责人的账号。
2. 负责人选择项目，在“项目信息与协作成员”中填写同事的注册邮箱、选择角色，点“添加成员”。系统不发送邀请邮件，请另行告知；负责人角色不能转让或新增。
3. 受邀同事登录后在项目列表中核对项目名称、中心代码与自己的角色。离组时由负责人移除，已录入的数据保留。录入协作人被移除或降为分析 / 只读角色时，确认后本项目现有的随访链接全部失效，需要继续随访的请重新生成。

关闭导出不等于防复制：能查看的人就能看到研究数据，请只授权必要的人。选择角色也不构成伦理授权。

试用或订阅到期后，项目转为只读：不能录入、导入、更正，也不能生成新的随访链接；成员仍可查看，负责人和分析协作人仍可冻结与导出，负责人和录入协作人仍可撤销链接，负责人仍可管理成员。能否录入按项目负责人账户的状态判断，不要通过重复注册绕过。

3. 研究授权、知情同意与隐私

录入真实数据前，机构与课题负责人应确认研究方案、伦理审批（或适用的豁免）、知情同意、数据用途、字段范围、参与成员和数据接收方。工作台账号、冻结版本或数据质控通过都不能代替这些确认。

知情同意状态与随访状态

每位研究对象在“随访看板”一行的“研究状态”中记录两项状态，每次修改都会留痕：

• 改为“拒绝”“撤回”，或随访状态改为“退出研究”“死亡”时，需要填写原因；保存后该患者尚有效的随访链接由系统自动撤销，已提交的数据不受影响。撤回同意且不再随访时，建议同时把随访状态改为“退出研究”。
• 分析脚本默认只纳入知情同意为“已同意”或“伦理批准豁免”的患者，其余患者的记录不进入结果，排除人数写在运行日志中。所以请及时把“未确认”改为实际状态。

隐私与数据保护

医疗健康信息属于敏感个人信息。用研究编号替代姓名是去标识化，不等于匿名化，编码后的记录仍可能与个人关联，应按敏感个人信息管理。参见《个人信息保护法》第二十八条、第七十三条。

• 不要输入姓名、电话、身份证号、病案号、完整住址或编号对照表，也不要把含这些内容的报告全文粘贴进备注。
• 系统会提示或拦截部分常见的身份信息格式，但不能识别所有姓名、变体或组合识别风险，提交前仍需人工核对。
• 数据存放位置以隐私政策为准，见数据存在哪里。不能根据网站域名或网页服务器位置推断数据所在地。
• 误录或误发时，停止进一步传播，联系项目和机构的数据负责人处置。不要为“补救”自行批量删除记录或销毁留痕。见隐私政策、安全说明。

4. 首次准备：负责人完成后交接给同事

1. 在登录页用邮箱和密码登录（也可以选“邮箱登录链接”）。在“项目 → 新建项目”填写清晰的项目名称、中心代码，选择病种模块，点“创建项目”。同一中心的新研究也应单独建项目。
2. 在“项目设置（仅项目负责人）”中按研究方案确认随访间隔（7–730 天，默认 90 天），它决定看板上的“下次应随访”日期和逾期提醒。这里填写的研究名称、机构名称、伦理批件号和研究团队联系方式会显示在患者随访页上，只填写可以对外公开的信息，点“保存项目设置”。
3. 按研究方案确认基线日期定义、访视窗口、血肌酐和蛋白尿单位、病理与事件定义，以及哪些字段允许缺失，把数据字典版本发给所有录入人员。
4. 按权限表添加同事，确认每人看到的项目与角色正确。先用模拟数据演练录入、更正和一次冻结导出（见模拟演练），再开始正式采集。
5. 确认数据保管、联系人、成员离组处理和备份恢复安排。冻结导出保存的是当时的数据内容，不替代日常备份与恢复演练。

账号问题

• 忘记密码：在登录页选“忘记密码”，输入注册邮箱，打开邮件中的链接设置新密码。
• 邮件里的登录或确认链接打不开、提示过期：邮件链接只能使用一次且有有效期。打开后的提示页可以直接输入邮箱重新发送，也可以在登录页选“邮箱登录链接”。
• 提示邮箱还没有验证：在登录页按提示点“重新发送确认邮件”，并检查垃圾邮件。
• 添加成员失败：确认对方已用该邮箱注册并完成验证、尚未在本项目中，再重试。不要反复尝试他人邮箱；仍失败请联系支持。

5. 日常随访：看板、录入、研究状态与核对

1. 先选项目，看“项目概览”：入组人数、在访人数、近 30 天新增随访、核心四项完整率（随访日期、血压、血肌酐、尿蛋白/肌酐比值均已填写的随访占比）、逾期 / 14 天内到期 / 尚无随访人数、知情同意已确认 / 未确认人数、待处理的数据质控问题。点数字可跳到看板中对应的筛选。
2. 在“随访看板”确定今天要随访谁：每位研究对象一行，显示中心、最近随访日期、距今天数、下次应随访日期、状态（逾期、即将到期、尚无随访、正常、已停止随访）、有效链接数和知情同意状态，逾期者排在最前，可按研究编号查找。
3. 新增研究对象：在“新增患者（建立基线）”填写研究编号、性别、出生年份、真实基线日期及已获得的指标，点“核对并保存基线”。基线血肌酐按 μmol/L；尿蛋白/肌酐比值按化验单选择单位并核对换算。基线日期可以暂缺，但脚本无法据此建立年度窗口和基线变化。已有基线的研究编号不要重复建立。
4. 录入随访（研究人员代填）：在看板该行点“录入随访”。随访日期默认今天；收缩压一栏可直接输入“130/80”自动拆分；血肌酐可选 μmol/L 或 mg/dL，系统换算后按 μmol/L 保存；尿蛋白/肌酐比值选择 mg/g 或 g/g；备注不写身份信息。点“保存”，连续录多位时点“保存并录下一位”。同一天内容完全相同的记录不会重复保存；同一天已有内容不同的记录时，请打开“随访记录”核对后更正。
5. 或请患者自己填写：见随访链接。
6. 填写“研究状态”：见知情同意状态与随访状态。
7. 核对与更正：在看板该行点“随访记录”，检查日期、数值、单位和来源（经随访链接提交的会标注）；发现错误在该行点“核对 / 更正”，基线错误点“核对 / 更正基线”，核对修改前后的值，填写原因后保存，修改会留痕。研究编号不能在更正窗口中修改，编号错误交由负责人核查。
8. 病理和分组：只转录已有报告或已批准的分配结果。没有报告就留空，不把未知病理评分填 0；分组字段不提供自动随机化或分配隐藏。

6. 随访链接：生成、提交、撤销

随访链接是一项访问凭证：拿到完整链接的人不用登录就能为对应研究对象填写随访，并看到项目对患者显示的信息。只发给该患者或授权填写人，不发到公开群、公开文档或截图中。

1. 负责人或录入协作人在看板该行点“随访链接”。窗口上方“生成新链接”：设置有效期（1–365 天，默认 30 天）和是否“单次使用（提交一次后自动失效）”，点“生成新链接”。
2. 链接全文只在生成时显示一次，系统只保存无法还原链接的校验值。请立即点“复制链接”或“复制发送文本”发给填写人；遗失时撤销后重新生成。不要自行拼接或删改链接。
3. 填写人打开链接后核对项目与研究编号，不一致就停止填写；按化验单选择单位，核对后点“核对并提交”，保留提交回执。单次链接用过、过期或被撤销后不能再提交，下一次随访请重新生成。
4. 窗口下方“已发放的链接”列出每条链接的创建时间、到期时间、单次或多次、状态（有效、已使用、已过期、已撤销、系统自动停用）。链接泄露、发错或不再需要时点“撤销”，填写撤销原因（不含身份信息），链接立即失效，已提交的数据不受影响。
5. 以下情况系统会自动撤销或停用链接：知情同意改为“拒绝”或“撤回”、随访状态改为“退出研究”或“死亡”、录入协作人的写权限被撤销、同一链接提交过于频繁或同日提交次数超限。项目到期后不能生成新链接，但仍可撤销已发放的链接。

提交超时，请先看页面提示，重试同一次提交或重新验证链接，再核对回执和随访记录，不要立即新建一条相同的随访。读取历史失败不代表提交失败。

7. 日期、缺失与单位规则

分析时原始 eGFR 保留在 egfr_recorded 列，对明确标注 CKD-EPI 2021 的记录按当前来源重新估算并记录差异；来源不明的历史 eGFR 不视为已核实。公式来源见Inker 等，2021 年发表的 CKD-EPI 公式原文 Table 2；是否适用于本队列由研究团队判断。

8. 化验及扩展记录

在“附加数据”中先选研究对象，再选检验项目、采样或检验日期、原始数值与原单位，核对换算提示后保存。修改历史记录时用“核对 / 更正”并说明来源；原值与单位必须来自同一份报告。

CD19 百分比不能当作细胞绝对计数；病毒载量 copies/mL 与 IU/mL 没有经过验证的换算关系时不能按 1:1 互换。无法换算或原值与换算值矛盾时，记录保留并交团队核实，相关结果不进入分析。

用药按已有记录填写名称或分类、剂量、途径、频次和日期；终点事件填写类型、日期、来源与确认状态。系统不提供用药建议，事件仍需按研究方案裁定。用药和终点事件记录可由负责人或录入协作人删除，删除会留痕；化验记录录错时用“核对 / 更正”。

病理、检验编码、基因与其他专业字段

病理评分照报告转录，例如 IgA 肾病的牛津病理分类评分（MEST-C）、狼疮性肾炎的 ISN/RPS 分型。检验项目代码（如 LOINC）须与实际项目、样本、方法和单位一致。基因字段保留报告中的基因、HGVS 命名、转录本、合子状态及来源；基因数据涉及人类遗传资源管理，工作台默认不开放录入，迁至境内并完成合规评估后由管理员开启。不要为填满表格编造专业代码；分析脚本不做遗传变异解释，也不会因字段齐全自动生成遗传诊断或风险分层。

9. CSV 批量导入

1. 在“批量导入（CSV）”选择“患者基线”或“随访记录”，点“下载模板 CSV”。目前只支持这两类批量导入。
2. 每批最多 500 行，文件不超过 2MB。保留表头，研究编号按文本保存。基线须填写已核实的 UPCR 单位列，或在页面上明确选择该批未标注记录的单位；单位混杂的文件应逐行标注。
3. 基线模板可以包含知情同意与随访状态列，取值用以下代码：知情同意 unconfirmed（未确认）、consented（已同意）、waiver（伦理批准豁免）、declined（拒绝）、withdrawn（撤回）；随访状态 active（在访）、lost（失访）、withdrawn（退出研究）、deceased（死亡）、kidney_failure（肾衰竭）、transferred（转院）。
4. 确认血肌酐列为 μmol/L、随访 UPCR 为 mg/g，勾选单位确认后选择文件，查看预览、错误行与拟变更，先改正重复编号、必填值、日期和单位问题。
5. 点“确认导入”。服务器整批校验，校验失败不会只导入前半批。网络中断时先看反馈，在原页面重试同一批次（同一批次不会重复写入），再核对患者与随访数量。
6. 已有基线只按本次明确提供的字段处理，空白不会清除已有内容；需要清空或纠正时用更正功能并填写原因。

预览和服务器校验是数据质控的一部分，不能代替授权、单位核实或对原始病历的人工核对。来源不明的值不要通过填假单位或 0 强行导入。

10. 数据质控问题与更正

1. 在“数据质控问题”点“查看未解决的问题”，按研究编号和问题说明定位。看到“读取失败”时先解决读取问题，不能当作没有问题。
2. 点“核对原记录”，对照原始报告修改可更正的字段，填写具体原因，确认修改前后的值后保存。
3. 刷新列表确认重新检查的结果。不能用“标记已解决”代替更正数据。
4. 团队核实后决定保留异常原值时，选“接受不修复”并写明理由。该状态与“已修正”分开统计，原数据保持不变。

没有待处理的数据质控问题，不代表数据已完整、隐私风险已消除或临床终点已成立。本地分析还会另外检查身份、时间、单位与公式来源，输出 qc_issues.csv 和 qc_report.xlsx。

11. 冻结数据、下载分析包、复核结果

11.1 选择导出方式

负责人和分析协作人可在“导出当前项目数据”中单独下载基线、随访等 CSV 用于核对，但各次下载可能来自不同时刻。需要同一数据版本时，在“数据快照（冻结的数据版本）”中点“冻结并导出完整分析包”，或在“科研数据与分析脚本包”中点“导出分析脚本包（ZIP）”，两者都基于数据库同一时刻的一次读取。

“冻结当前数据版本”只保存版本、不下载。版本列表中的已冻结版本可以重新下载相同内容与校验值；早期的“元数据记录”只有说明和数量，不能恢复历史数据。冻结不会锁住后续录入，也不等于备份恢复。

11.2 包内九张表

analysis/data/ 中有前八张表的原值 CSV，前六张是分析脚本的核心输入，空表也有表头。excel_safe/ 中是供 Excel 查看的副本，文字可能带有防公式前缀，不要拿它替换分析输入。research_data.json 保留服务器原始内容和类型；data_dictionary.json 说明字段含义，包括知情同意与随访状态的取值。

11.3 校验与留存

export_manifest.json 记录源内容校验值 source_content_sha256 和包内每个文件的 SHA-256。请保留未改动的 ZIP 与清单；浏览器在读取冻结内容时会核对校验值，不一致会停止下载。同一冻结版本重新下载的 JSON 校验值相同；重新生成的 ZIP 可能因导出时间或脚本版本不同而不同。

需要人工核对时，在解压后的包根目录运行下面一条命令，把输出与清单中的 source_content_sha256 比较：

python -c "import hashlib,pathlib; print(hashlib.sha256(pathlib.Path('research_data.json').read_bytes()).hexdigest())"

校验值用于发现内容变化，不证明结论正确或数据已匿名化。只在获准的协作范围和环境中分享分析包，不上传到公开仓库或公开的在线工具。

11.4 在自己电脑上运行

安装 Python 3.11 或 3.12，在包含 analysis/ 的包根目录打开终端，先建立独立环境：

python -m venv .venv

Windows 命令提示符运行 .venv\Scripts\activate；macOS / Linux 运行 source .venv/bin/activate。然后：

python -m pip install -r analysis/requirements.txt
python analysis/run_analysis.py

只有看到 DESCRIPTIVE_REVIEW_OK，新生成的 analysis/outputs/run-时间/ 才是本次结果；出现 ANALYSIS_FAILED 表示本次失败，先解决输入问题，不要把上次的结果当成本次输出。如果基线表有知情同意状态，脚本只纳入“已同意”或“伦理批准豁免”的患者，排除人数写在 RUN_LOG.json。

不带研究方案运行时（上面的命令），输出：

• table1_baseline.xlsx：描述性基线表与各指标可用人数，不汇总任何下降率或缓解率。
• outcomes_12m.csv：在基线后 270–450 天内选离 365 天最近的一整条随访；没有合格记录标为“暂无可评估年度随访”，不补 0、不拼接。
• candidates_unconfirmed_egfr_decline.csv、candidates_unconfirmed_igan_proteinuria.csv：任一次测量越过固定数值就列出的“未确认候选”，不要求持续确认，不是终点，也不是缓解。
• manual_events_review.csv：逐条保留人工录入的事件；明确确认、有日期且在基线之后才标为随访期内已确认。
• egfr_slope_per_patient.csv 与趋势图：描述性个人趋势，至少需要两个不同日期，同日多个值先取均值。
• qc_issues.csv、qc_report.xlsx、labs_review.csv：缺失、单位和来源问题，需要团队复核。
• RUN_LOG.json、METHODS_ACTUAL_EN.md、MODEL_STATUS.json：本次的输入与输出校验值、人数、版本、实际执行步骤（英文方法学草稿，需研究团队审阅）和未执行的功能。

11.5 按研究方案判定终点

终点和缓解的定义属于研究方案，由课题负责人确定，脚本不替研究者选择临床阈值。包内 analysis/protocol_template.json 中的定义和阈值只是示例，全部标为“需课题负责人确认”；直接使用模板不会计算任何终点。

1. 复制模板（例如 analysis/my_protocol.json），修改方案编号和版本号；每次改动定义都换版本号。
2. 课题负责人对照原文和本研究方案，逐项确认基线取值方式、eGFR 下降阈值与持续确认条件（至少几次测量、首末间隔几天）、各病种的缓解条件、截尾规则（哪些随访状态与已确认事件的日期作为截尾）和单位。
3. 把已确认章节的“需确认”标记改为否，并填写确认人和日期。拼错字段名、出现模板没有的字段、数值越界、标为已确认却缺确认人或日期，脚本都会拒绝运行。
4. 运行 python analysis/run_analysis.py --protocol analysis/my_protocol.json。

输出 endpoints_per_protocol.csv（每行是一名患者的一个终点，写明“已按方案判定”、满足 / 未满足 / 无法判定 / 其余条件待人工补核，以及事件日期、基线值与截尾信息）和 timepoints_per_protocol.csv（按方案时间点选出的随访）；protocol_used.json 是所用方案的原样副本，方案全文与 SHA-256 同时写入 RUN_LOG.json 和 METHODS_ACTUAL_EN.md。未覆盖或未确认的病种和章节不计算。这是按方案参数的程序化判定，不等于终点委员会的人工裁定。

11.6 多中心合并

各中心按批准范围冻结导出，由数据协调中心（DCC）把各中心六张核心原值 CSV 分别放入 centers/A/、centers/B/ 等目录，保留各自的项目、中心和记录身份，不混入 Excel 副本，不改写编号：

python analysis/merge_centers.py --dirs centers/A centers/B --out analysis/merged-data --qc merge_qc.xlsx
python analysis/run_analysis.py --data analysis/merged-data

只有出现 MERGE_OK 才运行第二条。记录编号相同且内容完全一致的可以去重；同编号内容不同或同一患者有多条冲突基线会阻止合并。质控文件要放在输入和输出目录之外，重跑时换一个新的空输出目录。核对 RUN_LOG.json 中的输入目录、人数和输入校验值确实是合并后的数据。两张肾移植扩展表不在合并脚本范围内。

12. 一次模拟演练

13. 常见问题

数据存在哪里？

网页、账户认证、登记数据库与附件目前均部署在阿里云中国境内（上海）的服务器上，即登记数据存储在中国境内，每日自动加密备份；具体以隐私政策中的说明为准。如果所在机构对数据存储有额外要求（例如院内部署），请在录入真实数据前联系 china@kidneysphere.com 确认，并按机构要求完成相应评估。

谁能看到我的数据？

只有被负责人添加到该项目的成员能看到这个项目，看到和能做什么取决于角色，见权限表。其他项目的成员、其他中心看不到。患者通过随访链接只能为对应的研究对象填写随访并看到项目对患者显示的信息。平台运维人员仅在提供技术服务所需范围内按协议处理数据，详见隐私政策。

分中心怎么加入？

分中心成员先用自己的邮箱注册并验证，再由项目负责人在“项目信息与协作成员”中添加并选择角色；系统不会自动发送邀请邮件，请另行告知对方登录。每个项目只有一个中心代码，所以多中心研究通常每个中心一个项目：可由各中心负责人自建，也可由牵头单位创建后把分中心成员加进去（占用创建者的项目配额）。各中心冻结导出后，由数据协调中心合并（见多中心合并）。伦理备案和协作协议由各中心按机构要求办理。

导出能用 R、SPSS 或 Excel 打开吗？

可以。导出的 CSV 均为带 BOM 的 UTF-8 编码：Excel 查看请用 excel_safe/ 中的副本或 XLSX 文件；R 可用 read.csv(..., fileEncoding = "UTF-8-BOM", colClasses = c(patient_code = "character")) 读取；SPSS 和 Stata 导入文本数据时选择 UTF-8 编码，并把研究编号设为字符串。research_data.json 适合程序读取。研究编号务必按文本读入，避免 0001 变成 1。

患者不会用手机怎么办？

研究护士或医生可以在门诊或电话随访时，在“随访看板”该患者一行点“录入随访”直接代填，不需要随访链接；也可以由家属或护士用随访链接代为填写。代填时按原始化验单核对单位。

随访链接过期了怎么办？

过期、已使用或已撤销的链接不能再提交。先在该患者的“随访记录”中核对是否已经提交过；需要继续随访时，在看板该行点“随访链接”重新生成。不要修改链接中的字符。邮件中的登录链接过期属于账号问题，见账号问题。

录错了怎么改？

随访录错：看板该行点“随访记录”，在对应日期一行点“核对 / 更正”，修改后填写原因保存。基线录错：在同一窗口点“核对 / 更正基线”。数据质控问题列表中的记录可直接点“核对原记录”。每次修改都保留修改前后的值、修改人、时间和原因。研究编号本身不能在更正窗口修改，编号错误请交负责人核查。

能删除记录吗？

用药、基因和终点事件记录可由负责人或录入协作人在“附加数据”中删除，删除会留痕。基线、随访和化验记录在工作台中不提供删除按钮，录错请用更正功能并填写原因。确需删除某位研究对象的全部数据（例如撤回同意并要求删除）时，先把知情同意改为“撤回”，再由项目负责人联系 china@kidneysphere.com，经核实后处理；已冻结的版本和已下载的副本需按数据处理协议另行处置。注销账户也需通过邮件申请。

试用或订阅到期后，数据保留多久？

到期后数据不会被自动删除：项目转为只读，有权限的成员仍可查看，负责人和分析协作人仍可冻结与导出。数据的具体保留期限按用户协议、隐私政策以及与机构签订的数据处理协议执行。如需删除，请按上一条提出申请。

出错时怎么办

联系支持时请写明页面、操作步骤、时间和错误提示，先遮盖研究数据、完整随访链接、密码和密钥，不要把真实 CSV 作为普通附件发送。联系邮箱：china@kidneysphere.com。