PENTAGONAL STAR — Operation Manual操作手册

1. System Overview1. 系统概述

Pentagonal Star Logistics is a cross-border express management system covering the full chain: inbound → outbound → loading → unloading → pickup / confirm → fee settlement. It has two front-ends: the PC admin console at http://localhost:3000 and the mobile site at http://localhost:3000/mobile.

五角星物流是覆盖 入库 → 出库 → 装机 → 卸机 → 取件 / 确认 → 费用结算 全链路的跨境快递管理系统。双端使用：PC 管理端 http://localhost:3000，移动端 http://localhost:3000/mobile。

Part 1 — Logistics process一、物流过程

1.1 Full-chain flow at a glance1.1 全流程一览

One consignment passes three roles and six steps. Any role can report an exception at any step; after it is handled, the parcel goes back to the step it was on.

一票货经过三个岗位、六个步骤。任何一步都能上报异常，处理完之后回到原来那一步继续走。

1.2 Step details1.2 步骤明细

1.3 What every step must pass1.3 每一步必须通过的检查

Part 2 — Finance process二、财务过程

A waybill's fee moves through four payment states, from "not priced yet" to "cash received". The finance funnel groups all parcels into four layers by payment state, so anyone can see at a glance where the money is stuck and who should follow up.

一票快递的费用，从「还没定价」到「钱已到账」要经过四个支付状态。财务漏斗把全站包裹按支付状态分成四层，一眼就能看出钱卡在哪一层、该找谁跟进。

2.1 The four payment states2.1 支付状态四态流转

2.2 The four funnel layers2.2 财务漏斗四层

2.3 How a period is assigned2.3 账期归属规则

2.4 When a period is settled (any one)2.4 结清口径（满足任一即结清）

• Payable total ≤ 0.
• Every parcel in the period is Paid.
• Confirmed received amount accumulated ≥ payable total.

• 应付总额 ≤ 0。
• 该账期全部包裹已支付完成。
• 已确认收款金额累计 ≥ 应付总额。

Part 3 — Fixed business constants三、固定业务常量

2. Login & Language2. 登录与语言切换

1. Open the PC console, enter username and password, then click Login.
2. The language selector in the top-right switches the whole interface between EN / 中文 / AF / AR instantly — no page reload, and the current page keeps its pagination and filters.
3. Default language is English on first visit. The choice is remembered in the browser.
4. If login fails, the message distinguishes a network error (server unreachable) from invalid credentials.

1. 打开 PC 端，输入用户名与密码，点击 登录。
2. 右上角语言下拉框可在 EN / 中文 / AF / AR 之间即时切换，无需刷新页面，当前页面的分页与筛选条件不丢失。
3. 首次进入默认英文，选择结果会记在浏览器本地。
4. 登录失败时，提示会区分「网络错误（服务器无响应）」与「用户名或密码错误」。

3. Roles & Permissions3. 角色与权限

• Permissions are granted at the second-level menu granularity, one checkbox per item — there is no batch grant/revoke.
• The permission list is derived automatically by scanning the sidebar, so it always matches the menu count.
• If a menu is unchecked, it disappears from the sidebar and the page cannot be opened.

• 权限按 二级菜单 粒度逐项勾选开通，没有批量开通/关闭。
• 权限列表由侧边栏自动派生，菜单增删后项数自动对齐。
• 菜单未勾选时，侧边栏隐藏该项，对应页面也无法打开。

Organization scope (station isolation)所属机构与站点隔离

• Every employee is bound to an organization: Headquarters (0) or a pickup station (the station's ID).
• A pickup-station employee only sees and operates packages whose pickup station is their own; Headquarters staff and administrators see all packages.
• If an account has no organization yet, a non-dismissable dialog appears right after login asking the user to pick Headquarters or their station — the only choices are confirm or log out.
• The organization is set when the user is created and can be changed later in Users. It is independent of the "operating site" recorded on traces and flights.

• 每位员工绑定一个 所属机构：总公司（0）或某个取货站点（站点 ID）。
• 取货站点员工只能看到并操作「取货站点是自己站点」的包裹；总公司员工与管理员可查看全部包裹。
• 账号未设置所属机构时，登录后会弹出不可关闭的绑定对话框，只能选择「总公司 / 所属站点」或退出登录。
• 所属机构在新增用户时指定，也可在 用户管理 中修改；它与轨迹 / 航班上记录的「操作站点」是两回事。

4. New Inbound4. 新货入库

1. Enter the sender company (code auto-fills), pickup station, transport type, weight, quantity and goods category.
2. Fill in the real receiver name and phone. If left blank the system falls back to the station name / station phone.
3. Paste from the clipboard to auto-fill receiver details — single line, multi-line, phone: prefixed and bracketed remarks are all supported.
4. Save; a tracking number is generated as 3-letter destination-3-letter sender-MMDD-3-digit serial, e.g. JUB-PEN-0919-001. The serial resets daily.

1. 填写寄件单位（自动带出缩写）、取货站点、运输类型、重量、件数与货品种类。
2. 填写真实收件人姓名与电话；不填时回退使用站点名 / 站点电话。
3. 支持从剪贴板粘贴自动识别收件信息：单行逗号分隔、多行、phone: 前缀、括号备注均可识别，识别成功会有提示。
4. 保存后自动生成运单号，规则为 3字母目的地-3字母客户缩写-4位月日-3位序列号，如 JUB-PEN-0919-001，序列号每日重置。

5. Overweight Re-inbound5. 超重待退库重新入库

Packages returned from the airport because of overweight are listed here. The table shows checkbox, tracking no., sender company, pickup address, status, re-inbound count, weight, goods category and the Re-inbound action. Use it to put a returned package back into the outbound flow.

因超重被机场退回的包裹在此列表展示，表格包含勾选框、快递单号、寄件单位、取货地址、状态、退库次数、重量、商品类型与「重新入库」操作按钮，用于把退回包裹重新放入出库流程。

6. Pending Outbound6. 待出库

1. Only packages in PENDING_LOAD status can be pushed outbound.
2. Select packages and click Outbound. When air transport is chosen, a prohibited-goods check is mandatory.
3. Each row also has a 🖨️ button to print the waybill directly.
4. Cancelling an outbound selection is only allowed while the package is still PENDING_LOAD.

1. 仅 PENDING_LOAD（待装机）状态的包裹可以出库。
2. 勾选包裹后点击 出库；选择航空运输时必须完成违禁物品检查。
3. 每行提供 🖨️ 按钮，可直接打印面单。
4. 只有在 PENDING_LOAD 状态下才允许取消出库。

7. Flight Management7. 航班管理

Two tabs: New Flight and Flight List. The former "Planned Flights" and "Voyage List" tabs have been merged into one Flight List.

两个标签页：新增航班 与 航班列表（原「计划航班」与「航次列表」已合并为同一个列表）。

• Flight no. is a fixed dropdown of NO401 / NO402 / NO403, defaulting to NO401; origin is fixed to JUBA AIRPORT.
• New Flight also captures departure date and time, planned arrival time, pickup station (searchable) and loading method — Mixed (default) or Charter.
• Voyage no. is YYYYMMDD-2-digit serial-flight no.; the serial restarts from 01 each day.
• The Flight List covers every flight and can be filtered by status (Planned / Departed / Arrived / Cancelled, multi-select, all ticked by default).
• Actions in the Flight List: a Planned flight offers Depart and Cancel — Depart is blocked while no cargo is loaded, and Cancel is blocked once cargo is loaded. A Departed flight offers Land.
• Columns: flight code, flight no., origin, pickup station, loading method, flight status, scheduled departure, actual departure, actual arrival, take-off operator, landing operator. Columns are resizable and the page size is 20 / 40 / 60.

• 航班号为固定下拉 NO401 / NO402 / NO403，默认选中 NO401；始发站固定 JUBA AIRPORT。
• 新增航班还需填写起飞日期与时间、预计到达时间、取货站点（可搜索选择）与装载方式——混装（默认）或 包机。
• 航次号为 6位年月日-2位流水号-航班号，流水号每自然日从 01 递增。
• 航班列表涵盖全部航班，支持按状态筛选（计划中 / 已起飞 / 已降落 / 已取消，多选，默认全选）。
• 列表内操作：计划中 的航班提供 起飞 与 取消——未装载货物不能起飞，已装载货物不能取消；已起飞 的航班提供 降落。
• 列表列包含航次号、航班号、始发站、取货站点、装载方式、航班状态、计划起飞、实际起飞、实际到达、起飞操作人、降落操作人；列宽可拖拽调整，每页 20 / 40 / 60 条。

8. Loading8. 装机

1. Pick the destination station card to filter the package list; the header, station cards, flight info and action buttons stay pinned while scrolling.
2. Select packages and confirm the flight — only one flight can be chosen per loading batch.
3. After confirmation, packages move to LOADED (Pending Unload).

1. 点击目的站点卡片筛选包裹列表；滚动时标题、站点卡片、航班信息与操作按钮保持吸顶。
2. 勾选包裹后确认航班，单次装机只能选择一个航班。
3. 确认后包裹流转到 LOADED（待卸机）。

9. Unloading9. 卸机

1. Scan or search the tracking number in the left scan area, or search on the right; the scan area supports camera scanning.
2. Use Select All and Batch Unload together, then confirm.
3. After unloading, packages flow to PENDING_PICKUP at the destination station.

1. 左侧扫码区扫码识别运单号，或使用右侧搜索区查询；扫码区支持连接摄像头扫码。
2. 使用 全选 与 批量卸机 后确认。
3. 卸机后包裹流转到目的站点的 PENDING_PICKUP（待取件）。

10. Receiving Stations10. 站点接收

Each station group scrolls independently, with the group header and table header pinned inside the container. The station colour blocks stay on one row.

每个站点分组独立滚动，分组标题与表头在容器内吸顶；站点色块横排保持一行。

11. Track11. 查询

Query notice查询须知

• Pickup Station staff — packages of your own station from the last three calendar months are shown by default; for older ones, search by tracking number.
• Head Office staff — the last three calendar months are shown by default; for earlier data, search by tracking number.

• 【取货站点】人员：默认展示本站点相关近三个月（自当月 1 号起算）快递，超期请输入快递单号查询。
• 【总公司】员工：默认展示近三个月数据（自当月 1 号起算），如需更早数据请输入单号查询。

Search and filters搜索与筛选

1. Pick the field on the left of the search box — All / Tracking No / Sender / Receiver Name / Receiver Phone — then type a keyword and click Query (Enter works too). A Clear button appears once the box has content.
2. The Location Code box filters by storage location, and the result count is shown on the right of the toolbar.
3. Each status tab above the list carries a live count. Counts follow the current filters (time range + keyword + location code) and are limited to your own permission scope, so All always equals the number of rows the list returns.
4. Click a row, or View Package, to open the full trace from inbound to sign-off, including exception remarks.

1. 在搜索框左侧选择字段——全部 / 快递单号 / 寄件人 / 收件人姓名 / 收件人电话——输入关键词后点 查询（回车同样生效）。框内有关键词时会出现 清除 按钮。
2. 货位号 输入框按库内货位筛选；工具栏右侧显示当前搜索结果条数。
3. 列表上方的状态标签各自带实时数量。数量按当前筛选条件（时间范围 + 关键词 + 货位号）统计，并受本人权限范围限制，因此 全部 恒等于列表实际返回的条数。
4. 点击行或 查看包裹 可查看从入库到签收的完整轨迹及异常备注历史。

Time range时间范围

12. Messages12. 消息与通知

Site Messages (inbox)站内消息（用户端）

• Browse internal messages with publisher and publish time. Category tabs carry an unread badge and the sidebar entry shows a red unread dot.
• Opening a message marks it as read. Messages are targeted at roles, at a single user, or broadcast to everyone.
• The inbox lives under Info Center → Site Messages and only ever shows the messages you are allowed to see.

• 浏览站内消息，显示发布人与发布时间；分类标签带未读徽标，侧边栏入口有未读红点。
• 打开消息即标记已读。消息可按角色定向、定向到单个用户，或广播给所有人。
• 入口位于 信息中心 → 站内消息，只会显示你有权查看的消息。

Message Management (admin module)消息管理（管理模块）

1. Publish Message — compose an Admin Notice: text plus images/files (up to 20 attachments, pasted screenshots supported), tick one or more recipient roles (none ticked = everyone), and optionally link a tracking number.
2. Message History — filter by type (Outbound / Departure / Arrival / Exception / Admin Notice), tracking number, date range and keyword; the list shows recipients, read count and operator, and can open the reader list.
3. Message Templates — edit the bilingual body and default recipients of the four automatic notices. Placeholders such as {count}, {tracking_no}, {flight_no}, {flight_code}, {origin}, {destination}, {type}, {reason} and {time} are replaced when the notice is generated.
4. Follow Settings — administrator only. Followed sender companies or tracking numbers notify the chosen recipients on outbound, departure and arrival.

1. 发布消息 — 撰写「管理员通知」：正文 + 图片/文件（最多 20 个附件，支持粘贴截图），勾选一个或多个接收角色（全不勾 = 发给所有人），可关联一个快递单号。
2. 历史消息 — 按类型（出库 / 起飞 / 降落 / 异常 / 管理员通知）、快递单号、时间范围、关键词筛选；列表显示接收对象、已读人数与操作人，可查看已读名单。
3. 消息模板 — 编辑四类自动通知（出库 / 起飞 / 降落 / 异常）的中英双语正文与默认接收角色。{count}、{tracking_no}、{flight_no}、{flight_code}、{origin}、{destination}、{type}、{reason}、{time} 等占位符在生成通知时自动替换。
4. 关注设置 — 仅管理员可用。被关注的寄件单位或快递单号在出库、起飞、降落时通知指定接收对象。

13. Data Statistics13. 数据统计

13.1 Page structure & common rules13.1 页面结构与通用规则

• Five panels: Today Live Board / 7-Day Volume / 7-Day Flights / Pickup Site Snapshot / Stock Health. All five share the same width, so switching never shifts the layout.
• Top Site scope filter: administrators and headquarters staff see all sites; a pickup-station account sees only its own site. When a single site is selected a red note appears — click All sites to go back.
• Data refreshes automatically every 30 seconds; the header shows "just refreshed <time> · auto refresh every 30s".
• Hover a dot on a line chart to read its exact value (tap on mobile).
• Time basis is Juba / South Sudan time (UTC+2). "Today" means from 00:00 of the current day, and it resets at 00:00 the next day.
• The trend panels cover the past 7 complete days, excluding today (today is on the Today Live Board). The exact range is printed next to the table title, e.g. Range: 2026-09-28 ~ 2026-10-04 (excluding today).

• 共五个面板：今日实时看板 / 7天运量趋势 / 7天航次趋势 / 取货站点快照 / 库存健康度。五个面板宽度一致，切换时页面不会左右跳动。
• 顶部 站点范围 筛选：管理员与总部员工可见全部站点，取货站点账号仅可见本站点。选中某个站点时会出现红色提示，点 全部站点 即可看全部。
• 数据每 30 秒自动刷新；标题行显示「刚刚刷新 <时间> · 每30秒自动刷新」。
• 折线图上的圆点，鼠标悬浮（手机端点按）即可显示该点具体数值。
• 时间基准为朱巴 / 南苏丹时间（UTC+2）。「今日」指当天 00:00 起，次日 00:00 清零重算。
• 趋势类面板统计的是过去 7 个完整日期，不含今天（今天的数据看「今日实时看板」）。表格标题旁会标出准确区间，例如 统计区间：2026-09-28 ~ 2026-10-04（不含今天）。

13.2 Two iron rules: piece count & weight13.2 两条铁律：件数与重量

13.3 Panel 1 — Today Live Board13.3 面板一：今日实时看板

Table A · Today's Volume (counts everything that happened since 00:00 today). Header reads "total kg : pcs".

表 A · 今日业务量（统计今天 0 点至今发生的动作）。表头写作「总重量 kg ：件数」。

Table B · Current Stock Snapshot — pure stock, no time limit (includes historical leftovers), used to judge backlog and stagnation risk.

表 B · 当前库存快照——纯存量，不限时间（含历史留存），用于评估积压与滞留风险。

13.4 Panel 2 — 7-Day Volume Trend13.4 面板二：7天运量趋势

Metrics per site per day: Inbound / Outbound / Loaded / Delivered / Completed / Exceptions. Each row also shows the 7-day total, the daily average and a mini trend line; the chart above follows the site filter and its dots show exact values on hover.

按站点、按日统计的指标：入库 / 出库 / 装机 / 送达 / 已完成 / 异常。每行还给出 7 天合计、日均与迷你趋势线；上方折线图跟随站点筛选，圆点悬浮可看具体数值。

13.5 Panel 3 — 7-Day Flight Trend13.5 面板三：7天航次趋势

• A voyage is attributed by its actual departure time, so it can cross days.
• A voyage is grouped to a site by the flight destination (the destination is the pickup site).
• Charter and mixed flights are counted separately for voyage count and loaded weight, plus a combined total row so you never have to add the two by hand.
• Loaded-weight rows also show the matching voyage count in the same cell (weight : voyages); hovering a dot on the weight chart shows both weight and voyage count.

• 航次按实际起飞时间归属，因此可以跨天。
• 航次按航班目的地归到站点（目的地即取货站点）。
• 包机与混装分别统计航次数量与装载重量，并给出航次合计行，不用自己相加。
• 装载重量行同一格里也写了对应班次（重量 ：班次）；重量图上悬浮圆点会同时显示重量与班次。

13.6 Panel 4 — Pickup Site Snapshot13.6 面板四：取货站点快照

13.7 Panel 5 — Stock Health & 48h Signing13.7 面板五：库存健康度与 48h 签收时效

Closing stock: today's closing = yesterday's closing + arrived today − signed today. It carries a historical baseline, so it reflects the real stock on hand, not just the 7-day change. The bar chart shows each day's closing stock (value printed above the bar, date below).

今日结存库存：今日结存 = 昨日结存 + 今日到货 − 今日签收。它带有窗口前的历史基线，反映的是真实在手存量，而不只是 7 天内的增减。柱状图给出每天的结存（数字在柱子上方，日期在下方）。

48h signing rate: parcels signed within 48h ÷ completed parcels × 100%. The clock starts when the parcel is delivered to the site; the signing time is the parcel's "completed time" — no other timestamp is used.

48h 达成率：48 小时内签收件数 ÷ 已完成件数 × 100%。计时起点是包裹送达站点的时间；签收时间取包裹的「已完成时间」，不取任何其他时间。

13.8 FAQ — figures people ask about most13.8 常见疑问（最容易被问到的问题）

14. Personnel & Permissions14. 人员与权限

Users用户管理

Add a user with username, role, name, contact and bound site. New accounts use the default password 123456. Existing accounts can be reset, enabled or disabled. Users are paginated.

新增用户需填写用户名、角色、姓名、联系方式与绑定站点，新账号默认密码 123456。可重置密码、启用或禁用；用户列表带翻页。

Permission Settings权限配置

1. Type a role name and click + Add; the new role appears in the role list. Configure its permissions and click Save to take effect.
2. Tick each second-level menu item individually. A group checkbox selects the whole group; the count column shows how many items are enabled.
3. The admin role is always fully enabled and cannot be edited.
4. Reset restores that role's built-in defaults.

1. 输入角色名称点击 + 添加，新角色出现在角色列表中；配置权限后点击 保存 生效。
2. 逐项勾选二级菜单；分组复选框可整组勾选，右侧「已开通」列显示已开通数量。
3. admin 角色始终全量开通，不可编辑。
4. 重置 可恢复该角色的内置默认权限。

Password Reset Requests密码重置申请

1. Users who forgot their password submit a request from the mobile app ("Forgot password?") or from the login page.
2. Requests are listed with username, real name, contact, note, request time and status.
3. On a pending row click Reset and confirm: the password goes back to 123456, the user must change it on next login, and an in-app message is sent to that user only.
4. After handling, the row shows Done and the button disappears — it cannot be handled twice.

1. 忘记密码的用户在手机端（「忘记密码？」）或 PC 登录页提交申请。
2. 申请会出现在本列表，包含用户名、姓名、联系方式、备注、申请时间与状态。
3. 对待处理的行点击 重置密码 并二次确认：密码重置为 123456，该用户下次登录须强制改密，同时系统只向他本人发送一条站内消息。
4. 处理完成后该行状态变为 已重置，按钮消失，不可重复处理。

15. Address Settings15. 地址设置

• Add Sender Company — create a sender company (name, code, warehouse address). Below it there is a sender query box; query records are saved in the browser and can be deleted one by one or cleared.
• Sender Company Mgmt — list, search, disable or enable companies. Company name and code must be unique; there is no edit function.
• Pickup Station Mgmt — manage the fixed pickup stations: 3-letter code, detailed address, contact and phone. Code and address must be unique; there is no edit function.

• 新增寄件单位 — 新增寄件公司（名称、缩写、公司仓库地址）；下方为寄件单位查询，查询记录保存在浏览器本地，支持单条删除与一键清空。
• 寄件单位管理 — 列表、搜索、禁用/启用公司；公司名称与缩写均需唯一，无编辑功能。
• 取货站点管理 — 维护固定取货站点：3 字母缩写、详细地址、联系人、电话；缩写与地址均需唯一，无编辑功能。

16. Basic Management16. 基础管理

• Categories — goods categories. Enter a Chinese and/or English name; at least one is required. Built-in categories are translated into all four languages; custom ones fall back to the language you filled in.
• Exceptions — report an exception with type, description and photos; handle it with a status, opinion and evidence. Handled records show their conclusion read-only.
• Publish — publish a site message (same form as Site Messages).

• 货物种类 — 中文名称与英文名称至少填一项即可。内置种类四语言齐全；自建种类按已填语言回退显示。
• 异常管理 — 上报异常（类型、描述、照片），处理时填写处理状态、处理意见与凭证；已完成的记录处理结论为只读。
• 发布消息 — 发布站内消息（与站内消息页同一表单）。

17. Log Management17. 日志管理

18. Express Business & Finance18. 快递业务与财务管理

The former "Package & Cost" module is now split into two top menus: Express Business (3 sub-pages) and Finance Management (6 sub-pages). The old "Express Fee Management" and "Company Fee Management" pages are replaced by Freight Settlement and Customer Bill Summary; Base Freight Management has been merged into Freight Settlement.

原「包裹与费用管理」已拆分为两个一级菜单：快递业务管理（3 个二级页面）与财务管理（6 个二级页面）。旧「快递费用管理 / 公司费用管理」两页已分别由「运费结算管理 / 客户账单汇总」取代；原「基础运费管理」页已并入「运费结算管理」。

Voyage List Management航次列表管理

Search by voyage or flight number with a Clear button and live result count. Columns include voyage no., flight no., origin, destination, planned departure, actual departure, actual landing, operators, flight status, package count, weight and actions. This is a read-only lookup page under Express Business — creating flights and the depart / land operations are done on the separate Flight Management page (chapter 7).

可按航次号或航班号搜索，搜索框旁有「✕ 清除」按钮并实时显示结果条数。列包含航次号、航班号、出发机场、目的机场、计划起飞、实际起飞、实际降落、操作人、航班状态、包裹数量、重量与操作。本页为只读查询页（快递业务管理组下，比航班管理多「目的机场 / 包裹数量 / 重量」列）；新增航班与起飞 / 降落等操作在第 7 章「航班管理」页进行，两者不是同一个页面。

Package Management快递包裹管理

• Filters: keyword (tracking no. / sender company), logistics status, payment status (Amount Not Entered / Pending Payment / Paid / Voided), order-time range and done-time range, plus Search and Reset buttons.
• Batch row: on the left a dark-outlined Exceptions only switch — tick to list only packages with exceptions, tick again to show all; on the right the selected count, clear selection, batch export, reset column widths and column settings.
• The table has 14 columns, including the new Goods Category (the category chosen on the inbound form). Order time is no longer a standalone column (use the order-time filter instead). The Print column, its icon and the print count were removed from this table — to print a waybill, open the parcel detail dialog instead.
• Click a tracking no. to open the package detail dialog with its operation history.

• 筛选：关键词（快递单号 / 寄件单位）、物流状态、支付状态（金额待录入 / 待支付 / 支付完成 / 已作废）、下单时间区间、完成时间区间，配「搜索 / 重置」按钮。
• 批量操作行：左端为深色描边的「仅看异常」开关——勾选后只显示有异常的包裹，再次点击取消恢复全部；右端依次是已选统计、清除选择、批量导出、重置列宽与列设置。
• 表格共 14 列，含新增的「货物种类」（即下单页所选货物种类）；不再单列「下单时间」（改用下单时间筛选）。本表已删除「打印」列及其图标与打印次数，需要打印面单请在包裹详情弹窗里操作。
• 点击快递单号可打开包裹详情弹窗，查看操作记录历史。

Exception Packages异常快递管理

Two sub-tabs: Exception Report and Exception Handling. Filter by exception type (lost / damaged / address error / other) and keyword (tracking no. / reporter / contact / reason).

含「异常上报 / 异常处理」两个子页签，可按异常类型（丢失 / 破损 / 地址错误 / 其他）与关键词（单号 / 上报人 / 联系方式 / 原因）筛选。

Finance Funnel (Unsettled)财务漏斗（未结清）

• Daily to-do board listing only unsettled periods (sender × month); a period disappears from the funnel once fully collected.
• KPI cards: total parcels / cancelled orders / valid billable parcels (= total − cancelled), then awaiting amount, collected amount (split into this month and history), new collected this month and overdue collected.
• Row actions: Settle (jump to Freight Settlement pre-filled), View Bill (jump to Customer Bill Summary pre-filled). Payments are recorded in Freight Settlement: select parcels → Confirm Company Payment.
• Embedded finance funnel chart with an "All" range plus one button per unsettled billing month, in four layers by payment state — Fees Pending Import (blue) / Billable (purple) / Awaiting Payment (yellow) / Collected (green). Layer meanings and month attribution are explained in chapter 1, Part 2 — Finance process. Click a sub-row to drill into Package Management or Freight Settlement with filters pre-filled.

• 财务每日待办看板，只列出未结清的「寄件单位 × 账单月份」账期，收齐尾款自动从漏斗消失。
• 顶部 KPI 卡：总快递单数 / 已取消 / 有效计费（= 总单数 − 已取消），以及待回款金额、已回款金额（拆本月 / 历史）、本月新增回款、历史逾期回款。
• 行内动作：去结算（钻取运费结算管理并预填筛选）、看账单（钻取客户账单汇总并预填）。回款登记统一在运费结算管理里勾选后「确认公司收款」。
• 页面内嵌财务经营漏斗图：范围按钮为「全部」+ 逐个未结清账期月份，按支付状态分四层——费用待导入（蓝）/ 有效计费（紫）/ 待回款（黄）/ 已回款（绿）；层含义与月份归属见第 1 章「二、财务过程」。点击细分行可钻取到快递包裹管理或运费结算管理并自动带入筛选。

Price Import List价格导入列表

• Imports base freight by unit price. CSV / .xlsx columns are matched by header, so order may vary: Tracking No, Batch No., Sender, Pickup Station, Weight(kg), Goods Category, Unit Price(USD/kg). Goods Category is reference information only and is not validated. Deleting a reference column means it is skipped.
• Enter the unit price (USD/kg); the system computes the amount = unit price × batch total weight. For a multi-piece batch the whole batch must be imported together and share one unit price; the batch total fee is allocated across the pieces by each piece's weight share, and the last piece absorbs the rounding difference so the pieces always add up to the batch total exactly.
• Batch no. IMP-YYYYMMDD-NN with status Success / Partial / Failed; import records are read-only and keep the original file name for audit.
• On success the amount is locked and payment status becomes Pending Payment. Duplicate waybills within one file reject the whole file; already confirmed / paid / voided waybills are rejected.
• Failure reasons are stored as codes, shown in the interface language and grouped per batch.

• 只导入基础运费，改为按单价导入。支持 CSV / .xlsx，按表头识别列，顺序可变：Tracking No, Batch No., Sender, Pickup Station, Weight(kg), Goods Category, Unit Price(USD/kg)。货物种类仅为参照信息，不参与核对；删掉某一参照列即跳过该列核对。
• 填写单价(USD/kg)，系统自动核算金额 = 单价 × 批次总重。一批多件（一票多件）必须整批一起导入且单价一致；整批总费用按各子单重量占比分摊，末件吸收尾差，保证各子单金额之和恰好等于整批总费用。
• 批次号 IMP-YYYYMMDD-NN，状态：全部成功 / 部分成功 / 失败；导入记录只读，保留原始文件名作对账凭证。
• 导入成功即锁定金额、支付状态变「待支付」；同一文件内重复单号整单拒绝；已是待支付 / 支付完成 / 已作废的单号再次导入被拒。
• 失败原因以代码存储，按界面语言翻译展示，并按批次分组计数。

Freight Settlement运费结算管理

This page merges the former Base Freight Management page and lists every waybill of the open billing periods — including rows whose amount has not been imported yet: payment status shows Amount Not Entered / Pending Payment / Paid (Voided is excluded). The base freight amount is authoritative only after import — before import the amount stays empty; billing month = the natural month in which the waybill was completed.

本页已合并原「基础运费管理」页：列出所有未结清账期的快递单，包括尚未导入金额的运费单——支付状态显示「金额待录入 / 待支付 / 支付完成」（「已作废」不显示）。基础运费以导入金额为准，未导入时金额为空；账单归属月份 = 快递单完成所在自然月。

• Columns (15): checkbox, tracking no., sender company, settlement type, weight, logistics status, goods category, fee type, amount, unit price (right-aligned, locked at import), price status, billing month, payment status and paid at, plus a Payment Trace column. Adjustment rows (fee type ADJ) show a dash for unit price / price status.
• Payment Trace: click the trace button to open a timeline (same style as the logistics operation trace, latest on top) of the whole financial flow after the waybill is completed — package completed → unit price imported → price change requested / pending / approved / rejected → adjustment order created → payment completed. Every node shows the time, the operator and the action; the payment node also carries method / receiver account / holder with a voucher link — View Voucher opens the voucher image full-screen directly (it falls back to the original voucher dialog only when the voucher is a PDF or missing, with the payment details taken from the trace node). The former payment-method / account / holder / voucher / import-time / operator columns are all folded into the trace.
• Filters: keyword, logistics status, payment status (incl. Amount Not Entered), settlement type, price status (All / Not Adjusted / Pending / Approved / Rejected) and the Payment Completed Time range. "Payment Completed Time" means the moment Confirm Company Payment was saved; it is empty for records that have not been paid, so a range only matches paid rows.
• Freight Template Export on the toolbar: tick parcels whose payment status is Amount Not Entered, export the template (7 columns, incl. Goods Category), fill in the unit prices, then import the file on Finance → Price Import List (or with the import button on this toolbar). If any selected parcel is not "Amount Not Entered", a reminder dialog appears and the export stops.
• The unit price is locked at import time and can never be changed — a wrong amount is corrected only through a Price Request (finance submits, the admin approves). The Price Request toolbar button is enabled when exactly one waybill is selected whose payment status is Pending Payment (a base-freight row with no pending request and an amount already calculated); click it to open the request dialog. Weight can never be edited either.
• Select parcels and click Confirm Company Payment to mark them Paid and record payment method / receiver account / holder / voucher. Batch confirm requires the same sender company and the same payment status (blocked both front-end and back-end). Rows with status Amount Not Entered cannot be collected — the amount is not calculated yet; import the unit prices and confirm the amounts first.
• The amount is locked at import time and cannot be edited on this page — submit a Price Request instead. Payable total = base freight + adjustments. Logistics status and payment status are independent: parcels can be priced and collected from Pending Outbound onward; only Cancelled is blocked.

• 表格共 15 列：勾选框、快递单号、寄件单位、结算类型、重量、物流状态、货物种类、费用类型、金额、单价（右对齐，导入即锁定）、调价状态、账单月份、支付状态、支付时间，外加一列支付轨迹。调整运费行（费用类型 ADJ）的单价 / 调价状态显示「—」。
• 支付轨迹：点「轨迹」按钮弹窗查看财务全流程时间线（样式同物流操作轨迹，最新在最上面）——快递单完成 → 导入单价 → 调价申请 / 待审批 / 通过 / 拒绝 → 生成调整运费单 → 支付完成；每个节点含时间、操作人和操作方式，支付完成节点还展示付款方式 / 收款账号 / 户主并可点「查看凭证」——凭证为图片时直接全屏打开，凭证为 PDF 或无凭证时才回退原凭证弹窗（付款信息取自轨迹节点）。原付款方式 / 收款账号 / 户主名称 / 凭证 / 导入时间 / 操作人六列已全部收进轨迹。
• 筛选：关键词、物流状态、支付状态（含「金额待录入」）、结算类型、调价状态（全部 / 未调价 / 待审批 / 已通过 / 已拒绝），以及支付完成时间区间。「支付完成时间」指「确认公司收款」保存的时间，未收款的记录该字段为空，因此按区间筛选只会命中已收款的记录。
• 工具栏提供运费模板导出：勾选支付状态为「金额待录入」的包裹，导出运费模板（共 7 列，含货物种类），填写单价，到【财务管理 → 价格导入列表】导入（也可直接用本工具栏的导入按钮）。所选包裹只要有一票不是「金额待录入」，即弹出提醒弹窗并中止导出。
• 单价在导入时即锁死、不可修改——金额录错只能通过 申请调价 修正（财务发起、管理员审批）。工具栏的 申请调价 按钮在只勾选 1 条支付状态为「待支付」的基础运费单（尚无未决申请、金额已核算）时可用，点开申请弹窗即可发起。重量同样一律不可修改。
• 勾选快递单后点 确认公司收款 即置为「支付完成」，并记录付款方式 / 收款账号 / 户主名称 / 凭证。批量「确认收款」仅限同一寄件单位 + 同一支付状态（前端勾选即拦 + 后端双保险）。支付状态为「金额待录入」的单不能收款——金额尚未核算，请先导入单价并确认金额。
• 金额在导入时即锁定，本页不能改；要改金额在工具栏发起「申请调价」，管理员审批通过后由系统自动生成调整单。应付总额 = 基础运费 + 调整运费合计。物流状态与支付状态彼此独立：从「待出库」起即可导入费用与收款，仅拦截「已取消」。

Freight Difference运费差额管理

Read-only list. Adjustment no. ADJ-YYYYMM-NNN. Every difference order is generated automatically by the system when a Price Request is approved — finance has no direct entry (the "New Adjustment" button, the entry dialog, the type column and the type filter have been removed). The period is locked by the system to the month in which the price request is approved and can never be changed — history periods are never rewritten. The status column derives from whether the sender's period is settled. A 🔒 badge next to the adjustment no. marks a difference order created for a sealed (monthly-closed) period.

纯查看列表。调整单号 ADJ-YYYYMM-NNN。所有差额单均由 调价审批 通过后系统自动生成——财务无任何直录入口（「新增调整」按钮、录入弹窗、调整类型列与筛选均已移除）。归属账期由系统锁定为审批通过当天所在月，不可修改——历史账期永不改写。列表「状态」由该单位该账期是否全部结清推导。调整单号旁的 🔒 标识表示该差额单为封账（月度结清）后生成的差额调整单。

No direct entry at all on this page — discount, fee offset and claim adjustments all go through Price Approval (finance submits a request, the admin approves). An approved request lands here as a system-generated entry booked to the approval month. Unit prices are locked at import time and cannot be changed; a wrong amount is corrected only through a price request approved by the admin.

本页已无任何直录入口：折扣、费用冲抵与理赔调整单一律走 调价审批（财务发起申请、管理员审批）。审批通过后由系统自动生成调整单落在这里，归属审批当月。单价在导入时即锁死、不可修改，金额录错只能通过「申请调价」经管理员审批后修正。

Customer Bill Summary客户账单汇总

Aggregates by sender × completion month. Payable total = base freight + adjustments − claims. Row actions: View Base Freight (jump to Freight Settlement pre-filled with company and month). Payments are registered in Freight Settlement: select parcels → Confirm Company Payment.

按「寄件单位 + 完成时间所在月」聚合，应付总额 = 基础运费 + 调整运费 − 理赔费用。行内动作：查看基础运费（跳转运费结算管理并预填公司与月份）。回款登记在运费结算管理里勾选快递单后「确认公司收款」。

Settled Periods Archive已结清账期归档

A read-only history that lists settled periods only, with the settled time (the period's last "Confirm Company Payment" timestamp). Filter by company keyword and year; export a period snapshot CSV; 20 rows per page.

只读历史仓库，仅展示已结清账期，含结清时间（该账期最后一笔「确认公司收款」时间）。支持单位关键词与年份过滤；可导出该账期账单快照 CSV；每页 20 条。

Price Approval (Admin Only)调价审批（仅管理员可用）

Admin only. Finance has no final pricing power: a discount or a fee offset is a request, not an entry. Finance submits a price request (type: discount / offset; method: rate % or amount USD); the admin approves or rejects it. On approval the system auto-creates an adjustment entry (discount is negative) booked to the approval month; the original amount stays unchanged, so final payable = original + adjustment. A rejection must carry a reason and is kept in the approval log forever. The unit price is locked at import time, so a wrong amount can be corrected only through this approval flow. Two tabs: Price Approval (pending requests, with Approve / Reject) and Approval Log (all requests with status Pending / Approved / Rejected / Voided). A sidebar badge and a message of type "Price Request" alert the admin to pending requests.

仅管理员可见。财务没有最终定价权：折扣或费用冲抵是「申请」而非「记账」。财务发起调价申请（类型：折扣 / 费用冲抵；方式：比例 % 或金额 USD），由管理员同意或拒绝。同意后系统自动生成一条调整单（折扣为负）计入审批当月，原金额不变，最终应付 = 原金额 + 调整金额。拒绝必须填写原因并永久留存于审批日志。单价在导入时即锁死，金额录错只能走本审批流修正。页内两个子页：调价审批（待审批列表，含同意 / 拒绝）与审批日志（全部申请，状态为待审批 / 已通过 / 已拒绝 / 已作废）。侧边栏角标与「调价申请」类型的消息会提醒管理员有待办。

19. Manual & Updates19. 操作手册与更新

1. Open Manual & Updates → Feature Update Log from the sidebar.
2. The table lists every released version with its version number, release date and main changes.
3. The right column offers View (opens this manual in a new tab) and Download (saves the manual file).
4. The menu is enabled for all roles by default; it can be turned off per role in Permission Settings.

1. 在侧边栏打开 操作手册与更新 → 功能更新记录。
2. 表格按版本列出更新说明，含版本号、发布日期与主要更新内容。
3. 右侧提供 查看（新标签页打开本手册）与 下载（保存手册文件）。
4. 该菜单默认对所有角色开通，可在权限配置中按角色逐项关闭。

20. Waybill Printing20. 面单打印

• All-English content, palm size about 100 × 150 mm, split layout: information on the left, a 70 × 70 px QR code at the top right.
• Sender company shows the full legal name; pickup address shows the detailed address.
• Sender and receiver phones are masked: first 3 digits + **** + last 4 digits.
• The sign-off code and numbers are removed; the bottom shows the print count (Print: N) and the print time.
• Goods name, settlement type and transport type are kept. The QR code is reserved for later scan-to-sign-off.

• 全部英文，巴掌大小约 100 × 150 mm，左右分栏：左侧信息 + 右上角 70 × 70 px 二维码。
• 寄件公司显示单位全称；取货地址显示详细地址。
• 寄件人与收件人电话脱敏：前 3 位 + **** + 后 4 位。
• 删除签收码及数字；底部显示打印次数（Print: N）与打印时间。
• 保留货物信息名称、结算类型与运输类型；二维码用于后续扫码签收。

21. Package Status Machine21. 包裹状态机

All transitions are validated by a single state machine, so illegal jumps are rejected by the server.

所有状态流转由统一的状态机校验，非法跳转会被服务端拒绝。

22. FAQ22. 常见问题

A new menu does not appear新增菜单后看不到

Check the role's permissions first. If you are an administrator and still cannot see it, the hardcoded admin permission list on the server has to be updated, then the service restarted.

先检查该角色权限是否勾选。若管理员也看不到，说明服务端硬编码的管理员权限列表未同步，需补充后重启服务。

Some text stays in Chinese after switching language切换语言后仍有中文

A missing translation entry silently falls back to Chinese without an error. Add the entry to all four language blocks in i18n.js.

词条缺失会静默回退成中文且不报错。需在 i18n.js 的四个语言块中补齐该词条。

Front-end changes do not take effect前端改动不生效

Hard-refresh the browser (Ctrl + F5). Back-end changes require restarting the service.

请硬刷新浏览器（Ctrl + F5）；后端改动需要重启服务。

Export returns 401导出报 401

Exports must go through fetch() with the Authorization: Bearer <token> header. Do not use window.open(), which loses the token.

导出必须用 fetch() 并带上 Authorization: Bearer <token> 请求头；不要用 window.open()，会丢令牌。

Sticky table header stops working表头吸顶失效

Do not put overflow-x: auto on the scrolling container — it breaks sticky headers. Let columns adapt instead.

不要在滚动容器上使用 overflow-x: auto，会破坏 sticky 表头；应让列宽自适应。

A package older than three months is not in the list三个月前的快递查不到

The Track page defaults to the last three calendar months. Switch the search field to Tracking No and enter the full number — this lifts the time limit. Administrators can also pick an earlier date range; the current range is always shown next to the "Range" label.

查询页默认只显示最近三个自然月。把搜索字段切到 快递单号 并输入完整单号即可突破时间限制；管理员还可以自选更早的起止日期。「查询范围」旁始终显示当前生效的区间。