mirror of https://gitee.com/pnoker/iot-dc3.git synced 2026-09-19 02:04:37 +08:00

Files

T

pnoker 1fa2d6f0cf docs(comments): fill the real comment gaps across the repository

A comment-health audit driven by an AST scanner (regex scanners kept
false-positiving on annotation-separated javadoc; the AST pass with
constructor and @Override-implementation exemptions is what produced a
trustworthy worklist) ended with a much smaller true gap than the raw
numbers suggested: class-level javadoc is already at 100% repository-wide.

What actually gets filled here:

- AnalyticsModel: all 30 nested records of the S19 analytics facet get
  maintainer-voice javadoc (the @Schema descriptions serve the API side;
  these serve code readers).
- The whole entity/ext family (29 files, 47 nested classes): every
  Content/Ui/Validation/Security/AppliesTo/Template/Dedup/... schema
  class states what it actually holds — read from the fields, not
  templated.
- Adapter families: the @Bean methods of all six MQ adapters, all four
  TSDB adapters and the three DB dialect adapters get one-line
  maintainer docs (what binds to what, what is overridable).
- Nested support types across data/agentic/constant/public/facade:
  NotifyBindKey, CacheTuning, Credential, dashboard VOs' Item/BucketVO,
  ExpireListener (plus its null-doc placeholder javadoc replaced with a
  real contract), agentic chat/stream VOs' choice/delta/usage shapes,
  tool-context records, RequestHeader envelopes, FleetSummary,
  visualization Type/Scale codes.
- PointValueSampleConverter's boundary methods now state the port-side
  contract (quality default injection point, batch order preservation).

Comment drift fixed: the class javadoc of the can/mqtt/opc-da driver
skeletons claimed "see TODO markers in method bodies" — those markers
do not exist; the claims are corrected to plain work-in-progress notes.
The genuine TODOs (zigbee API verification, lwm2m lookup, ethernet-ip
CIP framing, CAN JNI) stay: they mark real unimplemented behavior.

Vendored-code boundary: the opc-da module carries a ported
org.openscada library (46 files, package org.openscada.*). Its trivial
accessors stay bare on purpose — filler comments on get/set pairs are
exactly the kind of noise this pass exists to remove — but the
non-obvious JIStruct wire-decoder methods (getStruct/fromStruct
FILETIME + three DO wrappers) now document the COM bridge shape.

Gates: full-repo compile green; data/model/constant/agentic/public
test suites green.

2026-08-24 21:23:39 +08:00

src

style(javadoc): document non-override public methods

2026-08-19 00:05:58 +08:00

pom.xml

feat: update pom version to 2026.5.22

2026-05-26 00:30:11 +08:00

README.md

docs(comments): fill the real comment gaps across the repository

2026-08-24 21:23:39 +08:00

README.md

DC3 Gateway

Overview

dc3-gateway is the API Gateway of the IoT DC3 platform, built on Spring Cloud Gateway (WebFlux). It serves as the single ingress point for all external HTTP traffic, providing rate limiting, authentication verification, service routing, and reverse proxying.

Module Information

Group ID: io.github.pnoker
Artifact ID: dc3-gateway
Package: io.github.pnoker.gateway

Service Ports

Protocol	Port	Override
HTTP	`8000`	`DC3_GATEWAY_PORT`

Key Responsibilities

Request Routing: Routes /api/v3/{service}/** requests to the corresponding center service via StripPrefix=2
Authentication Filter: Authentic filter validates Bearer tokens with the Auth Center before forwarding protected routes
Service Addressing: Routes to backend centers via static addresses, overridable through GATEWAY_ROUTE_* / CENTER_*_HOST environment variables (no service registry)
gRPC Client: Connects to dc3-center-auth (port 9300) for token validation
OAuth2 / MCP Ingress: Exposes the Auth Center's OAuth2 authorization-server and MCP discovery endpoints

Routing Rules

Routes are matched in definition order (first match wins); the public token and OAuth metadata routes are deliberately defined before the /api/v3/auth/** wildcard.

Path Pattern	Backend Service	Auth Required
`/.well-known/oauth-authorization-server`, `/oauth2/jwks`, `/oauth2/token`, `/oauth2/revoke`, `/oauth2/register`	`dc3-center-auth`	No
`/oauth2/authorize`	`dc3-center-auth`	Yes
`/api/v3/auth/token/**`	`dc3-center-auth`	No
`/api/v3/auth/**`	`dc3-center-auth`	Yes
`/api/v3/manager/**`	`dc3-center-manager`	Yes
`/api/v3/data/**`	`dc3-center-data`	Yes
`/api/v3/agentic/**`	`dc3-center-agentic`	Yes

The /oauth2/** and /.well-known/** routes expose the Auth Center's OAuth2 authorization-server and MCP discovery endpoints for MCP clients.

Dependencies

Business logic is shared via dc3-common-gateway:

<dependency>
    <groupId>io.github.pnoker</groupId>
    <artifactId>dc3-common-gateway</artifactId>
</dependency>

Configuration

application.yml — base port, active profile, facade mode, SpringDoc aggregation
application-dev.yml — dev env: profile group and debug logging
application-pre.yml — pre-release overrides
application-pro.yml — production: disables SpringDoc / Swagger UI

Route definitions and the auth gRPC channel are shared in dc3-common-gateway's application-gateway.yml (overridable via GATEWAY_ROUTE_* / CENTER_*_HOST env vars).

Running Locally

1. Start Infrastructure

make up-db

2. Build

mvn -s .mvn/settings.xml -pl dc3-gateway -am package

3. Run after the required center services are available

java -jar dc3-gateway/target/dc3-gateway.jar

Testing

Run the module tests from the repository root:

mvn -s .mvn/settings.xml -pl dc3-gateway -am test

dc3-common-gateway — Authentic filter implementation and gateway utilities
dc3-api-auth — gRPC API contracts for token validation
dc3-center-auth — Token validation backend

README.md

DC3 Gateway

Overview

Module Information

Service Ports

Key Responsibilities

Routing Rules

Dependencies

Configuration

Running Locally

1. Start Infrastructure

2. Build

3. Run after the required center services are available

Testing

Related Modules