251 lines
11 KiB
Markdown
251 lines
11 KiB
Markdown
# Codebase Structure
|
||
|
||
**Analysis Date:** 2026-03-27
|
||
|
||
## Directory Layout
|
||
|
||
```text
|
||
junhong_cmp_fiber/
|
||
├── cmd/ # API、Worker、文档生成入口
|
||
├── internal/ # 核心业务代码（handler/service/store/model/routes/bootstrap/task）
|
||
├── pkg/ # 可复用基础设施与跨模块工具
|
||
├── migrations/ # SQL 迁移脚本
|
||
├── docs/ # 业务文档、接入指南、架构说明
|
||
├── openspec/ # 当前能力规格与变更档案
|
||
├── specs/ # 早期 Speckit 规格文档
|
||
├── scripts/ # 检查与初始化脚本
|
||
├── docker/ # 部署相关辅助文件
|
||
├── logs/ # 运行期日志输出目录
|
||
└── .planning/codebase/ # 当前代码地图产物
|
||
```
|
||
|
||
## Directory Purposes
|
||
|
||
**`cmd/`:**
|
||
- Purpose: 进程级入口和独立命令。
|
||
- Contains: `cmd/api/main.go`, `cmd/api/docs.go`, `cmd/worker/main.go`, `cmd/gendocs/main.go`
|
||
- Key files: `cmd/api/main.go`, `cmd/worker/main.go`
|
||
|
||
**`internal/bootstrap/`:**
|
||
- Purpose: 依赖装配中心。
|
||
- Contains: API/Worker 的 stores、services、handlers、middlewares 初始化。
|
||
- Key files: `internal/bootstrap/bootstrap.go`, `internal/bootstrap/services.go`, `internal/bootstrap/worker.go`, `internal/bootstrap/types.go`
|
||
|
||
**`internal/routes/`:**
|
||
- Purpose: 路由域划分与 OpenAPI 绑定。
|
||
- Contains: 域入口 `admin.go`, `auth.go`, `personal.go` 以及各模块路由文件。
|
||
- Key files: `internal/routes/routes.go`, `internal/routes/registry.go`, `internal/routes/admin.go`, `internal/routes/personal.go`
|
||
|
||
**`internal/handler/`:**
|
||
- Purpose: HTTP Handler 层。
|
||
- Contains: `admin/`、`app/`、`auth/`、`callback/` 四个子域。
|
||
- Key files: `internal/handler/admin/account.go`, `internal/handler/auth/handler.go`, `internal/handler/callback/payment.go`
|
||
|
||
**`internal/service/`:**
|
||
- Purpose: 业务逻辑层。
|
||
- Contains: 按业务模块拆分的子目录，每个模块通常有一个 `service.go`。
|
||
- Key files: `internal/service/account/service.go`, `internal/service/order/service.go`, `internal/service/package/service.go`, `internal/service/polling/*.go`
|
||
|
||
**`internal/store/`:**
|
||
- Purpose: 数据访问层。
|
||
- Contains: 基础抽象 `store.go`、查询选项 `options.go`、以及 `postgres/` 下的具体实现。
|
||
- Key files: `internal/store/store.go`, `internal/store/options.go`, `internal/store/postgres/account_store.go`, `internal/store/postgres/order_store.go`
|
||
|
||
**`internal/model/`:**
|
||
- Purpose: 持久化模型与 DTO。
|
||
- Contains: 业务实体模型、基础模型、DTO 子目录。
|
||
- Key files: `internal/model/account.go`, `internal/model/order.go`, `internal/model/shop.go`, `internal/model/dto/account_dto.go`
|
||
|
||
**`internal/task/`:**
|
||
- Purpose: Asynq 任务处理逻辑。
|
||
- Contains: 轮询、导入、订单超时、邮件、佣金等任务处理器。
|
||
- Key files: `internal/task/polling_handler.go`, `internal/task/order_expire.go`, `internal/task/device_import.go`
|
||
|
||
**`internal/polling/`:**
|
||
- Purpose: 轮询调度器与专用运行时组件。
|
||
- Contains: `Scheduler`、激活处理器、流量重置处理器。
|
||
- Key files: `internal/polling/scheduler.go`
|
||
|
||
**`internal/gateway/`:**
|
||
- Purpose: 对外 Gateway HTTP 客户端封装。
|
||
- Contains: 请求签名、设备/卡查询与操作客户端。
|
||
- Key files: `internal/gateway/client.go`（由 `cmd/api/main.go`、`cmd/worker/main.go` 初始化）
|
||
|
||
**`pkg/`:**
|
||
- Purpose: 通用基础设施。
|
||
- Contains: 配置、数据库、日志、认证、错误、响应、OpenAPI、队列、对象存储、微信、短信、中间件辅助。
|
||
- Key files: `pkg/config/config.go`, `pkg/config/loader.go`, `pkg/database/postgres.go`, `pkg/middleware/auth.go`, `pkg/middleware/data_scope.go`, `pkg/openapi/generator.go`
|
||
|
||
**`migrations/`:**
|
||
- Purpose: 数据库结构演进。
|
||
- Contains: 成对的 `*.up.sql` / `*.down.sql` 与少量补数 SQL。
|
||
- Key files: `migrations/000000_create_legacy_tables.up.sql`, `migrations/000055_package_system_upgrade.up.sql`, `migrations/000088_rename_card_wallet_id_to_asset_wallet_id.up.sql`
|
||
|
||
**`docs/`:**
|
||
- Purpose: 面向开发和业务的说明文档。
|
||
- Contains: 功能总结、架构说明、接入指南、运维说明、第三方资料。
|
||
- Key files: `docs/api-documentation-guide.md`, `docs/auth-architecture.md`, `docs/polling-system/README.md`
|
||
|
||
**`openspec/`:**
|
||
- Purpose: 规范驱动开发资产。
|
||
- Contains: `config.yaml`、当前 specs、历史归档变更。
|
||
- Key files: `openspec/config.yaml`, `openspec/specs/**/spec.md`, `openspec/changes/archive/**`
|
||
|
||
## Key File Locations
|
||
|
||
**Entry Points:**
|
||
- `cmd/api/main.go`: API 服务主入口。
|
||
- `cmd/worker/main.go`: Worker 服务主入口。
|
||
- `cmd/gendocs/main.go`: 离线 OpenAPI 生成命令。
|
||
|
||
**Configuration:**
|
||
- `pkg/config/config.go`: 配置结构与校验规则。
|
||
- `pkg/config/loader.go`: 嵌入配置 + 环境变量覆盖加载。
|
||
- `openspec/config.yaml`: 规范生成器上下文与规则。
|
||
|
||
**Core Logic:**
|
||
- `internal/service/`: 所有业务服务主实现。
|
||
- `internal/store/postgres/`: 所有 PostgreSQL 访问实现。
|
||
- `internal/bootstrap/`: 依赖注入和装配。
|
||
- `internal/polling/scheduler.go`: 轮询核心调度逻辑。
|
||
|
||
**API Surface:**
|
||
- `internal/routes/`: 路由分组与注册。
|
||
- `internal/handler/admin/`, `internal/handler/app/`, `internal/handler/auth/`, `internal/handler/callback/`: 传输层处理器。
|
||
|
||
**Data Definitions:**
|
||
- `internal/model/*.go`: 表模型。
|
||
- `internal/model/dto/*.go`: 请求/响应 DTO。
|
||
|
||
**Documentation / Planning:**
|
||
- `docs/`: 功能文档。
|
||
- `openspec/specs/`: 现行规格。
|
||
- `openspec/changes/archive/`: 历史变更记录。
|
||
|
||
## Naming Conventions
|
||
|
||
**Files:**
|
||
- 模块按业务名命名：`internal/service/account/service.go`, `internal/handler/admin/account.go`
|
||
- 大部分 Store 文件采用 `{resource}_store.go`：`internal/store/postgres/account_store.go`
|
||
- DTO 文件采用 `{module}_dto.go`：`internal/model/dto/account_dto.go`
|
||
- 路由文件按模块命名：`internal/routes/account.go`, `internal/routes/polling_config.go`
|
||
|
||
**Directories:**
|
||
- 分层目录使用小写单数语义：`internal/service/`, `internal/store/`, `internal/model/`
|
||
- 传输域用子目录表达边界：`internal/handler/admin/`, `internal/handler/app/`, `internal/handler/callback/`
|
||
- 规格目录按能力名组织：`openspec/specs/account-management/`, `openspec/specs/order-payment/`
|
||
|
||
## Ownership / Responsibility Guide
|
||
|
||
**如果改接口路径或加新 API：**
|
||
- 先看 `internal/routes/registry.go` 与对应模块路由文件。
|
||
- 再同步检查 `docs/api-documentation-guide.md`、`cmd/api/docs.go`、`cmd/gendocs/main.go`、`pkg/openapi/handlers.go`。
|
||
|
||
**如果改业务规则：**
|
||
- 主要落点在 `internal/service/{module}/service.go`。
|
||
- 如涉及跨模块，先看 `internal/bootstrap/services.go` 中该服务依赖谁。
|
||
|
||
**如果改查询或权限过滤：**
|
||
- 主要落点在 `internal/store/postgres/*.go`。
|
||
- 数据范围辅助逻辑集中在 `pkg/middleware/data_scope.go` 与 `pkg/middleware/permission_helper.go`。
|
||
|
||
**如果改表结构或模型：**
|
||
- SQL 先改 `migrations/`。
|
||
- Go 模型同步改 `internal/model/*.go`。
|
||
- DTO 变更再改 `internal/model/dto/*.go`。
|
||
|
||
**如果改异步任务：**
|
||
- 任务实现放 `internal/task/*.go`。
|
||
- 注册入口在 `pkg/queue/handler.go`。
|
||
- Worker 依赖拼装在 `internal/bootstrap/worker*.go`。
|
||
|
||
**如果改轮询系统：**
|
||
- 调度逻辑看 `internal/polling/scheduler.go`。
|
||
- 执行逻辑看 `internal/task/polling_handler.go`。
|
||
- 配置/监控/清理相关服务看 `internal/service/polling/*.go`。
|
||
|
||
## Where to Add New Code
|
||
|
||
**New Admin API Feature:**
|
||
- Primary code: `internal/handler/admin/{module}.go`, `internal/service/{module}/service.go`, `internal/store/postgres/{module}_store.go`, `internal/routes/{module}.go`
|
||
- Models / DTOs: `internal/model/{module}.go`, `internal/model/dto/{module}_dto.go`
|
||
- Wiring: `internal/bootstrap/services.go`, `internal/bootstrap/handlers.go`, `internal/bootstrap/types.go`, `internal/routes/admin.go`
|
||
|
||
**New Personal Client Feature:**
|
||
- Primary code: `internal/handler/app/{feature}.go`, `internal/service/{feature}/service.go` 或复用现有服务
|
||
- Routes: `internal/routes/personal.go`
|
||
- Auth-sensitive DTOs: `internal/model/dto/` 下新增对应 DTO 文件
|
||
|
||
**New Worker Task:**
|
||
- Implementation: `internal/task/{task_name}.go`
|
||
- Registration: `pkg/queue/handler.go`
|
||
- Dependencies: `internal/bootstrap/worker_services.go` 或 `internal/bootstrap/worker_stores.go`
|
||
- Constants: `pkg/constants/` 中对应任务类型定义
|
||
|
||
**New Shared Utility:**
|
||
- Shared helpers: `pkg/{subsystem}/`
|
||
- 仅限跨多个业务模块复用的基础能力，不要把业务逻辑塞进 `pkg/`
|
||
|
||
**New Business Spec / Plan Artifact:**
|
||
- Current capability spec: `openspec/specs/{capability}/spec.md`
|
||
- Historical change proposal: `openspec/changes/...`
|
||
- Developer-facing long-form doc: `docs/{feature-id}/` 或现有专题目录
|
||
|
||
## Practical Navigation Guide
|
||
|
||
**从请求入口追代码：**
|
||
1. 在 `internal/routes/*.go` 找路径。
|
||
2. 跳到对应 `internal/handler/...` 方法。
|
||
3. 看该 Handler 注入了哪个 Service。
|
||
4. 到 `internal/service/...` 看业务编排。
|
||
5. 再进入 `internal/store/postgres/...` 看 SQL 过滤与分页。
|
||
6. 最后回到 `internal/model/` / `internal/model/dto/` 看字段定义。
|
||
|
||
**从一个模块反查装配方式：**
|
||
1. 先找 `internal/bootstrap/services.go` 是否实例化该 Service。
|
||
2. 再看 `internal/bootstrap/handlers.go` 是否把它交给 Handler。
|
||
3. 再看 `internal/routes/admin.go` 或 `internal/routes/personal.go` 是否挂载了该模块。
|
||
|
||
**从一个异步任务反查来源：**
|
||
1. 看 `pkg/queue/handler.go` 的 `registerXxxHandler()`。
|
||
2. 跳到 `internal/task/{task}.go`。
|
||
3. 若任务由调度器触发，再看 `internal/polling/scheduler.go` 或 `cmd/worker/main.go` 的 Asynq Scheduler 注册。
|
||
|
||
## Special Directories
|
||
|
||
**`logs/`:**
|
||
- Purpose: 运行日志输出目录。
|
||
- Generated: Yes
|
||
- Committed: No（运行期产物）
|
||
|
||
**`migrations/`:**
|
||
- Purpose: 数据库迁移脚本。
|
||
- Generated: No
|
||
- Committed: Yes
|
||
|
||
**`docs/第三方文档/`:**
|
||
- Purpose: 外部供应商或接口资料归档。
|
||
- Generated: No
|
||
- Committed: Yes
|
||
|
||
**`openspec/changes/archive/`:**
|
||
- Purpose: 已归档历史变更。
|
||
- Generated: No
|
||
- Committed: Yes
|
||
|
||
**`.planning/codebase/`:**
|
||
- Purpose: 供规划/执行命令消费的代码地图文档。
|
||
- Generated: Yes
|
||
- Committed: Yes
|
||
|
||
## Structural Notes for Contributors
|
||
|
||
- 这个仓库的“物理结构”严格围绕 Go 后端单体展开；新增代码优先放进现有层级，不要新造平行架构。
|
||
- `internal/bootstrap/handlers.go` 当前会为客户端能力额外 new 一批 Store，这意味着某些接口不是纯 Service 注入；新增客户端功能前先确认是否要复用现有 `services` 聚合，还是遵循当前适配方式。
|
||
- OpenAPI 不是完全自动发现；新增 Handler、Route 之后，必须同步维护 `internal/bootstrap/types.go`、`internal/bootstrap/handlers.go`、`internal/routes/*.go`、`cmd/api/docs.go`、`cmd/gendocs/main.go`、`pkg/openapi/handlers.go`。
|
||
- 数据权限过滤不在统一 GORM 查询回调中自动生效；新增 Store 查询时，要主动选对 `ApplyShopFilter`、`ApplyEnterpriseFilter`、`ApplySellerShopFilter`、`ApplyOwnerShopFilter` 等函数。
|
||
|
||
---
|
||
|
||
*Structure analysis: 2026-03-27*
|