backend: 补《他应该知道的》与《回执模板》,并指路

Browse Source
- 他应该知道的.md:生意背景/机器约束/数据边界/术语表/我们的纪律
- 回执模板.md:照着填即可(问题分析+改正意见+你改了什么+我方问题+运维个人想问的)
- 两份交接说明里指向回执模板;仓库根 README 标出两批交付
This commit is contained in:
Suda
2026-10-05 18:55:16 +08:00
parent 1d67fda9d5
commit c6034e9acd
7 changed files with 280 additions and 2 deletions
+14
View File
@@ -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` | | **本地的自助管理后台** | `backend-tools/` | 局域网开单后台(带 PIN 锁)+ 纯本机开单工具 + 渲染机 + Blender 出图脚本 + 部署/启动脚本 | `backend-tools/交接说明.md` |
| **用于测试的工程** | `模板/` | 三个 Blender 模板工程(已脱敏,可直接打开渲染) | `模板/说明.md` | | **用于测试的工程** | `模板/` | 三个 Blender 模板工程(已脱敏,可直接打开渲染) | `模板/说明.md` |
| **其他需要的** | `deploy/` | 反向代理的路由与限流片段(部署层)+ 这一层的取舍说明 | `deploy/nginx-片段.md` | | **其他需要的** | `deploy/` | 反向代理的路由与限流片段(部署层)+ 这一层的取舍说明 | `deploy/nginx-片段.md` |
| **背景须知** | `他应该知道的.md` | 生意背景 / 机器约束 / 数据边界 / 术语表 / 我们这边的纪律 | — |
| **回执模板** | `回执模板.md` | 直接照着填:问题分析 / 改正意见 / 你改了什么 + 我们拿不准的问题 + **运维个人想知道的** | — |
--- ---
+2
View File
@@ -168,6 +168,8 @@ inactive 停用(网页单等付款 / 手动停用)
请你读完之后**回一份文档**(放在同一个仓库里就行,文件名 `回执-<你的名字>.md`),至少包含三部分: 请你读完之后**回一份文档**(放在同一个仓库里就行,文件名 `回执-<你的名字>.md`),至少包含三部分:
> 📋 **格式不用自己起** —— 仓库根目录有一份 `回执模板.md`,照着填就行。
1. **问题分析** —— 你看到的问题、风险、坏味道。分个轻重(会导致丢钱/丢数据/被人打的,排前面)。 1. **问题分析** —— 你看到的问题、风险、坏味道。分个轻重(会导致丢钱/丢数据/被人打的,排前面)。
请**尽量指到具体函数/行**,并说清**触发条件**(什么输入、什么并发时序会踩到)。 请**尽量指到具体函数/行**,并说清**触发条件**(什么输入、什么并发时序会踩到)。
2. **改正意见** —— 每条给**你建议怎么改**(不一定要写代码,说清思路和代价也行)。 2. **改正意见** —— 每条给**你建议怎么改**(不一定要写代码,说清思路和代价也行)。
+2
View File
@@ -107,6 +107,8 @@
同样请回一份 `回执-<你的名字>.md`,含三部分: 同样请回一份 `回执-<你的名字>.md`,含三部分:
> 📋 **格式不用自己起** —— 仓库根目录有一份 `回执模板.md`,照着填就行。
1. **问题分析** —— 你看到的 bug、健壮性问题、坏味道。**特别欢迎**指这几类: 1. **问题分析** —— 你看到的 bug、健壮性问题、坏味道。**特别欢迎**指这几类:
- **静默失败**:出错了但看着"一切正常"的地方(我们被这个坑过好几次) - **静默失败**:出错了但看着"一切正常"的地方(我们被这个坑过好几次)
- **状态不一致**:显示与真实不一致(比如界面说排队中、实际没领单) - **状态不一致**:显示与真实不一致(比如界面说排队中、实际没领单)
+4 -2
View File
@@ -1,10 +1,10 @@
# 交付清单(自查用) # 交付清单(自查用)
> 生成:2026-10-05 18:52 共 29 个文件 合计 44.7 MB > 生成:2026-10-05 18:55 共 31 个文件 合计 44.7 MB
| 文件 | 字节 | SHA-256 | | 文件 | 字节 | SHA-256 |
|---|---|---| |---|---|---|
| `README.md` | 7,532 | `e551e8da39ec955f6d2a25fdd724e2949dffccb6de83d0121df62a8944e909bc` | | `README.md` | 8,498 | `15ccb27558e0612ff1a9fc7822f7a0ec8da298753617b317cbf057a4902ddbb5` |
| `backend-site/admin.py` | 24,214 | `3b9818c063e4c7297d3052cad4ff2a88941b4d07b85e2e5eaf495eed35d3f484` | | `backend-site/admin.py` | 24,214 | `3b9818c063e4c7297d3052cad4ff2a88941b4d07b85e2e5eaf495eed35d3f484` |
| `backend-site/pngcheck.py` | 4,945 | `ccec7ab21b0399da651029ffa5781bad498e0905b31a1102f6ba3e3f01e8594d` | | `backend-site/pngcheck.py` | 4,945 | `ccec7ab21b0399da651029ffa5781bad498e0905b31a1102f6ba3e3f01e8594d` |
| `backend-site/server.py` | 160,560 | `9470b057f9eaf1927d06917ac5909fb0e733a4b44a04c039b82bbd907b9f2a62` | | `backend-site/server.py` | 160,560 | `9470b057f9eaf1927d06917ac5909fb0e733a4b44a04c039b82bbd907b9f2a62` |
@@ -29,6 +29,8 @@
| `backend-tools/ys_worker.py` | 30,465 | `ab6cdff13ce16ed15363c28cf016628b378a1ec255d2b8eeb62566cf38631eb9` | | `backend-tools/ys_worker.py` | 30,465 | `ab6cdff13ce16ed15363c28cf016628b378a1ec255d2b8eeb62566cf38631eb9` |
| `backend-tools/交接说明.md` | 11,008 | `731c591b545c4332c3ad5336910a78e5dfb8b6541da6f33e8f4e70bb3b7dab48` | | `backend-tools/交接说明.md` | 11,008 | `731c591b545c4332c3ad5336910a78e5dfb8b6541da6f33e8f4e70bb3b7dab48` |
| `deploy/nginx-片段.md` | 4,145 | `183179dc694e1f2ac3a791f3c96aa6f7d292b1968276ae1af4d850e26fbf78d0` | | `deploy/nginx-片段.md` | 4,145 | `183179dc694e1f2ac3a791f3c96aa6f7d292b1968276ae1af4d850e26fbf78d0` |
| `他应该知道的.md` | 6,988 | `177f08cb455bf5cf4b299abda5b227ff530c1da634c69f81c8ca7498ccc00cbe` |
| `回执模板.md` | 5,049 | `0e38a6c19dff7b55767b8998d294b0252aa6024053dad0c63956ddd58b56a07a` |
| `模板/1站立正反.blend` | 16,486,783 | `985dc61aeaa6eaaf5dc87ccbba6dfd4e1c5eb95468f7d0a9610d47aff14cb9dc` | | `模板/1站立正反.blend` | 16,486,783 | `985dc61aeaa6eaaf5dc87ccbba6dfd4e1c5eb95468f7d0a9610d47aff14cb9dc` |
| `模板/4海边自拍.blend` | 18,101,431 | `629df363d00e73e18820bddb6b7b92d7dbdd55d0f5c98de5378c76a48b705183` | | `模板/4海边自拍.blend` | 18,101,431 | `629df363d00e73e18820bddb6b7b92d7dbdd55d0f5c98de5378c76a48b705183` |
| `模板/5不看爆炸.blend` | 11,849,599 | `3bb67516632e206c89fe44e2cf04667f5e34e1eab70e395c00830555e033e223` | | `模板/5不看爆炸.blend` | 11,849,599 | `3bb67516632e206c89fe44e2cf04667f5e34e1eab70e395c00830555e033e223` |
+119
View File
@@ -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),
都是被真实压力逼出来的,不是过度设计 —— 但也**欢迎你说"这处没必要"**。
+126
View File
@@ -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 样例(脱敏)>
---
*(感谢。你写的每一条我们都会看,也会回你"采纳 / 不采纳 + 为什么"。)*