HW

HW 是一个面向宴请筹备场景的 Web 管理系统，用来按“户”为单位管理邀请、出席、礼金、回礼、CSV 导入导出、审计日志和账号权限。

当前仓库已经收敛为两条主线：

1. 本地研发使用：基于仓库内 .venv、SQLite、Tailwind CSS 编译链和 pytest / Playwright 测试
2. 生产部署使用：基于 Python 3.13 容器化部署，固定使用 /opt/hw 和 /opt/hw.conf.d

---

文档入口

如果你只想快速开始，先看本 README；如果需要详细信息，再进入对应文档：

• 本地研发说明：docs/development-setup.md
• 生产部署说明：docs/production-deployment.md
• 生产运维说明：docs/production-ops.md
• 技术设计：docs/technical-design.md

---

一、项目技术基线

• 后端：Python 3 + Flask
• ORM：Flask-SQLAlchemy / SQLAlchemy 2.x
• 前端：Jinja2 SSR + jQuery 增强 + Tailwind CSS v4 CLI
• 数据库：
  • 本地研发：SQLite
  • 生产环境：MySQL（推荐）
• 测试：pytest + Playwright

当前本地常用 Python 执行方式统一为：

.venv/bin/python

当前页面与交互基线：

• 管理首页：完整后台管理，保留搜索、筛选、标签筛选、备注、CSV、审计与账号能力
• 快速录入：只服务婚礼当天的搜索、改礼金、搜不到时快速新增一户并记礼金
• 分享页面：只服务搜索、进入单独编辑页、保存后返回搜索
• 系统初始化后不预置默认标签；标签和关系分类都允许按需新增
• 户搜索统一围绕：户主、成员、拼音、标签、备注

---

二、本地研发怎么用

1. 初始化依赖

如果仓库里还没有 .venv：

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
npm install

如果 .venv 已存在，只更新依赖：

.venv/bin/python -m pip install -r requirements.txt
npm install

2. 编译前端样式

npm run build:css

如果你正在调样式，建议单独开一个终端持续监听：

npm run watch:css

相关路径：

• Tailwind 源文件：app/static/src/styles.css
• 编译输出：app/static/css/main.css

3. 一键启动本地开发环境

推荐命令：

npm run build:css
.venv/bin/python -m flask dev-bootstrap

这个命令会自动完成：

• flask db upgrade
• flask seed-all
• flask seed-demo
• 输出演示账号
• 启动本地开发服务

默认演示账号：

• admin / ChangeMe123!
• editor-demo / EditorDemo123!
• entry-demo / EntryDemo123!

如果你只想准备数据，不想启动服务：

.venv/bin/python -m flask dev-bootstrap --skip-server

4. 常用本地研发命令

运行测试：

.venv/bin/python -m pytest tests

安装 Playwright Chromium：

.venv/bin/python -m playwright install chromium

运行 E2E：

.venv/bin/python -m pytest tests/e2e -q

执行迁移：

FLASK_APP=run.py .venv/bin/flask db upgrade

生成演示数据：

FLASK_APP=run.py .venv/bin/flask seed-demo

生成压力测试数据：

FLASK_APP=run.py .venv/bin/flask seed-stress

5. 本地健康检查

启动后可访问：

GET /health

预期返回：

{
  "project": "HappyWedding",
  "short_name": "hw",
  "status": "ok"
}

---

三、生产部署怎么用

当前生产方案已经统一为：

• Python 3.13 容器化部署
• 使用 Docker --restart unless-stopped 常驻

1. 固定目录约定

• 应用目录：/opt/hw
• 配置目录：/opt/hw.conf.d
• 环境文件：/opt/hw.conf.d/hw.env
• 运行时目录：/opt/hw/instance

宿主机和容器内都使用同样的目录约定。

2. 首次部署步骤

第一步：同步代码到服务器

例如：

sudo mkdir -p /opt/hw
sudo rsync -a ./ /opt/hw/

第二步：安装 Docker 和准备目录

在仓库根目录执行：

sudo bash scripts/install-linux-container.sh

第三步：编辑生产环境变量

参考模板：

• deploy/env/hw.env.example

编辑：

sudo vi /opt/hw.conf.d/hw.env

至少配置：

HW_CONFIG=production
HW_SECRET_KEY=replace-with-a-long-random-secret
DATABASE_URL=mysql+pymysql://hw_user:replace-password@127.0.0.1:3306/hw

第四步：执行部署

sudo bash scripts/deploy-container.sh

脚本会自动完成：

• 在 /opt/hw 构建生产镜像
• 启动或替换 hw 容器
• 挂载 /opt/hw/instance
• 只读挂载 /opt/hw.conf.d
• 容器启动时自动执行 flask db upgrade
• 启动 Gunicorn

第五步：执行校验

sudo bash scripts/verify-container-deployment.sh

3. 首次空库部署时初始化基础数据

如果这是一个全新的空库，需要同时初始化基础数据：

sudo RUN_SEED_ALL=1 bash scripts/deploy-container.sh

4. 常用生产运维命令

查看容器：

docker ps --filter name=hw

查看日志：

docker logs -f hw

重启容器：

docker restart hw

重新部署最新代码：

cd /opt/hw
sudo bash scripts/deploy-container.sh
sudo bash scripts/verify-container-deployment.sh

直接检查健康接口：

curl -fsS http://127.0.0.1:8000/health

---

四、当前仓库里最重要的部署文件

• Dockerfile
• .dockerignore
• docker/entrypoint.sh
• deploy/env/hw.env.example
• scripts/generate-secrets.sh
• scripts/install-linux-container.sh
• scripts/deploy-container.sh
• scripts/verify-container-deployment.sh

---

五、补充说明

• 生产环境推荐使用 MySQL，SQLite 只适合轻量或临时环境
• 当前生产镜像构建阶段会自动编译 app/static/css/main.css
• 当前生产配置会强制要求设置 HW_SECRET_KEY 和 DATABASE_URL
• 当前项目正式对外发布前，仍建议继续补充 CSRF 等安全加固

如果你只是：

• 要做研发 → 优先看上面的“本地研发怎么用”和 docs/development-setup.md
• 要做部署 → 优先看上面的“生产部署怎么用”和 docs/production-deployment.md
• 要做运维 → 直接看 docs/production-ops.md