# 数据信息填报系统 · 文档中心

> 职业技能等级认定**报名材料收集 SaaS**
> **一期范围**：学校收集 + 自主认定（4 类材料，全部有实测样本）。社会收集 / 社会评价 / 专项职业能力后置二期
> 学生在微信小程序填报 · 班主任在手机初审 · 管理员在 PC 终审与导出
> 最后更新：2026-09-28　|　**状态：需求已冻结（客户全部确认，可开工）**

---

## 一、这是什么

客户（职业院校 / 认定机构）每年要收集几百名学生的认定报名材料（一寸照片、身份证、学籍表、工作证明）。现状是靠班主任在微信群里收、手工改名、手工压缩、手工核对——**一个班 28 人就有 112 个文件、59 个命名违规、31 个超体积**，全靠人眼。

本系统把这件事做成流程：**门禁核验 → 按规则自动命名与压缩 → 材料识别 → 校验 → 分级审核 → 一键导出规范包**。

**核心增量**：官方 Excel 模板里「报考职业」「报考工种」是自由填写、没有下拉——我们把它变成**从名单聚合 + 一致性体检**。

---

## 二、文档地图

### 按角色读

| 你是 | 从这几份开始 | 顺序 |
|---|---|---|
| **客户 / 业务方** | `01-客户与机构确认函.md` → `prototype/index.html` | 先看确认函（有 23 项待拍板），再点开原型 |
| **项目经理** | `00-交付计划.md` → `05-开发任务拆解.md` → `交接摘要.md` | 先看进度，再看 94 个任务与 14 周排期 |
| **产品 / 需求** | `数据信息填报系统PRD.md` → `数据信息填报系统PRD-功能逻辑卷.md` | 前者含库表接口，后者是纯功能逻辑 |
| **后端开发** | `03-接口设计.md` → `04-核心模块设计说明.md` → `db/schema-postgresql.sql` | 接口收发 → 引擎怎么做 → 建表 |
| **前端开发** | `prototype/` → `03-接口设计.md` | 原型是视觉与交互的**唯一基准** |
| **测试** | `06-验收测试清单.md` → `04-核心模块设计说明.md` 附录 B | 29 条 Golden 断言 + 85 条功能验收 |
| **新加入的人** | `交接摘要.md` → 本文件 | 一份文档看清全部状态 |

### 全部文档

| # | 文档 | 规模 | 内容 | 状态 |
|:--:|---|:--:|---|:--:|
| 00 | `00-交付计划.md` | 8 KB | 7 项计划与进度追踪、风险跟踪 | ✅ |
| 01 | `01-客户与机构确认函.md` | 18 KB | **23 项已全部确认** + 客户回执 + 落地动作清单 | ✅ **需求冻结** |
| 02 | `02-需求追溯矩阵.md` | 10 KB | 115 条 FR ↔ 原型/库表/接口 的自审报告 | ✅ |
| 03 | `03-接口设计.md` | 112 KB | **121 个接口**字段级定义、枚举全集、12 个 VO、**57 个错误码** | ✅ |
| 04 | `04-核心模块设计说明.md` | 56 KB | **6 个模块**伪代码级说明 + 依赖图 + 26 项回归基线 | ✅ |
| 05 | `05-开发任务拆解.md` | 31 KB | **100 个任务 / 387 人日 / 15 周**，含关键路径、一期范围与风险 | ✅ |
| 06 | `06-验收测试清单.md` | 29 KB | **36 条 Golden 断言** + 111 条功能验收 + 签署表 | ✅ |
| — | `交接摘要.md` | 11 KB | **状态源**：客户回执、13 条铁律、已完成、待办、环境、教训 | ✅ |
| — | `数据信息填报系统PRD.md` | 190 KB | 主 PRD V2.3+：**125 条 FR**、**21 条 VAL**、**20 张表 DDL**、验收标准 | ✅ |
| — | `数据信息填报系统PRD-功能逻辑卷.md` | 88 KB | 纯功能运转逻辑（**不含库表/接口/代码**） | ✅ |
| — | `db/schema-postgresql.sql` | 36 KB | 可执行 PG DDL（20 表），**已在 PostgreSQL 16 实测零错误** | ✅ |
| — | `prototype/`（4 份） | 240 KB | **31 屏**交互原型：学生端 11 / 班主任端 9 / 管理端 11 | ✅ |

---

## 三、三分钟看懂产品

### 一条主线

```
          ┌─ 学生端（小程序）─┐   ┌─ 班主任端（手机）─┐   ┌─ 管理端（PC）─┐
名单 ──→  门禁核验 ──→ 填报 ──→   卡片流初审 ──→ 终审 ──→ 导出规范包
          └─✗ 失败 → 申请加入名单 → 管理员审批 → 入册放行
 ▲                  ▲   ▲                                        ▲
 │                  │   │                                        │
 报考范围           识别 命名+压缩                              汇总 Excel
 从名单聚合         校验  (≤1M 无例外)                          + 目录树
```

### 两个必须知道的数字

| 数字 | 含义 |
|---|---|
| **59 / 112** | 真实批次里的命名违规率（52.7%）。系统自动修 |
| **475 MB → 37 MB** | 原始总量 → 导出包，压缩率 92%。**300dpi 清晰度零损失** |

### 三条铁律（不要试图绕过）

| # | 铁律 | 理由 |
|:--:|---|---|
| 1 | **必须先导名单**，姓名+身份证匹配不通过不放行 | 门禁是产品根基 |
| 2 | **有不合格文件时直接禁用导出按钮** | 带问题打包出去，返工成本远高于当场修 |
| 3 | **识别失败一律放行** | 不阻断提交是完成率的底线 |
| 4 | **归属存疑一律阻断，且无"仍然继续"** | 文件名的姓/证号指向别人 = 传错材料。**自动改名会把错传洗白**，审核看不出来、事后无从追溯 |

---

## 四、关键决策速查

> 完整 13 条见 `交接摘要.md` 第二节。这里只列最容易被反复讨论的。

| 决策 | 内容 |
|---|---|
| 压缩 | **强制 ≤1M，无例外**；默认 300dpi/q85（实测 28/28 达标，均值 806KB） |
| 材料来源 | 只有**聊天记录 / 相册 / 手机文件**，「直接拍照」默认关闭 |
| 报考范围 | **从名单聚合**，不存在独立的"计划清单"文件 |
| 数据库 | **PostgreSQL**（纯 PG）；软删除字段名 `deleted` |
| 滑动交互 | 班主任端**只做右滑通过**，驳回必须点按钮 |
| 批量通过 | **只带无问题项**，红黄一律排除 |
| 动态表单 | 内置字段（固定列可统计）+ 扩展字段（`extras_json`） |
| 名单外的人 | **申请加入名单 → 管理员逐条审批**；通道只解决"进名单"，**不绕过门禁** |
| 归属判定优先级 | **证件号反查名册 > OCR 内容 > 姓名（仅辅助，不做独立规则）** |
| 联系方式 | **系统内不展示任何班主任/管理员联系方式**——学生本来就有；门禁失败只给「重新填写 / 申请加入名单」两条系统内出路 |
| 校验位的作用 | **失败 = 不是真实号码 → 可自动改**；**通过 = 真人 → 改了就是改身份 → 必须阻断** |
| 审批粒度 | 批量通过**不提供"全选"**，驳回**必须逐条填原因**（身份认定误操作代价极高） |

---

## 五、目录结构

```
xiaotutongxue/
├── README.md                      ← 本文件
└── docs/
    ├── 00-交付计划.md
    ├── 01-客户与机构确认函.md
    ├── 02-需求追溯矩阵.md
    ├── 03-接口设计.md
    ├── 04-核心模块设计说明.md
    ├── 05-开发任务拆解.md
    ├── 06-验收测试清单.md
    ├── 交接摘要.md
    ├── 数据信息填报系统PRD.md
    ├── 数据信息填报系统PRD-功能逻辑卷.md
    ├── db/
    │   └── schema-postgresql.sql
    └── prototype/
        ├── index.html              ← 三端入口，从这里打开
        ├── student-app.html
        ├── teacher-app.html
        └── admin-web.html
```

---

## 六、快速上手

### 看原型

直接双击 `docs/prototype/index.html`。**单文件自包含、零外部依赖**，不需要服务器。
管理端原型支持 100% / 82% / 66% 缩放查看。

### 验证数据库

```bash
# 起一个 PG 容器
docker run -d --name pg-verify -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=filldb -p 5432:5432 postgres:16

# 执行 DDL
docker exec -i pg-verify psql -U postgres -d filldb < docs/db/schema-postgresql.sql

# 验证结果：19 张表 / 167 列注释 / 61 索引，零错误
docker exec -it pg-verify psql -U postgres -d filldb
```

> 容器仍在本机运行时可 `docker exec -it pg-verify psql -U postgres -d filldb` 直接进入；
> 不需要了用 `docker rm -f pg-verify` 清理。

### 跑原型结构校验

```bash
python check2.py docs/prototype/admin-web.html
# 输出：标签配对 / CSS 变量 / SVG 图标 / emoji / 外部依赖 五项检查
```

---

## 七、交付状态

| 阶段 | 内容 | 状态 |
|---|---|---|
| **需求** | 主 PRD（**125 FR** / 20 VAL / **20 张表**）+ 功能逻辑卷 | ✅ |
| **设计** | 数据库 DDL（PG 16 实测）+ 接口设计（**121**）+ 模块设计（6） | ✅ |
| **原型** | **31 屏**（学生 **11** / 班主任 9 / 管理 **11**）= 31 | ✅ |
| **计划** | **100 任务 / 387 人日 / 15 周**（一期范围已收窄） | ✅ |
| **测试** | **36** 条 Golden 断言 + **111** 条功能验收 | ✅ |
| **待外部** | ~~客户确认函（23 项）~~ | ✅ **已确认，按建议执行** |

### 客户已确认（2026-09-28 · 可开工）

| 项 | 确认结论 |
|---|---|
| **A1** | ✅ 认定机构接受 300dpi 输出 |
| **B1** | ✅ 增加「申请加入名单 → 管理员审批」通道（**唯一功能增量，已落地**） |
| **B3** | ✅ 字段三分类：姓名/证件号/报考三项锁定，其余可核对修改并留痕 |

**其余 20 项均与现有设计一致，零改动。** 需求已冻结，可按 `05-开发任务拆解.md` 的 **M0** 开工。

---

## 八、数据与测试基线

| 项 | 值 |
|---|---|
| **Golden Test Set** | `D:\项目\202609机电填报系统\24中技数控1班\` |
| 规模 | 28 人 × 4 类材料 = **112 个文件**，原始 **475 MB** |
| 命名违规 | **59**（52.7%） |
| 双扩展名 | **56** |
| 体积超标 | **31** |
| 证件号异常 | **5**（自动修 3 + 待人工 2） |
| 疑似串档 | **1**（唯一必须人工判断的） |
| 压缩后 | 均值 **806 KB**，最大 **831 KB**，**0 张超标** |
| 导出包 | **≈37 MB**，压缩率 **92%** |

> ⚠️ **这个数据集不可替代**。所有"实测"结论都来自它；换成构造数据，双扩展名 56/112 这种数字就复现不出来。
> 必须纳入版本管理或保留只读副本。

---

## 九、开发环境

| 项 | 说明 |
|---|---|
| 数据库 | PostgreSQL 16（DDL 已实测通过） |
| 开发顺序 | **M1 命名引擎 → M4 门禁 → M2 压缩 → M5 校验 → M3 识别 → M6 导出** |
| 客户回执 | 全部 23 项按建议执行；唯一功能增量 B1（申请加入名单）已落地 |
| 原型约束 | 单文件自包含、零外部依赖、内联 SVG 图标、**无 emoji** |
| 最长的两个单点 | 压缩引擎 12 人日、打包引擎 10 人日（**加人无效**） |
| 回归门禁 | 改动后必须复现 **15 项基线指标**（对应 29 条断言），偏差即回归 |

---

## 十、两条踩过的坑

| # | 教训 |
|:--:|---|
| 1 | **脚本审计前先验证脚本本身**。追溯矩阵审计时脚本漏匹配加粗编号，误报 3 个"需求问题"，若直接采信会引入 3 处错误 |
| 2 | **引用已有编号前先脚本核对，不凭记忆**。模块设计里把 VAL 编号整体写错位（VAL-01 是姓名 vs 证件号格式），若不查会与 PRD 互相矛盾 |

> 详见 `交接摘要.md` 第七节。

---

**文档中心维护约定**：任何改动后，请更新 `00-交付计划.md` 的执行记录与 `交接摘要.md` 的状态；改动接口/库表/FR 编号时，**必须重跑跨文档一致性核对**。