brapi-java/docs/dev/01-core/08-list.md

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。