docs/悦/货代SAAS平台后台/AGENTS.md

货代 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 定向检索

$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 的导航项；不要通过复制页面解决导航问题。

修改后验证

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	模块归属与完整原型中的页面顺序	新增、删除、改名或移动页面时