fix(api): 接口契约三修——422/500 统一中文、导出权限 fail-closed、操作日志服务端分页

- 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
main
mula.liu 2026-11-04 01:11:35 +08:00
parent 417cf484b7
commit 3ea36bd2bb
5 changed files with 100 additions and 10 deletions

View File

@ -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`,容易挤窄的列(区域、负责人)在 `<td>` 上加 `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 配置状态

View File

@ -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"])

View File

@ -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:

View File

@ -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)

View File

@ -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 = `<div class="ctabs">` + RBAC_TABS.map(([k, label]) =>
`<button class="ctab ${tab === k ? "active" : ""}" data-rbactab="${k}">${label}</button>`).join("") + `</div>`;
@ -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 @@
<thead><tr>
<th class="nowrap">时间</th><th>操作人</th><th>动作</th><th>菜单</th><th>接口</th><th class="num">状态</th><th>说明</th>
</tr></thead><tbody>
${pagedRows(items, "rbacLog").map((x) => `<tr>
${items.map((x) => `<tr>
<td class="nowrap">${esc((x.created_at || "").replace("T", " ").slice(0, 19))}</td>
<td>${esc(x.username || "—")}</td>
<td>${esc(label(x.action))}</td>
@ -3800,7 +3810,7 @@
</tbody></table>`;
return listCard({
title: "操作日志", count: data.total, rows: items, table: table, empty: "这个时间段没有操作记录",
pager: pagerBar("rbacLog", items.length),
pager: pagerBar("rbacLog", data.total || 0),
tools: `<input class="search" id="lgUser" type="search" placeholder="操作人" value="${esc(f.username)}" style="width:120px;height:30px" />` +
sel("lgMenu", "", menus, f.menu) + sel("lgAction", "", actions, f.action) + sel("lgDays", "", days, f.days) +
(rw ? `<button class="btn sm" id="lgClear">清空日志</button>` : ""),
@ -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");