docs/开发环境独立任务协作登记.md

# 开发环境独立任务协作登记

> 仅适用于保存项目“开发环境”（projectId `6f874ec3-d3b2-49bd-8625-327f4d685f98`）和工作目录 `C:\Users\BY-OY\Desktop\code\chongchong-global-dev`。测试环境任务不得复用本表任务，本表任务也不得访问测试目录。

## 环境隔离门禁

- 开发总控只向本表 task_id 下发当前系统全流程开发工作；不得向 `C:\Users\BY-OY\Desktop\code\chongchong-global` 的测试环境任务下发，即使提示中另写开发目录也不例外。
- 每个任务必须同时满足 projectId、cwd 和登记环境一致；任一项不一致立即停止，不读取、不修改、不运行命令，也不得自行切换目录补救。
- 开发专项日常只执行源码实现、定向测试、类型检查和构建；开发数据库与开发部署只能由开发总控在代码门禁通过后按精确服务、数据库和变更清单单独下发。测试环境、测试数据库、生产环境和 Jenkins 仍禁止。
- 开发与测试目录之间不得复制未提交文件、生成补丁、自动合并或 cherry-pick；需要移交时由用户明确授权具体方向、提交和范围。
- 同一批次每个应用或服务只允许一个生产代码写入者；共享路由、导航、权限初始化、OpenAPI 和 SQL 的写入权由开发总控在下发时明确。
- 每次提交前必须先在目标仓库执行 `git fetch origin test dev`，保持当前分支为 `dev`，把最新 `origin/test` 合并到 `dev` 后再提交本轮改动；不得通过切换分支、rebase、force push 或跳过冲突来规避同步。发生冲突时由该仓库当前唯一 Git 集成者处理，必须同时保留 test 最新有效改动与开发总控已冻结的 dev 契约，并在提交前重跑直接受影响门禁。

## 开发环境操作授权

- 用户已在当前持续目标中授权本总控部署开发环境、操作开发数据库、使用 Jenkins 部署开发环境，并对开发环境执行真实 HTTP 调用。授权不扩展到测试或生产环境。
- 数据库操作前必须确认开发库、精确表、业务主键或 SQL 文件和预计影响行；优先使用事务并保留执行结果。仓库已审核的开发增量 SQL、测试造数和职责范围内的数据修正可执行。
- `DROP`、`TRUNCATE`、整库重置、清空表、无明确主键范围的批量删除及其他不可恢复操作不在授权内，仍需用户当轮单独确认。
- 开发部署必须在受影响测试、类型检查或构建通过后进行，并记录精确部署单元、使用的提交或工作区状态、配置来源和部署结果。若唯一部署方式依赖 Jenkins，执行前重新取得用户对 Jenkins 的明确授权。
- 开发环境真实 HTTP 在部署和数据库变更完成后执行，可包含当前全流程职责范围内的读写验收；只使用开发身份和开发数据，记录接口路径、HTTP 状态、业务码、`requestId`/`traceId` 与结果，不输出或持久化 Token、密码和敏感载荷。破坏性批量请求仍需单独确认。

## 登记表

总控：

| task_id | project_id | 展示名称 | 长期职责 |
|---|---|---|---|
| `01a05b10-a5fc-7d51-8203-c671f3a823ad` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发总控】全流程开发 | 接收当前系统端到端全流程开发任务，冻结跨端契约和串行批次，协调本表专项完成实现、定向测试和构建；代码门禁通过后按本表授权操作开发数据库、通过 Jenkins 部署开发环境并执行真实 HTTP 验收；不操作测试或生产环境。 |

长期专项：

| task_id | parent_task_id | project_id | 展示名称 | 唯一长期职责 |
|---|---|---|---|---|
| `01a05b23-bfc6-7121-a6f2-7fc14ee456a3` | `01a05b10-a5fc-7d51-8203-c671f3a823ad` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程前端】Admin | `apps/admin-web/` 全部平台管理页面、路由、API、权限消费、测试与构建；不修改 Client、PDA、后端或 SQL。 |
| `01a05b23-c20f-7f52-8a26-543f1563f0f8` | `01a05b10-a5fc-7d51-8203-c671f3a823ad` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程前端】Client | `apps/client-web/` 全部客户工作台页面、路由、API、权限消费、测试与构建；不修改 Admin、PDA、后端或 SQL。 |
| `01a05b78-6e28-7460-babf-3a87331f6dd4` | `01a05b10-a5fc-7d51-8203-c671f3a823ad` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程前端】海外PDA | `apps/pda-overseas-uniapp/` 全部海外仓现场作业、真实 API、恢复、扫码、幂等、测试与构建；派送仍由 Admin/Client 承载。 |
| `01a05b23-c5ff-77c3-8f77-ceb4f4c40de2` | `01a05b10-a5fc-7d51-8203-c671f3a823ad` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程后端】Lastleg | `baiyue-firstleg/lastleg-service/` 海外尾程、入仓、库存、换标、转运、废弃、排车、出库、派送、一件代发、异常、回访及海外业务的接口、OpenAPI、SQL、权限强制和测试。 |
| `01a05b23-c7f8-72e0-bb3c-afbbf1c7f9e7` | `01a05b10-a5fc-7d51-8203-c671f3a823ad` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程后端】IAM权限 | `baiyue-firstleg/iam/` 及必要 common-security 的平台/客户全流程权限资源、角色初始化、授权快照、OpenAPI、SQL 和测试；不修改 Lastleg 业务或前端。 |

验收与部署任务不常驻登记。只有用户明确要求开始验收、准备部署或执行验收时，才另行决定是否创建；开发任务不得代行。

## 当前 P0 全流程补齐批次

本批只处理原型盘点确认的 P0，不混入 Admin 经营分析、销售管理、官网、小程序、独立 APP 或全量视觉验收。现有文档业务域改名属于总控在途改动，各专项必须保留，不得暂存、提交、覆盖或回滚。

| 工作包 | 执行任务 | 写入范围 | 交付目标 | 依赖与集成边界 |
|---|---|---|---|---|
| `P0-BE-LASTLEG` | 【开发全流程后端】Lastleg | `baiyue-firstleg/lastleg-service/` | 补齐客户海外采购、本土卡、本土散板、海外入库订单所需客户 API；核对并补齐 PDA 盘点、移库、换标、库存/库位/托盘查询专用 API、OpenAPI 与测试 | 先冻结 DTO、权限码和状态机并通知 Client、海外 PDA、IAM；不修改 `iam/`、统一 SQL或前端 |
| `P0-BE-IAM` | 【开发全流程后端】IAM权限 | `baiyue-firstleg/iam/` 及必要 `common-security/` | 补齐并核对客户海外业务、海外入库查询和海外 PDA 现场作业的权限资源、角色初始化、OpenAPI 与模块 SQL | 消费 Lastleg 冻结的权限码；不修改 Lastleg、统一 SQL或前端 |
| `P0-FE-CLIENT` | 【开发全流程前端】Client | `apps/client-web/` | 将海外采购、美国本土卡、美本土散板和海外入库订单从占位收敛为真实页面；修正首页快捷入口；覆盖权限、加载、空态、错误态、幂等与测试 | 只消费客户正式 API，不调用平台/内部接口，不模拟成功；“我的订单”统一查询不在本批 |
| `P0-FE-OVERSEAS-PDA` | 【开发全流程前端】海外PDA | `apps/pda-overseas-uniapp/` | 接通库存盘点、商品移库、换标收货/执行/复核、库存/库位/托盘查询共 8 项现场能力，完成扫码、恢复、并发冲突、幂等、错误态和构建测试 | 只调用 `/api/pda/**` 正式接口；不得通过 `available: true` 掩盖未接通能力，不改后端或其他前端 |

完成门禁：四包定向测试与构建通过，跨端契约一致，所有 P0 页面或 PDA 入口均不再是 `prototype`、`available: false` 或模拟成功。专项本批不提交、不推送、不部署、不执行数据库和真实 HTTP；总控汇总差异并处理现有文档改动后，再按各仓库最新测试分支同步门禁统一集成。

### P0 批次结果（2026-09-04）

| 工作包 | 状态 | 结果与门禁 |
|---|---|---|
| `P0-BE-LASTLEG` | 已完成 | 客户海外采购、本土卡、本土散板、海外入库列表/详情接口及 PDA 作业 OpenAPI 已补齐；Lastleg 548 项测试通过，2 项跳过 |
| `P0-BE-IAM` | 已完成 | 4 项客户权限已冻结并只授予企业负责人，PDA 继续使用统一 `lastleg:pda:operate`；IAM 全量 284 项测试通过 |
| `P0-FE-CLIENT` | 已完成（总控接管） | 原 Client 任务连续两次网络流中断；总控在同一工作区完成三类跨境订单列表/详情/新增、海外入库列表/详情和首页正确路由；Client 263 项测试、类型检查、生产构建通过 |
| `P0-FE-OVERSEAS-PDA` | 已完成 | 盘点、移库、换标收货/执行/复核、库存/库位/托盘查询 8 项入口已接真实 `/api/pda/**`；64 项测试及 H5/App 资源构建通过 |
| 总控集成 | 已完成 | IAM 模块 SQL 与统一增量 SQL 内容一致；开发/测试登记隔离、页面索引、权限、Gateway、PDA 能力等 832 项索引合同通过；各 Git 仓库 `git diff --check` 通过 |

总控已在每次提交前重新获取并合并对应测试分支，完成开发分支提交与推送：Backend `54cb9cea`、Auth 修复 `81470359`，Client `6998f81`，Admin `7d29f3d`，国内 PDA `881c273`，海外 PDA `f960b9f`。五个工作区提交后均保持在 `dev` 分支且无未提交业务改动。

开发部署已完成：Admin Jenkins `#41`、Client `#42`、IAM `#33`、Lastleg `#65`、Auth `#24` 均成功，其中后端任务显式使用 `ENVIRONMENT=development` 与 `DEPLOY=true`；未触发测试或生产任务。开发数据库只在 `8.163.49.32:3306` 执行统一增量，环境标记为 `dev`，迁移合同结果为 `PASS`，4 项权限及负责人授权、唯一索引和重复绑定清理结果均已核对；未重建或删除数据库。

开发环境真实 HTTP 已通过：登录后签发国内及海外 Token，IAM 返回 4 项目标权限；海外采购、本土卡、本土散板和海外入仓计划 4 个客户接口均返回 HTTP 200、业务码 200。Client 已按 `1920×1080`、浏览器缩放 `100%` 验收业务总览、三个出海下单列表、散板新增表单和海外入仓列表，未发现遮挡、溢出、错误日志或“暂无权限”；海外 PDA H5/App 构建已通过，真机广播扫码、拍照等硬件能力仍需设备证据。

### 全流程收口检查点（2026-09-04）

- Backend 已在提交前重新获取并合并 `origin/test`，开发分支提交为 `e477f739`、`b8a649e7`；开发 Jenkins Backend `#165` 及下游 Firstleg `#72` 成功。
- 最新开发环境真实 HTTP 全流程报告 `baiyue-firstleg/reports/admin-test-env-acceptance-20260904080448.json` 结果为 `PASS`：`8166/8166` 断言通过、`112` 次模块运行、`92` 个唯一模块、`4981` 个唯一请求，`failed=0`、`skippedModules=0`、`deploymentBlockers=0`。17 项覆盖说明均为非阻断项，包含设备能力、外部船司依赖和无公开接口可稳定构造的中间状态。
- Admin 已合并最新 `origin/release/test`，冲突按当前全流程契约收敛；补齐智能装柜箱数输入提示，`233/233` 个测试文件、`1670/1670` 条测试及生产构建通过，本地提交 `871d0a5`、`bc6629d`。Client 已合并最新 `origin/release/test`，全量测试及生产构建通过，本地提交 `dbd3c61`。国内 PDA `118/118` 条测试通过。海外 PDA `65/65` 条测试及 H5 构建通过，本地提交 `4f314fa`。
- 海外 PDA 已按 `390×844` 通过 H5 登录、工作台、拆柜收货、托盘、盘点、移库、换标、库存/库位/托盘查询、排车、出库、历史和个人中心的页面路由与横向溢出检查；托盘管理页不再显示“PDA 广播扫码与 H5 人工输入均可使用”。Android 广播扫码、相机与弱网恢复仍只计入设备验收，不以 H5 结果替代。
- Git 域名入口的写入凭据失效后，使用本机已登记的同一 Git 服务入口 `8.163.30.128:10082` 完成推送，未修改仓库远程配置：Admin `bc6629d`、Client `dbd3c61`、海外 PDA `4f314fa` 已进入远端 `dev`。本检查点无代码、部署或验收阻断。
- 最新前端提交已部署到开发环境：Admin Jenkins `#42`、Client Jenkins `#43` 均为 `SUCCESS`，`http://dev-admin.buggoglobal.com/healthz` 与 `http://dev-app.buggoglobal.com/healthz` 均返回 HTTP 200。Backend、Admin、Client、国内 PDA、海外 PDA 五个仓库的本地 `HEAD` 与远端 `origin/dev` 一致且工作区干净；AGENTS 索引合同 `872/872` 通过。
- 收口前再次同步 Backend `origin/test`，保留新财务链、隔离手机号可用性检查和 Firstleg 船期调度更新，并修正跨区财务合同的客户范围断言；提交 `07bcf316`、`61b7b3fb` 已推送。Node 合同 `14/14`、Firstleg 调度测试 `7/7`、AGENTS 索引合同 `873/873` 通过；开发 Backend Jenkins `#166` 与下游 Firstleg `#73` 均为 `SUCCESS`，国内及海外 Gateway `/actuator/health` 均为 HTTP 200、`UP`。
- 文档仓库已合并最新 `origin/test`，测试登记保持清空，开发登记保持独立有效；79 个文件按“订单与客户、入库测量与计费、国内货柜履约、海外仓业务、财务管理”业务域重组，非原型 Markdown/YAML/JSON 中历史期数称谓检索为 0，提交 `703f869`、`40492cd` 已推送。
- Backend 再次于提交前获取 `origin/test`（无新增提交），修复二进制只读下载瞬时失败重试、Finance 结算与直接已付执行顺序、合并后丢失的一件代发整托分配/整托拣货验收，以及当前 SQL、编号生成器、OpenAPI 与同步依赖基线；提交 `991bab9c` 已推送到远端 `dev`。根级 Node 合同 `122/122`、模块合同 `484/484`、Mapper 合同 `261/261`、AGENTS 索引合同 `873/873` 均通过。
- 最新开发环境真实 HTTP 全流程报告 `baiyue-firstleg/reports/admin-test-env-acceptance-20260904091729.json` 结果为 `PASS`：`8082/8082` 断言通过、`112` 次模块运行、`92` 个唯一模块、`4937` 个唯一请求，`failed=0`、`skippedModules=0`、`deploymentBlockers=0`。17 项覆盖说明均为非阻断项：设备能力 1 项、非版本化文档契约 1 项、外部第三方 9 项、无法通过公开接口稳定构造的 fixture 6 项。
- 内置浏览器复验覆盖 Client 海外贴标、仓储转运、货物废弃、退货换标的列表、详情或新建表单，以及 Admin 海外尾程、入库、排车、出库、派送、换标、托盘、库存、进销存、异常和客户回访列表；页面真实 API 加载成功且无控制台错误。复验发现并修复进销存页面暴露内部 DTO 说明、英文库存变动代码和操作人内部占位的问题，Admin 提交 `39ade43` 已在提交前合并最新 `origin/release/test` 并推送；`233/233` 个测试文件、`1685/1685` 条测试、类型检查和生产构建通过，开发 Jenkins `admin-web-dev #43` 为 `SUCCESS`，`/healthz` 返回 HTTP 200，部署后页面显示中文业务类型且内部文案不再出现。
- 海外 PDA H5 再次使用开发网关验证登录、工作台、拆柜收货、托盘、盘点、移库、换标、库存/库位/托盘查询、排车、出库、历史、个人中心及“退出确认→退出→重新登录”；全部正式入口可加载，无权限或请求错误，托盘管理页未回归“PDA 广播扫码与 H5 人工输入均可使用”。本次浏览器工具固定视口不替代已登记的 `390×844` 截图证据；Android 广播扫码、相机与弱网恢复仍保留为设备验收项。