优化结构

CLAUDE.md

@@ -62,15 +62,10 @@ design rather than add the import.
 
 **service (DTO ↔ DO)**
 
-- `convert<Resource>` parses an incoming proto into a DO. The reverse
-  direction is built inline at the return site; the reply type is
-  whatever the proto declares — usually the resource itself
-  (`return &v1.<Resource>{...}, nil`), sometimes a list wrapper
-  (`*v1.<Resources>Set`), or `&emptypb.Empty{}` for deletes. Inlining
-  keeps each handler self-contained.
-- Embed `Unimplemented<Resource>ServiceServer`.
-- Parse AIP list requests via `filtering` / `ordering` / `pagination`;
-  apply `fieldmask.Update` for partial updates.
+- Convert hand-written HTTP DTOs into domain objects at the service boundary,
+  and build response DTOs from returned domain objects.
+- Keep handlers focused on binding, authentication context, response envelopes,
+  and transport-specific limits.
 - Validate request inputs at the service boundary before delegating to the
   usecase.
 - Return `biz` errors. No business rules, no storage access, no PO.
@@ -109,18 +104,16 @@ design rather than add the import.
 
 ### Add-a-resource checklist
 
-1. **DTO**: define `Create<Resource>` / `Get<Resource>` /
-   `List<Resources>` / `Update<Resource>` / `Delete<Resource>` in
-   `api/<domain>/<version>/`, then `make api`.
+1. **DTO**: define request and response types in `internal/service/dto/`.
 2. **DO + repo interface**: declare both in `biz`; build the usecase on
    top of the interface.
 3. **Repo impl**: implement in `data` returning `biz.<Resource>Repo`;
    add a PO and the matching conversion helpers when storage shape
    diverges from DO.
-4. **Wiring**: register the repo constructor in `data.ProviderSet`, the
-   usecase in `biz.ProviderSet`, the service in `service.ProviderSet`;
-   register HTTP/gRPC services in `internal/server`.
-5. **Regenerate**: `make all` to refresh Wire and `go.mod`.
+4. **Transport**: add the service adapter, handler, router registration, and
+   routecatalog metadata.
+5. **Wiring**: register providers in the relevant sets.
+6. **Regenerate**: `make generate` or `make all` to refresh Wire and `go.mod`.
 
 ### Testing seam
 
@@ -130,8 +123,7 @@ tests exercise repo implementations at the storage boundary.
 
 ## Generation & generated files
 
-Regenerate via `make api` or `make all`; never hand-edit
-`*.pb.go`, `*_grpc.pb.go`, `*_http.pb.go`, or `wire_gen.go`.
+Regenerate via `make generate` or `make all`; never hand-edit `wire_gen.go`.
 
 ## Naming & error reasons
 
@@ -141,8 +133,8 @@ Regenerate via `make api` or `make all`; never hand-edit
   `<Resource>Service`. PO types live inside `internal/data/`; pick a
   name that fits the storage driver and convert with
   `new<Resource>(do)` / `toBiz(po)` free functions.
-- Error reasons: declared in `api/<domain>/<version>/error_reason.proto`,
-  surfaced as `Err<Resource><Cause>` in `biz`.
+- Error reasons use stable strings and are surfaced as `Err<Resource><Cause>` in
+  `biz`.
 
 ## Commits & security