ykt_server_hnswdx/doc/ecs-term-requirements.md

ECS 设备信息管理 — 需求规格说明书

1. 基础信息

属性	值
功能中文名	设备信息
功能简写	term
所属模块	ruoyi-modules/ruoyi-ecs
主表名	t_ecs_term
从表名	无
是否多租户	是
数据库类型	kingbase
描述	管理电子班牌设备信息，包括设备名称、编码、类型、网络配置、管理账号及所属教室，支持增删改查和导入导出

---

2. 接口清单

2.1 主表接口

接口	HTTP	路径（后端）	前端路径	权限字符
列表	GET	/term/list	/ecs/term/list	ecs:term:list
详情	GET	/term/{termId}	/ecs/term/{termId}	ecs:term:query
新增	POST	/term/	/ecs/term/	ecs:term:add
编辑	PUT	/term/	/ecs/term/	ecs:term:edit
删除	DELETE	/term/{termIds}	/ecs/term/{termIds}	ecs:term:remove
导出模板	POST	/term/exportTemplate	/ecs/term/exportTemplate	ecs:term:export
导入数据	POST	/term/importData	/ecs/term/importData	ecs:term:import
导出数据	POST	/term/export	/ecs/term/export	ecs:term:export

---

3. 字段属性速查表

属性	含义	可选值	说明
fieldName	字段名（驼峰）	—	代码变量名
columnName	列名（下划线）	—	数据库列名
fieldType	Java类型	String/Long/Integer/BigDecimal/Date
inDb	是否在表中存在	true/false	false=纯前端计算字段
inTable	列表是否显示	true/false	生成表格列
inQuery	是否查询字段	true/false	生成搜索条件
queryType	查询方式	eq/like/between	精确/模糊/范围
inForm	是否表单字段	true/false	生成表单项
inAdd	新增表单显示	true/false
inEdit	编辑表单显示	true/false
required	是否必填	true/false	生成校验注解
dictType	字典类型	字典标识	有值=字典下拉，否则普通输入
relation	关联选择配置	对象	有值=弹出选择框
component	前端组件类型	input/select/inputNumber/datetime/textarea	默认根据类型推断
width	表格列宽	数字(px)	默认auto
sort	排序	数字	越小越靠前
excelExport	Excel导出	true/false	默认true
lockRule	操作锁定规则	对象	有值=按此字段值控制行级操作权限

---

4. 字段清单

4.1 主表 t_ecs_term

fields:
  # ---------- 主键 ----------
  - fieldName: termId
    columnName: term_id
    fieldType: Long
    inDb: true
    inTable: false
    inForm: false
    remark: 设备Id

  # ---------- 业务字段 ----------
  - fieldName: termName
    columnName: term_name
    fieldType: String
    inDb: true
    inTable: true
    inQuery: true
    queryType: like
    inForm: true
    inAdd: true
    inEdit: true
    required: true
    component: input
    width: 150
    sort: 1
    excelExport: true
    remark: 设备名称

  - fieldName: termNumb
    columnName: term_numb
    fieldType: String
    inDb: true
    inTable: true
    inQuery: true
    queryType: like
    inForm: true
    inAdd: true
    inEdit: true
    required: true
    component: input
    width: 150
    sort: 2
    excelExport: true
    remark: 设备编码

  - fieldName: termType
    columnName: term_type
    fieldType: Integer
    inDb: true
    inTable: true
    inQuery: true
    queryType: eq
    inForm: true
    inAdd: true
    inEdit: true
    required: true
    dictType: term_type
    component: select
    width: 100
    sort: 3
    excelExport: true
    remark: 设备类型

  - fieldName: termIP
    columnName: term_ip
    fieldType: String
    inDb: true
    inTable: true
    inQuery: false
    inForm: true
    inAdd: true
    inEdit: true
    required: false
    component: input
    width: 140
    sort: 4
    excelExport: true
    remark: 设备IP

  - fieldName: termMac
    columnName: term_mac
    fieldType: String
    inDb: true
    inTable: true
    inQuery: false
    inForm: true
    inAdd: true
    inEdit: true
    required: false
    component: input
    width: 150
    sort: 5
    excelExport: true
    remark: MAC地址

  - fieldName: termPort
    columnName: term_port
    fieldType: Integer
    inDb: true
    inTable: false
    inQuery: false
    inForm: true
    inAdd: true
    inEdit: true
    required: false
    component: inputNumber
    sort: 6
    excelExport: true
    remark: 设备端口

  - fieldName: termBrand
    columnName: term_brand
    fieldType: Integer
    inDb: true
    inTable: false
    inQuery: false
    inForm: true
    inAdd: true
    inEdit: true
    required: false
    dictType: term_brand
    component: select
    sort: 7
    excelExport: true
    remark: 设备品牌

  - fieldName: adminName
    columnName: admin_name
    fieldType: String
    inDb: true
    inTable: false
    inQuery: false
    inForm: true
    inAdd: true
    inEdit: true
    required: false
    component: input
    sort: 8
    excelExport: true
    remark: 管理账号

  - fieldName: adminPwd
    columnName: admin_pwd
    fieldType: String
    inDb: true
    inTable: false
    inQuery: false
    inForm: true
    inAdd: true
    inEdit: true
    required: false
    component: input
    excelExport: false
    sort: 9
    remark: 管理密码

  - fieldName: serverIp
    columnName: server_ip
    fieldType: String
    inDb: true
    inTable: true
    inQuery: false
    inForm: true
    inAdd: true
    inEdit: true
    required: false
    component: input
    width: 140
    sort: 10
    excelExport: true
    remark: 服务器IP

  - fieldName: serverPort
    columnName: server_port
    fieldType: Integer
    inDb: true
    inTable: true
    inQuery: false
    inForm: true
    inAdd: true
    inEdit: true
    required: false
    component: inputNumber
    width: 100
    sort: 11
    excelExport: true
    remark: 服务器端口

  # ---------- 教室关联（冗余存储名称） ----------
  - fieldName: roomId
    columnName: room_id
    fieldType: Long
    inDb: true
    inTable: false
    inQuery: false
    inForm: true
    inAdd: true
    inEdit: true
    required: false
    relation:
      table: t_pt_room
      idField: ptRoomId
      nameField: roomName
      title: 选择教室
      path: /backstage/room/selectRoom
    component: roomSelect
    sort: 12
    remark: 教室Id（关联教室表）

  - fieldName: roomName
    columnName: room_name
    fieldType: String
    inDb: true
    inTable: true
    inQuery: true
    queryType: like
    inForm: false
    inAdd: false
    inEdit: false
    width: 150
    sort: 13
    excelExport: true
    remark: 教室名称（冗余存储，选择教室时自动回填）

  # ---------- 公共字段 ----------
  # 通用字段定义（无需在字段清单中重复写，建表时自动追加）：
  # | 字段          | Java类型        | 说明               |
  # | ------------- | --------------- | ------------------ |
  # | del_flag      | Integer         | 逻辑删除：0-未删除，1-已删除 |
  # | create_dept   | Long            | 创建部门             |
  # | create_by     | Long            | 创建者              |
  # | create_time   | Date            | 创建时间             |
  # | update_by     | Long            | 最后修改者            |
  # | update_time   | Date            | 最后修改时间           |
  # | tenant_id     | Long            | 租户ID（多租户表包含）      |

  - fieldName: createTime
    columnName: create_time
    fieldType: Date
    inDb: true
    inTable: true
    inQuery: false
    inForm: false
    component: datetime
    width: 180
    sort: 99
    excelExport: true

---

5. VO 结构

5.1 主表列表 VO

EcsTermVo:
  - termId
  - termName
  - termNumb
  - termType
  - termIP
  - termMac
  - serverIp
  - serverPort
  - roomId
  - roomName
  - createTime

---

6. 特殊需求

special:
  excelImport: true
  excelExport: true

  importRules:
    - fieldName: termName
      required: true
    - fieldName: termNumb
      required: true
      unique: true
    - fieldName: termType
      required: true

  dubboExpose: false

---

7. 字典项

字典类型	枚举值	说明
term_type	0=电子班牌, 1=考勤机, 2=门禁机	设备类型
term_brand	0=希沃, 1=鸿合, 2=其他	设备品牌

注意：字典值仅为示例，实际值由业务方确定。

---

8. 建表语句

8.1 主表 t_ecs_term

-- 人大金仓（KingbaseES）
CREATE TABLE "dbo"."t_ecs_term" (
  "term_id" bigint NOT NULL,
  "term_name" character varying(255 char) NOT NULL DEFAULT ''::varchar,
  "term_numb" character varying(255 char) NOT NULL DEFAULT ''::varchar,
  "term_type"  character varying(16 char) NOT NULL DEFAULT '0'::varchar,
  "term_ip" character varying(255 char) DEFAULT ''::varchar,
  "term_mac" character varying(255 char) DEFAULT ''::varchar,
  "term_port" integer,
  "term_brand"  character varying(16 char) NOT NULL DEFAULT 'dt'::varchar,
  "admin_name" character varying(255 char) DEFAULT ''::varchar,
  "admin_pwd" character varying(255 char) DEFAULT ''::varchar,
  "server_ip" character varying(255 char) DEFAULT ''::varchar,
  "server_port" integer,
  "room_id" bigint,
  "room_name" character varying(255 char) DEFAULT ''::varchar,
  "tenant_id" character varying(20 char) NOT NULL DEFAULT ''::varchar,
  "del_flag" character(1 char) NOT NULL DEFAULT '0'::bpchar,
  "create_dept" bigint,
  "create_by" bigint,
  "create_time" datetime,
  "update_by" bigint,
  "update_time" datetime,
  CONSTRAINT "t_ecs_term_pkey" PRIMARY KEY ("term_id")
);

-- 表注释
ALTER TABLE "dbo"."t_ecs_term" COMMENT '设备信息表';

-- 列注释
ALTER TABLE "dbo"."t_ecs_term" MODIFY "term_id" COMMENT '设备Id';
ALTER TABLE "dbo"."t_ecs_term" MODIFY "term_name" COMMENT '设备名称';
ALTER TABLE "dbo"."t_ecs_term" MODIFY "term_numb" COMMENT '设备编码';
ALTER TABLE "dbo"."t_ecs_term" MODIFY "term_type" COMMENT '设备类型：0-电子班牌，1-考勤机，2-门禁机';
ALTER TABLE "dbo"."t_ecs_term" MODIFY "term_ip" COMMENT '设备IP';
ALTER TABLE "dbo"."t_ecs_term" MODIFY "term_mac" COMMENT 'MAC地址';
ALTER TABLE "dbo"."t_ecs_term" MODIFY "term_port" COMMENT '设备端口';
ALTER TABLE "dbo"."t_ecs_term" MODIFY "term_brand" COMMENT '设备品牌';
ALTER TABLE "dbo"."t_ecs_term" MODIFY "admin_name" COMMENT '管理账号';
ALTER TABLE "dbo"."t_ecs_term" MODIFY "admin_pwd" COMMENT '管理密码';
ALTER TABLE "dbo"."t_ecs_term" MODIFY "server_ip" COMMENT '服务器IP';
ALTER TABLE "dbo"."t_ecs_term" MODIFY "server_port" COMMENT '服务器端口';
ALTER TABLE "dbo"."t_ecs_term" MODIFY "room_id" COMMENT '教室Id';
ALTER TABLE "dbo"."t_ecs_term" MODIFY "room_name" COMMENT '教室名称';
ALTER TABLE "dbo"."t_ecs_term" MODIFY "tenant_id" COMMENT '租户编号';
ALTER TABLE "dbo"."t_ecs_term" MODIFY "del_flag" COMMENT '删除标志（0-未删除 1-已删除）';
ALTER TABLE "dbo"."t_ecs_term" MODIFY "create_dept" COMMENT '创建部门';
ALTER TABLE "dbo"."t_ecs_term" MODIFY "create_by" COMMENT '创建者';
ALTER TABLE "dbo"."t_ecs_term" MODIFY "create_time" COMMENT '创建时间';
ALTER TABLE "dbo"."t_ecs_term" MODIFY "update_by" COMMENT '更新者';
ALTER TABLE "dbo"."t_ecs_term" MODIFY "update_time" COMMENT '更新时间';

---

9. 备注

1. 冗余存储教室名称：roomName 冗余存储教室名称，选择教室时自动回填，支持按教室名称模糊查询，避免关联查询性能问题。当教室信息变更时需考虑是否同步更新历史记录。
2. 管理密码：adminPwd 采用普通文本存储，不在列表中显示，不参与 Excel 导出，仅在表单中可编辑。
3. 设备编码唯一性：termNumb 在导入时做唯一性校验，确保设备编码不重复。
4. 教室关联选择：roomId 通过关联选择器从 t_pt_room 表选择，选择后自动回填 roomName。
5. 关联实体说明：
   • 教室 → 关联 t_pt_room 表（通过 backstage 模块的 RemotePtRoomService）