feat(entry): 团体项目多队（迁移 0025）+ 修联队团体名次 / 大屏分项成绩 / 预览算分口径；版本 dev_0.5.5

## 一、新能力：团体项目多队现场：羽毛球双打，一个单位可能派两个队，一个单位两个队各占一个名次。 - 迁移 `0025_entry_squad.sql`：`entries` 加 `squad TEXT NOT NULL DEFAULT ''`（自由文本队名，空串＝不区分队伍）；唯一索引由 `(category_id, team_id) WHERE athlete_id IS NULL` 换成 `(category_id, team_id, squad) WHERE athlete_id IS NULL` —— 原来那条正是「一个单位在一个组别只能报一条团体报名」的拦路虎。 - 导入：**第 13 列「队伍」**（`squad` / 队伍 / 队名 / 队伍名，可选，放最后）；老 12 列表照常导入。 - 显示：`单位名 + 队名`（不加括号），榜单不写队名（分与牌本来就归单位）。 - 新增「改队名」：`PUT /api/entries/{id}/squad` + 「成员单位与份额」弹窗里的队伍输入框（只对纯团体报名显示）。改队名**不需要重算**（`grep squad server/internal/domain/` = 0 处，改名前后流水/名次/榜单逐字节相同）。 - **老数据零变化**：接口层 JSON 剥掉新字段后逐字节相同；导出层 9 份导出件全单元格 750 行 dump 的 md5 相同。 ## 二、修：团体名次控件没体现联队联队的成员单位在「团体名次」里各占一行 → **合并成一行**（标签用大屏/导出一致的联队名），名次**只落主单位**；成员单位不再进保存载荷，顺手堵掉「看 A、B 各一行，给 B 也录一个名次 → B 重复拿分」。被并掉的成员单位原来若录过名次，区块里点名提示「已并入联队那一行，保存后清除」，不静默吞。 ## 三、修：大屏「分项成绩」排名错乱现场：第 3 栏列出的项目排名跳着显示（3、6、9、14、15、16），羽毛球单打第 1 名不显示。 **根因**：`group.rows.slice(0, 6)` 取的是**数据到达顺序**，整条渲染链**没有一处读 `rank`**。修法：按名次升序（并列保持原先后、无名次排最后）再截断 —— 与同页「实时赛况」的既有口径一致。复现证据：修前 `actual: [3,6,9,14,15,16]`（与现场数字一致）、`expected: [1,2,3,4,5,6]`。顺带澄清：「只有第 3 栏出问题」不是栏的问题，是那一栏分到的数据次序不成立。 ## 四、修：录入页预览算分与后端口径不一致（四处 + 一条延伸）现场：手动录名次的项目（台球）「积分（自动）」列全是 0，而后端**有分**。 1. **预览不读 `channel_manual_ranks`、也不按通道 scope 分名次来源** → 「按单位录名次」的项目预览全 0，反过来名次填在成绩表时预览有分而服务端 0； 2. **末位归零判据不同**：预览原本「区间跨末位就整组归零」，与后端的 `startRank == lastPlace` 不符（并列第 1 时预览 0、服务端 10）； 3. **`compare=none` 时预览静默降级成 manual**（后端此时直接报错）→ 改为同口径：显示**原因**而不是一个算不出来的数字； 4. **管理端保存计分通道缺守卫**：`compare=none + basis=result/aggregate` 原先只有规则包导入拦，手工能配出来、到发布才报错 → 保存前 400 + 人话。延伸：预览的「已发布分」基线**只扣行分**，不挂报名项的分（团体名次那类）没扣 → 发布确认框「最大分差」虚高；新增 `unitPoints` 一并扣。 ## 五、修：手录名次项目的「成绩」列空白 `displayResult()` 在 `resultValue`/`resultText` 都拿不到时**漏出空值**（且函数声明返回 `string`）→ 新增占位 `—`、类型收紧，实时赛况与底栏对齐同一口径。 ## 文档 `docs/报名名单导入规范.md`（12 → 13 列）、`docs/使用手册.md`（多队章节）、 `docs/升级说明.md`（新增 `dev_0.5.5` 一节）、`debug/使用说明/` 七份同步。 ## 验证 - 全量自检两轮**全绿、`EXIT=0`**：服务端 14 包 / 前端 **883 例** 0 fail / Console 68 例 0 fail。 - 各块都先写会红的测试、留了原始输出（含现场报的那组数字与「预览全 0」）。 ## 版本 `dev_0.5.4` → **`dev_0.5.5`**（含数据迁移 `0025`）；安装器素材同步重生成（照例只动 `brand.bmp` 两张）。 ## 下一批 `dev_0.5.6` = **团体报名队员身份**（把队员从文字名单变成人员关联，标识用**号码布**），工单见 `devdocs/20-团体报名队员身份.md`。
2026-09-14 11:45:32 +08:00
1 parent 9663d5bfb0
commit 7a3e4ad365
@@ -102,7 +102,7 @@

 表格列依次为：勾选框、录入（状态徽标）、号码、批次、单位、运动员 / 队、成绩输入、名次、状态、积分（自动）、备注、操作。**「运动员 / 队」这一列在姓名后面直接跟着该人的号码布**（灰色小字，例如 `张伟 101`）：号码列仍然保留，这一处只是省得在长表格里左右横跳找号。

-**「单位」这一列兼作「成员单位与份额」的入口**：普通报名显示单位简称（或全称）——**这一格与以前长得一模一样**，只是鼠标移上去变成手型、旁边有一行悬停提示，**点一下**会打开「成员单位与份额」弹窗（什么单位参赛、各占多少，见 4.11）。一条报名挂了多个单位（**联队**，两个单位因人数不足合并参赛）时，这一格会多一个「联队」小标，并把成员单位与份额逐条列出来：`联队 第一分公司 50% 第二分公司 50%`；不是均分时还会带上权重，例如 `联队 第一分公司 67%（权重 2） 第二分公司 33%`。
+**「单位」这一列兼作「成员单位与份额」的入口**：普通报名显示单位简称（或全称）——**这一格与以前长得一模一样**，只是鼠标移上去变成手型、旁边有一行悬停提示，**点一下**会打开「成员单位与份额」弹窗（什么单位参赛、各占多少，见 4.11）。一条报名挂了多个单位（**联队**，两个单位因人数不足合并参赛）时，这一格会多一个「联队」小标，并把成员单位与份额逐条列出来：`联队 第一分公司 50% 第二分公司 50%`；不是均分时还会带上权重，例如 `联队 第一分公司 67%（权重 2） 第二分公司 33%`。**报名的队名**（同一个单位派两个队时写的那个，见 4.12）直接跟在单位名后面显示，例如 `第一分公司二队`；**没填队名时这一格与以前逐字一样**。

 | 列 | 操作 |
 | --- | --- |
@@ -300,7 +300,8 @@
 3. 底部「**添加成员单位…**」下拉里选一个单位再点「添加」——下拉里列的是还没在成员里的单位（**已停用**的单位也可以加，会标注「已停用」；被「彻底删除」的单位不出现）；
 4. 弹窗下方实时显示 `当前比例：第一分公司 50% · 第二分公司 50%`，两个以上成员时旁边还会给出联队名预览（`第一分公司+第二分公司联队`）；
 5. **主单位不能去掉**（它的「移除」是灰的）：报名挂在它名下，要换主单位只能重新建报名；
-6. 点 **「保存成员单位」** 提交——服务端**当场重算该小项该组别**的名次与积分并刷新大屏榜单，提示「成员单位已保存」。**没改动时保存按钮是灰的**，点「关闭」不会发出任何请求。
+6. **纯团体报名还会多一个「队伍」输入框**（同一个单位派两个队时写队名，见 4.12）：**只有纯团体报名显示这个框，个人报名连框都不出现**；留空 = 不区分队伍。它与份额是**两个接口**，改队名**不会重算榜单**（队名只是标签）；
+7. 点 **「保存成员单位」** 提交——服务端**当场重算该小项该组别**的名次与积分并刷新大屏榜单，提示「成员单位已保存」。**没改动时保存按钮是灰的**，点「关闭」不会发出任何请求。按钮上的字会按你改了什么变：只改队名时是 **「保存队伍」**、只改份额时是 **「保存成员单位」**、两样都改了是 **「保存成员单位与队伍」**。

 **要注意的**

@@ -313,6 +314,34 @@
 - ⚠️ **「按队内平均」这类聚合通道的项目，联队不拆份额**：这类通道的名次不对应任何一条报名，分仍记在主单位头上（本轮如此）。要保证联队一起算，请用不聚合的口径（或按 4.9 在主单位上录名次）。
 - 一件事只做一次：**同一个小项同一个组别里，两个单位联合参赛就写一条 `A+B` 的报名**。`A+B` 与 `B+A` 是**两条不同的报名**（主单位不同），不要两种写法都填。

+### 4.12 团体项目多队（同一个单位派两个队）
+
+**羽毛球双打那种：一个单位在同一个组别报了两支队**（例如一队、二队），两队可能各占一个名次。系统支持这么报——**不用新建单位、也不用重复报两次**，两队各算各的成绩、名次与积分，最后都汇到同一个单位的总分上（一个单位两个队都进前三时，这个单位拿 **2 枚牌**）。
+
+**只对团体项目**：个人项目（按人报名的那些）不受影响，也没有「队」这回事。
+
+**怎么录（三条路，任选）**
+
+| 方式 | 怎么做 |
+| --- | --- |
+| **导入报名表** | 用**最后一列「队伍」**写队名：一队那行写 `一队`、二队那行写 `二队`（同一个单位、同一个组别写两行）。**只有一支队的单位这一列留空**；不填这一列、表头里没有它，都合法。列名与报错见[报名名单导入规范 · 第三节的「队伍」](./报名名单导入规范.md)——⚠️ **导入表由 12 列变成 13 列，但老 12 列表照常导入**（新列加在最后，一列都不会错位） |
+| **补报名（勾选）** | 在「成绩录入」页工具栏点 **「补报名」**（或「基础数据 → 报名导入」的**团体报名**页签）：勾上某个单位后，**那一行右侧会出现「队伍（留空＝不区分）」输入框**，填队名即可；**没勾的单位不显示这个框**。已经报过的单位徽标会写成 `已报名（一队、二队）` |
+| **改队名** | 队名填错了**不用删掉重建**：到「成绩录入」页**点那一行的「单位」格**，打开「成员单位与份额」弹窗，里面有 **「队伍」输入框**（**只有纯团体报名才显示**，个人报名连框都不出现）。改完点保存——按钮会按你改了什么都写明（`保存队伍` / `保存成员单位` / `保存成员单位与队伍`），**没改动时按钮是灰的** |
+
+**显示成什么样**
+
+- **`单位名 + 队名`，不加括号、不加分隔符**：`第一分公司一队`、`第一分公司二队`；**队名留空时仍然只写 `第一分公司`**（与以前逐字一样）；
+- 出现的地方：**成绩录入页 / 成绩审核页的「单位」列、批量操作的确认框、报错里的行名、大屏的分项成绩 / 实时赛况 / 底栏「最新完成项目」，以及导出件的「单位」列**（分项成绩表、全部成绩单页、报名名单、单位奖牌明细总表、单位积分总明细总表）；
+- **单位总分榜、单位奖牌榜、个人积分榜上不写队名**（它们的单位名来自单位汇总，分与奖牌本来就归到单位）。
+
+**要注意的**
+
+- **同一个单位、同一个组别、同一个队名只能有一条**：要派两支队就得写**两个不同的队名**。两个队名写一样（或都留空）时，第二行会被**逐行拦下**并说清是哪个单位、哪个队（见导入规范的第六节）；
+- **队伍只对团体行生效**：个人行（有姓名的那几行）**填了队名也不会写进库里**，导入结果里会给一条提示说明这一格被忽略了；
+- ⚠️ **改完队名之后，记得把报名表里的队名也改掉**：导入是按「小项 + 组别 + 单位 + 队名」认人的，以后再导一份**还写着旧队名**的表，会**新增出旧队名那一条报名**（不会静默合并）；
+- **改队名不影响成绩与榜单**：队名只是给现场看的一个标签，不参与名次、积分、奖牌的计算，所以改它**不会重算榜单**，也**不会给别处的大屏 / 录入页推刷新**——别的窗口要等下一次刷新才看到新队名（你自己那一次保存的页面上会立刻变）；
+- 队伍**不参与「团体名次」按单位录入**的那一类项目（篮球那种每个单位只有一支队）：名次仍然是按单位录的，与队名无关。
+
 ---

 ## 5. 成绩审核
@@ -723,12 +752,13 @@
 1. 选择单位，按姓名 / 工号搜索并在运动员列表里勾选：已报名的运动员显示「已报名」且不可重复勾选；证件号与号码布都没有的运动员显示「缺证件号/号码布」、不能勾选，请先到「运动员」分区补齐其中一项；
 2. 点「加入报名」，结果同样显示**新增 / 更新 / 跳过**数量；报名会自动带上该运动员的证件号与号码布。

-**团体报名**（一个单位一条报名）
+**团体报名**（默认一个单位一条报名；同一个单位要派两支队时见 4.12）

 1. 在参赛单位清单里勾选要参加本组别的单位，**默认一个都不勾**——不参加的单位不勾即可；每行显示该单位是否「已报名」、已登记几名队员；
-2. 要登记队员时点该行的「登记队员」展开名单逐个勾选（可按姓名 / 工号搜索）；一个队员都不勾就是**纯单位报名**，队员名单之后还能再补；
-3. 勾选「已报名」的单位会出现「提交将清空原名单」提醒：再次提交是用本次登记的队员覆盖原名单；
-4. 点「加入报名」，一次为所有勾选的单位各建一条报名。
+2. **同一个单位要派两支队时**（羽毛球双打那种）：勾上这个单位后，那一行右侧会出现 **「队伍（留空＝不区分）」** 输入框，填上队名（例如 `一队`）；**没勾的单位不显示这个框**。已经报过的单位徽标会写成 `已报名（一队、二队）`——**要再报第二支队，就再填一个新的队名提交一次**（同一个队名重复提交只是更新队员名单，不会新增）。详见 4.12；
+3. 要登记队员时点该行的「登记队员」展开名单逐个勾选（可按姓名 / 工号搜索）；一个队员都不勾就是**纯单位报名**，队员名单之后还能再补；
+4. 勾选「已报名」的单位会出现「提交将清空原名单」提醒：再次提交是用本次登记的队员覆盖原名单；
+5. 点「加入报名」，一次为所有勾选的单位各建一条报名（**同一个单位 + 同一个队名**只留一条）。
   - 「全选」只勾启用中且还没报名的单位（已停用的单位要单独勾），且不会展开队员面板；「清空」只取消单位勾选，已登记的队员名单留着，重新勾上就回来。

 **表格导入**
@@ -740,8 +770,9 @@
   - 「**分工作表 · 中文表头 / 分工作表 · 英文表头**」＝**分工作表模板**（`.xlsx`）：按当前赛事已配好的**小项 × 组别各建一张工作表**，表名是「**小项名称@组别名称**」（例如 `100 米跑@男子组 30岁以下`），范围由表名承担，数据区只填人和单位。小项组别多时用它更不容易抄串；
   - 两种模板的表头与列顺序完全一样，只有「范围从哪来」不同（详细规范见 [报名名单导入规范 · 第八节](./报名名单导入规范.md)）；
   - **两个单位联合参赛（联队）**：把「单位编码」那一格写成 `F1+F2`（加号左边是主单位，默认均分，见 4.11）。**分工作表模板**里，「单位编码」表头那一格挂了一条**单元格批注**（鼠标停上去就弹出来）、这一列还有**输入提示**（点中该列的格子就弹出来），中英各一份，写的正是这套写法——表头文字、列顺序与工作表名一个字都没动，**老表格照常导入**；
-2. 表头共 12 列：`event_code`、`category`、`team_code`、`athlete_name`、`id_card`、`gender`、`age`、`bib`、`seed`、`heat`、`status`、`member_names`（大小写不敏感）。其中 `id_card`（证件号）、`gender`（性别）、`age`（年龄）、`heat`（批次）为可选列，缺失不影响导入，其余列必须包含；
+2. 表头共 13 列：`event_code`、`category`、`team_code`、`athlete_name`、`id_card`、`gender`、`age`、`bib`、`seed`、`heat`、`status`、`member_names`、`squad`（大小写不敏感）。其中 `id_card`（证件号）、`gender`（性别）、`age`（年龄）、`heat`（批次）、`squad`（队伍）为可选列，缺失不影响导入，其余列必须包含；
   - `team_code`（单位编码）有两种填法：**一个单位**填它的编码（`F1`）；**两个单位联合参赛**填 `F1+F2`（加号左边是主单位，默认均分；非均分要到录入页改，见 4.11）；
+   - `squad`（队伍）是**最后一列**、**新加的（2026 年 9 月）**：同一个单位在同一个组别派两支队时（羽毛球双打的一队 / 二队）用它区分，写队名即可（中文表头里叫「队伍」，也认「队名」「队伍名」）；**只有一支队的单位整列留空**、整列不写、表头里没有它，三种都合法。**老 12 列表照常导入**（新列加在最后，一列都不会错位），详见 4.12 与[报名名单导入规范 · 第三节「队伍」](./报名名单导入规范.md)；
   - 用**分工作表模板**时，`event_code`、`category` 两列也可以整列不要或整列留空（范围由工作表名决定）；一旦填了就必须与工作表名一致，不一致的那一行会报错并跳过；
   - 工作表名必须是「小项名称@组别名称」；工作簿里只要有**一张**表名带 `@`，整份文件就按分工作表模板处理，别的表名不合规会**整份拒绝并点名是哪张表**（不让数据无声消失）；
   - 小项名与组别名里**不允许出现 `@`**（它是表名里的分隔符）：新建 / 编辑小项与组别时界面会当场拦下并说明原因；**已经带 `@` 的历史名字不影响报名与成绩**，但下载分工作表模板时会被点名要求先改名；
@@ -811,6 +842,7 @@
 | 个人积分总明细 | **在「积分榜 → 个人积分榜」页操作**：逐条列出单位 / 运动员 / 大项 / 小项 / 组别 / 名次 / 成绩 / 得分 / 来源，每个有得分的单位一张分表 | `个人积分总明细.xlsx` |

 - 「分项成绩表」需先选择小项，「单位积分明细」需先选择单位；「报名名单」的四个筛选（小项 / 组别 / 单位 / 批次）**都可以留空**，留空就是不筛这一维度（全导）；
+- **队名（同一个单位派两个队时写的那个，见 4.12）写进「单位」列**：分项成绩表 / 全部 / 全部（单页）/ 报名名单 / 单位奖牌明细总表 / 单位积分总明细总表里，写的是 **`第一分公司二队`** 这种「单位名 + 队名」（队名留空时仍然只写 `第一分公司`）。⚠️ **导出件里没有单独的「队名」列**——所以**不要拿导出的报名名单直接改完再导回去**（那会撞「同一个单位同一个队」的重复报名、报错拦下）；要改队名或改名单，用**导入模板**那条路，或到录入页点「单位」格改队名；
 - **联队（一条报名挂多个单位）在这几份导出件里的写法**（见 4.11）：
  - **「分项成绩表」「全部」「全部（单页）」的「单位」列**：写成联队全名 `第一分公司+第二分公司联队`（成员单位名写全，与导入表的 `F1+F2` 同构）；**「备注」列**写清这条分给了谁、各多少，例如 `联队分拆：第一分公司 5 分（50%）、第二分公司 5 分（50%）`——「积分」列写的是**联队拿到的总分**（上例 10 分），每家的那一份看备注；
  - **「报名名单」**：「单位编码」列回写成 `F1+F2`（**导出的名单可以直接拿去重导**，不用手工改回单个单位）、「单位名」列写联队全名、「备注」列写 `联队分拆：第一分公司 50%、第二分公司 50%`（这张表没有积分列，所以只写份额比例）；
@@ -1053,6 +1085,8 @@

 > **联队（两个单位合并参赛）在大屏上怎么写**（见 4.11）：「分项成绩」与「实时赛况」的**单位列写联队全名**——`第一分公司+第二分公司联队`，并且**把两个单位的 logo 都放上**（单位列宽会为该行实际要画的 logo 数留位置，第二个 logo 不会把名字挤成省略号）；底栏「最新完成项目」那一行同样写联队全名。**单位奖牌榜、总积分榜本来就是逐单位一行，服务端已按份额拆好**（例：A、B 各 1 枚金、各 7.5 分），屏上不需要另做处理。**没有联队的赛事，大屏画面与升级前逐像素一致**。

+> **队名（同一个单位派两个队时写的那个，见 4.12）同样写在大屏的单位名后面**：`第一分公司二队`——分项成绩、实时赛况、底栏「最新完成项目」三处都一样（同一个单位的两个队都进了名次时，两行只差队名，不写就分不出哪一行是谁）；**单位奖牌榜、总积分榜上不写队名**。队名留空时画面与以前逐像素一致。
+
 > 大屏的标题字体与正文字体取自「系统设置 → 赛事信息 → 字体」（见 14.3）：可选四款内置字体，也可以上传自己的字体；上传字体加载失败时自动回落到默认字体，画面不会出现方块或空白。

 > 除了 Console 开出来的本机大屏窗口，**局域网设备（另一台电脑、电视浏览器）打开 `http://<主机IP>:19540/display` 也能当大屏用**。这个地址不用手敲：管理端「大屏控制 → 局域网大屏」卡片里有**可复制的完整链接与二维码**（见第 9 节）。这类设备会出现在管理端「大屏控制 → 在线大屏」列表里（标记为「局域网浏览器」），也能被单独切页，用法见第 9 节；它们不受 Console 的 kiosk、防熄屏控制（另见常见问题 Q29）。
@@ -6,7 +6,74 @@

 ---

-## dev_0.5.4（当前版本）
+## dev_0.5.5（当前版本）
+
+### 一句话
+
+**有一条数据迁移（`0025`），老数据一个字节都不变**：团体项目现在支持**一个单位在一个组别派多支队**（羽毛球双打那种「一队 / 二队」）——以前数据库的唯一索引只允许一个单位一条团体报名，第二支队录不进去。升级后：**现有的报名、成绩、名次、积分、奖牌、导出件与升级前完全一样**（老数据的队名都是空的，在新索引下仍然「一个单位一条」），**多队能力只有在真的给某个单位报了第二支队之后才会体现**；**报名表由 12 列变成 13 列**（最后一列新增「队伍」），**老 12 列表照常导入**。
+
+### ① 数据迁移：一条（`0025`）
+
+- **它做什么**：给报名表加一列 `squad`（队伍，自由文本，**默认空串**），并把「同一个单位在同一个组别只能有一条团体报名」的那个唯一索引换成**带上队伍的版本**（`组别 + 单位 + 队伍`）。**带的运动员的报名不受影响**：它们仍然按「组别 + 单位 + 运动员」唯一，同一个运动员不会因为这次改动而在同一组别报两次。
+- **老数据零变化**：升级后所有旧报名的队伍都是**空串**，在新索引下等价于「一个单位一条」——**原来能跑的名单、成绩、榜单、导出件一个字节都不变**（对拍证据见下）。
+- **怎么看它跑过**：启动一次 Console，在运行日志或 `logs\operations\` 当天文件里能看到 `已应用迁移 … name=0025_entry_squad.sql`。
+- **对拍证据**：接口层把老数据 `GET /entries` 的 JSON 里新字段剥掉后**逐字节相同**；导出层把 9 份导出件的**全部单元格（共 750 行）dump 出来比对**，**md5 相同**（另带敏感度自检，确认这份对拍真的能发现差异）。
+
+### ② 新能力：团体项目多队（只给团体项目）
+
+**怎么做**：一个单位在同一个组别报两支队时——两队**各写一行**，靠队伍列 / 队名区分：
+
+| 场景 | 怎么做 |
+| --- | --- |
+| **导入报名表** | 用**最后一列「队伍」**写队名（`一队` / `二队` / `青年队`，随便写）；**只有一支队的单位这一列留空**。中文表头叫「队伍」，也认「队名」「队伍名」 |
+| **补报名（勾选）** | 「成绩录入」页的「补报名」或「基础数据 → 报名导入」的**团体报名**页签：勾上单位后**那一行右侧出现「队伍（留空＝不区分）」输入框**，填队名提交即可；**没勾的单位不显示这个框**；已报过的单位徽标写成 `已报名（一队、二队）` |
+| **改队名** | 填错不用删掉重建：「成绩录入」页**点那一行的「单位」格** → 弹窗里的 **「队伍」输入框**（**只有纯团体报名才显示**）→ 保存（按钮会按改了啥写成 `保存队伍` / `保存成员单位` / `保存成员单位与队伍`，**没改动时是灰的**） |
+
+**口径**：
+
+- **队伍只对团体项目**：个人项目（按人报名的那些）**不受影响**，也没有「队」这回事；个人行即使填了队名也**不会写进库里**，导入结果里会给一条提示；
+- **留空 = 不区分队伍**：绝大多数单位只有一支队，**这一列留空 / 整列不写 / 表头里没有它**都是一样的（= 升级前的行为）；
+- **同一个单位 + 同一个组别 + 同一个队名只能有一条**：要派两支队就写**两个不同的队名**；写重了会被**逐行拦下**并说清是哪个单位、哪个队，**其余行照常导入**；
+- **一个单位两个队都进前三 → 这个单位拿 2 枚牌**（两支队各算各的名次，分与牌都记到同一个单位头上）；
+- **队伍不影响算分**：两队的成绩、名次、积分各算各的，最后都汇到同一个单位的总分里；
+- **不涉及「按单位手工录名次」的项目**（篮球那种每个单位只有一支队）：名次仍然按单位录，与队名无关。
+
+### ③ 显示口径：`单位名 + 队名`
+
+- 写出来**不加括号、不加分隔符**：`第一分公司二队`；**队名留空时逐字保持原样**（`第一分公司`）；
+- **写队名的地方**：成绩录入页 / 成绩审核页的「单位」列、批量操作的确认框、报错里的行名、大屏的分项成绩 / 实时赛况 / 底栏「最新完成项目」，以及**导出件的「单位」列**（分项成绩表、全部成绩单页、报名名单、单位奖牌明细总表、单位积分总明细总表）；
+- **不写队名的地方**：**单位总分榜、单位奖牌榜、个人积分榜**——这三处是单位级汇总，分与奖牌本来就归到单位。
+
+### ④ 报名表 12 列 → 13 列（老表照常导入）
+
+- 新增的是**最后一列「队伍」**（英文规范名 `squad`，中文别名「队伍」/「队名」/「队伍名」），**可选**：整列不写、格子留空、表头里没有它，三种都合法；
+- 新列加在**表尾**，所以**手里原来的 12 列表一列都不会错位、照常导入**；下载的新模板是 13 列（分工作表模板也一样）；
+- 填法、报错文案与例子见《报名名单导入规范》第二节 / 第三节「队伍」/ 第五节的例 5。
+
+### ⑤ 改完队名，记得顺手改报名表
+
+⚠️ 导入是**按「小项 + 组别 + 单位 + 队名」认人**的：在界面上把「二队」改成「青年队」之后，如果以后再导一份**还写着「二队」**的报名表，系统会**新增出「二队」那一条报名**（不会静默合并，也不会报错）。所以**改队名时把报名表里的队名也改成一样**。
+
+### ⑥ 升级后 5 分钟核对
+
+1. 启动一次 Console，看运行日志 / `logs\operations\` 当天文件：应能看到 `0025` 这条迁移记录，没有别的报错；
+2. 刷新管理端「积分榜」与大屏：**单位总分榜、单位奖牌榜、个人积分榜的每一个数字与升级前一致**（本版不改任何算分口径）；
+3. 打开「成绩录入」页：**「单位」那一列与升级前长得一样**（老报名的队名是空的，不会多出任何字）；点某一行的「单位」格，**纯团体报名**的弹窗里应多出一个「队伍」输入框（**个人报名看不到这个框**，这是对的）；
+4. 打开「基础数据 → 报名导入」，下载一份模板：**表头最后一列应是「队伍」**（共 13 列）；拿一份升级前的老 12 列表导一次，应与升级前一样正常导入；
+5. 拿一个真要多队的项目试一次：同一个单位、同一个组别报两行、队伍列分别写 `一队` / `二队`，导入后到录入页确认**两支队各占一行、单位列写成 `第一分公司一队` / `第一分公司二队`**，录成绩发布后**两队各拿各的名次、单位的分数是两队之和**；
+6. 用《上线检查清单》过一遍。
+
+### ⑦ 详细说明在哪
+
+| 想了解 | 看 |
+| --- | --- |
+| 多队怎么录、显示成什么样、改队名在哪 | 《使用手册》4.12（以及 4.2、4.11、10.7、11.1、17.1 各处的衔接说明） |
+| 导入表「队伍」列怎么写、报什么错 | 《报名名单导入规范》第二节、第三节「队伍」、第五节的例 5、第六节 |
+| 迁移与唯一索引 | `server/migrations/event/0025_entry_squad.sql` |
+
+---
+
+## dev_0.5.4

 ### 一句话

@@ -67,7 +134,7 @@
 怎么用：

 - **配联队的两个入口**：
-  1. **导入报名表**时把单位编码写成 `A+B`（默认均分；最多 5 个单位；`A+`、`+B`、`A++B`、`A+A` 这些写法会被**逐行拦下**并说清是第几行、错在哪，**其余行照常导入**）；报名模板（分工作表 xlsx）的「单位编码」表头挂了一条**单元格批注**、该列还有**输入提示**，中英各一份，内容就是这套写法——**表头文字、列序、12 列、工作表命名一个字都没动**，老表格照常导入；
+  1. **导入报名表**时把单位编码写成 `A+B`（默认均分；最多 5 个单位；`A+`、`+B`、`A++B`、`A+A` 这些写法会被**逐行拦下**并说清是第几行、错在哪，**其余行照常导入**）；报名模板（分工作表 xlsx）的「单位编码」表头挂了一条**单元格批注**、该列还有**输入提示**，中英各一份，内容就是这套写法——**表头文字、列序、12 列、工作表命名一个字都没动**，老表格照常导入（**这一版是 12 列；`dev_0.5.5` 起表尾新增了第 13 列「队伍」，见那一节**）；
  2. 导入后到**「成绩录入」页点那一行的「单位」格**，打开「**成员单位与份额**」弹窗改（加成员单位、填权重、去掉成员）。⚠️ **非均分（例如 2:1）不能在导入表里写**，只能在弹窗里改。
 - **谁能改**：份额编辑与录成绩同档，**录入员及以上**；访客只读时输入框置灰并写明原因。
 - **改完当场生效**：保存立即重算该小项该组别并推送大屏。
@@ -11,14 +11,17 @@
 ## 一、先看懂三件事

 1. **用什么软件做表**：Excel 或 WPS 都行，做完存成 `.xlsx` 或 `.csv` 都可以（推荐 `.csv`，系统兼容性最好，不用管编码）。
-2. **表格长什么样**：**第一行是表头**（固定的 12 个列名，**中文、英文两套任选其一**，见第二节），**从第二行开始每人一行**。不要合并单元格，不要在表头上方再加标题行、说明行。
+2. **表格长什么样**：**第一行是表头**（固定的 13 个列名，**中文、英文两套任选其一**，见第二节），**从第二行开始每人一行**。不要合并单元格，不要在表头上方再加标题行、说明行。
 3. **编码不能自己编**：表里的「小项编码」「单位编码」「组别名称」必须是系统里已经配好的，**照抄系统里的写法**。系统里没有的编码，这一行会被跳过并报错。

 ---

 ## 二、表头（第一行的列名）

-一共 12 列。系统**同时认两套表头**——英文一套、中文一套，**两套都能导入**，也可以**中英混着写**（每一列各自认名字，例如英文 `event_code` 配中文「姓名」）。**英文是规范列名**：老的英文模板一个字都不用改，照常导入；中文只是给习惯看中文的人用的同义写法。
+一共 13 列。系统**同时认两套表头**——英文一套、中文一套，**两套都能导入**，也可以**中英混着写**（每一列各自认名字，例如英文 `event_code` 配中文「姓名」）。**英文是规范列名**：老的英文模板一个字都不用改，照常导入；中文只是给习惯看中文的人用的同义写法。
+
+> **第 13 列「队伍」是新加的（2026 年 9 月）**：**同一个单位在同一个组别派两支队**（羽毛球双打的一队 / 二队那种）时才需要填它；**绝大多数表格整列留空就行**，填法见第三节的「队伍」。
+> **老表格不用改**：表头里没有这一列、整列不写、格子留空，三种情况都合法，系统按「不区分队伍」处理——**原来的 12 列一列都不会错位**（新的一列加在**最后**）。

 下载模板时按手上表格的样子选：

@@ -43,6 +46,9 @@
 | `heat` | 批次（也认「批次号」） | 批次，可缺省 |
 | `status` | 状态（也认「报名状态」） | 报名状态 |
 | `member_names` | 队员名单 | 团体项目的队员名单 |
+| `squad` | 队伍（也认「队名」「队伍名」） | **队名，可缺省**；同一个单位在同一组别派两支队时用它区分（留空 = 不区分队伍） |
+
+> **第 13 列 `squad`（队伍）永远排在最后**：它是 2026 年 9 月新增的，加在表尾是为了让**手里那些原来 12 列的老表格一列都不会错位**（表格少的正是最后这一列）。整列不写、整列留空、表头没有它，三种情况都合法。

 > **同一列只能写一次**：一份表里同时出现 `event_code` 和「项目编码」（或者干脆把同一列写了两遍），会被整份拦下并提示「报名表表头重复」，删掉多余的那一列再导入即可——系统不会替你猜该信哪一列，免得静默丢掉另一列的数据。
 >
@@ -64,6 +70,7 @@
 | `heat`（批次） | 可选 | 批次号：1–999 的整数；**留空 = 未分批**（不参与算分，见下） | `1` |
 | `status`（状态） | 可选 | 报名状态：4 个英文词（大小写都行）或等价的中文别名（见下） | `registered` |
 | `member_names`（队员名单） | 可选 | 团体项目的队员名单，多人用 `/` 隔开 | `张三/李四/王五` |
+| `squad`（队伍） | 可选 | **队名**（自由写，例如 `一队`）；**留空 = 不区分队伍**。**同一个单位在同一个组别派两支队就靠它区分**，见第三节 | `一队` |

 > 「必须」指的是**这一列的表头要有**。至于每格里能不能留空，看下面第三节逐列的说明。

@@ -183,6 +190,23 @@ F1+F2
 - 团体项目**可以只报单位、不写队员**（这一列留空即可），队员名单以后还能补。
 - 系统界面里会把这条名单显示成「张三、李四、王五」。

+### `squad` 队伍 —— 可选（表的最后一列）
+
+**这一列只在「同一个单位在同一个组别派了不止一支队」时才需要填**，比如羽毛球双打：一个单位报了一队、二队，两队可能各占一个名次。
+
+```
+一队
+二队
+青年队
+```
+
+- **队名随便写**（`一队` / `二队` / `青年队` / `A 组` 都行），就是给现场看的一个标签；
+- **留空 = 不区分队伍**：一个单位在这个组别只有一支队（绝大多数情况）时，**整列留空、整列不写、表头里没有这一列**，三种都合法，与升级前的行为完全一样；
+- **只对团体项目有效**：这一列只认「姓名那一格留空」的团体行。**个人行（填了姓名的行）如果也填了队名，这一格不会写进库里**，导入结果里会给你一条提示：`第 N 行填了队伍「一队」，但这一行有运动员姓名、按个人报名处理：队伍只对团体报名（不填姓名那几行）生效，这一格没有写进库里`；
+- **同一个单位、同一个组别、同一个队名只能有一条**（要派两支队就写两个不同的队名）。撞上了会逐行拦下并说清是哪个单位、哪个队（见第六节）；
+- **队名只影响显示与查重，不影响成绩与算分**：两个队的成绩、名次、积分各算各的，最后都汇总到同一个单位的总分上；显示上写成「单位名 + 队名」，例如 `第一分公司二队`（队名留空时仍然只写 `第一分公司`）。**单位总分榜 / 单位奖牌榜 / 个人积分榜上不写队名**（分与牌本来就归到单位）；
+- 队名**改起来不用删掉重建**：到「成绩录入」页点那一行的「单位」格，在弹窗里改（见[使用手册 · 4.12](./使用手册.md)）。⚠️ 改完记得**把报名表里的队名也改成一样**——以后再导一份还写着旧队名的表，会因为认不出来而**新增出旧队名那一条**。
+
 ### 系统怎么认人（证件号 → 号码布 → 姓名 + 单位）
 有姓名的行，系统按下面的顺序认人。**证件号是唯一标识，号码布是它的替补，最后才靠「姓名 + 单位」兜底回填**：

@@ -196,7 +220,7 @@ F1+F2

 ---

-## 四、四个完整例子
+## 四、五个完整例子

 ### 例 1：个人项目（七单位 × 若干人）

@@ -246,11 +270,30 @@ F1+F2
 - 要改成 **2:1** 这类非均分：**不能在这张表里写**，导入后到「成绩录入」页点那一行的「单位」格改（见[使用手册 · 4.11](./使用手册.md#411-联队两个单位合并参赛)）；
 - 大屏与导出件里写的是 `第二分公司+第五分公司联队`，报名名单导出的「单位编码」列回写成 `F2+F5`（可以直接拿去重导）。

+### 例 5：同一个单位派两个队（团体项目多队）
+
+羽毛球双打，**F1 派出「一队」和「二队」两支队伍**，两队都可能拿名次。`BD` 是羽毛球双打、`男子组`：
+
+| event_code | category | team_code | athlete_name | id_card | gender | age | bib | seed | heat | status | member_names | squad |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| BD | 男子组 | F1 |  |  |  |  |  |  |  | registered | 张三/李四 | 一队 |
+| BD | 男子组 | F1 |  |  |  |  |  |  |  | registered | 王五/赵六 | 二队 |
+| BD | 男子组 | F2 |  |  |  |  |  |  |  | registered | 孙八/周九 |  |
+| BD | 男子组 | F3 |  |  |  |  |  |  |  | registered | 吴十/郑十一 |  |
+
+要点：
+
+- **同一个单位、同一个组别写两行**，靠**最后一列「队伍」**区分开：`一队`、`二队`。**一个单位两个队都进前三时，这个单位会拿 2 枚牌**（两支队各算各的名次）；
+- F2、F3 只有一支队，队伍列**留空**即可（也可以整列不填、或表头里干脆没有这一列）；
+- **列都写对了才有多队的效果**：两行的 `event_code` / `category` / `team_code` / `squad` 必须**都不一样的那一格正好是 squad**——如果两行队名也写成一样的（都写 `一队`），第二行会被拦下（「同一个单位同一个组别的同一个队只能报一条」）；如果两行队名都留空，第二行也会被拦下（「一个单位在一个组别只能有一条不分队的报名」）；
+- 显示上写成 **`第一分公司一队` / `第一分公司二队`**（单位名后面直接跟队名，不加括号不加分隔符）；**单位总分榜、单位奖牌榜、个人积分榜上只写 `第一分公司`**（两队的分数都已经算进这个单位的总分）；
+- 报了之后想改队名**不用删掉重建**：到「成绩录入」页点那一行的「单位」格，在弹窗里改（见[使用手册 · 4.12](./使用手册.md)）。⚠️ **改完记得把这张表里的队名也改成一样**——以后再导一份还写着旧队名的表，会**新增出旧队名那一条报名**（导入是按「小项 + 组别 + 单位 + 队名」认人的）。
+
 ---

 ## 五、导入前请先检查（自检清单）

- [ ] 第一行是那 12 个列名（**英文一套、中文一套都行**，也可以中英混着写，见第二节），没有被合并单元格、**同一列没有写两遍**
+- [ ] 第一行是那 13 个列名（**英文一套、中文一套都行**，也可以中英混着写，见第二节），没有被合并单元格、**同一列没有写两遍**
 - [ ] 表头上方没有多余的标题行或空行
 - [ ] `event_code`、`team_code` 都是从系统里抄的编码，没有空格
 - [ ] `category` 与系统里的组别名一字不差
@@ -262,6 +305,7 @@ F1+F2
 - [ ] `status` 只用那 4 个英文词（大小写都行）或第三节列的中文别名，不写别的词；拿不准就留空
 - [ ] `heat` 要么留空，要么是 1–999 的整数（不参与算分，只是录入分组）
 - [ ] **联队**（两个单位联合参赛）写的是 `F1+F2` 这种形状：加号两边都有编码、**同一个单位没写两遍**、成员不超过 5 个；**加号左边那个是主单位**（见第三节）
+- [ ] **「队伍」列**（最后一列）只在**同一个单位派了不止一支队**时才填：两队写了**两个不一样的队名**（都写一样或都留空会被拦下）；只有一支队的单位留空即可；**个人行（有姓名的行）没有填队名**（填了也不会写进库里，只给一条提示）
 - [ ] 全表没有因为"怕麻烦"把某些列删掉——**表头 8 个必须列一个都不能少**（哪怕整列是空的）
 - [ ] 用的是**分工作表模板**时：每张工作表的名字都是「小项名称@组别名称」、没有多余的工作表；「项目编码 / 组别」两列要么整列留空、要么与表名一字不差（见第八节）

@@ -284,6 +328,9 @@ F1+F2
 | 第 N 行：单位编码 F1+ 里有一段是空的：联队要写成两个单位编码用 + 连起来（例如 A+B） | **加号有一边是空的**（`F1+`、`+F2`、`F1++F2` 都是这一条）。多半是填一半或多了个加号 | 补上缺的那个编码，或删掉多余的加号；联队至少两个单位 |
 | 第 N 行：单位编码 F1+F1 里同一个单位出现了两次：联队的每个单位只能写一次 | 同一个单位在联队里写了两遍（`F1+F1`） | 一个单位只写一次；两个单位联合参赛就是 `F1+F2` |
 | 第 N 行：单位编码 … 里写了 6 个单位：一个联队最多 5 个单位 | 加号太多、成员超过 5 个 | **一个联队最多 5 个单位**；现场最多见过三个单位合并，超过 5 个多半是这一格填错了东西（例如整格都是加号） |
+| 第 N 行：单位 A 在本组别已经有一条队伍「一队」的报名：「同一个单位同一个组别的同一个队」只能报一条；要派两个队请换一个队伍名（例如 二队） | 同一个单位、同一个组别、**同一个队名**写了两遍（两支队要写两个不同的队名） | 把其中一行的「队伍」列改成另一个队名（`一队` / `二队`）；如果本来就是同一支队、只是想把队员名单补全，改完重导**不会新增**（同一单位同一队名是更新） |
+| 第 N 行：单位 A 在本组别已经有一条不分队的团体报名：队伍列留空就是不区分队伍，一个单位在一个组别只能有一条；要派两个队请在队伍列分别写清（例如 一队 / 二队） | **两行的队伍列都留空**（等于都说「这个单位在这个组别只有一支队」），或者库里以前报过一条不分队的、这行又留空 | 要派两支队就在两行的「队伍」列分别写 `一队` / `二队`；确实只有一支队，就把多余的那一行删掉 |
+| 第 N 行：单位 A 在本组别已经有这个人的报名：同一个人在同一组别只能报一条，请把重复行合并后再导入 | **个人行**（填了姓名的行）在同一个小项同一个组别里写了两次。个人报名按「人」唯一，队伍列不参与（也不影响）这件事 | 把两行合并成一行；同一个人要参加两个项目就写在**不同小项**里，不能靠队名分成两条 |
 | 第 N 行：组别 XXX 不存在 | 组别名和系统里不一致，或该小项还没有这个组别 | 到「基础数据 → 组别」核对名称（注意别多字少字） |
 | 第 N 行：小项 XXX 没有组别 | 该小项一个组别都没配 | 先在「组别」里配好，再导入 |
 | 第 N 行：填写了 athlete_name 就必须填 id_card 或 bib | 个人行缺两项标识 | 补证件号或号码布；确实都没有的，请先在「运动员」里登记 |
@@ -344,7 +391,7 @@ F1+F2

 ### 8.2 数据怎么填

- 每张工作表**第 1 行就是表头**（与单表模板同样的 12 列、中英两套都认），**从第 2 行开始填人**；
+- 每张工作表**第 1 行就是表头**（与单表模板同样的 13 列、中英两套都认），**从第 2 行开始填人**；
 - **「项目编码」「组别」两列可以整列留空**——表名已经说明了是哪个小项、哪个组别；
  一旦填了，就**必须与表名一致**，不一致的那一行会报错并跳过（系统不猜、也不会挑一个用）；
 - 其余列与单表模板完全一样（第三节逐列说明照样适用）；
@@ -395,6 +442,7 @@ Excel 对工作表名有硬限制：**最长 31 个字符**，同一份工作簿
 > 8. 填完先对着第五节的清单自查一遍，再发给收表人；
 > 9. **批次（`heat`）**可以不填；要分批比赛就填 1–999 的整数，它只影响录入时怎么分组找人，**不影响成绩与名次**；
 > 10. **两个单位联合参赛（联队）**：`team_code` 那一格写 `F1+F2`（加号左边是主单位，默认均分，最多 5 个单位），**不要**新建一个「联队单位」、也不要两个单位各写一行；非均分（例如 2:1）要在导入后到「成绩录入」页点那一行的「单位」格改；
-> 11. **存成什么格式**：Excel →「另存为」→「**CSV UTF-8 (逗号分隔) (*.csv)**」最稳；中文 Excel 默认的「CSV (逗号分隔)」也能用。**别用「Unicode 文本」（UTF-16）**，**别手工改名或把两个文件拼起来**，也别在格子里手写双引号（让 Excel 自己加）。
+> 11. **同一个单位派两支队**（羽毛球双打的一队 / 二队那种）：在**最后一列「队伍」**里分别写队名（`一队` / `二队`）；**只有一支队的单位这一列留空**，整列不写也行。**个人项目不用管这一列**；
+> 12. **存成什么格式**：Excel →「另存为」→「**CSV UTF-8 (逗号分隔) (*.csv)**」最稳；中文 Excel 默认的「CSV (逗号分隔)」也能用。**别用「Unicode 文本」（UTF-16）**，**别手工改名或把两个文件拼起来**，也别在格子里手写双引号（让 Excel 自己加）。
 >
 > 一句话：**下载模板 → 只往下面粘数据 → 另存为 CSV UTF-8 → 上传**。中间任何一个"顺手改一下"都可能让整份表被拦下。