# YschcmsService

> 本仓库由 projman 自动创建并注入 CI（`.gitea/workflows/build.yml`）与 Dockerfile（`docker/Dockerfile`）。
> 推送代码到 main 分支即自动构建镜像并推送到 Nexus，projman 收到通知后建档待部署，由运维在 projman「后端发布」手动点部署。

## 接口变更声明（2026-09-07 产品优化批次 B1~B5）

| 接口 | 变更 | 兼容性 |
| --- | --- | --- |
| `POST /api/site/save` | 权限语义拆分：原"仅超管"放宽为——校级角色（currentRole.schId 非空）可新建/编辑**本校主站下的院系子站**（parentSiteId>0 且主站属本校）；顶层站新建/编辑/子站提升为顶层仍仅超管；请求体显式 schId 与角色不一致直接拒绝（留空由服务端继承主站） | 校级为新增放行面；超管行为不变；越权统一 403 |
| `POST /api/attachment/upload` | 新增可选 `scene` 参数（banner/link/site 白名单），落 `ref_type` 作场景引用初步标记；不传保持原行为 | 纯新增可选参数，旧调用方不受影响 |
| `GET /api/attachment/page` | "孤儿"语义改为"未使用"：`articleId IS NULL AND ref_type IS NULL`；返回键 `orphanCount` 更名 `unusedCount`（无兼容别名，前端已同步）；`orphanOnly=true` 过滤同语义 | **破坏性**：消费 orphanCount 的旧前端需同步（本仓库 front 已于同批改造） |
| `cms_attachment` 表 | 新增 `ref_type VARCHAR(16)`、`ref_id INT` 与 `idx_att_ref` 索引（B2 附件引用模型）；存量数据不回填，旧场景图在重新保存前显示"未使用"为已知差异 | 加列向后兼容；开发库 ddl-auto=update 自动加列，生产执行 `sql/cms_init.sql` 增量 |
| `config_json.custom_css` | 新增站点级自定义样式键：服务端强校验（≤10240 字符；黑名单 `</style`/`<script`/`@import`/`expression(` 忽略大小写）；门户 5 套主题 head 内联直出 | 新增键，未配置站点不受影响 |

## 首次推送本地代码到本仓库

> 目标：把本地已有代码推上去，同时**保留** projman 注入的文件（`build.yml`、`Dockerfile`）。

```bash
# 1. 进入本地代码目录
cd /your/local/code/dir

# 2. 初始化 git（目录已有 .git 也安全，git init 幂等无副作用）
git init
git branch -M main

# 3. 先把本地代码提交成一个 commit（关键！不提交直接 merge 会丢失本地代码）
git add -A
git commit -m "init local code"

# 4. 关联远程仓库（幂等：已存在 origin 则改地址，不报错）
git remote add origin http://gitea.yunhaixingtong.com/yschcms/YschcmsService.git 2>/dev/null \
  || git remote set-url origin http://gitea.yunhaixingtong.com/yschcms/YschcmsService.git

# 5. 拉取远程信息（只下载，不合并）
git fetch origin

# 6. 合并远程 main（关键步骤）
#    本地与远程是两条独立历史，需允许合并不相关历史。
#    此步会把 projman 注入的 build.yml 与 Dockerfile 合并进你的本地工作区。
git merge origin/main --allow-unrelated-histories -m "merge projman injected files"

# 7. 查看状态（确认 .gitea/workflows/build.yml、docker/Dockerfile 已在本地）
git status

# 8. 提交并推送
git add -A
git commit -m "sync local code" 2>/dev/null || true
git push origin main
```

## 推送后验证

push 触发 CI 构建，前往 Gitea 仓库 → **Actions** 查看日志；构建成功后镜像推送到 Nexus，projman 建档待部署，在 projman 应用详情「后端发布」手动点部署。

## 禁止写法（会导致注入文件被删）

`git reset origin/main` + `git add -A` 会把远程已注入、但你本地没有的文件（`build.yml`、`Dockerfile`）当作"删除"提交并推送，导致这些文件被删、CI 失败。务必用 `git merge` 而非 `git reset`，且 merge 前先提交本地代码。

## 关于 Dockerfile

projman 注入的 Dockerfile 仅在仓库不存在时写入；你自备的 Dockerfile 优先，不会被覆盖。