语义说明：{@code code} 自 W4 起不是全局唯一（唯一键为 {@code uk_site_parent_code(parent_site_id, code)}），
+ * 多校部署下不同父站可挂同名 code 子站。**生产代码请用**
+ * {@link #findFirstByCodeOrderByIdAsc(String)}（确定性取最早一条，不会因歧义 500）；
+ * 本方法语义为"断言 code 唯一"，保留给集成测试做唯一性/落库断言。
+ */
Optional 歧义时不再抛异常导致 500，而是确定性取最早创建的站点；跨服务单键定位的正解仍是
+ * (siteCode,itemCode) 成对 + 建站保证 code 全局唯一（设计 §1.3/R4）。
+ */
+ Optional 兼容相对地址（{@code /cms/upload/..}）与带站点/网关前缀的绝对地址；非本站上传地址返回空
+ * （外链、data: 等一律不参与场景引用）。
+ */
+ public Optional 用途：正文内嵌图这类"没有 id 列表可依赖"的引用，保存时以内容为权威口径重建归属。
+ */
+ public Set 为什么需要"解除"这一步：封面/正文图在编辑时可能被删掉或换掉，若不按内容同步，
+ * 旧资产的引用会永久挂在本事项上（既不被内容引用、也不进入未使用清理口径）。
+ */
+ @Transactional
+ public int syncAssets(Integer siteId, String refType, Integer refId, Set 索引声明口径：带排序方向的门户列表索引 `idx_svc_item_portal`
+ * (site_id, status, sort_no ASC, publish_time DESC, id DESC) 含 DESC 列，Hibernate
+ * {@code @Index} 无法表达，故只声明在 cms_init.sql / upgrade_svcitem_r2.sql；
+ * 纯靠 ddl-auto=update 建立的开发库需跑一次 upgrade_svcitem_r2.sql 补建（脚本内为幂等守卫块）。
+ */
+@Getter
+@Setter
+@Entity
+@Table(name = "cms_service_item",
+ uniqueConstraints = @UniqueConstraint(name = "uk_svc_item_code", columnNames = {"site_id", "item_code"}),
+ indexes = {
+ @Index(name = "idx_svc_item_list", columnList = "site_id, status, online_flag, sort_no"),
+ @Index(name = "idx_svc_item_obj", columnList = "site_id, status, object_key"),
+ @Index(name = "idx_svc_item_cat", columnList = "site_id, status, category_key"),
+ @Index(name = "idx_svc_item_dept", columnList = "site_id, status, dept_group_id")})
+public class CmsServiceItem extends BaseEntity {
+
+ /** 所属站点（隔离/查询维度） */
+ @Column(name = "site_id", nullable = false)
+ private Integer siteId;
+
+ /** 事项编码，站内唯一；跨服务键的一半（另一半是 siteCode） */
+ @Column(name = "item_code", nullable = false, length = 64)
+ private String itemCode;
+
+ /** 事项名称 */
+ @Column(name = "title", nullable = false, length = 200)
+ private String title;
+
+ /** 一句话简介（列表卡片副标题、快照摘要） */
+ @Column(name = "summary", length = 500)
+ private String summary;
+
+ /** 服务对象，指向 cms_service_dict(dict_type=object) 的 dict_key */
+ @Column(name = "object_key", length = 64)
+ private String objectKey;
+
+ /** 事项类别，指向 cms_service_dict(dict_type=category) 的 dict_key */
+ @Column(name = "category_key", length = 64)
+ private String categoryKey;
+
+ /** 服务部门 = UserBase 组树节点 id 快照（不建字典表） */
+ @Column(name = "dept_group_id")
+ private Integer deptGroupId;
+
+ /** 部门名快照（列表/指南免跨服务查名；改名不自动同步） */
+ @Column(name = "dept_name", length = 128)
+ private String deptName;
+
+ /** 办理方式：1 线上 / 2 线下 / 3 线上线下（HandleModeEnum） */
+ @Column(name = "handle_mode", nullable = false)
+ private Integer handleMode = 1;
+
+ /** 是否可在线办理：1 是 / 0 否（"在线办理"筛选维度，与 handle_mode 允许不一致） */
+ @Column(name = "online_flag", nullable = false)
+ private Integer onlineFlag = 1;
+
+ /** 办理地点 */
+ @Column(name = "handle_place", length = 200)
+ private String handlePlace;
+
+ /** 办理时限（文本，如"3 个工作日"；一期不做工作日历） */
+ @Column(name = "handle_time_limit", length = 64)
+ private String handleTimeLimit;
+
+ /** 承诺时限（文本） */
+ @Column(name = "promise_time_limit", length = 64)
+ private String promiseTimeLimit;
+
+ /** 咨询电话 */
+ @Column(name = "contact_phone", length = 64)
+ private String contactPhone;
+
+ /** 监督投诉电话 */
+ @Column(name = "supervise_phone", length = 64)
+ private String supervisePhone;
+
+ /** 办理流程（保存时 jsoup 白名单清洗，同 article.content 口径） */
+ @Column(name = "process_html", columnDefinition = "LONGTEXT")
+ private String processHtml;
+
+ /** 所需材料（同上） */
+ @Column(name = "material_html", columnDefinition = "LONGTEXT")
+ private String materialHtml;
+
+ /** 注意事项（同上） */
+ @Column(name = "notice_html", columnDefinition = "LONGTEXT")
+ private String noticeHtml;
+
+ /** 关联 CMS 栏目：常见问题（逻辑外键 → cms_category.id） */
+ @Column(name = "faq_category_id")
+ private Integer faqCategoryId;
+
+ /** 关联 CMS 栏目：公告信息 */
+ @Column(name = "notice_category_id")
+ private Integer noticeCategoryId;
+
+ /** 关联 CMS 栏目：文件规定 */
+ @Column(name = "rule_category_id")
+ private Integer ruleCategoryId;
+
+ /** 事项图标/封面（存上传相对路径，渲染走 url.upload(...)） */
+ @Column(name = "cover_image", length = 500)
+ private String coverImage;
+
+ /** 管理端自定义排序（列表默认排序第一优先级，升序） */
+ @Column(name = "sort_no", nullable = false)
+ private Integer sortNo = 0;
+
+ /** 状态：0 草稿 / 1 已发布 / 2 已下架（ServiceItemStatusEnum） */
+ @Column(name = "status", nullable = false)
+ private Integer status = 0;
+
+ /** 发布时间 */
+ @Column(name = "publish_time")
+ private LocalDateTime publishTime;
+
+ /** 下架时间 */
+ @Column(name = "offline_time")
+ private LocalDateTime offlineTime;
+
+ /** 指南页浏览量（异步累加，不承诺精确） */
+ @Column(name = "view_count", nullable = false)
+ private Integer viewCount = 0;
+
+ /** 扩展字段 JSON（一期仅 apply_url：http(s) 外链，空则不渲染"我要办理"） */
+ @Column(name = "ext_json", columnDefinition = "JSON")
+ private String extJson;
+}
diff --git a/src/main/java/com/yunhai/cms/svcitem/enums/HandleModeEnum.java b/src/main/java/com/yunhai/cms/svcitem/enums/HandleModeEnum.java
new file mode 100644
index 0000000..ee14545
--- /dev/null
+++ b/src/main/java/com/yunhai/cms/svcitem/enums/HandleModeEnum.java
@@ -0,0 +1,37 @@
+package com.yunhai.cms.svcitem.enums;
+
+/**
+ * 办理方式（事项库详细设计 §2.4）。
+ * 与 online_flag 语义不同、允许不一致：如「线上线下」但本期未开通在线入口时 online_flag=0。
+ */
+public enum HandleModeEnum {
+
+ /** 线上办理 */
+ ONLINE(1),
+ /** 线下办理 */
+ OFFLINE(2),
+ /** 线上线下均可 */
+ BOTH(3);
+
+ private final int code;
+
+ HandleModeEnum(int code) {
+ this.code = code;
+ }
+
+ public int getCode() {
+ return code;
+ }
+
+ public static boolean isValid(Integer code) {
+ if (code == null) {
+ return false;
+ }
+ for (HandleModeEnum e : values()) {
+ if (e.code == code) {
+ return true;
+ }
+ }
+ return false;
+ }
+}
diff --git a/src/main/java/com/yunhai/cms/svcitem/enums/ServiceDictTypeEnum.java b/src/main/java/com/yunhai/cms/svcitem/enums/ServiceDictTypeEnum.java
new file mode 100644
index 0000000..639c4b5
--- /dev/null
+++ b/src/main/java/com/yunhai/cms/svcitem/enums/ServiceDictTypeEnum.java
@@ -0,0 +1,35 @@
+package com.yunhai.cms.svcitem.enums;
+
+/**
+ * 事项字典类型（一期两类，值域由本枚举收口，事项库详细设计 §2.2）：
+ * object=服务对象（个人/法人…）、category=事项类别（教务/后勤…）。
+ */
+public enum ServiceDictTypeEnum {
+
+ /** 服务对象 */
+ OBJECT("object"),
+ /** 事项类别 */
+ CATEGORY("category");
+
+ private final String key;
+
+ ServiceDictTypeEnum(String key) {
+ this.key = key;
+ }
+
+ public String getKey() {
+ return key;
+ }
+
+ /** 非法值（含 null）返回 null，由调用方决定报错口径 */
+ public static ServiceDictTypeEnum byKey(String key) {
+ if (key != null) {
+ for (ServiceDictTypeEnum e : values()) {
+ if (e.key.equals(key)) {
+ return e;
+ }
+ }
+ }
+ return null;
+ }
+}
diff --git a/src/main/java/com/yunhai/cms/svcitem/enums/ServiceItemStatusEnum.java b/src/main/java/com/yunhai/cms/svcitem/enums/ServiceItemStatusEnum.java
new file mode 100644
index 0000000..a23ed82
--- /dev/null
+++ b/src/main/java/com/yunhai/cms/svcitem/enums/ServiceItemStatusEnum.java
@@ -0,0 +1,37 @@
+package com.yunhai.cms.svcitem.enums;
+
+/**
+ * 事项状态（对齐 ArticleStatusEnum 三态，事项库详细设计 §2.4）：
+ * 草稿→发布→下架，重新编辑可从已发布/已下架回到草稿语义（保存即修改，状态不自动迁移）。
+ * 门户可见性：仅已发布。
+ */
+public enum ServiceItemStatusEnum {
+
+ /** 草稿 */
+ DRAFT(0),
+ /** 已发布 */
+ PUBLISHED(1),
+ /** 已下架 */
+ OFFLINE(2);
+
+ private final int code;
+
+ ServiceItemStatusEnum(int code) {
+ this.code = code;
+ }
+
+ public int getCode() {
+ return code;
+ }
+
+ public static ServiceItemStatusEnum byCode(Integer code) {
+ if (code != null) {
+ for (ServiceItemStatusEnum e : values()) {
+ if (e.code == code) {
+ return e;
+ }
+ }
+ }
+ return DRAFT;
+ }
+}
diff --git a/src/main/java/com/yunhai/cms/svcitem/event/ServiceItemChangedEvent.java b/src/main/java/com/yunhai/cms/svcitem/event/ServiceItemChangedEvent.java
new file mode 100644
index 0000000..c4a119e
--- /dev/null
+++ b/src/main/java/com/yunhai/cms/svcitem/event/ServiceItemChangedEvent.java
@@ -0,0 +1,36 @@
+package com.yunhai.cms.svcitem.event;
+
+/**
+ * 事项域变更事件（事项库详细设计 §3.6，照 SiteContentChangedEvent 形态）。
+ * 事务提交后由 PortalCacheEvictListener 失效 cms:svcItem 缓存：
+ * scope=item（事项自身增改发删排序）→ itemId 非空 evict 指南页模型 + evict filters:{siteId}；
+ * scope=dict/dept（字典改名停用、部门名同步）→ 影响所有指南页的展示名快照 → 整缓存 clear。
+ * 业务代码禁止直接 evict 缓存，一律发事件。
+ */
+public class ServiceItemChangedEvent {
+
+ private final Integer siteId;
+
+ private final Integer itemId;
+
+ /** 变更来源说明：item=事项自身（精确失效）/ dict=字典 / dept=部门名同步（后两者整缓存失效） */
+ private final String scope;
+
+ public ServiceItemChangedEvent(Integer siteId, Integer itemId, String scope) {
+ this.siteId = siteId;
+ this.itemId = itemId;
+ this.scope = scope;
+ }
+
+ public Integer getSiteId() {
+ return siteId;
+ }
+
+ public Integer getItemId() {
+ return itemId;
+ }
+
+ public String getScope() {
+ return scope;
+ }
+}
diff --git a/src/main/java/com/yunhai/cms/svcitem/model/dto/IdSortItem.java b/src/main/java/com/yunhai/cms/svcitem/model/dto/IdSortItem.java
new file mode 100644
index 0000000..9767ca1
--- /dev/null
+++ b/src/main/java/com/yunhai/cms/svcitem/model/dto/IdSortItem.java
@@ -0,0 +1,18 @@
+package com.yunhai.cms.svcitem.model.dto;
+
+import lombok.Data;
+
+import javax.validation.constraints.NotNull;
+
+/**
+ * 事项排序项（POST /api/svc/item/sort：按传入顺序落库 sortNo）。
+ */
+@Data
+public class IdSortItem {
+
+ @NotNull(message = "id 不得为空")
+ private Integer id;
+
+ @NotNull(message = "sortNo 不得为空")
+ private Integer sortNo;
+}
diff --git a/src/main/java/com/yunhai/cms/svcitem/model/dto/SvcDictSaveRequest.java b/src/main/java/com/yunhai/cms/svcitem/model/dto/SvcDictSaveRequest.java
new file mode 100644
index 0000000..1294fb6
--- /dev/null
+++ b/src/main/java/com/yunhai/cms/svcitem/model/dto/SvcDictSaveRequest.java
@@ -0,0 +1,41 @@
+package com.yunhai.cms.svcitem.model.dto;
+
+import lombok.Data;
+
+import javax.validation.constraints.NotBlank;
+import javax.validation.constraints.NotNull;
+import javax.validation.constraints.Pattern;
+import javax.validation.constraints.Size;
+
+/**
+ * 事项字典保存入参（事项库详细设计 §2.2/§3.3）。
+ * dict_key 为稳定键：编辑时若已被事项引用则不可修改（服务端校验），只能改名 dict_name。
+ */
+@Data
+public class SvcDictSaveRequest {
+
+ /** 修改时必填 */
+ private Integer id;
+
+ @NotNull(message = "siteId 不得为空")
+ private Integer siteId;
+
+ /** object=服务对象 / category=事项类别（ServiceDictTypeEnum 收口） */
+ @NotBlank(message = "字典类型不得为空")
+ private String dictType;
+
+ @NotBlank(message = "字典键不得为空")
+ @Pattern(regexp = "^[A-Za-z0-9_-]{1,64}$",
+ message = "字典键仅限字母/数字/下划线/中划线")
+ @Size(max = 64)
+ private String dictKey;
+
+ @NotBlank(message = "字典名称不得为空")
+ @Size(max = 128, message = "字典名称过长")
+ private String dictName;
+
+ private Integer sortNo;
+
+ /** 0 停用 / 1 启用（缺省 1；停用后不出现在筛选与选择器，存量引用仍可渲染） */
+ private Integer status;
+}
diff --git a/src/main/java/com/yunhai/cms/svcitem/model/dto/SvcItemSaveRequest.java b/src/main/java/com/yunhai/cms/svcitem/model/dto/SvcItemSaveRequest.java
new file mode 100644
index 0000000..36fd0a8
--- /dev/null
+++ b/src/main/java/com/yunhai/cms/svcitem/model/dto/SvcItemSaveRequest.java
@@ -0,0 +1,98 @@
+package com.yunhai.cms.svcitem.model.dto;
+
+import lombok.Data;
+
+import javax.validation.constraints.NotBlank;
+import javax.validation.constraints.NotNull;
+import javax.validation.constraints.Pattern;
+import javax.validation.constraints.Size;
+import java.util.List;
+
+/**
+ * 事项保存入参（事项库详细设计 §3.3）。富文本三字段服务端 jsoup 清洗；
+ * applyUrl 进 ext_json（渲染优先级见 PortalController.doGuide：手填 > svc_hall_base 生成 > 不渲染）。
+ */
+@Data
+public class SvcItemSaveRequest {
+
+ /** 修改时必填 */
+ private Integer id;
+
+ @NotNull(message = "siteId 不得为空")
+ private Integer siteId;
+
+ /** 事项编码：站内唯一，跨服务键的一半（URL 安全字符，进 svhall 发起页 URL） */
+ @NotBlank(message = "事项编码不得为空")
+ @Pattern(regexp = "^[A-Za-z0-9_-]{2,64}$",
+ message = "事项编码仅限字母/数字/下划线/中划线，2~64 位")
+ private String itemCode;
+
+ @NotBlank(message = "事项名称不得为空")
+ @Size(max = 200, message = "事项名称过长")
+ private String title;
+
+ @Size(max = 500, message = "简介过长")
+ private String summary;
+
+ /** 服务对象（cms_service_dict dict_type=object 的 dict_key，须为启用字典） */
+ @Size(max = 64)
+ private String objectKey;
+
+ /** 事项类别（dict_type=category 的 dict_key，须为启用字典） */
+ @Size(max = 64)
+ private String categoryKey;
+
+ /** 服务部门（UserBase 组树节点 id；服务端按组树校验并刷新部门名快照） */
+ private Integer deptGroupId;
+
+ /** 办理方式：1 线上 / 2 线下 / 3 线上线下（缺省 1；与 onlineFlag 允许不一致） */
+ private Integer handleMode;
+
+ /** 是否可在线办理：1/0（缺省 1；"在线办理"筛选维度） */
+ private Integer onlineFlag;
+
+ @Size(max = 200)
+ private String handlePlace;
+
+ @Size(max = 64)
+ private String handleTimeLimit;
+
+ @Size(max = 64)
+ private String promiseTimeLimit;
+
+ @Size(max = 64)
+ private String contactPhone;
+
+ @Size(max = 64)
+ private String supervisePhone;
+
+ /** 办理流程 HTML（服务端 jsoup 白名单清洗） */
+ private String processHtml;
+
+ /** 所需材料 HTML（同上） */
+ private String materialHtml;
+
+ /** 注意事项 HTML（同上） */
+ private String noticeHtml;
+
+ /** 关联栏目：常见问题（须属于本站点） */
+ private Integer faqCategoryId;
+
+ /** 关联栏目：公告信息 */
+ private Integer noticeCategoryId;
+
+ /** 关联栏目：文件规定 */
+ private Integer ruleCategoryId;
+
+ @Size(max = 500)
+ private String coverImage;
+
+ private Integer sortNo;
+
+ /** "我要办理"外链（写入 ext_json.apply_url；须 http(s)://，空=按站点 svc_hall_base 生成） */
+ @Size(max = 500)
+ private String applyUrl;
+
+ /** 指南页附件 id 列表（保存时按此列表精确重绑 ref_type=svc_item, ref_id=事项id；不在列表中的旧引用被解除） */
+ private List