fix:sample/plate 之前的开发

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

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