You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
73 lines
5.6 KiB
73 lines
5.6 KiB
11 hours ago
|
# crm-project（A5 项目管理）API-SUMMARY
|
||
|
|
|
||
|
|
> 对称 `.scratch/customer-module/API-SUMMARY.md` 形态；随票增量登记，票 18 做全量核对。
|
||
|
|
> 契约权威：`.scratch/crm-project-wayfinding/deliverable-spec.md`；实现：`crm-project`（`com.crm.project`）。
|
||
|
|
|
||
|
|
## 0. 通用约定
|
||
|
|
|
||
|
|
- 鉴权 Bearer（`Authorization: Bearer <token>`），响应信封 `Result<T>` = `{code, success, message, data}`，`code=0` 成功。
|
||
|
|
- 分页：入参 `BaseParam`（`current`/`size`/`keyword`/`orderBy`/`asc`）→ 出参 `PageResult<T>` = `{content,total,size,current,pages,empty}`。
|
||
|
|
- 雪花 id Long 序列化为字符串收发。
|
||
|
|
- 风格遵 ADR-0017：POST 写（表单绑定，禁 `@RequestBody`）、GET 读（query 参数）；禁 `@PathVariable`/`@PutMapping`/`@DeleteMapping`。Entity 不出 Controller，`deleted` 不出参。
|
||
|
|
- 深 tag 遵 ADR-0024：一级 = `A5 项目管理`；页面目录 = 项目管理（看板视图）/项目管理（分屏视图）/项目管理（列表视图）/我的项目/项目详情/项目建档（详情页对应原型 a5-1-2-1 页签详情，v29 树一行索引未展开，拍板记录于票仓 README Decisions）。
|
||
|
|
- 数据权限：`@DataScope(module="project", ownerColumn="owner_user_id", deptColumn="owner_dept_id")`（module 已由 crm-auth DataInitializer 内置 seed）。
|
||
|
|
- 错误码段：68xxx（`ProjectConstants`）。
|
||
|
|
|
||
|
|
## 1. 错误码总表（68xxx，`ProjectConstants`）
|
||
|
|
|
||
|
|
| 码 | 常量 | 含义 |
|
||
|
|
| --- | --- | --- |
|
||
|
|
| 68001 | CODE_PROJECT_INVALID | 项目入参非法（参数缺失/客户目录校验不过/冲突拦截） |
|
||
|
|
| 68002 | CODE_PROJECT_NOT_EXIST | 项目不存在或已被删除 |
|
||
|
|
| 68003 | CODE_PROJECT_LOCKED | 当前状态/终态锁不允许此操作（结项/已关闭/赢单锁死） |
|
||
|
|
| 68004 | CODE_STAGE_TRANSITION_INVALID | 非法阶段迁移（越级/方向错误/非 3→5 连跳） |
|
||
|
|
| 68005 | CODE_ROLLBACK_FORBIDDEN | 阶段回退权限不足（仅管理员+销售总监） |
|
||
|
|
| 68006 | CODE_ROLLBACK_TARGET_INVALID | 回退目标非法（不在已过节点/低于 stage1 下限） |
|
||
|
|
| 68007 | CODE_SCHEME_CARD_MISMATCH | 方案卡校验失败（不存在/归属或客户与项目不符） |
|
||
|
|
| 68008 | CODE_CONFLICT_RELEASE_INVALID | 冲突解除（报备审核回填）条件不满足（非 stage0 等） |
|
||
|
|
| 68009 | CODE_BID_RESULT_INVALID | 赢/输标记条件不满足（非 stage5/已标记） |
|
||
|
|
| 66015 | （crm-opportunity）CODE_SCHEME_CARD_PROJECT_PORT_UNWIRED | PROJECT 归属方案卡校验桩未接线——A5 部署后由真实现覆盖，正常不可再见 |
|
||
|
|
| 66007/66008/66009/66010 | （crm-opportunity）方案卡族 | A5 建档经 `OpportunitySchemeCardService` 读卡时可能透出（66008 已在 create 翻译为 68007） |
|
||
|
|
|
||
|
|
## 2. 接口清单（按页面/子域，随票增量）
|
||
|
|
|
||
|
|
### 2.1 项目建档（票 02）
|
||
|
|
|
||
|
|
| 方法 | 路径 | 说明 | 入参 |
|
||
|
|
| --- | --- | --- | --- |
|
||
|
|
| POST | `/api/project/create` | 独立建项目（本期唯一可达建项目入口） | `projectName`* / `customerId`* / `schemeCardId`* / `sourceOppId` / `projectAmount` / `regionCode` / `brand` |
|
||
|
|
|
||
|
|
行为要点：客户必填目录选（`CustomerCatalogPort.requireLive`，归档/缺失拒绝）；方案卡必填且卡客户=项目客户；PROJECT 归属卡不得重复绑定他项目；冲突检测留桩恒无冲突；落库 `stage=0/status=1/filing_status=1/bid_result=0`；owner 三列取操作人快照（操作人=初始负责人）；写两条动态（CREATE + FILING_SUBMIT）。出参 `data` = 项目 id。
|
||
|
|
|
||
|
|
### 2.2 项目详情（票 02）
|
||
|
|
|
||
|
|
| 方法 | 路径 | 说明 | 入参 |
|
||
|
|
| --- | --- | --- | --- |
|
||
|
|
| GET | `/api/project/detail` | 详情主档 + 头部 | `id`* |
|
||
|
|
|
||
|
|
出参 `ProjectDTO` 全量（阶段专属扩展列组仅 detail 回显）；阶段名回显 = 字典名（`project_stage` 分组）→ 枚举名兜底，别名优先接入点归票 13；客户名经 `CustomerCatalogPort` 回显（客户已归档时留空不阻断）。
|
||
|
|
|
||
|
|
（后续票：2.3 列表、2.4 看板、2.5 状态机动作、2.6 冲突解除、2.7 详情 Tab、2.8 移交同步……随票追加于此）
|
||
|
|
|
||
|
|
## 3. 状态 / 值域附录
|
||
|
|
|
||
|
|
- `project_stage`：0 冲突处理 / 1 方案设计 / 2 商务报价 / 3 招投标准备 / 4 商务跟进 / 5 赢单输单 / 6 结项（仅输单进）
|
||
|
|
- `project_status`：1 进行中 / 2 已关闭 / 3 已结项（赢单本期不落 3）
|
||
|
|
- `filing_status`：0 未报备（本期不可达·预留）/ 1 报备审核中（建项即此态）/ 2 报备通过 / 3 报备驳回
|
||
|
|
- `bid_result`：0 未定 / 1 赢单（stage5 闭环锁死）/ 2 输单（stage6 终态）
|
||
|
|
- `close_type`：MANUAL / CUSTOMER_CANCEL / LOST_CONTACT / OTHER
|
||
|
|
- 任务状态语义码：PENDING / DOING / DONE
|
||
|
|
- `scope`：manage（项目管理，@DataScope）/ mine（我的项目）
|
||
|
|
|
||
|
|
## 4. 联调速查
|
||
|
|
|
||
|
|
- 建档前置数据：一个有效客户（crm-customer）+ 该客户名下一张商机归属方案卡（crm-opportunity 方案卡保存接口，`A3 商机管理` 分区）。
|
||
|
|
- demo 单页见票仓 14/15 产出；`.bru` 位于 `E:\code\crm-api-docs\A5 项目管理\`（agent 不提交 git，留人工审查）。
|
||
|
|
|
||
|
|
## 5. 已知缺口与范围外（如实记录，避免联调踩坑）
|
||
|
|
|
||
|
|
- 冲突检测留桩恒「无冲突」（spec §8 选甲）：不会出现冲突拦截分支；`ConflictPullDTO` 维度配置源缺失为 spin-out 前置。
|
||
|
|
- PROJECT 归属方案卡的独立 HTTP 创建端点本期无（服务级通道 + A5 建档校验已通；自动转项目 spin-out 后接入）。
|
||
|
|
- 阶段名别名列头（stageAliasJson 优先）票 13 接入前，阶段名一律走字典名/枚举名兜底。
|
||
|
|
- 输单复盘字段（竞品/输单原因等）为后续字段（票 07 标注），本期 stage6 仅状态落位。
|