110 lines
22 KiB
Markdown
110 lines
22 KiB
Markdown
# 开发环境独立任务协作登记
|
||
|
||
> 仅适用于保存项目“开发环境”（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 | 展示名称 | 长期职责 |
|
||
|---|---|---|---|
|
||
| `01a06c0b-0515-7c60-b329-77342b54e666` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发总控】全流程开发 | 接收当前系统端到端全流程开发任务，冻结跨端契约和串行批次，协调本表专项完成实现、定向测试和构建；代码门禁通过后按本表授权操作开发数据库、通过 Jenkins 部署开发环境并执行真实 HTTP 验收；不操作测试或生产环境。 |
|
||
|
||
长期专项：
|
||
|
||
| task_id | parent_task_id | project_id | 展示名称 | 唯一长期职责 |
|
||
|---|---|---|---|---|
|
||
| `01a05b23-bfc6-7121-a6f2-7fc14ee456a3` | `01a06c0b-0515-7c60-b329-77342b54e666` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程前端】Admin | `apps/admin-web/` 全部平台管理页面、路由、API、权限消费、测试与构建；不修改 Client、PDA、后端或 SQL。 |
|
||
| `01a05b23-c20f-7f52-8a26-543f1563f0f8` | `01a06c0b-0515-7c60-b329-77342b54e666` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程前端】Client | `apps/client-web/` 全部客户工作台页面、路由、API、权限消费、测试与构建；不修改 Admin、PDA、后端或 SQL。 |
|
||
| `01a05b78-6e28-7460-babf-3a87331f6dd4` | `01a06c0b-0515-7c60-b329-77342b54e666` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程前端】海外PDA | `apps/pda-overseas-uniapp/` 全部海外仓现场作业、真实 API、恢复、扫码、幂等、测试与构建；派送仍由 Admin/Client 承载。 |
|
||
| `01a05b23-c5ff-77c3-8f77-ceb4f4c40de2` | `01a06c0b-0515-7c60-b329-77342b54e666` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程后端】Lastleg | `baiyue-firstleg/lastleg-service/` 海外尾程、入仓、库存、换标、转运、废弃、排车、出库、派送、一件代发、异常、回访及海外业务的接口、OpenAPI、SQL、权限强制和测试。 |
|
||
| `01a05b23-c7f8-72e0-bb3c-afbbf1c7f9e7` | `01a06c0b-0515-7c60-b329-77342b54e666` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程后端】IAM权限 | `baiyue-firstleg/iam/` 及必要 common-security 的平台/客户全流程权限资源、角色初始化、授权快照、OpenAPI、SQL 和测试；不修改 Lastleg 业务或前端。 |
|
||
|
||
验收与部署任务不常驻登记。只有用户明确要求开始验收、准备部署或执行验收时，才另行决定是否创建；开发任务不得代行。
|
||
|
||
## 当前节点：一件代发客户资金账户（充值先行）
|
||
|
||
本节点先跑通客户充值申请、平台审核、平台手工充值/扣款、余额与流水；微信/支付宝商户支付回调、订单消费、冻结/解冻及自动扣费后续另批处理。付款渠道仅展示已配置的静态收款二维码，客户提交金额、付款方式和付款截图后进入待审核。
|
||
|
||
资金口径固定为 CNY：`可用授信 = 授信额度 - 已用授信 - 冻结授信`，`总可用余额 = 实际余额 + 授信额度 - 已用授信 - 冻结金额`。冻结金额包含实际资金冻结与授信冻结；扣款先使用未冻结实际资金，再使用授信，充值先归还已用授信，再增加实际余额。初始授信由 Finance 环境配置统一设置，平台可按客户调整。每次成功变动必须生成唯一业务单号和不可变流水；同一幂等键同载荷重试返回原结果，不同载荷冲突，重复审核不得重复入账。
|
||
|
||
| 工作包 | 执行任务 | 写入范围 | 交付目标 | 依赖与集成边界 |
|
||
|---|---|---|---|---|
|
||
| `WALLET-BE-FINANCE` | 【开发总控】全流程开发 | `baiyue-firstleg/finance/`、Finance OpenAPI、模块 SQL 与统一增量 SQL、必要 Finance/File 内部客户端 | 新增客户资金账户、充值申请、授信额度、资金冻结和流水主账；提供客户账户/流水/充值申请接口及平台账户列表/详情、待审充值、审核、手工充值/扣款/授信接口，并提供业务模块使用的冻结、结算和释放内部接口；实现客户隔离、金额校验、权限、服务令牌、幂等、乐观并发与测试 | Finance 拥有余额、授信、冻结和流水；扣款先使用实际资金再使用授信，充值先归还已用授信；付款截图经 Finance 调用 File 内部 `FINANCE_VOUCHER` 保存；不接第三方支付回调，具体一件代发业务调用后续接线 |
|
||
| `WALLET-FE-CLIENT` | 【开发全流程前端】Client | `apps/client-web/src/modules/finance/` 及该模块路由、导航和测试 | 新增客户资金账户页，显示实际/冻结/可用余额和流水；按原型完成金额选择、微信/支付宝静态二维码、付款截图上传、提交待审核及状态反馈 | 客户范围只取登录态；只调用 `/api/client/finance/v1/**`，无二维码配置时明确不可提交，不模拟支付成功 |
|
||
| `WALLET-FE-ADMIN` | 【开发全流程前端】Admin | `apps/admin-web/src/modules/finance/` 及对应测试 | 将客户账户页收敛为三余额账户；详情中待审核客户充值置顶并提供审核，保留流水；列表/详情提供手工充值和手工扣款，操作列固定首列 | 只消费 Finance 正式 API；审核、充值、扣款分别受写权限控制；不在前端计算或兜底余额 |
|
||
| `WALLET-BE-IAM` | 【开发全流程后端】IAM权限 | `baiyue-firstleg/iam/` 及必要权限初始化 SQL、OpenAPI 和测试 | 新增并初始化客户账户查看/充值申请和平台充值审核/账户调账权限，保持列表只读与写操作分离 | 企业负责人默认获得客户账户查看和充值申请权限；平台财务角色按现有初始化规则获得审核与调账权限，不修改 Finance 业务 |
|
||
|
||
完成门禁：Finance、IAM 定向测试通过，Admin/Client 定向测试、类型检查和生产构建通过，跨端 DTO 与权限码一致；专项不提交、不推送、不部署、不操作数据库或真实 HTTP，由开发总控统一集成后再进入开发环境部署与验收。
|
||
|
||
### 资金账户节点结果（2026-09-05）
|
||
|
||
- Backend 已在 `dev` 完成 Finance 主账、充值申请、不可变流水、File 凭证代理、客户隔离、幂等、乐观并发及 IAM 四项独立权限，最终提交为 `37183ac2`；Finance 全量 162 项、最终运行时兜底行为 4 项及 IAM 定向 18 项测试通过。开发统一增量 SQL 执行结果为 `PASS`，确认 3 张资金表、45 个字段、4 项权限资源和 4 项默认授权，未重建或删除数据库。
|
||
- Client 提交 `e814902`、`719a642`，完成三余额、流水、充值申请和金额/渠道/截图提交弹窗；全量 267 项测试及生产构建通过。Admin 提交 `68fca1b`、`fb4cab6`，完成客户账户列表/详情、待审置顶、凭证预览、审核与手工充值/扣款，并消除详情初始化重复请求；全量 1691 项测试、最终页面定向 17 项及生产构建通过。
|
||
- 开发部署最终结果：Backend Jenkins `#171`（下游 Finance `#26`）、Admin `#45`、Client `#45` 均为 `SUCCESS`；Admin、Client 与国内 API 健康检查均返回 HTTP 200。开发环境以 `DEPLOY_ENV=development` 启用明确标注“开发示例、不可付款”的静态二维码，其他部署环境保持默认关闭。
|
||
- 真实 HTTP 验收使用客户登录态提交 PNG 付款截图：创建返回 `PENDING`，相同幂等键重放返回原申请，不同载荷返回 `FIN-IDEMPOTENCY-CONFLICT`；凭证下载为 HTTP 200 `image/png`；审核后余额从 ¥15 增至 ¥115，重复审核返回 `FIN-WALLET-409`；另一申请驳回后余额不变。手工充值 ¥25、扣款 ¥10 成功并生成流水，超额扣款返回 `FIN-WALLET-INSUFFICIENT`；最终 `实际余额 ¥115 = 冻结金额 ¥0 + 可用余额 ¥115`。
|
||
- 已按 `1920×1080`、浏览器缩放 `100%` 验收 Client 资金账户、流水、充值记录与充值弹窗，以及 Admin 客户筛选、账户详情、充值记录、凭证和手工充值/扣款表单。Client 资金页的账户、流水、申请、渠道接口各请求 1 次；Admin 去重修复后详情流水与充值申请接口各请求 1 次，未发现遮挡或横向溢出。
|
||
- 授信与冻结结算扩展已完成：Backend 提交 `ba4407eb`、权限断言修复 `ede63fac`，Admin 提交 `92b24cc`，Client 提交 `46a91fb`，财务契约提交 `08a80e7`。Finance 提供服务令牌保护的账户查询、冻结、结算和释放内部接口；初始化授信配置为 `FINANCE_WALLET_DEFAULT_CREDIT_LIMIT`，默认 `0.00`。
|
||
- 最新开发部署为 Backend Jenkins `#173`（下游 Finance `#29`）、Admin `#46`、Client `#46`，均为 `SUCCESS`。国内统一增量从首行完整执行并取得 `migration_status=PASS`；真实 HTTP 授信回归 `13/13` 通过，验证授信调整、现金优先扣款、额度下限门禁、充值优先归还授信及最终余额恢复。验收后账户为实际余额 `¥115.00`、冻结金额 `¥0.00`、授信额度/已用授信/冻结授信均为 `¥0.00`、总可用余额 `¥115.00`。
|
||
|
||
## 当前 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 广播扫码、相机与弱网恢复仍保留为设备验收项。
|