CodeSpirit CRUD开发完整指南

概述

本文档通过职工管理（Employee）的实际代码示例，展示如何使用CodeSpirit框架快速开发CRUD功能。该示例来自身份认证系统（IdentityApi），是一个标准的关联型CRUD模块，包含完整的验证逻辑、业务处理和关联关系管理。
最后更新: 2025年12月22日
框架版本: v2.0.0
示例来源: CodeSpirit.IdentityApi - 职工管理模块

开发流程概览

graph LR    A["1. 创建实体模型"] --> B["2. 创建DTO类"]    B --> C["3. 配置AutoMapper"]    C --> D["4. 创建服务层"]    D --> E["5. 创建控制器"]    E --> F["6. 配置数据库"]    F --> G["7. 创建迁移"]    G --> H["完成"]示例模块说明

职工管理（Employee）是一个典型的关联型CRUD模块，具有以下特点：

• ✅ 关联关系管理（部门、用户账号）
  
• ✅ 完整的CRUD操作
  
• ✅ 业务验证（工号唯一性、部门存在性、身份证格式等）
  
• ✅ 多条件查询（关键字、部门、状态、日期范围等）
  
• ✅ 表单分组展示（基本信息、联系方式、工作信息等）
  
• ✅ 多租户支持
  
• ✅ 审计字段自动记录
  
• ✅ 软删除支持
  

1. 创建实体模型

在Data/Models目录下创建实体类：

1. // Data/Models/Employee.cs
2. using CodeSpirit.Shared.Entities.Interfaces;
3. using CodeSpirit.MultiTenant.Abstractions;
4. using System.ComponentModel.DataAnnotations;
6. namespace CodeSpirit.IdentityApi.Data.Models;
8. /// <summary>
9. /// 职工信息
10. /// </summary>
11. public class Employee : IFullAuditable, IMultiTenant, IIsActive
12. {
13.     /// <summary>
14.     /// 职工ID
15.     /// </summary>
16.     public long Id { get; set; }
18.     /// <summary>
19.     /// 租户ID（多租户支持）
20.     /// </summary>
21.     [Required]
22.     [MaxLength(50)]
23.     public string TenantId { get; set; } = string.Empty;
25.     /// <summary>
26.     /// 工号（租户内唯一）
27.     /// </summary>
28.     [Required]
29.     [MaxLength(50)]
30.     public string EmployeeNo { get; set; } = string.Empty;
32.     /// <summary>
33.     /// 姓名
34.     /// </summary>
35.     [Required]
36.     [MaxLength(100)]
37.     public string Name { get; set; } = string.Empty;
39.     /// <summary>
40.     /// 性别
41.     /// </summary>
42.     public Gender Gender { get; set; }
44.     /// <summary>
45.     /// 身份证号码
46.     /// </summary>
47.     [MaxLength(18)]
48.     public string? IdNo { get; set; }
50.     /// <summary>
51.     /// 出生日期
52.     /// </summary>
53.     public DateTime? BirthDate { get; set; }
55.     /// <summary>
56.     /// 手机号码
57.     /// </summary>
58.     [MaxLength(15)]
59.     public string? PhoneNumber { get; set; }
61.     /// <summary>
62.     /// 电子邮箱
63.     /// </summary>
64.     [MaxLength(100)]
65.     [EmailAddress]
66.     public string? Email { get; set; }
68.     /// <summary>
69.     /// 部门ID
70.     /// </summary>
71.     public long? DepartmentId { get; set; }
73.     /// <summary>
74.     /// 所属部门（导航属性）
75.     /// </summary>
76.     public Department? Department { get; set; }
78.     /// <summary>
79.     /// 职位
80.     /// </summary>
81.     [MaxLength(100)]
82.     public string? Position { get; set; }
84.     /// <summary>
85.     /// 职级
86.     /// </summary>
87.     [MaxLength(50)]
88.     public string? JobLevel { get; set; }
90.     /// <summary>
91.     /// 入职日期
92.     /// </summary>
93.     public DateTime? HireDate { get; set; }
95.     /// <summary>
96.     /// 离职日期
97.     /// </summary>
98.     public DateTime? TerminationDate { get; set; }
100.     /// <summary>
101.     /// 在职状态
102.     /// </summary>
103.     public EmploymentStatus EmploymentStatus { get; set; }
105.     /// <summary>
106.     /// 关联的用户ID
107.     /// </summary>
108.     public long? UserId { get; set; }
110.     /// <summary>
111.     /// 关联的用户账号（导航属性）
112.     /// </summary>
113.     public ApplicationUser? User { get; set; }
115.     /// <summary>
116.     /// 紧急联系人
117.     /// </summary>
118.     [MaxLength(100)]
119.     public string? EmergencyContact { get; set; }
121.     /// <summary>
122.     /// 紧急联系电话
123.     /// </summary>
124.     [MaxLength(15)]
125.     public string? EmergencyPhone { get; set; }
127.     /// <summary>
128.     /// 地址
129.     /// </summary>
130.     [MaxLength(500)]
131.     public string? Address { get; set; }
133.     /// <summary>
134.     /// 备注
135.     /// </summary>
136.     [MaxLength(1000)]
137.     public string? Remarks { get; set; }
139.     /// <summary>
140.     /// 是否激活
141.     /// </summary>
142.     public bool IsActive { get; set; } = true;
144.     /// <summary>
145.     /// 头像地址
146.     /// </summary>
147.     [MaxLength(255)]
148.     [DataType(DataType.ImageUrl)]
149.     public string? AvatarUrl { get; set; }
151.     // 审计字段（实现IFullAuditable接口）
152.     public long CreatedBy { get; set; }
153.     public DateTime CreatedAt { get; set; }
154.     public long? UpdatedBy { get; set; }
155.     public DateTime? UpdatedAt { get; set; }
156.     public long? DeletedBy { get; set; }
157.     public DateTime? DeletedAt { get; set; }
158.     public bool IsDeleted { get; set; }
159. }

复制代码

说明：

• 实现IFullAuditable接口，自动包含完整的审计字段（创建、更新、删除）
  
• 实现IMultiTenant接口，支持多租户数据隔离
  
• 实现IIsActive接口，支持激活状态管理
  
• 使用long作为主键类型
  
• 包含关联关系的导航属性（部门、用户账号）
  
• 支持软删除（IsDeleted字段）
  

2. 创建DTO类

在Dtos/Employee目录下创建DTO类：
2.1 EmployeeDto（展示DTO）

1. // Dtos/Employee/EmployeeDto.cs
2. using CodeSpirit.Amis.Attributes.Columns;
3. using CodeSpirit.Core.Attributes;
4. using CodeSpirit.IdentityApi.Data.Models;
5. using System.ComponentModel;
7. namespace CodeSpirit.IdentityApi.Dtos.Employee;
9. /// <summary>
10. /// 职工数据传输对象
11. /// </summary>
12. public class EmployeeDto
13. {
14.     /// <summary>
15.     /// 职工ID
16.     /// </summary>
17.     public long Id { get; set; }
19.     /// <summary>
20.     /// 工号
21.     /// </summary>
22.     [DisplayName("工号")]
23.     public string EmployeeNo { get; set; } = string.Empty;
25.     /// <summary>
26.     /// 姓名
27.     /// </summary>
28.     [DisplayName("姓名")]
29.     [TplColumn(template: "${name}")]
30.     public string Name { get; set; } = string.Empty;
32.     /// <summary>
33.     /// 头像地址
34.     /// </summary>
35.     [DisplayName("头像")]
36.     [AvatarColumn(Text = "${name}", Src = "${avatarUrl}")]
37.     [Badge(Animation = true, VisibleOn = "isActive", Level = "info")]
38.     public string? AvatarUrl { get; set; }
40.     /// <summary>
41.     /// 性别
42.     /// </summary>
43.     [DisplayName("性别")]
44.     public Gender Gender { get; set; }
46.     /// <summary>
47.     /// 手机号码
48.     /// </summary>
49.     [DisplayName("手机号码")]
50.     public string? PhoneNumber { get; set; }
52.     /// <summary>
53.     /// 电子邮箱
54.     /// </summary>
55.     [DisplayName("电子邮箱")]
56.     public string? Email { get; set; }
58.     /// <summary>
59.     /// 部门ID
60.     /// </summary>
61.     [AmisColumn(Hidden = true)]
62.     public long? DepartmentId { get; set; }
64.     /// <summary>
65.     /// 部门名称
66.     /// </summary>
67.     [DisplayName("部门")]
68.     public string? DepartmentName { get; set; }
70.     /// <summary>
71.     /// 职位
72.     /// </summary>
73.     [DisplayName("职位")]
74.     public string? Position { get; set; }
76.     /// <summary>
77.     /// 职级
78.     /// </summary>
79.     [DisplayName("职级")]
80.     public string? JobLevel { get; set; }
82.     /// <summary>
83.     /// 入职日期
84.     /// </summary>
85.     [DisplayName("入职日期")]
86.     [DateColumn(Format = "YYYY-MM-DD")]
87.     public DateTime? HireDate { get; set; }
89.     /// <summary>
90.     /// 在职状态
91.     /// </summary>
92.     [DisplayName("在职状态")]
93.     public EmploymentStatus EmploymentStatus { get; set; }
95.     /// <summary>
96.     /// 是否激活
97.     /// </summary>
98.     [DisplayName("是否激活")]
99.     public bool IsActive { get; set; }
101.     /// <summary>
102.     /// 创建时间
103.     /// </summary>
104.     [DisplayName("创建时间")]
105.     [DateColumn(FromNow = true)]
106.     public DateTime CreatedAt { get; set; }
108.     /// <summary>
109.     /// 更新时间
110.     /// </summary>
111.     [DisplayName("更新时间")]
112.     [DateColumn(FromNow = true)]
113.     public DateTime? UpdatedAt { get; set; }
114. }

复制代码

说明：
列特性（Columns）：用于控制前端表格列的显示和格式

• AmisColumn：基础列特性，控制列的显示、排序、隐藏等
  
  
  
  • Hidden：是否隐藏列
    
  • Sortable：是否支持排序
    
  • Copyable：是否可复制
    
  • Fixed：是否固定列（left/right/none）
    
  • StatusMapping：状态映射（支持预定义映射如Boolean、HttpStatusCode等）
    
  
  
• TplColumn：自定义列显示模板，使用模板语法自定义列内容
  
  
  
  • template：模板字符串，支持变量插值（如${name}）
    
  
  
• AvatarColumn：头像列，显示头像图片
  
  
  
  • Text：头像下方显示的文本
    
  • Src：头像图片地址
    
  
  
• DateColumn：日期列，格式化日期显示
  
  
  
  • Format：日期格式（如YYYY-MM-DD、YYYY-MM-DD HH:mm）
    
  • FromNow：是否显示相对时间（如"2小时前"）
    
  
  
• IgnoreColumn：忽略列，该字段不在表格中显示
  
• TagsColumn：标签列，以标签形式显示数组数据
  
• LinkColumn：链接列，显示可点击的链接
  
• AmisStatusColumn：状态列，显示状态标签和图标
  
• LongTextColumn：长文本列，支持展开/收起
  
• ListColumn：列表列，显示列表数据
  
• IconColumn：图标列，显示图标
  

2.2 CreateEmployeeDto（创建DTO）

1. // Dtos/Employee/CreateEmployeeDto.cs
2. using CodeSpirit.Amis.Attributes.FormFields;
3. using CodeSpirit.IdentityApi.Data.Models;
4. using System.ComponentModel;
5. using System.ComponentModel.DataAnnotations;
7. namespace CodeSpirit.IdentityApi.Dtos.Employee;
9. /// <summary>
10. /// 创建职工数据传输对象
11. /// </summary>
12. [FormGroup("basic", "基本信息", "EmployeeNo,Name,Gender,IdNo,BirthDate", Order = 1)]
13. [FormGroup("contact", "联系方式", "PhoneNumber,Email,Address", Order = 2)]
14. [FormGroup("work", "工作信息", "DepartmentId,Position,JobLevel,HireDate,EmploymentStatus", Order = 3)]
15. [FormGroup("relation", "关联信息", "UserId", Order = 4)]
16. [FormGroup("emergency", "紧急联系人", "EmergencyContact,EmergencyPhone", Order = 5)]
17. [FormGroup("other", "其他信息", "AvatarUrl,Remarks,IsActive", Order = 6)]
18. public class CreateEmployeeDto
19. {
20.     /// <summary>
21.     /// 工号
22.     /// </summary>
23.     [Required(ErrorMessage = "工号不能为空")]
24.     [MaxLength(50, ErrorMessage = "工号长度不能超过50个字符")]
25.     [DisplayName("工号")]
26.     [AmisInputTextField(ColumnRatio = 6)]
27.     public string EmployeeNo { get; set; } = string.Empty;
29.     /// <summary>
30.     /// 姓名
31.     /// </summary>
32.     [Required(ErrorMessage = "姓名不能为空")]
33.     [MaxLength(100, ErrorMessage = "姓名长度不能超过100个字符")]
34.     [DisplayName("姓名")]
35.     [AmisInputTextField(ColumnRatio = 6)]
36.     public string Name { get; set; } = string.Empty;
38.     /// <summary>
39.     /// 性别
40.     /// </summary>
41.     [DisplayName("性别")]
42.     [AmisFormField(ColumnRatio = 6)]
43.     public Gender Gender { get; set; }
45.     /// <summary>
46.     /// 身份证号码
47.     /// </summary>
48.     [MaxLength(18, ErrorMessage = "身份证号码长度不能超过18个字符")]
49.     [DisplayName("身份证号")]
50.     [AmisInputTextField(ColumnRatio = 6)]
51.     public string? IdNo { get; set; }
53.     /// <summary>
54.     /// 出生日期
55.     /// </summary>
56.     [DisplayName("出生日期")]
57.     [AmisDateFieldAttribute(ColumnRatio = 6)]
58.     public DateTime? BirthDate { get; set; }
60.     /// <summary>
61.     /// 手机号码
62.     /// </summary>
63.     [MaxLength(15, ErrorMessage = "手机号码长度不能超过15个字符")]
64.     [Phone(ErrorMessage = "手机号码格式不正确")]
65.     [DisplayName("手机号码")]
66.     [AmisInputTextField(ColumnRatio = 6)]
67.     public string? PhoneNumber { get; set; }
69.     /// <summary>
70.     /// 电子邮箱
71.     /// </summary>
72.     [MaxLength(100, ErrorMessage = "电子邮箱长度不能超过100个字符")]
73.     [EmailAddress(ErrorMessage = "电子邮箱格式不正确")]
74.     [DisplayName("电子邮箱")]
75.     [AmisInputTextField(ColumnRatio = 6)]
76.     public string? Email { get; set; }
78.     /// <summary>
79.     /// 部门ID
80.     /// </summary>
81.     [DisplayName("部门")]
82.     [AmisInputTreeField(
83.         DataSource = "${ROOT_API}/api/identity/Departments/tree",
84.         LabelField = "name",
85.         ValueField = "id",
86.         Multiple = false,
87.         Searchable = true,
88.         ColumnRatio = 12
89.     )]
90.     public long? DepartmentId { get; set; }
92.     /// <summary>
93.     /// 职位
94.     /// </summary>
95.     [MaxLength(100, ErrorMessage = "职位长度不能超过100个字符")]
96.     [DisplayName("职位")]
97.     [AmisInputTextField(ColumnRatio = 6)]
98.     public string? Position { get; set; }
100.     /// <summary>
101.     /// 职级
102.     /// </summary>
103.     [MaxLength(50, ErrorMessage = "职级长度不能超过50个字符")]
104.     [DisplayName("职级")]
105.     [AmisInputTextField(ColumnRatio = 6)]
106.     public string? JobLevel { get; set; }
108.     /// <summary>
109.     /// 入职日期
110.     /// </summary>
111.     [DisplayName("入职日期")]
112.     [AmisDateFieldAttribute(ColumnRatio = 6)]
113.     public DateTime? HireDate { get; set; }
115.     /// <summary>
116.     /// 在职状态
117.     /// </summary>
118.     [DisplayName("在职状态")]
119.     [AmisFormField(ColumnRatio = 6)]
120.     public EmploymentStatus EmploymentStatus { get; set; } = EmploymentStatus.Active;
122.     /// <summary>
123.     /// 关联的用户ID
124.     /// </summary>
125.     [DisplayName("关联用户")]
126.     [AmisSelectField(
127.         Source = "${ROOT_API}/api/identity/Users",
128.         ValueField = "id",
129.         LabelField = "name",
130.         Multiple = false,
131.         Searchable = true,
132.         ColumnRatio = 12
133.     )]
134.     public long? UserId { get; set; }
136.     /// <summary>
137.     /// 紧急联系人
138.     /// </summary>
139.     [MaxLength(100, ErrorMessage = "紧急联系人长度不能超过100个字符")]
140.     [DisplayName("紧急联系人")]
141.     [AmisInputTextField(ColumnRatio = 6)]
142.     public string? EmergencyContact { get; set; }
144.     /// <summary>
145.     /// 紧急联系电话
146.     /// </summary>
147.     [MaxLength(15, ErrorMessage = "紧急联系电话长度不能超过15个字符")]
148.     [Phone(ErrorMessage = "紧急联系电话格式不正确")]
149.     [DisplayName("紧急联系电话")]
150.     [AmisInputTextField(ColumnRatio = 6)]
151.     public string? EmergencyPhone { get; set; }
153.     /// <summary>
154.     /// 地址
155.     /// </summary>
156.     [MaxLength(500, ErrorMessage = "地址长度不能超过500个字符")]
157.     [DisplayName("地址")]
158.     [AmisTextareaField(ColumnRatio = 12)]
159.     public string? Address { get; set; }
161.     /// <summary>
162.     /// 头像地址
163.     /// </summary>
164.     [MaxLength(255, ErrorMessage = "头像地址长度不能超过255个字符")]
165.     [DisplayName("头像")]
166.     [AmisInputImageField(
167.         Receiver = "/file/api/file/images/upload?BucketName=avatar",
168.         Accept = "image/png,image/jpeg,image/jpg",
169.         MaxSize = 2097152,
170.         Multiple = false,
171.         ColumnRatio = 12
172.     )]
173.     public string? AvatarUrl { get; set; }
175.     /// <summary>
176.     /// 备注
177.     /// </summary>
178.     [MaxLength(1000, ErrorMessage = "备注长度不能超过1000个字符")]
179.     [DisplayName("备注")]
180.     [AmisTextareaField(ColumnRatio = 12)]
181.     public string? Remarks { get; set; }
183.     /// <summary>
184.     /// 是否激活
185.     /// </summary>
186.     [DisplayName("是否激活")]
187.     [AmisFormField(ColumnRatio = 6)]
188.     public bool IsActive { get; set; } = true;
189. }

复制代码

说明：
表单特性（FormFields）：用于控制前端表单字段的显示和交互

• FormGroup：表单分组特性，将相关字段组织成组
  
  
  
  • Name：组名称
    
  • Title：组标题
    
  • Fields：包含的字段名称（逗号分隔）
    
  • Order：显示顺序（数值越小越靠前）
    
  • Mode：显示模式（Normal/Inline/Horizontal）
    
  
  
• AmisInputTextField：文本输入框
  
  
  
  • ColumnRatio：字段宽度比例（12为全宽，6为半宽）
    
  • EnableAddOn：是否启用右侧附加组件
    
  • AddOnLabel：附加组件标签
    
  • AddOnApi：附加组件API地址
    
  
  
• AmisInputTreeField：树形选择组件
  
  
  
  • DataSource：数据源URL
    
  • ValueField：值字段名
    
  • LabelField：标签字段名
    
  • Multiple：是否多选
    
  • Searchable：是否可搜索
    
  • ShowOutline：是否显示轮廓
    
  • SubmitOnChange：选择后是否自动提交
    
  
  
• AmisSelectField：下拉选择组件
  
  
  
  • Source：数据源URL
    
  • ValueField：值字段名
    
  • LabelField：标签字段名
    
  • Multiple：是否多选
    
  • Searchable：是否可搜索
    
  • Clearable：是否可清除
    
  
  
• AmisInputImageField：图片上传组件
  
  
  
  • Receiver：上传接口地址
    
  • Accept：接受的文件类型
    
  • MaxSize：最大文件大小（字节）
    
  • Multiple：是否支持多文件
    
  
  
• AmisDateFieldAttribute：日期选择组件
  
  
  
  • Format：日期格式
    
  • Placeholder：占位符
    
  • MinDate：最小日期
    
  • MaxDate：最大日期
    
  
  
• AmisTextareaField：多行文本输入框
  
  
  
  • MaxLength：最大长度
    
  • ShowCounter：是否显示字符计数
    
  • Rows：行数
    
  
  

通用属性：

• ColumnRatio：字段宽度比例（12为全宽，6为半宽，4为1/3宽）
  
• Required：是否必填
  
• Placeholder：占位符文本
  
• Disabled：是否禁用
  
• VisibleOn：显示条件表达式
  
• DisabledOn：禁用条件表达式
  

2.3 UpdateEmployeeDto（更新DTO）

1. // Dtos/Employee/UpdateEmployeeDto.cs
2. using CodeSpirit.Amis.Attributes.FormFields;
3. using CodeSpirit.IdentityApi.Data.Models;
4. using System.ComponentModel;
5. using System.ComponentModel.DataAnnotations;
7. namespace CodeSpirit.IdentityApi.Dtos.Employee;
9. /// <summary>
10. /// 更新职工数据传输对象
11. /// </summary>
12. [FormGroup("basic", "基本信息", "EmployeeNo,Name,Gender,IdNo,BirthDate", Order = 1)]
13. [FormGroup("contact", "联系方式", "PhoneNumber,Email,Address", Order = 2)]
14. [FormGroup("work", "工作信息", "DepartmentId,Position,JobLevel,HireDate,TerminationDate,EmploymentStatus", Order = 3)]
15. [FormGroup("relation", "关联信息", "UserId", Order = 4)]
16. [FormGroup("emergency", "紧急联系人", "EmergencyContact,EmergencyPhone", Order = 5)]
17. [FormGroup("other", "其他信息", "AvatarUrl,Remarks,IsActive", Order = 6)]
18. public class UpdateEmployeeDto
19. {
20.     /// <summary>
21.     /// 工号
22.     /// </summary>
23.     [Required(ErrorMessage = "工号不能为空")]
24.     [MaxLength(50, ErrorMessage = "工号长度不能超过50个字符")]
25.     [DisplayName("工号")]
26.     [AmisInputTextField(ColumnRatio = 6)]
27.     public string EmployeeNo { get; set; } = string.Empty;
29.     /// <summary>
30.     /// 姓名
31.     /// </summary>
32.     [Required(ErrorMessage = "姓名不能为空")]
33.     [MaxLength(100, ErrorMessage = "姓名长度不能超过100个字符")]
34.     [DisplayName("姓名")]
35.     [AmisInputTextField(ColumnRatio = 6)]
36.     public string Name { get; set; } = string.Empty;
38.     /// <summary>
39.     /// 性别
40.     /// </summary>
41.     [DisplayName("性别")]
42.     [AmisFormField(ColumnRatio = 6)]
43.     public Gender Gender { get; set; }
45.     /// <summary>
46.     /// 身份证号码
47.     /// </summary>
48.     [MaxLength(18, ErrorMessage = "身份证号码长度不能超过18个字符")]
49.     [DisplayName("身份证号")]
50.     [AmisInputTextField(ColumnRatio = 6)]
51.     public string? IdNo { get; set; }
53.     /// <summary>
54.     /// 出生日期
55.     /// </summary>
56.     [DisplayName("出生日期")]
57.     [AmisDateFieldAttribute(ColumnRatio = 6)]
58.     public DateTime? BirthDate { get; set; }
60.     /// <summary>
61.     /// 手机号码
62.     /// </summary>
63.     [MaxLength(15, ErrorMessage = "手机号码长度不能超过15个字符")]
64.     [Phone(ErrorMessage = "手机号码格式不正确")]
65.     [DisplayName("手机号码")]
66.     [AmisInputTextField(ColumnRatio = 6)]
67.     public string? PhoneNumber { get; set; }
69.     /// <summary>
70.     /// 电子邮箱
71.     /// </summary>
72.     [MaxLength(100, ErrorMessage = "电子邮箱长度不能超过100个字符")]
73.     [EmailAddress(ErrorMessage = "电子邮箱格式不正确")]
74.     [DisplayName("电子邮箱")]
75.     [AmisInputTextField(ColumnRatio = 6)]
76.     public string? Email { get; set; }
78.     /// <summary>
79.     /// 部门ID
80.     /// </summary>
81.     [DisplayName("部门")]
82.     [AmisInputTreeField(
83.         DataSource = "${ROOT_API}/api/identity/Departments/tree",
84.         LabelField = "name",
85.         ValueField = "id",
86.         Multiple = false,
87.         Searchable = true,
88.         ColumnRatio = 12
89.     )]
90.     public long? DepartmentId { get; set; }
92.     /// <summary>
93.     /// 职位
94.     /// </summary>
95.     [MaxLength(100, ErrorMessage = "职位长度不能超过100个字符")]
96.     [DisplayName("职位")]
97.     [AmisInputTextField(ColumnRatio = 6)]
98.     public string? Position { get; set; }
100.     /// <summary>
101.     /// 职级
102.     /// </summary>
103.     [MaxLength(50, ErrorMessage = "职级长度不能超过50个字符")]
104.     [DisplayName("职级")]
105.     [AmisInputTextField(ColumnRatio = 6)]
106.     public string? JobLevel { get; set; }
108.     /// <summary>
109.     /// 入职日期
110.     /// </summary>
111.     [DisplayName("入职日期")]
112.     [AmisDateFieldAttribute(ColumnRatio = 6)]
113.     public DateTime? HireDate { get; set; }
115.     /// <summary>
116.     /// 离职日期
117.     /// </summary>
118.     [DisplayName("离职日期")]
119.     [AmisDateFieldAttribute(ColumnRatio = 6)]
120.     public DateTime? TerminationDate { get; set; }
122.     /// <summary>
123.     /// 在职状态
124.     /// </summary>
125.     [DisplayName("在职状态")]
126.     [AmisFormField(ColumnRatio = 12)]
127.     public EmploymentStatus EmploymentStatus { get; set; }
129.     /// <summary>
130.     /// 关联的用户ID
131.     /// </summary>
132.     [DisplayName("关联用户")]
133.     [AmisSelectField(
134.         Source = "${ROOT_API}/api/identity/Users",
135.         ValueField = "id",
136.         LabelField = "name",
137.         Multiple = false,
138.         Searchable = true,
139.         ColumnRatio = 12
140.     )]
141.     public long? UserId { get; set; }
143.     /// <summary>
144.     /// 紧急联系人
145.     /// </summary>
146.     [MaxLength(100, ErrorMessage = "紧急联系人长度不能超过100个字符")]
147.     [DisplayName("紧急联系人")]
148.     [AmisInputTextField(ColumnRatio = 6)]
149.     public string? EmergencyContact { get; set; }
151.     /// <summary>
152.     /// 紧急联系电话
153.     /// </summary>
154.     [MaxLength(15, ErrorMessage = "紧急联系电话长度不能超过15个字符")]
155.     [Phone(ErrorMessage = "紧急联系电话格式不正确")]
156.     [DisplayName("紧急联系电话")]
157.     [AmisInputTextField(ColumnRatio = 6)]
158.     public string? EmergencyPhone { get; set; }
160.     /// <summary>
161.     /// 地址
162.     /// </summary>
163.     [MaxLength(500, ErrorMessage = "地址长度不能超过500个字符")]
164.     [DisplayName("地址")]
165.     [AmisTextareaField(ColumnRatio = 12)]
166.     public string? Address { get; set; }
168.     /// <summary>
169.     /// 头像地址
170.     /// </summary>
171.     [MaxLength(255, ErrorMessage = "头像地址长度不能超过255个字符")]
172.     [DisplayName("头像")]
173.     [AmisInputImageField(
174.         Receiver = "/file/api/file/images/upload?BucketName=avatar",
175.         Accept = "image/png,image/jpeg,image/jpg",
176.         MaxSize = 2097152,
177.         Multiple = false,
178.         ColumnRatio = 12
179.     )]
180.     public string? AvatarUrl { get; set; }
182.     /// <summary>
183.     /// 备注
184.     /// </summary>
185.     [MaxLength(1000, ErrorMessage = "备注长度不能超过1000个字符")]
186.     [DisplayName("备注")]
187.     [AmisTextareaField(ColumnRatio = 12)]
188.     public string? Remarks { get; set; }
190.     /// <summary>
191.     /// 是否激活
192.     /// </summary>
193.     [DisplayName("是否激活")]
194.     [AmisFormField(ColumnRatio = 6)]
195.     public bool IsActive { get; set; }
196. }

复制代码

2.4 EmployeeQueryDto（查询DTO）

1. // Dtos/Employee/EmployeeQueryDto.cs
2. using CodeSpirit.Amis.Attributes.FormFields;
3. using CodeSpirit.Core.Dtos;
4. using CodeSpirit.IdentityApi.Data.Models;
5. using System.ComponentModel;
7. namespace CodeSpirit.IdentityApi.Dtos.Employee;
9. /// <summary>
10. /// 职工查询数据传输对象
11. /// </summary>
12. public class EmployeeQueryDto : QueryDtoBase
13. {
14.     /// <summary>
15.     /// 关键字搜索（姓名、工号、身份证、手机、邮箱）
16.     /// </summary>
17.     [DisplayName("关键字")]
18.     public string? Keywords { get; set; }
20.     /// <summary>
21.     /// 是否激活
22.     /// </summary>
23.     [DisplayName("是否激活")]
24.     public bool? IsActive { get; set; }
26.     /// <summary>
27.     /// 性别筛选
28.     /// </summary>
29.     [DisplayName("性别")]
30.     public Gender? Gender { get; set; }
32.     /// <summary>
33.     /// 部门ID筛选
34.     /// </summary>
35.     [DisplayName("部门")]
36.     [AmisInputTreeField(
37.         DataSource = "${ROOT_API}/api/identity/Departments/tree",
38.         Multiple = false,
39.         JoinValues = true,
40.         ExtractValue = false,
41.         ShowOutline = true,
42.         LabelField = "name",
43.         ValueField = "id",
44.         Required = false,
45.         Clearable = true,
46.         SubmitOnChange = true,
47.         HeightAuto = true,
48.         SelectFirst = false,
49.         InputOnly = true,
50.         ShowIcon = true
51.     )]
52.     [PageAside()]
53.     public long? DepartmentId { get; set; }
55.     /// <summary>
56.     /// 在职状态筛选
57.     /// </summary>
58.     [DisplayName("在职状态")]
59.     public EmploymentStatus? EmploymentStatus { get; set; }
61.     /// <summary>
62.     /// 入职日期范围
63.     /// </summary>
64.     [DisplayName("入职日期")]
65.     public DateTime[]? HireDate { get; set; }
67.     /// <summary>
68.     /// 职位
69.     /// </summary>
70.     [DisplayName("职位")]
71.     public string? Position { get; set; }
73.     /// <summary>
74.     /// 职级
75.     /// </summary>
76.     [DisplayName("职级")]
77.     public string? JobLevel { get; set; }
78. }

复制代码

说明：
查询DTO特性：

• QueryDtoBase：基础查询DTO，提供了Page、PerPage、OrderBy、OrderDir、Keywords等分页和排序属性
  
• AmisInputTreeField：树形选择组件（用于查询表单）
  
  
  
  • DataSource：数据源URL
    
  • SubmitOnChange：选择后自动提交查询
    
  • Searchable：是否可搜索
    
  • Clearable：是否可清除
    
  • ShowOutline：是否显示轮廓
    
  • HeightAuto：高度自适应
    
  
  
• PageAside()特性：标记该字段在页面侧边栏显示
  
  
  
  • 标记了此特性的字段会自动从主查询表单中排除，避免重复显示
    
  • 特别适用于树形选择、分类筛选等需要独立展示的字段
    
  • 侧边栏字段的变化会自动触发主内容区域的查询刷新（通过SubmitOnChange配置）
    
  • 可以配置侧边栏的位置（左侧/右侧）、宽度、是否固定等属性
    
  
  

查询字段特性：

• 查询DTO中的字段可以使用表单特性（如AmisInputTreeField、AmisSelectField等）来配置查询表单的显示
  
• 支持多条件组合查询，提升查询灵活性
  
• 枚举类型字段会自动生成下拉选择组件
  
• 日期类型字段可以使用AmisDateFieldAttribute配置日期范围选择
  

3. 配置AutoMapper映射

在MappingProfiles目录下创建映射配置：

1. // MappingProfiles/EmployeeProfile.cs
2. using AutoMapper;
3. using CodeSpirit.IdentityApi.Data.Models;
4. using CodeSpirit.IdentityApi.Dtos.Employee;
5. using CodeSpirit.Shared.Extensions;
7. namespace CodeSpirit.IdentityApi.MappingProfiles;
9. /// <summary>
10. /// 职工映射配置
11. /// </summary>
12. public class EmployeeProfile : Profile
13. {
14.     /// <summary>
15.     /// 构造函数
16.     /// </summary>
17.     public EmployeeProfile()
18.     {
19.         // 使用扩展方法配置基本CRUD映射（自动处理Include导航属性）
20.         this.ConfigureBaseCRUDIMappings<
21.             Employee,
22.             EmployeeDto,
23.             long,
24.             CreateEmployeeDto,
25.             UpdateEmployeeDto,
26.             CreateEmployeeDto>();
27.             
28.         // 自定义映射：映射部门名称和用户名
29.         CreateMap<Employee, EmployeeDto>()
30.             .ForMember(dest => dest.DepartmentName, opt => opt.MapFrom(src => src.Department != null ? src.Department.Name : null))
31.             .ForMember(dest => dest.UserName, opt => opt.MapFrom(src => src.User != null ? src.User.UserName : null));
32.     }
33. }

复制代码

说明：

• ConfigureBaseCRUDIMappings扩展方法自动配置基本的CRUD映射
  
• 使用ForMember自定义字段映射逻辑，将导航属性映射到DTO
  
• 支持多个DTO类型的映射配置
  

4. 创建服务接口和实现

4.1 服务接口

1. // Services/IEmployeeService.cs
2. using CodeSpirit.Core;
3. using CodeSpirit.IdentityApi.Data.Models;
4. using CodeSpirit.IdentityApi.Dtos.Employee;
5. using CodeSpirit.Shared.Services;
7. namespace CodeSpirit.IdentityApi.Services;
9. /// <summary>
10. /// 职工服务接口
11. /// </summary>
12. public interface IEmployeeService : IBaseCRUDIService<Employee, EmployeeDto, long, CreateEmployeeDto, UpdateEmployeeDto, EmployeeBatchImportItemDto>, IScopedDependency
13. {
14.     /// <summary>
15.     /// 获取职工列表（分页）
16.     /// </summary>
17.     /// <param name="queryDto">查询条件</param>
18.     /// <returns>职工分页列表</returns>
19.     Task<PageList<EmployeeDto>> GetEmployeesAsync(EmployeeQueryDto queryDto);
21.     /// <summary>
22.     /// 根据部门获取职工列表
23.     /// </summary>
24.     /// <param name="departmentId">部门ID</param>
25.     /// <param name="includeSubDepartments">是否包含子部门</param>
26.     /// <returns>职工列表</returns>
27.     Task<List<EmployeeDto>> GetEmployeesByDepartmentAsync(long departmentId, bool includeSubDepartments = false);
29.     /// <summary>
30.     /// 设置职工激活状态
31.     /// </summary>
32.     /// <param name="id">职工ID</param>
33.     /// <param name="isActive">是否激活</param>
34.     Task SetActiveStatusAsync(long id, bool isActive);
36.     /// <summary>
37.     /// 转移职工到新部门
38.     /// </summary>
39.     /// <param name="employeeId">职工ID</param>
40.     /// <param name="newDepartmentId">新部门ID</param>
41.     Task TransferEmployeeAsync(long employeeId, long? newDepartmentId);
43.     /// <summary>
44.     /// 办理职工离职
45.     /// </summary>
46.     /// <param name="employeeId">职工ID</param>
47.     /// <param name="terminationDate">离职日期</param>
48.     Task TerminateEmployeeAsync(long employeeId, DateTime terminationDate);
50.     /// <summary>
51.     /// 验证工号是否唯一
52.     /// </summary>
53.     /// <param name="employeeNo">工号</param>
54.     /// <param name="excludeId">排除的职工ID（用于更新时验证）</param>
55.     /// <returns>是否唯一</returns>
56.     Task<bool> IsEmployeeNoUniqueAsync(string employeeNo, long? excludeId = null);
57. }

复制代码

4.2 服务实现

1. // Services/EmployeeService.cs
2. using AutoMapper;
3. using CodeSpirit.Core;
4. using CodeSpirit.Core.IdGenerator;
5. using CodeSpirit.IdentityApi.Data;
6. using CodeSpirit.IdentityApi.Data.Models;
7. using CodeSpirit.IdentityApi.Dtos.Employee;
8. using CodeSpirit.IdentityApi.Utilities;
9. using CodeSpirit.Shared.Repositories;
10. using CodeSpirit.Shared.Services;
11. using CodeSpirit.Shared.Dtos.Common;
12. using LinqKit;
13. using Microsoft.AspNetCore.Identity;
14. using Microsoft.EntityFrameworkCore;
16. namespace CodeSpirit.IdentityApi.Services;
18. /// <summary>
19. /// 职工服务实现
20. /// </summary>
21. public class EmployeeService : BaseCRUDIService<Employee, EmployeeDto, long, CreateEmployeeDto, UpdateEmployeeDto, EmployeeBatchImportItemDto>, IEmployeeService
22. {
23.     private readonly IRepository<Employee> _employeeRepository;
24.     private readonly IRepository<Department> _departmentRepository;
25.     private readonly IRepository _userRepository;
26.     private readonly ILogger<EmployeeService> _logger;
27.     private readonly IIdGenerator _idGenerator;
28.     private readonly ICurrentUser _currentUser;
29.     private readonly ApplicationDbContext _dbContext;
30.     private readonly IDepartmentService _departmentService;
31.     private readonly UserManager _userManager;
33.     /// <summary>
34.     /// 构造函数
35.     /// </summary>
36.     public EmployeeService(
37.         IRepository<Employee> employeeRepository,
38.         IRepository<Department> departmentRepository,
39.         IRepository userRepository,
40.         IMapper mapper,
41.         ILogger<EmployeeService> logger,
42.         IIdGenerator idGenerator,
43.         ICurrentUser currentUser,
44.         ApplicationDbContext dbContext,
45.         IDepartmentService departmentService,
46.         UserManager userManager,
47.         EnhancedBatchImportHelper<EmployeeBatchImportItemDto> importHelper)
48.         : base(employeeRepository, mapper, importHelper)
49.     {
50.         _employeeRepository = employeeRepository;
51.         _departmentRepository = departmentRepository;
52.         _userRepository = userRepository;
53.         _logger = logger;
54.         _idGenerator = idGenerator;
55.         _currentUser = currentUser;
56.         _dbContext = dbContext;
57.         _departmentService = departmentService;
58.         _userManager = userManager;
59.     }
61.     /// <summary>
62.     /// 获取职工列表（分页）
63.     /// </summary>
64.     public async Task<PageList<EmployeeDto>> GetEmployeesAsync(EmployeeQueryDto queryDto)
65.     {
66.         var predicate = PredicateBuilder.New<Employee>(true);
68.         // 应用搜索关键词过滤
69.         if (!string.IsNullOrWhiteSpace(queryDto.Keywords))
70.         {
71.             string searchLower = queryDto.Keywords.ToLower();
72.             predicate = predicate.Or(e => e.Name.ToLower().Contains(searchLower));
73.             predicate = predicate.Or(e => e.EmployeeNo.ToLower().Contains(searchLower));
74.             predicate = predicate.Or(e => e.IdNo.Contains(queryDto.Keywords));
75.             predicate = predicate.Or(e => e.PhoneNumber.Contains(queryDto.Keywords));
76.             predicate = predicate.Or(e => e.Email.ToLower().Contains(searchLower));
77.         }
79.         // 应用其他过滤条件
80.         if (queryDto.IsActive.HasValue)
81.         {
82.             predicate = predicate.And(e => e.IsActive == queryDto.IsActive.Value);
83.         }
85.         if (queryDto.Gender.HasValue)
86.         {
87.             predicate = predicate.And(e => e.Gender == queryDto.Gender.Value);
88.         }
90.         if (queryDto.DepartmentId.HasValue)
91.         {
92.             predicate = predicate.And(e => e.DepartmentId == queryDto.DepartmentId.Value);
93.         }
95.         if (queryDto.EmploymentStatus.HasValue)
96.         {
97.             predicate = predicate.And(e => e.EmploymentStatus == queryDto.EmploymentStatus.Value);
98.         }
100.         if (!string.IsNullOrWhiteSpace(queryDto.Position))
101.         {
102.             predicate = predicate.And(e => e.Position == queryDto.Position);
103.         }
105.         if (!string.IsNullOrWhiteSpace(queryDto.JobLevel))
106.         {
107.             predicate = predicate.And(e => e.JobLevel == queryDto.JobLevel);
108.         }
110.         if (queryDto.HireDate != null && queryDto.HireDate.Length == 2)
111.         {
112.             predicate = predicate.And(e => e.HireDate >= queryDto.HireDate[0]);
113.             predicate = predicate.And(e => e.HireDate <= queryDto.HireDate[1]);
114.         }
116.         // 创建查询
117.         var query = _employeeRepository.CreateQuery()
118.             .Include(e => e.Department)
119.             .Include(e => e.User)
120.             .Where(predicate);
122.         // 执行分页查询
123.         var totalCount = await query.CountAsync();
124.         var employees = await query
125.             .OrderByDescending(e => e.CreatedAt)
126.             .Skip((queryDto.Page - 1) * queryDto.PerPage)
127.             .Take(queryDto.PerPage)
128.             .ToListAsync();
130.         // 映射到DTO
131.         var employeeDtos = Mapper.Map<List<EmployeeDto>>(employees);
133.         // 设置关联数据
134.         foreach (var dto in employeeDtos)
135.         {
136.             var employee = employees.First(e => e.Id == dto.Id);
137.             dto.DepartmentName = employee.Department?.Name;
138.             dto.UserName = employee.User?.UserName;
139.         }
141.         return new PageList<EmployeeDto>(employeeDtos, totalCount);
142.     }
144.     /// <summary>
145.     /// 根据部门获取职工列表
146.     /// </summary>
147.     public async Task<List<EmployeeDto>> GetEmployeesByDepartmentAsync(long departmentId, bool includeSubDepartments = false)
148.     {
149.         var departmentIds = new List<long> { departmentId };
150.         
151.         if (includeSubDepartments)
152.         {
153.             var subDepartments = await _departmentService.GetSubDepartmentsAsync(departmentId);
154.             departmentIds.AddRange(subDepartments.Select(d => d.Id));
155.         }
157.         var employees = await _employeeRepository.CreateQuery()
158.             .Include(e => e.Department)
159.             .Include(e => e.User)
160.             .Where(e => departmentIds.Contains(e.DepartmentId ?? 0))
161.             .ToListAsync();
163.         return Mapper.Map<List<EmployeeDto>>(employees);
164.     }
166.     /// <summary>
167.     /// 设置职工激活状态
168.     /// </summary>
169.     public async Task SetActiveStatusAsync(long id, bool isActive)
170.     {
171.         var employee = await _employeeRepository.GetByIdAsync(id);
172.         if (employee == null)
173.         {
174.             throw new AppServiceException(404, "职工不存在");
175.         }
177.         employee.IsActive = isActive;
178.         await _employeeRepository.UpdateAsync(employee);
179.     }
181.     /// <summary>
182.     /// 转移职工到新部门
183.     /// </summary>
184.     public async Task TransferEmployeeAsync(long employeeId, long? newDepartmentId)
185.     {
186.         var employee = await _employeeRepository.GetByIdAsync(employeeId);
187.         if (employee == null)
188.         {
189.             throw new AppServiceException(404, "职工不存在");
190.         }
192.         if (newDepartmentId.HasValue)
193.         {
194.             var departmentExists = await _departmentRepository.ExistsAsync(d => d.Id == newDepartmentId.Value);
195.             if (!departmentExists)
196.             {
197.                 throw new AppServiceException(400, "部门不存在");
198.             }
199.         }
201.         employee.DepartmentId = newDepartmentId;
202.         await _employeeRepository.UpdateAsync(employee);
203.     }
205.     /// <summary>
206.     /// 办理职工离职
207.     /// </summary>
208.     public async Task TerminateEmployeeAsync(long employeeId, DateTime terminationDate)
209.     {
210.         var employee = await _employeeRepository.GetByIdAsync(employeeId);
211.         if (employee == null)
212.         {
213.             throw new AppServiceException(404, "职工不存在");
214.         }
216.         employee.EmploymentStatus = EmploymentStatus.Resigned;
217.         employee.TerminationDate = terminationDate;
218.         employee.IsActive = false;
219.         
220.         await _employeeRepository.UpdateAsync(employee);
221.     }
223.     /// <summary>
224.     /// 验证工号是否唯一
225.     /// </summary>
226.     public async Task<bool> IsEmployeeNoUniqueAsync(string employeeNo, long? excludeId = null)
227.     {
228.         var query = _employeeRepository.CreateQuery()
229.             .Where(e => e.EmployeeNo == employeeNo && e.TenantId == _currentUser.TenantId);
231.         if (excludeId.HasValue)
232.         {
233.             query = query.Where(e => e.Id != excludeId.Value);
234.         }
236.         return !await query.AnyAsync();
237.     }
239.     /// <summary>
240.     /// 验证创建DTO
241.     /// </summary>
242.     protected override async Task ValidateCreateDto(CreateEmployeeDto createDto)
243.     {
244.         await base.ValidateCreateDto(createDto);
246.         // 验证工号唯一性
247.         bool isUnique = await IsEmployeeNoUniqueAsync(createDto.EmployeeNo);
248.         if (!isUnique)
249.         {
250.             throw new AppServiceException(400, $"工号 {createDto.EmployeeNo} 已存在，请使用其他工号");
251.         }
253.         // 验证部门是否存在
254.         if (createDto.DepartmentId.HasValue)
255.         {
256.             var departmentExists = await _departmentRepository.ExistsAsync(d => d.Id == createDto.DepartmentId.Value);
257.             if (!departmentExists)
258.             {
259.                 throw new AppServiceException(400, "部门不存在");
260.             }
261.         }
263.         // 验证用户是否存在（如果指定了用户ID）
264.         if (createDto.UserId.HasValue)
265.         {
266.             var userExists = await _userRepository.ExistsAsync(u => u.Id == createDto.UserId.Value);
267.             if (!userExists)
268.             {
269.                 throw new AppServiceException(400, "用户不存在");
270.             }
271.         }
272.     }
274.     /// <summary>
275.     /// 验证更新DTO
276.     /// </summary>
277.     protected override async Task ValidateUpdateDto(long id, UpdateEmployeeDto updateDto)
278.     {
279.         await base.ValidateUpdateDto(id, updateDto);
281.         // 验证工号唯一性（排除当前记录）
282.         bool isUnique = await IsEmployeeNoUniqueAsync(updateDto.EmployeeNo, id);
283.         if (!isUnique)
284.         {
285.             throw new AppServiceException(400, $"工号 {updateDto.EmployeeNo} 已存在，请使用其他工号");
286.         }
288.         // 验证部门是否存在
289.         if (updateDto.DepartmentId.HasValue)
290.         {
291.             var departmentExists = await _departmentRepository.ExistsAsync(d => d.Id == updateDto.DepartmentId.Value);
292.             if (!departmentExists)
293.             {
294.                 throw new AppServiceException(400, "部门不存在");
295.             }
296.         }
298.         // 验证用户是否存在（如果指定了用户ID）
299.         if (updateDto.UserId.HasValue)
300.         {
301.             var userExists = await _userRepository.ExistsAsync(u => u.Id == updateDto.UserId.Value);
302.             if (!userExists)
303.             {
304.                 throw new AppServiceException(400, "用户不存在");
305.             }
306.         }
307.     }
309.     /// <summary>
310.     /// 创建实体前的处理
311.     /// </summary>
312.     protected override async Task<Employee> OnCreating(CreateEmployeeDto createDto)
313.     {
314.         var employee = await base.OnCreating(createDto);
315.         
316.         // 设置租户ID
317.         employee.TenantId = _currentUser.TenantId;
318.         
319.         // 生成ID（如果需要）
320.         if (employee.Id == 0)
321.         {
322.             employee.Id = await _idGenerator.GenerateIdAsync();
323.         }
325.         return employee;
326.     }
327. }

复制代码

说明：

• 继承自BaseCRUDIService，自动获得标准的CRUD方法和批量导入功能
  
• 实现IScopedDependency接口，服务会自动注册
  
• 重写ValidateCreateDto和ValidateUpdateDto方法实现业务验证（工号唯一性、部门存在性等）
  
• 重写OnCreating方法设置租户ID和生成ID
  
• 使用LinqKit的PredicateBuilder构建动态查询条件
  
• 提供额外的业务方法（设置激活状态、转移部门、办理离职等）
  

5. 创建控制器

在Controllers目录下创建控制器：

1. // Controllers/EmployeesController.cs
2. using CodeSpirit.Core;
3. using CodeSpirit.Core.Attributes;
4. using CodeSpirit.Core.Dtos;
5. using CodeSpirit.Core.Enums;
6. using CodeSpirit.IdentityApi.Dtos.Employee;
7. using CodeSpirit.IdentityApi.Services;
8. using CodeSpirit.Shared.Dtos.Common;
9. using Microsoft.AspNetCore.Mvc;
10. using System.ComponentModel;
12. namespace CodeSpirit.IdentityApi.Controllers;
14. /// <summary>
15. /// 职工管理控制器
16. /// </summary>
17. [DisplayName("职工管理")]
18. [Navigation(Icon = "fa-solid fa-user-tie", PlatformType = PlatformType.Tenant)]
19. public class EmployeesController : ApiControllerBase
20. {
21.     private readonly IEmployeeService _employeeService;
23.     /// <summary>
24.     /// 构造函数
25.     /// </summary>
26.     public EmployeesController(IEmployeeService employeeService)
27.     {
28.         _employeeService = employeeService;
29.     }
31.     /// <summary>
32.     /// 获取职工列表
33.     /// </summary>
34.     /// <param name="queryDto">查询条件</param>
35.     /// <returns>职工列表结果</returns>
36.     [HttpGet]
37.     [DisplayName("获取职工列表")]
38.     public async Task>>> GetEmployees([FromQuery] EmployeeQueryDto queryDto)
39.     {
40.         var employees = await _employeeService.GetEmployeesAsync(queryDto);
41.         return SuccessResponse(employees);
42.     }
44.     /// <summary>
45.     /// 根据部门获取职工列表
46.     /// </summary>
47.     /// <param name="departmentId">部门ID</param>
48.     /// <param name="includeSubDepartments">是否包含子部门</param>
49.     /// <returns>职工列表</returns>
50.     [HttpGet("department/{departmentId}")]
51.     [DisplayName("根据部门获取职工")]
52.     public async Task>>> GetEmployeesByDepartment(
53.         long departmentId,
54.         [FromQuery] bool includeSubDepartments = false)
55.     {
56.         var employees = await _employeeService.GetEmployeesByDepartmentAsync(departmentId, includeSubDepartments);
57.         return SuccessResponse(employees);
58.     }
60.     /// <summary>
61.     /// 获取职工详情
62.     /// </summary>
63.     /// <param name="id">职工ID</param>
64.     /// <returns>职工详细信息</returns>
65.     [HttpGet("{id:long}")]
66.     [DisplayName("获取职工详情")]
67.     public async Task>> GetEmployee(long id)
68.     {
69.         var employee = await _employeeService.GetAsync(id);
70.         return SuccessResponse(employee);
71.     }
73.     /// <summary>
74.     /// 创建职工
75.     /// </summary>
76.     /// <param name="createDto">创建职工请求数据</param>
77.     /// <returns>创建的职工信息</returns>
78.     [HttpPost]
79.     [DisplayName("创建职工")]
80.     public async Task>> CreateEmployee(CreateEmployeeDto createDto)
81.     {
82.         ArgumentNullException.ThrowIfNull(createDto);
83.         var employeeDto = await _employeeService.CreateAsync(createDto);
84.         return SuccessResponse(employeeDto);
85.     }
87.     /// <summary>
88.     /// 更新职工
89.     /// </summary>
90.     /// <param name="id">职工ID</param>
91.     /// <param name="updateDto">更新职工请求数据</param>
92.     /// <returns>更新操作结果</returns>
93.     [HttpPut("{id:long}")]
94.     [DisplayName("更新职工")]
95.     public async Task> UpdateEmployee(long id, UpdateEmployeeDto updateDto)
96.     {
97.         await _employeeService.UpdateAsync(id, updateDto);
98.         return SuccessResponse();
99.     }
101.     /// <summary>
102.     /// 删除职工
103.     /// </summary>
104.     /// <param name="id">职工ID</param>
105.     /// <returns>删除操作结果</returns>
106.     [HttpDelete("{id:long}")]
107.     [Operation("删除", "ajax", null, "确定要删除此职工吗？")]
108.     [DisplayName("删除职工")]
109.     public async Task> DeleteEmployee(long id)
110.     {
111.         await _employeeService.DeleteAsync(id);
112.         return SuccessResponse();
113.     }
115.     /// <summary>
116.     /// 批量删除职工
117.     /// </summary>
118.     /// <param name="request">批量删除请求</param>
119.     /// <returns>批量删除操作结果</returns>
120.     [HttpPost("batch-delete")]
121.     [Operation("批量删除", "ajax", null, "确定要批量删除选中的职工吗？", isBulkOperation: true)]
122.     [DisplayName("批量删除职工")]
123.     public async Task> BatchDeleteEmployees([FromBody] BatchOperationDto<long> request)
124.     {
125.         ArgumentNullException.ThrowIfNull(request);
126.         (int successCount, List<long> failedIds) = await _employeeService.BatchDeleteAsync(request.Ids);
127.         
128.         return failedIds.Any()
129.             ? SuccessResponse($"成功删除 {successCount} 个职工，但以下职工删除失败: {string.Join(", ", failedIds)}")
130.             : SuccessResponse($"成功删除 {successCount} 个职工！");
131.     }
133.     /// <summary>
134.     /// 设置职工激活状态
135.     /// </summary>
136.     /// <param name="id">职工ID</param>
137.     /// <param name="isActive">是否激活</param>
138.     /// <returns>操作结果</returns>
139.     [HttpPut("{id:long}/active")]
140.     [DisplayName("设置激活状态")]
141.     public async Task> SetActiveStatus(long id, [FromBody] bool isActive)
142.     {
143.         await _employeeService.SetActiveStatusAsync(id, isActive);
144.         return SuccessResponse();
145.     }
147.     /// <summary>
148.     /// 转移职工到新部门
149.     /// </summary>
150.     /// <param name="id">职工ID</param>
151.     /// <param name="request">转移请求</param>
152.     /// <returns>操作结果</returns>
153.     [HttpPut("{id:long}/transfer")]
154.     [DisplayName("转移部门")]
155.     public async Task> TransferEmployee(long id, [FromBody] TransferEmployeeRequest request)
156.     {
157.         await _employeeService.TransferEmployeeAsync(id, request.DepartmentId);
158.         return SuccessResponse();
159.     }
161.     /// <summary>
162.     /// 办理职工离职
163.     /// </summary>
164.     /// <param name="id">职工ID</param>
165.     /// <param name="request">离职请求</param>
166.     /// <returns>操作结果</returns>
167.     [HttpPut("{id:long}/terminate")]
168.     [DisplayName("办理离职")]
169.     public async Task> TerminateEmployee(long id, [FromBody] TerminateEmployeeRequest request)
170.     {
171.         await _employeeService.TerminateEmployeeAsync(id, request.TerminationDate);
172.         return SuccessResponse();
173.     }
174. }
176. /// <summary>
177. /// 转移职工请求
178. /// </summary>
179. public class TransferEmployeeRequest
180. {
181.     public long? DepartmentId { get; set; }
182. }
184. /// <summary>
185. /// 离职请求
186. /// </summary>
187. public class TerminateEmployeeRequest
188. {
189.     public DateTime TerminationDate { get; set; }
190. }

复制代码

说明：

• 继承自ApiControllerBase，自动获得统一的响应格式和异常处理
  
• DisplayName特性用于前端界面显示
  
• Navigation特性用于添加到导航菜单
  
• Operation特性用于配置操作按钮（删除确认对话框）
  
• 使用SuccessResponse方法返回统一的成功响应
  
• 提供额外的业务操作接口（设置激活状态、转移部门、办理离职等）
  

6. 配置数据库上下文

在Data目录下的DbContext中添加实体：

1. // Data/ApplicationDbContext.cs
2. using CodeSpirit.IdentityApi.Data.Models;
3. using CodeSpirit.Shared.Data;
4. using Microsoft.EntityFrameworkCore;
6. namespace CodeSpirit.IdentityApi.Data;
8. /// <summary>
9. /// 身份认证系统数据库上下文 - 支持多租户和多数据库
10. /// </summary>
11. public class ApplicationDbContext : MultiDatabaseDbContextBase
12. {
13.     /// <summary>
14.     /// 职工
15.     /// </summary>
16.     public DbSet<Employee> Employees => Set<Employee>();
18.     protected override void OnModelCreating(ModelBuilder modelBuilder)
19.     {
20.         base.OnModelCreating(modelBuilder);
22.         // 配置Employee实体
23.         modelBuilder.Entity<Employee>(entity =>
24.         {
25.             entity.ToTable(nameof(Employee));
26.             entity.Property(e => e.Id).ValueGeneratedNever();
28.             // 租户感知的工号复合唯一索引：同一租户内工号唯一
29.             entity.HasIndex(e => new { e.TenantId, e.EmployeeNo })
30.                 .IsUnique()
31.                 .HasDatabaseName("IX_Employee_TenantId_EmployeeNo");
33.             // 索引 DepartmentId，提高查询部门员工的性能
34.             entity.HasIndex(e => e.DepartmentId)
35.                 .HasDatabaseName("IX_Employee_DepartmentId");
37.             // 索引 UserId，提高查询用户关联的性能
38.             entity.HasIndex(e => e.UserId)
39.                 .HasDatabaseName("IX_Employee_UserId");
41.             // 索引 IsActive，提高按状态过滤的性能
42.             entity.HasIndex(e => e.IsActive)
43.                 .HasDatabaseName("IX_Employee_IsActive");
45.             // 索引 EmploymentStatus，提高按在职状态过滤的性能
46.             entity.HasIndex(e => e.EmploymentStatus)
47.                 .HasDatabaseName("IX_Employee_EmploymentStatus");
49.             // 配置与部门的关系
50.             entity.HasOne(e => e.Department)
51.                 .WithMany()
52.                 .HasForeignKey(e => e.DepartmentId)
53.                 .OnDelete(DeleteBehavior.SetNull);
55.             // 配置与用户的关系
56.             entity.HasOne(e => e.User)
57.                 .WithMany()
58.                 .HasForeignKey(e => e.UserId)
59.                 .OnDelete(DeleteBehavior.SetNull);
60.         });
61.     }
62. }

复制代码

说明：

• 继承自MultiDatabaseDbContextBase，支持MySQL和SQL Server
  
• 配置表名、主键、字段长度等
  
• 配置复合唯一索引（租户ID + 工号），确保同一租户内工号唯一
  
• 配置关联关系的级联删除策略（SetNull表示删除部门或用户时，职工记录保留但关联字段设为null）
  
• 添加必要的索引提升查询性能
  

7. 服务注册

CodeSpirit框架通过标记接口自动注册服务，无需手动注册：

1. // IEmployeeService接口继承了IScopedDependency接口
2. public interface IEmployeeService : IBaseCRUDIService<...>, IScopedDependency
3. {
4.     // ...
5. }

复制代码

说明：

• 服务接口继承IScopedDependency接口，服务会自动注册为Scoped生命周期
  
• 框架会自动扫描并注册所有标记接口的服务
  
• 无需在Program.cs中手动注册
  

8. 创建数据库迁移

CodeSpirit框架支持多数据库架构，迁移文件按数据库类型分离存储。创建迁移时必须指定迁移目录参数。

1. # 进入IdentityApi项目目录
2. cd Src/ApiServices/CodeSpirit.IdentityApi
4. # 创建迁移（根据数据库类型选择）
5. # MySQL - 迁移文件将保存到 Migrations/MySql/ 目录
6. dotnet ef migrations add AddEmployees --context MySqlApplicationDbContext --output-dir Migrations/MySql
8. # SQL Server - 迁移文件将保存到 Migrations/SqlServer/ 目录
9. dotnet ef migrations add AddEmployees --context SqlServerApplicationDbContext --output-dir Migrations/SqlServer
11. # 应用迁移
12. dotnet ef database update --context MySqlApplicationDbContext
13. # 或
14. dotnet ef database update --context SqlServerApplicationDbContext

复制代码

迁移目录结构：

1. Src/ApiServices/CodeSpirit.IdentityApi/
2. ├── Migrations/
3. │   ├── MySql/                          # MySQL迁移文件
4. │   │   ├── 20251222_AddEmployees.cs
5. │   │   ├── 20251222_AddEmployees.Designer.cs
6. │   │   └── MySqlApplicationDbContextModelSnapshot.cs
7. │   └── SqlServer/                      # SQL Server迁移文件
8. │       ├── 20251222_AddEmployees.cs
9. │       ├── 20251222_AddEmployees.Designer.cs
10. │       └── SqlServerApplicationDbContextModelSnapshot.cs

复制代码

说明：

• --output-dir参数用于指定迁移文件的输出目录
  
• MySQL迁移文件必须保存到Migrations/MySql/目录
  
• SQL Server迁移文件必须保存到Migrations/SqlServer/目录
  
• 每个数据库类型都有独立的ModelSnapshot.cs文件
  
• 这样可以确保不同数据库类型的迁移文件互不干扰
  

功能特性

通过以上步骤，您已经完成了一个完整的CRUD功能开发。CodeSpirit框架会自动提供以下功能：
自动生成的功能

• ✅ AMIS前端界面：基于控制器和DTO的特性自动生成
  
  
  
  • 表格展示（支持头像、日期格式化、状态显示等）
    
  • 表单编辑（支持表单分组、树形选择、图片上传等）
    
  • 多条件搜索筛选（关键字、部门、状态、日期范围等）
    
  • 批量操作（批量删除等）
    
  
  
• ✅ 统一的API响应格式：使用ApiResponse统一响应
  
• ✅ 分页查询：支持分页、排序、多条件筛选
  
• ✅ 批量操作：支持批量删除、批量导入等操作
  
• ✅ 异常处理：统一的异常处理和错误响应
  
• ✅ 权限控制：支持基于特性的权限控制
  
• ✅ 审计日志：自动记录创建、更新、删除操作
  
• ✅ 多租户支持：自动进行数据隔离
  
• ✅ 软删除支持：删除操作使用软删除，数据可恢复
  

标准CRUD操作

操作HTTP方法路径说明查询列表GET/api/identity/Employees支持多条件查询和关键字搜索查询详情GET/api/identity/Employees/{id}根据ID获取单个职工创建POST/api/identity/Employees创建新职工更新PUT/api/identity/Employees/{id}更新职工信息删除DELETE/api/identity/Employees/{id}删除单个职工（软删除）批量删除POST/api/identity/Employees/batch-delete批量删除职工根据部门查询GET/api/identity/Employees/department/{departmentId}根据部门获取职工列表设置激活状态PUT/api/identity/Employees/{id}/active设置职工激活状态转移部门PUT/api/identity/Employees/{id}/transfer转移职工到新部门办理离职PUT/api/identity/Employees/{id}/terminate办理职工离职业务验证示例

创建时验证

1. protected override async Task ValidateCreateDto(CreateEmployeeDto createDto)
2. {
3.     await base.ValidateCreateDto(createDto);
5.     // 验证工号唯一性
6.     bool isUnique = await IsEmployeeNoUniqueAsync(createDto.EmployeeNo);
7.     if (!isUnique)
8.     {
9.         throw new AppServiceException(400, $"工号 {createDto.EmployeeNo} 已存在，请使用其他工号");
10.     }
12.     // 验证部门是否存在
13.     if (createDto.DepartmentId.HasValue)
14.     {
15.         var departmentExists = await _departmentRepository.ExistsAsync(d => d.Id == createDto.DepartmentId.Value);
16.         if (!departmentExists)
17.         {
18.             throw new AppServiceException(400, "部门不存在");
19.         }
20.     }
22.     // 验证用户是否存在（如果指定了用户ID）
23.     if (createDto.UserId.HasValue)
24.     {
25.         var userExists = await _userRepository.ExistsAsync(u => u.Id == createDto.UserId.Value);
26.         if (!userExists)
27.         {
28.             throw new AppServiceException(400, "用户不存在");
29.         }
30.     }
31. }

复制代码

更新时验证

1. protected override async Task ValidateUpdateDto(long id, UpdateEmployeeDto updateDto)
2. {
3.     await base.ValidateUpdateDto(id, updateDto);
5.     // 验证工号唯一性（排除当前记录）
6.     bool isUnique = await IsEmployeeNoUniqueAsync(updateDto.EmployeeNo, id);
7.     if (!isUnique)
8.     {
9.         throw new AppServiceException(400, $"工号 {updateDto.EmployeeNo} 已存在，请使用其他工号");
10.     }
12.     // 验证部门是否存在
13.     if (updateDto.DepartmentId.HasValue)
14.     {
15.         var departmentExists = await _departmentRepository.ExistsAsync(d => d.Id == updateDto.DepartmentId.Value);
16.         if (!departmentExists)
17.         {
18.             throw new AppServiceException(400, "部门不存在");
19.         }
20.     }
21. }

复制代码

创建前处理

1. protected override async Task<Employee> OnCreating(CreateEmployeeDto createDto)
2. {
3.     var employee = await base.OnCreating(createDto);
4.    
5.     // 设置租户ID
6.     employee.TenantId = _currentUser.TenantId;
7.    
8.     // 生成ID（如果需要）
9.     if (employee.Id == 0)
10.     {
11.         employee.Id = await _idGenerator.GenerateIdAsync();
12.     }
14.     return employee;
15. }

复制代码

扩展功能示例

添加权限控制

1. [HttpPost]
2. [DisplayName("创建职工")]
3. [Permission("identity_employees_create")]  // 添加权限控制
4. public async Task>> CreateEmployee(CreateEmployeeDto createDto)
5. {
6.     // ...
7. }

复制代码

添加导航菜单

1. [DisplayName("职工管理")]
2. [Navigation(Icon = "fa-solid fa-user-tie", PlatformType = PlatformType.Tenant)]  // 添加到导航菜单
3. public class EmployeesController : ApiControllerBase
4. {
5.     // ...
6. }

复制代码

自定义查询方法

1. /// <summary>
2. /// 获取在职职工列表
3. /// </summary>
4. public async Task<List<EmployeeDto>> GetActiveEmployeesAsync()
5. {
6.     var employees = await Repository.CreateQuery()
7.         .Where(e => e.IsActive && e.EmploymentStatus == EmploymentStatus.Active)
8.         .Include(e => e.Department)
9.         .Include(e => e.User)
10.         .ToListAsync();
12.     return Mapper.Map<List<EmployeeDto>>(employees);
13. }

复制代码

使用PageAside特性实现侧边栏筛选

PageAside()特性用于将查询字段放置在页面侧边栏，特别适用于树形选择、分类筛选等场景。使用此特性后，该字段会从主查询表单中移除，仅在侧边栏显示。
特性说明：

1. /// <summary>
2. /// 部门ID筛选
3. /// </summary>
4. [DisplayName("部门")]
5. [AmisInputTreeField(
6.     DataSource = "${ROOT_API}/api/identity/Departments/tree",
7.     Multiple = false,
8.     JoinValues = true,
9.     ExtractValue = false,
10.     ShowOutline = true,
11.     LabelField = "name",
12.     ValueField = "id",
13.     Required = false,
14.     Clearable = true,
15.     SubmitOnChange = true,  // 选择后自动提交查询
16.     HeightAuto = true,
17.     SelectFirst = false,
18.     InputOnly = true,
19.     ShowIcon = true
20. )]
21. [PageAside()]  // 标记为侧边栏字段
22. public long? DepartmentId { get; set; }

复制代码

PageAside特性的主要属性：

• Target：表单提交目标，如果为空则自动设置为CRUD组件名称
  
• SubmitOnInit：是否在初始化时提交，默认为false
  
• WrapWithPanel：是否不使用面板包装，默认为false
  
• AsideResizor：侧边栏宽度是否可调整，默认为true
  
• AsideMinWidth：侧边栏最小宽度（像素），默认为0
  
• AsideMaxWidth：侧边栏最大宽度（像素），默认为0
  
• AsideSticky：侧边栏是否固定，默认为true
  
• AsidePosition：侧边栏位置（Left/Right），默认为Left
  

使用场景：

• 树形分类筛选：如部门树、分类树等，放在侧边栏作为导航筛选器
  
• 独立筛选器：需要独立展示的筛选条件，避免主表单过于拥挤
  
• 联动查询：侧边栏字段变化时自动触发主内容区域刷新
  

注意事项：

• 标记了PageAside()特性的字段会自动从主查询表单中排除
  
• 建议配合SubmitOnChange = true使用，实现选择后自动查询
  
• 侧边栏字段的查询条件会自动合并到主查询中
  

最佳实践

• 实体设计：
  
  
  
  • 实现IFullAuditable接口获得完整的审计字段（创建、更新、删除）
    
  • 实现IMultiTenant接口支持多租户数据隔离
    
  • 实现IIsActive接口支持激活状态管理
    
  • 合理设计导航属性，使用Include避免N+1查询问题
    
  • 为唯一性字段创建复合唯一索引（租户ID + 业务字段）
    
  
  
• DTO分离：
  
  
  
  • 为创建、更新、查询分别创建DTO
    
  • 使用DisplayName特性提供友好的字段名称
    
  • 使用AmisColumn特性控制前端表格列显示
    
  • 使用FormGroup特性将表单字段分组，提升用户体验
    
  • 使用AmisInputTreeField等特性自动生成合适的表单组件
    
  
  
• 服务层：
  
  
  
  • 继承BaseCRUDIService获得CRUD和批量导入功能
    
  • 服务接口继承IScopedDependency接口自动注册
    
  • 重写ValidateCreateDto和ValidateUpdateDto实现业务验证
    
  • 重写OnCreating方法设置租户ID和生成ID
    
  • 使用LinqKit的PredicateBuilder构建动态查询条件
    
  
  
• 控制器：
  
  
  
  • 保持简洁，主要调用服务层方法
    
  • 使用DisplayName和Navigation特性
    
  • 使用Operation特性配置操作按钮（删除确认对话框）
    
  • 提供额外的业务操作接口（如设置激活状态、转移部门等）
    
  
  
• 验证：
  
  
  
  • 使用DataAnnotations进行基础数据验证
    
  • 重写服务层的验证方法实现业务验证（唯一性、关联存在性等）
    
  • 使用AppServiceException抛出业务异常
    
  • 在数据库层面创建唯一索引确保数据完整性
    
  
  
• 数据库设计：
  
  
  
  • 为常用查询字段创建索引提升性能
    
  • 合理配置关联关系的级联删除策略
    
  • 使用复合唯一索引确保租户内业务字段唯一性
    
  
  
• 文档注释：
  
  
  
  • 为所有公共成员添加XML文档注释
    
  • 使用、、标签
    
  
  

相关文档

• CodeSpirit.Core核心框架
  
• 开发环境搭建指南
  
• 项目整体架构设计
  
• 统一异常处理指南
  

总结

通过CodeSpirit框架的BaseCRUDIService和标准开发模式，您可以快速开发出功能完整的CRUD接口。职工管理模块展示了：

• ✅ 标准CRUD操作的实现
  
• ✅ 关联关系管理（部门、用户账号）
  
• ✅ 业务验证逻辑的编写（工号唯一性、部门存在性等）
  
• ✅ 多条件查询的实现（关键字、部门、状态、日期范围等）
  
• ✅ 表单分组展示的使用
  
• ✅ 额外业务操作的实现（设置激活状态、转移部门、办理离职等）
  
• ✅ AMIS特性的使用（表格列、表单字段、图片上传等）
  

框架会自动处理大部分样板代码，让您专注于业务逻辑的实现。
更多交流请关注“CodeSpirit-码灵”公众号进群！！！

祝您开发愉快！
来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！

yyds。多谢分享