brapi-java/docs/dev/01-core/02-person.md

01 Core - person 表录入说明

来源：docs/requirements/01-core-data-entry-requirements.md

录入目标

person 记录项目负责人、trial 联系人、study 联系人和 list owner。它支撑责任追踪、联系人展示、权限和通知。

前置依赖和下游引用

类型	内容
表	person
前置依赖	无
下游引用	program.lead_person_id、trial_contact、study_contact、list.list_owner_person_id

页面入口

页面	录入要求
Person 列表页	支持姓名、邮箱、机构筛选；新增、编辑、查看详情、停用
Person 新增/编辑页	使用联系人表单维护人员信息
Person 详情页	展示负责的 program、参与的 trial/study、拥有的 list

列表页表格字段：姓名、邮箱、电话、机构、负责项目数、参与 study 数。

字段录入

字段	类型	控件	录入说明	校验/来源
id	varchar(255)	隐藏/只读	人员主键	必填、唯一
auth_user_id	varchar(255)	隐藏	数据所属用户	登录上下文自动写入
description	varchar(255)	多行文本	人员说明、职责补充	可选
email_address	varchar(255)	邮箱输入框	邮箱地址	邮箱格式校验，建议唯一
first_name	varchar(255)	文本框	名	与 last_name 至少填写一个
institute_name	varchar(255)	文本框/选择器	所属机构	可选
last_name	varchar(255)	文本框	姓	与 first_name 至少填写一个
mailing_address	varchar(255)	多行文本	通讯地址	可选
middle_name	varchar(255)	文本框	中间名	可选
phone_number	varchar(255)	电话输入框	联系电话	可选，格式提示
userid	varchar(255)	文本框	外部用户 ID 或登录名	可选，建议唯一

校验规则

1. 姓名必填，first_name 与 last_name 至少填写一个。
2. email_address 需要校验邮箱格式。
3. 同一邮箱不建议重复录入。
4. 作为负责人或联系人被引用时，不允许物理删除。

接口能力

接口	用途
GET /persons	person 分页查询
POST /persons	新增 person
GET /persons/{id}	person 详情
PUT /persons/{id}	编辑 person
DELETE /persons/{id}	删除或停用 person，需做引用检查
GET /selectors/persons	person 搜索下拉，参数 keyword、instituteName

导入导出

1. 支持通过 Core 导入流程导入 person。
2. 模板列名使用数据库字段名。
3. 可按 id 幂等更新；无 id 时新增。
4. 列表页支持导出当前筛选结果，导出文件应包含 ID 和展示名称。

删除/停用

当 person 已作为 program 负责人、trial 联系人、study 联系人或 list owner 时，不允许物理删除。后端需要返回引用对象类型和数量，前端展示后引导用户停用。

验收点

1. Person 列表页支持分页、关键词搜索和机构筛选。
2. 邮箱格式错误时不能提交。
3. 作为负责人或联系人被引用的 person 删除失败时，前端展示引用详情。