mirror of https://gitee.com/pnoker/iot-dc3.git synced 2026-11-03 03:32:08 +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/main/protobuf/api/common/data

feat(tsdb): rewire the data center onto the tsdb port and retire the repository module

2026-08-20 21:58:01 +08:00

pom.xml

refactor(api): reorganize proto files from center to common package

2026-07-09 12:43:48 +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 API Data

dc3-api-data defines gRPC contracts for values, commands, events, status, and system-health queries. Generated Java types use io.github.pnoker.api.center.data; proto sources live under src/main/protobuf/api/common/data/.

Services

Service	RPCs	Purpose
`PointValueApi`	`GetLastValue`, `ListHistoryValues`, `ListSeriesVolumes`	query point values and value-volume series
`PointValueApi`	`ReadCommand`, `WriteCommand`	submit point read/write commands
`CommandHistoryApi`	`CallCommand`, `GetByRecordId`, `ListByPage`	dispatch and query command history
`EventHistoryApi`	`ReportEvent`, `GetByRecordId`, `ListByPage`	report and query event history
`StatusHealthApi`	`DeviceStatusesByIds`, `DeviceStatusesByProfileId`	query device status snapshots
`StatusHealthApi`	`DriverStatusesByIds`, `DriverDeviceStatusSummary`	query driver status snapshots and device summaries
`StatusHealthApi`	`SystemHealth`	query the platform health snapshot

Single-result RPCs use GetXxx; collection/page results use ListXxx or an explicitly named status aggregation. Do not reintroduce legacy SelectXxx names.

Consumers and implementation

dc3-common-data implements the data-side servers.
dc3-common-facade-grpc wraps generated stubs in transport-independent facades.
Manager and other business modules should call the facade API rather than construct channels directly.

All write/report requests must carry tenant context through the transport and into the business layer.

Build and Verification

mvn -s .mvn/settings.xml -q -pl dc3-api/dc3-api-data -am compile

This contract module has no module-specific tests. Compile it after proto changes, then run the matching server and facade tests in dc3-common-data and dc3-common-facade-grpc.