# mjava-ai 待办看板

> 更新：2026-04-18
> 范围：跨 change 的待办池 + 每 change 内部进度汇总
> 用途：按优先级顺序执行；完成一项立即更新对应 `tasks.md` 和本文件

## 执行阶段

| 阶段 | 内容 | 当前状态 |
|------|------|---------|
| A | 开发规范 + 待办清单（文档层） | 进行中 |
| B.1 | 代码优化：补全 mjava 模块 API 能力 | 待启动 |
| B.2 | 代码优化：待办功能添加（非 pro/com 的基座增强） | 待启动 |
| C | mjava-pro / mjava-com 两个专项子模块开发 | 待 B 完成后启动 |

## 阶段 A 待办

| ID | 任务 | 状态 |
|----|------|------|
| A1 | 开发规范 11 章（mjava-baseline.md）写到 §3.5 审计、§3.4 Client/Service 分层 | ✅ 完成 |
| A2 | yida-serverside.md 从原 CLAUDE.md 拆出 | ✅ 完成 |
| A3 | 后端/CLAUDE.md 改为总索引 | ✅ 完成 |
| A4 | 上层 claude/CLAUDE.md 同步索引 | ✅ 完成 |
| A5 | server 目录分层 cur/pre | ✅ 完成 |
| A6 | mjava-ai 仓库 git init + 首次 commit + push | ✅ 完成 |
| A7 | 敏感文件 .gitignore 防护 + .example 模板 | ✅ 完成 |
| A8 | mjava-pro / mjava-com 专项提案四件套 | ✅ 完成 |
| A9 | init-project-baseline tasks 5.1-5.3 验证 | ✅ 完成 |
| A10 | 归档 `extract-dingtalk-standard-api` | ✅ 完成，`changes/archive/2026-04-18-extract-dingtalk-standard-api/` |
| A11 | `brew install maven` 后补做 init-baseline 任务 5.4（编译冒烟） | ⏳ 阻塞在本机未装 Maven |
| A12 | `/Users/malk/Desktop/Tech/claude/` git init（规范文档版本化） | ✅ 完成（白名单策略，只收规范 md） |
| A13 | 扩展 `mjava-baseline.md §3.4` — Client API 对齐详细规则（§3.4.1-§3.4.5）| ✅ 完成 |

## 阶段 B.1 — 补全 mjava 模块 API 能力

按用户优先级指令（2026-04-18）：**先宜搭，后钉钉通讯录，其余 vendor 暂不做**。改造行为由 `/opsx:apply` 触发，本阶段**先完成规则定义**。

| ID | 任务 | 归属 change | 状态 |
|----|------|------------|------|
| B1.1 | **宜搭**表单 + 流程 API 对齐规则与覆盖度矩阵 | `changes/extend-yida-api-coverage/` | ✅ 规则就绪（proposal/design/spec/tasks 四件套 valid） |
| B1.2 | **钉钉通讯录** API 对齐规则与覆盖度矩阵 | `changes/extend-dingtalk-contacts-api/` | ✅ 规则就绪 |
| B1.3 | 钉钉其余模块（考勤/审批/消息/群聊/...）| 未立项 | ⏸ 暂缓，待用户指令 |
| B1.4 | 其他 vendor（北森/teambition/fxiaoke/h3yun/vika/xbongbong/feishu/ekuaibao）| 未立项 | ⏸ 低优先级，按需补 |
| B1.5 | **实施**：宜搭原子 Client 落地（`/opsx:apply extend-yida-api-coverage`） | — | ⏳ 待用户触发 |
| B1.6 | **实施**：钉钉通讯录原子 Client 落地（`/opsx:apply extend-dingtalk-contacts-api`） | — | ⏳ 待用户触发 |

## 阶段 B.2 — 待办功能添加（基座增强）

不依赖 pro/com 专项的基座功能增强，都先做在 `mjava/` 基座里，让三个现存客户模块可立刻受益。

| ID | 任务 | 归属 change | 备注 |
|----|------|-------------|------|
| B2.1 | `UtilHttp` 内部落实 §3.5 审计日志（请求/响应脱敏 + latency + success） | 待立项 | 脱敏规则：token/appSecret/password/aesKey/privateKey → `***` |
| B2.2 | `UtilToken` 支持 namespace 参数（为 mjava-pro 租户隔离铺路） | 待立项 | API：`put(namespace, key, value, ttl)` |
| B2.3 | `CallerRateLimiter` 抽象（通用限流组件） | 待立项 | Guava RateLimiter 封装 |
| B2.4 | 完成 `add-observability-foundation` tasks 4.2 / 5.2（生产冒烟） | observability | 需 Maven |
| B2.5 | 把 Client 方法兼容全参数的**代码审查清单**（checklist）沉淀进 `/opsx:propose` 的模板 | 未定，文档侧 | 避免将来 PR 漏传字段 |
| B2.6 | 请求监听的 trace 输出示例 | 文档 | baseline §3.5 / §8 |
| **B2.7** | **基座请求鉴权 + 防重放**（HMAC-SHA256 + 时间窗 + Nonce） | `changes/add-request-auth-replay-guard/` | ✅ 规则就绪，0/33 任务；**mjava-com 的前置依赖** |

## 阶段 C — 专项子模块开发（最后启动）

| 专项 | tasks.md 进度 |
|------|--------------|
| `add-mjava-pro/` | 0 / 30 |
| `add-mjava-com/` | 0 / 30 |

按 tasks.md 依序走 `/opsx:apply`。

## 进度总览（2026-04-19 更新）

```
✅ Phase A 完成（文档体系 + server 分层 + git 初始化）
✅ Phase B.1 extend-yida-api-coverage       代码落地 + mvn compile 通过
✅ Phase B.1 extend-dingtalk-contacts-api   代码落地 + mvn compile 通过
✅ Phase B.2 add-request-auth-replay-guard  代码落地 + mvn compile 通过
✅ Phase C   add-mjava-pro                  骨架 + mvn compile 通过
✅ Phase C   add-mjava-com                  骨架 + mvn compile 通过
✅ 全 reactor 6 模块 mvn package -DskipTests 全部打包成功（2026-04-19）
✅ Archive: extract-dingtalk-standard-api (2026-04-18)
✅ Archive: init-project-baseline (2026-04-19)

📋 剩余:
- add-observability-foundation 2 项运行冒烟（java -jar 启动验证 actuator）
- 各 change 的子模块 .example yml 扩展 mjava.auth 段
- logback pattern 追加 %X{authKey:-} / %X{tenantId:-} / %X{callerId:-}
- DingtalkActionRegistry / AliworkActionRegistry 首批 action 注册
- 覆盖度矩阵官方文档人工复核（yida/dingtalk）
- 单元 / 集成测试
```

## 实施中风险记录

### add-request-auth-replay-guard（2026-04-19 实施）

1. **Body 二次读取**：`AuthInterceptor.readBody` 直接 `request.getReader()`，读完后 Controller 再读会拿空。生产启用前需加 `ContentCachingRequestWrapper`（Filter 层包装），否则 Controller 的 `@RequestBody` 会失效。记 BACKLOG 明日修（或随首个实际启用 enabled 的客户同时做）。
2. **logback pattern**：未在基座 logback-spring.xml 追加 `[%X{authKey:-}]`。默认 enabled=false 下无影响；启用时记得加。
3. **单元 + 集成测试**：阻塞 Maven。
4. **NonceCache 并发**：用 `synchronized putIfAbsent`，高 QPS 单实例可能成瓶颈。当前单点场景足够，多实例部署时评估 Redis。
5. **编译未验证**：本机无 Maven。`McR.error(String, String)` 签名已核对；`HandlerInterceptorAdapter` 在 Spring Boot 2.2 可用（Spring 5.3+ deprecated 但仍可编译）。

### extend-dingtalk-contacts-api（2026-04-19 实施）

1. **URL 路径待官方复核**：
   - `/topapi/role/add_role` vs `/topapi/role/addrole` 钉钉历史版本命名不一（underscored vs kebab vs camel），实施前需对照官方文档逐条核准
   - `/topapi/v2/department/listparentbydept` 推断
   - `/topapi/hide_field/*` 推断（可能实际路径为 `/topapi/contact/empAttr/visibility/...`）
2. **dept_id_list 格式**：`createUser_v2` 用 `String.join(",", ...)` 转逗号串。钉钉部分接口接受数组 `List<Long>`，部分接受逗号字符串；需对照官方文档确认。若官方要求数组，删掉 join 直接传 List。
3. **编译未验证**：本机无 Maven；`DDR.isSuccess()` 假定存在（从 `DDR.getResult()` 推断），若实际无此方法 `deleteDepartment` / `deleteRole` / 批量分配等方法返回值判定会编译错。
4. **Role 模块返回结构**：`listRoles` / `listRoleEmployees` 返回 Map 含 `list` / `page_cursor` / `has_more` 等字段，调用方需理解翻页；未做便利封装。

### extend-yida-api-coverage（2026-04-18 实施）

1. **官方文档 fetch 失败**：WebFetch 拿到的是索引页，URL 路径基于训练知识 + 旧 `YDClientImpl` 已验证 endpoint 推断。以下路径**未经人工官方文档对照**，冒烟前需复核：
   - `/processes/tasks/{agree|disagree|redirect|cc|comment}`
   - `/processes/instances/{terminate|revoke|redirect}`
   - `/processes/operationRecords`（listApprovalRecords 推断）
2. **编译未验证**：本机无 Maven，Java 代码未 `mvn compile`。潜在风险：
   - `x-acs-dingtalk-access-token` header key 是否与 `ddClient.initTokenHeader()` 返回一致未验证
   - `DDR_New.getResult()` 返回 `Object`，各处 cast 未实地测试
   - `UtilHttp.doPut/doDelete` 的 4 参重载确认
3. **Boolean 返回判定**：宜搭多数写操作返回 `true/false`，实现用 `Boolean.TRUE.equals(r.getResult())` 判定，但部分 endpoint 实际返回 Map 或数字时可能错判；实施冒烟时需抽样确认。
4. **listFormIds** URL + body 都传 appType/formUuid，沿用旧实现逻辑，可能冗余但不影响正确性。
5. **YDService 迁移**：本阶段不切换 YDService 内部调用到新原子方法（tasks 5.x 标为"可选不做"），等编译通过后再决定。