5cd8f0f551
- tools/{uuid,md5,random,time,ip}/index.go → 对应 <功能名>.go（git mv 保留历史）
- 目录名=包名=文件名三一致，扩展时目录内按功能加文件（ocr.go → + idcard.go + invoice.go）
- doc.go / AGENTS.md / PROJECT_STRUCTURE.md 同步规则说明
- 冒烟测试 5 端点全部通过
156 lines
9.8 KiB
Go
156 lines
9.8 KiB
Go
# Change Log — 2026-08-24
|
||
|
||
## 请求
|
||
|
||
1. 新增一个「公共模块」，模块下存放 `tools` 功能模块，`tools` 下再分各种子功能。
|
||
2. 建立项目上下文记忆体系：记录每次请求与更改，方案对比后落地；要求后续使用其他 CodeBuddy 账号也能无缝衔接。
|
||
|
||
## 变更
|
||
|
||
新增文件：
|
||
|
||
- `common/doc.go` — 公共模块说明（不依赖 internal、可独立抽取）
|
||
- `common/tools/doc.go` — tools 模块布局清单与封装规则
|
||
- `common/tools/md5/md5.go` — MD5 摘要（Md5Hex / Md5Bytes / Md5File）
|
||
- `common/tools/cryptox/cryptox.go` — AES-128-CBC / DES-ECB 加解密（base64 输出，密钥任意长度自动规范化）
|
||
- `common/tools/uuid/uuid.go` — 唯一 ID（New 32 位 / Short 短随机码）
|
||
- `common/tools/random/random.go` — 随机数/随机串（Int / String / Digits / Letters）
|
||
- `common/tools/timex/timex.go` — 时间工具（Format / Timestamp / StartOfDay / EndOfDay）
|
||
- `common/tools/convertx/convertx.go` — 类型转换带默认值（ToInt / ToInt64 / ToFloat64 / ToString / ToBool）
|
||
- `common/tools/strx/strx.go` — 字符串工具（命名转换 SnakeCase/CamelCase + 脱敏 MaskPhone/MaskIDCard/MaskName）
|
||
- `common/tools/slicex/slicex.go` — 泛型切片工具（Contains / Unique / Chunk / Map / Filter）
|
||
- `common/tools/ip/ip.go` — IP 工具（IsValid / LocalIP / IsInternal / ToLong / ToString）
|
||
- `common/tools/filex/filex.go` — 文件工具（Exists / IsDir / ReadString / WriteString）
|
||
- `AGENTS.md` — 项目智能体说明书（架构、规范、命令、记忆体系索引）
|
||
- `docs/change-log/2026-08-24.md` — 本文档
|
||
|
||
修改文件：
|
||
|
||
- `.gitignore` — 追加 `.workbuddy/`（本机记忆不入库）
|
||
- `PROJECT_STRUCTURE.md` — 目录树补充 `common/` 与 `docs/change-log/`（见后续提交）
|
||
|
||
验证：`go build ./...` 与 `go vet ./common/...` 全部通过。
|
||
|
||
## 决策与理由
|
||
|
||
- **公共模块放顶层 `common/` 而非 `internal/common/`**：Go 的 internal 包无法被外部模块引用，放顶层便于未来抽取为独立库/被同仓库其他服务复用。
|
||
- **tools 一律薄封装 GoFrame 内置组件**：v2.10.2 中 AES/DES 已拆为 `crypto/gaes`、`crypto/gdes`，UUID 为 `util/guid`，无 `gslicer`（用标准库 `slices` 替代）；避免重复造轮子，保持与框架一致。
|
||
- **记忆体系三层方案**（对比见下）：
|
||
1. `AGENTS.md`（根目录）— 长期稳定规范，跨工具标准（Claude Code/CodeBuddy/Codex 等均识别），随 git 走；
|
||
2. `docs/change-log/YYYY-MM-DD.md` — 每次请求变更的结构化记录，随 git 走，**这是跨账号衔接的关键**；
|
||
3. `.workbuddy/memory/` — WorkBuddy 本机增强，不入库。
|
||
- 对比过 `CLAUDE.md`（Claude Code 专属、已建议统一为 AGENTS.md）、`.cursor/rules`（Cursor 专属）、`.codebuddy/`（仅 CodeBuddy 读取）——它们都不是最大公约数，故不采用。
|
||
|
||
## 待办与风险
|
||
|
||
- 后续每次任务完成后：更新 `docs/change-log/`（当日文件追加）+ 提交 git，确保其他账号 clone 即恢复上下文。
|
||
- `convertx` 依赖 gconv 的"转换失败返回零值"行为（无法区分"0"与非法输入），需要严格转换的场景应在 service 层先校验。
|
||
- 本次变更尚未 git 提交，建议尽快 commit。
|
||
|
||
---
|
||
|
||
## 追加（17:30）：方向纠正 — 「公共模块」实为公共接口
|
||
|
||
### 请求
|
||
|
||
用户澄清：要新增的是**给前端调用的公共 HTTP 接口**（此前误建成 Go 工具包），确认应规划到 `api/` 契约层。
|
||
|
||
### 变更
|
||
|
||
新增文件：
|
||
|
||
- `api/common/v1/tools.go` — 公共接口契约：`UUIDReq/Res`、`MD5Req/Res`、`RandomReq/Res`、`TimeReq/Res`、`IPReq/Res`（g.Meta 路由元数据）
|
||
- `internal/controller/common/tools.go` — 控制器实现，薄适配层，复用 `common/tools/*` Go 包
|
||
|
||
修改文件：
|
||
|
||
- `internal/cmd/cmd.go` — 新增公开分组 `s.Group("/api/common/v1", ...)`（Recover+CORS+HandlerResponse，**无鉴权**）
|
||
- `common/tools/timex/timex.go` — 修复：`Format` 内部改用 `Layout()` 方法（见决策）
|
||
- `internal/controller/common/tools.go` — `Time` 用 `now.Layout(...)`
|
||
- `AGENTS.md` — 目录树与新增「公共接口」小节、注意事项补 gtime 与包名差异
|
||
- `PROJECT_STRUCTURE.md` — 目录树补充 `api/common/v1`
|
||
|
||
验证：`go build ./...`、`go vet` 通过；**实际启动服务冒烟测试** 5 个端点全部返回正确（含修复后 time 格式化）。
|
||
|
||
### 决策与理由
|
||
|
||
- **路由前缀 `/api/common/v1`**：与 `/api/v1`(user)、`/admin/v1`(admin) 平级的独立公开前缀，天然不套登录鉴权；前端三个端（mini/h5/app）通用。
|
||
- **契约层放 `api/common/v1`，实现放 `internal/controller/common`**：与 user/admin 完全同构；公共接口不需要 service 层（纯工具计算），controller 直接复用 `common/tools` 包，避免过度分层。
|
||
- **🐛 gtime v2.10.2 大坑（已修复）**：`Time.Format()` 参数是 **PHP 风格**（`"Y-m-d H:i:s"`），传 Go layout（`"2006-01-02 15:04:05"`）会原样输出！Go layout 必须用 `Time.Layout()`。`common/tools/timex` 已统一封装为 `Layout` 语义，调用方直接 `timex.Format(t, layout...)` 即可。
|
||
- **冒烟测试教训**：`go run` 会 spawn 子进程，`kill %1` 只杀包装进程，残留的 `main.exe` 会继续占用 8000 端口导致后续测试打到旧代码——杀进程需 `netstat -ano | grep :8000` 找 PID 后 `Stop-Process`。
|
||
|
||
### 待办与风险
|
||
|
||
- 本次追加变更同样未提交 git，与上文合并为一次 commit。
|
||
- 公共接口已开放无鉴权能力（md5/random/uuid 等），后续新增接口时需评审是否应限流/加签名，避免被滥用。
|
||
|
||
---
|
||
|
||
## 追加（18:05）：开放接口命名决策 + API 目录重构
|
||
|
||
### 请求
|
||
|
||
1. 变更 API 目录设计：契约层改为 `tools/<子功能>/index.go` 结构（示例 `/api/common/v1/tools/ocr/index.go`）。
|
||
2. 同步修改所有涉及处（控制器、路由）。
|
||
3. 把命名规则记入项目记忆。
|
||
4. 咨询：公共接口一般用 common 命名吗？有没有更好的？
|
||
|
||
### 变更
|
||
|
||
新增文件（契约层按子功能拆目录）：
|
||
|
||
- `api/open/v1/tools/doc.go` — tools 目录结构规则说明
|
||
- `api/open/v1/tools/uuid/index.go`、`md5/index.go`、`random/index.go`、`time/index.go`、`ip/index.go` — 每子功能一个目录，index.go 内 `package <子功能名>`，g.Meta tags 改 `Open/Tools`
|
||
- `internal/controller/open/controller.go` — Controller 结构 + New()
|
||
- `internal/controller/open/uuid.go`、`md5.go`、`random.go`、`time.go`、`ip.go` — 按子功能拆文件，import 对应契约子包
|
||
|
||
删除文件：
|
||
|
||
- `api/common/v1/tools.go`、`api/common/` 目录
|
||
- `internal/controller/common/tools.go`、`internal/controller/common/` 目录
|
||
|
||
修改文件：
|
||
|
||
- `internal/cmd/cmd.go` — import `commonctl`→`openctl`；路由 `/api/common/v1`→`/api/open/v1`，注释改 Open tools API
|
||
- `AGENTS.md` — 目录树更新；「公共接口」小节改为「开放接口（api/open/v1）与命名规则」，记录 open 命名决策与 tools 子功能目录规则
|
||
- `PROJECT_STRUCTURE.md` — 目录树同步
|
||
|
||
验证：`go build ./...`、`go vet` 通过；冒烟测试：旧路由 `/api/common/v1/tools/time` 返回 404，新路由 `/api/open/v1/tools/*` 5 端点全部正确。
|
||
|
||
### 决策与理由
|
||
|
||
- **命名 common → open**：用户询问"公共接口一般用 common 吗"，对比后选 **open**（业界开放接口惯例，如支付宝 /open/api；语义强调对外暴露、无鉴权）。`public` 为并列备选（更强调"公开"），`common` 偏内部通用语义、弃用。命名规则已记入 AGENTS.md「开放接口」小节。
|
||
- **契约层目录规则**：`api/open/v1/tools/<子功能名>/index.go` 每子功能一目录（与 GoFrame 惯例「api 下按功能分包」一致，用户示例 ocr 即为后续子功能，如未来加 OCR 识别接口即建 `tools/ocr/index.go`）；控制器 `internal/controller/open/<子功能名>.go` 对应拆文件（同 package open）。
|
||
- **路由绑定不受目录重构影响**：GoFrame 通过 controller 方法参数反射定位 g.Meta，契约包拆成多个子包（uuid/md5/random/time/ip）不影响 `group.Bind(openctl.New())` 自动注册，cmd.go 只需改前缀。
|
||
- 包名 `time`（api/open/v1/tools/time）与标准库 time 潜在同名，controller 中统一用 import 别名 `timeapi` 规避。
|
||
|
||
### 待办与风险
|
||
|
||
- 前端若已联调旧 `/api/common/v1` 路径需同步改 `/api/open/v1`（当前无线上前端，风险低）。
|
||
- 新增子功能记得更新 `api/open/v1/tools/doc.go` 的示例清单。
|
||
|
||
---
|
||
|
||
## 追加（18:08）：契约文件 index.go → <功能名>.go
|
||
|
||
### 请求
|
||
|
||
用户咨询"子功能目录内用 index.go 还是 <功能名>.go 更易扩展维护"，确认推荐后执行改动。
|
||
|
||
### 变更
|
||
|
||
- `git mv` 重命名 5 个契约文件：`tools/{uuid,md5,random,time,ip}/index.go` → `tools/{uuid,md5,random,time,ip}/{uuid,md5,random,time,ip}.go`（包内容不变）
|
||
- `api/open/v1/tools/doc.go` — 规则说明改为「目录名=包名=文件名三一致」，补充"功能变大后目录内加文件"的扩展指引
|
||
- `AGENTS.md` / `PROJECT_STRUCTURE.md` — 同步 index.go 引用为 <name>.go
|
||
|
||
验证：`go build ./...`、`go vet` 通过；冒烟测试 5 端点全部正常。
|
||
|
||
### 决策与理由
|
||
|
||
- **选 <功能名>.go 而非 index.go**：① 目录名=包名=文件名三一致，导航直观；② index.go 是"入口"语义，功能膨胀后出现 `index.go + idcard.go` 混排会失去入口意义，而 `<name>.go + idcard.go` 自然；③ 符合 Go 生态主流（strings/strings.go）与 GoFrame 官方模板（api/user/v1/user.go）。
|
||
- **扩展路径已定型**：子功能从 1 个端点到多个端点，只需在目录内加文件（如 ocr 目录 `ocr.go → + idcard.go + invoice.go`），无需重构文件名。
|
||
|
||
### 待办与风险
|
||
|
||
- 无新增风险；后续新增子功能统一按 `tools/<name>/<name>.go` 建文件。
|