# 货代 SaaS 平台后台原型指引

## 首读入口

- 页面、字段和局部交互先按下方“原型模块快速索引”定位，再只读取命中的 `prototype-src/modules/*.html`。
- 页面涉及弹窗、抽屉或跨模块交互时，再读取 `prototype-src/overlays.html` 和 `prototype-src/app.js` 中对应 ID/函数；视觉样式按需读取 `prototype-src/shell.html`。
- `index.html` 是由拆分源码生成的完整可运行入口，本地预览直接双击它。
- WMS 字段未在原型中明确时，再读取 `wms_full_data.json` 和 `柏悦WMS系统文档.md`。

## 怎么看

- 本地看完整后台：双击 `index.html`。它是当前模块源码生成的可运行总入口，不要打开备份文件作为产品验收入口。
- 查看某个业务模块：直接打开索引命中的 `prototype-src/modules/*.html`；模块文件是页面片段，不是可独立运行的完整 HTML，不能直接双击判断布局。
- 查看某个页面：先在 `prototype-src/manifest.json` 搜索页面 ID，再在对应模块中搜索 `id="page-页面ID"`。
- 查看页面字段：读取该页面容器内的 `<th>`、表单 `<label>`、按钮文字和 `id`；若 `<tbody>` 为空或由 `renderTable` 填充，继续读取 `prototype-src/app.js` 的数据数组和渲染函数。
- 查看页面流程：从页面内的 `onclick`、`data-*` 和返回链接开始，追踪 `switchPage('页面ID')`、`showModal('弹窗ID')`、`render...()`、`save...()`、`submit...()`；弹窗定义在 `overlays.html`，函数通常在 `app.js`。
- 查看导航入口：读取 `prototype-src/shell.html` 中对应 `.sidebar-item` 和 `.sub-menu-item`；页面存在但没有导航入口时，按历史/隐藏页面处理，不要自行假定它是当前产品入口。

## 怎么读取

### 产品确认页面

按以下顺序读取，满足需求即可停止，不要默认加载整个原型：

1. 本文件的“原型模块快速索引”。
2. 命中的模块 HTML，定位 `page-页面ID`。
3. 页面中涉及的弹窗 ID，读取 `prototype-src/overlays.html` 对应弹窗。
4. 页面按钮引用的函数，读取 `prototype-src/app.js` 中对应函数及其直接调用的数据数组。
5. 若涉及 WMS 字段，再读取 `wms_full_data.json` 或 `柏悦WMS系统文档.md`。

### 开发实现需求

读取结果至少记录：页面 ID、模块文件、导航入口、页面字段、操作按钮、弹窗 ID、跳转页面 ID、数据数组、渲染函数、保存/提交函数和状态变化。无法从原型确认的流程必须标记为“原型未定义”，不得用猜测补齐。

### 按页面 ID 定向检索

```powershell
$page = 'clearance-doc'
rg -n -C 3 "page-$page|switchPage\('$page'|render.*$page|$page" prototype-src
```

检索结果跨模块时，以 `manifest.json` 的归属为准；不要因为同名数据或函数出现在共享脚本，就把页面移动到共享文件。

## 修改规则

- `prototype-src/modules/*.html`、`prototype-src/shell.html`、`prototype-src/overlays.html`、`prototype-src/app.js` 和 `prototype-src/tail.html` 是维护源码。
- 页面主体放在唯一一个模块文件中；共用弹窗放 `overlays.html`，全局样式和导航壳放 `shell.html`，交互脚本放 `app.js`。
- 新增、删除、改名或移动 `page-*` 时同步更新本文件中的模块索引和 `prototype-src/manifest.json`；页面 ID 在所有模块中必须唯一。
- 修改后在本目录执行 `node scripts/build-prototype.cjs`，重建 `index.html`，再执行 `node tests/verify-prototype-modules.cjs`。
- `node scripts/split-prototype.cjs` 会用完整原型覆盖全部拆分源码，仅用于首次迁移或明确需要从总文件重新拆分时，日常修改禁止执行。
- 原型中的产品层级、文案和表格操作列继续遵守仓库根 `AGENTS.md`；原型不能替代阶段需求和已确认契约。

## 模块边界

- 模块按后台一级业务导航划分，列表、详情、新增、编辑及其同域隐藏页面保留在同一个模块文件。
- `12-legacy-orders.html`、`13-freight-customs.html` 收纳当前侧栏未直接展示但完整原型仍保留的历史页面，修改前需先确认当前需求是否仍使用。
- 不把同一业务拆成“一页一文件”；这会割裂列表与详情上下文，也会增加产品同步维护成本。

## 怎么加页面

### 新增普通页面

1. 先确定一级业务模块和唯一页面 ID，例如 `page-customs-audit`。
2. 在对应 `prototype-src/modules/*.html` 的同域页面末尾添加完整 `<div class="page" id="page-...">...</div>`；列表、详情、新增、编辑页面放在同一模块。
3. 在 `prototype-src/manifest.json` 的对应模块 `pages` 和 `pageOrder` 中登记页面 ID，保持页面顺序与生成入口一致。
4. 若页面需要侧栏入口，在 `prototype-src/shell.html` 增加 `.sub-menu-item`，其调用必须是 `switchPage('页面ID',this)`。
5. 若页面有动态表格或交互，在 `prototype-src/app.js` 增加数据、渲染和操作函数；共用弹窗放 `prototype-src/overlays.html`。
6. 执行构建和校验命令，确认新页面能在 `index.html` 中找到且导航可进入。

### 新增弹窗或详情操作

- 页面内按钮只负责调用 `showModal('modal-唯一ID')` 或业务函数。
- 弹窗 HTML 放 `prototype-src/overlays.html`，保存/提交逻辑放 `prototype-src/app.js`，不要把大段共用弹窗复制到多个模块。
- 新增字段时同时检查弹窗初始值、校验、保存数据、列表渲染和详情展示。

## 怎么改页面

### 改静态字段或文案

1. 在模块文件中按 `page-页面ID` 定位目标页面。
2. 修改对应 `<th>`、`<label>`、按钮或提示文字。
3. 搜索旧字段文本和相关 `id`，确认详情、弹窗、空态和操作列没有遗漏。
4. 构建并校验；如果字段是产品契约的一部分，同时核对对应阶段需求文档。

### 改动态表格字段

必须同时检查四处：

- 模块 HTML 的 `<th>` 顺序和表格容器。
- `app.js` 的数据数组字段名。
- `renderTable(...)` 或专用 `render...()` 的列映射。
- 操作列、详情弹窗和导出/打印函数是否仍使用旧字段。

只改 `<th>` 只能改变表头，不代表字段已经接通。

### 改页面流程

- 页面跳转：修改页面内 `switchPage` 调用，并检查目标页面 ID 在 manifest 中存在。
- 弹窗流程：同时修改按钮、弹窗 HTML、打开函数、保存/提交函数和成功/失败提示。
- 状态流转：搜索状态文案在模块、数据数组、渲染函数和筛选条件中的全部引用，确认状态前后兼容。
- 导航调整：只改 `shell.html` 的导航项；不要通过复制页面解决导航问题。

## 修改后验证

```powershell
node scripts/build-prototype.cjs
node tests/verify-prototype-modules.cjs
```

- 必须确认 `index.html` 已生成、目标 `page-*` 只出现一次、`manifest.json` 与模块页面清单一致。
- 涉及交互时，在浏览器打开 `index.html` 手工走一遍入口、主操作、返回、弹窗确认和错误/空态。
- 不要执行 `node scripts/split-prototype.cjs` 作为日常构建；它会从完整备份覆盖拆分源码，可能抹掉模块中的产品修改。

## 原型模块快速索引

| 业务模块 | 首读文件 | 页面 ID / 内容 |
|---|---|---|
| 首页数据看板 | `prototype-src/modules/00-dashboard.html` | `dashboard` |
| 客户管理 | `prototype-src/modules/01-customers.html` | `tenant-list`、`tenant-detail`、`warehouse-tier-fee` |
| 国内仓 | `prototype-src/modules/02-domestic-warehouse.html` | 入库订单与详情、测量/收货审核、WMS 基础/入库/盘点/出库/库存/加工/移库/上架、库位、托盘及详情、国内整柜 |
| 海外仓 | `prototype-src/modules/03-overseas-warehouse.html` | 尾程订单，海外仓入库/出库/换标，产品/托盘/箱号/库存，采购库存及详情 |
| 海外派送 | `prototype-src/modules/04-overseas-delivery.html` | `outbound-dispatch`、BOL/自提历史页、排车列表/编辑/详情 |
| 客户服务 | `prototype-src/modules/04a-customer-service.html` | `outbound-exception`（异常订单） |
| 供应商中心 | `prototype-src/modules/05-suppliers.html` | 供应商列表/编辑、快递公司、往来单位、海运渠道 |
| 货柜管理 | `prototype-src/modules/06-containers.html` | 订舱、拖车、货柜、装柜清单、预装清单、装柜看板 |
| 海外业务 | `prototype-src/modules/07-overseas-business.html` | 采购订单、本土卡车及详情、本土散板及新增/编辑/详情 |
| 财务管理 | `prototype-src/modules/08-finance.html` | 客户账户、应收应付、对账单、结算单、费用分析、利润表及历史财务报表页 |
| 销售管理 | `prototype-src/modules/09-sales.html` | 拜访记录新增/详情、销售提成 |
| 通用资料 | `prototype-src/modules/10-general.html` | 产品、费用项目、汇率管理、仓库（`gen-owned-warehouse`、`gen-fba`、`gen-partner-warehouse`）、下载、船期价格、车辆及详情、派送车队报价表、历史库位/托盘/路线页 |
| 系统与消息 | `prototype-src/modules/11-system-messages.html` | 用户、角色、菜单权限、品牌/客户历史页、消息管理/模板/我的消息、海外用户 |
| 历史订单与库存 | `prototype-src/modules/12-legacy-orders.html` | 旧运单、OMS、库存及库龄页面；当前侧栏无直接入口，使用前核对需求 |
| 运价、报关与清关 | `prototype-src/modules/13-freight-customs.html` | 旧运价/报价/空运/铁路/对账/报表、报关基础资料、清关页面；当前侧栏无直接入口，使用前核对需求 |

精确页面 ID 清单以 `prototype-src/manifest.json` 为准，避免在本文件重复 169 个 ID 后产生双份维护。

## 共享文件快速索引

| 文件 | 内容 | 何时读取 |
|---|---|---|
| `prototype-src/shell.html` | 文档头、全局 CSS、顶部导航、侧栏和主内容开头 | 调整全局视觉、布局或导航时 |
| `prototype-src/overlays.html` | 页面外的共用弹窗、抽屉和浮层 | 页面操作打开弹窗/抽屉时 |
| `prototype-src/app.js` | 全部示例数据、渲染函数和交互逻辑 | 核对按钮行为、状态切换、数据映射时 |
| `prototype-src/tail.html` | 主脚本后的附加脚本及 HTML 结尾 | 只有对应函数不在 `app.js` 时 |
| `prototype-src/manifest.json` | 模块归属与完整原型中的页面顺序 | 新增、删除、改名或移动页面时 |