FitStudio 健身工作室管理系统

01 / PROJECT OVERVIEW

让问题、实现与交付连成一条线

把工作室的预约、课时余额和操作原因连起来。每一个状态变化都应有业务含义，每一次扣课都应能解释，而不只是让一个余额数字变小。

业务场景

小型私人健身工作室

使用入口

会员端 / 教练与管理端

交付状态

已上线，依据后续部署记录

工程重点

规则、隔离、事务与可追踪性

02 / BACKGROUND

项目背景

朋友经营小型健身工作室，需要管理会员、课程套餐、购课、可预约时段、余额与上课记录。手机上完成这些日常操作，比维护零散人工记录更方便。

项目围绕真实规则持续迭代：什么时候占用课时、取消何时扣课、教练取消如何补课、误扣后怎样保留证据。它是服务具体工作室的系统，不是已实现多租户的商业 SaaS。

03 / MY ROLE

个人职责

在 AI 辅助下参与需求梳理、业务规则制定、功能迭代与验收，并实践 Linux 生产部署。

• 分析工作室业务需求，把课时、取消与改期规则整理为明确场景。
• 在 AI 辅助下参与管理端与会员端开发迭代，确认用户操作和权限边界。
• 围绕状态、余额与历史记录做功能验收，并实践服务器部署与后续维护准备。

项目在 AI 辅助下完成迭代。这里展示实际参与的需求、业务判断、实现与验收，不把辅助生成等同于独立精通。

MY DECISIONS / 个人贡献与取舍

我的取舍：先解释课时为什么变化，再实现操作

我的工作从工作室的日常流程开始：会员购课后能预约多少次，哪些取消会扣课，误操作怎样恢复。这些问题必须先有统一规则，页面和数据库才能围绕同一种含义实现。开发中使用 AI 辅助，我承担需求与规则判断、功能迭代、测试验收和部署维护，而不是声称每行代码都由我独立手写。

预约只占用可用课时，不立即扣余额。规则演示（非真实会员数据）：余额为 10、待上课占用 1 时，可用为 9；正常完成后增加一笔 -1 流水，余额汇总为 9，待上课占用释放。迟取消和爽约也扣一次；教练取消只释放占用、不产生扣课流水，另安排补课。余额来自流水汇总，不是额外维护一份随时可能失配的数字。

完整链路是会员选择时段 → 身份与可用课时校验 → 创建预约并占用 → 按完成/取消/爽约结果分支 → 必要时写扣课流水并汇总余额 → 记录状态与操作事件。重复完成先返回已有状态；其他非法状态明确拒绝。改期生成替代预约，取消判断用新时间，会员成功自行改期后锁定再次自主取消/改期。每次操作仍要确认当次规则。

权限隔离需要在服务端重新确认会员绑定，不能信任前端传来的会员编号；身份、规则、状态变更在事务中处理。SQLite 使用 IMMEDIATE 事务与锁忙重试提示，不把 select_for_update 描述成 SQLite 行锁，也不据此宣称已经证明高并发能力。

部署上，浏览器经 HTTPS/Caddy 到 Gunicorn、Django 和 SQLite，应用使用 Docker。持久化、迁移、静态资源检查和发布前备份有历史记录；回滚需兼顾新业务账目，不能拿旧库直接覆盖。教练端与会员端已上线；历史多阶段测试记录存在，但最新完整会员手机流程、流水联调及恢复演练仍需补齐签字。

依据：RC1 studio/services.py:161–163,306–372；portal_services.py:19–35,100–111,134–192；portal_access.py:6–15；已有脱敏部署记录。

04 / TECH STACK

技术选择，要能解释用途

Python + Django

服务端模板、表单、会员登录、业务服务、权限与事务。

SQLite + Django ORM

记录会员、套餐、预约、流水及操作事件，以流水汇总余额。

HTML / CSS / JavaScript

手机优先页面、逐次确认和预约交互，服务端仍负责最终校验。

Docker + Gunicorn

容器运行 Django，持久化数据并输出服务日志。

Caddy + HTTPS

为用户访问提供反向代理与加密入口，不公开后端应用监听端口。

05 / SYSTEM ARCHITECTURE

系统架构

06 / CORE FEATURES

核心功能

07 / TECHNICAL CHALLENGES

技术难点：把业务例外放进设计

规则之间存在依赖：只在页面上隐藏按钮不够，只给扣课函数加一个判断也不够。约束必须进入服务层、数据模型和可核对的记录。

• 把复杂业务规则变成状态与记录 ↓
• 重复请求与竞争不能重复扣课 ↓
• 余额、流水与状态必须同时成立 ↓
• 会员隔离要在服务端再次检查 ↓
• 部署完成之后仍需要可维护 ↓

08 / SOLUTIONS

解决方案

SOURCE EXCERPT

代码节选：从实现看取舍

完成操作对已完成预约直接返回，拒绝不合适状态和提前完成，再调用统一扣课并写事件。并发保护还依赖 operation 装饰器和数据库约束，不能只从这一个判断推断全部保证。

@operation("complete_booking")
def complete_booking(booking_id, *, actor, reason="确认课程完成"):
    reason = _reason(reason)
    booking = _get(Booking, booking_id)
    if booking.status == Booking.Status.COMPLETED:
        return booking
    if booking.status != Booking.Status.PENDING:
        raise BusinessError("仅待上课预约可以确认完成。")
    if booking.ends_at > timezone.now():
        raise BusinessError("课程尚未结束，不能提前确认完成。")
    _consume(booking, LessonEntry.Kind.COMPLETE, actor, reason, booking.ends_at)
    booking.status = Booking.Status.COMPLETED
    booking.save(update_fields=["status", "updated_at"])
    _event(booking, "complete", actor, reason, before="pending", after="completed")
    return booking

DEVELOPMENT PROCESS

开发过程

按现有实现与版本资料整理阶段，不推断未经确认的具体开发日期。

1. 01

   需求与规则先行

   围绕工作室真实日常确认预约占用、取消时限、补课和冲正，逐步形成可说明的状态流转。

2. 02

   从管理操作扩展到会员入口

   在管理端基础上增加会员账户、可用时段、预约与记录，并把归属检查、规则确认和自主改期锁定落到服务层。

3. 03

   形成测试依据与部署交付

   保留关键规则、重复操作和竞争场景的回归设计；后续 RC1 记录包含迁移、容器健康与 HTTPS 验证，不把早期部署准备文档当作最终状态。

09 / TESTING & VALIDATION

测试与验收

早期源码保存了扣课、改期和 SQLite 竞争等回归测试；较新交付包提供会员端实现，但该包未附完整测试源码。下面区分已有测试依据与应继续执行的验收设计。

• ↳

  预约不扣余额，完成只扣一次

  已有早期测试检查余额与可用课时区别，并验证重复完成不重复记账。

  早期回归：studio/tests/test_bookings.py:test_booking_reserves_available_but_does_not_deduct_ledger / test_complete_deducts_once_and_records_event
• ↳

  改期、教练取消与补课

  已有早期测试检查新日期的取消规则、冲突回滚、补课来源以及一次扣课。

  早期回归：studio/tests/test_m5_confirmed_rules.py · test_m4_rules.py
• ↳

  并发与事务中途失败

  已有文件 SQLite + 独立连接的竞争测试，检查同时完成、时段争用、锁等待和回滚。

  早期回归：studio/tests/test_concurrency.py · test_bookings.py:test_failure_between_ledger_and_state_rolls_back
• ↳

  会员归属、逐次确认与自主锁定

  已核验 _owned、_rule、member_locked 等实现。验收设计：伪造他人预约应拒绝；旧规则需重确认；一次自主改期后再次取消/改期应拒绝。

  RC1 源码核验 / 后续验收设计：studio/portal_services.py:38–192
• ↳

  生产切换与后续验收

  历史 RC1 记录包含迁移、健康状态和 HTTPS/静态资源检查；完整正式版身份隔离与扣课联调、长期运行和恢复演练仍需明确。

  后续部署记录：DEPLOYMENT_RESULT.md（已脱敏核对）

以上为业务项目源码中的验证设计与测试依据。本轮验证的是作品集网站，没有重新运行这些业务项目的完整测试，也没有对线上系统做操作。

11 / FUTURE IMPROVEMENTS

未来规划

以下是后续改进方向，不是已完成能力。

• 规划在授权测试环境补齐正式版完整角色隔离、预约—取消—改期—锁定—扣课链路的可复现验收。
• 规划建立明确的备份保留、恢复责任和恢复演练记录。
• 规划基于真实使用反馈改善手机操作和业务反馈，不先引入复杂服务。
• 规划有真实并发需求后评估 PostgreSQL 与压力测试，而不是宣称现有 SQLite 已解决所有并发场景。

PROJECT GALLERY

项目截图与输出示例

这张是真实教练端首页：展示新增会员、查看会员、创建预约及今日课程入口。空状态不证明完整会员流程验收；会员端、预约过程与脱敏验收截图尚待补充。

已展示使用者提供的真实界面。脱敏报表和更多业务场景待补充；不以空数据截图证明识别准确率、运营规模或完整验收。