这是一个基于开源/模板微信商城小程序改造的胡团蛋糕项目，不是从零开发。
当前最重要的目标不是马上做支付、闪送或完整会员系统，而是先让朋友能在手机微信里稳定测试这条链路：
打开小程序
-> 微信登录/用户身份
-> 浏览蛋糕商品
-> 选择/填写收货地址
-> 创建订单
-> mock 支付或商家标记已支付
-> 商家手动处理订单和配送
hutuanCake/
├── README.md # 项目入口说明
├── docs/
│ ├── project.md # 当前项目说明，也就是本文档
│ ├── api-and-models.md # 从现有前端代码梳理出的接口和模型
│ ├── bugs.md # 当前 Bug 整理
│ └── cloudrun-deployment.md # 微信云托管部署与配置
├── frontend/ # 微信小程序前端，微信开发者工具导入这个目录
└── backend/ # Go 本地后端，保留方法名 API 接口
以后项目相关文档优先放在本仓库 docs/ 里，不再同时维护一份外部 Markdown 知识库版本，避免两边不一致。
前端目录：
frontend/
微信开发者工具应该导入这个目录。
当前前端统一通过 frontend/utils/api.js 调用后端，典型调用方式是：
API.login_wx(...)
API.authorize(...)
API.queryAddressV2(...)
API.addAddress(...)
API.defaultAddress(...)
API.orderCreate(...)
当前本地接口配置在：
frontend/config.js
当前配置指向：
apiBaseUrl: http://127.0.0.1:8080
subDomain: hutuanCake
merchantId: 27
这适合微信开发者工具模拟器本机调试。真机预览时，手机上的 127.0.0.1 指的是手机自己，不是电脑，所以需要改成局域网 IP 或 HTTPS 隧道地址。
后端目录：
backend/
后端定位是：先用本地 Go 服务保留方法名 API 接口，让开源小程序能跑起来，后续再逐步替换成真实业务后端。
当前已具备：
/healthz健康检查；/api/{methodName}方法名路由；- 商品、分类、门店、购物车、订单、地址、优惠券等 mock/半真实接口；
- MySQL 持久化入口，本地和线上统一使用 MySQL。
本地联调建议直接连接本地或线上 MySQL：
cd backend
DB_DSN='mysql://user:pass@127.0.0.1:3306/hutuan' go run ./cmd/server后端只支持 MySQL；快速检查接口也需要连接本地或线上 MySQL。
当前最应该先做的是微信用户身份，不是完整会员系统。
推荐第一版链路：
小程序 wx.login()
-> 得到临时 code
-> 后端 login_wx 接收 code
-> 本地开发阶段：后端生成 mock openid / uid / token
-> 正式阶段：后端用 AppID + AppSecret 调微信 jscode2session 换 openid
-> 前端保存 token 和 uid
-> 后续购物车、地址、订单都用 token 归属到同一个用户
关键点：
wx.login()本身不需要用户点授权弹窗；- 不要一开始做手机号授权、完整会员等级、余额充值；
- 第一阶段只要能区分不同测试用户的购物车、地址、订单即可；
getUserProfile只适合拿头像昵称展示，不应该作为订单身份的核心依据。
当前最应该先做的是：
手动地址表单
+ wx.chooseLocation() 地图选点
+ 手动填写联系人、手机号、门牌号
+ 保存到后端地址表
+ 下单时保存地址快照
关键点：
wx.chooseLocation()会打开地图选点，前端拿到地址、经纬度；- 联系人、手机号、门牌号由用户在表单里手动填写；
- 保存地址时必须带经纬度，供后续闪送下单使用；
- 下单时订单里必须保存地址快照，不能只保存 address_id，否则用户之后改地址会影响历史订单。
可以做：
wx.login()流程；- 后端 mock token；
- 地址列表、新增地址、默认地址；
- 地图选点和手动地址表单；
- 下单链路；
限制：
- 模拟器对定位、地图选点、用户真实环境支持不如真机；
- 如果后端跑在 WSL，模拟器访问
http://127.0.0.1:8080通常可行，但真机不行； - 如果要调用微信正式
jscode2session，需要正式 AppID/AppSecret，不能把 AppSecret 写进前端或 Git。
可以实现，而且用户授权和地址授权最好最终在真机验证。
真机测试有三种方式：
- 真机调试：开发者工具连接手机，适合开发者自己调试。
- 预览二维码：适合短时间给自己或朋友扫一下看效果。
- 体验版：适合让朋友持续测试，但需要把朋友加为体验成员。
真机测试后端地址要注意：
127.0.0.1 / localhost 只代表手机自己，不代表电脑。
所以真机测试需要二选一：
电脑局域网 IP，例如 http://192.168.x.x:8080
或：
HTTPS 隧道，例如 https://xxxx.trycloudflare.com
如果是体验版或更接近真实用户的测试，优先用 HTTPS 隧道或正式 HTTPS 域名，后续上线必须配置微信小程序合法 request 域名。
这些不是当前第一优先级：
- 真实微信支付；
- 闪送 API 全自动下单；
- 完整会员系统；
- 积分、充值、礼品卡；
- 多门店复杂后台；
- 正式云数据库；
- 上线审核材料。
当前先把用户身份和地址链路跑通，再把商品/订单链路稳定下来。