曼陀林知识库

Edit the page and hit Save. See syntax for Wiki syntax. Please edit the page only if you can improve it. If you want to test some things, learn to make your first steps on the playground.

====== 研发库房管理 H5 — 冷启动文件 ======

> 版本: 2.3 ｜ 更新: 2026-08-30 ｜ 用途: 研发库房样品出入库管理系统的冷启动/重建/排障手册
> ⚠️ **功能保全铁律（用户 2026-08-30 定稿）：本系统功能只增不减，改版前先读本文件"功能清单"，改完按"改版验证清单"逐项验证，功能不允许丢失。**
> ⚠️ **测试铁律（用户 2026-08-30 强调）：测试必须用独立库（STORE_DB=/tmp/store_test.db + STORE_PORT=13599 起独立实例），严禁操作生产库；测试数据必须即时删除清理，严禁残留污染生产数据（曾两次残留被用户发现）。**
> 地址: http://82.156.85.124:13545/store/ ｜ 服务: rd-store.service（systemd，:13545）
> 数据库: /home/ubuntu/docs/store/store.db（SQLite，samples/requests/history 表，软删除保留历史）
> 附件: /home/ubuntu/docs/store/attachments/ ｜ 前端: ~/.hermes/scripts/rd_store.html（单文件零外链）｜ 后端: rd_store.py

===== 1. 核心业务流程（用户定稿 2026-08-28~30） =====

<code>
物料编码（A+10位数字，唯一，自动随机/手动/反查）
   ↓
样品入库登记（新样品，全字段+图纸+备注，数量→生成个体编号 N1~Nn）
   ↓
出库申请（选样品显示详情+选编号，默认顺序，备注信息）→ 审核人批准 → 生成准出编号（ZC-YYYYMMDD-NNN）→ 扣库存
   ↓ 测试后重新入库（申请-审核制，三种模式）
原样品（原物归库）/组合样品（新建）/组合样品（原物归库）→ 填写审核人 → 📨 提交入库申请（待审核）→ 审核人批准 → 执行入库（恢复在库/新建组合样品/各准出编号抵消台账）
   ↓ 破坏性测试报废
销毁申请（按准出编号）→ 输入准出编号→确认→显示对应样品信息→审核人批准→该编号作废(已销毁)
   ↓
领料人台账：出库挂人名下，未抵消 = 出库总量 - 归还总量 - 销毁总量（销毁也抵消）；最新记录在上
<code>

===== 2. 数据模型 =====

* **samples 表**（软删除）：id/data(JSON)/deleted/deleted_at/created_at
  * data 含：id/name/material_code(A+10位唯一)/model/spec/supplier{name,addr,phone}/waybill/qty/project/purpose/in_time/operator/photo/status(新样品|入库留样保存)/location/drawing/remark(备注追加不覆盖)/combine/units[](个体编号N1~Nn: no/status/pass_no/out_log[])/compose_pass/hist[](出入库历史含备注)
  * **requests 表**：申请记录（kind 出库|销毁 / sample_id/qty/units[](编号)/receiver/auditor/status/pass_no/settled(台账抵消)/settle_time/note(备注)）
  * **history 表**：出入库流水（note 含"审核批准，备注：xxx"）

===== 3. API 表 =====

| API | 方法 | 说明 |
| ----- | ------ | ------ |
| /api/store/meta | GET | 人员(钉钉全量)+历史下拉(样品名/供应商/项目/用途/位置/型号/物料) |
| /api/store/material?code= | GET | 按物料编码反查物料全部信息（唯一性定位） |
| /api/store/samples | GET/POST | 样品列表（qty=在库个体数）/ 入库登记（物料编码自动生成或查重） |
| /api/store/samples/<id> | POST | 修改档案（白名单字段，不碰 units/hist） |
| /api/store/samples/<id> | DELETE | **软删除**（进回收站，可恢复） |
| /api/store/samples/<id>/append | POST | 追加数量（编号顺延 N11、N12...） |
| /api/store/out | POST | 出库申请（unit_no 指定编号或默认顺序，note 备注） |
| /api/store/destroy | POST | 销毁申请（**按准出编号**：pass_no 校验+防重复） |
| /api/store/requests | GET | 申请列表 |
| /api/store/requests/<id> | POST | 审核（approve 出库→准出编号+标记编号出库 / 销毁→核销该编号 / reject） |
| /api/store/requests/<id> | DELETE | 删除申请记录 |
| /api/store/find?pass_no= | GET | 按准出编号查样品全量信息（原样品/销毁用） |
| /api/store/back_apply | POST | **入库申请**（mode=orig/comb/append，提交申请待审核，防重复） |
| /api/store/back | POST | 原样品/组合样品原物归库执行（申请审核后调用；已销毁拒绝） |
| /api/store/combine | POST | 组合样品新建（新档案+编号 N 序+多个准出编号→各抵消台账） |
| /api/store/ledger | GET | 领料人台账（出库全量+归还+销毁+未抵消=出库-归还-销毁） |
| /api/store/history | GET | 流水列表（note 含备注） |
| /api/store/history/<idx> | DELETE | 删除流水（idx=数组下标） |
| /api/store/trash | GET | 回收站（已删除样品） |
| /api/store/trash/<id> | POST | 从回收站恢复样品 |
| /api/store/upload | POST | 附件上传（照片/图纸） |

===== 4. 关键规则 =====

* **物料编码**：A+10位数字，样品唯一标识；自动随机生成（去重50次）或手动录入；已有编码拒绝重复建档并显示该物料全部信息
  * **个体编号**：数量 N → 生成 N1~Nn；出库按编号（默认顺序=最小在库编号），重新入库按编号匹配；追加数量编号顺延
  * **准出编号**：ZC-YYYYMMDD-NNN，审核批准时生成；只有贴准出编号样品可做研发测试（测试才有效）；**每次出库须重新申请生成新准出编号**
  * **销毁**：按准出编号销毁（申请校验编号存在/未销毁/未归还+防重复申请）；批准后该编号作废；**已销毁编号不可再销毁/重新入库/出库**
  * **台账抵消**：原样品/组合样品原物归库 → 各准出编号 settled=true；**未抵消 = 出库总量 - 归还总量 - 销毁总量**（销毁也抵消）
  * **审核人默认武燕青**（所有申请表单自动填入，可改）
  * **销毁原因**写入销毁申请备注（审核中心可见）
  * **申请全部显示备注**（出库/销毁/入库，待审核+已处理列表均显示）
  * **备注**：出库申请"备注信息"贯穿样品历史/流水/台账；样品备注追加不覆盖
  * **库存只走出入库/销毁流程**；删除样品=软删除（历史保留可恢复）
  * **历史保护**：编辑只改白名单字段；SQLite+软删除+git 三重保障

===== 5. 部署与运维 =====

<code>
重启：sudo systemctl restart rd-store.service
日志：journalctl -u rd-store.service -n 50
防火墙：腾讯云轻量 13545 TCP（lhins-1dai07vu ap-beijing）
数据库：sqlite3 ~/docs/store/store.db（samples 表 deleted=1 即回收站）
测试隔离：STORE_DB=/tmp/store_test.db STORE_PORT=13599 venv/bin/python rd_store.py（独立实例，测完删库）
前端改完即生效（读文件）；后端改完需重启
<code>

===== 6. 界面规范（永久保留，禁止回归） =====

* **人员选择 = 文本框下拉列表**（2026-08-30 用户定稿）：所有人员字段（操作人 iOp/bOrigOp/cOp/apOp、领料人 oRecv、审核人 oAud/dAud、申请人 dRecv）均用 combo 组件：
  * 下拉选项 = **钉钉通讯录全量**（/api/store/meta 的 people，实时拉取+快照兜底）
  * 点击/输入文本框 → 弹出下拉（输入即时过滤），**选择后自动收起**（comboDDs）
  * 下拉用普通流布局（不绝对定位）→ **不遮挡下方内容**，展开时推挤下方
  * 可自定义输入新人员（文本框）
  * 项目选择（iProj/oProj）同 combo 组件（历史项目列表）
  * combo 绑定列表维护位置：fillDatalists() 中 `['iOp','oRecv','oAud','dRecv','dAud','bOrigOp','cOp','apOp']`——**新增人员字段必须同步加入此列表**（曾因 bOp 改名漏绑导致原样品/组合入库人员无下拉）
  * **样品选择下拉：名称后不加括号内容**（曾导致用户无法选择编号）；出库编号下拉只显示纯编号
  * ⚠️ **fillDatalists 必须用 setDL 安全填充**（元素不存在不报错）——曾因删除 hisMat datalist 导致 combo 绑定全部中断
  * ⚠️ **getElementById 赋值前必须判空**——销毁改准出编号后 dSamp 删除导致 renderSampSelect 中断、出库编号下拉空白（用户无法选编号）
  * 页面禁缓存（meta no-cache + 服务端 no-store）——微信缓存旧 JS 曾导致下拉空白/样品不存在

===== 7. 功能清单（2026-08-30 存档，只增不减） =====

| # | 模块 | 功能点 |
| --- | ------ | -------- |
| 1 | 📦 样品档案 | 列表/搜索(名称编码型号位置+样品名下拉)/筛选(状态/项目)/详情(全部字段+图纸+备注+编号明细含转出记录+出入库历史)/软删除/✕删/＋追加数量(编号顺延) |
| 2 | ⬇️ 样品入库 | 全字段：名称(历史下拉)/物料编码(A+10位自动随机🔄/手动/反查确认显示物料信息)/型号/规格/图纸📄/供应商(名址电)/运单/数量(编号N1~Nn提示)/项目(下拉)/用途/时间/操作人(下拉)/状态/位置(下拉)/照片/备注 |
| 3 | ⬆️ 出库申请 | 选样品→显示全部详情/数量/在库编号下拉(纯编号,默认顺序=最小在库,自动带出第一个)/领料人(下拉)/领料时间/项目(下拉)/审核人(下拉)/**备注信息** |
| 4 | ✅ 审核中心 | 待审列表(出库/销毁/**入库**)批准→出库生成准出编号/销毁核销/入库执行/驳回/已处理列表+✕删；**全部显示备注列**（含销毁原因） |
| 5 | 💥 销毁申请 | **按准出编号**：输入准出编号→确认→显示对应样品信息→申请人(下拉)/审核人(下拉)/销毁原因→审核批准→该编号作废(已销毁)；防重复销毁；销毁后禁重新入库 |
| 6 | ↩️ 重新入库 | **申请-审核制**（填审核人提交申请，批准后执行）：**原样品(原物归库)**/组合样品(新建)/组合样品(原物归库) 三模式，批准后恢复在库/新建组合样品/抵消台账 |
| 7 | 👤 领料人台账 | 按人分组：出库(全量含已归还)/归还/销毁/未抵消=出库-归还-销毁；最新记录在上；显示样品编号/准出编号/物料编码/备注 |
| 8 | 📜 流水 | 全量记录(含备注)+每行✕删 |
| 9 | 🗑️ 回收站 | 已删除样品列表(软删除保留)+一键恢复 |
| 10 | 👥 人员选择 | **所有人员字段=文本框下拉列表（钉钉通讯录全量18人，输入过滤，选中自动收起，不遮挡下方）——永久规范** |
| 11 | 🗄️ 数据 | SQLite 数据库（软删除保留历史）/附件上传(照片/图纸)/git 管理 |

===== 8. 改版验证清单（改完必查，防止功能丢失） =====

<code>
① 8 个人员字段 combo 绑定正常（iOp/oRecv/oAud/dRecv/dAud/bOrigOp/cOp/apOp）——点输入框弹出钉钉全量下拉，选中自动收起
② fillDatalists 无 null 报错（必须用 setDL 安全填充）；renderSampSelect 无 null 报错（getElementById 判空）
③ 主流程走通：入库→出库申请(选编号)→审核(准出编号)→重新入库申请→审核批准执行(台账抵消)→按准出编号销毁；审核人默认武燕青
④ 物料编码：自动生成格式 A+10位 / 手动查重 / 反查显示物料信息
⑤ 样品档案：搜索/筛选/详情/软删除→回收站→恢复/追加数量
⑥ 台账：未抵消=出库-归还-销毁；最新在上；备注显示
⑦ 数据不丢：SQLite 软删除 + git 提交
⑧ 测试用独立库（STORE_DB/STORE_PORT），测完删库，生产零污染
<code>

===== 9. 排障速查 =====

| 现象 | 处理 |
| ------ | ------ |
| 人员列表为空 | /api/store/meta；.env DINGTALK_CLIENT_ID/SECRET；ding_org.json 快照兜底 |
| 数据库只读 | chown ubuntu:ubuntu ~/docs/store/store.db |
| 样品删除找不到 | 回收站 tab（软删除，可恢复） |
| 物料编码重复 | 自动生成去重；手动输入已有→拒绝+显示物料信息 |
| 台账未抵消计算 | 未抵消=出库-归还-销毁；销毁仅统计 kind=销毁（曾把入库申请误算为销毁，已修复） |
| 出库编号下拉空白 | ①强刷(微信缓存) ②renderSampSelect 无 null（dSamp 判空）③loadAll 完成后再切 tab |
| 删除记录刷新又出现 | save 已改全量同步（DELETE+INSERT），若再出现重启服务 |
| 台账无中生有记录 | **测试污染**：测试必须独立库 STORE_DB（2026-08-30 修复） |
| 外网打不开 | 防火墙 13545 + systemd 状态 |

Edit summary

Note: By editing this page you agree to license your content under the following license: CC Attribution-Share Alike 4.0 International