From f301e41c6ebcd3943ee207b9dc4bc1745e8a8aa2 Mon Sep 17 00:00:00 2001 From: pnoker Date: Sun, 28 Jun 2026 19:04:31 +0800 Subject: [PATCH] style: apply consistent formatting to docs, config, and root files Line wrapping, table alignment, blank line consistency across config.mts, i18n, locale JSONs, FAQ, quickstart, frontend/development guides, superpowers plans, README variants, and PR template. --- .github/PULL_REQUEST_TEMPLATE.md | 2 + README.ja.md | 3 +- README.md | 3 +- docs/.vitepress/config.mts | 53 +++- docs/.vitepress/i18n.ts | 2 +- docs/locales/en.json | 15 -- docs/locales/zh.json | 15 -- .../2026-06-18-settings-entity-list-engine.md | 36 +-- .../plans/2026-06-28-todo-polish.md | 227 ++++++++++-------- docs/zh/community/faq.md | 34 ++- docs/zh/development/index.md | 36 +-- docs/zh/frontend/index.md | 28 ++- docs/zh/quickstart/index.md | 13 +- 13 files changed, 253 insertions(+), 214 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 2380eaf7f..731945659 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -9,11 +9,13 @@ ## Verification ### 后端 (Java / Maven) + - [ ] `mvn -B -DskipTests compile` 通过 - [ ] 新增 / 修改的行为有测试覆盖 - [ ] 文档已更新（如有 API / 行为变更） ### 前端 (dc3-web) + - [ ] `pnpm lint-check && pnpm check && pnpm build` 通过 - [ ] 大范围改动通过 `pnpm run test:ci` 覆盖门槛 - [ ] E2E 数据动态创建并清理，无固定业务 ID diff --git a/README.ja.md b/README.ja.md index 012c6c02a..628749890 100644 --- a/README.ja.md +++ b/README.ja.md @@ -247,7 +247,8 @@ cp .env.example .env # テンプレートをコピー | **デスクトップ** | Tauri 2 | | **デプロイ** | Podman · Docker Compose | -> 💡 フロントエンドのソースコードは本リポジトリの `dc3-web/` ディレクトリにあります（旧スタンドアロンリポジトリ `iot-dc3-web` はアーカイブ済み）。 +> 💡 フロントエンドのソースコードは本リポジトリの `dc3-web/` ディレクトリにあります（旧スタンドアロンリポジトリ +`iot-dc3-web` はアーカイブ済み）。 ## 📖 ドキュメントとコミュニティ diff --git a/README.md b/README.md index 1f3c932dc..19a9b6b03 100644 --- a/README.md +++ b/README.md @@ -249,7 +249,8 @@ and API paths. Clear boundaries that scale across services and teams. | **Desktop** | Tauri 2 | | **Deployment** | Podman · Docker Compose | -> 💡 Frontend source code is in the `dc3-web/` directory of this repository (the standalone `iot-dc3-web` repo is archived). +> 💡 Frontend source code is in the `dc3-web/` directory of this repository (the standalone `iot-dc3-web` repo is +> archived). ## 📖 Documentation and Community diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 53af796ec..a6703c610 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -17,7 +17,7 @@ import {defineConfig} from 'vitepress' import {withMermaid} from 'vitepress-plugin-mermaid' -import {t, Lang} from './i18n' +import {Lang, t} from './i18n' // ── i18n via locales/{lang}.json ── // All user-facing strings are resolved through t(lang, key). @@ -40,8 +40,14 @@ const PILLARS: ReadonlyArray = [ paths: ['introduction', 'quickstart'], activeMatch: '^/(zh|en)/(introduction|quickstart)/', groups: [ {key: '', items: [['introduction'], ['introduction/concepts'], ['introduction/paths']]}, - {key: 'group.objects-data', items: [['introduction/concepts/profile'], ['introduction/concepts/device'], ['introduction/concepts/driver'], ['introduction/concepts/point'], ['introduction/concepts/point-value']]}, - {key: 'group.capabilities-boundaries', items: [['introduction/concepts/command'], ['introduction/concepts/event'], ['introduction/concepts/attribute-config'], ['introduction/concepts/tenant']]}, + { + key: 'group.objects-data', + items: [['introduction/concepts/profile'], ['introduction/concepts/device'], ['introduction/concepts/driver'], ['introduction/concepts/point'], ['introduction/concepts/point-value']] + }, + { + key: 'group.capabilities-boundaries', + items: [['introduction/concepts/command'], ['introduction/concepts/event'], ['introduction/concepts/attribute-config'], ['introduction/concepts/tenant']] + }, {key: 'group.quickstart', items: [['quickstart'], ['quickstart/environment'], ['quickstart/first-device']]}, {key: 'group.appendix', items: [['introduction/glossary'], ['introduction/license']]} ] @@ -52,7 +58,10 @@ const PILLARS: ReadonlyArray = [ groups: [ {key: '', items: [['architecture']]}, {key: 'group.services-collab', items: [['architecture/services'], ['architecture/facade-modes']]}, - {key: 'group.pipelines-model', items: [['architecture/data-plane'], ['architecture/command-plane'], ['architecture/auth-rbac'], ['architecture/domain-model']]}, + { + key: 'group.pipelines-model', + items: [['architecture/data-plane'], ['architecture/command-plane'], ['architecture/auth-rbac'], ['architecture/domain-model']] + }, {key: 'group.modules', items: [['architecture/modules'], ['modules']]} ] }, @@ -62,11 +71,23 @@ const PILLARS: ReadonlyArray = [ activeMatch: '^/(zh|en)/(drivers/|operation/device-onboarding)', groups: [ {key: 'group.onboarding', items: [['drivers'], ['operation/device-onboarding']]}, - {key: 'group.industrial-bus', items: [['drivers/modbus-tcp'], ['drivers/modbus-rtu'], ['drivers/opc-ua'], ['drivers/opc-da'], ['drivers/plcs7'], ['drivers/melsec'], ['drivers/fins'], ['drivers/ethernet-ip']]}, - {key: 'group.scada-power', items: [['drivers/bacnet-ip'], ['drivers/iec104'], ['drivers/dlms'], ['drivers/sl651'], ['drivers/snmp']]}, - {key: 'group.iot-wireless', items: [['drivers/mqtt'], ['drivers/coap'], ['drivers/lwm2m'], ['drivers/http'], ['drivers/ble'], ['drivers/zigbee'], ['drivers/can']]}, + { + key: 'group.industrial-bus', + items: [['drivers/modbus-tcp'], ['drivers/modbus-rtu'], ['drivers/opc-ua'], ['drivers/opc-da'], ['drivers/plcs7'], ['drivers/melsec'], ['drivers/fins'], ['drivers/ethernet-ip']] + }, + { + key: 'group.scada-power', + items: [['drivers/bacnet-ip'], ['drivers/iec104'], ['drivers/dlms'], ['drivers/sl651'], ['drivers/snmp']] + }, + { + key: 'group.iot-wireless', + items: [['drivers/mqtt'], ['drivers/coap'], ['drivers/lwm2m'], ['drivers/http'], ['drivers/ble'], ['drivers/zigbee'], ['drivers/can']] + }, {key: 'group.serial-network', items: [['drivers/serial'], ['drivers/tcp-udp']]}, - {key: 'group.database', items: [['drivers/mysql'], ['drivers/postgresql'], ['drivers/oracle'], ['drivers/sqlserver']]}, + { + key: 'group.database', + items: [['drivers/mysql'], ['drivers/postgresql'], ['drivers/oracle'], ['drivers/sqlserver']] + }, {key: 'group.virtual-test', items: [['drivers/virtual'], ['drivers/listening-virtual']]}, {key: 'group.appendix-drivers', items: [['drivers/matrix']]} ] @@ -84,10 +105,15 @@ const PILLARS: ReadonlyArray = [ ] }, { // ⑤ - navKey: 'pillar.develop', landing: 'development', - paths: ['development', 'frontend', 'ai', 'automation'], activeMatch: '^/(zh|en)/(development|frontend|ai|automation)/', + navKey: 'pillar.develop', + landing: 'development', + paths: ['development', 'frontend', 'ai', 'automation'], + activeMatch: '^/(zh|en)/(development|frontend|ai|automation)/', groups: [ - {key: 'group.development', items: [['development'], ['development/driver-authoring'], ['development/api-documentation'], ['development/testing'], ['development/changelog']]}, + { + key: 'group.development', + items: [['development'], ['development/driver-authoring'], ['development/api-documentation'], ['development/testing'], ['development/changelog']] + }, {key: 'group.ai-integration', items: [['ai'], ['ai/agentic'], ['ai/mcp']]}, {key: 'group.frontend', items: [['frontend'], ['frontend/test-debugging']]}, {key: 'group.automation', items: [['automation/cli']]} @@ -98,7 +124,10 @@ const PILLARS: ReadonlyArray = [ paths: ['operation', 'guide'], activeMatch: '^/(zh|en)/(operation|guide)/', groups: [ {key: 'group.operations', items: [['operation'], ['operation/data-commands'], ['operation/alarms']]}, - {key: 'group.deploy-ops', items: [['guide/usage'], ['guide/observability'], ['guide/logging'], ['guide/troubleshooting']]} + { + key: 'group.deploy-ops', + items: [['guide/usage'], ['guide/observability'], ['guide/logging'], ['guide/troubleshooting']] + } ] } ] diff --git a/docs/.vitepress/i18n.ts b/docs/.vitepress/i18n.ts index 876fff353..7bed52781 100644 --- a/docs/.vitepress/i18n.ts +++ b/docs/.vitepress/i18n.ts @@ -13,7 +13,7 @@ import en from '../locales/en.json' export type Lang = 'zh' | 'en' -const bundles: Record> = { zh, en } +const bundles: Record> = {zh, en} /** Resolve a translation key for the given language. Falls back to zh if key or lang is missing. */ export function t(lang: Lang, key: string): string { diff --git a/docs/locales/en.json b/docs/locales/en.json index 3fd940977..f3d8c1c3c 100644 --- a/docs/locales/en.json +++ b/docs/locales/en.json @@ -5,9 +5,7 @@ "pillar.foundations": "Foundations", "pillar.develop": "Develop", "pillar.operations": "Operations", - "community": "Community", - "introduction": "Overview", "introduction/concepts": "Core Concepts", "introduction/paths": "Choose Your Path", @@ -22,11 +20,9 @@ "introduction/concepts/tenant": "Tenant", "introduction/glossary": "Glossary", "introduction/license": "License", - "quickstart": "Local Development", "quickstart/environment": "Environment Variables", "quickstart/first-device": "First Device", - "foundations": "IoT Technology Overview", "foundations/sensing": "Sensing & Measurement", "foundations/identification": "Auto-ID & Positioning", @@ -36,7 +32,6 @@ "foundations/data-pipeline": "Time-Series & Streaming", "foundations/aiot": "Data Intelligence & AIoT", "foundations/security": "IoT Security", - "architecture": "Overview", "architecture/services": "Services & Topology", "architecture/facade-modes": "Facade Modes", @@ -46,10 +41,8 @@ "architecture/domain-model": "Domain Model", "architecture/modules": "Module Map", "modules": "Catalog", - "drivers": "Drivers", "operation/device-onboarding": "Device Onboarding", - "drivers/modbus-tcp": "Modbus TCP", "drivers/modbus-rtu": "Modbus RTU", "drivers/opc-ua": "OPC UA", @@ -79,7 +72,6 @@ "drivers/virtual": "Virtual", "drivers/listening-virtual": "Listening Virtual", "drivers/matrix": "Driver Capability Matrix", - "operation": "Overview", "operation/data-commands": "Data & Commands", "operation/alarms": "Alarms & Notifications", @@ -87,27 +79,21 @@ "guide/observability": "Observability", "guide/logging": "Logging", "guide/troubleshooting": "Troubleshooting", - "development": "Overview", "development/driver-authoring": "Driver Authoring", "development/api-documentation": "API Documentation", "development/testing": "Testing", "development/changelog": "Changelog", - "ai": "AI Overview", "ai/agentic": "Agentic Center", "ai/mcp": "AI Agent / MCP", - "automation/cli": "CLI Guide", - "frontend": "Frontend Guide", "frontend/test-debugging": "Test Debugging FAQ", - "community/contributing": "Contributing", "community/code-of-conduct": "Code of Conduct", "community/security": "Security", "community/faq": "FAQ", - "group.objects-data": "Objects & Data", "group.capabilities-boundaries": "Capabilities & Boundaries", "group.quickstart": "Quick Start", @@ -134,7 +120,6 @@ "group.ai-integration": "AI Integration", "group.automation": "Automation", "group.frontend": "Frontend", - "ui.editLinkText": "Edit this page on GitHub", "ui.outlineLabel": "On this page", "ui.lastUpdatedText": "Last updated", diff --git a/docs/locales/zh.json b/docs/locales/zh.json index bc5283a92..f8c77c705 100644 --- a/docs/locales/zh.json +++ b/docs/locales/zh.json @@ -5,9 +5,7 @@ "pillar.foundations": "基础", "pillar.develop": "开发", "pillar.operations": "运维", - "community": "社区", - "introduction": "总览", "introduction/concepts": "核心概念", "introduction/paths": "按角色选择路径", @@ -22,11 +20,9 @@ "introduction/concepts/tenant": "租户", "introduction/glossary": "术语表", "introduction/license": "开源与许可", - "quickstart": "本地开发", "quickstart/environment": "环境变量", "quickstart/first-device": "第一个设备", - "foundations": "物联网技术总览", "foundations/sensing": "传感与测量", "foundations/identification": "自动识别与定位", @@ -36,7 +32,6 @@ "foundations/data-pipeline": "时序数据与流处理", "foundations/aiot": "数据智能与 AIoT", "foundations/security": "物联网安全", - "architecture": "总览", "architecture/services": "服务与拓扑", "architecture/facade-modes": "Facade 模式", @@ -46,10 +41,8 @@ "architecture/domain-model": "领域模型", "architecture/modules": "模块地图", "modules": "模块清单", - "drivers": "驱动总览", "operation/device-onboarding": "设备接入流程", - "drivers/modbus-tcp": "Modbus TCP", "drivers/modbus-rtu": "Modbus RTU", "drivers/opc-ua": "OPC UA", @@ -79,7 +72,6 @@ "drivers/virtual": "虚拟 Virtual", "drivers/listening-virtual": "监听虚拟", "drivers/matrix": "驱动能力矩阵", - "operation": "概览", "operation/data-commands": "数据与命令", "operation/alarms": "告警与通知", @@ -87,27 +79,21 @@ "guide/observability": "可观测性", "guide/logging": "日志规范", "guide/troubleshooting": "故障排查", - "development": "概览", "development/driver-authoring": "驱动开发", "development/api-documentation": "API 文档", "development/testing": "测试", "development/changelog": "变更日志", - "ai": "AI 概览", "ai/agentic": "Agentic 中心", "ai/mcp": "AI Agent / MCP", - "automation/cli": "CLI 使用指南", - "frontend": "前端开发指南", "frontend/test-debugging": "测试调试 FAQ", - "community/contributing": "贡献指南", "community/code-of-conduct": "行为准则", "community/security": "安全策略", "community/faq": "常见问题", - "group.objects-data": "对象与数据", "group.capabilities-boundaries": "能力与边界", "group.quickstart": "快速开始", @@ -134,7 +120,6 @@ "group.ai-integration": "AI 集成", "group.automation": "自动化", "group.frontend": "前端", - "ui.editLinkText": "在 GitHub 上编辑此页", "ui.outlineLabel": "页面导航", "ui.lastUpdatedText": "最后更新于", diff --git a/docs/superpowers/plans/2026-06-18-settings-entity-list-engine.md b/docs/superpowers/plans/2026-06-18-settings-entity-list-engine.md index 958197685..6591564d4 100644 --- a/docs/superpowers/plans/2026-06-18-settings-entity-list-engine.md +++ b/docs/superpowers/plans/2026-06-18-settings-entity-list-engine.md @@ -198,9 +198,9 @@ export interface EntityListConfig { - `openEdit`：以 `defaultForm()` 为底，按 `fields` 覆盖 `row` 值，写入 `id`/`version`。 - `openDetail`：`config.detail` 存在则 `router.push({ name: config.detail.routeName, query: { id: String(row.id) } })`。 - `formatCell(row, column)`： - - 取值支持点路径（`column.prop.split('.').reduce(...)`）。 - - `column.formatter` 优先（传 `{ t, relations }`）。 - - `kind==='time'`→`timestampLabel`；`kind==='tag'`→`optionLabel(column.options, value)`；空→`'-'`；余→`String`。 + - 取值支持点路径（`column.prop.split('.').reduce(...)`）。 + - `column.formatter` 优先（传 `{ t, relations }`）。 + - `kind==='time'`→`timestampLabel`；`kind==='tag'`→`optionLabel(column.options, value)`；空→`'-'`；余→`String`。 - `tagType(value)`：`ENABLE/SUCCESS/NORMAL/AUTO→success`、`DISABLE/FAILED/FIRING→danger`、 `PENDING/RETRYING/RECOVERED→warning`、余 `info`（enable 列实际用 ``，此函数供普通 tag 列）。 - `canEdit(row)=config.rowEditable?config.rowEditable(row):true`；`canDelete` 同理。 @@ -232,9 +232,9 @@ const optionLabel = (options: EntityOption[] | undefined, value: unknown) => { - `defineProps<{ config: EntityListConfig }>()`，调用 `useEntityListPage(props.config)`。 - 搜索区 `#filters` 改为 `v-for="field in config.searchFields"`： - - `kind==='enableFlag'`→``； - - `kind==='select'`→``； - - 余→``。 + - `kind==='enableFlag'`→``； + - `kind==='select'`→``； + - 余→``。 - 表格：`v-if="config.mode==='tree'"` 的 ``；否则分页 ``。两者列循环相同。 @@ -253,8 +253,8 @@ const optionLabel = (options: EntityOption[] | undefined, value: unknown) => { - 颜色色块样式 `.entity-list__swatch` 迁自原 Label/LabelDetail 的 `.label-color__swatch`。 - [ ] **Step 2: 写 composable 单测** `tests/unit/use-entity-list-page.test.ts`：mock 一个最小 config（含 1 个 list 返回固定 - records、1 个 search 字段、2 列），断言 `query()` 注入搜索参数、`formatCell` 对 time/tag/空值的输出、`payload()` 对 json - 字段的解析。遵守 guardrails：kebab 文件名、小写动词 `it()` 描述、无 `toBeTruthy`、fixture 放 `tests/fixtures/`。 + records、1 个 search 字段、2 列），断言 `query()` 注入搜索参数、`formatCell` 对 time/tag/空值的输出、`payload()` 对 json + 字段的解析。遵守 guardrails：kebab 文件名、小写动词 `it()` 描述、无 `toBeTruthy`、fixture 放 `tests/fixtures/`。 - [ ] **Step 3: 验收** `pnpm check` + `pnpm test:unit tests/unit/use-entity-list-page.test.ts` + `pnpm test:guard`。 @@ -385,7 +385,7 @@ export const createLabelConfig = (t: T): EntityListConfig => ({ - CRUD：`listGroup/addGroup/updateGroup/deleteGroup`；detail `settingsGroupDetail`。 - [ ] Step 1 写 `groupConfig.ts` · Step 2 改写 `Group.vue` · Step 3 删旧文件 · Step 4 验收 `pnpm check`+ - `pnpm test:guard`+手测 · Step 5 Commit `refactor(settings): migrate group to entity list engine` + `pnpm test:guard`+手测 · Step 5 Commit `refactor(settings): migrate group to entity list engine` --- @@ -404,7 +404,7 @@ export const createLabelConfig = (t: T): EntityListConfig => ({ - 引擎需正确隐藏 Add 按钮与 edit/delete 操作（`editable:false`），操作列只剩 detail（宽 100）。 - [ ] Step 1 写 config · Step 2 改写 `Api.vue` · Step 3 删旧 · Step 4 验收（重点确认只读：无新增/编辑/删除按钮）· Step 5 - Commit `refactor(settings): migrate read-only api page to entity list engine` + Commit `refactor(settings): migrate read-only api page to entity list engine` --- @@ -441,7 +441,7 @@ config 工厂签名 `createUserConfig(t, { onAssignRoles })`，其中 - CRUD `listUser/addUser/updateUser/deleteUser`；detail `settingsUserDetail`。 - [ ] Step 1 写 config · Step 2 改写 `User.vue`（含 assign 接线）· Step 3 删旧 · Step 4 验收 + 手测（含分配角色弹窗打开）· - Step 5 Commit `refactor(settings): migrate user page to entity list engine` + Step 5 Commit `refactor(settings): migrate user page to entity list engine` --- @@ -460,7 +460,7 @@ config 工厂签名 `createUserConfig(t, { onAssignRoles })`，其中 - CRUD `listRole/addRole/updateRole/deleteRole`；detail `settingsRoleDetail`。 - [ ] Step 1 写 config · Step 2 改写 `Role.vue` · Step 3 删旧 · Step 4 验收 + 手测 · Step 5 Commit - `refactor(settings): migrate role page to entity list engine` + `refactor(settings): migrate role page to entity list engine` --- @@ -499,7 +499,7 @@ config 工厂签名 `createUserConfig(t, { onAssignRoles })`，其中 - CRUD `addResource/updateResource/deleteResource`；detail `settingsResourceDetail`。 - [ ] Step 1 写 config（迁入实体名聚合）· Step 2 改写 `Resource.vue` · Step 3 删旧 · Step 4 验收 + 手测（树展开/分组节点禁编辑/实体名显示）· - Step 5 Commit `refactor(settings): migrate resource tree page to entity list engine` + Step 5 Commit `refactor(settings): migrate resource tree page to entity list engine` --- @@ -517,14 +517,14 @@ config 工厂签名 `createUserConfig(t, { onAssignRoles })`，其中 - 字段：parentMenuId(treeSelect tree.load=listMenuTree required)/menuName(authNameRules max32 required)/menuCode(required max64)/titleZh(required max64)/titleEn(required max64)/menuTypeFlag(select required)/menuLevel(select MENU_LEVEL_OPTIONS required)/menuIndex(number)/icon(select iconNames)/url(input)/enableFlag/remark(textarea)。 - - 注意 add/update payload 需把 titleZh/titleEn/icon/url 组装回 `menuExt.content`（沿用现 edit/index.ts 的组装逻辑）——在 - config 的 `add`/`update` 包装函数里做映射，或在 `defaultForm`/`payload` 钩子处理。本任务在 config 提供 - `add:(p)=>addMenu(toMenuPayload(p))`、`update:(p)=>updateMenu(toMenuPayload(p))`，`toMenuPayload` 迁自现 - edit/index.ts。 + - 注意 add/update payload 需把 titleZh/titleEn/icon/url 组装回 `menuExt.content`（沿用现 edit/index.ts 的组装逻辑）——在 + config 的 `add`/`update` 包装函数里做映射，或在 `defaultForm`/`payload` 钩子处理。本任务在 config 提供 + `add:(p)=>addMenu(toMenuPayload(p))`、`update:(p)=>updateMenu(toMenuPayload(p))`，`toMenuPayload` 迁自现 + edit/index.ts。 - CRUD `addMenu/updateMenu/deleteMenu`；detail `settingsMenuDetail`。 - [ ] Step 1 写 config（迁入 ext 组装 + icon）· Step 2 改写 `Menu.vue` · Step 3 删旧 · Step 4 验收 + 手测（图标列/URL - 列/树展开/编辑回填）· Step 5 Commit `refactor(settings): migrate menu tree page to entity list engine` + 列/树展开/编辑回填）· Step 5 Commit `refactor(settings): migrate menu tree page to entity list engine` --- diff --git a/docs/superpowers/plans/2026-06-28-todo-polish.md b/docs/superpowers/plans/2026-06-28-todo-polish.md index c1a3551e7..4d70de20b 100644 --- a/docs/superpowers/plans/2026-06-28-todo-polish.md +++ b/docs/superpowers/plans/2026-06-28-todo-polish.md @@ -6,11 +6,11 @@ TODO.md 所列 19 项全部验证属实（详见底部验证矩阵）。按影响面和紧急度分为三个批次： -| 批次 | 项数 | 预估工作量 | 描述 | -|------|------|-----------|------| -| P0 救火 | 3 | 0.5h | 语法错误、链接缺失、命名不统一 —— 用户一眼可见的 bug | -| P1 核心 | 10 | 3-5d | 文档质量、UX、内容补充 —— 决定文档站专业度 | -| P2 工程化 | 6 | 2-3d | 开发体验、部署完整性、仓库治理 | +| 批次 | 项数 | 预估工作量 | 描述 | +|--------|----|-------|--------------------------------| +| P0 救火 | 3 | 0.5h | 语法错误、链接缺失、命名不统一 —— 用户一眼可见的 bug | +| P1 核心 | 10 | 3-5d | 文档质量、UX、内容补充 —— 决定文档站专业度 | +| P2 工程化 | 6 | 2-3d | 开发体验、部署完整性、仓库治理 | --- @@ -65,10 +65,12 @@ socialLinks: [ ### #10 "接入" → "驱动" 命名统一 **文件**: + - `iot-dc3/docs/.vitepress/config.mts:153` — `navZh: '接入'` → `navZh: '驱动'` - `iot-dc3/docs/zh/index.md:36` — `title: 接入` → `title: 驱动`，`linkText: 接入设备` → `linkText: 接入设备`（保留，语义不同） -**修法**: PILLARS[3] 的 `navZh` 从 `'接入'` 改为 `'驱动'`。index.md 的 feature card title 同步修改。但 `linkText: '接入设备'` 保留（动词"接入"与名词"驱动"不冲突）。 +**修法**: PILLARS[3] 的 `navZh` 从 `'接入'` 改为 `'驱动'`。index.md 的 feature card title 同步修改。但 `linkText: '接入设备'` +保留（动词"接入"与名词"驱动"不冲突）。 **验证**: 导航栏显示"驱动"，首页 feature 卡片显示"驱动"，sidebar 标题为"接入指南"（保留）。 @@ -80,24 +82,27 @@ socialLinks: [ **范围**: `docs/zh/` 下 16+ 个 .md 文件中的 mermaid 代码块 -**策略**: 沿用项目已有的 `.dc3-diagram` + SVG 组件范式（DataPlane / CommandPlane / AuthFlow / FourLayers 等），将关键图表逐个替换。不是全删 mermaid —— mermaid 作为 Markdown 原生语法的轻量图表在某些场景仍有用（如简单流程图、状态图），但**架构级、数据流级、部署拓扑级**图表必须用组件。 +**策略**: 沿用项目已有的 `.dc3-diagram` + SVG 组件范式（DataPlane / CommandPlane / AuthFlow / FourLayers +等），将关键图表逐个替换。不是全删 mermaid —— mermaid 作为 Markdown 原生语法的轻量图表在某些场景仍有用（如简单流程图、状态图），但 +**架构级、数据流级、部署拓扑级**图表必须用组件。 **替换优先级**: -| priority | 文件 | 当前 mermaid | 替换方案 | -|----------|------|-------------|---------| -| 1 | architecture/index.md | 分层架构图 | 已有 `` 但需增强交互（点击跳转子页面） | -| 2 | architecture/data-plane.md | 数据流时序图 | `` 组件（已有） | -| 3 | architecture/command-plane.md | 命令下发时序图 | `` 组件（已有） | -| 4 | architecture/auth-rbac.md | 鉴权流程图 | `` 组件（已有） | -| 5 | architecture/domain-model.md | ER 图 | 新建 `` 组件 | -| 6 | architecture/services.md | 服务拓扑图 | 新建 `` 组件 | -| 7 | foundations/ 下各页 | 四层架构、协议栈 | `` 组件（已有），其余用新组件 | -| 8 | ai/agentic.md | Agent 交互时序 | 新建 `` 组件 | -| 9 | quickstart/index.md | 启动流程图 | 轻量简单，保留 mermaid（项目内 Bootstrap 类流程图例外） | -| 10 | operation/data-commands.md | 数据流 | 保留 mermaid 或新建精简组件 | +| priority | 文件 | 当前 mermaid | 替换方案 | +|----------|-------------------------------|------------|---------------------------------------| +| 1 | architecture/index.md | 分层架构图 | 已有 `` 但需增强交互（点击跳转子页面） | +| 2 | architecture/data-plane.md | 数据流时序图 | `` 组件（已有） | +| 3 | architecture/command-plane.md | 命令下发时序图 | `` 组件（已有） | +| 4 | architecture/auth-rbac.md | 鉴权流程图 | `` 组件（已有） | +| 5 | architecture/domain-model.md | ER 图 | 新建 `` 组件 | +| 6 | architecture/services.md | 服务拓扑图 | 新建 `` 组件 | +| 7 | foundations/ 下各页 | 四层架构、协议栈 | `` 组件（已有），其余用新组件 | +| 8 | ai/agentic.md | Agent 交互时序 | 新建 `` 组件 | +| 9 | quickstart/index.md | 启动流程图 | 轻量简单，保留 mermaid（项目内 Bootstrap 类流程图例外） | +| 10 | operation/data-commands.md | 数据流 | 保留 mermaid 或新建精简组件 | **架构图组件规范**（参考 memory `dc3-docs-diagram-preference.md`）: + - `.dc3-diagram` 调色板：主色 `#0e9f6e`（品牌绿）、辅色 `#1296db`（品牌蓝）、背景 `#f6f9fc` - 组件放在 `.vitepress/theme/components/` 下 - props: `lang: 'zh' | 'en'` 支持双语 @@ -116,12 +121,13 @@ socialLinks: [ **方案**: VitePress 无内置 lightbox。两种方案： -| 方案 | 优点 | 缺点 | -|------|------|------| -| A. medium-zoom 插件 | 轻量 (~3KB)，无依赖，纯 vanilla | 需在 theme setup 中 `onMounted` 调用 | -| B. VitePress 自定义 wrapper | 无需外部依赖，可定制 | 需手写点击→全屏逻辑 | +| 方案 | 优点 | 缺点 | +|--------------------------|-------------------------|---------------------------------| +| A. medium-zoom 插件 | 轻量 (~3KB)，无依赖，纯 vanilla | 需在 theme setup 中 `onMounted` 调用 | +| B. VitePress 自定义 wrapper | 无需外部依赖，可定制 | 需手写点击→全屏逻辑 | -**推荐方案 A**: 在 `.vitepress/theme/index.ts` 的 `onMounted` 中 `import mediumZoom from 'medium-zoom'` 并 `mediumZoom('.main img')`。 +**推荐方案 A**: 在 `.vitepress/theme/index.ts` 的 `onMounted` 中 `import mediumZoom from 'medium-zoom'` 并 +`mediumZoom('.main img')`。 ```typescript // .vitepress/theme/index.ts @@ -147,6 +153,7 @@ export default { **问题分析**: 当前 VitePress 默认的 Shiki 代码高亮 + 默认排版，代码块与整体品牌调性不一致。 **具体调整项**: + 1. 代码块字体：`'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace`（需要时从 Google Fonts 加载或 fallback 系统字体） 2. 代码块边框颜色：品牌绿 `#0e9f6e` 左边框（4px）配合品牌调色板 3. 行内代码背景色：`rgba(14, 159, 110, 0.08)` @@ -163,9 +170,11 @@ export default { **范围**: `iot-dc3/docs/zh/index.md` + `iot-dc3/README.md` -**当前状态**: `zh/index.md:66` 已有 `` 组件。但 `iot-dc3/README.md` 是纯 Markdown，不能直接用 Vue 组件。 +**当前状态**: `zh/index.md:66` 已有 `` 组件。但 `iot-dc3/README.md` 是纯 Markdown，不能直接用 +Vue 组件。 **方案**: + - `zh/index.md`: 已有 Architecture 组件，确认是否满足需求；增强交互性 - `iot-dc3/README.md`: 用 `dc3/images/` 下的 SVG/PNG 架构图代替（README 是纯 MD，无法用 Vue 组件） @@ -178,20 +187,21 @@ export default { **策略**: 对标 `iot-books/` 中的 IoT 书籍，系统性补充理论深度和实践案例。 **当前状态**: + - `foundations/` 8 页覆盖了四层架构框架，但多为概念简述 - `introduction/` 12 页覆盖核心概念，较完整 - `architecture/` 8 页覆盖关键设计，较完整 **补充计划**: -| 区域 | 当前 | 目标 | 对标书籍 | -|------|------|------|---------| -| foundations/sensing | 基础传感概念 | 补充传感器分类、选型指南、工业传感器校准 | iot-books/sensing-identification/ | -| foundations/fieldbus | 协议列表 | 深入各协议工作原理、适用场景对比矩阵 | iot-books/communication-networking/ | -| foundations/edge-cloud | 浅述 | 补充边缘计算架构设计模式、云边协同策略 | iot-books/platform-cloud-bigdata/ | -| foundations/aiot | 概览 | 补充行业案例（智能制造、能源管理、智慧城市） | iot-books/app-dev-programming/ | -| architecture/domain-model | 概念 | 补充实体生命周期、状态机细节 | - | -| introduction/paths | 角色路径 | 按角色（运维/开发/架构师）细化学习路线 | - | +| 区域 | 当前 | 目标 | 对标书籍 | +|---------------------------|--------|------------------------|-------------------------------------| +| foundations/sensing | 基础传感概念 | 补充传感器分类、选型指南、工业传感器校准 | iot-books/sensing-identification/ | +| foundations/fieldbus | 协议列表 | 深入各协议工作原理、适用场景对比矩阵 | iot-books/communication-networking/ | +| foundations/edge-cloud | 浅述 | 补充边缘计算架构设计模式、云边协同策略 | iot-books/platform-cloud-bigdata/ | +| foundations/aiot | 概览 | 补充行业案例（智能制造、能源管理、智慧城市） | iot-books/app-dev-programming/ | +| architecture/domain-model | 概念 | 补充实体生命周期、状态机细节 | - | +| introduction/paths | 角色路径 | 按角色（运维/开发/架构师）细化学习路线 | - | **工作方式**: 每项约 1-2h 研读书籍 + 0.5-1h 撰写。 @@ -204,16 +214,19 @@ export default { **文件**: `iot-dc3/docs/.vitepress/config.mts:35-271` **当前顺序** (PILLARS 数组): + ``` 总览 → 基础 → 架构 → 接入 → 运维 → 开发 ``` **期望顺序**: + ``` 总览 → 架构 → 驱动 → 基础 → 开发 → 运维 ``` -**修法**: 调整 PILLARS 数组的顺序，并确保 `activeMatch` 和 sidebar `paths` 配置相应调整。`首页` 已在 nav builder 中作为第一项，不需改动。 +**修法**: 调整 PILLARS 数组的顺序，并确保 `activeMatch` 和 sidebar `paths` 配置相应调整。`首页` 已在 nav builder +中作为第一项，不需改动。 **风险评估**: 中等。移动 pillar 位置需要同步调整 sidebar 的 `paths` 和 `activeMatch` 正则，避免导航高亮错位。 @@ -226,12 +239,14 @@ export default { **问题**: `zh/frontend/` 目录下有 4 个文件但**不在 sidebar 中**，且无启动指南。 **方案**: + 1. 新建 `zh/frontend/index.md` — 前端启动说明（安装 pnpm、配置环境变量、`pnpm dev`、端口说明） 2. 将 `frontend-testing-guardrails.md` 和 `test-debugging.md` 整理为正式文档 3. 删除 `bad.md`（反例开发笔记） 4. 在 `config.mts` 的 PILLARS 中新增 frontend pillar 或并入 Development pillar **前端 pillar 结构**: + ``` 开发 pillar ├── development/ ← 已存在 @@ -252,17 +267,18 @@ export default { **问题**: 文档站正式发布的页面中无任何前端界面截图。 **方案**: + 1. 启动前端 `pnpm dev` → 浏览器截图 2. 关键页面清单： - - 登录页 (`/login`) - - 仪表盘主页 (`/home`) - - 设备列表 (`/device`) - - 设备详情 (`/device/:id`) - - 驱动列表 (`/driver`) - - 位号管理 (`/point`) - - 物模型管理 (`/profile`) - - 系统设置 (`/settings`) - - AI 对话 (`/chat`) + - 登录页 (`/login`) + - 仪表盘主页 (`/home`) + - 设备列表 (`/device`) + - 设备详情 (`/device/:id`) + - 驱动列表 (`/driver`) + - 位号管理 (`/point`) + - 物模型管理 (`/profile`) + - 系统设置 (`/settings`) + - AI 对话 (`/chat`) 3. 截图放 `docs/public/images/screenshots/` 4. 在对应文档页中引用 @@ -309,24 +325,25 @@ operation/ **文件**: 新建 `zh/community/faq.md` **内容大纲**: + 1. **许可证与授权** - - AGPL-3.0 对我有什么影响？ - - 商业授权如何获取？ - - 可以闭源二次开发吗？ + - AGPL-3.0 对我有什么影响？ + - 商业授权如何获取？ + - 可以闭源二次开发吗？ 2. **收费问题** - - IoT DC3 本身收费吗？ - - 有哪些付费服务？ + - IoT DC3 本身收费吗？ + - 有哪些付费服务？ 3. **技术选型** - - 为什么用 Java 而不是 Go/Node.js？ - - 为什么用 PostgreSQL 而不是 MySQL？ - - 支持哪些设备协议？怎么选择？ + - 为什么用 Java 而不是 Go/Node.js？ + - 为什么用 PostgreSQL 而不是 MySQL？ + - 支持哪些设备协议？怎么选择？ 4. **部署运维** - - 最低硬件要求？ - - 如何从开发环境迁移到生产？ - - 数据备份怎么做？ + - 最低硬件要求？ + - 如何从开发环境迁移到生产？ + - 数据备份怎么做？ 5. **社区参与** - - 如何参与贡献？ - - 遇到问题怎么求助？ + - 如何参与贡献？ + - 遇到问题怎么求助？ **验证**: `pnpm --filter docs docs:dev` 确认 Q&A 页面渲染正确，sidebar 可见。 @@ -339,6 +356,7 @@ operation/ **问题**: `iot-dc3/README.md` 引用 `dc3/images/logo-blue.png`，需确认是否为最新品牌 logo。 **操作**: + 1. 确认最新的 logo 文件位置（`docs/public/images/logo.svg`？`dc3/images/logo-blue.png`？） 2. 如果是 SVG 版本，`iot-dc3/README.md` 中 `` 标签引用 SVG 3. 确保 GitHub README 渲染正常（GitHub 支持 SVG） @@ -350,10 +368,12 @@ operation/ ### #3 仓库合并与 Web 归档 **问题**: monorepo 已有 `iot-dc3-web/`（在 `iot-dc3/dc3-web/` 下）和 `dc3-cli/`，但： + - `zh/index.md:77-78` 仍引用 `https://github.com/pnoker/iot-dc3-web` 外部仓库 - 未在 README 中说明 web 项目后续由后端 monorepo 统一管理 **方案**: + 1. 更新 `zh/index.md` 技术栈中的外部链接，改为 `./dc3-web/` 相对路径或直接描述 2. 在 `iot-dc3/README.md` 中添加说明：前端已并入 monorepo，原 `iot-dc3-web` 独立仓库已归档 3. 检查 `iot-dc3-web/` 独立仓库是否需要添加归档说明 @@ -367,19 +387,20 @@ operation/ **问题**: `quickstart/` 虽有 3 个文件，但对 JetBrains IDEA 用户不够友好。 **补充内容**: + 1. **IDEA 导入步骤**（截图+文字）： - - Open → 选择 `iot-dc3/pom.xml` → Open as Project - - 等待 Maven 索引完成 + - Open → 选择 `iot-dc3/pom.xml` → Open as Project + - 等待 Maven 索引完成 2. **EnvFile 插件安装与配置**： - - 插件市场搜索 "EnvFile" - - Run Configuration → EnvFile tab → 添加 `dc3/env/dev.env` + - 插件市场搜索 "EnvFile" + - Run Configuration → EnvFile tab → 添加 `dc3/env/dev.env` 3. **IDEA 运行配置**： - - 各服务的 Spring Boot Run Configuration - - 各服务的端口、VM options、program arguments + - 各服务的 Spring Boot Run Configuration + - 各服务的端口、VM options、program arguments 4. **常见 IDEA 问题**： - - Lombok 注解处理器未启用 - - Maven 索引卡住 - - 模块未被识别 + - Lombok 注解处理器未启用 + - Maven 索引卡住 + - 模块未被识别 **验证**: 按文档步骤在 IDEA 中操作可成功启动。 @@ -392,16 +413,17 @@ operation/ **诊断**: 当前文档假设读者已熟悉 Spring Boot 生态和 Maven 多模块项目，对不熟悉这些的开发者门槛过高。 **补充内容**: + 1. **开发指南**: - - "第一行代码" 教程：从克隆到提交一个最简单的 Controller - - 多模块项目导航：哪个模块干什么、依赖关系图 - - 常用 Maven 命令速查 - - 调试技巧（IDEA 远程调试、日志级别调整） + - "第一行代码" 教程：从克隆到提交一个最简单的 Controller + - 多模块项目导航：哪个模块干什么、依赖关系图 + - 常用 Maven 命令速查 + - 调试技巧（IDEA 远程调试、日志级别调整） 2. **贡献指南**: - - 从 Issue 到 PR 的完整流程视频/截图 - - PR 模板解读：每项填什么 - - CI 失败怎么排查 - - 代码评审常见反馈及修法 + - 从 Issue 到 PR 的完整流程视频/截图 + - PR 模板解读：每项填什么 + - CI 失败怎么排查 + - 代码评审常见反馈及修法 **验证**: 让初级开发者按文档操作，收集反馈。 @@ -412,12 +434,14 @@ operation/ **文件**: 新增 `iot-dc3/.mvn/wrapper/maven-wrapper.properties` + `mvnw` + `mvnw.cmd` **操作**: + ```bash cd iot-dc3 mvn wrapper:wrapper -Dtype=only-script # 只生成 wrapper 脚本，保持已有 .mvn/settings.xml ``` **注意事项**: + - 保留已有的 `.mvn/settings.xml`、`maven.config`、`jvm.config`、`settings-container.xml` - `maven-wrapper.properties` 中指定 Maven 版本（与项目当前 Maven 3.9+ 一致） - 更新 `AGENTS.md` 中的命令从 `mvn` 改为 `./mvnw` @@ -435,15 +459,16 @@ mvn wrapper:wrapper -Dtype=only-script # 只生成 wrapper 脚本，保持已 **补充清单**（按优先级）: -| 批次 | 驱动 | 理由 | -|------|------|------| -| 1 | bacnet-ip, fins, melsec, ethernet-ip | 工业总线类高频使用 | -| 2 | iec104, sl651, snmp, dlms | 电力/SCADA 类 | -| 3 | coap, lwm2m, http, ble, zigbee, can | IoT/无线类 | -| 4 | serial, tcp-udp | 通用接入 | -| 5 | mysql, postgresql, oracle, sqlserver | 数据库类 | +| 批次 | 驱动 | 理由 | +|----|--------------------------------------|------------| +| 1 | bacnet-ip, fins, melsec, ethernet-ip | 工业总线类高频使用 | +| 2 | iec104, sl651, snmp, dlms | 电力/SCADA 类 | +| 3 | coap, lwm2m, http, ble, zigbee, can | IoT/无线类 | +| 4 | serial, tcp-udp | 通用接入 | +| 5 | mysql, postgresql, oracle, sqlserver | 数据库类 | **每个驱动 compose 服务模板**: + ```yaml dc3-driver-: image: ${DC3_IMAGE_REGISTRY:-pnoker}/dc3-driver-:${DC3_IMAGE_TAG:-2026.6} @@ -478,24 +503,24 @@ Week 3-4: P1 #5 #8 #13 #14 (3-5d) ← 最大工作量 ## 附录: 验证矩阵 -| # | TODO | 验证结果 | 证据位置 | -|---|------|---------|---------| -| 1 | 缺 Gitee/Twitter | ✅ 真实 | `config.mts:500` 仅 GitHub | -| 2 | logo 未更新 | ✅ 真实 | `iot-dc3/README.md:14` 引用 `logo-blue.png` | -| 3 | 仓库合并/归档 | ⚠️ 部分完成 | monorepo 已有 web+cli，但 index.md 仍引外部仓库 | -| 4 | 架构图组件 | ✅ 真实 | 仅 1 个 `` 组件，README 无图 | -| 5 | mermaid 体验差 | ✅ 真实 | 16+ 文件用 mermaid | -| 6 | 无图片放大 | ✅ 真实 | docs 未找到 zoom/lightbox | -| 7 | 代码片段样式 | ✅ 真实 | style.css 无代码块定制 | -| 8 | 内容不足 | ✅ 真实 | foundations 各页偏概念简述 | -| 9 | 快速开始不细 | ✅ 真实 | 3 文件，无 IDEA 截图步骤 | -| 10 | 接入→驱动 | ⚠️ 部分完成 | 目录已是 drivers，nav 仍写"接入" | -| 11 | 菜单顺序 | ✅ 真实 | 当前: 总览→基础→架构→接入→运维→开发 | -| 12 | 缺前端启动 | ✅ 真实 | frontend 目录不在 sidebar 中 | -| 13 | 缺前端截图 | ✅ 真实 | docs 中图片引用为 0 | -| 14 | 缺用户手册 | ✅ 真实 | 无图文逐页操作手册 | -| 15 | `**` 语法错误 | ✅ 真实 | `zh/index.md:72-73` | -| 16 | 缺 Q&A | ✅ 真实 | community 无 faq.md | -| 17 | 指南太简单 | ✅ 真实 | 179+136行偏概念化 | -| 18 | Maven Wrapper | ✅ 真实 | 有 `.mvn/` 但无 `mvnw` | -| 19 | compose 驱动不全 | ✅ 真实 | 8/28 驱动在 compose 中 | +| # | TODO | 验证结果 | 证据位置 | +|----|-----------------|---------|-------------------------------------------| +| 1 | 缺 Gitee/Twitter | ✅ 真实 | `config.mts:500` 仅 GitHub | +| 2 | logo 未更新 | ✅ 真实 | `iot-dc3/README.md:14` 引用 `logo-blue.png` | +| 3 | 仓库合并/归档 | ⚠️ 部分完成 | monorepo 已有 web+cli，但 index.md 仍引外部仓库 | +| 4 | 架构图组件 | ✅ 真实 | 仅 1 个 `` 组件，README 无图 | +| 5 | mermaid 体验差 | ✅ 真实 | 16+ 文件用 mermaid | +| 6 | 无图片放大 | ✅ 真实 | docs 未找到 zoom/lightbox | +| 7 | 代码片段样式 | ✅ 真实 | style.css 无代码块定制 | +| 8 | 内容不足 | ✅ 真实 | foundations 各页偏概念简述 | +| 9 | 快速开始不细 | ✅ 真实 | 3 文件，无 IDEA 截图步骤 | +| 10 | 接入→驱动 | ⚠️ 部分完成 | 目录已是 drivers，nav 仍写"接入" | +| 11 | 菜单顺序 | ✅ 真实 | 当前: 总览→基础→架构→接入→运维→开发 | +| 12 | 缺前端启动 | ✅ 真实 | frontend 目录不在 sidebar 中 | +| 13 | 缺前端截图 | ✅ 真实 | docs 中图片引用为 0 | +| 14 | 缺用户手册 | ✅ 真实 | 无图文逐页操作手册 | +| 15 | `**` 语法错误 | ✅ 真实 | `zh/index.md:72-73` | +| 16 | 缺 Q&A | ✅ 真实 | community 无 faq.md | +| 17 | 指南太简单 | ✅ 真实 | 179+136行偏概念化 | +| 18 | Maven Wrapper | ✅ 真实 | 有 `.mvn/` 但无 `mvnw` | +| 19 | compose 驱动不全 | ✅ 真实 | 8/28 驱动在 compose 中 | diff --git a/docs/zh/community/faq.md b/docs/zh/community/faq.md index c9adc0b80..fd9ede853 100644 --- a/docs/zh/community/faq.md +++ b/docs/zh/community/faq.md @@ -10,21 +10,23 @@ title: 常见问题 IoT DC3 基于 [AGPL-3.0](https://github.com/pnoker/iot-dc3/blob/release/LICENSE-AGPL.txt) 协议发布。 -AGPL-3.0 的核心要求：如果你修改了平台代码并**通过网络提供服务**（包括 SaaS、内部系统），你必须将修改后的完整源代码开源。如果只是内部使用、未分发、未通过网络提供服务，则无需开源。 +AGPL-3.0 的核心要求：如果你修改了平台代码并**通过网络提供服务**（包括 +SaaS、内部系统），你必须将修改后的完整源代码开源。如果只是内部使用、未分发、未通过网络提供服务，则无需开源。 ### AGPL-3.0 对我们公司意味着什么？ -| 场景 | 是否需要开源 | -|------|-------------| -| 内部部署、不改代码、仅自己用 | 否 | -| 内部部署、改了代码、仅自己用（未对外提供服务） | 否（但建议贡献回来） | -| 基于 DC3 做 SaaS 产品对外售卖 | **是**，必须开源全部修改 | -| 基于 DC3 做了二次开发并分发给客户部署 | **是**，必须开源全部修改 | -| 只是调用 DC3 的 API，未修改 DC3 本身 | 否 | +| 场景 | 是否需要开源 | +|---------------------------|----------------| +| 内部部署、不改代码、仅自己用 | 否 | +| 内部部署、改了代码、仅自己用（未对外提供服务） | 否（但建议贡献回来） | +| 基于 DC3 做 SaaS 产品对外售卖 | **是**，必须开源全部修改 | +| 基于 DC3 做了二次开发并分发给客户部署 | **是**，必须开源全部修改 | +| 只是调用 DC3 的 API，未修改 DC3 本身 | 否 | ### 可以闭源二次开发吗？ -如果你只是通过 API 调用 DC3、没有修改 DC3 源码本身，你的调用方代码可以闭源。一旦你修改了 DC3 源码并通过网络对外提供服务，AGPL-3.0 要求你将修改开源。 +如果你只是通过 API 调用 DC3、没有修改 DC3 源码本身，你的调用方代码可以闭源。一旦你修改了 DC3 源码并通过网络对外提供服务，AGPL-3.0 +要求你将修改开源。 ### 有商业授权吗？ @@ -40,7 +42,8 @@ AGPL-3.0 的核心要求：如果你修改了平台代码并**通过网络提供 ### 项目方如何盈利？ -目前 IoT DC3 是维护者的个人开源项目，以社区驱动方式运作。未来可能的商业化方向包括：技术支持服务、企业定制开发、SaaS 托管服务等。核心平台本身将始终保持开源。 +目前 IoT DC3 是维护者的个人开源项目，以社区驱动方式运作。未来可能的商业化方向包括：技术支持服务、企业定制开发、SaaS +托管服务等。核心平台本身将始终保持开源。 ### 使用 IoT DC3 需要付费给谁吗？ @@ -89,11 +92,13 @@ IoT DC3 对 PostgreSQL 的依赖很深，这三个扩展（TimescaleDB + AGE + p ### 最低硬件要求？ **开发环境**（仅依赖栈 PostgreSQL + RabbitMQ）： + - CPU: 2 核 - 内存: 4 GB - 磁盘: 20 GB **生产环境**（全栈：网关 + 4 个中心 + N 个驱动 + 依赖栈）： + - CPU: 8 核及以上 - 内存: 16 GB 及以上 - 磁盘: 100 GB SSD 及以上（时序数据持续增长，需规划扩容） @@ -138,7 +143,8 @@ podman exec dc3-postgres pg_dump -U dc3 \ ### 驱动一定要用 Java 吗？ -Driver SDK 本身是 Java 的，但你也可以通过 **MQTT 桥接** 或 **HTTP 代理** 的方式用任意语言实现设备接入：非 Java 程序将数据发到 MQTT Topic → MQTT 驱动订阅 → 进入平台数据管道。不过这种方式会丢失 SDK 内置的状态管理、自动重连、健康上报等能力。 +Driver SDK 本身是 Java 的，但你也可以通过 **MQTT 桥接** 或 **HTTP 代理** 的方式用任意语言实现设备接入：非 Java 程序将数据发到 +MQTT Topic → MQTT 驱动订阅 → 进入平台数据管道。不过这种方式会丢失 SDK 内置的状态管理、自动重连、健康上报等能力。 --- @@ -153,11 +159,13 @@ IoT DC3 的 Agentic 中心（基于 Spring AI）让大模型具备以下能力 - **告警分析**：AI 分析告警历史，给出根因推断 - **数据洞察**：对时序数据做趋势分析和异常检测 -AI 能力通过 MCP（Model Context Protocol）协议暴露，可被 Claude Desktop、VS Code、Cursor 等 AI 工具直接调用。详见 [AI 概览](../ai/)。 +AI 能力通过 MCP（Model Context Protocol）协议暴露，可被 Claude Desktop、VS Code、Cursor 等 AI +工具直接调用。详见 [AI 概览](../ai/)。 ### 支持哪些大模型？ -通过 Spring AI，理论上支持所有主流模型提供商：OpenAI、Anthropic Claude、Google Gemini、阿里通义千问、百度文心一言、本地 Ollama 模型等。具体配置见 [Agentic 中心](../ai/agentic)。 +通过 Spring AI，理论上支持所有主流模型提供商：OpenAI、Anthropic Claude、Google Gemini、阿里通义千问、百度文心一言、本地 Ollama +模型等。具体配置见 [Agentic 中心](../ai/agentic)。 --- diff --git a/docs/zh/development/index.md b/docs/zh/development/index.md index 6e8b0de12..cfcbac2b6 100644 --- a/docs/zh/development/index.md +++ b/docs/zh/development/index.md @@ -130,14 +130,14 @@ docs(env): explain JetBrains IDEA environment variables ## 常用 Maven 命令速查 -| 场景 | 命令 | 说明 | -|------|------|------| -| 全量编译 | `mvn -s .mvn/settings.xml compile` | 只编译，不跑测试 | -| 快速编译检查 | `mvn -s .mvn/settings.xml -q -DskipTests compile` | 安静模式，改完快速验证 | -| 全量打包 | `mvn -s .mvn/settings.xml clean package` | 编译+测试+打包 | -| 跳测试打包 | `mvn -s .mvn/settings.xml -DskipTests clean package` | 不跑测试 | -| 单模块打包 | `mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-virtual package` | -pl 指定模块 | -| 查看依赖树 | `mvn -s .mvn/settings.xml dependency:tree -pl <模块>` | 排查传递冲突 | +| 场景 | 命令 | 说明 | +|--------|----------------------------------------------------------------------|-------------| +| 全量编译 | `mvn -s .mvn/settings.xml compile` | 只编译，不跑测试 | +| 快速编译检查 | `mvn -s .mvn/settings.xml -q -DskipTests compile` | 安静模式，改完快速验证 | +| 全量打包 | `mvn -s .mvn/settings.xml clean package` | 编译+测试+打包 | +| 跳测试打包 | `mvn -s .mvn/settings.xml -DskipTests clean package` | 不跑测试 | +| 单模块打包 | `mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-virtual package` | -pl 指定模块 | +| 查看依赖树 | `mvn -s .mvn/settings.xml dependency:tree -pl <模块>` | 排查传递冲突 | ::: tip 并行构建 `.mvn/maven.config` 已配 `-T 1C`，不需要手动加。 @@ -153,16 +153,16 @@ VM options 添加 `-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address ### 模块导航速查 -| 我要... | 去这里 | -|---------|--------| -| 改设备/驱动/位号业务逻辑 | `dc3-center/dc3-center-manager` | -| 改认证/租户/RBAC | `dc3-center/dc3-center-auth` | -| 改位号值存储/命令分发 | `dc3-center/dc3-center-data` | -| 改 AI 对话/工具调用 | `dc3-center/dc3-center-agentic` | -| 改网关路由/过滤器 | `dc3-gateway` | -| 新加协议驱动 | `dc3-driver/`，从 `dc3-driver-virtual` 复制 | -| 改 gRPC proto | `dc3-api/`，改完重新 `mvn compile` | -| 改前端页面 | `dc3-web/`（独立 pnpm 项目）| +| 我要... | 去这里 | +|---------------|-----------------------------------------| +| 改设备/驱动/位号业务逻辑 | `dc3-center/dc3-center-manager` | +| 改认证/租户/RBAC | `dc3-center/dc3-center-auth` | +| 改位号值存储/命令分发 | `dc3-center/dc3-center-data` | +| 改 AI 对话/工具调用 | `dc3-center/dc3-center-agentic` | +| 改网关路由/过滤器 | `dc3-gateway` | +| 新加协议驱动 | `dc3-driver/`，从 `dc3-driver-virtual` 复制 | +| 改 gRPC proto | `dc3-api/`，改完重新 `mvn compile` | +| 改前端页面 | `dc3-web/`（独立 pnpm 项目） | ## 延伸阅读 diff --git a/docs/zh/frontend/index.md b/docs/zh/frontend/index.md index 621d29a9e..abf21bb24 100644 --- a/docs/zh/frontend/index.md +++ b/docs/zh/frontend/index.md @@ -8,10 +8,10 @@ IoT DC3 前端基于 **Vue 3 + TypeScript + Vite + Element Plus** 构建，源 ## 环境准备 -| 工具 | 最低版本 | 说明 | -|------|---------|------| -| Node.js | 20 LTS | 推荐使用 fnm/nvm 管理版本 | -| pnpm | 9+ | 包管理器，项目 `packageManager` 字段已锁定版本 | +| 工具 | 最低版本 | 说明 | +|---------|--------|----------------------------------| +| Node.js | 20 LTS | 推荐使用 fnm/nvm 管理版本 | +| pnpm | 9+ | 包管理器，项目 `packageManager` 字段已锁定版本 | ```bash # 安装 pnpm（如未安装） @@ -36,6 +36,7 @@ pnpm dev ``` 开发服务器启动后： + - 前端页面：`http://localhost:8080` - 默认代理后端 API 到 `http://localhost:8000`（网关端口） - 修改后端地址：编辑 `vite.config.ts` 中的 proxy 配置 @@ -47,6 +48,7 @@ pnpm dev # 在仓库根目录 make up-dev # 起网关 + 4 个中心 + 常用驱动 ``` + ::: ## 项目结构 @@ -101,15 +103,15 @@ dc3_menu 表写入 → 前端路由注册 → i18n 翻译 → 权限点绑定 ## 常用命令 -| 命令 | 说明 | -|------|------| -| `pnpm dev` | 启动开发服务器 | -| `pnpm build` | 生产构建 | -| `pnpm preview` | 预览生产构建 | -| `pnpm test` | 运行单元测试 | -| `pnpm test:e2e` | 运行 E2E 测试（Playwright） | -| `pnpm lint` | ESLint 检查 | -| `pnpm type-check` | TypeScript 类型检查 | +| 命令 | 说明 | +|-------------------|-----------------------| +| `pnpm dev` | 启动开发服务器 | +| `pnpm build` | 生产构建 | +| `pnpm preview` | 预览生产构建 | +| `pnpm test` | 运行单元测试 | +| `pnpm test:e2e` | 运行 E2E 测试（Playwright） | +| `pnpm lint` | ESLint 检查 | +| `pnpm type-check` | TypeScript 类型检查 | ## 测试 diff --git a/docs/zh/quickstart/index.md b/docs/zh/quickstart/index.md index 39fa3da61..676c76502 100644 --- a/docs/zh/quickstart/index.md +++ b/docs/zh/quickstart/index.md @@ -41,17 +41,18 @@ JDK/构建工具，外加一个容器运行时。 打开入口类，点击 `main` 左侧绿色按钮 → **Modify Run Configuration**，在 EnvFile 标签页添加 `dc3/env/dev.env`： -| 服务 | 入口类 | 模块 | -|------|--------|------| -| Gateway | `GatewayApplication` | `dc3-gateway` | -| Auth 中心 | `AuthApplication` | `dc3-center/dc3-center-auth` | +| 服务 | 入口类 | 模块 | +|------------|----------------------|---------------------------------| +| Gateway | `GatewayApplication` | `dc3-gateway` | +| Auth 中心 | `AuthApplication` | `dc3-center/dc3-center-auth` | | Manager 中心 | `ManagerApplication` | `dc3-center/dc3-center-manager` | -| Data 中心 | `DataApplication` | `dc3-center/dc3-center-data` | +| Data 中心 | `DataApplication` | `dc3-center/dc3-center-data` | | Agentic 中心 | `AgenticApplication` | `dc3-center/dc3-center-agentic` | ### 4. 启动顺序 -1. **Auth 中心**（8300）→ 2. **Manager 中心**（8400）→ 3. **Data 中心**（8500）→ 4. **Agentic 中心**（8600）→ 5. **Gateway**（8000） +1. **Auth 中心**（8300）→ 2. **Manager 中心**（8400）→ 3. **Data 中心**（8500）→ 4. **Agentic 中心**（8600）→ 5. **Gateway** + （8000） ### 5. 常见问题