docs/README.md

虫虫出海文档索引

项目交付文档按阶段归档，跨阶段原型、调研和过程设计保留在原专题目录。

阶段文档

• 一期文档：一期范围、开发进度和头程订单最小闭环。
• 二期文档：预约取货、到仓收货、实测差异和指定库位闭环。
• 三期文档：智能排柜、订舱、拖车、PDA 拣货、报关协同和国内出仓闭环。
• 四期文档：国内出仓后的船节点定时查询、海外接柜、合作仓卸货入库、库存与库内操作，以及海外采购、本土卡车和本土散板；不包含海外仓出库业务。
• 独立任务协作登记：只维护总控与用户可见独立任务的稳定 task_id、父子关系和职责范围，不记录动态进度或归档状态。

跨阶段参考

• 跨区域认证与服务通信契约：统一账号、国内/海外 Token、双区域 API、JWKS、Outbox/Inbox 与服务身份边界。
• 双区域部署与 Nacos 规划：开发/测试同机共置、生产国内/海外独立控制面、Nacos、数据库及 Event Bridge 部署边界。
• 平台、客户层级与权限契约：平台/客户两级产品语义、列表包含详情的只读权限和跨层同步要求。
• AI 工程执行与协作约束：临时目录、依赖复用、当前开发阶段、部署数据库授权、质量门禁和独立任务协作规则。
• 财务管理闭环盘点与范围建议：基于当前入库计费、财务原型和现有代码盘点财务闭环、缺口及建议的首期应收边界。
• 墨家设备测量上传接口说明 V3：墨家测量设备经 Gateway 上传箱码、尺寸、重量和图片的开放接口契约。
• 统一订单主状态与操作契约：统一订单七状态、操作编码、内部状态兼容映射，以及与三期一致的 LOADED 硬门禁和 DELIVERED 可信回传边界。
• 首页数据看板真实化与统计策略规划：记录首页看板当前数据能力、实时/缓存边界、指标口径和后续实施顺序。
• Admin/Client 前端原型还原验收规则：已确认原型页面的逐操作承载方式、视觉还原、响应式检查和验收证据要求。
• 数据库中文注释维护规范：数据库注释口径、职责、迁移流程、自动门禁与实值验收要求。
• 测试环境 Jenkins 部署指南：测试环境持续部署授权、Job 参数、执行边界、健康检查与失败处理。
• 悦/：产品原型、流程图、历史架构资料和调研数据，仅作为需求参考，不直接等同于已确认范围。
• superpowers/：具体功能的设计与实施记录，按日期和主题维护。

维护规则

• 只影响单个阶段的范围、进度和验收文档放入对应阶段目录。
• 公共架构、跨阶段契约和长期产品资料保留在 docs/ 根目录或独立专题目录。
• 阶段范围变化时同步更新该阶段的规划、进度表及受影响的公共契约。
• 原型中出现的功能不自动进入开发范围，必须在阶段规划中明确优先级、依赖和验收标准。