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 条）
这个提交包含在：
@@ -0,0 +1,123 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
"""WorkBuddy Portal —— 独立 Flask 项目。
|
||||
|
||||
一个程序管全部：
|
||||
* 采集：进程内调度线程按配置的时刻调用云端接口，增量写入 SQLite
|
||||
* 存储：SQLite 单文件正本（WAL），去重靠主键，聚合下推 SQL
|
||||
* 呈现：Jinja 负责配置/任务/日志/明细；ECharts 大屏独立成页，数据走 /api/*
|
||||
* 鉴权：局域网可访问 ⇒ 必须有登录，cookie 等凭证存数据库由后台页面维护
|
||||
|
||||
用法：
|
||||
python manage.py init 初始化数据库（建表 + 默认配置 + 管理员）
|
||||
python manage.py serve 启动 Web（默认 0.0.0.0:8848，含调度线程）
|
||||
python manage.py collect 执行一次增量采集（CLI，不影响 Web）
|
||||
...
|
||||
"""
|
||||
import logging
|
||||
import os
|
||||
from datetime import timedelta
|
||||
from logging.handlers import RotatingFileHandler
|
||||
|
||||
from flask import Flask, jsonify, render_template, request
|
||||
|
||||
from . import config, db, security
|
||||
|
||||
__version__ = "1.1.0"
|
||||
PROJECT_NAME = config.PROJECT_NAME
|
||||
|
||||
|
||||
def _setup_logging(app):
|
||||
config.ensure_dirs()
|
||||
handler = RotatingFileHandler(config.APP_LOG, maxBytes=2 * 1024 * 1024,
|
||||
backupCount=3, encoding="utf-8")
|
||||
handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)-7s [%(name)s] %(message)s"))
|
||||
handler.setLevel(logging.INFO)
|
||||
root = logging.getLogger()
|
||||
if not any(isinstance(h, RotatingFileHandler) and getattr(h, "baseFilename", "") == handler.baseFilename
|
||||
for h in root.handlers):
|
||||
root.addHandler(handler)
|
||||
root.setLevel(logging.INFO)
|
||||
app.logger.info("启动 %s v%s（db=%s）", __name__, __version__, config.SQLITE_PATH)
|
||||
|
||||
|
||||
def create_app(start_scheduler=True, do_init_db=True, **overrides):
|
||||
app = Flask(__name__,
|
||||
template_folder="web/templates",
|
||||
static_folder="web/static",
|
||||
static_url_path="/static")
|
||||
app.config.update(
|
||||
SECRET_KEY=config.secret_key(),
|
||||
PERMANENT_SESSION_LIFETIME=timedelta(hours=config.SESSION_HOURS),
|
||||
SESSION_COOKIE_HTTPONLY=True,
|
||||
SESSION_COOKIE_SAMESITE="Lax",
|
||||
SESSION_COOKIE_NAME="workbuddy_portal_sid",
|
||||
MAX_CONTENT_LENGTH=4 * 1024 * 1024,
|
||||
TEMPLATES_AUTO_RELOAD=True,
|
||||
SEND_FILE_MAX_AGE_DEFAULT=0,
|
||||
)
|
||||
app.config.update(overrides)
|
||||
app.json.ensure_ascii = False
|
||||
app.json.sort_keys = False
|
||||
|
||||
if do_init_db:
|
||||
db.init_db()
|
||||
|
||||
_setup_logging(app)
|
||||
security.init_app(app)
|
||||
|
||||
from .web import register as register_web
|
||||
register_web(app)
|
||||
|
||||
@app.teardown_appcontext
|
||||
def _close(exc=None):
|
||||
db.close_db(exc)
|
||||
|
||||
# ---- 错误处理 ----
|
||||
@app.errorhandler(404)
|
||||
def _404(e):
|
||||
if request.path.startswith("/api/"):
|
||||
return jsonify({"ok": False, "error": "not_found", "message": "接口不存在"}), 404
|
||||
return render_template("error.html", code=404, message="页面不存在"), 404
|
||||
|
||||
@app.errorhandler(400)
|
||||
def _400(e):
|
||||
if request.path.startswith("/api/"):
|
||||
return jsonify({"ok": False, "error": "bad_request", "message": str(e)}), 400
|
||||
return render_template("error.html", code=400, message=str(e)), 400
|
||||
|
||||
@app.errorhandler(403)
|
||||
def _403(e):
|
||||
if request.path.startswith("/api/"):
|
||||
return jsonify({"ok": False, "error": "forbidden", "message": "没有权限"}), 403
|
||||
return render_template("error.html", code=403, message="没有权限"), 403
|
||||
|
||||
@app.errorhandler(500)
|
||||
def _500(e):
|
||||
app.logger.exception("内部错误")
|
||||
if request.path.startswith("/api/"):
|
||||
return jsonify({"ok": False, "error": "internal", "message": "服务器内部错误"}), 500
|
||||
return render_template("error.html", code=500, message="服务器内部错误"), 500
|
||||
|
||||
@app.errorhandler(ValueError)
|
||||
def _value_error(e):
|
||||
"""参数解析类异常统一归 400（例如 base64/日期/整数解析失败）。
|
||||
|
||||
没有这层的话，一个手写的 query string 就能把 500 页面暴露出去。
|
||||
"""
|
||||
app.logger.warning("参数错误：%s", e)
|
||||
if request.path.startswith("/api/"):
|
||||
return jsonify({"ok": False, "error": "bad_request", "message": str(e)}), 400
|
||||
return render_template("error.html", code=400, message=str(e)), 400
|
||||
|
||||
@app.context_processor
|
||||
def _inject():
|
||||
return {"app_version": __version__, "nav_active": "",
|
||||
"project_name": config.PROJECT_NAME,
|
||||
"project_title": config.PROJECT_TITLE,
|
||||
"project_desc": config.PROJECT_DESC}
|
||||
|
||||
if start_scheduler:
|
||||
from . import scheduler
|
||||
scheduler.start_from_app(app)
|
||||
|
||||
return app
|
||||
在新工单中引用
屏蔽一个用户