- driver replicas are per-instance nodes with their own RabbitMQ
command queues (group=dc3.driver.client, key service.node), not
workers over shared queues; FAQ now also states Compose/Swarm keep
protocol drivers at 1 replica (shared driver_data / SQLite outbox)
- fail-fast gate covers AUTH_HMAC_SECRET only; DC3_SECURITY_KEY is
non-empty-checked, so a weak default still boots
- 6271 is intended as the device UDP channel but every publish site
omits /udp / protocol: UDP and actually publishes TCP - say so
- k8s scaling note: scaled driver pods are independent nodes, not one
shared worker pool
- swarm runbook: pushing dependency images is a multi-node requirement,
a local build is fine on a single node
- USAGE.md: NODE_ENV bullet narrowed to weak AUTH_HMAC_SECRET rejected
- add ble, can, dlt645, dnp3, iec61850, kafka, knx, lorawan, mbus, redis, and zigbee to the k8s driver list, kustomization, helm values, and compose service stacks
- regenerate k8s driver deployments and preserve the listening-virtual ports in the generator
- replace the per-driver named volumes with one shared driver_data volume isolated by mount path, matching the scale/swarm stacks
- correct scaling docs: compose scale/swarm drivers stay at one replica because replicas would share one SQLite outbox file
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.
Prose rewrapping and table reflow from a project-wide markdown pass;
no content changes. Also reverts two formatter mistakes: restores
MD5(password) in dc3-web/AGENTS.md and drops spurious spaces after
CJK punctuation in README.zh.md / README.ja.md.
Covers root guides (AGENTS/CONTRIBUTING/SECURITY/README.*), module
READMEs across dc3-api/center/common/driver/e2e/gateway, the nginx
guide, dc3/doc/{README,TITLE}.md, and dc3-web docs.
* chore(docs): move docs site to standalone pnoker/iot-dc3-docs repo
The VitePress docs site now lives in pnoker/iot-dc3-docs and serves docs.dc3.site from there. Remove the in-repo docs/ and all docs-only build/deploy wiring so nothing dangles.
- delete docs/ (source moved to pnoker/iot-dc3-docs)
- delete .github/workflows/docs.yml (deploy owned by iot-dc3-docs)
- drop npm /docs dependabot block; clean codeql/.gitignore docs paths
- remove Makefile docs-* targets
- relocate AI testing policy into dc3-web/tests/ so the required Web guardrail test is self-contained (was reading ../docs/...)
- rewire README image refs (7 READMEs) and in-repo doc links (README.ai.md, AGENTS.md, dc3/doc/README.md) to https://docs.dc3.site / the new repo
dc3/doc/{TITLE,CHANGE,USAGE}.md STAY - release tooling (make changelog, docker-ci) regenerates them; the docs repo snapshots them.
* fix(docs): repair pre-existing broken doc links found during migration
- 8 READMEs: /en|zh/introduction/technology-stack -> /en|zh/development/technology-stack (page lives under development/, not introduction/)
- dc3-web/tests/README.md: ../docs/test-debugging.md (missing) -> https://docs.dc3.site/en/frontend/test-debugging
Update auth, gateway, architecture, quickstart, changelog, and superpowers design documents for the Principal identity model and OAuth-backed MCP server.
The MkDocs Material site felt visually dated. Switch to VitePress to
get a fresher default theme (the same one Vue, Vite, Pinia and
Element Plus use) and align the docs toolchain with the project's
Node ecosystem.
- Replace mkdocs.yml/requirements-docs.txt with package.json
(pnpm scripts), pinned vitepress 1.5+, and pnpm-lock.yaml.
- Add docs/.vitepress/config.mts: zh-CN, /iot-dc3/ base, cleanUrls,
per-section sidebars, local search with Chinese UI strings, edit
link, light/dark theme labels in Chinese.
- Rewrite docs/index.md as layout: home with hero, six feature
cards, and platform/architecture/license blocks underneath.
- docs/assets/ -> docs/public/ rename (VitePress static-asset
convention). This rename was already absorbed by an unrelated
upstream commit; only the architecture page reference is updated
to /images/architecture-cn.png.
- Convert MkDocs snippets to VitePress <!--@include:-->:
- community/{contributing,code-of-conduct,security} pull repo-root
governance files,
- development/changelog and guide/usage pull the docker-ci-
referenced dc3/doc/{CHANGE,USAGE}.md.
- Wrap R<T> in inline code in architecture/modules.md so the Vue
parser does not treat it as an unclosed HTML tag.
- Rewrite .github/workflows/docs.yml: pnpm/action-setup@v4 +
setup-node@v4 (pnpm cache) + pnpm install --frozen-lockfile +
pnpm docs:build + upload-pages-artifact (docs/.vitepress/dist)
+ deploy-pages. Trigger paths include docs/, package.json,
pnpm-lock.yaml, governance files, and the two dc3/doc/ files
referenced via include.
- Update .gitignore: drop /site/ and the Python-only venv entries,
add docs/.vitepress/{cache,dist}/ and a Node/pnpm section.
- Adjust dc3/doc/README.md wording to mention VitePress include
syntax instead of MkDocs snippets.
Verification: pnpm install + pnpm docs:build pass locally (5.44s);
the include-based pages (community/contributing, development/
changelog, guide/usage) render content from their source files; all
per-section sidebars resolve.
The release-note source TITLE.md still carried outdated wording
("project development", "device integration and management") and
omitted the "AI-ready" positioning that README.md and the four
localized READMEs (zh/ja/vi) all promote as a core value proposition.
docker-ci.yml inlines this file into the GitHub Release body, so the
inconsistency surfaces every time we cut a release.
Realign the second paragraph with README.md:16-19 while keeping the
${SERVICE_VERSION} placeholder and the relative architecture image
path so docker-ci.yml's perl-based assembly continues to work.
Set up an end-to-end documentation site so contributors and users have
a unified, searchable, and publishable entry point for project docs.
- Add mkdocs.yml: Chinese-first language, light/dark palette, tabbed
navigation, indexed sections, glightbox for diagrams, and
pymdownx.snippets so community pages can pull from root governance
files (CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md) without
duplicating content.
- Add requirements-docs.txt pinning mkdocs-material and
mkdocs-glightbox.
- Build the docs/ skeleton: index, quickstart, guide, architecture,
development, modules, community. Migrate the seven generic manuals
from dc3/doc/ (QUICKSTART, ENVIRONMENT, LOGGING, TROUBLESHOOTING,
MODULES, DRIVER-AUTHORING, TESTING) and rewire their cross-doc
links. CHANGE.md, TITLE.md, and USAGE.md stay in dc3/doc/ because
docker-ci.yml depends on them; the docs site references them via
mkdocs snippets to keep a single source of truth.
- Add .github/workflows/docs.yml that builds with --strict on push to
release and deploys via actions/deploy-pages.
- Rewrite dc3/doc/README.md as a migration pointer to the new site
and to the three retained release-flow files.
Verification: mkdocs build --strict passes locally; snippets render
correctly; GitHub Pages already enabled in workflow mode via gh api.
Align all READMEs, AGENTS.md, CONTRIBUTING.md and dc3/doc/* with the
new Makefile interface (SERVICES/GROUP selectors, REGISTRY=cn, podman
default) and updated Dockerfile structure.
Refresh module READMEs, AGENTS.md, CONTRIBUTING.md, and dc3/doc/
guides to reflect the unified Dockerfile, consolidated compose stacks,
and updated build instructions.
Driver SPI used the cryptic RValue/WValue names for read/write payload
envelopes. Rename them to ReadPointValue/WritePointValue so the public
contract reads naturally, add a sibling CalculatedPointValue for values
that need their derived/scaled form to flow alongside the raw sample,
and pull the value-type conversion utility into a dedicated
support/TypedValueConverter helper instead of leaving it inline.
DriverCustomService.read/write signatures and the seven driver
implementations (modbus-tcp, mqtt, opc-da, opc-ua, plcs7, virtual,
listening-virtual) move to the new types in lockstep so every consumer
of the SDK keeps compiling. Tests are renamed and resequenced to match,
and the driver authoring guide reflects the new identifiers.
Introduce dc3/doc/TESTING.md as the canonical reference for the iot-dc3
test pyramid, naming conventions, time/randomness isolation rules,
Testcontainers conventions pinned to the production timescaledb-ha:pg18
image, fixture data strategy, contract base classes shipped by
dc3-common-test, the make commands developers run locally and the
ci.yml/test.yml/e2e.yml workflow contract.
Update AGENTS.md so:
- The Validation Checklist references make test, make test-it,
make coverage and proto contract tests; coverage regressions over 1%
block PRs.
- The Documentation Rules section now lists TESTING.md alongside the
other domain-specific docs to keep the guide current as the harness
evolves.
This closes the S0 stage of the test build-out: every subsequent stage
(S1..S8) will deliver business test cases under the layout defined here.
Rename the generic DriverCustomServiceImpl in each driver module to a
protocol-specific name (e.g., ModbusTcpDriverCustomServiceImpl) so
that static analysis tools can scan every driver module without
filtering duplicate fully-qualified class names. Update
DRIVER-AUTHORING.md to reflect the new convention.
The HMAC signing feature was dormant because no deployment config
set the shared secret. Add AUTH_HMAC_SECRET to .env.example, dev
env files, both compose stacks (all 12 services), and document it
in ENVIRONMENT.md.
pnoker