概述

1.1 设计目标

1.2 技术选型

2. 总体架构

2.1 分层

┌──────────────────────────────────────────────────────────┐
│ 浏览器（门店前台电脑，127.0.0.1:5000）                     │
└───────────────  HTTP（表单 / JSON） ──────────────────────┘
                          │
┌──────────────────────────────────────────────────────────┐
│ 表现层  templates/*.html + static/app.css                │
├──────────────────────────────────────────────────────────┤
│ 路由层  app/*_bp（11 个蓝图：dashboard/members/cards/      │
│         items/booking/pos/commission/inventory/reports/   │
│         system/auth）                                    │
├──────────────────────────────────────────────────────────┤
│ 横切层  auth.py（登录/权限/日志）  utils.py（金额/单号/上传/ │
│         Excel）  db.py（连接/查询辅助）                     │
├──────────────────────────────────────────────────────────┤
│ 业务层  services.py（卡资金、次卡核销、提成、库存、过期标记） │
├──────────────────────────────────────────────────────────┤
│ 数据层  SQLite：schema.sql 定义的 22 张表                  │
└──────────────────────────────────────────────────────────┘

2.2 请求生命周期

1. Flask 接收请求 → 蓝图路由匹配；

2. @login_required 校验会话，未登录重定向 /login?next=...；

3. @perm_required('x.y') 校验角色权限，不足返回 403 页面；

4. get_db() 在应用上下文内取请求级连接（g.db），开启外键约束；

5. 路由函数解析表单 → 调用 services.py 业务函数 → 同一连接内执行多次写操作；

6. 成功 commit()，业务校验失败 rollback() 并 flash 提示；

7. log_operation() 写入 operation_logs；

8. 请求结束 teardown_appcontext → close_db() 提交并关闭连接。

2.3 关键目录

2.4 前端渲染约定（离线优先）

• 零外部依赖：不使用任何 CDN、npm 包或图表库；样式全部手写在 static/app.css。

• 图表用服务端计算的 SVG：折线图的坐标、刻度、面积路径在 _area_geo() 里算好，模板只做遍历输出；环形图用 stroke-dasharray/dashoffset 分段绘制；柱状/分段条同理。好处：无 JS 即可出图、断网可用、便于截图与自动化测试断言。

• 左侧菜单用原生 <details> 分组：无需 JS 即可折叠；服务端根据 request.endpoint给分组打 open 与 active（例：进入 /members/ 时"客户中心"自动展开并高亮）。

• 菜单与快捷入口按权限渲染：模板统一判断 current_user.perms，新增权限点只需在 app/seed.py::ROLE_PERMS 注册，无需改模板结构。

• 图表数据口径：分类营收与项目热度采用"项目业绩口径"——现金结算取 order_items.amount，次卡核销取 unit_price × quantity，与技师提成的业绩基数口径保持一致。

3. 数据模型

共 22 张表，可分为 6 组。

3.1 组织与权限

3.2 会员

3.3 卡项（核心）

设计要点：储值卡消费时先扣赠送金额、再扣本金（services.consume_balance），本金与赠送分开记账，便于核算真实负债；退款时调用 services.split_refund_by_consume() 读取该订单的消费流水，按当时的本金/赠送扣款比例原路退回，避免"赠送被吃掉、本金虚增"的账务错配。

3.4 项目与商品

3.5 预约与工位

3.6 交易与库存

4. 核心业务流程

4.1 开单结算（POST /pos/checkout）

解析明细行 → 校验（次卡可用性/剩余次数）→ 计算金额
  ├─ money_subtotal = Σ(现金结算行 单价×数量)
  ├─ times_value    = Σ(次卡核销行 原价×数量)   ← 只计业绩，不参与收款
  ├─ total = max(money_subtotal − 折扣, 0)
  └─ 校验 收款组合 == total（误差 > 0.01 直接拒绝，事务回滚）
写入 orders → 写入 order_items → 实扣（余额/代金券）→ 次卡扣次（生成 usage）
→ 生成提成 → 可选耗材出库 → log_operation

• 收款方式：balance(会员余额) / cash(现金) / custom(自定义，手工记录名称，不接支付接口) / voucher(代金券)，可组合为 mixed。

• 挂单：action=hold → status=pending，不扣款、不扣次、不计提成，后续 /pos/orders/<id>/pay 补结算。

• 免单：action=free → 折扣等于小计、status=free、不计提成。

4.2 次卡核销与提成时点

• 办卡/充值不计业绩；只有在订单中核销（settle_type='times'）时才：

1. used_times += 1（用完自动置 depleted）；

2. 写 card_usage_logs（含剩余次数、技师、订单号）；

3. 按会员价作为业绩基数计提提成（该行 amount=0，不产生收款）。

• 到期处理：任何打开卡列表的请求都会调用 mark_expired_cards() 自动置 expired；冻结/过期/转让的卡 is_card_usable() 返回 False，禁止核销。

4.3 退款（POST /pos/orders/<id>/refund）

1. 回退该订单全部次卡核销次数（写负次数流水）；

2. 按原支付渠道退回：会员余额退回原储值卡（本金与赠送金额按原扣款比例拆分退回，见split_refund_by_consume()）、代金券退回面额；

3. 登记 refunds 记录；

4. 冲减该订单全部提成（amount=0，名称追加「已退款」）；

5. 订单置 refunded 并写操作日志。

4.4 提成计算（services.commission_for）

• 规则命中：commission_rules(target_type, target_id)，未命中返回 0；

• fixed：提成 = 固定金额；percent：提成 = 业绩基数 × 百分比 / 100；

• 整单折扣分摊：现金结算行按 total / subtotal 系数折算后计算，次卡核销行不打折；

• 默认种子规则：服务项目 30%、附加项固定 8 元、零售商品 10%。

4.5 库存变动（services.change_stock）

统一入口：校验变动后库存不为负 → 更新 inventory_items.stock → 写 inventory_logs（含变动前后与单位成本）。出库类型：out 领用、loss 报损、order 开单消耗；check 盘点传入实际盘点数量，自动计算差额。

5. 权限模型

权限点（16 个）：member.view、member.edit、card.manage、cashier、finance.recharge、finance.refund、inventory.view、inventory.edit、commission.view_all、commission.view_self、commission.setting、report.view、booking.view、booking.edit、staff.manage、system.backup、item.manage。

技师账号（t01/t02）登录后仅能看到自己的排班与业绩，无法看到门店财务总账。权限不足返回 403 页面（模板 templates/errors/403.html）。

6. 接口清单

6.1 认证

6.2 业务

7. 关键实现细节

8. 部署与运维

8.1 启动

推荐：一键启动脚本（自动完成环境检测 → 虚拟环境 → 依赖安装 → 启动前自检 → 启动）

启动系统.bat::正常启动（自动打开浏览器）
启动系统.bat--no-browser::不自动打开浏览器
启动系统.bat--skip-venv::跳过.venv，直接用系统Python
启动系统.bat--selftest::先跑pytest通过后再启动
启动系统.bat--help

脚本流程与容错策略：

编码注意事项（实践踩坑）

• .bat 必须存为 GBK/ANSI，且不要在脚本里 chcp 65001：UTF-8 批处理配合 chcp 会让 cmd 的文件指针按字节错位，中文行会被当作命令执行。

• .ps1 必须存为 UTF-8 with BOM：PowerShell 5.1 对无 BOM 文件按 ANSI(cp936) 解码，中文会变乱码并导致解析失败。

• .bat 换行统一 CRLF；.sh 保持 LF。

备选：命令行启动

pip install -r requirements.txt
python run.py                # 默认 5000 端口并自动打开浏览器
setNAIL_PORT=8080# Windows 换端口
setNAIL_NO_BROWSER=1# 不自动打开浏览器
setNAIL_DATA_DIR=D:\nail    # 自定义数据目录（可放U盘/网盘同步目录）

run.py 会把 stdout/stderr 重新配置为 UTF-8，避免中文提示在 Windows 控制台/重定向时乱码。

8.2 数据迁移

1. 在原机器「系统设置 → 备份恢复 → 立即备份」或点击下载 .db；

2. 新机器安装 Python + 依赖，放好代码；

3. 上传备份文件 → 点击「恢复」；或把整个 data/ 目录拷贝到新机器覆盖。

8.3 日常维护建议

• 每天下班前执行一次本地备份（data/backups/），重要时拷贝到 U 盘；

• 定期在「系统设置 → 备份恢复」下载历史备份归档；

• 需要核对账务时，用任意 SQLite 工具直接打开 data/nail.db 查询 orders、card_balance_logs、refunds。

8.4 常见问题

9. 测试

9.1 运行

python -m pytest tests -q# 36 passed

tests/conftest.py 提供：临时数据目录的应用 fixture、login() 助手、boss/technician 已登录客户端、seed_order() 造单助手。

9.2 用例清单

9.3 测试中的断言要点

• 提成金额精确到分：纯色美甲 138 元 × 30% = 41.40，钻饰固定 8.00；

• 次卡核销订单 total = 0（顾客不付钱）但 commissions 有记录；

• 退款后储值卡可用余额回到 1000、提成合计为 0。

9.4 端到端浏览器测试（Playwright）

# 1) 用独立数据目录启动服务（避免污染正式数据）
setNAIL_DATA_DIR=<项目目录>\data_demo
setNAIL_PORT=5057
python run.py
# 2) 另开命令行执行
setE2E_BASE=http://127.0.0.1:5057
setE2E_DB=data_demo/nail.db
python e2e_check.py

脚本 e2e_check.py 会驱动 Chromium 真实走完业务闭环（登录 → 建会员 → 上传照片 → 办卡充值 →办次卡 → 三种开单 → 退款 → 预约签到转单 → 挂单结算 → 库存 → 提成 → 报表导出 → 员工/日志/备份/仿真 →技师越权校验），随后直接查询 SQLite 核对金额（订单数、营收、储值本金/赠送、剩余次数、退款、提成合计、库存、日志条数），并把关键页面截图输出到 docs/screenshots/。脚本对 JS 控制台错误与 HTTP 5xx 采取零容忍（发现即失败退出）。

最新一次执行：53 步全部通过，0 失败，0 个 JS 错误。

10. 二次开发指南

代码规范约定

• 所有涉及钱/库存/次数的写操作必须经过 app/services.py，禁止在路由里直接 UPDATE 余额；

• 新增写操作必须调用 log_operation(module, action, target_type, target_id, detail)；

• 金额统一 money()；日期统一 db.now() / utils.today()；

• 页面统一继承 templates/base.html，左侧菜单按 current_user.perms 自动显隐。

2. 登录与界面总览

2.1 登录

默认账号（密码均为 123456，登录后请及时修改）：

2.2 工作台（首页）

工作台从上到下依次是：快捷操作 → 今日经营数据 → 数据图表 → 待办提醒 → 今日预约。

① 快捷操作：常用的 8 个入口一点即达，不用在菜单里找。

快捷入口与左侧菜单都会按账号权限自动显示：例如技师登录看不到"经营报表"，前台登录看不到"员工与权限"。

② 今日经营数据（8 个卡片）

• 今日营收、今日单量 / 挂单数、今日充值、次卡核销次数；
• 会员总数 / 今日新增、储值余额总额（本金 + 赠送）、未核销剩余次数、本月营收。

③ 数据图表（全部为本地绘制，断网也能看）

分类营收按项目业绩口径统计：现金结算按实收金额，次卡核销按项目会员价计入，
所以环形图中心的"业绩合计"可能略高于当天实际收款（次卡核销当下不产生收款）。

④ 待办与提醒

• 待结算挂单、次卡即将到期（30 天）、库存预警三张提醒卡；
• 今日预约列表，可直接点"处理"跳到预约页做签到/开单。

2.3 左侧菜单（分组子菜单）

左侧菜单按业务分成四组，点组名可折叠/展开，当前页面所在分组会自动展开并高亮：

左侧菜单即为全部功能入口，菜单会按当前账号的权限自动显隐。

3. 会员建档与会员查询

3.1 新建会员

菜单「会员档案」→ 右上角「+ 新建会员」，填写姓名、手机号、生日、来源、标签，以及美甲美睫专属档案（指甲/睫毛情况、过敏备注）。

3.2 上传历史款式照片

在会员详情页「历史款式照片」区域选择图片、填写备注后点「上传」。图片保存在本机 data/uploads/members/，开单做款前可随时调阅客户历史款式与过敏信息。

3.3 会员查询

• 顶部搜索框支持手机号 / 姓名 / 标签模糊检索；
• 列表直接显示持卡数量与累计消费；
• 点姓名进入详情，可查看全部历史消费、卡内余额、剩余次数、款式照片、回访记录。
  

3.4 客户回访记录

会员详情页底部「客户回访记录」→ 填写回访日期、内容与下次回访日期 → 「记录回访」。纯手动录入，无自动短信/微信推送（本系统不依赖外网）。

4. 卡项管理：储值卡 / 次卡 / 券

4.1 办卡

三种入口，效果一致：

2. 会员详情页 →「会员卡项」→「办理新卡 / 发券」；
4. 菜单「卡项管理」→ 顶部办卡表单（先选会员）；
6. 开单收银时若发现客户没有卡，可先去卡项管理补办。

卡类型说明：