docs: add govdoc migration analysis and implementation notes
This commit is contained in:
wren
@@ -0,0 +1,242 @@
|
||||
# 内部公文模块运行与验收手册
|
||||
|
||||
## 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. 再处理余下产品细节
|
||||
Reference in New Issue
Block a user