hiwork-core 0.0.18 → 0.0.21

package/lib/types/pms-client.d.ts

@@ -0,0 +1,293 @@
+/**
+ * PMS 服务基址 —— **全仓唯一一处**写死这个域名的地方。
+ *
+ * 为什么固定而不是配置项：PMS 是组织自建且**只有这一个生产部署**的内部系统（不像 ai-router 那样
+ * 需要自建/多环境），让每台终端在设置里填一个 URL 只会多一个能填错、又没人能集中改的地方；真要
+ * 换部署，改这一个常量、发一版即可。反过来说，**任何别处都不许再写这个域名**（包括文档示例之外
+ * 的代码、错误消息、日志），否则「唯一的基址」立刻变成两处能漂移的真相。
+ */
+export declare const PMS_BASE_URL = "https://pms.hivery.cn";
+/**
+ * 单次请求超时：10 秒（spec §7 的冻结决策）。
+ * Host 是唯一会替界面等 PMS 的地方，超时不给足会让右栏面板一直转圈；给太多则用户以为卡死。
+ */
+export declare const PMS_REQUEST_TIMEOUT_MS = 10000;
+/**
+ * access token 的**兜底**有效期：10 小时（= PMS `jwt.expiration=36000000`）。
+ * 只在响应缺 `expiresIn` 时用；正常路径一律按服务端给的 `expiresIn` 算过期时刻。
+ */
+export declare const PMS_ACCESS_TOKEN_TTL_MS: number;
+/** 本客户端只有三个错误码：凭据失效 / 上游不可用 / 权限不足。其余（输入不合法等）由 Bridge 层判。 */
+export type PmsErrorCode = 'UNAUTHORIZED' | 'UPSTREAM_UNAVAILABLE' | 'FORBIDDEN';
+/** PMS 调用失败。`message` 一律是稳定文案，可直接展示给用户。 */
+export declare class PmsError extends Error {
+    readonly code: PmsErrorCode;
+    readonly status?: number | undefined;
+    constructor(code: PmsErrorCode, message: string, status?: number | undefined);
+}
+/** 未登录 / 凭据失效的文案（与 Bridge 侧 `UNAUTHORIZED` 同口径：引导重新输入，不静默失败）。 */
+export declare const PMS_UNAUTHORIZED_MESSAGE = "\u767B\u5F55\u5DF2\u8FC7\u671F\uFF0C\u8BF7\u91CD\u65B0\u8F93\u5165 PMS \u8D26\u53F7\u5BC6\u7801";
+/** 通用失败文案：不暴露任何 PMS 实现细节（baseURL / 路径 / 状态码 / 响应体）。 */
+export declare const PMS_GENERIC_FAILURE_MESSAGE = "PMS \u6682\u65F6\u4E0D\u53EF\u7528\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5";
+/**
+ * 权限不足的**固定**文案（spec §3 D7 逐字要求）：UI 必须明说「在 HiWork 里没有完成任务的权限」，
+ * 而不是静默失败或回滚得莫名其妙——用户该做的是去 PMS 页面操作。
+ *
+ * 与 `UNAUTHORIZED` 分开的理由：重新登录**不会**解决它（权限是角色给的），把两者混成一个码，
+ * 界面就只能给出「请重新输入密码」这种无效引导。
+ */
+export declare const PMS_FORBIDDEN_MESSAGE = "\u5728 HiWork \u91CC\u6CA1\u6709\u5B8C\u6210\u4EFB\u52A1\u7684\u6743\u9650\uFF0C\u8BF7\u5230 PMS \u64CD\u4F5C";
+/**
+ * 完成任务时用的状态值（PMS `TaskVO.status`：0-待办 / 1-进行中 / 2-已完成 / 3-逾期）。
+ * 完成与激活走同一个 `PUT /{id}/status`，差别只有这个 query 值。
+ */
+export declare const PMS_TASK_STATUS_COMPLETED = 2;
+/**
+ * 「我的任务」只取**未完成**的三种状态（spec §3 D7 的 `status=0&status=1&status=3`）。
+ * 2（已完成）不取：面板是待办视图，把做完的任务一起拉回来只会让列表变长。
+ * 顺序即 query 里的出现顺序（由测试钉死）。
+ */
+export declare const PMS_TASK_OPEN_STATUSES: readonly [0, 1, 3];
+/** 「我的任务」的默认页大小（spec §3 D7）。50 条足够覆盖一个人的未完成任务，且一次请求就够。 */
+export declare const PMS_TASK_PAGE_SIZE = 50;
+/**
+ * 一次成功登录 / 刷新换来的会话。
+ *
+ * `accessToken` **绝不出 Host**；`expiresAt` 是绝对时刻（epoch ms）而不是剩余秒数——剩余秒数
+ * 一旦跨过任何一个 await 就开始漂，而「过期了没有」是授权路径上唯一的判据。
+ */
+export interface PmsTokenSet {
+    accessToken: string;
+    /** 7 天有效；PMS 没回时缺省（此时 access token 过期就只能重新输入账号密码）。 */
+    refreshToken?: string;
+    expiresAt: number;
+    /**
+     * PMS 的**用户 id**（登录响应 `data.userId`，spec §3 D7 要求登录时捕获）。
+     *
+     * 它**不是**凭据（是个人数字 id，PMS 侧内部的 `user_id`），但它是「我的任务」唯一的查询键
+     * （`assigneeId`），所以必须跟着会话一起存下来。`refresh` 的响应里也可能有，但**不以它为准**
+     * ——见 `src/pms-todo-bridge.ts` 的 `authorize`（刷新不改变 userId）。
+     */
+    userId?: number;
+}
+/**
+ * 一条待办（**冻结契约**，spec §4.2 的 `TodoItem`，字段名与 PMS 的 `TodoTaskVO` 一一对应）。
+ *
+ * 演进纪律（§4.2）：**未知字段忽略、未知枚举原样透传**。`status` / `priority` 刻意不写成联合
+ * 类型——PMS 将来加一个 `URGENT` 优先级不该让老客户端崩，也不该让 Host 把它当成脏数据丢掉。
+ * 可选字段**按服务端给的有没有来**（没给就不写这个键），不由本层补 `undefined`。
+ */
+export interface PmsTodoItem {
+    id: number;
+    title: string;
+    description?: string;
+    /** `TODO` | `TEMP`（原样透传）。 */
+    category?: string;
+    /** `HIGH` | `MEDIUM` | `LOW` | 服务端将来新增的值，一律原样透传。 */
+    priority?: string;
+    /** `PENDING` | `COMPLETED` | 服务端将来新增的值，一律原样透传。 */
+    status: string;
+    /** `yyyy-MM-dd`。 */
+    startDate?: string;
+    dueDate?: string;
+    completedTime?: string;
+    /** 服务端判定（`status='PENDING' AND due_date < CURDATE()`），**客户端不重算**。 */
+    isOverdue?: boolean;
+    /** 服务端判定（今日视图里 = 今天到期或无截止日期），**客户端不重算**。 */
+    isDueSoon?: boolean;
+}
+/** 勾选用的两个字面量（PMS 的 `updateTaskStatus` 只认这两个值）。 */
+export type PmsTodoStatusValue = 'PENDING' | 'COMPLETED';
+/**
+ * 一条**项目任务**（spec §3 D7；服务端 `pms-task` 的 `TaskVO` 投影）。字段类型按 PMS 源码定：
+ * `id` / `projectId` / `assigneeId` / `status` / `priority` / `auditStatus` 是数字，
+ * `deadline` 是 `yyyy-MM-dd HH:mm:ss`（PMS 的 `@JsonFormat`），其余是字符串，
+ * `estimatedHours` / `actualHours` 是 `BigDecimal`（Jackson 序列化成数字）。
+ *
+ * 演进纪律与 {@link PmsTodoItem} 同款，但**多一条**：任务的状态与优先级在 PMS 侧是**数字**
+ * （0/1/2/3 与 1/2/3），所以这里没有「未知枚举」可言——数字照发，`statusName` / `priorityName`
+ * 这两个给人看的名字原样透传（将来 PMS 加档位不该让老客户端崩）。未知**字段**忽略。
+ *
+ * 必填项（设计里没标 `?` 的那些）**一定会出现**，服务端没给时按类型兜底（`''` / `0`）：
+ * 界面按 `status === 3` 判逾期、按 `projectName` 渲染徽标，少一个键就得让每个消费方各写一遍兜底。
+ * 设计里明确标可选的那五个（阶段名 / 需求名 / 模块名 / 两个工时）**只按服务端给没给来**。
+ */
+export interface PmsTaskItem {
+    id: number;
+    taskName: string;
+    description: string;
+    projectId: number;
+    projectName: string;
+    /** 所属项目阶段名（服务端没给就没有这个键）。 */
+    projectStageName?: string;
+    assigneeId: number;
+    assigneeName: string;
+    /** `yyyy-MM-dd HH:mm:ss`；没有截止时间时是空串。 */
+    deadline: string;
+    /** 0-待办 / 1-进行中 / 2-已完成 / 3-逾期。 */
+    status: number;
+    statusName: string;
+    /** 1-低 / 2-中 / 3-高。 */
+    priority: number;
+    priorityName: string;
+    taskType: string;
+    taskTypeName: string;
+    /** 0-待审核 / 1-已通过 / 2-已驳回。 */
+    auditStatus: number;
+    auditStatusName: string;
+    /** 关联需求名（服务端没给就没有这个键）。 */
+    requirementName?: string;
+    /** 关联功能模块名（服务端没给就没有这个键）。 */
+    moduleName?: string;
+    /** 预估工时（小时）。 */
+    estimatedHours?: number;
+    /** 实际工时（小时，PMS 从 `work_hour` 汇总）。 */
+    actualHours?: number;
+}
+/**
+ * 「我的任务」的返回（spec §3 D7 的**分页对象**投影，服务端是 `PageResult<TaskVO>`）。
+ *
+ * ⚠️ 与 `today` 的区别就在这里：待办的 `data` 是**数组**，任务的 `data` 是**分页对象**
+ * （`{records, total, current, size}`）——把两者当成同一个形状读，轻则列表永远空，重则把
+ * `records` 当 `undefined` 抛错。
+ */
+export interface PmsTaskList {
+    items: PmsTaskItem[];
+    /** 总条数（服务端缺省时回退成 `items.length`，免得界面显示「共 0 条」却列着内容）。 */
+    total: number;
+    current: number;
+    size: number;
+}
+/** 「我的任务」的可选项（`size` 默认 {@link PMS_TASK_PAGE_SIZE}，非正整数一律回退缺省值）。 */
+export interface PmsMyTasksOptions {
+    size?: number;
+}
+/** `PUT /api/task/tasks/{id}/status` 的结果（PMS 这个接口回 void，所以按请求值回退）。 */
+export interface PmsTaskStatusResult {
+    id: number;
+    /** 任务状态数字（完成是 {@link PMS_TASK_STATUS_COMPLETED}）。 */
+    status: number;
+}
+/** `GET /api/todo/statistics` 的投影（spec §D4）。 */
+export interface PmsTodoStatistics {
+    total: number;
+    pending: number;
+    completed: number;
+    overdue: number;
+}
+/** `PUT /api/todo/{id}/status` 的结果（服务端缺 `completedTime` 时缺省）。 */
+export interface PmsTodoStatusResult {
+    id: number;
+    status: PmsTodoStatusValue;
+    completedTime?: string;
+}
+/** 构造选项（全部可选；生产只传 `log`）。 */
+export interface PmsClientOptions {
+    /** 基址覆盖（**测试用**）；缺省 {@link PMS_BASE_URL}。生产不许传。 */
+    baseURL?: string;
+    /** 超时覆盖（测试用）；缺省 {@link PMS_REQUEST_TIMEOUT_MS}。 */
+    timeoutMs?: number;
+    /** 时钟注入（测试用）；缺省 `Date.now`。 */
+    now?: () => number;
+    /**
+     * Host 日志出口。**只记事件与业务 code**——用户可见的 message 与响应体都不许进来
+     * （§7：账号密码与 JWT 不进日志；业务 message 可能带用户数据）。
+     */
+    log?: ((message: string) => void) | undefined;
+}
+/**
+ * PMS HTTP 客户端。零 DSH 依赖、零凭据——它只负责「把一次调用发出去、把结果或稳定错误返回」。
+ *
+ * @param options - 见 {@link PmsClientOptions}。
+ */
+export declare class PmsClient {
+    private readonly baseURL;
+    private readonly timeoutMs;
+    private readonly now;
+    private readonly log;
+    constructor(options?: PmsClientOptions);
+    /**
+     * `POST /api/auth/login`：用账号密码换 JWT（access + refresh）。
+     *
+     * 失败语义（由 {@link PmsClient.call} 统一给出）：
+     *  - 账号密码不对 → `UNAUTHORIZED`（HTTP 401 **或** 信封 `code:401`，两者同义）；
+     *  - 其余（网络 / 超时 / 5xx / 非业务信封）→ `UPSTREAM_UNAVAILABLE`。
+     * **本方法不重试**，调用方也不许替它重试（§7：避免用错密码连续触发 PMS 的失败锁定）。
+     */
+    login(username: string, password: string): Promise<PmsTokenSet>;
+    /**
+     * `POST /api/auth/refresh`：用 refresh token 续一次 access token。
+     *
+     * refresh token 失效（7 天到期 / 已被 PMS 撤销）→ `UNAUTHORIZED`，此时**只能**重新输入账号密码；
+     * 网络问题 → `UPSTREAM_UNAVAILABLE`（那是「稍后重试」，不是「要重新登录」——两者对用户是两件事）。
+     */
+    refresh(refreshToken: string): Promise<PmsTokenSet>;
+    /**
+     * `GET /api/todo/today`：今日待办（⚠️ 口径比名字宽：**今天 + 明天 + 无截止日期**都算，spec §D4）。
+     *
+     * `data` 必须是数组；不是数组时按**上游不可用**处理（绝不读成「今天没有待办」——那是把中间层的
+     * 维护页当成空清单，用户会以为自己清空了所有待办）。缺 `id` 的条目跳过：没有 id 就没法勾选，
+     * 渲染出来只会是一个点了没反应的复选框。
+     */
+    today(accessToken: string): Promise<PmsTodoItem[]>;
+    /** `GET /api/todo/statistics`：total / pending / completed / overdue 四个计数。 */
+    statistics(accessToken: string): Promise<PmsTodoStatistics>;
+    /**
+     * `PUT /api/todo/{id}/status?status=PENDING|COMPLETED`：勾完成 / 取消完成。
+     *
+     * `status` 走 **query**（PMS 侧就是这么定的），所以必须 `encodeURIComponent`——虽然本层只放行
+     * 两个字面量、编码后与原值相同，但「拼进 URL 的值一律编码」是纪律：少一次编码在参数集合变化时
+     * 就是一个注入面。
+     *
+     * ⚠️ 副作用（spec §D5）：勾完成时若来源是项目任务且该任务下再无 PENDING 待办，**PMS 会把项目
+     * 任务一并标记完成**；反向不成立。本层只负责发请求，提示文案属 UI 的职责。
+     *
+     * 返回值以服务端回声为准（`data.id` / `data.status`），`data` 为空（PMS 这个接口可能回 void）
+     * 时回退成请求里的 id / status——调用方要的是「我勾的是哪条、现在是什么状态」，两者都知道。
+     */
+    setStatus(accessToken: string, id: number, status: PmsTodoStatusValue): Promise<PmsTodoStatusResult>;
+    /**
+     * `GET /api/task/tasks?assigneeId={userId}&status=0&status=1&status=3&current=1&size=50`
+     * （spec §3 D7）：**我的未完成项目任务**。
+     *
+     * 为什么必须直接查任务而不是只读待办：PMS 只在**任务创建那一刻**生成待办
+     * （`TaskService.createFromTask`），转派、走 SQL 批量建的历史任务、以及机制上线前的任务都
+     * 没有待办——只读 `todo_task` 会让这些任务在面板上凭空消失（§3 D7 的缺口表）。
+     *
+     * `status` 在 PMS 侧是 `List<Integer>`，所以是**多个同名参数**而不是逗号分隔（`status=0&status=1&status=3`）；
+     * 顺序按 {@link PMS_TASK_OPEN_STATUSES}，`assigneeId` 是**当前登录人的 PMS userId**
+     * （由调用方从凭据记录里取，见 `src/pms-todo-bridge.ts`）。
+     *
+     * ⚠️ 响应的 `data` 是**分页对象**（`{records, total, current, size}`）**不是数组**：
+     * 不是对象或 `records` 不是数组时按**上游不可用**处理（绝不读成「我没有任务」——那会让用户
+     * 以为活都干完了，而这正是本次最要避免的误读）。
+     *
+     * @param accessToken - Host 内存里的 PMS JWT。
+     * @param userId - 我的 PMS userId（凭据记录里的 `userId`）。
+     * @param opts - 见 {@link PmsMyTasksOptions}。
+     */
+    myTasks(accessToken: string, userId: number, opts?: PmsMyTasksOptions): Promise<PmsTaskList>;
+    /**
+     * `PUT /api/task/tasks/{taskId}/status?status=2`：**完成一条项目任务**（spec §3 D7）。
+     *
+     * 与 {@link PmsClient.setStatus} 同款：`status` 走 **query** 且被编码；要求业务 `code === 200`，
+     * `data` 容许为 `null`（PMS 这个接口的返回类型是 `Result<Void>`，实测就是 null），此时回退成
+     * 请求里的 id / 状态数字——调用方要的是「我完成的是哪条、现在是什么状态」，两者都知道。
+     *
+     * ⚠️ 权限：这个端点带 `@PreAuthorize("hasAuthority('task:list:edit')")`，没有该权限的角色会失败
+     * （`FORBIDDEN`，见 {@link PMS_FORBIDDEN_MESSAGE}）。这与待办那条不同——**不要**把它当成「凭据
+     * 过期」让用户重新登录。
+     */
+    completeTask(accessToken: string, taskId: number): Promise<PmsTaskStatusResult>;
+    /**
+     * 发一次调用并解开 `Result` 信封。**所有错误都在这里收敛**，返回值只有 `data`。
+     *
+     * 顺序是刻意的：**先看 HTTP 401，再解信封**——PMS 未登录时回的是 Spring Security 形状
+     * （`{path, code:"AUTH_001", message}`），它的 `message` 是给浏览器看跳登录页的，既不是业务文案
+     * 也可能带 `path` 等实现细节。把它当业务信封解析，轻则文案变成一句英文，重则把「凭据失效」
+     * 误判成「上游故障」而让用户不知道要重新输入密码。
+     */
+    private call;
+    /** 登录 / 刷新的 `data` → {@link PmsTokenSet}。200 却不给 token 视为契约破坏（上游不可用）。 */
+    private tokenSet;
+}