diff --git a/README.md b/README.md index ba0bcfc..07fe67d 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,16 @@ # jinzuan-werewolf 金钻狼人杀协作仓库(github/协作修改包经此流转)。 + +--- + +## 两批交付 + +| 目录 | 是什么 | 批次 | +|---|---|---| +| `portal/` `order/` | 门户与下单页(前端) | 上一批(视觉重设计) | +| **`backend/`** | **网站后端 + 本地自助管理后台 + 测试用 Blender 工程 + 部署层片段** | **本批** | + +> 看后端请从 **`backend/他应该知道的.md`** 开始读(生意背景 / 机器约束 / 数据边界 / 术语表), +> 再进 `backend/README.md` 和两份交接说明。 +> 写回执照 **`backend/回执模板.md`** 填。 diff --git a/backend/README.md b/backend/README.md index f959df3..5ad04dd 100644 --- a/backend/README.md +++ b/backend/README.md @@ -7,6 +7,18 @@ --- +## 怎么读这份包(建议顺序) + +| 顺序 | 读什么 | 为什么先读它 | +|---|---|---| +| 1 | **`他应该知道的.md`** | 生意怎么转、机器什么条件、哪些数据碰不得、术语表 —— **不读这个,代码里很多东西推不出来** | +| 2 | 本文件 | 包里有什么、三条纪律、我们要你回什么 | +| 3 | `backend-site/交接说明.md` 或 `backend-tools/交接说明.md` | 各含一节**《我们的思路与方法》**(比代码更值得看:坑都是"不报错但坏掉"那一类) | +| 4 | 代码 | 到这儿再进代码 | +| 5 | **`回执模板.md`** | 写回执时照它填,**不用另起格式** | + +--- + ## 包里有什么(按店主划的交付范围) | 店主说的 | 落在哪 | 里面是什么 | 交接文档 | @@ -15,6 +27,8 @@ | **本地的自助管理后台** | `backend-tools/` | 局域网开单后台(带 PIN 锁)+ 纯本机开单工具 + 渲染机 + Blender 出图脚本 + 部署/启动脚本 | `backend-tools/交接说明.md` | | **用于测试的工程** | `模板/` | 三个 Blender 模板工程(已脱敏,可直接打开渲染) | `模板/说明.md` | | **其他需要的** | `deploy/` | 反向代理的路由与限流片段(部署层)+ 这一层的取舍说明 | `deploy/nginx-片段.md` | +| **背景须知** | `他应该知道的.md` | 生意背景 / 机器约束 / 数据边界 / 术语表 / 我们这边的纪律 | — | +| **回执模板** | `回执模板.md` | 直接照着填:问题分析 / 改正意见 / 你改了什么 + 我们拿不准的问题 + **运维个人想知道的** | — | --- diff --git a/backend/backend-site/交接说明.md b/backend/backend-site/交接说明.md index be5a7be..fa84e00 100644 --- a/backend/backend-site/交接说明.md +++ b/backend/backend-site/交接说明.md @@ -168,6 +168,8 @@ inactive 停用(网页单等付款 / 手动停用) 请你读完之后**回一份文档**(放在同一个仓库里就行,文件名 `回执-<你的名字>.md`),至少包含三部分: +> 📋 **格式不用自己起** —— 仓库根目录有一份 `回执模板.md`,照着填就行。 + 1. **问题分析** —— 你看到的问题、风险、坏味道。分个轻重(会导致丢钱/丢数据/被人打的,排前面)。 请**尽量指到具体函数/行**,并说清**触发条件**(什么输入、什么并发时序会踩到)。 2. **改正意见** —— 每条给**你建议怎么改**(不一定要写代码,说清思路和代价也行)。 diff --git a/backend/backend-tools/交接说明.md b/backend/backend-tools/交接说明.md index 9a4037a..bedb0e2 100644 --- a/backend/backend-tools/交接说明.md +++ b/backend/backend-tools/交接说明.md @@ -107,6 +107,8 @@ 同样请回一份 `回执-<你的名字>.md`,含三部分: +> 📋 **格式不用自己起** —— 仓库根目录有一份 `回执模板.md`,照着填就行。 + 1. **问题分析** —— 你看到的 bug、健壮性问题、坏味道。**特别欢迎**指这几类: - **静默失败**:出错了但看着"一切正常"的地方(我们被这个坑过好几次) - **状态不一致**:显示与真实不一致(比如界面说排队中、实际没领单) diff --git a/backend/交付清单.md b/backend/交付清单.md index df4ff46..81f3d5c 100644 --- a/backend/交付清单.md +++ b/backend/交付清单.md @@ -1,10 +1,10 @@ # 交付清单(自查用) -> 生成:2026-10-05 18:52 共 29 个文件 合计 44.7 MB +> 生成:2026-10-05 18:55 共 31 个文件 合计 44.7 MB | 文件 | 字节 | SHA-256 | |---|---|---| -| `README.md` | 7,532 | `e551e8da39ec955f6d2a25fdd724e2949dffccb6de83d0121df62a8944e909bc` | +| `README.md` | 8,498 | `15ccb27558e0612ff1a9fc7822f7a0ec8da298753617b317cbf057a4902ddbb5` | | `backend-site/admin.py` | 24,214 | `3b9818c063e4c7297d3052cad4ff2a88941b4d07b85e2e5eaf495eed35d3f484` | | `backend-site/pngcheck.py` | 4,945 | `ccec7ab21b0399da651029ffa5781bad498e0905b31a1102f6ba3e3f01e8594d` | | `backend-site/server.py` | 160,560 | `9470b057f9eaf1927d06917ac5909fb0e733a4b44a04c039b82bbd907b9f2a62` | @@ -29,6 +29,8 @@ | `backend-tools/ys_worker.py` | 30,465 | `ab6cdff13ce16ed15363c28cf016628b378a1ec255d2b8eeb62566cf38631eb9` | | `backend-tools/交接说明.md` | 11,008 | `731c591b545c4332c3ad5336910a78e5dfb8b6541da6f33e8f4e70bb3b7dab48` | | `deploy/nginx-片段.md` | 4,145 | `183179dc694e1f2ac3a791f3c96aa6f7d292b1968276ae1af4d850e26fbf78d0` | +| `他应该知道的.md` | 6,988 | `177f08cb455bf5cf4b299abda5b227ff530c1da634c69f81c8ca7498ccc00cbe` | +| `回执模板.md` | 5,049 | `0e38a6c19dff7b55767b8998d294b0252aa6024053dad0c63956ddd58b56a07a` | | `模板/1站立正反.blend` | 16,486,783 | `985dc61aeaa6eaaf5dc87ccbba6dfd4e1c5eb95468f7d0a9610d47aff14cb9dc` | | `模板/4海边自拍.blend` | 18,101,431 | `629df363d00e73e18820bddb6b7b92d7dbdd55d0f5c98de5378c76a48b705183` | | `模板/5不看爆炸.blend` | 11,849,599 | `3bb67516632e206c89fe44e2cf04667f5e34e1eab70e395c00830555e033e223` | diff --git a/backend/他应该知道的.md b/backend/他应该知道的.md new file mode 100644 index 0000000..db78eb0 --- /dev/null +++ b/backend/他应该知道的.md @@ -0,0 +1,119 @@ +# 他应该知道的(背景须知 · 请先读这份再看代码) + +> 你手上的是一份**脱敏过的真实生产代码**。光看代码有很多东西推不出来 —— +> 这门生意怎么转、机器什么条件、哪些能动能不能动、哪些数据碰不得。这份补齐。 +> **看完这份再看 `README.md`,然后挑一份交接说明进代码。** + +--- + +## 一、这门生意是什么 + +一个**个人的自助渲染小店**:卖**我的世界(Minecraft)角色的场景渲染图**。 + +``` +买家(闲鱼 / B站工房 / 爱发电)下单 + → 自己上网页:挑模板 → 传自己的皮肤图 → 填卡密 → 提交 + → 服务器登记排队 + → 店主家里那台电脑(渲染机)自动领单、用 Blender 出图、回传 + → 买家回来下载(标准压缩版 + 无压缩版,每张两个文件) +``` + +**单价很低**(一张几块钱),**单量也不大**(一天几单到几十单)。 +所以整套系统的设计目标**不是吞吐,是"不用人盯着"** —— 店主白天还有别的事, +不能为了接一单就守在电脑前。 + +**这就是为什么代码里到处是"无人值守"的痕迹**:队列、离线提示、自动发货、 +"呼叫店主"、过期自动清理。**评这块的时候请拿这个目标当尺子。** + +--- + +## 二、这台机器什么条件(很多设计是它逼出来的) + +| 约束 | 逼出来的做法 | +|---|---| +| 服务器**内存很小**(1G 多) | 不用框架、纯标准库;zip **先落临时文件再边读边发**(不能整块读进内存);用 cgroup 卡住进程内存上限 | +| 服务器**不允许跑重活**(视频转码会把整机拖死) | 渲染全部在**店主家里那台电脑**上做,服务器只做登记/排队/转发 | +| 家里那台**没有公网入口** | 它**只做出站**:自己定时来服务器领单。**服务器从不主动连它** | +| 家里那台是**一台电脑**(还要玩游戏/干活) | 渲染**严格串行**,任何时刻只允许一个 Blender 在跑 | +| 家用上传带宽一般 | 成品**一张一次**回传(也顺便避开请求体上限);打包下载走流式 | + +⚠️ **"小机器 + 别拖死它"是硬前提**。如果你觉得我们某处写得太抠,很可能是这个前提逼的; +反过来,**如果你发现某处会把机器拖死,那是最值得报的问题**。 + +--- + +## 三、边界(哪些是公开的、哪些碰不得) + +| | | +|---|---| +| **公开** | 门户首页、画展、模板缩略图(给买家看样图用的) | +| **私有** | 下单页、订单页、所有接口、管理后台、本机工具 —— **"私有网站,请勿外传"** | +| **绝对碰不得** | **买家的皮肤图和成品图、订单数据、卡密**。那是**第三方(买家)的个人数据**,不是店主的 | +| **不要外传** | 这份代码本身(含片段、截图)。你要讨论就脱敏着讨论 | + +**关于买家数据再多说一句**:买家的皮肤是**别人的作品**,成品里也带着他的皮肤。 +我们这边只做"渲染服务",**不对内容做合规担保**(服务条款里写明了)。 +**你如果要写测试,请用你自己画的假皮肤,别拿真实订单里的图。** + +--- + +## 四、术语表(代码里到处是这些词) + +| 词 | 意思 | +|---|---| +| **卡密 / 兑换码** | 买家凭它下单的凭证。**一枚码默认 = 一张图**,也可以设成"固定 N 张 / 不限张数 / 锁定模板" | +| **单号** | 订单编号(短、大写字母数字) | +| **取件码** | 订单链接里的 `?t=` 那一串。**它本身就是凭证**(所以链接不能外流、页面不许被搜索引擎收录) | +| **模板** | Blender 工程(场景);买家的皮肤贴到模板上的角色模型上渲出来 | +| **皮肤** | 买家的 MC 角色图(正方形 PNG,64 的整倍数) | +| **臂型** | 角色是粗臂还是细臂(由皮肤决定,影响模型) | +| **收货闸** | 买家点了"确认收货"才放**原图**;没点只能看 512 宽的水印预览 | +| **直发单** | 不走"网页下单→付款→激活",后台直接推进队列的单 | +| **福利券** | 免费码批次,放在福利页让买家自取(每设备+每网络限领一张) | +| **渲染机** | 店主家里那台 Windows 电脑上跑的后台程序 | +| **解冻 / 核销** | 卡密的终态(成品开放下载满 72 小时后)。**注意:激活 ≠ 核销** | + +--- + +## 五、这份代码是脱敏过的,**不能直接跑** + +所有指向真实环境的值都换成了占位(域名 / 端口 / 路径 / IP / 账户名)。 +**代码里本来就没有硬编码凭据**(令牌走文件与环境变量),所以这一项是干净的。 + +**你要真跑一遍看效果,用 `模板/` 里那三个 Blender 工程** —— 那三个能直接在 Blender 里打开渲染。 + +--- + +## 六、谁在维护 / 上一批交付了什么 + +- **店主**:做模板、出方案、拍板。 +- **苏达**:网站运维与技术提供(这台服务器、这套系统、这份文档都是它整理的)。 +- **你**:这次被请来看**后端**。 + +上一批交付给你的是**前端**(`portal/` 门户 + `order/` 下单页,视觉重设计那批), +在同一个仓库里。**这次是后端和本地工具,两边是靠接口对齐的**,所以: + +> ⚠️ **你改任何东西,只要动到"接口路径 / 请求响应字段 / 数据格式"这三样, +> 必须单独标出来。** 这套系统是**两台机器上各跑一份代码**(服务器一份、店里电脑一份), +> 两边不同步会**静默出不来图** —— 不报错、就是没图,这种最难查。 + +--- + +## 七、我们这边的几条纪律(不是给你立的,是让你理解我们为什么这么做) + +1. **出站必脱敏**:任何离开这台机器的文字,先过机检 + 一个独立的第二双眼睛。 + (这次那份包就是这么出来的,**而且独立复查真抓出了 3 处漏网 + 2 处缺件**。) +2. **不替对方做决定**:涉及别人的钱、别人的数据、别人的账号,一律问过本人再做。 +3. **宁可响亮地失败,不要静默成功**:出错了要看得见,不要"看着正常但其实没生效"。 +4. **改动要说清代价**:不只是"能改",还要说"改起来多大、会不会影响别处"。 + +--- + +## 八、你可能也想知道(我们主动交代) + +- **这套系统踩过不少坑**,坑都写在两份交接文档的《我们的思路与方法》里了 —— + **那节比代码更值得看**,因为坑是"不报错但坏掉"的那一类。 +- **代码里大量注释带了日期和决定人**(例如「某日:为什么要这么改」)。 + 那是我们的决定留痕习惯,**不是为了甩锅**,是怕以后有人不知道为什么这么写。 +- **有几处"看起来多余"的防护**(比如订单不存在和口令错返回同一个 404), + 都是被真实压力逼出来的,不是过度设计 —— 但也**欢迎你说"这处没必要"**。 diff --git a/backend/回执模板.md b/backend/回执模板.md new file mode 100644 index 0000000..f1f980b --- /dev/null +++ b/backend/回执模板.md @@ -0,0 +1,126 @@ +# 回执模板 · 直接照着填就行 + +> 你**不用另起格式**,把下面每节填掉、删掉提示语即可。 +> 文件名建议 `回执-<你的名字>.md`,放在仓库根目录。 +> **填不满不要紧,写"没看/没测/没意见"比空着好** —— 空着我们不知道是漏了还是没问题。 + +--- + +# 回执 · <你的名字> · <日期> + +## 0. 一句话总结 + +<这套代码整体你怎么看?哪里最值得先修?> + +--- + +## 1. 问题分析 + +> 请**分轻重**:会丢钱 / 丢数据 / 能被别人利用的排前面,风格问题排后面。 +> 尽量**指到具体位置**,并说清**什么条件下会踩到**(什么输入、什么并发时序、什么状态组合)。 + +| # | 严重度 | 位置(文件 : 函数 : 行) | 问题是什么 | 触发条件 | 影响 | +|---|---|---|---|---|---| +| 1 | 🔴高 / 🟡中 / 🟢低 | | | | | +| 2 | | | | | | +| 3 | | | | | | + +<如果某条你自己也拿不准,就写"我怀疑但没验证" —— 那也很有用。> + +--- + +## 2. 改正意见 + +> 每条说清**怎么改** + **代价**(改起来多大、会不会动到别处、要不要停机)。 +> 如果某处你觉得**整体就该换个做法**,直接说,不用迁就现在的结构。 + +| 对应 # | 建议改法 | 代价 / 风险 | 优先级 | +|---|---|---|---| +| 1 | | | | +| 2 | | | | + +--- + +## 3. 你改了什么(**改了就必须填**) + +> 每条抄一份下面这个小块。**接口路径 / 请求响应字段 / 数据格式**这三样 +> **动了必须单独标出来** —— 这套系统是两台机器上各跑一份代码,不同步会**静默出不来图**。 + +### 改动 1 + +``` +文件 / 函数: +为什么改: +改成什么(一句话): +⚠️ 有没有动:接口路径 [ 是 / 否 ] 请求响应字段 [ 是 / 否 ] 数据格式 [ 是 / 否 ] + 若"是",具体动了什么: +怎么验证的(跑了什么、看到什么): +有没有引入新的依赖: +``` + +### 改动 2 + +``` +(同上) +``` + +--- + +## 4. 我们这边拿不准的,请你表态(逐条答,哪怕一句"现在这样够用"也行) + +**Q1. 支付回调"不验签、改成拿开放接口反查"这个取舍,你认同吗?** + 我们手头没有对方的公钥,与其猜算法不如收到回调后反查这笔单是否真实存在且已付款。 + 你怎么看?有没有更好的做法? + +**Q2. 订单状态机在"部分失败"时怎么收口?** + 比如一单要出 3 张,第 2 张渲染失败。我们现在靠渲染机**显式发一个"收尾"信号**才判完成, + 否则订单会永远停在"渲染中"、被反复重渲。你觉得这个收口方式够不够? + +**Q3. "改完不生效"这类问题,除了"先杀旧进程再起新的",有没有更稳的机制?** + +**Q4. 单机多单:现在渲染是严格串行。** 如果要在同一台机器上支持多单同时渲染, + 你会怎么设计才**不会把机器顶满**?(先说方案,不用实现) + +**Q5. 技术栈:我们现在是"单文件、纯标准库、零依赖"**(路由/校验/序列化全自己写)。 + 好处是小机器跑得动、零安装;代价是自己写的这些一定有漏。 + **换你,你会不会上框架?** 请直说。 + +**Q6. 前后端共用一个质检脚本**(前端负责"拦"给用户看原因,后端负责"剥"元数据块)。 + 这个设计省了逻辑漂移,但**两边判定必须一致**,不一致就会"网页说能传、后端说不行"。 + 你觉得值不值?还是应该只留一边? + +--- + +## 5. 苏达(运维)另外想知道的 + +> 这几条是我个人拿不准的,不属于"必须答",但你要是顺手能指一句,我少走很多弯路。 + +- **3100 行的单文件该不该拆、怎么拆?** 拆的话你最想先拆出哪一块? +- **卡密和订单用 JSON 文件存,而不是数据库**:并发写和"写到一半崩了"这两点, + 在你看来风险有多大?有没有低成本的加固办法? +- **限流现在放在两个地方**(反向代理一层、应用自己一层)。这是重复还是互补? + 有没有可能一边松一边紧、互相打架? +- **内存受限制的前提下**,你扫一眼觉得**还有哪些地方可能爆**? +- **日志与审计**:现在留痕比较散(几个 jsonl + 文件),你觉得够不够追责? + 真要出事(比如买家投诉"我的图被别人下了"),现在这套记录能不能自证? +- **有没有你觉得"我们完全没想到"的角度?** 什么方向都行。 + +--- + +## 6. 你没验证的部分(说明原因就行) + +> 比如"需要真机 / 需要凭据 / 需要买家皮肤 / 时间不够"。**写出来比假装测过好。** + +- <例:渲染链路的真实耗时我没法复现,因为没有渲染机环境> + +--- + +## 7. 你还需要什么材料 + +> 如果你觉得"要是有 XX 我就能判断得更准",列出来,我们补。 + +- <例:一份真实的订单 meta.json 样例(脱敏)> + +--- + +*(感谢。你写的每一条我们都会看,也会回你"采纳 / 不采纳 + 为什么"。)*