项目文件夹
场馆约课与身心放松小程序 · 文档仓库
微信小程序「场馆约课与身心放松」的设计文档。线下身心疗愈场馆（瑜伽、颂钵、普拉提、冥想类）的课程预约系统。
代码仓库：basevec/fangsuo_mp
目录约定
本仓库同时作为代码仓 AI Native Dev 流程的知识库（AI_NATIVE_KNOWLEDGE_REPO），因此目录结构遵循其约定：
| 目录 | 内容 | 谁写 |
|---|---|---|
prd/ |
产品需求文档与设计稿 | 人工维护；Docs 阶段 Agent 可能修改 |
tech/ |
技术方案 | 人工维护；Docs 阶段 Agent 可能修改 |
issues/{org}/{repo}/{id}/ |
每个 Issue 的 objective.md / plan.md / tech-review.md |
Agent 自动写入，不要手改 |
⚠️ 不要在根目录直接放文档。 Docs 阶段的 Agent 只认
prd/和tech/，放在根目录会导致同一份文档出现两个位置。
代码仓里的 backend/docs/ 是另一回事，那里放 seed.sql、errcode.md、api-contract.md、field-contract.md 这类需要跟代码同步演进的工程物料——尤其 seed.sql 是要被执行的，必须和 migrations/ 同仓库，否则版本会对不上。本仓库只放设计文档。
当前有效文档
| 文档 | 版本 | 内容 | 维护人 |
|---|---|---|---|
| prd/产品设计-V1.0.md | V1.0 | 产品需求原件：页面逻辑、状态定义、预约支付链路、41 张设计稿。两份技术方案的需求依据 | 产品 |
| tech/技术方案-小程序后端-V1.3.md | V1.3 | 后端完整技术方案：数据模型、状态机、并发方案、接口契约、定时任务 | 赵雅涛 |
| tech/技术方案-运营后台-V1.3.md | V1.3 | /api/admin/* 模块与运营后台前端：架构与部署、业务规则、接口设计、前端方案、开发排期 |
李绍焕 |
| tech/数据库表结构说明.md | V1.3 | 现网 11 张表的 DDL 摘录，叠上 001～005。建表以代码仓 backend/migrations/ 为准 |
李绍焕 |
产品文档记录的是设计思路与阶段性讨论，不是实现规格。 其中部分内容仍是初版、部分明确不做（候补、系列筛选、老师线上申请、兴趣内容播放器、首页）、部分状态定义在技术评审中被重新拆解过。凡与技术方案冲突，一律以技术方案为准，具体清单见该文档开头的「阅读须知」。
文字准确性方面以飞书原件为准：本仓库的是导出转换版，正文未改动，只整理了格式（图片重命名、补 alt、修正标题层级）。产品更新后需重新导出。三个空章节（后端配置、数据埋点、测试流程）在原文里就是空的，已在文中标注，不是转换丢失。
⚠️ 本仓库中的技术方案以 V1.3 为准。 若在飞书或其他渠道看到 V1.1，其第 5 章 DDL 已作废（按两层模型 +
venues/rooms表编写），不要参考。V1.2 与 V1.3 数据模型完全兼容，V1.3 仅为增量修订，变更内容见第 16 章变更记录。
两份方案的边界：数据模型、状态机、并发方案以《小程序后端》为准，运营后台方案与其对齐、不重复定义；运营后台方案只负责
/api/admin/*的接口实现、后台前端、以及运营侧的业务规则（编辑限制、上下架校验、退款操作）。现网表结构以backend/migrations/与《数据库表结构说明》为准——两份技术方案里的 DDL 摘录若与迁移不一致，以迁移为准并回来改文档。
项目范围
| 项 | 内容 |
|---|---|
| 本期做 | 约课全链路：浏览 / 报名 / 支付 / 取消退款 / 商家课程管理 / 老师主页 |
| 本期不做 | 绿洲（发现页音视频内容）、首页、数据埋点、候补、用户线上申请成为老师 |
| 技术栈 | Go 1.22 + Gin + PostgreSQL 16 |
| 服务形态 | 单体服务，小程序端与商家后台共用一个后端、一个数据库 |
| 数据模型 | 一层模型（courses 直接承载时间与库存，无课程模板/场次分层） |
分工
| 模块 | 负责人 | 路由前缀 | 职责 |
|---|---|---|---|
| 小程序端 | 赵雅涛 | /api/mp/* |
小程序接口、支付回调、全部定时任务、小程序前端 |
| 商家后台 | 李绍焕 | /api/admin/* |
后台接口、后台 HTML 页面、建表迁移脚本 |
建表迁移由李绍焕统一维护（migrations/ 目录），赵雅涛需要改表结构时提 PR。
技术方案章节导航
共 16 章 + 2 附录，4700+ 行。按需要看，不必通读：
| 想了解 | 看哪章 |
|---|---|
| 项目背景、上线前置依赖（备案 / 支付资质） | 1 |
| 系统架构、表归属、跨模块写入约定 | 2 |
| 为什么是一层模型（含被推翻的理由复核） | 3.1 |
| 角色与权限 | 4 |
全部建表 DDL（10 张共用表见第 5 章；ops_audit_logs 见运营后台 / 表结构说明；调度锁不建） |
5 + 《数据库表结构说明》 |
| 五个状态机 | 6 |
| 并发正确性方案（防超卖、时段冲突、幂等） | 7 |
| 小程序端专项（字段契约、配置下发、按钮状态） | 8 |
| 七条核心业务流程 | 9 |
| 6 个定时任务 | 10 |
| 接口契约 | 11 |
| 技术选型、Go 工程约定 | 12 |
| 日志 / 监控 / 安全 / 性能 | 13 |
| 开发排期 | 14 |
| 两人协作约定 | 15 |
| 已确认决策 + 待确认问题 + 变更记录 | 16 |
新接手建议阅读顺序：3.1（理解模型） → 5（表结构） → 7（难点方案） → 15（协作边界）。
运营后台方案章节导航
共 12 章，1900+ 行。与《小程序后端》对齐，不重复定义数据模型与状态机。
| 想了解 | 看哪章 |
|---|---|
| 本期做什么 / 不做什么、外部依赖 | 1 |
| 为什么前端是独立部署服务（不含在单体里） | 2.2 |
| 请求链路、Next 同源代理、构建期固化的坑 | 3 |
表清单与归属、ops_audit_logs 审计表 |
4 |
| 发布态与展示态的三维度拆分 | 5.1 |
并发正确性：为什么必须有 enrolled_count |
5.5 |
老师时段冲突与 23P01 的三条触发路径 |
5.6 |
前后端分离后业务规则如何只保留一份（actions 出参） |
5.7 |
| 取消本场的二次确认设计 | 5.8 |
老师管理、单笔退款（含 releaseSeat） |
5.9 / 5.10 |
| 富文本的存储与后端 HTML 清洗 | 5.11 |
| 复制课程（一层模型的体验补偿） | 5.12 |
/api/admin/* 接口清单、响应结构、错误码 |
6 |
JWT、token_version 撤销、双轨凭证 |
7 |
| 后台前端设计（页面、表单、上传、编辑器） | 8 |
internal/admin 分包与前端目录结构 |
9 |
| K8s 部署、种子数据 | 10 |
| 开发排期（后端 14 人日 + 前端约 15 人日） | 11 |
| 已确认决策、与 V1.3 的 3 处待拍板出入、已知风险 | 12 |
建议先看：第 12 节三项（role / 登录标识 / 审计表）已拍板并落地（002/003），本节保留历史。现网 DDL 看《数据库表结构说明》。
四个关键设计点
看方案时容易忽略但很重要的：
① enrolled_count 不是可选优化
既防报名超卖，也是「已有人报名的课不允许下架」这个校验的正确性前提。不加这个字段，下架校验用 NOT EXISTS 子查询存在竞态（子查询锁 courses 行，并发 INSERT 在 course_enrollments 上，两者不冲突）。见 7.2.5。
② 抢库存 SQL 的两个条件缺一不可
WHERE id = $1 AND publish_state = 'published' AND enrolled_count < capacity。少了状态判断，用户能报上一门已下架的课。见 7.2.2。
③ 业务规则不得硬编码在前端
小程序改前端要重新提审（1~3 个工作日）。所有规则（日历天数、支付倒计时、免费取消时限）由后端下发，按钮状态也收敛到后端返回的 actionType。见 8.4、8.3.2。
④ 软删除的索引配套
唯一索引与排他约束必须带 AND deleted_at IS NULL，否则删掉的课仍占用老师时段。见 5.2.5。
待确认问题
第 16 章列了尚未拍板的问题。这些不要自行决定，需要找对应的人确认。