chore: 项目定名为 workbuddy-portal,容器化并补齐文档体系

## 项目定名
- 目录 wb_usage_portal → workbuddy-portal
- Python 包 wb_usage → workbuddy_portal(含 session cookie 名)
- 界面品牌统一为 WorkBuddy Portal;项目标识收敛到 config 单一来源

## 容器化
- Dockerfile:多阶段构建,依赖层与源码解耦;非 root(uid 1000);内置健康检查
- docker-compose.yml:单服务 + 绑定挂载 data/logs + 日志轮转 + TZ
- docker/entrypoint.sh:幂等初始化 → exec serve(LF 行尾,已由 .gitattributes 锁定)
- docker/healthcheck.py:纯标准库探活 /login(slim 镜像无 curl)
- .dockerignore / .env.example;数据目录可用 WB_DATA_DIR 等环境变量覆盖

## 文档
- docs/USER-GUIDE.md    用户使用手册(含 9 张真实界面截图)
- docs/DEPLOYMENT.md    部署运维(Docker / 裸机 / 反代 / 备份 / 推 Gitea 注册表)
- docs/ARCHITECTURE.md  架构与设计说明(含已知坑与红线、验证体系)
- docs/API.md           接口参考(路径 / 参数 / 返回结构 / 错误码)
- docs/FAQ.md           常见问题;docs/CHANGELOG.md 变更日志

## 修复缺陷(8)
1. /records/export 必然 500:生成器在请求上下文销毁后才迭代,改用自建连接
2. 大屏页图表全白:相对路径把 echarts.min.js 解析成 /vendor/... → 404
3. /users 500:路由已注册但模板缺失
4. 明细页日期筛选失效:视图传 f.frm、模板读 f.from
5. 配置页维护按钮全死:调用了不存在的 WBU.bindMaint()
6. 审计只能看最近 40 条:LIMIT 写死
7. 明细页多跑一条无用 SELECT:day_list() 取了没人用
8. 登录页锁定阈值未从配置注入

## 安全加固
- 新增 safe_next():拒绝 //evil.com 等协议相对 URL 的开放重定向
- 缺 CSRF 的写请求统一 400
- 默认开启云端 HTTPS 证书校验(ssl_verify=1);Cookie 是账号凭证
- 登录失败计数表加上限与 TTL
- /logout 拆分为 POST(执行) + GET(仅提示),防 <img src=/logout> 静默退出
- settings 内部簿记键 slot:* 读写两侧过滤,不再从 /api/settings 泄漏

## 内部质量与工具
- 设置项写时校验 + 读时兜底,杜绝「一个手滑的数字让采集整个跑不起来」
- 全局 ValueError → 400:手写 query string 不再暴露 500 页面
- CSV 导出改 csv.writer 流式写入(原手工拼串,字段含逗号会串列)
- bundle 明细加 20000 上限并回传 recordsTotal/recordsTruncated,不静默丢数据
- tools/smoke.py 离线回归 99 项;tools/check_live.py 真实 HTTP 56 项
- tools/shots.py Playwright 逐页截图 + JS 报错收集

## 验证
- compileall 通过;smoke 99/99;对容器实例 check_live 56/56;截图 0 JS 报错
- 容器内采集实测成功(trigger=startup 补跑:新增 11 条)
这个提交包含在:
2026-09-14 14:55:50 +08:00
当前提交 86631ae7ab
共修改 58 个文件,包含 9409 行新增和 0 行删除
+417
查看文件
@@ -0,0 +1,417 @@
/* ============================================================
WorkBuddy Portal —— 统一视觉系统
设计令牌与大屏页(static/dashboard/index.html)保持一致,
两处用同一套色板/圆角/间距,避免后台与大屏像两个产品。
============================================================ */
:root {
/* 底色与层次 */
--bg: #080d1a;
--panel: rgba(255, 255, 255, .045);
--panel-hi: rgba(255, 255, 255, .07);
--panel-dim: rgba(0, 0, 0, .30);
--line: rgba(255, 255, 255, .09);
--line-soft: rgba(255, 255, 255, .06);
/* 文本 */
--text: #e8edf7;
--sub: #8b9bb4;
--dim: #64748b;
/* 主色板(与大屏 ECharts PALETTE 同源) */
--cyan: #22d3ee;
--violet: #a78bfa;
--amber: #fbbf24;
--green: #34d399;
--red: #f87171;
--blue: #60a5fa;
--pink: #f472b6;
/* 语义色(用量口径:升用琥珀、降用青,刻意不用红绿) */
--up: var(--amber);
--down: var(--cyan);
/* 形状与节奏 */
--r-card: 14px;
--r-ctl: 9px;
--r-pill: 6px;
--gap: 16px;
--shadow: 0 12px 34px rgba(0, 0, 0, .42);
color-scheme: dark;
}
* { box-sizing: border-box; }
html, body { margin: 0; padding: 0; }
body {
background:
radial-gradient(1100px 600px at 12% -10%, rgba(34, 211, 238, .10), transparent 60%),
radial-gradient(900px 500px at 100% 0%, rgba(167, 139, 250, .10), transparent 55%),
var(--bg);
color: var(--text);
font: 13.5px/1.65 "Microsoft YaHei", "PingFang SC", system-ui, -apple-system,
"Segoe UI", Roboto, Helvetica, Arial, sans-serif;
min-height: 100vh;
-webkit-font-smoothing: antialiased;
}
a { color: var(--cyan); text-decoration: none; transition: color .15s; }
a:hover { text-decoration: underline; }
/* 表单控件必须显式继承字体:曾经写过 `font: 13px/1.5 inherit`,
那是非法声明(简写里不能出现 inherit 作为字族),整条被浏览器丢弃,
结果输入框用回浏览器默认字体,与页面格格不入。 */
button, input, select, textarea { font-family: inherit; font-size: 13px; }
code {
background: rgba(255, 255, 255, .07); padding: 1px 5px; border-radius: 4px;
font: 12px/1.5 ui-monospace, Consolas, "Cascadia Mono", monospace;
color: var(--cyan);
}
.mono, .logbox, .fullprompt {
font-family: ui-monospace, Consolas, "Cascadia Mono", monospace;
}
.mono { font-size: 12px; }
.sm { font-size: 11.5px; }
.nowrap { white-space: nowrap; }
.num, .tabular { font-variant-numeric: tabular-nums; }
.muted { color: var(--sub); }
.right { text-align: right; }
/* 页面标题里嵌的关键数字(如总积分),给一点强调但不喧宾夺主 */
.hl { color: var(--cyan); font-variant-numeric: tabular-nums; }
/* 0 积分的记录整行数字变暗,扫一眼就能跳过长尾 */
.tbl td.zero { color: var(--dim); }
/* 可访问性:键盘焦点一定要看得见 */
:focus-visible { outline: 2px solid rgba(34, 211, 238, .65); outline-offset: 2px; }
/* ---------------- 顶栏 ---------------- */
.topbar {
display: flex; align-items: center; gap: 18px;
padding: 0 22px; height: 58px;
background: rgba(10, 16, 28, .86);
border-bottom: 1px solid var(--line);
backdrop-filter: blur(10px);
position: sticky; top: 0; z-index: 50;
}
.brand { display: flex; align-items: center; gap: 9px; font-size: 14px; letter-spacing: .2px; }
.brand a { color: var(--text); }
.brand a:hover { text-decoration: none; color: var(--cyan); }
.brand .dot {
width: 9px; height: 9px; border-radius: 50%; background: var(--cyan);
box-shadow: 0 0 12px var(--cyan); flex: 0 0 auto;
}
.brand .ver { color: var(--dim); font-size: 11px; }
.topbar nav { display: flex; gap: 3px; margin-left: 6px; overflow-x: auto; }
.topbar nav a {
padding: 6px 13px; border-radius: var(--r-ctl); color: var(--sub);
font-size: 13px; white-space: nowrap; position: relative;
}
.topbar nav a:hover { background: var(--panel-hi); color: var(--text); text-decoration: none; }
.topbar nav a.on {
background: linear-gradient(135deg, rgba(34, 211, 238, .22), rgba(167, 139, 250, .22));
color: #fff; font-weight: 600;
}
.topbar .me { margin-left: auto; display: flex; align-items: center; gap: 10px; flex: 0 0 auto; }
.topbar .who { color: var(--sub); font-size: 12.5px; }
.topbar .who b { color: var(--text); font-weight: 600; }
/* ---------------- 布局 ---------------- */
.wrap { max-width: 1480px; margin: 0 auto; padding: 20px 22px 60px; }
.pagehead {
display: flex; align-items: flex-end; justify-content: space-between;
gap: 14px; flex-wrap: wrap; margin-bottom: var(--gap);
}
.pagehead h1 {
font-size: 20px; margin: 0; font-weight: 700; letter-spacing: .3px;
display: flex; align-items: center; gap: 10px;
}
.pagehead h1::before {
content: ""; width: 4px; height: 19px; border-radius: 2px;
background: linear-gradient(180deg, var(--cyan), var(--violet)); flex: 0 0 auto;
}
.pagehead .lead { color: var(--sub); font-size: 12.5px; margin: 4px 0 0 14px; }
.pagehead .actions { display: flex; gap: 10px; flex-wrap: wrap; }
.grid2 { display: grid; grid-template-columns: 1fr 1fr; gap: var(--gap); margin-bottom: var(--gap); }
.grid3 { display: grid; grid-template-columns: repeat(auto-fit, minmax(240px, 1fr)); gap: var(--gap); margin-bottom: var(--gap); }
/* ---------------- 卡片 ---------------- */
.card {
background: var(--panel);
border: 1px solid var(--line); border-radius: var(--r-card);
padding: 16px 18px; margin-bottom: var(--gap);
}
.card > h2, .card > .cardhead > h2 {
font-size: 14px; margin: 0 0 12px; font-weight: 600; letter-spacing: .2px;
display: flex; align-items: center; gap: 8px; flex-wrap: wrap;
}
.card > .cardhead > h2 { margin-bottom: 0; }
.card > h2::before, .card > .cardhead > h2::before {
content: ""; width: 3px; height: 13px; border-radius: 2px;
background: var(--cyan); flex: 0 0 auto;
}
.cardhead {
display: flex; align-items: center; justify-content: space-between;
gap: 12px; flex-wrap: wrap; margin-bottom: 12px;
}
.cardhead > h2 { margin-bottom: 0; }
.card h3 { font-size: 13px; margin: 18px 0 10px; font-weight: 600; color: var(--text); }
.card h3:first-child { margin-top: 0; }
.hint { color: var(--sub); font-size: 12px; line-height: 1.75; }
.hint a { text-decoration: underline; text-decoration-color: rgba(34, 211, 238, .4); }
.card > .hint:last-child { margin-bottom: 0; }
.sect-divider { border: 0; border-top: 1px solid var(--line); margin: 18px 0; }
/* ---------------- KPI ---------------- */
.kpis {
display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
gap: 14px; margin-bottom: var(--gap);
}
.kpi {
background: var(--panel); border: 1px solid var(--line); border-radius: var(--r-card);
padding: 14px 16px; position: relative; overflow: hidden;
}
.kpi::after {
content: ""; position: absolute; left: 0; top: 0; width: 3px; height: 100%;
background: var(--c, var(--cyan));
}
.kpi > span { color: var(--sub); font-size: 12px; display: block; letter-spacing: .2px; }
.kpi > b {
display: block; font-size: 23px; margin: 7px 0 4px; font-weight: 700;
font-variant-numeric: tabular-nums; letter-spacing: .3px;
}
.kpi > i { color: var(--sub); font-size: 11.5px; font-style: normal; display: block; }
.kpi > i .delta { color: var(--up); font-variant-numeric: tabular-nums; }
.kpi > i .delta.dn { color: var(--down); }
/* ---------------- 表格 ---------------- */
/* 表格必须包在 .tablewrap 里:窄屏时横向滚动,而不是把卡片撑破 */
.tablewrap { overflow-x: auto; margin: 0 -2px; }
.tablewrap::-webkit-scrollbar { height: 8px; }
.tablewrap::-webkit-scrollbar-thumb { background: rgba(255, 255, 255, .14); border-radius: 4px; }
.tbl { width: 100%; border-collapse: collapse; font-size: 12.5px; }
.tbl th, .tbl td {
padding: 9px 10px; text-align: left; border-bottom: 1px solid var(--line-soft);
vertical-align: top;
}
.tbl th {
color: var(--sub); font-weight: 500; font-size: 11.5px;
white-space: nowrap; letter-spacing: .3px;
position: sticky; top: 0; background: rgba(12, 18, 32, .96);
backdrop-filter: blur(4px); z-index: 1;
}
.tbl tbody tr:hover { background: rgba(255, 255, 255, .028); }
.tbl tbody tr:last-child td { border-bottom: 0; }
.tbl td.num, .tbl th.num { text-align: right; font-variant-numeric: tabular-nums; white-space: nowrap; }
.tbl td.empty, .tbl td.empty:hover { text-align: center; color: var(--sub); padding: 28px; }
.tbl td.px { max-width: 460px; min-width: 220px; }
.tbl details summary { cursor: pointer; color: var(--sub); }
.tbl details summary:hover { color: var(--text); }
.tbl details[open] summary { color: var(--cyan); }
.scroll-y { max-height: 340px; overflow: auto; }
.kv { width: 100%; border-collapse: collapse; font-size: 12.5px; }
.kv th {
width: 118px; color: var(--sub); text-align: left; font-weight: 500;
padding: 7px 10px 7px 0; vertical-align: top; white-space: nowrap;
}
.kv td { padding: 7px 0; }
.fullprompt {
margin-top: 9px; padding: 11px 13px; background: var(--panel-dim);
border: 1px solid var(--line); border-radius: 8px;
white-space: pre-wrap; word-break: break-word; color: var(--text);
font-size: 12px; line-height: 1.75; max-height: 320px; overflow: auto;
}
/* ---------------- 标签 / 徽章 ---------------- */
.tag {
display: inline-block; padding: 1px 7px; border-radius: var(--r-pill);
font-size: 11px; line-height: 17px; white-space: nowrap;
background: rgba(255, 255, 255, .08); color: var(--sub); vertical-align: 1px;
}
.tag.ok { background: rgba(52, 211, 153, .16); color: var(--green); }
.tag.warn { background: rgba(251, 191, 36, .16); color: var(--amber); }
.tag.bad { background: rgba(248, 113, 113, .16); color: var(--red); }
.tag.info { background: rgba(96, 165, 250, .16); color: var(--blue); }
.tag.accent { background: rgba(167, 139, 250, .18); color: var(--violet); }
.tag.mute { background: rgba(255, 255, 255, .06); color: var(--dim); }
.kbd {
display: inline-block; padding: 0 6px; border-radius: 4px;
border: 1px solid var(--line); background: var(--panel-dim);
font: 11.5px/18px ui-monospace, Consolas, monospace; color: var(--sub);
}
/* ---------------- 按钮 ---------------- */
.btn {
display: inline-flex; align-items: center; justify-content: center; gap: 6px;
padding: 7px 14px; border-radius: var(--r-ctl); border: 1px solid var(--line);
background: var(--panel-hi); color: var(--text); font-size: 12.5px;
cursor: pointer; transition: background .15s, border-color .15s, box-shadow .15s, filter .15s;
white-space: nowrap; text-decoration: none;
}
.btn:hover { background: rgba(255, 255, 255, .11); text-decoration: none; }
.btn.primary {
background: linear-gradient(135deg, rgba(34, 211, 238, .26), rgba(167, 139, 250, .26));
border-color: rgba(34, 211, 238, .42); color: #fff; font-weight: 600;
}
.btn.primary:hover { border-color: var(--cyan); box-shadow: 0 0 14px rgba(34, 211, 238, .22); }
.btn.ghost { background: transparent; color: var(--sub); }
.btn.ghost:hover { color: var(--text); background: var(--panel-hi); }
.btn.danger { border-color: rgba(248, 113, 113, .34); color: var(--red); background: rgba(248, 113, 113, .10); }
.btn.danger:hover { background: rgba(248, 113, 113, .18); }
.btn.sm { padding: 4px 10px; font-size: 12px; }
.btn[disabled], .btn[aria-disabled=true] { opacity: .5; cursor: not-allowed; }
.btnrow { display: flex; gap: 8px; flex-wrap: wrap; align-items: center; }
form .btn { margin-top: 8px; }
/* ---------------- 表单 ---------------- */
label { display: block; color: var(--sub); font-size: 12px; }
label input, label select, label textarea, .inp {
width: 100%; margin-top: 5px; padding: 8px 10px; border-radius: 8px;
background: var(--panel-dim); border: 1px solid var(--line); color: var(--text);
font-size: 13px; line-height: 1.5; outline: none; transition: border-color .15s, background .15s;
}
label input:hover, label select:hover, label textarea:hover { border-color: rgba(255, 255, 255, .16); }
label input:focus, label select:focus, label textarea:focus {
border-color: var(--cyan); background: rgba(0, 0, 0, .42);
}
label textarea {
font-family: ui-monospace, Consolas, "Cascadia Mono", monospace;
font-size: 12px; line-height: 1.6; resize: vertical;
}
label.col { margin-bottom: 13px; }
label.row { display: flex; align-items: center; gap: 12px; margin-bottom: 11px; }
label.row > span { flex: 0 0 132px; }
label.row input, label.row select { margin-top: 0; }
label.row.inline { display: inline-flex; margin-bottom: 0; }
label.row.inline > span { flex: 0 0 auto; }
label .unit { color: var(--dim); font-size: 11.5px; margin-left: 8px; flex: 0 0 auto; }
.field-err { color: var(--red); font-size: 11.5px; margin-top: 4px; }
select option { background: #111a2e; color: var(--text); }
.filters { display: flex; flex-wrap: wrap; gap: 12px; align-items: flex-end; }
.filters label { flex: 1 1 152px; }
.filters label input, .filters label select { min-width: 110px; }
.filters .btn { margin-top: 0; }
/* 快捷区间按钮组:卡片标题右侧、筛选条里都可能出现,所以不限定父级 */
.quick { display: flex; gap: 6px; flex-wrap: wrap; align-items: center; }
/* 行内小输入框(用户列表里直接改显示名/权限) */
.inp-sm { padding: 4px 8px; font-size: 12px; margin-top: 0; width: auto; min-width: 96px; }
.tbl select.inp-sm { min-width: 84px; }
/* 分段控件(与大屏页 .seg 一致) */
.seg {
display: inline-flex; background: var(--panel-hi); border: 1px solid var(--line);
border-radius: var(--r-ctl); overflow: hidden;
}
.seg a, .seg button {
background: transparent; border: 0; color: var(--sub); padding: 5px 12px;
font-size: 12.5px; cursor: pointer; transition: .15s; font-family: inherit;
text-decoration: none; white-space: nowrap;
}
.seg a:hover, .seg button:hover { color: var(--text); background: rgba(255, 255, 255, .06); text-decoration: none; }
.seg a.on, .seg button.on {
background: linear-gradient(135deg, rgba(34, 211, 238, .28), rgba(167, 139, 250, .28));
color: #fff; font-weight: 600;
}
/* ---------------- 分页 ---------------- */
.pager { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 14px; align-items: center; }
.pager a, .pager .cur, .pager .gap {
padding: 4px 11px; border-radius: 7px; border: 1px solid var(--line);
font-size: 12px; color: var(--sub); min-width: 34px; text-align: center;
}
.pager a:hover { color: var(--text); border-color: rgba(34, 211, 238, .45); text-decoration: none; }
.pager .cur {
background: linear-gradient(135deg, rgba(34, 211, 238, .24), rgba(167, 139, 250, .24));
color: #fff; border-color: transparent; font-weight: 600;
}
.pager .gap { border-color: transparent; color: var(--dim); }
.pager .meta { margin-left: auto; color: var(--sub); font-size: 11.5px; }
/* ---------------- 提示 / 日志 ---------------- */
.flashes { margin-bottom: var(--gap); }
.flash {
padding: 11px 14px; border-radius: var(--r-ctl); font-size: 12.5px;
margin-bottom: 8px; border: 1px solid var(--line);
background: rgba(34, 211, 238, .10); color: var(--text);
line-height: 1.7;
}
.flash.error { background: rgba(248, 113, 113, .12); border-color: rgba(248, 113, 113, .3); }
.flash.warn { background: rgba(251, 191, 36, .12); border-color: rgba(251, 191, 36, .3); }
.flash.ok { background: rgba(52, 211, 153, .12); border-color: rgba(52, 211, 153, .3); }
.flash:last-child { margin-bottom: 0; }
.logbox {
background: rgba(0, 0, 0, .40); border: 1px solid var(--line); border-radius: var(--r-ctl);
padding: 12px 14px; max-height: 430px; overflow: auto; margin: 0;
font-size: 11.5px; line-height: 1.75; white-space: pre-wrap;
word-break: break-word; color: #c6d3e6;
}
.logbox:empty::before { content: "(暂无内容)"; color: var(--dim); }
.empty-state {
padding: 34px 16px; text-align: center; color: var(--sub); font-size: 12.5px;
border: 1px dashed var(--line); border-radius: var(--r-ctl);
}
.empty-state b { display: block; color: var(--text); font-size: 13.5px; margin-bottom: 6px; font-weight: 600; }
/* ---------------- 登录 ---------------- */
.loginwrap {
display: flex; align-items: center; justify-content: center;
min-height: calc(100vh - 140px); padding: 24px 16px;
}
.login { width: 100%; max-width: 400px; padding: 28px 28px 22px; margin: 0; }
.login .logo {
width: 44px; height: 44px; border-radius: 13px; margin-bottom: 14px;
background: linear-gradient(135deg, var(--cyan), var(--violet));
display: flex; align-items: center; justify-content: center;
font-size: 20px; font-weight: 800; color: #061019;
}
.login h1 { font-size: 19px; margin: 0 0 5px; }
.login .hint { margin: 0 0 20px; }
.login label { margin-bottom: 14px; }
.login .btn { width: 100%; padding: 10px; margin-top: 4px; }
.login .foot-note {
margin: 16px 0 0; padding-top: 14px; border-top: 1px solid var(--line);
color: var(--dim); font-size: 11.5px; line-height: 1.7;
}
/* ---------------- 错误页 ---------------- */
.errpage { text-align: center; padding: 66px 24px; }
.errpage .code {
font-size: 52px; font-weight: 800; line-height: 1; margin: 0 0 12px;
background: linear-gradient(135deg, var(--cyan), var(--violet));
-webkit-background-clip: text; background-clip: text; color: transparent;
}
.errpage p { color: var(--sub); margin: 0 0 20px; }
.foot {
text-align: center; color: var(--dim); font-size: 11.5px;
padding: 18px 22px 30px; line-height: 1.9;
}
.foot code { font-size: 11px; }
/* ---------------- 响应式 ---------------- */
@media (max-width: 1100px) {
.grid2 { grid-template-columns: 1fr; }
}
@media (max-width: 820px) {
.topbar { gap: 10px; padding: 0 12px; height: auto; flex-wrap: wrap; padding-bottom: 8px; }
.topbar nav { order: 3; width: 100%; margin-left: 0; padding-bottom: 2px; }
.topbar .me { margin-left: auto; }
.wrap { padding: 14px 12px 48px; }
.pagehead { align-items: flex-start; }
.pagehead h1 { font-size: 18px; }
.kpi > b { font-size: 20px; }
label.row { flex-direction: column; align-items: stretch; gap: 4px; }
label.row > span { flex: 0 0 auto; }
.card { padding: 14px; }
.login { padding: 22px 18px 18px; }
}
@media (prefers-reduced-motion: reduce) {
* { transition: none !important; animation: none !important; }
}