From 3ea36bd2bb6be394e6d2bf28fb7a2538ff17a769 Mon Sep 17 00:00:00 2001 From: "mula.liu" Date: Wed, 4 Nov 2026 01:11:35 +0800 Subject: [PATCH] =?UTF-8?q?fix(api):=20=E6=8E=A5=E5=8F=A3=E5=A5=91?= =?UTF-8?q?=E7=BA=A6=E4=B8=89=E4=BF=AE=E2=80=94=E2=80=94422/500=20?= =?UTF-8?q?=E7=BB=9F=E4=B8=80=E4=B8=AD=E6=96=87=E3=80=81=E5=AF=BC=E5=87=BA?= =?UTF-8?q?=E6=9D=83=E9=99=90=20fail-closed=E3=80=81=E6=93=8D=E4=BD=9C?= =?UTF-8?q?=E6=97=A5=E5=BF=97=E6=9C=8D=E5=8A=A1=E7=AB=AF=E5=88=86=E9=A1=B5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - main.py:/api 子应用挂 RequestValidationError 与 Exception 处理器——FastAPI 默认英文 「Field required」/「Internal Server Error」此前会被前端 api() 原样 toast,中文界面冒英文。 现统一为「提交的数据有误:「字段」不能为空/格式不正确」「服务器内部错误,请稍后重试」。 - security.resolve_rule:/export/* 未登记 EXPORT_MENU 的名字从 fail-open(登录即可下载) 改为 403;新加导出忘挂权限不再静默绕过 RBAC。 - 操作日志分页断裂修复:前端此前固定 limit=200 不发 offset,本地翻页把 200 条当全量, 第 201 条起界面永远看不到。现 limit/offset 跟随页码条(与全站同构:每页条数下拉、 筛选回第 1 页、越界回退重取),count 与 pager 都用服务端 total。 - 新增 tests/test_api_contract.py(4 例):/health 与 / 可达、422 中文 detail、 未登记导出名 403 + 6 个已登记导出归属正确、日志跨页不重不漏。 - README:日志端点参数补 offset 并注明服务端分页;界面设计语言加「报错一律中文」与 导出 fail-closed 两条。 - pytest 88 passed --- README.md | 4 ++- app/main.py | 21 ++++++++++++++- app/security.py | 7 ++++- tests/test_api_contract.py | 53 ++++++++++++++++++++++++++++++++++++++ web/app.js | 25 +++++++++++++----- 5 files changed, 100 insertions(+), 10 deletions(-) create mode 100644 tests/test_api_contract.py diff --git a/README.md b/README.md index e88bc14..6486e9b 100644 --- a/README.md +++ b/README.md @@ -409,6 +409,7 @@ python scripts/legacy/add_entry_date.py --force # 全部重算 - **交付环节图标按 `code` 取**:后端 `CUSTOM_PIPELINE` 下发的字段是 **`code`**(不是 `key`),前端一律 `Ico.pipe(s.code)`;写成 `s.key` 会静默退化成通用圆点。 - **表格防竖排**:`table.tbl th` / `.pill` / `.tag-mini` 统一 `white-space:nowrap`,容易挤窄的列(区域、负责人)在 `` 上加 `class="nowrap"`;实在挤不下交给 `.tbl-wrap { overflow:auto }` 横向滚动。 - **抽屉不被内容撑破**:`.form-row > div { min-width: 0 }`(grid 子项默认 `min-width:auto`,会被交付环节步骤条撑出整表横向滚动),步骤条本身 `flex:1 1 132px`(132px = 日期输入框含日历图标的最小可用宽度)。 +- **报错一律中文**:Pydantic 422 与未捕获 500 在 `app/main.py` 的 exception handler 统一换成中文 `detail`(「提交的数据有误:…」/「服务器内部错误…」),前端 `api()` 原样 toast,界面不中英夹杂。新增 `/export/*` 必须登记 `security.EXPORT_MENU` 权限归属,未登记一律 403(fail-closed,防「忘挂权限 = 登录即可下载」)。 > 备注:历史遗留的 `.pcard`、`.board-grid`、`.svg-chart`、`.legend`、`.risk-item` 等零引用样式已随死代码清理删除(2026-10-29)。 @@ -607,7 +608,8 @@ PATCH|DELETE /api/rbac/users/{id} 改资料、启停、重设密码;停用 POST /api/rbac/users/{id}/revoke 只吊销某个账号的全部会话 GET /api/rbac/sessions 在线会话(用户、IP、UA、到期、token 摘要) DELETE /api/rbac/sessions/{token} 吊销单个会话 -GET|DELETE /api/rbac/logs 操作审计 ?username=&menu=&action=&days=&limit= / DELETE 按 days 清理 +GET|DELETE /api/rbac/logs 操作审计(服务端分页)?username=&menu=&action=&days=&limit=&offset=;返回 {total, items} + / DELETE 按 days 清理 # 通用 GET /api/meta 状态字典 / 优先级 / 菜单 / AI 配置状态 diff --git a/app/main.py b/app/main.py index f79b109..cfc588d 100644 --- a/app/main.py +++ b/app/main.py @@ -3,8 +3,9 @@ from __future__ import annotations import uuid from fastapi import Depends, FastAPI +from fastapi.exceptions import RequestValidationError from fastapi.middleware.cors import CORSMiddleware -from fastapi.responses import FileResponse +from fastapi.responses import FileResponse, JSONResponse from fastapi.staticfiles import StaticFiles from . import audit, config, finance, security @@ -43,6 +44,24 @@ app.add_middleware( # 所有 /api 接口先过 RBAC 总闸(登录 + 菜单权限),登录接口自身除外 api = FastAPI(title="DMS管理平台 API", dependencies=[Depends(security.guard)]) + + +@api.exception_handler(RequestValidationError) +async def validation_error_cn(request, exc): + """Pydantic/查询参数校验失败默认返回英文 detail,前端会原样 toast 出「Field required」。 + 统一换成中文,界面不再中英夹杂。""" + bits = [] + for e in exc.errors(): + field = str(e.get("loc", ("?",))[-1]) + kind = "不能为空" if str(e.get("type", "")).endswith("missing") else "格式不正确" + bits.append(f"「{field}」{kind}") + return JSONResponse(status_code=422, content={"detail": "提交的数据有误:" + ";".join(bits)}) + + +@api.exception_handler(Exception) +async def server_error_cn(request, exc): + """未捕获异常的默认响应是纯文本 'Internal Server Error',同样会被前端 toast 出来。""" + return JSONResponse(status_code=500, content={"detail": "服务器内部错误,请稍后重试"}) api.middleware("http")(audit.audit_middleware_factory()) api.include_router(board.router, prefix="", tags=["board"]) api.include_router(projects.router, prefix="", tags=["projects"]) diff --git a/app/security.py b/app/security.py index ea25946..326c385 100644 --- a/app/security.py +++ b/app/security.py @@ -255,7 +255,12 @@ def resolve_rule(path: str, method: str): """请求 -> (菜单, 是否写操作);菜单为 None 表示只要登录就能访问。""" parts = [x for x in path.split("/") if x] # /api/custom/projects -> [...] if len(parts) >= 2 and parts[0] == "api" and parts[1] == "export": - menu = EXPORT_MENU.get(parts[2] if len(parts) > 2 else "") + name = parts[2] if len(parts) > 2 else "" + menu = EXPORT_MENU.get(name) + if menu is None: + # fail-closed:新增 /export/* 必须先在 EXPORT_MENU 登记归属菜单,否则一律 403, + # 不会出现「忘了挂权限、任何登录用户都能下载」的窗口。 + raise HTTPException(status_code=403, detail=f"导出接口「{name}」未登记权限归属,禁止访问") elif len(parts) >= 2 and parts[0] == "api": menu = SEGMENT_MENU.get(parts[1]) else: diff --git a/tests/test_api_contract.py b/tests/test_api_contract.py new file mode 100644 index 0000000..9166279 --- /dev/null +++ b/tests/test_api_contract.py @@ -0,0 +1,53 @@ +# 接口契约:错误信息语言、健康检查、导出权限 fail-closed、操作日志服务端分页 +import pytest +from fastapi import HTTPException + +from app.security import EXPORT_MENU, resolve_rule + + +def test_健康检查与首页可达(h): + """README 承诺 GET /health 与 GET /,一直没进回归;补上。""" + r = h.admin.get("/health") + assert r.status_code == 200 + body = r.json() + assert body["ok"] is True and "boot" in body and "db" in body + r = h.admin.get("/") + assert r.status_code == 200 + assert "DMS管理平台" in r.text + + +def test_校验失败返回中文detail(h): + """FastAPI 默认 422 detail 是英文(Field required),前端会原样 toast——必须已换成中文。""" + r = h.admin.post("/api/projects", json={}) + assert r.status_code == 422 + detail = r.json()["detail"] + assert detail.startswith("提交的数据有误") and "name" in detail + assert "Field required" not in detail + # 查询参数越界同样走中文(limit ge=1) + r = h.admin.get("/api/rbac/logs", params={"limit": 0}) + assert r.status_code == 422 and "格式不正确" in r.json()["detail"] + + +def test_未登记导出接口fail_closed(): + """/export/* 一律按 EXPORT_MENU 判权限;没登记的导出名不允许 fail-open 成「登录即可下载」。""" + assert set(EXPORT_MENU) >= {"custom", "custom-updates", "projects", "updates", "staff", "focus"} + for name, menu in EXPORT_MENU.items(): + assert resolve_rule("/api/export/" + name, "GET") == (menu, False) + with pytest.raises(HTTPException) as e: + resolve_rule("/api/export/not-registered", "GET") + assert e.value.status_code == 403 + + +def test_操作日志服务端分页(h): + """前端翻页发 limit/offset:跨页不重不漏,total 是全量而非当前页。""" + for i in range(3): + h.category(f"日志分页{i}") + total = h.admin.get("/api/rbac/logs", params={"days": 30, "limit": 1000}).json()["total"] + assert total >= 3 + p0 = h.admin.get("/api/rbac/logs", params={"days": 30, "limit": 2, "offset": 0}).json() + p1 = h.admin.get("/api/rbac/logs", params={"days": 30, "limit": 2, "offset": 2}).json() + assert p0["total"] == p1["total"] == total + assert len(p0["items"]) == 2 and len(p1["items"]) == 2 + ids0 = {x["id"] for x in p0["items"]} + ids1 = {x["id"] for x in p1["items"]} + assert not (ids0 & ids1) diff --git a/web/app.js b/web/app.js index a3e30b1..da58313 100644 --- a/web/app.js +++ b/web/app.js @@ -3582,7 +3582,14 @@ }; let sessions = [], logs = { total: 0, items: [] }; if (tab === "sessions") sessions = await api("/rbac/sessions"); - if (tab === "logs") logs = await api("/rbac/logs" + rbacLogQuery()); + if (tab === "logs") { + logs = await api("/rbac/logs" + rbacLogQuery()); + // 筛选后当前页可能越过末尾(比如日志刚被清空):退回第 1 页再取一次 + if (logs.total > 0 && !logs.items.length) { + state.pager.rbacLog = 1; + logs = await api("/rbac/logs" + rbacLogQuery()); + } + } const tabs = `
` + RBAC_TABS.map(([k, label]) => ``).join("") + `
`; @@ -3765,9 +3772,12 @@ } /* ---- tab 4:操作日志 ---- */ + /** 日志是唯一走服务端分页的列表:写日志量大,一次拉全量不划算。 + 页码 / 每页条数改的是本查询的 offset / limit,翻页 = 重新请求。 */ function rbacLogQuery() { const f = state.rbacLog; - const p = ["days=" + f.days, "limit=200"]; + const page = Math.max(1, state.pager.rbacLog || 1); + const p = ["days=" + f.days, "limit=" + state.pageSize, "offset=" + (page - 1) * state.pageSize]; if (f.username) p.push("username=" + encodeURIComponent(f.username)); if (f.menu) p.push("menu=" + encodeURIComponent(f.menu)); if (f.action) p.push("action=" + encodeURIComponent(f.action)); @@ -3788,7 +3798,7 @@ 时间操作人动作菜单接口状态说明 - ${pagedRows(items, "rbacLog").map((x) => ` + ${items.map((x) => ` ${esc((x.created_at || "").replace("T", " ").slice(0, 19))} ${esc(x.username || "—")} ${esc(label(x.action))} @@ -3800,7 +3810,7 @@ `; return listCard({ title: "操作日志", count: data.total, rows: items, table: table, empty: "这个时间段没有操作记录", - pager: pagerBar("rbacLog", items.length), + pager: pagerBar("rbacLog", data.total || 0), tools: `` + sel("lgMenu", "", menus, f.menu) + sel("lgAction", "", actions, f.action) + sel("lgDays", "", days, f.days) + (rw ? `` : ""), @@ -3814,13 +3824,14 @@ input.addEventListener("keydown", (e) => { if (e.key !== "Enter") return; e.preventDefault(); - f.username = input.value.trim(); renderRbac(); + f.username = input.value.trim(); state.pager.rbacLog = 1; renderRbac(); }); - input.addEventListener("search", () => { f.username = input.value.trim(); renderRbac(); }); + input.addEventListener("search", () => { f.username = input.value.trim(); state.pager.rbacLog = 1; renderRbac(); }); } const bindSel = (id, key, cast) => { const el = $("#" + id); - if (el) el.addEventListener("change", () => { f[key] = cast ? cast(el.value) : el.value; renderRbac(); }); + // 改筛选 = 换查询条件,日志页码回 1 + if (el) el.addEventListener("change", () => { f[key] = cast ? cast(el.value) : el.value; state.pager.rbacLog = 1; renderRbac(); }); }; bindSel("lgMenu", "menu"); bindSel("lgAction", "action");