leaudit-platform-backend/docs/内部公文模块/内部公文模块运行与验收手册.md

# 内部公文模块运行与验收手册

## 1. 文档目的

本文档只解决 4 个现实问题：

- 当前 `govdoc` 正确的运行链路是什么
- 现在页面为什么还可能报 `404 / 500 / 502 / 401`
- 应该按什么顺序排障
- 如何判断“内部公文模块已经真正接到当前 1 后端”

本文档基于 2026-05-17 当前机器与当前仓库实际联调结果整理。

---

## 2. 正确链路

当前内部公文模块正确链路应为：

1. 浏览器访问 `http://172.16.0.59:5173/govdoc/audits?entryModuleId=3`
2. `5173` 由 `nginx` 提供入口
3. `nginx` 上游转到当前前端开发服务 `127.0.0.1:5193`
4. 前端 `/api/govdoc/*` 代理到 `http://172.16.0.59:8096/api/govdoc/*`
5. `8096` 由当前仓库 `leaudit-platform` 后端提供
6. 审查任务由当前仓库 Celery worker 消费

只要这 6 段里任意一段错了，外部表现就会异常。

---

## 3. 当前已确认事实

本次联调已确认以下事实成立：

- 当前仓库后端标准端口是 `8096`
- 当前仓库前端开发服务端口是 `5193`
- 当前对外入口端口是 `5173`
- 当前 `govdoc` 接口代理文件是：
  - [route.ts](/home/wren-dev/Porject/leaudit-platform/legal-platform-frontend/app/api/govdoc/[...path]/route.ts)
- 当前前端环境配置里：
  - `API_BACKEND_TARGET=http://172.16.0.59:8096`
- 当前 `GET /api/govdoc/documents?page=1&pageSize=1` 已经能到达当前后端
- 未登录访问该接口时，返回 `401 Unauthorized`
- 未登录访问 `/govdoc/audits` 时，会重定向到 `/login`

这说明：

- `govdoc` 文档列表接口已经接到当前 1 后端
- 当前若再看到异常，优先怀疑运行进程或登录态，而不是先怀疑接口没接

---

## 4. 当前机器上的关键风险

当前机器上还存在一个高风险旧进程：

- `python start_worker_with_routing.py --config-port 8096`
- `cwd=/home/wren-dev/Porject/docauditai`

它不是当前仓库 worker。

这意味着：

- 即使当前仓库代码已经修好
- 只要正式任务仍被旧 worker 消费
- `govdoc` 实际执行结果仍可能继续偏向旧项目行为

结论：

- 当前最大运行风险不是代码本身，而是**旧 worker 未彻底退出正式链路**

---

## 5. 正确启动方式

当前仓库建议使用：

```bash
cd /home/wren-dev/Porject/leaudit-platform
./leaudit.sh start
```

查看状态：

```bash
./leaudit.sh status
```

查看巡检结果：

```bash
./leaudit.sh doctor
```

查看日志：

```bash
./leaudit.sh logs backend
./leaudit.sh logs frontend
./leaudit.sh logs worker
./leaudit.sh logs beat
```

当前脚本关键文件：

- [leaudit.sh](/home/wren-dev/Porject/leaudit-platform/leaudit.sh)
- [start_worker.sh](/home/wren-dev/Porject/leaudit-platform/scripts/start_worker.sh)
- [start_beat.sh](/home/wren-dev/Porject/leaudit-platform/scripts/start_beat.sh)

---

## 6. 四类典型报错怎么判断

### 6.1 `404`

通常说明：

- `govdoc` 代理没走到当前后端
- 当前后端没启动
- 请求被打到了错误服务

优先检查：

- `8096` 是否监听
- `/api/govdoc/*` 是否仍代理到当前 `8096`
- 是否还在访问旧项目接口

### 6.2 `500`

通常说明：

- 路由已经接到了正确后端
- 但数据库、表、规则文件、运行数据或服务层逻辑有问题

这类问题要优先看：

- `.codex-run/backend.log`
- 后端 traceback
- `govdoc_runs / govdoc_report_artifacts` 相关表和数据

### 6.3 `502`

通常说明：

- `5173` 的 nginx 上游失活
- `5193` 前端服务未启动
- `8096` 后端未启动

这类问题不是业务 bug，先查进程和端口。

### 6.4 `401`

通常说明：

- 链路已经通到当前后端
- 只是当前请求没有有效登录态

这类情况恰恰说明：

- `govdoc` 接口已经不是 `404`
- 前后端契约已经在工作

---

## 7. 当前最小排障顺序

每次出现问题，建议严格按这个顺序查：

1. 先看 `./leaudit.sh status`
2. 再看 `ss -ltnp` 是否存在 `5173 / 5193 / 8096`
3. 再看旧 worker 是否还在：
   - `ps -ef | rg "start_worker_with_routing.py --config-port 8096"`
4. 再看前端 `govdoc` 代理是否还是指向 `8096`
5. 再看后端日志是 `401 / 404 / 500` 哪一类
6. 最后才去怀疑业务代码

不要反过来先改代码。

---

## 8. 当前验收标准

如果要判断“内部公文模块已经真正接到当前后端并基本可用”，至少要满足：

### 8.1 运行层

- `5173` 正常访问
- `5193` 正常运行
- `8096` 正常运行
- 当前仓库 worker 正常运行
- 当前仓库 beat 正常运行

### 8.2 接口层

- 未登录访问 `/govdoc/audits` 时，正常跳到登录页
- 已登录访问 `/api/govdoc/documents` 时，返回真实列表数据
- 不再出现 `404 Not Found`

### 8.3 业务层

- 文档列表可打开
- 详情页可打开
- 新 run 完成后有正式报告产物
- 可打开 HTML 报告
- 可下载批注 DOCX
- 段落视图可渲染

### 8.4 数据层

- `govdoc_runs` 有最新 run
- `govdoc_report_artifacts` 有正式产物索引
- 历史修复前 run 如需报告，已补跑

---

## 9. 当前还没完全收口的点

截至当前，还没彻底收口的不是主链是否存在，而是这些细节：

- 旧 `docauditai` worker 仍在机器上存活
- 正式 supervisor / 守护方式还没有完全切回当前仓库
- 历史成功 run 不会自动补出报告产物，需要补跑
- 还需要带真实登录态做一轮完整前端验收

---

## 10. 当前结论

当前内部公文模块的真实状态应表述为：

- 业务语义主线已基本对齐
- 后端主链路已接通
- 报告产物主闭环已补齐
- 前端 `govdoc` 列表接口已接到当前 1 后端
- 当前最大的剩余问题是运行部署收口，而不是“文档列表没接后端”

后续如果继续推进，优先级应为：

1. 清理旧 worker 干扰
2. 固化正式启动/重启方式
3. 带真实登录态做完整联调验收
4. 再处理余下产品细节