baiyue-firstleg/firstleg/AGENTS.md

Firstleg Service 模块指引

职责边界

• 负责订单提交后的国内头程履约任务、操作分配和分配历史。
• 订单主单、商户草稿和交易状态属于 order/；不要把订单模型复制进本服务。

快速索引

功能	入口
应用入口	src/main/java/com/baiyue/firstleg/BaiyueFirstlegApplication.java
平台履约任务查询与分配 API	controller/PlatformFulfillmentAssignmentController.java（/api/platform/v1/first-leg/tasks）
任务列表、详情、按订单查询、分配历史	FulfillmentTaskService.java、FulfillmentTaskRepository.java；只读权限码见控制器 @PreAuthorize
服务状态	controller/FirstlegHealthController.java
查询与分配请求	dto/FulfillmentTaskQuery.java、dto/AssignRequest.java
履约与分配编排	service/FulfillmentTaskService.java
任务与历史持久化	entity/、mapper/、repository/FulfillmentTaskRepository.java
表结构与查询索引迁移	src/main/resources/db/firstleg.sql、src/main/resources/db/phase1-firstleg-task-list-index.sql
OpenAPI 与测试	src/main/resources/openapi/firstleg-v1.yaml、service/FulfillmentTaskServiceTest.java、controller/FulfillmentTaskControllerContractTest.java（测试路径均从 src/test/java/com/baiyue/firstleg/ 起算）
本地/Nacos 配置	src/main/resources/application.yml、../config/nacos/{local,cn}/firstleg-service.yml

修改与验证

• 任务状态与订单状态保持领域分离；需要联动时使用稳定 DTO 或事件，不共享 Order Entity 或数据库。
• 分配操作要保留历史、操作者、时间和幂等语义；平台端接口必须执行权限校验。
• 所有查询必须带目标租户并在仓储层过滤；列表和分配历史使用统一分页响应，详情不存在使用 HTTP 200 + body code A0404。
• 普通任务不存在、状态冲突和参数错误均遵循 HTTP 200 + body code，平台 Security 拒绝仍保留真实 403。
• 新建库由 firstleg.sql 创建查询索引；既有库必须再执行可重复部署的 phase1-firstleg-task-list-index.sql，不能只依赖 CREATE TABLE IF NOT EXISTS。
• 修改任务查询、状态或分配逻辑时同步扩展 Service 测试和 Controller 契约测试，不以模块构建代替行为验证。
• 从父目录运行 mvn -pl firstleg -am test。
• 数据库执行顺序：新库执行 firstleg.sql；已有库在此后执行 phase1-firstleg-task-list-index.sql，为任务列表、按订单查询和分配历史分页补齐索引。