宗教管理系统 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 评审项一：宗教信息录入与数据维护

评审要求概要：

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

DEMO 实现范围：

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

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

评审要求概要：

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

DEMO 实现范围：

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

第 3 章：角色与权限模型

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

3.1 角色定义

管理员（Admin）
- 负责全局配置与演示操作；
- 权限包含：
  - 场所管理：增删改查；
  - 人员管理：增删改查、批量维护；
  - 人员导入：上传、解析、冲突处理、提交；
  - 审计日志：查看；
  - 字典管理：可维护教别、政治面貌等；
  - 用户与角色管理：可选。
区县用户（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 核心业务实体

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

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

4.2.1 场所表 religion_place

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

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

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

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

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 模块中新增业务包。

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 模板位于：

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 场所新增流程

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

7.2 场所修改流程

在“场所列表”中选中某条记录，点击“编辑”；
进入 place_form.html，展示原有字段；
用户修改负责人姓名或电话等信息；
提交后，Service 层获取旧记录 + 新记录；
计算字段差异（例如通过反射比对或手动比对重要字段）；

构造 op_detail JSON，如：

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

写入 religion_audit_log；
返回成功。

7.3 批量修改政治面貌流程

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

7.4 人员导入流程

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

7.5 区县校核流程

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

第 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
批量修改政治面貌：
```
{
"personIds": [1,2,3],
"politicalStatus": "群众"
}
```

9.3 导入 ImportController

基路径：/religion/import

POST /upload?placeId={placeId}
上传 Excel 并解析；参数中 placeId 作为人员绑定场所。
GET /result/{batchId}
获取解析结果，包括错误列表和冲突列表。

POST /resolveConflict
对冲突数据进行处理：

{
"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
批量通过校核：
```
{
"ids": [1,2,3]
}
```

9.5 审计日志 AuditController

基路径：/religion/audit

GET /list
审计日志列表。
GET /detail/{logId}
日志详情。

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

10.1 ReligionPlaceService

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

10.2 ReligionPersonService

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

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

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

10.5 ReligionAuditLogService

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 校验规则

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

第 12 章：冲突处理规则

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

支持三种处理模式：

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

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

第 13 章：审计日志规范

13.1 日志记录场景

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

13.2 字段差异 JSON 示例

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

13.3 日志查看

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

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

14.1 返回结构

统一使用 RuoYi 风格的 AjaxResult：

成功：

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

失败：

{
  "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

元素说明：

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

16.3 冲突处理弹框 person_conflict.html

布局：

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

16.4 校核工作台 check_workbench.html

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

16.5 审计日志列表 audit_list.html

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

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

17.1 包结构规范

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 接口返回结构应统一为：

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

异常时：

{
  "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 关系说明

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 项目开发与后期维护的基础文档。

宗教管理系统DEMO开发技术说明文档.md 29 KB Постоянная ссылка История Исходник