# 宗教管理系统 DEMO 开发技术说明文档（1–21 章完整版）

> Version: 1.0  
> Author: ChatGPT  
> Purpose: 作为 Codex / Cursor / VSCode / 开发团队统一技术规范与唯一事实来源（Single Source of Truth）  
> Framework: RuoYi-SpringBoot (Thymeleaf)  
> Backend: Java 8 / Spring Boot 2.2.x / MyBatis / Druid  
> Frontend: Thymeleaf + Bootstrap 3.3.7  
> Database: MySQL 5.7+  
> Date: 2025-01  

---

# 第 1 章：系统概述

本 DEMO 系统为《西安市民宗委宗教管理信息系统建设项目》立项评审所需的演示版本。  
目标是在现场评审中，通过 **10 分钟内的真实系统操作演示**，向评审专家展示系统在以下方面的能力：

- 宗教活动场所信息管理（场所新增、修改、校验、日志）  
- 教职人员信息管理（批量导入、批量维护、状态流转）  
- 数据质量控制（格式校验、冲突识别、冲突处理）  
- 多级管理与区县校核流程（区县工作台、按教别筛选、批量校核）  
- 审计与追责能力（操作留痕、字段级差异记录）  
- 完整的登录与权限体系（管理员/区县用户角色分工）  

本 DEMO 不追求功能“大而全”，而是围绕评审要求的两个核心演示点，聚焦于：

- **“一套完整可用的业务闭环”**  
- **“相对规范的系统架构与代码结构”**  

系统架构采用 RuoYi-SpringBoot 单体框架，以降低搭建成本，加快 DEMO 开发效率，并便于今后升级为正式系统。

---

# 第 2 章：DEMO 范围（评审要求与覆盖关系）

## 2.1 评审项一：宗教信息录入与数据维护

**评审要求概要：**

1. 登录模拟管理账号，进入宗教活动场所管理模块；  
2. 新增清真寺场所信息，填写 18 个核心字段（名称、宗教类别、地址、面积等），系统自动校验必填项和数据格式；  
3. 演示信息修改功能：修改场所负责人信息；  
4. 系统自动记录修改前后的数据变化；  
5. 日志中需包含修改人、修改时间、修改内容等关键信息；  
6. 使用批量维护功能，选择该场所的 3 名人员，批量更新政治面貌为“群众”；  
7. 系统提供修改预览和二次确认；  
8. 执行后，所有相关记录同步更新，并记录批量操作日志。

**DEMO 实现范围：**

- 模块：场所管理、教职人员管理、审计日志  
- 页面：场所列表、场所表单、人员列表、批量维护弹框、审计日志列表/详情  
- 核心点：  
  - 场所新增（18 字段）  
  - 场所修改（字段差异分析 + 写审计日志）  
  - 批量修改政治面貌（预览 + 二次确认 + 日志）

---

## 2.2 评审项二：智能数据导入与多级审批工作流

**评审要求概要：**

1. 上传包含 500 条虚拟人员信息的 Excel；  
2. 系统自动进行智能校验，显示格式错误与数据冲突；  
3. 对冲突数据，系统提供三种处理方式：  
   - 覆盖现有数据；  
   - 保留现有数据；  
   - 手工处理（逐条比对与修改）；  
4. 进入区县校核工作台，对本区县有效记录进行批量和逐条校核；  
5. 按教别分类处理，校核通过后数据状态变更为“已校核待上报”。

**DEMO 实现范围：**

- 模块：导入管理、人员管理、区县校核工作台、审计日志  
- 页面：人员导入页面、冲突处理页面、校核工作台页面、日志页面  
- 核心点：  
  - Excel 导入并解析 500 条（正常 + 错误 + 冲突）  
  - 自动格式校验（必填、身份证、日期、枚举值等）  
  - 冲突识别（姓名 + 身份证号）  
  - 三种冲突处理模式  
  - 区县视角的校核与状态变更  
  - 审计日志记录导入与校核操作

---

# 第 3 章：角色与权限模型

系统采用 RuoYi 原生 RBAC（基于角色的访问控制）模型。  

## 3.1 角色定义

1. **管理员（Admin）**
   - 负责全局配置与演示操作；
   - 权限包含：
     - 场所管理：增删改查；
     - 人员管理：增删改查、批量维护；
     - 人员导入：上传、解析、冲突处理、提交；
     - 审计日志：查看；
     - 字典管理：可维护教别、政治面貌等；
     - 用户与角色管理：可选。

2. **区县用户（CountyUser）**
   - 对应区县民宗部门业务人员；
   - 权限包含：
     - 仅可查看本区县的人员数据；
     - 进入“区县校核工作台”；
     - 对本区县的待校核人员进行校核（批量/单条）；
     - 无权新增/修改场所；
     - 无权查看审计日志模块。

## 3.2 权限控制方式

- RuoYi 菜单绑定权限字符串，例如：
  - `religion:place:list`  
  - `religion:place:add`  
  - `religion:place:edit`  
  - `religion:person:list`  
  - `religion:person:import`  
  - `religion:check:list`  
  - `religion:audit:list` 等。
- Controller 方法上使用 `@RequiresPermissions("xxx")` 注解进行细粒度控制；
- 数据权限（区县）可以简单通过当前登录用户的 `deptId` 或扩展字段进行过滤，例如：  
  `WHERE county = #{user.county}`。

---

# 第 4 章：数据模型（ERD + SQL）

## 4.1 核心业务实体

1. **religion_place**：宗教活动场所信息表  
2. **religion_person**：宗教教职人员信息表  
3. **religion_import_batch**：导入批次表  
4. **religion_import_item**：导入项表（每一行 Excel 记录在解析阶段对应一个 item）  
5. **religion_audit_log**：业务操作审计日志表

## 4.2 表结构 SQL（含中文注释）

### 4.2.1 场所表 religion_place

```sql
CREATE TABLE religion_place (
  place_id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '场所ID',
  place_name VARCHAR(256) NOT NULL COMMENT '场所名称',
  religion_type VARCHAR(64) NOT NULL COMMENT '宗教类别',
  place_category VARCHAR(64) NOT NULL COMMENT '场所类别（寺/观/清真寺/教堂等）',
  county VARCHAR(128) NOT NULL COMMENT '所属区县',
  address VARCHAR(512) NOT NULL COMMENT '详细地址',
  charge_name VARCHAR(128) NOT NULL COMMENT '负责人姓名',
  charge_phone VARCHAR(32) NOT NULL COMMENT '负责人联系电话',
  place_area DECIMAL(10,2) COMMENT '场所占地面积（平方米）',
  building_area DECIMAL(10,2) COMMENT '建筑面积（平方米）',
  approve_organ VARCHAR(128) COMMENT '批准设立机关',
  approve_time DATE COMMENT '批准设立时间',
  reg_organ VARCHAR(128) COMMENT '登记机关',
  reg_no VARCHAR(64) COMMENT '登记证号',
  reg_time DATE COMMENT '登记时间',
  legal_qualified TINYINT DEFAULT 0 COMMENT '是否具有法人资格：0否1是',
  legal_time DATE COMMENT '法人资格取得时间',
  credit_code VARCHAR(32) COMMENT '统一社会信用代码',
  longitude DECIMAL(10,6) COMMENT '经度',
  latitude DECIMAL(10,6) COMMENT '纬度',
  create_by VARCHAR(64) COMMENT '创建人',
  create_time DATETIME COMMENT '创建时间',
  update_by VARCHAR(64) COMMENT '更新人',
  update_time DATETIME COMMENT '更新时间'
);
```

---

### 4.2.2 教职人员表 religion_person

```sql
CREATE TABLE religion_person (
  person_id BIGINT PRIMARY_KEY AUTO_INCREMENT COMMENT '人员ID',
  place_id BIGINT NOT NULL COMMENT '所属场所ID（外键，关联 religion_place.place_id）',
  name VARCHAR(128) NOT NULL COMMENT '姓名',
  religion_type VARCHAR(64) NOT NULL COMMENT '宗教类别',
  gender VARCHAR(8) COMMENT '性别',
  nation VARCHAR(64) COMMENT '民族（字典：sys_nation）',
  id_number VARCHAR(32) NOT NULL COMMENT '身份证号',
  birthday DATE COMMENT '出生日期',
  county VARCHAR(128) COMMENT '所属区县',
  address VARCHAR(512) COMMENT '家庭地址／联系地址',
  political_status VARCHAR(128) COMMENT '政治面貌',
  edu_national VARCHAR(128) COMMENT '国民教育学历',
  edu_religious VARCHAR(128) COMMENT '宗教学历',
  join_time DATE COMMENT '入教／出家时间',
  phone VARCHAR(32) COMMENT '联系电话',
  domicile VARCHAR(128) COMMENT '户籍所在地',
  native_place VARCHAR(128) COMMENT '籍贯',
  org_name VARCHAR(256) COMMENT '所属宫观名称（Excel 原始值，仅留档）',
  org_address VARCHAR(512) COMMENT '所属宫观地址（Excel 原始值，仅留档）',
  status VARCHAR(32) DEFAULT 'TO_CHECK' COMMENT '状态：TO_CHECK待校核/CHECKED已校核/REPORTED已上报',
  create_by VARCHAR(64) COMMENT '创建人',
  create_time DATETIME COMMENT '创建时间',
  update_by VARCHAR(64) COMMENT '更新人',
  update_time DATETIME COMMENT '更新时间',
  UNIQUE KEY uk_id_name (id_number, name),
  INDEX idx_place_id (place_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='教职人员表';
);
```

---

### 4.2.3 导入批次表 religion_import_batch

```sql
create table religion_import_batch
(
    batch_id          bigint auto_increment comment '批次ID'
        primary key,
    batch_no          varchar(64)  null comment '批次号（可用时间戳+随机数生成）',
    file_name         varchar(256) null comment '导入文件名',
    uploader          varchar(64)  null comment '上传人登录名',
    upload_time       datetime     null comment '上传时间',
    last_process_time datetime     null comment '最近一次处理时间',
    total_rows        int          null comment '总记录数',
    valid_rows        int          null comment '有效记录数',
    error_rows        int          null comment '格式错误记录数',
    conflict_rows     int          null comment '冲突记录数',
    imported_rows     int          null comment '最终成功导入记录数（包含新增和更新）',
    abandoned_rows    int          null comment '放弃导入记录数',
    status            varchar(32)  null comment '状态：PARSED已解析/PARTIAL部分处理/FINISHED已完成',
    extra             json         null comment '扩展字段（预留）'
);
```

---

### 4.2.4 导入项表 religion_import_item

```sql
create table religion_import_item
(
    item_id        bigint auto_increment comment '导入项ID'
        primary key,
    batch_id       bigint       null comment '批次ID，对应 religion_import_batch.batch_id',
    row_no         int          null comment 'Excel 行号（从1开始）',
    json_data      json         null comment '该行原始数据的 JSON 表示',
    error_msg      varchar(512) null comment '格式错误说明，为空表示无格式错误',
    conflict_flag  tinyint      null comment '是否为冲突记录：0否1是',
    status         varchar(32)  null comment '系统校验状态：NORMAL正常/ERROR格式错误/CONFLICT冲突',
    action         varchar(32)  null comment '用户处理决策：IMPORT/OVERWRITE/KEEP/ABANDON/MANUAL',
    action_by      varchar(64)  null comment '决策人登录名',
    action_time    datetime     null comment '决策时间',
    processed_flag tinyint      null comment '是否已完成处理：0否1是',
    create_time    datetime     null comment '记录创建时间'
);

create index idx_batch
    on religion_import_item (batch_id);
```

---

### 4.2.5 审计日志表 religion_audit_log

```sql
CREATE TABLE religion_audit_log (
  log_id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '日志ID',
  user_id VARCHAR(64) COMMENT '操作用户ID',
  user_name VARCHAR(128) COMMENT '操作用户姓名',
  op_type VARCHAR(64) COMMENT '操作类型（ADD_PLACE/UPDATE_PLACE/BATCH_UPDATE_PERSON/IMPORT_PERSON/CHECK_PERSON等）',
  resource_type VARCHAR(64) COMMENT '资源类型 place/person/import',
  resource_id VARCHAR(64) COMMENT '资源ID（如 place_id/person_id/batch_id）',
  op_detail JSON COMMENT '操作详情（字段差异JSON或附加说明）',
  op_time DATETIME COMMENT '操作时间',
  ip VARCHAR(64) COMMENT '操作IP地址',
  extra JSON COMMENT '扩展字段（可记录请求参数快照等）'
);
```

---

# 第 5 章：字段字典（Field Dictionary）

用于：

- 表单中的下拉选项；  
- Excel 导入时的枚举校验；  
- 系统数据一致性控制。

## 5.1 宗教类别（religion_type）

- 佛教  
- 道教  
- 伊斯兰教  
- 基督教  
- 天主教  

## 5.2 政治面貌（political_status）

- 群众  
- 中共党员  
- 民革党员  
- 民盟盟员  
- 其它民主党派  

## 5.3 国民教育学历（edu_national）

- 小学  
- 初中  
- 高中  
- 中专  
- 大专  
- 本科  
- 研究生  

## 5.4 宗教学历（edu_religious）

- 无  
- 经学院  
- 宗教院校本科  
- 宗教院校研究生  

## 5.5 人员状态（person.status）

- TO_CHECK：待区县校核  
- CHECKED：已区县校核  
- REPORTED：已上报（本 DEMO 中仅作为预留状态，不实现上报流程）

## 5.6 导入批次状态（batch.status）

- PARSED：文件已解析，等待冲突处理与导入；  
- PARTIAL：部分冲突已通过手工处理；  
- FINISHED：导入完全完成。  

---

# 第 6 章：目录结构规范（RuoYi 标准）

以 RuoYi-SpringBoot 标准单体工程结构为基础，在 `ruoyi-admin` 模块中新增业务包。

```text
ruoyi-admin
 └── src/main/java/com/ruoyi/project/religion
      ├── place
      │    ├── controller    # ReligionPlaceController
      │    ├── domain        # ReligionPlace 实体类
      │    ├── service       # ReligionPlaceService / impl
      │    ├── mapper        # ReligionPlaceMapper + XML
      │    └── mapper/xml    # MyBatis XML
      ├── person
      │    ├── controller    # ReligionPersonController
      │    ├── domain        # ReligionPerson
      │    ├── service
      │    ├── mapper
      │    └── mapper/xml
      ├── import
      │    ├── controller    # ReligionImportController
      │    ├── service
      │    ├── mapper        # 如需要，可存 batch/item 等
      │    └── mapper/xml
      └── audit
           ├── controller    # ReligionAuditController
           ├── domain        # ReligionAuditLog
           ├── service
           ├── mapper
           └── mapper/xml
```

前端 Thymeleaf 模板位于：

```text
ruoyi-admin/src/main/resources/templates/religion
 ├── place
 │    ├── place_list.html
 │    └── place_form.html
 ├── person
 │    ├── person_list.html
 │    ├── person_import.html
 │    └── person_conflict.html
 ├── check
 │    └── check_workbench.html
 └── audit
      └── audit_list.html
```

---

# 第 7 章：业务流程说明

## 7.1 场所新增流程

1. 管理员登录系统；  
2. 进入“场所管理”菜单，点击“新增场所”；  
3. 打开 `place_form.html`，填写 18 个字段；  
4. 前端进行必填与基本格式校验（如手机号、面积数字等）；  
5. 点击“保存”；  
6. 后端进行二次校验（避免绕过前端）；  
7. 成功保存 `religion_place`；  
8. 使用 `ReligionAuditLogService.logCreate(...)` 写一条新增日志；  
9. 前端提示“保存成功”，返回列表页。

## 7.2 场所修改流程

1. 在“场所列表”中选中某条记录，点击“编辑”；  
2. 进入 `place_form.html`，展示原有字段；  
3. 用户修改负责人姓名或电话等信息；  
4. 提交后，Service 层获取旧记录 + 新记录；  
5. 计算字段差异（例如通过反射比对或手动比对重要字段）；  
6. 构造 `op_detail` JSON，如：  
   ```json
   {
     "charge_name": ["张三", "李四"],
     "charge_phone": ["13800000000", "13900000000"]
   }
   ```  
7. 写入 `religion_audit_log`；  
8. 返回成功。

## 7.3 批量修改政治面貌流程

1. 在“人员列表”选中 3 个教职人员；  
2. 点击“批量维护” → 弹出批量修改对话框；  
3. 选择“政治面貌”字段，新值选择为“群众”；  
4. 点击“预览”，系统展示：  
   - 每个人员原政治面貌 → 新政治面貌；  
5. 用户确认后点击“执行”；  
6. Service 执行批量更新；  
7. 写审计日志：记录操作人、时间、受影响人数、字段名及新值；  
8. 返回成功并刷新列表。

## 7.4 人员导入流程

1. 管理员进入“人员导入”页面 `person_import.html`；  
2. 顶部选择“所属场所”；  
3. 选择导入文件（500 条 Excel）；  
4. 点击“上传并解析”；  
5. 后端：
   - 创建 `religion_import_batch` 记录；
   - 解析 Excel，每行构造 JSON，判定格式错误；
   - 根据 `name + id_number` 与 `religion_person` 比较，标记冲突；
   - 将结果写入 `religion_import_item`；
   - 返回统计信息（总数 / 正常 / 错误 / 冲突）。  
6. 前端展示：
   - 错误数据表格（红色高亮）；  
   - 冲突数据表格；  
   - 三种处理模式选项（覆盖/保留/手工）；  
7. 用户根据需要：
   - 选择“直接覆盖”或“保留”；或  
   - 进入“手工处理”弹框逐行对比修改；  
8. 处理完成后点击“提交导入”；  
9. 后端：
   - 将有效数据写入 `religion_person`；
   - 冲突行根据模式分别处理；
   - 写审计日志；  
10. 更新批次状态为 FINISHED。

## 7.5 区县校核流程

1. 区县用户登录；  
2. 进入“区县校核工作台” `check_workbench.html`；  
3. 输入筛选条件（教别、姓名、身份证等）；  
4. 列表展示“待校核（TO_CHECK）”人员；  
5. 用户可以：
   - 勾选多条，点击“批量通过”；  
   - 或单击某条，打开详情后“通过校核”；  
6. 通过校核后：
   - `religion_person.status` 更新为 `CHECKED` 或 `REPORTED`（按需求）；  
   - 写审计日志记录校核人、时间、人数；  
7. 列表刷新后，不再展示已校核的数据。

---

# 第 8 章：模块功能描述

## 8.1 场所管理模块

- 场所列表：查询、分页、导出（可选）；  
- 场所新增：18字段录入；  
- 场所编辑：字段修改；  
- 场所详情：只读查看；  

## 8.2 教职人员管理模块

- 人员列表：按姓名、身份证、教别、场所、状态筛选；  
- 人员编辑：单条修改基本信息；  
- 批量维护：批量修改政治面貌（DEMO 重点）。

## 8.3 人员导入模块

- 上传 Excel；  
- 展示解析统计（总/错误/冲突）；  
- 展示格式错误列表；  
- 展示冲突列表；  
- 提供冲突处理模式选择与手工处理界面；  
- 最终导入。

## 8.4 区县校核工作台模块

- 按教别查看待校核人员；  
- 批量通过；  
- 单条通过；  

## 8.5 业务审计日志模块

- 日志列表：查询条件包括操作人、操作类型、资源类型、时间范围；  
- 日志详情：展示 `op_detail` JSON 格式化内容；  
- 支持导出（可选）。

---

# 第 9 章：后端接口设计（Controller 层）

以下为主要接口清单（以 RESTful 风格描述），实际实现时按 RuoYi 要求返回 AjaxResult。

## 9.1 场所管理 PlaceController

基路径：`/religion/place`

- `GET /list`  
  场所列表查询；支持分页与条件过滤。

- `POST /create`  
  新增场所；Body 为 JSON，包含 18 字段。

- `PUT /update/{placeId}`  
  修改场所；需比对旧值并写日志。

- `GET /detail/{placeId}`  
  获取场所详情。

## 9.2 教职人员管理 PersonController

基路径：`/religion/person`

- `GET /list`  
  人员列表查询。

- `PUT /update/{personId}`  
  修改人员信息。

- `POST /batch/updatePoliticalStatus`  
  批量修改政治面貌：
  ```json
  {
    "personIds": [1,2,3],
    "politicalStatus": "群众"
  }
  ```

## 9.3 导入 ImportController

基路径：`/religion/import`

- `POST /upload?placeId={placeId}`  
  上传 Excel 并解析；参数中 placeId 作为人员绑定场所。

- `GET /result/{batchId}`  
  获取解析结果，包括错误列表和冲突列表。

- `POST /resolveConflict`  
  对冲突数据进行处理：
  ```json
  {
    "batchId": 11,
    "mode": "override | keep | manual",
    "manualList": [
      { "itemId": 123, "finalData": { ... } }
    ]
  }
  ```

- `POST /commit/{batchId}`  
  提交导入：将解析完成的数据写入 `religion_person`。

## 9.4 区县校核 CheckController

基路径：`/religion/check`

- `GET /listByCounty`  
  查询本区县待校核数据，支持教别筛选。

- `POST /singleCheck/{personId}`  
  单条通过校核。

- `POST /batchCheck`  
  批量通过校核：
  ```json
  {
    "ids": [1,2,3]
  }
  ```

## 9.5 审计日志 AuditController

基路径：`/religion/audit`

- `GET /list`  
  审计日志列表。

- `GET /detail/{logId}`  
  日志详情。

---

# 第 10 章：Service 与 Mapper 方法定义（示意）

## 10.1 ReligionPlaceService

```java
public interface ReligionPlaceService {
    List<ReligionPlace> list(PlaceQuery query);
    ReligionPlace getById(Long id);
    int create(ReligionPlace place);
    int update(ReligionPlace place);
}
```

## 10.2 ReligionPersonService

```java
public interface ReligionPersonService {
    List<ReligionPerson> list(PersonQuery query);
    ReligionPerson getById(Long id);
    int update(ReligionPerson person);
    int batchUpdatePoliticalStatus(List<Long> ids, String status, String operator);
}
```

## 10.3 ReligionImportService

```java
public interface ReligionImportService {
    ImportBatch upload(MultipartFile file, Long placeId, String uploader);
    ParseResult getParseResult(Long batchId);
    HandleResult resolveConflict(ConflictRequest request);
    int commit(Long batchId, String operator);
}
```

## 10.4 ReligionCheckService

```java
public interface ReligionCheckService {
    List<ReligionPerson> listToCheck(CountyQuery query);
    int singleCheck(Long personId, String operator);
    int batchCheck(List<Long> ids, String operator);
}
```

## 10.5 ReligionAuditLogService

```java
public interface ReligionAuditLogService {
    List<ReligionAuditLog> list(AuditQuery query);
    ReligionAuditLog detail(Long id);

    void logCreate(String resourceType, Long resourceId, Object newValue);
    void logUpdate(String resourceType, Long resourceId, Object oldValue, Object newValue);
    void logBatch(String resourceType, List<Long> ids, Object diff);
}
```

---

# 第 11 章：Excel 导入与校验规则

## 11.1 Excel 模板字段（示例）

- 姓名  
- 教别  
- 性别  
- 身份证号  
- 出生日期  
- 所在县区  
- 详细地址  
- 政治面貌  
- 国民教育学历  
- 宗教学历  
- 入教/出家时间  
- 电话  
- 户籍所在地  
- 籍贯  
- 所属宫观  
- 宫观地址  

## 11.2 校验规则

1. 必填项：姓名、教别、身份证号、政治面貌等不可为空；  
2. 身份证：长度为 18 位，可做简单正则校验；  
3. 日期字段：须为 `yyyy-MM-dd` 格式；  
4. 枚举字段：教别、政治面貌、学历等必须在字典中；  
5. 若字段不满足规则，则该行标记为“格式错误”，写入 `error_msg`。

---

# 第 12 章：冲突处理规则

冲突定义：**姓名 + 身份证号** 与数据库中既有数据完全相同，视为同一人，存在“数据冲突”。

支持三种处理模式：

1. **覆盖（override）**  
   - 使用 Excel 中的数据覆盖数据库中的对应记录；  
2. **保留（keep）**  
   - 不导入该条 Excel 记录，保留库中记录；  
3. **手工处理（manual）**  
   - 打开手工处理界面，显示“旧值 vs 新值”，由操作员逐字段决定最终值。

所有冲突处理操作需要写审计日志，记录操作人、时间和处理方式。

---

# 第 13 章：审计日志规范

## 13.1 日志记录场景

- 新增场所、修改场所；  
- 批量修改人员政治面貌；  
- 导入提交；  
- 校核操作（批量/单条）。

## 13.2 字段差异 JSON 示例

```json
{
  "charge_name": ["张三", "李四"],
  "charge_phone": ["13800000000", "13900000000"]
}
```

## 13.3 日志查看

- 列表展示操作时间、操作人、操作类型、资源类型、资源ID；  
- 详情展示 `op_detail` JSON 的格式化内容。

---

# 第 14 章：接口返回与异常处理规范

## 14.1 返回结构

统一使用 RuoYi 风格的 AjaxResult：

成功：

```json
{
  "code": 200,
  "msg": "success",
  "data": { ... }
}
```

失败：

```json
{
  "code": 500,
  "msg": "错误信息"
}
```

## 14.2 异常处理

- 业务异常（如导入批次不存在）抛 `ServiceException`；  
- 参数校验异常由全局异常处理器统一转换为 500 错误。

---

# 第 15 章：数据字段字典（Field Dictionary）

> 本章整理系统中用到的枚举/字典值，便于前后端统一。

## 15.1 宗教类别（religion_type）

- 佛教  
- 道教  
- 伊斯兰教  
- 基督教  
- 天主教  

## 15.2 政治面貌（political_status）

- 群众  
- 中共党员  
- 民革党员  
- 民盟盟员  
- 其它民主党派  

## 15.3 国民教育学历（edu_national）

- 小学  
- 初中  
- 高中  
- 中专  
- 大专  
- 本科  
- 研究生  

## 15.4 宗教学历（edu_religious）

- 无  
- 经学院  
- 宗教院校本科  
- 宗教院校研究生  

## 15.5 人员状态（person.status）

- TO_CHECK：待区县校核  
- CHECKED：已区县校核  
- REPORTED：已上报（本 DEMO 不实现上报流程）

## 15.6 导入批次状态（batch.status）

- PARSED：已解析，未最终导入；  
- PARTIAL：部分冲突已手工处理；  
- FINISHED：导入完成。

---

# 第 16 章：页面交互逻辑（Thymeleaf）

## 16.1 场所表单 place_form.html

- 上方为基本信息（名称、宗教类别、场所类型、区县、地址）；  
- 中间为负责人信息（姓名、电话）；  
- 下方为资质信息与坐标信息；  
- “保存”按钮提交至 `/religion/place/create` 或 `/update`。

## 16.2 人员导入页面 person_import.html

元素说明：

1. 场所选择下拉框（必选）  
2. 文件上传控件  
3. 解析结果统计区域：总数/错误数/冲突数  
4. 错误数据表格（可分页）  
5. 冲突数据表格（带“查看详情/手工处理”按钮）  
6. 冲突模式选择（覆盖/保留/手工）  
7. “提交导入”按钮

## 16.3 冲突处理弹框 person_conflict.html

布局：

- 左侧为“系统中已有数据”（旧值）；  
- 右侧为“Excel 导入数据”（新值）；  
- 中间可加小图标/箭头表示字段比对；  
- 下方“采用旧值/新值” 或由用户编辑最终值。

## 16.4 校核工作台 check_workbench.html

- 顶部筛选区域：
  - 教别下拉；
  - 姓名关键字；
  - 身份证号；  
- 表格区域展示待校核人员：姓名、身份证、教别、场所、状态等；  
- 按钮：
  - 批量通过；
  - 单条通过（详情页中）。

## 16.5 审计日志列表 audit_list.html

- 筛选项：
  - 操作人；
  - 操作类型；
  - 资源类型；
  - 时间范围；  
- 表格列：
  - 操作时间；
  - 操作人；
  - 类型；
  - 资源类型；
  - 资源ID；
  - “查看详情”链接；  
- 详情页展示 `op_detail` JSON 的格式化结构。

---

# 第 17 章：开发规范（命名 / 结构 / 代码）

## 17.1 包结构规范

```text
com.ruoyi.project.religion.place
com.ruoyi.project.religion.person
com.ruoyi.project.religion.import
com.ruoyi.project.religion.audit
```

## 17.2 Controller 命名规范

- ReligionPlaceController  
- ReligionPersonController  
- ReligionImportController  
- ReligionCheckController  
- ReligionAuditController  

## 17.3 Service/Mapper 命名规范

- Interface：`XxxService`  
- Impl：`XxxServiceImpl`  
- Mapper：`XxxMapper` + 对应 XML 文件。

## 17.4 HTML 页面命名规范

- place_list.html  
- place_form.html  
- person_list.html  
- person_import.html  
- person_conflict.html  
- check_workbench.html  
- audit_list.html  

## 17.5 代码风格

- 遵循 Java 命名规范（驼峰）；  
- Controller 中仅做参数处理和结果封装，业务逻辑放在 Service 中；  
- Mapper 层只做 SQL 映射，不写业务逻辑。

---

# 第 18 章：接口返回结构规范（再次强调）

所有 REST 接口返回结构应统一为：

```json
{
  "code": 200,
  "msg": "success",
  "data": { ... }
}
```

异常时：

```json
{
  "code": 500,
  "msg": "错误描述"
}
```

其中 `code` 可扩展为其它业务码，但 DEMO 中保持 200 / 500 即可。

---

# 第 19 章：异常与日志策略

- 对于参数错误及时抛出 ServiceException；  
- 对于系统异常由统一异常处理器捕获并打印日志；  
- 关键业务操作必须调用 `ReligionAuditLogService` 写业务日志。

---

# 第 20 章：与 Codex 协同开发的建议（可选使用）

- 在 VSCode 中打开项目后，可将本 md 文档作为上下文输入给 Codex；  
- 在编写某模块时，将相关章节（数据结构 + 接口 + 页面说明）复制给 Codex，要求其生成对应 Controller/Service/Mapper/HTML；  
- 开发顺序建议：
  1. 建表（MySQL）  
  2. Entity + Mapper  
  3. Service 实现  
  4. Controller  
  5. 页面 HTML + JS  

---

# 第 21 章：ER 关系说明

```text
religion_place (1) —— (N) religion_person
    一个场所可以对应多个教职人员；
    教职人员通过 place_id 关联所属场所。

religion_import_batch (1) —— (N) religion_import_item
    一个导入批次对应多条导入记录（每条对应 Excel 中一行）。

religion_person (N) —— (1) religion_place
    人员通过 place_id 绑定到唯一的场所。
```

ER 关系可以绘制成图（可交由 Codex 或 UML 工具）：

- 实体：Place、Person、ImportBatch、ImportItem、AuditLog；
- 关系：
  - Place 1 — N Person  
  - ImportBatch 1 — N ImportItem  
  - AuditLog 与 Place/Person/Batch 为 N — 1（通过 resource_id）。

---

**文档完毕：1–21 章完整开发规范，可作为 DEMO 项目开发与后期维护的基础文档。**