init: readme guide [skip ci]

README.md

@@ -1,3 +1,53 @@
 # UserclassFront
 
-managed by projman
+> 本仓库由 projman 自动创建并注入 CI（`.gitea/workflows/build.yml`）与 Dockerfile（`docker/Dockerfile`）。
+> 推送代码到 main 分支即自动构建镜像并推送到 Nexus，projman 收到通知后建档待部署，由运维在 projman「后端发布」手动点部署。
+
+## 首次推送本地代码到本仓库
+
+> 目标：把本地已有代码推上去，同时**保留** 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/userclass/UserclassFront.git 2>/dev/null \
+  || git remote set-url origin http://gitea.yunhaixingtong.com/userclass/UserclassFront.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 优先，不会被覆盖。