四人家庭超市的自营商城:商品、价格、库存、订单、配送、顾客全部自己管,完全独立于牵牛花中台,只保留月度 CSV 库存对账。
- 为什么做:牵牛花抽成与账期不可控、顾客数据沉淀在平台侧;自建后佣金归零、顾客可私域运营,前台价格与配送规则由自己定。
- 卖给谁:门店周边固定客群(熟客 + 微信群),MVP 范围限常温 + 酒水。
- 形态:以 Web 端商城为主(手机浏览器即可下单,无需下载),微信小程序线已启动(骨架恢复为
miniprogram/,业务与后端完全复用,见miniprogram/README.md)。
| 阶段 | 内容 | 状态 |
|---|---|---|
| M0 | 项目基建(目录/规范/双端同步约定) | ✅ 完成 |
| M1 | 页面展示层(顾客端 → 管理端 → 扫码体验) | ✅ 完成 |
| M2 | 规则与数据(价格防护、配送规则、种子数据) | ✅ 完成 |
| M3 | 牵牛花月度 CSV 对账工具 | ✅ 完成 |
| M4 | Go 后端服务(数据层 / 规则 / 条码链 / HTTP API / 部署件) | ✅ 完成,本地联调通过 |
| M5 | 微信小程序化 | ⛳ 产品定型已改(2026-10-15):批发商订货——顾客是来进货的店主、一次整箱整提、货一律自己送、不接任何第三方跑腿平台;原「小区即时零售」的 30 分钟送达 / 3 元配送费 / 满 30 包邮按批发场景重想。产品说明(零技术词、给老板看)见 docs/批发订货-产品说明.md;本定型目前只写了说明、尚未改代码(等老板确认第七节那 5 件事)。🚧 进行中(第 21 轮起):骨架恢复为 miniprogram/、主题/配置/只读扫码完成;AppID 与生产 HTTPS 域名就绪(第 22 轮);第 23 轮打通微信登录(D28)——wx.login → 服务端 code2session → openid 绑手机号档案,「我的」页可登录/退出并按等级看价,开发版 0.2.0 已上传;第 24 轮吸收开源商城 EastWorld/wechat-app-mall 重做界面:引入 @vant/weapp 1.11.7(本项目唯一获批的 npm 依赖,仅小程序端)、页面 4 → 10 页、浏览→详情→下单主链路打通,Web 端同步对齐,开发版 0.3.0 已上传;第 25 轮把登录与信息展示收敛(D31)——登录改微信官方「头像昵称填写能力」、不再绑手机号(手机号推后到下单时填并记住)、登录后不再显示登录按钮、修掉头像椭圆、顾客端「后端连接 / 后端已连接」全换小绿点;上线后按老板反馈连收三轮:① 头像只留一处(登录卡里重复的那个删掉)、② 四个顾客页统一小圆点、③ 头像改「纯 view 圆容器 + 透明 button 点击层」才真正是圆、「微信头像昵称」卡与保存按钮整块删掉(点头像即选即存)、④ 「我的」页最底下的「开发者选项」可见入口删掉,随后老板又说「长按版本号进面板 这个功能也不需要」,于是连调试面板一起整块删除**——顾客端没有任何开发入口,「退出登录」留在顾客区、⑤ 订单页 6 个状态标签改等分 + 缩字号,不再顶出屏幕,开发版 0.4.0 已上传**;第 26 轮做员工身份 + 员工扫码工作台(D32)——wx_user 加 role(customer 默认 / staff)与 staff_token 两列(都走 ensureColumn 幂等迁移,令牌故意不进 store.WxUser 结构体,防止列表接口泄露),登录时可选「我是顾客 / 我是员工」(默认顾客,权限只能老板在 Web 管理端新增的「用户角色」面板给,小程序自己点不出员工身份,选了员工但后台没标成员工会被 403 挡下);员工端是非 tab 的 pages/staff/* 5 页工作台(工作台 / 扫码台 / 库存 / 订单 / 员工我的,自绘底栏 components/staff-nav,顾客的 5 个 tab 一个字节没改),扫码台 wx.scanCode 扫 69 码 → 服务端查货 → 入库 / 出库 / 盘点都要员工再点一下并二次确认才动库存(扫码只读,D8 不变)、未建档条码可当场建档(库存留空就一个字节都不发,守 D16)、可改价可上下架(只走独立接口,守 D23);员工是全权限(与管理后台同级),两个新的员工聚合接口用请求头 X-Staff-Token 守、失败一律 401;站点级管理端鉴权仍是遗留项;开发版 0.5.0 已上传;第 27 轮买得完 / 看得对(D33)——四条正确性 + 身份底座:① 身份与归属(身份解析优先级 = 有效 X-Staff-Token(员工,全量)> 显式管理端标记 X-Admin:1 > openid(用 wx_user.phone 认人)> phone(Web 顾客兼容)> 无身份 400),GET /api/orders 带身份只回本人单、total 是真实总数、limit/offset 生效,按单号查 / 取消他人单一律 404,advance 只有员工能推、唯一例外是归属人自己 to=done(确认收货);② 下单幂等 clientToken(同 token 第二次返回原单 + duplicated:true)+ 原子扣库存(WHERE stock>=?,不再读-判-写)+ 起送门槛 minOrder;③ 地址簿能力钥匙(GET/DELETE /api/addresses 必须带 phone+key,修掉「仅凭手机号就能读写别人地址」);④ 规则单一真源(配送费三端口径统一:先 round2 再比门槛、minFree<=0 永不包邮、未知配送方式按 delivery、状态文案五档三端逐字相同);⑤ 示例数据不再进生产库(SEED_DEMO=1 才播种);⑥ 顾客端 10 页统一 loading→error(可重试)→empty→ok 四态;⑦ 管理端鉴权灰度交付(ADMIN_PASSWORD + 签名 Cookie,第 27 轮生产故意不设口令)。本轮最有价值的发现是一个真 bug:管理端 Cookie 与顾客页同域共用,早期实现「带了管理员 Cookie 就按管理员身份」会把老板自己逛顾客页变成全店视角(看到所有顾客姓名地址)——修法是管理端身份必须显式声明 X-Admin: 1(仅用于区分同浏览器里的两个页面,安全边界始终是 Cookie),由回归测试 TestR27AdminChannelOn 与 deploy/accept-r27.js 严格档抓出。两处必须如实披露的缺口:(a) 灰度档下无身份请求按管理端放行(能读全店订单、推进/取消),R27 契约里「无身份→400」「无令牌 advance→403」只在通道开启时成立;(b) requireAdmin 不认员工令牌且后台还没有登录页,所以一开口令会同时把员工(扫码入库/建档/上下架)和老板锁在门外——本轮生产故意不配口令,这两条与后台登录页 #loginGate 一起留到第 30 轮交付。生产顾客端真实发的请求都带 openid/phone,所以「只看得到自己的单」「查他人单 404」在生产是真生效的;第 28 轮(D34)「找得快」——让顾客「找得到」、老板「筛得出、导得走」:后端 GET /api/products 新增 sort(default/hot/price_asc/price_desc/stock_desc,未知值 → 400 排序方式不支持:<值>)与 limit/offset,响应 {items,total,tier} 的 total 改为过滤后的真实总数(不再是当前页条数)并补 hasMore;新增 GET /api/products/hot?limit=8&phone=(近 30 天订单明细 SUM(qty) 降序,没销量的商品排在后面而不是被排除,并列按 on_sale DESC, name ASC)与 GET /api/products/alternatives?code=<缺货码>&limit=5&phone=(on_sale=1 + stock>0 + 排除自身,优先同分类热销、不足用全店热销补足;code 缺失/商品不存在 → {"items":[],"total":0} 而不是 400 —— total = 候选池总数(已排除自身/缺货/下架),可以大于 limit,只有 items 截断到 limit);GET /api/orders 新增 q(顾客名/手机号/订单号模糊)/status(逗号分隔多值)/date=YYYY-MM-DD(按本地日)/from/to(含端点)/`type=pickup |
| M5′ | Web 端商城现代化 + 功能实现 | 🔄 进行中(任务池 8 项已完成 7 项);第 28 轮(D34)「找得快」已交付,开发版 0.7.0 已上传、生产已滚动更新(两实例 healthy) |
| M6 | 部署上线验证 | ✅ 已完成(第 22 轮):Docker 蓝绿 + 主机 Nginx 域名入口 https://mall.shadouyou.cloud(acme.sh/ZeroSSL ECC 证书、80 自动 301、每日自动续期),管理端走干净地址 /admin;IP 直连 HTTP 入口保留为备用 |
📌 节奏:第 13 轮后曾在 2026-10-10 本机暂停并全量同步仓库;2026-10-12 用户要求「继续开发」,已陆续完成任务池第 4 项「销售报表 / 日报」与第 5 项「批量改价 / 批量操作」;第 16 轮按用户要求先把项目部署到生产服务器,可打开真实界面边看边提优化;第 17 轮据用户提问补了管理端干净地址
/admin(D22)、演示数据一键灌库脚本deploy/seed-demo.py,并修掉一次「rsync 误删生产库」的事故;第 18 轮完成任务池第 ⑥ 项「商品图片与分类管理」——商品图(本地web/assets/demo/*.svg演示图,不依赖外部 CDN)、商品上下架(含批量上下架,新增product.on_sale字段与 D23 口径)、分类计数与改名/合并,全部已上生产;第 19 轮完成任务池第 ⑦ 项「批发价与顾客等级」(新增product.wholesale_price与customer.tier、价格口径真源挪到服务端,见 D24);第 20 轮:不在任务池 8 项内的一轮加固——D25「消灭 localStorage 单点」,把原先只活在浏览器localStorage的四样东西落进后端库(库存流水 / 配送员名单 / 门店抬头 / 顾客备注),库存变更收成唯一入口store.ChangeStock(改库存与写流水同一事务、失败不留痕、流水只留最近 500 条),新增POST /api/stock/change、GET /api/stocklog、GET|POST /api/couriers、GET|POST /api/settings、POST /api/customers/note;生产 CDP 真浏览器写库时发现并修掉「浏览器顶层const不在window上 → 在线改库存页面不同步」的缺陷;第 21 轮启动小程序线:小程序注册已完成(主体:海宁啥都有网络科技有限公司,小额打款验证通过),骨架由归档恢复为正式目录miniprogram/,主题色对齐#16a34a、新增唯一域名配置点utils/config.js、新增只读扫码找货wx.scanCode+api.resolveBarcode(D8 只读),三套测试 73 / 57 / 24 项全绿;下一步只等已备案 HTTPS 域名 + AppID(见小程序开发引导.html)。第 22 轮:① 定清「线上超市该勾哪几个服务类目」并写进引导文档(生活服务→百货/超市/便利店 + 商家自营→食品/酒盐 + 按需初级食用农产品/美妆洗护);② 归档营业执照信息,OCR 出来的统一社会信用代码含一位非法字符(S),按国标校验位算法修正为91330481MADQ66GM5E;③ 微信凭证防误提交加固——用户那两个文件名没有前导点(cert.txt/private.wx….key),而.gitignore里写的是带点版本,等于根本没被忽略,再跑一次例行git add -A就会把 AppSecret 推进公开仓库;已补齐规则并核实「从未提交过」;④ 把正式 AppID(公开信息)填进miniprogram/project.config.json;⑤ 域名上线:mall.shadouyou.cloud用本机既有 acme.sh(不用 certbot,共用 webroot/usr/share/nginx/html/beian)签发 ZeroSSL ECC 证书 → 按deploy/host-nginx.conf装到生产 → HTTPS 前台 //admin//api全 200、CDP 真浏览器 0 异常 0 坏请求、生产只读探针 14 商品 + 扫码只读通过;⑥miniprogram/utils/config.js的PROD_BASE_URL填上域名,小程序真机可直接连生产。第 23 轮(2026-10-13):做微信登录(D28)——服务端wx.login→code2session→openid落wx_user(POST /api/wx/login、GET /api/wx/users),WX_APPID/WX_SECRET只进服务器.env与 compose(未配置时登录返 503、其它功能照常),小程序「我的」页登录/退出、登录后按服务端有效价看价、购物车重算;小程序测试 104 / 70 / 27、Go 46 全绿;生产滚动更新并验证微信侧链路(假 code 探针返回「微信登录码无效或已过期」),开发版 0.2.0 已上传。第 24 轮(2026-10-13):按用户要求参考开源商城EastWorld/wechat-app-mall重做小程序界面并吸收其页面骨架(决策 D30)——引入@vant/weapp 1.11.7(本项目唯一被批准的 npm 依赖,只在小程序端,且因本机无微信开发者工具而手工入库miniprogram_npm/),页面从 4 页扩到 10 页(新增商品详情 / 分类 / 搜索 / 订单详情 / 地址簿增删改,重做首页 / 购物车 / 订单列表 / 我的),打通浏览→详情→下单主链路(详情页「加入购物车 / 立即购买」、购物车多选+左滑删除+数量步进+地址簿回填、订单列表状态分页与「确认收货 / 取消 / 再来一单」);Web 端同步对齐(详情弹窗「立即购买」临时单、订单卡状态文案与「确认收货」);服务端新增GET /api/products/{code}(只读详情,带?phone=算有效价)与GET /api/products/categories;门店品牌更名「小邻里超市 → 啥都有快送」(D29),生产库已生效。测试全绿:Go 48、小程序 104 / 131 / 50、Web 42 / 109 / 117 / 206 / 211,并对生产公网地址跑 CDP 真浏览器验收(0 异常 / 0console.error/ 0 横向溢出)。开发版 0.3.0 已上传。第 25 轮(2026-10-13):按用户五条反馈收敛登录与信息展示(D31)——① 登录头像昵称改用微信官方能力(<button open-type="chooseAvatar">+<input type="nickname">;wx.getUserProfile自 2022-10-25 起只给灰头像与「微信用户」,不能用),头像用wx.getFileSystemManager().saveFile落本机永久文件、并POST /api/wx/profile回传云地址;② 登录不再要手机号(wx.login→openid即登录,手机号推后到下单时填,填过一次由api.rememberPhone()记住——手机号仍是价格身份与地址簿钥匙,D24/D18 不变);③ 登录后不再显示「微信一键登录」,也没有「保存头像昵称」入口(点头像即选即存);④ 头像椭圆彻底修掉(原生button自带padding/行高/::after会把圆形容器撑扁 → 可见层换成纯view/image圆 + 透明button点击层);⑤ 顾客端不露开发信息——「我的」页删掉「后端连接」一行、首页「后端已连接」徽标换成 9px 小圆点(Web 顾客端同步换点;管理端保留详细徽标,老板工具里连接状态有用)。服务端wx_user加avatar列(ensureColumn幂等迁移)、/api/wx/login的phone变可选、新增POST /api/wx/profile(空值保留原值 / 昵称截 20 字 / 头像 ≤512 字)。测试 Go 48、小程序 104 / 167 / 50、Web 42 / 109 / 117 / 206 / 212 全绿,生产已滚动更新并对公网跑 CDP 真浏览器验收(9px 绿点、0 开发字样、0 异常),开发版 0.4.0 已上传。第 26 轮(2026-10-14):做员工身份 + 员工扫码工作台(D32)——wx_user加role/staff_token两列(ensureColumn幂等迁移),POST /api/wx/login新增可选role与 403 语义、新增POST /api/wx/role(Web 管理端「用户角色」面板是老板给员工授权的唯一入口),新增GET /api/staff/overview与GET /api/staff/scan?code=(X-Staff-Token鉴权,失败 401);小程序登录时可选「我是顾客 / 我是员工」(默认顾客),员工进非 tab 的pages/staff/*5 页工作台(自绘底栏components/staff-nav,wx.redirectTo切页);扫码台扫 69 码 → 服务端查货 → 入库 / 出库 / 盘点都要再点一下并二次确认才动库存(扫码只读,D8),未建档可当场建档(库存留空就不发stock,守 D16),可改价、可上下架(守 D23);测试 Go 50 / 小程序 147 / 218 / 71 / Web 42 / 109 / 117 / 222 / 238 全绿,开发版 0.5.0 已上传;员工扫码台的真机效果要老板人眼确认。第 27 轮(2026-10-14)「买得完 / 看得对 · 正确性与身份底座」(D33,开发版 0.6.0 代码侧已 bump):一轮「正确性」轮——不是加功能,而是把三端会算错钱、会越权、会把失败当空数据的地方一次修掉。① 身份与归属(新增server/cmd/server/identity.go):身份解析优先级 = 有效X-Staff-Token(员工,全量)> 显式管理端标记(X-Admin: 1且ADMIN_PASSWORD已设置且 Cookie 有效)>openid(服务端用wx_user.phone认人)>phone(Web 顾客兼容路径)> 无身份 400;GET /api/orders带身份只回本人单、total是真实总数、limit(默认 50 / 上限 200)/offset生效;按单号查或取消他人单一律 404(不泄露存在性);advance只有员工能做,唯一例外是归属人自己to=done(确认收货),否则 403「只有店主可以推进订单状态」;cancel走独立路由、回补库存并写stock_log(kindcancel_return,reason「取消订单回补」,回填order_id)。② 那个真 bug:管理端 Cookie 与顾客页同域共用,早期实现「带了管理员 Cookie 就按管理员身份」会把老板自己逛顾客页变成全店视角(看到所有顾客姓名地址);修法是管理端身份必须显式声明X-Admin: 1(identityOf里的adminMarked(r)),web/sdy-api.js的reqHeaders只在管理端调用(ordersAll=true)时带这个头——它不是安全边界(谁都能加),安全边界始终是管理端 Cookie,它只用来把「同一浏览器里的管理后台」和「顾客页」区分开;这是回归测试TestR27AdminChannelOn与deploy/accept-r27.js严格档抓出来的。③ 下单幂等 + 原子扣库存 + 起送价:POST /api/orders新增clientToken,同 token 第二次返回原单 +duplicated:true,只扣一次库存;库存改成带WHERE stock>=?的原子 UPDATE(不再读-判-写),被扣空的行整单回滚 400「库存不足:<名称>(还剩 N 件)」;新增起送门槛minOrder,goods<minOrder时 400「还差 X 元起送」。④ 地址簿能力钥匙:GET /api/addresses/DELETE /api/addresses/{id}必须带phone+key(每次写入新地址时服务端生成的 32 位 hex,随 POST 响应下发),key错误或缺失一律静默看不到、删不掉——修掉「仅凭手机号就能读写别人地址」。⑤ 规则单一真源:配送费口径三端统一——goods=round2(Σ price×qty);fee=(minFree>0 && goods>=minFree)?0:deliveryFee;minFree<=0表示永不包邮;未知配送方式按 delivery;先 round2 再比门槛(29.995 → 30.00 → 免运费;29.994 → 收 3 元);状态文案五档三端逐字相同(pending待备货 /delivering配送中 /ready待取货 /done已完成 /cancelled已取消)——web/pricing.js、miniprogram/utils/rules.js都退化成薄适配层。⑥ 示例数据不再进生产库:seedIfEmpty改为只有显式设置SEED_DEMO=1(或true)才播种,默认跳过并打日志,生产用deploy/seed-demo.py。⑦ 管理端鉴权灰度交付(新增server/cmd/server/adminauth.go):ADMIN_PASSWORD+POST /api/admin/login(下HttpOnly/SameSite=Strict/7 天的sdy_admin签名 Cookie,HMAC-SHA256 + 常量时间比较)、POST /api/admin/logout,以及requireAdmin逐路由包装管理端接口、adminGate管「一个路由里只有部分方法属管理端」;不设ADMIN_PASSWORD时是灰度档:只打一次 WARN 然后放行。第 27 轮生产故意不设这个口令,因为requireAdmin目前不认员工令牌、而后台还没有登录页——一开口令会同时把员工(扫码入库/建档/上下架)和老板锁在门外。因此本轮有两处必须如实披露的缺口:(a) 灰度档下无身份请求按管理端放行(能读到全店订单、能推进/取消),R27 契约里「无身份 → 400」「无令牌 advance → 403」只在通道开启时成立;(b)requireAdmin不认员工令牌,要在第 30 轮和后台登录页#loginGate一起交付,二者缺一不可。生产顾客端实际发的请求都带 openid/phone,所以「只看得到自己的单」「查他人单 404」在生产是真生效的。⑧ 顾客端体验:小程序 10 个顾客页统一loading → error(带「重新加载」)→ empty(仅成功且为空)→ ok四态(新文件miniprogram/pages/common/ui.js把request:fail/timeout/Failed to fetch翻成人话)+miniprogram/styles/state.wxss;角标全改store.subscribe;购物车离线不提交也不跳转;兜底库存上限、失效商品分组不参与结算;结算运费只认 settings 下发值;低库存阈值四页统一走服务端下发;未登录/无身份时订单页直接拦在页面(一个请求都不发)。Web 端web/sdy-api.js请求超时 2000 → 5000ms,失败文案改人话(带技术原因),地址钥匙落到sdy_addr_key。本轮实跑bash deploy/verify-all.sh全绿 17 行:Go 78(store 37 / cmd-server 24 / barcode 6 / pricing 11)、accept-r27 54 通过 / 0 失败、小程序 167 / 281 / 88、CDP 首页与/admin两页均 0 异常、Web 46 / 111 / 141 / 246 / 259。第 28 轮(2026-10-14)「找得快」(D34,开发版 0.7.0 已上传,生产已滚动更新):一轮**「让顾客找得到、让老板筛得出 / 导得走」的交付,三端同批落地。① 后端商品:GET /api/products加sort(default/hot/price_asc/price_desc/stock_desc,未知值400 排序方式不支持:<值>)+limit/offset,total改成过滤后的真实总数并补hasMore;价格排序在 SQL 里用CASE WHEN按顾客等级取有效价(applyTier把pricing.EffectivePrice写到Price,价格口径仍只有一个真源)。② 热销与缺货推荐:GET /api/products/hot?limit=8&phone=(上限 20)按近 30 天**status IN ('pending','delivering','ready','done')的订单明细SUM(qty)降序,没销量的商品排在后面而不是被排除,并列按on_sale DESC, name ASC;GET /api/products/alternatives?code=<缺货码>&limit=5&phone=(上限 20)取on_sale=1+stock>0+ 排除自身,优先同分类热销、不足用全店热销补足,code缺失或商品不存在返回{"items":[],"total":0}(不是 400)——total是候选池总数、可以大于limit,只有items截断到limit(本轮定稿语义)。③ 订单筛选与导出:GET /api/orders加q/status(逗号分隔多值)/date=YYYY-MM-DD(本地日)/from+to(含端点)/type,六个参数都不参与身份判定(身份照第 27 轮,顾客先按归属过滤再筛),date与from/to同给以date优先,坏日期400 日期格式应为 YYYY-MM-DD;新增GET /api/orders/export.csv(同筛选参数 +limit默认 2000 / 上限 5000),首三字节 EF BB BF、固定 12 列、商品名×数量;明细、RFC4180 转义、文件名orders-YYYYMMDD-HHmm.csv,走adminGate。④ 前端:小程序搜索 300ms 防抖 + 四档排序 + 触底分页 + 无结果补热销 6 件 + 详情页缺货才推同类 ≤5 件;Web 商城SORT_TABS四档 +debounce+IntersectionObserver触底自动加载(无 IO 就静默降级、加载更多按钮兜底);管理后台订单筛选条 + 页脚计数 + 导出 CSV,导出与列表共用同一个Admin.orderFilterQuery、filter 里永不出现phone、筛选结果只用于本次渲染、订单镜像恒为全量(否则会截断「当前待处理(不限日期)」与「今日营业额」)。⑤ 索引与迁移:idx_order_item_code进schemaStmts、idx_product_onsale_category必须进postMigrateStmts(补列之后才建,SQLite 不允许 DROP 被索引引用的列),本轮不新增任何数据库列。本轮实跑bash deploy/verify-all.sh全绿 18 行:Go 91(store 44 / cmd-server 30 / barcode 6 / pricing 11)、accept-r2754 通过 / 0 失败、accept-r28灰度档 68 通过 / 0 失败、严格档 71 通过 / 0 失败、小程序 193 / 327 / 105、Web 46 / 142 / 173 / 283 / 301、CDP 首页 //admin/ 搜索防抖三处 0 异常(防抖实测「300ms / 只发 1 次请求 / 关键词完整」)。缺口照实披露(两条与第 27 轮同源):(a) 未设ADMIN_PASSWORD的灰度档下无身份请求仍按管理端放行,所以GET /api/orders与export.csv无身份也能调;(b)requireAdmin还不认员工令牌、后台也没有登录页——这两条与后台登录页#loginGate一起留到第 30 轮。
上线后老板又连提四轮收口:⑥ 「开发者选项」不许可见 → 那行带下划线的入口删掉,连调试面板一起整块删除(老板随后又说「长按版本号进面板 这个功能也不需要」,顾客端不留任何开发入口),同时把**「退出登录」挪回顾客区**(它是顾客的正常功能,藏在开发面板里顾客就退不了登录),订单页 6 个状态标签从「横向滚动 22%×6 = 132% 溢出」改成 swipe-threshold="{{6}}" 等分(--tab-font-size:23rpx);⑦ 登录卡与顶部绿框功能冗余、退出登录后头像还挂在绿框里 → 登录表单搬进 .mhead 的 .mlogin(独立登录卡删除),登录按钮本身就是 open-type="chooseAvatar" 按钮(点一次同时选微信头像 + 完成登录),删掉「更换头像」点击层(.mavatar-hit),doLogout() 额外 wx.removeStorageSync('sdy_mp_avatar') + 清 nickname/avatar;⑧ 购物车三个输入框的字只露上半截 → 根因是原生 input 自带 1.4rem(≈56rpx) 默认高度,再叠 padding:16rpx 20rpx 被 box-sizing:border-box 压成 24rpx 内容区(≈半个字高),改成写死 height:80rpx; line-height:78rpx; padding:0 20rpx 并加断言防止回退;⑨ 顾客端连调试面板都不要——老板随后又说「长按版本号进面板 这个功能也不需要」,于是把 wx:if="{{devMode}}" 的整个面板(后端地址输入框 + 保存并重连 / 清空本地缓存两个按钮)与 .mfoot 的 bindlongpress="toggleDev" 一起删除,mine.js 的 devMode/statusDetail/apiBase 与 toggleDev/onBase/saveBase/clearAll 全部删掉,「退出登录」卡片留在顾客区。续做请看下方「下一步(待续)」与 开发计划.html 的任务池。
M5′ 任务池进度:①商品建档/编辑/删除 ✅ ②订单打印/小票 ✅ ③顾客端收货地址簿 ✅ ④销售报表/日报 ✅ ⑤批量改价/批量操作 ✅ ⑥商品图片与分类管理(含上下架)✅ ⑦批发价与顾客等级 ✅(第 19 轮,D24) ⑧上线部署验证 ✅(第 22 轮:生产 HTTPS 域名上线,前台 / 管理端 / API 全绿);第 20 轮另补一轮加固(不在 8 项内):D25「消灭 localStorage 单点」——库存流水 / 配送员名单 / 门店抬头 / 顾客备注落进后端库;第 24 轮也不在 8 项内:按用户要求参考开源商城 wechat-app-mall 重做小程序界面(D30 引入 @vant/weapp)+ Web 端对齐 + 品牌更名(D29);第 25 轮同样不在 8 项内:登录与信息展示收敛(D31——《小程序登录获取头像昵称、登录后不再要手机号、修头像椭圆、顾客端只留小绿点);第 26 轮同样不在 8 项内:员工身份 + 员工扫码工作台(D32——role / staff_token 两列、登录选身份且角色只能后台给、非 tab 的 5 页员工工作台、扫码只读 + 二次确认才动库存、Web「用户角色」面板,开发版 0.5.0 已上传);第 27 轮同样不在 8 项内:买得完 / 看得对 · 正确性与身份底座(D33——身份与归属、下单幂等、地址钥匙、规则单一真源、SEED_DEMO 默认关、顾客端四态、管理端鉴权灰度交付,代码侧 0.6.0 已 bump);第 28 轮同样不在 8 项内:找得快(D34——商品排序 / 分页 / 搜索防抖 / 热销与缺货同类推荐 / 订单多条件筛选 / CSV 导出;三端排序取值逐字相同、total 为过滤后真实总数、alternatives.total = 候选池总数、CSV 带 BOM 固定 12 列、q/status/date/from/to/type 只筛选不参与身份、本轮不新增数据库列、idx_product_onsale_category 必须放 postMigrateStmts),开发版 0.7.0 已上传。
现在就能用:起后端后,顾客端 http://127.0.0.1:8093/ 可浏览商品、加购、下单、看我的订单,并维护收货地址簿(下单自动带出默认地址、改门牌顺手存新地址);管理端 /admin(旧 /admin.html 仍可用)可看 KPI、流转订单、给订单打小票 / 批量打印待备货小票、入库/改数/盘点、建档/编辑/删除商品档案(带比价防线校验)、勾选一批商品批量改价 / 批量改分类 / 批量改批发标记(改价逐款过比价防线)、跑价格防护、维护顾客档案,以及看销售报表 / 日报(今天/昨天/近 7 天/近 30 天/本月/全部,日柱状图 + 热销 TOP + 环比,一键复制或打印日报);顾客端有「💰 我的价格」——填一次手机号就按顾客等级(零售 / 批发 / 白名单)显示对应价格(批发价划线原价),管理端可给商品设批发价、给顾客改等级(D24)。前端与后端数据打通(web/sdy-api.js 为唯一通道),后端不在时自动降级为本地演示模式;库存每一次入库 / 改数 / 盘点都会写后端审计流水(谁、何时、为什么、前后多少),管理端库存页直接读它(第 20 轮 / D25)。
为什么先 Web 后小程序(用户决定):Web 端零门槛、当天能上线、功能可以立刻试;小程序要账号 + 商户号(1–2 周审批)且审核周期不可控,先把业务跑通再包壳。
sdy/
├── web/ # 商城 Web 端(唯一在用的前端)
│ ├── index.html # 顾客端:首页/分类/搜索/扫码找货/购物车/结算(常用地址带出)/我的订单/收货地址簿
│ ├── admin.html # 管理端:总览 KPI/销售报表/订单(含小票打印)/库存/商品档案(建档·编辑·删除·商品图·上下架)/价格防护/顾客/系统(服务端另有 /admin 干净地址)
│ ├── assets/theme.css # 共用设计系统(令牌 + 组件类 + 三档响应式)
│ ├── assets/demo/*.svg # 演示商品图(仓库自带,随静态目录部署,不依赖外网图床)
│ ├── mall.js # 领域逻辑:商品/购物车/订单/配送规则/收货地址簿(全局 Mall)
│ ├── mall-admin.js # 后台逻辑:库存流水/盘点/商品档案 CRUD/配送员/顾客档案/小票模型/报表日报模型(全局 Admin)
│ ├── pricing.js # 价格防护规则(全局 Pricing)
│ ├── sdy-api.js # 后端通道:在线=服务端真源,离线=本地演示(全局 SdyApi)
│ └── test-*.js # 6 套前端测试(见「测试矩阵」)
├── server/ # Go 后端(cmd/server + internal/{store,pricing,barcode} + Dockerfile + smoke.sh)
│ ├── cmd/server/ # 入口 main.go + **第 27 轮新增 identity.go(身份解析/归属/地址钥匙)与 adminauth.go(ADMIN_PASSWORD 签名 Cookie 鉴权)**
│ └── internal/store/ # **第 28 轮新增测试:store_r28_test.go(排序/分页/筛选/索引/老库迁移)与 cmd/server/main_r28_test.go(HTTP 契约,`-run R28` 共 55 个 RUN 节点)**
├── barcode-demo/ # 条码双库工具:扫码台(摄像头)+ 商品库/条码库/扫码日志
├── sync-demo/ # 牵牛花月度 CSV 对账引擎 + 工作台 + 导出字段确认清单
├── deploy/ # 部署件:deploy.sh / rolling-update.sh / seed-demo.py(演示数据一键灌库)/ 主机 Nginx 模板
│ └── … # 第 27 轮新增:verify-all.sh(三端全量验收,第 28 轮扩到 18 步)/ accept-r27.js(真后端契约验收)/ fake-wx.js(假微信)/ cdp-check.js(CDP 异常检查、第 28 轮加真下载 CSV 校验);**第 28 轮新增:accept-r28.js(第 28 轮契约验收,灰度 68 / 严格 71 通过)、cdp-debounce.js(真浏览器实测搜索防抖「300ms / 只发 1 次 / 关键词完整」)**
├── miniprogram/ # 微信小程序端(M5:app.json + utils{config,api,rules,store,staff,tools.wxs} + 16 页(顾客端 11 含收银台 pages/pay + 员工工作台 pages/staff 5)+ components/staff-nav + @vant/weapp + 3 套测试)
│ ├── pages/common/ui.js # 第 27 轮:顾客页四态共用的错误翻译与身份前置(唯一真源)
│ └── styles/state.wxss # 第 27 轮:四态共用样式(错误卡 + 加载骨架 + 低库存角标)
├── docs/ # 迭代路线图-第27~31轮.md(六路审计现状诊断 + 路线图 + 契约表 + 验收清单);支付与配送-方案与验收.md(支付轮 §1 已上线、§2 第三方配送**已作废**);批发订货-产品说明.md(**2026-10-15 新定型**,给老板看、零技术词)
├── 小程序开发引导.html # 小程序上线引导(配置项、回传清单、常见坑)
├── docker-compose.yml # 蓝绿 api-a(8093) / api-b(8094)
├── convert_html.py # 历史工具(老板指定保留):HTML → docx + md,给人读的版本导出用
├── 开发计划.html # 路线图与里程碑状态(唯一「计划」入口)
├── 细节讨论记录.html # 决策台账 D1–D34 + 逐轮记录
└── 独立小程序商城可行性分析与架构方案.html # 架构与实现现状(可行性、成本、设计)
# ① 纯前端演示(无后端,数据在浏览器 localStorage)
cd web && python3 -m http.server 8910 # 顾客端 /index.html,管理端 /admin.html
# ② 接后端(推荐:规则与账目由服务端执行,前端只做展示)
cd server && STATIC_DIR=.. go run ./cmd/server # 顾客端 http://127.0.0.1:8093/ ,管理端 /admin(旧 /admin.html 仍可用)
# ③ Go 工具链不在默认 PATH 时,先导出(本机路径)
export GOROOT=$PWD/.tools/go-sdk/go
export PATH=$GOROOT/bin:$PATH
export GOPATH=$PWD/.tools/gopath GOMODCACHE=$PWD/.tools/gopath/pkg/mod
export GOCACHE=$PWD/.tools/gocache GOPROXY=https://goproxy.cn,direct
export CGO_ENABLED=0 GOFLAGS=-mod=mod页面顶部胶囊显示 🟢 后端已连接 / 🟡 本地演示,同一套页面代码在两种模式下都能用。商城页面与扫码台共用同源 localStorage 商品库 bd_products,要用同一个端口打开才能互相看到数据。
| 模块 | 命令 | 用例数 | 需要后端 |
|---|---|---|---|
| Web 领域逻辑 | node web/test-mall.js |
142 | 否 |
| 价格规则 | node web/test-pricing.js |
46 | 否 |
| 后台逻辑 | node web/test-admin.js |
301 | 否 |
| 后端通道降级 | node web/test-sdy-api.js |
173 | 否 |
| 页面启动冒烟(假 DOM) | node web/test-page-boot.js |
283 | 否 |
| 前后端联调 | node web/test-integration.js |
50 | 是(SDY_API_BASE) |
| 条码核心链路 | node barcode-demo/test-core.js |
7 组 | 否 |
| 条码后端通道 | node barcode-demo/test-api.js |
55 | 否 |
| 扫码台启动冒烟 | node barcode-demo/test-page-boot.js |
28 | 否 |
| 扫码台联调 | node barcode-demo/test-integration.js |
34 | 是 |
| 对账引擎 | node sync-demo/test-sync.js |
62 | 否 |
| 小程序 | node miniprogram/test-api.js / test-pages.js / test-integration.js |
193 / 327 / 105 | 最后一个需要 |
| 三端全量验收(第 27 轮新增,第 28 轮扩到 18 步) | bash deploy/verify-all.sh |
18 行汇总(Go + 小程序三套 + Web 五套 + CDP /、/admin、搜索防抖);deploy/accept-r27.js 另计 54 项、deploy/accept-r28.js 另计 68 / 71 项 |
脚本自起临时后端与假微信 |
| 后端 | cd server && go test ./...(+ gofmt/go vet/./smoke.sh) |
91(store 44 / cmd-server 30 / barcode 6 / pricing 11) | 自起服务 |
约定:
- 联调测试做到与库状态无关(库存只比基线、商品条数用「至少 N 条」、建档用时间戳条码),可反复跑同一个库。
- 改任何页面后必须补一层真实浏览器检查(
node /tmp/cdp-errors.js <url>):classic script 之间共享全局词法环境,顶层const重名会让整个脚本静默失效,而假 DOM 测试发现不了(详见.agent_rules.md第 13 条)。本模型读不了截图,UI 验收一律用 CDP 取数值证据。
- D6 双库条码:
barcode_lib字典层(永久缓存,扫码先命中)+product档案层(价格/库存等经营数据);云端只在双库都未命中时调用,配额按 HTTP 200 计,连续失败触发当日熔断。 - D8 扫码只读:扫码只做识别/建档/查询,不改库存;库存一律手动调整(入库单、盘点差异、直接改数)。
- 价格防护:零售价必须 ≤ 牵牛花参考价 −5%(
round2(ref*0.95)),批发/白名单豁免。 - 商品档案:建档/编辑由服务端校验(条码与名称必填、价格与库存非负、比价防线超价即 400),编辑表单不改库存(
stock不传即保留原值);删除要求库存为 0 且无进行中订单,删档保留条码字典层(D6)。 - 配送规则:自提 0 元;配送满 30 元免运费,否则 3 元。
- 订单小票:
Admin.buildReceipt(order)是只读投影(不改订单/库存/价格),纯前端@media print打印,无打印库依赖;抬头(店名/电话/地址/票尾)第 20 轮起存后端setting(/api/settings,离线时回退本地mall_store),默认值「家庭超市」;配送单印地址与配送员,自提单印「到店自提」,已取消订单盖「作废」。 - D18 收货地址簿:按手机号维护常用地址(Go 端
customer_address表 +/api/addresses;离线走localStorage.mall_addresses),默认地址在结算时自动带出;订单里的地址是下单当时的快照,改地址簿不影响历史订单;下单时若地址与带出的那条完全一致就不重复写,改了内容则存成新的一条(绝不覆盖已有地址,要改已有地址走「地址簿管理」的编辑);删掉默认地址时由最早的一条顶为默认。 - D19 销售报表口径:只统计非取消订单;营业额按下单口径(含未完成)并另拆「已完成 / 进行中」——家庭店要看「今天做了多少生意」,未交付的钱也要单独可见;商品金额取各单
subtotal(不含配送费),客单价 = 营业额 ÷ 单量;时间按本机时区的自然日切分,区间含首尾、零单日也占一格(柱状图横轴连续);环比对等长的上一个区间(「全部」不比较);实现是纯前端纯函数(Admin.buildReport/Admin.reportText),不加后端接口、离线也能出报表,日报可一键复制或按 72mm 打印。 - D20 批量操作边界:批量可改售价 / 分类 / 批发标记,库存一律不动(D16);批量改价逐款过比价防线,超线默认跳过并在预览里标红,可点「按防线顶格」按
round2(参考价×0.95)落价;批发商品与缺牵牛花参考价的商品跳过比价检查,但仍照常改价并记流水;写库前逐款重读当前商品再写,只覆盖要改的字段,避免拿过期快照盖掉别人刚改的分类/单位(第 18 轮补:每个 payload 都要带上img,否则UpsertProduct的img=excluded.img会把已存图片抹成空串);每款改动都单独记一条商品流水(原因写明规则,如「批量改价:+10%」)。第 18 轮商品表有了on_sale(D23),批量上下架随之补上。 - D21 生产部署口径:先上「IP 直连」HTTP 入口(
deploy/host-nginx-ip.conf的server_name只写本机 IP),域名 + 备案到位后再切deploy/host-nginx.conf的域名 + TLS;因为按 Host 精确匹配,未知 Host 仍落同机 beian 的 default_server,不影响 yiguan / beian 等既有站点。容器以uid 10001(app)运行:宿主机data/必须chown 10001(否则 SQLite 报unable to open database file: out of memory (14)),web/必须对 others 可读(本地仓库常见 600 权限会让容器 403 / 退化成目录列表),从本机 rsync 一律带--chmod=D755,F644;api-a/api-b两容器共享/data/sdy.db(SQLite DSN 带 WAL +busy_timeout(5000)),日常更新走deploy/rolling-update.sh先 B 后 A 不停服;生产库里的演示数据(14 款商品 / 6 张订单 / 3 条地址)只用于「打开界面看效果」,正式开张前清库重建即可。 - D22 管理端干净地址:管理端对外统一走
/admin(Go 侧/admin直接吐admin.html,/admin/301 到/admin),旧/admin.html继续可用,不让已收藏的链接失效。之所以带尾斜杠要重定向:/admin不带尾斜杠时页面内的相对路径(assets/theme.css、mall-admin.js、index.html)仍以根目录为基准,而/admin/会把基准变成/admin/,静态资源全部 404。不引入静态托管重写规则,Nginx 侧也不用改(location /整站反代给 Go)。 - D23 商品上下架口径(第 18 轮):上下架是独立动作,只改
product.on_sale一个字段,走独立接口(POST /api/products/onsale,{codes:[...], onSale:true|false});编辑商品档案不改上下架状态(和「编辑不改库存」同理);下架只在顾客端生效——档案、库存、历史订单、条码字典全都不动,顾客端列表里看不到、加购与直接打开详情都被拦住;服务端 JSON 一律下发不带omitempty的onSale(缺字段视为上架,只有明确的false才算下架,老库/老前端不会因为多一个字段就集体消失);product新增on_sale INTEGER NOT NULL DEFAULT 1,用ensureColumn幂等迁移(老库直接升,不用清库)。 - D24 批发价与顾客等级(第 19 轮):顾客等级三档
retail(默认)/wholesale/vip白名单,存在customer.tier,手机号即身份(延续 D18,系统仍然没有账号体系);商品可设product.wholesale_price(0 = 未设,就是「这货不批发」,批发客户也按零售价)。有效价 = 非零售等级且批发价 > 0 ? 批发价 : 零售价(一律round2),算价真源在服务端:GET /api/products?phone=由服务端按该手机号的等级算好price下发(不带omitempty,页面只读它、不自己算),下单时CreateOrder用同一个函数再算一次,前端传的价不参与(同 D12);离线本地演示模式退化为本地按等级算(口径与 Go 完全一致)。批发价不参与零售比价防线(比价只约束零售价,沿用商品维度isWholesale豁免)。改等级只影响之后的单——历史订单的价格是下单当时的快照,不会被动过。顾客端有「💰 我的价格」(填手机号存本地mall_my_phone),批发客户看批发价并把原价划线、购物车行标「批发价」;管理端商品表单可填批发价(高于零售价会被拦)、商品表显示「批 ¥x.xx」、顾客视图可一键登记/改等级。product.wholesale_price与customer.tier都用ensureColumn幂等迁移(老库直接升,不用清库)。 - D25 消灭 localStorage 单点(第 20 轮):原先只活在浏览器
localStorage的四样东西落进后端库——库存流水stock_log、配送员名单courier、门店抬头setting、顾客备注与标签(复用customer.tags/note)。改库存只有一个入口store.ChangeStock(code, kind, qty, reason, by)(kind∈stock_in/adjust/stock_take),改数与写流水在同一事务、任何失败路径defer Rollback——绝不允许「库存变了、没流水」(D8 既然定了库存手动调整,就必须有「谁在什么时候为什么改了多少」的审计;老接口POST /api/products/stock保留,内部折算成adjust且记reason="直接改数",同值不写流水)。流水只留最近 500 条(插入后同事务内裁剪),GET /api/stocklog?limit=倒序返回。前端在线时先写后端再刷本地:SdyApi.changeStock返回{ok, entry, stock},本地镜像一律用服务端的after对齐(Admin.recordStockEntry,按id幂等),后端拒绝就整笔中止并原样透出错误(D12),绝不「本地先改、后端后补」;盘点只在实盘数 ≠ 账面数时才发请求。配送员至少保留一位(ErrConflict→ 409),门店抬头默认值与前端DEFAULT_STORE一致,顾客标签 ≤60 字、备注 ≤200 字,/api/customers/tier(等级)与/api/customers/note(备注)职责分离。踩坑:浏览器里顶层const不是window的属性,web/mall-admin.js必须显式window.Admin = Admin,否则web/sdy-api.js的resolveAdmin()拿不到它、在线改库存会「服务端改了、页面没改」——这个缺陷 Node 单测(显式注入admin: Admin)看不见,是生产 CDP 真浏览器写库(stockAfter必须等于服务端after)才暴露的。 - D26 小程序端口径(第 21 轮):微信小程序线启动,
archive/miniprogram/恢复为正式目录miniprogram/(同一套后端与规则,不复制业务逻辑)。三条口径:① 域名只有一个配置点——miniprogram/utils/config.js的PROD_BASE_URL(DEV_BASE_URL兜底,api.js的DEFAULT_BASE只读它),上线要改的域名/接口地址永远不散落在页面里;② 小程序不存任何密钥——AppID 属公开信息可入库,AppSecret / 商户号 / APIv3 密钥只进服务器.env(延续 D13);③ 扫码只读照旧(D8)——wx.scanCode→api.resolveBarcode(code)→GET /api/barcode/resolve,只把结果填进搜索框筛商品,认不出的条码也原样填进去交老板人工看,绝不自动加购、绝不改库存。主题色与 Web 端统一#16a34a。AppID 与 HTTPS 域名均已到位(见 D27),下一步接微信登录(POST /api/wx/login→code2session)与微信支付。 - D27 域名与证书口径(第 22 轮):生产域名
mall.shadouyou.cloud(A 记录指向生产公网 IP;沿用shadouyou.cloud的备案,子域名即可,真 IP 仍只存本地文件),顾客端https://mall.shadouyou.cloud/、管理端/admin,80 一律 301 到 HTTPS。证书只用本机既有的 acme.sh(v3.1.3,cron 每日--cron自动续期),不装 certbot:--issue -d <域名> --webroot /usr/share/nginx/html/beian --keylength ec-256(webroot 与同机其它站点共用),--install-cert --ecc --fullchain-file /etc/nginx/conf.d/certs/<域名>.fullchain.pem --key-file /etc/nginx/conf.d/certs/<域名>.key --reloadcmd "systemctl reload nginx"(key 一律chmod 600,证书目录与本机其它站点一致)。两条硬约束:① 站点文件里的upstream名不能与同机其它 nginx 文件重名——deploy/host-nginx-ip.conf已占用sdy_api,域名站点必须用sdy_api_domain,否则两个文件同时存在时nginx -t直接[emerg] duplicate upstream "sdy_api"(第 22 轮真实踩到);② 先 80 段、后 443 段的两步上线——证书还没签发就把 443 段写进站点文件,nginx -t会因为ssl_certificate文件不存在而失败,正确顺序是:装 80 段(含/.well-known/acme-challenge/)→ reload → 签发 → 装证书 → 再补 443 段 → reload。微信侧「服务器域名 → request 合法域名」只能填这个 HTTPS 域名(不能是 IP、不能带端口)。 - D28 微信登录口径(第 23 轮):小程序端只有一次
wx.login——拿到的code交给服务端POST /api/wx/login,服务端用WX_APPID/WX_SECRET调sns/jscode2session换openid并落wx_user表;session_key只留服务端、不回传,客户端要记住的只有openid+ 手机号。手机号仍是价格身份(customer.tier),openid 只回答「这台微信是谁」;登录绝不提权——顾客填手机号只是把 openid 绑到已有/新建的零售档顾客上,批发价与白名单只能老板在管理端改(D24 不变),绑定只在新档案姓名为空时补名、绝不覆盖老板维护的姓名,昵称超 20 字截断不报错(绝不让登录因为称呼太长失败)。AppSecret 不出服务器:只进.env(.env.example留空位)与docker-compose.yml两个服务的environment;没配时/api/wx/login返503 微信登录未配置(服务端缺少 WX_APPID / WX_SECRET),其余接口完全不受影响(本机演示与未配密钥的环境照常跑)。小程序登录后商品列表带?onSale=1&phone=,价格仍取服务端下发的有效价(保留零售价用于划线),退出登录同时清会话与价格缓存(sdy_mp_session/sdy_mp_products)。 - D32 员工身份与员工扫码工作台(第 26 轮):小程序里只有两种角色——
customer(顾客,默认)/staff(员工),store.ValidRole只认这两个小写值;角色只能由管理后台设定,POST /api/wx/role {openid, role}配合 Web 管理端新增的「用户角色」面板(GET /api/wx/users列出微信用户,一键在顾客 / 员工之间切换)是老板给员工授权的唯一入口——小程序端点一下是变不出员工身份的。POST /api/wx/login的 body 新增可选role:缺省是顾客;非法值 →400 身份只能是 customer(顾客)或 staff(员工);选了员工但后台没把这个微信号标成员工 →403 这个微信号还不是员工,请让老板在管理后台把角色改成员工(缺 openid →400 缺少 openid(让对方先用小程序登录一次)、未知 openid 报「微信用户 (让它先用小程序登录一次)」、非法角色报「角色只能是 customer(顾客)或 staff(员工)」)。响应新增role/wantRole,是员工就一律回 64 位staffToken(32 字节crypto/rand→ 64 位 hex,每次员工登录轮换、旧令牌立刻失效;即使这次选了顾客身份登录也回令牌,只为「我的」页一键进工作台方便,不是提权——员工本来就跟管理后台同权限)。两个新列与令牌分开:wx_user加role TEXT NOT NULL DEFAULT 'customer'与staff_token TEXT NOT NULL DEFAULT ''(都走ensureColumn幂等迁移,老库直接升),但store.WxUser不带令牌字段(列表接口不下发,防泄露);角色改回顾客时staff_token一并清空(SetWxUserRole),所以「切回顾客版界面」(setView('customer'))不等于交出员工身份——令牌还在,只有老板在后台降级才失效。员工是全权限(跟管理后台一样,能改价 / 删商品 / 改顾客等级),因此员工的写操作一律复用既有开放接口,只有两个新的员工聚合接口用请求头X-Staff-Token鉴权(也接受?staff=兜底,失败一律401 员工身份已失效,请用员工身份重新登录):GET /api/staff/overview(stats{todayRevenue,todayOrders,pending,lowStockCount,products}+pendingOrders最多 5 条 +lowStockItems最多 5 条(低库存阈值 5,与 Web 管理端同一口径)+recent最近 5 条库存流水)、GET /api/staff/scan?code=(命中已建档条码返回product,未建档返回条码解析结果resolve,并附该条码最近 5 条流水;扫码绝不改库存,D8 不变量不变)。小程序端为什么不做 tabBar:小程序 tabBar 最多 5 项且app.json里是静态的,顾客的 5 个 tab 已占满;于是员工端用自绘底栏组件components/staff-nav(wx.redirectTo切页,避免页面栈越堆越深),只在各员工页的 page json 里声明、不写进app.json的全局usingComponents,顾客路径完全不动。扫码台是本轮核心:wx.scanCode扫 69 码 → 服务端查货 → 显示名称 / 规格 / 条码 / 库存 / 售价 / 进价 / 上下架,扫码本身只读;入库(stock_in,增量)、出库(adjust,传负数)、盘点(stock_take,传实盘绝对值)都要员工再点一下并二次确认才动库存,每次动作写库存流水(记原因与操作人);未建档的条码可当场建档(表单里库存留空就一个字节都不发,绝不把现有库存覆盖成 0,守 D16),可改价、可上下架(上下架只走独立接口,守 D23)。遗留(如实记):站点级管理端鉴权仍是历史遗留项;员工令牌随员工登录轮换、角色降回顾客即失效;小程序真机效果(扫 69 码、二次确认手感、「我的」页一键进工作台)要老板人眼确认。 - D33 身份底座、正确性收敛与管理端鉴权灰度(第 27 轮):这一轮不加功能,只修「会算错钱、会越权、会把失败当空数据」的地方,主线是先把身份与归属立起来。① 身份解析优先级(
server/cmd/server/identity.go,唯一入口identityOf):有效X-Staff-Token(员工 = 全量,返回Admin:true+Staff)> 显式管理端标记(adminMarked(r)即X-Admin: 1且adminEnabled()且adminOK(r),即使同时带 phone 也按全量)>openid(服务端查wx_user.phone认人,认不到就继续往下)>phone(Web 顾客兼容路径)>!adminEnabled() && adminOK(r)(灰度放行必须排在顾客身份之后)> 无身份 400。为什么灰度放行必须排最后:灰度默认(未设ADMIN_PASSWORD)时如果把它放最前,任何请求都算管理员,于是?phone=B也能读到 A 的订单、地址簿 key 形同虚设、无令牌也能推进订单(第 27 轮验收实测),这是本轮修掉的真实缺陷。② 那个真 bug(X-Admin为什么必须显式):管理端 Cookie 与顾客页同域共用,早期实现「带了管理员 Cookie 就按管理员身份」会把老板自己逛顾客页变成全店视角(看到所有顾客姓名地址)。修法是管理端身份必须显式声明X-Admin: 1——adminMarked(r)的注释写明:它不是安全边界(谁都能加这个头),安全边界始终是管理端 Cookie;它只用来把「同一浏览器里的管理后台」与「顾客页」分开。web/sdy-api.js的reqHeaders(body)只在管理端调用(ordersAll === true)时才带这个头;同源部署还要credentials: 'same-origin'才能把 Cookie 带上。③ 订单归属:GET /api/orders先identityOf,!Admin && Phone == ""→ 400「缺少身份:顾客请带 openid/phone,员工请带 X-Staff-Token」;!Admin时OrderFilter.Phone = ident.Phone,走ListOrdersFiltered返回{items, total, limit(默认 50/上限 200), offset}(total是符合条件总数,不是本页条数);按单号查、取消他人单一律 404「订单不存在」(不泄露存在性);advance非员工且不是「归属人 +to=done」→ 403「只有店主可以推进订单状态」。orderBelongsTo(o, id)=id.Phone != "" && TrimSpace(o.Phone) == id.Phone。④ 取消走独立路由POST /api/orders/{id}/cancel:事务里回补库存并写stock_log(kind=cancel_return、reason=取消订单回补、回填order_id),RowsAffected=0只记日志不失败(保证审计可追)。⑤ 下单幂等 + 原子扣库存 + 起送价:POST /api/ordersbody 新增clientToken(客户端生成,服务端拿它去重),同 token 第二次返回原单 +duplicated:true(orderResp内嵌store.Order平铺字段)且不再扣库存;扣减改成原子UPDATE product SET stock=stock-? WHERE code=? AND stock>=?,任一行 0 行 → 整单回滚 400「库存不足:<名称>(还剩 N 件)」;goods < minOrder→ 400「还差 X 元起送」(minOrder=0不限)。⑥ 地址簿能力钥匙:GET /api/addresses/DELETE /api/addresses/{id}必须带phone+key(首次写入新地址时EnsureAddressKey生成 32 位 hex,随 POST 响应addressResp{ok, key}下发);addressAllowed(r, st, ident, phone)= 管理员 true,否则要求?key=非空且st.CheckAddressKey(phone, key);不允许时读「静默空{items:[],total:0}」、删「404 地址不存在」。⑦ 规则单一真源:pricing.DeliveryFee的Normalize()刻意不再给MinFree兜底(MinFree <= 0= 明确语义「永不包邮」,缺省 30 由DefaultConfig给);DeliveryFee里if kind != "pickup" { kind = "delivery" }(未知配送方式按 delivery,不再 400)且s := Round2(subtotal)先取整再比门槛(29.995 → 30.00 → 免运费;写成s >= cfg.MinFree而不带cfg.MinFree > 0会让门槛 0 变成「随便买都免」,语义正好搞反);新增StatusPending/…/StatusCancelled+statusLabels{待备货/配送中/待取货/已完成/已取消}+StatusText;Round2 = math.Floor(v*100+0.5)/100(与 JSMath.round同口径,导出给 main.go 用);NormalizeTier把空串与未知等级都归一成 retail;新增MinOrderGap(goods, minOrder)。web/pricing.js与miniprogram/utils/rules.js都退化为薄适配层(normalizeDeliveryType/ 同一组边界用例),三端文案逐字相同并有测试锁定。⑧minOrder与GET /api/settings扩容:settings 现在下发lowStock(=5)/minOrder/deliveryFee/minFree(原来只有 name/phone/address/footer),三端删除硬编码 5;POST /api/settings用指针LowStock *float64/MinOrder *float64区分「没传 = 保留现值」与「传 0 = 回落默认」。⑨SEED_DEMO默认关:seedIfEmpty只有SEED_DEMO为1/true才写 6 个示例商品(都带isDemo: true),默认跳过并打日志——生产库不再被演示数据污染。⑩ 管理端鉴权灰度交付(server/cmd/server/adminauth.go):adminOK(r)是「谁是管理员」的唯一真源(requireAdmin与订单/地址身份解析都调它,不许各写一份);口令空 →adminWarnOnce打一次 WARN 然后 return true;否则读sdy_adminCookie 并verifyAdminCookie(ts + '.' + hex(HMAC-SHA256(pw, "sdy-admin:"+ts)),先比过期时间戳再hmac.Equal常量时间比较)。POST /api/admin/login成功下HttpOnly+SameSite=Strict+Path=/+ 7 天的 Cookie;POST /api/admin/logout立即失效;requireAdmin包装管理端点(失败 401「请先登录管理后台」)、adminGate给「一个路由里只有部分方法属管理端」用(如POST /api/products、POST /api/settings、DELETE /api/products/{code})。公开端点:/healthz、/api/admin/login|logout、/api/wx/*、/api/staff/*、顾客端商品接口与/admin(不含数据的登录壳)。⑪ 灰度缺口的如实披露:本轮生产故意不设ADMIN_PASSWORD——因为requireAdmin还不认员工令牌,而后台还没有登录页,一开口令会把员工(扫码入库/建档/上下架)和老板一起锁在门外。所以 (a) 灰度档下无身份请求按管理端放行(能读全店订单、能推进/取消),R27 契约的「无身份 → 400」「无令牌 advance → 403」只在通道开启时成立(deploy/accept-r27.js会打印这条警告);(b)requireAdmin支持员工令牌 + 后台登录页#loginGate要在第 30 轮一起交付,二者缺一不可。⑫ 顾客端四态与体验:小程序 10 个顾客页统一loading → error(带「重新加载」)→ empty(仅成功且为空)→ ok(miniprogram/pages/common/ui.js用errText()把request:fail/timeout/Failed to fetch翻成人话店里系统没连上,请稍后重试;hasIdentity()让订单/地址页在本地就拦住没身份的请求),样式集中在miniprogram/styles/state.wxss;miniprogram/utils/api.js新增identityParams/authHeader/addrKey/saveAddrKey/lowStock,下单带clientToken、取消改走/cancel;角标全改store.subscribe;购物车离线不提交也不跳转;结算运费只认 settings 下发值。Web 端web/sdy-api.js超时 2000 → 5000ms(reqHeaders+credentials: 'same-origin'+X-Admin)、失败文案「无法连接后端(…):连不上店里,请检查网络后重试 [技术原因:…]」、地址钥匙落sdy_addr_key、sync(phone, {all})的ordersAll口径(顾客页绝不传all,否则灰度模式下会拿回全店订单)、notifyMallMode()把在线状态同步给Mall.setServerConnected(Mall.loadCatalog因此不再用本地演示商品顶替空库)。⑬ 测试与验收:新增deploy/accept-r27.js(真后端契约验收 54 项)、deploy/verify-all.sh(三端全量:Go + 小程序三套 + Web 五套 + CDP,17 行汇总)、deploy/fake-wx.js(假微信jscode2session,不含真实凭证)、deploy/cdp-check.js(CDP 抓异常与全局量)。本轮实跑 17 行全绿:Go 78、小程序 167 / 281 / 88、Web 46 / 111 / 141 / 246 / 259、CDP 两页 0 异常。本轮唯一没做到的是:管理端鉴权只交付了「通道」,正式启用(配ADMIN_PASSWORD+requireAdmin认员工令牌 + 后台登录页)留第 30 轮。 - D34 找得快:排序 / 分页 / 搜索防抖 / 热销与缺货推荐 / 订单筛选 / CSV 导出(第 28 轮):一轮把「顾客找得到、老板筛得出 / 导得走」做齐的交付,排序与筛选参数三端逐字相同(Go 的
sort、小程序utils/api.js的SORTS、Web 的SORT_TABS取值都是default/hot/price_asc/price_desc,Go 另接受stock_desc;页面只上四档)。① 商品分页与真实总数:GET /api/products新增limit/offset与hasMore,total是过滤后的真实总数(不是当前页条数)——沿用 D33 的total口径,页面才敢显示「共 N 件」;sort给未知值一律400 排序方式不支持:<值>(不静默回落成默认排序)。② 价格排序不另立口径:价格排序在 SQL 里用CASE WHEN按顾客等级取有效价,applyTier把pricing.EffectivePrice的结果写进Price—— D24 的「有效价只有一条公式」没有被排序绕开。③ 热销口径:GET /api/products/hot(近 30 天status IN ('pending','delivering','ready','done')的订单明细SUM(qty)降序),没销量的商品排在后面而不是被排除(新店第一天也要有列表),并列按on_sale DESC, name ASC。④alternatives.total是候选池总数(已排除自身 / 缺货 / 下架),可以大于limit,只有items截断到limit—— 第 28 轮定稿语义,别按「total = 返回条数」理解;code缺失或商品不存在返回{"items":[],"total":0}而不是 400(「没有推荐」不是错误)。⑤ 订单筛选只筛不认人:q(顾客名 / 手机号 / 订单号模糊)/status(逗号分隔多值)/date=YYYY-MM-DD(本地日)/from+to(含端点)/type一律不参与身份判定,身份仍走 D33 的identityOf;顾客身份先按归属过滤再筛选(筛不到别人的单);date与from/to同时给 →date优先;坏日期 →400 日期格式应为 YYYY-MM-DD。⑥ CSV 导出是给老板对账的:GET /api/orders/export.csv(同筛选参数,limit默认 2000 / 上限 5000),首三字节必须是 EF BB BF(没 BOM,Excel 打开中文乱码)、固定 12 列(订单号,下单时间,状态,顾客,手机号,配送方式,商品明细,件数,商品金额,配送费,合计,备注)、明细商品名×数量;(末条也带;)、RFC4180 转义、文件名orders-YYYYMMDD-HHmm.csv,走adminGate;「备注」列本轮恒为空串(orders 本轮没有备注列,空着不等于漏了)。前端downloadOrdersCSV用 fetch 拿 blob →<a download>,blob URL 必须setTimeout(..., 0)延迟释放——刚触发下载就revokeObjectURL会把下载取消掉。⑦ 管理端筛选用一个函数:导出与列表共用Admin.orderFilterQuery(不会「列表筛了、导出没筛」),filter 里永不出现phone(身份照 D33),筛选结果只用于本次渲染、订单镜像恒为全量(否则「当前待处理(不限日期)」与「今日营业额」会被筛选截断)。⑧ 索引与迁移顺序:idx_order_item_code ON order_item(code)进schemaStmts,idx_product_onsale_category ON product(on_sale, category)必须进postMigrateStmts(补列之后才建)——SQLite 不允许 DROP 被索引引用的列,老库升级顺序错了会直接失败;本轮不新增任何数据库列(所以不涉及老库升级陷阱)。⑨ 新参数用严格版queryCount(非整数 / 负数 → 400),旧queryInt保持静默回退(订单分页仍用旧版)——加新参数不偷偷改老接口行为。⑩ 验收与遗留:新增deploy/accept-r28.js(灰度 68 / 严格 71 通过)与deploy/cdp-debounce.js(真浏览器实测「300ms / 只发 1 次请求 / 关键词完整」),verify-all.sh扩到 18 步;第 27 轮那两处缺口原样继承——灰度档下无身份请求仍按管理端放行(订单与export.csv都受影响),requireAdmin仍不认员工令牌且后台没有登录页,一并留到第 30 轮。 - D12 单一真源:前端不直连数据库、不持有任何密钥,所有请求走
web/sdy-api.js(小程序侧同理走miniprogram/utils/api.js);服务端是规则与账目的唯一真源,冲突(409)原样呈现。 - 技术栈:后端 Go 1.24 + 标准库
net/http+modernc.org/sqlite(纯 Go,CGO_ENABLED=0静态单文件);前端纯 HTML/JS + 一个共享 CSS,无构建步骤、无 npm 依赖。 - 红线:敏感信息绝不上库(IP/凭证/APPCODE 只存本地且已 gitignore);建档必须人工确认;价格与库存永不自动填云端值;对账以本地实物库存为准、牵牛花为单据权威。
代码侧(按任务池顺序,一次一轮,每轮都补测试 + 真浏览器验收):
| # | 任务 | 要点 |
|---|---|---|
✅ 第 18 轮已交付:商品图(product.img,管理端表单填图片地址 + 缩略图列,顾客端卡片/详情/购物车都渲染,空图回退分类 emoji)、分类计数与改名/合并(chip-x)、单个 + 批量上下架(D23);演示图见 web/assets/demo/*.svg |
||
✅ 第 19 轮已交付(D24):customer.tier(零售/批发/白名单,手机号即身份)+ product.wholesale_price(0=未设);服务端按等级算价下发(GET /api/products?phone= 的 price、下单 CreateOrder 同一函数,前端传价不参与);批发价豁免零售比价防线;改等级只影响之后的单;顾客端「💰 我的价格」+ 划线原价 + 购物车「批发价」标,管理端商品批发价字段 + 顾客等级视图;接口 GET /api/customers、POST /api/customers/tier |
||
| ➕ | 消灭 localStorage 单点 | ✅ 第 20 轮已交付(D25,任务池 8 项之外的一轮加固):新增 stock_log / courier / setting 三张表 + 顾客备注落库;store.ChangeStock 唯一入口(改数与写流水同一事务、失败不留痕、流水留最近 500 条);新增 POST /api/stock/change、GET /api/stocklog、`GET |
| ⑧ | 上线部署验证 | ✅ 第 22 轮已完成:生产 HTTPS 域名 https://mall.shadouyou.cloud 上线(acme.sh + ZeroSSL ECC 证书、80 自动 301、每日自动续期),顾客端 / /admin / /api 全 200、CDP 真浏览器 0 异常 0 坏请求;IP 直连 HTTP 入口保留作备用 |
| 🆕 | 小程序线(M5) | 🚧 第 21 轮启动:骨架恢复为 miniprogram/、主题对齐 #16a34a、域名配置单点 utils/config.js、只读扫码找货 wx.scanCode + api.resolveBarcode |
| ➕ | 微信登录(第 23 轮,D28) | ✅ 已交付:服务端 POST /api/wx/login(code2session → openid 落 wx_user)+ GET /api/wx/users;小程序「我的」页登录/退出、登录后按服务端有效价看价、购物车重算;WX_APPID/WX_SECRET 只进服务器 .env(未配置时登录返 503、其它功能照常);生产已滚动更新并验证(假 code 探针返回「微信登录码无效或已过期」= AppSecret 与微信侧链路已通),开发版 0.2.0 已上传;测试 Go 46 / 小程序 104 / 70 / 27 全绿 |
| ➕ | 小程序界面重做 + 主链路(第 24 轮,D29/D30) | ✅ 已交付:参考开源商城 EastWorld/wechat-app-mall 吸收页面骨架(只吸交互,不吸它的 SaaS 后端、优惠券/拼团/分销等业务);引入 @vant/weapp 1.11.7(本项目唯一获批的 npm 依赖,仅小程序端;本机无微信开发者工具 → 手工入库 miniprogram_npm/,配 ignoreUploadUnusedFiles 瘦身后整包 ~470 KB);页面 4 → 10 页(新增 商品详情 / 分类 / 搜索 / 订单详情 / 地址簿 list+edit,重做 首页 / 购物车 / 订单 / 我的);浏览→详情→下单全链路(详情「加入购物车 / 立即购买」、购物车多选 + 左滑删除 + 步进 + 地址簿回填、订单列表按状态分页 + 确认收货/取消/再来一单);Web 端同步对齐(详情弹窗「立即购买」临时单不污染购物车、订单卡状态文案 + 确认收货);服务端新增 GET /api/products/{code}(只读详情 + ?phone= 有效价)与 GET /api/products/categories;品牌更名「小邻里超市 → 啥都有快送」;测试 Go 48 / 小程序 104 / 131 / 50 / Web 42·109·117·206·211 全绿,生产公网 CDP 验收 0 异常,开发版 0.3.0 已上传 |
| ➕ | 登录与信息展示收敛(第 25 轮,D31) | ✅ 已交付:① 登录改用微信官方「头像昵称填写能力」(chooseAvatar + type="nickname"),头像经 wx.getFileSystemManager().saveFile 落本机永久文件并 POST /api/wx/profile 回传云地址;② 登录不再绑手机号——只走 wx.login → 服务端 code2session → openid,手机号推后到下单时填,填过一次由 api.rememberPhone() 记住(手机号仍是价格身份与地址簿钥匙,D24/D18 不变),地址簿三个接口改成「显式手机号优先、否则用记住的」;③ 登录后不再显示「微信一键登录」按钮,也没有「保存头像昵称」入口——点头像即选即存、昵称随登录 body 提交,之后每次进来自动带出来(上线后老板又让把那张「微信头像昵称」卡整个删掉);④ 头像椭圆彻底修掉(两次才修对:第一次重置原生 button 的 padding/line-height/::after 后仍不对,最终改成可见层是纯 view + image 圆容器、button 退化成 opacity:0 的透明点击层,形状不再由原生组件决定);⑤ 顾客端不露开发信息——小程序「我的」页删掉「后端连接」一行、首页徽标换 9px 小圆点(sdot),Web 顾客端同步换点(dot-mode,说明只留在 title;管理端保留详细徽标);服务端 wx_user 加 avatar 列(ensureColumn 幂等迁移)、/api/wx/login 的 phone 变可选、新增 POST /api/wx/profile(空值保留原值 / 昵称截 20 字 / 头像 ≤512 字),BindWxUser 改 5 参;测试 Go 48 / 小程序 104 / 167 / 50 / Web 42 / 109 / 117 / 206 / 212 全绿,生产 CDP 验收 0 异常,开发版 0.4.0 已上传;上线后老板又连提三轮收口(「开发者选项」删可见入口、随后连调试面板一起删除 + 订单状态标签 6 格等分;登录表单搬进顶部绿框、登录按钮本身就是 chooseAvatar 按钮(点一次同时选头像 + 登录)、删掉「更换头像」、退出登录清掉本机头像;购物车原生 input 写死 height:80rpx; line-height:78rpx,修掉「字只露上半截」) |
| ➕ | 员工身份 + 员工扫码工作台(第 26 轮,D32) | ✅ 已交付:① wx_user 加 role TEXT NOT NULL DEFAULT 'customer' 与 staff_token TEXT NOT NULL DEFAULT '' 两列(ensureColumn 幂等迁移),store.WxUser 不带令牌(列表接口不下发);② 新增 store.RoleCustomer / RoleStaff / ValidRole 与 SetWxUserRole / RotateStaffToken(32 字节 crypto/rand → 64 位 hex)/ GetStaffByToken,角色改回顾客时 staff_token 一并清空;③ POST /api/wx/login 新增可选 role(默认顾客;非法 → 400;选了员工但后台没标成员工 → 403「这个微信号还不是员工,请让老板在管理后台把角色改成员工」),响应加 role / wantRole,是员工就一律回 64 位 staffToken(每次登录轮换,旧令牌立刻失效);④ 新增 POST /api/wx/role(缺 openid → 400,未知 openid → 报「微信用户 …(让它先用小程序登录一次)」,非法角色 → 「角色只能是 customer(顾客)或 staff(员工)」)与 Web 管理端「用户角色」面板(GET /api/wx/users + POST /api/wx/role);⑤ 新增 GET /api/staff/overview(今日营业额 / 今日订单 / 待处理 / 低库存 + 待处理前 5 + 低库存前 5(阈值 5)+ 最近 5 条流水)与 GET /api/staff/scan?code=(命中返 product、未建档返 resolve + 最近 5 条流水,绝不改库存,D8),都用 X-Staff-Token 鉴权、失败 401;⑥ 小程序登录可选「我是顾客 / 我是员工」,员工进非 tab 的 pages/staff/* 5 页(工作台 / 扫码台 / 库存 / 订单 / 员工我的,自绘底栏 components/staff-nav,顾客的 5 个 tab 完全不动),页面数 10 → 15,扫码台支持当场建档(库存留空就一个字节都不发)、改价、上下架;⑦ utils/api.js 新增并导出 sessionRole / isStaff / staffToken / staffHeaders / view / setView / staffOverview / staffScan / changeStock / saveProduct / setOnSale / listAllProducts(不是员工时这些接口在本地就被拒绝,一个请求都不发);测试 Go 50(store 27 / cmd-server 12 / barcode 6 / pricing 5)/ 小程序 147 / 218 / 71 / Web 42 / 109 / 117 / 222 / 238 全绿,开发版 0.5.0 已上传 |
| ➕ | 小程序线准备(第 22 轮) | ✅ 已完成:① AppID(wx3f2d2aa52660b80f,公开信息)填进 project.config.json;② AppSecret / 代码上传密钥只存本地(.wx_secret.env / .private.wx….key),并补齐 .gitignore 与 deploy/deploy.sh 的 rsync 排除——原先那两个文件名没有前导点、其实没被忽略,差点被提交进公开仓库;③ 生产 HTTPS 域名上线;④ utils/config.js 的 PROD_BASE_URL 填域名;⑤ 服务类目选型写进 小程序开发引导.html。待办(用户侧):小程序后台配「服务器域名」✅ 已配 → 微信认证 ¥300 已付款、审核中(2026-10-13) → 关联商户号(未开始);之后接 POST /api/wx/pay、/api/wx/notify 与订阅消息 |
需要用户推进(我做不了的部分):
备案域名✅ 已完成(2026-10-13 第 22 轮):mall.shadouyou.cloud已上线 HTTPS(acme.sh/ZeroSSL ECC、每日自动续期、80→301)。现在顾客端 =https://mall.shadouyou.cloud/、管理端 =https://mall.shadouyou.cloud/admin;生产 IP 仍只存本地.server_cred.md。- 牵牛花导出字段确认(行动项 0,
sync-demo/牵牛花导出确认清单.html):对账引擎从未用真实导出文件验证过,需要一份真样例。 - 微信小程序账号 + 商户号:账号已注册并通过对公账户小额打款验证(主体:海宁啥都有网络科技有限公司,2026-10-12),AppID ✅ 已拿到(
wx3f2d2aa52660b80f,已填进miniprogram/project.config.json;AppSecret 只存本地.wx_secret.env,将来只写服务器.env)。进展(2026-10-15):① 服务器域名 → request 合法域名已填https://mall.shadouyou.cloud✅;② 微信认证 ✅ 已通过;③ 微信支付商户号已开通并与小程序关联 ✅(商户号只写服务器.env,公开文档不披露),商户 API 证书(5 年期,2026-10-14 起)、APIv3 密钥(32 位)、微信支付公钥与公钥 ID 全部到手;密钥与证书只放服务器/root/sdy/secrets/,绝不入库、绝不进日志。 - 小程序提审体验版(开发版 0.9.0 已上传):老板要在微信公众平台把开发版设为体验版并把家人 / 店员的微信号加进体验成员,才能真机看支付轮(「下单 → 收银台 → 微信支付 → 支付成功」与 0.01 元测试商品);另外「服务器域名」目前只配了 request 合法域名,还要补
<image>组件用的 downloadFile 合法域名(同一域名https://mall.shadouyou.cloud),否则真机上的商品图可能显示不出来。「选为体验版」只能在mp.weixin.qq.com → 管理 → 版本管理 → 开发版本手点,命令行没有对应接口(见 D35)。 - 未决产品问题:入库场景范围(D1)、无条码商品策略(D2)、批次效期(D3)、入库单据完整度(D4)、多单位换算(D5);批发电子发票 / 储值 / 生鲜属于 P1+ 待议。
当前状态(第 16–22 轮;第 28 轮已按 deploy/rolling-update.sh 再次滚动更新,两实例 healthy):已部署到生产服务器并可外部访问——Docker 蓝绿两个容器(sdy-api-a/sdy-api-b,宿主 127.0.0.1:8093/8094)已跑起来;主入口是域名 + HTTPS:https://mall.shadouyou.cloud/(顾客端)、https://mall.shadouyou.cloud/admin(管理端),主机 Nginx 同时保留「IP 直连」HTTP 入口 http://<生产服务器IP>/ 与 http://<生产服务器IP>/admin(旧 /admin.html 仍可用)作备用,/api/ 由 Nginx 反代到蓝绿池;生产服务器 IP 只存本地 .server_cred.md,公开仓库不出现。演示数据用 python3 deploy/seed-demo.py http://<地址> 一键灌库(14 款商品 / 7 张订单(含 1 张已取消)/ 3 条地址簿,营业额 ¥205.00、客单价 ¥34.17、售出 36 件,其中 6 款商品带仓库自带的 web/assets/demo/*.svg 演示图、7 款商品带批发价,并登记 2 位顾客等级(13800001111 王阿姨=批发 / 13900002222 李叔=白名单);脚本幂等,可反复执行),打开即可看到 KPI、订单流转、小票、库存、报表、批量改价、商品图与上下架、批发价与顾客等级的真实效果——顾客端点顶部「💰 我的价格」填 13800001111 即可看到批发价与原价划线。第 20 轮又上线了 D25:库存页标题变成「最近 N 条(后端审计)」、每笔入库/改数/盘点都有流水(谁 / 何时 / 为什么 / 前后值),配送员名单与门店抬头也存服务端(deploy/seed-demo.py 会补 4 位配送员、门店抬头与 3 条演示流水)。
- 范式和端口见 deploy/:Docker Compose 蓝绿 A/B + 主机 Nginx(80/443),后端
api-a→127.0.0.1:8093、api-b→127.0.0.1:8094,不对外直连;避开同机已占用端口 22/53/80/443/8081/8082。主机 Nginx 上两个站点模板:deploy/host-nginx.conf(域名 + HTTPS 主入口,已用于mall.shadouyou.cloud)与deploy/host-nginx-ip.conf(IP 直连备用);两者的upstream名必须不同(域名版sdy_api_domain、IP 版sdy_api),nginx 的 upstream 名是全局唯一的,同名会直接[emerg] duplicate upstream。 - 流程:rsync 同步(带
--chmod=D755,F644)→cp .env.example .env(填 APPCODE、SDY_DOMAIN)→./deploy/deploy.sh(会自动chown数据目录、chmod静态目录)→ 首次配主机 Nginx:照deploy/host-nginx.conf注释里的步骤做(证书一律用本机 acme.sh,不装 certbot:--issue -d <域名> --webroot /usr/share/nginx/html/beian --keylength ec-256→--install-cert --ecc装到/etc/nginx/conf.d/certs/<域名>.fullchain.pem|.key+--reloadcmd "systemctl reload nginx";先装 80 段、签发成功后再补 443 段,否则ssl_certificate文件还不存在、nginx -t会失败);mall.shadouyou.cloud已于 2026-10-13 按此上线,续期由 acme.sh 的每日 cron 自动完成。只需用 IP 看界面时用deploy/host-nginx-ip.conf;日常更新./deploy/rolling-update.sh逐台重启不停服;只改前端时不必重启容器——./web:/app/web:ro是只读挂载,同步文件即生效。 - ⛔ rsync 禁止加
--delete/--delete-excluded:服务器上的data/sdy.db(真数据)与.env都不在仓库里,加了就会被同步删掉,容器随即报unable to open database file: out of memory (14)并无限重启(第 17 轮真实踩过一次:api-a握着已删 inode 的旧库所以公网看着还在,api-b反复重启、滚动更新中断)。恢复动作:cp -n .env.example .env→ 填SDY_DOMAIN→mkdir -p data && chown -R 10001:10001 data→bash deploy/rolling-update.sh→python3 deploy/seed-demo.py http://<地址>重建演示数据。 - 服务器地址与登录凭证只存本地
.server_cred.md(已 gitignore,公开仓库绝不出现)。
| 文件 | 说明 |
|---|---|
开发计划.html |
里程碑路线图、当前重心、依赖用户推进的事项 |
细节讨论记录.html |
决策台账 D1–D34 + 逐轮讨论记录 |
独立小程序商城可行性分析与架构方案.html |
可行性分析、成本、架构与实现现状 |
web/README.md |
商城 Web 端(顾客端 + 管理端) |
server/README.md |
Go 后端:接口、环境变量、测试 |
barcode-demo/README.md |
条码双库与扫码台 |
sync-demo/README.md |
牵牛花 CSV 对账 |
.agent_rules.md |
协作与工程规则(含页面验收、进程/端口卫生) |
三份 HTML 只在仓库内维护(2026-10-15 起):腾讯文档 pull/push 流程已取消(用户 m15454;.agent_rules.md 文首说明),改完直接 commit + push 即可,不再需要拉取比对、转换或推送。
历史工具已移到
archive/local-tools/(pull_tencent_docs.py/push_tencent_docs.py/set_tencent_permission.py/sync_docs_lib.py;仍在仓库里可查,只是不在根目录,见archive/README.md)。 根目录保留convert_html.py:它能把 HTML 转成 docx/md(注意方向是 HTML → docx + md,依赖.venv里的lxml/python-docx,用法.venv/bin/python3 convert_html.py <输入.html>)。
- 开工先同步:
git pull --rebase,确认无残留改动再动手,避免覆盖另一端的提交。 - 收工必推送:每轮改动 commit + push 到
github.com/kiddyt00/sdy(main),保证云端代码最新。 - 敏感信息绝不入库:推送前三层扫描(工作区 / 暂存区 / 已提交历史);本仓库是 public,IP、口令、APPCODE、腾讯文档凭据一律只留本地。
- 本仓库产物约定:
*.docx与腾讯文档转换出的*.md属本地产物,已在.gitignore。