csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Files
Iteration/7-11
junhong_cmp_fiber/.planning/codebase/STRUCTURE.md

11 KiB
Raw Permalink Blame History

Codebase Structure

Analysis Date: 2026-03-27

Directory Layout

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

Reference in New Issue View Git Blame Copy Permalink