# art_school 数据结构适配调整清单

## 1. 调整概览
本次根据 `docs/51dx_school.json` 的结构补齐学校详情字段，主要涉及 `art_school_detail` 表新增若干 JSONB/文本/数值字段，用于保存特色专业、就业报告、图片、学科评估、科研信息、满意度明细等。

## 2. 需要新增/修改的表结构

### 2.0 `art_school_detail` 已覆盖字段（无需新增）
以下字段在你当前的 `art_school_detail` 表中已经存在，可直接复用：
`back_ground`、`is_public`、`master_proportion_rate`、`abroad_proportion_rate`、`has_regular`、`has_junior`、`has_master`、`is_double_high_plan`、`is_strong_plan`、`twsdl_rank`、`xyh_rank`、`wsl_rank`、`usdalu_rank`、`qsdalu_rank`、`employment_rate`、`satisfaction_rate`、`master_point`、`doctor_point`、`key_major_count`、`tags`、`univ_id` 等。

### 2.1 `art_school_detail` 需要新增字段
用途：承载 51dx 学校详情中的结构化字段与长文本字段。

| 字段名 | 类型(建议) | 含义 | 来源字段 | 调整原因 |
| --- | --- | --- | --- | --- |
| `combined_score` | DECIMAL(10,2) | 综合评分 | `combinedScore` | 评分指标缺失 |
| `overall_rank` | INT | 综合排名 | `rank` | 排名指标缺失 |
| `env_satisfaction` | DECIMAL(10,2) | 环境满意度 | `envSatisfaction` | 满意度细分缺失 |
| `env_vote` | INT | 环境满意度投票数 | `envVote` | 满意度细分缺失 |
| `live_satisfaction` | DECIMAL(10,2) | 生活满意度 | `liveSatisfaction` | 满意度细分缺失 |
| `live_vote` | INT | 生活满意度投票数 | `liveVote` | 满意度细分缺失 |
| `combined_satisfaction` | DECIMAL(10,2) | 综合满意度(原始分) | `combinedSatisfaction` | 保留原始评分 |
| `combined_vote` | INT | 综合满意度投票数 | `combinedVote` | 满意度细分缺失 |
| `satisfaction_json` | JSONB | 满意度明细 JSON | `satisfactionJson` | 结构化明细未存储 |
| `teachers` | LONGTEXT | 师资力量说明 | `teachers` | 文字说明缺失 |
| `scholarship` | LONGTEXT | 奖学金说明 | `scholarship` | 文字说明缺失 |
| `scholarship_json` | JSONB | 奖学金数组 JSON | `scholarshipArray` | 结构化说明缺失 |
| `grant_desc` | LONGTEXT | 助学金说明 | `grant` | 文字说明缺失 |
| `canteen` | LONGTEXT | 食堂说明 | `canteen` | 文字说明缺失 |
| `dormitory` | LONGTEXT | 宿舍说明 | `dormitory` | 文字说明缺失 |
| `master_explain` | TEXT | 硕士点说明 | `masterExplain` | 说明字段缺失 |
| `doctor_explain` | TEXT | 博士点说明 | `doctorExplain` | 说明字段缺失 |
| `special_major_json` | JSONB | 特色专业 JSON | `specialMajor` | 结构化内容缺失 |
| `employment_report_json` | JSONB | 就业报告 JSON | `employmentReport` | 结构化内容缺失 |
| `photo_json` | JSONB | 图片 JSON | `photoJson` | 结构化内容缺失 |
| `accommodation_json` | JSONB | 建筑/配套 JSON | `accommodationArray` | 结构化内容缺失 |
| `subject_reviews_json` | JSONB | 学科评估 JSON | `subjectReviews` | 结构化内容缺失 |
| `research_json` | JSONB | 科研信息 JSON | `researchJson` | 结构化内容缺失 |
| `univ_majors_json` | JSONB | 专业标签 JSON | `univMajors` | 结构化内容缺失 |
| `univ_postgraduate_json` | JSONB | 保研信息 JSON | `univPostgraduateList` | 结构化内容缺失 |

### 2.2 关联关系调整
本次未新增关系。新增字段均挂在 `art_school_detail`，与 `art_school.school_id` 关系保持不变。

## 3. 是否需要新增实体/表的评估
短期不必新增独立表，理由：
1. 51dx 的结构性字段（如 `specialMajor`、`employmentReport`、`subjectReviews`）主要用于展示，不涉及复杂查询与统计，存 JSON 字段可以满足当前需求。
2. 当前已有 `art_school_media`、`art_school_major_tag` 等表，但与 51dx 数据结构不完全匹配，新增映射成本高且收益有限。

若后续有以下需求，建议拆表：
1. 需要对特色专业/学科评估进行检索与排序。
2. 就业报告需要独立管理、下载或审核。
3. 图片需要按类型、排序进行管理（可复用 `art_school_media`，增加 `biz_type=school` 的批量导入逻辑）。

## 4. SQL 参考（PostgreSQL + JSONB + COMMENT）

```sql
-- 如果已经创建了 rank/grant 列，先重命名避免关键字冲突
ALTER TABLE art_school_detail
  RENAME COLUMN "rank" TO overall_rank;
ALTER TABLE art_school_detail
  RENAME COLUMN "grant" TO grant_desc;

ALTER TABLE art_school_detail
  ADD COLUMN combined_score NUMERIC(10,2),
  ADD COLUMN overall_rank INTEGER,
  ADD COLUMN env_satisfaction NUMERIC(10,2),
  ADD COLUMN env_vote INTEGER,
  ADD COLUMN live_satisfaction NUMERIC(10,2),
  ADD COLUMN live_vote INTEGER,
  ADD COLUMN combined_satisfaction NUMERIC(10,2),
  ADD COLUMN combined_vote INTEGER,
  ADD COLUMN satisfaction_json JSONB,
  ADD COLUMN teachers TEXT,
  ADD COLUMN scholarship TEXT,
  ADD COLUMN scholarship_json JSONB,
  ADD COLUMN grant_desc TEXT,
  ADD COLUMN canteen TEXT,
  ADD COLUMN dormitory TEXT,
  ADD COLUMN master_explain TEXT,
  ADD COLUMN doctor_explain TEXT,
  ADD COLUMN special_major_json JSONB,
  ADD COLUMN employment_report_json JSONB,
  ADD COLUMN photo_json JSONB,
  ADD COLUMN accommodation_json JSONB,
  ADD COLUMN subject_reviews_json JSONB,
  ADD COLUMN research_json JSONB,
  ADD COLUMN univ_majors_json JSONB,
  ADD COLUMN univ_postgraduate_json JSONB;

COMMENT ON COLUMN art_school_detail.combined_score IS '综合评分';
COMMENT ON COLUMN art_school_detail.overall_rank IS '综合排名';
COMMENT ON COLUMN art_school_detail.env_satisfaction IS '环境满意度';
COMMENT ON COLUMN art_school_detail.env_vote IS '环境满意度投票数';
COMMENT ON COLUMN art_school_detail.live_satisfaction IS '生活满意度';
COMMENT ON COLUMN art_school_detail.live_vote IS '生活满意度投票数';
COMMENT ON COLUMN art_school_detail.combined_satisfaction IS '综合满意度(原始分)';
COMMENT ON COLUMN art_school_detail.combined_vote IS '综合满意度投票数';
COMMENT ON COLUMN art_school_detail.satisfaction_json IS '满意度明细JSON';
COMMENT ON COLUMN art_school_detail.teachers IS '师资力量描述';
COMMENT ON COLUMN art_school_detail.scholarship IS '奖学金说明';
COMMENT ON COLUMN art_school_detail.scholarship_json IS '奖学金数组JSON';
COMMENT ON COLUMN art_school_detail.grant_desc IS '助学金说明';
COMMENT ON COLUMN art_school_detail.canteen IS '食堂说明';
COMMENT ON COLUMN art_school_detail.dormitory IS '宿舍说明';
COMMENT ON COLUMN art_school_detail.master_explain IS '硕士点说明';
COMMENT ON COLUMN art_school_detail.doctor_explain IS '博士点说明';
COMMENT ON COLUMN art_school_detail.special_major_json IS '特色专业JSON';
COMMENT ON COLUMN art_school_detail.employment_report_json IS '就业报告JSON';
COMMENT ON COLUMN art_school_detail.photo_json IS '图片JSON';
COMMENT ON COLUMN art_school_detail.accommodation_json IS '建筑/配套JSON';
COMMENT ON COLUMN art_school_detail.subject_reviews_json IS '学科评估JSON';
COMMENT ON COLUMN art_school_detail.research_json IS '科研信息JSON';
COMMENT ON COLUMN art_school_detail.univ_majors_json IS '专业标签JSON';
COMMENT ON COLUMN art_school_detail.univ_postgraduate_json IS '保研信息JSON';
```

## 5. JSONB 性能简要说明
一般情况下，PostgreSQL 的 JSONB 比 TEXT 存 JSON 更适合查询与索引，读写成本略高但查询性能更好；若仅做原样展示且几乎不查询，可用 TEXT 降低写入开销。当前场景包含后续检索可能性，建议使用 JSONB。

## 6. 前端表单与接口调整建议

### 6.1 前端需要新增的字段（按展示/编辑分组）
以下字段建议直接在学校详情页（或学校详情编辑页）增加表单项；展示为主、无需复杂查询：
- 文本/富文本：`teachers`、`scholarship`、`grant_desc`、`canteen`、`dormitory`、`master_explain`、`doctor_explain`
- 数值：`combined_score`、`overall_rank`、`env_satisfaction`、`env_vote`、`live_satisfaction`、`live_vote`、`combined_satisfaction`、`combined_vote`
- JSONB 原样展示（可选做 JSON 编辑器/分块表单）：`satisfaction_json`、`research_json`、`univ_majors_json`、`univ_postgraduate_json`

### 6.2 建议拆表并提供独立编辑的模块（可增删列表）
如果需要列表化编辑、排序、筛选，则建议拆表并提供独立接口：
- 特色专业（`special_major_json`）
  - 建议拆表字段：`school_id`、`type`、`major_id`、`major_name`、`sort_no`、`remark`
- 学科评估（`subject_reviews_json`）
  - 建议拆表字段：`school_id`、`review_type`、`subject_name`、`assess_level`、`assess_grade`、`sort_no`、`remark`
- 就业报告（`employment_report_json`）
  - 建议拆表字段：`school_id`、`report_name`、`online_preview`、`report_url`、`year`、`sort_no`、`remark`
- 图片（`photo_json`）
  - 建议直接使用现有 `art_school_media`（`biz_type=school`）做多图管理

### 6.3 接口调整建议（最小改动）
如果先不拆表，推荐在现有学校详情保存接口中直接读写 JSONB 字段：
- 新增/更新：`ArtSchoolService.insertWithDetailByBo` / `updateWithDetailByBo`
- 查询：`ArtSchoolDetailController` 的 `getInfo` / `list` 保持返回 JSONB 字段

如拆表，则建议新增独立模块接口（示例）：
1. 特色专业
   - `GET /art/school/specialMajor/list?schoolId=`
   - `POST /art/school/specialMajor`
   - `PUT /art/school/specialMajor`
   - `DELETE /art/school/specialMajor/{id}`
2. 学科评估
   - `GET /art/school/subjectReview/list?schoolId=`
   - `POST /art/school/subjectReview`
   - `PUT /art/school/subjectReview`
   - `DELETE /art/school/subjectReview/{id}`
3. 就业报告
   - `GET /art/school/employmentReport/list?schoolId=`
   - `POST /art/school/employmentReport`
   - `PUT /art/school/employmentReport`
   - `DELETE /art/school/employmentReport/{id}`
4. 学校图片（复用）
   - `GET /art/school/media/list?bizType=school&bizId=`
   - `POST /art/school/media`
   - `DELETE /art/school/media/{id}`

### 6.4 前端表单交互建议
- JSONB 字段：可用「分组表单 + 预览 JSON」或直接 JSON 编辑器组件，提交时序列化为字符串。
- 列表型字段：使用可增删行的表单组件，对应独立接口，避免整条详情表单过大。