Files
jinzuanwork/backend/他应该知道的.md
T
Suda c6034e9acd backend: 补《他应该知道的》与《回执模板》,并指路
- 他应该知道的.md:生意背景/机器约束/数据边界/术语表/我们的纪律
- 回执模板.md:照着填即可(问题分析+改正意见+你改了什么+我方问题+运维个人想问的)
- 两份交接说明里指向回执模板;仓库根 README 标出两批交付
2026-10-05 18:55:16 +08:00

120 lines
6.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 他应该知道的(背景须知 · 请先读这份再看代码)
> 你手上的是一份**脱敏过的真实生产代码**。光看代码有很多东西推不出来 ——
> 这门生意怎么转、机器什么条件、哪些能动能不能动、哪些数据碰不得。这份补齐。
> **看完这份再看 `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),
都是被真实压力逼出来的,不是过度设计 —— 但也**欢迎你说"这处没必要"**。