@alanwang-merit/meritdata-platform-skill-package 1.0.0

package/skills/meritdata-platform-domain-model/references/anti-patterns.md

@@ -0,0 +1,538 @@
+# 反模式 vs 正模式（domain-model）
+
+> **本文件与 rules/code-dev-rules.md §八.2 一一对应**。每条铁律给出：❌ 反模式 → ✅ 正模式 → 根因 → 真实案例。
+>
+> **使用方法**：新二开业务建模时按目录逐项检查；聚合根设计后逐项打钩；CI 扫描时按 [validate-rules.md](validate-rules.md) 自动检测。
+
+---
+
+## 1. 二开业务表/字段必须小写蛇形（铁律 1）
+
+**铁律来源**：[rules §八.2](../../../../rules/code-dev-rules.md#82-业务建模规则domain-model) + §七
+
+### 1.1 表名大写/驼峰
+
+#### ❌ 反模式
+
+```sql
+-- 大写
+CREATE TABLE PurchaseOrder (
+    OrderNo VARCHAR(50),
+    CreateBy BIGINT
+);
+
+-- 大驼峰
+CREATE TABLE Purchase_Order (
+    orderNo VARCHAR(50)
+);
+
+-- 沿用 PF_ 前缀
+CREATE TABLE PF_PURCHASE_ORDER (
+    order_no VARCHAR(50)
+);
+```
+
+#### ✅ 正模式
+
+```sql
+-- 小写蛇形 + t_ 前缀
+CREATE TABLE t_purchase_order (
+    id BIGINT PRIMARY KEY,
+    order_no VARCHAR(50) NOT NULL,
+    create_by BIGINT NOT NULL,
+    create_time DATETIME NOT NULL,
+    deleted BOOLEAN DEFAULT FALSE,
+    UNIQUE KEY uk_t_purchase_order_no (order_no, deleted)  -- 含 deleted 让软删除可重用编号
+);
+
+CREATE INDEX idx_t_purchase_order_create_by ON t_purchase_order(create_by);
+```
+
+### 1.2 字段名大写驼峰
+
+#### ❌ 反模式
+
+```sql
+CREATE TABLE t_purchase_order (
+    OrderNo VARCHAR(50),    -- 大驼峰
+    orderNo VARCHAR(50),    -- 小驼峰
+    CREATETIME DATETIME     -- 大写
+);
+```
+
+#### ✅ 正模式
+
+```sql
+CREATE TABLE t_purchase_order (
+    order_no VARCHAR(50),
+    create_time DATETIME
+);
+```
+
+### 1.3 实体类与表名解耦
+
+**实体类命名规则**（与表命名解耦）：
+
+| 类型 | 规则 | 示例 |
+|------|------|------|
+| 表名 | 小写蛇形 + t_ 前缀 | `t_purchase_order` |
+| 实体类 | 大驼峰（PascalCase） | `PurchaseOrder` |
+| 字段 | 驼峰 | `orderNo`、`createBy` |
+| 映射 | `@Column("order_no")` | 显式声明 |
+
+#### ❌ 反模式（驼峰实体无 @Column 映射）
+
+```java
+// 字段名 orderNo 与表字段 order_no 依赖 Hibernate 命名策略，迁移数据库时极易断裂
+@Entity
+@Table(name = "t_purchase_order")
+public class PurchaseOrder {
+    private String orderNo;  // ❌ 没声明 @Column
+    private Long createBy;
+}
+```
+
+#### ✅ 正模式（显式 @Column 映射）
+
+```java
+@Entity
+@Table(name = "t_purchase_order")
+public class PurchaseOrder {
+    @Column(name = "order_no")
+    private String orderNo;
+
+    @Column(name = "create_by")
+    private Long createBy;
+
+    @Column(name = "create_time")
+    private LocalDateTime createTime;
+}
+```
+
+### 1.4 历史/特殊主表例外
+
+**例外流程**（必须同时满足）：
+
+1. 显式声明例外开关（如 `@TableName(value = "LEGACY_ORDER", excludeProperty = {...})`）
+2. 注明"不可改名原因"（对接上游老系统 / 监管要求 / 数据迁移约束）
+3. 新业务列、关联表**不随主表例外放宽**——仍按 §1.1 走小写蛇形
+
+**反例**：因主表叫 `T_LEGACY_ORDER`，就给新加的 `T_LEGACY_ORDER_DETAIL` 也用大写 → **禁止**。
+
+### 根因
+
+- 不同数据库对大小写敏感性不同（PostgreSQL 区分、MySQL 不区分但查询要求一致）
+- 命名风格不统一导致跨库迁移失败
+- 实体类字段与表字段无显式映射，Hibernate 命名策略变更时静默失败
+
+### 真实踩坑案例
+
+- **2025-09**：某项目主表 `OrderInfo`（大驼峰），迁 PostgreSQL 时全部失败（PG 默认小写）
+- **2026-01**：某项目实体字段 `orderNo` 无 `@Column`，Hibernate 5 → 6 升级后映射静默失败，查询返回 null
+
+---
+
+## 2. 不得把人员/组织名称作为关联键（铁律 2）
+
+**铁律来源**：[rules §八.2](../../../../rules/code-dev-rules.md#82-业务建模规则domain-model)
+
+### 2.1 用姓名做 WHERE 关联
+
+#### ❌ 反模式
+
+```sql
+-- 用姓名做关联，姓名一变就查不到
+SELECT o.*
+FROM t_order o
+WHERE o.applicant_name = '张三'  -- 💥 改名/重名/调动后失效
+  AND o.dept_name = '采购部';
+```
+
+#### ✅ 正模式（用稳定 ID）
+
+```sql
+-- 用稳定 user_id / dept_id 关联
+SELECT o.*
+FROM t_order o
+WHERE o.applicant_user_id = '10001'  -- ✅ 稳定
+  AND o.dept_id = 'D001';
+```
+
+### 2.2 实体设计
+
+#### ❌ 反模式（用名称做关联键）
+
+```java
+@Entity
+@Table(name = "t_order")
+public class Order {
+    private String applicantName;  // ❌ 关联字段
+    private String deptName;       // ❌ 关联字段
+    // 缺 ID 字段
+}
+```
+
+#### ✅ 正模式（稳定 ID + 名称作快照）
+
+```java
+@Entity
+@Table(name = "t_order")
+public class Order {
+    @Column(name = "applicant_user_id")
+    private Long applicantUserId;  // ✅ 稳定 ID（关联用）
+
+    @Column(name = "applicant_name_snapshot")
+    private String applicantNameSnapshot;  // 📸 显示用快照（创建时锁定）
+
+    @Column(name = "dept_id")
+    private String deptId;  // ✅ 稳定 ID
+
+    @Column(name = "dept_name_snapshot")
+    private String deptNameSnapshot;  // 📸 显示用快照
+}
+```
+
+### 2.3 名称快照使用场景
+
+| 场景 | 用 ID | 用名称快照 |
+|------|------|----------|
+| WHERE / JOIN 查询 | ✅ | ❌ |
+| 列表显示 | ❌ | ✅ |
+| 历史记录展示（用户已删除）| ❌ | ✅ |
+| 业务规则判断（如"申请人=当前用户"）| ✅ | ❌ |
+
+### 根因
+
+- 人员/组织名称会变更（重名、调动、组织合并）
+- 数据库 JOIN 用名称无法走索引，性能差
+- 删除人员后历史订单显示成"用户已删除""
+
+---
+
+## 3. 跨服务禁止数据库外键（铁律 3）
+
+**铁律来源**：[rules §八.2](../../../../rules/code-dev-rules.md#82-业务建模规则domain-model)
+
+### 3.1 跨服务数据库外键
+
+#### ❌ 反模式
+
+```sql
+-- 二开服务 A 创建外键指向二开服务 B 的表
+ALTER TABLE service_a.t_order
+ADD CONSTRAINT fk_order_user
+FOREIGN KEY (user_id) REFERENCES service_b.t_user(id);  -- 💥 跨服务外键
+```
+
+#### ✅ 正模式（应用层 ID 引用 + 应用服务编排）
+
+```sql
+-- service_a.t_order 只存 user_id，不建外键
+CREATE TABLE service_a.t_order (
+    id BIGINT PRIMARY KEY,
+    user_id BIGINT NOT NULL,  -- 仅 ID 引用，不建 FOREIGN KEY
+    INDEX idx_t_order_user_id (user_id)
+);
+```
+
+```java
+// service_a 应用层：通过 Feign 装配 user 信息
+@Service
+public class OrderService {
+    private final OrderRepo orderRepo;
+    private final UserClient userClient;  // 跨服务调用
+
+    public OrderVO getOrder(Long orderId) {
+        Order order = orderRepo.findById(orderId).orElseThrow();
+        OrderVO vo = toVO(order);
+
+        // 应用层一致性：服务 B 的 user 删了，服务 A 不级联
+        try {
+            UserDTO user = userClient.getById(order.getUserId()).orElse(null);
+            vo.setUserName(user != null ? user.getName() : "用户已删除");
+        } catch (FeignException e) {
+            vo.setUserName("用户服务不可用");
+        }
+        return vo;
+    }
+}
+```
+
+### 3.2 跨服务事务
+
+#### ❌ 反模式（跨服务 @Transactional）
+
+```java
+// service_a 创建订单时直接调 service_b 的方法（在 service_a 的事务里）
+@Transactional
+public void createOrder(OrderDTO dto) {
+    orderRepo.save(toEntity(dto));
+
+    // 💥 跨服务调用在事务里，网络故障导致长事务
+    userClient.deductBalance(dto.getUserId(), dto.getAmount());
+    inventoryClient.reduceStock(dto.getProductId(), dto.getQuantity());
+}
+```
+
+#### ✅ 正模式（最终一致性 / Saga / 消息）
+
+```java
+// 方案 1：本地事务 + 异步消息
+@Transactional
+public void createOrder(OrderDTO dto) {
+    orderRepo.save(toEntity(dto));
+    // 本地事务只保证订单创建
+    outboxRepo.save(new OutboxEvent("ORDER_CREATED", dto));  // outbox 模式
+}
+
+// 单独的进程消费 outbox，调远程服务
+@EventListener
+public void onOrderCreated(OutboxEvent event) {
+    try {
+        userClient.deductBalance(event.getUserId(), event.getAmount());
+        outboxRepo.markDone(event.getId());
+    } catch (FeignException e) {
+        // 重试 / 补偿 / 人工介入
+    }
+}
+
+// 方案 2：TCC / Saga（复杂场景）
+// 见 meritdata-platform-integration 中的分布式事务章节
+```
+
+### 根因
+
+- **服务拆分要求数据自治**：每个服务拥有自己的数据
+- **跨服务外键导致级联删除/更新跨网络**：事务无法保证，数据库锁等待
+- **部署独立化失败**：服务 B 表结构变更，服务 A 必须同步
+- **跨服务事务违反 CAP**：网络分区时无法保证一致性
+
+### 真实踩坑案例
+
+- **2025-10**：服务 A、B 之间建外键，服务 B 表迁移时服务 A 数据库锁等待 2 小时
+- **2026-03**：服务 A 调服务 B 在同一事务里，网络抖动导致服务 A 接口 P99 达到 30 秒
+
+---
+
+## 4. 唯一性校验穿透软删除（铁律 4 — 与 code-spec 联动）
+
+**铁律来源**：[rules §八.2](../../../../rules/code-dev-rules.md#82-业务建模规则domain-model) + §八.3
+
+> **本铁律完整反模式案例见** [code-spec anti-patterns §1](../meritdata-platform-code-spec/references/anti-patterns.md#1-软删除实体反模式核心反模式)。
+
+本节只补充建模层的关键决策。
+
+### 4.1 唯一约束设计
+
+#### ❌ 反模式（不含 deleted）
+
+```sql
+CREATE TABLE t_project (
+    id BIGINT PRIMARY KEY,
+    project_no VARCHAR(50) NOT NULL,
+    deleted BOOLEAN DEFAULT FALSE,
+    UNIQUE KEY uk_t_project_no (project_no)  -- 💥 软删除的 project_no 也占用唯一
+);
+```
+
+#### ✅ 正模式（含 deleted）
+
+```sql
+CREATE TABLE t_project (
+    id BIGINT PRIMARY KEY,
+    project_no VARCHAR(50) NOT NULL,
+    deleted BOOLEAN DEFAULT FALSE,
+    UNIQUE KEY uk_t_project_no (project_no, deleted)  -- ✅ 软删除+硬删除可重用编号
+);
+```
+
+### 4.2 实体设计配合
+
+```java
+@Entity
+@Table(name = "t_project")
+@SQLDelete(sql = "UPDATE t_project SET deleted = true WHERE id = ?")
+@Where(clause = "deleted = false")
+public class Project {
+    @Id
+    private Long id;
+    private String projectNo;
+    private Boolean deleted;
+
+    // 业务查询（受 @Where 过滤）
+    public static final String Q_FIND_BY_NO =
+        "SELECT * FROM t_project WHERE project_no = :no";
+
+    // 全量查询（穿透 @Where）
+    public static final String Q_FIND_NO_INCLUDING_DELETED =
+        "SELECT * FROM t_project WHERE project_no = :no AND deleted = :deleted";
+}
+
+@Repository
+public interface ProjectRepo extends JpaRepository<Project, Long> {
+    // ❌ 错：JPQL 受 @Where 过滤
+    @Query("SELECT p FROM Project p WHERE p.projectNo = :no")
+    Optional<Project> findByProjectNo(@Param("no") String no);
+
+    // ✅ 对：nativeQuery 穿透
+    @Query(value = "SELECT * FROM t_project WHERE project_no = :no AND deleted = :deleted",
+           nativeQuery = true)
+    Optional<Project> findProjectNoIncludingDeleted(
+        @Param("no") String no,
+        @Param("deleted") boolean deleted);
+}
+```
+
+### 4.3 业务查询 / 全量查询成对出现
+
+**命名约定**（来自 code-spec §1.3）：
+
+| 业务查询（受 @Where 过滤）| 全量查询（穿透 @Where）|
+|--------------------------|------------------------|
+| `findByXxxNo` | `findXxxNoIncludingDeleted` |
+| `findAllXxxStartingWith` | `findAllXxxStartingWithIncludingDeleted` |
+
+**禁止**：
+- ❌ 唯一性校验用 `findByXxx`
+- ❌ 业务展示用 `*IncludingDeleted`
+
+### 根因
+
+DB 唯一约束 `uk_xxx_no` 包含所有记录，业务查询看不到软删除 → 校验放行 → INSERT 500。
+
+**完整根因 + 真实踩坑案例**（2026-06-12 Project + Customer）见 [code-spec anti-patterns §1](../meritdata-platform-code-spec/references/anti-patterns.md#1-软删除实体反模式核心反模式)。
+
+---
+
+## 5. 平台语义字段映射（与铁律配套）
+
+### 5.1 人员/申请人/经办人
+
+#### ❌ 反模式（用姓名做关联）
+
+```java
+@Entity
+@Table(name = "t_order")
+public class Order {
+    private String applicantName;  // 💥 名称做关联
+    private String applicantCode;  // 💥 工号做关联（工号会变）
+}
+```
+
+#### ✅ 正模式
+
+```java
+@Entity
+@Table(name = "t_order")
+public class Order {
+    @Column(name = "applicant_user_id")
+    private Long applicantUserId;  // ✅ 稳定 user_id
+
+    @Column(name = "applicant_name_snapshot")
+    private String applicantNameSnapshot;  // 📸 显示用
+}
+```
+
+**服务层**：用 `meritdata-platform-integration` 的 User Feign 装配。
+
+### 5.2 部门/组织
+
+```java
+@Column(name = "dept_id")
+private String deptId;  // 部门稳定 ID（如 "D001"）
+
+@Column(name = "dept_name_snapshot")
+private String deptNameSnapshot;  // 快照
+```
+
+### 5.3 字典/状态
+
+```java
+@Column(name = "status")
+private String status;  // 字典 code 而非中文名
+
+// 字典翻译由前端用 meritdata-platform-dict-api 完成
+```
+
+### 5.4 附件
+
+#### ❌ 反模式（二进制存主表）
+
+```java
+@Column(name = "attachment")
+private byte[] attachment;  // 💥 主表膨胀，备份慢
+```
+
+#### ✅ 正模式（业务附件关联表）
+
+```sql
+CREATE TABLE t_order_attachment (
+    id BIGINT PRIMARY KEY,
+    order_id BIGINT NOT NULL,
+    file_id VARCHAR(100) NOT NULL,  -- 平台文件 ID
+    file_name VARCHAR(255),
+    upload_time DATETIME,
+    INDEX idx_t_order_attachment_order_id (order_id)
+);
+```
+
+上传/下载由 `meritdata-platform-impexp` 处理。
+
+### 5.5 审批状态
+
+#### ❌ 反模式（业务状态与流程实例 ID 混用）
+
+```java
+@Column(name = "status")
+private String status;  // 同时存业务状态和流程状态码，含义混乱
+```
+
+#### ✅ 正模式（业务状态 + 流程实例 ID 分离）
+
+```java
+@Column(name = "biz_status")
+private String bizStatus;  // 业务状态（DRAFT / SUBMITTED / APPROVED / REJECTED）
+
+@Column(name = "process_instance_id")
+private String processInstanceId;  // 流程实例 ID，独立字段
+```
+
+启动流程 / 推进节点由 `meritdata-platform-bpm` 处理。
+
+---
+
+## 6. 关系模式决策表
+
+| 模式 | 适用场景 | 关键决策 | 反模式 |
+|------|---------|---------|--------|
+| 一对多（主子表）| 主表 + N 个子项 | 子表 owner = 主表；删除默认级联；子表 `parent_id` + 索引 | 主子表都用同一状态字段 |
+| 多对多 | 双 owner 关系（角色-用户）| 必须显式中间表 + 两个外键 + 联合索引 | 用 JSON 数组存关联 |
+| 树形 | 组织 / 菜单 / 分类 | `parent_id` + 路径枚举/闭包表/物化路径，按查询模式选 | 递归查询（深度大时性能差）|
+| 跨服务 | 二开 A → 二开 B | 禁外键，仅 ID 引用 + Feign | 跨服务数据库外键 |
+| 跨平台 | 二开 → cloud 平台表 | 禁外键，data-boundary 装配 | `@TableName("PF_*")` |
+
+---
+
+## 7. 速查表
+
+| 铁律 | 反模式关键特征 | 正模式关键特征 |
+|------|--------------|--------------|
+| 表名小写蛇形 | `CREATE TABLE OrderInfo` | `CREATE TABLE t_order_info` |
+| 字段小写蛇形 | `OrderNo`, `CreateTime` | `order_no`, `create_time` |
+| 实体显式映射 | 字段无 `@Column` | `@Column("order_no") String orderNo;` |
+| 用 ID 关联 | `WHERE applicant_name = ?` | `WHERE applicant_user_id = ?` |
+| 名称做快照 | 缺快照字段 | `applicant_name_snapshot` |
+| 跨服务禁外键 | `FOREIGN KEY ... REFERENCES other_service.t_*` | 仅 ID 引用 + Feign |
+| 业务状态分离 | 业务状态 + 流程状态同一字段 | `biz_status` + `process_instance_id` 分离 |
+| 附件关联表 | 主表存 byte[] | `t_xxx_attachment` 关联表 |
+| 软删除唯一约束 | `UNIQUE KEY (xxx_no)` | `UNIQUE KEY (xxx_no, deleted)` |
+| 软删除查询穿透 | `findByXxxNo`（JPQL）| `findXxxNoIncludingDeleted(nativeQuery)` |
+
+---
+
+## 8. 关联阅读
+
+- [validate-rules.md](validate-rules.md) — CI 自动化校验命令
+- [code-spec anti-patterns §1](../meritdata-platform-code-spec/references/anti-patterns.md#1-软删除实体反模式核心反模式) — 软删除完整反模式
+- [data-boundary anti-patterns](../meritdata-platform-data-boundary/references/anti-patterns.md) — 数据访问边界反模式
+- [rules/code-dev-rules.md §八.2](../../../../rules/code-dev-rules.md#82-业务建模规则domain-model) — 铁律摘要

package/skills/meritdata-platform-domain-model/references/relationship-patterns.md

@@ -0,0 +1,112 @@
+# 关系模式选择（relationship-patterns）
+
+> **v2.6.1 补建**：v2.5.0 拆分时遗漏创建。
+> 配套主文档：[anti-patterns.md](anti-patterns.md)
+
+## 一、一对多（1:N）
+
+**场景**：父表 + 多个子记录（如订单 + 订单明细）
+
+```sql
+CREATE TABLE t_order (
+  id BIGINT PRIMARY KEY,
+  order_no VARCHAR(64) UNIQUE
+);
+
+CREATE TABLE t_order_item (
+  id BIGINT PRIMARY KEY,
+  order_id BIGINT NOT NULL,
+  sku_id BIGINT NOT NULL,
+  qty INT
+);
+CREATE INDEX idx_t_order_item_order_id ON t_order_item(order_id);
+```
+
+**Java 实体**：
+
+```java
+// 父
+@Entity @TableName("t_order")
+public class Order {
+  @TableId
+  private Long id;
+  @TableField("order_no")
+  private String orderNo;
+  @TableField(exist = false)
+  private List<OrderItem> items;  // 非数据库字段，运行时装配
+}
+
+// 子
+@Entity @TableName("t_order_item")
+public class OrderItem {
+  @TableId
+  private Long id;
+  @TableField("order_id")
+  private Long orderId;
+}
+```
+
+## 二、多对多（M:N）
+
+**场景**：用户-角色、用户-资源等关联
+
+**模式 A：中间表（推荐）**
+
+```sql
+CREATE TABLE t_user_role (
+  user_id BIGINT NOT NULL,
+  role_id BIGINT NOT NULL,
+  create_time DATETIME,
+  PRIMARY KEY (user_id, role_id)
+);
+```
+
+**模式 B：JSON 字段（轻量场景）**
+
+```sql
+CREATE TABLE t_user (
+  id BIGINT PRIMARY KEY,
+  role_ids JSON  -- 简单场景
+);
+```
+
+模式 A 可独立查询"拥有某角色的所有用户"，模式 B 查询效率低但简单。
+
+## 三、树形结构（同服务内）
+
+| 方案 | 适用 | 优点 | 缺点 |
+|------|------|------|------|
+| `parent_id` 自关联 | < 1000 节点 | 简单 | 递归查询 |
+| `path` 路径枚举 | 中型 | 查询子树高效 | 移动子树需更新所有子节点 |
+| `lft/rgt` 嵌套集 | 频繁查询子树 | 查询 O(1) | 增删改复杂 |
+| 闭包表 | 复杂权限 | 查询最灵活 | 表大 |
+
+**推荐**：组织/部门等 < 5000 节点 → `parent_id` 自关联 + N+1 预加载。
+
+## 四、跨服务关联（应用层编排）
+
+**禁止**：跨服务数据库外键（违反铁律 §2.2）
+
+**正确模式**：
+
+```java
+// 二开服务 A
+@Entity @TableName("t_order_a")
+public class OrderA {
+  @TableField("user_id")
+  private Long userId;  // 只存 ID，不加外键
+}
+
+// 装配时 Feign 批量拉 UserDTO
+List<UserDTO> users = userClient.listByIds(orderList.stream()
+    .map(OrderA::getUserId).distinct().collect(Collectors.toList()));
+Map<Long, UserDTO> userMap = users.stream()
+    .collect(Collectors.toMap(UserDTO::getId, u -> u));
+```
+
+## 五、参考
+
+- [anti-patterns.md](anti-patterns.md) — 反模式 + 正模式
+- [review-checklist.md](review-checklist.md) — review 时如何检查
+- [validate-rules.md](validate-rules.md) — CI 检测外键
+- [rules/meritdata-platform-domain-model-rules.md §2](../../../../rules/meritdata-platform-domain-model-rules.md) — 关联键硬规则

package/skills/meritdata-platform-domain-model/references/review-checklist.md

@@ -0,0 +1,39 @@
+# Review Checklist（review-checklist）
+
+> **v2.6.1 补建**：v2.5.0 拆分时遗漏创建。
+> 配套主文档：[anti-patterns.md](anti-patterns.md)
+
+## 一、表命名（必查）
+
+- [ ] 表名小写蛇形 + `t_` 前缀（如 `t_purchase_order`）
+- [ ] 字段名小写蛇形（`order_no`、`create_by`）
+- [ ] 索引名规范（`idx_t_xxx_col`、`uk_t_xxx_no`）
+- [ ] 不沿用 `PF_` 前缀（二开库）
+
+## 二、关联键（必查）
+
+- [ ] 不用人名/部门名做关联键
+- [ ] 跨服务**无数据库外键**
+- [ ] 平台人员/组织/字典字段用 `_user_id` / `_org_id` / `_type`
+- [ ] 名称字段冗余快照（`*_name_snapshot`）
+
+## 三、平台语义（必查）
+
+- [ ] 人员字段用 `meritdata-platform-ui-components` 人员弹框
+- [ ] 组织/部门用部门树组件
+- [ ] 字典字段用 `ILookupService` + 字典选择器
+- [ ] 附件用业务附件关联表（不存二进制到主表）
+- [ ] 审批状态独立字段 + 流程实例 ID 单独存储
+
+## 四、软删除（必查）
+
+- [ ] 唯一性校验走 `findXxxIncludingDeleted`（nativeQuery）
+- [ ] 编号生成器查已用编号走 `findAllNosStartingWithIncludingDeleted`
+- [ ] 业务查询和全量查询成对出现
+
+## 五、参考
+
+- [anti-patterns.md](anti-patterns.md) — 反模式对照
+- [relationship-patterns.md](relationship-patterns.md) — 关系模式
+- [validate-rules.md](validate-rules.md) — CI 检测脚本
+- [rules/meritdata-platform-domain-model-rules.md](../../../../rules/meritdata-platform-domain-model-rules.md) — 硬规则