# 01 Core - list 表录入说明

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

## 录入目标

`list` 是通用分组列表的主表，用于维护一组业务对象或文本项。`list` 负责列表基本信息，`list_item` 负责列表明细。

## 前置依赖和下游引用

| 类型 | 内容 |
| --- | --- |
| 表 | `list` |
| 前置依赖 | 可选 `person` |
| 下游引用 | `list_item`、业务查询和分组 |

## 页面入口

| 页面 | 录入要求 |
| --- | --- |
| List 列表页 | 展示 list，支持查询、新增、编辑 |
| List 详情页 | 顶部展示 list 基本信息，下方内嵌 list_item 表格 |

List 详情页支持新增 item、批量导入 item、删除 item、排序。同一 list 内 item 不重复。

## 字段录入

| 字段 | 类型 | 控件 | 录入说明 | 校验/来源 |
| --- | --- | --- | --- | --- |
| `id` | varchar(255) | 隐藏/只读 | 列表主键 | 必填、唯一 |
| `auth_user_id` | varchar(255) | 隐藏 | 数据所属用户 | 登录上下文自动写入 |
| `date_created` | timestamp | 只读日期时间 | 创建时间 | 系统自动写入 |
| `date_modified` | timestamp | 只读日期时间 | 修改时间 | 系统自动更新 |
| `description` | varchar(255) | 多行文本 | 列表描述 | 可选 |
| `list_name` | varchar(255) | 文本框 | 列表名称 | 必填 |
| `list_owner_name` | varchar(255) | 文本框 | 列表 owner 名称 | 可选，可由 owner person 带出 |
| `list_source` | varchar(255) | 文本框 | 列表来源 | 可选 |
| `list_type` | integer | 下拉框 | 列表类型 | 必填，按 BrAPI 枚举 |
| `list_owner_person_id` | varchar(255) | 人员选择器 | 列表 owner | 可选，来源 `person.id` |

## 校验规则

1. `list_name` 必填。
2. `list_type` 必填，按 BrAPI 枚举选择。
3. 如果绑定 owner，`list_owner_person_id` 必须引用已存在的 `person.id`。
4. `date_created`、`date_modified` 由系统维护，前端只读。

## 接口能力

| 接口 | 用途 |
| --- | --- |
| `GET /lists` | list 查询 |
| `POST /lists` | 新增 list |
| `PUT /lists/{id}` | 编辑 list |
| `POST /lists/{id}/items` | 给 list 添加 item |
| `DELETE /lists/{id}/items/{itemId}` | 删除 list item |

## 导入导出

1. 支持通过 Core 导入流程导入 `list`。
2. 模板列名使用数据库字段名。
3. 外键列支持填写 `list_owner_person_id`；可额外支持名称匹配，但名称重复时必须报错。
4. 列表页支持导出当前筛选结果，导出文件应包含 ID 和展示名称。

## 删除/停用

当 `list` 已有 `list_item` 时，删除前必须提示。可以先清空明细再删除 list。

## 验收点

1. List 详情页顶部展示 list 基本信息，下方展示 list_item 表格。
2. 同一 list 内 item 不重复。
3. 绑定 owner 时只能保存已存在的 person ID。