# 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 删除失败时，前端展示引用详情。