77 lines
6.6 KiB
Markdown
77 lines
6.6 KiB
Markdown
# 拼豆私域小程序首期实施计划
|
||
|
||
**目标：** 建立 uni-app 顾客端、Gin 服务端和 Vue 3 店员后台，完成图纸制作/收藏/保存、店内服务及管理员处理流程。
|
||
|
||
**已确认：** 用户已授权创建三个工程并编码。首期单店，数据预留多店隔离。支付与储值仅保留禁用的能力接口。内外网独立 HTTPS 域名；非 Wi-Fi 不探测内网。Wi-Fi 下短超时验证内网门店服务，失败回退公网。不读取 SSID。
|
||
|
||
## 全局约束
|
||
|
||
- 三个工程：perler-beads-applet、perler-beads-server、perler-beads-webui。
|
||
- 小程序 uni-app + Vue 3 + TypeScript；后台 Vue 3 + Element Plus + Pinia + Vue Router；禁止引入 Tailwind。
|
||
- 服务端 Gin + PostgreSQL + Redis，业务持久化以 PostgreSQL 为准，不以 Redis 为持久化真源。
|
||
- 所有 JSON 接口采用 HTTP 200 与 `{code,msg,data}`，code=200 成功、403 未登录、401 未授权；平台登录密钥不交给前端。
|
||
- 商户配置、图纸数据和权限必须在服务端校验；网络连通性不授予员工权限。
|
||
- 无微信凭据时提供显式开发模式，生产模式禁止开发登录。
|
||
- 首期支付/储值不可操作，返回 enabled=false；不建立假成功支付或余额。
|
||
- 首期打印为可下载 SVG 实际尺寸文件 + 店员手动打印任务；不宣称已自动驱动硬件。
|
||
- 原始图片在小程序本地处理；保存到服务端的是色号网格和元数据。演示色板与图纸明确标记，正式色板由后台维护。
|
||
|
||
## 接口契约
|
||
|
||
基础路径 `/api`。所有 ID 均 string。JSON 字段 camelCase。数组接口直接返回数组，不包 items。
|
||
|
||
- GET /health：data={service:"perler-beads",storeId:"store-001",version:"0.1.0"}，不含个人信息。
|
||
- POST /auth/login：{code:string} 微信登录；开发模式允许 {code:"dev-guest"}，data={token,user:{id,name,role,storeId}}。
|
||
- POST /auth/admin：{username,password}，返回同登录形状；管理员凭据环境配置。
|
||
- GET /me：当前用户；GET /capabilities：{payment:{enabled:false},storedValue:{enabled:false}}。
|
||
- GET /stores：Store[]；Store={id,name,address,hours,notice,localBaseUrl,publicBaseUrl}。
|
||
- GET /palettes?storeId=：Color[]；Color={code,name,hex,location,available}。
|
||
- GET /patterns?storeId=&q=：Pattern[]；GET /patterns/:id：Pattern。
|
||
- Pattern={id,title,category,width,height,cells:(string|null)[],colors:Color[],beadCount,ownerId?,visibility:"public"|"private",createdAt}。颜色和 cells 使用同一 code。透明为 null。
|
||
- POST /patterns（登录）：{title,category,width,height,cells,colors,visibility:"private",storeId}；DELETE /patterns/:id（所有者）；GET /my/patterns。
|
||
- GET /favorites：string[]；PUT /favorites/:id：{active:boolean}。
|
||
- POST /visits：{storeId,tableCode}，data=Visit；GET /visits/current：Visit|null；DELETE /visits/current 退出；Visit={id,storeId,tableCode,status:"active"|"closed"}。tableCode 来自后台已启用桌位。
|
||
- GET /tables?storeId=（员工）：Table[]；Table={code,label,enabled}。
|
||
- GET /service-requests：顾客自己的任务；员工当前门店任务。ServiceRequest={id,storeId,userId,tableCode,kind:"help"|"refill"|"ironing"|"print",note,status:"pending"|"accepted"|"completed"|"cancelled",patternId?,createdAt,updatedAt}。
|
||
- POST /service-requests：{kind,note,patternId?,requestId}；要求有效到店 session，store/table 取 session。requestId UUID 持久幂等；重复呼叫返回原任务或业务冲突。重复键不同内容不能误判为同次请求。
|
||
- PATCH /service-requests/:id：{status}；员工可 pending->accepted->completed；顾客仅取消自己的 pending。校验门店。
|
||
- GET /admin/patterns；POST /admin/patterns；PATCH /admin/patterns/:id（发布/下架、名称分类）；仅管理员。
|
||
- PUT /admin/palette：{storeId,colors:Color[]}；PUT /admin/store：Store；PUT /admin/tables：{storeId,tables:Table[]}；仅管理员。
|
||
- GET /patterns/:id/print?pitchMm=5：鉴权访问对应图纸，返回实际尺寸 SVG 文件，含色号/坐标/色量与校准标尺，超大图说明分页；不接受未校验 ID 文件路径。
|
||
|
||
## Task 1：服务端与数据持久化
|
||
|
||
- [x] 为图纸校验、服务状态变更、权限、幂等建立失败测试，再实现。
|
||
- [x] 建立 Gin 模块、迁移、配置、鉴权、PostgreSQL 仓储、Redis 会话/限流适配及演示数据。
|
||
- [x] 实现以上契约，保证用户私有图纸隔离和门店任务隔离。
|
||
- [x] 提供 go test ./...、go vet ./...、构建验证；数据库集成测试使用独立测试库，缺环境明确报告。
|
||
|
||
## Task 2：小程序与图纸工具
|
||
|
||
- [x] uni-app Vue 3 工程，图纸/制作/门店/我的四个页面，详情/跟做页。
|
||
- [x] 先用 Node 测试网络路由：蜂窝零探测、Wi-Fi 成功、失败回退、none、unknown、网络切换取消过期结果、幂等重试。
|
||
- [x] 图片本地裁剪采样、色板量化、透明网格、文字生成、局部改色、计数、逐色高亮、草稿和进度保存。
|
||
- [x] 图纸列表搜索收藏、账号保存、桌码到店、呼叫/补豆/熨烫/打印、取消与状态反馈。
|
||
- [x] 本地/公网连接统一封装，配置合法 HTTPS 端点，开发 localhost 仅开发构建。
|
||
- [x] 执行核心逻辑测试、类型检查、H5 与微信小程序构建。
|
||
|
||
## Task 3：店员管理后台
|
||
|
||
- [x] 登录、路由权限、门店切换边界、待处理服务列表、接单完成操作。
|
||
- [x] 图纸管理与导入、色板与物料位置编辑、桌位、门店配置、禁用支付能力展示。
|
||
- [x] Element Plus 控件与表格、侧栏、抽屉编辑，响应式、空/错/载入状态、无障碍标签。
|
||
- [x] 类型检查、构建、桌面/移动浏览器交互核查。
|
||
|
||
## Task 4：交付与整体验证
|
||
|
||
- [x] Docker Compose（PostgreSQL、Redis、服务端），双 HTTPS 域名与 frp 示例、环境变量模板。
|
||
- [x] README：本地启动、微信配置、示例色板限制、打印方式、真实部署验证清单。
|
||
- [x] 复查 API 联通、鉴权、重复呼叫与网络回退；独立代码审查，修复重要问题。
|
||
- [x] 记录真实执行结果；微信真机、实际 DNS/TLS、打印硬件未验证则明确列出。
|
||
|
||
## 进度
|
||
|
||
- 2026-10-03：用户确认开始编码。当前仅有 example 截图，无 Git 仓库、无已有代码；直接在指定工程目录创建，不创建额外 worktree。
|
||
|
||
- 2026-10-03：三端首期实现完成。最终类型检查、构建与测试通过，真实 PostgreSQL/Redis 联调及独立审查通过。部署模板已交付但未在 Docker 或门店网络运行；真机与打印验收仍待实际环境，详见 verification.md。
|