add compose deployment docs

README.md

@@ -1,6 +1,15 @@
 # HIS_Sur_Data_Deal
 
-网页端检测数据处理工具。上传 `待处理检测数据.zip` 后，服务会自动识别 V1/V2 数据结构，调用原处理脚本生成 Excel，并在网页中展示结果摘要、工作表统计和数据预览；用户可调整每个工作表的预览行数，并按需导出单个 Excel。
+网页端检测数据处理工具。上传 `待处理检测数据.zip` 后，系统会自动识别 V1/V2 数据结构，调用原处理脚本生成 Excel，并在网页中展示结果摘要、工作表统计和数据预览。
+
+处理完成后可在结果页：
+
+- 调整每个工作表的预览行数。
+- 选择是否显示基本工作表、未匹配检测内容项、未检测到内容汇总表。
+- 按姓名、采样时间、检测原因选择升序或降序排序。
+- 导出当前内容选择和排序后的单个 Excel。
+
+“未检测到内容汇总”会在每个“姓名 / 住院号 / 采样时间 / 检测原因”分组标题下单独排序，不会把不同检测原因的分组混在一起。
 
 ## 本地运行
 
@@ -9,7 +18,11 @@ pip install -r requirements.txt
 uvicorn app.main:app --host 0.0.0.0 --port 8000
 ```
 
-访问 `http://localhost:8000`。
+访问：
+
+```text
+http://localhost:8000
+```
 
 ## Docker 构建与运行
 
@@ -18,7 +31,145 @@ docker build -t his-sur-data-deal .
 docker run --rm -p 8000:8000 his-sur-data-deal
 ```
 
-## 推送镜像示例
+访问：
+
+```text
+http://localhost:8000
+```
+
+## Docker Compose 通用部署
+
+通用配置文件：
+
+```text
+docker_compose.yaml
+```
+
+这个配置是本地构建配置，不会从远程镜像仓库拉取 `his-sur-data-deal:latest`。运行时必须在项目源码目录执行，目录中需要包含：
+
+```text
+Dockerfile
+requirements.txt
+app/
+docker_compose.yaml
+```
+
+启动：
+
+```bash
+docker compose -f docker_compose.yaml up -d --build
+```
+
+默认映射：
+
+```text
+宿主机 8000 -> 容器 8000
+```
+
+访问：
+
+```text
+http://服务器IP:8000
+```
+
+## frpc + NPM 反向代理到公网域名
+
+如果本服务运行在内网机器，想通过公网服务器域名访问，可按下面链路处理：
+
+```text
+浏览器
+  -> 公网域名
+  -> 公网服务器 Nginx Proxy Manager
+  -> 公网服务器 frps 暴露端口
+  -> 内网机器 frpc
+  -> 内网 Docker 服务 127.0.0.1:8000
+```
+
+内网机器运行本项目：
+
+```bash
+docker compose -f docker_compose.yaml up -d --build
+```
+
+内网机器 frpc 示例：
+
+```toml
+serverAddr = "公网服务器IP"
+serverPort = 7000
+
+[[proxies]]
+name = "his-sur-data-deal"
+type = "tcp"
+localIP = "127.0.0.1"
+localPort = 8000
+remotePort = 18004
+```
+
+公网服务器 Nginx Proxy Manager 中新增 Proxy Host：
+
+```text
+Domain Names: 你的域名，例如 his.example.com
+Scheme: http
+Forward Hostname / IP: 127.0.0.1
+Forward Port: 18004
+Websockets Support: 可不开
+Block Common Exploits: 建议开启
+SSL: 按需申请 Let's Encrypt
+```
+
+如果公网服务器的 NPM 与 frps 不在同一台机器，则 `Forward Hostname / IP` 填写 frps 所在服务器的内网或公网 IP。
+
+## NAS Docker Compose 部署
+
+NAS 地址：
+
+```text
+http://192.168.31.5/
+```
+
+NAS 专用配置文件：
+
+```text
+docker_compose-Nas.yaml
+```
+
+这个配置同样是本地构建配置，不依赖远程镜像仓库。NAS 上请把整个项目源码放到下面目录：
+
+```text
+/share/Container/his_sur_data_deal/app
+```
+
+该目录中必须包含：
+
+```text
+/share/Container/his_sur_data_deal/app/Dockerfile
+/share/Container/his_sur_data_deal/app/requirements.txt
+/share/Container/his_sur_data_deal/app/app/
+/share/Container/his_sur_data_deal/app/docker_compose-Nas.yaml
+```
+
+如果只在 NAS 面板里粘贴 yaml，而没有把 `Dockerfile` 和 `app/` 一起放到上述路径，NAS 会报 `failed to read dockerfile: open Dockerfile: no such file or directory`。
+
+启动：
+
+```bash
+cd /share/Container/his_sur_data_deal/app
+docker compose -f docker_compose-Nas.yaml up -d --build
+```
+
+默认映射：
+
+```text
+NAS 4004 -> 容器 8000
+```
+
+访问：
+
+```text
+http://192.168.31.5:4004
+```
+
+## 镜像推送示例
 
 ```bash
 docker tag his-sur-data-deal 192.168.31.5:5002/admin/his-sur-data-deal:latest
@@ -27,19 +178,23 @@ docker push 192.168.31.5:5002/admin/his-sur-data-deal:latest
 
 ## 数据模式
 
-V1：zip 解压后包含 `Patients_info.csv`、`Tests_List`、`Tests_Detail_List`，输出一个汇总 Excel。
+V1：
 
-V2：zip 解压后包含 `Patients_info.csv`，并按患者目录分别保存检测汇总和具体检测，输出多个患者 Excel。
+- zip 解压后包含 `Patients_info.csv`、`Tests_List`、`Tests_Detail_List`。
+- 输出一个汇总 Excel。
 
-患者编号类型可选择自动识别。自动识别会读取 `Patients_info.csv` 中的 `pat_no`，并与 `Tests_List` 文件名或患者目录名比对：若更匹配 10 位补零编号，则使用 `pat_no`；若更匹配原始编号，则使用 `zhuyuanhao`。
+V2：
 
-系统默认输出完整结果；处理完成后可在结果页通过“内容选择”立即切换预览内容，并同步影响右侧“导出此 Excel”的文件内容。结果页还可以按姓名、采样时间或检测原因选择升序/降序排序；“未检测到内容汇总”会在每个分组标题下单独排序，不会把不同检测原因的分组混在一起。可选择是否保留：
+- zip 解压后包含 `Patients_info.csv`。
+- 按患者目录分别保存检测汇总和具体检测。
+- 输出多个患者 Excel。
 
-- 基本工作表
-- 未匹配检测内容项
-- 未检测到内容汇总表
+患者编号类型可选择自动识别。自动识别会读取 `Patients_info.csv` 中的 `pat_no`，并与 `Tests_List` 文件名或患者目录名比对：如果更匹配 10 位补零编号，则使用 `pat_no`；如果更匹配原始编号，则使用 `zhuyuanhao`。
 
-“未检测到内容汇总”会收集标准字段全部为 `Not_Find`、但存在未匹配检测内容的记录，并按检测原因排序汇总。
+## 结果规则
 
-未匹配检测内容会被规范化为独立列：表头为未匹配检测项目名，数据行仅保存对应检测值。
-如果某个工作表没有任何未匹配检测项目，则不会显示“未匹配检测内容”标识列。标准字段全为 `Not_Find` 且没有未匹配值的空结果行会被移除。
+- 系统默认输出完整结果。
+- `未匹配检测内容` 会规范化为独立列：表头为未匹配检测项目名，数据行只保存对应检测值。
+- 如果某个工作表没有任何未匹配检测项目，不显示 `未匹配检测内容` 标识列。
+- 标准检测字段全为 `Not_Find` 的记录会移入 `未检测到内容汇总`，不继续留在原基本工作表中。
+- 导出 Excel 会跟随页面上的内容选择和排序。