优化

README.md

@@ -1,88 +1,49 @@
-# 虫虫出海文档索引
+# 虫虫出海文档入口
 
-项目交付文档按业务域组织。当前只有测试环境，以端到端全流程为统一范围；历史规划、确认和验收记录保留在对应业务域目录，仅用于追溯决策，不构成功能边界。
+本文件只负责选入口，不保存业务规则或部署进度。已知页面、文件、API 或当前正文时跳过本文件；未知代码入口查[业务索引](业务快速索引.md)的命中行，不沿所有 README 逐层读取。
 
-- [测试环境单机部署与配置契约](测试环境单机部署与配置契约.md)：唯一环境、部署配置、整体切换与验收。
-- [统一认证与服务通信契约](统一认证与服务通信契约.md)：统一入口、权限撤销、逐事件投递与幂等。
-- [业务单据编号契约](业务单据编号契约.md)：单据前缀、北京时间日流水、唯一性及保留编号范围。
+## 按任务选一种入口
 
-## 业务域文档
+| 任务 | 从哪里开始 |
+|---|---|
+| 改代码、文案或局部逻辑 | 已知目标文件及适用 `AGENTS.md`；业务语义不明才补一段正文 |
+| 只有中文业务词或多义词 | [业务索引](业务快速索引.md)，代码入口与规则正文分开选择 |
+| 跨阶段流程、节点关系或上下游交接 | [全流程维护入口](头程到尾程/README.md)，只查受影响阶段 |
+| 已知某个业务域，需要找规则 | 下表选择该域；找到正文后停止扩展 |
+| 运行、验证、部署或数据库操作 | 下方工程专题，按操作类型只选对应章节 |
 
-- [业务快速索引](业务快速索引.md)：按关键词检索跨端代码入口与业务边界；含独立的按需原型入口表。先查根 AGENTS.md 短路由，只读命中行。
-- 终端业务细则：[Admin](../apps/admin-web/docs/business-index.md)、[Client](../apps/client-web/docs/business-index.md)、[海外 PDA](../apps/pda-overseas-uniapp/docs/business-index.md)；先从各应用 AGENTS.md 短表定位，行为变更再核对受影响条款。
+## 业务域入口
 
-- [订单与客户](订单与客户/README.md)：登录认证、客户与企业、权限、头程订单和客户工作台。
-- [入库测量与计费](入库测量与计费/README.md)：预约取货、到仓收货、箱码与箱唛、测量、尺寸策略、计价和入库费用。
-  - [Firstleg 按需业务索引](../baiyue-firstleg/firstleg/docs/business-index.md)：服务代码入口及测量、计价、装柜、PDA 资源结算细则；先读服务 AGENTS，再查受影响条款。
-- [国内货柜履约](国内货柜履约/README.md)：分柜与同柜、智能排柜、订舱、拖车、PDA 拣货、装柜、报关和国内出仓。
-  - [船期日历功能规划](国内货柜履约/船期日历功能规划.md)：渠道、周模板、单次船期、收货截止时间和按渠道货量统计的独立日历规划。
-- [海外仓业务](海外仓业务/README.md)：船节点、海外接柜、入仓、库存、托盘、换标、转运、废弃、退货、排车、PDA 出库、派送、异常退回、客户回访、一件代发及海外本土业务。
-  - [Lastleg 按需业务索引](../baiyue-firstleg/lastleg-service/docs/business-index.md)：服务代码入口及事件、查询、履约约束；先读服务 AGENTS，再查受影响条款。
-  - [排车列表统一作业改造契约](海外仓业务/排车列表统一作业改造契约.md)：五阶段排车、一单一趟、跨客户同车、派送安排及四块排车详情的当前改造入口。
-  - [外配业务首版开发契约](海外仓业务/外配业务首版开发契约.md)：原排车装车后的外配车辆视图、整车承运金额、到达时间和五个装车照片位。
-  - [排车流程修复规划](海外仓业务/排车流程修复规划.md)：取消释放、派送状态、换标全托、合托来源和前端草稿的修复边界、分工及回归要求。
-  - [采购订单样品履约流程变更需求](海外仓业务/采购订单样品履约流程变更需求.md)：采购样品购买、装箱、面单、交寄、国内核费与寄客户的变更入口。
-  - [船节点标准化契约](海外仓业务/船节点标准化契约.md)：统一船司原始状态、标准节点、预计/实际时间、异常事实、还柜停止规则和新增船司接入门禁。
-  - [美国预约管理统一总览与优化方案](海外仓业务/美国预约管理统一总览与优化方案.md)：美国段各类预约的范围、关联关系、表单精简及分步实施建议。
-  - [预约工作日历 V13 变更说明](海外仓业务/预约工作日历V13变更说明.md)：多客户共车、分批后送、改期取消、重新预约和未定日期跟进的正式业务规则与验收场景。
-  - [预约工作日历开发协作契约](海外仓业务/预约工作日历开发协作契约.md)：工作日历与完整待办的接口、数据归属和开发文件边界。
-  - [预约送仓](海外仓业务/README.md#预约送仓)：预约日历与跨客户同仓预约入口。
-  - [车辆管理原型梳理与任务规划](海外仓业务/车辆管理原型梳理与任务规划.md)：司机资质、车次、自有/外接承运、运维与报价的范围及契约入口。
-  - [内部拼车需求池首版开发契约](海外仓业务/内部拼车需求池首版开发契约.md)：车次余位发布、销售意向、承运占位、本土订单关联及我仓上车流程。
-- [财务管理](财务管理/README.md)：应收、应付、费用池、账单、收款、成本、核销、凭证以及国内外业务费用来源。
-- [自营业务](自营业务/README.md)：平台自营经营总览图表、SKU 销量、分仓产品库存、库存周转视图与数据采集；Admin 入口 `apps/admin-web/src/modules/self-operated/AGENTS.md`，业务设计、采集页面与进度图、查询性能优化及领星 API 联调依据见该业务域入口。
-- [打印标签维护](打印标签维护/README.md)：箱唛、各类托盘标、HOLD、BOL 与其他单据的现状盘点、参考样张和逐项改版记录。
+| 业务域 | 入口 |
+|---|---|
+| 客户、企业、权限与头程订单 | [订单与客户](订单与客户/README.md) |
+| 到仓、测量、箱码、计价与入库费用 | [入库测量与计费](入库测量与计费/README.md) |
+| 分柜、装柜、订舱、拖车、报关与国内出仓 | [国内货柜履约](国内货柜履约/README.md) |
+| 接柜、库存、库内服务、排车、预约与海外本土业务 | [海外仓业务](海外仓业务/README.md) |
+| 费用入池、账单、资金账户与收付款 | [财务管理](财务管理/README.md) |
+| 自营经营、库存周转与领星采集 | [自营业务](自营业务/README.md) |
+| 箱唛、托盘标、HOLD 与 BOL | [打印标签维护](打印标签维护/README.md) |
 
-## 全流程公共契约
+## 公共契约与工程专题（命中才读）
 
-### 当前流程入口（收尾变更只看这里）
+| 主题 | 当前入口 |
+|---|---|
+| 服务拓扑、环境配置、部署状态与验收项 | [部署主契约](测试环境单机部署与配置契约.md) |
+| Gateway、Auth 会话、服务身份与可靠投递 | [认证与通信主契约](统一认证与服务通信契约.md) |
+| 平台/客户、菜单与操作权限 | [层级与权限契约](平台客户层级与权限契约.md) |
+| 单据编号、订单主状态与操作 | [编号契约](业务单据编号契约.md)、[订单状态契约](统一订单主状态与操作契约.md)，按问题选一项 |
+| 本机资源、最小验证、工作区与协作执行 | [工程执行约束](AI工程执行与协作约束.md) |
+| Admin 样式、Client 样式或视觉验收 | [Admin 样式](Admin高密度界面规范.md)、[Client 样式](Client界面样式规范.md)、[前端验收](Admin-Client前端原型还原验收规则.md)，不将三份作为共同必读 |
+| 测试 Jenkins、数据库操作与中文注释 | [测试部署指南](测试环境Jenkins部署指南.md)、[数据库操作手册](../baiyue-firstleg/deploy/sql/数据库迁移操作手册.md)、[数据库注释规范](数据库注释维护规范.md)，按操作选读 |
+| 测量设备上传 | [墨家接口说明](墨家设备测量上传接口说明-V3.md) |
 
-- [头程到尾程当前维护入口](头程到尾程/README.md)：集中进入总览、六个阶段、货柜入口、报关专题，以及页面和需求参考。
+## 方案、证据与历史（按需）
 
-### 历史与参考（保留，不作为日常流程入口）
+- 独立主题设计只在该任务触发：[数据库发布方案](数据库版本迁移与Jenkins自动发布方案.md)、[生产发布方案](生产服务监控告警与无停机发布方案.md)、[生产环境方案](阿里云生产环境选型压测与上线手册.md)、[OSS 设计](阿里云OSS文件中心接入设计与评审.md)、[看板规划](首页数据看板真实化与统计策略规划.md)。方案不证明已实现或已部署。
+- 原型与截图按应用指引定向查找；样板、样式核对记录、进度表和验收报告不作为日常开发入口。
+- [历史流程](归档/头程到尾程/README.md)、[货柜历史](国内货柜履约/归档/README.md)、[财务历史](财务管理/归档/财务闭环盘点历史记录.md)仅用于追溯；旧双区域架构不覆盖当前主契约。
+- 只有独立任务协作才查[开发环境独立任务协作登记](开发环境独立任务协作登记.md)或[测试环境独立任务协作登记](独立任务协作登记.md)，不同时读取两表。
 
-- [头程到尾程历史文档](归档/头程到尾程/README.md)：全流程操作手册、旧现状全景、AI 上下文和易用性方案。
-- [国内货柜履约历史记录](国内货柜履约/归档/README.md)：开发规划、进度、门禁、验收矩阵、审计和旧确认材料。
+## 维护边界
 
-以上文件继续保留，分别用于历史现状、操作说明和方案追溯；开发规划、进度、门禁和验收记录也按业务域保留，不再与当前节点总表同步改写。
-- [跨区域认证与服务通信契约](跨区域认证与服务通信契约.md)：统一账号、国内/海外 Token、双区域 API、JWKS、Outbox/Inbox 与服务身份边界。
-- [双区域部署与 Nacos 规划](双区域部署与Nacos规划.md)：开发/测试同机共置、生产国内/海外独立控制面、Nacos、数据库及 Event Bridge 部署边界。
-
-### 通用规则与专项入口
-
-- [平台、客户层级与权限契约](平台客户层级与权限契约.md)：平台/客户两级产品语义、列表包含详情的只读权限和跨层同步要求。
-- [统一订单主状态与操作契约](统一订单主状态与操作契约.md)：统一订单状态、操作编码、内部状态映射和可信履约回传边界。
-- [Admin 界面规范（样式唯一入口）](Admin高密度界面规范.md)：按任务查列表、详情、弹窗、提示与加载、蓝白主题、密度及公共样式接入；现行样式只在本文维护。
-- [Admin/Client 前端验收规则](Admin-Client前端原型还原验收规则.md)：逐操作承载核对、指定视口、自动检查及人工截图证据，不另定 Admin 样式。
-- [蓝白样板目录与原图](界面参考/蓝白卡片式工作台风格参考.md)：需要查看参考页面或原始截图时再读，不是第二套规范。
-- 模块范围与验收记录（按任务选读，不定义通用规则）：[客户管理](Admin客户管理样式核对记录.md)、[国内仓](Admin国内仓样式核对记录.md)、[货柜管理](Admin货柜管理样式核对记录.md)、[海外仓](Admin海外仓样式核对记录.md)、[列表推广](Admin列表样式推广核对记录.md)。
-- [AI 工程执行与协作约束](AI工程执行与协作约束.md)：工作区、依赖、Git、部署、数据库、质量门禁、本机多对话重型检查限流和独立任务协作规则。
-- [数据库中文注释维护规范](数据库注释维护规范.md)：数据库注释口径、职责、迁移流程、自动门禁与实值验收要求。
-- [数据库版本迁移与 Jenkins 自动发布方案](数据库版本迁移与Jenkins自动发布方案.md)：两人团队自动迁移规划；统一工具入口、自动编号、开发/测试/生产执行分工、单服务迁移范围、漏写迁移检查、Flyway 校验、失败候选修订、发布证据保留、带数据升级演练及实施顺序。
-- [数据库迁移操作手册](../baiyue-firstleg/deploy/sql/数据库迁移操作手册.md)：开发者和发布执行人日常使用说明；包含新建、检查、生成清单、测试执行、生产晋级、失败处理和维护规则。
-- [生产服务监控告警与无停机发布方案](生产服务监控告警与无停机发布方案.md)：容器与外部可用性监控、部署期告警处理、自动恢复、发布通知及滚动/蓝绿发布演进方案。
-- [测试环境 Jenkins 部署指南](测试环境Jenkins部署指南.md)：测试环境持续部署授权、Job 参数、健康检查与失败处理。
-- [阿里云生产环境选型、压测与上线手册](阿里云生产环境选型压测与上线手册.md)：ECS/ALB、RDS MySQL、Redis、OSS、Nacos、RocketMQ、压测、高可用、监控、备份与上线清单。
-- [阿里云 OSS 文件中心接入设计与评审](阿里云OSS文件中心接入设计与评审.md)：Admin、Client、国内/海外 PDA 文件接入 OSS 的区域拓扑、存储适配、权限、一致性、实施拆分、验收门禁和方案评审。
-- [首页数据看板真实化与统计策略规划](首页数据看板真实化与统计策略规划.md)：首页指标、实时与缓存边界、统计口径和实施顺序。
-- [墨家设备测量上传接口说明 V3](墨家设备测量上传接口说明-V3.md)：测量设备经 Gateway 上传箱码、尺寸、重量和图片的接口契约。
-
-## 环境协作
-
-- [开发环境独立任务协作登记](开发环境独立任务协作登记.md)：开发环境全流程总控与长期专项的稳定任务、职责及开发数据库/部署/HTTP 授权。
-- [测试环境独立任务协作登记](独立任务协作登记.md)：测试环境独立任务的稳定身份、职责和协作边界。
-- [测试任务盘点与需求台账](测试任务盘点与需求台账.md)：历史任务快照、未闭环需求、提交线索和待核实证据，不作为当前调度依据。
-
-## 参考资料
-
-- `悦/`：产品原型、流程图、历史架构资料和调研数据，只作为需求参考，不直接定义当前范围。
-- `superpowers/`：按日期和主题保留的具体功能设计与实施记录。
-
-## 维护规则
-
-- 新文档按业务域归档，不新增以开发批次编号命名的目录、文件、标题、任务或范围标签。
-- 已完成开发阶段的流程手册、规划、进度和验收资料统一放入 `归档/`；后续流程变更只从[头程到尾程当前维护入口](头程到尾程/README.md)进入。
-- 当前交付范围始终按端到端全流程理解；业务域目录只用于检索和职责归属，不用于排除上下游流程。
-- 范围、字段或流程冲突时遵循根 AGENTS.md 的事实优先级；归档确认记录不覆盖当前正式契约。文档角色按当前入口和明确标记判断，不只按文件名判断。
-- 业务事实变化只修改其当前主文档及实际受影响的接口、权限、SQL、代码和测试；业务域 README 与索引仅在入口或职责变化时更新。历史规划、确认和验收记录冻结，不为追随当前规则批量改写。
-- 原型中出现的功能不自动成为有效实现；必须由正式契约、代码和验收证据共同确认。
+同一主题优先更新现行正文，不为每轮对话新增方案、总结、进度或交接文件。只有独立主题且现有正文无法承载时才新增，并在所属域登记角色、触发条件和替代关系。已完成的过程材料冻结归档；索引只同步路径或职责变化，不复制阶段数量、字段、状态、测试结果或完成进度。事实优先级及修改范围遵循工作区根指引。