- Add mcp-server.md: full design for exposing OpenAPI interfaces as MCP
tools through the gateway, covering architecture, database model,
permission control (reusing dc3_resource/dc3_role_resource_bind),
HTTP vs gRPC analysis, dynamic tool refresh, and observability
- Register MCP Service in VitePress sidebar config
- Add entry to design index page
Separate the public docs (how to understand, deploy, and use IoT DC3) from
engineering material (design drafts, analyses, roadmaps, legacy operation
screenshots):
- add an internal archive area with its own nav, grouping design,
analysis, strategy, backlog, and legacy-operation sections
- migrate design, operation (data/device/driver/template), analyses, and
todo notes into the archive, preserving history
- refresh public docs: README (en/zh/ja/vi), operation guides
(agentic/concepts/data-commands/device-onboarding), architecture,
development, guide, quickstart, and modules
- promote the project overview to README.ai.md at the repo root
- Add docs/development/api-documentation.md describing the Swagger UI layout,
per-center grouping, auth headers, and production exposure.
- Add a `make openapi` target + dc3/bin/export_openapi.sh to snapshot each
center's OpenAPI JSON from a running stack.
- Update AGENTS.md: OpenAPI/Swagger conventions, and correct the enum-suffix
examples (multi-valued sets use *TypeEnum, not *FlagEnum).
Introduce CommandAttribute/EventAttribute with config variants:
- REST controllers, MyBatis mappers, services, and DAL managers
- gRPC client/server builders and proto message definitions
- DTOs, BOs, DOs, VOs for type-safe data transfer layer
fix: add explicit ::text casts in json_build_object parameters
PostgreSQL cannot infer parameter types inside json_build_object()
calls. Add ::text casts to #{stateExtType} and #{stateDescription}
to resolve "could not determine data type of parameter $10" errors.
refactor: restructure driver gRPC client and metadata layer
- Rename GrpcStubConfig to DriverClientStubConfig with dedicated DTOs
- Extract attribute builders from inline gRPC conversion logic
- Consolidate driver metadata, register service, and command handling
- Update device state heartbeat and command result event handling
docs: add multilingual architecture diagram and sync READMEs
- Translate architecture SVG into zh, ja, vi variants
- Update README architecture image references per language
- Add missing service-level shortcut sections to ja/vi READMEs
- Add IoT DC3 layered architecture diagram (SVG + HTML viewer)
with Application / Management / Data / Driver layers,
Security & Load and Platform & System sidebars,
Data→Driver connection flows, and color-coded sections
- Reposition README descriptions across all languages (en, zh, ja, vi)
and pom.xml to AI-ready narrative: "Connects devices, collects
data organized for AI, and orchestrates the closed loop"
- Add README.ai.md with Chinese multi-paragraph AI narrative
and closed-loop flowchart
- Optimize package.json metadata (name, license, scripts)
Add EVENT target type to AlarmTargetTypeFlagEnum, wire event report
into the alarm rule pipeline, add RabbitMQ contract E2E tests for
command call and event report, and create design documentation.
P0: Replace content JSON-string with sealed PointCommandPayload + record DTOs.
P0: Accept write() boolean return, suppress echo on failure.
P1: Return commandId from POST endpoints, add RESTful GET /{commandId}.
P1: Add driver-online check via EntityStateMapper, PointCommandValidator.
P2: Add DeviceLockManager for per-device serialized command execution.
P3: Add POST /list API with pagination, commandId idempotency support.
- Replace two duplicate enums with single EntityStatusEnum (same index/code)
- Rename DB columns: state_flag→entity_state_flag, state_ext→entity_state_ext
- Add stateDescription field to DeviceStateDTO/DriverStateDTO for diagnostics
- Add description field to DeviceHealthState/DriverHealthState
- UPSERT SQL now writes stateDescription into entity_state_ext on heartbeat
- Remove EntityStateStatus interface (no longer needed with single enum)
- Update MQ layer, heartbeat services, status queries, gRPC, and all tests
Replace local Caffeine cache as the source of truth for driver and
device online status with dc3_entity_state, a persistent state lease
table backed by PostgreSQL.
- Add EntityStateDO/Mapper/Manager persistence stack.
- Add EntityStateExpiryScanner that scans expire_time every 15 seconds
with lease_version recheck to avoid stale alarm writes.
- Dual-write heartbeat path: DriverStateServiceImpl and
DeviceStateServiceImpl now write dc3_entity_state first, then local
cache.
- All status queries (controllers, gRPC server, local facade,
SystemHealthServiceImpl) read from dc3_entity_state. Rows missing or
past expire_time return offline.
- OfflineExpiryListener gains a DB dedup check to skip expiry events
already handled by the scanner.
- Add @EnableScheduling to DataApplication.
- Add design doc docs/design/entity-state.md with full DDL.
This resolves restart state loss, multi-instance inconsistency, and
races between expiry checks and fresh heartbeats.
The dc3-docs VuePress 1.x source repository has the original
Markdown for the operation manual. Migrate four pages whose
content survives unchanged in the current product flow:
driver / template / device / data, plus a hand-written
operation/index.md as the section landing page. Add the
corresponding Web UI screenshots under docs/public/images/legacy/
(the full assets/images tree from the old site, ~169 files).
- Replace the Ant Design Vue <a-alert> component in data.md with
a VitePress ::: tip container.
- Rewrite /assets/images/ to /images/legacy/ so paths resolve
under VitePress's public/ static-asset convention with the
/iot-dc3/ base.
- Add a "操作手册" entry to the top nav and a per-section sidebar
in .vitepress/config.mts.
Skipped from dc3-docs:
- operation/0-index.md - "待开发中" placeholder.
- function/{api,driver}.md - "🚧施工中🚧" placeholders.
- function/0-directory.md - obsolete (refers to dc3-common as a
separate repo and lists mongo/redis/mysql common modules that
no longer exist).
- function/storage.md - lists mongodb/influxdb/opentsdb as
supported storage; the project ships PostgreSQL only.
Verification: pnpm docs:build passes (5.26s). The five operation
pages render; image src attributes resolve to
/iot-dc3/images/legacy/operation/<page>/<uuid>.png and the files
exist in dist/.
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.
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.
Captures the steps for adding a new dc3-driver-* module — module
layout, the dc3-common-driver base classes to extend, gRPC registration
with Manager, RabbitMQ routing-key conventions tied to the driver
service name, and the application.yml conventions the rest of the
platform expects.
- docs/MODULES.md: full module dependency map and runtime flow
- docs/QUICKSTART.md: one-stop local development setup
- docs/TROUBLESHOOTING.md: common build/runtime issues and fixes
- Add docs links to README.md, README.zh.md, README.ja.md, README.vi.md
pnoker