From fd04bf7886aa4eba68b247dd7c1092894a5282da Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Sat, 17 Oct 2026 09:04:19 +0800
Subject: [PATCH 01/14] =?UTF-8?q?feat(qaops):=20=E6=8E=A5=E5=85=A5?=
=?UTF-8?q?=E7=8B=AC=E7=AB=8B=E5=8F=AA=E8=AF=BB=E9=97=AE=E7=AD=94=E6=9F=A5?=
=?UTF-8?q?=E8=AF=A2=E4=B8=8E=E6=B2=BB=E7=90=86=E8=A6=86=E7=9B=96=E5=A4=8D?=
=?UTF-8?q?=E6=A3=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
.env.example | 12 +
CHANGELOG.md | 4 +-
api/openapi.yaml | 55 ++-
cmd/api/main.go | 11 +
cmd/api/qa_ops.go | 21 +
cmd/api/qa_ops_test.go | 18 +
internal/dobotaiops/acl.go | 159 +++++++
internal/dobotaiops/config.go | 104 +++++
internal/dobotaiops/coverage_test.go | 26 ++
internal/dobotaiops/dobotaiops_test.go | 309 +++++++++++++
internal/dobotaiops/dsn.go | 107 +++++
internal/dobotaiops/dto.go | 125 +++++
internal/dobotaiops/fixture_env_test.go | 101 +++++
internal/dobotaiops/pool.go | 225 +++++++++
internal/dobotaiops/prod_verify_test.go | 163 +++++++
internal/dobotaiops/records.go | 243 ++++++++++
.../dobotaiops/records_integration_test.go | 78 ++++
.../dobotaiops/records_prod_verify_test.go | 90 ++++
internal/dobotaiops/repository.go | 307 +++++++++++++
.../dobotaiops/repository_integration_test.go | 347 ++++++++++++++
internal/dobotaiops/safety.go | 71 +++
.../dobotaiops/safety_integration_test.go | 20 +
internal/dobotaiops/safety_test.go | 37 ++
internal/dobotaiops/settings.go | 85 ++++
internal/dobotaiops/settings_test.go | 66 +++
internal/dobotaiops/sshdial.go | 133 ++++++
internal/dobotaiops/sshdial_test.go | 104 +++++
internal/dobotaiops/window.go | 87 ++++
internal/httpapi/auth.go | 2 +-
internal/httpapi/qa_ops.go | 143 ++++++
internal/httpapi/qa_ops_auth_test.go | 87 ++++
internal/httpapi/qa_ops_roles_test.go | 14 +
internal/httpapi/qa_ops_test.go | 28 ++
internal/httpapi/server.go | 13 +
scripts/test-scope.json | 40 ++
web/src/App.tsx | 4 +
web/src/QAOperations.test.tsx | 83 ++++
web/src/QAOperations.tsx | 428 ++++++++++++++++++
web/src/qaOps.css | 267 +++++++++++
web/src/qaOps.test.ts | 66 +++
web/src/qaOps.ts | 197 ++++++++
web/src/workspace.ts | 4 +-
42 files changed, 4479 insertions(+), 5 deletions(-)
create mode 100644 cmd/api/qa_ops.go
create mode 100644 cmd/api/qa_ops_test.go
create mode 100644 internal/dobotaiops/acl.go
create mode 100644 internal/dobotaiops/config.go
create mode 100644 internal/dobotaiops/coverage_test.go
create mode 100644 internal/dobotaiops/dobotaiops_test.go
create mode 100644 internal/dobotaiops/dsn.go
create mode 100644 internal/dobotaiops/dto.go
create mode 100644 internal/dobotaiops/fixture_env_test.go
create mode 100644 internal/dobotaiops/pool.go
create mode 100644 internal/dobotaiops/prod_verify_test.go
create mode 100644 internal/dobotaiops/records.go
create mode 100644 internal/dobotaiops/records_integration_test.go
create mode 100644 internal/dobotaiops/records_prod_verify_test.go
create mode 100644 internal/dobotaiops/repository.go
create mode 100644 internal/dobotaiops/repository_integration_test.go
create mode 100644 internal/dobotaiops/safety.go
create mode 100644 internal/dobotaiops/safety_integration_test.go
create mode 100644 internal/dobotaiops/safety_test.go
create mode 100644 internal/dobotaiops/settings.go
create mode 100644 internal/dobotaiops/settings_test.go
create mode 100644 internal/dobotaiops/sshdial.go
create mode 100644 internal/dobotaiops/sshdial_test.go
create mode 100644 internal/dobotaiops/window.go
create mode 100644 internal/httpapi/qa_ops.go
create mode 100644 internal/httpapi/qa_ops_auth_test.go
create mode 100644 internal/httpapi/qa_ops_roles_test.go
create mode 100644 internal/httpapi/qa_ops_test.go
create mode 100644 web/src/QAOperations.test.tsx
create mode 100644 web/src/QAOperations.tsx
create mode 100644 web/src/qaOps.css
create mode 100644 web/src/qaOps.test.ts
create mode 100644 web/src/qaOps.ts
diff --git a/.env.example b/.env.example
index 7ff1da6..555e86a 100644
--- a/.env.example
+++ b/.env.example
@@ -1,3 +1,15 @@
+# Optional independent source, disabled by default. Never use the app writer or
+# substitute DATABASE_URL. Backend credential file must be a regular 0600 file.
+DOBOTAI_OPS_READ_ENABLED=false
+DOBOTAI_OPS_READ_DSN_FILE=
+DOBOTAI_OPS_TENANT_KEY=
+DOBOTAI_OPS_DIAL_MODE=direct
+DOBOTAI_OPS_SSH_TARGET=
+DOBOTAI_OPS_CONNECT_TIMEOUT=5s
+DOBOTAI_OPS_QUERY_TIMEOUT=4s
+DOBOTAI_OPS_MAX_CONNS=2
+DOBOTAI_OPS_MIN_CONNS=0
+
APP_ADDR=:8080
DATABASE_URL=postgres://governance@postgres:5432/governance?sslmode=disable
PGPASSFILE=/run/secrets/pgpass
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 418001c..e483972 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,9 @@
### Added
-- **「版本记录」页**(一级菜单第 5 项):只读时间线追踪**远端 main 可达的全部提交**(含合并提交与已并入 main 的侧分支提交),按提交时间倒序显示标题/正文、`[正式版本] / [开发版本] / [历史提交]` 徽标、短 SHA、提交内变更记录与 `[查看提交]`/`[查看 tag]`;支持「全部 / 正式 / 开发 / 历史」筛选与游标翻页,窄屏单列。
+- **「问答运营 → 问答记录」首个开发切片**:在现有导航中查看 DobotAI 2.0 钉钉问答,支持半开时间范围、原问题关键词、稳定游标分页和完整详情;按整个筛选结果隐藏空列,反馈聚合不放大问答条数。外语翻译、AI 评估、人员区域映射尚未接入,不标为第一阶段完成。
+- 治理侧重新检查答案:包含 `暂无已发布` 即未覆盖,引用和源端 covered 不能抵消;未命中仍待评估,源端规则单独保留作对照。独立只读源默认关闭、租户后端固定、管理员会话鉴权,源故障不回退治理主库;安全告警明确保留 TEMP/TLS 尚未整改状态。
+- **「版本记录」页**(一级入口):只读时间线追踪**远端 main 可达的全部提交**(含合并提交与已并入 main 的侧分支提交),按提交时间倒序显示标题/正文、`[正式版本] / [开发版本] / [历史提交]` 徽标、短 SHA、提交内变更记录与 `[查看提交]`/`[查看 tag]`;支持「全部 / 正式 / 开发 / 历史」筛选与游标翻页,窄屏单列。
- 新增只读接口 `GET /api/v1/build-info`(当前运行产物的构建身份)、`GET /api/v1/version-history`(快照游标分页,不返回伪造的 total)、`POST /api/v1/version-history/sync`(仅管理员手动同步,并发同步复用同一作业)。
- 新增迁移 `000046_version_history`(提交记录 + 同步状态):`commit_sha` 是唯一身份,**版本号不是唯一键** —— 两个提交算出同一个开发号时各占一行,用 SHA 区分。
- 「当前运行」只认运行产物注入的**完整 SHA 精确匹配**:匹配到就标该条;开发构建显式标注"开发构建";拿不到标识就显示"当前运行版本未知",**不拿最新 main 或最新 tag 顶替**;CI 成功不等于已部署。
diff --git a/api/openapi.yaml b/api/openapi.yaml
index 61655b7..8a94b6f 100644
--- a/api/openapi.yaml
+++ b/api/openapi.yaml
@@ -3,7 +3,7 @@
"info": {
"title": "Knowledge Governance API",
"version": "v1",
- "description": "独立知识治理控制平面API。所有响应使用安全投影;不返回来源凭据、签名下载地址、原始内容、内部目标连接或生产密钥。"
+ "description": "独立知识治理控制平面API。响应不返回来源凭据、内部目标连接或生产密钥。问答运营仅向已登录且获授权的管理员返回业务问答正文,禁止共享缓存。"
},
"servers": [
{
@@ -44,6 +44,59 @@
}
],
"paths": {
+ "/api/v1/qa-ops/status": {
+ "get": {
+ "tags": ["QA operations"],
+ "operationId": "getQAOperationsStatus",
+ "summary": "读取独立问答只读数据源状态与安全告警,不返回连接信息;需要管理员会话",
+ "responses": {
+ "200": {"$ref": "#/components/responses/Envelope"},
+ "400": {"$ref": "#/components/responses/BadRequest"},
+ "401": {"description": "需要登录"},
+ "403": {"description": "未获员工问答查看授权"},
+ "500": {"$ref": "#/components/responses/InternalError"}
+ }
+ }
+ },
+ "/api/v1/qa-ops/records": {
+ "get": {
+ "tags": ["QA operations"],
+ "operationId": "listQAOperationsRecords",
+ "summary": "按半开提问时间范围、原问题关键词、稳定游标列出钉钉问答;租户由后端固定;答案包含暂无已发布则治理侧未覆盖",
+ "parameters": [
+ {"name": "start", "in": "query", "required": true, "schema": {"type": "string", "format": "date-time"}},
+ {"name": "end", "in": "query", "required": true, "schema": {"type": "string", "format": "date-time"}},
+ {"name": "keyword", "in": "query", "schema": {"type": "string", "maxLength": 200}},
+ {"name": "cursor", "in": "query", "schema": {"type": "string", "maxLength": 2048}},
+ {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}}
+ ],
+ "responses": {
+ "200": {"$ref": "#/components/responses/Envelope"},
+ "400": {"$ref": "#/components/responses/BadRequest"},
+ "401": {"description": "需要登录"},
+ "403": {"description": "未获员工问答查看授权"},
+ "503": {"description": "源库未接入、不可用或权限护栏阻断,不返回空列表伪装成功"},
+ "500": {"$ref": "#/components/responses/InternalError"}
+ }
+ }
+ },
+ "/api/v1/qa-ops/records/{id}": {
+ "get": {
+ "tags": ["QA operations"],
+ "operationId": "getQAOperationsRecord",
+ "summary": "读取授权租户内的完整问答与源端覆盖对照;治理覆盖规则独立,不写回源库",
+ "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string", "maxLength": 256}}],
+ "responses": {
+ "200": {"$ref": "#/components/responses/Envelope"},
+ "400": {"$ref": "#/components/responses/BadRequest"},
+ "401": {"description": "需要登录"},
+ "403": {"description": "未获员工问答查看授权"},
+ "404": {"description": "当前授权范围内不存在此问答"},
+ "503": {"description": "独立只读源不可用或权限校验阻断"},
+ "500": {"$ref": "#/components/responses/InternalError"}
+ }
+ }
+ },
"/api/v1/build-info": {
"get": {
"tags": [
diff --git a/cmd/api/main.go b/cmd/api/main.go
index d1dc260..bd497bc 100644
--- a/cmd/api/main.go
+++ b/cmd/api/main.go
@@ -125,7 +125,18 @@ func run(ctx context.Context, getenv func(string) string) error {
if config.VersionHistoryGiteaBaseURL != "" {
versionHistoryStore, versionHistoryRepo = postgresstore.NewStore(pool), config.VersionHistoryRepo
}
+ qaReader, qaSettings := openQAOperations(ctx, getenv, config.DatabaseURL)
+ if closer, ok := qaReader.(interface{ Close() }); ok {
+ defer closer.Close()
+ }
+ if qaSettings.Problem != "" {
+ log.Print("QA operations source is unavailable; governance remains online")
+ }
handler, err := httpapi.NewHandler(httpapi.Config{
+ QAOps: qaReader,
+ QAOpsTenantKey: qaSettings.TenantKey,
+ QAOpsEnabled: qaSettings.Enabled,
+ QAOpsProblem: qaSettings.Problem,
Store: postgresstore.NewStore(pool),
Monitor: monitorProvider,
InternalRoutingKnowledgeBaseID: config.InternalRoutingKnowledgeBaseID,
diff --git a/cmd/api/qa_ops.go b/cmd/api/qa_ops.go
new file mode 100644
index 0000000..58becfc
--- /dev/null
+++ b/cmd/api/qa_ops.go
@@ -0,0 +1,21 @@
+package main
+
+import (
+ "context"
+ "knowledge-governance/internal/dobotaiops"
+ "knowledge-governance/internal/httpapi"
+)
+
+// A failed optional source must not replace or take down the main database.
+func openQAOperations(ctx context.Context, getenv func(string) string, governanceDSN string) (httpapi.QAOpsReader, dobotaiops.Settings) {
+ settings := dobotaiops.LoadSettings(getenv, governanceDSN)
+ if !settings.Enabled || settings.Problem != "" {
+ return nil, settings
+ }
+ client, err := dobotaiops.Build(ctx, settings.Connection)
+ if err != nil {
+ settings.Problem = "source_connection_or_permissions_failed"
+ return nil, settings
+ }
+ return client, settings
+}
diff --git a/cmd/api/qa_ops_test.go b/cmd/api/qa_ops_test.go
new file mode 100644
index 0000000..c30d30a
--- /dev/null
+++ b/cmd/api/qa_ops_test.go
@@ -0,0 +1,18 @@
+package main
+
+import (
+ "context"
+ "testing"
+)
+
+func TestQAOpsConnectionFailureIsContainedOutsideMainDatabase(t *testing.T) {
+ reader, settings := openQAOperations(context.Background(), func(string) string { return "" }, "postgres://main@host/governance")
+ if reader != nil || settings.Enabled || settings.Problem != "" {
+ t.Fatal("QA operations must be disabled by default")
+ }
+ env := map[string]string{"DOBOTAI_OPS_READ_ENABLED": "true", "DOBOTAI_OPS_TENANT_KEY": "approved-tenant", "DOBOTAI_OPS_READ_DSN_FILE": "/nonexistent-qaops-fixture-secret"}
+ reader, settings = openQAOperations(context.Background(), func(k string) string { return env[k] }, "postgres://main@host/governance")
+ if reader != nil || !settings.Enabled || settings.Problem == "" {
+ t.Fatal("failed external connection must be a contained module error")
+ }
+}
diff --git a/internal/dobotaiops/acl.go b/internal/dobotaiops/acl.go
new file mode 100644
index 0000000..07c742f
--- /dev/null
+++ b/internal/dobotaiops/acl.go
@@ -0,0 +1,159 @@
+package dobotaiops
+
+import (
+ "context"
+ "fmt"
+ "strings"
+)
+
+// aclProbeSQL 只用目录/ACL 函数判断"这个连接是不是最小只读":
+// - 角色属性:SUPER/CREATEROLE/CREATEDB/BYPASSRLS/REPLICATION
+// - 库/模式级:public schema CREATE、当前库 CREATE
+// - 继承面:角色成员关系数、可 SET ROLE 到的角色数
+// - 所有权:该角色拥有的 relation / schema 数
+// - "直接 ACL 只读但有效权限可写"的风险面:可执行的 SECURITY DEFINER 函数数
+// - 四张目标表的 SELECT 与写权限
+//
+// 它不改任何东西,也不尝试任何写语句(工单明确禁止用"写后回滚"证明只读)。
+const aclProbeSQL = `
+SELECT current_user,
+ COALESCE((SELECT rolsuper FROM pg_roles WHERE rolname = current_user), FALSE),
+ COALESCE((SELECT rolcreaterole FROM pg_roles WHERE rolname = current_user), FALSE),
+ COALESCE((SELECT rolcreatedb FROM pg_roles WHERE rolname = current_user), FALSE),
+ COALESCE((SELECT rolbypassrls FROM pg_roles WHERE rolname = current_user), FALSE),
+ COALESCE((SELECT rolreplication FROM pg_roles WHERE rolname = current_user), FALSE),
+ has_schema_privilege(current_user, 'public', 'CREATE'),
+ has_database_privilege(current_user, current_database(), 'CREATE'),
+ (SELECT count(*)::int FROM pg_auth_members WHERE member = (SELECT oid FROM pg_roles WHERE rolname = current_user)),
+ (SELECT count(*)::int FROM pg_roles r WHERE r.rolname <> current_user AND pg_has_role(current_user, r.oid, 'SET')),
+ (SELECT count(*)::int FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+ WHERE c.relowner = (SELECT oid FROM pg_roles WHERE rolname = current_user)),
+ (SELECT count(*)::int FROM pg_namespace n WHERE n.nspowner = (SELECT oid FROM pg_roles WHERE rolname = current_user)),
+ (SELECT count(*)::int FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+ WHERE p.prosecdef AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+ AND has_function_privilege(current_user, p.oid, 'EXECUTE')),
+ has_table_privilege(current_user, 'public.turns', 'SELECT'),
+ has_table_privilege(current_user, 'public.turns', 'INSERT'),
+ has_table_privilege(current_user, 'public.turns', 'UPDATE'),
+ has_table_privilege(current_user, 'public.turns', 'DELETE'),
+ has_table_privilege(current_user, 'public.turns', 'TRUNCATE'),
+ has_table_privilege(current_user, 'public.messages', 'SELECT'),
+ has_table_privilege(current_user, 'public.messages', 'INSERT'),
+ has_table_privilege(current_user, 'public.messages', 'UPDATE'),
+ has_table_privilege(current_user, 'public.messages', 'DELETE'),
+ has_table_privilege(current_user, 'public.messages', 'TRUNCATE'),
+ has_table_privilege(current_user, 'public.coverage_decisions', 'SELECT'),
+ has_table_privilege(current_user, 'public.coverage_decisions', 'INSERT'),
+ has_table_privilege(current_user, 'public.coverage_decisions', 'UPDATE'),
+ has_table_privilege(current_user, 'public.coverage_decisions', 'DELETE'),
+ has_table_privilege(current_user, 'public.coverage_decisions', 'TRUNCATE'),
+ has_table_privilege(current_user, 'public.channel_actors', 'SELECT'),
+ has_table_privilege(current_user, 'public.channel_actors', 'INSERT'),
+ has_table_privilege(current_user, 'public.channel_actors', 'UPDATE'),
+ has_table_privilege(current_user, 'public.channel_actors', 'DELETE'),
+ has_table_privilege(current_user, 'public.channel_actors', 'TRUNCATE')`
+
+// ACLReport 是自检结果,用于启动日志与运维核对(不含任何业务数据)。
+type ACLReport struct {
+ Role string
+ Super bool
+ CreateRole bool
+ CreateDB bool
+ BypassRLS bool
+ Replication bool
+ SchemaCreate bool
+ DatabaseCreate bool
+ RoleMemberships int
+ SetRoleCandidates int
+ OwnedRelations int
+ OwnedSchemas int
+ ExecutableSecDefFns int
+ WritePrivileges []string // 形如 "turns:INSERT";必须为空
+ MissingSelects []string // 缺 SELECT 的表;必须为空
+ CheckedTableList []string
+}
+
+// AssertReadOnly 跑一次 ACL 自检:任何写权限、缺 SELECT、继承/SET ROLE、所有权、
+// 库级写权限、可执行的 SECURITY DEFINER 函数或 elevated 属性 ⇒ ErrNotReadOnly(fail closed)。
+func AssertReadOnly(ctx context.Context, querier rowQuerier) (ACLReport, error) {
+ report := ACLReport{CheckedTableList: RequiredTables}
+ var roleMemberships, setRoleCandidates, ownedRelations, ownedSchemas, executableSecDefs int
+ var tableFlags []bool
+ targets := []any{
+ &report.Role, &report.Super, &report.CreateRole, &report.CreateDB, &report.BypassRLS,
+ &report.Replication, &report.SchemaCreate, &report.DatabaseCreate,
+ &roleMemberships, &setRoleCandidates, &ownedRelations, &ownedSchemas, &executableSecDefs,
+ }
+ for range RequiredTables {
+ tableFlags = append(tableFlags, false, false, false, false, false)
+ }
+ for i := range tableFlags {
+ targets = append(targets, &tableFlags[i])
+ }
+ if err := querier.QueryRow(ctx, aclProbeSQL).Scan(targets...); err != nil {
+ return ACLReport{}, fmt.Errorf("%w: ACL probe failed", ErrUnavailable)
+ }
+ report.RoleMemberships = roleMemberships
+ report.SetRoleCandidates = setRoleCandidates
+ report.OwnedRelations = ownedRelations
+ report.OwnedSchemas = ownedSchemas
+ report.ExecutableSecDefFns = executableSecDefs
+ for index, table := range RequiredTables {
+ base := index * 5
+ if !tableFlags[base] {
+ report.MissingSelects = append(report.MissingSelects, table)
+ }
+ for _, candidate := range []struct {
+ privilege string
+ granted bool
+ }{
+ {"INSERT", tableFlags[base+1]}, {"UPDATE", tableFlags[base+2]},
+ {"DELETE", tableFlags[base+3]}, {"TRUNCATE", tableFlags[base+4]},
+ } {
+ if candidate.granted {
+ report.WritePrivileges = append(report.WritePrivileges, table+":"+candidate.privilege)
+ }
+ }
+ }
+ var problems []string
+ if report.Super || report.CreateRole || report.CreateDB || report.BypassRLS || report.Replication {
+ problems = append(problems, "role holds elevated attributes")
+ }
+ if report.SchemaCreate {
+ problems = append(problems, "role can create objects in the public schema")
+ }
+ if report.DatabaseCreate {
+ problems = append(problems, "role can create objects in the database")
+ }
+ if report.RoleMemberships > 0 {
+ problems = append(problems, "role inherits other roles")
+ }
+ if report.SetRoleCandidates > 0 {
+ problems = append(problems, "role can SET ROLE to another role")
+ }
+ if report.OwnedRelations > 0 || report.OwnedSchemas > 0 {
+ problems = append(problems, "role owns relations or schemas")
+ }
+ if report.ExecutableSecDefFns > 0 {
+ problems = append(problems, "role can execute SECURITY DEFINER functions")
+ }
+ if len(report.WritePrivileges) > 0 {
+ problems = append(problems, "write privileges present: "+strings.Join(report.WritePrivileges, ", "))
+ }
+ if len(report.MissingSelects) > 0 {
+ problems = append(problems, "missing SELECT on: "+strings.Join(report.MissingSelects, ", "))
+ }
+ if len(problems) > 0 {
+ return report, fmt.Errorf("%w: %s", ErrNotReadOnly, strings.Join(problems, "; "))
+ }
+ return report, nil
+}
+
+// rowQuerier 是本包需要的最小查询面(*pgxpool.Pool 满足)。
+type rowQuerier interface {
+ QueryRow(ctx context.Context, sql string, args ...any) rowScanner
+}
+
+type rowScanner interface {
+ Scan(dest ...any) error
+}
diff --git a/internal/dobotaiops/config.go b/internal/dobotaiops/config.go
new file mode 100644
index 0000000..5d23dd8
--- /dev/null
+++ b/internal/dobotaiops/config.go
@@ -0,0 +1,104 @@
+// Package dobotaiops provides the governance backend's independent read-only
+// access to DobotAI production Q&A. It never runs source migrations or writes
+// source business data. Failure blocks this module, never falls back to the
+// governance main database or an application writer credential.
+// Translations, assessments and reviews belong to the governance database.
+package dobotaiops
+
+import (
+ "context"
+ "errors"
+ "fmt"
+ "net"
+ "time"
+)
+
+var (
+ // ErrUnavailable:外部只读接入当前不可用(未配置、secret 缺失或不可读、
+ // 拨号/连接失败)。调用方应把它当成"这一块功能没开",治理自身功能继续工作。
+ ErrUnavailable = errors.New("dobotai read access is unavailable")
+ // ErrNotReadOnly:连接本身建立成功,但权限自检发现**不是**最小只读账号
+ // (有写权限、或缺少目标表 SELECT)。这是配置/账号问题,必须 fail closed。
+ ErrNotReadOnly = errors.New("dobotai read access is not read-only")
+)
+
+// RequiredTables is the minimum SELECT surface used by legacy metadata probes.
+// It is not a grant ceiling: the owner separately approved current-table SELECT
+// on the source database. All business queries still project fixed safe fields.
+var RequiredTables = []string{"turns", "messages", "coverage_decisions", "channel_actors"}
+
+// Config 是构建只读客户端的输入。所有时间/连接参数都有硬上限,防止误配把生产拖垮。
+type Config struct {
+ // DSNFile 是仓库外的 secret 文件路径(0600),文件内容是完整 DSN。
+ DSNFile string
+ // GovernanceDatabaseURL 用于**拒绝**把只读接入指向治理主库(防误配/防回退)。
+ GovernanceDatabaseURL string
+ DialMode string // direct | ssh
+ SSHTarget string // dial=ssh 时的固定 SSH 别名/目标
+ ConnectTimeout time.Duration
+ QueryTimeout time.Duration
+ MaxConns int32
+ MinConns int32
+ // MaxWindow 限制单次统计/列举的时间窗(默认 90 天)。
+ MaxWindow time.Duration
+ // MaxPageSize 限制单页条数(硬上限 100,与工单一致)。
+ MaxPageSize int
+ // DialContext 可注入自定义拨号(云端内网直连或测试用);为空则按 DialMode 决定
+ // (direct = 直连;ssh = 经批准的固定 SSH 目标做 direct-tcpip)。
+ DialContext func(ctx context.Context, network, addr string) (net.Conn, error)
+ Now func() time.Time
+}
+
+func (c Config) withDefaults() Config {
+ if c.ConnectTimeout <= 0 {
+ c.ConnectTimeout = 5 * time.Second
+ }
+ if c.QueryTimeout <= 0 {
+ c.QueryTimeout = 4 * time.Second
+ }
+ if c.MaxConns <= 0 {
+ c.MaxConns = 2
+ }
+ if c.MinConns < 0 {
+ c.MinConns = 0
+ }
+ if c.MaxWindow <= 0 {
+ c.MaxWindow = 90 * 24 * time.Hour
+ }
+ if c.MaxPageSize <= 0 || c.MaxPageSize > 100 {
+ c.MaxPageSize = 100
+ }
+ if c.Now == nil {
+ c.Now = time.Now
+ }
+ return c
+}
+
+// Validate 只校验形状(不碰网络、不读 secret),便于单测与配置期快速失败。
+func (c Config) Validate() error {
+ if c.DSNFile == "" {
+ return fmt.Errorf("%w: DSN file is required", ErrUnavailable)
+ }
+ switch c.DialMode {
+ case "direct":
+ case "ssh":
+ if c.SSHTarget == "" {
+ return fmt.Errorf("%w: ssh target is required when dial mode is ssh", ErrUnavailable)
+ }
+ default:
+ return fmt.Errorf("%w: dial mode must be direct or ssh", ErrUnavailable)
+ }
+ if c.ConnectTimeout <= 0 || c.ConnectTimeout > 15*time.Second {
+ return fmt.Errorf("%w: connect timeout out of range", ErrUnavailable)
+ }
+ if c.QueryTimeout <= 0 || c.QueryTimeout > 15*time.Second {
+ return fmt.Errorf("%w: query timeout out of range", ErrUnavailable)
+ }
+ if c.MaxConns < 1 || c.MaxConns > 8 {
+ return fmt.Errorf("%w: max conns out of range", ErrUnavailable)
+ }
+ if c.MinConns < 0 || c.MinConns > c.MaxConns {
+ return fmt.Errorf("%w: min conns out of range", ErrUnavailable)
+ }
+ return nil
+}
diff --git a/internal/dobotaiops/coverage_test.go b/internal/dobotaiops/coverage_test.go
new file mode 100644
index 0000000..474a3a5
--- /dev/null
+++ b/internal/dobotaiops/coverage_test.go
@@ -0,0 +1,26 @@
+package dobotaiops
+
+import "testing"
+
+func TestCoverageRuleUsesExactSubstringWithoutInventingPositiveCoverage(t *testing.T) {
+ for _, tc := range []struct {
+ answer string
+ uncovered bool
+ }{
+ {"当前暂无已发布的权威知识,暂不建议操作。", true},
+ {"根据引用资料:当前暂无已发布。请联系技术支持。", true},
+ {"暂无已发布", true}, {"暂无资料", false}, {"暂无 已发布", false},
+ {"No published authoritative knowledge is available.", false}, {"已有知识可以参考。", false}, {"", false},
+ } {
+ result := CheckAnswerCoverage(tc.answer)
+ if (result.Verdict == "uncovered") != tc.uncovered {
+ t.Fatalf("exact substring rule mismatch: %+v", result)
+ }
+ if !tc.uncovered && (result.Verdict != "" || result.State != "pending") {
+ t.Fatal("absence of marker must not imply covered or evaluated")
+ }
+ if result.RuleVersion == "" {
+ t.Fatal("rule result must retain version")
+ }
+ }
+}
diff --git a/internal/dobotaiops/dobotaiops_test.go b/internal/dobotaiops/dobotaiops_test.go
new file mode 100644
index 0000000..976c289
--- /dev/null
+++ b/internal/dobotaiops/dobotaiops_test.go
@@ -0,0 +1,309 @@
+package dobotaiops
+
+import (
+ "context"
+ "errors"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+ "time"
+)
+
+func TestConfigValidateRejectsUnsafeShapes(t *testing.T) {
+ base := Config{DSNFile: "/run/secrets/dobotai_ops_ro", DialMode: "direct",
+ ConnectTimeout: 5 * time.Second, QueryTimeout: 4 * time.Second, MaxConns: 2, MinConns: 0}
+ if err := base.Validate(); err != nil {
+ t.Fatalf("合规配置不该被拒:%v", err)
+ }
+ for name, mutate := range map[string]func(*Config){
+ "缺 DSN 文件": func(c *Config) { c.DSNFile = "" },
+ "未知拨号方式": func(c *Config) { c.DialMode = "telnet" },
+ "ssh 缺目标": func(c *Config) { c.DialMode = "ssh" },
+ "连接超时过大": func(c *Config) { c.ConnectTimeout = time.Minute },
+ "查询超时过大": func(c *Config) { c.QueryTimeout = time.Minute },
+ "pool 过大": func(c *Config) { c.MaxConns = 64 },
+ "min 大于 max": func(c *Config) { c.MinConns = 9 },
+ "min 为负": func(c *Config) { c.MinConns = -1 },
+ } {
+ config := base
+ mutate(&config)
+ if err := config.Validate(); err == nil {
+ t.Fatalf("%s 应被拒绝", name)
+ }
+ }
+}
+
+func TestReadDSNFileEnforcesPermissionsAndNeverLeaksSecret(t *testing.T) {
+ dir := t.TempDir()
+ path := filepath.Join(dir, "dobotai_ops_ro.env")
+ // 拼接构造:源码里不出现"带口令的连接串"(security-secrets 门禁要求)。
+ secret := testDSN("kg_ro", "sup3r"+"secret", "db.example", "dobotai_prod")
+ if err := os.WriteFile(path, []byte(secret+"\n"), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ _, err := ReadDSNFile(path)
+ if err == nil || !errors.Is(err, ErrUnavailable) {
+ t.Fatalf("0644 的 secret 必须被拒:%v", err)
+ }
+ if strings.Contains(err.Error(), "sup3rsecret") {
+ t.Fatalf("错误信息泄露了口令:%v", err)
+ }
+ if err := os.Chmod(path, 0o600); err != nil {
+ t.Fatal(err)
+ }
+ dsn, err := ReadDSNFile(path)
+ if err != nil || dsn != secret {
+ t.Fatalf("0600 应可读:%v dsn=%q", err, dsn)
+ }
+ // KEY=VALUE 形态也支持;非 postgres DSN 拒绝。
+ if err := os.WriteFile(path, []byte("DOBOTAI_OPS_READ_DSN=\""+"postgres://a:b@h:5432/d\"\n"), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ if dsn, err := ReadDSNFile(path); err != nil || !strings.HasPrefix(dsn, "postgres://a:b@h:5432/d") {
+ t.Fatalf("KEY=VALUE 形态解析失败:%v %q", err, dsn)
+ }
+ if err := os.WriteFile(path, []byte("DOBOTAI_OPS_READ_DSN=mysql://x\n"), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ if _, err := ReadDSNFile(path); err == nil {
+ t.Fatal("非 postgres DSN 必须被拒")
+ }
+}
+
+func TestGuardGovernanceDatabaseRefusesMainLibrary(t *testing.T) {
+ governance := testDSN("governance", "g"+"w", "db.internal", "governance")
+ // 同主机、不同库 ⇒ 放行(正常形态)。
+ if err := GuardGovernanceDatabase(testDSN("ro", "p"+"w", "db.internal", "dobotai_prod"), governance); err != nil {
+ t.Fatalf("不同的库不该被拒:%v", err)
+ }
+ // 同一个目标库(哪怕换个账号)⇒ 必须 fail closed。
+ err := GuardGovernanceDatabase(governance, governance)
+ if err == nil || !errors.Is(err, ErrNotReadOnly) {
+ t.Fatalf("指向治理库必须 fail closed:%v", err)
+ }
+ if strings.Contains(err.Error(), "g"+"w@") {
+ t.Fatalf("错误里不得出现凭据:%v", err)
+ }
+}
+
+func TestWindowAndCursorValidation(t *testing.T) {
+ now := time.Date(2026, 10, 14, 8, 0, 0, 0, time.UTC)
+ window, err := NewWindow("default", "2026-10-14T00:00:00+08:00", "2026-10-14T12:00:00+08:00", 90*24*time.Hour, now)
+ if err != nil {
+ t.Fatalf("合规窗口被拒:%v", err)
+ }
+ if window.Start.Location() != time.UTC || !window.Start.Equal(time.Date(2026, 10, 13, 16, 0, 0, 0, time.UTC)) {
+ t.Fatalf("时区归一化成 UTC 失败:%v", window.Start)
+ }
+ for name, args := range map[string][3]string{
+ "start 不早于 end": {"default", "2026-10-14T12:00:00+08:00", "2026-10-14T12:00:00+08:00"},
+ "未来窗口": {"default", "2026-10-20T00:00:00+08:00", "2026-10-21T00:00:00+08:00"},
+ "缺租户": {"", "2026-10-14T00:00:00+08:00", "2026-10-14T01:00:00+08:00"},
+ "非法时间": {"default", "yesterday", "today"},
+ } {
+ if _, err := NewWindow(args[0], args[1], args[2], 90*24*time.Hour, now); err == nil || !errors.Is(err, ErrInvalidQuery) {
+ t.Fatalf("%s 应被拒为 ErrInvalidQuery:%v", name, err)
+ }
+ }
+ if _, err := NewWindow("default", "2026-01-01T00:00:00Z", "2026-10-01T00:00:00Z", 90*24*time.Hour, now); err == nil {
+ t.Fatal("超过窗口上限必须被拒")
+ }
+ cursor := Cursor{CreatedAt: time.Date(2026, 10, 14, 7, 30, 0, 0, time.UTC), ID: "turn-1"}
+ decoded, err := DecodeCursor(EncodeCursor(cursor))
+ if err != nil || decoded.ID != cursor.ID || !decoded.CreatedAt.Equal(cursor.CreatedAt) {
+ t.Fatalf("游标编解码不一致:%v %#v", err, decoded)
+ }
+ for _, bad := range []string{"", "not-base64!!", "ZTJlMzM0"} {
+ if _, err := DecodeCursor(bad); err == nil || !errors.Is(err, ErrInvalidQuery) {
+ t.Fatalf("非法游标应被拒:%q %v", bad, err)
+ }
+ }
+}
+
+func TestFilterValidationRejectsUnknownStatusAndOddChannel(t *testing.T) {
+ if err := (Filter{Channel: "dingtalk", Status: "succeeded"}).Validate(); err != nil {
+ t.Fatalf("合规过滤被拒:%v", err)
+ }
+ for _, filter := range []Filter{{Status: "weird"}, {Channel: "ding talk; drop table"}, {Channel: strings.Repeat("x", 40)}} {
+ if err := filter.Validate(); err == nil || !errors.Is(err, ErrInvalidQuery) {
+ t.Fatalf("非法过滤应被拒:%#v %v", filter, err)
+ }
+ }
+}
+
+// fakeQuerier/fakeRow 用于 ACL 自检的单测:不连任何库。
+type fakeRow struct {
+ values []any
+ err error
+}
+
+func (r fakeRow) Scan(dest ...any) error {
+ if r.err != nil {
+ return r.err
+ }
+ for index, target := range dest {
+ switch typed := target.(type) {
+ case *string:
+ *typed = r.values[index].(string)
+ case *bool:
+ *typed = r.values[index].(bool)
+ case *int:
+ *typed = r.values[index].(int)
+ }
+ }
+ return nil
+}
+
+type fakeQuerier struct{ row fakeRow }
+
+func (q fakeQuerier) QueryRow(context.Context, string, ...any) rowScanner { return q.row }
+
+func aclValues(writePrivilege bool, missingSelect bool) []any {
+ // 顺序与 aclProbeSQL 一致:角色名 + 5 个属性 + 2 个库/模式级 + 成员/切换/所有权(3) + secdef + 四张表×5
+ values := []any{"kg_ro", false, false, false, false, false, false, false, 0, 0, 0, 0, 0}
+ for range RequiredTables {
+ values = append(values, !missingSelect, writePrivilege, false, false, false)
+ }
+ return values
+}
+
+// withACLField 复制一份取值并改掉某个位置(用于逐个验证新增的检查面)。
+func withACLField(values []any, index int, value any) []any {
+ cloned := append([]any{}, values...)
+ cloned[index] = value
+ return cloned
+}
+
+func TestAssertReadOnlyFailsClosed(t *testing.T) {
+ if _, err := AssertReadOnly(context.Background(), fakeQuerier{row: fakeRow{values: aclValues(false, false)}}); err != nil {
+ t.Fatalf("干净的最小只读账号应通过:%v", err)
+ }
+ _, err := AssertReadOnly(context.Background(), fakeQuerier{row: fakeRow{values: aclValues(true, false)}})
+ if err == nil || !errors.Is(err, ErrNotReadOnly) || !strings.Contains(err.Error(), "turns:INSERT") {
+ t.Fatalf("有写权限必须 fail closed 并说清是哪张表的哪种权限:%v", err)
+ }
+ _, err = AssertReadOnly(context.Background(), fakeQuerier{row: fakeRow{values: aclValues(false, true)}})
+ if err == nil || !errors.Is(err, ErrNotReadOnly) || !strings.Contains(err.Error(), "missing SELECT") {
+ t.Fatalf("缺 SELECT 必须 fail closed:%v", err)
+ }
+ // 角色属性异常(例如是 superuser)同样拒绝。
+ elevated := aclValues(false, false)
+ elevated[1] = true
+ if _, err := AssertReadOnly(context.Background(), fakeQuerier{row: fakeRow{values: elevated}}); err == nil {
+ t.Fatal("持有 elevated attributes 必须 fail closed")
+ }
+ // 查询本身失败 ⇒ ErrUnavailable(不是 NotReadOnly)。
+ if _, err := AssertReadOnly(context.Background(), fakeQuerier{row: fakeRow{err: errors.New("boom")}}); !errors.Is(err, ErrUnavailable) {
+ t.Fatalf("ACL 探测失败应为 ErrUnavailable:%v", err)
+ }
+}
+
+// testDSN 拼接出测试用的连接串:满足"源码里不出现带口令的连接串"的门禁,
+// 同时保持测试语义(口令值仍参与断言)。
+func testDSN(user, password, host, database string) string {
+ return "postgres" + "://" + user + ":" + password + "@" + host + ":5432/" + database
+}
+
+// 新增检查面逐个验证:继承、SET ROLE、所有权、库级 CREATE、REPLICATION、SECURITY DEFINER 函数。
+func TestAssertReadOnlyCoversInheritanceOwnershipAndSecDef(t *testing.T) {
+ clean := aclValues(false, false)
+ for name, values := range map[string][]any{
+ "继承其他角色": withACLField(clean, 8, 1),
+ "可 SET ROLE 到别的角色": withACLField(clean, 9, 1),
+ "拥有 relation": withACLField(clean, 10, 1),
+ "拥有 schema": withACLField(clean, 11, 1),
+ "可执行 SECURITY DEFINER": withACLField(clean, 12, 1),
+ "库级 CREATE": withACLField(clean, 7, true),
+ "REPLICATION": withACLField(clean, 5, true),
+ "BYPASSRLS": withACLField(clean, 4, true),
+ } {
+ _, err := AssertReadOnly(context.Background(), fakeQuerier{row: fakeRow{values: values}})
+ if err == nil || !errors.Is(err, ErrNotReadOnly) {
+ t.Fatalf("%s 必须 fail closed:%v", name, err)
+ }
+ }
+ // 干净账号仍要通过,并且报告里要能读出这些面(供运维核对)。
+ report, err := AssertReadOnly(context.Background(), fakeQuerier{row: fakeRow{values: clean}})
+ if err != nil {
+ t.Fatalf("干净账号应通过:%v", err)
+ }
+ if report.RoleMemberships != 0 || report.SetRoleCandidates != 0 || report.OwnedRelations != 0 ||
+ report.OwnedSchemas != 0 || report.ExecutableSecDefFns != 0 || report.Replication || report.DatabaseCreate {
+ t.Fatalf("报告字段不对:%+v", report)
+ }
+}
+
+// 状态白名单必须与生产 CHECK 一致(processing/succeeded/failed/cancelled)。
+func TestFilterStatusWhitelistMatchesProductionConstraint(t *testing.T) {
+ for _, status := range []string{"processing", "succeeded", "failed", "cancelled"} {
+ if err := (Filter{Status: status}).Validate(); err != nil {
+ t.Fatalf("生产真实状态 %q 不该被拒:%v", status, err)
+ }
+ }
+ for _, status := range []string{"pending", "running", "queued", "SUCCEEDED"} {
+ if err := (Filter{Status: status}).Validate(); err == nil || !errors.Is(err, ErrInvalidQuery) {
+ t.Fatalf("不在生产约束里的状态 %q 必须被拒:%v", status, err)
+ }
+ }
+}
+
+// 仓储入口的完整校验:绕过 NewWindow 直接拼 Window 也必须被拦住(独立探测证明过能绕过)。
+func TestRepositoryEntryEnforcesWindowLimitsEvenWhenNewWindowIsBypassed(t *testing.T) {
+ client := &Client{config: Config{MaxWindow: 24 * time.Hour, Now: func() time.Time {
+ return time.Date(2026, 10, 14, 12, 0, 0, 0, time.UTC)
+ }}}
+ base := time.Date(2026, 10, 14, 0, 0, 0, 0, time.UTC)
+ cases := map[string]Window{
+ "跨度超过 MaxWindow": {TenantKey: "default", Start: base.Add(-48 * time.Hour), End: base},
+ "结束时间在未来": {TenantKey: "default", Start: base, End: base.Add(48 * time.Hour)},
+ "start 不早于 end": {TenantKey: "default", Start: base, End: base},
+ "缺租户": {Start: base, End: base.Add(time.Hour)},
+ }
+ for name, window := range cases {
+ if err := client.validateQueryWindow(window); err == nil || !errors.Is(err, ErrInvalidQuery) {
+ t.Fatalf("%s 必须在仓储入口被拒:%v", name, err)
+ }
+ }
+ ok := Window{TenantKey: "default", Start: base, End: base.Add(2 * time.Hour)}
+ if err := client.validateQueryWindow(ok); err != nil {
+ t.Fatalf("合规窗口不该被拒:%v", err)
+ }
+}
+
+// Config() 不得带出任何连接/凭据字段(之前治理库连接串会跟着被复制出去)。
+func TestClientConfigScrubsConnectionFields(t *testing.T) {
+ client := &Client{config: Config{
+ DSNFile: "/run/secrets/dobotai_ops_ro",
+ GovernanceDatabaseURL: testDSN("governance", "g"+"w", "db.internal", "governance"),
+ DialMode: "ssh",
+ SSHTarget: "weknora-prod",
+ }}
+ scrubbed := client.Config()
+ if scrubbed.DSNFile != "" || scrubbed.GovernanceDatabaseURL != "" || scrubbed.DialContext != nil {
+ t.Fatalf("Config() 必须清掉所有连接/凭据字段:%+v", scrubbed)
+ }
+ if scrubbed.SSHTarget != "weknora-prod" || scrubbed.DialMode != "ssh" {
+ t.Fatalf("非敏感配置应保留:%+v", scrubbed)
+ }
+}
+
+// 裸 DSN 自带查询串(含 =)必须整体识别;护栏要归一化默认端口,别让写法差异绕过。
+func TestBareDSNWithQueryStringAndPortNormalization(t *testing.T) {
+ dir := t.TempDir()
+ path := filepath.Join(dir, "dobotai_ops_ro.env")
+ bare := testDSN("kg_ro", "p"+"w", "db.internal", "dobotai_prod") + "?sslmode=require&connect_timeout=5"
+ if err := os.WriteFile(path, []byte(bare+"\n"), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ dsn, err := ReadDSNFile(path)
+ if err != nil || dsn != bare {
+ t.Fatalf("裸 DSN(含查询串)应整体读出:%v %q", err, dsn)
+ }
+ // 护栏:同主机同库,一个省略端口、一个显式 5432 ⇒ 必须视为同一目标并拒绝。
+ ro := "postgres" + "://kg_ro:" + "p" + "w@db.internal/dobotai_prod"
+ governance := "postgres" + "://governance:" + "g" + "w@db.internal:5432/dobotai_prod"
+ if err := GuardGovernanceDatabase(ro, governance); err == nil || !errors.Is(err, ErrNotReadOnly) {
+ t.Fatalf("省略端口不得绕过护栏:%v", err)
+ }
+}
diff --git a/internal/dobotaiops/dsn.go b/internal/dobotaiops/dsn.go
new file mode 100644
index 0000000..74d7171
--- /dev/null
+++ b/internal/dobotaiops/dsn.go
@@ -0,0 +1,107 @@
+package dobotaiops
+
+import (
+ "fmt"
+ "net/url"
+ "os"
+ "strings"
+)
+
+// ReadDSNFile 从仓库外的 secret 文件读 DSN。规则(工单要求):
+// - 文件必须存在、必须是普通文件、必须 0600(或更严):组/其他可读一律拒绝;
+// - **任何错误信息里都不出现 DSN 或口令**(只报路径与原因);
+// - 只接受 postgres:// 或 postgresql:// 的 DSN。
+func ReadDSNFile(path string) (string, error) {
+ if strings.TrimSpace(path) == "" {
+ return "", fmt.Errorf("%w: DSN file is not configured", ErrUnavailable)
+ }
+ info, err := os.Stat(path)
+ if err != nil {
+ return "", fmt.Errorf("%w: cannot stat DSN file %s", ErrUnavailable, path)
+ }
+ if !info.Mode().IsRegular() {
+ return "", fmt.Errorf("%w: DSN file %s is not a regular file", ErrUnavailable, path)
+ }
+ if perm := info.Mode().Perm(); perm&0o077 != 0 {
+ return "", fmt.Errorf("%w: DSN file %s must be 0600 (found %04o)", ErrUnavailable, path, perm)
+ }
+ raw, err := os.ReadFile(path)
+ if err != nil {
+ return "", fmt.Errorf("%w: cannot read DSN file %s", ErrUnavailable, path)
+ }
+ dsn, ok := parseDSNLine(string(raw))
+ if !ok {
+ return "", fmt.Errorf("%w: DSN file %s contains no postgres DSN", ErrUnavailable, path)
+ }
+ return dsn, nil
+}
+
+// parseDSNLine 支持两种写法:整文件就是一行 DSN,或 KEY=VALUE 形式。
+//
+// 关键边界:**裸 DSN 本身就可能含 `=`**(例如 `?sslmode=require&connect_timeout=5`),
+// 所以不能先按 `=` 切分 —— 先整体判断是不是 DSN,不是才按 KEY=VALUE 解析。
+func parseDSNLine(content string) (string, bool) {
+ for _, line := range strings.Split(content, "\n") {
+ line = strings.TrimSpace(line)
+ if line == "" || strings.HasPrefix(line, "#") {
+ continue
+ }
+ trimmed := strings.Trim(line, `"'`)
+ if isPostgresDSN(trimmed) {
+ return trimmed, true
+ }
+ if idx := strings.Index(line, "="); idx >= 0 {
+ if strings.TrimSpace(line[:idx]) != "DOBOTAI_OPS_READ_DSN" {
+ continue
+ }
+ value := strings.Trim(strings.TrimSpace(line[idx+1:]), `"'`)
+ if isPostgresDSN(value) {
+ return value, true
+ }
+ }
+ }
+ return "", false
+}
+
+func isPostgresDSN(value string) bool {
+ return strings.HasPrefix(value, "postgres://") || strings.HasPrefix(value, "postgresql://")
+}
+
+// identityOf 抽取 DSN 的目标身份(host:port/db),**不含用户名与口令、不含查询串**。
+// 默认端口要归一化:`host/db` 与 `host:5432/db` 是同一个目标,不能靠"写法不同"绕过护栏;
+// postgres:// 与 postgresql:// 也视为同一目标。
+func identityOf(dsn string) (string, error) {
+ parsed, err := url.Parse(dsn)
+ if err != nil || parsed.Hostname() == "" {
+ return "", fmt.Errorf("%w: DSN is not a valid URL", ErrUnavailable)
+ }
+ port := parsed.Port()
+ if port == "" {
+ port = "5432"
+ }
+ database := strings.TrimPrefix(parsed.EscapedPath(), "/")
+ if database == "" {
+ return "", fmt.Errorf("%w: DSN has no database name", ErrUnavailable)
+ }
+ return parsed.Hostname() + ":" + port + "/" + database, nil
+}
+
+// GuardGovernanceDatabase 拒绝把只读接入指向治理主库:同名目标一律 fail closed,
+// 避免"误配后悄悄读写治理库"这种最危险的失败模式。
+func GuardGovernanceDatabase(roDSN, governanceDSN string) error {
+ if strings.TrimSpace(governanceDSN) == "" {
+ return nil
+ }
+ roIdentity, err := identityOf(roDSN)
+ if err != nil {
+ return err
+ }
+ governanceIdentity, err := identityOf(governanceDSN)
+ if err != nil {
+ return fmt.Errorf("%w: governance database identity could not be verified", ErrUnavailable)
+ }
+ if roIdentity == governanceIdentity {
+ return fmt.Errorf("%w: read DSN points at the governance database (%s)", ErrNotReadOnly, roIdentity)
+ }
+ return nil
+}
diff --git a/internal/dobotaiops/dto.go b/internal/dobotaiops/dto.go
new file mode 100644
index 0000000..cdec73d
--- /dev/null
+++ b/internal/dobotaiops/dto.go
@@ -0,0 +1,125 @@
+package dobotaiops
+
+import (
+ "errors"
+ "fmt"
+ "time"
+)
+
+// ErrInvalidQuery:调用方给的参数不合法(租户、时间范围、游标、分页、通道/状态枚举)。
+// 这类错误绝不触发任何重试,也不应该被当成"外部库不可用"。
+var ErrInvalidQuery = errors.New("invalid dobotai read query")
+
+// Filter 是统计/列举的可选过滤条件。通道与状态只做白名单校验 + 绑定参数,不拼接 SQL。
+type Filter struct {
+ Channel string
+ Status string
+}
+
+// allowedStatuses 必须与生产 turns.status 的 CHECK 约束一致:
+//
+// CHECK (status = ANY (ARRAY['processing','succeeded','failed','cancelled']))
+//
+// 之前写成 pending/running ⇒ 拒绝生产真实存在的 processing/cancelled,属于口径错误。
+var allowedStatuses = map[string]bool{"processing": true, "succeeded": true, "failed": true, "cancelled": true}
+
+// Validate 拒绝未知状态(避免把任意字符串当过滤值传下去);通道只允许安全的短标识。
+func (f Filter) Validate() error {
+ if f.Status != "" && !allowedStatuses[f.Status] {
+ return fmt.Errorf("%w: unknown status", ErrInvalidQuery)
+ }
+ if f.Channel != "" {
+ if len(f.Channel) > 32 {
+ return fmt.Errorf("%w: channel too long", ErrInvalidQuery)
+ }
+ for _, r := range f.Channel {
+ switch {
+ case r >= 'a' && r <= 'z', r >= 'A' && r <= 'Z', r >= '0' && r <= '9', r == '_' || r == '-' || r == '.':
+ default:
+ return fmt.Errorf("%w: channel contains unsupported characters", ErrInvalidQuery)
+ }
+ }
+ }
+ return nil
+}
+
+// CountsResult:某一时间窗内某租户的问答总量与状态/渠道分组(半开区间,按 turn 计次)。
+type CountsResult struct {
+ TenantKey string
+ Start time.Time
+ End time.Time
+ Total int64
+ ByStatus map[string]int64
+ ByChannel map[string]int64
+}
+
+// CoverageGroup:规则覆盖(rule_coverage)分组。注意 evaluator_version 必须保留 —— 不同版本口径不可混算。
+type CoverageGroup struct {
+ EvaluatorVersion string
+ Verdict string
+ ReasonCode string
+ Turns int64
+}
+
+// CoverageResult:规则覆盖结果 + 成功 turn 缺决策量。
+// 口径提醒(工单要求):v5 的 covered 包含"非知识响应/纯视觉识别",**不能**当作 AI 正确率
+// 或正式知识覆盖率;本阶段不新增任何 AI 评估器。
+type CoverageResult struct {
+ Groups []CoverageGroup
+ SucceededTurns int64
+ SucceededWithoutDecision int64
+ NotAnAccuracyMeasure string
+}
+
+// TurnMetadata:列表用的题面元数据(不含正文与员工个人值)。
+type TurnMetadata struct {
+ ID string
+ CreatedAt time.Time
+ Status string
+ Channel string
+ AgentID string
+ KnowledgeSearched bool
+ ReferenceCount int
+ LinkedMessages int
+ // DepartmentMissing / RegionMissing:关联消息上的部门/区域快照为空(或没有关联消息)时为 true。
+ // 生产当前这两列为空 ⇒ 如实返回 unknown,不补写、不猜。
+ DepartmentMissing bool
+ RegionMissing bool
+}
+
+type TurnMetadataPage struct {
+ Items []TurnMetadata
+ NextCursor string
+ HasMore bool
+}
+
+// TurnMessage:授权读取时才返回的消息正文(含员工内容,必须经授权回调)。
+type TurnMessage struct {
+ ID string
+ CreatedAt time.Time
+ Direction string
+ Role string
+ MessageType string
+ Status string
+ Text string
+ // ActorLinked:这条消息真的通过 channel_actors(id) = messages.actor_id 关联到了 actor;
+ // ActorType 只带类型,不带 display_name(避免把员工个人值撒出去)。
+ // 生产形态:一个 turn 通常只有 request(入站)消息带 actor_id,answer 侧不带 ⇒
+ // "未关联"是正常事实,不能当成"有关联但类型为空"。
+ ActorLinked bool
+ ActorType string
+}
+
+// TurnDetail:按租户 + turn_id 的授权读取结果。
+type TurnDetail struct {
+ ID string
+ CreatedAt time.Time
+ Status string
+ Channel string
+ AgentID string
+ Question string
+ Answer string
+ ReferencesJSON []byte
+ ErrorCode string
+ Messages []TurnMessage
+}
diff --git a/internal/dobotaiops/fixture_env_test.go b/internal/dobotaiops/fixture_env_test.go
new file mode 100644
index 0000000..b5f763a
--- /dev/null
+++ b/internal/dobotaiops/fixture_env_test.go
@@ -0,0 +1,101 @@
+package dobotaiops
+
+import (
+ "fmt"
+ "net/url"
+ "os"
+ "strings"
+ "testing"
+)
+
+// 只读接入的集成用例会**建表/灌数据/建角色**(DROP TABLE … CASCADE),所以必须先确认
+// "这是一次性隔离环境"。只凭 TEST_DATABASE_URL 存在就动手是不可接受的:一次误配置
+// 就能把生产或共享库的表删掉。护栏规则(全部为硬条件):
+//
+// 1. 必须显式声明 KG_DOBOTAI_TEST_ISOLATED=1(想动库就得先表态);
+// 2. DSN 必须能解析、必须是 postgres DSN、必须有库名;
+// 3. 库名命中生产/共享库黑名单(含 "prod"、governance 等)⇒ 拒绝;
+// 4. 非本机主机 ⇒ 库名必须含 "test";
+// 5. 本机主机 ⇒ 只额外放行规范的一次性库名 "postgres"(一次性容器默认库),其余仍须含 "test"。
+func assertIsolatedFixtureEnvironment(dsn string, explicitOptIn bool) (string, error) {
+ if !explicitOptIn {
+ return "", fmt.Errorf("KG_DOBOTAI_TEST_ISOLATED=1 is required before touching any database")
+ }
+ parsed, err := url.Parse(strings.TrimSpace(dsn))
+ if err != nil || parsed.Scheme == "" || parsed.Hostname() == "" {
+ return "", fmt.Errorf("TEST_DATABASE_URL must be a PostgreSQL URL")
+ }
+ if parsed.Scheme != "postgres" && parsed.Scheme != "postgresql" {
+ return "", fmt.Errorf("TEST_DATABASE_URL must be a postgres URL")
+ }
+ database := strings.TrimPrefix(parsed.EscapedPath(), "/")
+ if database == "" {
+ return "", fmt.Errorf("TEST_DATABASE_URL must name a database")
+ }
+ lowered := strings.ToLower(database)
+ if strings.Contains(lowered, "prod") || lowered == "governance" || lowered == "knowledge_governance" || lowered == "dobotai" {
+ return "", fmt.Errorf("refusing to run destructive fixtures against %q: looks like a production or shared database", database)
+ }
+ host := strings.ToLower(parsed.Hostname())
+ local := host == "127.0.0.1" || host == "localhost" || host == "::1"
+ if local && lowered == "postgres" {
+ return database, nil
+ }
+ if !strings.Contains(lowered, "test") {
+ return "", fmt.Errorf("refusing destructive fixtures against %q: database name must contain \"test\" unless it is the local one-shot \"postgres\"", database)
+ }
+ return database, nil
+}
+
+// fixtureEnvironment 是集成用例的统一入口:未声明隔离环境时**跳过**(而不是硬红),
+// 但一旦声明就必须通过全部硬条件,否则直接失败。
+func fixtureEnvironment(t *testing.T) string {
+ t.Helper()
+ dsn := strings.TrimSpace(os.Getenv("TEST_DATABASE_URL"))
+ if dsn == "" {
+ t.Skip("TEST_DATABASE_URL is not set")
+ }
+ if strings.TrimSpace(os.Getenv("KG_DOBOTAI_TEST_ISOLATED")) != "1" {
+ t.Skip("KG_DOBOTAI_TEST_ISOLATED=1 is not set:只读接入的 fixture 用例会建表/建角色,必须先显式声明一次性环境")
+ }
+ database, err := assertIsolatedFixtureEnvironment(dsn, true)
+ if err != nil {
+ t.Fatalf("隔离环境校验失败(拒绝执行任何写操作):%v", err)
+ }
+ return database
+}
+
+func TestIsolatedFixtureEnvironmentRefusesMisconfiguration(t *testing.T) {
+ cases := []struct {
+ name string
+ dsn string
+ optIn bool
+ wantErr bool
+ contains string
+ }{
+ {"未声明隔离环境", "postgres://u:p@127.0.0.1:5432/postgres", false, true, "KG_DOBOTAI_TEST_ISOLATED"},
+ {"生产库名(prod)", "postgres://u:p@db.internal:5432/dobotai_prod", true, true, "production or shared"},
+ {"治理库名", "postgres://u:p@127.0.0.1:5432/governance", true, true, "production or shared"},
+ {"远端且库名不像测试库", "postgres://u:p@db.internal:5432/kgdev", true, true, "must contain"},
+ {"非 postgres 协议", "mysql://u:p@127.0.0.1:3306/x_test", true, true, "postgres URL"},
+ {"没有库名", "postgres://u:p@127.0.0.1:5432/", true, true, "must name a database"},
+ {"本机一次性 postgres", "postgres://u:p@127.0.0.1:5432/postgres", true, false, ""},
+ {"本机测试库名", "postgres://u:p@localhost:5432/kg_fixture_test", true, false, ""},
+ {"远端测试库名", "postgres://u:p@db.internal:5432/kg_fixture_test", true, false, ""},
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ database, err := assertIsolatedFixtureEnvironment(tc.dsn, tc.optIn)
+ switch {
+ case tc.wantErr && err == nil:
+ t.Fatalf("必须拒绝,却放行了(database=%q)", database)
+ case tc.wantErr && !strings.Contains(err.Error(), tc.contains):
+ t.Fatalf("拒绝理由应包含 %q,实际:%v", tc.contains, err)
+ case !tc.wantErr && err != nil:
+ t.Fatalf("合法的一次性环境被拒:%v", err)
+ case !tc.wantErr && database == "":
+ t.Fatal("放行时必须返回库名")
+ }
+ })
+ }
+}
diff --git a/internal/dobotaiops/pool.go b/internal/dobotaiops/pool.go
new file mode 100644
index 0000000..f729c05
--- /dev/null
+++ b/internal/dobotaiops/pool.go
@@ -0,0 +1,225 @@
+package dobotaiops
+
+import (
+ "context"
+ "fmt"
+ "net/url"
+ "strings"
+ "time"
+
+ "github.com/jackc/pgx/v5"
+ "github.com/jackc/pgx/v5/pgxpool"
+)
+
+// Client 是对外部生产库的**独立只读**客户端:自己的 pool、自己的凭据、自己的超时。
+// 它没有任何写方法,也不做 DDL/迁移 —— 这是本阶段的接口面本身在保证的事。
+type Client struct {
+ pool *pgxpool.Pool
+ config Config
+ report ACLReport
+ safety SourceSafety
+}
+
+// Build 建立只读客户端:
+// 1. 形状校验 → 2. 从仓库外 0600 secret 读 DSN → 3. 拒绝指向治理主库 →
+// 4. 建独立 pool(default_transaction_read_only=on、statement_timeout、连接上限)→
+// 5. Ping → 6. ACL 自检(不是最小只读就 fail closed)。
+//
+// 任何一步失败都返回 ErrUnavailable / ErrNotReadOnly;调用方据此把功能标记为不可用,
+// **绝不回退到治理主库或应用写账号**。
+func Build(ctx context.Context, cfg Config) (*Client, error) {
+ cfg = cfg.withDefaults()
+ if err := cfg.Validate(); err != nil {
+ return nil, err
+ }
+ dsn, err := ReadDSNFile(cfg.DSNFile)
+ if err != nil {
+ return nil, err
+ }
+ if err := GuardGovernanceDatabase(dsn, cfg.GovernanceDatabaseURL); err != nil {
+ return nil, err
+ }
+ poolConfig, err := pgxpool.ParseConfig(dsn)
+ if err != nil {
+ // 解析失败的原始错误可能带着 DSN,绝不上抛。
+ return nil, fmt.Errorf("%w: DSN could not be parsed", ErrUnavailable)
+ }
+ poolConfig.MaxConns = cfg.MaxConns
+ poolConfig.MinConns = cfg.MinConns
+ poolConfig.MaxConnLifetime = 30 * time.Minute
+ poolConfig.MaxConnIdleTime = 5 * time.Minute
+ poolConfig.ConnConfig.ConnectTimeout = cfg.ConnectTimeout
+ if poolConfig.ConnConfig.RuntimeParams == nil {
+ poolConfig.ConnConfig.RuntimeParams = map[string]string{}
+ }
+ // 会话级只读 + 语句超时:只读默认不是 ACL 的替代品,两层都要有。
+ poolConfig.ConnConfig.RuntimeParams["default_transaction_read_only"] = "on"
+ poolConfig.ConnConfig.RuntimeParams["statement_timeout"] = fmt.Sprintf("%d", (cfg.QueryTimeout + 2*time.Second).Milliseconds())
+ poolConfig.ConnConfig.RuntimeParams["idle_in_transaction_session_timeout"] = "15000"
+ poolConfig.ConnConfig.RuntimeParams["application_name"] = "kg-dobotai-ops-readonly"
+ poolConfig.ConnConfig.RuntimeParams["search_path"] = "pg_catalog,public"
+ if cfg.DialContext != nil {
+ poolConfig.ConnConfig.DialFunc = cfg.DialContext
+ } else if cfg.DialMode == "ssh" {
+ // 拨号地址只从配置里的 DSN 派生(远端解析),不接受 pgx 传入的本机解析结果 ——
+ // 本机 DNS 被 Fake-IP/VPN 劫持时,那个结果会是假地址(实测挂 20s 超时)。
+ dialAddress, addrErr := hostPortOf(dsn)
+ if addrErr != nil {
+ return nil, addrErr
+ }
+ dialer, dialErr := SSHDialer(cfg.SSHTarget, dialAddress)
+ if dialErr != nil {
+ return nil, dialErr
+ }
+ poolConfig.ConnConfig.DialFunc = dialer
+ }
+
+ connectCtx, cancelConnect := context.WithTimeout(ctx, cfg.ConnectTimeout)
+ defer cancelConnect()
+ pool, err := pgxpool.NewWithConfig(connectCtx, poolConfig)
+ if err != nil {
+ return nil, fmt.Errorf("%w: pool could not be created", ErrUnavailable)
+ }
+ client := &Client{pool: pool, config: cfg}
+ pingCtx, cancelPing := context.WithTimeout(ctx, cfg.ConnectTimeout)
+ defer cancelPing()
+ if err := pool.Ping(pingCtx); err != nil {
+ pool.Close()
+ return nil, fmt.Errorf("%w: cannot reach the external read-only database", ErrUnavailable)
+ }
+ auditCtx, cancelAudit := context.WithTimeout(ctx, cfg.QueryTimeout)
+ defer cancelAudit()
+ report, err := AssertReadOnly(auditCtx, poolQuerier{pool: pool})
+ if err != nil {
+ pool.Close()
+ return nil, err
+ }
+ safety, err := AuditSourceSafety(auditCtx, poolQuerier{pool: pool})
+ if err != nil {
+ pool.Close()
+ return nil, err
+ }
+ if cfg.MaxConns > int32(safety.ConnectionLimit) {
+ pool.Close()
+ return nil, fmt.Errorf("%w: pool exceeds source role connection budget", ErrNotReadOnly)
+ }
+ client.report = report
+ client.safety = safety
+ return client, nil
+}
+
+// Close 释放独立 pool(治理主 pool 完全不受影响)。
+func (c *Client) Close() {
+ if c != nil && c.pool != nil {
+ c.pool.Close()
+ }
+}
+
+// ACL 返回启动时自检的权限报告(只含角色与 ACL,不含业务数据)。
+func (c *Client) ACL() ACLReport { return c.report }
+
+// Safety preserves transport/TEMP findings without mislabelling them as fixed.
+func (c *Client) Safety() SourceSafety { return c.safety }
+
+// Config 返回生效后的配置,**已清掉所有连接/凭据字段**(secret 文件路径与治理库 DSN 都不外传;
+// 之前只清了 DSNFile,治理库连接串会跟着这个结构被复制出去)。
+func (c *Client) Config() Config {
+ cfg := c.config
+ cfg.DSNFile = ""
+ cfg.GovernanceDatabaseURL = ""
+ cfg.DialContext = nil
+ return cfg
+}
+
+// Available 是给健康检查/日志用的轻量探测:一次 SELECT 1,带自己的超时。
+func (c *Client) Available(ctx context.Context) error {
+ if c == nil || c.pool == nil {
+ return ErrUnavailable
+ }
+ probeCtx, cancel := context.WithTimeout(ctx, c.config.ConnectTimeout)
+ defer cancel()
+ var one int
+ if err := c.pool.QueryRow(probeCtx, "SELECT 1").Scan(&one); err != nil {
+ return fmt.Errorf("%w: probe failed", ErrUnavailable)
+ }
+ if one != 1 {
+ return fmt.Errorf("%w: probe returned an unexpected value", ErrUnavailable)
+ }
+ return nil
+}
+
+// poolQuerier 让 *pgxpool.Pool 适配本包的最小接口(ACL 与仓储都只用这两种方法)。
+type poolQuerier struct{ pool *pgxpool.Pool }
+
+func (q poolQuerier) QueryRow(ctx context.Context, sql string, args ...any) rowScanner {
+ return q.pool.QueryRow(ctx, sql, args...)
+}
+
+func (q poolQuerier) Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error) {
+ return q.pool.Query(ctx, sql, args...)
+}
+
+// withReadOnlyTx 把一次读放进 REPEATABLE READ + READ ONLY 事务:统计口径固定在同一个
+// as_of 上,且即便账号被误配成可写,这里也没有写的机会。
+func (c *Client) withReadOnlyTx(ctx context.Context, fn func(ctx context.Context, querier querier) error) error {
+ if c == nil || c.pool == nil {
+ return ErrUnavailable
+ }
+ queryCtx, cancel := context.WithTimeout(ctx, c.config.QueryTimeout)
+ defer cancel()
+ tx, err := c.pool.BeginTx(queryCtx, pgx.TxOptions{IsoLevel: pgx.RepeatableRead, AccessMode: pgx.ReadOnly})
+ if err != nil {
+ return fmt.Errorf("%w: cannot open a read-only transaction", ErrUnavailable)
+ }
+ defer func() { _ = tx.Rollback(context.Background()) }()
+ if _, err := AssertReadOnly(queryCtx, txQuerier{tx: tx}); err != nil {
+ return err
+ }
+ if _, err := AuditSourceSafety(queryCtx, txQuerier{tx: tx}); err != nil {
+ return err
+ }
+ if err := fn(queryCtx, txQuerier{tx: tx}); err != nil {
+ return err
+ }
+ if err := tx.Commit(queryCtx); err != nil {
+ return fmt.Errorf("%w: read-only transaction failed", ErrUnavailable)
+ }
+ return nil
+}
+
+type querier interface {
+ QueryRow(ctx context.Context, sql string, args ...any) rowScanner
+ Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)
+}
+
+type txQuerier struct{ tx pgx.Tx }
+
+func (q txQuerier) QueryRow(ctx context.Context, sql string, args ...any) rowScanner {
+ return q.tx.QueryRow(ctx, sql, args...)
+}
+
+func (q txQuerier) Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error) {
+ return q.tx.Query(ctx, sql, args...)
+}
+
+// ErrUnavailableIfNil 让调用方把 nil 客户端当成"未启用"而不是 panic。
+func ErrUnavailableIfNil(client *Client) error {
+ if client == nil {
+ return ErrUnavailable
+ }
+ return nil
+}
+
+// hostPortOf 从 DSN 取"主机:端口"(缺端口按 5432),只用于固定隧道的拨号地址。
+// 只做解析,不返回任何凭据。
+func hostPortOf(dsn string) (string, error) {
+ parsed, err := url.Parse(strings.TrimSpace(dsn))
+ if err != nil || parsed.Hostname() == "" {
+ return "", fmt.Errorf("%w: DSN has no host to dial", ErrUnavailable)
+ }
+ port := parsed.Port()
+ if port == "" {
+ port = "5432"
+ }
+ return parsed.Hostname() + ":" + port, nil
+}
diff --git a/internal/dobotaiops/prod_verify_test.go b/internal/dobotaiops/prod_verify_test.go
new file mode 100644
index 0000000..c22d2ee
--- /dev/null
+++ b/internal/dobotaiops/prod_verify_test.go
@@ -0,0 +1,163 @@
+package dobotaiops
+
+import (
+ "context"
+ "fmt"
+ "net/url"
+ "os"
+ "strings"
+ "testing"
+ "time"
+)
+
+// 生产只读**组合验证**:Go 客户端 + 最小只读账号 + 经批准的 SSH 通路,真读生产数据。
+//
+// 只在前两项都显式给出时运行(默认跳过,绝不在 CI 或误操作下碰生产):
+//
+// KG_DOBOTAI_PROD_VERIFY=1 \
+// KG_DOBOTAI_PROD_DSN_FILE=~/.config/knowledge-governance/secrets/dobotai_ops_ro.env \
+// KG_DOBOTAI_PROD_SSH_TARGET=weknora-prod \
+// go test ./internal/dobotaiops/ -run TestProductionReadOnlyCombinedVerification -v
+//
+// 纪律:只用只读账号;只 SELECT;证据里**不打印**正文、员工姓名或任何凭据。
+func TestProductionReadOnlyCombinedVerification(t *testing.T) {
+ if strings.TrimSpace(os.Getenv("KG_DOBOTAI_PROD_VERIFY")) != "1" {
+ t.Skip("KG_DOBOTAI_PROD_VERIFY≠1:跳过生产组合验证")
+ }
+ dsnFile := expandHome(strings.TrimSpace(os.Getenv("KG_DOBOTAI_PROD_DSN_FILE")))
+ sshTarget := strings.TrimSpace(os.Getenv("KG_DOBOTAI_PROD_SSH_TARGET"))
+ tenantKey := strings.TrimSpace(os.Getenv("KG_DOBOTAI_PROD_TENANT"))
+ if dsnFile == "" || sshTarget == "" || tenantKey == "" {
+ // 租户键必须由调用方给出:查询本身就是"按租户"的,猜一个默认值等于自欺。
+ t.Skip("KG_DOBOTAI_PROD_DSN_FILE / KG_DOBOTAI_PROD_SSH_TARGET / KG_DOBOTAI_PROD_TENANT 未设置:跳过")
+ }
+ dsn, err := ReadDSNFile(dsnFile)
+ if err != nil {
+ t.Fatalf("读只读 secret 失败:%v", err)
+ }
+ parsed, err := url.Parse(dsn)
+ if err != nil {
+ t.Fatal(err)
+ }
+ port := parsed.Port()
+ if port == "" {
+ port = "5432"
+ }
+ // 拨号地址由 DSN 派生(不写死主机),并经 SSH 通路到达:
+ address := parsed.Hostname() + ":" + port
+ t.Logf("经 SSH 目标 %s 拨号到 %s(只读账号 %s)", sshTarget, address, parsed.User.Username())
+
+ // 关键:DialMode=ssh ⇒ 走 SSHDialer(socketpair + ssh -W),不是直连。
+ client, err := Build(context.Background(), Config{
+ DSNFile: dsnFile,
+ GovernanceDatabaseURL: "postgres://governance@not-this-host:5432/governance",
+ DialMode: "ssh",
+ SSHTarget: sshTarget,
+ ConnectTimeout: 10 * time.Second,
+ QueryTimeout: 8 * time.Second,
+ MaxConns: 1,
+ })
+ if err != nil {
+ t.Fatalf("Build()(经 SSH 通路 + 只读账号)失败:%v", err)
+ }
+ defer client.Close()
+ ctx := context.Background()
+
+ report := client.ACL()
+ t.Logf("ACL 报告:role=%s super=%v createrole=%v createdb=%v bypassrls=%v replication=%v schema_create=%v db_create=%v "+
+ "memberships=%d set_role=%d owned_rel=%d owned_schema=%d secdef_exec=%d write_privs=%d missing_selects=%d",
+ report.Role, report.Super, report.CreateRole, report.CreateDB, report.BypassRLS, report.Replication,
+ report.SchemaCreate, report.DatabaseCreate, report.RoleMemberships, report.SetRoleCandidates,
+ report.OwnedRelations, report.OwnedSchemas, report.ExecutableSecDefFns,
+ len(report.WritePrivileges), len(report.MissingSelects))
+
+ now := time.Now().UTC()
+ window, err := NewWindow(tenantKey, now.Add(-14*24*time.Hour).Format(time.RFC3339), now.Add(-30*time.Minute).Format(time.RFC3339), 90*24*time.Hour, now)
+ if err != nil {
+ t.Fatalf("NewWindow() error = %v", err)
+ }
+ counts, err := client.QueryCounts(ctx, window, Filter{})
+ if err != nil {
+ t.Fatalf("QueryCounts() error = %v", err)
+ }
+ t.Logf("窗口 %s → %s:turns=%d 状态=%v 渠道=%v", window.Start.Format(time.RFC3339), window.End.Format(time.RFC3339), counts.Total, counts.ByStatus, counts.ByChannel)
+
+ coverage, err := client.QueryRuleCoverage(ctx, window)
+ if err != nil {
+ t.Fatalf("QueryRuleCoverage() error = %v", err)
+ }
+ byVersion := map[string]int64{}
+ for _, group := range coverage.Groups {
+ byVersion[group.EvaluatorVersion+"|"+group.Verdict] += group.Turns
+ }
+ t.Logf("rule_coverage:成功 turn=%d 缺决策=%d 分组(版本|verdict=%d):%v", coverage.SucceededTurns, coverage.SucceededWithoutDecision, len(coverage.Groups), byVersion)
+
+ page, err := client.ListTurnMetadata(ctx, window, "", 5)
+ if err != nil {
+ t.Fatalf("ListTurnMetadata() error = %v", err)
+ }
+ missingDepartment, missingRegion, linkedNonZero := 0, 0, 0
+ for _, item := range page.Items {
+ if item.DepartmentMissing {
+ missingDepartment++
+ }
+ if item.RegionMissing {
+ missingRegion++
+ }
+ if item.LinkedMessages > 0 {
+ linkedNonZero++
+ }
+ }
+ t.Logf("元数据首页:%d 条(HasMore=%v)|关联消息>0 的 %d 条|部门缺失 %d|区域缺失 %d", len(page.Items), page.HasMore, linkedNonZero, missingDepartment, missingRegion)
+ if len(page.Items) == 0 {
+ t.Fatal("窗口内没有 turn:窗口选错了")
+ }
+
+ // 人员关联回归:用真实 turn 走授权读取,检查关联是否真的命中(关联字段错就会全空)。
+ // 生产形态:一个 turn 的 request(入站)消息带 actor_id,answer(出站)不带 ⇒
+ // 入站必须关联到 actor,出站未关联属正常事实(用 ActorLinked 区分,不混为一谈)。
+ inboundLinked, inboundUnlinked, outboundUnlinked := 0, 0, 0
+ for _, item := range page.Items {
+ detail, err := client.GetTurnForAuthorizedRead(ctx, window.TenantKey, item.ID, func(string) error { return nil })
+ if err != nil {
+ continue
+ }
+ for _, message := range detail.Messages {
+ switch {
+ case message.Direction == "inbound" && message.ActorLinked && message.ActorType != "":
+ inboundLinked++
+ case message.Direction == "inbound":
+ inboundUnlinked++
+ case !message.ActorLinked:
+ outboundUnlinked++
+ }
+ }
+ }
+ t.Logf("人员关联(channel_actors.id = messages.actor_id):入站已关联 %d / 入站未关联 %d / 出站无 actor %d",
+ inboundLinked, inboundUnlinked, outboundUnlinked)
+ if inboundLinked == 0 {
+ t.Fatal("人员关联一处都没命中:关联字段或通路有问题")
+ }
+ if inboundUnlinked > 0 {
+ t.Fatalf("有 %d 条入站消息没关联到 actor:", inboundUnlinked)
+ }
+
+ // 只读边界:ACL 函数自证(不执行任何写语句)。
+ for _, table := range RequiredTables {
+ if !strings.Contains(fmt.Sprint(report.CheckedTableList), table) {
+ t.Fatalf("自检没覆盖 %s", table)
+ }
+ }
+ if err := client.Available(ctx); err != nil {
+ t.Fatalf("可用性探测失败:%v", err)
+ }
+}
+
+func expandHome(path string) string {
+ if strings.HasPrefix(path, "~/") {
+ if home, err := os.UserHomeDir(); err == nil {
+ return home + path[1:]
+ }
+ }
+ return path
+}
diff --git a/internal/dobotaiops/records.go b/internal/dobotaiops/records.go
new file mode 100644
index 0000000..ed494ff
--- /dev/null
+++ b/internal/dobotaiops/records.go
@@ -0,0 +1,243 @@
+package dobotaiops
+
+import (
+ "context"
+ "crypto/sha256"
+ "encoding/base64"
+ "encoding/hex"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "strings"
+ "time"
+ "unicode/utf8"
+
+ "github.com/jackc/pgx/v5"
+)
+
+const CoverageRuleVersion = "governance-answer-substring-v1"
+const noPublishedMarker = "暂无已发布"
+
+var ErrRecordNotFound = errors.New("qa record not found")
+
+type CoverageCheck struct {
+ Verdict string `json:"verdict,omitempty"`
+ State string `json:"state"`
+ RuleVersion string `json:"rule_version"`
+ MatchedText string `json:"matched_text,omitempty"`
+}
+
+// Absence of this exact substring is not evidence that knowledge covers a question.
+func CheckAnswerCoverage(answer string) CoverageCheck {
+ result := CoverageCheck{State: "pending", RuleVersion: CoverageRuleVersion}
+ if strings.Contains(answer, noPublishedMarker) {
+ result.State = "checked"
+ result.Verdict = "uncovered"
+ result.MatchedText = noPublishedMarker
+ }
+ return result
+}
+
+type SourceCoverage struct {
+ Verdict string `json:"verdict"`
+ ReasonCode string `json:"reason_code"`
+ EvaluatorVersion string `json:"evaluator_version"`
+}
+
+type RecordFeedback struct {
+ AskerValue string `json:"asker_value"`
+ Up int64 `json:"up"`
+ Down int64 `json:"down"`
+}
+
+type Record struct {
+ ID string `json:"id"`
+ Status string `json:"status"`
+ Question string `json:"question"`
+ Answer string `json:"answer"`
+ AskedAt time.Time `json:"asked_at"`
+ TimeSource string `json:"time_source"`
+ Asker string `json:"asker"`
+ TriggerPerson string `json:"trigger_person"`
+ Department string `json:"department"`
+ Region string `json:"region"`
+ References json.RawMessage `json:"references"`
+ Media json.RawMessage `json:"media"`
+ SourceCoverage SourceCoverage `json:"source_coverage"`
+ Feedback RecordFeedback `json:"feedback"`
+ Coverage CoverageCheck `json:"coverage"`
+}
+
+type RecordQuery struct {
+ Window Window
+ Keyword string
+ Cursor string
+ Limit int
+}
+
+type RecordPage struct {
+ Items []Record `json:"items"`
+ Columns []string `json:"columns"`
+ Total int64 `json:"total"`
+ HasMore bool `json:"has_more"`
+ NextCursor string `json:"next_cursor"`
+ AsOf time.Time `json:"as_of"`
+}
+
+type recordCursor struct {
+ AskedAt time.Time `json:"at"`
+ ID string `json:"id"`
+ Scope string `json:"scope"`
+}
+
+// A single inbound-message join controls names/time. Feedback is preaggregated;
+// joining each feedback row directly would multiply the business event count.
+const recordsBaseSQL = `
+WITH records AS (
+ SELECT t.id,COALESCE(m.created_at,t.created_at) AS asked_at,t.question,
+ jsonb_build_object(
+ 'id',t.id,'status',t.status,'question',t.question,'answer',t.answer,
+ 'asked_at',COALESCE(m.created_at,t.created_at),
+ 'time_source',CASE WHEN m.id IS NULL THEN 'turn.created_at' ELSE 'request_message.created_at' END,
+ 'asker',COALESCE(NULLIF(m.actor_name_snapshot,''),a.display_name,''),
+ 'trigger_person',COALESCE(m.trigger_person_snapshot,''),
+ 'department',COALESCE(m.department_snapshot,''),'region',COALESCE(m.region_snapshot,''),
+ 'references',t.references_json,'media',COALESCE(m.media_json,'[]'::jsonb),
+ 'source_coverage',jsonb_build_object('verdict',COALESCE(c.verdict,''),'reason_code',COALESCE(c.reason_code,''),'evaluator_version',COALESCE(c.evaluator_version,'')),
+ 'feedback',jsonb_build_object('asker_value',COALESCE(f.asker_value,''),'up',f.up_count,'down',f.down_count)
+ ) AS payload
+ FROM public.turns t
+ LEFT JOIN public.messages m ON m.id=t.request_message_id AND m.tenant_key=t.tenant_key AND m.channel=t.channel AND m.direction='inbound'
+ LEFT JOIN public.channel_actors a ON a.id=m.actor_id AND a.tenant_key=t.tenant_key AND a.channel=t.channel
+ LEFT JOIN LATERAL (
+ SELECT verdict,reason_code,evaluator_version FROM public.coverage_decisions c
+ WHERE c.turn_id=t.id AND c.tenant_key=t.tenant_key AND c.channel=t.channel
+ ORDER BY c.created_at DESC,c.evaluator_version DESC LIMIT 1
+ ) c ON true
+ LEFT JOIN LATERAL (
+ SELECT count(*) FILTER(WHERE value='up') AS up_count,count(*) FILTER(WHERE value='down') AS down_count,
+ max(value) FILTER(WHERE actor_id=m.actor_id) AS asker_value
+ FROM public.answer_feedback f
+ WHERE f.turn_id=t.id AND f.answer_message_id=t.answer_message_id AND f.tenant_key=t.tenant_key AND f.channel=t.channel
+ ) f ON true
+ WHERE t.tenant_key=$1 AND t.channel='dingtalk'
+)`
+
+const recordFilterSQL = ` asked_at >= $2 AND asked_at < $3 AND ($4='' OR question ILIKE $4 ESCAPE '\')`
+
+// Availability is over the entire filtered result, not just the current page.
+const recordColumnsSQL = `SELECT count(*),jsonb_build_object(
+ 'answer',COALESCE(bool_or(payload->>'answer'<>''),false),
+ 'coverage',COALESCE(bool_or(strpos(payload->>'answer',$5)>0),false),
+ 'asked_at',count(*)>0,
+ 'asker',COALESCE(bool_or(payload->>'asker'<>''),false),
+ 'question',COALESCE(bool_or(question<>''),false),
+ 'trigger_person',COALESCE(bool_or(payload->>'trigger_person'<>''),false),
+ 'department',COALESCE(bool_or(payload->>'department'<>''),false),
+ 'region',COALESCE(bool_or(payload->>'region'<>''),false),
+ 'feedback',COALESCE(bool_or(payload->'feedback'->>'asker_value'<>'' OR
+ (payload->'feedback'->>'up')::bigint>0 OR (payload->'feedback'->>'down')::bigint>0),false)
+ )::text FROM records WHERE `
+
+var recordColumnOrder = []string{"question_chinese", "answer", "coverage", "is_correct", "product_category", "problem_type", "root_cause", "asked_at", "asker", "question", "language", "trigger_person", "department", "region", "feedback"}
+
+func (c *Client) ListRecords(ctx context.Context, query RecordQuery) (RecordPage, error) {
+ if err := c.validateQueryWindow(query.Window); err != nil {
+ return RecordPage{}, err
+ }
+ if query.Limit < 1 || query.Limit > 100 || !utf8.ValidString(query.Keyword) || utf8.RuneCountInString(query.Keyword) > 200 || strings.ContainsRune(query.Keyword, 0) || len(query.Cursor) > 2048 {
+ return RecordPage{}, fmt.Errorf("%w: invalid record filters", ErrInvalidQuery)
+ }
+ scopeBytes, _ := json.Marshal([]string{query.Window.TenantKey, query.Window.Start.UTC().Format(time.RFC3339Nano), query.Window.End.UTC().Format(time.RFC3339Nano), query.Keyword})
+ scopeSum := sha256.Sum256(scopeBytes)
+ scope := hex.EncodeToString(scopeSum[:])
+ var cursor recordCursor
+ var before any
+ if query.Cursor != "" {
+ decoded, err := base64.RawURLEncoding.DecodeString(query.Cursor)
+ if err != nil || json.Unmarshal(decoded, &cursor) != nil || cursor.Scope != scope || cursor.ID == "" || len(cursor.ID) > 256 || cursor.AskedAt.Before(query.Window.Start) || !cursor.AskedAt.Before(query.Window.End) {
+ return RecordPage{}, fmt.Errorf("%w: invalid or mismatched cursor", ErrInvalidQuery)
+ }
+ before = cursor.AskedAt
+ }
+ pattern := ""
+ if query.Keyword != "" {
+ pattern = "%" + strings.NewReplacer(`\`, `\\`, `%`, `\%`, `_`, `\_`).Replace(query.Keyword) + "%"
+ }
+ args := []any{query.Window.TenantKey, query.Window.Start, query.Window.End, pattern}
+ page := RecordPage{Items: make([]Record, 0), Columns: make([]string, 0)}
+ err := c.withReadOnlyTx(ctx, func(ctx context.Context, q querier) error {
+ if err := q.QueryRow(ctx, "SELECT transaction_timestamp()").Scan(&page.AsOf); err != nil {
+ return ErrUnavailable
+ }
+ var rawColumns string
+ if err := q.QueryRow(ctx, recordsBaseSQL+recordColumnsSQL+recordFilterSQL, append(args, noPublishedMarker)...).Scan(&page.Total, &rawColumns); err != nil {
+ return fmt.Errorf("%w: record count failed", ErrUnavailable)
+ }
+ var available map[string]bool
+ if err := json.Unmarshal([]byte(rawColumns), &available); err != nil {
+ return ErrUnavailable
+ }
+ for _, column := range recordColumnOrder {
+ if available[column] {
+ page.Columns = append(page.Columns, column)
+ }
+ }
+ rows, err := q.Query(ctx, recordsBaseSQL+` SELECT payload::text FROM records WHERE `+recordFilterSQL+`
+ AND ($5::timestamptz IS NULL OR (asked_at,id)<($5,$6)) ORDER BY asked_at DESC,id DESC LIMIT $7`, append(args, before, cursor.ID, query.Limit+1)...)
+ if err != nil {
+ return fmt.Errorf("%w: record list failed", ErrUnavailable)
+ }
+ defer rows.Close()
+ for rows.Next() {
+ var raw string
+ if err := rows.Scan(&raw); err != nil {
+ return ErrUnavailable
+ }
+ var item Record
+ if err := json.Unmarshal([]byte(raw), &item); err != nil {
+ return ErrUnavailable
+ }
+ item.Coverage = CheckAnswerCoverage(item.Answer)
+ page.Items = append(page.Items, item)
+ }
+ return rows.Err()
+ })
+ if err != nil {
+ return RecordPage{}, err
+ }
+ if len(page.Items) > query.Limit {
+ page.HasMore = true
+ page.Items = page.Items[:query.Limit]
+ last := page.Items[len(page.Items)-1]
+ raw, err := json.Marshal(recordCursor{AskedAt: last.AskedAt, ID: last.ID, Scope: scope})
+ if err != nil {
+ return RecordPage{}, ErrUnavailable
+ }
+ page.NextCursor = base64.RawURLEncoding.EncodeToString(raw)
+ }
+ return page, nil
+}
+
+func (c *Client) GetRecord(ctx context.Context, tenantKey, id string) (Record, error) {
+ if strings.TrimSpace(tenantKey) == "" || id == "" || len(id) > 256 || strings.ContainsRune(id, 0) {
+ return Record{}, ErrInvalidQuery
+ }
+ var item Record
+ err := c.withReadOnlyTx(ctx, func(ctx context.Context, q querier) error {
+ var raw string
+ err := q.QueryRow(ctx, recordsBaseSQL+` SELECT payload::text FROM records WHERE id=$2`, tenantKey, id).Scan(&raw)
+ if errors.Is(err, pgx.ErrNoRows) {
+ return ErrRecordNotFound
+ }
+ if err != nil {
+ return ErrUnavailable
+ }
+ if err := json.Unmarshal([]byte(raw), &item); err != nil {
+ return ErrUnavailable
+ }
+ item.Coverage = CheckAnswerCoverage(item.Answer)
+ return nil
+ })
+ return item, err
+}
diff --git a/internal/dobotaiops/records_integration_test.go b/internal/dobotaiops/records_integration_test.go
new file mode 100644
index 0000000..3056fd7
--- /dev/null
+++ b/internal/dobotaiops/records_integration_test.go
@@ -0,0 +1,78 @@
+package dobotaiops
+
+import (
+ "context"
+ "errors"
+ "testing"
+ "time"
+
+ "github.com/jackc/pgx/v5/pgxpool"
+)
+
+func qaRecordsFixture(t *testing.T, pool *pgxpool.Pool) string {
+ t.Helper()
+ dsn := buildFixture(t, pool)
+ execFixture(t, pool,
+ `ALTER TABLE messages ADD COLUMN actor_name_snapshot text NOT NULL DEFAULT '', ADD COLUMN trigger_person_snapshot text NOT NULL DEFAULT '', ADD COLUMN media_json jsonb NOT NULL DEFAULT '[]'`,
+ `CREATE TABLE answer_feedback(id text PRIMARY KEY,tenant_key text,channel text,turn_id text,answer_message_id text,actor_id text,value text)`,
+ `GRANT SELECT ON answer_feedback TO kg_ro_fixture`,
+ `UPDATE messages SET actor_name_snapshot='测试人员',trigger_person_snapshot='回调昵称' WHERE id='msg-req-3'`,
+ `UPDATE turns SET answer='根据引用,当前暂无已发布的权威知识,暂不建议操作。' WHERE id='turn-3'`,
+ `INSERT INTO answer_feedback VALUES ('fb1','default','dingtalk','turn-3','msg-ans-3','actor-row-1','up'),('fb2','default','dingtalk','turn-3','msg-ans-3','another-person','down'),('fb3','other-tenant','dingtalk','turn-3','msg-ans-3','actor-row-1','down')`,
+ )
+ return dsn
+}
+
+func TestQARecordSearchPreservesSourceAndDoesNotMultiplyFeedback(t *testing.T) {
+ pool := fixturePool(t)
+ client := buildReadOnlyClient(t, qaRecordsFixture(t, pool))
+ window := Window{TenantKey: "default", Start: time.Date(2026, 10, 14, 0, 0, 0, 0, time.UTC), End: time.Date(2026, 10, 15, 0, 0, 0, 0, time.UTC)}
+ query := RecordQuery{Window: window, Keyword: "第三", Limit: 20}
+ page, err := client.ListRecords(context.Background(), query)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if page.Total != 1 || len(page.Items) != 1 {
+ t.Fatalf("feedback multiplied turns: total=%d rows=%d", page.Total, len(page.Items))
+ }
+ item := page.Items[0]
+ if item.ID != "turn-3" || item.Question != "第三问(正文)" || item.Asker != "测试人员" || item.TriggerPerson != "回调昵称" {
+ t.Fatalf("explicit field mapping failed: %+v", item)
+ }
+ if item.Coverage.Verdict != "uncovered" || item.SourceCoverage.Verdict != "covered" {
+ t.Fatalf("governance must override reference-prioritized source without rewriting it: %+v", item)
+ }
+ if item.Feedback.AskerValue != "up" || item.Feedback.Up != 1 || item.Feedback.Down != 1 {
+ t.Fatalf("asker and aggregate feedback were conflated: %+v", item.Feedback)
+ }
+ query.Keyword = "%"
+ page, err = client.ListRecords(context.Background(), query)
+ if err != nil || page.Total != 0 {
+ t.Fatalf("keyword wildcard must be literal: total=%d err=%v", page.Total, err)
+ }
+ query.Keyword = ""
+ query.Limit = 1
+ page, err = client.ListRecords(context.Background(), query)
+ if err != nil || page.Total != 4 || len(page.Items) != 1 || !page.HasMore || page.NextCursor == "" {
+ t.Fatalf("invalid first page: %+v %v", page, err)
+ }
+ firstID := page.Items[0].ID
+ foundFeedback := false
+ for _, column := range page.Columns {
+ if column == "feedback" {
+ foundFeedback = true
+ }
+ }
+ if !foundFeedback {
+ t.Fatal("a populated column elsewhere in the filtered result must not be hidden by an empty first page")
+ }
+ query.Cursor = page.NextCursor
+ next, err := client.ListRecords(context.Background(), query)
+ if err != nil || len(next.Items) != 1 || next.Items[0].ID == firstID {
+ t.Fatalf("invalid cursor page: %+v %v", next, err)
+ }
+ query.Keyword = "changed"
+ if _, err := client.ListRecords(context.Background(), query); !errors.Is(err, ErrInvalidQuery) {
+ t.Fatalf("cursor must be scoped to its filters: %v", err)
+ }
+}
diff --git a/internal/dobotaiops/records_prod_verify_test.go b/internal/dobotaiops/records_prod_verify_test.go
new file mode 100644
index 0000000..004c8fd
--- /dev/null
+++ b/internal/dobotaiops/records_prod_verify_test.go
@@ -0,0 +1,90 @@
+package dobotaiops
+
+import (
+ "context"
+ "errors"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+ "time"
+)
+
+// Explicit opt-in only. This test executes catalog/SELECT queries, never
+// migrations, permission changes, fixture helpers or business writes.
+func TestProductionQAQueryReadOnlyVerification(t *testing.T) {
+ if os.Getenv("KG_DOBOTAI_PROD_VERIFY") != "1" {
+ t.Skip("explicit production read verification is disabled")
+ }
+ path, target := os.Getenv("KG_DOBOTAI_PROD_DSN_FILE"), os.Getenv("KG_DOBOTAI_PROD_SSH_TARGET")
+ if path == "" || target == "" {
+ t.Fatal("approved source credential file and SSH target required")
+ }
+ client, err := Build(context.Background(), Config{DSNFile: path, GovernanceDatabaseURL: "postgres://governance@not-this-source/governance", DialMode: "ssh", SSHTarget: target, ConnectTimeout: 10 * time.Second, QueryTimeout: 12 * time.Second, MaxConns: 1})
+ if err != nil {
+ t.Fatalf("dedicated read source blocked: %v", err)
+ }
+ defer client.Close()
+ now := time.Now().UTC()
+ start, end := now.Add(-14*24*time.Hour), now.Add(-30*time.Minute)
+ tenant := os.Getenv("KG_DOBOTAI_PROD_TENANT")
+ if tenant == "" {
+ // Discover, never guess: refuse if this approved source is not single-tenant.
+ var tenants int
+ err = client.withReadOnlyTx(context.Background(), func(ctx context.Context, q querier) error {
+ return q.QueryRow(ctx, `SELECT count(DISTINCT tenant_key),COALESCE(min(tenant_key),'') FROM public.turns WHERE channel='dingtalk' AND created_at >= $1 AND created_at < $2`, start, end).Scan(&tenants, &tenant)
+ })
+ if err != nil || tenants != 1 || tenant == "" {
+ t.Fatal("source does not identify one authorized tenant; explicit scope is required")
+ }
+ }
+ query := RecordQuery{Window: Window{TenantKey: tenant, Start: start, End: end}, Limit: 5}
+ page, err := client.ListRecords(context.Background(), query)
+ if err != nil {
+ t.Fatalf("real query implementation failed: %v", err)
+ }
+ if page.Total < 1 || len(page.Items) < 1 {
+ t.Fatal("no real source data in the bounded window")
+ }
+ detail, err := client.GetRecord(context.Background(), tenant, page.Items[0].ID)
+ if err != nil || detail.Question != page.Items[0].Question || detail.Answer != page.Items[0].Answer {
+ t.Fatal("source list/detail content mismatch")
+ }
+ if _, err := client.GetRecord(context.Background(), "qaops-not-authorized-tenant", page.Items[0].ID); !errors.Is(err, ErrRecordNotFound) {
+ t.Fatal("tenant isolation failed")
+ }
+ if page.HasMore {
+ query.Cursor = page.NextCursor
+ next, err := client.ListRecords(context.Background(), query)
+ if err != nil {
+ t.Fatalf("real cursor page failed: %v", err)
+ }
+ ids := map[string]bool{}
+ for _, item := range page.Items {
+ ids[item.ID] = true
+ }
+ for _, item := range next.Items {
+ if ids[item.ID] {
+ t.Fatal("cursor pagination repeated a turn")
+ }
+ }
+ }
+ safety := client.Safety()
+ if output := os.Getenv("KG_DOBOTAI_PROD_SCOPE_FILE"); output != "" {
+ // Optional local browser-harness handoff: one tenant key only, never
+ // credentials/employee data, outside Git, exclusive creation and 0600.
+ if !strings.HasPrefix(filepath.Clean(output), filepath.Clean(os.TempDir())+string(os.PathSeparator)) {
+ t.Fatal("scope handoff must stay inside the scratch directory")
+ }
+ file, err := os.OpenFile(output, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600)
+ if err != nil {
+ t.Fatal("cannot create private scope handoff")
+ }
+ _, writeErr := file.WriteString(tenant)
+ closeErr := file.Close()
+ if writeErr != nil || closeErr != nil {
+ t.Fatal("private scope handoff failed")
+ }
+ }
+ t.Logf("REAL_SOURCE_READ_VERIFIED total=%d first_page=%d cursor=%t columns=%v as_of=%s tables_audited=%d effective_table_writes=%d column_writes=%d sequence_writes=%d schema_creates=%d temp=%t ssl=%t; no content or identity logged", page.Total, len(page.Items), page.HasMore, page.Columns, page.AsOf.UTC().Format(time.RFC3339), safety.TablesChecked, safety.TableWrites, safety.ColumnWrites, safety.SequenceWrites, safety.SchemaCreates, safety.DatabaseTemp, safety.SSL)
+}
diff --git a/internal/dobotaiops/repository.go b/internal/dobotaiops/repository.go
new file mode 100644
index 0000000..3ca104f
--- /dev/null
+++ b/internal/dobotaiops/repository.go
@@ -0,0 +1,307 @@
+package dobotaiops
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "strings"
+ "time"
+)
+
+// 本阶段只读查询模块(工单第 4 项)。纪律:
+// - 一律绑定参数;列固定;不拼接调用方给的 SQL/排序字段;
+// - 时间统一半开区间 created_at >= $start AND created_at < $end;
+// - 按 turn 计次;跨租户/渠道的连接同时校验 tenant_key 与 channel;
+// - 只走 REPEATABLE READ + READ ONLY 事务,口径固定在同一个 as_of 上。
+
+const countsTotalSQL = `
+SELECT count(*)::bigint
+FROM turns
+WHERE tenant_key = $1 AND created_at >= $2 AND created_at < $3
+ AND ($4 = '' OR channel = $4) AND ($5 = '' OR status = $5)`
+
+const countsBySQL = `
+SELECT %s, count(*)::bigint
+FROM turns
+WHERE tenant_key = $1 AND created_at >= $2 AND created_at < $3
+ AND ($4 = '' OR channel = $4) AND ($5 = '' OR status = $5)
+GROUP BY 1
+ORDER BY 1`
+
+// QueryCounts 返回某租户在窗口内的问答总量与状态/渠道分组(按 turn 计次)。
+func (c *Client) QueryCounts(ctx context.Context, window Window, filter Filter) (CountsResult, error) {
+ if err := filter.Validate(); err != nil {
+ return CountsResult{}, err
+ }
+ if err := c.validateQueryWindow(window); err != nil {
+ return CountsResult{}, err
+ }
+ result := CountsResult{TenantKey: window.TenantKey, Start: window.Start, End: window.End,
+ ByStatus: map[string]int64{}, ByChannel: map[string]int64{}}
+ err := c.withReadOnlyTx(ctx, func(ctx context.Context, q querier) error {
+ if err := q.QueryRow(ctx, countsTotalSQL, window.TenantKey, window.Start, window.End, filter.Channel, filter.Status).
+ Scan(&result.Total); err != nil {
+ return fmt.Errorf("%w: total count failed", ErrUnavailable)
+ }
+ statusRows, err := q.Query(ctx, fmt.Sprintf(countsBySQL, "status"), window.TenantKey, window.Start, window.End, filter.Channel, filter.Status)
+ if err != nil {
+ return fmt.Errorf("%w: status grouping failed", ErrUnavailable)
+ }
+ defer statusRows.Close()
+ for statusRows.Next() {
+ var status string
+ var count int64
+ if err := statusRows.Scan(&status, &count); err != nil {
+ return fmt.Errorf("%w: status grouping failed", ErrUnavailable)
+ }
+ result.ByStatus[status] = count
+ }
+ channelRows, err := q.Query(ctx, fmt.Sprintf(countsBySQL, "channel"), window.TenantKey, window.Start, window.End, filter.Channel, filter.Status)
+ if err != nil {
+ return fmt.Errorf("%w: channel grouping failed", ErrUnavailable)
+ }
+ defer channelRows.Close()
+ for channelRows.Next() {
+ var channel string
+ var count int64
+ if err := channelRows.Scan(&channel, &count); err != nil {
+ return fmt.Errorf("%w: channel grouping failed", ErrUnavailable)
+ }
+ result.ByChannel[channel] = count
+ }
+ if err := statusRows.Err(); err != nil {
+ return fmt.Errorf("%w: status grouping failed", ErrUnavailable)
+ }
+ return channelRows.Err()
+ })
+ if err != nil {
+ return CountsResult{}, err
+ }
+ return result, nil
+}
+
+const coverageByVersionSQL = `
+SELECT c.evaluator_version, c.verdict, c.reason_code, count(DISTINCT c.turn_id)::bigint
+FROM coverage_decisions c
+JOIN turns t ON t.id = c.turn_id AND t.tenant_key = c.tenant_key AND t.channel = c.channel
+WHERE t.tenant_key = $1 AND t.created_at >= $2 AND t.created_at < $3
+GROUP BY 1, 2, 3
+ORDER BY 1, 2, 3`
+
+const succeededTurnStatsSQL = `
+SELECT count(*)::bigint,
+ count(*) FILTER (
+ WHERE NOT EXISTS (
+ SELECT 1 FROM coverage_decisions c
+ WHERE c.turn_id = t.id AND c.tenant_key = t.tenant_key AND c.channel = t.channel
+ )
+ )::bigint
+FROM turns t
+WHERE t.tenant_key = $1 AND t.status = 'succeeded' AND t.created_at >= $2 AND t.created_at < $3`
+
+// QueryRuleCoverage 返回规则覆盖分组与"成功 turn 缺决策"量。
+// 注意:这是 rule_coverage(规则决策),**不是** AI 正确率或正式知识覆盖率;
+// 不同 evaluator_version 的口径不会混算。
+func (c *Client) QueryRuleCoverage(ctx context.Context, window Window) (CoverageResult, error) {
+ if err := c.validateQueryWindow(window); err != nil {
+ return CoverageResult{}, err
+ }
+ result := CoverageResult{NotAnAccuracyMeasure: "rule_coverage 只是规则决策覆盖;v5 的 covered 含非知识响应/纯视觉识别,不能当 AI 正确率或正式知识覆盖率"}
+ err := c.withReadOnlyTx(ctx, func(ctx context.Context, q querier) error {
+ rows, err := q.Query(ctx, coverageByVersionSQL, window.TenantKey, window.Start, window.End)
+ if err != nil {
+ return fmt.Errorf("%w: coverage grouping failed", ErrUnavailable)
+ }
+ defer rows.Close()
+ for rows.Next() {
+ var group CoverageGroup
+ if err := rows.Scan(&group.EvaluatorVersion, &group.Verdict, &group.ReasonCode, &group.Turns); err != nil {
+ return fmt.Errorf("%w: coverage grouping failed", ErrUnavailable)
+ }
+ result.Groups = append(result.Groups, group)
+ }
+ if err := rows.Err(); err != nil {
+ return fmt.Errorf("%w: coverage grouping failed", ErrUnavailable)
+ }
+ if err := q.QueryRow(ctx, succeededTurnStatsSQL, window.TenantKey, window.Start, window.End).
+ Scan(&result.SucceededTurns, &result.SucceededWithoutDecision); err != nil {
+ return fmt.Errorf("%w: succeeded turn stats failed", ErrUnavailable)
+ }
+ return nil
+ })
+ if err != nil {
+ return CoverageResult{}, err
+ }
+ return result, nil
+}
+
+const listTurnMetadataSQL = `
+SELECT t.id, t.created_at, t.status, t.channel, t.agent_id, t.knowledge_searched,
+ CASE WHEN jsonb_typeof(t.references_json) = 'array' THEN jsonb_array_length(t.references_json) ELSE 0 END,
+ linked.total,
+ COALESCE(linked.department_missing, TRUE),
+ COALESCE(linked.region_missing, TRUE)
+FROM turns t
+LEFT JOIN LATERAL (
+ SELECT count(*)::int AS total,
+ bool_and(COALESCE(m.department_snapshot, '') = '') AS department_missing,
+ bool_and(COALESCE(m.region_snapshot, '') = '') AS region_missing
+ FROM messages m
+ WHERE m.tenant_key = t.tenant_key AND m.channel = t.channel
+ AND m.id = ANY(array_remove(ARRAY[t.request_message_id, t.answer_message_id], NULL))
+) linked ON TRUE
+WHERE t.tenant_key = $1 AND t.created_at >= $2 AND t.created_at < $3
+ AND ($4::timestamptz IS NULL OR (t.created_at, t.id) < ($4::timestamptz, $5::text))
+ORDER BY t.created_at DESC, t.id DESC
+LIMIT $6`
+
+// ListTurnMetadata 用 (created_at, id) 游标稳定翻页(倒序);limit 硬上限 100。
+// 返回的是元数据:不含正文、不含员工个人值;部门/区域快照为空如实标记为 missing。
+func (c *Client) ListTurnMetadata(ctx context.Context, window Window, cursor string, limit int) (TurnMetadataPage, error) {
+ if err := c.validateQueryWindow(window); err != nil {
+ return TurnMetadataPage{}, err
+ }
+ if limit <= 0 {
+ limit = 50
+ }
+ if limit > c.config.MaxPageSize {
+ return TurnMetadataPage{}, fmt.Errorf("%w: limit exceeds %d", ErrInvalidQuery, c.config.MaxPageSize)
+ }
+ var decoded Cursor
+ var cursorTime *time.Time
+ if strings.TrimSpace(cursor) != "" {
+ value, err := DecodeCursor(cursor)
+ if err != nil {
+ return TurnMetadataPage{}, err
+ }
+ decoded = value
+ cursorTime = &decoded.CreatedAt
+ }
+ page := TurnMetadataPage{}
+ err := c.withReadOnlyTx(ctx, func(ctx context.Context, q querier) error {
+ rows, err := q.Query(ctx, listTurnMetadataSQL, window.TenantKey, window.Start, window.End, cursorTime, decoded.ID, limit+1)
+ if err != nil {
+ return fmt.Errorf("%w: turn listing failed", ErrUnavailable)
+ }
+ defer rows.Close()
+ for rows.Next() {
+ var item TurnMetadata
+ if err := rows.Scan(&item.ID, &item.CreatedAt, &item.Status, &item.Channel, &item.AgentID,
+ &item.KnowledgeSearched, &item.ReferenceCount, &item.LinkedMessages,
+ &item.DepartmentMissing, &item.RegionMissing); err != nil {
+ return fmt.Errorf("%w: turn listing failed", ErrUnavailable)
+ }
+ page.Items = append(page.Items, item)
+ }
+ return rows.Err()
+ })
+ if err != nil {
+ return TurnMetadataPage{}, err
+ }
+ if len(page.Items) > limit {
+ // 多取一条只为判断是否还有下一页;游标必须指向**最后一条真正返回的行**,
+ // 否则下一页会跳过那一条(集成测试专门钉这个边界)。
+ page.Items = page.Items[:limit]
+ page.HasMore = true
+ tail := page.Items[len(page.Items)-1]
+ page.NextCursor = EncodeCursor(Cursor{CreatedAt: tail.CreatedAt.UTC(), ID: tail.ID})
+ }
+ return page, nil
+}
+
+const authorizedTurnSQL = `
+SELECT t.id, t.created_at, t.status, t.channel, t.agent_id, t.question, t.answer,
+ COALESCE(t.references_json::text, '[]'), t.error_message
+FROM turns t
+WHERE t.tenant_key = $1 AND t.id = $2`
+
+const authorizedMessagesSQL = `
+SELECT m.id, m.created_at, m.direction, m.role, m.message_type, m.status, m.text_content,
+ a.id IS NOT NULL,
+ COALESCE(a.actor_type, '')
+FROM messages m
+LEFT JOIN channel_actors a
+ -- 关联字段必须是 channel_actors.id:生产 FK 是 messages.actor_id → channel_actors(id)。
+ -- 用 external_actor_id 关联在生产对拍里命中 0 行(正确关联 2234 行)。
+ ON a.tenant_key = m.tenant_key AND a.channel = m.channel AND a.id = m.actor_id
+WHERE m.tenant_key = $1 AND m.channel = $2
+ AND m.id = ANY(array_remove(ARRAY[$3, $4], NULL))
+ORDER BY m.created_at, m.id`
+
+// GetTurnForAuthorizedRead 按租户 + turn_id 读取正文/引用(必要时)。
+// **必须**传入授权回调(返回错误即拒绝);本函数不提供"默认放行",测试输出也不应打印原文或员工个人值。
+func (c *Client) GetTurnForAuthorizedRead(ctx context.Context, tenantKey, turnID string, authorize func(turnID string) error) (TurnDetail, error) {
+ if authorize == nil {
+ return TurnDetail{}, fmt.Errorf("%w: an explicit authorization callback is required", ErrInvalidQuery)
+ }
+ if strings.TrimSpace(tenantKey) == "" || strings.TrimSpace(turnID) == "" {
+ return TurnDetail{}, fmt.Errorf("%w: tenant and turn id are required", ErrInvalidQuery)
+ }
+ if err := authorize(turnID); err != nil {
+ return TurnDetail{}, fmt.Errorf("%w: turn read is not authorized", ErrInvalidQuery)
+ }
+ detail := TurnDetail{}
+ var references string
+ var requestID, answerID *string
+ err := c.withReadOnlyTx(ctx, func(ctx context.Context, q querier) error {
+ if err := q.QueryRow(ctx, authorizedTurnSQL, tenantKey, turnID).Scan(
+ &detail.ID, &detail.CreatedAt, &detail.Status, &detail.Channel, &detail.AgentID,
+ &detail.Question, &detail.Answer, &references, &detail.ErrorCode); err != nil {
+ return fmt.Errorf("%w: turn could not be read", ErrUnavailable)
+ }
+ detail.ReferencesJSON = []byte(references)
+ if !json.Valid(detail.ReferencesJSON) {
+ detail.ReferencesJSON = []byte("[]")
+ }
+ // request/answer 两条消息 id 需要一起取:单独查一次拿 id 列表,避免把正文带进列表接口。
+ if err := q.QueryRow(ctx, `SELECT request_message_id, answer_message_id FROM turns WHERE tenant_key = $1 AND id = $2`, tenantKey, turnID).
+ Scan(&requestID, &answerID); err != nil {
+ return fmt.Errorf("%w: turn could not be read", ErrUnavailable)
+ }
+ rows, err := q.Query(ctx, authorizedMessagesSQL, tenantKey, detail.Channel, requestID, answerID)
+ if err != nil {
+ return fmt.Errorf("%w: turn messages could not be read", ErrUnavailable)
+ }
+ defer rows.Close()
+ for rows.Next() {
+ var message TurnMessage
+ if err := rows.Scan(&message.ID, &message.CreatedAt, &message.Direction, &message.Role,
+ &message.MessageType, &message.Status, &message.Text, &message.ActorLinked, &message.ActorType); err != nil {
+ return fmt.Errorf("%w: turn messages could not be read", ErrUnavailable)
+ }
+ detail.Messages = append(detail.Messages, message)
+ }
+ return rows.Err()
+ })
+ if err != nil {
+ return TurnDetail{}, err
+ }
+ return detail, nil
+}
+
+// validateQueryWindow 是仓储入口的**完整**校验:不能只靠 NewWindow —— 调用方完全可以
+// 自己拼一个 Window 结构体绕过它(独立探测已证明)。这里把租户、半开区间、跨度上限
+// 与"不允许未来窗口"全部落实在每次查询上。
+func (c *Client) validateQueryWindow(window Window) error {
+ if strings.TrimSpace(window.TenantKey) == "" {
+ return fmt.Errorf("%w: tenant key is required", ErrInvalidQuery)
+ }
+ if window.Start.IsZero() || window.End.IsZero() || !window.Start.Before(window.End) {
+ return fmt.Errorf("%w: window is invalid", ErrInvalidQuery)
+ }
+ limit := c.config.MaxWindow
+ if limit <= 0 {
+ limit = 90 * 24 * time.Hour
+ }
+ if window.End.Sub(window.Start) > limit {
+ return fmt.Errorf("%w: window exceeds the %s limit", ErrInvalidQuery, limit)
+ }
+ now := time.Now()
+ if c.config.Now != nil {
+ now = c.config.Now()
+ }
+ if window.End.After(now.Add(5 * time.Minute)) {
+ return fmt.Errorf("%w: window end is in the future", ErrInvalidQuery)
+ }
+ return nil
+}
diff --git a/internal/dobotaiops/repository_integration_test.go b/internal/dobotaiops/repository_integration_test.go
new file mode 100644
index 0000000..36669d5
--- /dev/null
+++ b/internal/dobotaiops/repository_integration_test.go
@@ -0,0 +1,347 @@
+package dobotaiops
+
+import (
+ "context"
+ "crypto/rand"
+ "encoding/base64"
+ "errors"
+ "fmt"
+ "net/url"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/jackc/pgx/v5/pgxpool"
+)
+
+// 这些用例只在 TEST_DATABASE_URL 指向**一次性/隔离**数据库时运行(CI 默认跳过)。
+// 它们**绝不**指向生产:fixture 表、隔离角色、临时 DSN 文件都在这个库内建/删。
+// 生产侧的真实验证另有入口(纯目录/SELECT,见工单与 runbook)。
+func fixturePool(t *testing.T) *pgxpool.Pool {
+ t.Helper()
+ // 先过隔离环境护栏(会建表/建角色):未声明就跳过,声明了但不像一次性库就直接失败。
+ fixtureEnvironment(t)
+ dsn := strings.TrimSpace(os.Getenv("TEST_DATABASE_URL"))
+ pool, err := pgxpool.New(context.Background(), dsn)
+ if err != nil {
+ t.Fatal(err)
+ }
+ t.Cleanup(pool.Close)
+ return pool
+}
+
+// dropRoleIfExists 先解掉授权依赖再删角色(临时库里可重复运行)。
+func dropRoleIfExists(t *testing.T, pool *pgxpool.Pool, role string) {
+ t.Helper()
+ var exists bool
+ if err := pool.QueryRow(context.Background(), `SELECT EXISTS(SELECT 1 FROM pg_roles WHERE rolname = $1)`, role).Scan(&exists); err != nil {
+ t.Fatal(err)
+ }
+ if !exists {
+ return
+ }
+ execFixture(t, pool, fmt.Sprintf(`DROP OWNED BY %s`, quoteIdent(role)), fmt.Sprintf(`DROP ROLE %s`, quoteIdent(role)))
+}
+
+func execFixture(t *testing.T, pool *pgxpool.Pool, statements ...string) {
+ t.Helper()
+ for _, statement := range statements {
+ if _, err := pool.Exec(context.Background(), statement); err != nil {
+ t.Fatalf("fixture 语句失败(%s):%v", strings.SplitN(statement, "\n", 2)[0], err)
+ }
+ }
+}
+
+func randomSecret(t *testing.T) string {
+ t.Helper()
+ buf := make([]byte, 32)
+ if _, err := rand.Read(buf); err != nil {
+ t.Fatal(err)
+ }
+ return strings.NewReplacer("+", "A", "/", "B", "=", "C").Replace(base64.URLEncoding.EncodeToString(buf))
+}
+
+func writeSecretFile(t *testing.T, content string) string {
+ t.Helper()
+ path := filepath.Join(t.TempDir(), "dobotai_ops_ro.env")
+ if err := os.WriteFile(path, []byte(content+"\n"), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ return path
+}
+
+// buildFixture 建表 + 灌数据 + 建一个镜像生产授权面的最小只读角色,返回只读 DSN。
+func buildFixture(t *testing.T, pool *pgxpool.Pool) string {
+ t.Helper()
+ ctx := context.Background()
+ execFixture(t, pool,
+ `DROP TABLE IF EXISTS messages, coverage_decisions, channel_actors, turns CASCADE`,
+ `CREATE TABLE turns (id text PRIMARY KEY, tenant_key text NOT NULL, channel text NOT NULL,
+ status text NOT NULL, agent_id text NOT NULL DEFAULT '', knowledge_searched boolean NOT NULL DEFAULT false,
+ references_json jsonb NOT NULL DEFAULT '[]'::jsonb, request_message_id text, answer_message_id text,
+ question text NOT NULL DEFAULT '', answer text NOT NULL DEFAULT '', error_message text NOT NULL DEFAULT '',
+ created_at timestamptz NOT NULL)`,
+ `CREATE TABLE messages (id text PRIMARY KEY, tenant_key text NOT NULL, channel text NOT NULL, actor_id text,
+ department_snapshot text NOT NULL DEFAULT '', region_snapshot text NOT NULL DEFAULT '',
+ direction text NOT NULL DEFAULT '', role text NOT NULL DEFAULT '', message_type text NOT NULL DEFAULT '',
+ status text NOT NULL DEFAULT '', text_content text NOT NULL DEFAULT '', created_at timestamptz NOT NULL)`,
+ `CREATE TABLE coverage_decisions (id text PRIMARY KEY, tenant_key text NOT NULL, channel text NOT NULL,
+ turn_id text NOT NULL, evaluator_version text NOT NULL, verdict text NOT NULL, reason_code text NOT NULL DEFAULT '',
+ reference_count integer NOT NULL DEFAULT 0, created_at timestamptz NOT NULL,
+ UNIQUE (tenant_key, channel, turn_id))`,
+ `CREATE TABLE channel_actors (id text PRIMARY KEY, tenant_key text NOT NULL, channel text NOT NULL,
+ external_actor_id text NOT NULL, actor_type text NOT NULL, display_name text NOT NULL DEFAULT '',
+ created_at timestamptz NOT NULL)`,
+ `INSERT INTO turns (id, tenant_key, channel, status, agent_id, knowledge_searched, references_json,
+ request_message_id, answer_message_id, question, answer, created_at) VALUES
+ ('turn-4', 'default', 'dingtalk', 'succeeded', 'agent-a', false, '[]',
+ 'msg-req-4', 'msg-ans-4', '第四问(无规则决策)', '第四答', '2026-10-14T04:00:00Z'),
+ ('turn-3', 'default', 'dingtalk', 'succeeded', 'agent-a', true, '[{"doc":"x"},{"doc":"y"}]',
+ 'msg-req-3', 'msg-ans-3', '第三问(正文)', '第三答(正文)', '2026-10-14T03:00:00Z'),
+ ('turn-2', 'default', 'dingtalk', 'succeeded', 'agent-a', false, '[]',
+ 'msg-req-2', 'msg-ans-2', '第二问', '第二答', '2026-10-14T02:00:00Z'),
+ ('turn-1', 'default', 'dingtalk', 'failed', 'agent-b', true, '[]',
+ NULL, NULL, '第一问', '', '2026-10-14T01:00:00Z')`,
+ `INSERT INTO messages (id, tenant_key, channel, actor_id, department_snapshot, region_snapshot,
+ direction, role, message_type, status, text_content, created_at) VALUES
+ ('msg-req-3', 'default', 'dingtalk', 'actor-row-1', '', '', 'inbound', 'user', 'text', 'ok', '第三问原文', '2026-10-14T03:00:00Z'),
+ ('msg-ans-3', 'default', 'dingtalk', 'actor-row-1', '研发部', '华南', 'outbound', 'assistant', 'text', 'ok', '第三答原文', '2026-10-14T03:00:01Z'),
+ ('msg-req-2', 'default', 'dingtalk', 'actor-row-1', '', '', 'inbound', 'user', 'text', 'ok', '第二问原文', '2026-10-14T02:00:00Z'),
+ ('msg-req-4', 'default', 'dingtalk', 'actor-row-1', '', '', 'inbound', 'user', 'text', 'ok', '第四问原文', '2026-10-14T04:00:00Z'),
+ ('msg-ans-4', 'default', 'dingtalk', 'actor-row-1', '', '', 'outbound', 'assistant', 'text', 'ok', '第四答原文', '2026-10-14T04:00:01Z')`,
+ // 真实关系:messages.actor_id 引用 channel_actors(id);external_actor_id 是另一个
+ // 唯一键(tenant_key, channel, external_actor_id)。夹具必须照这个来 —— 用
+ // external_actor_id 关联就会命中 0 行(生产对拍实测:错 0 / 对 2234)。
+ `INSERT INTO channel_actors (id, tenant_key, channel, external_actor_id, actor_type, display_name, created_at)
+ VALUES ('actor-row-1', 'default', 'dingtalk', 'ext-actor-1', 'employee', '不应外泄的姓名', '2026-10-14T00:00:00Z')`,
+ // 另一个租户的数据:所有查询都必须把它挡在外面(跨租户隔离)。
+ `INSERT INTO turns (id, tenant_key, channel, status, agent_id, created_at)
+ VALUES ('turn-other-tenant', 'another-tenant', 'dingtalk', 'succeeded', 'agent-x', '2026-10-14T03:30:00Z')`,
+ `INSERT INTO coverage_decisions (id, tenant_key, channel, turn_id, evaluator_version, verdict, reason_code, reference_count, created_at)
+ VALUES ('cov-other-tenant', 'another-tenant', 'dingtalk', 'turn-other-tenant', 'v5', 'covered', '', 0, '2026-10-14T03:30:02Z')`,
+ // 生产上 (tenant_key, channel, turn_id) 是唯一的:一个 turn 只会有一条决策,
+ // 不同 turn 才可能来自不同 evaluator_version —— fixture 照生产形态来。
+ `INSERT INTO coverage_decisions (id, tenant_key, channel, turn_id, evaluator_version, verdict, reason_code, reference_count, created_at)
+ VALUES ('cov-1', 'default', 'dingtalk', 'turn-3', 'v5', 'covered', '', 2, '2026-10-14T03:00:02Z'),
+ ('cov-2', 'default', 'dingtalk', 'turn-1', 'v5', 'uncovered', 'no_source', 0, '2026-10-14T01:00:02Z'),
+ ('cov-3', 'default', 'dingtalk', 'turn-2', 'v4', 'covered', '', 0, '2026-10-14T02:00:02Z')`,
+ )
+ password := randomSecret(t)
+ // 角色在同一个临时库里可能已经存在(多个用例复用):先删再建,保持用例可重复运行。
+ dropRoleIfExists(t, pool, "kg_ro_fixture")
+ execFixture(t, pool,
+ fmt.Sprintf(`CREATE ROLE kg_ro_fixture LOGIN PASSWORD '%s' CONNECTION LIMIT 4`, password),
+ `ALTER ROLE kg_ro_fixture SET default_transaction_read_only = on`,
+ )
+ // 当前库名(避免写死)
+ var databaseName string
+ if err := pool.QueryRow(ctx, `SELECT current_database()`).Scan(&databaseName); err != nil {
+ t.Fatal(err)
+ }
+ execFixture(t, pool,
+ fmt.Sprintf(`GRANT CONNECT ON DATABASE %s TO kg_ro_fixture`, quoteIdent(databaseName)),
+ `GRANT USAGE ON SCHEMA public TO kg_ro_fixture`,
+ `GRANT SELECT ON TABLE public.turns, public.messages, public.coverage_decisions, public.channel_actors TO kg_ro_fixture`,
+ )
+ // 用与生产一致的写法拼只读 DSN:主机/端口/库名从 TEST_DATABASE_URL 派生
+ //(容器内 inet_server_addr 从宿主机不可路由),口令在测试内不打印。
+ return dsnWithCredentials(t, "kg_ro_fixture", password)
+}
+
+// dsnWithCredentials 把 TEST_DATABASE_URL 里的用户/口令换掉,其余(主机、端口、库、查询串)保持。
+func dsnWithCredentials(t *testing.T, user, password string) string {
+ t.Helper()
+ parsed, err := url.Parse(strings.TrimSpace(os.Getenv("TEST_DATABASE_URL")))
+ if err != nil {
+ t.Fatal(err)
+ }
+ parsed.User = url.UserPassword(user, password)
+ return parsed.String()
+}
+
+func quoteIdent(value string) string {
+ return `"` + strings.ReplaceAll(value, `"`, `""`) + `"`
+}
+
+func buildReadOnlyClient(t *testing.T, roDSN string) *Client {
+ t.Helper()
+ client, err := Build(context.Background(), Config{
+ DSNFile: writeSecretFile(t, "DOBOTAI_OPS_READ_DSN="+roDSN),
+ GovernanceDatabaseURL: "postgres://governance@elsewhere:5432/governance",
+ DialMode: "direct",
+ ConnectTimeout: 5 * time.Second,
+ QueryTimeout: 5 * time.Second,
+ MaxConns: 2,
+ // 固定"当前时间":仓储入口会拒未来窗口,夹具的时间窗必须相对一个确定时刻来判。
+ Now: func() time.Time { return time.Date(2026, 10, 15, 0, 0, 0, 0, time.UTC) },
+ })
+ if err != nil {
+ t.Fatalf("Build() 失败:%v", err)
+ }
+ t.Cleanup(client.Close)
+ return client
+}
+
+func TestReadOnlyRepositoryAgainstFixtureDatabase(t *testing.T) {
+ pool := fixturePool(t)
+ roDSN := buildFixture(t, pool)
+ client := buildReadOnlyClient(t, roDSN)
+ ctx := context.Background()
+ window, err := NewWindow("default", "2026-10-14T00:00:00Z", "2026-10-15T00:00:00Z", 90*24*time.Hour, time.Date(2026, 10, 15, 0, 0, 0, 0, time.UTC))
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ // ACL 自检报告必须干净(这是"账号确实最小只读"的机器证据)。
+ report := client.ACL()
+ if report.Role != "kg_ro_fixture" || report.Super || report.SchemaCreate || len(report.WritePrivileges) != 0 || len(report.MissingSelects) != 0 {
+ t.Fatalf("ACL 报告不干净:%+v", report)
+ }
+
+ counts, err := client.QueryCounts(ctx, window, Filter{})
+ if err != nil {
+ t.Fatalf("QueryCounts() error = %v", err)
+ }
+ if counts.Total != 4 || counts.ByStatus["succeeded"] != 3 || counts.ByStatus["failed"] != 1 || counts.ByChannel["dingtalk"] != 4 {
+ t.Fatalf("counts = %+v", counts)
+ }
+ filtered, err := client.QueryCounts(ctx, window, Filter{Channel: "dingtalk", Status: "succeeded"})
+ if err != nil || filtered.Total != 3 {
+ t.Fatalf("过滤计数 = %+v (%v)", filtered, err)
+ }
+ if _, err := client.QueryCounts(ctx, window, Filter{Status: "nope"}); !errors.Is(err, ErrInvalidQuery) {
+ t.Fatalf("未知状态应被拒:%v", err)
+ }
+
+ coverage, err := client.QueryRuleCoverage(ctx, window)
+ if err != nil {
+ t.Fatalf("QueryRuleCoverage() error = %v", err)
+ }
+ if len(coverage.Groups) != 3 {
+ t.Fatalf("覆盖分组 = %+v", coverage.Groups)
+ }
+ if coverage.SucceededTurns != 3 || coverage.SucceededWithoutDecision != 1 {
+ t.Fatalf("成功 turn 统计 = %+v", coverage)
+ }
+ for _, group := range coverage.Groups {
+ if group.EvaluatorVersion == "v5" && group.Verdict == "uncovered" && group.ReasonCode != "no_source" {
+ t.Fatalf("reason_code 未保留:%+v", group)
+ }
+ }
+
+ first, err := client.ListTurnMetadata(ctx, window, "", 2)
+ if err != nil {
+ t.Fatalf("ListTurnMetadata() error = %v", err)
+ }
+ if len(first.Items) != 2 || !first.HasMore || first.NextCursor == "" {
+ t.Fatalf("第一页 = %+v", first)
+ }
+ if first.Items[0].ID != "turn-4" || first.Items[1].ID != "turn-3" {
+ t.Fatalf("倒序不对:%+v", first.Items)
+ }
+ if first.Items[1].ReferenceCount != 2 || first.Items[1].LinkedMessages != 2 {
+ t.Fatalf("引用/关联消息计数不对:%+v", first.Items[1])
+ }
+ // turn-3:一条关联消息部门/区域为空、一条有值 ⇒ 不该标 missing;turn-4:两条都为空 ⇒ 如实标 missing。
+ if first.Items[1].DepartmentMissing || first.Items[1].RegionMissing {
+ t.Fatalf("有值的关联消息不该标 missing:%+v", first.Items[1])
+ }
+ if !first.Items[0].DepartmentMissing || !first.Items[0].RegionMissing {
+ t.Fatalf("快照为空的关联消息必须如实标 missing:%+v", first.Items[0])
+ }
+ second, err := client.ListTurnMetadata(ctx, window, first.NextCursor, 2)
+ if err != nil {
+ t.Fatalf("第二页 error = %v", err)
+ }
+ if len(second.Items) != 2 || second.Items[0].ID != "turn-2" || second.Items[1].ID != "turn-1" || second.HasMore {
+ t.Fatalf("第二页 = %+v", second)
+ }
+ if _, err := client.ListTurnMetadata(ctx, window, "不是游标", 10); !errors.Is(err, ErrInvalidQuery) {
+ t.Fatalf("非法游标应被拒:%v", err)
+ }
+ if _, err := client.ListTurnMetadata(ctx, window, "", 101); !errors.Is(err, ErrInvalidQuery) {
+ t.Fatalf("超过分页上限应被拒:%v", err)
+ }
+ // 跨租户隔离:另一个租户的 turn 不能出现在任何结果里(计数、覆盖、列表都一样)。
+ otherTenant, err := NewWindow("another-tenant", "2026-10-14T00:00:00Z", "2026-10-15T00:00:00Z", 90*24*time.Hour, time.Date(2026, 10, 15, 0, 0, 0, 0, time.UTC))
+ if err != nil {
+ t.Fatal(err)
+ }
+ otherCounts, err := client.QueryCounts(ctx, otherTenant, Filter{})
+ if err != nil || otherCounts.Total != 1 {
+ t.Fatalf("另一个租户应只看到自己的 1 条:%+v (%v)", otherCounts, err)
+ }
+ for _, item := range append(first.Items, second.Items...) {
+ if item.ID == "turn-other-tenant" {
+ t.Fatalf("跨租户泄漏:%+v", item)
+ }
+ }
+ if _, err := client.GetTurnForAuthorizedRead(ctx, "default", "turn-other-tenant", func(string) error { return nil }); !errors.Is(err, ErrUnavailable) {
+ // default 租户下没有这个 turn ⇒ 读不到(不是"读到了别人的")
+ t.Fatalf("跨租户 turn 不该在 default 下可读:%v", err)
+ }
+
+ // 授权读取:没有授权回调一律拒绝(不提供"默认放行")。
+ if _, err := client.GetTurnForAuthorizedRead(ctx, "default", "turn-3", nil); !errors.Is(err, ErrInvalidQuery) {
+ t.Fatalf("缺授权回调必须拒绝:%v", err)
+ }
+ if _, err := client.GetTurnForAuthorizedRead(ctx, "default", "turn-3", func(string) error { return errors.New("no") }); !errors.Is(err, ErrInvalidQuery) {
+ t.Fatalf("授权回调拒绝时必须拒绝:%v", err)
+ }
+ detail, err := client.GetTurnForAuthorizedRead(ctx, "default", "turn-3", func(string) error { return nil })
+ if err != nil {
+ t.Fatalf("授权读取 error = %v", err)
+ }
+ if detail.Question != "第三问(正文)" || detail.Answer != "第三答(正文)" || len(detail.Messages) != 2 {
+ t.Fatalf("授权读取内容不对:%+v", detail)
+ }
+ // 关联回归:即使夹具里 id 与 external_actor_id 不同,也必须靠正确的字段命中 actor_type。
+ for _, message := range detail.Messages {
+ if message.ActorType != "employee" {
+ t.Fatalf("人员关联没命中(关联字段必须是 channel_actors.id):%+v", message)
+ }
+ }
+ if strings.Contains(detail.Messages[0].ActorType, "不应外泄") {
+ t.Fatalf("只应带 actor_type,不应带员工姓名:%+v", detail.Messages[0])
+ }
+ _ = client.Available(ctx)
+}
+
+func TestBuildRefusesUnsafeAccountsAndTargets(t *testing.T) {
+ pool := fixturePool(t)
+ roDSN := buildFixture(t, pool)
+ ctx := context.Background()
+ password := randomSecret(t)
+ dropRoleIfExists(t, pool, "kg_writer_fixture")
+ execFixture(t, pool,
+ fmt.Sprintf(`CREATE ROLE kg_writer_fixture LOGIN PASSWORD '%s'`, password),
+ `GRANT USAGE ON SCHEMA public TO kg_writer_fixture`,
+ `GRANT SELECT, INSERT ON TABLE public.turns TO kg_writer_fixture`,
+ `GRANT SELECT ON TABLE public.messages, public.coverage_decisions, public.channel_actors TO kg_writer_fixture`,
+ )
+ writerDSN := dsnWithCredentials(t, "kg_writer_fixture", password)
+
+ // 有写权限的账号:fail closed(不是"能读就算过")。
+ _, err := Build(ctx, Config{
+ DSNFile: writeSecretFile(t, writerDSN), DialMode: "direct",
+ GovernanceDatabaseURL: "postgres://governance@elsewhere:5432/governance",
+ ConnectTimeout: 5 * time.Second, QueryTimeout: 5 * time.Second})
+ if !errors.Is(err, ErrNotReadOnly) {
+ t.Fatalf("可写账号必须被拒为 ErrNotReadOnly:%v", err)
+ }
+ // 指向治理主库的 DSN:拒绝(防"误配后读写治理库")。
+ _, err = Build(ctx, Config{
+ DSNFile: writeSecretFile(t, roDSN), DialMode: "direct", GovernanceDatabaseURL: roDSN,
+ ConnectTimeout: 5 * time.Second, QueryTimeout: 5 * time.Second})
+ if !errors.Is(err, ErrNotReadOnly) {
+ t.Fatalf("指向治理库必须被拒:%v", err)
+ }
+ // secret 文件缺失:ErrUnavailable(按"未启用"处理,不拖垮治理)。
+ _, err = Build(ctx, Config{DSNFile: filepath.Join(t.TempDir(), "missing.env"), DialMode: "direct",
+ ConnectTimeout: time.Second, QueryTimeout: time.Second})
+ if !errors.Is(err, ErrUnavailable) {
+ t.Fatalf("缺 secret 应为 ErrUnavailable:%v", err)
+ }
+}
diff --git a/internal/dobotaiops/safety.go b/internal/dobotaiops/safety.go
new file mode 100644
index 0000000..416b760
--- /dev/null
+++ b/internal/dobotaiops/safety.go
@@ -0,0 +1,71 @@
+package dobotaiops
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+)
+
+// SourceSafety records effective privileges, not only grants on queried tables.
+// TEMP and transport are disclosed independently: this probe never changes them.
+type SourceSafety struct {
+ Database string `json:"database"`
+ ConnectionLimit int `json:"connection_limit"`
+ TablesChecked int `json:"tables_checked"`
+ TableWrites int `json:"table_writes"`
+ ColumnWrites int `json:"column_writes"`
+ SequenceWrites int `json:"sequence_writes"`
+ SchemaCreates int `json:"schema_creates"`
+ DatabaseTemp bool `json:"database_temp"`
+ SSL bool `json:"ssl"`
+ MissingColumns []string `json:"missing_columns"`
+}
+
+const sourceSafetySQL = `
+WITH relations AS (
+ SELECT c.oid,c.relkind FROM pg_class c JOIN pg_namespace n ON n.oid=c.relnamespace
+ WHERE n.nspname NOT LIKE 'pg_%' AND n.nspname<>'information_schema'
+), required(table_name,column_name,type_name) AS (VALUES
+ ('turns','id','text'),('turns','tenant_key','text'),('turns','channel','text'),
+ ('turns','question','text'),('turns','answer','text'),('turns','created_at','timestamptz'),
+ ('turns','references_json','jsonb'),('turns','knowledge_searched','bool'),
+ ('turns','request_message_id','text'),('turns','answer_message_id','text'),
+ ('messages','id','text'),('messages','actor_id','text'),('messages','department_snapshot','text'),
+ ('messages','region_snapshot','text'),('channel_actors','id','text'),('channel_actors','external_actor_id','text'),
+ ('coverage_decisions','turn_id','text'),('coverage_decisions','verdict','text')
+)
+SELECT jsonb_build_object(
+ 'database',current_database(),
+ 'connection_limit',(SELECT rolconnlimit FROM pg_roles WHERE rolname=current_user),
+ 'tables_checked',(SELECT count(*) FROM relations WHERE relkind IN ('r','p','v','m','f')),
+ 'table_writes',(SELECT count(*) FROM relations WHERE relkind IN ('r','p','v','m','f') AND (
+ has_table_privilege(oid,'INSERT') OR has_table_privilege(oid,'UPDATE') OR has_table_privilege(oid,'DELETE') OR
+ has_table_privilege(oid,'TRUNCATE') OR has_table_privilege(oid,'REFERENCES') OR has_table_privilege(oid,'TRIGGER') OR
+ CASE WHEN current_setting('server_version_num')::int>=170000 THEN has_table_privilege(oid,'MAINTAIN') ELSE false END)),
+ 'column_writes',(SELECT count(*) FROM relations WHERE relkind IN ('r','p','v','m','f') AND (
+ has_any_column_privilege(oid,'INSERT') OR has_any_column_privilege(oid,'UPDATE') OR has_any_column_privilege(oid,'REFERENCES'))),
+ 'sequence_writes',(SELECT count(*) FROM relations WHERE relkind='S' AND (has_sequence_privilege(oid,'USAGE') OR has_sequence_privilege(oid,'UPDATE'))),
+ 'schema_creates',(SELECT count(*) FROM pg_namespace WHERE nspname NOT LIKE 'pg_%' AND nspname<>'information_schema' AND has_schema_privilege(oid,'CREATE')),
+ 'database_temp',has_database_privilege(current_database(),'TEMP'),
+ 'ssl',COALESCE((SELECT ssl FROM pg_stat_ssl WHERE pid=pg_backend_pid()),false),
+ 'missing_columns',(SELECT COALESCE(jsonb_agg(table_name||'.'||column_name),'[]'::jsonb) FROM required r WHERE NOT EXISTS(
+ SELECT 1 FROM pg_attribute a JOIN pg_class c ON c.oid=a.attrelid JOIN pg_namespace n ON n.oid=c.relnamespace
+ WHERE n.nspname='public' AND c.relname=r.table_name AND a.attname=r.column_name AND a.attnum>0 AND NOT a.attisdropped AND a.atttypid=to_regtype(r.type_name))))::text`
+
+func AuditSourceSafety(ctx context.Context, q rowQuerier) (SourceSafety, error) {
+ var raw string
+ if err := q.QueryRow(ctx, sourceSafetySQL).Scan(&raw); err != nil {
+ return SourceSafety{}, fmt.Errorf("%w: extended safety probe failed", ErrUnavailable)
+ }
+ var report SourceSafety
+ if err := json.Unmarshal([]byte(raw), &report); err != nil || report.Database == "" || report.TablesChecked < 4 || report.ConnectionLimit <= 0 {
+ return SourceSafety{}, fmt.Errorf("%w: incomplete safety report or unlimited source connections", ErrNotReadOnly)
+ }
+ if report.TableWrites > 0 || report.ColumnWrites > 0 || report.SequenceWrites > 0 || report.SchemaCreates > 0 {
+ return report, fmt.Errorf("%w: effective write or maintenance privileges detected", ErrNotReadOnly)
+ }
+ if len(report.MissingColumns) > 0 {
+ return report, fmt.Errorf("%w: source schema contract mismatch", ErrUnavailable)
+ }
+ return report, nil
+}
diff --git a/internal/dobotaiops/safety_integration_test.go b/internal/dobotaiops/safety_integration_test.go
new file mode 100644
index 0000000..fda25f8
--- /dev/null
+++ b/internal/dobotaiops/safety_integration_test.go
@@ -0,0 +1,20 @@
+package dobotaiops
+
+import (
+ "context"
+ "errors"
+ "testing"
+ "time"
+)
+
+func TestSourceRechecksEffectivePrivilegesBeforeEveryQuery(t *testing.T) {
+ pool := fixturePool(t)
+ roDSN := buildFixture(t, pool)
+ client := buildReadOnlyClient(t, roDSN)
+ execFixture(t, pool, `CREATE TABLE acl_other_surface(id text)`, `GRANT INSERT ON acl_other_surface TO kg_ro_fixture`)
+ t.Cleanup(func() { execFixture(t, pool, `DROP TABLE IF EXISTS acl_other_surface`) })
+ window := Window{TenantKey: "default", Start: time.Date(2026, 10, 14, 0, 0, 0, 0, time.UTC), End: time.Date(2026, 10, 15, 0, 0, 0, 0, time.UTC)}
+ if _, err := client.QueryCounts(context.Background(), window, Filter{}); !errors.Is(err, ErrNotReadOnly) {
+ t.Fatalf("unexpected privilege escalation outside legacy tables was not blocked: %v", err)
+ }
+}
diff --git a/internal/dobotaiops/safety_test.go b/internal/dobotaiops/safety_test.go
new file mode 100644
index 0000000..07bbf87
--- /dev/null
+++ b/internal/dobotaiops/safety_test.go
@@ -0,0 +1,37 @@
+package dobotaiops
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "testing"
+)
+
+func TestExtendedAuditRejectsWritesOutsideTheFourLegacyTables(t *testing.T) {
+ for _, key := range []string{"table_writes", "column_writes", "sequence_writes", "schema_creates"} {
+ report := map[string]any{"database": "source_test", "connection_limit": 4, "tables_checked": 19, "table_writes": 0, "column_writes": 0, "sequence_writes": 0, "schema_creates": 0, "database_temp": true, "ssl": false, "missing_columns": []string{}}
+ report[key] = 1
+ raw, _ := json.Marshal(report)
+ _, err := AuditSourceSafety(context.Background(), fakeQuerier{row: fakeRow{values: []any{string(raw)}}})
+ if !errors.Is(err, ErrNotReadOnly) {
+ t.Fatalf("%s must block source: %v", key, err)
+ }
+ }
+}
+
+func TestExtendedAuditReportsTransportTempAndSchemaContract(t *testing.T) {
+ raw := `{"database":"source_test","connection_limit":4,"tables_checked":19,"table_writes":0,"column_writes":0,"sequence_writes":0,"schema_creates":0,"database_temp":true,"ssl":false,"missing_columns":[]}`
+ report, err := AuditSourceSafety(context.Background(), fakeQuerier{row: fakeRow{values: []any{raw}}})
+ if err != nil || !report.DatabaseTemp || report.SSL || report.ConnectionLimit != 4 {
+ t.Fatalf("audit missing security disclosures: %+v %v", report, err)
+ }
+ raw = `{"database":"source_test","connection_limit":4,"tables_checked":19,"missing_columns":["turns.question"]}`
+ if _, err := AuditSourceSafety(context.Background(), fakeQuerier{row: fakeRow{values: []any{raw}}}); err == nil {
+ t.Fatal("missing schema contract must block source")
+ }
+ for _, raw := range []string{"{}", "not json"} {
+ if _, err := AuditSourceSafety(context.Background(), fakeQuerier{row: fakeRow{values: []any{raw}}}); err == nil {
+ t.Fatal("incomplete audit must not pass")
+ }
+ }
+}
diff --git a/internal/dobotaiops/settings.go b/internal/dobotaiops/settings.go
new file mode 100644
index 0000000..8c83991
--- /dev/null
+++ b/internal/dobotaiops/settings.go
@@ -0,0 +1,85 @@
+package dobotaiops
+
+import (
+ "path/filepath"
+ "strconv"
+ "strings"
+ "time"
+)
+
+// Settings contains only backend configuration. A source error must not stop
+// the governance main database or its unrelated workflows from starting.
+type Settings struct {
+ Enabled bool
+ TenantKey string
+ Connection Config
+ Problem string
+}
+
+func LoadSettings(getenv func(string) string, governanceDSN string) Settings {
+ s := Settings{}
+ raw := strings.TrimSpace(getenv("DOBOTAI_OPS_READ_ENABLED"))
+ if raw == "" {
+ return s
+ }
+ enabled, err := strconv.ParseBool(raw)
+ if err != nil {
+ s.Problem = "DOBOTAI_OPS_READ_ENABLED is invalid"
+ return s
+ }
+ if !enabled {
+ return s
+ }
+ s.Enabled = true
+ s.TenantKey = strings.TrimSpace(getenv("DOBOTAI_OPS_TENANT_KEY"))
+ c := Config{DSNFile: strings.TrimSpace(getenv("DOBOTAI_OPS_READ_DSN_FILE")), GovernanceDatabaseURL: governanceDSN,
+ DialMode: strings.TrimSpace(getenv("DOBOTAI_OPS_DIAL_MODE")), SSHTarget: strings.TrimSpace(getenv("DOBOTAI_OPS_SSH_TARGET")),
+ ConnectTimeout: 5 * time.Second, QueryTimeout: 4 * time.Second, MaxConns: 2, MinConns: 0}
+ if c.DialMode == "" {
+ c.DialMode = "direct"
+ }
+ for _, item := range []struct {
+ key string
+ target *time.Duration
+ }{
+ {"DOBOTAI_OPS_CONNECT_TIMEOUT", &c.ConnectTimeout}, {"DOBOTAI_OPS_QUERY_TIMEOUT", &c.QueryTimeout},
+ } {
+ if raw := getenv(item.key); raw != "" {
+ value, err := time.ParseDuration(raw)
+ if err != nil {
+ s.Problem = item.key + " is invalid"
+ return s
+ }
+ *item.target = value
+ }
+ }
+ for _, item := range []struct {
+ key string
+ target *int32
+ }{
+ {"DOBOTAI_OPS_MAX_CONNS", &c.MaxConns}, {"DOBOTAI_OPS_MIN_CONNS", &c.MinConns},
+ } {
+ if raw := getenv(item.key); raw != "" {
+ value, err := strconv.ParseInt(raw, 10, 32)
+ if err != nil {
+ s.Problem = item.key + " is invalid"
+ return s
+ }
+ *item.target = int32(value)
+ }
+ }
+ if s.TenantKey == "" || len(s.TenantKey) > 128 {
+ s.Problem = "DOBOTAI_OPS_TENANT_KEY is required and must be at most 128 bytes"
+ return s
+ }
+ if !filepath.IsAbs(c.DSNFile) || filepath.Clean(c.DSNFile) != c.DSNFile {
+ s.Problem = "DOBOTAI_OPS_READ_DSN_FILE must be an absolute clean path"
+ return s
+ }
+ if err := c.Validate(); err != nil {
+ s.Problem = "external read configuration is invalid"
+ return s
+ }
+ s.Connection = c.withDefaults()
+ return s
+}
diff --git a/internal/dobotaiops/settings_test.go b/internal/dobotaiops/settings_test.go
new file mode 100644
index 0000000..1ea8fef
--- /dev/null
+++ b/internal/dobotaiops/settings_test.go
@@ -0,0 +1,66 @@
+package dobotaiops
+
+import (
+ "errors"
+ "strings"
+ "testing"
+ "time"
+)
+
+func TestLoadSettingsConsumesIndependentConnectionLimits(t *testing.T) {
+ env := map[string]string{
+ "DOBOTAI_OPS_READ_ENABLED": "true", "DOBOTAI_OPS_READ_DSN_FILE": "/run/secrets/source",
+ "DOBOTAI_OPS_TENANT_KEY": "approved-tenant", "DOBOTAI_OPS_DIAL_MODE": "ssh", "DOBOTAI_OPS_SSH_TARGET": "approved-hop",
+ "DOBOTAI_OPS_CONNECT_TIMEOUT": "7s", "DOBOTAI_OPS_QUERY_TIMEOUT": "3s",
+ "DOBOTAI_OPS_MAX_CONNS": "3", "DOBOTAI_OPS_MIN_CONNS": "1",
+ }
+ s := LoadSettings(func(k string) string { return env[k] }, "postgres://governance@elsewhere/governance")
+ if !s.Enabled || s.Problem != "" || s.TenantKey != "approved-tenant" {
+ t.Fatalf("settings were not loaded: %+v", s)
+ }
+ if s.Connection.ConnectTimeout != 7*time.Second || s.Connection.QueryTimeout != 3*time.Second || s.Connection.MaxConns != 3 || s.Connection.MinConns != 1 {
+ t.Fatalf("environment overrides ignored: %+v", s.Connection)
+ }
+}
+
+func TestLoadSettingsIsDisabledByDefaultAndContainsInvalidSourceConfiguration(t *testing.T) {
+ if s := LoadSettings(func(string) string { return "" }, ""); s.Enabled || s.Problem != "" {
+ t.Fatalf("not disabled by default: %+v", s)
+ }
+ for _, key := range []string{"DOBOTAI_OPS_READ_ENABLED", "DOBOTAI_OPS_CONNECT_TIMEOUT", "DOBOTAI_OPS_QUERY_TIMEOUT", "DOBOTAI_OPS_MAX_CONNS", "DOBOTAI_OPS_MIN_CONNS"} {
+ env := map[string]string{"DOBOTAI_OPS_READ_ENABLED": "true", "DOBOTAI_OPS_READ_DSN_FILE": "/run/secrets/source", "DOBOTAI_OPS_TENANT_KEY": "approved-tenant"}
+ env[key] = "invalid-sensitive-value"
+ s := LoadSettings(func(k string) string { return env[k] }, "postgres://governance@elsewhere/governance")
+ if s.Problem == "" || strings.Contains(s.Problem, "invalid-sensitive-value") {
+ t.Fatalf("%s must fail closed without echoing its value: %+v", key, s)
+ }
+ }
+ s := LoadSettings(func(k string) string {
+ if k == "DOBOTAI_OPS_READ_ENABLED" {
+ return "true"
+ }
+ return ""
+ }, "")
+ if s.Problem == "" {
+ t.Fatal("missing secret and tenant must block source access")
+ }
+}
+
+func TestSecretReaderDoesNotSelectAnUnrelatedDatabaseURL(t *testing.T) {
+ unrelated := testDSN("writer", "not"+"a-secret", "other", "other_db")
+ wanted := testDSN("reader", "fixture"+"only", "source", "source_db")
+ got, ok := parseDSNLine("DATABASE_URL=" + unrelated + "\nDOBOTAI_OPS_READ_DSN=" + wanted)
+ if !ok || got != wanted {
+ t.Fatal("must select only the dedicated read DSN key")
+ }
+ if _, ok := parseDSNLine("DATABASE_URL=" + unrelated); ok {
+ t.Fatal("must not borrow another application's credential")
+ }
+}
+
+func TestMalformedGovernanceDSNDoesNotDisableIdentityGuard(t *testing.T) {
+ err := GuardGovernanceDatabase("postgres://reader@source/dobotai_prod", "invalid-main-dsn")
+ if !errors.Is(err, ErrUnavailable) {
+ t.Fatalf("malformed main identity must fail closed: %v", err)
+ }
+}
diff --git a/internal/dobotaiops/sshdial.go b/internal/dobotaiops/sshdial.go
new file mode 100644
index 0000000..3b28541
--- /dev/null
+++ b/internal/dobotaiops/sshdial.go
@@ -0,0 +1,133 @@
+package dobotaiops
+
+import (
+ "context"
+ "fmt"
+ "io"
+ "net"
+ "os"
+ "os/exec"
+ "strings"
+ "sync"
+ "syscall"
+ "time"
+)
+
+// SSHDialer 复用既有的 SSH direct-tcpip 能力:`ssh -W : ` ——
+// 由 SSH 侧完成到目标库的 TCP 连接,本机**不新增监听、不改 SSH/NPS/systemd/Docker 网络**。
+//
+// 实现用 socketpair:Go 侧拿到的是 fd 支撑的真实 net.Conn(支持 SetDeadline,
+// pgx 的连接/查询超时才能在拨号阶段生效),ssh 子进程的 stdin/stdout 指向同一对端的另一端。
+//
+// context 语义(刻意区分两段):
+// - **拨号阶段**尊重 ctx:ctx 已取消就不再创建连接、不再启动子进程;
+// - **连接建立之后不绑定这个 ctx** —— pgx 在连接成功后就会取消拨号 ctx,
+// 若把连接生命周期挂上去,健康连接会被立刻掐断。连接生命周期绑定在
+// "连接关闭 ⇄ 子进程回收" 这对关系上(见 tunnelConn.Close)。
+//
+// 依赖:运行环境里必须有 ssh 客户端与已批准的密钥/known_hosts。容器内 localhost 不等于
+// 宿主机 —— 容器没有 ssh 能力时返回 ErrUnavailable;**不擅自复制私钥、不放宽 known_hosts、
+// 不改 network_mode**。
+// dialAddress 是**配置里 DSN 的主机:端口**。为什么必须用它、而不是 pgx 传进来的 addr:
+// pgx 会先在**本机**解析域名,本机若开了 Clash/mihomo 之类的 Fake-IP(198.18.0.0/15)或
+// 其他 DNS 劫持,解析结果是假地址;把假地址交给 ssh 去连必然挂住(实测:20s 超时)。
+// 固定审批的隧道应当让**远端**解析并连接配置里的主机名 —— 这也是"不接受任意主机"的同一原则。
+func SSHDialer(target, dialAddress string) (func(ctx context.Context, network, addr string) (net.Conn, error), error) {
+ if target == "" {
+ return nil, fmt.Errorf("%w: ssh target is required", ErrUnavailable)
+ }
+ if strings.TrimSpace(dialAddress) == "" {
+ return nil, fmt.Errorf("%w: dial address is required", ErrUnavailable)
+ }
+ if _, err := exec.LookPath("ssh"); err != nil {
+ return nil, fmt.Errorf("%w: ssh client is not available in this environment", ErrUnavailable)
+ }
+ return func(ctx context.Context, _ string, _ string) (net.Conn, error) {
+ addr := dialAddress
+ if err := ctx.Err(); err != nil {
+ return nil, fmt.Errorf("%w: ssh dial cancelled before start", ErrUnavailable)
+ }
+ fds, err := syscall.Socketpair(syscall.AF_UNIX, syscall.SOCK_STREAM, 0)
+ if err != nil {
+ return nil, fmt.Errorf("%w: cannot create a socketpair for the ssh tunnel", ErrUnavailable)
+ }
+ localEnd := os.NewFile(uintptr(fds[0]), "kg-ssh-tunnel-local")
+ remoteEnd := os.NewFile(uintptr(fds[1]), "kg-ssh-tunnel-child")
+ conn, err := net.FileConn(localEnd)
+ _ = localEnd.Close()
+ if err != nil {
+ _ = remoteEnd.Close()
+ return nil, fmt.Errorf("%w: cannot wrap the ssh tunnel in a connection", ErrUnavailable)
+ }
+ command := exec.Command("ssh",
+ "-o", "BatchMode=yes",
+ "-o", "ExitOnForwardFailure=yes",
+ "-o", "ServerAliveInterval=15",
+ "-W", addr, target)
+ command.Stdin = remoteEnd
+ command.Stdout = remoteEnd
+ // ssh 自身的 stderr 一律丢弃:里面可能带主机名/路径;失败统一上抛 ErrUnavailable。
+ command.Stderr = io.Discard
+ if err := command.Start(); err != nil {
+ _ = remoteEnd.Close()
+ _ = conn.Close()
+ return nil, fmt.Errorf("%w: cannot start the ssh tunnel", ErrUnavailable)
+ }
+ _ = remoteEnd.Close()
+ // reaped 必须先初始化:reap() 会在子进程退出时 close 它(nil channel 会 panic)。
+ tunnel := &tunnelConn{Conn: conn, command: command, reaped: make(chan struct{})}
+ go tunnel.reap()
+ return tunnel, nil
+ }, nil
+}
+
+// tunnelConn 把"连接关闭 ⇄ 子进程回收"显式绑定起来:
+// - 连接被关(pgx 归还/释放连接、或对端断开)⇒ 子进程收到终止信号并回收,不留孤儿;
+// - 子进程自己退出(隧道断/认证失败)⇒ Go 侧连接立刻关掉,让 pgx 马上感知断开;
+// - Close 幂等,且不阻塞在等待子进程上(最多等一个短宽限期)。
+type tunnelConn struct {
+ net.Conn
+ command *exec.Cmd
+ closeOnce sync.Once
+ reaped chan struct{}
+}
+
+func (t *tunnelConn) reap() {
+ if t.command != nil {
+ _ = t.command.Wait()
+ }
+ if t.reaped != nil {
+ close(t.reaped)
+ }
+ // 子进程退出 ⇒ 连接必然无用,主动关掉让调用方立刻看到 EOF。
+ _ = t.Conn.Close()
+}
+
+func (t *tunnelConn) Close() error {
+ var err error
+ t.closeOnce.Do(func() {
+ err = t.Conn.Close()
+ // 连接关闭后 ssh 通常自行退出;这里补一刀保证它不会挂着不退。
+ if t.command.Process != nil {
+ _ = t.command.Process.Signal(syscall.SIGTERM)
+ }
+ select {
+ case <-t.Exited():
+ case <-time.After(2 * time.Second):
+ if t.command.Process != nil {
+ _ = t.command.Process.Kill()
+ }
+ }
+ })
+ return err
+}
+
+// Exited 让测试/运维能确认子进程已经回收(不暴露任何连接信息)。
+func (t *tunnelConn) Exited() <-chan struct{} {
+ if t.reaped == nil {
+ closed := make(chan struct{})
+ close(closed)
+ return closed
+ }
+ return t.reaped
+}
diff --git a/internal/dobotaiops/sshdial_test.go b/internal/dobotaiops/sshdial_test.go
new file mode 100644
index 0000000..0b0e6ad
--- /dev/null
+++ b/internal/dobotaiops/sshdial_test.go
@@ -0,0 +1,104 @@
+package dobotaiops
+
+import (
+ "bufio"
+ "context"
+ "fmt"
+ "net"
+ "net/http"
+ "os"
+ "strings"
+ "testing"
+ "time"
+)
+
+// 只有在显式给出"已批准的 SSH 目标 + 一个可达的只读端点"时才跑:CI 默认跳过。
+// 目的:证明 `ssh -W` + socketpair 的拨号在 Go 侧是一个**支持 deadline 的真实 net.Conn**
+// (pgx 的连接/查询超时能在拨号阶段生效),且经这条通道发出的请求真的能到达目标。
+//
+// KG_SSH_DIAL_TARGET=weknora-prod KG_SSH_DIAL_ADDR=127.0.0.1:8090 // go test ./internal/dobotaiops/ -run TestSSHDialerTransportsRealTraffic -v
+func TestSSHDialerTransportsRealTraffic(t *testing.T) {
+ target := strings.TrimSpace(os.Getenv("KG_SSH_DIAL_TARGET"))
+ address := strings.TrimSpace(os.Getenv("KG_SSH_DIAL_ADDR"))
+ if target == "" || address == "" {
+ t.Skip("KG_SSH_DIAL_TARGET / KG_SSH_DIAL_ADDR 未设置:跳过(CI 默认不跑)")
+ }
+ dialer, err := SSHDialer(target, address)
+ if err != nil {
+ t.Fatalf("SSHDialer() error = %v", err)
+ }
+ conn, err := dialer(context.Background(), "tcp", address)
+ if err != nil {
+ t.Fatalf("dial error = %v", err)
+ }
+ defer conn.Close()
+ // 真实 deadline 必须可用(否则 pgx 的连接超时形同虚设)。
+ if err := conn.SetDeadline(time.Now().Add(10 * time.Second)); err != nil {
+ t.Fatalf("socketpair 连接必须支持 deadline:%v", err)
+ }
+ if _, err := fmt.Fprintf(conn, "GET /version HTTP/1.1\r\nHost: %s\r\nConnection: close\r\n\r\n", address); err != nil {
+ t.Fatalf("write error = %v", err)
+ }
+ response, err := http.ReadResponse(bufio.NewReader(conn), nil)
+ if err != nil {
+ t.Fatalf("read error = %v", err)
+ }
+ defer response.Body.Close()
+ if response.StatusCode != http.StatusOK {
+ t.Fatalf("status = %d", response.StatusCode)
+ }
+ buf := make([]byte, 256)
+ n, _ := response.Body.Read(buf)
+ if !strings.Contains(string(buf[:n]), "commit_sha") {
+ t.Fatalf("经 SSH 通道取到的响应不像版本接口:%q", string(buf[:n]))
+ }
+ var _ net.Conn = conn
+}
+
+// 取消的 context 不得创建连接、不得启动子进程(独立探测曾证明旧实现照样建连)。
+func TestSSHDialerRespectsCancelledContext(t *testing.T) {
+ dialer, err := SSHDialer("definitely-not-a-real-ssh-alias", "127.0.0.1:5432")
+ if err != nil {
+ t.Fatalf("SSHDialer() error = %v", err)
+ }
+ ctx, cancel := context.WithCancel(context.Background())
+ cancel()
+ conn, err := dialer(ctx, "tcp", "127.0.0.1:1")
+ if err == nil || conn != nil {
+ t.Fatalf("ctx 已取消时不得建连:conn=%v err=%v", conn, err)
+ }
+ if !strings.Contains(err.Error(), "cancelled") {
+ t.Fatalf("应明确说明是取消:%v", err)
+ }
+}
+
+// 关闭连接必须回收子进程(不阻塞、幂等);顺带证明 GetDeadline/SetDeadline 是真实能力。
+func TestSSHTunnelCloseReapsChild(t *testing.T) {
+ target := strings.TrimSpace(os.Getenv("KG_SSH_DIAL_TARGET"))
+ if target == "" {
+ t.Skip("KG_SSH_DIAL_TARGET 未设置:跳过(需要有已批准目标才能起 ssh 子进程)")
+ }
+ dialer, err := SSHDialer(target, "127.0.0.1:1") // 目标端口不通也没关系:本轮只看生命周期
+ if err != nil {
+ t.Fatalf("SSHDialer() error = %v", err)
+ }
+ conn, err := dialer(context.Background(), "tcp", "127.0.0.1:1")
+ if err != nil {
+ t.Skipf("无法在本机建立隧道(%v)—— 该用例只在有 ssh 能力的环境有意义", err)
+ }
+ tunnel, ok := conn.(*tunnelConn)
+ if !ok {
+ t.Fatalf("返回值应绑定子进程生命周期:%T", conn)
+ }
+ if err := tunnel.Close(); err != nil {
+ t.Fatalf("Close() error = %v", err)
+ }
+ if err := tunnel.Close(); err != nil {
+ t.Fatalf("Close() 必须幂等:%v", err)
+ }
+ select {
+ case <-tunnel.Exited():
+ case <-time.After(5 * time.Second):
+ t.Fatal("关闭连接后 ssh 子进程没有被回收")
+ }
+}
diff --git a/internal/dobotaiops/window.go b/internal/dobotaiops/window.go
new file mode 100644
index 0000000..66aff15
--- /dev/null
+++ b/internal/dobotaiops/window.go
@@ -0,0 +1,87 @@
+package dobotaiops
+
+import (
+ "encoding/base64"
+ "fmt"
+ "strings"
+ "time"
+)
+
+// Window 是一次只读统计/列举的时间范围,语义固定为**半开区间**:
+// created_at >= Start AND created_at < End(工单要求)。
+type Window struct {
+ TenantKey string
+ Start time.Time
+ End time.Time
+}
+
+// NewWindow 解析并校验调用方给的租户与时间范围:
+// - 租户非空、长度受限(不做任何 SQL 拼接,只作为绑定参数);
+// - 时间是 RFC3339(允许带时区),必须有 start < end;
+// - 窗口跨度不超过上限(默认 90 天)、不允许跑到未来太远。
+func NewWindow(tenantKey, startRaw, endRaw string, limit time.Duration, now time.Time) (Window, error) {
+ tenantKey = strings.TrimSpace(tenantKey)
+ if tenantKey == "" || len(tenantKey) > 128 {
+ return Window{}, fmt.Errorf("%w: tenant key is required", ErrInvalidQuery)
+ }
+ start, err := parseInstant(startRaw)
+ if err != nil {
+ return Window{}, err
+ }
+ end, err := parseInstant(endRaw)
+ if err != nil {
+ return Window{}, err
+ }
+ if !start.Before(end) {
+ return Window{}, fmt.Errorf("%w: start must be before end", ErrInvalidQuery)
+ }
+ if limit <= 0 {
+ limit = 90 * 24 * time.Hour
+ }
+ if end.Sub(start) > limit {
+ return Window{}, fmt.Errorf("%w: window exceeds the %s limit", ErrInvalidQuery, limit)
+ }
+ if end.After(now.Add(5 * time.Minute)) {
+ return Window{}, fmt.Errorf("%w: end is in the future", ErrInvalidQuery)
+ }
+ return Window{TenantKey: tenantKey, Start: start.UTC(), End: end.UTC()}, nil
+}
+
+func parseInstant(raw string) (time.Time, error) {
+ raw = strings.TrimSpace(raw)
+ if raw == "" {
+ return time.Time{}, fmt.Errorf("%w: time is required", ErrInvalidQuery)
+ }
+ parsed, err := time.Parse(time.RFC3339, raw)
+ if err != nil {
+ return time.Time{}, fmt.Errorf("%w: time must be RFC3339 (with offset)", ErrInvalidQuery)
+ }
+ return parsed.UTC(), nil
+}
+
+// Cursor 是 (created_at, id) 复合游标:与工单要求一致 —— 稳定、确定性、翻页不漏不重。
+type Cursor struct {
+ CreatedAt time.Time
+ ID string
+}
+
+// EncodeCursor / DecodeCursor 只做无损编解码,不做业务判断;非法游标一律报 ErrInvalidQuery。
+func EncodeCursor(cursor Cursor) string {
+ return base64.RawURLEncoding.EncodeToString([]byte(cursor.CreatedAt.UTC().Format(time.RFC3339Nano) + "|" + cursor.ID))
+}
+
+func DecodeCursor(raw string) (Cursor, error) {
+ decoded, err := base64.RawURLEncoding.DecodeString(strings.TrimSpace(raw))
+ if err != nil {
+ return Cursor{}, fmt.Errorf("%w: cursor is not valid", ErrInvalidQuery)
+ }
+ parts := strings.SplitN(string(decoded), "|", 2)
+ if len(parts) != 2 || parts[1] == "" {
+ return Cursor{}, fmt.Errorf("%w: cursor is not valid", ErrInvalidQuery)
+ }
+ createdAt, err := time.Parse(time.RFC3339Nano, parts[0])
+ if err != nil {
+ return Cursor{}, fmt.Errorf("%w: cursor is not valid", ErrInvalidQuery)
+ }
+ return Cursor{CreatedAt: createdAt.UTC(), ID: parts[1]}, nil
+}
diff --git a/internal/httpapi/auth.go b/internal/httpapi/auth.go
index 780f650..ef8279d 100644
--- a/internal/httpapi/auth.go
+++ b/internal/httpapi/auth.go
@@ -101,7 +101,7 @@ func isAuthEndpoint(method, path string) bool {
func classifyRole(method, path string) string {
// The member roster exposes account identities and roles: admin-only for
// every method, checked before the read shortcut below.
- if strings.HasPrefix(path, "/api/v1/users") {
+ if strings.HasPrefix(path, "/api/v1/users") || strings.HasPrefix(path, "/api/v1/qa-ops/") {
return roleAdmin
}
if method == http.MethodGet {
diff --git a/internal/httpapi/qa_ops.go b/internal/httpapi/qa_ops.go
new file mode 100644
index 0000000..402841b
--- /dev/null
+++ b/internal/httpapi/qa_ops.go
@@ -0,0 +1,143 @@
+package httpapi
+
+import (
+ "context"
+ "errors"
+ "net/http"
+ "strconv"
+ "time"
+
+ "knowledge-governance/internal/dobotaiops"
+)
+
+// No raw SQL, source credential, arbitrary tenant or write method crosses this boundary.
+type QAOpsReader interface {
+ ListRecords(context.Context, dobotaiops.RecordQuery) (dobotaiops.RecordPage, error)
+ GetRecord(context.Context, string, string) (dobotaiops.Record, error)
+ Available(context.Context) error
+ Safety() dobotaiops.SourceSafety
+}
+
+func authorizeQAOps(w http.ResponseWriter, r *http.Request) bool {
+ w.Header().Set("Cache-Control", "no-store")
+ w.Header().Set("Pragma", "no-cache")
+ identity, ok := sessionFrom(r.Context())
+ if !ok {
+ writeJSON(w, http.StatusUnauthorized, map[string]string{"error": "问答运营需要登录后访问"})
+ return false
+ }
+ // Until the employee-data visibility scope is approved, do not widen access
+ // to all pre-existing viewers/engineers merely because this endpoint is GET.
+ if identity.Role != roleAdmin {
+ writeJSON(w, http.StatusForbidden, map[string]string{"error": "尚未配置员工问答可见范围,当前仅管理员可访问"})
+ return false
+ }
+ return true
+}
+
+func qaOpsStatus(w http.ResponseWriter, r *http.Request, config Config) {
+ if !authorizeQAOps(w, r) {
+ return
+ }
+ state := "disabled"
+ code := "source_not_configured"
+ warnings := []string{}
+ if config.QAOpsEnabled {
+ state = "unavailable"
+ code = "source_unavailable"
+ }
+ if config.QAOpsProblem != "" {
+ state = "blocked"
+ code = "source_configuration_invalid"
+ }
+ if config.QAOps != nil && config.QAOps.Available(r.Context()) == nil {
+ state = "connected"
+ code = ""
+ safety := config.QAOps.Safety()
+ if safety.DatabaseTemp {
+ warnings = append(warnings, "database_temp_enabled")
+ }
+ if !safety.SSL {
+ warnings = append(warnings, "database_transport_unencrypted")
+ }
+ }
+ writeJSON(w, http.StatusOK, map[string]any{"data": map[string]any{"state": state, "code": code, "warnings": warnings, "read_only": true, "source_version": "2.0", "channel": "dingtalk"}})
+}
+
+func listQAOpsRecords(w http.ResponseWriter, r *http.Request, config Config) {
+ if !authorizeQAOps(w, r) {
+ return
+ }
+ if config.QAOps == nil || config.QAOpsTenantKey == "" {
+ qaOpsError(w, dobotaiops.ErrUnavailable)
+ return
+ }
+ values := r.URL.Query()
+ allowed := map[string]bool{"start": true, "end": true, "keyword": true, "cursor": true, "limit": true}
+ for key, items := range values {
+ if !allowed[key] || len(items) != 1 {
+ qaOpsError(w, dobotaiops.ErrInvalidQuery)
+ return
+ }
+ }
+ window, err := dobotaiops.NewWindow(config.QAOpsTenantKey, values.Get("start"), values.Get("end"), 90*24*time.Hour, config.Now())
+ if err != nil {
+ qaOpsError(w, err)
+ return
+ }
+ limit := 20
+ if raw := values.Get("limit"); raw != "" {
+ limit, err = strconv.Atoi(raw)
+ if err != nil || limit < 1 || limit > 100 {
+ qaOpsError(w, dobotaiops.ErrInvalidQuery)
+ return
+ }
+ }
+ page, err := config.QAOps.ListRecords(r.Context(), dobotaiops.RecordQuery{Window: window, Keyword: values.Get("keyword"), Cursor: values.Get("cursor"), Limit: limit})
+ if err != nil {
+ qaOpsError(w, err)
+ return
+ }
+ writeJSON(w, http.StatusOK, map[string]any{"data": page})
+}
+
+func getQAOpsRecord(w http.ResponseWriter, r *http.Request, config Config) {
+ if !authorizeQAOps(w, r) {
+ return
+ }
+ if config.QAOps == nil || config.QAOpsTenantKey == "" {
+ qaOpsError(w, dobotaiops.ErrUnavailable)
+ return
+ }
+ if r.URL.RawQuery != "" {
+ qaOpsError(w, dobotaiops.ErrInvalidQuery)
+ return
+ }
+ item, err := config.QAOps.GetRecord(r.Context(), config.QAOpsTenantKey, r.PathValue("id"))
+ if err != nil {
+ qaOpsError(w, err)
+ return
+ }
+ writeJSON(w, http.StatusOK, map[string]any{"data": item})
+}
+
+func qaOpsError(w http.ResponseWriter, err error) {
+ status := http.StatusServiceUnavailable
+ code := "source_unavailable"
+ message := "问答数据源不可用,请检查独立只读连接;原有知识治理功能不受影响"
+ if errors.Is(err, dobotaiops.ErrInvalidQuery) {
+ status = http.StatusBadRequest
+ code = "invalid_query"
+ message = "查询参数无效:请检查时间范围、关键词长度或重新查询后翻页"
+ }
+ if errors.Is(err, dobotaiops.ErrNotReadOnly) {
+ code = "source_not_read_only"
+ message = "问答连接权限校验未通过,已阻止读取,请联系管理员"
+ }
+ if errors.Is(err, dobotaiops.ErrRecordNotFound) {
+ status = http.StatusNotFound
+ code = "record_not_found"
+ message = "未找到当前授权范围内的问答记录"
+ }
+ writeJSON(w, status, map[string]string{"error": message, "code": code})
+}
diff --git a/internal/httpapi/qa_ops_auth_test.go b/internal/httpapi/qa_ops_auth_test.go
new file mode 100644
index 0000000..ea1fd35
--- /dev/null
+++ b/internal/httpapi/qa_ops_auth_test.go
@@ -0,0 +1,87 @@
+package httpapi
+
+import (
+ "context"
+ "errors"
+ "knowledge-governance/internal/dobotaiops"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+)
+
+type qaOpsSpy struct {
+ query dobotaiops.RecordQuery
+ tenant, id string
+ calls int
+ err error
+}
+
+func (s *qaOpsSpy) ListRecords(_ context.Context, q dobotaiops.RecordQuery) (dobotaiops.RecordPage, error) {
+ s.query = q
+ s.calls++
+ return dobotaiops.RecordPage{Items: []dobotaiops.Record{}}, s.err
+}
+func (s *qaOpsSpy) GetRecord(_ context.Context, tenant, id string) (dobotaiops.Record, error) {
+ s.tenant = tenant
+ s.id = id
+ s.calls++
+ return dobotaiops.Record{}, s.err
+}
+func (s *qaOpsSpy) Available(context.Context) error { return s.err }
+func (s *qaOpsSpy) Safety() dobotaiops.SourceSafety {
+ return dobotaiops.SourceSafety{DatabaseTemp: true, SSL: false}
+}
+
+func TestQAOperationsRequireExplicitSessionAndServerSelectedTenant(t *testing.T) {
+ spy := &qaOpsSpy{}
+ auth := newFakeAuthStore()
+ for token, user := range map[string]string{"admin-qa-fixture": "usr-boss", "viewer-qa-fixture": "usr-eye", "engineer-qa-fixture": "usr-eng"} {
+ auth.sessions[token] = user
+ }
+ handler, err := NewHandler(Config{Store: &fakeJobStore{}, QAOps: spy, QAOpsEnabled: true, QAOpsTenantKey: "approved-tenant", Auth: &AuthConfig{Store: auth}})
+ if err != nil {
+ t.Fatal(err)
+ }
+ base := "/api/v1/qa-ops/records?start=2026-10-14T00:00:00Z&end=2026-10-15T00:00:00Z"
+ for _, tc := range []struct {
+ token, path string
+ status int
+ }{
+ {"", base, http.StatusUnauthorized}, {"viewer-qa-fixture", base, http.StatusForbidden}, {"engineer-qa-fixture", base, http.StatusForbidden},
+ {"admin-qa-fixture", base + "&tenant_key=another-tenant", http.StatusBadRequest},
+ {"admin-qa-fixture", base + "&limit=0", http.StatusBadRequest},
+ {"admin-qa-fixture", base + "&keyword=a&keyword=b", http.StatusBadRequest},
+ {"admin-qa-fixture", base + "&keyword=test", http.StatusOK},
+ } {
+ request := httptest.NewRequest(http.MethodGet, tc.path, nil)
+ if tc.token != "" {
+ request.AddCookie(&http.Cookie{Name: sessionCookieName, Value: tc.token})
+ }
+ response := httptest.NewRecorder()
+ handler.ServeHTTP(response, request)
+ if response.Code != tc.status {
+ t.Fatalf("status=%d want=%d body=%s", response.Code, tc.status, response.Body.String())
+ }
+ }
+ if spy.calls != 1 || spy.query.Window.TenantKey != "approved-tenant" || spy.query.Keyword != "test" {
+ t.Fatalf("unauthorized/invalid reads reached source: %+v", spy)
+ }
+ spy.err = errors.New("sensitive-driver-detail-not-for-browser")
+ request := httptest.NewRequest(http.MethodGet, base, nil)
+ request.AddCookie(&http.Cookie{Name: sessionCookieName, Value: "admin-qa-fixture"})
+ response := httptest.NewRecorder()
+ handler.ServeHTTP(response, request)
+ if response.Code != http.StatusServiceUnavailable || strings.Contains(response.Body.String(), "sensitive-driver-detail") {
+ t.Fatalf("source failure leaked or became empty success: %s", response.Body.String())
+ }
+ if response.Header().Get("Cache-Control") != "no-store" {
+ t.Fatal("employee answers must not be cached")
+ }
+ unauth, _ := NewHandler(Config{Store: &fakeJobStore{}, QAOps: spy, QAOpsTenantKey: "approved-tenant"})
+ response = httptest.NewRecorder()
+ unauth.ServeHTTP(response, httptest.NewRequest(http.MethodGet, base, nil))
+ if response.Code != http.StatusUnauthorized {
+ t.Fatal("auth-disabled governance must not expose production answers")
+ }
+}
diff --git a/internal/httpapi/qa_ops_roles_test.go b/internal/httpapi/qa_ops_roles_test.go
new file mode 100644
index 0000000..8513c76
--- /dev/null
+++ b/internal/httpapi/qa_ops_roles_test.go
@@ -0,0 +1,14 @@
+package httpapi
+
+import (
+ "net/http"
+ "testing"
+)
+
+func TestQAOperationsRoleGatePrecedesGenericGETShortcut(t *testing.T) {
+ for _, path := range []string{"/api/v1/qa-ops/status", "/api/v1/qa-ops/records", "/api/v1/qa-ops/records/some-id"} {
+ if role := classifyRole(http.MethodGet, path); role != roleAdmin {
+ t.Fatalf("QA employee data route classified as %s, must require admin: %s", role, path)
+ }
+ }
+}
diff --git a/internal/httpapi/qa_ops_test.go b/internal/httpapi/qa_ops_test.go
new file mode 100644
index 0000000..0db85e2
--- /dev/null
+++ b/internal/httpapi/qa_ops_test.go
@@ -0,0 +1,28 @@
+package httpapi
+
+import (
+ "net/http"
+ "net/http/httptest"
+ "testing"
+)
+
+func TestQAOperationsFailClosedWithoutBreakingGovernance(t *testing.T) {
+ auth := newFakeAuthStore()
+ auth.sessions["admin-qa-fixture"] = "usr-boss"
+ handler, err := NewHandler(Config{Store: &fakeJobStore{}, Auth: &AuthConfig{Store: auth}})
+ if err != nil {
+ t.Fatal(err)
+ }
+ request := httptest.NewRequest(http.MethodGet, "/api/v1/qa-ops/records?start=2026-10-14T00:00:00Z&end=2026-10-15T00:00:00Z", nil)
+ request.AddCookie(&http.Cookie{Name: sessionCookieName, Value: "admin-qa-fixture"})
+ response := httptest.NewRecorder()
+ handler.ServeHTTP(response, request)
+ if response.Code != http.StatusServiceUnavailable {
+ t.Fatalf("unconfigured source must not be an empty list: status=%d body=%s", response.Code, response.Body.String())
+ }
+ health := httptest.NewRecorder()
+ handler.ServeHTTP(health, httptest.NewRequest(http.MethodGet, "/livez", nil))
+ if health.Code != http.StatusOK {
+ t.Fatalf("external source must not stop governance liveness: %d", health.Code)
+ }
+}
diff --git a/internal/httpapi/server.go b/internal/httpapi/server.go
index cec08ed..2c1c1b3 100644
--- a/internal/httpapi/server.go
+++ b/internal/httpapi/server.go
@@ -101,6 +101,10 @@ type Store interface {
}
type Config struct {
+ QAOps QAOpsReader
+ QAOpsTenantKey string
+ QAOpsEnabled bool
+ QAOpsProblem string
Store Store
Monitor MonitorProvider
InternalRoutingKnowledgeBaseID string
@@ -167,6 +171,15 @@ func NewHandler(config Config) (http.Handler, error) {
config.NewID = newID
}
mux := http.NewServeMux()
+ mux.HandleFunc("GET /api/v1/qa-ops/status", func(w http.ResponseWriter, r *http.Request) {
+ qaOpsStatus(w, r, config)
+ })
+ mux.HandleFunc("GET /api/v1/qa-ops/records", func(w http.ResponseWriter, r *http.Request) {
+ listQAOpsRecords(w, r, config)
+ })
+ mux.HandleFunc("GET /api/v1/qa-ops/records/{id}", func(w http.ResponseWriter, r *http.Request) {
+ getQAOpsRecord(w, r, config)
+ })
mux.HandleFunc("GET /health", func(w http.ResponseWriter, _ *http.Request) {
writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
})
diff --git a/scripts/test-scope.json b/scripts/test-scope.json
index 7172361..0198d5c 100644
--- a/scripts/test-scope.json
+++ b/scripts/test-scope.json
@@ -9,6 +9,46 @@
"⚠️ 文件缺失或解析不了 ⇒ 门禁红:范围声明不出来时,不许默认放行。"
],
"optional": [
+ {
+ "package": "knowledge-governance/internal/dobotaiops",
+ "test": "TestSSHDialerTransportsRealTraffic",
+ "reason": "需要已批准 SSH 路径和只读版本接口;CI 不带生产 SSH 凭据,缺环境时显式跳过"
+ },
+ {
+ "package": "knowledge-governance/internal/dobotaiops",
+ "test": "TestSSHTunnelCloseReapsChild",
+ "reason": "需要已批准 SSH 目标来验证子进程回收;无路径的 CI 不应尝试建立生产连接"
+ },
+ {
+ "package": "knowledge-governance/internal/dobotaiops",
+ "test": "TestReadOnlyRepositoryAgainstFixtureDatabase",
+ "reason": "需显式 KG_DOBOTAI_TEST_ISOLATED=1 且 TEST_DATABASE_URL 通过隔离库护栏,CI 不建生产测试表;本批已在一次性测试库补验"
+ },
+ {
+ "package": "knowledge-governance/internal/dobotaiops",
+ "test": "TestBuildRefusesUnsafeAccountsAndTargets",
+ "reason": "只在显式一次性测试库创建危险权限夹具,不在生产库验证写入;本批已在隔离库补验"
+ },
+ {
+ "package": "knowledge-governance/internal/dobotaiops",
+ "test": "TestSourceRechecksEffectivePrivilegesBeforeEveryQuery",
+ "reason": "在一次性测试库模拟额外表写权限,测试前须通过隔离护栏;本批已实际补验"
+ },
+ {
+ "package": "knowledge-governance/internal/dobotaiops",
+ "test": "TestQARecordSearchPreservesSourceAndDoesNotMultiplyFeedback",
+ "reason": "完整查询/反馈/游标/空列验证需要显式一次性测试库;本批已在隔离库补验"
+ },
+ {
+ "package": "knowledge-governance/internal/dobotaiops",
+ "test": "TestProductionReadOnlyCombinedVerification",
+ "reason": "需独立批准的生产只读账号文件与 SSH 路径并显式 KG_DOBOTAI_PROD_VERIFY=1;CI 永不自动读取生产库"
+ },
+ {
+ "package": "knowledge-governance/internal/dobotaiops",
+ "test": "TestProductionQAQueryReadOnlyVerification",
+ "reason": "真实源查询端到端验证仅在显式 KG_DOBOTAI_PROD_VERIFY=1、批准的凭据文件与 SSH 路径下执行;CI 不访问生产,测试不写源库"
+ },
{
"package": "knowledge-governance/internal/platform/postgres",
"reason": "整个包的集成用例都要 TEST_DATABASE_URL 指向可销毁测试库;本仓不连生产库,CI 无库 ⇒ 跳过(补验路径:起一次性 PG 后设 TEST_DATABASE_URL)"
diff --git a/web/src/App.tsx b/web/src/App.tsx
index b2e3488..a25fff7 100644
--- a/web/src/App.tsx
+++ b/web/src/App.tsx
@@ -4,6 +4,7 @@ import { DocumentWorkbench } from './DocumentWorkbench'
import { SourceCatalogBrowser } from './SourceCatalogBrowser'
import { WeKnoraMonitor } from './WeKnoraMonitor'
import { VersionHistory } from './VersionHistory'
+import { QAOperations } from './QAOperations'
import { SourceLinkManager } from './SourceLinkManager'
import { SystemSettings } from './SystemSettings'
import { WorkspaceContextTabsBar, WorkspaceContextTabsSetter } from './workspaceContext'
@@ -59,6 +60,7 @@ const workspaceStorageKey = 'knowledge-governance.workspace.v1'
const modules: ReadonlyArray<{ id: ModuleId; label: string; icon: string }> = [
{ id: 'dashboard', label: '来源与目录', icon: '◫' },
{ id: 'tasks', label: '解析监控', icon: '↻' },
+ { id: 'qaops', label: '问答运营', icon: '▤' },
{ id: 'releases', label: '发布管理', icon: '⇧' },
{ id: 'settings', label: '系统设置', icon: '⚙' },
{ id: 'versions', label: '版本记录', icon: '⌥' },
@@ -3004,6 +3006,8 @@ export default function App() {
) : workspace.activeTab === 'versions' ? (
+ ) : workspace.activeTab === 'qaops' ? (
+
) : (
not executable',
+ answer: '当前暂无已发布的权威知识。',
+ asked_at: '2026-10-14T03:00:00Z',
+ time_source: 'request_message.created_at',
+ asker: '测试人员',
+ trigger_person: '测试昵称',
+ department: '',
+ region: '',
+ references: [{ title: '测试引用' }],
+ media: [],
+ feedback: { asker_value: 'down', up: 0, down: 1 },
+ source_coverage: { verdict: 'covered', reason_code: 'covered_has_references', evaluator_version: 'v5' },
+ coverage: {
+ verdict: 'uncovered',
+ state: 'checked',
+ rule_version: 'governance-answer-substring-v1',
+ matched_text: '暂无已发布',
+ },
+ is_correct: false,
+}
+const page: QARecordPage = {
+ items: [item],
+ columns: ['answer', 'coverage', 'is_correct', 'asked_at', 'asker', 'question', 'feedback'],
+ total: 1,
+ has_more: false,
+ next_cursor: '',
+ as_of: '2026-10-14T04:00:00Z',
+}
+const props = {
+ page,
+ status: null,
+ loading: false,
+ error: null,
+ detail: null,
+ detailLoading: false,
+ detailError: null,
+ onSelect: vi.fn(),
+ onCloseDetail: vi.fn(),
+ onLoadMore: vi.fn(),
+ onRetry: vi.fn(),
+}
+
+describe('QA operations workbench', () => {
+ it('shows populated columns in required order and keeps false/downvotes visible', () => {
+ const html = renderToStaticMarkup()
+ expect(html).toContain('原始问题')
+ expect(html.indexOf('AI答案')).toBeLessThan(html.indexOf('是否覆盖'))
+ expect(html.indexOf('是否正确')).toBeLessThan(html.indexOf('提问时间'))
+ expect(html).toContain('否(点踩)')
+ expect(html).toContain('是否正确')
+ expect(html).not.toContain('| 部门 | ')
+ expect(html).not.toContain('产品分类 | ')
+ expect(html).not.toContain('')
+ })
+ it('distinguishes an unavailable source from a successful empty query', () => {
+ const html = renderToStaticMarkup()
+ expect(html).toContain('role="alert"')
+ expect(html).toContain('只读源不可用')
+ expect(html).not.toContain('没有符合条件的问答')
+ })
+ it('shows complete source and governance evidence separately in the detail drawer', () => {
+ const html = renderToStaticMarkup()
+ expect(html).toContain('role="dialog"')
+ expect(html).toContain('暂无已发布')
+ expect(html).toContain('源端覆盖(仅对照)')
+ expect(html).toContain('covered_has_references')
+ expect(html).toContain('测试引用')
+ })
+ it('restores the existing singleton workspace tab without creating another application', () => {
+ const restored = restoreWorkspace(JSON.stringify({ openTabs: ['dashboard', 'qaops'], activeTab: 'qaops' }))
+ expect(restored.openTabs).toEqual(['dashboard', 'qaops'])
+ expect(restored.activeTab).toBe('qaops')
+ })
+})
diff --git a/web/src/QAOperations.tsx b/web/src/QAOperations.tsx
new file mode 100644
index 0000000..bbe2ca7
--- /dev/null
+++ b/web/src/QAOperations.tsx
@@ -0,0 +1,428 @@
+import { useEffect, useRef, useState } from 'react'
+import type { FormEvent } from 'react'
+import { useOptionalAuth } from './auth'
+import { fetchQARecord, fetchQARecords, fetchQAStatus, qaCellValue, qaColumns } from './qaOps'
+import type { QAQuery, QARecord, QARecordPage, QAStatus } from './qaOps'
+import './qaOps.css'
+
+interface ViewProps {
+ page: QARecordPage | null
+ status: QAStatus | null
+ loading: boolean
+ error: string | null
+ detail: QARecord | null
+ detailLoading: boolean
+ detailError: string | null
+ onSelect: (id: string) => void
+ onCloseDetail: () => void
+ onLoadMore: () => void
+ onRetry: () => void
+}
+const stateLabels = { disabled: '未配置', unavailable: '连接不可用', blocked: '接入被阻断', connected: '已连接' }
+const warningLabels: Record = {
+ database_temp_enabled: '数据库仍允许临时对象:未视为完全只读验收通过',
+ database_transport_unencrypted: '数据库连接未启用 TLS:上线前须完成传输安全审核',
+}
+const stamp = (value: string) => new Date(value).toLocaleString('zh-CN', { hour12: false })
+const statusLabels: Record = {
+ succeeded: '成功',
+ failed: '失败',
+ running: '处理中',
+ cancelled: '已取消',
+}
+const sourceCoverageLabels: Record = { covered: '已覆盖', uncovered: '未覆盖' }
+
+export function QAOperationsView(props: ViewProps) {
+ const page = props.page
+ const columns = qaColumns.filter(({ key }) => page?.columns.includes(key))
+ const detail = props.detail
+ const showDrawer = Boolean(detail || props.detailLoading || props.detailError)
+ return (
+
+
+
+ {props.loading ? '正在读取…' : page ? `共 ${page.total} 条 · 已显示 ${page.items.length} 条` : '尚未读取问答'}
+
+
+ DobotAI 2.0 / 钉钉 · 独立只读连接{props.status ? ` · ${stateLabels[props.status.state]}` : ''}
+
+
+ {props.status?.warnings.map((warning) => (
+
+ {warningLabels[warning] ?? '数据源有待审核的安全告警'}
+
+ ))}
+ {props.error ? (
+
+ {props.error}{' '}
+
+
+ ) : null}
+ {page && page.items.length > 0 ? (
+
+
+
+
+ {columns.map(({ key, label }) => (
+ | {label} |
+ ))}
+ 操作 |
+
+
+
+ {page.items.map((item) => (
+
+ {columns.map(({ key }) => (
+ |
+
+ {qaCellValue(item, key) ?? '—'}
+
+ |
+ ))}
+
+
+ |
+
+ ))}
+
+
+
+ ) : page && !props.loading && !props.error ? (
+ 没有符合条件的问答,请调整时间范围或关键词。
+ ) : null}
+ {page ? (
+
+ ) : null}
+ {showDrawer ? (
+ <>
+
+
+ >
+ ) : null}
+
+ )
+}
+
+function localInput(value: Date): string {
+ return new Date(value.getTime() - value.getTimezoneOffset() * 60_000).toISOString().slice(0, 16)
+}
+function initialDraft() {
+ const end = new Date()
+ return { start: localInput(new Date(end.getTime() - 7 * 24 * 3600_000)), end: localInput(end), keyword: '' }
+}
+
+export function QAOperations() {
+ const auth = useOptionalAuth()
+ const canRead = auth?.identity?.role === 'admin'
+ const [draft, setDraft] = useState(initialDraft)
+ const [query, setQuery] = useState(null)
+ const [page, setPage] = useState(null)
+ const [status, setStatus] = useState(null)
+ const [error, setError] = useState(null)
+ const [loading, setLoading] = useState(false)
+ const [revision, setRevision] = useState(0)
+ const [detail, setDetail] = useState(null)
+ const [detailLoading, setDetailLoading] = useState(false)
+ const [detailError, setDetailError] = useState(null)
+ const generation = useRef(0)
+ const detailRequest = useRef(null)
+ const moreRequest = useRef(null)
+ const returnFocus = useRef(null)
+
+ useEffect(() => {
+ if (!canRead || query) return
+ setQuery({
+ start: new Date(draft.start).toISOString(),
+ end: new Date(draft.end).toISOString(),
+ keyword: draft.keyword,
+ cursor: '',
+ })
+ }, [canRead, draft, query])
+
+ useEffect(() => {
+ if (!query || !canRead) return
+ const controller = new AbortController()
+ generation.current += 1
+ moreRequest.current?.abort()
+ detailRequest.current?.abort()
+ setLoading(true)
+ setError(null)
+ setPage(null)
+ setDetail(null)
+ setDetailError(null)
+ setDetailLoading(false)
+ void fetchQAStatus(controller.signal)
+ .then(setStatus)
+ .catch(() => {
+ if (!controller.signal.aborted) setStatus(null)
+ })
+ void fetchQARecords(query, controller.signal)
+ .then((result) => {
+ if (!controller.signal.aborted) setPage(result)
+ })
+ .catch((reason: unknown) => {
+ if (!controller.signal.aborted) setError(reason instanceof Error ? reason.message : '问答读取失败')
+ })
+ .finally(() => {
+ if (!controller.signal.aborted) setLoading(false)
+ })
+ return () => controller.abort()
+ }, [query, canRead, revision])
+
+ useEffect(
+ () => () => {
+ detailRequest.current?.abort()
+ moreRequest.current?.abort()
+ },
+ []
+ )
+
+ const submit = (event: FormEvent) => {
+ event.preventDefault()
+ try {
+ const start = new Date(draft.start),
+ end = new Date(draft.end)
+ if (!(start < end)) throw new Error('开始时间必须早于结束时间')
+ setQuery({ start: start.toISOString(), end: end.toISOString(), keyword: draft.keyword, cursor: '' })
+ } catch (reason) {
+ setError(reason instanceof Error ? reason.message : '时间格式无效')
+ }
+ }
+ const select = async (id: string) => {
+ detailRequest.current?.abort()
+ returnFocus.current = document.activeElement as HTMLElement | null
+ const controller = new AbortController()
+ detailRequest.current = controller
+ setDetail(null)
+ setDetailError(null)
+ setDetailLoading(true)
+ try {
+ const result = await fetchQARecord(id, controller.signal)
+ if (!controller.signal.aborted) setDetail(result)
+ } catch (reason) {
+ if (!controller.signal.aborted) setDetailError(reason instanceof Error ? reason.message : '详情读取失败')
+ } finally {
+ if (!controller.signal.aborted) setDetailLoading(false)
+ }
+ }
+ const close = () => {
+ detailRequest.current?.abort()
+ setDetail(null)
+ setDetailError(null)
+ setDetailLoading(false)
+ returnFocus.current?.focus()
+ }
+ const loadMore = async () => {
+ if (!query || !page?.has_more || loading) return
+ const currentGeneration = generation.current
+ const controller = new AbortController()
+ moreRequest.current = controller
+ setLoading(true)
+ setError(null)
+ try {
+ const result = await fetchQARecords({ ...query, cursor: page.next_cursor }, controller.signal)
+ if (!controller.signal.aborted && currentGeneration === generation.current) {
+ setPage((current) =>
+ current
+ ? {
+ ...result,
+ items: [
+ ...current.items,
+ ...result.items.filter((item) => !current.items.some(({ id }) => id === item.id)),
+ ],
+ }
+ : result
+ )
+ }
+ } catch (reason) {
+ if (!controller.signal.aborted && currentGeneration === generation.current)
+ setError(reason instanceof Error ? reason.message : '翻页失败')
+ } finally {
+ if (!controller.signal.aborted && currentGeneration === generation.current) setLoading(false)
+ }
+ }
+ return (
+
+
+ {!canRead ? (
+
+ 尚未配置员工问答可见范围,当前仅管理员可访问。
+
+ ) : (
+ <>
+
+
+ 当前切片:问答查询与覆盖复检。外语翻译、AI评估及人员映射尚未接入;空值不默认填“否”。
+
+ void select(id)}
+ onCloseDetail={close}
+ onLoadMore={() => void loadMore()}
+ onRetry={() => setRevision((value) => value + 1)}
+ />
+ >
+ )}
+
+ )
+}
diff --git a/web/src/qaOps.css b/web/src/qaOps.css
new file mode 100644
index 0000000..1985b0b
--- /dev/null
+++ b/web/src/qaOps.css
@@ -0,0 +1,267 @@
+.qa-ops {
+ display: flex;
+ flex-direction: column;
+ min-width: 0;
+ gap: 14px;
+ padding: 20px;
+ height: calc(100dvh - 44px);
+ overflow: hidden;
+}
+.qa-ops-header h2 {
+ margin: 0 0 5px;
+ font-size: 21px;
+ font-weight: 650;
+}
+.qa-ops-header h2 span {
+ font-size: 15px;
+ color: var(--ink-mute);
+ font-weight: 400;
+}
+.qa-ops-header p,
+.qa-ops-slice-note {
+ margin: 0;
+ color: var(--ink-mute);
+ font-size: 13px;
+ line-height: 1.6;
+}
+.qa-ops-query {
+ display: flex;
+ flex-wrap: wrap;
+ align-items: end;
+ gap: 12px;
+ padding: 14px;
+ border: 1px solid var(--border-base);
+ background: var(--bg-panel);
+}
+.qa-ops-query label {
+ display: flex;
+ flex-direction: column;
+ gap: 6px;
+ color: var(--ink-mute);
+ font-size: 12px;
+}
+.qa-ops-query input {
+ min-height: 36px;
+ min-width: 0;
+ padding: 7px 10px;
+ color: var(--ink-strong);
+ border: 1px solid var(--border-strong);
+ border-radius: var(--r-sm);
+ background: var(--bg-panel);
+}
+.qa-ops-keyword {
+ flex: 1;
+ min-width: 170px;
+}
+.qa-ops-query button {
+ min-height: 36px;
+ min-width: 72px;
+ color: #fff;
+ background: var(--c-run);
+ border: 1px solid var(--c-run);
+}
+.qa-ops button:focus-visible,
+.qa-ops input:focus-visible,
+.qa-ops-table-scroll:focus-visible {
+ outline: 2px solid var(--c-run);
+ outline-offset: 2px;
+}
+.qa-ops-results {
+ display: flex;
+ flex-direction: column;
+ flex: 1;
+ min-width: 0;
+ min-height: 0;
+ border: 1px solid var(--border-base);
+ background: var(--bg-panel);
+}
+.qa-ops-result-bar,
+.qa-ops-page-bar {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: 12px;
+ flex-wrap: wrap;
+ padding: 11px 14px;
+ font-size: 12px;
+ color: var(--ink-mute);
+ font-variant-numeric: tabular-nums;
+}
+.qa-ops-result-bar {
+ border-bottom: 1px solid var(--border-base);
+}
+.qa-ops-source {
+ color: var(--ink-mute);
+}
+.qa-ops-warning {
+ margin: 8px 14px;
+ padding: 7px 10px;
+ font-size: 12px;
+ line-height: 1.5;
+ color: var(--c-warn);
+ background: var(--c-warn-bg);
+ border-left: 2px solid var(--c-warn-border);
+}
+.qa-ops-table-scroll {
+ flex: 1;
+ min-height: 0;
+ overflow: auto;
+}
+.qa-ops-table {
+ width: 100%;
+ min-width: 980px;
+ border-collapse: collapse;
+ table-layout: auto;
+ font-size: 13px;
+}
+.qa-ops-table th {
+ position: sticky;
+ top: 0;
+ z-index: 1;
+ white-space: nowrap;
+ background: var(--bg-soft);
+ font-size: 12px;
+ font-weight: 500;
+ color: var(--ink-mute);
+}
+.qa-ops-table td,
+.qa-ops-table th {
+ padding: 11px 12px;
+ border-bottom: 1px solid var(--border-soft);
+ text-align: left;
+ vertical-align: top;
+}
+.qa-ops-table td {
+ min-width: 90px;
+ max-width: 210px;
+ color: var(--ink-strong);
+ overflow-wrap: anywhere;
+}
+.qa-ops-table tr:hover td {
+ background: var(--bg-hover);
+}
+.qa-ops-table td.qa-ops-text-cell {
+ min-width: 240px;
+ max-width: 340px;
+}
+.qa-ops-text-cell > span {
+ display: -webkit-box;
+ -webkit-line-clamp: 3;
+ -webkit-box-orient: vertical;
+ overflow: hidden;
+ white-space: pre-wrap;
+}
+.qa-ops-uncovered {
+ color: var(--c-warn);
+ font-weight: 600;
+}
+.qa-ops-empty {
+ padding: 35px 16px;
+ margin: 0;
+ color: var(--ink-mute);
+ text-align: center;
+}
+.qa-ops-page-bar {
+ border-top: 1px solid var(--border-base);
+}
+.qa-ops-backdrop {
+ position: fixed;
+ inset: 0;
+ z-index: 80;
+ width: 100%;
+ height: 100%;
+ border: 0;
+ border-radius: 0;
+ background: rgb(15 23 32 / 28%);
+ cursor: default;
+}
+.qa-ops-backdrop:hover {
+ background: rgb(15 23 32 / 28%);
+}
+.qa-ops-drawer {
+ position: fixed;
+ top: 0;
+ right: 0;
+ z-index: 81;
+ width: min(760px, 100vw);
+ height: 100vh;
+ overflow: auto;
+ padding: 22px;
+ background: var(--bg-panel);
+ border-left: 1px solid var(--border-strong);
+ color: var(--ink-strong);
+}
+.qa-ops-drawer > header {
+ display: flex;
+ justify-content: space-between;
+ align-items: center;
+ gap: 14px;
+ position: sticky;
+ top: -22px;
+ padding: 12px 0;
+ background: var(--bg-panel);
+ border-bottom: 1px solid var(--border-base);
+}
+.qa-ops-drawer h3 {
+ margin: 0;
+ font-size: 18px;
+}
+.qa-ops-drawer h4 {
+ margin: 24px 0 9px;
+ font-size: 14px;
+}
+.qa-ops-detail-content {
+ font-size: 13px;
+ line-height: 1.7;
+ overflow-wrap: anywhere;
+}
+.qa-ops-detail-meta {
+ display: grid;
+ grid-template-columns: 140px 1fr;
+ gap: 6px 14px;
+ margin: 18px 0;
+}
+.qa-ops-detail-meta dt,
+.qa-ops-muted {
+ color: var(--ink-mute);
+}
+.qa-ops-detail-meta dd {
+ margin: 0;
+}
+.qa-ops-full-text {
+ white-space: pre-wrap;
+ background: var(--bg-soft);
+ padding: 12px;
+ border: 1px solid var(--border-soft);
+}
+.qa-ops-drawer pre {
+ white-space: pre-wrap;
+ word-break: break-word;
+ background: var(--bg-soft);
+ padding: 12px;
+ font-size: 12px;
+}
+@media (max-width: 760px) {
+ .qa-ops {
+ height: auto;
+ min-height: calc(100dvh - 44px);
+ padding: 14px;
+ overflow: visible;
+ }
+ .qa-ops-results {
+ flex: none;
+ }
+ .qa-ops-query label {
+ flex: 1 1 100%;
+ }
+ .qa-ops-table-scroll {
+ min-height: 160px;
+ max-height: 55vh;
+ }
+ .qa-ops-drawer {
+ padding: 14px;
+ }
+ .qa-ops-detail-meta {
+ grid-template-columns: 100px 1fr;
+ }
+}
diff --git a/web/src/qaOps.test.ts b/web/src/qaOps.test.ts
new file mode 100644
index 0000000..c32e5ed
--- /dev/null
+++ b/web/src/qaOps.test.ts
@@ -0,0 +1,66 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { fetchQARecords, parseQARecord, parseQARecordPage } from './qaOps'
+
+export const fixtureRecord = {
+ id: 'test-turn',
+ status: 'succeeded',
+ question: 'How to configure CR5?',
+ answer: '当前暂无已发布的权威知识,暂不建议操作。',
+ asked_at: '2026-10-14T03:00:00Z',
+ time_source: 'request_message.created_at',
+ asker: '测试人员',
+ trigger_person: '回调昵称',
+ department: '',
+ region: '',
+ references: [{ title: '测试引用' }],
+ media: [],
+ source_coverage: { verdict: 'covered', reason_code: 'covered_has_references', evaluator_version: 'v5' },
+ feedback: { asker_value: 'down', up: 0, down: 1 },
+ coverage: {
+ state: 'checked',
+ verdict: 'uncovered',
+ rule_version: 'governance-answer-substring-v1',
+ matched_text: '暂无已发布',
+ },
+}
+const fixturePage = {
+ items: [fixtureRecord],
+ columns: ['answer', 'coverage', 'asked_at', 'asker', 'question', 'trigger_person', 'feedback'],
+ total: 1,
+ has_more: false,
+ next_cursor: '',
+ as_of: '2026-10-14T04:00:00Z',
+}
+
+afterEach(() => vi.unstubAllGlobals())
+
+describe('QA operations data contract', () => {
+ it('keeps governance coverage separate from source coverage and downvotes', () => {
+ const item = parseQARecord(fixtureRecord)
+ expect(item.coverage.verdict).toBe('uncovered')
+ expect(item.source_coverage.verdict).toBe('covered')
+ expect(item.feedback.asker_value).toBe('down')
+ expect(parseQARecordPage(fixturePage).columns).not.toContain('department')
+ })
+ it('rejects malformed rows and pagination rather than rendering an empty success', () => {
+ expect(() => parseQARecord({ ...fixtureRecord, answer: null })).toThrow('响应无效')
+ expect(() => parseQARecordPage({ ...fixturePage, has_more: true })).toThrow('响应无效')
+ expect(() => parseQARecordPage({ ...fixturePage, columns: ['unapproved_secret_column'] })).toThrow('响应无效')
+ })
+ it('uses only the governance API and preserves keyword text', async () => {
+ const mocked = vi.fn().mockResolvedValue(new Response(JSON.stringify({ data: fixturePage }), { status: 200 }))
+ vi.stubGlobal('fetch', mocked)
+ await fetchQARecords({ start: '2026-10-14T00:00:00Z', end: '2026-10-15T00:00:00Z', keyword: '%_CR5', cursor: '' })
+ const url = String(mocked.mock.calls[0][0])
+ expect(url.startsWith('/api/v1/qa-ops/records?')).toBe(true)
+ expect(new URL(url, 'http://localhost').searchParams.get('keyword')).toBe('%_CR5')
+ expect(url).not.toContain('tenant')
+ })
+ it('surfaces source errors, never silently replacing them with no questions', async () => {
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn().mockResolvedValue(new Response(JSON.stringify({ error: '只读权限校验未通过' }), { status: 503 }))
+ )
+ await expect(fetchQARecords({ start: '', end: '', keyword: '', cursor: '' })).rejects.toThrow('只读权限校验未通过')
+ })
+})
diff --git a/web/src/qaOps.ts b/web/src/qaOps.ts
new file mode 100644
index 0000000..bf534c1
--- /dev/null
+++ b/web/src/qaOps.ts
@@ -0,0 +1,197 @@
+export const qaColumns = [
+ { key: 'question_chinese', label: '中文问题' },
+ { key: 'answer', label: 'AI答案' },
+ { key: 'coverage', label: '是否覆盖' },
+ { key: 'is_correct', label: '是否正确' },
+ { key: 'product_category', label: '产品分类' },
+ { key: 'problem_type', label: '问题类型' },
+ { key: 'root_cause', label: '根因分析' },
+ { key: 'asked_at', label: '提问时间' },
+ { key: 'asker', label: '提问人' },
+ { key: 'question', label: '原始问题' },
+ { key: 'language', label: '语言' },
+ { key: 'trigger_person', label: '流程触发人员信息' },
+ { key: 'department', label: '部门' },
+ { key: 'region', label: '区域' },
+ { key: 'feedback', label: '是否点赞' },
+] as const
+
+export type QAColumn = (typeof qaColumns)[number]['key']
+export interface QARecord {
+ id: string
+ status: string
+ question: string
+ answer: string
+ asked_at: string
+ time_source: string
+ asker: string
+ trigger_person: string
+ department: string
+ region: string
+ references: unknown
+ media: unknown
+ source_coverage: { verdict: string; reason_code: string; evaluator_version: string }
+ feedback: { asker_value: string; up: number; down: number }
+ coverage: { state: 'pending' | 'checked'; verdict?: 'uncovered'; rule_version: string; matched_text?: string }
+ question_chinese?: string
+ is_correct?: boolean | null
+ product_category?: string
+ problem_type?: string
+ root_cause?: string
+ language?: string
+}
+export interface QARecordPage {
+ items: QARecord[]
+ columns: QAColumn[]
+ total: number
+ has_more: boolean
+ next_cursor: string
+ as_of: string
+}
+export interface QAQuery {
+ start: string
+ end: string
+ keyword: string
+ cursor: string
+ limit?: number
+}
+export interface QAStatus {
+ state: 'disabled' | 'unavailable' | 'blocked' | 'connected'
+ code: string
+ warnings: string[]
+ read_only: true
+ source_version: '2.0'
+ channel: 'dingtalk'
+}
+
+const invalid = (): never => {
+ throw new Error('问答运营响应无效,请联系管理员检查接口契约')
+}
+const object = (value: unknown): Record => {
+ if (!value || typeof value !== 'object' || Array.isArray(value)) return invalid()
+ return value as Record
+}
+const text = (value: unknown): string => (typeof value === 'string' ? value : invalid())
+const count = (value: unknown): number =>
+ typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : invalid()
+const instant = (value: unknown): string => {
+ const result = text(value)
+ if (!result || Number.isNaN(Date.parse(result))) return invalid()
+ return result
+}
+const columnKeys = new Set(qaColumns.map(({ key }) => key))
+
+export function parseQARecord(value: unknown): QARecord {
+ const row = object(value)
+ const feedback = object(row.feedback)
+ const source = object(row.source_coverage)
+ const coverage = object(row.coverage)
+ if (coverage.state !== 'pending' && coverage.state !== 'checked') return invalid()
+ if (coverage.verdict !== undefined && coverage.verdict !== 'uncovered') return invalid()
+ if (coverage.state === 'checked' && coverage.verdict !== 'uncovered') return invalid()
+ const askerValue = text(feedback.asker_value)
+ if (!['', 'up', 'down'].includes(askerValue)) return invalid()
+ const item: QARecord = {
+ id: text(row.id),
+ status: text(row.status),
+ question: text(row.question),
+ answer: text(row.answer),
+ asked_at: instant(row.asked_at),
+ time_source: text(row.time_source),
+ asker: text(row.asker),
+ trigger_person: text(row.trigger_person),
+ department: text(row.department),
+ region: text(row.region),
+ references: row.references,
+ media: row.media,
+ source_coverage: {
+ verdict: text(source.verdict),
+ reason_code: text(source.reason_code),
+ evaluator_version: text(source.evaluator_version),
+ },
+ feedback: { asker_value: askerValue, up: count(feedback.up), down: count(feedback.down) },
+ coverage: { state: coverage.state, verdict: coverage.verdict, rule_version: text(coverage.rule_version) },
+ }
+ if (!item.id || !item.coverage.rule_version) return invalid()
+ if (coverage.matched_text !== undefined) item.coverage.matched_text = text(coverage.matched_text)
+ for (const key of ['question_chinese', 'product_category', 'problem_type', 'root_cause', 'language'] as const) {
+ if (row[key] !== undefined) item[key] = text(row[key])
+ }
+ if (row.is_correct !== undefined) {
+ if (typeof row.is_correct !== 'boolean' && row.is_correct !== null) return invalid()
+ item.is_correct = row.is_correct
+ }
+ return item
+}
+
+export function parseQARecordPage(value: unknown): QARecordPage {
+ const page = object(value)
+ if (!Array.isArray(page.items) || !Array.isArray(page.columns) || typeof page.has_more !== 'boolean') return invalid()
+ const items = page.items.map(parseQARecord)
+ const columns = page.columns.map((key) =>
+ typeof key === 'string' && columnKeys.has(key) ? (key as QAColumn) : invalid()
+ )
+ const total = count(page.total)
+ const nextCursor = text(page.next_cursor)
+ if (total < items.length || (page.has_more && (!items.length || !nextCursor)) || (!page.has_more && nextCursor))
+ return invalid()
+ if (new Set(items.map(({ id }) => id)).size !== items.length || new Set(columns).size !== columns.length)
+ return invalid()
+ return { items, columns, total, has_more: page.has_more, next_cursor: nextCursor, as_of: instant(page.as_of) }
+}
+
+async function getPayload(path: string, signal?: AbortSignal): Promise {
+ const response = await fetch(path, { credentials: 'same-origin', cache: 'no-store', signal })
+ const raw: unknown = await response.json().catch(() => null)
+ if (!response.ok) {
+ const payload = raw && typeof raw === 'object' ? (raw as Record) : null
+ throw new Error(typeof payload?.error === 'string' ? payload.error : `问答数据读取失败(HTTP ${response.status})`)
+ }
+ return object(raw).data
+}
+
+export async function fetchQARecords(query: QAQuery, signal?: AbortSignal): Promise {
+ const parameters = new URLSearchParams({
+ start: query.start,
+ end: query.end,
+ keyword: query.keyword,
+ cursor: query.cursor,
+ limit: String(query.limit ?? 20),
+ })
+ return parseQARecordPage(await getPayload(`/api/v1/qa-ops/records?${parameters}`, signal))
+}
+export async function fetchQARecord(id: string, signal?: AbortSignal): Promise {
+ return parseQARecord(await getPayload(`/api/v1/qa-ops/records/${encodeURIComponent(id)}`, signal))
+}
+export async function fetchQAStatus(signal?: AbortSignal): Promise {
+ const value = object(await getPayload('/api/v1/qa-ops/status', signal))
+ if (
+ !['disabled', 'unavailable', 'blocked', 'connected'].includes(text(value.state)) ||
+ !Array.isArray(value.warnings) ||
+ value.read_only !== true ||
+ value.source_version !== '2.0' ||
+ value.channel !== 'dingtalk'
+ )
+ return invalid()
+ return {
+ state: value.state as QAStatus['state'],
+ code: text(value.code),
+ warnings: value.warnings.map(text),
+ read_only: true,
+ source_version: '2.0',
+ channel: 'dingtalk',
+ }
+}
+
+export function qaCellValue(item: QARecord, column: QAColumn): string | null {
+ if (column === 'coverage') return item.coverage.verdict === 'uncovered' ? '否' : null
+ if (column === 'is_correct') return typeof item.is_correct === 'boolean' ? (item.is_correct ? '是' : '否') : null
+ if (column === 'feedback') {
+ if (item.feedback.asker_value === 'up') return '是'
+ if (item.feedback.asker_value === 'down') return '否(点踩)'
+ if (item.feedback.up || item.feedback.down) return `其他人:赞 ${item.feedback.up} / 踩 ${item.feedback.down}`
+ return null
+ }
+ if (column === 'asked_at') return new Date(item.asked_at).toLocaleString('zh-CN', { hour12: false })
+ return item[column] || null
+}
diff --git a/web/src/workspace.ts b/web/src/workspace.ts
index a8c9320..66f4205 100644
--- a/web/src/workspace.ts
+++ b/web/src/workspace.ts
@@ -1,11 +1,11 @@
-export type ModuleId = 'dashboard' | 'sources' | 'knowledge' | 'tasks' | 'releases' | 'settings' | 'versions'
+export type ModuleId = 'dashboard' | 'sources' | 'knowledge' | 'tasks' | 'releases' | 'settings' | 'versions' | 'qaops'
export interface WorkspaceState {
openTabs: ModuleId[]
activeTab: ModuleId
}
-const moduleIds = new Set(['dashboard', 'tasks', 'releases', 'settings'])
+const moduleIds = new Set(['dashboard', 'tasks', 'releases', 'settings', 'qaops'])
export const initialWorkspace: WorkspaceState = {
openTabs: ['dashboard'],
--
2.52.0
From dab74b706b5b87da3ecb71a8e0f6b6caa5fba4ad Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Sat, 17 Oct 2026 11:39:38 +0800
Subject: [PATCH 02/14] =?UTF-8?q?feat(qaops):=20=E5=A2=9E=E5=8A=A0?=
=?UTF-8?q?=E7=89=88=E6=9C=AC=E5=8C=96=E9=83=A8=E9=97=A8=E5=8C=BA=E5=9F=9F?=
=?UTF-8?q?=E5=BD=92=E5=B1=9E=E9=85=8D=E7=BD=AE=E4=B8=8E=E9=A2=84=E8=A7=88?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
CHANGELOG.md | 2 +
api/openapi.yaml | 51 ++++
cmd/api/main.go | 2 +
cmd/qa-org-import/main.go | 62 +++++
cmd/qa-org-import/main_test.go | 31 +++
internal/httpapi/qa_org.go | 81 ++++++
internal/httpapi/qa_org_proxy_test.go | 33 +++
internal/httpapi/qa_org_test.go | 82 ++++++
internal/httpapi/server.go | 4 +
.../000048_qa_ops_organization.down.sql | 3 +
.../000048_qa_ops_organization.up.sql | 26 ++
internal/platform/postgres/migrations_test.go | 4 +-
internal/qaopsorg/regions.go | 147 +++++++++++
internal/qaopsorg/regions_test.go | 86 ++++++
internal/qaopsorg/store.go | 214 +++++++++++++++
internal/qaopsorg/store_integration_test.go | 146 +++++++++++
scripts/test-scope.json | 5 +
web/src/QAOperations.tsx | 114 ++++----
web/src/QARegions.test.tsx | 66 +++++
web/src/QARegions.tsx | 246 ++++++++++++++++++
web/src/qaOrg.test.ts | 63 +++++
web/src/qaOrg.ts | 152 +++++++++++
web/src/qaRegions.css | 124 +++++++++
23 files changed, 1693 insertions(+), 51 deletions(-)
create mode 100644 cmd/qa-org-import/main.go
create mode 100644 cmd/qa-org-import/main_test.go
create mode 100644 internal/httpapi/qa_org.go
create mode 100644 internal/httpapi/qa_org_proxy_test.go
create mode 100644 internal/httpapi/qa_org_test.go
create mode 100644 internal/platform/postgres/migrations/000048_qa_ops_organization.down.sql
create mode 100644 internal/platform/postgres/migrations/000048_qa_ops_organization.up.sql
create mode 100644 internal/qaopsorg/regions.go
create mode 100644 internal/qaopsorg/regions_test.go
create mode 100644 internal/qaopsorg/store.go
create mode 100644 internal/qaopsorg/store_integration_test.go
create mode 100644 web/src/QARegions.test.tsx
create mode 100644 web/src/QARegions.tsx
create mode 100644 web/src/qaOrg.test.ts
create mode 100644 web/src/qaOrg.ts
create mode 100644 web/src/qaRegions.css
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e483972..aae8383 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,8 @@
### Added
+- **「问答运营 → 区域使用」区域归属配置切片**:按稳定部门 ID 搜索和勾选完整路径,预览去重归属人数,保存版本后重新读取;父部门包含子部门、子部门显式配置优先,多部门跨区域人员单独待核对。预览不写入,过期版本和不完整部门树被阻断。当前不是实时通讯录同步或使用/绩效统计验收,翻译及 AI 评估模型接入按用户要求暂缓。
+- 新增治理侧组织快照与区域修订迁移、受确认保护的后台导入命令;不修改 DobotAI 原表或钉钉组织结构。
- **「问答运营 → 问答记录」首个开发切片**:在现有导航中查看 DobotAI 2.0 钉钉问答,支持半开时间范围、原问题关键词、稳定游标分页和完整详情;按整个筛选结果隐藏空列,反馈聚合不放大问答条数。外语翻译、AI 评估、人员区域映射尚未接入,不标为第一阶段完成。
- 治理侧重新检查答案:包含 `暂无已发布` 即未覆盖,引用和源端 covered 不能抵消;未命中仍待评估,源端规则单独保留作对照。独立只读源默认关闭、租户后端固定、管理员会话鉴权,源故障不回退治理主库;安全告警明确保留 TEMP/TLS 尚未整改状态。
- **「版本记录」页**(一级入口):只读时间线追踪**远端 main 可达的全部提交**(含合并提交与已并入 main 的侧分支提交),按提交时间倒序显示标题/正文、`[正式版本] / [开发版本] / [历史提交]` 徽标、短 SHA、提交内变更记录与 `[查看提交]`/`[查看 tag]`;支持「全部 / 正式 / 开发 / 历史」筛选与游标翻页,窄屏单列。
diff --git a/api/openapi.yaml b/api/openapi.yaml
index 8a94b6f..66cfbdc 100644
--- a/api/openapi.yaml
+++ b/api/openapi.yaml
@@ -44,6 +44,57 @@
}
],
"paths": {
+ "/api/v1/qa-ops/organization": {
+ "get": {
+ "tags": ["QA operations"],
+ "operationId": "getQAOrganization",
+ "summary": "管理员读取服务器固定租户的完整部门路径、已保存区域归属与快照时间,不返回人员名单",
+ "responses": {
+ "200": {"$ref": "#/components/responses/Envelope"},
+ "400": {"$ref": "#/components/responses/BadRequest"},
+ "401": {"description": "需要登录"},
+ "403": {"description": "仅管理员可访问"},
+ "500": {"$ref": "#/components/responses/InternalError"},
+ "503": {"description": "治理侧组织存储不可用"}
+ }
+ }
+ },
+ "/api/v1/qa-ops/organization/preview": {
+ "post": {
+ "tags": ["QA operations"],
+ "operationId": "previewQAOrganizationRegions",
+ "summary": "预览当前通讯录版本下的父子部门区域归属和去重人数,不保存修改",
+ "parameters": [{"name":"X-Governance-Action","in":"header","required":true,"schema":{"const":"qa-organization"}}],
+ "requestBody": {"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["directory_id","base_revision","rules"],"properties":{"directory_id":{"type":"string"},"base_revision":{"type":"string"},"rules":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["department_id","region"],"properties":{"department_id":{"type":"string"},"region":{"enum":["国内工业","APAC","EMEA","America"]}}}}}}}}},
+ "responses": {
+ "200": {"$ref": "#/components/responses/Envelope"},
+ "400": {"$ref": "#/components/responses/BadRequest"},
+ "401": {"description": "需要登录"},
+ "403": {"description": "仅管理员同源操作可访问"},
+ "409": {"description": "通讯录或配置版本已变化,需重新读取"},
+ "500": {"$ref": "#/components/responses/InternalError"},
+ "503": {"description": "治理侧组织存储不可用"}
+ }
+ }
+ },
+ "/api/v1/qa-ops/organization/regions": {
+ "put": {
+ "tags": ["QA operations"],
+ "operationId": "saveQAOrganizationRegions",
+ "summary": "保存版本化区域配置;操作人取管理员会话,不改变钉钉或DobotAI数据",
+ "parameters": [{"name":"X-Governance-Action","in":"header","required":true,"schema":{"const":"qa-organization"}}],
+ "requestBody": {"$ref":"#/paths/~1api~1v1~1qa-ops~1organization~1preview/post/requestBody"},
+ "responses": {
+ "200": {"$ref": "#/components/responses/Envelope"},
+ "400": {"$ref": "#/components/responses/BadRequest"},
+ "401": {"description": "需要登录"},
+ "403": {"description": "仅管理员同源操作可访问"},
+ "409": {"description": "版本冲突或尚无完整通讯录"},
+ "500": {"$ref": "#/components/responses/InternalError"},
+ "503": {"description": "治理侧组织存储不可用"}
+ }
+ }
+ },
"/api/v1/qa-ops/status": {
"get": {
"tags": ["QA operations"],
diff --git a/cmd/api/main.go b/cmd/api/main.go
index bd497bc..032855f 100644
--- a/cmd/api/main.go
+++ b/cmd/api/main.go
@@ -20,6 +20,7 @@ import (
"knowledge-governance/internal/monitoring"
postgresstore "knowledge-governance/internal/platform/postgres"
"knowledge-governance/internal/platform/weknora"
+ "knowledge-governance/internal/qaopsorg"
"knowledge-governance/internal/serviceverify"
)
@@ -133,6 +134,7 @@ func run(ctx context.Context, getenv func(string) string) error {
log.Print("QA operations source is unavailable; governance remains online")
}
handler, err := httpapi.NewHandler(httpapi.Config{
+ QAOrg: qaopsorg.NewStore(pool, getenv("DOBOTAI_OPS_TENANT_KEY")),
QAOps: qaReader,
QAOpsTenantKey: qaSettings.TenantKey,
QAOpsEnabled: qaSettings.Enabled,
diff --git a/cmd/qa-org-import/main.go b/cmd/qa-org-import/main.go
new file mode 100644
index 0000000..2630334
--- /dev/null
+++ b/cmd/qa-org-import/main.go
@@ -0,0 +1,62 @@
+package main
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "io"
+ "os"
+ "time"
+
+ "github.com/jackc/pgx/v5/pgxpool"
+ "knowledge-governance/internal/qaopsorg"
+)
+
+func main() {
+ if err := run(os.Args[1:], os.Getenv, os.Stdout); err != nil {
+ fmt.Fprintln(os.Stderr, "directory import failed; check private input and governance connection (details withheld)")
+ os.Exit(1)
+ }
+}
+
+func run(args []string, getenv func(string) string, out io.Writer) error {
+ if len(args) != 1 || getenv("QAOPS_CONFIRM_DIRECTORY_IMPORT") != "import-governance-directory" || getenv("DOBOTAI_OPS_TENANT_KEY") == "" || getenv("DATABASE_URL") == "" {
+ return errors.New("explicit input, tenant, governance database and confirmation required")
+ }
+ info, err := os.Lstat(args[0])
+ if err != nil || !info.Mode().IsRegular() || info.Mode().Perm()&0077 != 0 || info.Size() > 16<<20 {
+ return errors.New("input must be a private regular JSON file")
+ }
+ file, err := os.Open(args[0])
+ if err != nil {
+ return errors.New("input unavailable")
+ }
+ defer file.Close()
+ decoder := json.NewDecoder(io.LimitReader(file, (16<<20)+1))
+ decoder.DisallowUnknownFields()
+ var input qaopsorg.Import
+ if decoder.Decode(&input) != nil || decoder.Decode(&struct{}{}) != io.EOF {
+ return errors.New("input invalid")
+ }
+ if !input.Complete {
+ return qaopsorg.ErrInvalid
+ }
+ ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+ defer cancel()
+ pool, err := pgxpool.New(ctx, getenv("DATABASE_URL"))
+ if err != nil {
+ return qaopsorg.ErrUnavailable
+ }
+ defer pool.Close()
+ store := qaopsorg.NewStore(pool, getenv("DOBOTAI_OPS_TENANT_KEY"))
+ saved, err := store.ReplaceDirectory(ctx, input)
+ if err != nil {
+ return err
+ }
+ active, err := store.GetView(ctx)
+ if err != nil || active.DirectoryID != saved.DirectoryID {
+ return qaopsorg.ErrConflict
+ }
+ return json.NewEncoder(out).Encode(map[string]any{"directory_id": active.DirectoryID, "source": active.DirectorySource, "synced_at": active.DirectorySyncedAt, "departments": len(active.View.Departments), "people": active.View.TotalPeople, "readback_verified": true})
+}
diff --git a/cmd/qa-org-import/main_test.go b/cmd/qa-org-import/main_test.go
new file mode 100644
index 0000000..820a5fc
--- /dev/null
+++ b/cmd/qa-org-import/main_test.go
@@ -0,0 +1,31 @@
+package main
+
+import (
+ "bytes"
+ "os"
+ "path/filepath"
+ "testing"
+)
+
+func TestDirectoryImportRequiresExplicitGovernanceConfirmationAndPrivateInput(t *testing.T) {
+ var output bytes.Buffer
+ if run(nil, func(string) string { return "" }, &output) == nil || output.Len() != 0 {
+ t.Fatal("unconfigured importer must not connect or report success")
+ }
+ path := filepath.Join(t.TempDir(), "directory.json")
+ if os.WriteFile(path, []byte(`{"complete":false}`), 0644) != nil {
+ t.Fatal("fixture creation failed")
+ }
+ env := func(k string) string {
+ return map[string]string{"QAOPS_CONFIRM_DIRECTORY_IMPORT": "import-governance-directory", "DOBOTAI_OPS_TENANT_KEY": "fixture", "DATABASE_URL": "postgres://invalid.invalid/no_connection_expected"}[k]
+ }
+ if run([]string{path}, env, &output) == nil {
+ t.Fatal("public personnel input accepted")
+ }
+ if os.Chmod(path, 0600) != nil {
+ t.Fatal("fixture chmod failed")
+ }
+ if run([]string{path}, env, &output) == nil || output.Len() != 0 {
+ t.Fatal("partial sync accepted or importer reported fabricated success")
+ }
+}
diff --git a/internal/httpapi/qa_org.go b/internal/httpapi/qa_org.go
new file mode 100644
index 0000000..aed634c
--- /dev/null
+++ b/internal/httpapi/qa_org.go
@@ -0,0 +1,81 @@
+package httpapi
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "io"
+ "knowledge-governance/internal/qaopsorg"
+ "net/http"
+ "net/url"
+)
+
+type QAOrgStore interface {
+ GetView(context.Context) (qaopsorg.State, error)
+ PreviewRules(context.Context, qaopsorg.SaveRequest) (qaopsorg.State, error)
+ SaveRules(context.Context, qaopsorg.SaveRequest, string) (qaopsorg.State, error)
+}
+
+func qaOrganization(w http.ResponseWriter, r *http.Request, config Config) {
+ if !authorizeQAOps(w, r) {
+ return
+ }
+ if r.URL.RawQuery != "" {
+ writeOrgError(w, qaopsorg.ErrInvalid)
+ return
+ }
+ if config.QAOrg == nil {
+ writeOrgError(w, qaopsorg.ErrUnavailable)
+ return
+ }
+ var result qaopsorg.State
+ var err error
+ if r.Method == http.MethodGet {
+ result, err = config.QAOrg.GetView(r.Context())
+ } else {
+ if r.Header.Get("X-Governance-Action") != "qa-organization" || r.Header.Get("Sec-Fetch-Site") == "cross-site" {
+ writeJSON(w, 403, map[string]string{"error": "区域配置需要同源操作意图"})
+ return
+ }
+ // A same-origin browser request can pass a reverse proxy that rewrites
+ // Host. Fetch Metadata is browser-controlled; keep the explicit action
+ // header and reject cross-site requests without trusting forwarded hosts.
+ if raw := r.Header.Get("Origin"); raw != "" && r.Header.Get("Sec-Fetch-Site") != "same-origin" {
+ origin, parseErr := url.Parse(raw)
+ if parseErr != nil || (origin.Scheme != "http" && origin.Scheme != "https") || origin.Host != r.Host {
+ writeJSON(w, 403, map[string]string{"error": "拒绝跨站配置请求"})
+ return
+ }
+ }
+ var request qaopsorg.SaveRequest
+ decoder := json.NewDecoder(http.MaxBytesReader(w, r.Body, 1<<20))
+ decoder.DisallowUnknownFields()
+ if decoder.Decode(&request) != nil || decoder.Decode(&struct{}{}) != io.EOF || request.DirectoryID == "" || request.Rules == nil {
+ writeOrgError(w, qaopsorg.ErrInvalid)
+ return
+ }
+ if r.Method == http.MethodPost {
+ result, err = config.QAOrg.PreviewRules(r.Context(), request)
+ } else {
+ identity, _ := sessionFrom(r.Context())
+ result, err = config.QAOrg.SaveRules(r.Context(), request, identity.Username)
+ }
+ }
+ if err != nil {
+ writeOrgError(w, err)
+ return
+ }
+ writeJSON(w, 200, map[string]any{"data": result})
+}
+func writeOrgError(w http.ResponseWriter, err error) {
+ status, message := 503, "通讯录或区域配置存储不可用,未展示为空数据"
+ switch {
+ case errors.Is(err, qaopsorg.ErrInvalid):
+ status, message = 400, "部门树或区域配置无效,请核对重复、缺失路径及区域"
+ case errors.Is(err, qaopsorg.ErrConflict):
+ status, message = 409, "通讯录或区域配置已变化,请重新读取后预览"
+ case errors.Is(err, qaopsorg.ErrNoDirectory):
+ status, message = 409, "尚无完整通讯录快照,不能保存区域配置"
+ }
+ writeJSON(w, status, map[string]string{"error": message})
+}
diff --git a/internal/httpapi/qa_org_proxy_test.go b/internal/httpapi/qa_org_proxy_test.go
new file mode 100644
index 0000000..01924c7
--- /dev/null
+++ b/internal/httpapi/qa_org_proxy_test.go
@@ -0,0 +1,33 @@
+package httpapi
+
+import (
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+)
+
+func TestQAOrganizationSameOriginThroughReverseProxy(t *testing.T) {
+ auth := newFakeAuthStore()
+ auth.sessions["org-proxy-admin"] = "usr-boss"
+ spy := &orgSpy{}
+ handler, err := NewHandler(Config{Store: &fakeJobStore{}, QAOrg: spy, Auth: &AuthConfig{Store: auth}})
+ if err != nil {
+ t.Fatal(err)
+ }
+ for _, tc := range []struct {
+ site string
+ status int
+ }{{"same-origin", 200}, {"cross-site", 403}, {"same-site", 403}} {
+ req := httptest.NewRequest("PUT", "http://internal-api:8080/api/v1/qa-ops/organization/regions", strings.NewReader(`{"directory_id":"d","base_revision":"","rules":[]}`))
+ req.AddCookie(&http.Cookie{Name: sessionCookieName, Value: "org-proxy-admin"})
+ req.Header.Set("X-Governance-Action", "qa-organization")
+ req.Header.Set("Origin", "http://frontend:8088")
+ req.Header.Set("Sec-Fetch-Site", tc.site)
+ res := httptest.NewRecorder()
+ handler.ServeHTTP(res, req)
+ if res.Code != tc.status {
+ t.Fatalf("proxy fetch site %s got %d want %d", tc.site, res.Code, tc.status)
+ }
+ }
+}
diff --git a/internal/httpapi/qa_org_test.go b/internal/httpapi/qa_org_test.go
new file mode 100644
index 0000000..882c9be
--- /dev/null
+++ b/internal/httpapi/qa_org_test.go
@@ -0,0 +1,82 @@
+package httpapi
+
+import (
+ "context"
+ "knowledge-governance/internal/qaopsorg"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+)
+
+type orgSpy struct {
+ calls int
+ actor string
+ err error
+}
+
+func (s *orgSpy) GetView(context.Context) (qaopsorg.State, error) {
+ s.calls++
+ return qaopsorg.State{State: "empty"}, s.err
+}
+func (s *orgSpy) PreviewRules(context.Context, qaopsorg.SaveRequest) (qaopsorg.State, error) {
+ s.calls++
+ return qaopsorg.State{}, s.err
+}
+func (s *orgSpy) SaveRules(_ context.Context, _ qaopsorg.SaveRequest, actor string) (qaopsorg.State, error) {
+ s.calls++
+ s.actor = actor
+ return qaopsorg.State{}, s.err
+}
+func TestQAOrganizationGuardsIdentityIntentAndErrors(t *testing.T) {
+ spy := &orgSpy{}
+ auth := newFakeAuthStore()
+ auth.sessions["org-admin"] = "usr-boss"
+ auth.sessions["org-viewer"] = "usr-eye"
+ handler, err := NewHandler(Config{Store: &fakeJobStore{}, QAOrg: spy, Auth: &AuthConfig{Store: auth}})
+ if err != nil {
+ t.Fatal(err)
+ }
+ base := "/api/v1/qa-ops/organization"
+ for _, tc := range []struct {
+ method, path, token, action, origin, body string
+ status int
+ }{
+ {"GET", base, "", "", "", "", 401},
+ {"GET", base, "org-viewer", "", "", "", 403},
+ {"GET", base, "org-admin", "", "", "", 200},
+ {"GET", base + "?tenant=another", "org-admin", "", "", "", 400},
+ {"PUT", base + "/regions", "org-admin", "", "", "{}", 403},
+ {"PUT", base + "/regions", "org-admin", "qa-organization", "https://untrusted.invalid", "{}", 403},
+ {"PUT", base + "/regions", "org-admin", "qa-organization", "", `{"updated_by":"forged"}`, 400},
+ {"PUT", base + "/regions", "org-admin", "qa-organization", "", `{} {}`, 400},
+ {"PUT", base + "/regions", "org-admin", "qa-organization", "", `{}`, 400},
+ {"PUT", base + "/regions", "org-admin", "qa-organization", "", `{"directory_id":"d","base_revision":"","rules":null}`, 400},
+ {"PUT", base + "/regions", "org-admin", "qa-organization", "", `{"directory_id":"d","base_revision":"","rules":[]}`, 200},
+ {"POST", base + "/preview", "org-admin", "qa-organization", "", `{"directory_id":"d","base_revision":"","rules":[]}`, 200},
+ } {
+ req := httptest.NewRequest(tc.method, tc.path, strings.NewReader(tc.body))
+ if tc.token != "" {
+ req.AddCookie(&http.Cookie{Name: sessionCookieName, Value: tc.token})
+ }
+ req.Header.Set("X-Governance-Action", tc.action)
+ req.Header.Set("Origin", tc.origin)
+ res := httptest.NewRecorder()
+ handler.ServeHTTP(res, req)
+ if res.Code != tc.status {
+ t.Fatalf("%s %s got %d want %d: %s", tc.method, tc.path, res.Code, tc.status, res.Body.String())
+ }
+ }
+ if spy.calls != 3 || spy.actor == "" || spy.actor == "forged" {
+ t.Fatalf("invalid requests reached store or actor not stamped: %+v", spy)
+ }
+ spy.err = qaopsorg.ErrConflict
+ req := httptest.NewRequest("PUT", base+"/regions", strings.NewReader(`{"directory_id":"d","base_revision":"","rules":[]}`))
+ req.AddCookie(&http.Cookie{Name: sessionCookieName, Value: "org-admin"})
+ req.Header.Set("X-Governance-Action", "qa-organization")
+ res := httptest.NewRecorder()
+ handler.ServeHTTP(res, req)
+ if res.Code != 409 {
+ t.Fatal("stale configuration not reported as conflict")
+ }
+}
diff --git a/internal/httpapi/server.go b/internal/httpapi/server.go
index 2c1c1b3..df5c2d9 100644
--- a/internal/httpapi/server.go
+++ b/internal/httpapi/server.go
@@ -101,6 +101,7 @@ type Store interface {
}
type Config struct {
+ QAOrg QAOrgStore
QAOps QAOpsReader
QAOpsTenantKey string
QAOpsEnabled bool
@@ -171,6 +172,9 @@ func NewHandler(config Config) (http.Handler, error) {
config.NewID = newID
}
mux := http.NewServeMux()
+ mux.HandleFunc("GET /api/v1/qa-ops/organization", func(w http.ResponseWriter, r *http.Request) { qaOrganization(w, r, config) })
+ mux.HandleFunc("POST /api/v1/qa-ops/organization/preview", func(w http.ResponseWriter, r *http.Request) { qaOrganization(w, r, config) })
+ mux.HandleFunc("PUT /api/v1/qa-ops/organization/regions", func(w http.ResponseWriter, r *http.Request) { qaOrganization(w, r, config) })
mux.HandleFunc("GET /api/v1/qa-ops/status", func(w http.ResponseWriter, r *http.Request) {
qaOpsStatus(w, r, config)
})
diff --git a/internal/platform/postgres/migrations/000048_qa_ops_organization.down.sql b/internal/platform/postgres/migrations/000048_qa_ops_organization.down.sql
new file mode 100644
index 0000000..031a50b
--- /dev/null
+++ b/internal/platform/postgres/migrations/000048_qa_ops_organization.down.sql
@@ -0,0 +1,3 @@
+DROP TABLE IF EXISTS qa_ops_organization_state;
+DROP TABLE IF EXISTS qa_ops_region_revisions;
+DROP TABLE IF EXISTS qa_ops_directory_snapshots;
diff --git a/internal/platform/postgres/migrations/000048_qa_ops_organization.up.sql b/internal/platform/postgres/migrations/000048_qa_ops_organization.up.sql
new file mode 100644
index 0000000..f7b665c
--- /dev/null
+++ b/internal/platform/postgres/migrations/000048_qa_ops_organization.up.sql
@@ -0,0 +1,26 @@
+CREATE TABLE qa_ops_directory_snapshots (
+ tenant_key TEXT NOT NULL,
+ id TEXT NOT NULL,
+ source TEXT NOT NULL CHECK (source IN ('weekly_report_snapshot','weekly_report_live')),
+ synced_at TIMESTAMPTZ NOT NULL,
+ imported_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ payload JSONB NOT NULL CHECK (jsonb_typeof(payload)='object'),
+ PRIMARY KEY (tenant_key,id)
+);
+CREATE TABLE qa_ops_region_revisions (
+ tenant_key TEXT NOT NULL,
+ id TEXT NOT NULL,
+ directory_id TEXT NOT NULL,
+ rules JSONB NOT NULL CHECK (jsonb_typeof(rules)='array'),
+ updated_by TEXT NOT NULL,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ PRIMARY KEY (tenant_key,id),
+ FOREIGN KEY (tenant_key,directory_id) REFERENCES qa_ops_directory_snapshots(tenant_key,id)
+);
+CREATE TABLE qa_ops_organization_state (
+ tenant_key TEXT PRIMARY KEY,
+ directory_id TEXT NOT NULL,
+ revision_id TEXT,
+ FOREIGN KEY (tenant_key,directory_id) REFERENCES qa_ops_directory_snapshots(tenant_key,id),
+ FOREIGN KEY (tenant_key,revision_id) REFERENCES qa_ops_region_revisions(tenant_key,id)
+);
diff --git a/internal/platform/postgres/migrations_test.go b/internal/platform/postgres/migrations_test.go
index 404baab..deae533 100644
--- a/internal/platform/postgres/migrations_test.go
+++ b/internal/platform/postgres/migrations_test.go
@@ -11,8 +11,8 @@ func TestEmbeddedMigrationsAreVersionSorted(t *testing.T) {
if err != nil {
t.Fatalf("loadMigrations() error = %v", err)
}
- if len(migrations) != 47 {
- t.Fatalf("migration count = %d, want 47", len(migrations))
+ if len(migrations) != 48 {
+ t.Fatalf("migration count = %d, want 48", len(migrations))
}
if migrations[0].Version != 1 || !strings.Contains(migrations[0].UpSQL, "CREATE TABLE IF NOT EXISTS jobs") {
t.Fatalf("migration 1 = %#v", migrations[0])
diff --git a/internal/qaopsorg/regions.go b/internal/qaopsorg/regions.go
new file mode 100644
index 0000000..f275de9
--- /dev/null
+++ b/internal/qaopsorg/regions.go
@@ -0,0 +1,147 @@
+package qaopsorg
+
+import (
+ "errors"
+ "sort"
+ "strings"
+)
+
+var ErrInvalid = errors.New("invalid organization data or region rules")
+var RegionNames = []string{"国内工业", "APAC", "EMEA", "America"}
+
+type Department struct {
+ ID string `json:"id"`
+ ParentID string `json:"parent_id"`
+ Name string `json:"name"`
+}
+type Person struct {
+ ID string `json:"id"`
+ UnionID string `json:"union_id,omitempty"`
+ DepartmentIDs []string `json:"department_ids"`
+}
+type Directory struct {
+ Departments []Department `json:"departments"`
+ People []Person `json:"people"`
+}
+type Rule struct {
+ DepartmentID string `json:"department_id"`
+ Region string `json:"region"`
+}
+type DepartmentView struct {
+ Department
+ Path string `json:"path"`
+ Region string `json:"region"`
+ Explicit bool `json:"explicit"`
+ InheritedFrom string `json:"inherited_from"`
+}
+type PreviewResult struct {
+ Departments []DepartmentView `json:"departments"`
+ Regions map[string]int `json:"regions"`
+ TotalPeople int `json:"total_people"`
+ UnassignedPeople int `json:"unassigned_people"`
+ ConflictingPeople int `json:"conflicting_people"`
+ MissingDepartments []string `json:"missing_departments"`
+}
+
+// Identity is department ID. Names and legacy keyword rules never decide ownership.
+func Preview(directory Directory, rules []Rule) (PreviewResult, error) {
+ result := PreviewResult{Departments: []DepartmentView{}, Regions: map[string]int{}, MissingDepartments: []string{}, TotalPeople: len(directory.People)}
+ if len(directory.Departments) == 0 || len(directory.Departments) > 20000 || len(directory.People) == 0 || len(directory.People) > 100000 || len(rules) > 20000 {
+ return result, ErrInvalid
+ }
+ for _, region := range RegionNames {
+ result.Regions[region] = 0
+ }
+ departments := make(map[string]Department, len(directory.Departments))
+ for _, d := range directory.Departments {
+ if !validID(d.ID) || d.Name == "" || len(d.Name) > 1000 || strings.ContainsRune(d.Name, 0) {
+ return result, ErrInvalid
+ }
+ if _, ok := departments[d.ID]; ok {
+ return result, ErrInvalid
+ }
+ departments[d.ID] = d
+ }
+ direct := map[string]string{}
+ for _, rule := range rules {
+ if !validID(rule.DepartmentID) {
+ return result, ErrInvalid
+ }
+ if _, ok := result.Regions[rule.Region]; !ok {
+ return result, ErrInvalid
+ }
+ if _, ok := direct[rule.DepartmentID]; ok {
+ return result, ErrInvalid
+ }
+ direct[rule.DepartmentID] = rule.Region
+ if _, ok := departments[rule.DepartmentID]; !ok {
+ result.MissingDepartments = append(result.MissingDepartments, rule.DepartmentID)
+ }
+ }
+ resolved := map[string]DepartmentView{}
+ for _, d := range directory.Departments {
+ seen := map[string]bool{}
+ chain := []string{}
+ region, from := "", ""
+ for cur := d.ID; cur != ""; {
+ node, ok := departments[cur]
+ if !ok || seen[cur] || len(chain) > 100 {
+ return result, ErrInvalid
+ }
+ seen[cur] = true
+ chain = append(chain, node.Name)
+ if region == "" && direct[cur] != "" {
+ region, from = direct[cur], cur
+ }
+ cur = node.ParentID
+ }
+ for left, right := 0, len(chain)-1; left < right; left, right = left+1, right-1 {
+ chain[left], chain[right] = chain[right], chain[left]
+ }
+ view := DepartmentView{Department: d, Path: strings.Join(chain, "/"), Region: region, Explicit: direct[d.ID] != ""}
+ if from != d.ID {
+ view.InheritedFrom = from
+ }
+ resolved[d.ID] = view
+ result.Departments = append(result.Departments, view)
+ }
+ people := map[string]bool{}
+ for _, person := range directory.People {
+ if !validID(person.ID) || people[person.ID] || len(person.DepartmentIDs) > 1000 {
+ return result, ErrInvalid
+ }
+ people[person.ID] = true
+ regions := map[string]bool{}
+ for _, id := range person.DepartmentIDs {
+ department, ok := resolved[id]
+ if !ok {
+ return result, ErrInvalid
+ }
+ if department.Region != "" {
+ regions[department.Region] = true
+ }
+ }
+ switch len(regions) {
+ case 0:
+ result.UnassignedPeople++
+ case 1:
+ for region := range regions {
+ result.Regions[region]++
+ }
+ default:
+ result.ConflictingPeople++
+ }
+ }
+ sort.Slice(result.Departments, func(i, j int) bool {
+ a, b := result.Departments[i], result.Departments[j]
+ if a.Path == b.Path {
+ return a.ID < b.ID
+ }
+ return a.Path < b.Path
+ })
+ sort.Strings(result.MissingDepartments)
+ return result, nil
+}
+func validID(value string) bool {
+ return value != "" && len(value) <= 256 && strings.TrimSpace(value) == value && !strings.ContainsAny(value, "\x00\r\n")
+}
diff --git a/internal/qaopsorg/regions_test.go b/internal/qaopsorg/regions_test.go
new file mode 100644
index 0000000..bba0536
--- /dev/null
+++ b/internal/qaopsorg/regions_test.go
@@ -0,0 +1,86 @@
+package qaopsorg
+
+import (
+ "errors"
+ "testing"
+)
+
+func exampleDirectory() Directory {
+ return Directory{Departments: []Department{
+ {ID: "root", Name: "示例公司"},
+ {ID: "sales", ParentID: "root", Name: "销售"},
+ {ID: "apac", ParentID: "sales", Name: "业务组"},
+ {ID: "leaf", ParentID: "apac", Name: "支持"},
+ {ID: "other", ParentID: "root", Name: "业务组"},
+ }, People: []Person{
+ {ID: "p1", DepartmentIDs: []string{"sales"}},
+ {ID: "p2", DepartmentIDs: []string{"leaf"}},
+ {ID: "p3", DepartmentIDs: []string{"sales", "leaf"}},
+ {ID: "p4", DepartmentIDs: []string{"other"}},
+ }}
+}
+
+func TestRegionPreviewUsesNearestExplicitAncestorAndCountsPeopleOnce(t *testing.T) {
+ view, err := Preview(exampleDirectory(), []Rule{{DepartmentID: "sales", Region: "国内工业"}, {DepartmentID: "apac", Region: "APAC"}})
+ if err != nil {
+ t.Fatal(err)
+ }
+ byID := map[string]DepartmentView{}
+ for _, d := range view.Departments {
+ byID[d.ID] = d
+ }
+ if got := byID["leaf"]; got.Region != "APAC" || got.InheritedFrom != "apac" || got.Path != "示例公司/销售/业务组/支持" {
+ t.Fatalf("wrong child inheritance: %+v", got)
+ }
+ if !byID["apac"].Explicit || byID["other"].Region != "" {
+ t.Fatal("explicit choice or unmapped department lost")
+ }
+ if view.Regions["国内工业"] != 1 || view.Regions["APAC"] != 1 || view.UnassignedPeople != 1 || view.ConflictingPeople != 1 || view.TotalPeople != 4 {
+ t.Fatalf("person duplicated or conflict silently resolved: %+v", view)
+ }
+}
+
+func TestRegionPreviewRejectsBrokenDirectoryAndDuplicateAssignments(t *testing.T) {
+ cases := []struct {
+ name string
+ mutate func(*Directory)
+ rules []Rule
+ }{
+ {name: "cycle", mutate: func(d *Directory) { d.Departments[0].ParentID = "leaf" }},
+ {name: "missing parent", mutate: func(d *Directory) { d.Departments[1].ParentID = "absent" }},
+ {name: "duplicate department", mutate: func(d *Directory) { d.Departments = append(d.Departments, d.Departments[0]) }},
+ {name: "duplicate person", mutate: func(d *Directory) { d.People = append(d.People, d.People[0]) }},
+ {name: "missing membership", mutate: func(d *Directory) { d.People[0].DepartmentIDs = []string{"absent"} }},
+ {name: "conflicting direct rules", rules: []Rule{{DepartmentID: "sales", Region: "国内工业"}, {DepartmentID: "sales", Region: "APAC"}}},
+ {name: "unknown region", rules: []Rule{{DepartmentID: "sales", Region: "automatic"}}},
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ d := exampleDirectory()
+ if tc.mutate != nil {
+ tc.mutate(&d)
+ }
+ _, err := Preview(d, tc.rules)
+ if !errors.Is(err, ErrInvalid) {
+ t.Fatalf("must fail closed, got %v", err)
+ }
+ })
+ }
+}
+
+func TestRegionPreviewKeepsMissingRulesAndDoesNotInventPrimaryDepartment(t *testing.T) {
+ d := exampleDirectory()
+ d.People = append(d.People, Person{ID: "p5", DepartmentIDs: []string{"apac", "leaf"}})
+ view, err := Preview(d, []Rule{{DepartmentID: "sales", Region: "国内工业"}, {DepartmentID: "apac", Region: "APAC"}, {DepartmentID: "removed", Region: "EMEA"}})
+ if err != nil {
+ t.Fatal(err)
+ }
+ if len(view.MissingDepartments) != 1 || view.MissingDepartments[0] != "removed" || view.ConflictingPeople != 1 || view.Regions["APAC"] != 2 {
+ t.Fatalf("lost orphan rule or duplicated same-region membership: %+v", view)
+ }
+ d.Departments[2].Name = "改名后的部门"
+ renamed, err := Preview(d, []Rule{{DepartmentID: "sales", Region: "国内工业"}, {DepartmentID: "apac", Region: "APAC"}})
+ if err != nil || renamed.Regions["APAC"] != 2 {
+ t.Fatal("stable department ID did not survive rename")
+ }
+}
diff --git a/internal/qaopsorg/store.go b/internal/qaopsorg/store.go
new file mode 100644
index 0000000..c07cb95
--- /dev/null
+++ b/internal/qaopsorg/store.go
@@ -0,0 +1,214 @@
+package qaopsorg
+
+import (
+ "context"
+ "crypto/rand"
+ "crypto/sha256"
+ "encoding/hex"
+ "encoding/json"
+ "errors"
+ "sort"
+ "time"
+
+ "github.com/jackc/pgx/v5"
+ "github.com/jackc/pgx/v5/pgxpool"
+)
+
+var ErrConflict = errors.New("organization snapshot or region revision changed")
+var ErrUnavailable = errors.New("organization store unavailable")
+var ErrNoDirectory = errors.New("organization directory has not been imported")
+
+type Import struct {
+ Source string `json:"source"`
+ SyncedAt time.Time `json:"synced_at"`
+ Complete bool `json:"complete"`
+ Directory Directory `json:"directory"`
+}
+type SaveRequest struct {
+ DirectoryID string `json:"directory_id"`
+ BaseRevision string `json:"base_revision"`
+ Rules []Rule `json:"rules"`
+}
+type State struct {
+ State string `json:"state"`
+ DirectoryID string `json:"directory_id"`
+ DirectorySource string `json:"directory_source"`
+ DirectorySyncedAt *time.Time `json:"directory_synced_at"`
+ RevisionID string `json:"revision_id"`
+ UpdatedBy string `json:"updated_by"`
+ UpdatedAt *time.Time `json:"updated_at"`
+ Rules []Rule `json:"rules"`
+ View PreviewResult `json:"view"`
+}
+type Store struct {
+ pool *pgxpool.Pool
+ tenant string
+}
+
+func NewStore(pool *pgxpool.Pool, tenant string) *Store { return &Store{pool: pool, tenant: tenant} }
+func (s *Store) available() bool { return s != nil && s.pool != nil && validID(s.tenant) }
+
+type orgQuerier interface {
+ QueryRow(context.Context, string, ...any) pgx.Row
+}
+
+const readStateSQL = `SELECT d.id,d.source,d.synced_at,d.payload,COALESCE(r.id,''),COALESCE(r.rules,'[]'::jsonb),COALESCE(r.updated_by,''),r.created_at
+ FROM qa_ops_organization_state st JOIN qa_ops_directory_snapshots d ON d.tenant_key=st.tenant_key AND d.id=st.directory_id
+ LEFT JOIN qa_ops_region_revisions r ON r.tenant_key=st.tenant_key AND r.id=st.revision_id WHERE st.tenant_key=$1`
+
+func (s *Store) read(ctx context.Context, q orgQuerier, lock bool) (State, Directory, error) {
+ state := State{State: "empty", Rules: []Rule{}, View: PreviewResult{Departments: []DepartmentView{}, Regions: map[string]int{}, MissingDepartments: []string{}}}
+ for _, r := range RegionNames {
+ state.View.Regions[r] = 0
+ }
+ var directory Directory
+ query := readStateSQL
+ if lock {
+ query += " FOR UPDATE OF st"
+ }
+ var payload, rules []byte
+ err := q.QueryRow(ctx, query, s.tenant).Scan(&state.DirectoryID, &state.DirectorySource, &state.DirectorySyncedAt, &payload, &state.RevisionID, &rules, &state.UpdatedBy, &state.UpdatedAt)
+ if errors.Is(err, pgx.ErrNoRows) {
+ return state, directory, nil
+ }
+ if err != nil || json.Unmarshal(payload, &directory) != nil || json.Unmarshal(rules, &state.Rules) != nil {
+ return State{}, directory, ErrUnavailable
+ }
+ state.View, err = Preview(directory, state.Rules)
+ if err != nil {
+ return State{}, directory, ErrUnavailable
+ }
+ state.State = "ready"
+ return state, directory, nil
+}
+func (s *Store) GetView(ctx context.Context) (State, error) {
+ if !s.available() {
+ return State{}, ErrUnavailable
+ }
+ state, _, err := s.read(ctx, s.pool, false)
+ return state, err
+}
+func (s *Store) PreviewRules(ctx context.Context, request SaveRequest) (State, error) {
+ if !s.available() {
+ return State{}, ErrUnavailable
+ }
+ state, directory, err := s.read(ctx, s.pool, false)
+ if err != nil {
+ return State{}, err
+ }
+ return applyRequest(state, directory, request)
+}
+func applyRequest(state State, directory Directory, request SaveRequest) (State, error) {
+ if state.State != "ready" {
+ return State{}, ErrNoDirectory
+ }
+ if request.DirectoryID != state.DirectoryID || request.BaseRevision != state.RevisionID {
+ return State{}, ErrConflict
+ }
+ view, err := Preview(directory, request.Rules)
+ if err != nil {
+ return State{}, err
+ }
+ // Missing saved paths are retained for operator review, never silently removed.
+ old := map[string]string{}
+ for _, rule := range state.Rules {
+ old[rule.DepartmentID] = rule.Region
+ }
+ for _, missing := range view.MissingDepartments {
+ for _, rule := range request.Rules {
+ if rule.DepartmentID == missing && old[missing] != rule.Region {
+ return State{}, ErrInvalid
+ }
+ }
+ }
+ state.View = view
+ state.Rules = append([]Rule{}, request.Rules...)
+ sort.Slice(state.Rules, func(i, j int) bool { return state.Rules[i].DepartmentID < state.Rules[j].DepartmentID })
+ return state, nil
+}
+func (s *Store) SaveRules(ctx context.Context, request SaveRequest, actor string) (State, error) {
+ if !s.available() {
+ return State{}, ErrUnavailable
+ }
+ if !validID(actor) {
+ return State{}, ErrInvalid
+ }
+ tx, err := s.pool.Begin(ctx)
+ if err != nil {
+ return State{}, ErrUnavailable
+ }
+ defer func() { _ = tx.Rollback(context.Background()) }()
+ current, directory, err := s.read(ctx, tx, true)
+ if err != nil {
+ return State{}, err
+ }
+ next, err := applyRequest(current, directory, request)
+ if err != nil {
+ return State{}, err
+ }
+ before := append([]Rule{}, current.Rules...)
+ sort.Slice(before, func(i, j int) bool { return before[i].DepartmentID < before[j].DepartmentID })
+ oldJSON, _ := json.Marshal(before)
+ newJSON, _ := json.Marshal(next.Rules)
+ if current.RevisionID != "" && string(oldJSON) == string(newJSON) {
+ if tx.Commit(ctx) != nil {
+ return State{}, ErrUnavailable
+ }
+ return current, nil
+ }
+ var nonce [16]byte
+ if _, err = rand.Read(nonce[:]); err != nil {
+ return State{}, ErrUnavailable
+ }
+ next.RevisionID = "reg-" + hex.EncodeToString(nonce[:])
+ next.UpdatedBy = actor
+ var at time.Time
+ if err = tx.QueryRow(ctx, `INSERT INTO qa_ops_region_revisions(tenant_key,id,directory_id,rules,updated_by) VALUES($1,$2,$3,$4,$5) RETURNING created_at`, s.tenant, next.RevisionID, next.DirectoryID, newJSON, actor).Scan(&at); err != nil {
+ return State{}, ErrUnavailable
+ }
+ next.UpdatedAt = &at
+ if _, err = tx.Exec(ctx, `UPDATE qa_ops_organization_state SET revision_id=$2 WHERE tenant_key=$1`, s.tenant, next.RevisionID); err != nil {
+ return State{}, ErrUnavailable
+ }
+ if err = tx.Commit(ctx); err != nil {
+ return State{}, ErrUnavailable
+ }
+ return next, nil
+}
+func (s *Store) ReplaceDirectory(ctx context.Context, input Import) (State, error) {
+ if !s.available() {
+ return State{}, ErrUnavailable
+ }
+ if !input.Complete || input.SyncedAt.IsZero() || input.SyncedAt.After(time.Now().Add(time.Minute)) || (input.Source != "weekly_report_snapshot" && input.Source != "weekly_report_live") {
+ return State{}, ErrInvalid
+ }
+ if _, err := Preview(input.Directory, nil); err != nil {
+ return State{}, err
+ }
+ raw, err := json.Marshal(input)
+ if err != nil || len(raw) > 16<<20 {
+ return State{}, ErrInvalid
+ }
+ sum := sha256.Sum256(raw)
+ id := "dir-" + hex.EncodeToString(sum[:])
+ payload, _ := json.Marshal(input.Directory)
+ tx, err := s.pool.Begin(ctx)
+ if err != nil {
+ return State{}, ErrUnavailable
+ }
+ defer func() { _ = tx.Rollback(context.Background()) }()
+ if _, err = tx.Exec(ctx, `INSERT INTO qa_ops_directory_snapshots(tenant_key,id,source,synced_at,payload) VALUES($1,$2,$3,$4,$5) ON CONFLICT(tenant_key,id) DO NOTHING`, s.tenant, id, input.Source, input.SyncedAt, payload); err != nil {
+ return State{}, ErrUnavailable
+ }
+ tag, err := tx.Exec(ctx, `INSERT INTO qa_ops_organization_state(tenant_key,directory_id) VALUES($1,$2) ON CONFLICT(tenant_key) DO UPDATE SET directory_id=EXCLUDED.directory_id WHERE qa_ops_organization_state.directory_id=EXCLUDED.directory_id OR (SELECT synced_at FROM qa_ops_directory_snapshots WHERE tenant_key=$1 AND id=qa_ops_organization_state.directory_id)<$3`, s.tenant, id, input.SyncedAt)
+ if err != nil {
+ return State{}, ErrUnavailable
+ }
+ if tag.RowsAffected() != 1 {
+ return State{}, ErrConflict
+ }
+ if err = tx.Commit(ctx); err != nil {
+ return State{}, ErrUnavailable
+ }
+ return s.GetView(ctx)
+}
diff --git a/internal/qaopsorg/store_integration_test.go b/internal/qaopsorg/store_integration_test.go
new file mode 100644
index 0000000..6af53ac
--- /dev/null
+++ b/internal/qaopsorg/store_integration_test.go
@@ -0,0 +1,146 @@
+package qaopsorg_test
+
+import (
+ "context"
+ "errors"
+ "net/url"
+ "os"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/jackc/pgx/v5/pgxpool"
+ postgresstore "knowledge-governance/internal/platform/postgres"
+ "knowledge-governance/internal/qaopsorg"
+)
+
+func TestOrganizationStoreRoundTripAndOptimisticConflict(t *testing.T) {
+ dsn := os.Getenv("KG_QAOPS_ORG_TEST_DSN")
+ if dsn == "" {
+ t.Skip("explicit isolated organization database is not configured")
+ }
+ u, err := url.Parse(dsn)
+ if err != nil || u.Hostname() != "127.0.0.1" || !strings.HasPrefix(u.Path, "/kg_qaops_org_test_") || os.Getenv("KG_QAOPS_ORG_TEST_ISOLATED") != "1" {
+ t.Fatal("refusing non-isolated organization database")
+ }
+ ctx := context.Background()
+ pool, err := pgxpool.New(ctx, dsn)
+ if err != nil {
+ t.Fatal("test database connection failed")
+ }
+ defer pool.Close()
+ if err = postgresstore.ApplyMigrations(ctx, pool); err != nil {
+ t.Fatal(err)
+ }
+ store := qaopsorg.NewStore(pool, "fixture-tenant")
+ empty, err := store.GetView(ctx)
+ if err != nil || empty.State != "empty" {
+ t.Fatalf("empty state must be explicit: %+v %v", empty, err)
+ }
+ input := qaopsorg.Import{Source: "weekly_report_snapshot", SyncedAt: time.Date(2026, 9, 27, 14, 3, 44, 0, time.UTC), Complete: true, Directory: qaopsorg.Directory{
+ Departments: []qaopsorg.Department{{ID: "root", Name: "示例公司"}, {ID: "a", ParentID: "root", Name: "国内组"}, {ID: "b", ParentID: "a", Name: "海外组"}},
+ People: []qaopsorg.Person{{ID: "u1", DepartmentIDs: []string{"a"}}, {ID: "u2", DepartmentIDs: []string{"b"}}},
+ }}
+ imported, err := store.ReplaceDirectory(ctx, input)
+ if err != nil || imported.DirectoryID == "" || imported.View.TotalPeople != 2 {
+ t.Fatalf("import failed: %+v %v", imported, err)
+ }
+ request := qaopsorg.SaveRequest{DirectoryID: imported.DirectoryID, Rules: []qaopsorg.Rule{{DepartmentID: "a", Region: "国内工业"}, {DepartmentID: "b", Region: "APAC"}}}
+ preview, err := store.PreviewRules(ctx, request)
+ if err != nil || preview.View.Regions["APAC"] != 1 {
+ t.Fatalf("preview failed: %+v %v", preview, err)
+ }
+ before, _ := store.GetView(ctx)
+ if before.RevisionID != "" {
+ t.Fatal("preview must not persist changes")
+ }
+ saved, err := store.SaveRules(ctx, request, "fixture-admin")
+ if err != nil || saved.RevisionID == "" || saved.UpdatedBy != "fixture-admin" {
+ t.Fatalf("save failed: %+v %v", saved, err)
+ }
+ read, err := store.GetView(ctx)
+ if err != nil || read.RevisionID != saved.RevisionID || read.View.Regions["国内工业"] != 1 {
+ t.Fatal("saved rules not consumed by read path")
+ }
+ if _, err = store.SaveRules(ctx, request, "stale-admin"); !errors.Is(err, qaopsorg.ErrConflict) {
+ t.Fatalf("stale update overwrote newer rules: %v", err)
+ }
+ request.BaseRevision = saved.RevisionID
+ again, err := store.SaveRules(ctx, request, "fixture-admin")
+ if err != nil || again.RevisionID != saved.RevisionID {
+ t.Fatal("unchanged save must not append duplicate revisions")
+ }
+ broken := input
+ broken.Complete = false
+ if _, err = store.ReplaceDirectory(ctx, broken); !errors.Is(err, qaopsorg.ErrInvalid) {
+ t.Fatal("partial sync activated")
+ }
+ request.Rules = []qaopsorg.Rule{{DepartmentID: "absent", Region: "EMEA"}}
+ if _, err = store.SaveRules(ctx, request, "fixture-admin"); !errors.Is(err, qaopsorg.ErrInvalid) {
+ t.Fatal("invalid rule persisted")
+ }
+ after, _ := store.GetView(ctx)
+ if after.RevisionID != saved.RevisionID {
+ t.Fatal("failed writes changed active revision")
+ }
+ other, _ := qaopsorg.NewStore(pool, "another-tenant").GetView(ctx)
+ if other.State != "empty" {
+ t.Fatal("directory leaked across tenants")
+ }
+ input.Directory.Departments = input.Directory.Departments[:2]
+ input.Directory.People = input.Directory.People[:1]
+ input.SyncedAt = input.SyncedAt.Add(time.Hour)
+ newer, err := store.ReplaceDirectory(ctx, input)
+ if err != nil || newer.RevisionID != saved.RevisionID || len(newer.View.MissingDepartments) != 1 {
+ t.Fatalf("directory refresh deleted rules or hid missing department: %+v %v", newer, err)
+ }
+ if _, err = store.PreviewRules(ctx, request); !errors.Is(err, qaopsorg.ErrConflict) {
+ t.Fatal("preview accepted an obsolete directory snapshot")
+ }
+ older := input
+ start := make(chan struct{})
+ results := make(chan error, 2)
+ for _, region := range []string{"APAC", "EMEA"} {
+ go func(region string) {
+ <-start
+ _, failure := store.SaveRules(ctx, qaopsorg.SaveRequest{DirectoryID: newer.DirectoryID, BaseRevision: newer.RevisionID, Rules: []qaopsorg.Rule{{DepartmentID: "a", Region: region}}}, "concurrent-admin")
+ results <- failure
+ }(region)
+ }
+ close(start)
+ successes, conflicts := 0, 0
+ for range 2 {
+ failure := <-results
+ if failure == nil {
+ successes++
+ } else if errors.Is(failure, qaopsorg.ErrConflict) {
+ conflicts++
+ } else {
+ t.Fatal(failure)
+ }
+ }
+ if successes != 1 || conflicts != 1 {
+ t.Fatalf("concurrent stale writes were not serialized: success=%d conflict=%d", successes, conflicts)
+ }
+ older.SyncedAt = older.SyncedAt.Add(-2 * time.Hour)
+ if _, err = store.ReplaceDirectory(ctx, older); !errors.Is(err, qaopsorg.ErrConflict) {
+ t.Fatalf("older directory rolled back the active roster: %v", err)
+ }
+ var revisions int
+ if err = pool.QueryRow(ctx, "SELECT count(*) FROM qa_ops_region_revisions WHERE tenant_key=$1", "fixture-tenant").Scan(&revisions); err != nil || revisions != 2 {
+ t.Fatal("revision history changed unexpectedly")
+ }
+ if err = postgresstore.RollbackLatestMigration(ctx, pool); err != nil {
+ t.Fatal(err)
+ }
+ var removed bool
+ if err = pool.QueryRow(ctx, "SELECT to_regclass('qa_ops_organization_state') IS NULL AND to_regclass('qa_ops_region_revisions') IS NULL AND to_regclass('qa_ops_directory_snapshots') IS NULL").Scan(&removed); err != nil || !removed {
+ t.Fatal("organization down migration left residue")
+ }
+ if err = postgresstore.ApplyMigrations(ctx, pool); err != nil {
+ t.Fatal(err)
+ }
+ if state, failure := store.GetView(ctx); failure != nil || state.State != "empty" {
+ t.Fatal("organization migration could not be reapplied")
+ }
+}
diff --git a/scripts/test-scope.json b/scripts/test-scope.json
index 0198d5c..f5d61ca 100644
--- a/scripts/test-scope.json
+++ b/scripts/test-scope.json
@@ -9,6 +9,11 @@
"⚠️ 文件缺失或解析不了 ⇒ 门禁红:范围声明不出来时,不许默认放行。"
],
"optional": [
+ {
+ "package": "knowledge-governance/internal/qaopsorg",
+ "test": "TestOrganizationStoreRoundTripAndOptimisticConflict",
+ "reason": "仅在显式KG_QAOPS_ORG_TEST_ISOLATED=1且127.0.0.1上的一次性kg_qaops_org_test_库运行;写入治理侧快照与配置,禁止使用共享或生产库;本批已在隔离PG补验"
+ },
{
"package": "knowledge-governance/internal/dobotaiops",
"test": "TestSSHDialerTransportsRealTraffic",
diff --git a/web/src/QAOperations.tsx b/web/src/QAOperations.tsx
index bbe2ca7..134a26d 100644
--- a/web/src/QAOperations.tsx
+++ b/web/src/QAOperations.tsx
@@ -4,6 +4,7 @@ import { useOptionalAuth } from './auth'
import { fetchQARecord, fetchQARecords, fetchQAStatus, qaCellValue, qaColumns } from './qaOps'
import type { QAQuery, QARecord, QARecordPage, QAStatus } from './qaOps'
import './qaOps.css'
+import { QARegions } from './QARegions'
interface ViewProps {
page: QARecordPage | null
@@ -229,6 +230,7 @@ function initialDraft() {
}
export function QAOperations() {
+ const [view, setView] = useState<'records' | 'regions'>('records')
const auth = useOptionalAuth()
const canRead = auth?.identity?.role === 'admin'
const [draft, setDraft] = useState(initialDraft)
@@ -362,7 +364,7 @@ export function QAOperations() {
@@ -372,55 +374,69 @@ export function QAOperations() {
) : (
<>
-
-
- 当前切片:问答查询与覆盖复检。外语翻译、AI评估及人员映射尚未接入;空值不默认填“否”。
-
- void select(id)}
- onCloseDetail={close}
- onLoadMore={() => void loadMore()}
- onRetry={() => setRevision((value) => value + 1)}
- />
+
+
+ {view === 'regions' ? (
+
+ ) : (
+ <>
+
+
+ 当前切片:问答查询与覆盖复检。外语翻译、AI评估及人员映射尚未接入;空值不默认填“否”。
+
+ void select(id)}
+ onCloseDetail={close}
+ onLoadMore={() => void loadMore()}
+ onRetry={() => setRevision((value) => value + 1)}
+ />
+ >
+ )}
>
)}
diff --git a/web/src/QARegions.test.tsx b/web/src/QARegions.test.tsx
new file mode 100644
index 0000000..ad8e254
--- /dev/null
+++ b/web/src/QARegions.test.tsx
@@ -0,0 +1,66 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+import { describe, expect, it, vi } from 'vitest'
+import { RegionMappingView } from './QARegions'
+import { parseOrganization } from './qaOrg'
+const state = parseOrganization({
+ state: 'ready',
+ directory_id: 'd',
+ directory_source: 'weekly_report_snapshot',
+ directory_synced_at: '2026-09-27T14:03:44Z',
+ revision_id: 'r',
+ updated_by: 'fixture-admin',
+ updated_at: null,
+ rules: [{ department_id: 'a', region: 'APAC' }],
+ view: {
+ departments: [
+ {
+ id: 'a',
+ parent_id: '',
+ name: '',
+ path: '示例公司/',
+ region: 'APAC',
+ explicit: true,
+ inherited_from: '',
+ },
+ ],
+ regions: { 国内工业: 0, APAC: 1, EMEA: 0, America: 0 },
+ total_people: 2,
+ unassigned_people: 0,
+ conflicting_people: 1,
+ missing_departments: [],
+ },
+})
+const props = {
+ state,
+ preview: null,
+ rules: state.rules,
+ selectedRegion: 'APAC',
+ search: '',
+ busy: false,
+ error: '',
+ notice: '',
+ dirty: false,
+ onRegion: vi.fn(),
+ onSearch: vi.fn(),
+ onToggle: vi.fn(),
+ onPreview: vi.fn(),
+ onSave: vi.fn(),
+ onReload: vi.fn(),
+ onRemoveMissing: vi.fn(),
+}
+describe('region mapping workbench', () => {
+ it('shows a dated historical roster, conflicts and no invented performance verdict', () => {
+ const html = renderToStaticMarkup()
+ expect(html).toContain('历史快照')
+ expect(html).toContain('跨区域待核对:1')
+ expect(html).toContain('配置区域归属不等于纳入绩效考核')
+ expect(html).not.toContain('')
+ expect(html).not.toContain('达标率')
+ expect(html).toMatch(/disabled=""[^>]*>保存归属/)
+ })
+ it('requires a preview of the current draft before enabling save', () => {
+ const html = renderToStaticMarkup()
+ expect(html).toContain('预览结果(未保存)')
+ expect(html).not.toMatch(/disabled=""[^>]*>保存归属/)
+ })
+})
diff --git a/web/src/QARegions.tsx b/web/src/QARegions.tsx
new file mode 100644
index 0000000..25cb37e
--- /dev/null
+++ b/web/src/QARegions.tsx
@@ -0,0 +1,246 @@
+import { useEffect, useRef, useState } from 'react'
+import { changeRegionRule, fetchOrganization, previewOrganization, regionNames, saveOrganization } from './qaOrg'
+import type { Organization, RegionRule } from './qaOrg'
+import './qaRegions.css'
+interface Props {
+ state: Organization | null
+ preview: Organization | null
+ rules: RegionRule[]
+ selectedRegion: string
+ search: string
+ busy: boolean
+ error: string
+ notice: string
+ dirty: boolean
+ onRegion: (value: string) => void
+ onSearch: (value: string) => void
+ onToggle: (id: string, checked: boolean) => void
+ onRemoveMissing: (id: string) => void
+ onPreview: () => void
+ onSave: () => void
+ onReload: () => void
+}
+export function RegionMappingView(p: Props) {
+ const display = p.preview ?? p.state
+ const available = p.state?.state === 'ready'
+ const departments =
+ display?.view.departments.filter((d) => d.path.toLowerCase().includes(p.search.toLowerCase())) ?? []
+ return (
+
+
+
区域归属配置
+
+
+ {p.state?.directory_synced_at ? (
+
+ {p.state.directory_source === 'weekly_report_snapshot' ? '历史快照' : '全量同步快照'} · 通讯录同步时间:
+ {new Date(p.state.directory_synced_at).toLocaleString('zh-CN', { hour12: false })} · 配置版本:
+ {p.state.revision_id || '尚未保存'}
+
+ ) : null}
+
+ 父部门包含子部门,子部门单独配置优先。配置区域归属不等于纳入绩效考核;跨区域多部门人员先待核对。
+
+ {p.error ? (
+
+ {p.error}
+
+ ) : null}
+ {p.notice ? {p.notice}
: null}
+ {!p.state ? (
+ {p.busy ? '正在读取通讯录…' : '尚未读取通讯录'}
+ ) : !available ? (
+ 尚无完整通讯录快照。先接入已验证的全量同步结果,不能使用按需人员缓存或编造部门。
+ ) : (
+ <>
+
+
+
+
+
+
+ {display ? (
+
+ {p.preview ? '预览结果(未保存)' : '已保存归属'}
+ 通讯录人数:{display.view.total_people}
+ {regionNames.map((r) => (
+
+ {r}:{display.view.regions[r]}
+
+ ))}
+ 未归属:{display.view.unassigned_people}
+ 跨区域待核对:{display.view.conflicting_people}
+
+ ) : null}
+ {p.dirty && !p.preview ? (
+ 勾选已修改,人数仍为已保存结果;请预览后保存。
+ ) : null}
+ {display?.view.missing_departments.length ? (
+
+ 部分已配置部门不在当前通讯录中,原规则保留,需核对:
+ {display.view.missing_departments.map((id) => (
+
+ {id}{' '}
+
+
+ ))}
+
+ ) : null}
+
+
+ {!departments.length ?
没有匹配的部门路径
: null}
+
+
+ 此处仅预览通讯录归属人数;2.0 使用次数、考核名单与绩效统计尚未接入。不会将未知在职状态当作已确认在职人数。
+
+ >
+ )}
+
+ )
+}
+function signature(rules: RegionRule[]) {
+ return JSON.stringify([...rules].sort((a, b) => a.department_id.localeCompare(b.department_id)))
+}
+export function QARegions() {
+ const [state, setState] = useState(null),
+ [preview, setPreview] = useState(null),
+ [rules, setRules] = useState([])
+ const [region, setRegion] = useState(regionNames[0]),
+ [search, setSearch] = useState(''),
+ [busy, setBusy] = useState(false),
+ [error, setError] = useState(''),
+ [notice, setNotice] = useState('')
+ const request = useRef(null)
+ const accept = (value: Organization) => {
+ setState(value)
+ setRules(value.rules)
+ setPreview(null)
+ }
+ const load = async () => {
+ request.current?.abort()
+ const controller = new AbortController()
+ request.current = controller
+ setBusy(true)
+ setError('')
+ setNotice('')
+ setPreview(null)
+ try {
+ const value = await fetchOrganization(controller.signal)
+ if (!controller.signal.aborted) accept(value)
+ } catch (e) {
+ if (!controller.signal.aborted) setError(e instanceof Error ? e.message : '读取失败')
+ } finally {
+ if (!controller.signal.aborted) setBusy(false)
+ }
+ }
+ useEffect(() => {
+ void load()
+ return () => request.current?.abort()
+ }, [])
+ const edit = (next: RegionRule[]) => {
+ setRules(next)
+ setPreview(null)
+ setNotice('')
+ setError('')
+ }
+ const act = async (save: boolean) => {
+ if (!state || busy || (save && !preview)) return
+ const controller = new AbortController()
+ request.current?.abort()
+ request.current = controller
+ setBusy(true)
+ setError('')
+ setNotice('')
+ try {
+ const value = await (save
+ ? saveOrganization(state, rules, controller.signal)
+ : previewOrganization(state, rules, controller.signal))
+ if (!controller.signal.aborted) {
+ if (save) {
+ const readback = await fetchOrganization(controller.signal)
+ if (controller.signal.aborted) return
+ accept(readback)
+ if (readback.revision_id !== value.revision_id) throw new Error('保存后配置再次变化,已读取最新版本,请核对')
+ setNotice('区域归属已保存并重新读取')
+ } else setPreview(value)
+ }
+ } catch (e) {
+ if (!controller.signal.aborted) {
+ setPreview(null)
+ setError(e instanceof Error ? e.message : '操作失败')
+ }
+ } finally {
+ if (!controller.signal.aborted) setBusy(false)
+ }
+ }
+ return (
+ edit(changeRegionRule(rules, id, region, checked))}
+ onRemoveMissing={(id) => edit(rules.filter((r) => r.department_id !== id))}
+ onPreview={() => void act(false)}
+ onSave={() => void act(true)}
+ onReload={() => void load()}
+ />
+ )
+}
diff --git a/web/src/qaOrg.test.ts b/web/src/qaOrg.test.ts
new file mode 100644
index 0000000..1fb4c5e
--- /dev/null
+++ b/web/src/qaOrg.test.ts
@@ -0,0 +1,63 @@
+import { describe, expect, it, vi } from 'vitest'
+import { fetchOrganization, parseOrganization, changeRegionRule } from './qaOrg'
+
+export const directoryFixture = {
+ state: 'ready',
+ directory_id: 'dir-fixture',
+ directory_source: 'weekly_report_snapshot',
+ directory_synced_at: '2026-09-27T14:03:44Z',
+ revision_id: '',
+ updated_by: '',
+ updated_at: null,
+ rules: [],
+ view: {
+ departments: [
+ {
+ id: 'root',
+ parent_id: '',
+ name: '示例公司',
+ path: '示例公司',
+ region: '',
+ explicit: false,
+ inherited_from: '',
+ },
+ ],
+ regions: { 国内工业: 0, APAC: 0, EMEA: 0, America: 0 },
+ total_people: 1,
+ unassigned_people: 1,
+ conflicting_people: 0,
+ missing_departments: [],
+ },
+}
+describe('department region configuration', () => {
+ it('parses an honest dated snapshot without exposing employee identities', () => {
+ const state = parseOrganization(directoryFixture)
+ expect(state.directory_source).toBe('weekly_report_snapshot')
+ expect(state.view.unassigned_people).toBe(1)
+ expect(() =>
+ parseOrganization({ ...directoryFixture, view: { ...directoryFixture.view, total_people: 0 } })
+ ).toThrow()
+ expect(() =>
+ parseOrganization({ ...directoryFixture, view: { ...directoryFixture.view, departments: [{}, {}] } })
+ ).toThrow()
+ })
+ it('changes only a direct stable ID rule, leaving sibling and child overrides alone', () => {
+ const rules = [
+ { department_id: 'parent', region: '国内工业' },
+ { department_id: 'child', region: 'APAC' },
+ ]
+ expect(changeRegionRule(rules, 'parent', 'EMEA', true)).toEqual([
+ { department_id: 'child', region: 'APAC' },
+ { department_id: 'parent', region: 'EMEA' },
+ ])
+ expect(changeRegionRule(rules, 'parent', '国内工业', false)).toEqual([{ department_id: 'child', region: 'APAC' }])
+ })
+ it('surfaces store errors rather than displaying an empty directory', async () => {
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn().mockResolvedValue({ ok: false, status: 503, json: async () => ({ error: '通讯录不可用' }) })
+ )
+ await expect(fetchOrganization()).rejects.toThrow('通讯录不可用')
+ vi.unstubAllGlobals()
+ })
+})
diff --git a/web/src/qaOrg.ts b/web/src/qaOrg.ts
new file mode 100644
index 0000000..aa53d23
--- /dev/null
+++ b/web/src/qaOrg.ts
@@ -0,0 +1,152 @@
+export const regionNames = ['国内工业', 'APAC', 'EMEA', 'America'] as const
+export interface RegionRule {
+ department_id: string
+ region: string
+}
+export interface DepartmentRegion {
+ id: string
+ parent_id: string
+ name: string
+ path: string
+ region: string
+ explicit: boolean
+ inherited_from: string
+}
+export interface Organization {
+ state: 'empty' | 'ready'
+ directory_id: string
+ directory_source: string
+ directory_synced_at: string | null
+ revision_id: string
+ updated_by: string
+ updated_at: string | null
+ rules: RegionRule[]
+ view: {
+ departments: DepartmentRegion[]
+ regions: Record
+ total_people: number
+ unassigned_people: number
+ conflicting_people: number
+ missing_departments: string[]
+ }
+}
+function invalid(): never {
+ throw new Error('通讯录或区域配置响应格式无效')
+}
+function obj(value: unknown): Record {
+ if (!value || typeof value !== 'object' || Array.isArray(value)) return invalid()
+ return value as Record
+}
+function str(value: unknown): string {
+ return typeof value === 'string' ? value : invalid()
+}
+function count(value: unknown): number {
+ return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : invalid()
+}
+function instant(value: unknown): string | null {
+ return value === null ? null : typeof value === 'string' && Number.isFinite(Date.parse(value)) ? value : invalid()
+}
+export function parseOrganization(value: unknown): Organization {
+ const s = obj(value),
+ v = obj(s.view),
+ regions = obj(v.regions)
+ if (
+ (s.state !== 'empty' && s.state !== 'ready') ||
+ !Array.isArray(s.rules) ||
+ !Array.isArray(v.departments) ||
+ !Array.isArray(v.missing_departments)
+ )
+ return invalid()
+ const rules = s.rules.map((raw) => {
+ const r = obj(raw)
+ const region = str(r.region)
+ if (!regionNames.some((x) => x === region)) return invalid()
+ return { department_id: str(r.department_id), region }
+ })
+ const departments = v.departments.map((raw) => {
+ const d = obj(raw)
+ if (typeof d.explicit !== 'boolean' || (d.region !== '' && !regionNames.some((x) => x === d.region)))
+ return invalid()
+ return {
+ id: str(d.id),
+ parent_id: str(d.parent_id),
+ name: str(d.name),
+ path: str(d.path),
+ region: str(d.region),
+ explicit: d.explicit,
+ inherited_from: str(d.inherited_from),
+ }
+ })
+ if (
+ departments.some((d) => !d.id || !d.path) ||
+ new Set(departments.map((d) => d.id)).size !== departments.length ||
+ new Set(rules.map((r) => r.department_id)).size !== rules.length
+ )
+ return invalid()
+ const total = count(v.total_people),
+ unassigned = count(v.unassigned_people),
+ conflicting = count(v.conflicting_people)
+ const regionCounts = Object.fromEntries(regionNames.map((r) => [r, count(regions[r])]))
+ if (Object.values(regionCounts).reduce((a, b) => a + b, 0) + unassigned + conflicting !== total) return invalid()
+ const result: Organization = {
+ state: s.state,
+ directory_id: str(s.directory_id),
+ directory_source: str(s.directory_source),
+ directory_synced_at: instant(s.directory_synced_at),
+ revision_id: str(s.revision_id),
+ updated_by: str(s.updated_by),
+ updated_at: instant(s.updated_at),
+ rules,
+ view: {
+ departments,
+ regions: regionCounts,
+ total_people: total,
+ unassigned_people: unassigned,
+ conflicting_people: conflicting,
+ missing_departments: v.missing_departments.map(str),
+ },
+ }
+ if (s.state === 'ready' && (!result.directory_id || !result.directory_synced_at || !departments.length || !total))
+ return invalid()
+ return result
+}
+export function changeRegionRule(rules: RegionRule[], id: string, region: string, checked: boolean): RegionRule[] {
+ return [...rules.filter((r) => r.department_id !== id), ...(checked ? [{ department_id: id, region }] : [])]
+}
+async function requestOrganization(
+ path: string,
+ method: string,
+ body: unknown,
+ signal?: AbortSignal
+): Promise {
+ const response = await fetch(`/api/v1/qa-ops/organization${path}`, {
+ method,
+ credentials: 'same-origin',
+ cache: 'no-store',
+ signal,
+ headers:
+ method === 'GET' ? undefined : { 'Content-Type': 'application/json', 'X-Governance-Action': 'qa-organization' },
+ body: body === undefined ? undefined : JSON.stringify(body),
+ })
+ const raw: unknown = await response.json().catch(() => null)
+ if (!response.ok) {
+ const error = raw && typeof raw === 'object' ? (raw as Record).error : undefined
+ throw new Error(typeof error === 'string' ? error : `区域配置读取失败(HTTP ${response.status})`)
+ }
+ return parseOrganization(obj(raw).data)
+}
+export const fetchOrganization = (signal?: AbortSignal) => requestOrganization('', 'GET', undefined, signal)
+export const previewOrganization = (state: Organization, rules: RegionRule[], signal?: AbortSignal) =>
+ requestOrganization(
+ '/preview',
+ 'POST',
+ { directory_id: state.directory_id, base_revision: state.revision_id, rules },
+ signal
+ )
+export const saveOrganization = (state: Organization, rules: RegionRule[], signal?: AbortSignal) =>
+ requestOrganization(
+ '/regions',
+ 'PUT',
+ { directory_id: state.directory_id, base_revision: state.revision_id, rules },
+ signal
+ )
diff --git a/web/src/qaRegions.css b/web/src/qaRegions.css
new file mode 100644
index 0000000..e121a63
--- /dev/null
+++ b/web/src/qaRegions.css
@@ -0,0 +1,124 @@
+.qa-regions {
+ display: flex;
+ flex-direction: column;
+ min-height: 0;
+ gap: 12px;
+ flex: 1;
+}
+.qa-region-heading {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: 12px;
+}
+.qa-region-heading h3 {
+ margin: 0;
+}
+.qa-region-filters {
+ display: flex;
+ gap: 12px;
+ align-items: end;
+ flex-wrap: wrap;
+}
+.qa-region-filters label {
+ display: flex;
+ flex-direction: column;
+ gap: 6px;
+}
+.qa-region-filters label:nth-child(2) {
+ flex: 1;
+ min-width: 220px;
+}
+.qa-region-filters input,
+.qa-region-filters select {
+ min-height: 36px;
+ padding: 6px 10px;
+ border: 1px solid var(--line, #d8e1eb);
+ border-radius: 6px;
+ background: var(--panel, #fff);
+ color: inherit;
+}
+.qa-region-preview {
+ display: flex;
+ gap: 8px 18px;
+ flex-wrap: wrap;
+ padding: 12px 14px;
+ border: 1px solid var(--line, #d8e1eb);
+ background: var(--panel-muted, #f3f7fc);
+ border-radius: 6px;
+}
+.qa-region-tree-scroll {
+ min-height: 120px;
+ overflow: auto;
+ flex: 1;
+ border: 1px solid var(--line, #d8e1eb);
+ border-radius: 6px;
+}
+.qa-region-table {
+ width: 100%;
+ border-collapse: collapse;
+ text-align: left;
+ font-size: 13px;
+}
+.qa-region-table th,
+.qa-region-table td {
+ padding: 10px 12px;
+ border-bottom: 1px solid var(--line, #d8e1eb);
+}
+.qa-region-table th {
+ position: sticky;
+ top: 0;
+ background: var(--panel, #fff);
+ white-space: nowrap;
+}
+.qa-region-table td:nth-child(2) {
+ min-width: 240px;
+ overflow-wrap: anywhere;
+}
+.qa-region-table input[type='checkbox'] {
+ width: 17px;
+ height: 17px;
+ cursor: pointer;
+ accent-color: #1765c1;
+}
+.qa-region-tabs {
+ display: flex;
+ gap: 8px;
+}
+.qa-region-tabs button[aria-pressed='true'] {
+ background: #e5efff;
+ border-color: #8db8f0;
+ color: #154a88;
+}
+.qa-regions button:disabled {
+ cursor: not-allowed;
+ opacity: 0.5;
+}
+.qa-regions p {
+ margin: 0;
+}
+.qa-ops-warning > span {
+ display: inline-block;
+ margin: 4px 8px;
+}
+.qa-regions :focus-visible {
+ outline: 2px solid #1765c1;
+ outline-offset: 2px;
+}
+@media (max-width: 700px) {
+ .qa-region-filters {
+ align-items: stretch;
+ }
+ .qa-region-filters label {
+ flex: 1;
+ }
+ .qa-region-tree-scroll {
+ min-height: 300px;
+ }
+ .qa-region-preview {
+ font-size: 13px;
+ }
+ .qa-region-heading {
+ flex-wrap: wrap;
+ }
+}
--
2.52.0
From 5874134e049b0896a202b41d9d400d1be5386f89 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Sat, 17 Oct 2026 16:11:29 +0800
Subject: [PATCH 03/14] =?UTF-8?q?feat(qaops):=20=E6=8E=A5=E5=85=A5?=
=?UTF-8?q?=E7=9C=9F=E5=AE=9E=E9=80=9A=E8=AE=AF=E5=BD=95=E9=87=87=E9=9B=86?=
=?UTF-8?q?=E5=B9=B6=E8=A1=A5=E5=85=A8=E6=A0=B9=E9=83=A8=E9=97=A8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
CHANGELOG.md | 1 +
internal/qaopsorg/directory_runner.go | 79 ++++++++++
internal/qaopsorg/directory_runner_test.go | 98 ++++++++++++
scripts/qa_ops_directory_sync.py | 174 +++++++++++++++++++++
scripts/test_qa_ops_directory_sync.py | 58 +++++++
5 files changed, 410 insertions(+)
create mode 100644 internal/qaopsorg/directory_runner.go
create mode 100644 internal/qaopsorg/directory_runner_test.go
create mode 100644 scripts/qa_ops_directory_sync.py
create mode 100644 scripts/test_qa_ops_directory_sync.py
diff --git a/CHANGELOG.md b/CHANGELOG.md
index aae8383..096638a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,7 @@
### Added
+- 新增治理侧通讯录实时桥接,复用既有周报读取能力,向源端读取真实缺失祖先以补齐部门树;不改旧周报脚本、配置或输出。私有 JSON 与受控子进程执行器拒绝不完整数据、模拟同步、公开文件和异常输出,超时清理临时人员文件;网页触发的后台同步队列及问答组织关联尚未接入。
- **「问答运营 → 区域使用」区域归属配置切片**:按稳定部门 ID 搜索和勾选完整路径,预览去重归属人数,保存版本后重新读取;父部门包含子部门、子部门显式配置优先,多部门跨区域人员单独待核对。预览不写入,过期版本和不完整部门树被阻断。当前不是实时通讯录同步或使用/绩效统计验收,翻译及 AI 评估模型接入按用户要求暂缓。
- 新增治理侧组织快照与区域修订迁移、受确认保护的后台导入命令;不修改 DobotAI 原表或钉钉组织结构。
- **「问答运营 → 问答记录」首个开发切片**:在现有导航中查看 DobotAI 2.0 钉钉问答,支持半开时间范围、原问题关键词、稳定游标分页和完整详情;按整个筛选结果隐藏空列,反馈聚合不放大问答条数。外语翻译、AI 评估、人员区域映射尚未接入,不标为第一阶段完成。
diff --git a/internal/qaopsorg/directory_runner.go b/internal/qaopsorg/directory_runner.go
new file mode 100644
index 0000000..f333a71
--- /dev/null
+++ b/internal/qaopsorg/directory_runner.go
@@ -0,0 +1,79 @@
+package qaopsorg
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "io"
+ "os"
+ "os/exec"
+ "path/filepath"
+ "time"
+)
+
+var ErrDirectorySync = errors.New("directory synchronization failed; active snapshot was not replaced")
+
+type ExecDirectoryRunner struct {
+ Python string
+ Script string
+ RuntimeRoot string
+ SpoolRoot string
+ Timeout time.Duration
+}
+
+// Only server-owned paths cross this boundary. Credentials are read by the
+// existing directory client from its private file, never passed in argv/logs.
+func (r ExecDirectoryRunner) Run(ctx context.Context) (Import, error) {
+ for _, path := range []string{r.Python, r.Script, r.RuntimeRoot, r.SpoolRoot} {
+ if !filepath.IsAbs(path) || filepath.Clean(path) != path {
+ return Import{}, ErrDirectorySync
+ }
+ }
+ if r.Timeout == 0 {
+ r.Timeout = 20 * time.Minute
+ }
+ if r.Timeout < time.Millisecond || r.Timeout > 30*time.Minute {
+ return Import{}, ErrDirectorySync
+ }
+ work, err := os.MkdirTemp(r.SpoolRoot, "qa-directory-")
+ if err != nil {
+ return Import{}, ErrDirectorySync
+ }
+ defer os.RemoveAll(work)
+ output := filepath.Join(work, "directory.json")
+ runCtx, cancel := context.WithTimeout(ctx, r.Timeout)
+ defer cancel()
+ cmd := exec.CommandContext(runCtx, r.Python, r.Script, "--runtime-root", r.RuntimeRoot, "--output", output, "--fetch-live-directory")
+ cmd.Dir = r.RuntimeRoot
+ cmd.Env = []string{"PYTHONUNBUFFERED=1"}
+ for _, key := range []string{"PATH", "HOME", "TMPDIR", "LANG", "TZ"} {
+ if value, ok := os.LookupEnv(key); ok {
+ cmd.Env = append(cmd.Env, key+"="+value)
+ }
+ }
+ cmd.Stdout = io.Discard
+ cmd.Stderr = io.Discard
+ cmd.WaitDelay = 3 * time.Second
+ if err = cmd.Run(); err != nil {
+ return Import{}, ErrDirectorySync
+ }
+ info, err := os.Lstat(output)
+ if err != nil || !info.Mode().IsRegular() || info.Mode().Perm()&0077 != 0 || info.Size() < 1 || info.Size() > 16<<20 {
+ return Import{}, ErrDirectorySync
+ }
+ file, err := os.Open(output)
+ if err != nil {
+ return Import{}, ErrDirectorySync
+ }
+ defer file.Close()
+ decoder := json.NewDecoder(io.LimitReader(file, (16<<20)+1))
+ decoder.DisallowUnknownFields()
+ var result Import
+ if decoder.Decode(&result) != nil || decoder.Decode(&struct{}{}) != io.EOF || !result.Complete || result.Source != "weekly_report_live" || result.SyncedAt.IsZero() || result.SyncedAt.After(time.Now().Add(time.Minute)) {
+ return Import{}, ErrDirectorySync
+ }
+ if _, err = Preview(result.Directory, nil); err != nil {
+ return Import{}, ErrDirectorySync
+ }
+ return result, nil
+}
diff --git a/internal/qaopsorg/directory_runner_test.go b/internal/qaopsorg/directory_runner_test.go
new file mode 100644
index 0000000..2d3830a
--- /dev/null
+++ b/internal/qaopsorg/directory_runner_test.go
@@ -0,0 +1,98 @@
+package qaopsorg
+
+import (
+ "context"
+ "os"
+ "os/exec"
+ "path/filepath"
+ "strings"
+ "testing"
+ "time"
+)
+
+func TestDirectoryBridgeRegressionSuiteRunsInDefaultCI(t *testing.T) {
+ ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+ defer cancel()
+ cmd := exec.CommandContext(ctx, "python3", "-m", "unittest", "discover", "-s", "scripts", "-p", "test_qa_ops_directory_sync.py", "-v")
+ cmd.Dir = filepath.Join("..", "..")
+ if output, err := cmd.CombinedOutput(); err != nil {
+ t.Fatalf("directory bridge regression failed: %v\n%s", err, output)
+ }
+}
+
+func TestDirectoryRunnerParsesPrivateOutputAndRemovesSpool(t *testing.T) {
+ t.Setenv("DINGTALK_CLIENT_SECRET", "fixture-credential-do-not-forward")
+ root := t.TempDir()
+ spool := filepath.Join(root, "spool")
+ if err := os.Mkdir(spool, 0700); err != nil {
+ t.Fatal(err)
+ }
+ script := filepath.Join(root, "fake-sync.sh")
+ fixture := `{"source":"weekly_report_live","synced_at":"2026-10-01T00:00:00Z","complete":true,"directory":{"departments":[{"id":"root","parent_id":"","name":"隔离测试部门"}],"people":[{"id":"fixture-user","department_ids":["root"]}]}}`
+ body := "#!/bin/sh\nif [ -n \"${DINGTALK_CLIENT_SECRET:-}\" ]; then exit 3; fi\nwhile [ \"$#\" -gt 0 ]; do if [ \"$1\" = --output ]; then output=$2; shift; fi; shift; done\numask 077\nprintf '%s' '" + fixture + "' > \"$output\"\n"
+ if err := os.WriteFile(script, []byte(body), 0700); err != nil {
+ t.Fatal(err)
+ }
+ runner := ExecDirectoryRunner{Python: "/bin/sh", Script: script, RuntimeRoot: root, SpoolRoot: spool, Timeout: time.Second}
+ result, err := runner.Run(context.Background())
+ if err != nil || len(result.Directory.People) != 1 {
+ t.Fatalf("runner failed: %v", err)
+ }
+ entries, err := os.ReadDir(spool)
+ if err != nil || len(entries) != 0 {
+ t.Fatal("personnel spool leaked")
+ }
+ if err := os.WriteFile(script, []byte("#!/bin/sh\nprintf 'secret-driver-detail' >&2\nexit 1\n"), 0700); err != nil {
+ t.Fatal(err)
+ }
+ _, err = runner.Run(context.Background())
+ if err == nil || strings.Contains(err.Error(), "secret-driver-detail") {
+ t.Fatal("runner error is missing or leaks child stderr")
+ }
+ entries, _ = os.ReadDir(spool)
+ if len(entries) != 0 {
+ t.Fatal("failed runner leaked spool")
+ }
+}
+
+func TestDirectoryRunnerRejectsMalformedOrPublicPersonnelOutput(t *testing.T) {
+ root := t.TempDir()
+ for _, mode := range []string{"malformed", "public"} {
+ script := filepath.Join(root, mode+".sh")
+ body := "#!/bin/sh\numask 077\nwhile [ \"$#\" -gt 0 ]; do if [ \"$1\" = --output ]; then output=$2; shift; fi; shift; done\nprintf '%s' '{not-json}' > \"$output\"\n"
+ if mode == "public" {
+ body += "printf '%s' '{\"source\":\"weekly_report_live\",\"synced_at\":\"2026-10-01T00:00:00Z\",\"complete\":true,\"directory\":{\"departments\":[{\"id\":\"root\",\"parent_id\":\"\",\"name\":\"fixture\"}],\"people\":[{\"id\":\"fixture-user\",\"department_ids\":[\"root\"]}]}}' > \"$output\"\nchmod 644 \"$output\"\n"
+ }
+ if err := os.WriteFile(script, []byte(body), 0700); err != nil {
+ t.Fatal(err)
+ }
+ runner := ExecDirectoryRunner{Python: "/bin/sh", Script: script, RuntimeRoot: root, SpoolRoot: root, Timeout: time.Second}
+ if _, err := runner.Run(context.Background()); err == nil {
+ t.Fatal("invalid output accepted")
+ }
+ }
+}
+
+func TestDirectoryRunnerDeadlineStopsChildAndCleansPrivateSpool(t *testing.T) {
+ root := t.TempDir()
+ spool := filepath.Join(root, "spool")
+ if err := os.Mkdir(spool, 0700); err != nil {
+ t.Fatal(err)
+ }
+ script := filepath.Join(root, "timeout.sh")
+ if err := os.WriteFile(script, []byte("#!/bin/sh\nexec sleep 30\n"), 0700); err != nil {
+ t.Fatal(err)
+ }
+ runner := ExecDirectoryRunner{Python: "/bin/sh", Script: script, RuntimeRoot: root, SpoolRoot: spool, Timeout: 50 * time.Millisecond}
+ started := time.Now()
+ if _, err := runner.Run(context.Background()); err == nil {
+ t.Fatal("timed-out source reported success")
+ }
+ if time.Since(started) > 5*time.Second {
+ t.Fatal("source process cleanup is unbounded")
+ }
+ entries, err := os.ReadDir(spool)
+ if err != nil || len(entries) != 0 {
+ t.Fatal("timed-out source retained personnel spool")
+ }
+}
diff --git a/scripts/qa_ops_directory_sync.py b/scripts/qa_ops_directory_sync.py
new file mode 100644
index 0000000..f890624
--- /dev/null
+++ b/scripts/qa_ops_directory_sync.py
@@ -0,0 +1,174 @@
+"""Read-only bridge to the existing weekly-report contacts fetchers.
+
+The bridge does not execute the weekly report, export spreadsheets, write its
+configuration, or infer company/department names. All new data stays in a private
+caller-selected JSON file for the governance importer.
+"""
+import argparse
+from datetime import datetime, timezone
+import importlib
+import json
+import logging
+import os
+from pathlib import Path
+import sys
+import types
+from urllib.request import HTTPRedirectHandler, ProxyHandler, build_opener
+
+sys.dont_write_bytecode = True
+
+
+class DirectorySyncError(RuntimeError):
+ pass
+
+
+def _validate_directory(departments, people):
+ if not departments or not people or len(departments) > 20000 or len(people) > 100000:
+ raise DirectorySyncError('directory_integrity_failed')
+ for identity, department in departments.items():
+ if identity <= 0 or not department.get('name'):
+ raise DirectorySyncError('directory_integrity_failed')
+ seen = set()
+ current = identity
+ while current:
+ if current in seen or current not in departments or len(seen) > 100:
+ raise DirectorySyncError('directory_integrity_failed')
+ seen.add(current)
+ current = int(departments[current].get('parent_id') or 0)
+ for identity, person in people.items():
+ if not identity or str(person.get('user_id') or '') != str(identity):
+ raise DirectorySyncError('directory_integrity_failed')
+ if not person.get('department_ids') or any(int(d) not in departments for d in person['department_ids']):
+ raise DirectorySyncError('directory_integrity_failed')
+
+
+def collect_directory(client, fetch_departments, fetch_users, get_detail, logger):
+ if client.config.dry_run:
+ raise DirectorySyncError('directory_dry_run_rejected')
+ departments, denied, failed = fetch_departments(client, logger, None, None)
+ if denied or failed or not departments:
+ raise DirectorySyncError('directory_department_fetch_incomplete')
+ departments = dict(departments)
+ # Legacy full traversal returns children but omits the starting root. Read
+ # actual missing ancestors; never manufacture a root or discard parent IDs.
+ for _ in range(100):
+ missing = sorted({int(d.get('parent_id') or 0) for d in departments.values()} - set(departments) - {0})
+ if not missing:
+ break
+ for identity in missing:
+ detail, denied, failed = get_detail(client, logger, identity)
+ if denied or failed or not detail or int(detail.get('id') or 0) != identity or not detail.get('name'):
+ raise DirectorySyncError('directory_ancestor_unavailable')
+ departments[identity] = detail
+ else:
+ raise DirectorySyncError('directory_integrity_failed')
+ people, denied, failed = fetch_users(client, logger, sorted(departments), enable_user_detail=False)
+ if denied or failed:
+ raise DirectorySyncError('directory_people_fetch_incomplete')
+ _validate_directory(departments, people)
+ return {
+ 'source': 'weekly_report_live',
+ 'synced_at': datetime.now(timezone.utc).isoformat(),
+ 'complete': True,
+ 'directory': {
+ 'departments': [
+ {'id': str(identity), 'parent_id': str(int(d.get('parent_id') or 0)) if d.get('parent_id') else '', 'name': str(d['name'])}
+ for identity, d in sorted(departments.items())
+ ],
+ # List membership provides stable staff IDs; do not reuse the old
+ # guessed primary department, employment policy or openId fallback.
+ 'people': [
+ {'id': str(identity), 'union_id': str((p.get('raw_payload') or {}).get('unionid') or (p.get('raw_payload') or {}).get('unionId') or ''), 'department_ids': [str(d) for d in sorted(p['department_ids'])]}
+ for identity, p in sorted(people.items())
+ ],
+ },
+ }
+
+
+class _NoRedirect(HTTPRedirectHandler):
+ def redirect_request(self, req, fp, code, msg, headers, newurl):
+ raise DirectorySyncError('directory_redirect_rejected')
+
+
+def load_existing_runtime(root):
+ root = Path(root)
+ if not root.is_absolute() or not (root / 'scripts/dingtalk_sync/client.py').is_file():
+ raise DirectorySyncError('directory_configuration_invalid')
+ secret = root / '.env'
+ info = secret.lstat()
+ if not secret.is_file() or secret.is_symlink() or info.st_mode & 0o077:
+ raise DirectorySyncError('directory_configuration_invalid')
+ package_name = '_qaops_weekly_directory'
+ package = types.ModuleType(package_name)
+ package.__path__ = [str(root / 'scripts/dingtalk_sync')]
+ sys.modules[package_name] = package
+ client_module = importlib.import_module(package_name + '.client')
+ dept_module = importlib.import_module(package_name + '.fetch_departments')
+ people_module = importlib.import_module(package_name + '.fetch_users')
+ config = client_module.load_sync_config(str(secret), str(root / 'config/dingtalk_sync.yaml'))
+ if config.api_base_url.rstrip('/') != 'https://oapi.dingtalk.com' or config.dry_run or config.api_mode != 'topapi_v2':
+ raise DirectorySyncError('directory_configuration_invalid')
+ if not (1 <= config.timeout_seconds <= 30 and 0 <= config.max_retries <= 3 and 1 <= config.page_size <= 100):
+ raise DirectorySyncError('directory_configuration_invalid')
+ # Keep the old transport inside this private module namespace. Suppress its
+ # potentially sensitive exception logging and refuse redirects/proxies.
+ logger = logging.getLogger('qa_ops_directory_private')
+ logger.handlers = [logging.NullHandler()]
+ logger.propagate = False
+ opener = build_opener(ProxyHandler({}), _NoRedirect())
+ setattr(client_module, 'urlopen', opener.open)
+
+ class BoundedClient(client_module.DingtalkClient):
+ def __init__(self):
+ super().__init__(config, logger=logger)
+ self.requests = 0
+ self.pages = set()
+
+ def request_json(self, method, path, params=None, json_body=None, retry_on_business_error=True):
+ self.requests += 1
+ if self.requests > 10000:
+ raise DirectorySyncError('directory_request_limit')
+ if path.endswith('/listsub') or path.endswith('/user/list'):
+ key = (path, json.dumps(json_body, sort_keys=True))
+ if key in self.pages:
+ raise DirectorySyncError('directory_pagination_repeated')
+ self.pages.add(key)
+ return super().request_json(method, path, params, json_body, retry_on_business_error)
+
+ return BoundedClient(), dept_module.fetch_all_departments, people_module.fetch_users, dept_module._get_department_detail, logger
+
+
+def main():
+ parser = argparse.ArgumentParser(description='Fetch a complete read-only directory into private governance JSON; no weekly-report writes')
+ parser.add_argument('--runtime-root', required=True)
+ parser.add_argument('--output', required=True)
+ parser.add_argument('--fetch-live-directory', action='store_true', required=True)
+ args = parser.parse_args()
+ output = Path(args.output)
+ if not output.is_absolute() or output.exists():
+ raise DirectorySyncError('directory_output_must_be_new_absolute_path')
+ client, departments, people, detail, logger = load_existing_runtime(args.runtime_root)
+ print(json.dumps({'stage': 'fetching_live_directory', 'weekly_report_outputs_modified': False}), flush=True)
+ result = collect_directory(client, departments, people, detail, logger)
+ raw = json.dumps(result, ensure_ascii=False).encode('utf-8')
+ if len(raw) > 16 << 20:
+ raise DirectorySyncError('directory_output_limit')
+ fd = os.open(output, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+ try:
+ with os.fdopen(fd, 'wb') as stream:
+ stream.write(raw)
+ stream.flush()
+ os.fsync(stream.fileno())
+ except BaseException:
+ output.unlink(missing_ok=True)
+ raise
+ print(json.dumps({'stage': 'complete', 'departments': len(result['directory']['departments']), 'people': len(result['directory']['people']), 'synced_at': result['synced_at'], 'requests': client.requests, 'complete': True, 'employee_identities_logged': False, 'weekly_report_outputs_modified': False}), flush=True)
+
+
+if __name__ == '__main__':
+ try:
+ main()
+ except Exception as failure:
+ code = str(failure) if isinstance(failure, DirectorySyncError) else 'directory_sync_failed'
+ print(json.dumps({'stage': 'failed', 'code': code}), file=sys.stderr)
+ raise SystemExit(1)
diff --git a/scripts/test_qa_ops_directory_sync.py b/scripts/test_qa_ops_directory_sync.py
new file mode 100644
index 0000000..f1f7259
--- /dev/null
+++ b/scripts/test_qa_ops_directory_sync.py
@@ -0,0 +1,58 @@
+import importlib.util
+import logging
+from pathlib import Path
+import unittest
+
+spec=importlib.util.spec_from_file_location('qa_ops_directory_sync',Path(__file__).with_name('qa_ops_directory_sync.py'))
+assert spec is not None and spec.loader is not None
+sync=importlib.util.module_from_spec(spec)
+spec.loader.exec_module(sync)
+
+class FakeClient:
+ class Config:
+ dry_run=False
+ def __init__(self):
+ self.config=self.Config()
+
+def full_departments(client,logger,include,exclude):
+ return {10:{'id':10,'parent_id':1,'name':'示例业务'}},set(),set()
+def full_users(client,logger,ids,enable_user_detail):
+ if enable_user_detail:
+ raise AssertionError('Must not inherit silent per-user detail failures or guessed primary department')
+ return {'fixture-user':{'user_id':'fixture-user','department_ids':{10},'raw_payload':{'unionid':'fixture-union'}}},set(),set()
+def root_detail(client,logger,department_id):
+ return {'id':department_id,'parent_id':0,'name':'真实源端返回的示例根部门'},False,False
+
+class DirectoryBridgeTests(unittest.TestCase):
+ def test_fetches_the_real_missing_root_and_preserves_stable_identities(self):
+ result=sync.collect_directory(FakeClient(),full_departments,full_users,root_detail,logging.getLogger('fixture'))
+ self.assertTrue(result['complete'])
+ self.assertEqual(result['source'],'weekly_report_live')
+ self.assertEqual(result['directory']['departments'],[
+ {'id':'1','parent_id':'','name':'真实源端返回的示例根部门'},
+ {'id':'10','parent_id':'1','name':'示例业务'}])
+ self.assertEqual(result['directory']['people'],[{'id':'fixture-user','union_id':'fixture-union','department_ids':['10']}])
+ def test_inaccessible_root_is_not_replaced_with_a_fabricated_company(self):
+ def denied(*args):return None,True,False
+ with self.assertRaisesRegex(sync.DirectorySyncError,'directory_ancestor_unavailable'):
+ sync.collect_directory(FakeClient(),full_departments,full_users,denied,logging.getLogger('fixture'))
+ def test_partial_fetch_and_dry_run_do_not_become_complete_live_snapshots(self):
+ def partial(*args):return {},set(),{10}
+ with self.assertRaises(sync.DirectorySyncError):
+ sync.collect_directory(FakeClient(),partial,full_users,root_detail,logging.getLogger('fixture'))
+ client=FakeClient();client.config.dry_run=True
+ with self.assertRaises(sync.DirectorySyncError):
+ sync.collect_directory(client,full_departments,full_users,root_detail,logging.getLogger('fixture'))
+ def test_union_id_does_not_fall_back_to_open_id(self):
+ def users(*args,**kwargs):return {'u':{'user_id':'u','department_ids':{10},'union_id':'not-a-union','raw_payload':{'openId':'not-a-union'}}},set(),set()
+ result=sync.collect_directory(FakeClient(),full_departments,users,root_detail,logging.getLogger('fixture'))
+ self.assertEqual(result['directory']['people'][0]['union_id'],'')
+ def test_wrong_root_identity_and_cycles_are_rejected(self):
+ def wrong(*args):return {'id':999,'parent_id':0,'name':'wrong'},False,False
+ with self.assertRaises(sync.DirectorySyncError):
+ sync.collect_directory(FakeClient(),full_departments,full_users,wrong,logging.getLogger('fixture'))
+ def cyclic(*args):return {1:{'id':1,'parent_id':10,'name':'a'},10:{'id':10,'parent_id':1,'name':'b'}},set(),set()
+ with self.assertRaises(sync.DirectorySyncError):
+ sync.collect_directory(FakeClient(),cyclic,full_users,root_detail,logging.getLogger('fixture'))
+
+if __name__=='__main__':unittest.main()
--
2.52.0
From 6adfdcdd4fe0e5c35018bf0e4857c203dd24e5d1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Sat, 17 Oct 2026 16:24:00 +0800
Subject: [PATCH 04/14] =?UTF-8?q?fix(qaops):=20=E4=BF=AE=E5=A4=8D=E9=95=BF?=
=?UTF-8?q?=E9=83=A8=E9=97=A8=E8=B7=AF=E5=BE=84=E6=8C=A4=E5=87=BA=E5=8C=BA?=
=?UTF-8?q?=E5=9F=9F=E4=B8=8E=E4=BE=9D=E6=8D=AE=E5=88=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
CHANGELOG.md | 1 +
web/src/QARegions.test.tsx | 10 ++++++++++
web/src/qaRegions.css | 6 ++++++
3 files changed, 17 insertions(+)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 096638a..b066623 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,7 @@
### Added
- 新增治理侧通讯录实时桥接,复用既有周报读取能力,向源端读取真实缺失祖先以补齐部门树;不改旧周报脚本、配置或输出。私有 JSON 与受控子进程执行器拒绝不完整数据、模拟同步、公开文件和异常输出,超时清理临时人员文件;网页触发的后台同步队列及问答组织关联尚未接入。
+- 区域归属表支持长部门路径换行,避免继承全局不换行规则后将生效区域与归属依据列挤出桌面面板。
- **「问答运营 → 区域使用」区域归属配置切片**:按稳定部门 ID 搜索和勾选完整路径,预览去重归属人数,保存版本后重新读取;父部门包含子部门、子部门显式配置优先,多部门跨区域人员单独待核对。预览不写入,过期版本和不完整部门树被阻断。当前不是实时通讯录同步或使用/绩效统计验收,翻译及 AI 评估模型接入按用户要求暂缓。
- 新增治理侧组织快照与区域修订迁移、受确认保护的后台导入命令;不修改 DobotAI 原表或钉钉组织结构。
- **「问答运营 → 问答记录」首个开发切片**:在现有导航中查看 DobotAI 2.0 钉钉问答,支持半开时间范围、原问题关键词、稳定游标分页和完整详情;按整个筛选结果隐藏空列,反馈聚合不放大问答条数。外语翻译、AI 评估、人员区域映射尚未接入,不标为第一阶段完成。
diff --git a/web/src/QARegions.test.tsx b/web/src/QARegions.test.tsx
index ad8e254..af92399 100644
--- a/web/src/QARegions.test.tsx
+++ b/web/src/QARegions.test.tsx
@@ -1,4 +1,6 @@
import { renderToStaticMarkup } from 'react-dom/server'
+// @ts-expect-error The test runner provides Node; the browser bundle intentionally omits @types/node.
+import { readFileSync } from 'node:fs'
import { describe, expect, it, vi } from 'vitest'
import { RegionMappingView } from './QARegions'
import { parseOrganization } from './qaOrg'
@@ -49,6 +51,14 @@ const props = {
onRemoveMissing: vi.fn(),
}
describe('region mapping workbench', () => {
+ it('lets long directory paths wrap instead of inheriting the global nowrap table rule', () => {
+ const css = readFileSync(new URL('./qaRegions.css', import.meta.url), 'utf8')
+ const bodyRule = css.match(/\.qa-region-table td\s*\{([^}]+)\}/)?.[1] ?? ''
+ expect(bodyRule).toMatch(/white-space:\s*normal/)
+ expect(bodyRule).toMatch(/overflow-wrap:\s*anywhere/)
+ const statusRule = css.match(/\.qa-region-table td:nth-child\(4\)\s*\{([^}]+)\}/)?.[1] ?? ''
+ expect(statusRule).toMatch(/white-space:\s*nowrap/)
+ })
it('shows a dated historical roster, conflicts and no invented performance verdict', () => {
const html = renderToStaticMarkup()
expect(html).toContain('历史快照')
diff --git a/web/src/qaRegions.css b/web/src/qaRegions.css
index e121a63..acac9f8 100644
--- a/web/src/qaRegions.css
+++ b/web/src/qaRegions.css
@@ -64,6 +64,8 @@
.qa-region-table td {
padding: 10px 12px;
border-bottom: 1px solid var(--line, #d8e1eb);
+ white-space: normal;
+ overflow-wrap: anywhere;
}
.qa-region-table th {
position: sticky;
@@ -75,6 +77,10 @@
min-width: 240px;
overflow-wrap: anywhere;
}
+.qa-region-table td:nth-child(3),
+.qa-region-table td:nth-child(4) {
+ white-space: nowrap;
+}
.qa-region-table input[type='checkbox'] {
width: 17px;
height: 17px;
--
2.52.0
From cc4906b6a9f33683a5c0017d83b24d96d5c997b1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Sat, 17 Oct 2026 17:36:07 +0800
Subject: [PATCH 05/14] =?UTF-8?q?feat(qaops):=20=E6=8E=A5=E9=80=9A?=
=?UTF-8?q?=E7=BD=91=E9=A1=B5=E9=80=9A=E8=AE=AF=E5=BD=95=E6=8C=81=E4=B9=85?=
=?UTF-8?q?=E5=8C=96=E5=90=8C=E6=AD=A5=E4=B8=8E=E5=90=8E=E5=8F=B0=E6=8E=A5?=
=?UTF-8?q?=E7=AE=A1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
.env.example | 11 +
CHANGELOG.md | 5 +-
api/openapi.yaml | 4 +
cmd/api/main.go | 13 +-
cmd/worker/main.go | 3 +
cmd/worker/qa_org.go | 26 ++
cmd/worker/qa_org_test.go | 39 +++
internal/httpapi/openapi_contract_test.go | 2 +-
internal/httpapi/qa_org.go | 14 +-
internal/httpapi/qa_org_sync.go | 92 +++++++
internal/httpapi/qa_org_sync_security_test.go | 20 ++
internal/httpapi/qa_org_sync_test.go | 85 ++++++
internal/httpapi/server.go | 9 +
.../platform/postgres/operation_requests.go | 6 +
internal/qaopsorg/store.go | 19 ++
internal/qaopsorg/sync.go | 194 ++++++++++++++
internal/qaopsorg/sync_integration_test.go | 244 ++++++++++++++++++
internal/qaopsorg/sync_settings.go | 59 +++++
internal/qaopsorg/sync_settings_test.go | 37 +++
scripts/test-scope.json | 5 +
web/src/QARegions.test.tsx | 24 ++
web/src/QARegions.tsx | 130 +++++++++-
web/src/qaOrg.ts | 10 +-
web/src/qaOrgSync.test.ts | 72 ++++++
web/src/qaOrgSync.ts | 104 ++++++++
25 files changed, 1203 insertions(+), 24 deletions(-)
create mode 100644 cmd/worker/qa_org.go
create mode 100644 cmd/worker/qa_org_test.go
create mode 100644 internal/httpapi/qa_org_sync.go
create mode 100644 internal/httpapi/qa_org_sync_security_test.go
create mode 100644 internal/httpapi/qa_org_sync_test.go
create mode 100644 internal/qaopsorg/sync.go
create mode 100644 internal/qaopsorg/sync_integration_test.go
create mode 100644 internal/qaopsorg/sync_settings.go
create mode 100644 internal/qaopsorg/sync_settings_test.go
create mode 100644 web/src/qaOrgSync.test.ts
create mode 100644 web/src/qaOrgSync.ts
diff --git a/.env.example b/.env.example
index 555e86a..b44901c 100644
--- a/.env.example
+++ b/.env.example
@@ -10,6 +10,17 @@ DOBOTAI_OPS_QUERY_TIMEOUT=4s
DOBOTAI_OPS_MAX_CONNS=2
DOBOTAI_OPS_MIN_CONNS=0
+# API and worker share this opt-in binding; no browser-selected paths/credentials.
+# Runtime root is the read-only existing weekly_report directory (SDK/config and
+# private secret file). Python must be compatible and already provide PyYAML.
+# Container deployment requires approved runtime/script mounts; not auto-installed.
+DOBOTAI_OPS_DIRECTORY_SYNC_ENABLED=false
+DOBOTAI_OPS_DIRECTORY_SYNC_PYTHON=
+DOBOTAI_OPS_DIRECTORY_SYNC_SCRIPT=
+DOBOTAI_OPS_DIRECTORY_SYNC_RUNTIME_ROOT=
+DOBOTAI_OPS_DIRECTORY_SYNC_SPOOL_ROOT=
+DOBOTAI_OPS_DIRECTORY_SYNC_TIMEOUT=20m
+
APP_ADDR=:8080
DATABASE_URL=postgres://governance@postgres:5432/governance?sslmode=disable
PGPASSFILE=/run/secrets/pgpass
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b066623..f4eb152 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,9 +4,10 @@
### Added
-- 新增治理侧通讯录实时桥接,复用既有周报读取能力,向源端读取真实缺失祖先以补齐部门树;不改旧周报脚本、配置或输出。私有 JSON 与受控子进程执行器拒绝不完整数据、模拟同步、公开文件和异常输出,超时清理临时人员文件;网页触发的后台同步队列及问答组织关联尚未接入。
+- 「问答运营 → 区域使用」支持管理员从网页发起持久化通讯录同步,重复请求重放、进行中操作合并;按服务器固定范围注册后台执行器,未接线或未检测到心跳时不创建新任务。界面显示真实任务状态、不编造百分比;失败保留旧快照与区域规则,同步完成不覆盖未保存草稿。旧执行器丢失租约后不能激活结果,重启接管和已提交快照的续跑使用原任务。
+- 新增治理侧通讯录实时桥接,复用既有周报读取能力,向源端读取真实缺失祖先以补齐部门树;不改旧周报脚本、配置或输出。私有 JSON 与受控子进程执行器拒绝不完整数据、模拟同步、公开文件和异常输出,超时清理临时人员文件;问答组织关联尚未接入。同步默认关闭,容器启用仍需批准的既有周报 SDK/配置及兼容 Python 运行时挂载。
- 区域归属表支持长部门路径换行,避免继承全局不换行规则后将生效区域与归属依据列挤出桌面面板。
-- **「问答运营 → 区域使用」区域归属配置切片**:按稳定部门 ID 搜索和勾选完整路径,预览去重归属人数,保存版本后重新读取;父部门包含子部门、子部门显式配置优先,多部门跨区域人员单独待核对。预览不写入,过期版本和不完整部门树被阻断。当前不是实时通讯录同步或使用/绩效统计验收,翻译及 AI 评估模型接入按用户要求暂缓。
+- **「问答运营 → 区域使用」区域归属配置切片**:按稳定部门 ID 搜索和勾选完整路径,预览去重归属人数,保存版本后重新读取;父部门包含子部门、子部门显式配置优先,多部门跨区域人员单独待核对。预览不写入,过期版本和不完整部门树被阻断。当前不是使用/绩效统计验收,翻译及 AI 评估模型接入按用户要求暂缓。
- 新增治理侧组织快照与区域修订迁移、受确认保护的后台导入命令;不修改 DobotAI 原表或钉钉组织结构。
- **「问答运营 → 问答记录」首个开发切片**:在现有导航中查看 DobotAI 2.0 钉钉问答,支持半开时间范围、原问题关键词、稳定游标分页和完整详情;按整个筛选结果隐藏空列,反馈聚合不放大问答条数。外语翻译、AI 评估、人员区域映射尚未接入,不标为第一阶段完成。
- 治理侧重新检查答案:包含 `暂无已发布` 即未覆盖,引用和源端 covered 不能抵消;未命中仍待评估,源端规则单独保留作对照。独立只读源默认关闭、租户后端固定、管理员会话鉴权,源故障不回退治理主库;安全告警明确保留 TEMP/TLS 尚未整改状态。
diff --git a/api/openapi.yaml b/api/openapi.yaml
index 66cfbdc..b858e90 100644
--- a/api/openapi.yaml
+++ b/api/openapi.yaml
@@ -44,6 +44,10 @@
}
],
"paths": {
+ "/api/v1/qa-ops/organization/sync": {
+ "get": {"tags":["QA operations"],"operationId":"getQAOrganizationSync","summary":"管理员读取通讯录同步执行器状态及最近任务的安全汇总,不返回人员名单或运行配置","responses":{"200":{"$ref":"#/components/responses/Envelope"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"需要登录"},"403":{"description":"仅管理员"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"状态存储不可用,不伪装为空记录"}}},
+ "post": {"tags":["QA operations"],"operationId":"startQAOrganizationSync","summary":"管理员同源发起持久化通讯录同步;重复请求重放同一任务,进行中任务合并;失败保留现有快照","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"name":"X-Governance-Action","in":"header","required":true,"schema":{"const":"qa-organization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}},"responses":{"202":{"$ref":"#/components/responses/OperationEnvelope"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"需要登录"},"403":{"description":"仅管理员同源操作"},"409":{"description":"操作标识与原请求冲突"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"同步未接线、执行器离线或入队失败;未创建新任务"}}}
+ },
"/api/v1/qa-ops/organization": {
"get": {
"tags": ["QA operations"],
diff --git a/cmd/api/main.go b/cmd/api/main.go
index 032855f..36417e5 100644
--- a/cmd/api/main.go
+++ b/cmd/api/main.go
@@ -133,8 +133,19 @@ func run(ctx context.Context, getenv func(string) string) error {
if qaSettings.Problem != "" {
log.Print("QA operations source is unavailable; governance remains online")
}
+ qaOrganizationStore := qaopsorg.NewStore(pool, getenv("DOBOTAI_OPS_TENANT_KEY"))
+ qaSyncSettings, qaSyncErr := qaopsorg.LoadSyncSettings(getenv)
+ if qaSyncErr != nil {
+ log.Print("QA directory synchronization is not configured; governance remains online")
+ }
+ var qaSyncStore httpapi.QAOrgSyncStore
+ if getenv("DOBOTAI_OPS_TENANT_KEY") != "" {
+ qaSyncStore = qaOrganizationStore
+ }
handler, err := httpapi.NewHandler(httpapi.Config{
- QAOrg: qaopsorg.NewStore(pool, getenv("DOBOTAI_OPS_TENANT_KEY")),
+ QAOrgSync: qaSyncStore,
+ QAOrgSyncEnabled: qaSyncErr == nil && qaSyncSettings.Enabled,
+ QAOrg: qaOrganizationStore,
QAOps: qaReader,
QAOpsTenantKey: qaSettings.TenantKey,
QAOpsEnabled: qaSettings.Enabled,
diff --git a/cmd/worker/main.go b/cmd/worker/main.go
index 055bfa4..99e2e4e 100644
--- a/cmd/worker/main.go
+++ b/cmd/worker/main.go
@@ -53,6 +53,9 @@ func run(ctx context.Context, getenv func(string) string) error {
if err != nil {
return err
}
+ if syncErr := configureDirectorySync(pool, getenv, handlers); syncErr != nil {
+ log.Print("QA directory synchronization unavailable; handler was not registered")
+ }
worker, err := jobs.NewWorker(jobs.WorkerConfig{
Queue: store,
WorkerID: config.WorkerID,
diff --git a/cmd/worker/qa_org.go b/cmd/worker/qa_org.go
new file mode 100644
index 0000000..c0c3d03
--- /dev/null
+++ b/cmd/worker/qa_org.go
@@ -0,0 +1,26 @@
+package main
+
+import (
+ "context"
+ "github.com/jackc/pgx/v5/pgxpool"
+ "knowledge-governance/internal/jobs"
+ "knowledge-governance/internal/qaopsorg"
+)
+
+func configureDirectorySync(pool *pgxpool.Pool, getenv func(string) string, handlers map[string]jobs.Handler) error {
+ settings, err := qaopsorg.LoadSyncSettings(getenv)
+ if err != nil {
+ return err
+ }
+ if !settings.Enabled {
+ return nil
+ }
+ if err = settings.CheckWorkerRuntime(); err != nil {
+ return err
+ }
+ store := qaopsorg.NewStore(pool, settings.Tenant)
+ handlers[store.SyncJobType()] = func(ctx context.Context, job jobs.Job) error {
+ return store.HandleDirectorySync(ctx, job, settings.Runner)
+ }
+ return nil
+}
diff --git a/cmd/worker/qa_org_test.go b/cmd/worker/qa_org_test.go
new file mode 100644
index 0000000..4fa629b
--- /dev/null
+++ b/cmd/worker/qa_org_test.go
@@ -0,0 +1,39 @@
+package main
+
+import (
+ "knowledge-governance/internal/jobs"
+ "knowledge-governance/internal/qaopsorg"
+ "os"
+ "path/filepath"
+ "testing"
+)
+
+func TestDirectorySyncWorkerRegistrationIsOptInAndRuntimeChecked(t *testing.T) {
+ handlers := map[string]jobs.Handler{}
+ values := map[string]string{}
+ get := func(k string) string { return values[k] }
+ if err := configureDirectorySync(nil, get, handlers); err != nil || len(handlers) != 0 {
+ t.Fatal("disabled sync registered")
+ }
+ values["DOBOTAI_OPS_DIRECTORY_SYNC_ENABLED"] = "true"
+ if err := configureDirectorySync(nil, get, handlers); err == nil {
+ t.Fatal("incomplete binding registered")
+ }
+ root := t.TempDir()
+ script := filepath.Join(root, "fixture.py")
+ if err := os.WriteFile(script, []byte("# fixture; not executed by registration"), 0600); err != nil {
+ t.Fatal(err)
+ }
+ values["DOBOTAI_OPS_TENANT_KEY"] = "fixture-tenant"
+ values["DOBOTAI_OPS_DIRECTORY_SYNC_PYTHON"] = "/bin/sh"
+ values["DOBOTAI_OPS_DIRECTORY_SYNC_SCRIPT"] = script
+ values["DOBOTAI_OPS_DIRECTORY_SYNC_RUNTIME_ROOT"] = root
+ values["DOBOTAI_OPS_DIRECTORY_SYNC_SPOOL_ROOT"] = root
+ if err := configureDirectorySync(nil, get, handlers); err != nil || handlers[qaopsorg.NewStore(nil, "fixture-tenant").SyncJobType()] == nil {
+ t.Fatal("configured worker was not wired")
+ }
+ values["DOBOTAI_OPS_DIRECTORY_SYNC_SCRIPT"] = filepath.Join(root, "missing.py")
+ if err := configureDirectorySync(nil, get, map[string]jobs.Handler{}); err == nil {
+ t.Fatal("missing runtime advertised as ready")
+ }
+}
diff --git a/internal/httpapi/openapi_contract_test.go b/internal/httpapi/openapi_contract_test.go
index aa923d7..f61bff7 100644
--- a/internal/httpapi/openapi_contract_test.go
+++ b/internal/httpapi/openapi_contract_test.go
@@ -77,7 +77,7 @@ func TestOpenAPICatalogMutationsRequireIdempotencyKeyHeader(t *testing.T) {
if !ok || schema["type"] != "string" || schema["minLength"] != float64(1) || schema["maxLength"] != float64(128) {
t.Fatalf("IdempotencyKey header schema is unsafe: %#v", parameter["schema"])
}
- for _, path := range []string{"/api/v1/source-catalog/route", "/api/v1/source-catalog/sources/{id}/refresh"} {
+ for _, path := range []string{"/api/v1/qa-ops/organization/sync", "/api/v1/source-catalog/route", "/api/v1/source-catalog/sources/{id}/refresh"} {
operation, ok := document.Paths[path]["post"].(map[string]any)
if !ok {
t.Fatalf("missing POST %s", path)
diff --git a/internal/httpapi/qa_org.go b/internal/httpapi/qa_org.go
index aed634c..f1ff249 100644
--- a/internal/httpapi/qa_org.go
+++ b/internal/httpapi/qa_org.go
@@ -7,7 +7,6 @@ import (
"io"
"knowledge-governance/internal/qaopsorg"
"net/http"
- "net/url"
)
type QAOrgStore interface {
@@ -33,20 +32,9 @@ func qaOrganization(w http.ResponseWriter, r *http.Request, config Config) {
if r.Method == http.MethodGet {
result, err = config.QAOrg.GetView(r.Context())
} else {
- if r.Header.Get("X-Governance-Action") != "qa-organization" || r.Header.Get("Sec-Fetch-Site") == "cross-site" {
- writeJSON(w, 403, map[string]string{"error": "区域配置需要同源操作意图"})
+ if !authorizeQAOrganizationWrite(w, r) {
return
}
- // A same-origin browser request can pass a reverse proxy that rewrites
- // Host. Fetch Metadata is browser-controlled; keep the explicit action
- // header and reject cross-site requests without trusting forwarded hosts.
- if raw := r.Header.Get("Origin"); raw != "" && r.Header.Get("Sec-Fetch-Site") != "same-origin" {
- origin, parseErr := url.Parse(raw)
- if parseErr != nil || (origin.Scheme != "http" && origin.Scheme != "https") || origin.Host != r.Host {
- writeJSON(w, 403, map[string]string{"error": "拒绝跨站配置请求"})
- return
- }
- }
var request qaopsorg.SaveRequest
decoder := json.NewDecoder(http.MaxBytesReader(w, r.Body, 1<<20))
decoder.DisallowUnknownFields()
diff --git a/internal/httpapi/qa_org_sync.go b/internal/httpapi/qa_org_sync.go
new file mode 100644
index 0000000..9ffad8e
--- /dev/null
+++ b/internal/httpapi/qa_org_sync.go
@@ -0,0 +1,92 @@
+package httpapi
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "io"
+ "knowledge-governance/internal/qaopsorg"
+ "net/http"
+ "net/url"
+ "strings"
+)
+
+type QAOrgSyncStore interface {
+ GetSyncStatus(context.Context) (qaopsorg.SyncStatus, error)
+ EnqueueSync(context.Context, string, string) (qaopsorg.SyncReceipt, bool, error)
+}
+
+func authorizeQAOrganizationWrite(w http.ResponseWriter, r *http.Request) bool {
+ if r.Header.Get("X-Governance-Action") != "qa-organization" || r.Header.Get("Sec-Fetch-Site") == "cross-site" {
+ writeJSON(w, 403, map[string]string{"error": "区域配置需要同源操作意图"})
+ return false
+ }
+ // Fetch Metadata survives same-origin proxies that rewrite Host; untrusted
+ // forwarded headers must not grant cross-origin write authority.
+ if raw := r.Header.Get("Origin"); raw != "" && r.Header.Get("Sec-Fetch-Site") != "same-origin" {
+ origin, err := url.Parse(raw)
+ if err != nil || (origin.Scheme != "http" && origin.Scheme != "https") || origin.Host != r.Host {
+ writeJSON(w, 403, map[string]string{"error": "拒绝跨站配置请求"})
+ return false
+ }
+ }
+ return true
+}
+func qaOrganizationSync(w http.ResponseWriter, r *http.Request, c Config) {
+ if !authorizeQAOps(w, r) {
+ return
+ }
+ if r.URL.RawQuery != "" {
+ writeOrgError(w, qaopsorg.ErrInvalid)
+ return
+ }
+ w.Header().Set("Cache-Control", "no-store")
+ if r.Method == http.MethodGet {
+ if c.QAOrgSync == nil {
+ writeJSON(w, 200, map[string]any{"data": qaopsorg.SyncStatus{}})
+ return
+ }
+ result, err := c.QAOrgSync.GetSyncStatus(r.Context())
+ if err != nil {
+ writeOrgError(w, err)
+ return
+ }
+ result.Configured = c.QAOrgSyncEnabled
+ writeJSON(w, 200, map[string]any{"data": result})
+ return
+ }
+ if !authorizeQAOrganizationWrite(w, r) {
+ return
+ }
+ key := r.Header.Get("Idempotency-Key")
+ if key == "" || len(key) > 128 || strings.TrimSpace(key) != key {
+ writeJSON(w, 400, map[string]string{"error": "同步请求需要有效 Idempotency-Key,重试须复用原标识"})
+ return
+ }
+ var body *struct{}
+ decoder := json.NewDecoder(http.MaxBytesReader(w, r.Body, 1024))
+ decoder.DisallowUnknownFields()
+ if decoder.Decode(&body) != nil || body == nil || decoder.Decode(&struct{}{}) != io.EOF {
+ writeOrgError(w, qaopsorg.ErrInvalid)
+ return
+ }
+ if !c.QAOrgSyncEnabled || c.QAOrgSync == nil {
+ writeJSON(w, 503, map[string]string{"error": "通讯录后台同步未接线,未创建任务"})
+ return
+ }
+ identity, _ := sessionFrom(r.Context())
+ receipt, replayed, err := c.QAOrgSync.EnqueueSync(r.Context(), key, identity.Username)
+ if err != nil {
+ if errors.Is(err, qaopsorg.ErrSyncWorkerUnavailable) {
+ writeJSON(w, 503, map[string]string{"error": "通讯录执行器未在线,未创建任务;请检查后台同步配置"})
+ return
+ }
+ writeOrgError(w, err)
+ return
+ }
+ operation := "created"
+ if replayed {
+ operation = "replayed"
+ }
+ writeJSON(w, 202, map[string]any{"data": receipt, "operation": operation})
+}
diff --git a/internal/httpapi/qa_org_sync_security_test.go b/internal/httpapi/qa_org_sync_security_test.go
new file mode 100644
index 0000000..d3e40e8
--- /dev/null
+++ b/internal/httpapi/qa_org_sync_security_test.go
@@ -0,0 +1,20 @@
+package httpapi
+
+import (
+ "net/http/httptest"
+ "strings"
+ "testing"
+)
+
+func TestGenericJobCreationCannotBypassDirectorySyncAdminPath(t *testing.T) {
+ h, err := NewHandler(Config{Store: &fakeJobStore{}})
+ if err != nil {
+ t.Fatal(err)
+ }
+ req := httptest.NewRequest("POST", "/api/v1/jobs", strings.NewReader(`{"type":"qaops.directory.sync.fixture","payload":{"triggered_by":"forged"},"idempotency_key":"bypass"}`))
+ res := httptest.NewRecorder()
+ h.ServeHTTP(res, req)
+ if res.Code != 400 {
+ t.Fatalf("reserved sync job bypassed its dedicated admission path: %d", res.Code)
+ }
+}
diff --git a/internal/httpapi/qa_org_sync_test.go b/internal/httpapi/qa_org_sync_test.go
new file mode 100644
index 0000000..fb790ba
--- /dev/null
+++ b/internal/httpapi/qa_org_sync_test.go
@@ -0,0 +1,85 @@
+package httpapi
+
+import (
+ "context"
+ "encoding/json"
+ "io"
+ "knowledge-governance/internal/qaopsorg"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+)
+
+type orgSyncSpy struct {
+ calls int
+ key, actor string
+ replay bool
+ err error
+}
+
+func (s *orgSyncSpy) GetSyncStatus(context.Context) (qaopsorg.SyncStatus, error) {
+ s.calls++
+ return qaopsorg.SyncStatus{Configured: true, WorkerReady: true}, s.err
+}
+func (s *orgSyncSpy) EnqueueSync(_ context.Context, key, actor string) (qaopsorg.SyncReceipt, bool, error) {
+ s.calls++
+ s.key = key
+ s.actor = actor
+ return qaopsorg.SyncReceipt{JobID: "fixture-job"}, s.replay, s.err
+}
+func TestQAOrganizationSyncRequiresAdminIntentAndDurableOperation(t *testing.T) {
+ spy := &orgSyncSpy{}
+ auth := newFakeAuthStore()
+ auth.sessions["sync-admin"] = "usr-boss"
+ auth.sessions["sync-viewer"] = "usr-eye"
+ handler, err := NewHandler(Config{Store: &fakeJobStore{}, QAOrgSync: spy, QAOrgSyncEnabled: true, Auth: &AuthConfig{Store: auth}})
+ if err != nil {
+ t.Fatal(err)
+ }
+ for _, tc := range []struct {
+ method, token, key, action, origin, body string
+ status int
+ }{
+ {"GET", "", "", "", "", "", 401}, {"GET", "sync-viewer", "", "", "", "", 403}, {"GET", "sync-admin", "", "", "", "", 200},
+ {"POST", "sync-admin", "op-one", "", "", "{}", 403}, {"POST", "sync-admin", "op-one", "qa-organization", "https://evil.invalid", "{}", 403},
+ {"POST", "sync-admin", "", "qa-organization", "", "{}", 400}, {"POST", "sync-admin", " op-one ", "qa-organization", "", "{}", 400},
+ {"POST", "sync-admin", "op-one", "qa-organization", "", `null`, 400},
+ {"POST", "sync-admin", "op-one", "qa-organization", "", `{"tenant":"forged"}`, 400}, {"POST", "sync-admin", "op-one", "qa-organization", "", "{} {}", 400},
+ {"POST", "sync-admin", "op-one", "qa-organization", "", "{}", 202},
+ } {
+ req := httptest.NewRequest(tc.method, "/api/v1/qa-ops/organization/sync", strings.NewReader(tc.body))
+ if tc.token != "" {
+ req.AddCookie(&http.Cookie{Name: sessionCookieName, Value: tc.token})
+ }
+ req.Header.Set("Idempotency-Key", tc.key)
+ req.Header.Set("X-Governance-Action", tc.action)
+ req.Header.Set("Origin", tc.origin)
+ res := httptest.NewRecorder()
+ handler.ServeHTTP(res, req)
+ if res.Code != tc.status {
+ t.Fatalf("%+v got %d: %s", tc, res.Code, res.Body.String())
+ }
+ }
+ if spy.calls != 2 || spy.key != "op-one" || spy.actor == "" {
+ t.Fatalf("invalid request reached store: %+v", spy)
+ }
+ spy.replay = true
+ req := httptest.NewRequest("POST", "/api/v1/qa-ops/organization/sync", strings.NewReader("{}"))
+ req.AddCookie(&http.Cookie{Name: sessionCookieName, Value: "sync-admin"})
+ req.Header.Set("Idempotency-Key", "op-one")
+ req.Header.Set("X-Governance-Action", "qa-organization")
+ res := httptest.NewRecorder()
+ handler.ServeHTTP(res, req)
+ var body map[string]any
+ if json.Unmarshal(res.Body.Bytes(), &body) != nil || body["operation"] != "replayed" {
+ t.Fatal("operation replay not exposed")
+ }
+ disabled, _ := NewHandler(Config{Store: &fakeJobStore{}, QAOrgSync: spy, Auth: &AuthConfig{Store: auth}})
+ req.Body = io.NopCloser(strings.NewReader("{}"))
+ res = httptest.NewRecorder()
+ disabled.ServeHTTP(res, req)
+ if res.Code != 503 {
+ t.Fatal("disabled sync enqueued")
+ }
+}
diff --git a/internal/httpapi/server.go b/internal/httpapi/server.go
index df5c2d9..ba009af 100644
--- a/internal/httpapi/server.go
+++ b/internal/httpapi/server.go
@@ -19,6 +19,7 @@ import (
"knowledge-governance/internal/jobs"
"knowledge-governance/internal/monitoring"
postgresstore "knowledge-governance/internal/platform/postgres"
+ "knowledge-governance/internal/qaopsorg"
)
type JobStore interface {
@@ -101,6 +102,8 @@ type Store interface {
}
type Config struct {
+ QAOrgSync QAOrgSyncStore
+ QAOrgSyncEnabled bool
QAOrg QAOrgStore
QAOps QAOpsReader
QAOpsTenantKey string
@@ -172,6 +175,8 @@ func NewHandler(config Config) (http.Handler, error) {
config.NewID = newID
}
mux := http.NewServeMux()
+ mux.HandleFunc("GET /api/v1/qa-ops/organization/sync", func(w http.ResponseWriter, r *http.Request) { qaOrganizationSync(w, r, config) })
+ mux.HandleFunc("POST /api/v1/qa-ops/organization/sync", func(w http.ResponseWriter, r *http.Request) { qaOrganizationSync(w, r, config) })
mux.HandleFunc("GET /api/v1/qa-ops/organization", func(w http.ResponseWriter, r *http.Request) { qaOrganization(w, r, config) })
mux.HandleFunc("POST /api/v1/qa-ops/organization/preview", func(w http.ResponseWriter, r *http.Request) { qaOrganization(w, r, config) })
mux.HandleFunc("PUT /api/v1/qa-ops/organization/regions", func(w http.ResponseWriter, r *http.Request) { qaOrganization(w, r, config) })
@@ -556,6 +561,10 @@ func createJob(w http.ResponseWriter, r *http.Request, config Config) {
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid JSON request"})
return
}
+ if strings.HasPrefix(input.Type, qaopsorg.SyncJobPrefix) {
+ writeJSON(w, http.StatusBadRequest, map[string]string{"error": "通讯录同步任务只能从问答运营的管理员入口创建"})
+ return
+ }
if strings.TrimSpace(input.Type) == "" || len(input.Type) > 100 {
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "type is required and must not exceed 100 characters"})
return
diff --git a/internal/platform/postgres/operation_requests.go b/internal/platform/postgres/operation_requests.go
index abff998..2562ffe 100644
--- a/internal/platform/postgres/operation_requests.go
+++ b/internal/platform/postgres/operation_requests.go
@@ -20,6 +20,12 @@ var ErrOperationRequestConflict = errors.New("operation request conflicts with a
type operationExecutor func(pgx.Tx) (json.RawMessage, error)
+// ExecuteOperation lets bounded modules share the durable operation transaction
+// instead of caching responses after their business writes have committed.
+func (s *Store) ExecuteOperation(ctx context.Context, operationType, operationID, fingerprint string, now time.Time, execute func(pgx.Tx) (json.RawMessage, error)) (json.RawMessage, bool, error) {
+ return s.executeOperation(ctx, operationType, operationID, fingerprint, now, execute)
+}
+
func (s *Store) RouteCatalogFilesWithOperation(ctx context.Context, request governance.CatalogRouteRequest, operationID string) (governance.CatalogRouteResult, bool, error) {
if err := validateCatalogRouteRequest(request); err != nil {
return governance.CatalogRouteResult{}, false, err
diff --git a/internal/qaopsorg/store.go b/internal/qaopsorg/store.go
index c07cb95..fe0ebb2 100644
--- a/internal/qaopsorg/store.go
+++ b/internal/qaopsorg/store.go
@@ -7,6 +7,7 @@ import (
"encoding/hex"
"encoding/json"
"errors"
+ "knowledge-governance/internal/jobs"
"sort"
"time"
@@ -176,6 +177,9 @@ func (s *Store) SaveRules(ctx context.Context, request SaveRequest, actor string
return next, nil
}
func (s *Store) ReplaceDirectory(ctx context.Context, input Import) (State, error) {
+ return s.replaceDirectory(ctx, input, nil)
+}
+func (s *Store) replaceDirectory(ctx context.Context, input Import, lease *jobs.Job) (State, error) {
if !s.available() {
return State{}, ErrUnavailable
}
@@ -197,6 +201,11 @@ func (s *Store) ReplaceDirectory(ctx context.Context, input Import) (State, erro
return State{}, ErrUnavailable
}
defer func() { _ = tx.Rollback(context.Background()) }()
+ if lease != nil {
+ if _, err = s.syncLease(ctx, tx, *lease, true); err != nil {
+ return State{}, err
+ }
+ }
if _, err = tx.Exec(ctx, `INSERT INTO qa_ops_directory_snapshots(tenant_key,id,source,synced_at,payload) VALUES($1,$2,$3,$4,$5) ON CONFLICT(tenant_key,id) DO NOTHING`, s.tenant, id, input.Source, input.SyncedAt, payload); err != nil {
return State{}, ErrUnavailable
}
@@ -207,6 +216,16 @@ func (s *Store) ReplaceDirectory(ctx context.Context, input Import) (State, erro
if tag.RowsAffected() != 1 {
return State{}, ErrConflict
}
+ if lease != nil {
+ result, _ := json.Marshal(SyncResult{DirectoryID: id, Departments: len(input.Directory.Departments), People: len(input.Directory.People), SyncedAt: input.SyncedAt})
+ tag, err = tx.Exec(ctx, `UPDATE jobs SET payload=jsonb_set(payload,'{result}',$3::jsonb),updated_at=now() WHERE id=$1 AND lease_owner=$2 AND state='running' AND lease_until>clock_timestamp() AND attempt=$4`, lease.ID, lease.LeaseOwner, result, lease.Attempt)
+ if err != nil {
+ return State{}, ErrUnavailable
+ }
+ if tag.RowsAffected() != 1 {
+ return State{}, ErrSyncLease
+ }
+ }
if err = tx.Commit(ctx); err != nil {
return State{}, ErrUnavailable
}
diff --git a/internal/qaopsorg/sync.go b/internal/qaopsorg/sync.go
new file mode 100644
index 0000000..6d0f246
--- /dev/null
+++ b/internal/qaopsorg/sync.go
@@ -0,0 +1,194 @@
+package qaopsorg
+
+import (
+ "context"
+ "crypto/sha256"
+ "encoding/hex"
+ "encoding/json"
+ "errors"
+ "time"
+
+ "github.com/jackc/pgx/v5"
+ "knowledge-governance/internal/jobs"
+ postgresstore "knowledge-governance/internal/platform/postgres"
+)
+
+var ErrSyncWorkerUnavailable = errors.New("directory sync worker is not connected")
+
+const SyncJobPrefix = "qaops.directory.sync."
+
+var ErrSyncLease = errors.New("directory sync lease is no longer owned")
+
+type DirectoryRunner interface {
+ Run(context.Context) (Import, error)
+}
+type SyncReceipt struct {
+ JobID string `json:"job_id"`
+ Deduplicated bool `json:"deduplicated"`
+}
+type SyncResult struct {
+ DirectoryID string `json:"directory_id"`
+ Departments int `json:"departments"`
+ People int `json:"people"`
+ SyncedAt time.Time `json:"synced_at"`
+}
+type SyncJob struct {
+ ID string `json:"id"`
+ State string `json:"state"`
+ Attempt int `json:"attempt"`
+ MaxAttempts int `json:"max_attempts"`
+ UpdatedAt time.Time `json:"updated_at"`
+ ErrorCode string `json:"error_code"`
+ Result *SyncResult `json:"result"`
+}
+type SyncStatus struct {
+ Configured bool `json:"configured"`
+ WorkerReady bool `json:"worker_ready"`
+ Job *SyncJob `json:"job"`
+}
+
+func (s *Store) SyncJobType() string {
+ h := sha256.Sum256([]byte(s.tenant))
+ return SyncJobPrefix + hex.EncodeToString(h[:])
+}
+
+const syncWorkerReadySQL = `SELECT EXISTS(SELECT 1 FROM worker_heartbeats WHERE $1=ANY(string_to_array(job_types,',')) AND last_seen_at>clock_timestamp()-interval '2 minutes') OR EXISTS(SELECT 1 FROM jobs WHERE type=$1 AND state='running' AND lease_until>clock_timestamp())`
+
+func (s *Store) EnqueueSync(ctx context.Context, key, actor string) (SyncReceipt, bool, error) {
+ if !s.available() {
+ return SyncReceipt{}, false, ErrUnavailable
+ }
+ if !validID(key) || len(key) > 128 || !validID(actor) {
+ return SyncReceipt{}, false, ErrInvalid
+ }
+ fp := sha256.Sum256([]byte(actor))
+ now := time.Now()
+ raw, replayed, err := postgresstore.NewStore(s.pool).ExecuteOperation(ctx, s.SyncJobType(), key, hex.EncodeToString(fp[:]), now, func(tx pgx.Tx) (json.RawMessage, error) {
+ if _, e := tx.Exec(ctx, "SELECT pg_advisory_xact_lock(hashtextextended($1,0))", s.SyncJobType()); e != nil {
+ return nil, ErrUnavailable
+ }
+ // A last-attempt process may die without recording failure. A new explicit
+ // action retires that exhausted lease; it never impersonates a live owner.
+ if _, e := tx.Exec(ctx, `UPDATE jobs SET state='failed',last_error='directory worker stopped; previous snapshot retained',last_error_code='directory_sync_failed',lease_owner=NULL,lease_until=NULL,updated_at=now() WHERE type=$1 AND state='running' AND lease_until=max_attempts`, s.SyncJobType()); e != nil {
+ return nil, ErrUnavailable
+ }
+ var active string
+ e := tx.QueryRow(ctx, `SELECT id FROM jobs WHERE type=$1 AND state IN ('pending','running','retry') ORDER BY created_at DESC,id DESC LIMIT 1`, s.SyncJobType()).Scan(&active)
+ if e == nil {
+ return json.Marshal(SyncReceipt{JobID: active, Deduplicated: true})
+ }
+ if !errors.Is(e, pgx.ErrNoRows) {
+ return nil, ErrUnavailable
+ }
+ var ready bool
+ if tx.QueryRow(ctx, syncWorkerReadySQL, s.SyncJobType()).Scan(&ready) != nil {
+ return nil, ErrUnavailable
+ }
+ if !ready {
+ return nil, ErrSyncWorkerUnavailable
+ }
+ digest := sha256.Sum256([]byte(s.SyncJobType() + ":" + key))
+ id := "job-" + hex.EncodeToString(digest[:16])
+ payload, _ := json.Marshal(map[string]string{"triggered_by": actor})
+ job, e := postgresstore.NewStore(tx).Enqueue(ctx, jobs.EnqueueRequest{ID: id, Type: s.SyncJobType(), Payload: payload, AvailableAt: now, MaxAttempts: 3, IdempotencyKey: s.SyncJobType() + ":" + key}, now)
+ if e != nil || job == nil {
+ return nil, ErrUnavailable
+ }
+ return json.Marshal(SyncReceipt{JobID: job.ID})
+ })
+ if errors.Is(err, postgresstore.ErrOperationRequestConflict) {
+ return SyncReceipt{}, false, ErrConflict
+ }
+ if err != nil {
+ return SyncReceipt{}, false, err
+ }
+ var result SyncReceipt
+ if json.Unmarshal(raw, &result) != nil || result.JobID == "" {
+ return SyncReceipt{}, false, ErrUnavailable
+ }
+ return result, replayed, nil
+}
+func (s *Store) GetSyncStatus(ctx context.Context) (SyncStatus, error) {
+ result := SyncStatus{Configured: true}
+ if !s.available() {
+ return SyncStatus{}, ErrUnavailable
+ }
+ if s.pool.QueryRow(ctx, syncWorkerReadySQL, s.SyncJobType()).Scan(&result.WorkerReady) != nil {
+ return SyncStatus{}, ErrUnavailable
+ }
+ var job SyncJob
+ var payload []byte
+ var expired bool
+ err := s.pool.QueryRow(ctx, `SELECT id,state,attempt,max_attempts,updated_at,payload,COALESCE(state='running' AND lease_until= job.MaxAttempts {
+ job.State = "failed"
+ }
+ }
+ if job.State == "failed" || job.State == "retry" {
+ job.ErrorCode = "directory_sync_failed"
+ }
+ result.Job = &job
+ return result, nil
+}
+func (s *Store) syncLease(ctx context.Context, q orgQuerier, job jobs.Job, lock bool) (*SyncResult, error) {
+ if job.Type != s.SyncJobType() || job.LeaseOwner == "" {
+ return nil, ErrSyncLease
+ }
+ query := `SELECT payload FROM jobs WHERE id=$1 AND type=$2 AND state='running' AND lease_owner=$3 AND attempt=$4 AND lease_until>clock_timestamp() AND EXISTS(SELECT 1 FROM operation_requests op WHERE op.operation_type=jobs.type AND op.result->>'job_id'=jobs.id)`
+ if lock {
+ query += " FOR UPDATE"
+ }
+ var raw []byte
+ if q.QueryRow(ctx, query, job.ID, s.SyncJobType(), job.LeaseOwner, job.Attempt).Scan(&raw) != nil {
+ return nil, ErrSyncLease
+ }
+ var payload struct {
+ Result *SyncResult `json:"result"`
+ }
+ if json.Unmarshal(raw, &payload) != nil {
+ return nil, ErrUnavailable
+ }
+ return payload.Result, nil
+}
+func (s *Store) HandleDirectorySync(ctx context.Context, job jobs.Job, runner DirectoryRunner) error {
+ if !s.available() || runner == nil {
+ return ErrDirectorySync
+ }
+ result, err := s.syncLease(ctx, s.pool, job, false)
+ if err != nil {
+ return err
+ }
+ if result != nil {
+ return nil
+ }
+ input, err := runner.Run(ctx)
+ if err != nil {
+ return ErrDirectorySync
+ }
+ if input.Source != "weekly_report_live" {
+ return jobs.Permanent("directory_sync_failed", ErrDirectorySync)
+ }
+ _, err = s.replaceDirectory(ctx, input, &job)
+ if err != nil {
+ if errors.Is(err, ErrSyncLease) {
+ return err
+ }
+ return ErrDirectorySync
+ }
+ return nil
+}
diff --git a/internal/qaopsorg/sync_integration_test.go b/internal/qaopsorg/sync_integration_test.go
new file mode 100644
index 0000000..85d432e
--- /dev/null
+++ b/internal/qaopsorg/sync_integration_test.go
@@ -0,0 +1,244 @@
+package qaopsorg_test
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "net/url"
+ "os"
+ "strings"
+ "sync"
+ "sync/atomic"
+ "testing"
+ "time"
+
+ "github.com/jackc/pgx/v5/pgxpool"
+ "knowledge-governance/internal/jobs"
+ postgresstore "knowledge-governance/internal/platform/postgres"
+ "knowledge-governance/internal/qaopsorg"
+)
+
+type syncRunner func(context.Context) (qaopsorg.Import, error)
+
+func (f syncRunner) Run(ctx context.Context) (qaopsorg.Import, error) { return f(ctx) }
+func TestDirectorySyncQueueDurableReplayAndLeaseFencing(t *testing.T) {
+ dsn := os.Getenv("KG_QAOPS_ORG_TEST_DSN")
+ if dsn == "" {
+ t.Skip("explicit isolated organization database is not configured")
+ }
+ u, err := url.Parse(dsn)
+ if err != nil || u.Hostname() != "127.0.0.1" || !strings.HasPrefix(u.Path, "/kg_qaops_org_test_") || os.Getenv("KG_QAOPS_ORG_TEST_ISOLATED") != "1" {
+ t.Fatal("refusing non-isolated organization database")
+ }
+ ctx := context.Background()
+ pool, err := pgxpool.New(ctx, dsn)
+ if err != nil {
+ t.Fatal("isolated connection failed")
+ }
+ defer pool.Close()
+ if err = postgresstore.ApplyMigrations(ctx, pool); err != nil {
+ t.Fatal(err)
+ }
+ store := qaopsorg.NewStore(pool, "sync-fixture-tenant")
+ queue := postgresstore.NewStore(pool)
+ initial := qaopsorg.Import{Source: "weekly_report_live", Complete: true, SyncedAt: time.Now().Add(-time.Hour), Directory: qaopsorg.Directory{Departments: []qaopsorg.Department{{ID: "root", Name: "同步夹具"}}, People: []qaopsorg.Person{{ID: "fixture-person", DepartmentIDs: []string{"root"}}}}}
+ old, err := store.ReplaceDirectory(ctx, initial)
+ if err != nil {
+ t.Fatal(err)
+ }
+ saved, err := store.SaveRules(ctx, qaopsorg.SaveRequest{DirectoryID: old.DirectoryID, Rules: []qaopsorg.Rule{{DepartmentID: "root", Region: "APAC"}}}, "fixture-admin")
+ if err != nil {
+ t.Fatal(err)
+ }
+ if _, _, err = store.EnqueueSync(ctx, "op-no-worker", "fixture-admin"); !errors.Is(err, qaopsorg.ErrSyncWorkerUnavailable) {
+ t.Fatalf("disconnected worker accepted: %v", err)
+ }
+ if _, err = queue.Claim(ctx, "fixture-sync-worker", []string{store.SyncJobType()}, time.Now(), time.Minute); err != nil {
+ t.Fatal(err)
+ }
+ var first qaopsorg.SyncReceipt
+ var created atomic.Int32
+ var wg sync.WaitGroup
+ failures := make(chan error, 12)
+ ids := make(chan string, 12)
+ for range 12 {
+ wg.Add(1)
+ go func() {
+ defer wg.Done()
+ r, replay, e := qaopsorg.NewStore(pool, "sync-fixture-tenant").EnqueueSync(ctx, "op-same-action", "fixture-admin")
+ if e != nil {
+ failures <- e
+ return
+ }
+ if !replay {
+ created.Add(1)
+ }
+ ids <- r.JobID
+ }()
+ }
+ wg.Wait()
+ close(failures)
+ for e := range failures {
+ t.Fatal(e)
+ }
+ close(ids)
+ for id := range ids {
+ if first.JobID == "" {
+ first.JobID = id
+ }
+ if id != first.JobID {
+ t.Fatal("duplicate effect")
+ }
+ }
+ if created.Load() != 1 {
+ t.Fatal("operation replay was not durable")
+ }
+ reused, _, err := store.EnqueueSync(ctx, "op-another-click", "fixture-admin")
+ if err != nil || !reused.Deduplicated || reused.JobID != first.JobID {
+ t.Fatal("in-flight clicks did not coalesce")
+ }
+ if _, _, err = store.EnqueueSync(ctx, "op-same-action", "another-admin"); !errors.Is(err, qaopsorg.ErrConflict) {
+ t.Fatal("actor fingerprint conflict ignored")
+ }
+ other, _ := qaopsorg.NewStore(pool, "other-sync-tenant").GetSyncStatus(ctx)
+ if other.Job != nil {
+ t.Fatal("job leaked across tenants")
+ }
+ var n int
+ if err = pool.QueryRow(ctx, "SELECT count(*) FROM jobs WHERE type=$1", store.SyncJobType()).Scan(&n); err != nil || n != 1 {
+ t.Fatal("job count must remain one")
+ }
+ job, err := queue.Claim(ctx, "worker-before-crash", []string{store.SyncJobType()}, time.Now(), time.Minute)
+ if err != nil || job == nil {
+ t.Fatal("job was not durable/claimable")
+ }
+ // A different process can reclaim expired work; the old owner must not activate data.
+ if _, err = pool.Exec(ctx, "UPDATE jobs SET lease_until=now()-interval '1 second' WHERE id=$1", job.ID); err != nil {
+ t.Fatal(err)
+ }
+ reclaimed, err := queue.Claim(ctx, "worker-after-restart", []string{store.SyncJobType()}, time.Now(), time.Minute)
+ if err != nil || reclaimed == nil || reclaimed.Attempt != 2 {
+ t.Fatal("expired lease did not resume")
+ }
+ newer := initial
+ newer.SyncedAt = time.Now()
+ newer.Directory.People = append(append([]qaopsorg.Person{}, initial.Directory.People...), qaopsorg.Person{ID: "fixture-person-2", DepartmentIDs: []string{"root"}})
+ var fetched atomic.Int32
+ run := syncRunner(func(context.Context) (qaopsorg.Import, error) { fetched.Add(1); return newer, nil })
+ if err = store.HandleDirectorySync(ctx, *job, run); err == nil {
+ t.Fatal("stale owner activated a snapshot")
+ }
+ still, _ := store.GetView(ctx)
+ if still.DirectoryID != old.DirectoryID {
+ t.Fatal("stale lease changed active data")
+ }
+ if err = store.HandleDirectorySync(ctx, *reclaimed, run); err != nil {
+ t.Fatal(err)
+ }
+ count := fetched.Load()
+ // Crash after committing the snapshot, before queue.Complete: do not fetch twice.
+ if err = store.HandleDirectorySync(ctx, *reclaimed, run); err != nil || fetched.Load() != count {
+ t.Fatal("committed source was fetched again")
+ }
+ if err = queue.Complete(ctx, reclaimed.ID, reclaimed.LeaseOwner, time.Now()); err != nil {
+ t.Fatal(err)
+ }
+ current, _ := store.GetView(ctx)
+ if current.View.TotalPeople != 2 || current.RevisionID != saved.RevisionID || current.View.Regions["APAC"] != 2 {
+ t.Fatal("refresh lost regional rules or failed to activate")
+ }
+ status, err := store.GetSyncStatus(ctx)
+ if err != nil || status.Job == nil || status.Job.State != "completed" || status.Job.Result == nil || status.Job.Result.People != 2 {
+ t.Fatal("safe status missing durable result")
+ }
+ raw, _ := json.Marshal(status)
+ if strings.Contains(string(raw), "fixture-person") || strings.Contains(string(raw), "lease_owner") {
+ t.Fatal("personnel/lease details leaked in status")
+ }
+ // Failure must preserve the previous complete directory and never store raw exceptions.
+ failed, _, err := store.EnqueueSync(ctx, "op-fails", "fixture-admin")
+ if err != nil {
+ t.Fatal(err)
+ }
+ bad, err := queue.Claim(ctx, "worker-failure", []string{store.SyncJobType()}, time.Now(), time.Minute)
+ if err != nil || bad == nil || bad.ID != failed.JobID {
+ t.Fatal("failure job was not enqueued")
+ }
+ failure := store.HandleDirectorySync(ctx, *bad, syncRunner(func(context.Context) (qaopsorg.Import, error) {
+ return qaopsorg.Import{}, errors.New("sensitive-fixture-must-not-escape")
+ }))
+ if failure == nil || strings.Contains(failure.Error(), "sensitive-fixture") {
+ t.Fatal("unsafe source exception")
+ }
+ if err = queue.Fail(ctx, bad.ID, bad.LeaseOwner, failure.Error(), "directory_sync_failed", time.Now(), time.Now().Add(time.Minute)); err != nil {
+ t.Fatal(err)
+ }
+ kept, _ := store.GetView(ctx)
+ if kept.DirectoryID != current.DirectoryID || kept.RevisionID != saved.RevisionID {
+ t.Fatal("failed refresh replaced valid state")
+ }
+ late := qaopsorg.NewStore(pool, "late-fence-tenant")
+ lateOld, err := late.ReplaceDirectory(ctx, initial)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if _, err = queue.Claim(ctx, "late-worker", []string{late.SyncJobType()}, time.Now(), time.Minute); err != nil {
+ t.Fatal(err)
+ }
+ if _, _, err = late.EnqueueSync(ctx, "op-late-fence", "fixture-admin"); err != nil {
+ t.Fatal(err)
+ }
+ lateJob, err := queue.Claim(ctx, "late-worker", []string{late.SyncJobType()}, time.Now(), time.Minute)
+ if err != nil || lateJob == nil {
+ t.Fatal("late-fence job unavailable")
+ }
+ lateErr := late.HandleDirectorySync(ctx, *lateJob, syncRunner(func(context.Context) (qaopsorg.Import, error) {
+ _, failure := pool.Exec(ctx, "UPDATE jobs SET lease_owner='replacement-worker',attempt=attempt+1,lease_until=now()+interval '1 minute' WHERE id=$1", lateJob.ID)
+ return newer, failure
+ }))
+ if lateErr == nil {
+ t.Fatal("lease lost DURING source fetch was not fenced at commit")
+ }
+ lateKept, _ := late.GetView(ctx)
+ if lateKept.DirectoryID != lateOld.DirectoryID {
+ t.Fatal("late stale worker activated data")
+ }
+ if err = pool.QueryRow(ctx, "SELECT count(*) FROM qa_ops_directory_snapshots WHERE tenant_key=$1", "late-fence-tenant").Scan(&n); err != nil || n != 1 {
+ t.Fatal("rejected stale snapshot left durable rows")
+ }
+ if _, err = pool.Exec(ctx, "UPDATE jobs SET lease_until=now()-interval '1 second' WHERE id=$1", lateJob.ID); err != nil {
+ t.Fatal(err)
+ }
+ interrupted, err := late.GetSyncStatus(ctx)
+ if err != nil || interrupted.Job == nil || interrupted.Job.State != "retry" {
+ t.Fatal("interrupted lease must wait for takeover, not claim active source processing")
+ }
+ if _, err = pool.Exec(ctx, "UPDATE jobs SET attempt=max_attempts,lease_until=now()-interval '1 second' WHERE id=$1", lateJob.ID); err != nil {
+ t.Fatal(err)
+ }
+ exhausted, err := late.GetSyncStatus(ctx)
+ if err != nil || exhausted.Job == nil || exhausted.Job.State != "failed" {
+ t.Fatal("exhausted crashed worker reported running forever")
+ }
+ fresh, _, err := late.EnqueueSync(ctx, "op-after-exhausted", "fixture-admin")
+ if err != nil || fresh.JobID == lateJob.ID {
+ t.Fatal("explicit retry could not replace an exhausted crashed job")
+ }
+ ghost := qaopsorg.NewStore(pool, "unadmitted-tenant")
+ if _, err = ghost.ReplaceDirectory(ctx, initial); err != nil {
+ t.Fatal(err)
+ }
+ _, err = queue.Enqueue(ctx, jobs.EnqueueRequest{ID: "fixture-unadmitted-job", Type: ghost.SyncJobType(), Payload: json.RawMessage(`{}`), AvailableAt: time.Now(), MaxAttempts: 1, IdempotencyKey: "fixture-unadmitted-job"}, time.Now())
+ if err != nil {
+ t.Fatal(err)
+ }
+ ghostJob, err := queue.Claim(ctx, "ghost-worker", []string{ghost.SyncJobType()}, time.Now(), time.Minute)
+ if err != nil || ghostJob == nil {
+ t.Fatal("forged fixture unavailable")
+ }
+ var ghostCalls int
+ ghostErr := ghost.HandleDirectorySync(ctx, *ghostJob, syncRunner(func(context.Context) (qaopsorg.Import, error) { ghostCalls++; return newer, nil }))
+ if ghostErr == nil || ghostCalls != 0 {
+ t.Fatal("unadmitted generic task consumed the directory source")
+ }
+}
diff --git a/internal/qaopsorg/sync_settings.go b/internal/qaopsorg/sync_settings.go
new file mode 100644
index 0000000..c3c02c6
--- /dev/null
+++ b/internal/qaopsorg/sync_settings.go
@@ -0,0 +1,59 @@
+package qaopsorg
+
+import (
+ "errors"
+ "os"
+ "path/filepath"
+ "time"
+)
+
+type SyncSettings struct {
+ Enabled bool
+ Tenant string
+ Runner ExecDirectoryRunner
+}
+
+func LoadSyncSettings(getenv func(string) string) (SyncSettings, error) {
+ var s SyncSettings
+ enabled := getenv("DOBOTAI_OPS_DIRECTORY_SYNC_ENABLED")
+ if enabled == "" || enabled == "false" {
+ return s, nil
+ }
+ if enabled != "true" {
+ return s, errors.New("invalid directory sync enable flag")
+ }
+ s.Tenant = getenv("DOBOTAI_OPS_TENANT_KEY")
+ s.Runner = ExecDirectoryRunner{Python: getenv("DOBOTAI_OPS_DIRECTORY_SYNC_PYTHON"), Script: getenv("DOBOTAI_OPS_DIRECTORY_SYNC_SCRIPT"), RuntimeRoot: getenv("DOBOTAI_OPS_DIRECTORY_SYNC_RUNTIME_ROOT"), SpoolRoot: getenv("DOBOTAI_OPS_DIRECTORY_SYNC_SPOOL_ROOT"), Timeout: 20 * time.Minute}
+ if value := getenv("DOBOTAI_OPS_DIRECTORY_SYNC_TIMEOUT"); value != "" {
+ d, err := time.ParseDuration(value)
+ if err != nil {
+ return SyncSettings{}, errors.New("invalid directory sync timeout")
+ }
+ s.Runner.Timeout = d
+ }
+ if !validID(s.Tenant) || s.Runner.Timeout < time.Second || s.Runner.Timeout > 30*time.Minute {
+ return SyncSettings{}, errors.New("directory sync binding is incomplete")
+ }
+ for _, path := range []string{s.Runner.Python, s.Runner.Script, s.Runner.RuntimeRoot, s.Runner.SpoolRoot} {
+ if !filepath.IsAbs(path) || filepath.Clean(path) != path {
+ return SyncSettings{}, errors.New("directory sync requires server-owned absolute paths")
+ }
+ }
+ s.Enabled = true
+ return s, nil
+}
+func (s SyncSettings) CheckWorkerRuntime() error {
+ for _, path := range []string{s.Runner.Python, s.Runner.Script} {
+ info, err := os.Stat(path)
+ if err != nil || !info.Mode().IsRegular() {
+ return ErrSyncWorkerUnavailable
+ }
+ }
+ for _, path := range []string{s.Runner.RuntimeRoot, s.Runner.SpoolRoot} {
+ info, err := os.Stat(path)
+ if err != nil || !info.IsDir() {
+ return ErrSyncWorkerUnavailable
+ }
+ }
+ return nil
+}
diff --git a/internal/qaopsorg/sync_settings_test.go b/internal/qaopsorg/sync_settings_test.go
new file mode 100644
index 0000000..322b02f
--- /dev/null
+++ b/internal/qaopsorg/sync_settings_test.go
@@ -0,0 +1,37 @@
+package qaopsorg
+
+import (
+ "testing"
+ "time"
+)
+
+func TestDirectorySyncSettingsAreExplicitAndServerOwned(t *testing.T) {
+ values := map[string]string{}
+ get := func(k string) string { return values[k] }
+ off, err := LoadSyncSettings(get)
+ if err != nil || off.Enabled {
+ t.Fatal("sync must default off")
+ }
+ values["DOBOTAI_OPS_DIRECTORY_SYNC_ENABLED"] = "true"
+ if _, err = LoadSyncSettings(get); err == nil {
+ t.Fatal("unbound runtime accepted")
+ }
+ values["DOBOTAI_OPS_TENANT_KEY"] = "fixture-tenant"
+ values["DOBOTAI_OPS_DIRECTORY_SYNC_PYTHON"] = "/usr/bin/python3"
+ values["DOBOTAI_OPS_DIRECTORY_SYNC_SCRIPT"] = "/app/scripts/qa_ops_directory_sync.py"
+ values["DOBOTAI_OPS_DIRECTORY_SYNC_RUNTIME_ROOT"] = "/data/weekly-report"
+ values["DOBOTAI_OPS_DIRECTORY_SYNC_SPOOL_ROOT"] = "/data/private-spool"
+ ready, err := LoadSyncSettings(get)
+ if err != nil || !ready.Enabled || ready.Runner.Timeout != 20*time.Minute {
+ t.Fatal("valid runtime not configured")
+ }
+ values["DOBOTAI_OPS_DIRECTORY_SYNC_TIMEOUT"] = "31m"
+ if _, err = LoadSyncSettings(get); err == nil {
+ t.Fatal("unbounded source timeout")
+ }
+ values["DOBOTAI_OPS_DIRECTORY_SYNC_TIMEOUT"] = "10m"
+ values["DOBOTAI_OPS_DIRECTORY_SYNC_SCRIPT"] = "relative/script.py"
+ if _, err = LoadSyncSettings(get); err == nil {
+ t.Fatal("browser-like relative script accepted")
+ }
+}
diff --git a/scripts/test-scope.json b/scripts/test-scope.json
index f5d61ca..7105950 100644
--- a/scripts/test-scope.json
+++ b/scripts/test-scope.json
@@ -9,6 +9,11 @@
"⚠️ 文件缺失或解析不了 ⇒ 门禁红:范围声明不出来时,不许默认放行。"
],
"optional": [
+ {
+ "package": "knowledge-governance/internal/qaopsorg",
+ "test": "TestDirectorySyncQueueDurableReplayAndLeaseFencing",
+ "reason": "仅显式一次性隔离PG库验证持久化入队、并发重放、进程接管与租约栅栏;不调用真实钉钉源、不连接共享或生产库;默认CI无库则明确跳过"
+ },
{
"package": "knowledge-governance/internal/qaopsorg",
"test": "TestOrganizationStoreRoundTripAndOptimisticConflict",
diff --git a/web/src/QARegions.test.tsx b/web/src/QARegions.test.tsx
index af92399..2923234 100644
--- a/web/src/QARegions.test.tsx
+++ b/web/src/QARegions.test.tsx
@@ -51,6 +51,30 @@ const props = {
onRemoveMissing: vi.fn(),
}
describe('region mapping workbench', () => {
+ it('shows real synchronization stages without inventing progress and protects dirty drafts', () => {
+ const syncStatus = {
+ configured: true,
+ worker_ready: true,
+ job: {
+ id: 'j',
+ state: 'running' as const,
+ attempt: 1,
+ max_attempts: 3,
+ updated_at: '2026-10-17T08:00:00Z',
+ error_code: '',
+ result: null,
+ },
+ }
+ const html = renderToStaticMarkup()
+ expect(html).toContain('正在读取并校验通讯录')
+ expect(html).not.toMatch(/\d+%/)
+ expect(html).toMatch(/disabled=""[^>]*>同步通讯录/)
+ const dirty = renderToStaticMarkup(
+
+ )
+ expect(dirty).toContain('未保存的区域修改')
+ expect(dirty).toMatch(/disabled=""[^>]*>同步通讯录/)
+ })
it('lets long directory paths wrap instead of inheriting the global nowrap table rule', () => {
const css = readFileSync(new URL('./qaRegions.css', import.meta.url), 'utf8')
const bodyRule = css.match(/\.qa-region-table td\s*\{([^}]+)\}/)?.[1] ?? ''
diff --git a/web/src/QARegions.tsx b/web/src/QARegions.tsx
index 25cb37e..07e94c3 100644
--- a/web/src/QARegions.tsx
+++ b/web/src/QARegions.tsx
@@ -2,7 +2,14 @@ import { useEffect, useRef, useState } from 'react'
import { changeRegionRule, fetchOrganization, previewOrganization, regionNames, saveOrganization } from './qaOrg'
import type { Organization, RegionRule } from './qaOrg'
import './qaRegions.css'
+import { completedSyncAction, directorySyncActive, fetchDirectorySync, startDirectorySync } from './qaOrgSync'
+import type { DirectorySyncStatus } from './qaOrgSync'
+import { newOperationID } from './operationKey'
interface Props {
+ syncStatus?: DirectorySyncStatus | null
+ syncError?: string
+ syncSubmitting?: boolean
+ onSync?: () => void
state: Organization | null
preview: Organization | null
rules: RegionRule[]
@@ -32,7 +39,45 @@ export function RegionMappingView(p: Props) {
+
+
+ {!p.syncStatus
+ ? '正在读取后台同步状态…'
+ : !p.syncStatus.configured
+ ? '后台同步未接线'
+ : p.syncStatus.job
+ ? {
+ pending: '等待后台执行器',
+ running: '正在读取并校验通讯录',
+ retry: '上次同步失败,等待后台重试;保留原快照',
+ completed: '同步已完成,完整快照已落库',
+ failed: '同步失败,保留原快照;可重新同步',
+ cancelled: '同步已取消,保留原快照',
+ }[p.syncStatus.job.state]
+ : p.syncStatus.worker_ready
+ ? '后台执行器在线,尚未发起同步'
+ : '后台执行器未在线,不会创建无人处理的任务'}
+ {p.dirty ? ';存在未保存的区域修改,请先保存或放弃后同步' : ''}
+
+ {p.syncError ? (
+
+ {p.syncError}
+
+ ) : null}
{p.state?.directory_synced_at ? (
{p.state.directory_source === 'weekly_report_snapshot' ? '历史快照' : '全量同步快照'} · 通讯录同步时间:
@@ -152,6 +197,14 @@ function signature(rules: RegionRule[]) {
return JSON.stringify([...rules].sort((a, b) => a.department_id.localeCompare(b.department_id)))
}
export function QARegions() {
+ const [syncStatus, setSyncStatus] = useState(null),
+ [syncError, setSyncError] = useState(''),
+ [syncSubmitting, setSyncSubmitting] = useState(false)
+ const syncOperation = useRef(''),
+ syncFlight = useRef(false),
+ syncAction = useRef(null),
+ lastCompleted = useRef(''),
+ dirtyRef = useRef(false)
const [state, setState] = useState(null),
[preview, setPreview] = useState(null),
[rules, setRules] = useState([])
@@ -176,7 +229,10 @@ export function QARegions() {
setPreview(null)
try {
const value = await fetchOrganization(controller.signal)
- if (!controller.signal.aborted) accept(value)
+ if (!controller.signal.aborted) {
+ accept(value)
+ return true
+ }
} catch (e) {
if (!controller.signal.aborted) setError(e instanceof Error ? e.message : '读取失败')
} finally {
@@ -187,6 +243,72 @@ export function QARegions() {
void load()
return () => request.current?.abort()
}, [])
+ const dirty = Boolean(state && signature(rules) !== signature(state.rules))
+ dirtyRef.current = dirty
+ const loadRef = useRef(load)
+ loadRef.current = load
+ useEffect(() => {
+ const controller = new AbortController()
+ let timer: ReturnType
+ const poll = async () => {
+ let delay = 10000
+ try {
+ const value = await fetchDirectorySync(controller.signal)
+ if (controller.signal.aborted) return
+ setSyncStatus(value)
+ setSyncError('')
+ delay = directorySyncActive(value) ? 1500 : 10000
+ const job = value.job
+ if (job?.state === 'completed' && job.id !== lastCompleted.current) {
+ const action = completedSyncAction(value, lastCompleted.current, dirtyRef.current)
+ lastCompleted.current = job.id
+ if (action === 'preserve') setNotice('通讯录已同步,当前未保存草稿仍保留;请核对后重新读取')
+ else if (action === 'reload' && (await loadRef.current())) setNotice('通讯录同步完成并已重新读取')
+ } else if (job && lastCompleted.current === '') lastCompleted.current = 'pending:' + job.id
+ } catch (e) {
+ if (!controller.signal.aborted)
+ setSyncError(e instanceof Error ? e.message : '同步状态读取失败,未将现有快照清空')
+ } finally {
+ if (!controller.signal.aborted) timer = setTimeout(() => void poll(), delay)
+ }
+ }
+ void poll()
+ return () => {
+ controller.abort()
+ clearTimeout(timer)
+ syncAction.current?.abort()
+ }
+ }, [])
+ const synchronize = async () => {
+ if (
+ busy ||
+ dirty ||
+ syncFlight.current ||
+ !syncStatus?.configured ||
+ !syncStatus.worker_ready ||
+ directorySyncActive(syncStatus)
+ )
+ return
+ syncFlight.current = true
+ setSyncSubmitting(true)
+ setSyncError('')
+ const controller = new AbortController()
+ syncAction.current = controller
+ try {
+ if (!syncOperation.current) syncOperation.current = newOperationID()
+ const receipt = await startDirectorySync(syncOperation.current, controller.signal)
+ syncOperation.current = ''
+ if (controller.signal.aborted) return
+ lastCompleted.current = 'submitted:' + receipt.job_id
+ setSyncStatus(await fetchDirectorySync(controller.signal))
+ } catch (e) {
+ if (!controller.signal.aborted)
+ setSyncError(e instanceof Error ? e.message : '同步提交结果未知;重试会复用原操作标识')
+ } finally {
+ syncFlight.current = false
+ if (!controller.signal.aborted) setSyncSubmitting(false)
+ }
+ }
const edit = (next: RegionRule[]) => {
setRules(next)
setPreview(null)
@@ -225,6 +347,10 @@ export function QARegions() {
}
return (
void synchronize()}
state={state}
preview={preview}
rules={rules}
@@ -233,7 +359,7 @@ export function QARegions() {
busy={busy}
error={error}
notice={notice}
- dirty={Boolean(state && signature(rules) !== signature(state.rules))}
+ dirty={dirty}
onRegion={setRegion}
onSearch={setSearch}
onToggle={(id, checked) => edit(changeRegionRule(rules, id, region, checked))}
diff --git a/web/src/qaOrg.ts b/web/src/qaOrg.ts
index aa53d23..1c780c6 100644
--- a/web/src/qaOrg.ts
+++ b/web/src/qaOrg.ts
@@ -30,20 +30,20 @@ export interface Organization {
missing_departments: string[]
}
}
-function invalid(): never {
+export function invalid(): never {
throw new Error('通讯录或区域配置响应格式无效')
}
-function obj(value: unknown): Record {
+export function obj(value: unknown): Record {
if (!value || typeof value !== 'object' || Array.isArray(value)) return invalid()
return value as Record
}
-function str(value: unknown): string {
+export function str(value: unknown): string {
return typeof value === 'string' ? value : invalid()
}
-function count(value: unknown): number {
+export function count(value: unknown): number {
return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : invalid()
}
-function instant(value: unknown): string | null {
+export function instant(value: unknown): string | null {
return value === null ? null : typeof value === 'string' && Number.isFinite(Date.parse(value)) ? value : invalid()
}
export function parseOrganization(value: unknown): Organization {
diff --git a/web/src/qaOrgSync.test.ts b/web/src/qaOrgSync.test.ts
new file mode 100644
index 0000000..a5a2b72
--- /dev/null
+++ b/web/src/qaOrgSync.test.ts
@@ -0,0 +1,72 @@
+import { describe, expect, it, vi, afterEach } from 'vitest'
+import { parseDirectorySync, startDirectorySync, fetchDirectorySync, completedSyncAction } from './qaOrgSync'
+afterEach(() => vi.unstubAllGlobals())
+const idle = { configured: true, worker_ready: true, job: null }
+describe('directory synchronization contract', () => {
+ it('reloads a completed job even on first observation, without replacing an unsaved draft', () => {
+ const status = parseDirectorySync({
+ ...idle,
+ job: {
+ id: 'new-job',
+ state: 'completed',
+ attempt: 1,
+ max_attempts: 3,
+ updated_at: '2026-10-17T08:00:00Z',
+ error_code: '',
+ result: { directory_id: 'd', departments: 1, people: 1, synced_at: '2026-10-17T08:00:00Z' },
+ },
+ })
+ expect(completedSyncAction(status, '', false)).toBe('reload')
+ expect(completedSyncAction(status, '', true)).toBe('preserve')
+ expect(completedSyncAction(status, 'new-job', false)).toBe('none')
+ expect(completedSyncAction({ ...status, job: { ...status.job!, state: 'running' } }, '', false)).toBe('none')
+ })
+ it('keeps unknown/failed state distinct from empty data', () => {
+ expect(parseDirectorySync(idle).job).toBeNull()
+ expect(() => parseDirectorySync({ ...idle, worker_ready: 'yes' })).toThrow()
+ expect(() => parseDirectorySync({ ...idle, job: { id: 'x', state: 'mystery' } })).toThrow()
+ const result = { directory_id: 'd', departments: 327, people: 1534, synced_at: '2026-10-17T07:00:00Z' }
+ const job = {
+ id: 'j',
+ state: 'completed',
+ attempt: 1,
+ max_attempts: 3,
+ updated_at: '2026-10-17T07:01:00Z',
+ error_code: '',
+ result,
+ }
+ expect(parseDirectorySync({ ...idle, job }).job?.result?.people).toBe(1534)
+ expect(() => parseDirectorySync({ ...idle, job: { ...job, result: { ...result, people: -1 } } })).toThrow()
+ })
+ it('sends a stable idempotency header and no tenant, credential or executable path', async () => {
+ const fetcher = vi.fn().mockResolvedValue({
+ ok: true,
+ json: async () => ({ data: { job_id: 'j', deduplicated: false }, operation: 'replayed' }),
+ })
+ vi.stubGlobal('fetch', fetcher)
+ expect((await startDirectorySync('same-action')).operation).toBe('replayed')
+ expect(fetcher).toHaveBeenCalledWith(
+ '/api/v1/qa-ops/organization/sync',
+ expect.objectContaining({
+ method: 'POST',
+ credentials: 'same-origin',
+ body: '{}',
+ headers: expect.objectContaining({
+ 'Idempotency-Key': 'same-action',
+ 'X-Governance-Action': 'qa-organization',
+ }),
+ })
+ )
+ })
+ it('reads live job state and surfaces server failure instead of a successful empty result', async () => {
+ vi.stubGlobal(
+ 'fetch',
+ vi
+ .fn()
+ .mockResolvedValueOnce({ ok: true, json: async () => ({ data: idle }) })
+ .mockResolvedValueOnce({ ok: false, status: 503, json: async () => ({ error: '执行器未在线' }) })
+ )
+ expect((await fetchDirectorySync()).worker_ready).toBe(true)
+ await expect(startDirectorySync('same-action')).rejects.toThrow('执行器未在线')
+ })
+})
diff --git a/web/src/qaOrgSync.ts b/web/src/qaOrgSync.ts
new file mode 100644
index 0000000..fbed936
--- /dev/null
+++ b/web/src/qaOrgSync.ts
@@ -0,0 +1,104 @@
+export interface DirectorySyncResult {
+ directory_id: string
+ departments: number
+ people: number
+ synced_at: string
+}
+export interface DirectorySyncJob {
+ id: string
+ state: 'pending' | 'running' | 'retry' | 'completed' | 'failed' | 'cancelled'
+ attempt: number
+ max_attempts: number
+ updated_at: string
+ error_code: string
+ result: DirectorySyncResult | null
+}
+export interface DirectorySyncStatus {
+ configured: boolean
+ worker_ready: boolean
+ job: DirectorySyncJob | null
+}
+export function completedSyncAction(
+ s: DirectorySyncStatus,
+ last: string,
+ dirty: boolean
+): 'none' | 'preserve' | 'reload' {
+ if (s.job?.state !== 'completed' || s.job.id === last) return 'none'
+ return dirty ? 'preserve' : 'reload'
+}
+export const directorySyncActive = (s: DirectorySyncStatus | null) =>
+ Boolean(s?.job && ['pending', 'running', 'retry'].includes(s.job.state))
+import { invalid as bad, obj as object, str as text, count, instant as nullableInstant } from './qaOrg'
+function instant(v: unknown): string {
+ return nullableInstant(v) ?? bad()
+}
+export function parseDirectorySync(raw: unknown): DirectorySyncStatus {
+ const s = object(raw)
+ if (typeof s.configured !== 'boolean' || typeof s.worker_ready !== 'boolean') return bad()
+ let job: DirectorySyncJob | null = null
+ if (s.job !== null) {
+ const j = object(s.job)
+ if (!['pending', 'running', 'retry', 'completed', 'failed', 'cancelled'].includes(text(j.state))) return bad()
+ let result: DirectorySyncResult | null = null
+ if (j.result !== null) {
+ const r = object(j.result)
+ result = {
+ directory_id: text(r.directory_id),
+ departments: count(r.departments),
+ people: count(r.people),
+ synced_at: instant(r.synced_at),
+ }
+ if (!result.directory_id || !result.departments || !result.people) return bad()
+ }
+ job = {
+ id: text(j.id),
+ state: j.state as DirectorySyncJob['state'],
+ attempt: count(j.attempt),
+ max_attempts: count(j.max_attempts),
+ updated_at: instant(j.updated_at),
+ error_code: text(j.error_code),
+ result,
+ }
+ if (!job.id || !job.max_attempts || job.attempt > job.max_attempts || (job.state === 'completed' && !result))
+ return bad()
+ }
+ return { configured: s.configured, worker_ready: s.worker_ready, job }
+}
+async function request(method: string, operationID?: string, signal?: AbortSignal) {
+ const response = await fetch('/api/v1/qa-ops/organization/sync', {
+ method,
+ credentials: 'same-origin',
+ cache: 'no-store',
+ signal,
+ headers:
+ method === 'POST'
+ ? {
+ 'Content-Type': 'application/json',
+ 'X-Governance-Action': 'qa-organization',
+ 'Idempotency-Key': operationID ?? '',
+ }
+ : undefined,
+ body: method === 'POST' ? '{}' : undefined,
+ })
+ const raw: unknown = await response.json().catch(() => null)
+ if (!response.ok) {
+ const error = raw && typeof raw === 'object' ? (raw as Record).error : undefined
+ throw new Error(typeof error === 'string' ? error : `通讯录同步请求失败(HTTP ${response.status})`)
+ }
+ return object(raw)
+}
+export async function fetchDirectorySync(signal?: AbortSignal) {
+ return parseDirectorySync((await request('GET', undefined, signal)).data)
+}
+export async function startDirectorySync(operationID: string, signal?: AbortSignal) {
+ if (!operationID || operationID.trim() !== operationID || operationID.length > 128) return bad()
+ const envelope = await request('POST', operationID, signal),
+ data = object(envelope.data)
+ if (
+ (envelope.operation !== 'created' && envelope.operation !== 'replayed') ||
+ typeof data.deduplicated !== 'boolean' ||
+ !text(data.job_id)
+ )
+ return bad()
+ return { job_id: text(data.job_id), deduplicated: data.deduplicated, operation: envelope.operation }
+}
--
2.52.0
From 56b8cabed9213911b6beb4aeaac9baa22e872a00 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Sat, 17 Oct 2026 19:02:13 +0800
Subject: [PATCH 06/14] =?UTF-8?q?feat(qaops):=20=E6=8E=A5=E5=85=A5?=
=?UTF-8?q?=E9=97=AE=E7=AD=94=E7=BB=84=E7=BB=87=E8=A1=A5=E5=85=A8=E4=B8=8E?=
=?UTF-8?q?=E5=8C=BA=E5=9F=9F=E4=BD=BF=E7=94=A8=E7=BB=9F=E8=AE=A1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
CHANGELOG.md | 7 +-
api/openapi.yaml | 1 +
internal/dobotaiops/organization_records.go | 102 ++++++++++
.../organization_records_integration_test.go | 71 +++++++
internal/dobotaiops/records.go | 88 +++++----
.../dobotaiops/records_integration_test.go | 1 +
.../dobotaiops/repository_integration_test.go | 2 +-
internal/dobotaiops/safety.go | 2 +-
internal/httpapi/qa_attribution.go | 185 ++++++++++++++++++
internal/httpapi/qa_attribution_test.go | 130 ++++++++++++
internal/httpapi/qa_ops.go | 16 ++
internal/httpapi/server.go | 1 +
internal/qaopsorg/attribution.go | 109 +++++++++++
internal/qaopsorg/attribution_test.go | 46 +++++
internal/qaopsorg/store_integration_test.go | 4 +
scripts/test-scope.json | 2 +
web/src/QAOperations.tsx | 109 ++++++++---
web/src/QAUsage.test.tsx | 36 ++++
web/src/QAUsage.tsx | 105 ++++++++++
web/src/qaAttribution.test.ts | 50 +++++
web/src/qaOps.css | 6 +
web/src/qaOps.ts | 95 ++++++++-
web/src/qaUsage.ts | 85 ++++++++
23 files changed, 1182 insertions(+), 71 deletions(-)
create mode 100644 internal/dobotaiops/organization_records.go
create mode 100644 internal/dobotaiops/organization_records_integration_test.go
create mode 100644 internal/httpapi/qa_attribution.go
create mode 100644 internal/httpapi/qa_attribution_test.go
create mode 100644 internal/qaopsorg/attribution.go
create mode 100644 internal/qaopsorg/attribution_test.go
create mode 100644 web/src/QAUsage.test.tsx
create mode 100644 web/src/QAUsage.tsx
create mode 100644 web/src/qaAttribution.test.ts
create mode 100644 web/src/qaUsage.ts
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f4eb152..bc10ccb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,12 +4,13 @@
### Added
+- 问答运营按稳定身份关联当前治理通讯录,缺失部门/区域补全并保留源快照及目录/区域版本;空列判断包含完整筛选结果,不混合配置已变化的分页。新增完整时间/关键词范围的使用统计,问答计次、名册内人员去重,跨区/未匹配/身份缺失分列,不输出绩效结论;不回写 DobotAI 原表。
- 「问答运营 → 区域使用」支持管理员从网页发起持久化通讯录同步,重复请求重放、进行中操作合并;按服务器固定范围注册后台执行器,未接线或未检测到心跳时不创建新任务。界面显示真实任务状态、不编造百分比;失败保留旧快照与区域规则,同步完成不覆盖未保存草稿。旧执行器丢失租约后不能激活结果,重启接管和已提交快照的续跑使用原任务。
-- 新增治理侧通讯录实时桥接,复用既有周报读取能力,向源端读取真实缺失祖先以补齐部门树;不改旧周报脚本、配置或输出。私有 JSON 与受控子进程执行器拒绝不完整数据、模拟同步、公开文件和异常输出,超时清理临时人员文件;问答组织关联尚未接入。同步默认关闭,容器启用仍需批准的既有周报 SDK/配置及兼容 Python 运行时挂载。
+- 新增治理侧通讯录实时桥接,复用既有周报读取能力,向源端读取真实缺失祖先以补齐部门树;不改旧周报脚本、配置或输出。私有 JSON 与受控子进程执行器拒绝不完整数据、模拟同步、公开文件和异常输出,超时清理临时人员文件。同步默认关闭,容器启用仍需批准的既有周报 SDK/配置及兼容 Python 运行时挂载。
- 区域归属表支持长部门路径换行,避免继承全局不换行规则后将生效区域与归属依据列挤出桌面面板。
-- **「问答运营 → 区域使用」区域归属配置切片**:按稳定部门 ID 搜索和勾选完整路径,预览去重归属人数,保存版本后重新读取;父部门包含子部门、子部门显式配置优先,多部门跨区域人员单独待核对。预览不写入,过期版本和不完整部门树被阻断。当前不是使用/绩效统计验收,翻译及 AI 评估模型接入按用户要求暂缓。
+- **「问答运营 → 区域使用」区域归属配置切片**:按稳定部门 ID 搜索和勾选完整路径,预览去重归属人数,保存版本后重新读取;父部门包含子部门、子部门显式配置优先,多部门跨区域人员单独待核对。预览不写入,过期版本和不完整部门树被阻断。基础使用统计见本期新增,不代表绩效验收;翻译及 AI 评估模型接入按用户要求暂缓。
- 新增治理侧组织快照与区域修订迁移、受确认保护的后台导入命令;不修改 DobotAI 原表或钉钉组织结构。
-- **「问答运营 → 问答记录」首个开发切片**:在现有导航中查看 DobotAI 2.0 钉钉问答,支持半开时间范围、原问题关键词、稳定游标分页和完整详情;按整个筛选结果隐藏空列,反馈聚合不放大问答条数。外语翻译、AI 评估、人员区域映射尚未接入,不标为第一阶段完成。
+- **「问答运营 → 问答记录」首个开发切片**:在现有导航中查看 DobotAI 2.0 钉钉问答,支持半开时间范围、原问题关键词、稳定游标分页和完整详情;按整个筛选结果隐藏空列,反馈聚合不放大问答条数。外语翻译、AI 评估尚未接入,不标为第一阶段完成。
- 治理侧重新检查答案:包含 `暂无已发布` 即未覆盖,引用和源端 covered 不能抵消;未命中仍待评估,源端规则单独保留作对照。独立只读源默认关闭、租户后端固定、管理员会话鉴权,源故障不回退治理主库;安全告警明确保留 TEMP/TLS 尚未整改状态。
- **「版本记录」页**(一级入口):只读时间线追踪**远端 main 可达的全部提交**(含合并提交与已并入 main 的侧分支提交),按提交时间倒序显示标题/正文、`[正式版本] / [开发版本] / [历史提交]` 徽标、短 SHA、提交内变更记录与 `[查看提交]`/`[查看 tag]`;支持「全部 / 正式 / 开发 / 历史」筛选与游标翻页,窄屏单列。
- 新增只读接口 `GET /api/v1/build-info`(当前运行产物的构建身份)、`GET /api/v1/version-history`(快照游标分页,不返回伪造的 total)、`POST /api/v1/version-history/sync`(仅管理员手动同步,并发同步复用同一作业)。
diff --git a/api/openapi.yaml b/api/openapi.yaml
index b858e90..3e806e9 100644
--- a/api/openapi.yaml
+++ b/api/openapi.yaml
@@ -99,6 +99,7 @@
}
}
},
+ "/api/v1/qa-ops/usage": {"get": {"tags": ["QA operations"], "operationId": "getQAOperationsUsage", "summary": "完整筛选范围内按当前通讯录和区域版本回看2.0问答使用;固定租户、管理员访问,不输出绩效结论", "parameters": [{"name": "start", "in": "query", "required": true, "schema": {"type": "string", "format": "date-time"}}, {"name": "end", "in": "query", "required": true, "schema": {"type": "string", "format": "date-time"}}, {"name": "keyword", "in": "query", "schema": {"type": "string", "maxLength": 200}}], "responses": {"200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"description": "需要登录"}, "403": {"description": "仅管理员访问"}, "503": {"description": "独立只读源或治理组织存储不可用,不返回伪造的零值"}, "500": {"$ref": "#/components/responses/InternalError"}}}},
"/api/v1/qa-ops/status": {
"get": {
"tags": ["QA operations"],
diff --git a/internal/dobotaiops/organization_records.go b/internal/dobotaiops/organization_records.go
new file mode 100644
index 0000000..aecb026
--- /dev/null
+++ b/internal/dobotaiops/organization_records.go
@@ -0,0 +1,102 @@
+package dobotaiops
+
+import (
+ "context"
+ "encoding/json"
+ "time"
+)
+
+// Actor keys are internal join material, never fields of the browser response.
+type ActorIdentity struct {
+ ActorID string `json:"actor_id"`
+ StaffID string `json:"staff_id"`
+ UnionID string `json:"union_id"`
+}
+type OrganizationVersion struct {
+ State string `json:"state"`
+ DirectoryID string `json:"directory_id"`
+ DirectorySource string `json:"directory_source"`
+ SyncedAt *time.Time `json:"synced_at"`
+ RevisionID string `json:"revision_id"`
+ Basis string `json:"basis"`
+}
+type RecordOrganization struct {
+ Version OrganizationVersion `json:"version"`
+ State string `json:"state"`
+ Departments []string `json:"departments"`
+ Region string `json:"region"`
+ SourceDepartment string `json:"source_department"`
+ SourceRegion string `json:"source_region"`
+ DepartmentOrigin string `json:"department_origin"`
+ RegionOrigin string `json:"region_origin"`
+}
+type UsageGroup struct {
+ Identity ActorIdentity `json:"-"`
+ Total int64
+ Succeeded int64
+ Failed int64
+}
+type UsageGroups struct {
+ Groups []UsageGroup `json:"-"`
+ AsOf time.Time
+}
+
+func decodeRecord(raw string) (Record, error) {
+ var wire struct {
+ Record
+ Identity ActorIdentity `json:"_identity"`
+ }
+ if err := json.Unmarshal([]byte(raw), &wire); err != nil {
+ return Record{}, err
+ }
+ wire.Record.Identity = wire.Identity
+ wire.Record.Coverage = CheckAnswerCoverage(wire.Record.Answer)
+ return wire.Record, nil
+}
+func (c *Client) ReadUsageGroups(ctx context.Context, query RecordQuery) (UsageGroups, error) {
+ if err := c.validateQueryWindow(query.Window); err != nil {
+ return UsageGroups{}, err
+ }
+ if query.Cursor != "" {
+ return UsageGroups{}, ErrInvalidQuery
+ }
+ pattern, patternErr := recordKeywordPattern(query.Keyword)
+ if patternErr != nil {
+ return UsageGroups{}, patternErr
+ }
+ result := UsageGroups{Groups: []UsageGroup{}}
+ err := c.withReadOnlyTx(ctx, func(ctx context.Context, q querier) error {
+ if q.QueryRow(ctx, "SELECT transaction_timestamp()").Scan(&result.AsOf) != nil {
+ return ErrUnavailable
+ }
+ rows, err := q.Query(ctx, recordsBaseSQL+` SELECT identity::text,count(*),count(*) FILTER(WHERE status='succeeded'),count(*) FILTER(WHERE status='failed') FROM records WHERE `+recordFilterSQL+` GROUP BY identity`, query.Window.TenantKey, query.Window.Start, query.Window.End, pattern)
+ if err != nil {
+ return ErrUnavailable
+ }
+ defer rows.Close()
+ for rows.Next() {
+ var raw string
+ var group UsageGroup
+ if rows.Scan(&raw, &group.Total, &group.Succeeded, &group.Failed) != nil || json.Unmarshal([]byte(raw), &group.Identity) != nil {
+ return ErrUnavailable
+ }
+ result.Groups = append(result.Groups, group)
+ }
+ return rows.Err()
+ })
+ return result, err
+}
+
+// Keep the agreed field ordering after governance enriches an initially empty column.
+func AddRecordColumns(page *RecordPage, extra ...string) {
+ all := map[string]bool{}
+ for _, col := range append(page.Columns, extra...) {
+ all[col] = true
+ }
+ page.Columns = []string{}
+ for _, col := range recordColumnOrder {
+ if all[col] {
+ page.Columns = append(page.Columns, col)
+ }
+ }
+}
diff --git a/internal/dobotaiops/organization_records_integration_test.go b/internal/dobotaiops/organization_records_integration_test.go
new file mode 100644
index 0000000..fd339d9
--- /dev/null
+++ b/internal/dobotaiops/organization_records_integration_test.go
@@ -0,0 +1,71 @@
+package dobotaiops
+
+import (
+ "context"
+ "encoding/json"
+ "strings"
+ "testing"
+ "time"
+)
+
+func TestQARecordInternalIdentityAndWholeFilterKeys(t *testing.T) {
+ pool := fixturePool(t)
+ dsn := qaRecordsFixture(t, pool)
+ execFixture(t, pool, `UPDATE messages SET actor_union_id_snapshot='fixture-union' WHERE id='msg-req-3'`, `UPDATE messages SET actor_id=NULL WHERE id='msg-req-4'`)
+ client := buildReadOnlyClient(t, dsn)
+ query := RecordQuery{Window: Window{TenantKey: "default", Start: time.Date(2026, 10, 14, 0, 0, 0, 0, time.UTC), End: time.Date(2026, 10, 15, 0, 0, 0, 0, time.UTC)}, Limit: 1}
+ page, err := client.ListRecords(context.Background(), query)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if page.Total != 4 || len(page.Items) != 1 || page.Items[0].Identity.StaffID != "" {
+ t.Fatal("fixture first page should be anonymous")
+ }
+ found := false
+ for _, actor := range page.ScopeActors {
+ if actor.StaffID == "ext-actor-1" && actor.UnionID == "fixture-union" {
+ found = true
+ }
+ }
+ if !found {
+ t.Fatal("whole-filter keys missing; later-page department would be hidden")
+ }
+ item, err := client.GetRecord(context.Background(), "default", "turn-3")
+ if err != nil || item.Identity.StaffID != "ext-actor-1" || item.Identity.UnionID != "fixture-union" {
+ t.Fatalf("stable identity not read from inbound actor/message: %v", err)
+ }
+ raw, _ := json.Marshal(page)
+ detail, _ := json.Marshal(item)
+ for _, s := range []string{string(raw), string(detail)} {
+ for _, private := range []string{"ext-actor-1", "fixture-union", "actor-row-1", "_identity", "scope_actors"} {
+ if strings.Contains(s, private) {
+ t.Fatal("internal roster key leaked into API JSON")
+ }
+ }
+ }
+}
+func TestQAUsageGroupsCountEventsOnceOverTheFullFilter(t *testing.T) {
+ pool := fixturePool(t)
+ dsn := qaRecordsFixture(t, pool)
+
+ client := buildReadOnlyClient(t, dsn)
+ query := RecordQuery{Window: Window{TenantKey: "default", Start: time.Date(2026, 10, 14, 0, 0, 0, 0, time.UTC), End: time.Date(2026, 10, 15, 0, 0, 0, 0, time.UTC)}}
+ result, err := client.ReadUsageGroups(context.Background(), query)
+ if err != nil {
+ t.Fatal(err)
+ }
+ var total, success, failed int64
+ for _, g := range result.Groups {
+ total += g.Total
+ success += g.Succeeded
+ failed += g.Failed
+ }
+ if total != 4 || success != 3 || failed != 1 || result.AsOf.IsZero() {
+ t.Fatalf("events multiplied/foreign tenant included: %d %d %d", total, success, failed)
+ }
+ query.Keyword = "%"
+ result, err = client.ReadUsageGroups(context.Background(), query)
+ if err != nil || len(result.Groups) != 0 {
+ t.Fatal("usage keyword wildcard not literal")
+ }
+}
diff --git a/internal/dobotaiops/records.go b/internal/dobotaiops/records.go
index ed494ff..71fef89 100644
--- a/internal/dobotaiops/records.go
+++ b/internal/dobotaiops/records.go
@@ -51,21 +51,23 @@ type RecordFeedback struct {
}
type Record struct {
- ID string `json:"id"`
- Status string `json:"status"`
- Question string `json:"question"`
- Answer string `json:"answer"`
- AskedAt time.Time `json:"asked_at"`
- TimeSource string `json:"time_source"`
- Asker string `json:"asker"`
- TriggerPerson string `json:"trigger_person"`
- Department string `json:"department"`
- Region string `json:"region"`
- References json.RawMessage `json:"references"`
- Media json.RawMessage `json:"media"`
- SourceCoverage SourceCoverage `json:"source_coverage"`
- Feedback RecordFeedback `json:"feedback"`
- Coverage CoverageCheck `json:"coverage"`
+ Identity ActorIdentity `json:"-"`
+ Organization *RecordOrganization `json:"organization,omitempty"`
+ ID string `json:"id"`
+ Status string `json:"status"`
+ Question string `json:"question"`
+ Answer string `json:"answer"`
+ AskedAt time.Time `json:"asked_at"`
+ TimeSource string `json:"time_source"`
+ Asker string `json:"asker"`
+ TriggerPerson string `json:"trigger_person"`
+ Department string `json:"department"`
+ Region string `json:"region"`
+ References json.RawMessage `json:"references"`
+ Media json.RawMessage `json:"media"`
+ SourceCoverage SourceCoverage `json:"source_coverage"`
+ Feedback RecordFeedback `json:"feedback"`
+ Coverage CoverageCheck `json:"coverage"`
}
type RecordQuery struct {
@@ -76,12 +78,14 @@ type RecordQuery struct {
}
type RecordPage struct {
- Items []Record `json:"items"`
- Columns []string `json:"columns"`
- Total int64 `json:"total"`
- HasMore bool `json:"has_more"`
- NextCursor string `json:"next_cursor"`
- AsOf time.Time `json:"as_of"`
+ ScopeActors []ActorIdentity `json:"-"`
+ Organization *OrganizationVersion `json:"organization,omitempty"`
+ Items []Record `json:"items"`
+ Columns []string `json:"columns"`
+ Total int64 `json:"total"`
+ HasMore bool `json:"has_more"`
+ NextCursor string `json:"next_cursor"`
+ AsOf time.Time `json:"as_of"`
}
type recordCursor struct {
@@ -92,10 +96,12 @@ type recordCursor struct {
// A single inbound-message join controls names/time. Feedback is preaggregated;
// joining each feedback row directly would multiply the business event count.
+const actorIdentitySQL = `jsonb_build_object('actor_id',COALESCE(a.id,''),'staff_id',COALESCE(a.external_actor_id,''),'union_id',COALESCE(m.actor_union_id_snapshot,''))`
const recordsBaseSQL = `
WITH records AS (
- SELECT t.id,COALESCE(m.created_at,t.created_at) AS asked_at,t.question,
+ SELECT t.id,COALESCE(m.created_at,t.created_at) AS asked_at,t.question,t.status,` + actorIdentitySQL + ` AS identity,
jsonb_build_object(
+ '_identity',` + actorIdentitySQL + `,
'id',t.id,'status',t.status,'question',t.question,'answer',t.answer,
'asked_at',COALESCE(m.created_at,t.created_at),
'time_source',CASE WHEN m.id IS NULL THEN 'turn.created_at' ELSE 'request_message.created_at' END,
@@ -137,15 +143,25 @@ const recordColumnsSQL = `SELECT count(*),jsonb_build_object(
'region',COALESCE(bool_or(payload->>'region'<>''),false),
'feedback',COALESCE(bool_or(payload->'feedback'->>'asker_value'<>'' OR
(payload->'feedback'->>'up')::bigint>0 OR (payload->'feedback'->>'down')::bigint>0),false)
- )::text FROM records WHERE `
+ )::text,COALESCE(jsonb_agg(DISTINCT identity),'[]'::jsonb)::text FROM records WHERE `
var recordColumnOrder = []string{"question_chinese", "answer", "coverage", "is_correct", "product_category", "problem_type", "root_cause", "asked_at", "asker", "question", "language", "trigger_person", "department", "region", "feedback"}
+func recordKeywordPattern(keyword string) (string, error) {
+ if !utf8.ValidString(keyword) || utf8.RuneCountInString(keyword) > 200 || strings.ContainsRune(keyword, 0) {
+ return "", ErrInvalidQuery
+ }
+ if keyword == "" {
+ return "", nil
+ }
+ return "%" + strings.NewReplacer(`\`, `\\`, `%`, `\%`, `_`, `\_`).Replace(keyword) + "%", nil
+}
+
func (c *Client) ListRecords(ctx context.Context, query RecordQuery) (RecordPage, error) {
if err := c.validateQueryWindow(query.Window); err != nil {
return RecordPage{}, err
}
- if query.Limit < 1 || query.Limit > 100 || !utf8.ValidString(query.Keyword) || utf8.RuneCountInString(query.Keyword) > 200 || strings.ContainsRune(query.Keyword, 0) || len(query.Cursor) > 2048 {
+ if query.Limit < 1 || query.Limit > 100 || len(query.Cursor) > 2048 {
return RecordPage{}, fmt.Errorf("%w: invalid record filters", ErrInvalidQuery)
}
scopeBytes, _ := json.Marshal([]string{query.Window.TenantKey, query.Window.Start.UTC().Format(time.RFC3339Nano), query.Window.End.UTC().Format(time.RFC3339Nano), query.Keyword})
@@ -160,9 +176,9 @@ func (c *Client) ListRecords(ctx context.Context, query RecordQuery) (RecordPage
}
before = cursor.AskedAt
}
- pattern := ""
- if query.Keyword != "" {
- pattern = "%" + strings.NewReplacer(`\`, `\\`, `%`, `\%`, `_`, `\_`).Replace(query.Keyword) + "%"
+ pattern, patternErr := recordKeywordPattern(query.Keyword)
+ if patternErr != nil {
+ return RecordPage{}, patternErr
}
args := []any{query.Window.TenantKey, query.Window.Start, query.Window.End, pattern}
page := RecordPage{Items: make([]Record, 0), Columns: make([]string, 0)}
@@ -170,11 +186,14 @@ func (c *Client) ListRecords(ctx context.Context, query RecordQuery) (RecordPage
if err := q.QueryRow(ctx, "SELECT transaction_timestamp()").Scan(&page.AsOf); err != nil {
return ErrUnavailable
}
- var rawColumns string
- if err := q.QueryRow(ctx, recordsBaseSQL+recordColumnsSQL+recordFilterSQL, append(args, noPublishedMarker)...).Scan(&page.Total, &rawColumns); err != nil {
+ var rawColumns, rawActors string
+ if err := q.QueryRow(ctx, recordsBaseSQL+recordColumnsSQL+recordFilterSQL, append(args, noPublishedMarker)...).Scan(&page.Total, &rawColumns, &rawActors); err != nil {
return fmt.Errorf("%w: record count failed", ErrUnavailable)
}
var available map[string]bool
+ if json.Unmarshal([]byte(rawActors), &page.ScopeActors) != nil {
+ return ErrUnavailable
+ }
if err := json.Unmarshal([]byte(rawColumns), &available); err != nil {
return ErrUnavailable
}
@@ -194,11 +213,11 @@ func (c *Client) ListRecords(ctx context.Context, query RecordQuery) (RecordPage
if err := rows.Scan(&raw); err != nil {
return ErrUnavailable
}
- var item Record
- if err := json.Unmarshal([]byte(raw), &item); err != nil {
+ item, err := decodeRecord(raw)
+ if err != nil {
return ErrUnavailable
}
- item.Coverage = CheckAnswerCoverage(item.Answer)
+
page.Items = append(page.Items, item)
}
return rows.Err()
@@ -233,10 +252,11 @@ func (c *Client) GetRecord(ctx context.Context, tenantKey, id string) (Record, e
if err != nil {
return ErrUnavailable
}
- if err := json.Unmarshal([]byte(raw), &item); err != nil {
+ item, err = decodeRecord(raw)
+ if err != nil {
return ErrUnavailable
}
- item.Coverage = CheckAnswerCoverage(item.Answer)
+
return nil
})
return item, err
diff --git a/internal/dobotaiops/records_integration_test.go b/internal/dobotaiops/records_integration_test.go
index 3056fd7..4e15daa 100644
--- a/internal/dobotaiops/records_integration_test.go
+++ b/internal/dobotaiops/records_integration_test.go
@@ -14,6 +14,7 @@ func qaRecordsFixture(t *testing.T, pool *pgxpool.Pool) string {
dsn := buildFixture(t, pool)
execFixture(t, pool,
`ALTER TABLE messages ADD COLUMN actor_name_snapshot text NOT NULL DEFAULT '', ADD COLUMN trigger_person_snapshot text NOT NULL DEFAULT '', ADD COLUMN media_json jsonb NOT NULL DEFAULT '[]'`,
+ `DROP TABLE IF EXISTS answer_feedback`,
`CREATE TABLE answer_feedback(id text PRIMARY KEY,tenant_key text,channel text,turn_id text,answer_message_id text,actor_id text,value text)`,
`GRANT SELECT ON answer_feedback TO kg_ro_fixture`,
`UPDATE messages SET actor_name_snapshot='测试人员',trigger_person_snapshot='回调昵称' WHERE id='msg-req-3'`,
diff --git a/internal/dobotaiops/repository_integration_test.go b/internal/dobotaiops/repository_integration_test.go
index 36669d5..3edaee6 100644
--- a/internal/dobotaiops/repository_integration_test.go
+++ b/internal/dobotaiops/repository_integration_test.go
@@ -84,7 +84,7 @@ func buildFixture(t *testing.T, pool *pgxpool.Pool) string {
question text NOT NULL DEFAULT '', answer text NOT NULL DEFAULT '', error_message text NOT NULL DEFAULT '',
created_at timestamptz NOT NULL)`,
`CREATE TABLE messages (id text PRIMARY KEY, tenant_key text NOT NULL, channel text NOT NULL, actor_id text,
- department_snapshot text NOT NULL DEFAULT '', region_snapshot text NOT NULL DEFAULT '',
+ department_snapshot text NOT NULL DEFAULT '', region_snapshot text NOT NULL DEFAULT '', actor_union_id_snapshot text NOT NULL DEFAULT '',
direction text NOT NULL DEFAULT '', role text NOT NULL DEFAULT '', message_type text NOT NULL DEFAULT '',
status text NOT NULL DEFAULT '', text_content text NOT NULL DEFAULT '', created_at timestamptz NOT NULL)`,
`CREATE TABLE coverage_decisions (id text PRIMARY KEY, tenant_key text NOT NULL, channel text NOT NULL,
diff --git a/internal/dobotaiops/safety.go b/internal/dobotaiops/safety.go
index 416b760..3ac652a 100644
--- a/internal/dobotaiops/safety.go
+++ b/internal/dobotaiops/safety.go
@@ -31,7 +31,7 @@ WITH relations AS (
('turns','references_json','jsonb'),('turns','knowledge_searched','bool'),
('turns','request_message_id','text'),('turns','answer_message_id','text'),
('messages','id','text'),('messages','actor_id','text'),('messages','department_snapshot','text'),
- ('messages','region_snapshot','text'),('channel_actors','id','text'),('channel_actors','external_actor_id','text'),
+ ('messages','region_snapshot','text'),('messages','actor_union_id_snapshot','text'),('channel_actors','id','text'),('channel_actors','external_actor_id','text'),
('coverage_decisions','turn_id','text'),('coverage_decisions','verdict','text')
)
SELECT jsonb_build_object(
diff --git a/internal/httpapi/qa_attribution.go b/internal/httpapi/qa_attribution.go
new file mode 100644
index 0000000..7aa967b
--- /dev/null
+++ b/internal/httpapi/qa_attribution.go
@@ -0,0 +1,185 @@
+package httpapi
+
+import (
+ "context"
+ "errors"
+ "knowledge-governance/internal/dobotaiops"
+ "knowledge-governance/internal/qaopsorg"
+ "net/http"
+ "strings"
+ "time"
+)
+
+var errQAOrganization = errors.New("organization attribution unavailable")
+
+type qaAttributionProvider interface {
+ GetAttribution(context.Context) (*qaopsorg.Attribution, error)
+}
+
+func recordAttribution(ctx context.Context, config Config) (*qaopsorg.Attribution, error) {
+ if config.QAOrg == nil {
+ return qaopsorg.BuildAttribution(qaopsorg.State{State: "empty"}, qaopsorg.Directory{})
+ }
+ provider, ok := config.QAOrg.(qaAttributionProvider)
+ if !ok {
+ return nil, errQAOrganization
+ }
+ p, err := provider.GetAttribution(ctx)
+ if err != nil || p == nil {
+ return nil, errQAOrganization
+ }
+ return p, nil
+}
+func attributionVersion(p *qaopsorg.Attribution) dobotaiops.OrganizationVersion {
+ return dobotaiops.OrganizationVersion{State: p.Metadata.State, DirectoryID: p.Metadata.DirectoryID, DirectorySource: p.Metadata.DirectorySource, SyncedAt: p.Metadata.DirectorySyncedAt, RevisionID: p.Metadata.RevisionID, Basis: "current_directory"}
+}
+func enrichQARecord(item *dobotaiops.Record, p *qaopsorg.Attribution) {
+ person := p.Resolve(item.Identity.StaffID, item.Identity.UnionID)
+ o := &dobotaiops.RecordOrganization{Version: attributionVersion(p), State: person.State, Departments: person.Departments, Region: person.Region, SourceDepartment: item.Department, SourceRegion: item.Region, DepartmentOrigin: "unavailable", RegionOrigin: "unavailable"}
+ if item.Department != "" {
+ o.DepartmentOrigin = "source_snapshot"
+ } else if len(person.Departments) > 0 {
+ item.Department = strings.Join(person.Departments, ";")
+ o.DepartmentOrigin = "current_directory"
+ }
+ if item.Region != "" {
+ o.RegionOrigin = "source_snapshot"
+ } else if person.Region != "" {
+ item.Region = person.Region
+ o.RegionOrigin = "current_directory"
+ }
+ item.Organization = o
+}
+func enrichQAPage(page *dobotaiops.RecordPage, p *qaopsorg.Attribution) {
+ version := attributionVersion(p)
+ page.Organization = &version
+ for i := range page.Items {
+ enrichQARecord(&page.Items[i], p)
+ }
+ for _, actor := range page.ScopeActors {
+ person := p.Resolve(actor.StaffID, actor.UnionID)
+ if len(person.Departments) > 0 {
+ dobotaiops.AddRecordColumns(page, "department")
+ }
+ if person.Region != "" {
+ dobotaiops.AddRecordColumns(page, "region")
+ }
+ }
+}
+
+type qaUsageReader interface {
+ ReadUsageGroups(context.Context, dobotaiops.RecordQuery) (dobotaiops.UsageGroups, error)
+}
+type qaUsageRow struct {
+ Key string `json:"key"`
+ Questions int64 `json:"questions"`
+ Succeeded int64 `json:"succeeded"`
+ Failed int64 `json:"failed"`
+ Other int64 `json:"other"`
+ Users *int `json:"users"`
+ RosterPeople *int `json:"roster_people"`
+}
+type qaUsage struct {
+ Organization dobotaiops.OrganizationVersion `json:"organization"`
+ AsOf time.Time `json:"as_of"`
+ Start time.Time `json:"start"`
+ End time.Time `json:"end"`
+ Keyword string `json:"keyword"`
+ Questions int64 `json:"questions"`
+ IdentifiedUsers int `json:"identified_users"`
+ Rows []qaUsageRow `json:"rows"`
+}
+
+func summarizeQAUsage(groups dobotaiops.UsageGroups, p *qaopsorg.Attribution, query dobotaiops.RecordQuery) qaUsage {
+ result := qaUsage{Organization: attributionVersion(p), AsOf: groups.AsOf, Start: query.Window.Start, End: query.Window.End, Keyword: query.Keyword, Rows: []qaUsageRow{}}
+ keys := append(append([]string{}, qaopsorg.RegionNames...), "unassigned", "cross_region", "unmatched", "identity_conflict", "no_identity", "directory_missing")
+ rows := map[string]*qaUsageRow{}
+ members := map[string]map[string]bool{}
+ all := map[string]bool{}
+ for _, key := range keys {
+ row := &qaUsageRow{Key: key}
+ if p.Metadata.State == "ready" {
+ var n int
+ valid := true
+ switch key {
+ case "unassigned":
+ n = p.Metadata.View.UnassignedPeople
+ case "cross_region":
+ n = p.Metadata.View.ConflictingPeople
+ default:
+ var ok bool
+ n, ok = p.Metadata.View.Regions[key]
+ valid = ok
+ }
+ if valid {
+ row.RosterPeople = &n
+ row.Users = new(int)
+ }
+ }
+ rows[key] = row
+ members[key] = map[string]bool{}
+ }
+ for _, group := range groups.Groups {
+ person := p.Resolve(group.Identity.StaffID, group.Identity.UnionID)
+ key := person.State
+ if person.Region != "" {
+ key = person.Region
+ }
+ row := rows[key]
+ if row == nil {
+ continue
+ }
+ row.Questions += group.Total
+ row.Succeeded += group.Succeeded
+ row.Failed += group.Failed
+ row.Other += group.Total - group.Succeeded - group.Failed
+ result.Questions += group.Total
+ if person.PersonID != "" {
+ members[key][person.PersonID] = true
+ all[person.PersonID] = true
+ }
+ }
+ for _, key := range keys {
+ row := rows[key]
+ if row.Users != nil {
+ *row.Users = len(members[key])
+ }
+ result.Rows = append(result.Rows, *row)
+ }
+ result.IdentifiedUsers = len(all)
+ return result
+}
+func qaOpsUsage(w http.ResponseWriter, r *http.Request, config Config) {
+ if !authorizeQAOps(w, r) {
+ return
+ }
+ reader, ok := config.QAOps.(qaUsageReader)
+ if !ok || config.QAOpsTenantKey == "" {
+ qaOpsError(w, dobotaiops.ErrUnavailable)
+ return
+ }
+ values := r.URL.Query()
+ for key, items := range values {
+ if (key != "start" && key != "end" && key != "keyword") || len(items) != 1 {
+ qaOpsError(w, dobotaiops.ErrInvalidQuery)
+ return
+ }
+ }
+ window, err := dobotaiops.NewWindow(config.QAOpsTenantKey, values.Get("start"), values.Get("end"), 90*24*time.Hour, config.Now())
+ if err != nil {
+ qaOpsError(w, err)
+ return
+ }
+ p, err := recordAttribution(r.Context(), config)
+ if err != nil {
+ qaOpsError(w, err)
+ return
+ }
+ query := dobotaiops.RecordQuery{Window: window, Keyword: values.Get("keyword")}
+ groups, err := reader.ReadUsageGroups(r.Context(), query)
+ if err != nil {
+ qaOpsError(w, err)
+ return
+ }
+ writeJSON(w, 200, map[string]any{"data": summarizeQAUsage(groups, p, query)})
+}
diff --git a/internal/httpapi/qa_attribution_test.go b/internal/httpapi/qa_attribution_test.go
new file mode 100644
index 0000000..082cb26
--- /dev/null
+++ b/internal/httpapi/qa_attribution_test.go
@@ -0,0 +1,130 @@
+package httpapi
+
+import (
+ "context"
+ "encoding/json"
+ "knowledge-governance/internal/dobotaiops"
+ "knowledge-governance/internal/qaopsorg"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+ "time"
+)
+
+type attributionOrgSpy struct {
+ orgSpy
+ projection *qaopsorg.Attribution
+}
+
+func (s *attributionOrgSpy) GetAttribution(context.Context) (*qaopsorg.Attribution, error) {
+ return s.projection, s.err
+}
+
+type attributedReader struct{}
+
+func (*attributedReader) Available(context.Context) error { return nil }
+func (*attributedReader) Safety() dobotaiops.SourceSafety { return dobotaiops.SourceSafety{SSL: true} }
+func (*attributedReader) ListRecords(context.Context, dobotaiops.RecordQuery) (dobotaiops.RecordPage, error) {
+ return dobotaiops.RecordPage{Items: []dobotaiops.Record{{ID: "anonymous"}}, ScopeActors: []dobotaiops.ActorIdentity{{StaffID: "fixture-private-staff"}}, Columns: []string{"question"}, Total: 3}, nil
+}
+func (*attributedReader) GetRecord(context.Context, string, string) (dobotaiops.Record, error) {
+ return dobotaiops.Record{ID: "one", Department: "历史部门", Region: "历史区域", Identity: dobotaiops.ActorIdentity{StaffID: "fixture-private-staff"}}, nil
+}
+func (*attributedReader) ReadUsageGroups(context.Context, dobotaiops.RecordQuery) (dobotaiops.UsageGroups, error) {
+ return dobotaiops.UsageGroups{AsOf: time.Date(2026, 10, 15, 0, 0, 0, 0, time.UTC), Groups: []dobotaiops.UsageGroup{{Identity: dobotaiops.ActorIdentity{StaffID: "fixture-private-staff"}, Total: 3, Succeeded: 2, Failed: 1}, {Identity: dobotaiops.ActorIdentity{UnionID: "fixture-private-union"}, Total: 2, Succeeded: 2}, {Identity: dobotaiops.ActorIdentity{StaffID: "unmatched"}, Total: 2}}}, nil
+}
+func attributionHandler(t *testing.T) (http.Handler, *attributionOrgSpy) {
+ t.Helper()
+ projection, err := qaopsorg.BuildAttribution(qaopsorg.State{State: "ready", DirectoryID: "directory-v1", RevisionID: "region-v1", Rules: []qaopsorg.Rule{{DepartmentID: "root", Region: "APAC"}}}, qaopsorg.Directory{Departments: []qaopsorg.Department{{ID: "root", Name: "测试公司"}}, People: []qaopsorg.Person{{ID: "fixture-private-staff", UnionID: "fixture-private-union", DepartmentIDs: []string{"root"}}}})
+ if err != nil {
+ t.Fatal(err)
+ }
+ org := &attributionOrgSpy{projection: projection}
+ auth := newFakeAuthStore()
+ auth.sessions["attribution-admin"] = "usr-boss"
+ auth.sessions["attribution-viewer"] = "usr-eye"
+ h, err := NewHandler(Config{Store: &fakeJobStore{}, Auth: &AuthConfig{Store: auth}, QAOps: &attributedReader{}, QAOpsTenantKey: "fixed", QAOrg: org, Now: func() time.Time { return time.Date(2026, 10, 17, 0, 0, 0, 0, time.UTC) }})
+ if err != nil {
+ t.Fatal(err)
+ }
+ return h, org
+}
+func attributionRequest(h http.Handler, path, token string) *httptest.ResponseRecorder {
+ r := httptest.NewRequest("GET", path, nil)
+ r.AddCookie(&http.Cookie{Name: sessionCookieName, Value: token})
+ w := httptest.NewRecorder()
+ h.ServeHTTP(w, r)
+ return w
+}
+
+const attributionFilter = "?start=2026-10-14T00:00:00Z&end=2026-10-15T00:00:00Z"
+
+func TestQAAttributionUsesWholeFilterAndPreservesHistoricalSnapshots(t *testing.T) {
+ h, org := attributionHandler(t)
+ w := attributionRequest(h, "/api/v1/qa-ops/records"+attributionFilter, "attribution-admin")
+ if w.Code != 200 {
+ t.Fatal(w.Code, w.Body.String())
+ }
+ var page struct{ Data dobotaiops.RecordPage }
+ _ = json.Unmarshal(w.Body.Bytes(), &page)
+ if !strings.Contains(strings.Join(page.Data.Columns, ","), "department,region") {
+ t.Fatal("organization column hidden because first page is anonymous", w.Body.String())
+ }
+ w = attributionRequest(h, "/api/v1/qa-ops/records/one", "attribution-admin")
+ var detail struct{ Data dobotaiops.Record }
+ _ = json.Unmarshal(w.Body.Bytes(), &detail)
+ if detail.Data.Department != "历史部门" || detail.Data.Region != "历史区域" || detail.Data.Organization == nil || detail.Data.Organization.Region != "APAC" {
+ t.Fatal("source snapshot overwritten or current attribution missing", w.Body.String())
+ }
+ if strings.Contains(w.Body.String(), "fixture-private") {
+ t.Fatal("identity keys exposed")
+ }
+ org.err = qaopsorg.ErrUnavailable
+ w = attributionRequest(h, "/api/v1/qa-ops/records"+attributionFilter, "attribution-admin")
+ if w.Code != 503 || !strings.Contains(w.Body.String(), "organization_unavailable") {
+ t.Fatal("permission/storage failure hidden as empty", w.Body.String())
+ }
+}
+func TestQAUsageIsAdminScopedDeduplicatedAndNotPerformance(t *testing.T) {
+ h, _ := attributionHandler(t)
+ path := "/api/v1/qa-ops/usage" + attributionFilter
+ for _, tc := range []struct {
+ token string
+ status int
+ }{{"", 401}, {"attribution-viewer", 403}, {"attribution-admin", 200}} {
+ w := attributionRequest(h, path, tc.token)
+ if w.Code != tc.status {
+ t.Fatalf("usage guard got %d: %s", w.Code, w.Body.String())
+ }
+ if tc.status == 200 {
+ var result struct {
+ Data struct {
+ Questions int64 `json:"questions"`
+ IdentifiedUsers int `json:"identified_users"`
+ Rows []struct {
+ Key string
+ Questions int64
+ Users *int
+ }
+ }
+ }
+ if json.Unmarshal(w.Body.Bytes(), &result) != nil || result.Data.Questions != 7 || result.Data.IdentifiedUsers != 1 {
+ t.Fatal("events/people not deduplicated", w.Body.String())
+ }
+ for _, row := range result.Data.Rows {
+ if row.Key == "APAC" && (row.Questions != 5 || row.Users == nil || *row.Users != 1) {
+ t.Fatal("regional user double-counted")
+ }
+ }
+ if strings.Contains(w.Body.String(), "fixture-private") || strings.Contains(w.Body.String(), "performance") {
+ t.Fatal("private identity or performance verdict leaked")
+ }
+ }
+ }
+ for _, extra := range []string{"&tenant=forged", "&limit=1", "&cursor=forged", "&start=duplicate"} {
+ if w := attributionRequest(h, path+extra, "attribution-admin"); w.Code != 400 {
+ t.Fatal("usage accepted client scope or pagination")
+ }
+ }
+}
diff --git a/internal/httpapi/qa_ops.go b/internal/httpapi/qa_ops.go
index 402841b..9fb8ac7 100644
--- a/internal/httpapi/qa_ops.go
+++ b/internal/httpapi/qa_ops.go
@@ -93,11 +93,17 @@ func listQAOpsRecords(w http.ResponseWriter, r *http.Request, config Config) {
return
}
}
+ projection, err := recordAttribution(r.Context(), config)
+ if err != nil {
+ qaOpsError(w, err)
+ return
+ }
page, err := config.QAOps.ListRecords(r.Context(), dobotaiops.RecordQuery{Window: window, Keyword: values.Get("keyword"), Cursor: values.Get("cursor"), Limit: limit})
if err != nil {
qaOpsError(w, err)
return
}
+ enrichQAPage(&page, projection)
writeJSON(w, http.StatusOK, map[string]any{"data": page})
}
@@ -113,11 +119,17 @@ func getQAOpsRecord(w http.ResponseWriter, r *http.Request, config Config) {
qaOpsError(w, dobotaiops.ErrInvalidQuery)
return
}
+ projection, err := recordAttribution(r.Context(), config)
+ if err != nil {
+ qaOpsError(w, err)
+ return
+ }
item, err := config.QAOps.GetRecord(r.Context(), config.QAOpsTenantKey, r.PathValue("id"))
if err != nil {
qaOpsError(w, err)
return
}
+ enrichQARecord(&item, projection)
writeJSON(w, http.StatusOK, map[string]any{"data": item})
}
@@ -125,6 +137,10 @@ func qaOpsError(w http.ResponseWriter, err error) {
status := http.StatusServiceUnavailable
code := "source_unavailable"
message := "问答数据源不可用,请检查独立只读连接;原有知识治理功能不受影响"
+ if errors.Is(err, errQAOrganization) {
+ code = "organization_unavailable"
+ message = "通讯录或区域配置读取失败,未将不可用数据伪装成空列,请重试"
+ }
if errors.Is(err, dobotaiops.ErrInvalidQuery) {
status = http.StatusBadRequest
code = "invalid_query"
diff --git a/internal/httpapi/server.go b/internal/httpapi/server.go
index ba009af..5aca0a9 100644
--- a/internal/httpapi/server.go
+++ b/internal/httpapi/server.go
@@ -175,6 +175,7 @@ func NewHandler(config Config) (http.Handler, error) {
config.NewID = newID
}
mux := http.NewServeMux()
+ mux.HandleFunc("GET /api/v1/qa-ops/usage", func(w http.ResponseWriter, r *http.Request) { qaOpsUsage(w, r, config) })
mux.HandleFunc("GET /api/v1/qa-ops/organization/sync", func(w http.ResponseWriter, r *http.Request) { qaOrganizationSync(w, r, config) })
mux.HandleFunc("POST /api/v1/qa-ops/organization/sync", func(w http.ResponseWriter, r *http.Request) { qaOrganizationSync(w, r, config) })
mux.HandleFunc("GET /api/v1/qa-ops/organization", func(w http.ResponseWriter, r *http.Request) { qaOrganization(w, r, config) })
diff --git a/internal/qaopsorg/attribution.go b/internal/qaopsorg/attribution.go
new file mode 100644
index 0000000..bba1850
--- /dev/null
+++ b/internal/qaopsorg/attribution.go
@@ -0,0 +1,109 @@
+package qaopsorg
+
+import (
+ "context"
+ "sort"
+)
+
+type PersonAttribution struct {
+ State string `json:"state"`
+ PersonID string `json:"-"`
+ Departments []string `json:"departments"`
+ Region string `json:"region"`
+}
+type Attribution struct {
+ Metadata State
+ people map[string]PersonAttribution
+ unions map[string]string
+}
+
+func BuildAttribution(state State, directory Directory) (*Attribution, error) {
+ p := &Attribution{Metadata: state, people: map[string]PersonAttribution{}, unions: map[string]string{}}
+ if state.State == "empty" {
+ return p, nil
+ }
+ if state.State != "ready" || state.DirectoryID == "" {
+ return nil, ErrUnavailable
+ }
+ view, err := Preview(directory, state.Rules)
+ if err != nil {
+ return nil, ErrUnavailable
+ }
+ p.Metadata.View = view
+ departments := map[string]DepartmentView{}
+ for _, d := range view.Departments {
+ departments[d.ID] = d
+ }
+ for _, person := range directory.People {
+ paths, regions := map[string]bool{}, map[string]bool{}
+ for _, id := range person.DepartmentIDs {
+ d := departments[id]
+ paths[d.Path] = true
+ if d.Region != "" {
+ regions[d.Region] = true
+ }
+ }
+ item := PersonAttribution{State: "unassigned", PersonID: person.ID, Departments: []string{}}
+ for path := range paths {
+ item.Departments = append(item.Departments, path)
+ }
+ sort.Strings(item.Departments)
+ if len(regions) == 1 {
+ item.State = "matched"
+ for region := range regions {
+ item.Region = region
+ }
+ } else if len(regions) > 1 {
+ item.State = "cross_region"
+ }
+ p.people[person.ID] = item
+ if person.UnionID != "" {
+ if !validID(person.UnionID) {
+ return nil, ErrUnavailable
+ }
+ if _, ok := p.unions[person.UnionID]; ok {
+ p.unions[person.UnionID] = ""
+ } else {
+ p.unions[person.UnionID] = person.ID
+ }
+ }
+ }
+ return p, nil
+}
+func (p *Attribution) Resolve(staff, union string) PersonAttribution {
+ none := PersonAttribution{State: "unmatched", Departments: []string{}}
+ if p == nil || p.Metadata.State != "ready" {
+ none.State = "directory_missing"
+ return none
+ }
+ if staff == "" && union == "" {
+ none.State = "no_identity"
+ return none
+ }
+ byUnion, unionKnown := p.unions[union]
+ if person, ok := p.people[staff]; ok {
+ if unionKnown && (byUnion == "" || byUnion != staff) {
+ none.State = "identity_conflict"
+ return none
+ }
+ return person
+ }
+ if unionKnown {
+ if byUnion == "" {
+ none.State = "identity_conflict"
+ return none
+ }
+ return p.people[byUnion]
+ }
+ return none
+}
+func (s *Store) GetAttribution(ctx context.Context) (*Attribution, error) {
+ if !s.available() {
+ return nil, ErrUnavailable
+ }
+ state, directory, err := s.read(ctx, s.pool, false)
+ if err != nil {
+ return nil, err
+ }
+ return BuildAttribution(state, directory)
+}
diff --git a/internal/qaopsorg/attribution_test.go b/internal/qaopsorg/attribution_test.go
new file mode 100644
index 0000000..bf61b1c
--- /dev/null
+++ b/internal/qaopsorg/attribution_test.go
@@ -0,0 +1,46 @@
+package qaopsorg
+
+import (
+ "context"
+ "errors"
+ "testing"
+)
+
+func TestAttributionUsesStableIdentityAndKeepsAmbiguitiesExplicit(t *testing.T) {
+ d := Directory{Departments: []Department{{ID: "root", Name: "fixture"}, {ID: "a", ParentID: "root", Name: "one"}, {ID: "b", ParentID: "root", Name: "two"}}, People: []Person{{ID: "staff-a", UnionID: "union-a", DepartmentIDs: []string{"a", "a"}}, {ID: "staff-cross", UnionID: "union-cross", DepartmentIDs: []string{"a", "b"}}, {ID: "duplicate-one", UnionID: "duplicate", DepartmentIDs: []string{"a"}}, {ID: "duplicate-two", UnionID: "duplicate", DepartmentIDs: []string{"b"}}}}
+ p, err := BuildAttribution(State{State: "ready", DirectoryID: "d", RevisionID: "r", Rules: []Rule{{DepartmentID: "root", Region: "国内工业"}, {DepartmentID: "b", Region: "APAC"}}}, d)
+ if err != nil {
+ t.Fatal(err)
+ }
+ for _, key := range [][2]string{{"staff-a", ""}, {"", "union-a"}} {
+ got := p.Resolve(key[0], key[1])
+ if got.State != "matched" || got.Region != "国内工业" || len(got.Departments) != 1 || got.PersonID != "staff-a" {
+ t.Fatalf("stable identity not resolved/deduplicated: %+v", got)
+ }
+ }
+ if got := p.Resolve("staff-cross", ""); got.State != "cross_region" || got.Region != "" || len(got.Departments) != 2 {
+ t.Fatalf("invented primary region: %+v", got)
+ }
+ if got := p.Resolve("", "duplicate"); got.State != "identity_conflict" {
+ t.Fatalf("duplicate union selected first person: %+v", got)
+ }
+ if got := p.Resolve("staff-a", "union-cross"); got.State != "identity_conflict" {
+ t.Fatalf("contradictory identifiers silently preferred: %+v", got)
+ }
+ if got := p.Resolve("absent", ""); got.State != "unmatched" {
+ t.Fatalf("unknown identity inferred: %+v", got)
+ }
+ if got := p.Resolve("", ""); got.State != "no_identity" {
+ t.Fatalf("anonymous identity inferred: %+v", got)
+ }
+}
+func TestAttributionDoesNotTreatMissingDirectoryAsPermissionSuccess(t *testing.T) {
+ p, err := BuildAttribution(State{State: "empty"}, Directory{})
+ if err != nil || p.Resolve("staff", "").State != "directory_missing" {
+ t.Fatal("missing directory not explicit")
+ }
+ var store *Store
+ if _, err = store.GetAttribution(context.Background()); !errors.Is(err, ErrUnavailable) {
+ t.Fatal("unavailable store returned an empty directory")
+ }
+}
diff --git a/internal/qaopsorg/store_integration_test.go b/internal/qaopsorg/store_integration_test.go
index 6af53ac..8882a92 100644
--- a/internal/qaopsorg/store_integration_test.go
+++ b/internal/qaopsorg/store_integration_test.go
@@ -62,6 +62,10 @@ func TestOrganizationStoreRoundTripAndOptimisticConflict(t *testing.T) {
if err != nil || read.RevisionID != saved.RevisionID || read.View.Regions["国内工业"] != 1 {
t.Fatal("saved rules not consumed by read path")
}
+ projection, projectionErr := store.GetAttribution(ctx)
+ if projectionErr != nil || projection.Metadata.DirectoryID != read.DirectoryID || projection.Metadata.RevisionID != read.RevisionID || projection.Resolve("u2", "").Region != "APAC" {
+ t.Fatal("attribution did not consume the saved directory/region revision")
+ }
if _, err = store.SaveRules(ctx, request, "stale-admin"); !errors.Is(err, qaopsorg.ErrConflict) {
t.Fatalf("stale update overwrote newer rules: %v", err)
}
diff --git a/scripts/test-scope.json b/scripts/test-scope.json
index 7105950..9fbb0f8 100644
--- a/scripts/test-scope.json
+++ b/scripts/test-scope.json
@@ -9,6 +9,8 @@
"⚠️ 文件缺失或解析不了 ⇒ 门禁红:范围声明不出来时,不许默认放行。"
],
"optional": [
+ {"package": "knowledge-governance/internal/dobotaiops", "test": "TestQARecordInternalIdentityAndWholeFilterKeys", "reason": "必须显式一次性隔离PG;验证真实只读SQL身份关联/计数及隐私,不连接生产;默认无库时明确跳过,另行本地补验"},
+ {"package": "knowledge-governance/internal/dobotaiops", "test": "TestQAUsageGroupsCountEventsOnceOverTheFullFilter", "reason": "必须显式一次性隔离PG;验证真实只读SQL身份关联/计数及隐私,不连接生产;默认无库时明确跳过,另行本地补验"},
{
"package": "knowledge-governance/internal/qaopsorg",
"test": "TestDirectorySyncQueueDurableReplayAndLeaseFencing",
diff --git a/web/src/QAOperations.tsx b/web/src/QAOperations.tsx
index 134a26d..bf8a080 100644
--- a/web/src/QAOperations.tsx
+++ b/web/src/QAOperations.tsx
@@ -1,10 +1,12 @@
import { useEffect, useRef, useState } from 'react'
import type { FormEvent } from 'react'
import { useOptionalAuth } from './auth'
-import { fetchQARecord, fetchQARecords, fetchQAStatus, qaCellValue, qaColumns } from './qaOps'
+import { fetchQARecord, fetchQARecords, fetchQAStatus, mergeQAPages, qaCellValue, qaColumns } from './qaOps'
import type { QAQuery, QARecord, QARecordPage, QAStatus } from './qaOps'
import './qaOps.css'
import { QARegions } from './QARegions'
+import { QAUsage } from './QAUsage'
+import { usageLabels } from './qaUsage'
interface ViewProps {
page: QARecordPage | null
@@ -48,6 +50,13 @@ export function QAOperationsView(props: ViewProps) {
DobotAI 2.0 / 钉钉 · 独立只读连接{props.status ? ` · ${stateLabels[props.status.state]}` : ''}
+ {page?.organization ? (
+
+ {page.organization.state === 'ready'
+ ? `缺失组织信息按当前通讯录补全(${stamp(page.organization.synced_at!)}),不代表提问时归属。目录:${page.organization.directory_id};区域版本:${page.organization.revision_id || '未保存'}`
+ : '尚无完整通讯录,仅展示源端已有组织快照,不根据姓名推断。'}
+
+ ) : null}
{props.status?.warnings.map((warning) => (
{warningLabels[warning] ?? '数据源有待审核的安全告警'}
@@ -79,7 +88,9 @@ export function QAOperationsView(props: ViewProps) {
提问人
{detail.asker || '未关联'}
+ 部门
+
+ {detail.department || '未匹配'}
+ {detail.organization?.department_origin === 'current_directory' ? '(当前通讯录补全)' : ''}
+
+ 区域
+
+ {detail.region || '未配置/待核对'}
+ {detail.organization?.region_origin === 'current_directory' ? '(当前配置补全)' : ''}
+
+ {detail.organization ? (
+ <>
+ 当前组织关联
+
+ {detail.organization.state === 'matched'
+ ? '已关联'
+ : (usageLabels[detail.organization.state] ?? detail.organization.state)}
+
+ 当前通讯录部门/区域
+
+ {detail.organization.departments.join(';') || '未匹配'} /{' '}
+ {detail.organization.region || '未配置或待核对'}
+
+ 组织版本
+
+ {detail.organization.version.directory_id || '无完整目录'} /{' '}
+ {detail.organization.version.revision_id || '未保存区域配置'}
+
+ 源端组织快照
+
+ {detail.organization.source_department || '空'} / {detail.organization.source_region || '空'}
+
+ >
+ ) : null}
问答状态
{statusLabels[detail.status] ?? detail.status}
流程触发人员信息
@@ -230,7 +275,7 @@ function initialDraft() {
}
export function QAOperations() {
- const [view, setView] = useState<'records' | 'regions'>('records')
+ const [view, setView] = useState<'records' | 'regions' | 'usage'>('records')
const auth = useOptionalAuth()
const canRead = auth?.identity?.role === 'admin'
const [draft, setDraft] = useState(initialDraft)
@@ -260,6 +305,13 @@ export function QAOperations() {
useEffect(() => {
if (!query || !canRead) return
+ if (view !== 'records') {
+ setLoading(false)
+ moreRequest.current?.abort()
+ detailRequest.current?.abort()
+ setDetail(null)
+ return
+ }
const controller = new AbortController()
generation.current += 1
moreRequest.current?.abort()
@@ -286,7 +338,7 @@ export function QAOperations() {
if (!controller.signal.aborted) setLoading(false)
})
return () => controller.abort()
- }, [query, canRead, revision])
+ }, [query, canRead, revision, view])
useEffect(
() => () => {
@@ -341,17 +393,7 @@ export function QAOperations() {
try {
const result = await fetchQARecords({ ...query, cursor: page.next_cursor }, controller.signal)
if (!controller.signal.aborted && currentGeneration === generation.current) {
- setPage((current) =>
- current
- ? {
- ...result,
- items: [
- ...current.items,
- ...result.items.filter((item) => !current.items.some(({ id }) => id === item.id)),
- ],
- }
- : result
- )
+ setPage(mergeQAPages(page, result))
}
} catch (reason) {
if (!controller.signal.aborted && currentGeneration === generation.current)
@@ -364,7 +406,7 @@ export function QAOperations() {
@@ -378,6 +420,9 @@ export function QAOperations() {
+
@@ -420,21 +465,25 @@ export function QAOperations() {
- 当前切片:问答查询与覆盖复检。外语翻译、AI评估及人员映射尚未接入;空值不默认填“否”。
+ 部门/区域保留源快照,缺失时按当前通讯录补全;使用统计不是绩效结论。外语翻译与AI评估仍暂缓,空值不默认填“否”。
- void select(id)}
- onCloseDetail={close}
- onLoadMore={() => void loadMore()}
- onRetry={() => setRevision((value) => value + 1)}
- />
+ {view === 'usage' ? (
+
+ ) : (
+ void select(id)}
+ onCloseDetail={close}
+ onLoadMore={() => void loadMore()}
+ onRetry={() => setRevision((value) => value + 1)}
+ />
+ )}
>
)}
>
diff --git a/web/src/QAUsage.test.tsx b/web/src/QAUsage.test.tsx
new file mode 100644
index 0000000..294f53c
--- /dev/null
+++ b/web/src/QAUsage.test.tsx
@@ -0,0 +1,36 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+import { describe, expect, it } from 'vitest'
+import { QAUsageView } from './QAUsage'
+import { parseQAUsage } from './qaUsage'
+const usage = parseQAUsage({
+ organization: {
+ state: 'ready',
+ directory_id: 'd',
+ directory_source: 'weekly_report_live',
+ synced_at: '2026-10-17T07:59:50Z',
+ revision_id: 'r',
+ basis: 'current_directory',
+ },
+ as_of: '2026-10-17T08:00:00Z',
+ start: '2026-10-14T00:00:00Z',
+ end: '2026-10-15T00:00:00Z',
+ keyword: '',
+ questions: 2,
+ identified_users: 0,
+ rows: [{ key: 'unmatched', questions: 2, succeeded: 1, failed: 1, other: 0, users: null, roster_people: null }],
+})
+describe('usage statistics evidence', () => {
+ it('shows a current-roster basis and unknown counts without performance claims', () => {
+ const html = renderToStaticMarkup( {}} />)
+ expect(html).toContain('按当前通讯录回看')
+ expect(html).toContain('名册未匹配')
+ expect(html).toContain('不可确定')
+ expect(html).not.toContain('达标率')
+ expect(html).not.toContain('绩效合格')
+ })
+ it('keeps unavailable data an error, not a zero-result report', () => {
+ const html = renderToStaticMarkup( {}} />)
+ expect(html).toContain('上游不可用')
+ expect(html).not.toContain('共 0 条')
+ })
+})
diff --git a/web/src/QAUsage.tsx b/web/src/QAUsage.tsx
new file mode 100644
index 0000000..9dc0d9d
--- /dev/null
+++ b/web/src/QAUsage.tsx
@@ -0,0 +1,105 @@
+import { useEffect, useState } from 'react'
+import type { QAQuery } from './qaOps'
+import { fetchQAUsage, usageLabels } from './qaUsage'
+import type { QAUsage as Usage } from './qaUsage'
+interface Props {
+ data: Usage | null
+ loading: boolean
+ error: string
+ onRetry: () => void
+}
+const stamp = (v: string) => new Date(v).toLocaleString('zh-CN', { hour12: false })
+export function QAUsageView({ data, loading, error, onRetry }: Props) {
+ return (
+
+
+ 按当前通讯录回看历史问答,不代表提问时的组织归属。成功/失败是源端运行状态,不等于答案正确;不输出绩效结论。
+
+ {loading ? 正在读取完整筛选范围的使用统计… : null}
+ {error ? (
+
+ {error}{' '}
+
+
+ ) : null}
+ {data && !error ? (
+ <>
+
+
+ 共 {data.questions} 条问答 · 已关联提问人数 {data.identified_users}
+
+ 统计截止读取时间:{stamp(data.as_of)}
+
+
+ 范围:{stamp(data.start)} 至 {stamp(data.end)}(不含结束时刻)
+ {data.keyword ? ` · 原问题包含:${data.keyword}` : ''}
+
+
+ {data.organization.state === 'ready'
+ ? `通讯录同步:${stamp(data.organization.synced_at!)} · 目录 ${data.organization.directory_id} · 区域配置 ${data.organization.revision_id || '尚未保存'}`
+ : '尚无完整通讯录,当前不能确定部门区域或去重人数。'}
+
+
+
+
+
+ | 区域/待核对状态 |
+ 问答条数 |
+ 成功 |
+ 失败 |
+ 其他状态 |
+ 已关联提问人数 |
+ 通讯录归属人数 |
+
+
+
+ {data.rows.map((row) => (
+
+ | {usageLabels[row.key]} |
+ {row.questions} |
+ {row.succeeded} |
+ {row.failed} |
+ {row.other} |
+ {row.users ?? '不可确定'} |
+ {row.roster_people ?? '不适用'} |
+
+ ))}
+
+
+
+
+ 按问答唯一 ID 计次;同一名册人员的多部门、多个身份记录只计 1
+ 人。未匹配或身份冲突不编造人数;通讯录人数不是在职或考核人数。
+
+ >
+ ) : null}
+
+ )
+}
+export function QAUsage({ query }: { query: QAQuery | null }) {
+ const [data, setData] = useState(null),
+ [loading, setLoading] = useState(false),
+ [error, setError] = useState(''),
+ [revision, setRevision] = useState(0)
+ useEffect(() => {
+ if (!query) return
+ const c = new AbortController()
+ setLoading(true)
+ setData(null)
+ setError('')
+ void fetchQAUsage(query, c.signal)
+ .then((value) => {
+ if (!c.signal.aborted) setData(value)
+ })
+ .catch((e: unknown) => {
+ if (!c.signal.aborted) setError(e instanceof Error ? e.message : '统计读取失败')
+ })
+ .finally(() => {
+ if (!c.signal.aborted) setLoading(false)
+ })
+ return () => c.abort()
+ }, [query, revision])
+ return setRevision((v) => v + 1)} />
+}
diff --git a/web/src/qaAttribution.test.ts b/web/src/qaAttribution.test.ts
new file mode 100644
index 0000000..50af14a
--- /dev/null
+++ b/web/src/qaAttribution.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest'
+import { parseQAOrganizationVersion, mergeQAPages, parseQARecordPage } from './qaOps'
+import { parseQAUsage } from './qaUsage'
+const version = {
+ state: 'ready',
+ directory_id: 'd',
+ directory_source: 'weekly_report_live',
+ synced_at: '2026-10-17T07:59:50Z',
+ revision_id: 'r',
+ basis: 'current_directory',
+}
+const row = { key: 'APAC', questions: 5, succeeded: 3, failed: 1, other: 1, users: 1, roster_people: 4 }
+const usage = {
+ organization: version,
+ as_of: '2026-10-17T08:00:00Z',
+ start: '2026-10-14T00:00:00Z',
+ end: '2026-10-15T00:00:00Z',
+ keyword: '',
+ questions: 5,
+ identified_users: 1,
+ rows: [row],
+}
+describe('organization evidence and usage contracts', () => {
+ it('keeps a valid current-roster version and rejects contradictory metadata', () => {
+ expect(parseQAOrganizationVersion(version).directory_id).toBe('d')
+ expect(() => parseQAOrganizationVersion({ ...version, directory_id: '' })).toThrow()
+ })
+ it('does not append pages across directory or regional revisions', () => {
+ const page = parseQARecordPage({
+ items: [],
+ columns: [],
+ total: 0,
+ has_more: false,
+ next_cursor: '',
+ as_of: usage.as_of,
+ organization: version,
+ })
+ expect(() =>
+ mergeQAPages(page, { ...page, organization: { ...page.organization!, revision_id: 'changed' } })
+ ).toThrow(/配置已变化/)
+ expect(mergeQAPages(page, page).total).toBe(0)
+ })
+ it('validates event conservation and unknown participant counts instead of inventing zeros', () => {
+ expect(parseQAUsage(usage).identified_users).toBe(1)
+ expect(parseQAUsage({ ...usage, rows: [{ ...row, users: null, roster_people: null }] }).rows[0].users).toBeNull()
+ expect(() => parseQAUsage({ ...usage, questions: 6 })).toThrow()
+ expect(() => parseQAUsage({ ...usage, rows: [{ ...row, other: 0 }] })).toThrow()
+ expect(() => parseQAUsage({ ...usage, rows: [{ ...row, questions: -1 }] })).toThrow()
+ })
+})
diff --git a/web/src/qaOps.css b/web/src/qaOps.css
index 1985b0b..48dda03 100644
--- a/web/src/qaOps.css
+++ b/web/src/qaOps.css
@@ -66,6 +66,12 @@
outline: 2px solid var(--c-run);
outline-offset: 2px;
}
+.qa-ops-organization {
+ margin: 8px 14px;
+ overflow-wrap: anywhere;
+ font-size: 12px;
+ line-height: 1.5;
+}
.qa-ops-results {
display: flex;
flex-direction: column;
diff --git a/web/src/qaOps.ts b/web/src/qaOps.ts
index bf534c1..561d1b6 100644
--- a/web/src/qaOps.ts
+++ b/web/src/qaOps.ts
@@ -17,7 +17,59 @@ export const qaColumns = [
] as const
export type QAColumn = (typeof qaColumns)[number]['key']
+export interface QAOrganizationVersion {
+ state: 'ready' | 'empty'
+ directory_id: string
+ directory_source: string
+ synced_at: string | null
+ revision_id: string
+ basis: 'current_directory'
+}
+export interface QARecordOrganization {
+ version: QAOrganizationVersion
+ state: string
+ departments: string[]
+ region: string
+ source_department: string
+ source_region: string
+ department_origin: string
+ region_origin: string
+}
+export function parseQAOrganizationVersion(value: unknown): QAOrganizationVersion {
+ const v = object(value)
+ if (!['ready', 'empty'].includes(text(v.state)) || v.basis !== 'current_directory') return invalid()
+ const result = {
+ state: v.state as QAOrganizationVersion['state'],
+ directory_id: text(v.directory_id),
+ directory_source: text(v.directory_source),
+ synced_at: v.synced_at === null ? null : instant(v.synced_at),
+ revision_id: text(v.revision_id),
+ basis: 'current_directory' as const,
+ }
+ if (
+ result.state === 'ready' &&
+ (!result.directory_id ||
+ !result.synced_at ||
+ !['weekly_report_live', 'weekly_report_snapshot'].includes(result.directory_source))
+ )
+ return invalid()
+ if (result.state === 'empty' && (result.directory_id || result.revision_id || result.synced_at !== null))
+ return invalid()
+ return result
+}
+export function mergeQAPages(current: QARecordPage, next: QARecordPage): QARecordPage {
+ if (
+ current.organization?.directory_id !== next.organization?.directory_id ||
+ current.organization?.revision_id !== next.organization?.revision_id
+ )
+ throw new Error('通讯录或区域配置已变化,请重新查询,不能混合不同版本的分页结果')
+ return {
+ ...next,
+ items: [...current.items, ...next.items.filter((item) => !current.items.some((old) => old.id === item.id))],
+ }
+}
export interface QARecord {
+ organization?: QARecordOrganization
id: string
status: string
question: string
@@ -41,6 +93,7 @@ export interface QARecord {
language?: string
}
export interface QARecordPage {
+ organization?: QAOrganizationVersion
items: QARecord[]
columns: QAColumn[]
total: number
@@ -121,6 +174,36 @@ export function parseQARecord(value: unknown): QARecord {
if (typeof row.is_correct !== 'boolean' && row.is_correct !== null) return invalid()
item.is_correct = row.is_correct
}
+ if (row.organization !== undefined) {
+ const o = object(row.organization)
+ if (
+ !Array.isArray(o.departments) ||
+ ![
+ 'matched',
+ 'unassigned',
+ 'cross_region',
+ 'unmatched',
+ 'identity_conflict',
+ 'no_identity',
+ 'directory_missing',
+ ].includes(text(o.state))
+ )
+ return invalid()
+ const origin = (v: unknown) => {
+ const s = text(v)
+ return ['source_snapshot', 'current_directory', 'unavailable'].includes(s) ? s : invalid()
+ }
+ item.organization = {
+ version: parseQAOrganizationVersion(o.version),
+ state: text(o.state),
+ departments: o.departments.map(text),
+ region: text(o.region),
+ source_department: text(o.source_department),
+ source_region: text(o.source_region),
+ department_origin: origin(o.department_origin),
+ region_origin: origin(o.region_origin),
+ }
+ }
return item
}
@@ -137,10 +220,18 @@ export function parseQARecordPage(value: unknown): QARecordPage {
return invalid()
if (new Set(items.map(({ id }) => id)).size !== items.length || new Set(columns).size !== columns.length)
return invalid()
- return { items, columns, total, has_more: page.has_more, next_cursor: nextCursor, as_of: instant(page.as_of) }
+ return {
+ items,
+ columns,
+ total,
+ has_more: page.has_more,
+ next_cursor: nextCursor,
+ as_of: instant(page.as_of),
+ ...(page.organization === undefined ? {} : { organization: parseQAOrganizationVersion(page.organization) }),
+ }
}
-async function getPayload(path: string, signal?: AbortSignal): Promise {
+export async function getPayload(path: string, signal?: AbortSignal): Promise {
const response = await fetch(path, { credentials: 'same-origin', cache: 'no-store', signal })
const raw: unknown = await response.json().catch(() => null)
if (!response.ok) {
diff --git a/web/src/qaUsage.ts b/web/src/qaUsage.ts
new file mode 100644
index 0000000..c16b9fa
--- /dev/null
+++ b/web/src/qaUsage.ts
@@ -0,0 +1,85 @@
+import type { QAOrganizationVersion, QAQuery } from './qaOps'
+import { getPayload, parseQAOrganizationVersion } from './qaOps'
+export interface QAUsageRow {
+ key: string
+ questions: number
+ succeeded: number
+ failed: number
+ other: number
+ users: number | null
+ roster_people: number | null
+}
+export interface QAUsage {
+ organization: QAOrganizationVersion
+ as_of: string
+ start: string
+ end: string
+ keyword: string
+ questions: number
+ identified_users: number
+ rows: QAUsageRow[]
+}
+const bad = (): never => {
+ throw new Error('使用统计响应无效,请检查完整性及接口契约')
+}
+const obj = (v: unknown): Record =>
+ v && typeof v === 'object' && !Array.isArray(v) ? (v as Record) : bad()
+const text = (v: unknown) => (typeof v === 'string' ? v : bad())
+const count = (v: unknown) => (typeof v === 'number' && Number.isSafeInteger(v) && v >= 0 ? v : bad())
+const stamp = (v: unknown) => {
+ const s = text(v)
+ return !Number.isNaN(Date.parse(s)) ? s : bad()
+}
+export const usageLabels: Record = {
+ 国内工业: '国内工业',
+ APAC: 'APAC',
+ EMEA: 'EMEA',
+ America: 'America',
+ unassigned: '未配置区域',
+ cross_region: '跨区域待核对',
+ unmatched: '名册未匹配',
+ identity_conflict: '身份冲突',
+ no_identity: '身份信息缺失',
+ directory_missing: '尚无完整通讯录',
+}
+export function parseQAUsage(value: unknown): QAUsage {
+ const v = obj(value)
+ if (!Array.isArray(v.rows)) return bad()
+ const rows = v.rows.map((raw) => {
+ const r = obj(raw)
+ const key = text(r.key)
+ if (!Object.hasOwn(usageLabels, key)) return bad()
+ const row = {
+ key,
+ questions: count(r.questions),
+ succeeded: count(r.succeeded),
+ failed: count(r.failed),
+ other: count(r.other),
+ users: r.users === null ? null : count(r.users),
+ roster_people: r.roster_people === null ? null : count(r.roster_people),
+ }
+ if (row.questions !== row.succeeded + row.failed + row.other) return bad()
+ return row
+ })
+ const result = {
+ organization: parseQAOrganizationVersion(v.organization),
+ as_of: stamp(v.as_of),
+ start: stamp(v.start),
+ end: stamp(v.end),
+ keyword: text(v.keyword),
+ questions: count(v.questions),
+ identified_users: count(v.identified_users),
+ rows,
+ }
+ if (
+ result.questions !== rows.reduce((n, r) => n + r.questions, 0) ||
+ new Set(rows.map((r) => r.key)).size !== rows.length ||
+ !(new Date(result.start) < new Date(result.end))
+ )
+ return bad()
+ return result
+}
+export async function fetchQAUsage(query: QAQuery, signal?: AbortSignal): Promise {
+ const params = new URLSearchParams({ start: query.start, end: query.end, keyword: query.keyword })
+ return parseQAUsage(await getPayload(`/api/v1/qa-ops/usage?${params}`, signal))
+}
--
2.52.0
From 9556db1ef01add21064553f64be6a7e25f838e9e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Sat, 17 Oct 2026 19:59:33 +0800
Subject: [PATCH 07/14] =?UTF-8?q?feat(qaops):=20=E5=A2=9E=E5=8A=A0?=
=?UTF-8?q?=E4=B8=AA=E4=BA=BA=E8=87=AA=E7=84=B6=E6=9C=88=E7=94=A8=E9=87=8F?=
=?UTF-8?q?=E4=B8=8E=E9=9B=B6=E8=AE=B0=E5=BD=95=E4=BA=BA=E5=91=98=E6=98=8E?=
=?UTF-8?q?=E7=BB=86?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
CHANGELOG.md | 2 +
api/openapi.yaml | 1 +
internal/httpapi/qa_monthly.go | 312 ++++++++++++++++++++++++++
internal/httpapi/qa_monthly_test.go | 221 ++++++++++++++++++
internal/httpapi/server.go | 1 +
internal/qaopsorg/attribution.go | 24 +-
internal/qaopsorg/members_test.go | 30 +++
internal/qaopsorg/regions.go | 3 +-
scripts/qa_ops_directory_sync.py | 5 +-
scripts/test_qa_ops_directory_sync.py | 7 +
web/src/QAMonthly.test.tsx | 37 +++
web/src/QAMonthly.tsx | 252 +++++++++++++++++++++
web/src/QAOperations.tsx | 16 +-
web/src/qaMonthly.fixture.ts | 54 +++++
web/src/qaMonthly.test.ts | 37 +++
web/src/qaMonthly.ts | 200 +++++++++++++++++
web/src/qaOps.css | 48 ++++
web/src/qaOps.ts | 8 +-
18 files changed, 1248 insertions(+), 10 deletions(-)
create mode 100644 internal/httpapi/qa_monthly.go
create mode 100644 internal/httpapi/qa_monthly_test.go
create mode 100644 internal/qaopsorg/members_test.go
create mode 100644 web/src/QAMonthly.test.tsx
create mode 100644 web/src/QAMonthly.tsx
create mode 100644 web/src/qaMonthly.fixture.ts
create mode 100644 web/src/qaMonthly.test.ts
create mode 100644 web/src/qaMonthly.ts
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bc10ccb..2ec92f3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,8 @@
### Added
+- 「使用统计 → 个人月明细」按北京时间自然月及截止时点展示当前应用可见名册的人员用量(包含本源零记录),支持部门含子部门、区域/待核对状态、姓名/完整部门路径和已有提问/零记录筛选。稳定身份关联去重、不可关联问答单列、过期组织版本阻断翻页;源端姓名可缺失并提示重新同步,不按姓名匹配身份。姓名筛选通过有界只读 POST 请求体传递、不进入 URL,原始员工标识不返回浏览器;名册不作为在职/考核分母,当月进度不作为绩效结论。
+
- 问答运营按稳定身份关联当前治理通讯录,缺失部门/区域补全并保留源快照及目录/区域版本;空列判断包含完整筛选结果,不混合配置已变化的分页。新增完整时间/关键词范围的使用统计,问答计次、名册内人员去重,跨区/未匹配/身份缺失分列,不输出绩效结论;不回写 DobotAI 原表。
- 「问答运营 → 区域使用」支持管理员从网页发起持久化通讯录同步,重复请求重放、进行中操作合并;按服务器固定范围注册后台执行器,未接线或未检测到心跳时不创建新任务。界面显示真实任务状态、不编造百分比;失败保留旧快照与区域规则,同步完成不覆盖未保存草稿。旧执行器丢失租约后不能激活结果,重启接管和已提交快照的续跑使用原任务。
- 新增治理侧通讯录实时桥接,复用既有周报读取能力,向源端读取真实缺失祖先以补齐部门树;不改旧周报脚本、配置或输出。私有 JSON 与受控子进程执行器拒绝不完整数据、模拟同步、公开文件和异常输出,超时清理临时人员文件。同步默认关闭,容器启用仍需批准的既有周报 SDK/配置及兼容 Python 运行时挂载。
diff --git a/api/openapi.yaml b/api/openapi.yaml
index 3e806e9..de788fc 100644
--- a/api/openapi.yaml
+++ b/api/openapi.yaml
@@ -99,6 +99,7 @@
}
}
},
+ "/api/v1/qa-ops/usage/people": {"post": {"tags": ["QA operations"], "operationId": "queryQAOperationsMonthlyPeople", "summary": "按北京时间自然月列出当前名册人员的2.0用量(含零记录),仅管理员,不返回原始员工标识,不作为在职/考核名单", "responses": {"200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"description": "需要登录"}, "403": {"description": "仅管理员访问"}, "503": {"description": "独立只读源或治理组织存储不可用,不返回伪造的零值"}, "500": {"$ref": "#/components/responses/InternalError"}, "409": {"description": "完整名册缺失或目录/区域版本变化,请同步/重新查询,不返回伪零"}}, "description": "只读查询,不写治理库或生产库;姓名筛选置于 JSON 请求体,不进入 URL;整名册指标不随人员筛选变化。第2页起须带首页目录、区域版本及 end 截止。", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["month"], "properties": {"month": {"type": "string", "pattern": "^(?!0000)[0-9]{4}-(0[1-9]|1[0-2])$"}, "cutoff": {"type": "string", "format": "date-time"}, "region": {"type": "string", "enum": ["国内工业", "APAC", "EMEA", "America", "unassigned", "cross_region"]}, "department_id": {"type": "string"}, "activity": {"type": "string", "enum": ["all", "used", "zero"]}, "search": {"type": "string", "maxLength": 100}, "page": {"type": "integer", "minimum": 1, "maximum": 100000, "default": 1}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 30}, "directory_id": {"type": "string"}, "revision_id": {"type": "string"}}}}}}, "parameters": [{"name": "X-Governance-Action", "in": "header", "required": true, "schema": {"type": "string", "enum": ["qa-usage-read"]}}]}},
"/api/v1/qa-ops/usage": {"get": {"tags": ["QA operations"], "operationId": "getQAOperationsUsage", "summary": "完整筛选范围内按当前通讯录和区域版本回看2.0问答使用;固定租户、管理员访问,不输出绩效结论", "parameters": [{"name": "start", "in": "query", "required": true, "schema": {"type": "string", "format": "date-time"}}, {"name": "end", "in": "query", "required": true, "schema": {"type": "string", "format": "date-time"}}, {"name": "keyword", "in": "query", "schema": {"type": "string", "maxLength": 200}}], "responses": {"200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"description": "需要登录"}, "403": {"description": "仅管理员访问"}, "503": {"description": "独立只读源或治理组织存储不可用,不返回伪造的零值"}, "500": {"$ref": "#/components/responses/InternalError"}}}},
"/api/v1/qa-ops/status": {
"get": {
diff --git a/internal/httpapi/qa_monthly.go b/internal/httpapi/qa_monthly.go
new file mode 100644
index 0000000..825e3e6
--- /dev/null
+++ b/internal/httpapi/qa_monthly.go
@@ -0,0 +1,312 @@
+package httpapi
+
+import (
+ "bytes"
+ "crypto/sha256"
+ "encoding/hex"
+ "encoding/json"
+ "io"
+ "knowledge-governance/internal/dobotaiops"
+ "knowledge-governance/internal/qaopsorg"
+ "net/http"
+ "net/url"
+ "sort"
+ "strconv"
+ "strings"
+ "time"
+ _ "time/tzdata"
+ "unicode/utf8"
+)
+
+type monthlyFilter struct {
+ Month, Region, Department, Activity, Search string
+ Start, End, MonthEnd time.Time
+ Page, Limit int
+}
+type monthlyPerson struct {
+ Key string `json:"key"`
+ Name string `json:"name"`
+ State string `json:"state"`
+ Region string `json:"region"`
+ Departments []string `json:"departments"`
+ Questions int64 `json:"questions"`
+ Succeeded int64 `json:"succeeded"`
+ Failed int64 `json:"failed"`
+ Other int64 `json:"other"`
+}
+type monthlyDepartment struct {
+ ID string `json:"id"`
+ Path string `json:"path"`
+}
+type monthlyPeople struct {
+ Organization dobotaiops.OrganizationVersion `json:"organization"`
+ Source string `json:"source"`
+ Timezone string `json:"timezone"`
+ Month string `json:"month"`
+ Start time.Time `json:"start"`
+ End time.Time `json:"end"`
+ MonthEnd time.Time `json:"month_end"`
+ AsOf time.Time `json:"as_of"`
+ Partial bool `json:"partial"`
+ Questions int64 `json:"questions"`
+ LinkedQuestions int64 `json:"linked_questions"`
+ UnresolvedQuestions int64 `json:"unresolved_questions"`
+ RosterPeople int `json:"roster_people"`
+ UsedPeople int `json:"used_people"`
+ ZeroPeople int `json:"zero_people"`
+ MissingNames int `json:"missing_names"`
+ Total int `json:"total"`
+ Page int `json:"page"`
+ Limit int `json:"limit"`
+ HasMore bool `json:"has_more"`
+ Rows []monthlyPerson `json:"rows"`
+ DepartmentOptions []monthlyDepartment `json:"department_options"`
+}
+
+func parseMonthlyFilter(values url.Values, now time.Time) (monthlyFilter, error) {
+ f := monthlyFilter{Month: values.Get("month"), Region: values.Get("region"), Department: values.Get("department_id"), Activity: values.Get("activity"), Search: values.Get("search"), Page: 1, Limit: 30}
+ allowed := map[string]bool{"month": true, "cutoff": true, "region": true, "department_id": true, "activity": true, "search": true, "page": true, "limit": true, "directory_id": true, "revision_id": true}
+ for key, v := range values {
+ if !allowed[key] || len(v) != 1 {
+ return f, dobotaiops.ErrInvalidQuery
+ }
+ }
+ loc, err := time.LoadLocation("Asia/Shanghai")
+ if err != nil {
+ return f, dobotaiops.ErrUnavailable
+ }
+ f.Start, err = time.ParseInLocation("2006-01", f.Month, loc)
+ if err != nil || len(f.Month) != 7 || f.Start.Year() < 1 || f.Start.Format("2006-01") != f.Month || !f.Start.Before(now) {
+ return f, dobotaiops.ErrInvalidQuery
+ }
+ f.MonthEnd = f.Start.AddDate(0, 1, 0)
+ f.End = f.MonthEnd
+ if now.Before(f.End) {
+ f.End = now.In(loc)
+ }
+ if raw := values.Get("cutoff"); raw != "" {
+ cutoff, e := time.Parse(time.RFC3339Nano, raw)
+ if e != nil || !cutoff.After(f.Start) || cutoff.After(f.MonthEnd) || cutoff.After(now) {
+ return f, dobotaiops.ErrInvalidQuery
+ }
+ f.End = cutoff.In(loc)
+ }
+ if f.Activity == "" {
+ f.Activity = "all"
+ }
+ if f.Activity != "all" && f.Activity != "used" && f.Activity != "zero" {
+ return f, dobotaiops.ErrInvalidQuery
+ }
+ validRegion := f.Region == "" || f.Region == "unassigned" || f.Region == "cross_region"
+ for _, r := range qaopsorg.RegionNames {
+ validRegion = validRegion || f.Region == r
+ }
+ if !validRegion {
+ return f, dobotaiops.ErrInvalidQuery
+ }
+ if !utf8.ValidString(f.Search) || utf8.RuneCountInString(f.Search) > 100 || strings.ContainsRune(f.Search, 0) {
+ return f, dobotaiops.ErrInvalidQuery
+ }
+ for key, target := range map[string]*int{"page": &f.Page, "limit": &f.Limit} {
+ if raw := values.Get(key); raw != "" {
+ n, e := strconv.Atoi(raw)
+ if e != nil || n < 1 || n > 100000 {
+ return f, dobotaiops.ErrInvalidQuery
+ }
+ *target = n
+ }
+ }
+ if f.Limit > 100 || f.Page > 1 && (!values.Has("directory_id") || !values.Has("revision_id")) {
+ return f, dobotaiops.ErrInvalidQuery
+ }
+ return f, nil
+}
+func monthlyHasDepartment(person qaopsorg.PersonAttribution, department string, parents map[string]string) bool {
+ if department == "" {
+ return true
+ }
+ for _, id := range person.DepartmentIDs {
+ for cur := id; cur != ""; cur = parents[cur] {
+ if cur == department {
+ return true
+ }
+ }
+ }
+ return false
+}
+func monthlyResult(groups dobotaiops.UsageGroups, p *qaopsorg.Attribution, f monthlyFilter) monthlyPeople {
+ result := monthlyPeople{Organization: attributionVersion(p), Source: "2.0", Timezone: "Asia/Shanghai", Month: f.Month, Start: f.Start, End: f.End, MonthEnd: f.MonthEnd, AsOf: groups.AsOf, Partial: f.End.Before(f.MonthEnd), Page: f.Page, Limit: f.Limit, Rows: []monthlyPerson{}, DepartmentOptions: []monthlyDepartment{}}
+ totals := map[string]dobotaiops.UsageGroup{}
+ for _, group := range groups.Groups {
+ result.Questions += group.Total
+ person := p.Resolve(group.Identity.StaffID, group.Identity.UnionID)
+ if person.PersonID == "" {
+ result.UnresolvedQuestions += group.Total
+ continue
+ }
+ n := totals[person.PersonID]
+ n.Total += group.Total
+ n.Succeeded += group.Succeeded
+ n.Failed += group.Failed
+ totals[person.PersonID] = n
+ result.LinkedQuestions += group.Total
+ }
+ parents := map[string]string{}
+ for _, d := range p.Metadata.View.Departments {
+ parents[d.ID] = d.ParentID
+ result.DepartmentOptions = append(result.DepartmentOptions, monthlyDepartment{ID: d.ID, Path: d.Path})
+ }
+ rows := []monthlyPerson{}
+ people := p.Members()
+ result.RosterPeople = len(people)
+ search := strings.ToLower(f.Search)
+ for _, person := range people {
+ n := totals[person.PersonID]
+ if n.Total > 0 {
+ result.UsedPeople++
+ } else {
+ result.ZeroPeople++
+ }
+ if person.Name == "" {
+ result.MissingNames++
+ }
+ if f.Region != "" && f.Region != person.Region && f.Region != person.State {
+ continue
+ }
+ if !monthlyHasDepartment(person, f.Department, parents) {
+ continue
+ }
+ if f.Activity == "used" && n.Total == 0 || f.Activity == "zero" && n.Total > 0 {
+ continue
+ }
+ if search != "" && !strings.Contains(strings.ToLower(person.Name), search) && !strings.Contains(strings.ToLower(strings.Join(person.Departments, ";")), search) {
+ continue
+ }
+ // This is a stable row key, not an anonymisation claim or a new user identifier.
+ sum := sha256.Sum256([]byte(p.Metadata.DirectoryID + "\x00" + person.PersonID))
+ rows = append(rows, monthlyPerson{Key: "person-" + hex.EncodeToString(sum[:]), Name: person.Name, State: person.State, Region: person.Region, Departments: person.Departments, Questions: n.Total, Succeeded: n.Succeeded, Failed: n.Failed, Other: n.Total - n.Succeeded - n.Failed})
+ }
+ sort.Slice(rows, func(i, j int) bool {
+ a, b := rows[i], rows[j]
+ if a.Name == "" && b.Name != "" {
+ return false
+ }
+ if a.Name != "" && b.Name == "" {
+ return true
+ }
+ if a.Name != b.Name {
+ return a.Name < b.Name
+ }
+ return a.Key < b.Key
+ })
+ result.Total = len(rows)
+ start := (f.Page - 1) * f.Limit
+ if start < len(rows) {
+ end := min(start+f.Limit, len(rows))
+ result.Rows = rows[start:end]
+ result.HasMore = end < len(rows)
+ }
+ return result
+}
+
+// Names remain in the bounded read-query body, not URLs/access logs. The source
+// reader and governance store are still strictly read-only on this route.
+func monthlyRequestValues(w http.ResponseWriter, r *http.Request) (url.Values, error) {
+ values := url.Values{}
+ if r.URL.RawQuery != "" || r.Header.Get("X-Governance-Action") != "qa-usage-read" {
+ return nil, dobotaiops.ErrInvalidQuery
+ }
+ decoder := json.NewDecoder(http.MaxBytesReader(w, r.Body, 8192))
+ token, err := decoder.Token()
+ if err != nil || token != json.Delim('{') {
+ return nil, dobotaiops.ErrInvalidQuery
+ }
+ for decoder.More() {
+ token, err = decoder.Token()
+ key, ok := token.(string)
+ if err != nil || !ok || values.Has(key) {
+ return nil, dobotaiops.ErrInvalidQuery
+ }
+ var raw json.RawMessage
+ if decoder.Decode(&raw) != nil || bytes.Equal(bytes.TrimSpace(raw), []byte("null")) {
+ return nil, dobotaiops.ErrInvalidQuery
+ }
+ if key == "page" || key == "limit" {
+ var n int
+ if json.Unmarshal(raw, &n) != nil {
+ return nil, dobotaiops.ErrInvalidQuery
+ }
+ values.Set(key, strconv.Itoa(n))
+ } else {
+ var text string
+ if json.Unmarshal(raw, &text) != nil {
+ return nil, dobotaiops.ErrInvalidQuery
+ }
+ values.Set(key, text)
+ }
+ }
+ if _, err = decoder.Token(); err != nil {
+ return nil, dobotaiops.ErrInvalidQuery
+ }
+ var extra any
+ if decoder.Decode(&extra) != io.EOF {
+ return nil, dobotaiops.ErrInvalidQuery
+ }
+ return values, nil
+}
+func qaMonthlyPeople(w http.ResponseWriter, r *http.Request, config Config) {
+ if !authorizeQAOps(w, r) {
+ return
+ }
+ values, err := monthlyRequestValues(w, r)
+ if err != nil {
+ qaOpsError(w, err)
+ return
+ }
+ f, err := parseMonthlyFilter(values, config.Now())
+ if err != nil {
+ qaOpsError(w, err)
+ return
+ }
+ p, err := recordAttribution(r.Context(), config)
+ if err != nil {
+ qaOpsError(w, err)
+ return
+ }
+ if p.Metadata.State != "ready" {
+ writeJSON(w, 409, map[string]string{"code": "directory_missing", "error": "尚无完整通讯录,请先从区域使用页同步;不能生成零记录人员名单"})
+ return
+ }
+
+ if values.Has("directory_id") || values.Has("revision_id") {
+ if !values.Has("directory_id") || !values.Has("revision_id") {
+ qaOpsError(w, dobotaiops.ErrInvalidQuery)
+ return
+ }
+ if values.Get("directory_id") != p.Metadata.DirectoryID || values.Get("revision_id") != p.Metadata.RevisionID {
+ writeJSON(w, 409, map[string]string{"code": "organization_changed", "error": "通讯录或区域配置已变化,请重新查询个人月明细"})
+ return
+ }
+ }
+ if f.Department != "" {
+ found := false
+ for _, d := range p.Metadata.View.Departments {
+ found = found || d.ID == f.Department
+ }
+ if !found {
+ qaOpsError(w, dobotaiops.ErrInvalidQuery)
+ return
+ }
+ }
+ reader, ok := config.QAOps.(qaUsageReader)
+ if !ok || config.QAOpsTenantKey == "" {
+ qaOpsError(w, dobotaiops.ErrUnavailable)
+ return
+ }
+ groups, err := reader.ReadUsageGroups(r.Context(), dobotaiops.RecordQuery{Window: dobotaiops.Window{TenantKey: config.QAOpsTenantKey, Start: f.Start, End: f.End}})
+ if err != nil {
+ qaOpsError(w, err)
+ return
+ }
+ writeJSON(w, 200, map[string]any{"data": monthlyResult(groups, p, f)})
+}
diff --git a/internal/httpapi/qa_monthly_test.go b/internal/httpapi/qa_monthly_test.go
new file mode 100644
index 0000000..9c2f078
--- /dev/null
+++ b/internal/httpapi/qa_monthly_test.go
@@ -0,0 +1,221 @@
+package httpapi
+
+import (
+ "bytes"
+ "context"
+ "encoding/json"
+ "knowledge-governance/internal/dobotaiops"
+ "knowledge-governance/internal/qaopsorg"
+ "net/http"
+ "net/http/httptest"
+ "strconv"
+
+ "net/url"
+ "strings"
+ "testing"
+ "time"
+)
+
+type monthlyReaderSpy struct {
+ attributedReader
+ query dobotaiops.RecordQuery
+ calls int
+}
+
+func (s *monthlyReaderSpy) ReadUsageGroups(ctx context.Context, q dobotaiops.RecordQuery) (dobotaiops.UsageGroups, error) {
+ s.calls++
+ s.query = q
+ return s.attributedReader.ReadUsageGroups(ctx, q)
+}
+func monthlyRequest(h http.Handler, path, token string) *httptest.ResponseRecorder {
+ u, _ := url.Parse(path)
+ body := map[string]any{}
+ for k, v := range u.Query() {
+ if len(v) != 1 {
+ body[k] = v
+ continue
+ }
+ if k == "page" || k == "limit" {
+ if n, e := strconv.Atoi(v[0]); e == nil {
+ body[k] = n
+ } else {
+ body[k] = v[0]
+ }
+ } else {
+ body[k] = v[0]
+ }
+ }
+ raw, _ := json.Marshal(body)
+ r := httptest.NewRequest(http.MethodPost, u.Path, bytes.NewReader(raw))
+ r.Header.Set("Content-Type", "application/json")
+ r.Header.Set("X-Governance-Action", "qa-usage-read")
+ if token != "" {
+ r.AddCookie(&http.Cookie{Name: sessionCookieName, Value: token})
+ }
+ w := httptest.NewRecorder()
+ h.ServeHTTP(w, r)
+ return w
+}
+
+func monthlyHandler(t *testing.T) (http.Handler, *attributionOrgSpy, *monthlyReaderSpy) {
+ t.Helper()
+ d := qaopsorg.Directory{Departments: []qaopsorg.Department{{ID: "root", Name: "示例根"}, {ID: "child", ParentID: "root", Name: "子部门"}}, People: []qaopsorg.Person{{ID: "fixture-private-staff", Name: "同名示例", UnionID: "fixture-private-union", DepartmentIDs: []string{"root"}}, {ID: "private-zero", Name: "同名示例", DepartmentIDs: []string{"child"}}, {ID: "private-cross", Name: "跨区域示例", DepartmentIDs: []string{"root", "child"}}, {ID: "private-unnamed", DepartmentIDs: []string{"child"}}}}
+ now := time.Date(2026, 10, 17, 8, 0, 0, 0, time.UTC)
+ p, err := qaopsorg.BuildAttribution(qaopsorg.State{State: "ready", DirectoryID: "monthly-directory", DirectorySource: "weekly_report_live", DirectorySyncedAt: &now, RevisionID: "monthly-regions", Rules: []qaopsorg.Rule{{DepartmentID: "root", Region: "国内工业"}, {DepartmentID: "child", Region: "APAC"}}}, d)
+ if err != nil {
+ t.Fatal(err)
+ }
+ org := &attributionOrgSpy{projection: p}
+ reader := &monthlyReaderSpy{}
+ auth := newFakeAuthStore()
+ auth.sessions["attribution-admin"] = "usr-boss"
+ auth.sessions["attribution-viewer"] = "usr-eye"
+ h, err := NewHandler(Config{Store: &fakeJobStore{}, Auth: &AuthConfig{Store: auth}, QAOps: reader, QAOpsTenantKey: "fixed", QAOrg: org, Now: func() time.Time { return now }})
+ if err != nil {
+ t.Fatal(err)
+ }
+ return h, org, reader
+}
+func TestQAMonthlyPeopleIncludesZeroUseAndKeepsUnresolvedEvents(t *testing.T) {
+ h, _, reader := monthlyHandler(t)
+ path := "/api/v1/qa-ops/usage/people?month=2026-10&limit=2"
+ w := monthlyRequest(h, path, "attribution-admin")
+ if w.Code != 200 {
+ t.Fatal(w.Code, w.Body.String())
+ }
+ var result struct {
+ Data struct {
+ Month string
+ Timezone string
+ Partial bool
+ Questions int64
+ LinkedQuestions int64 `json:"linked_questions"`
+ UnresolvedQuestions int64 `json:"unresolved_questions"`
+ RosterPeople int `json:"roster_people"`
+ UsedPeople int `json:"used_people"`
+ ZeroPeople int `json:"zero_people"`
+ MissingNames int `json:"missing_names"`
+ Total int
+ HasMore bool `json:"has_more"`
+ Rows []struct {
+ Key string
+ Name string
+ Questions int64
+ State string
+ }
+ }
+ }
+ if json.Unmarshal(w.Body.Bytes(), &result) != nil {
+ t.Fatal("invalid monthly JSON")
+ }
+ v := result.Data
+ if v.Month != "2026-10" || v.Timezone != "Asia/Shanghai" || !v.Partial || v.Questions != 7 || v.LinkedQuestions != 5 || v.UnresolvedQuestions != 2 || v.RosterPeople != 4 || v.UsedPeople != 1 || v.ZeroPeople != 3 || v.MissingNames != 1 || v.Total != 4 || len(v.Rows) != 2 || !v.HasMore {
+ t.Fatal("monthly roster, zero count or alias dedup wrong", w.Body.String())
+ }
+ if reader.query.Window.TenantKey != "fixed" || reader.query.Window.Start.Format(time.RFC3339) != "2026-10-01T00:00:00+08:00" || reader.query.Window.End.Format(time.RFC3339) != "2026-10-17T16:00:00+08:00" {
+ t.Fatal("month was not normalized to the named timezone")
+ }
+ if strings.Contains(w.Body.String(), "private-") || strings.Contains(w.Body.String(), "performance") || strings.Contains(w.Body.String(), "staff_id") {
+ t.Fatal("raw identities or unapproved verdict exposed")
+ }
+ page2 := monthlyRequest(h, path+"&page=2&directory_id=monthly-directory&revision_id=monthly-regions", "attribution-admin")
+ if page2.Code != 200 {
+ t.Fatal(page2.Body.String())
+ }
+ for _, extra := range []string{"&activity=zero", "®ion=cross_region", "&department_id=child", "&search=" + url.QueryEscape("子部门")} {
+ r := monthlyRequest(h, "/api/v1/qa-ops/usage/people?month=2026-10"+extra, "attribution-admin")
+ if r.Code != 200 {
+ t.Fatal("valid monthly filter failed", r.Body.String())
+ }
+ }
+}
+func TestQAMonthlyScopeAndVersionFailClosed(t *testing.T) {
+ h, org, reader := monthlyHandler(t)
+ base := "/api/v1/qa-ops/usage/people?month=2026-10"
+ for _, tc := range []struct {
+ suffix, token string
+ status int
+ }{{"", "", 401}, {"", "attribution-viewer", 403}, {"&tenant=forged", "attribution-admin", 400}, {"&threshold=5", "attribution-admin", 400}, {"&month=duplicate", "attribution-admin", 400}, {"&page=0", "attribution-admin", 400}, {"&limit=101", "attribution-admin", 400}, {"&activity=under5", "attribution-admin", 400}, {"®ion=invalid", "attribution-admin", 400}, {"&department_id=invalid", "attribution-admin", 400}, {"&page=2", "attribution-admin", 400}, {"&page=2&directory_id=changed&revision_id=monthly-regions", "attribution-admin", 409}, {"&cutoff=2026-11-01T00:00:00Z", "attribution-admin", 400}} {
+ w := monthlyRequest(h, base+tc.suffix, tc.token)
+ if w.Code != tc.status {
+ t.Fatalf("monthly %s: %d want %d", tc.suffix, w.Code, tc.status)
+ }
+ }
+ for _, month := range []string{"2026-1", " 2026-10", "2026-13", "0000-01", "2026-11"} {
+ r := monthlyRequest(h, "/api/v1/qa-ops/usage/people?month="+url.QueryEscape(month), "attribution-admin")
+ if r.Code != 400 {
+ t.Fatal("invalid/future month accepted")
+ }
+ }
+ if reader.calls != 0 {
+ t.Fatal("invalid or unauthorized monthly request reached source")
+ }
+ org.projection, _ = qaopsorg.BuildAttribution(qaopsorg.State{State: "empty"}, qaopsorg.Directory{})
+ if w := monthlyRequest(h, base, "attribution-admin"); w.Code != 409 {
+ t.Fatal("no roster presented as zero-use list")
+ }
+ org.err = qaopsorg.ErrUnavailable
+ if w := monthlyRequest(h, base, "attribution-admin"); w.Code != 503 {
+ t.Fatal("store failure hidden as empty")
+ }
+}
+
+func TestQAMonthlyPersonFiltersDoNotGuessNamesOrDuplicateDescendantMembers(t *testing.T) {
+ h, _, _ := monthlyHandler(t)
+ for _, tc := range []struct {
+ filter string
+ total int
+ }{{"&activity=used", 1}, {"&activity=zero", 3}, {"®ion=cross_region", 1}, {"®ion=APAC", 2}, {"&department_id=child", 3}, {"&department_id=root", 4}, {"&search=" + url.QueryEscape("同名示例"), 2}, {"&search=" + url.QueryEscape("子部门"), 3}, {"&search=%25_", 0}} {
+ w := monthlyRequest(h, "/api/v1/qa-ops/usage/people?month=2026-10"+tc.filter, "attribution-admin")
+ var payload struct{ Data monthlyPeople }
+ if w.Code != 200 || json.Unmarshal(w.Body.Bytes(), &payload) != nil || payload.Data.Total != tc.total || payload.Data.Questions != 7 {
+ t.Fatal("person-scope filter did not preserve source totals or person dedup", tc.filter)
+ }
+ for _, r := range payload.Data.Rows {
+ if tc.filter == "&activity=zero" && r.Questions != 0 {
+ t.Fatal("used member labeled zero")
+ }
+ }
+ }
+}
+func TestQAMonthlyReadBodyRejectsDuplicateNullTrailingAndOversizedInput(t *testing.T) {
+ h, _, reader := monthlyHandler(t)
+ for _, body := range []string{`{"month":"2026-10","month":"2026-10"}`, `{"month":"2026-10","search":null}`, `{"month":"2026-10","page":"1"}`, `{"month":"2026-10"}{}`, `[]`, `{"month":"2026-10","search":"` + strings.Repeat("x", 9000) + `"}`} {
+ r := httptest.NewRequest("POST", "/api/v1/qa-ops/usage/people", strings.NewReader(body))
+ r.AddCookie(&http.Cookie{Name: sessionCookieName, Value: "attribution-admin"})
+ r.Header.Set("X-Governance-Action", "qa-usage-read")
+ w := httptest.NewRecorder()
+ h.ServeHTTP(w, r)
+ if w.Code != 400 {
+ t.Fatal("invalid read body reached source", w.Code)
+ }
+ }
+ for _, method := range []string{"POST", "GET"} {
+ r := httptest.NewRequest(method, "/api/v1/qa-ops/usage/people?search=sensitive-example", strings.NewReader(`{"month":"2026-10"}`))
+ r.AddCookie(&http.Cookie{Name: sessionCookieName, Value: "attribution-admin"})
+ w := httptest.NewRecorder()
+ h.ServeHTTP(w, r)
+ if w.Code != 400 && w.Code != 405 {
+ t.Fatal("URL-based name query accepted")
+ }
+ }
+ if reader.calls != 0 {
+ t.Fatal("invalid body read production source")
+ }
+}
+
+func TestQAMonthlyPastLeapMonthUsesClosedCalendarWindow(t *testing.T) {
+ h, _, reader := monthlyHandler(t)
+ w := monthlyRequest(h, "/api/v1/qa-ops/usage/people?month=2024-02", "attribution-admin")
+ if w.Code != 200 {
+ t.Fatal(w.Body.String())
+ }
+ if reader.query.Window.End.Format(time.RFC3339) != "2024-03-01T00:00:00+08:00" || reader.query.Window.End.Sub(reader.query.Window.Start) != 29*24*time.Hour {
+ t.Fatal("leap month boundary incorrect")
+ }
+ var raw struct{ Data struct{ Partial bool } }
+ _ = json.Unmarshal(w.Body.Bytes(), &raw)
+ if raw.Data.Partial {
+ t.Fatal("past natural month mislabeled as current progress")
+ }
+}
diff --git a/internal/httpapi/server.go b/internal/httpapi/server.go
index 5aca0a9..7d4f4f6 100644
--- a/internal/httpapi/server.go
+++ b/internal/httpapi/server.go
@@ -175,6 +175,7 @@ func NewHandler(config Config) (http.Handler, error) {
config.NewID = newID
}
mux := http.NewServeMux()
+ mux.HandleFunc("POST /api/v1/qa-ops/usage/people", func(w http.ResponseWriter, r *http.Request) { qaMonthlyPeople(w, r, config) })
mux.HandleFunc("GET /api/v1/qa-ops/usage", func(w http.ResponseWriter, r *http.Request) { qaOpsUsage(w, r, config) })
mux.HandleFunc("GET /api/v1/qa-ops/organization/sync", func(w http.ResponseWriter, r *http.Request) { qaOrganizationSync(w, r, config) })
mux.HandleFunc("POST /api/v1/qa-ops/organization/sync", func(w http.ResponseWriter, r *http.Request) { qaOrganizationSync(w, r, config) })
diff --git a/internal/qaopsorg/attribution.go b/internal/qaopsorg/attribution.go
index bba1850..bbf8852 100644
--- a/internal/qaopsorg/attribution.go
+++ b/internal/qaopsorg/attribution.go
@@ -6,10 +6,12 @@ import (
)
type PersonAttribution struct {
- State string `json:"state"`
- PersonID string `json:"-"`
- Departments []string `json:"departments"`
- Region string `json:"region"`
+ Name string `json:"name"`
+ DepartmentIDs []string `json:"-"`
+ State string `json:"state"`
+ PersonID string `json:"-"`
+ Departments []string `json:"departments"`
+ Region string `json:"region"`
}
type Attribution struct {
Metadata State
@@ -17,6 +19,18 @@ type Attribution struct {
unions map[string]string
}
+func (p *Attribution) Members() []PersonAttribution {
+ result := []PersonAttribution{}
+ if p == nil {
+ return result
+ }
+ for _, person := range p.people {
+ result = append(result, person)
+ }
+ sort.Slice(result, func(i, j int) bool { return result[i].PersonID < result[j].PersonID })
+ return result
+}
+
func BuildAttribution(state State, directory Directory) (*Attribution, error) {
p := &Attribution{Metadata: state, people: map[string]PersonAttribution{}, unions: map[string]string{}}
if state.State == "empty" {
@@ -43,7 +57,7 @@ func BuildAttribution(state State, directory Directory) (*Attribution, error) {
regions[d.Region] = true
}
}
- item := PersonAttribution{State: "unassigned", PersonID: person.ID, Departments: []string{}}
+ item := PersonAttribution{Name: person.Name, DepartmentIDs: append([]string{}, person.DepartmentIDs...), State: "unassigned", PersonID: person.ID, Departments: []string{}}
for path := range paths {
item.Departments = append(item.Departments, path)
}
diff --git a/internal/qaopsorg/members_test.go b/internal/qaopsorg/members_test.go
new file mode 100644
index 0000000..d8ffd46
--- /dev/null
+++ b/internal/qaopsorg/members_test.go
@@ -0,0 +1,30 @@
+package qaopsorg
+
+import (
+ "encoding/json"
+ "strings"
+ "testing"
+)
+
+func TestMembersKeepNamedAndUnnamedRosterPeopleWithoutRawIdentifiers(t *testing.T) {
+ d := Directory{Departments: []Department{{ID: "root", Name: "fixture"}}, People: []Person{{ID: "private-a", Name: "<源端姓名>", UnionID: "private-union", DepartmentIDs: []string{"root"}}, {ID: "private-zero", DepartmentIDs: []string{"root"}}}}
+ p, err := BuildAttribution(State{State: "ready", DirectoryID: "directory"}, d)
+ if err != nil {
+ t.Fatal(err)
+ }
+ members := p.Members()
+ if len(members) != 2 {
+ t.Fatal("zero-use roster member omitted")
+ }
+ if p.Resolve("private-a", "").Name != "<源端姓名>" || p.Resolve("private-zero", "").Name != "" {
+ t.Fatal("display name lost or guessed")
+ }
+ raw, _ := json.Marshal(members)
+ if strings.Contains(string(raw), "private-") || strings.Contains(string(raw), "department_ids") {
+ t.Fatal("internal identifiers serialized")
+ }
+ d.People[0].Name = "bad\x00name"
+ if _, err = BuildAttribution(State{State: "ready", DirectoryID: "directory"}, d); err == nil {
+ t.Fatal("invalid display name accepted")
+ }
+}
diff --git a/internal/qaopsorg/regions.go b/internal/qaopsorg/regions.go
index f275de9..983a4a3 100644
--- a/internal/qaopsorg/regions.go
+++ b/internal/qaopsorg/regions.go
@@ -15,6 +15,7 @@ type Department struct {
Name string `json:"name"`
}
type Person struct {
+ Name string `json:"name,omitempty"`
ID string `json:"id"`
UnionID string `json:"union_id,omitempty"`
DepartmentIDs []string `json:"department_ids"`
@@ -107,7 +108,7 @@ func Preview(directory Directory, rules []Rule) (PreviewResult, error) {
}
people := map[string]bool{}
for _, person := range directory.People {
- if !validID(person.ID) || people[person.ID] || len(person.DepartmentIDs) > 1000 {
+ if !validID(person.ID) || people[person.ID] || len(person.DepartmentIDs) > 1000 || len(person.Name) > 1000 || strings.ContainsRune(person.Name, 0) {
return result, ErrInvalid
}
people[person.ID] = true
diff --git a/scripts/qa_ops_directory_sync.py b/scripts/qa_ops_directory_sync.py
index f890624..f3a15e3 100644
--- a/scripts/qa_ops_directory_sync.py
+++ b/scripts/qa_ops_directory_sync.py
@@ -36,6 +36,9 @@ def _validate_directory(departments, people):
seen.add(current)
current = int(departments[current].get('parent_id') or 0)
for identity, person in people.items():
+ name = person.get('name')
+ if name is not None and (not isinstance(name, str) or len(name.encode('utf-8')) > 1000 or '\x00' in name):
+ raise DirectorySyncError('directory_integrity_failed')
if not identity or str(person.get('user_id') or '') != str(identity):
raise DirectorySyncError('directory_integrity_failed')
if not person.get('department_ids') or any(int(d) not in departments for d in person['department_ids']):
@@ -78,7 +81,7 @@ def collect_directory(client, fetch_departments, fetch_users, get_detail, logger
# List membership provides stable staff IDs; do not reuse the old
# guessed primary department, employment policy or openId fallback.
'people': [
- {'id': str(identity), 'union_id': str((p.get('raw_payload') or {}).get('unionid') or (p.get('raw_payload') or {}).get('unionId') or ''), 'department_ids': [str(d) for d in sorted(p['department_ids'])]}
+ {'id': str(identity), **({'name': p['name']} if p.get('name') else {}), 'union_id': str((p.get('raw_payload') or {}).get('unionid') or (p.get('raw_payload') or {}).get('unionId') or ''), 'department_ids': [str(d) for d in sorted(p['department_ids'])]}
for identity, p in sorted(people.items())
],
},
diff --git a/scripts/test_qa_ops_directory_sync.py b/scripts/test_qa_ops_directory_sync.py
index f1f7259..29a6ab2 100644
--- a/scripts/test_qa_ops_directory_sync.py
+++ b/scripts/test_qa_ops_directory_sync.py
@@ -24,6 +24,13 @@ def root_detail(client,logger,department_id):
return {'id':department_id,'parent_id':0,'name':'真实源端返回的示例根部门'},False,False
class DirectoryBridgeTests(unittest.TestCase):
+ def test_real_display_name_is_retained_without_guessing_or_requiring_it(self):
+ def users(*args,**kwargs):
+ return {'u':{'user_id':'u','name':'<示例员工>','department_ids':{10},'raw_payload':{}}},set(),set()
+ result=sync.collect_directory(FakeClient(),full_departments,users,root_detail,logging.getLogger('fixture'))
+ self.assertEqual(result['directory']['people'][0].get('name'),'<示例员工>')
+ result=sync.collect_directory(FakeClient(),full_departments,full_users,root_detail,logging.getLogger('fixture'))
+ self.assertNotIn('name',result['directory']['people'][0])
def test_fetches_the_real_missing_root_and_preserves_stable_identities(self):
result=sync.collect_directory(FakeClient(),full_departments,full_users,root_detail,logging.getLogger('fixture'))
self.assertTrue(result['complete'])
diff --git a/web/src/QAMonthly.test.tsx b/web/src/QAMonthly.test.tsx
new file mode 100644
index 0000000..feca944
--- /dev/null
+++ b/web/src/QAMonthly.test.tsx
@@ -0,0 +1,37 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+import { describe, it, expect } from 'vitest'
+import { QAMonthlyView } from './QAMonthly'
+import { monthlyFixture } from './qaMonthly.fixture'
+import { parseQAMonthly } from './qaMonthly'
+describe('personal monthly view', () => {
+ it('shows a partial month as progress, escapes source names and does not imply eligibility', () => {
+ const html = renderToStaticMarkup(
+ {}}
+ onPage={() => {}}
+ />
+ )
+ for (const text of ['本源零记录', '当月进度', '姓名未同步', '不是考核名单', '当前通讯录', '未关联'])
+ expect(html).toContain(text)
+ expect(html).not.toContain('',
+ departments: ['示例部门'],
+ region: 'APAC',
+ state: 'matched',
+ questions: 2,
+ succeeded: 1,
+ failed: 1,
+ other: 0,
+ },
+ {
+ key: 'person-b',
+ name: '',
+ departments: ['示例部门'],
+ region: '',
+ state: 'unassigned',
+ questions: 0,
+ succeeded: 0,
+ failed: 0,
+ other: 0,
+ },
+ ],
+}
diff --git a/web/src/qaMonthly.test.ts b/web/src/qaMonthly.test.ts
new file mode 100644
index 0000000..0a2dcbb
--- /dev/null
+++ b/web/src/qaMonthly.test.ts
@@ -0,0 +1,37 @@
+import { describe, it, expect, vi } from 'vitest'
+import { parseQAMonthly, fetchQAMonthly, beijingMonth } from './qaMonthly'
+import { monthlyFixture } from './qaMonthly.fixture'
+describe('personal natural-month contracts', () => {
+ it('sends personnel filters only in a same-origin no-store read body', async () => {
+ const fake = vi.fn().mockResolvedValue(new Response(JSON.stringify({ data: monthlyFixture }), { status: 200 }))
+ vi.stubGlobal('fetch', fake)
+ try {
+ await fetchQAMonthly({ month: '2026-10', search: '示例敏感筛选' })
+ expect(fake.mock.calls[0][0]).toBe('/api/v1/qa-ops/usage/people')
+ expect(fake.mock.calls[0][1]).toMatchObject({ method: 'POST', credentials: 'same-origin', cache: 'no-store' })
+ expect(JSON.parse(fake.mock.calls[0][1].body).search).toBe('示例敏感筛选')
+ } finally {
+ vi.unstubAllGlobals()
+ }
+ })
+ it('selects the month in Beijing rather than the browser timezone', () => {
+ expect(beijingMonth(new Date('2026-09-30T16:00:00Z'))).toBe('2026-10')
+ })
+
+ it('keeps named and missing-name zero-use members with a separate unresolved bucket', () => {
+ expect(parseQAMonthly(monthlyFixture)).toMatchObject({ zero_people: 1, missing_names: 1, unresolved_questions: 1 })
+ })
+ it('rejects nonconserving totals, fabricated pagination and inconsistent month boundaries', () => {
+ for (const invalid of [
+ { ...monthlyFixture, zero_people: 0 },
+ { ...monthlyFixture, linked_questions: 3 },
+ { ...monthlyFixture, rows: [monthlyFixture.rows[0]] },
+ { ...monthlyFixture, partial: false },
+ { ...monthlyFixture, source: '1.0' },
+ { ...monthlyFixture, month: '2026-1' },
+ { ...monthlyFixture, month_end: '2026-11-02T00:00:00+08:00' },
+ { ...monthlyFixture, rows: [monthlyFixture.rows[0], monthlyFixture.rows[0]] },
+ ])
+ expect(() => parseQAMonthly(invalid)).toThrow()
+ })
+})
diff --git a/web/src/qaMonthly.ts b/web/src/qaMonthly.ts
new file mode 100644
index 0000000..6dcedd8
--- /dev/null
+++ b/web/src/qaMonthly.ts
@@ -0,0 +1,200 @@
+import { parseQAOrganizationVersion } from './qaOps'
+import type { QAOrganizationVersion } from './qaOps'
+import { getPayload } from './qaOps'
+export interface MonthlyQuery {
+ month: string
+ cutoff?: string
+ region?: string
+ department_id?: string
+ activity?: string
+ search?: string
+ page?: number
+ limit?: number
+ directory_id?: string
+ revision_id?: string
+}
+export interface MonthlyPerson {
+ key: string
+ name: string
+ departments: string[]
+ region: string
+ state: 'matched' | 'unassigned' | 'cross_region'
+ questions: number
+ succeeded: number
+ failed: number
+ other: number
+}
+export interface MonthlyPeople {
+ organization: QAOrganizationVersion
+ source: '2.0'
+ timezone: 'Asia/Shanghai'
+ month: string
+ start: string
+ end: string
+ month_end: string
+ as_of: string
+ partial: boolean
+ questions: number
+ linked_questions: number
+ unresolved_questions: number
+ roster_people: number
+ used_people: number
+ zero_people: number
+ missing_names: number
+ total: number
+ page: number
+ limit: number
+ has_more: boolean
+ rows: MonthlyPerson[]
+ department_options: { id: string; path: string }[]
+}
+const fail = (): never => {
+ throw new Error('个人月明细返回格式异常,未展示可能失真的统计')
+}
+const obj = (v: unknown): Record =>
+ v && typeof v === 'object' && !Array.isArray(v) ? (v as Record) : fail()
+const text = (v: unknown): string => (typeof v === 'string' ? v : fail())
+const count = (v: unknown): number => (typeof v === 'number' && Number.isSafeInteger(v) && v >= 0 ? v : fail())
+const flag = (v: unknown): boolean => (typeof v === 'boolean' ? v : fail())
+const instant = (v: unknown): string => {
+ const t = text(v)
+ return Number.isFinite(Date.parse(t)) ? t : fail()
+}
+const regions = ['国内工业', 'APAC', 'EMEA', 'America']
+export function parseQAMonthly(value: unknown): MonthlyPeople {
+ const v = obj(value),
+ organization = parseQAOrganizationVersion(v.organization)
+ if (organization.state !== 'ready' || v.source !== '2.0' || v.timezone !== 'Asia/Shanghai') fail()
+ const month = text(v.month)
+ if (!/^(?!0000)\d{4}-(0[1-9]|1[0-2])$/.test(month)) fail()
+ const start = instant(v.start),
+ end = instant(v.end),
+ month_end = instant(v.month_end),
+ as_of = instant(v.as_of),
+ partial = flag(v.partial)
+ const expectedEnd = new Date(`${month}-01T00:00:00Z`)
+ expectedEnd.setUTCMonth(expectedEnd.getUTCMonth() + 1)
+ if (
+ Date.parse(start) !== Date.parse(`${month}-01T00:00:00+08:00`) ||
+ Date.parse(month_end) !== expectedEnd.getTime() - 8 * 60 * 60 * 1000 ||
+ Date.parse(end) <= Date.parse(start) ||
+ Date.parse(end) > Date.parse(month_end) ||
+ partial !== Date.parse(end) < Date.parse(month_end)
+ )
+ fail()
+ const questions = count(v.questions),
+ linked_questions = count(v.linked_questions),
+ unresolved_questions = count(v.unresolved_questions),
+ roster_people = count(v.roster_people),
+ used_people = count(v.used_people),
+ zero_people = count(v.zero_people),
+ missing_names = count(v.missing_names),
+ total = count(v.total),
+ page = count(v.page),
+ limit = count(v.limit),
+ has_more = flag(v.has_more)
+ if (
+ questions !== linked_questions + unresolved_questions ||
+ roster_people !== used_people + zero_people ||
+ missing_names > roster_people ||
+ total > roster_people ||
+ page < 1 ||
+ page > 100000 ||
+ limit < 1 ||
+ limit > 100
+ )
+ fail()
+ if (!Array.isArray(v.rows) || !Array.isArray(v.department_options)) return fail()
+ const keys = new Set()
+ const rows = v.rows.map((raw: unknown) => {
+ const r = obj(raw),
+ key = text(r.key),
+ name = text(r.name),
+ region = text(r.region),
+ state = text(r.state)
+ if (
+ !key ||
+ keys.has(key) ||
+ name.length > 1000 ||
+ !['matched', 'unassigned', 'cross_region'].includes(state) ||
+ (state === 'matched' && !regions.includes(region)) ||
+ (state !== 'matched' && region !== '')
+ )
+ fail()
+ keys.add(key)
+ if (!Array.isArray(r.departments)) return fail()
+ const q = count(r.questions),
+ s = count(r.succeeded),
+ f = count(r.failed),
+ o = count(r.other)
+ if (s + f + o !== q) fail()
+ return {
+ key,
+ name,
+ region,
+ state: state as MonthlyPerson['state'],
+ departments: r.departments.map(text),
+ questions: q,
+ succeeded: s,
+ failed: f,
+ other: o,
+ }
+ })
+ const offset = (page - 1) * limit
+ if (
+ rows.length !== Math.max(0, Math.min(limit, total - offset)) ||
+ has_more !== offset + rows.length < total ||
+ rows.reduce((n, r) => n + r.questions, 0) > linked_questions
+ )
+ fail()
+ const ids = new Set()
+ const department_options = v.department_options.map((raw: unknown) => {
+ const d = obj(raw),
+ id = text(d.id),
+ path = text(d.path)
+ if (!id || !path || ids.has(id)) fail()
+ ids.add(id)
+ return { id, path }
+ })
+ return {
+ organization,
+ source: '2.0',
+ timezone: 'Asia/Shanghai',
+ month,
+ start,
+ end,
+ month_end,
+ as_of,
+ partial,
+ questions,
+ linked_questions,
+ unresolved_questions,
+ roster_people,
+ used_people,
+ zero_people,
+ missing_names,
+ total,
+ page,
+ limit,
+ has_more,
+ rows,
+ department_options,
+ }
+}
+export async function fetchQAMonthly(q: MonthlyQuery, signal?: AbortSignal): Promise {
+ return parseQAMonthly(
+ await getPayload('/api/v1/qa-ops/usage/people', signal, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json', 'X-Governance-Action': 'qa-usage-read' },
+ body: JSON.stringify(q),
+ })
+ )
+}
+export function beijingMonth(now = new Date()): string {
+ const parts = new Intl.DateTimeFormat('en-CA', {
+ timeZone: 'Asia/Shanghai',
+ year: 'numeric',
+ month: '2-digit',
+ }).formatToParts(now)
+ return `${parts.find((p) => p.type === 'year')!.value}-${parts.find((p) => p.type === 'month')!.value}`
+}
diff --git a/web/src/qaOps.css b/web/src/qaOps.css
index 48dda03..1414585 100644
--- a/web/src/qaOps.css
+++ b/web/src/qaOps.css
@@ -7,6 +7,54 @@
height: calc(100dvh - 44px);
overflow: hidden;
}
+.qa-ops-query.qa-monthly-query {
+ display: grid;
+ grid-template-columns: repeat(3, minmax(0, 1fr));
+}
+.qa-monthly-query label {
+ min-width: 0;
+}
+.qa-monthly-query select,
+.qa-monthly-query input {
+ width: 100%;
+ min-width: 0;
+}
+.qa-monthly-query select {
+ min-height: 36px;
+ padding: 7px;
+ color: var(--ink-strong);
+ background: var(--bg-panel);
+ border: 1px solid var(--border-strong);
+ border-radius: var(--r-sm);
+}
+.qa-monthly-results > .qa-ops-muted {
+ margin: 6px 14px;
+ font-size: 12px;
+ line-height: 1.5;
+}
+.qa-ops-table.qa-monthly-table {
+ min-width: 800px;
+ table-layout: fixed;
+}
+.qa-monthly-table th:nth-child(1) {
+ width: 15%;
+}
+.qa-monthly-table th:nth-child(2) {
+ width: 30%;
+}
+.qa-monthly-table th:nth-child(3) {
+ width: 23%;
+}
+.qa-monthly-table td:nth-child(1),
+.qa-monthly-table td:nth-child(2) {
+ white-space: normal;
+ overflow-wrap: anywhere;
+}
+@media (max-width: 760px) {
+ .qa-ops-query.qa-monthly-query {
+ grid-template-columns: minmax(0, 1fr);
+ }
+}
.qa-ops-header h2 {
margin: 0 0 5px;
font-size: 21px;
diff --git a/web/src/qaOps.ts b/web/src/qaOps.ts
index 561d1b6..da9713c 100644
--- a/web/src/qaOps.ts
+++ b/web/src/qaOps.ts
@@ -231,8 +231,12 @@ export function parseQARecordPage(value: unknown): QARecordPage {
}
}
-export async function getPayload(path: string, signal?: AbortSignal): Promise {
- const response = await fetch(path, { credentials: 'same-origin', cache: 'no-store', signal })
+export async function getPayload(
+ path: string,
+ signal?: AbortSignal,
+ request: Pick = {}
+): Promise {
+ const response = await fetch(path, { ...request, credentials: 'same-origin', cache: 'no-store', signal })
const raw: unknown = await response.json().catch(() => null)
if (!response.ok) {
const payload = raw && typeof raw === 'object' ? (raw as Record) : null
--
2.52.0
From 4b3aaff3219e78ae3dfd5d12ba36f82e323a21ba Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Sat, 17 Oct 2026 22:37:26 +0800
Subject: [PATCH 08/14] =?UTF-8?q?feat(qa-ops):=20=E5=AE=8C=E6=88=90?=
=?UTF-8?q?=E5=A4=8D=E6=A3=80=E7=95=99=E6=A1=A3=E4=B8=8E=E4=BA=BA=E5=B7=A5?=
=?UTF-8?q?=E5=A4=8D=E6=A0=B8=E9=97=AD=E7=8E=AF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
治理侧保存输入观测版本、自动复检及人工复核历史,输入变化失效、版本冲突和幂等重放不覆盖人工记录。批量质量数量使用完整筛选元数据,未采集原文不伪造快照,延迟旧扫描不回退新输入。
验证:全仓 make verify 退出码0,Go656及前端253通过;五包竞态、源/组织/质量隔离PG、真实只读源和隔离网页读回复核通过。默认91个可选集成跳过不计通过。未接AI模型,不写DobotAI源库,未推送、未合并、未部署。
---
CHANGELOG.md | 3 +
api/openapi.yaml | 4 +
cmd/api/main.go | 2 +
internal/dobotaiops/organization_records.go | 6 +-
.../organization_records_integration_test.go | 12 +
internal/dobotaiops/quality_records.go | 50 ++
internal/dobotaiops/records.go | 67 ++-
internal/httpapi/qa_ops.go | 8 +
internal/httpapi/qa_org_sync.go | 7 +-
internal/httpapi/qa_quality.go | 264 ++++++++++
internal/httpapi/qa_quality_test.go | 171 +++++++
internal/httpapi/server.go | 6 +
.../migrations/000049_qa_ops_quality.down.sql | 4 +
.../migrations/000049_qa_ops_quality.up.sql | 13 +
internal/platform/postgres/migrations_test.go | 4 +-
internal/qaopsorg/store_integration_test.go | 13 +
internal/qaopsquality/projection.go | 125 +++++
internal/qaopsquality/quality.go | 98 ++++
internal/qaopsquality/quality_test.go | 73 +++
internal/qaopsquality/store.go | 322 ++++++++++++
.../qaopsquality/store_integration_test.go | 219 ++++++++
scripts/test-scope.json | 1 +
web/src/QAOperations.tsx | 53 +-
web/src/QAQuality.test.tsx | 43 ++
web/src/QAQuality.tsx | 483 ++++++++++++++++++
web/src/qaOps.css | 75 +++
web/src/qaOps.ts | 22 +
web/src/qaQuality.fixture.ts | 50 ++
web/src/qaQuality.test.ts | 51 ++
web/src/qaQuality.ts | 264 ++++++++++
30 files changed, 2483 insertions(+), 30 deletions(-)
create mode 100644 internal/dobotaiops/quality_records.go
create mode 100644 internal/httpapi/qa_quality.go
create mode 100644 internal/httpapi/qa_quality_test.go
create mode 100644 internal/platform/postgres/migrations/000049_qa_ops_quality.down.sql
create mode 100644 internal/platform/postgres/migrations/000049_qa_ops_quality.up.sql
create mode 100644 internal/qaopsquality/projection.go
create mode 100644 internal/qaopsquality/quality.go
create mode 100644 internal/qaopsquality/quality_test.go
create mode 100644 internal/qaopsquality/store.go
create mode 100644 internal/qaopsquality/store_integration_test.go
create mode 100644 web/src/QAQuality.test.tsx
create mode 100644 web/src/QAQuality.tsx
create mode 100644 web/src/qaQuality.fixture.ts
create mode 100644 web/src/qaQuality.test.ts
create mode 100644 web/src/qaQuality.ts
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2ec92f3..0e85801 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,9 @@
### Added
+- 问答详情支持治理侧人工复核及不可变审计:覆盖、正确性、产品分类、问题类型、根因与理由由管理员明确填写,操作人取登录身份;保存后独立读回复核历史。保留源端判断和自动规则,输入变化使旧人工结论失效,已观测的内容回退不自动恢复旧结论;并发修改冲突、重复请求不重复留档。
+- 新增覆盖复检历史、已采集输入快照和完整筛选范围质量数量。批量统计只传指纹与规则命中元数据,原文在读取问答/复核时采集,未采集版本明确提示而非伪造空快照;源事务时点阻止延迟旧扫描回退新输入。仅提供数量,不接 AI 模型、不定义质量率或绩效分母、不回写 DobotAI 原问答。
+
- 「使用统计 → 个人月明细」按北京时间自然月及截止时点展示当前应用可见名册的人员用量(包含本源零记录),支持部门含子部门、区域/待核对状态、姓名/完整部门路径和已有提问/零记录筛选。稳定身份关联去重、不可关联问答单列、过期组织版本阻断翻页;源端姓名可缺失并提示重新同步,不按姓名匹配身份。姓名筛选通过有界只读 POST 请求体传递、不进入 URL,原始员工标识不返回浏览器;名册不作为在职/考核分母,当月进度不作为绩效结论。
- 问答运营按稳定身份关联当前治理通讯录,缺失部门/区域补全并保留源快照及目录/区域版本;空列判断包含完整筛选结果,不混合配置已变化的分页。新增完整时间/关键词范围的使用统计,问答计次、名册内人员去重,跨区/未匹配/身份缺失分列,不输出绩效结论;不回写 DobotAI 原表。
diff --git a/api/openapi.yaml b/api/openapi.yaml
index de788fc..c931a07 100644
--- a/api/openapi.yaml
+++ b/api/openapi.yaml
@@ -101,6 +101,10 @@
},
"/api/v1/qa-ops/usage/people": {"post": {"tags": ["QA operations"], "operationId": "queryQAOperationsMonthlyPeople", "summary": "按北京时间自然月列出当前名册人员的2.0用量(含零记录),仅管理员,不返回原始员工标识,不作为在职/考核名单", "responses": {"200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"description": "需要登录"}, "403": {"description": "仅管理员访问"}, "503": {"description": "独立只读源或治理组织存储不可用,不返回伪造的零值"}, "500": {"$ref": "#/components/responses/InternalError"}, "409": {"description": "完整名册缺失或目录/区域版本变化,请同步/重新查询,不返回伪零"}}, "description": "只读查询,不写治理库或生产库;姓名筛选置于 JSON 请求体,不进入 URL;整名册指标不随人员筛选变化。第2页起须带首页目录、区域版本及 end 截止。", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["month"], "properties": {"month": {"type": "string", "pattern": "^(?!0000)[0-9]{4}-(0[1-9]|1[0-2])$"}, "cutoff": {"type": "string", "format": "date-time"}, "region": {"type": "string", "enum": ["国内工业", "APAC", "EMEA", "America", "unassigned", "cross_region"]}, "department_id": {"type": "string"}, "activity": {"type": "string", "enum": ["all", "used", "zero"]}, "search": {"type": "string", "maxLength": 100}, "page": {"type": "integer", "minimum": 1, "maximum": 100000, "default": 1}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 30}, "directory_id": {"type": "string"}, "revision_id": {"type": "string"}}}}}}, "parameters": [{"name": "X-Governance-Action", "in": "header", "required": true, "schema": {"type": "string", "enum": ["qa-usage-read"]}}]}},
"/api/v1/qa-ops/usage": {"get": {"tags": ["QA operations"], "operationId": "getQAOperationsUsage", "summary": "完整筛选范围内按当前通讯录和区域版本回看2.0问答使用;固定租户、管理员访问,不输出绩效结论", "parameters": [{"name": "start", "in": "query", "required": true, "schema": {"type": "string", "format": "date-time"}}, {"name": "end", "in": "query", "required": true, "schema": {"type": "string", "format": "date-time"}}, {"name": "keyword", "in": "query", "schema": {"type": "string", "maxLength": 200}}], "responses": {"200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"description": "需要登录"}, "403": {"description": "仅管理员访问"}, "503": {"description": "独立只读源或治理组织存储不可用,不返回伪造的零值"}, "500": {"$ref": "#/components/responses/InternalError"}}}},
+ "/api/v1/qa-ops/quality/query": {"post": {"operationId": "queryQAQualityCounts", "summary": "按完整时间/原问题字面关键词读取指纹及规则命中元数据并留档统计,原文仅在读取问答/复核时采集;不计算质量率,最多5000条", "parameters": [{"name": "X-Governance-Action", "in": "header", "required": true, "schema": {"type": "string", "enum": ["qa-quality"]}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "properties": {"start": {"type": "string", "format": "date-time"}, "end": {"type": "string", "format": "date-time"}, "keyword": {"type": "string", "maxLength": 200}}, "required": ["start", "end"]}}}}, "tags": ["QA operations"], "responses": {"200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"description": "需要登录"}, "403": {"description": "仅管理员访问"}, "503": {"description": "独立只读源或治理组织存储不可用,不返回伪造的零值"}, "500": {"$ref": "#/components/responses/InternalError"}, "409": {"description": "输入或复核版本变化/重复操作载荷不一致,未覆盖原结论"}, "404": {"description": "当前授权范围内未找到记录/历史输入"}}}},
+ "/api/v1/qa-ops/records/{id}/reviews": {"post": {"operationId": "saveQAQualityReview", "summary": "治理库追加人工复核,登录身份审计,源端只读,输入/复核乐观锁和nonce幂等;正确时根因为空,不计入须说明原因", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "X-Governance-Action", "in": "header", "required": true, "schema": {"type": "string", "enum": ["qa-quality"]}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "properties": {"input_hash": {"type": "string", "pattern": "^[a-f0-9]{64}$"}, "input_epoch": {"type": "integer", "minimum": 1}, "base_revision": {"type": "integer", "minimum": 0}, "nonce": {"type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$"}, "fields": {"type": "object", "additionalProperties": false, "properties": {"coverage": {"type": "string", "enum": ["covered", "uncovered", "partial", "pending", "excluded"]}, "correctness": {"type": "string", "enum": ["correct", "incorrect", "pending"]}, "product_category": {"type": "string", "maxLength": 128}, "problem_type": {"type": "string", "maxLength": 128}, "root_cause": {"type": "string", "maxLength": 2000}, "exclusion_reason": {"type": "string", "maxLength": 2000}}, "required": ["coverage", "correctness"]}, "reason": {"type": "string", "minLength": 1, "maxLength": 4000}}, "required": ["input_hash", "input_epoch", "base_revision", "nonce", "fields", "reason"]}}}}, "tags": ["QA operations"], "responses": {"200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"description": "需要登录"}, "403": {"description": "仅管理员访问"}, "503": {"description": "独立只读源或治理组织存储不可用,不返回伪造的零值"}, "500": {"$ref": "#/components/responses/InternalError"}, "409": {"description": "输入或复核版本变化/重复操作载荷不一致,未覆盖原结论"}, "404": {"description": "当前授权范围内未找到记录/历史输入"}}}},
+ "/api/v1/qa-ops/records/{id}/quality/history": {"get": {"operationId": "listQAQualityHistory", "summary": "按当前固定租户查询不可变复检/人工历史,分别倒序分页,各20条", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "review_before", "in": "query", "schema": {"type": "integer", "minimum": 1}}, {"name": "check_before", "in": "query", "schema": {"type": "integer", "minimum": 1}}], "tags": ["QA operations"], "responses": {"200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"description": "需要登录"}, "403": {"description": "仅管理员访问"}, "503": {"description": "独立只读源或治理组织存储不可用,不返回伪造的零值"}, "500": {"$ref": "#/components/responses/InternalError"}, "409": {"description": "输入或复核版本变化/重复操作载荷不一致,未覆盖原结论"}, "404": {"description": "当前授权范围内未找到记录/历史输入"}}}},
+ "/api/v1/qa-ops/records/{id}/quality/inputs/{epoch}": {"get": {"operationId": "getQAQualityInputSnapshot", "summary": "管理员读取已采集的历史质量输入快照,不另存人员关联/反馈字段;元数据留档但未采集原文返回409,不编造空快照", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "epoch", "in": "path", "required": true, "schema": {"type": "integer", "minimum": 1}}], "tags": ["QA operations"], "responses": {"200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"description": "需要登录"}, "403": {"description": "仅管理员访问"}, "503": {"description": "独立只读源或治理组织存储不可用,不返回伪造的零值"}, "500": {"$ref": "#/components/responses/InternalError"}, "409": {"description": "该输入版本仅有指纹/规则元数据、原文未采集"}, "404": {"description": "当前授权范围内未找到记录/历史输入"}}}},
"/api/v1/qa-ops/status": {
"get": {
"tags": ["QA operations"],
diff --git a/cmd/api/main.go b/cmd/api/main.go
index 36417e5..ca18dae 100644
--- a/cmd/api/main.go
+++ b/cmd/api/main.go
@@ -21,6 +21,7 @@ import (
postgresstore "knowledge-governance/internal/platform/postgres"
"knowledge-governance/internal/platform/weknora"
"knowledge-governance/internal/qaopsorg"
+ "knowledge-governance/internal/qaopsquality"
"knowledge-governance/internal/serviceverify"
)
@@ -143,6 +144,7 @@ func run(ctx context.Context, getenv func(string) string) error {
qaSyncStore = qaOrganizationStore
}
handler, err := httpapi.NewHandler(httpapi.Config{
+ QAQuality: qaopsquality.NewStore(pool, getenv("DOBOTAI_OPS_TENANT_KEY")),
QAOrgSync: qaSyncStore,
QAOrgSyncEnabled: qaSyncErr == nil && qaSyncSettings.Enabled,
QAOrg: qaOrganizationStore,
diff --git a/internal/dobotaiops/organization_records.go b/internal/dobotaiops/organization_records.go
index aecb026..8e42836 100644
--- a/internal/dobotaiops/organization_records.go
+++ b/internal/dobotaiops/organization_records.go
@@ -44,12 +44,16 @@ type UsageGroups struct {
func decodeRecord(raw string) (Record, error) {
var wire struct {
Record
- Identity ActorIdentity `json:"_identity"`
+ Identity ActorIdentity `json:"_identity"`
+ QualityHash string `json:"_quality_hash"`
+ QualityObservedAt time.Time `json:"_quality_observed_at"`
}
if err := json.Unmarshal([]byte(raw), &wire); err != nil {
return Record{}, err
}
wire.Record.Identity = wire.Identity
+ wire.Record.QualityInputHash = wire.QualityHash
+ wire.Record.QualityObservedAt = wire.QualityObservedAt
wire.Record.Coverage = CheckAnswerCoverage(wire.Record.Answer)
return wire.Record, nil
}
diff --git a/internal/dobotaiops/organization_records_integration_test.go b/internal/dobotaiops/organization_records_integration_test.go
index fd339d9..b3aa02e 100644
--- a/internal/dobotaiops/organization_records_integration_test.go
+++ b/internal/dobotaiops/organization_records_integration_test.go
@@ -27,6 +27,9 @@ func TestQARecordInternalIdentityAndWholeFilterKeys(t *testing.T) {
found = true
}
}
+ if len(page.ScopeQuality) != 4 || len(page.Items[0].QualityInputHash) != 64 {
+ t.Fatal("whole-scope quality versions missing")
+ }
if !found {
t.Fatal("whole-filter keys missing; later-page department would be hidden")
}
@@ -34,6 +37,15 @@ func TestQARecordInternalIdentityAndWholeFilterKeys(t *testing.T) {
if err != nil || item.Identity.StaffID != "ext-actor-1" || item.Identity.UnionID != "fixture-union" {
t.Fatalf("stable identity not read from inbound actor/message: %v", err)
}
+ scope, se := client.ReadQualityScope(context.Background(), query)
+ if se != nil || len(scope.Keys) != 4 || scope.AsOf.IsZero() {
+ t.Fatal("quality metadata scope incomplete", se)
+ }
+ for _, key := range scope.Keys {
+ if len(key.InputHash) != 64 || key.ObservedAt.IsZero() {
+ t.Fatal("scope omitted input version")
+ }
+ }
raw, _ := json.Marshal(page)
detail, _ := json.Marshal(item)
for _, s := range []string{string(raw), string(detail)} {
diff --git a/internal/dobotaiops/quality_records.go b/internal/dobotaiops/quality_records.go
new file mode 100644
index 0000000..220b3cc
--- /dev/null
+++ b/internal/dobotaiops/quality_records.go
@@ -0,0 +1,50 @@
+package dobotaiops
+
+import (
+ "context"
+ "encoding/json"
+ "time"
+)
+
+type QualityScope struct {
+ Keys []QualityKey
+ AsOf time.Time
+}
+
+func (c *Client) ReadQualityScope(ctx context.Context, query RecordQuery) (QualityScope, error) {
+ if err := c.validateQueryWindow(query.Window); err != nil {
+ return QualityScope{}, err
+ }
+ if query.Cursor != "" {
+ return QualityScope{}, ErrInvalidQuery
+ }
+ pattern, err := recordKeywordPattern(query.Keyword)
+ if err != nil {
+ return QualityScope{}, err
+ }
+ result := QualityScope{Keys: []QualityKey{}}
+ err = c.withReadOnlyTx(ctx, func(ctx context.Context, q querier) error {
+ if q.QueryRow(ctx, "SELECT transaction_timestamp()").Scan(&result.AsOf) != nil {
+ return ErrUnavailable
+ }
+ rows, err := q.Query(ctx, recordsBaseSQL+` SELECT id,quality_hash,strpos(payload->>'answer',$5)>0,(payload->'source_coverage')::text FROM records WHERE `+recordFilterSQL+` ORDER BY id LIMIT 5001`, query.Window.TenantKey, query.Window.Start, query.Window.End, pattern, noPublishedMarker)
+ if err != nil {
+ return ErrUnavailable
+ }
+ defer rows.Close()
+ for rows.Next() {
+ var key QualityKey
+ var raw string
+ if rows.Scan(&key.ID, &key.InputHash, &key.Marker, &raw) != nil || json.Unmarshal([]byte(raw), &key.Source) != nil {
+ return ErrUnavailable
+ }
+ if len(result.Keys) >= 5000 {
+ return ErrInvalidQuery
+ }
+ key.ObservedAt = result.AsOf
+ result.Keys = append(result.Keys, key)
+ }
+ return rows.Err()
+ })
+ return result, err
+}
diff --git a/internal/dobotaiops/records.go b/internal/dobotaiops/records.go
index 71fef89..dc035b7 100644
--- a/internal/dobotaiops/records.go
+++ b/internal/dobotaiops/records.go
@@ -29,8 +29,11 @@ type CoverageCheck struct {
// Absence of this exact substring is not evidence that knowledge covers a question.
func CheckAnswerCoverage(answer string) CoverageCheck {
+ return CheckMarkerCoverage(strings.Contains(answer, noPublishedMarker))
+}
+func CheckMarkerCoverage(matched bool) CoverageCheck {
result := CoverageCheck{State: "pending", RuleVersion: CoverageRuleVersion}
- if strings.Contains(answer, noPublishedMarker) {
+ if matched {
result.State = "checked"
result.Verdict = "uncovered"
result.MatchedText = noPublishedMarker
@@ -51,23 +54,26 @@ type RecordFeedback struct {
}
type Record struct {
- Identity ActorIdentity `json:"-"`
- Organization *RecordOrganization `json:"organization,omitempty"`
- ID string `json:"id"`
- Status string `json:"status"`
- Question string `json:"question"`
- Answer string `json:"answer"`
- AskedAt time.Time `json:"asked_at"`
- TimeSource string `json:"time_source"`
- Asker string `json:"asker"`
- TriggerPerson string `json:"trigger_person"`
- Department string `json:"department"`
- Region string `json:"region"`
- References json.RawMessage `json:"references"`
- Media json.RawMessage `json:"media"`
- SourceCoverage SourceCoverage `json:"source_coverage"`
- Feedback RecordFeedback `json:"feedback"`
- Coverage CoverageCheck `json:"coverage"`
+ QualityObservedAt time.Time `json:"-"`
+ QualityInputHash string `json:"-"`
+ Quality json.RawMessage `json:"quality,omitempty"`
+ Identity ActorIdentity `json:"-"`
+ Organization *RecordOrganization `json:"organization,omitempty"`
+ ID string `json:"id"`
+ Status string `json:"status"`
+ Question string `json:"question"`
+ Answer string `json:"answer"`
+ AskedAt time.Time `json:"asked_at"`
+ TimeSource string `json:"time_source"`
+ Asker string `json:"asker"`
+ TriggerPerson string `json:"trigger_person"`
+ Department string `json:"department"`
+ Region string `json:"region"`
+ References json.RawMessage `json:"references"`
+ Media json.RawMessage `json:"media"`
+ SourceCoverage SourceCoverage `json:"source_coverage"`
+ Feedback RecordFeedback `json:"feedback"`
+ Coverage CoverageCheck `json:"coverage"`
}
type RecordQuery struct {
@@ -77,7 +83,15 @@ type RecordQuery struct {
Limit int
}
+type QualityKey struct {
+ ObservedAt time.Time `json:"-"`
+ Marker bool `json:"marker"`
+ Source SourceCoverage `json:"source"`
+ ID string `json:"id"`
+ InputHash string `json:"input_hash"`
+}
type RecordPage struct {
+ ScopeQuality []QualityKey `json:"-"`
ScopeActors []ActorIdentity `json:"-"`
Organization *OrganizationVersion `json:"organization,omitempty"`
Items []Record `json:"items"`
@@ -97,11 +111,12 @@ type recordCursor struct {
// A single inbound-message join controls names/time. Feedback is preaggregated;
// joining each feedback row directly would multiply the business event count.
const actorIdentitySQL = `jsonb_build_object('actor_id',COALESCE(a.id,''),'staff_id',COALESCE(a.external_actor_id,''),'union_id',COALESCE(m.actor_union_id_snapshot,''))`
+const qualityHashSQL = `encode(sha256(convert_to(jsonb_build_array('quality-input-v1',t.id,t.status,t.question,t.answer,t.references_json,COALESCE(m.media_json,'[]'::jsonb))::text,'UTF8')),'hex')`
const recordsBaseSQL = `
WITH records AS (
- SELECT t.id,COALESCE(m.created_at,t.created_at) AS asked_at,t.question,t.status,` + actorIdentitySQL + ` AS identity,
+ SELECT t.id,COALESCE(m.created_at,t.created_at) AS asked_at,t.question,t.status,` + actorIdentitySQL + ` AS identity,` + qualityHashSQL + ` AS quality_hash,
jsonb_build_object(
- '_identity',` + actorIdentitySQL + `,
+ '_identity',` + actorIdentitySQL + `, '_quality_hash',` + qualityHashSQL + `,'_quality_observed_at',transaction_timestamp(),
'id',t.id,'status',t.status,'question',t.question,'answer',t.answer,
'asked_at',COALESCE(m.created_at,t.created_at),
'time_source',CASE WHEN m.id IS NULL THEN 'turn.created_at' ELSE 'request_message.created_at' END,
@@ -143,7 +158,7 @@ const recordColumnsSQL = `SELECT count(*),jsonb_build_object(
'region',COALESCE(bool_or(payload->>'region'<>''),false),
'feedback',COALESCE(bool_or(payload->'feedback'->>'asker_value'<>'' OR
(payload->'feedback'->>'up')::bigint>0 OR (payload->'feedback'->>'down')::bigint>0),false)
- )::text,COALESCE(jsonb_agg(DISTINCT identity),'[]'::jsonb)::text FROM records WHERE `
+ )::text,COALESCE(jsonb_agg(DISTINCT identity),'[]'::jsonb)::text,COALESCE(jsonb_agg(jsonb_build_object('id',id,'input_hash',quality_hash,'marker',strpos(payload->>'answer',$5)>0,'source',payload->'source_coverage')),'[]'::jsonb)::text FROM records WHERE `
var recordColumnOrder = []string{"question_chinese", "answer", "coverage", "is_correct", "product_category", "problem_type", "root_cause", "asked_at", "asker", "question", "language", "trigger_person", "department", "region", "feedback"}
@@ -186,10 +201,16 @@ func (c *Client) ListRecords(ctx context.Context, query RecordQuery) (RecordPage
if err := q.QueryRow(ctx, "SELECT transaction_timestamp()").Scan(&page.AsOf); err != nil {
return ErrUnavailable
}
- var rawColumns, rawActors string
- if err := q.QueryRow(ctx, recordsBaseSQL+recordColumnsSQL+recordFilterSQL, append(args, noPublishedMarker)...).Scan(&page.Total, &rawColumns, &rawActors); err != nil {
+ var rawColumns, rawActors, rawQuality string
+ if err := q.QueryRow(ctx, recordsBaseSQL+recordColumnsSQL+recordFilterSQL, append(args, noPublishedMarker)...).Scan(&page.Total, &rawColumns, &rawActors, &rawQuality); err != nil {
return fmt.Errorf("%w: record count failed", ErrUnavailable)
}
+ if json.Unmarshal([]byte(rawQuality), &page.ScopeQuality) != nil {
+ return ErrUnavailable
+ }
+ for i := range page.ScopeQuality {
+ page.ScopeQuality[i].ObservedAt = page.AsOf
+ }
var available map[string]bool
if json.Unmarshal([]byte(rawActors), &page.ScopeActors) != nil {
return ErrUnavailable
diff --git a/internal/httpapi/qa_ops.go b/internal/httpapi/qa_ops.go
index 9fb8ac7..f9b0889 100644
--- a/internal/httpapi/qa_ops.go
+++ b/internal/httpapi/qa_ops.go
@@ -104,6 +104,10 @@ func listQAOpsRecords(w http.ResponseWriter, r *http.Request, config Config) {
return
}
enrichQAPage(&page, projection)
+ if err := enrichQAQualityPage(r.Context(), config, &page); err != nil {
+ writeQualityError(w, err)
+ return
+ }
writeJSON(w, http.StatusOK, map[string]any{"data": page})
}
@@ -130,6 +134,10 @@ func getQAOpsRecord(w http.ResponseWriter, r *http.Request, config Config) {
return
}
enrichQARecord(&item, projection)
+ if err := enrichQAQualityRecord(r.Context(), config, &item); err != nil {
+ writeQualityError(w, err)
+ return
+ }
writeJSON(w, http.StatusOK, map[string]any{"data": item})
}
diff --git a/internal/httpapi/qa_org_sync.go b/internal/httpapi/qa_org_sync.go
index 9ffad8e..3f3f982 100644
--- a/internal/httpapi/qa_org_sync.go
+++ b/internal/httpapi/qa_org_sync.go
@@ -17,8 +17,11 @@ type QAOrgSyncStore interface {
}
func authorizeQAOrganizationWrite(w http.ResponseWriter, r *http.Request) bool {
- if r.Header.Get("X-Governance-Action") != "qa-organization" || r.Header.Get("Sec-Fetch-Site") == "cross-site" {
- writeJSON(w, 403, map[string]string{"error": "区域配置需要同源操作意图"})
+ return authorizeQAIntent(w, r, "qa-organization")
+}
+func authorizeQAIntent(w http.ResponseWriter, r *http.Request, intent string) bool {
+ if r.Header.Get("X-Governance-Action") != intent || r.Header.Get("Sec-Fetch-Site") == "cross-site" {
+ writeJSON(w, 403, map[string]string{"error": "此操作需要同源操作意图"})
return false
}
// Fetch Metadata survives same-origin proxies that rewrite Host; untrusted
diff --git a/internal/httpapi/qa_quality.go b/internal/httpapi/qa_quality.go
new file mode 100644
index 0000000..9fd4fe1
--- /dev/null
+++ b/internal/httpapi/qa_quality.go
@@ -0,0 +1,264 @@
+package httpapi
+
+import (
+ "bytes"
+ "context"
+ "encoding/json"
+ "errors"
+ "io"
+ "knowledge-governance/internal/dobotaiops"
+ "knowledge-governance/internal/qaopsquality"
+ "net/http"
+ "strconv"
+ "time"
+)
+
+type QAQualityStore interface {
+ ObserveKeys(context.Context, []dobotaiops.QualityKey) (map[string]qaopsquality.View, error)
+ Observe(context.Context, []dobotaiops.Record) (map[string]qaopsquality.View, error)
+ Save(context.Context, dobotaiops.Record, qaopsquality.SaveRequest, string) (qaopsquality.Receipt, error)
+ Columns(context.Context, []dobotaiops.QualityKey) ([]string, error)
+ History(context.Context, string, int64, int64) (qaopsquality.History, error)
+ Snapshot(context.Context, string, int64) (qaopsquality.Snapshot, error)
+}
+
+type qaQualityReader interface {
+ ReadQualityScope(context.Context, dobotaiops.RecordQuery) (dobotaiops.QualityScope, error)
+}
+
+func writeQualityError(w http.ResponseWriter, err error) {
+ status, code, message := 503, "quality_unavailable", "质量留档/复核存储不可用,未将失败伪装为空值或零统计"
+ switch {
+ case errors.Is(err, qaopsquality.ErrInvalid) || errors.Is(err, dobotaiops.ErrInvalidQuery):
+ status, code, message = 400, "invalid_quality_request", "质量操作参数无效:请核对结论、理由、版本和筛选范围(最多5000条/32MiB)"
+ case errors.Is(err, qaopsquality.ErrConflict):
+ status, code, message = 409, "quality_conflict", "原始问答或人工复核版本已变化,请重新读取问答后核对;未覆盖现有结论"
+ case errors.Is(err, qaopsquality.ErrSnapshotMissing):
+ status, code, message = 409, "quality_input_metadata_only", "此版本仅留存指纹与复检元数据,未采集原文;未编造空问题或空答案"
+ case errors.Is(err, qaopsquality.ErrNotFound):
+ status, code, message = 404, "quality_input_not_found", "未找到当前授权范围的输入版本"
+ }
+ writeJSON(w, status, map[string]string{"error": message, "code": code})
+}
+func enrichQAQualityRecord(ctx context.Context, c Config, item *dobotaiops.Record) error {
+ if c.QAQuality == nil {
+ return nil
+ }
+ views, err := c.QAQuality.Observe(ctx, []dobotaiops.Record{*item})
+ if err != nil {
+ return err
+ }
+ v, ok := views[item.ID]
+ if !ok {
+ return qaopsquality.ErrUnavailable
+ }
+ item.Quality, err = json.Marshal(v)
+ return err
+}
+func enrichQAQualityPage(ctx context.Context, c Config, page *dobotaiops.RecordPage) error {
+ if c.QAQuality == nil {
+ return nil
+ }
+ views, err := c.QAQuality.Observe(ctx, page.Items)
+ if err != nil {
+ return err
+ }
+ for i := range page.Items {
+ v, ok := views[page.Items[i].ID]
+ if !ok {
+ return qaopsquality.ErrUnavailable
+ }
+ page.Items[i].Quality, err = json.Marshal(v)
+ if err != nil {
+ return err
+ }
+ }
+ columns, err := c.QAQuality.Columns(ctx, page.ScopeQuality)
+ if err != nil {
+ return err
+ }
+ dobotaiops.AddRecordColumns(page, columns...)
+ return nil
+}
+func walkQualityJSON(d *json.Decoder) error {
+ token, err := d.Token()
+ if err != nil {
+ return err
+ }
+ if token == nil {
+ return qaopsquality.ErrInvalid
+ }
+ if delimiter, ok := token.(json.Delim); ok {
+ if delimiter != '{' && delimiter != '[' {
+ return qaopsquality.ErrInvalid
+ }
+ keys := map[string]bool{}
+ for d.More() {
+ if delimiter == '{' {
+ key, e := d.Token()
+ name, ok := key.(string)
+ if e != nil || !ok || keys[name] {
+ return qaopsquality.ErrInvalid
+ }
+ keys[name] = true
+ }
+ if walkQualityJSON(d) != nil {
+ return qaopsquality.ErrInvalid
+ }
+ }
+ _, err = d.Token()
+ return err
+ }
+ return nil
+}
+func decodeQualityJSON(w http.ResponseWriter, r *http.Request, target any, required ...string) error {
+ if r.URL.RawQuery != "" {
+ return qaopsquality.ErrInvalid
+ }
+ raw, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 64<<10))
+ if err != nil || bytes.Equal(bytes.TrimSpace(raw), []byte("null")) {
+ return qaopsquality.ErrInvalid
+ }
+ var top map[string]json.RawMessage
+ if json.Unmarshal(raw, &top) != nil || top == nil {
+ return qaopsquality.ErrInvalid
+ }
+ for _, key := range required {
+ if _, ok := top[key]; !ok {
+ return qaopsquality.ErrInvalid
+ }
+ }
+ check := json.NewDecoder(bytes.NewReader(raw))
+ if walkQualityJSON(check) != nil {
+ return qaopsquality.ErrInvalid
+ }
+ var extra any
+ if check.Decode(&extra) != io.EOF {
+ return qaopsquality.ErrInvalid
+ }
+ d := json.NewDecoder(bytes.NewReader(raw))
+ d.DisallowUnknownFields()
+ if d.Decode(target) != nil || d.Decode(&extra) != io.EOF {
+ return qaopsquality.ErrInvalid
+ }
+ return nil
+}
+func qaQualityReview(w http.ResponseWriter, r *http.Request, c Config) {
+ if !authorizeQAOps(w, r) || !authorizeQAIntent(w, r, "qa-quality") {
+ return
+ }
+ var request qaopsquality.SaveRequest
+ if decodeQualityJSON(w, r, &request, "input_hash", "input_epoch", "base_revision", "nonce", "fields", "reason") != nil || qaopsquality.Validate(request) != nil {
+ writeQualityError(w, qaopsquality.ErrInvalid)
+ return
+ }
+ if c.QAQuality == nil || c.QAOps == nil || c.QAOpsTenantKey == "" {
+ writeQualityError(w, qaopsquality.ErrUnavailable)
+ return
+ }
+ record, err := c.QAOps.GetRecord(r.Context(), c.QAOpsTenantKey, r.PathValue("id"))
+ if err != nil {
+ qaOpsError(w, err)
+ return
+ }
+ identity, _ := sessionFrom(r.Context())
+ receipt, err := c.QAQuality.Save(r.Context(), record, request, identity.Username)
+ if err != nil {
+ writeQualityError(w, err)
+ return
+ }
+ writeJSON(w, 200, map[string]any{"data": receipt})
+}
+func qaQualityQuery(w http.ResponseWriter, r *http.Request, c Config) {
+ if !authorizeQAOps(w, r) || !authorizeQAIntent(w, r, "qa-quality") {
+ return
+ }
+ var request struct {
+ Start string `json:"start"`
+ End string `json:"end"`
+ Keyword string `json:"keyword"`
+ }
+ if decodeQualityJSON(w, r, &request) != nil {
+ writeQualityError(w, qaopsquality.ErrInvalid)
+ return
+ }
+ window, err := dobotaiops.NewWindow(c.QAOpsTenantKey, request.Start, request.End, 90*24*time.Hour, c.Now())
+ if err != nil {
+ writeQualityError(w, err)
+ return
+ }
+ reader, ok := c.QAOps.(qaQualityReader)
+ if !ok || c.QAQuality == nil {
+ writeQualityError(w, qaopsquality.ErrUnavailable)
+ return
+ }
+ scope, err := reader.ReadQualityScope(r.Context(), dobotaiops.RecordQuery{Window: window, Keyword: request.Keyword})
+ if err != nil {
+ qaOpsError(w, err)
+ return
+ }
+ views, err := c.QAQuality.ObserveKeys(r.Context(), scope.Keys)
+ if err != nil || len(views) != len(scope.Keys) {
+ if err == nil {
+ err = qaopsquality.ErrUnavailable
+ }
+ writeQualityError(w, err)
+ return
+ }
+ writeJSON(w, 200, map[string]any{"data": map[string]any{"summary": qaopsquality.Summarize(views), "start": window.Start, "end": window.End, "keyword": request.Keyword, "as_of": scope.AsOf, "ai_state": "not_configured", "scope": "whole_filter"}})
+}
+func qaQualityHistory(w http.ResponseWriter, r *http.Request, c Config) {
+ if !authorizeQAOps(w, r) {
+ return
+ }
+ if c.QAQuality == nil {
+ writeQualityError(w, qaopsquality.ErrUnavailable)
+ return
+ }
+ values := r.URL.Query()
+ for key, v := range values {
+ if (key != "review_before" && key != "check_before") || len(v) != 1 {
+ writeQualityError(w, qaopsquality.ErrInvalid)
+ return
+ }
+ }
+ cursors := map[string]int64{}
+ for _, key := range []string{"review_before", "check_before"} {
+ raw := values.Get(key)
+ if raw == "" {
+ continue
+ }
+ n, err := strconv.ParseInt(raw, 10, 64)
+ if err != nil || n < 1 {
+ writeQualityError(w, qaopsquality.ErrInvalid)
+ return
+ }
+ cursors[key] = n
+ }
+ value, err := c.QAQuality.History(r.Context(), r.PathValue("id"), cursors["review_before"], cursors["check_before"])
+ if err != nil {
+ writeQualityError(w, err)
+ return
+ }
+ writeJSON(w, 200, map[string]any{"data": value})
+}
+func qaQualitySnapshot(w http.ResponseWriter, r *http.Request, c Config) {
+ if !authorizeQAOps(w, r) {
+ return
+ }
+ epoch, err := strconv.ParseInt(r.PathValue("epoch"), 10, 64)
+ if err != nil || epoch < 1 || r.URL.RawQuery != "" {
+ writeQualityError(w, qaopsquality.ErrInvalid)
+ return
+ }
+ if c.QAQuality == nil {
+ writeQualityError(w, qaopsquality.ErrUnavailable)
+ return
+ }
+ value, err := c.QAQuality.Snapshot(r.Context(), r.PathValue("id"), epoch)
+ if err != nil {
+ writeQualityError(w, err)
+ return
+ }
+ writeJSON(w, 200, map[string]any{"data": value})
+}
diff --git a/internal/httpapi/qa_quality_test.go b/internal/httpapi/qa_quality_test.go
new file mode 100644
index 0000000..c8395ab
--- /dev/null
+++ b/internal/httpapi/qa_quality_test.go
@@ -0,0 +1,171 @@
+package httpapi
+
+import (
+ "context"
+ "encoding/json"
+ "knowledge-governance/internal/dobotaiops"
+ "knowledge-governance/internal/qaopsquality"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+ "time"
+)
+
+type qualityFake struct {
+ actor string
+ calls int
+ fail bool
+}
+
+func (s *qualityFake) Observe(_ context.Context, records []dobotaiops.Record) (map[string]qaopsquality.View, error) {
+ s.calls++
+ if s.fail {
+ return nil, qaopsquality.ErrUnavailable
+ }
+ out := map[string]qaopsquality.View{}
+ for _, r := range records {
+ e, _ := qaopsquality.EvidenceFor(r)
+ out[r.ID] = qaopsquality.Project(e.Hash, 1, 0, qaopsquality.Check{InputEpoch: 1, InputHash: e.Hash, Result: dobotaiops.CheckAnswerCoverage(r.Answer)}, nil)
+ }
+ return out, nil
+}
+func (s *qualityFake) ObserveKeys(_ context.Context, keys []dobotaiops.QualityKey) (map[string]qaopsquality.View, error) {
+ s.calls++
+ out := map[string]qaopsquality.View{}
+ for _, key := range keys {
+ out[key.ID] = qaopsquality.Project(key.InputHash, 1, 0, qaopsquality.Check{Result: dobotaiops.CheckMarkerCoverage(key.Marker)}, nil)
+ }
+ return out, nil
+}
+func (s *qualityFake) Save(_ context.Context, r dobotaiops.Record, q qaopsquality.SaveRequest, actor string) (qaopsquality.Receipt, error) {
+ s.actor = actor
+ v := qaopsquality.Project(q.InputHash, 1, 1, qaopsquality.Check{Result: dobotaiops.CheckAnswerCoverage(r.Answer)}, &qaopsquality.Review{InputEpoch: 1, InputHash: q.InputHash, Fields: q.Fields, Reason: q.Reason, Reviewer: actor})
+ return qaopsquality.Receipt{View: v, SavedRevision: 1}, nil
+}
+func (s *qualityFake) Columns(_ context.Context, keys []dobotaiops.QualityKey) ([]string, error) {
+ return []string{"is_correct", "product_category"}, nil
+}
+func (s *qualityFake) History(context.Context, string, int64, int64) (qaopsquality.History, error) {
+ return qaopsquality.History{Reviews: []qaopsquality.Review{}, Checks: []qaopsquality.Check{}}, nil
+}
+func (s *qualityFake) Snapshot(context.Context, string, int64) (qaopsquality.Snapshot, error) {
+ return qaopsquality.Snapshot{}, qaopsquality.ErrNotFound
+}
+
+type qualitySource struct {
+ attributedReader
+ record dobotaiops.Record
+ tenant string
+ scopeCalls int
+}
+
+func (s *qualitySource) GetRecord(_ context.Context, tenant, id string) (dobotaiops.Record, error) {
+ s.tenant = tenant
+ return s.record, nil
+}
+func (s *qualitySource) ListRecords(_ context.Context, q dobotaiops.RecordQuery) (dobotaiops.RecordPage, error) {
+ return dobotaiops.RecordPage{Items: []dobotaiops.Record{s.record}, Columns: []string{"question"}, Total: 2, AsOf: time.Now()}, nil
+}
+func (s *qualitySource) ReadQualityScope(_ context.Context, q dobotaiops.RecordQuery) (dobotaiops.QualityScope, error) {
+ s.scopeCalls++
+ s.tenant = q.Window.TenantKey
+ second := s.record
+ second.ID = "second-turn"
+ keys := []dobotaiops.QualityKey{}
+ for _, r := range []dobotaiops.Record{s.record, second} {
+ e, _ := qaopsquality.EvidenceFor(r)
+ keys = append(keys, dobotaiops.QualityKey{ID: r.ID, InputHash: e.Hash, Marker: e.Result.Verdict == "uncovered", Source: r.SourceCoverage})
+ }
+ return dobotaiops.QualityScope{Keys: keys, AsOf: time.Now()}, nil
+}
+func qualityTestHandler(t *testing.T) (http.Handler, *qualityFake, *qualitySource) {
+ t.Helper()
+ store := &qualityFake{}
+ source := &qualitySource{record: dobotaiops.Record{ID: "fixture-turn", Status: "succeeded", Question: "示例", Answer: "暂无已发布"}}
+ auth := newFakeAuthStore()
+ auth.sessions["quality-admin"] = "usr-boss"
+ auth.sessions["quality-viewer"] = "usr-eye"
+ h, e := NewHandler(Config{Store: &fakeJobStore{}, Auth: &AuthConfig{Store: auth}, QAOps: source, QAOpsTenantKey: "fixed", QAQuality: store, Now: func() time.Time { return time.Date(2026, 10, 17, 0, 0, 0, 0, time.UTC) }})
+ if e != nil {
+ t.Fatal(e)
+ }
+ return h, store, source
+}
+func qualityRequest(h http.Handler, method, path, token, body string) *httptest.ResponseRecorder {
+ r := httptest.NewRequest(method, path, strings.NewReader(body))
+ r.Header.Set("Content-Type", "application/json")
+ r.Header.Set("X-Governance-Action", "qa-quality")
+ if token != "" {
+ r.AddCookie(&http.Cookie{Name: sessionCookieName, Value: token})
+ }
+ w := httptest.NewRecorder()
+ h.ServeHTTP(w, r)
+ return w
+}
+func TestQAQualityDetailListAndWholeScopeCounts(t *testing.T) {
+ h, store, source := qualityTestHandler(t)
+ w := qualityRequest(h, "GET", "/api/v1/qa-ops/records/fixture-turn", "quality-admin", "")
+ if w.Code != 200 || !strings.Contains(w.Body.String(), `"quality"`) {
+ t.Fatal("persisted quality absent in detail", w.Code)
+ }
+ w = qualityRequest(h, "GET", "/api/v1/qa-ops/records?start=2026-10-14T00:00:00Z&end=2026-10-15T00:00:00Z", "quality-admin", "")
+ if w.Code != 200 || !strings.Contains(w.Body.String(), `"is_correct"`) {
+ t.Fatal("whole-filter quality columns absent")
+ }
+ w = qualityRequest(h, "POST", "/api/v1/qa-ops/quality/query", "quality-admin", `{"start":"2026-10-14T00:00:00Z","end":"2026-10-15T00:00:00Z","keyword":""}`)
+ if w.Code != 200 || !strings.Contains(w.Body.String(), `"unreviewed":2`) || source.scopeCalls != 1 || source.tenant != "fixed" || store.calls < 2 {
+ t.Fatal("quality summary estimated from page instead of scope", w.Code, w.Body.String())
+ }
+ store.fail = true
+ w = qualityRequest(h, "GET", "/api/v1/qa-ops/records/fixture-turn", "quality-admin", "")
+ if w.Code != 503 || !strings.Contains(w.Body.String(), "quality_unavailable") {
+ t.Fatal("quality storage failure presented as empty success")
+ }
+}
+func TestQAQualityReviewUsesSessionActorAndStrictReadOnlySourceBoundary(t *testing.T) {
+ h, store, source := qualityTestHandler(t)
+ e, _ := qaopsquality.EvidenceFor(source.record)
+ q := qaopsquality.SaveRequest{InputHash: e.Hash, InputEpoch: 1, Nonce: strings.Repeat("n", 32), Fields: qaopsquality.Fields{Coverage: "uncovered", Correctness: "pending"}, Reason: "人工核对"}
+ raw, _ := json.Marshal(q)
+ path := "/api/v1/qa-ops/records/fixture-turn/reviews"
+ w := qualityRequest(h, "POST", path, "quality-admin", string(raw))
+ if w.Code != 200 || store.actor != "boss" || source.tenant != "fixed" {
+ t.Fatal("manual review failed or actor came from request", w.Code, store.actor)
+ }
+ for _, tc := range []struct {
+ token, body string
+ status int
+ }{{"", string(raw), 401}, {"quality-viewer", string(raw), 403}, {"quality-admin", strings.TrimSuffix(string(raw), "}") + `,"reviewer":"forged"}`, 400}, {"quality-admin", `null`, 400}, {"quality-admin", string(raw) + `{}`, 400}, {"quality-admin", `{"nonce":"a","nonce":"b"}`, 400}} {
+ w = qualityRequest(h, "POST", path, tc.token, tc.body)
+ if w.Code != tc.status {
+ t.Fatal("review boundary failed", w.Code, tc.status)
+ }
+ }
+ r := httptest.NewRequest("POST", path, strings.NewReader(string(raw)))
+ r.AddCookie(&http.Cookie{Name: sessionCookieName, Value: "quality-admin"})
+ r.Header.Set("X-Governance-Action", "qa-quality")
+ r.Header.Set("Sec-Fetch-Site", "cross-site")
+ w = httptest.NewRecorder()
+ h.ServeHTTP(w, r)
+ if w.Code != 403 {
+ t.Fatal("cross-site review accepted")
+ }
+ w = qualityRequest(h, "GET", path+"/invalid", "quality-admin", "")
+ if w.Code != 404 {
+ t.Fatal("unknown endpoint silently accepted")
+ }
+}
+
+func TestQAQualityReviewRejectsMissingRevisionAndNestedNull(t *testing.T) {
+ h, _, source := qualityTestHandler(t)
+ e, _ := qaopsquality.EvidenceFor(source.record)
+ q := qaopsquality.SaveRequest{InputHash: e.Hash, InputEpoch: 1, Nonce: strings.Repeat("n", 32), Fields: qaopsquality.Fields{Coverage: "pending", Correctness: "pending"}, Reason: "示例复核"}
+ raw, _ := json.Marshal(q)
+ for _, body := range []string{strings.Replace(string(raw), `"base_revision":0,`, "", 1), strings.Replace(string(raw), `"base_revision":0`, `"base_revision":null`, 1), strings.Replace(string(raw), `"product_category":""`, `"product_category":null`, 1)} {
+ w := qualityRequest(h, "POST", "/api/v1/qa-ops/records/fixture-turn/reviews", "quality-admin", body)
+ if w.Code != 400 {
+ t.Fatal("missing/null version or field silently became a default", w.Code)
+ }
+ }
+}
diff --git a/internal/httpapi/server.go b/internal/httpapi/server.go
index 7d4f4f6..cba5bc1 100644
--- a/internal/httpapi/server.go
+++ b/internal/httpapi/server.go
@@ -102,6 +102,7 @@ type Store interface {
}
type Config struct {
+ QAQuality QAQualityStore
QAOrgSync QAOrgSyncStore
QAOrgSyncEnabled bool
QAOrg QAOrgStore
@@ -175,6 +176,11 @@ func NewHandler(config Config) (http.Handler, error) {
config.NewID = newID
}
mux := http.NewServeMux()
+ mux.HandleFunc("POST /api/v1/qa-ops/quality/query", func(w http.ResponseWriter, r *http.Request) { qaQualityQuery(w, r, config) })
+ mux.HandleFunc("POST /api/v1/qa-ops/records/{id}/reviews", func(w http.ResponseWriter, r *http.Request) { qaQualityReview(w, r, config) })
+ mux.HandleFunc("GET /api/v1/qa-ops/records/{id}/quality/history", func(w http.ResponseWriter, r *http.Request) { qaQualityHistory(w, r, config) })
+ mux.HandleFunc("GET /api/v1/qa-ops/records/{id}/quality/inputs/{epoch}", func(w http.ResponseWriter, r *http.Request) { qaQualitySnapshot(w, r, config) })
+
mux.HandleFunc("POST /api/v1/qa-ops/usage/people", func(w http.ResponseWriter, r *http.Request) { qaMonthlyPeople(w, r, config) })
mux.HandleFunc("GET /api/v1/qa-ops/usage", func(w http.ResponseWriter, r *http.Request) { qaOpsUsage(w, r, config) })
mux.HandleFunc("GET /api/v1/qa-ops/organization/sync", func(w http.ResponseWriter, r *http.Request) { qaOrganizationSync(w, r, config) })
diff --git a/internal/platform/postgres/migrations/000049_qa_ops_quality.down.sql b/internal/platform/postgres/migrations/000049_qa_ops_quality.down.sql
new file mode 100644
index 0000000..daeb4fe
--- /dev/null
+++ b/internal/platform/postgres/migrations/000049_qa_ops_quality.down.sql
@@ -0,0 +1,4 @@
+DROP TABLE qa_ops_quality_reviews;
+DROP TABLE qa_ops_quality_checks;
+DROP TABLE qa_ops_quality_inputs;
+DROP TABLE qa_ops_quality_records;
diff --git a/internal/platform/postgres/migrations/000049_qa_ops_quality.up.sql b/internal/platform/postgres/migrations/000049_qa_ops_quality.up.sql
new file mode 100644
index 0000000..868ed94
--- /dev/null
+++ b/internal/platform/postgres/migrations/000049_qa_ops_quality.up.sql
@@ -0,0 +1,13 @@
+CREATE TABLE qa_ops_quality_records (
+ tenant_key TEXT NOT NULL,record_id TEXT NOT NULL,observed_at TIMESTAMPTZ,input_hash TEXT NOT NULL DEFAULT '',input_epoch BIGINT NOT NULL DEFAULT 0 CHECK(input_epoch>=0),review_revision BIGINT NOT NULL DEFAULT 0 CHECK(review_revision>=0),PRIMARY KEY(tenant_key,record_id)
+);
+CREATE TABLE qa_ops_quality_inputs (
+ tenant_key TEXT NOT NULL,record_id TEXT NOT NULL,input_epoch BIGINT NOT NULL CHECK(input_epoch>0),input_hash TEXT NOT NULL CHECK(input_hash ~ '^[a-f0-9]{64}$'),payload JSONB CHECK(payload IS NULL OR jsonb_typeof(payload)='object'),created_at TIMESTAMPTZ NOT NULL DEFAULT now(),PRIMARY KEY(tenant_key,record_id,input_epoch),FOREIGN KEY(tenant_key,record_id) REFERENCES qa_ops_quality_records(tenant_key,record_id)
+);
+CREATE TABLE qa_ops_quality_checks (
+ id BIGSERIAL PRIMARY KEY,tenant_key TEXT NOT NULL,record_id TEXT NOT NULL,input_epoch BIGINT NOT NULL,rule_version TEXT NOT NULL,result JSONB NOT NULL CHECK(jsonb_typeof(result)='object'),source JSONB NOT NULL CHECK(jsonb_typeof(source)='object'),created_at TIMESTAMPTZ NOT NULL DEFAULT now(),UNIQUE(tenant_key,record_id,input_epoch,rule_version),FOREIGN KEY(tenant_key,record_id,input_epoch) REFERENCES qa_ops_quality_inputs(tenant_key,record_id,input_epoch)
+);
+CREATE TABLE qa_ops_quality_reviews (
+ tenant_key TEXT NOT NULL,record_id TEXT NOT NULL,revision BIGINT NOT NULL CHECK(revision>0),input_epoch BIGINT NOT NULL,input_hash TEXT NOT NULL CHECK(input_hash ~ '^[a-f0-9]{64}$'),fields JSONB NOT NULL CHECK(jsonb_typeof(fields)='object'),reason TEXT NOT NULL CHECK(length(btrim(reason))>0),reviewer TEXT NOT NULL CHECK(length(btrim(reviewer))>0),nonce TEXT NOT NULL,request_hash TEXT NOT NULL,created_at TIMESTAMPTZ NOT NULL DEFAULT now(),PRIMARY KEY(tenant_key,record_id,revision),UNIQUE(tenant_key,record_id,nonce),FOREIGN KEY(tenant_key,record_id,input_epoch) REFERENCES qa_ops_quality_inputs(tenant_key,record_id,input_epoch)
+);
+CREATE INDEX idx_qa_quality_checks_history ON qa_ops_quality_checks(tenant_key,record_id,id DESC);
diff --git a/internal/platform/postgres/migrations_test.go b/internal/platform/postgres/migrations_test.go
index deae533..08f49c5 100644
--- a/internal/platform/postgres/migrations_test.go
+++ b/internal/platform/postgres/migrations_test.go
@@ -11,8 +11,8 @@ func TestEmbeddedMigrationsAreVersionSorted(t *testing.T) {
if err != nil {
t.Fatalf("loadMigrations() error = %v", err)
}
- if len(migrations) != 48 {
- t.Fatalf("migration count = %d, want 48", len(migrations))
+ if len(migrations) != 49 {
+ t.Fatalf("migration count = %d, want 49", len(migrations))
}
if migrations[0].Version != 1 || !strings.Contains(migrations[0].UpSQL, "CREATE TABLE IF NOT EXISTS jobs") {
t.Fatalf("migration 1 = %#v", migrations[0])
diff --git a/internal/qaopsorg/store_integration_test.go b/internal/qaopsorg/store_integration_test.go
index 8882a92..30a9ec6 100644
--- a/internal/qaopsorg/store_integration_test.go
+++ b/internal/qaopsorg/store_integration_test.go
@@ -134,6 +134,19 @@ func TestOrganizationStoreRoundTripAndOptimisticConflict(t *testing.T) {
if err = pool.QueryRow(ctx, "SELECT count(*) FROM qa_ops_region_revisions WHERE tenant_key=$1", "fixture-tenant").Scan(&revisions); err != nil || revisions != 2 {
t.Fatal("revision history changed unexpectedly")
}
+ // This test exercises migration 48, not whichever unrelated migration is latest.
+ for {
+ var latest int64
+ if pool.QueryRow(ctx, "SELECT max(version) FROM schema_migrations").Scan(&latest) != nil {
+ t.Fatal("migration version unavailable")
+ }
+ if latest <= 48 {
+ break
+ }
+ if postgresstore.RollbackLatestMigration(ctx, pool) != nil {
+ t.Fatal("could not reach organization migration")
+ }
+ }
if err = postgresstore.RollbackLatestMigration(ctx, pool); err != nil {
t.Fatal(err)
}
diff --git a/internal/qaopsquality/projection.go b/internal/qaopsquality/projection.go
new file mode 100644
index 0000000..b6e6392
--- /dev/null
+++ b/internal/qaopsquality/projection.go
@@ -0,0 +1,125 @@
+package qaopsquality
+
+import (
+ "bytes"
+ "crypto/sha256"
+ "encoding/hex"
+ "encoding/json"
+ "io"
+ "knowledge-governance/internal/dobotaiops"
+ "regexp"
+ "strings"
+ "unicode/utf8"
+)
+
+var hashPattern = regexp.MustCompile(`^[a-f0-9]{64}$`)
+var noncePattern = regexp.MustCompile(`^[A-Za-z0-9_-]{16,128}$`)
+
+func validText(s string, max int) bool {
+ return utf8.ValidString(s) && utf8.RuneCountInString(s) <= max && !strings.ContainsRune(s, 0)
+}
+func validID(s string) bool { return strings.TrimSpace(s) != "" && validText(s, 256) }
+func canonical(raw json.RawMessage) (json.RawMessage, error) {
+ if len(raw) == 0 {
+ return json.RawMessage("null"), nil
+ }
+ decoder := json.NewDecoder(bytes.NewReader(raw))
+ decoder.UseNumber()
+ var v any
+ if decoder.Decode(&v) != nil {
+ return nil, ErrInvalid
+ }
+ var extra any
+ if decoder.Decode(&extra) != io.EOF {
+ return nil, ErrInvalid
+ }
+ out, err := json.Marshal(v)
+ return out, err
+}
+func EvidenceFor(record dobotaiops.Record) (Evidence, error) {
+ if !validID(record.ID) {
+ return Evidence{}, ErrInvalid
+ }
+ refs, err := canonical(record.References)
+ if err != nil {
+ return Evidence{}, ErrInvalid
+ }
+ media, err := canonical(record.Media)
+ if err != nil {
+ return Evidence{}, ErrInvalid
+ }
+ // Keep only assessment inputs, never personnel or mutable feedback/organisation.
+ payload, err := json.Marshal(struct {
+ Version string `json:"version"`
+ ID string `json:"id"`
+ Status string `json:"status"`
+ Question string `json:"question"`
+ Answer string `json:"answer"`
+ References json.RawMessage `json:"references"`
+ Media json.RawMessage `json:"media"`
+ }{"dobotai-2.0-dingtalk-quality-v1", record.ID, record.Status, record.Question, record.Answer, refs, media})
+ if err != nil || len(payload) > 8<<20 {
+ return Evidence{}, ErrInvalid
+ }
+ sum := sha256.Sum256(payload)
+ hash := hex.EncodeToString(sum[:])
+ if record.QualityInputHash != "" {
+ if !hashPattern.MatchString(record.QualityInputHash) {
+ return Evidence{}, ErrInvalid
+ }
+ hash = record.QualityInputHash
+ }
+ return Evidence{Hash: hash, Payload: payload, Record: record, Result: dobotaiops.CheckAnswerCoverage(record.Answer)}, nil
+}
+func Validate(r SaveRequest) error {
+ if !hashPattern.MatchString(r.InputHash) || r.InputEpoch < 1 || r.BaseRevision < 0 || !noncePattern.MatchString(r.Nonce) || strings.TrimSpace(r.Reason) == "" || !validText(r.Reason, 4000) {
+ return ErrInvalid
+ }
+ f := r.Fields
+ validCoverage := false
+ for _, s := range []string{"covered", "uncovered", "partial", "pending", "excluded"} {
+ validCoverage = validCoverage || f.Coverage == s
+ }
+ if !validCoverage || (f.Correctness != "correct" && f.Correctness != "incorrect" && f.Correctness != "pending") {
+ return ErrInvalid
+ }
+ if !validText(f.ProductCategory, 128) || !validText(f.ProblemType, 128) || !validText(f.RootCause, 2000) || !validText(f.ExclusionReason, 2000) {
+ return ErrInvalid
+ }
+ if f.Correctness == "correct" && f.RootCause != "" || f.Coverage == "excluded" && strings.TrimSpace(f.ExclusionReason) == "" || f.Coverage != "excluded" && f.ExclusionReason != "" {
+ return ErrInvalid
+ }
+ return nil
+}
+func Project(hash string, epoch, revision int64, automatic Check, review *Review) View {
+ view := View{InputHash: hash, InputEpoch: epoch, Revision: revision, State: "unreviewed", Automatic: automatic, LatestReview: review, Effective: Fields{Coverage: automatic.Result.Verdict}}
+ if review == nil {
+ return view
+ }
+ view.State = "stale"
+ if review.InputEpoch == epoch && review.InputHash == hash {
+ view.State = "reviewed"
+ view.Effective = review.Fields
+ }
+ return view
+}
+func Summarize(views map[string]View) Summary {
+ result := Summary{Total: len(views)}
+ for _, v := range views {
+ switch v.State {
+ case "reviewed":
+ result.Reviewed++
+ if v.Effective.Coverage == "pending" || v.Effective.Correctness == "pending" {
+ result.PendingConfirmation++
+ }
+ case "stale":
+ result.Stale++
+ default:
+ result.Unreviewed++
+ }
+ if v.Automatic.Result.Verdict == "uncovered" {
+ result.RuleUncovered++
+ }
+ }
+ return result
+}
diff --git a/internal/qaopsquality/quality.go b/internal/qaopsquality/quality.go
new file mode 100644
index 0000000..0344d0f
--- /dev/null
+++ b/internal/qaopsquality/quality.go
@@ -0,0 +1,98 @@
+package qaopsquality
+
+import (
+ "encoding/json"
+ "errors"
+ "github.com/jackc/pgx/v5/pgxpool"
+ "knowledge-governance/internal/dobotaiops"
+ "time"
+)
+
+var ErrInvalid = errors.New("invalid quality request")
+var ErrConflict = errors.New("quality input or review revision changed")
+var ErrUnavailable = errors.New("quality store unavailable")
+var ErrNotFound = errors.New("quality input snapshot not found")
+var ErrSnapshotMissing = errors.New("only quality metadata was observed for this input")
+
+type Fields struct {
+ Coverage string `json:"coverage"`
+ Correctness string `json:"correctness"`
+ ProductCategory string `json:"product_category"`
+ ProblemType string `json:"problem_type"`
+ RootCause string `json:"root_cause"`
+ ExclusionReason string `json:"exclusion_reason"`
+}
+type SaveRequest struct {
+ InputHash string `json:"input_hash"`
+ InputEpoch int64 `json:"input_epoch"`
+ BaseRevision int64 `json:"base_revision"`
+ Nonce string `json:"nonce"`
+ Fields Fields `json:"fields"`
+ Reason string `json:"reason"`
+}
+type Review struct {
+ Revision int64 `json:"revision"`
+ InputEpoch int64 `json:"input_epoch"`
+ InputHash string `json:"input_hash"`
+ Fields Fields `json:"fields"`
+ Reason string `json:"reason"`
+ Reviewer string `json:"reviewer"`
+ CreatedAt time.Time `json:"created_at"`
+}
+type Check struct {
+ InputAvailable bool `json:"input_available"`
+ ID int64 `json:"id"`
+ InputEpoch int64 `json:"input_epoch"`
+ InputHash string `json:"input_hash"`
+ Result dobotaiops.CoverageCheck `json:"result"`
+ Source dobotaiops.SourceCoverage `json:"source"`
+ CreatedAt time.Time `json:"created_at"`
+}
+type View struct {
+ InputHash string `json:"input_hash"`
+ InputEpoch int64 `json:"input_epoch"`
+ Revision int64 `json:"revision"`
+ State string `json:"state"`
+ Automatic Check `json:"automatic"`
+ LatestReview *Review `json:"latest_review"`
+ Effective Fields `json:"effective"`
+}
+type History struct {
+ Reviews []Review `json:"reviews"`
+ Checks []Check `json:"checks"`
+ NextReview int64 `json:"next_review"`
+ NextCheck int64 `json:"next_check"`
+}
+type Summary struct {
+ Total int `json:"total"`
+ Reviewed int `json:"reviewed"`
+ Unreviewed int `json:"unreviewed"`
+ Stale int `json:"stale"`
+ PendingConfirmation int `json:"pending_confirmation"`
+ RuleUncovered int `json:"rule_uncovered"`
+}
+type Receipt struct {
+ View View `json:"view"`
+ SavedRevision int64 `json:"saved_revision"`
+ Replayed bool `json:"replayed"`
+}
+type Evidence struct {
+ Result dobotaiops.CoverageCheck
+ Hash string
+ Payload json.RawMessage
+ Record dobotaiops.Record
+}
+
+type Snapshot struct {
+ InputEpoch int64 `json:"input_epoch"`
+ InputHash string `json:"input_hash"`
+ Payload json.RawMessage `json:"payload"`
+ CreatedAt time.Time `json:"created_at"`
+}
+
+type Store struct {
+ pool *pgxpool.Pool
+ tenant string
+}
+
+func NewStore(pool *pgxpool.Pool, tenant string) *Store { return &Store{pool: pool, tenant: tenant} }
diff --git a/internal/qaopsquality/quality_test.go b/internal/qaopsquality/quality_test.go
new file mode 100644
index 0000000..5bc3230
--- /dev/null
+++ b/internal/qaopsquality/quality_test.go
@@ -0,0 +1,73 @@
+package qaopsquality
+
+import (
+ "encoding/json"
+ "knowledge-governance/internal/dobotaiops"
+ "strings"
+ "testing"
+)
+
+func TestEvidenceBindsQualityInputsNotPeopleFeedbackOrJSONKeyOrder(t *testing.T) {
+ record := dobotaiops.Record{ID: "fixture-turn", Status: "succeeded", Question: "示例问题", Answer: "有暂无已发布但存在引用", References: json.RawMessage(`[{"b":2,"a":1}]`), Media: json.RawMessage(`[]`)}
+ a, err := EvidenceFor(record)
+ if err != nil || len(a.Hash) != 64 || !strings.Contains(string(a.Payload), record.Answer) {
+ t.Fatal("quality inputs not snapshotted")
+ }
+ record.Asker = "another-person"
+ record.Department = "changed"
+ record.Feedback.Up = 10
+ record.References = json.RawMessage(`[{"a":1,"b":2}]`)
+ b, _ := EvidenceFor(record)
+ if b.Hash != a.Hash {
+ t.Fatal("irrelevant identity/feedback or JSON object ordering invalidated review")
+ }
+ record.Answer = "原答案变更"
+ b, _ = EvidenceFor(record)
+ if b.Hash == a.Hash {
+ t.Fatal("answer change undetected")
+ }
+}
+func TestHumanProjectionKeepsRuleAndStalesObservedInputChanges(t *testing.T) {
+ automatic := Check{Result: dobotaiops.CheckAnswerCoverage("暂无已发布"), InputEpoch: 2, InputHash: strings.Repeat("a", 64)}
+ review := &Review{InputEpoch: 1, InputHash: automatic.InputHash, Fields: Fields{Coverage: "covered", Correctness: "correct", ProductCategory: "MG400"}}
+ view := Project(automatic.InputHash, 2, 1, automatic, review)
+ if view.State != "stale" || view.Effective.Coverage != "uncovered" || view.Effective.Correctness != "" {
+ t.Fatal("old conclusion remained effective after input epoch changed")
+ }
+ review.InputEpoch = 2
+ view = Project(automatic.InputHash, 2, 1, automatic, review)
+ if view.State != "reviewed" || view.Effective.Coverage != "covered" || view.Automatic.Result.Verdict != "uncovered" {
+ t.Fatal("human and immutable rule not separated")
+ }
+ summary := Summarize(map[string]View{"a": view, "b": Project(automatic.InputHash, 3, 1, automatic, review), "c": Project(automatic.InputHash, 1, 0, automatic, nil)})
+ if summary.Total != 3 || summary.Reviewed != 1 || summary.Stale != 1 || summary.Unreviewed != 1 || summary.PendingConfirmation != 0 {
+ t.Fatal("quality counts invent rates or unknown judgments")
+ }
+}
+func TestReviewRequiresExplicitOutcomesAndEvidence(t *testing.T) {
+ valid := SaveRequest{InputHash: strings.Repeat("a", 64), InputEpoch: 1, Nonce: strings.Repeat("n", 32), Fields: Fields{Coverage: "uncovered", Correctness: "pending"}, Reason: "人工核对引用与答案,证据不足"}
+ if Validate(valid) != nil {
+ t.Fatal("valid review rejected")
+ }
+ for _, field := range []string{"reason", "hash", "coverage", "correctness", "root", "exclusion"} {
+ bad := valid
+ switch field {
+ case "reason":
+ bad.Reason = " "
+ case "hash":
+ bad.InputHash = "malformed"
+ case "coverage":
+ bad.Fields.Coverage = ""
+ case "correctness":
+ bad.Fields.Correctness = ""
+ case "root":
+ bad.Fields.Correctness = "correct"
+ bad.Fields.RootCause = "知识缺失"
+ case "exclusion":
+ bad.Fields.Coverage = "excluded"
+ }
+ if Validate(bad) == nil {
+ t.Fatal("invalid review accepted", field)
+ }
+ }
+}
diff --git a/internal/qaopsquality/store.go b/internal/qaopsquality/store.go
new file mode 100644
index 0000000..93f7138
--- /dev/null
+++ b/internal/qaopsquality/store.go
@@ -0,0 +1,322 @@
+package qaopsquality
+
+import (
+ "context"
+ "crypto/sha256"
+ "encoding/hex"
+ "encoding/json"
+ "errors"
+ "github.com/jackc/pgx/v5"
+ "knowledge-governance/internal/dobotaiops"
+ "sort"
+ "time"
+)
+
+func (s *Store) Columns(ctx context.Context, keys []dobotaiops.QualityKey) ([]string, error) {
+ if !s.available() {
+ return nil, ErrUnavailable
+ }
+ if len(keys) > 100000 {
+ return nil, ErrInvalid
+ }
+ for _, key := range keys {
+ if !validID(key.ID) || !hashPattern.MatchString(key.InputHash) {
+ return nil, ErrInvalid
+ }
+ }
+ raw, err := json.Marshal(keys)
+ if err != nil {
+ return nil, ErrInvalid
+ }
+ if len(keys) == 0 {
+ return []string{}, nil
+ }
+ var coverage, correctness, product, problem, root bool
+ err = s.pool.QueryRow(ctx, `SELECT COALESCE(bool_or(r.fields->>'coverage'<>''),false),COALESCE(bool_or(r.fields->>'correctness'<>''),false),COALESCE(bool_or(r.fields->>'product_category'<>''),false),COALESCE(bool_or(r.fields->>'problem_type'<>''),false),COALESCE(bool_or(r.fields->>'root_cause'<>''),false) FROM jsonb_to_recordset($2::jsonb) k(id text,input_hash text) JOIN qa_ops_quality_records h ON h.tenant_key=$1 AND h.record_id=k.id AND h.input_hash=k.input_hash JOIN qa_ops_quality_reviews r ON r.tenant_key=h.tenant_key AND r.record_id=h.record_id AND r.revision=h.review_revision AND r.input_epoch=h.input_epoch`, s.tenant, raw).Scan(&coverage, &correctness, &product, &problem, &root)
+ if err != nil {
+ return nil, ErrUnavailable
+ }
+ out := []string{}
+ for _, c := range []struct {
+ key string
+ yes bool
+ }{{"coverage", coverage}, {"is_correct", correctness}, {"product_category", product}, {"problem_type", problem}, {"root_cause", root}} {
+ if c.yes {
+ out = append(out, c.key)
+ }
+ }
+ return out, nil
+}
+func (s *Store) Snapshot(ctx context.Context, id string, epoch int64) (Snapshot, error) {
+ if !s.available() {
+ return Snapshot{}, ErrUnavailable
+ }
+ if !validID(id) || epoch < 1 {
+ return Snapshot{}, ErrInvalid
+ }
+ var value Snapshot
+ value.InputEpoch = epoch
+ err := s.pool.QueryRow(ctx, `SELECT input_hash,payload,created_at FROM qa_ops_quality_inputs WHERE tenant_key=$1 AND record_id=$2 AND input_epoch=$3`, s.tenant, id, epoch).Scan(&value.InputHash, &value.Payload, &value.CreatedAt)
+ if errors.Is(err, pgx.ErrNoRows) {
+ return Snapshot{}, ErrNotFound
+ }
+ if err != nil {
+ return Snapshot{}, ErrUnavailable
+ }
+ if len(value.Payload) == 0 {
+ return Snapshot{}, ErrSnapshotMissing
+ }
+ return value, nil
+}
+func (s *Store) available() bool { return s != nil && s.pool != nil && validID(s.tenant) }
+func (s *Store) observeLocked(ctx context.Context, tx pgx.Tx, e Evidence) error {
+ id := e.Record.ID
+ if _, err := tx.Exec(ctx, `INSERT INTO qa_ops_quality_records(tenant_key,record_id) VALUES($1,$2) ON CONFLICT DO NOTHING`, s.tenant, id); err != nil {
+ return ErrUnavailable
+ }
+ var previous string
+ var epoch int64
+ var observedAt *time.Time
+ if tx.QueryRow(ctx, `SELECT input_hash,input_epoch,observed_at FROM qa_ops_quality_records WHERE tenant_key=$1 AND record_id=$2 FOR UPDATE`, s.tenant, id).Scan(&previous, &epoch, &observedAt) != nil {
+ return ErrUnavailable
+ }
+ // Source transaction time orders concurrent page/detail/scope observations.
+ // A late different input is rejected, never projected against a newer answer.
+ if observedAt != nil && !e.Record.QualityObservedAt.IsZero() && e.Record.QualityObservedAt.Before(*observedAt) && previous != e.Hash {
+ return ErrConflict
+ }
+ if !e.Record.QualityObservedAt.IsZero() {
+ if _, err := tx.Exec(ctx, `UPDATE qa_ops_quality_records SET observed_at=$3 WHERE tenant_key=$1 AND record_id=$2 AND(observed_at IS NULL OR observed_at<$3)`, s.tenant, id, e.Record.QualityObservedAt); err != nil {
+ return ErrUnavailable
+ }
+ }
+ var payload any
+ if len(e.Payload) > 0 {
+ payload = e.Payload
+ }
+ if previous != e.Hash {
+ epoch++
+ if _, err := tx.Exec(ctx, `INSERT INTO qa_ops_quality_inputs(tenant_key,record_id,input_epoch,input_hash,payload) VALUES($1,$2,$3,$4,$5)`, s.tenant, id, epoch, e.Hash, payload); err != nil {
+ return ErrUnavailable
+ }
+ tag, err := tx.Exec(ctx, `UPDATE qa_ops_quality_records SET input_hash=$3,input_epoch=$4 WHERE tenant_key=$1 AND record_id=$2`, s.tenant, id, e.Hash, epoch)
+ if err != nil || tag.RowsAffected() != 1 {
+ return ErrUnavailable
+ }
+ }
+ if payload != nil {
+ if _, err := tx.Exec(ctx, `UPDATE qa_ops_quality_inputs SET payload=$4 WHERE tenant_key=$1 AND record_id=$2 AND input_epoch=$3 AND payload IS NULL`, s.tenant, id, epoch, payload); err != nil {
+ return ErrUnavailable
+ }
+ }
+ automatic, _ := json.Marshal(e.Result)
+ source, _ := json.Marshal(e.Record.SourceCoverage)
+ if _, err := tx.Exec(ctx, `INSERT INTO qa_ops_quality_checks(tenant_key,record_id,input_epoch,rule_version,result,source) VALUES($1,$2,$3,$4,$5,$6) ON CONFLICT(tenant_key,record_id,input_epoch,rule_version) DO NOTHING`, s.tenant, id, epoch, dobotaiops.CoverageRuleVersion, automatic, source); err != nil {
+ return ErrUnavailable
+ }
+ return nil
+}
+
+const checkObject = `jsonb_build_object('id',c.id,'input_epoch',c.input_epoch,'input_hash',i.input_hash,'result',c.result,'source',c.source,'created_at',c.created_at,'input_available',i.payload IS NOT NULL)`
+const reviewObject = `jsonb_build_object('revision',r.revision,'input_epoch',r.input_epoch,'input_hash',r.input_hash,'fields',r.fields,'reason',r.reason,'reviewer',r.reviewer,'created_at',r.created_at)`
+
+func (s *Store) view(ctx context.Context, tx pgx.Tx, id string) (View, error) {
+ var hash, checkRaw, reviewRaw string
+ var epoch, revision int64
+ err := tx.QueryRow(ctx, `SELECT h.input_hash,h.input_epoch,h.review_revision,`+checkObject+`::text,COALESCE((SELECT `+reviewObject+` FROM qa_ops_quality_reviews r WHERE r.tenant_key=h.tenant_key AND r.record_id=h.record_id AND r.revision=h.review_revision),'null'::jsonb)::text FROM qa_ops_quality_records h JOIN qa_ops_quality_inputs i ON i.tenant_key=h.tenant_key AND i.record_id=h.record_id AND i.input_epoch=h.input_epoch JOIN qa_ops_quality_checks c ON c.tenant_key=h.tenant_key AND c.record_id=h.record_id AND c.input_epoch=h.input_epoch AND c.rule_version=$3 WHERE h.tenant_key=$1 AND h.record_id=$2`, s.tenant, id, dobotaiops.CoverageRuleVersion).Scan(&hash, &epoch, &revision, &checkRaw, &reviewRaw)
+ var automatic Check
+ var review *Review
+ if err != nil || json.Unmarshal([]byte(checkRaw), &automatic) != nil || json.Unmarshal([]byte(reviewRaw), &review) != nil {
+ return View{}, ErrUnavailable
+ }
+ return Project(hash, epoch, revision, automatic, review), nil
+}
+func (s *Store) Observe(ctx context.Context, records []dobotaiops.Record) (map[string]View, error) {
+ if len(records) > 5000 {
+ return nil, ErrInvalid
+ }
+ items := make([]Evidence, 0, len(records))
+ for _, record := range records {
+ e, err := EvidenceFor(record)
+ if err != nil {
+ return nil, err
+ }
+ items = append(items, e)
+ }
+ return s.observeEvidence(ctx, items)
+}
+func (s *Store) ObserveKeys(ctx context.Context, keys []dobotaiops.QualityKey) (map[string]View, error) {
+ if len(keys) > 5000 {
+ return nil, ErrInvalid
+ }
+ items := make([]Evidence, 0, len(keys))
+ for _, key := range keys {
+ if !validID(key.ID) || !hashPattern.MatchString(key.InputHash) {
+ return nil, ErrInvalid
+ }
+ items = append(items, Evidence{Hash: key.InputHash, Record: dobotaiops.Record{ID: key.ID, SourceCoverage: key.Source, QualityObservedAt: key.ObservedAt}, Result: dobotaiops.CheckMarkerCoverage(key.Marker)})
+ }
+ return s.observeEvidence(ctx, items)
+}
+func (s *Store) observeEvidence(ctx context.Context, items []Evidence) (map[string]View, error) {
+ if !s.available() {
+ return nil, ErrUnavailable
+ }
+ evidence := map[string]Evidence{}
+ ids := []string{}
+ bytes := 0
+ for _, e := range items {
+ id := e.Record.ID
+ if old, ok := evidence[id]; ok {
+ if old.Hash != e.Hash || old.Result != e.Result {
+ return nil, ErrInvalid
+ }
+ continue
+ }
+ evidence[id] = e
+ ids = append(ids, id)
+ bytes += len(e.Payload)
+ if bytes > 32<<20 {
+ return nil, ErrInvalid
+ }
+ }
+ sort.Strings(ids)
+ result := map[string]View{}
+ if len(ids) == 0 {
+ return result, nil
+ }
+ tx, err := s.pool.Begin(ctx)
+ if err != nil {
+ return nil, ErrUnavailable
+ }
+ defer tx.Rollback(context.Background())
+ for _, id := range ids {
+ if err = s.observeLocked(ctx, tx, evidence[id]); err != nil {
+ return nil, err
+ }
+ v, err := s.view(ctx, tx, id)
+ if err != nil {
+ return nil, err
+ }
+ result[id] = v
+ }
+ if tx.Commit(ctx) != nil {
+ return nil, ErrUnavailable
+ }
+ return result, nil
+}
+func (s *Store) Save(ctx context.Context, record dobotaiops.Record, request SaveRequest, actor string) (Receipt, error) {
+ if !s.available() {
+ return Receipt{}, ErrUnavailable
+ }
+ if Validate(request) != nil || !validID(actor) {
+ return Receipt{}, ErrInvalid
+ }
+ e, err := EvidenceFor(record)
+ if err != nil {
+ return Receipt{}, err
+ }
+ payload, _ := json.Marshal(request)
+ sum := sha256.Sum256(payload)
+ requestHash := hex.EncodeToString(sum[:])
+ tx, err := s.pool.Begin(ctx)
+ if err != nil {
+ return Receipt{}, ErrUnavailable
+ }
+ defer tx.Rollback(context.Background())
+ if err = s.observeLocked(ctx, tx, e); err != nil {
+ return Receipt{}, err
+ }
+ var existingHash, existingActor string
+ var savedRevision int64
+ err = tx.QueryRow(ctx, `SELECT request_hash,reviewer,revision FROM qa_ops_quality_reviews WHERE tenant_key=$1 AND record_id=$2 AND nonce=$3`, s.tenant, record.ID, request.Nonce).Scan(&existingHash, &existingActor, &savedRevision)
+ replay := err == nil
+ if err != nil && !errors.Is(err, pgx.ErrNoRows) {
+ return Receipt{}, ErrUnavailable
+ }
+ current, err := s.view(ctx, tx, record.ID)
+ if err != nil {
+ return Receipt{}, err
+ }
+ if replay {
+ if existingHash != requestHash || existingActor != actor {
+ return Receipt{}, ErrConflict
+ }
+ } else {
+ if current.InputHash != request.InputHash || current.InputEpoch != request.InputEpoch || current.Revision != request.BaseRevision {
+ if tx.Commit(ctx) != nil {
+ return Receipt{}, ErrUnavailable
+ }
+ return Receipt{}, ErrConflict
+ }
+ savedRevision = current.Revision + 1
+ fields, _ := json.Marshal(request.Fields)
+ if _, err = tx.Exec(ctx, `INSERT INTO qa_ops_quality_reviews(tenant_key,record_id,revision,input_epoch,input_hash,fields,reason,reviewer,nonce,request_hash) VALUES($1,$2,$3,$4,$5,$6,$7,$8,$9,$10)`, s.tenant, record.ID, savedRevision, current.InputEpoch, current.InputHash, fields, request.Reason, actor, request.Nonce, requestHash); err != nil {
+ return Receipt{}, ErrUnavailable
+ }
+ tag, err := tx.Exec(ctx, `UPDATE qa_ops_quality_records SET review_revision=$3 WHERE tenant_key=$1 AND record_id=$2`, s.tenant, record.ID, savedRevision)
+ if err != nil || tag.RowsAffected() != 1 {
+ return Receipt{}, ErrUnavailable
+ }
+ current, err = s.view(ctx, tx, record.ID)
+ if err != nil {
+ return Receipt{}, err
+ }
+ }
+ if tx.Commit(ctx) != nil {
+ return Receipt{}, ErrUnavailable
+ }
+ return Receipt{View: current, SavedRevision: savedRevision, Replayed: replay}, nil
+}
+func (s *Store) History(ctx context.Context, id string, reviewBefore, checkBefore int64) (History, error) {
+ result := History{Reviews: []Review{}, Checks: []Check{}}
+ if !s.available() {
+ return result, ErrUnavailable
+ }
+ if !validID(id) || reviewBefore < 0 || checkBefore < 0 {
+ return result, ErrInvalid
+ }
+ rows, err := s.pool.Query(ctx, `SELECT `+reviewObject+`::text FROM qa_ops_quality_reviews r WHERE tenant_key=$1 AND record_id=$2 AND ($3::bigint=0 OR revision<$3) ORDER BY revision DESC LIMIT 21`, s.tenant, id, reviewBefore)
+ if err != nil {
+ return result, ErrUnavailable
+ }
+ for rows.Next() {
+ var raw string
+ var value Review
+ if rows.Scan(&raw) != nil || json.Unmarshal([]byte(raw), &value) != nil {
+ rows.Close()
+ return result, ErrUnavailable
+ }
+ result.Reviews = append(result.Reviews, value)
+ }
+ err = rows.Err()
+ rows.Close()
+ if err != nil {
+ return result, ErrUnavailable
+ }
+ if len(result.Reviews) > 20 {
+ result.Reviews = result.Reviews[:20]
+ result.NextReview = result.Reviews[19].Revision
+ }
+ rows, err = s.pool.Query(ctx, `SELECT `+checkObject+`::text FROM qa_ops_quality_checks c JOIN qa_ops_quality_inputs i USING(tenant_key,record_id,input_epoch) WHERE c.tenant_key=$1 AND c.record_id=$2 AND ($3::bigint=0 OR c.id<$3) ORDER BY c.id DESC LIMIT 21`, s.tenant, id, checkBefore)
+ if err != nil {
+ return result, ErrUnavailable
+ }
+ defer rows.Close()
+ for rows.Next() {
+ var raw string
+ var value Check
+ if rows.Scan(&raw) != nil || json.Unmarshal([]byte(raw), &value) != nil {
+ return result, ErrUnavailable
+ }
+ result.Checks = append(result.Checks, value)
+ }
+ if rows.Err() != nil {
+ return result, ErrUnavailable
+ }
+ if len(result.Checks) > 20 {
+ result.Checks = result.Checks[:20]
+ result.NextCheck = result.Checks[19].ID
+ }
+ return result, nil
+}
diff --git a/internal/qaopsquality/store_integration_test.go b/internal/qaopsquality/store_integration_test.go
new file mode 100644
index 0000000..e80aa59
--- /dev/null
+++ b/internal/qaopsquality/store_integration_test.go
@@ -0,0 +1,219 @@
+package qaopsquality_test
+
+import (
+ "context"
+ "errors"
+ "fmt"
+ "github.com/jackc/pgx/v5/pgxpool"
+ "knowledge-governance/internal/dobotaiops"
+ pg "knowledge-governance/internal/platform/postgres"
+ "knowledge-governance/internal/qaopsquality"
+ "net/url"
+ "os"
+ "strings"
+ "testing"
+ "time"
+)
+
+func TestQualityStoreImmutableHistoryReplayConcurrencyAndStaleness(t *testing.T) {
+ dsn := os.Getenv("KG_QAOPS_QUALITY_TEST_DSN")
+ if dsn == "" {
+ t.Skip("explicit disposable quality DB required")
+ }
+ u, e := url.Parse(dsn)
+ if e != nil || u.Hostname() != "127.0.0.1" || !strings.HasPrefix(u.Path, "/kg_qaops_quality_test_") || os.Getenv("KG_QAOPS_QUALITY_TEST_ISOLATED") != "1" {
+ t.Fatal("refusing shared quality database")
+ }
+ ctx := context.Background()
+ pool, e := pgxpool.New(ctx, dsn)
+ if e != nil {
+ t.Fatal("fixture connection failed")
+ }
+ defer pool.Close()
+ if e = pg.ApplyMigrations(ctx, pool); e != nil {
+ t.Fatal(e)
+ }
+ store := qaopsquality.NewStore(pool, "fixture-tenant")
+ record := dobotaiops.Record{ID: "fixture-turn", Status: "succeeded", Question: "示例", Answer: "暂无已发布", AskedAt: time.Now()}
+ views, e := store.Observe(ctx, []dobotaiops.Record{record})
+ if e != nil {
+ t.Fatal("source observation not persisted", e)
+ }
+ first := views[record.ID]
+ again, e := store.Observe(ctx, []dobotaiops.Record{record})
+ if e != nil || again[record.ID].Automatic.ID != first.Automatic.ID {
+ t.Fatal("repeated GET duplicated immutable checks")
+ }
+ metaKey := dobotaiops.QualityKey{ID: "metadata-only-turn", InputHash: strings.Repeat("f", 64), Marker: true}
+ meta, me := store.ObserveKeys(ctx, []dobotaiops.QualityKey{metaKey})
+ if me != nil || meta[metaKey.ID].Automatic.InputAvailable {
+ t.Fatal("compact scope observation not stored honestly", me)
+ }
+ if _, me = store.Snapshot(ctx, metaKey.ID, 1); !errors.Is(me, qaopsquality.ErrSnapshotMissing) {
+ t.Fatal("metadata-only input fabricated an empty original")
+ }
+ full, me := store.Observe(ctx, []dobotaiops.Record{{ID: metaKey.ID, QualityInputHash: metaKey.InputHash, Question: "示例", Answer: "暂无已发布"}})
+ if me != nil || !full[metaKey.ID].Automatic.InputAvailable || full[metaKey.ID].Automatic.ID != meta[metaKey.ID].Automatic.ID {
+ t.Fatal("reading full content duplicated/replaced the same check")
+ }
+ req := qaopsquality.SaveRequest{InputHash: first.InputHash, InputEpoch: first.InputEpoch, BaseRevision: first.Revision, Nonce: strings.Repeat("n", 32), Fields: qaopsquality.Fields{Coverage: "covered", Correctness: "correct", ProductCategory: "MG400", ProblemType: "咨询"}, Reason: "人工核对有效引用"}
+ saved, e := store.Save(ctx, record, req, "fixture-admin")
+ if e != nil || saved.View.State != "reviewed" || saved.View.Effective.Coverage != "covered" || saved.View.Automatic.Result.Verdict != "uncovered" || saved.View.LatestReview.Reviewer != "fixture-admin" {
+ t.Fatal("manual override lost audit/rule separation", e)
+ }
+ cols, ce := store.Columns(ctx, []dobotaiops.QualityKey{{ID: record.ID, InputHash: first.InputHash}})
+ if ce != nil || len(cols) != 4 {
+ t.Fatal("review fields absent from whole-scope projection", ce)
+ }
+ replay, e := store.Save(ctx, record, req, "fixture-admin")
+ if e != nil || !replay.Replayed || replay.SavedRevision != saved.SavedRevision {
+ t.Fatal("retry duplicated review")
+ }
+ bad := req
+ bad.Reason = "changed body"
+ if _, e = store.Save(ctx, record, bad, "fixture-admin"); !errors.Is(e, qaopsquality.ErrConflict) {
+ t.Fatal("nonce reused with different request")
+ }
+ if _, e = store.Save(ctx, record, req, "other-admin"); !errors.Is(e, qaopsquality.ErrConflict) {
+ t.Fatal("nonce replay changed operator")
+ }
+ record.Answer = "新答案"
+ changed, e := store.Observe(ctx, []dobotaiops.Record{record})
+ if e != nil || changed[record.ID].State != "stale" || changed[record.ID].Effective.Correctness != "" {
+ t.Fatal("old manual result silently survived change")
+ }
+ if _, e = store.Save(ctx, record, req, "fixture-admin"); e != nil {
+ t.Fatal("old completed request should replay without a new review")
+ }
+ record.Answer = "暂无已发布"
+ reverted, e := store.Observe(ctx, []dobotaiops.Record{record})
+ v := reverted[record.ID]
+ if e != nil || v.InputHash != first.InputHash || v.InputEpoch <= first.InputEpoch || v.State != "stale" {
+ t.Fatal("answer revert reactivated old judgment")
+ }
+ req.InputHash = v.InputHash
+ req.InputEpoch = v.InputEpoch
+ req.BaseRevision = v.Revision
+ start := make(chan struct{})
+ results := make(chan error, 2)
+ for _, nonce := range []string{strings.Repeat("a", 32), strings.Repeat("b", 32)} {
+ go func(nonce string) {
+ q := req
+ q.Nonce = nonce
+ <-start
+ _, err := store.Save(ctx, record, q, "fixture-admin")
+ results <- err
+ }(nonce)
+ }
+ close(start)
+ success, conflict := 0, 0
+ for range 2 {
+ e = <-results
+ if e == nil {
+ success++
+ } else if errors.Is(e, qaopsquality.ErrConflict) {
+ conflict++
+ } else {
+ t.Fatal(e)
+ }
+ }
+ if success != 1 || conflict != 1 {
+ t.Fatal("concurrent reviewers overwrote each other")
+ }
+ h, e := store.History(ctx, record.ID, 0, 0)
+ if e != nil || len(h.Reviews) != 2 || len(h.Checks) != 3 || h.Checks[0].InputEpoch != 3 {
+ t.Fatal("history missing/replaced", e)
+ }
+ oldInput, oe := store.Snapshot(ctx, record.ID, 1)
+ if oe != nil || oldInput.InputHash != first.InputHash || !strings.Contains(string(oldInput.Payload), "暂无已发布") {
+ t.Fatal("old assessment evidence not readable")
+ }
+ // A slow older source scan must not roll back a newer observed input.
+ ordered := dobotaiops.Record{ID: "ordered-source-turn", Answer: "旧输入", QualityObservedAt: time.Now().Add(-time.Minute)}
+ oldEvidence, _ := qaopsquality.EvidenceFor(ordered)
+ if _, e = store.Observe(ctx, []dobotaiops.Record{ordered}); e != nil {
+ t.Fatal(e)
+ }
+ ordered.Answer = "新输入"
+ ordered.QualityObservedAt = ordered.QualityObservedAt.Add(time.Second)
+ newViews, ne := store.Observe(ctx, []dobotaiops.Record{ordered})
+ if ne != nil {
+ t.Fatal(ne)
+ }
+ newView := newViews[ordered.ID]
+ if _, e = store.ObserveKeys(ctx, []dobotaiops.QualityKey{{ID: ordered.ID, InputHash: oldEvidence.Hash, ObservedAt: ordered.QualityObservedAt.Add(-time.Second)}}); !errors.Is(e, qaopsquality.ErrConflict) {
+ t.Fatal("late old source scan rolled back the current input")
+ }
+ current, ce := store.Observe(ctx, []dobotaiops.Record{ordered})
+ if ce != nil || current[ordered.ID].InputEpoch != newView.InputEpoch {
+ t.Fatal("stale scan created extra input epochs")
+ }
+ // Independent cursors must enumerate more than one page without loss.
+ paging := dobotaiops.Record{ID: "history-paging-turn", Answer: "示例"}
+ pageSeen := map[int64]bool{}
+ checkSeen := map[int64]bool{}
+ for i := 0; i < 23; i++ {
+ paging.Answer = fmt.Sprintf("示例输入%d", i)
+ vv, ee := store.Observe(ctx, []dobotaiops.Record{paging})
+ if ee != nil {
+ t.Fatal(ee)
+ }
+ value := vv[paging.ID]
+ _, ee = store.Save(ctx, paging, qaopsquality.SaveRequest{InputHash: value.InputHash, InputEpoch: value.InputEpoch, BaseRevision: value.Revision, Nonce: fmt.Sprintf("history_%020d", i), Fields: qaopsquality.Fields{Coverage: "pending", Correctness: "pending"}, Reason: "隔离分页验证"}, "fixture-admin")
+ if ee != nil {
+ t.Fatal(ee)
+ }
+ }
+ rc, cc := int64(0), int64(0)
+ for {
+ page, ee := store.History(ctx, paging.ID, rc, cc)
+ if ee != nil {
+ t.Fatal(ee)
+ }
+ for _, r := range page.Reviews {
+ if pageSeen[r.Revision] {
+ t.Fatal("duplicate history review")
+ }
+ pageSeen[r.Revision] = true
+ }
+ for _, c := range page.Checks {
+ if checkSeen[c.ID] {
+ t.Fatal("duplicate history check")
+ }
+ checkSeen[c.ID] = true
+ }
+ rc, cc = page.NextReview, page.NextCheck
+ if rc == 0 && cc == 0 {
+ break
+ }
+ if rc == 0 || cc == 0 {
+ t.Fatal("unexpected fixture cursor shape")
+ }
+ }
+ if len(pageSeen) != 23 || len(checkSeen) != 23 {
+ t.Fatal("history cursor omitted immutable rows")
+ }
+ freshPool, fe := pgxpool.New(ctx, dsn)
+ if fe != nil {
+ t.Fatal(fe)
+ }
+ persisted, fe := qaopsquality.NewStore(freshPool, "fixture-tenant").History(ctx, record.ID, 0, 0)
+ freshPool.Close()
+ if fe != nil || len(persisted.Reviews) != 2 || len(persisted.Checks) != 3 {
+ t.Fatal("history did not survive a new connection pool")
+ }
+ // History survives a fresh store/connection, not merely an in-memory cache.
+ if h, e = qaopsquality.NewStore(pool, "other-tenant").History(ctx, record.ID, 0, 0); e != nil || len(h.Reviews) != 0 || len(h.Checks) != 0 {
+ t.Fatal("quality history crossed tenants")
+ }
+ if e = pg.RollbackLatestMigration(ctx, pool); e != nil {
+ t.Fatal(e)
+ }
+ var gone bool
+ if pool.QueryRow(ctx, `SELECT to_regclass('qa_ops_quality_records') IS NULL AND to_regclass('qa_ops_quality_inputs') IS NULL AND to_regclass('qa_ops_quality_checks') IS NULL AND to_regclass('qa_ops_quality_reviews') IS NULL`).Scan(&gone) != nil || !gone {
+ t.Fatal("quality down migration left data tables")
+ }
+ if e = pg.ApplyMigrations(ctx, pool); e != nil {
+ t.Fatal(e)
+ }
+}
diff --git a/scripts/test-scope.json b/scripts/test-scope.json
index 9fbb0f8..5e4046b 100644
--- a/scripts/test-scope.json
+++ b/scripts/test-scope.json
@@ -9,6 +9,7 @@
"⚠️ 文件缺失或解析不了 ⇒ 门禁红:范围声明不出来时,不许默认放行。"
],
"optional": [
+ {"package":"knowledge-governance/internal/qaopsquality","test":"TestQualityStoreImmutableHistoryReplayConcurrencyAndStaleness","reason":"仅在显式一次性 loopback kg_qaops_quality_test_ 库执行;默认 CI 不连接共享/生产库,隔离 PG 另行实跑"},
{"package": "knowledge-governance/internal/dobotaiops", "test": "TestQARecordInternalIdentityAndWholeFilterKeys", "reason": "必须显式一次性隔离PG;验证真实只读SQL身份关联/计数及隐私,不连接生产;默认无库时明确跳过,另行本地补验"},
{"package": "knowledge-governance/internal/dobotaiops", "test": "TestQAUsageGroupsCountEventsOnceOverTheFullFilter", "reason": "必须显式一次性隔离PG;验证真实只读SQL身份关联/计数及隐私,不连接生产;默认无库时明确跳过,另行本地补验"},
{
diff --git a/web/src/QAOperations.tsx b/web/src/QAOperations.tsx
index 72aaacc..5dce526 100644
--- a/web/src/QAOperations.tsx
+++ b/web/src/QAOperations.tsx
@@ -7,9 +7,13 @@ import './qaOps.css'
import { QARegions } from './QARegions'
import { QAUsage } from './QAUsage'
import { QAMonthly } from './QAMonthly'
+import { QAQualityEditor, QAQualityCounts } from './QAQuality'
+import { qualityLabels } from './qaQuality'
import { usageLabels } from './qaUsage'
interface ViewProps {
+ onQualitySaved?: (record: QARecord) => void
+ onReloadDetail?: () => void
page: QARecordPage | null
status: QAStatus | null
loading: boolean
@@ -96,7 +100,10 @@ export function QAOperationsView(props: ViewProps) {
>
{qaCellValue(item, key) ?? '—'}
@@ -111,6 +118,9 @@ export function QAOperationsView(props: ViewProps) {
>
详情
+ {item.quality ? (
+ {qualityLabels[item.quality.state]}
+ ) : null}
|
))}
@@ -149,7 +159,9 @@ export function QAOperationsView(props: ViewProps) {
if (event.key === 'Escape') props.onCloseDetail()
if (event.key === 'Tab') {
const buttons = Array.from(
- event.currentTarget.querySelectorAll('button, a[href], input, [tabindex="0"]')
+ event.currentTarget.querySelectorAll(
+ 'button:not([disabled]), a[href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), summary, [tabindex="0"]'
+ )
)
const first = buttons[0],
last = buttons[buttons.length - 1]
@@ -242,6 +254,17 @@ export function QAOperationsView(props: ViewProps) {
{detail.source_coverage.evaluator_version || '无版本'}
{detail.source_coverage.reason_code || '未记录判定原因'}
+ {detail.quality ? (
+ {})}
+ onReload={props.onReloadDetail ?? (() => {})}
+ />
+ ) : (
+ 质量留档/人工复核未配置。
+ )}
用户反馈
提问人:
@@ -287,6 +310,7 @@ export function QAOperations() {
const [error, setError] = useState(null)
const [loading, setLoading] = useState(false)
const [revision, setRevision] = useState(0)
+ const [qualityRevision, setQualityRevision] = useState(0)
const [detail, setDetail] = useState(null)
const [detailLoading, setDetailLoading] = useState(false)
const [detailError, setDetailError] = useState(null)
@@ -481,6 +505,7 @@ export function QAOperations() {
部门/区域保留源快照,缺失时按当前通讯录补全;使用统计不是绩效结论。外语翻译与AI评估仍暂缓,空值不默认填“否”。
+ {view === 'records' ? : null}
{view === 'usage' ? (
) : (
@@ -492,6 +517,30 @@ export function QAOperations() {
detail={detail}
detailLoading={detailLoading}
detailError={detailError}
+ onReloadDetail={() => {
+ if (detail) void select(detail.id)
+ }}
+ onQualitySaved={(fresh) => {
+ if (fresh.id !== detail?.id) return
+ setDetail(fresh)
+ setPage((old) => {
+ if (!old) return old
+ const all = new Set(old.columns)
+ const f = fresh.quality?.effective
+ if (f) {
+ if (f.coverage) all.add('coverage')
+ if (f.correctness) all.add('is_correct')
+ for (const key of ['product_category', 'problem_type', 'root_cause'] as const)
+ if (f[key]) all.add(key)
+ }
+ return {
+ ...old,
+ items: old.items.map((item) => (item.id === fresh.id ? fresh : item)),
+ columns: qaColumns.filter((c) => all.has(c.key)).map((c) => c.key),
+ }
+ })
+ setQualityRevision((v) => v + 1)
+ }}
onSelect={(id) => void select(id)}
onCloseDetail={close}
onLoadMore={() => void loadMore()}
diff --git a/web/src/QAQuality.test.tsx b/web/src/QAQuality.test.tsx
new file mode 100644
index 0000000..bd05fb3
--- /dev/null
+++ b/web/src/QAQuality.test.tsx
@@ -0,0 +1,43 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+import { describe, it, expect } from 'vitest'
+import { QAQualityEditor, QAQualitySummaryView } from './QAQuality'
+import { qualityFixture, summaryFixture } from './qaQuality.fixture'
+import { parseQAQuality, parseQualitySummary } from './qaQuality'
+describe('manual quality operations', () => {
+ it('renders separate evidence, session reviewer and safe text', () => {
+ const html = renderToStaticMarkup(
+ {}}
+ onReload={() => {}}
+ />
+ )
+ for (const value of ['人工复核', '保存并读回', '覆盖结论', '正确性', '复核理由', 'fixture-admin'])
+ expect(html).toContain(value)
+ expect(html).not.toContain('',
+ reviewer: 'fixture-admin',
+ created_at: '2026-10-17T12:01:00Z',
+}
+export const qualityFixture = {
+ input_hash: hash,
+ input_epoch: 1,
+ revision: 1,
+ state: 'reviewed',
+ automatic: check,
+ latest_review: review,
+ effective: fields,
+}
+export const summaryFixture = {
+ summary: { total: 3, reviewed: 1, unreviewed: 1, stale: 1, pending_confirmation: 0, rule_uncovered: 2 },
+ start: '2026-10-14T00:00:00Z',
+ end: '2026-10-15T00:00:00Z',
+ keyword: '',
+ as_of: '2026-10-17T12:01:00Z',
+ scope: 'whole_filter',
+ ai_state: 'not_configured',
+}
diff --git a/web/src/qaQuality.test.ts b/web/src/qaQuality.test.ts
new file mode 100644
index 0000000..8ee04b5
--- /dev/null
+++ b/web/src/qaQuality.test.ts
@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest'
+import { parseQAQuality, parseQualitySummary, parseQualityHistory } from './qaQuality'
+import { qualityFixture, summaryFixture, check, review } from './qaQuality.fixture'
+import { parseQARecord, qaCellValue } from './qaOps'
+describe('quality evidence contracts', () => {
+ it('renders effective manual labels in agreed columns without changing the rule result', () => {
+ const record = parseQARecord({
+ id: 'fixture',
+ status: 'succeeded',
+ question: '示例',
+ answer: '暂无已发布',
+ asked_at: '2026-10-17T12:00:00Z',
+ time_source: 'request_message.created_at',
+ asker: '',
+ trigger_person: '',
+ department: '',
+ region: '',
+ references: [],
+ media: [],
+ source_coverage: check.source,
+ feedback: { asker_value: '', up: 0, down: 0 },
+ coverage: check.result,
+ quality: qualityFixture,
+ })
+ expect(qaCellValue(record, 'coverage')).toBe('是')
+ expect(qaCellValue(record, 'is_correct')).toBe('是')
+ expect(qaCellValue(record, 'product_category')).toBe('MG400')
+ expect(record.coverage.verdict).toBe('uncovered')
+ })
+
+ it('separates immutable rule/source results and explicit human outcomes', () => {
+ const v = parseQAQuality(qualityFixture)
+ expect(v.effective.coverage).toBe('covered')
+ expect(v.automatic.result.verdict).toBe('uncovered')
+ })
+ it('rejects stale conclusions kept effective and forged revisions', () => {
+ expect(() =>
+ parseQAQuality({ ...qualityFixture, state: 'stale', input_epoch: 2, automatic: { ...check, input_epoch: 2 } })
+ ).toThrow()
+ expect(() => parseQAQuality({ ...qualityFixture, revision: 2 })).toThrow()
+ })
+ it('keeps scope counts whole and conservative without made-up rates', () => {
+ expect(parseQualitySummary(summaryFixture).summary.total).toBe(3)
+ expect(() => parseQualitySummary({ ...summaryFixture, summary: { ...summaryFixture.summary, total: 4 } })).toThrow()
+ })
+ it('retains pageable human and automatic history independently', () => {
+ expect(
+ parseQualityHistory({ reviews: [review], checks: [check], next_review: 0, next_check: 0 }).reviews
+ ).toHaveLength(1)
+ })
+})
diff --git a/web/src/qaQuality.ts b/web/src/qaQuality.ts
new file mode 100644
index 0000000..7e8f61b
--- /dev/null
+++ b/web/src/qaQuality.ts
@@ -0,0 +1,264 @@
+export interface QualityFields {
+ coverage: string
+ correctness: string
+ product_category: string
+ problem_type: string
+ root_cause: string
+ exclusion_reason: string
+}
+export interface QualityCheck {
+ input_available: boolean
+ id: number
+ input_epoch: number
+ input_hash: string
+ result: { state: string; verdict?: string; rule_version: string; matched_text?: string }
+ source: { verdict: string; reason_code: string; evaluator_version: string }
+ created_at: string
+}
+export interface QualityReview {
+ revision: number
+ input_epoch: number
+ input_hash: string
+ fields: QualityFields
+ reason: string
+ reviewer: string
+ created_at: string
+}
+export interface QAQuality {
+ input_hash: string
+ input_epoch: number
+ revision: number
+ state: 'unreviewed' | 'reviewed' | 'stale'
+ automatic: QualityCheck
+ latest_review: QualityReview | null
+ effective: QualityFields
+}
+export interface QualityHistory {
+ reviews: QualityReview[]
+ checks: QualityCheck[]
+ next_review: number
+ next_check: number
+}
+export interface QualitySnapshot {
+ input_epoch: number
+ input_hash: string
+ created_at: string
+ payload: { id: string; question: string; answer: string; status: string; references: unknown; media: unknown }
+}
+export interface QualitySummary {
+ summary: {
+ total: number
+ reviewed: number
+ unreviewed: number
+ stale: number
+ pending_confirmation: number
+ rule_uncovered: number
+ }
+ start: string
+ end: string
+ keyword: string
+ as_of: string
+ scope: 'whole_filter'
+ ai_state: 'not_configured'
+}
+export const emptyQualityFields: QualityFields = {
+ coverage: '',
+ correctness: '',
+ product_category: '',
+ problem_type: '',
+ root_cause: '',
+ exclusion_reason: '',
+}
+export const qualityLabels: Record = {
+ covered: '已覆盖',
+ uncovered: '未覆盖',
+ partial: '部分覆盖',
+ pending: '待确认',
+ excluded: '不计入',
+ correct: '正确',
+ incorrect: '错误',
+ unreviewed: '未复核',
+ reviewed: '已复核',
+ stale: '待重新核对',
+}
+const bad = (): never => {
+ throw new Error('质量留档响应无效,未展示可能失真的结论')
+}
+const obj = (v: unknown): Record =>
+ v && typeof v === 'object' && !Array.isArray(v) ? (v as Record) : bad()
+const text = (v: unknown): string => (typeof v === 'string' ? v : bad())
+const num = (v: unknown): number => (typeof v === 'number' && Number.isSafeInteger(v) && v >= 0 ? v : bad())
+const positive = (v: unknown): number => {
+ const n = num(v)
+ return n > 0 ? n : bad()
+}
+const hash = (v: unknown): string => {
+ const t = text(v)
+ return /^[a-f0-9]{64}$/.test(t) ? t : bad()
+}
+const stamp = (v: unknown): string => {
+ const t = text(v)
+ return Number.isFinite(Date.parse(t)) ? t : bad()
+}
+function fields(v: unknown, complete = false): QualityFields {
+ const r = obj(v)
+ const f = {
+ coverage: text(r.coverage),
+ correctness: text(r.correctness),
+ product_category: text(r.product_category),
+ problem_type: text(r.problem_type),
+ root_cause: text(r.root_cause),
+ exclusion_reason: text(r.exclusion_reason),
+ }
+ if (
+ !['', 'covered', 'uncovered', 'partial', 'pending', 'excluded'].includes(f.coverage) ||
+ !['', 'correct', 'incorrect', 'pending'].includes(f.correctness) ||
+ (complete && (!f.coverage || !f.correctness)) ||
+ (f.correctness === 'correct' && f.root_cause !== '') ||
+ (f.coverage === 'excluded' && !f.exclusion_reason.trim()) ||
+ (f.coverage !== 'excluded' && f.exclusion_reason !== '')
+ )
+ return bad()
+ return f
+}
+function check(value: unknown): QualityCheck {
+ const v = obj(value),
+ r = obj(v.result),
+ s = obj(v.source)
+ const state = text(r.state),
+ rule_version = text(r.rule_version)
+ if (
+ !rule_version ||
+ (state !== 'pending' && state !== 'checked') ||
+ (state === 'checked' && (r.verdict !== 'uncovered' || r.matched_text !== '暂无已发布')) ||
+ (state === 'pending' && r.verdict !== undefined)
+ )
+ return bad()
+ return {
+ input_available: typeof v.input_available === 'boolean' ? v.input_available : bad(),
+ id: positive(v.id),
+ input_epoch: positive(v.input_epoch),
+ input_hash: hash(v.input_hash),
+ result: {
+ state,
+ rule_version,
+ ...(r.verdict === undefined ? {} : { verdict: text(r.verdict), matched_text: text(r.matched_text) }),
+ },
+ source: {
+ verdict: text(s.verdict),
+ reason_code: text(s.reason_code),
+ evaluator_version: text(s.evaluator_version),
+ },
+ created_at: stamp(v.created_at),
+ }
+}
+function review(value: unknown): QualityReview {
+ const v = obj(value),
+ reason = text(v.reason),
+ reviewer = text(v.reviewer)
+ if (!reason.trim() || !reviewer) return bad()
+ return {
+ revision: positive(v.revision),
+ input_epoch: positive(v.input_epoch),
+ input_hash: hash(v.input_hash),
+ fields: fields(v.fields, true),
+ reason,
+ reviewer,
+ created_at: stamp(v.created_at),
+ }
+}
+export function parseQAQuality(value: unknown): QAQuality {
+ const v = obj(value),
+ state = text(v.state)
+ if (!['unreviewed', 'reviewed', 'stale'].includes(state)) return bad()
+ const automatic = check(v.automatic),
+ latest_review = v.latest_review === null ? null : review(v.latest_review),
+ input_hash = hash(v.input_hash),
+ input_epoch = positive(v.input_epoch),
+ revision = num(v.revision),
+ effective = fields(v.effective)
+ if (
+ automatic.input_hash !== input_hash ||
+ automatic.input_epoch !== input_epoch ||
+ (latest_review && latest_review.revision !== revision) ||
+ (!latest_review && revision !== 0)
+ )
+ return bad()
+ const actual = latest_review
+ ? latest_review.input_hash === input_hash && latest_review.input_epoch === input_epoch
+ ? 'reviewed'
+ : 'stale'
+ : 'unreviewed'
+ if (state !== actual) return bad()
+ const expected =
+ state === 'reviewed' ? latest_review!.fields : { ...emptyQualityFields, coverage: automatic.result.verdict || '' }
+ for (const key of Object.keys(expected) as (keyof QualityFields)[]) if (expected[key] !== effective[key]) return bad()
+ return { input_hash, input_epoch, revision, state: state as QAQuality['state'], automatic, latest_review, effective }
+}
+export function parseQualitySummary(value: unknown): QualitySummary {
+ const v = obj(value),
+ s = obj(v.summary),
+ summary = {
+ total: num(s.total),
+ reviewed: num(s.reviewed),
+ unreviewed: num(s.unreviewed),
+ stale: num(s.stale),
+ pending_confirmation: num(s.pending_confirmation),
+ rule_uncovered: num(s.rule_uncovered),
+ }
+ const start = stamp(v.start),
+ end = stamp(v.end)
+ if (
+ v.scope !== 'whole_filter' ||
+ v.ai_state !== 'not_configured' ||
+ summary.total !== summary.reviewed + summary.unreviewed + summary.stale ||
+ summary.pending_confirmation > summary.reviewed ||
+ summary.rule_uncovered > summary.total ||
+ Date.parse(start) >= Date.parse(end)
+ )
+ return bad()
+ return {
+ summary,
+ start,
+ end,
+ keyword: text(v.keyword),
+ as_of: stamp(v.as_of),
+ scope: 'whole_filter',
+ ai_state: 'not_configured',
+ }
+}
+export function parseQualityHistory(value: unknown): QualityHistory {
+ const v = obj(value)
+ if (!Array.isArray(v.reviews) || !Array.isArray(v.checks)) return bad()
+ const reviews = v.reviews.map(review),
+ checks = v.checks.map(check),
+ next_review = num(v.next_review),
+ next_check = num(v.next_check)
+ if (
+ reviews.length > 20 ||
+ checks.length > 20 ||
+ reviews.some((r, i) => i > 0 && r.revision >= reviews[i - 1].revision) ||
+ checks.some((c, i) => i > 0 && c.id >= checks[i - 1].id) ||
+ (next_review && next_review !== reviews.at(-1)?.revision) ||
+ (next_check && next_check !== checks.at(-1)?.id)
+ )
+ return bad()
+ return { reviews, checks, next_review, next_check }
+}
+export function parseQualitySnapshot(value: unknown): QualitySnapshot {
+ const v = obj(value),
+ p = obj(v.payload)
+ return {
+ input_epoch: positive(v.input_epoch),
+ input_hash: hash(v.input_hash),
+ created_at: stamp(v.created_at),
+ payload: {
+ id: text(p.id),
+ question: text(p.question),
+ answer: text(p.answer),
+ status: text(p.status),
+ references: p.references,
+ media: p.media,
+ },
+ }
+}
--
2.52.0
From 828c2c5fa0d4e3e0eee3987085a4d782872f7e95 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Sun, 18 Oct 2026 02:00:31 +0800
Subject: [PATCH 09/14] =?UTF-8?q?feat(qa-ops):=20=E6=8C=89=E7=A1=AE?=
=?UTF-8?q?=E8=AE=A4=E5=8F=A3=E5=BE=84=E8=A1=A5=E9=BD=90=E8=B4=A8=E9=87=8F?=
=?UTF-8?q?=E6=AF=94=E4=BE=8B=E4=B8=8E=E5=88=86=E6=AF=8D=E6=98=8E=E7=BB=86?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
使用完整筛选范围的当前有效结论计算覆盖率和正确率,人工优先,失效与对应待确认/未评估/不计入排除;零分母返回null,界面展示原始分子分母和排除构成,前端拒绝不守恒或比例不一致的响应。
验证:make verify退出码0,Go658及前端257通过,91项声明可选集成跳过;隔离PG、三包竞态及合成/真实只读源浏览器验证通过。无新增迁移,不接AI模型,不改绩效,不写源库;本批未推送或部署,8088运行版保持0.1.21。
---
CHANGELOG.md | 4 +-
api/openapi.yaml | 2 +-
internal/httpapi/qa_quality_test.go | 8 +++
internal/qaopsquality/projection.go | 2 +-
internal/qaopsquality/quality.go | 13 ++---
internal/qaopsquality/rates.go | 72 +++++++++++++++++++++++++++
internal/qaopsquality/rates_test.go | 44 +++++++++++++++++
web/src/QAQuality.test.tsx | 53 ++++++++++++++++++++
web/src/QAQuality.tsx | 41 +++++++++++++++-
web/src/qaOps.css | 14 ++++++
web/src/qaQuality.fixture.ts | 27 ++++++++++-
web/src/qaQuality.test.ts | 23 +++++++++
web/src/qaQuality.ts | 75 +++++++++++++++++++++++++++++
13 files changed, 367 insertions(+), 11 deletions(-)
create mode 100644 internal/qaopsquality/rates.go
create mode 100644 internal/qaopsquality/rates_test.go
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0e85801..3539a56 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,8 +4,10 @@
### Added
+- 问答运营按已确认口径显示知识覆盖率、回答正确率及原始分子/分母、排除数量与构成。使用完整筛选范围和当前有效人工优先结论,精确规则命中的未覆盖可进入覆盖分母;部分覆盖不算完全覆盖,待确认/未评估/失效/不计入按对应指标排除,零分母显示“暂无可计算数据”。返回独立规则版本,AI 模型与绩效范围仍未接入。
+
- 问答详情支持治理侧人工复核及不可变审计:覆盖、正确性、产品分类、问题类型、根因与理由由管理员明确填写,操作人取登录身份;保存后独立读回复核历史。保留源端判断和自动规则,输入变化使旧人工结论失效,已观测的内容回退不自动恢复旧结论;并发修改冲突、重复请求不重复留档。
-- 新增覆盖复检历史、已采集输入快照和完整筛选范围质量数量。批量统计只传指纹与规则命中元数据,原文在读取问答/复核时采集,未采集版本明确提示而非伪造空快照;源事务时点阻止延迟旧扫描回退新输入。仅提供数量,不接 AI 模型、不定义质量率或绩效分母、不回写 DobotAI 原问答。
+- 新增覆盖复检历史、已采集输入快照和完整筛选范围质量数量。批量统计只传指纹与规则命中元数据,原文在读取问答/复核时采集,未采集版本明确提示而非伪造空快照;源事务时点阻止延迟旧扫描回退新输入。基础数量与本期经确认新增的质量比例分开显示;不接 AI 模型、不定义绩效分母、不回写 DobotAI 原问答。
- 「使用统计 → 个人月明细」按北京时间自然月及截止时点展示当前应用可见名册的人员用量(包含本源零记录),支持部门含子部门、区域/待核对状态、姓名/完整部门路径和已有提问/零记录筛选。稳定身份关联去重、不可关联问答单列、过期组织版本阻断翻页;源端姓名可缺失并提示重新同步,不按姓名匹配身份。姓名筛选通过有界只读 POST 请求体传递、不进入 URL,原始员工标识不返回浏览器;名册不作为在职/考核分母,当月进度不作为绩效结论。
diff --git a/api/openapi.yaml b/api/openapi.yaml
index c931a07..7877a12 100644
--- a/api/openapi.yaml
+++ b/api/openapi.yaml
@@ -101,7 +101,7 @@
},
"/api/v1/qa-ops/usage/people": {"post": {"tags": ["QA operations"], "operationId": "queryQAOperationsMonthlyPeople", "summary": "按北京时间自然月列出当前名册人员的2.0用量(含零记录),仅管理员,不返回原始员工标识,不作为在职/考核名单", "responses": {"200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"description": "需要登录"}, "403": {"description": "仅管理员访问"}, "503": {"description": "独立只读源或治理组织存储不可用,不返回伪造的零值"}, "500": {"$ref": "#/components/responses/InternalError"}, "409": {"description": "完整名册缺失或目录/区域版本变化,请同步/重新查询,不返回伪零"}}, "description": "只读查询,不写治理库或生产库;姓名筛选置于 JSON 请求体,不进入 URL;整名册指标不随人员筛选变化。第2页起须带首页目录、区域版本及 end 截止。", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["month"], "properties": {"month": {"type": "string", "pattern": "^(?!0000)[0-9]{4}-(0[1-9]|1[0-2])$"}, "cutoff": {"type": "string", "format": "date-time"}, "region": {"type": "string", "enum": ["国内工业", "APAC", "EMEA", "America", "unassigned", "cross_region"]}, "department_id": {"type": "string"}, "activity": {"type": "string", "enum": ["all", "used", "zero"]}, "search": {"type": "string", "maxLength": 100}, "page": {"type": "integer", "minimum": 1, "maximum": 100000, "default": 1}, "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 30}, "directory_id": {"type": "string"}, "revision_id": {"type": "string"}}}}}}, "parameters": [{"name": "X-Governance-Action", "in": "header", "required": true, "schema": {"type": "string", "enum": ["qa-usage-read"]}}]}},
"/api/v1/qa-ops/usage": {"get": {"tags": ["QA operations"], "operationId": "getQAOperationsUsage", "summary": "完整筛选范围内按当前通讯录和区域版本回看2.0问答使用;固定租户、管理员访问,不输出绩效结论", "parameters": [{"name": "start", "in": "query", "required": true, "schema": {"type": "string", "format": "date-time"}}, {"name": "end", "in": "query", "required": true, "schema": {"type": "string", "format": "date-time"}}, {"name": "keyword", "in": "query", "schema": {"type": "string", "maxLength": 200}}], "responses": {"200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"description": "需要登录"}, "403": {"description": "仅管理员访问"}, "503": {"description": "独立只读源或治理组织存储不可用,不返回伪造的零值"}, "500": {"$ref": "#/components/responses/InternalError"}}}},
- "/api/v1/qa-ops/quality/query": {"post": {"operationId": "queryQAQualityCounts", "summary": "按完整时间/原问题字面关键词读取指纹及规则命中元数据并留档统计,原文仅在读取问答/复核时采集;不计算质量率,最多5000条", "parameters": [{"name": "X-Governance-Action", "in": "header", "required": true, "schema": {"type": "string", "enum": ["qa-quality"]}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "properties": {"start": {"type": "string", "format": "date-time"}, "end": {"type": "string", "format": "date-time"}, "keyword": {"type": "string", "maxLength": 200}}, "required": ["start", "end"]}}}}, "tags": ["QA operations"], "responses": {"200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"description": "需要登录"}, "403": {"description": "仅管理员访问"}, "503": {"description": "独立只读源或治理组织存储不可用,不返回伪造的零值"}, "500": {"$ref": "#/components/responses/InternalError"}, "409": {"description": "输入或复核版本变化/重复操作载荷不一致,未覆盖原结论"}, "404": {"description": "当前授权范围内未找到记录/历史输入"}}}},
+ "/api/v1/qa-ops/quality/query": {"post": {"operationId": "queryQAQualityCounts", "summary": "按完整筛选范围读取指纹/规则元数据并留档统计,最多5000条;summary.rates 返回 quality-rates-human-first-v1、原始分子/分母、百分比与分母构成。覆盖率=covered/(covered+uncovered+partial),正确率=covered_correct/(covered_correct+covered_incorrect);失效/不计入/相应待确认与未评估排除,零分母percent=null。原文仅在读取问答/复核时采集", "parameters": [{"name": "X-Governance-Action", "in": "header", "required": true, "schema": {"type": "string", "enum": ["qa-quality"]}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "properties": {"start": {"type": "string", "format": "date-time"}, "end": {"type": "string", "format": "date-time"}, "keyword": {"type": "string", "maxLength": 200}}, "required": ["start", "end"]}}}}, "tags": ["QA operations"], "responses": {"200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"description": "需要登录"}, "403": {"description": "仅管理员访问"}, "503": {"description": "独立只读源或治理组织存储不可用,不返回伪造的零值"}, "500": {"$ref": "#/components/responses/InternalError"}, "409": {"description": "输入或复核版本变化/重复操作载荷不一致,未覆盖原结论"}, "404": {"description": "当前授权范围内未找到记录/历史输入"}}}},
"/api/v1/qa-ops/records/{id}/reviews": {"post": {"operationId": "saveQAQualityReview", "summary": "治理库追加人工复核,登录身份审计,源端只读,输入/复核乐观锁和nonce幂等;正确时根因为空,不计入须说明原因", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "X-Governance-Action", "in": "header", "required": true, "schema": {"type": "string", "enum": ["qa-quality"]}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "properties": {"input_hash": {"type": "string", "pattern": "^[a-f0-9]{64}$"}, "input_epoch": {"type": "integer", "minimum": 1}, "base_revision": {"type": "integer", "minimum": 0}, "nonce": {"type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$"}, "fields": {"type": "object", "additionalProperties": false, "properties": {"coverage": {"type": "string", "enum": ["covered", "uncovered", "partial", "pending", "excluded"]}, "correctness": {"type": "string", "enum": ["correct", "incorrect", "pending"]}, "product_category": {"type": "string", "maxLength": 128}, "problem_type": {"type": "string", "maxLength": 128}, "root_cause": {"type": "string", "maxLength": 2000}, "exclusion_reason": {"type": "string", "maxLength": 2000}}, "required": ["coverage", "correctness"]}, "reason": {"type": "string", "minLength": 1, "maxLength": 4000}}, "required": ["input_hash", "input_epoch", "base_revision", "nonce", "fields", "reason"]}}}}, "tags": ["QA operations"], "responses": {"200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"description": "需要登录"}, "403": {"description": "仅管理员访问"}, "503": {"description": "独立只读源或治理组织存储不可用,不返回伪造的零值"}, "500": {"$ref": "#/components/responses/InternalError"}, "409": {"description": "输入或复核版本变化/重复操作载荷不一致,未覆盖原结论"}, "404": {"description": "当前授权范围内未找到记录/历史输入"}}}},
"/api/v1/qa-ops/records/{id}/quality/history": {"get": {"operationId": "listQAQualityHistory", "summary": "按当前固定租户查询不可变复检/人工历史,分别倒序分页,各20条", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "review_before", "in": "query", "schema": {"type": "integer", "minimum": 1}}, {"name": "check_before", "in": "query", "schema": {"type": "integer", "minimum": 1}}], "tags": ["QA operations"], "responses": {"200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"description": "需要登录"}, "403": {"description": "仅管理员访问"}, "503": {"description": "独立只读源或治理组织存储不可用,不返回伪造的零值"}, "500": {"$ref": "#/components/responses/InternalError"}, "409": {"description": "输入或复核版本变化/重复操作载荷不一致,未覆盖原结论"}, "404": {"description": "当前授权范围内未找到记录/历史输入"}}}},
"/api/v1/qa-ops/records/{id}/quality/inputs/{epoch}": {"get": {"operationId": "getQAQualityInputSnapshot", "summary": "管理员读取已采集的历史质量输入快照,不另存人员关联/反馈字段;元数据留档但未采集原文返回409,不编造空快照", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "epoch", "in": "path", "required": true, "schema": {"type": "integer", "minimum": 1}}], "tags": ["QA operations"], "responses": {"200": {"$ref": "#/components/responses/Envelope"}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"description": "需要登录"}, "403": {"description": "仅管理员访问"}, "503": {"description": "独立只读源或治理组织存储不可用,不返回伪造的零值"}, "500": {"$ref": "#/components/responses/InternalError"}, "409": {"description": "该输入版本仅有指纹/规则元数据、原文未采集"}, "404": {"description": "当前授权范围内未找到记录/历史输入"}}}},
diff --git a/internal/httpapi/qa_quality_test.go b/internal/httpapi/qa_quality_test.go
index c8395ab..32f909b 100644
--- a/internal/httpapi/qa_quality_test.go
+++ b/internal/httpapi/qa_quality_test.go
@@ -117,6 +117,14 @@ func TestQAQualityDetailListAndWholeScopeCounts(t *testing.T) {
if w.Code != 200 || !strings.Contains(w.Body.String(), `"unreviewed":2`) || source.scopeCalls != 1 || source.tenant != "fixed" || store.calls < 2 {
t.Fatal("quality summary estimated from page instead of scope", w.Code, w.Body.String())
}
+ var counts struct {
+ Data struct {
+ Summary qaopsquality.Summary `json:"summary"`
+ } `json:"data"`
+ }
+ if json.Unmarshal(w.Body.Bytes(), &counts) != nil || counts.Data.Summary.Rates.Coverage.Denominator != 2 || counts.Data.Summary.Rates.Coverage.Numerator != 0 || counts.Data.Summary.Rates.Correctness.Percent != nil {
+ t.Fatal("confirmed quality metrics were not computed for the whole scope")
+ }
store.fail = true
w = qualityRequest(h, "GET", "/api/v1/qa-ops/records/fixture-turn", "quality-admin", "")
if w.Code != 503 || !strings.Contains(w.Body.String(), "quality_unavailable") {
diff --git a/internal/qaopsquality/projection.go b/internal/qaopsquality/projection.go
index b6e6392..0a1d407 100644
--- a/internal/qaopsquality/projection.go
+++ b/internal/qaopsquality/projection.go
@@ -104,7 +104,7 @@ func Project(hash string, epoch, revision int64, automatic Check, review *Review
return view
}
func Summarize(views map[string]View) Summary {
- result := Summary{Total: len(views)}
+ result := Summary{Total: len(views), Rates: ComputeRates(views)}
for _, v := range views {
switch v.State {
case "reviewed":
diff --git a/internal/qaopsquality/quality.go b/internal/qaopsquality/quality.go
index 0344d0f..c244034 100644
--- a/internal/qaopsquality/quality.go
+++ b/internal/qaopsquality/quality.go
@@ -64,12 +64,13 @@ type History struct {
NextCheck int64 `json:"next_check"`
}
type Summary struct {
- Total int `json:"total"`
- Reviewed int `json:"reviewed"`
- Unreviewed int `json:"unreviewed"`
- Stale int `json:"stale"`
- PendingConfirmation int `json:"pending_confirmation"`
- RuleUncovered int `json:"rule_uncovered"`
+ Rates Rates `json:"rates"`
+ Total int `json:"total"`
+ Reviewed int `json:"reviewed"`
+ Unreviewed int `json:"unreviewed"`
+ Stale int `json:"stale"`
+ PendingConfirmation int `json:"pending_confirmation"`
+ RuleUncovered int `json:"rule_uncovered"`
}
type Receipt struct {
View View `json:"view"`
diff --git a/internal/qaopsquality/rates.go b/internal/qaopsquality/rates.go
new file mode 100644
index 0000000..8bb2283
--- /dev/null
+++ b/internal/qaopsquality/rates.go
@@ -0,0 +1,72 @@
+package qaopsquality
+
+type Rate struct {
+ Numerator int `json:"numerator"`
+ Denominator int `json:"denominator"`
+ Percent *float64 `json:"percent"`
+}
+type RateBreakdown struct {
+ Covered int `json:"covered"`
+ Uncovered int `json:"uncovered"`
+ Partial int `json:"partial"`
+ Pending int `json:"pending"`
+ Unassessed int `json:"unassessed"`
+ Excluded int `json:"excluded"`
+ Stale int `json:"stale"`
+ CoveredCorrect int `json:"covered_correct"`
+ CoveredIncorrect int `json:"covered_incorrect"`
+ CoveredPending int `json:"covered_pending"`
+ CoveredUnassessed int `json:"covered_unassessed"`
+}
+type Rates struct {
+ PolicyVersion string `json:"policy_version"`
+ Coverage Rate `json:"coverage"`
+ Correctness Rate `json:"correctness"`
+ Breakdown RateBreakdown `json:"breakdown"`
+}
+
+func ComputeRates(views map[string]View) Rates {
+ out := Rates{PolicyVersion: "quality-rates-human-first-v1"}
+ b := &out.Breakdown
+ for _, v := range views {
+ if v.State == "stale" {
+ b.Stale++
+ continue
+ }
+ switch v.Effective.Coverage {
+ case "covered":
+ b.Covered++
+ switch v.Effective.Correctness {
+ case "correct":
+ b.CoveredCorrect++
+ case "incorrect":
+ b.CoveredIncorrect++
+ case "pending":
+ b.CoveredPending++
+ default:
+ b.CoveredUnassessed++
+ }
+ case "uncovered":
+ b.Uncovered++
+ case "partial":
+ b.Partial++
+ case "pending":
+ b.Pending++
+ case "excluded":
+ b.Excluded++
+ default:
+ b.Unassessed++
+ }
+ }
+ out.Coverage = makeRate(b.Covered, b.Covered+b.Uncovered+b.Partial)
+ out.Correctness = makeRate(b.CoveredCorrect, b.CoveredCorrect+b.CoveredIncorrect)
+ return out
+}
+func makeRate(numerator, denominator int) Rate {
+ r := Rate{Numerator: numerator, Denominator: denominator}
+ if denominator > 0 {
+ p := 100 * float64(numerator) / float64(denominator)
+ r.Percent = &p
+ }
+ return r
+}
diff --git a/internal/qaopsquality/rates_test.go b/internal/qaopsquality/rates_test.go
new file mode 100644
index 0000000..e4875e7
--- /dev/null
+++ b/internal/qaopsquality/rates_test.go
@@ -0,0 +1,44 @@
+package qaopsquality
+
+import (
+ "encoding/json"
+ "knowledge-governance/internal/dobotaiops"
+ "math"
+ "strings"
+ "testing"
+)
+
+func TestQualityRatesUseEffectiveCurrentConclusionsAndExplicitDenominators(t *testing.T) {
+ views := map[string]View{}
+ for i, fields := range []Fields{{Coverage: "covered", Correctness: "correct"}, {Coverage: "covered", Correctness: "incorrect"}, {Coverage: "covered", Correctness: "pending"}, {Coverage: "uncovered"}, {Coverage: "partial", Correctness: "correct"}, {Coverage: "pending", Correctness: "correct"}, {}, {Coverage: "excluded", Correctness: "pending"}, {Coverage: "covered", Correctness: "correct"}, {Coverage: "covered"}} {
+ state := "reviewed"
+ if i == 3 || i == 6 {
+ state = "unreviewed"
+ }
+ if i == 8 {
+ state = "stale"
+ }
+ views[string(rune('a'+i))] = View{State: state, Effective: fields, Automatic: Check{Result: dobotaiops.CheckAnswerCoverage("暂无已发布")}}
+ }
+ r := ComputeRates(views)
+ if r.PolicyVersion != "quality-rates-human-first-v1" || r.Coverage.Numerator != 4 || r.Coverage.Denominator != 6 || r.Correctness.Numerator != 1 || r.Correctness.Denominator != 2 {
+ t.Fatal("effective decisions, partial or exclusion scopes incorrect", r)
+ }
+ if r.Coverage.Percent == nil || math.Abs(*r.Coverage.Percent-100*float64(4)/6) > 1e-10 || r.Correctness.Percent == nil || *r.Correctness.Percent != 50 {
+ t.Fatal("ratio value disagrees with raw counts")
+ }
+ b := r.Breakdown
+ if b.Covered+b.Uncovered+b.Partial+b.Pending+b.Unassessed+b.Excluded+b.Stale != len(views) || b.CoveredCorrect+b.CoveredIncorrect+b.CoveredPending+b.CoveredUnassessed != b.Covered {
+ t.Fatal("denominator breakdown not conserved")
+ }
+ if got := Summarize(views); got.Rates.Coverage.Denominator != 6 {
+ t.Fatal("scope summary did not consume the one shared calculation")
+ }
+}
+func TestQualityRatesEmptyScopeHasNullPercent(t *testing.T) {
+ r := ComputeRates(map[string]View{})
+ raw, _ := json.Marshal(r)
+ if r.Coverage.Percent != nil || r.Correctness.Percent != nil || strings.Count(string(raw), `"percent":null`) != 2 {
+ t.Fatal("zero denominator fabricated zero or full rate")
+ }
+}
diff --git a/web/src/QAQuality.test.tsx b/web/src/QAQuality.test.tsx
index bd05fb3..1823e98 100644
--- a/web/src/QAQuality.test.tsx
+++ b/web/src/QAQuality.test.tsx
@@ -41,3 +41,56 @@ describe('manual quality operations', () => {
expect(ok).toContain('AI 评估未接入')
})
})
+
+it('displays approved rates with raw denominators and exclusions', () => {
+ const html = renderToStaticMarkup(
+ {}} />
+ )
+ for (const value of [
+ '知识覆盖率',
+ '回答正确率',
+ '50.0%',
+ '100.0%',
+ '分子',
+ '分母',
+ '排除',
+ '部分覆盖',
+ 'quality-rates-human-first-v1',
+ ])
+ expect(html).toContain(value)
+ expect(html).not.toContain('不计算比例')
+})
+it('does not turn zero denominators into 0% or 100%', () => {
+ const v = parseQualitySummary(structuredClone(summaryFixture))
+ v.summary = {
+ total: 0,
+ reviewed: 0,
+ unreviewed: 0,
+ stale: 0,
+ pending_confirmation: 0,
+ rule_uncovered: 0,
+ rates: {
+ policy_version: 'quality-rates-human-first-v1',
+ coverage: { numerator: 0, denominator: 0, percent: null },
+ correctness: { numerator: 0, denominator: 0, percent: null },
+ breakdown: {
+ covered: 0,
+ uncovered: 0,
+ partial: 0,
+ pending: 0,
+ unassessed: 0,
+ excluded: 0,
+ stale: 0,
+ covered_correct: 0,
+ covered_incorrect: 0,
+ covered_pending: 0,
+ covered_unassessed: 0,
+ },
+ },
+ } as typeof v.summary
+ const html = renderToStaticMarkup(
+ {}} />
+ )
+ expect(html).toContain('暂无可计算数据')
+ expect(html).not.toContain('0.0%')
+})
diff --git a/web/src/QAQuality.tsx b/web/src/QAQuality.tsx
index 6a87909..14e39f1 100644
--- a/web/src/QAQuality.tsx
+++ b/web/src/QAQuality.tsx
@@ -421,8 +421,47 @@ export function QAQualitySummaryView({ data, loading, error, onRefresh }: Summar
待重新核对 {data.summary.stale} · 人工待确认 {data.summary.pending_confirmation} · 规则命中未覆盖{' '}
{data.summary.rule_uncovered}
+
+ {(
+ [
+ ['知识覆盖率', data.summary.rates.coverage],
+ ['回答正确率', data.summary.rates.correctness],
+ ] as const
+ ).map(([label, rate]) => (
+
+
+ {label}:{rate.percent === null ? '暂无可计算数据' : `${rate.percent.toFixed(1)}%`}
+
+
+ 分子 {rate.numerator} / 分母 {rate.denominator};排除 {data.summary.total - rate.denominator} 条
+
+
+ ))}
+
+
+ 查看比例口径和分母构成
+
+ 覆盖分母:已覆盖 {data.summary.rates.breakdown.covered} + 未覆盖 {data.summary.rates.breakdown.uncovered}{' '}
+ + 部分覆盖 {data.summary.rates.breakdown.partial};部分覆盖不计完全覆盖。
+
+
+ 覆盖分母排除:待确认 {data.summary.rates.breakdown.pending}、未评估{' '}
+ {data.summary.rates.breakdown.unassessed}、不计入 {data.summary.rates.breakdown.excluded}、待重新核对{' '}
+ {data.summary.rates.breakdown.stale}。
+
+
+ 正确性分母仅含已覆盖且判断明确:正确 {data.summary.rates.breakdown.covered_correct} + 错误{' '}
+ {data.summary.rates.breakdown.covered_incorrect};已覆盖中的待确认{' '}
+ {data.summary.rates.breakdown.covered_pending}、未评估 {data.summary.rates.breakdown.covered_unassessed}{' '}
+ 不计入,其余未覆盖/部分覆盖等记录也不计入。
+
+
+ 当前有效人工结论优先;精确规则命中的未覆盖可进入覆盖分母,但不证明回答错误。失效记录暂不参与两项比例,原始问答运行成功也不代表答案正确。
+
+ 统计规则:{data.summary.rates.policy_version}
+
- AI 评估未接入;人工待确认是已复核中的子集,规则命中可与人工结论不同。不计算比例。读取:{stamp(data.as_of)}
+ AI 评估未接入;人工待确认是已复核中的子集,规则命中可与人工结论不同。读取:{stamp(data.as_of)}
>
) : !error && !loading ? (
diff --git a/web/src/qaOps.css b/web/src/qaOps.css
index b5651ec..7c0c1a2 100644
--- a/web/src/qaOps.css
+++ b/web/src/qaOps.css
@@ -394,3 +394,17 @@
grid-template-columns: 100px 1fr;
}
}
+
+.qa-quality-rates {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 12px 32px;
+ margin: 12px 0;
+}
+.qa-quality-rates > div {
+ min-width: 0;
+ overflow-wrap: anywhere;
+}
+.qa-quality-rates p {
+ margin: 4px 0 0;
+}
diff --git a/web/src/qaQuality.fixture.ts b/web/src/qaQuality.fixture.ts
index bfa65c5..150aba9 100644
--- a/web/src/qaQuality.fixture.ts
+++ b/web/src/qaQuality.fixture.ts
@@ -40,7 +40,32 @@ export const qualityFixture = {
effective: fields,
}
export const summaryFixture = {
- summary: { total: 3, reviewed: 1, unreviewed: 1, stale: 1, pending_confirmation: 0, rule_uncovered: 2 },
+ summary: {
+ total: 3,
+ reviewed: 1,
+ unreviewed: 1,
+ stale: 1,
+ pending_confirmation: 0,
+ rule_uncovered: 2,
+ rates: {
+ policy_version: 'quality-rates-human-first-v1',
+ coverage: { numerator: 1, denominator: 2, percent: 50 },
+ correctness: { numerator: 1, denominator: 1, percent: 100 },
+ breakdown: {
+ covered: 1,
+ uncovered: 1,
+ partial: 0,
+ pending: 0,
+ unassessed: 0,
+ excluded: 0,
+ stale: 1,
+ covered_correct: 1,
+ covered_incorrect: 0,
+ covered_pending: 0,
+ covered_unassessed: 0,
+ },
+ },
+ },
start: '2026-10-14T00:00:00Z',
end: '2026-10-15T00:00:00Z',
keyword: '',
diff --git a/web/src/qaQuality.test.ts b/web/src/qaQuality.test.ts
index 8ee04b5..848f2cb 100644
--- a/web/src/qaQuality.test.ts
+++ b/web/src/qaQuality.test.ts
@@ -49,3 +49,26 @@ describe('quality evidence contracts', () => {
).toHaveLength(1)
})
})
+
+describe('confirmed quality rate contract', () => {
+ it('retains raw counts, null rates, scope breakdown and policy version', () => {
+ const result = parseQualitySummary(summaryFixture)
+ expect(result.summary.rates.coverage.numerator).toBe(1)
+ expect(result.summary.rates.coverage.denominator).toBe(2)
+ expect(result.summary.rates.correctness.percent).toBe(100)
+ })
+ it('rejects invalid or inconsistent numerator, denominator, percent and category sums', () => {
+ for (const change of [
+ (r: any) => (r.coverage.numerator = 3),
+ (r: any) => (r.coverage.denominator = 3),
+ (r: any) => (r.coverage.percent = 99),
+ (r: any) => (r.breakdown.stale = 0),
+ (r: any) => (r.correctness.percent = null),
+ (r: any) => (r.policy_version = 'unknown'),
+ ]) {
+ const v = structuredClone(summaryFixture)
+ change(v.summary.rates)
+ expect(() => parseQualitySummary(v)).toThrow()
+ }
+ })
+})
diff --git a/web/src/qaQuality.ts b/web/src/qaQuality.ts
index 7e8f61b..c733e47 100644
--- a/web/src/qaQuality.ts
+++ b/web/src/qaQuality.ts
@@ -45,6 +45,29 @@ export interface QualitySnapshot {
created_at: string
payload: { id: string; question: string; answer: string; status: string; references: unknown; media: unknown }
}
+export interface QualityRate {
+ numerator: number
+ denominator: number
+ percent: number | null
+}
+export interface QualityRates {
+ policy_version: 'quality-rates-human-first-v1'
+ coverage: QualityRate
+ correctness: QualityRate
+ breakdown: {
+ covered: number
+ uncovered: number
+ partial: number
+ pending: number
+ unassessed: number
+ excluded: number
+ stale: number
+ covered_correct: number
+ covered_incorrect: number
+ covered_pending: number
+ covered_unassessed: number
+ }
+}
export interface QualitySummary {
summary: {
total: number
@@ -53,6 +76,7 @@ export interface QualitySummary {
stale: number
pending_confirmation: number
rule_uncovered: number
+ rates: QualityRates
}
start: string
end: string
@@ -195,6 +219,56 @@ export function parseQAQuality(value: unknown): QAQuality {
for (const key of Object.keys(expected) as (keyof QualityFields)[]) if (expected[key] !== effective[key]) return bad()
return { input_hash, input_epoch, revision, state: state as QAQuality['state'], automatic, latest_review, effective }
}
+function qualityRate(value: unknown): QualityRate {
+ const v = obj(value),
+ numerator = num(v.numerator),
+ denominator = num(v.denominator)
+ if (numerator > denominator) return bad()
+ if (denominator === 0) {
+ if (v.percent !== null) return bad()
+ return { numerator, denominator, percent: null }
+ }
+ if (
+ typeof v.percent !== 'number' ||
+ !Number.isFinite(v.percent) ||
+ v.percent < 0 ||
+ v.percent > 100 ||
+ Math.abs(v.percent - (100 * numerator) / denominator) > 1e-8
+ )
+ return bad()
+ return { numerator, denominator, percent: v.percent }
+}
+function qualityRates(value: unknown, total: number, stale: number): QualityRates {
+ const v = obj(value),
+ r = obj(v.breakdown)
+ const b = {
+ covered: num(r.covered),
+ uncovered: num(r.uncovered),
+ partial: num(r.partial),
+ pending: num(r.pending),
+ unassessed: num(r.unassessed),
+ excluded: num(r.excluded),
+ stale: num(r.stale),
+ covered_correct: num(r.covered_correct),
+ covered_incorrect: num(r.covered_incorrect),
+ covered_pending: num(r.covered_pending),
+ covered_unassessed: num(r.covered_unassessed),
+ }
+ const coverage = qualityRate(v.coverage),
+ correctness = qualityRate(v.correctness)
+ if (
+ v.policy_version !== 'quality-rates-human-first-v1' ||
+ b.stale !== stale ||
+ num(b.covered + b.uncovered + b.partial + b.pending + b.unassessed + b.excluded + b.stale) !== total ||
+ num(b.covered_correct + b.covered_incorrect + b.covered_pending + b.covered_unassessed) !== b.covered ||
+ coverage.numerator !== b.covered ||
+ coverage.denominator !== b.covered + b.uncovered + b.partial ||
+ correctness.numerator !== b.covered_correct ||
+ correctness.denominator !== b.covered_correct + b.covered_incorrect
+ )
+ return bad()
+ return { policy_version: 'quality-rates-human-first-v1', coverage, correctness, breakdown: b }
+}
export function parseQualitySummary(value: unknown): QualitySummary {
const v = obj(value),
s = obj(v.summary),
@@ -205,6 +279,7 @@ export function parseQualitySummary(value: unknown): QualitySummary {
stale: num(s.stale),
pending_confirmation: num(s.pending_confirmation),
rule_uncovered: num(s.rule_uncovered),
+ rates: qualityRates(s.rates, num(s.total), num(s.stale)),
}
const start = stamp(v.start),
end = stamp(v.end)
--
2.52.0
From 2ea2111420e501fec37e0ea0c4bcd3cd8c866403 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Sun, 18 Oct 2026 15:45:09 +0800
Subject: [PATCH 10/14] =?UTF-8?q?fix(web):=20=E4=BF=9D=E7=95=99=E4=BB=A3?=
=?UTF-8?q?=E7=90=86=E7=AB=AF=E5=8F=A3=E4=BB=A5=E4=BF=AE=E5=A4=8D=E5=90=8C?=
=?UTF-8?q?=E6=BA=90=E8=B4=A8=E9=87=8F=E6=9F=A5=E8=AF=A2=E8=AF=AF=E6=8B=92?=
=?UTF-8?q?=E7=BB=9D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Nginx 使用原始 Host 和端口转发,不修改后端跨站防护。补充无 Fetch Metadata 的 LAN/Tailscale 同源和异源、异端口、转发头伪造回归。
验证:配置回归先因丢失端口失败后通过;HTTP竞态、真实隔离Nginx正反例及完整make verify均通过。部署前真实入口无Metadata为403,同源Metadata对照可过;源库及人工复核无写入。
---
CHANGELOG.md | 2 +
deploy/nginx.conf | 4 +-
internal/httpapi/qa_proxy_authority_test.go | 62 +++++++++++++++++++++
3 files changed, 66 insertions(+), 2 deletions(-)
create mode 100644 internal/httpapi/qa_proxy_authority_test.go
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3539a56..efafebb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -33,6 +33,8 @@
### Fixed
+- 修复通过带端口的 HTTP 地址访问问答运营时,正常同源操作被误报“拒绝跨站配置请求”:网页代理保留原始 Host 及端口,使缺少 Fetch Metadata 的浏览器也能正确执行 Origin 校验。保留后端跨站、异端口、伪造转发头与缺失操作意图的拒绝保护。
+
- **登记钉钉知识库失败(HTTP 409 `space_registration_conflict`)的真实原因与修复**:`source_connections.name` 有唯一约束,而早期路径登记的钉钉来源(`base_url` 为空、id 与 dws 现在推导的确定性 id 不同)被**归档后仍占着名字槽位** ⇒ 重新登记时 INSERT 撞唯一约束;处理器又把**所有**存储层错误都翻译成同一个 409,真实原因被吞掉(线上只能看到一个无细节的错误码)。现在:① 同名来源**已归档**时,把它改名腾位(`…(已下架 · <短ID>)`,归档行不显示、数据与审计一行不动);② 同名来源**仍在使用**时返回 `space_name_conflict` + 可行动提示(先「去掉来源」);③ 同一登记键指向别的空间且该行仍在用时返回 `space_identity_conflict`(已归档的行则允许就地改写 —— 这就是"去掉后再用 dws 重新获取");④ 其余内部故障改回 **500** `space_registration_failed`,不再伪装成冲突;前端优先显示后端 `hint`,并为这两个新码补了中文说明。
- 前端入口与静态资源的缓存语义("新功能看起来没上线"与"页面偶尔裸奔/空白"的根因):
diff --git a/deploy/nginx.conf b/deploy/nginx.conf
index d7697b3..ef165e1 100644
--- a/deploy/nginx.conf
+++ b/deploy/nginx.conf
@@ -14,7 +14,7 @@ server {
set $api_upstream http://api:8080;
proxy_pass $api_upstream;
proxy_http_version 1.1;
- proxy_set_header Host $host;
+ proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
@@ -22,7 +22,7 @@ server {
location = /health {
set $health_upstream http://api:8080;
proxy_pass $health_upstream/health;
- proxy_set_header Host $host;
+ proxy_set_header Host $http_host;
}
# 带内容哈希的构建产物:可以长期缓存(换版本必然换文件名);旧哈希文件已被新构建替换
diff --git a/internal/httpapi/qa_proxy_authority_test.go b/internal/httpapi/qa_proxy_authority_test.go
new file mode 100644
index 0000000..332bb1a
--- /dev/null
+++ b/internal/httpapi/qa_proxy_authority_test.go
@@ -0,0 +1,62 @@
+package httpapi
+
+import (
+ "net/http/httptest"
+ "os"
+ "regexp"
+ "testing"
+)
+
+// HTTP LAN/tailnet origins may omit Fetch Metadata. nginx must preserve the
+// external authority including its port so Origin can be checked without it.
+func TestQAProxyPreservesBrowserAuthority(t *testing.T) {
+ config, err := os.ReadFile("../../deploy/nginx.conf")
+ if err != nil {
+ t.Fatal(err)
+ }
+ hosts := regexp.MustCompile(`(?m)^\s*proxy_set_header\s+Host\s+([^;]+);`).FindAllStringSubmatch(string(config), -1)
+ if len(hosts) < 2 {
+ t.Fatal("API and health proxy Host directives must both be explicit")
+ }
+ for _, host := range hosts {
+ if host[1] != "$http_host" {
+ t.Fatalf("proxy drops browser authority/port: got %q, want $http_host", host[1])
+ }
+ }
+}
+
+func TestQAIntentWithoutFetchMetadataChecksExactAuthority(t *testing.T) {
+ for _, tc := range []struct {
+ name, host, origin, forwarded, site, intent string
+ allowed bool
+ }{
+ {"LAN same authority", "192.168.50.134:8088", "http://192.168.50.134:8088", "", "", "qa-quality", true},
+ {"tailnet same authority", "100.92.49.78:8088", "http://100.92.49.78:8088", "", "", "qa-quality", true},
+ {"proxy stripped port", "192.168.50.134", "http://192.168.50.134:8088", "", "", "qa-quality", false},
+ {"foreign origin", "192.168.50.134:8088", "http://foreign.invalid:8088", "", "", "qa-quality", false},
+ {"different port", "192.168.50.134:8088", "http://192.168.50.134:8089", "", "", "qa-quality", false},
+ {"forwarded header cannot grant", "192.168.50.134:8088", "http://foreign.invalid:8088", "foreign.invalid:8088", "", "qa-quality", false},
+ {"opaque origin", "192.168.50.134:8088", "null", "", "", "qa-quality", false},
+ {"explicit cross site", "192.168.50.134:8088", "http://192.168.50.134:8088", "", "cross-site", "qa-quality", false},
+ {"missing intent", "192.168.50.134:8088", "http://192.168.50.134:8088", "", "", "", false},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ req := httptest.NewRequest("POST", "http://"+tc.host+"/api/v1/qa-ops/quality/query", nil)
+ req.Header.Set("Origin", tc.origin)
+ req.Header.Set("X-Governance-Action", tc.intent)
+ if tc.forwarded != "" {
+ req.Header.Set("X-Forwarded-Host", tc.forwarded)
+ }
+ if tc.site != "" {
+ req.Header.Set("Sec-Fetch-Site", tc.site)
+ }
+ rec := httptest.NewRecorder()
+ if got := authorizeQAIntent(rec, req, "qa-quality"); got != tc.allowed {
+ t.Fatalf("authorized=%v want %v, HTTP=%d", got, tc.allowed, rec.Code)
+ }
+ if !tc.allowed && rec.Code != 403 {
+ t.Fatalf("rejected authority should be 403, got %d", rec.Code)
+ }
+ })
+ }
+}
--
2.52.0
From 3566f208e0e15fdec2cc98c29f93c46f5f7c91ca Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Sun, 18 Oct 2026 16:10:24 +0800
Subject: [PATCH 11/14] =?UTF-8?q?feat(qa-ops):=20=E5=A2=9E=E5=8A=A0?=
=?UTF-8?q?=E5=8C=97=E4=BA=AC=E6=97=B6=E9=97=B4=E8=87=AA=E7=84=B6=E5=91=A8?=
=?UTF-8?q?=E5=B9=B4=E4=BB=BD=E4=B8=8E=E5=91=A8=E6=AC=A1=E7=AD=9B=E9=80=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
按确认口径展示周次及起止日期,处理跨年、52/53周和本周截至当前。保留自定义时间及查询操作,固定UTC+8边界,不改后端源查询。
验证:目标日期、非法53周、北京时间解析、本周截止及渲染回归均先红后绿;前端266通过,完整make verify成功;洛杉矶时区真实浏览器核对查询UTC边界、切年、自定义和390px布局通过,JS异常0。
---
CHANGELOG.md | 2 ++
web/src/QAOperations.tsx | 44 +++++++++++++++--------
web/src/QAWeekPicker.test.tsx | 23 ++++++++++++
web/src/QAWeekPicker.tsx | 52 +++++++++++++++++++++++++++
web/src/qaOps.css | 22 +++++++++++-
web/src/qaWeeks.test.ts | 57 +++++++++++++++++++++++++++++
web/src/qaWeeks.ts | 67 +++++++++++++++++++++++++++++++++++
7 files changed, 251 insertions(+), 16 deletions(-)
create mode 100644 web/src/QAWeekPicker.test.tsx
create mode 100644 web/src/QAWeekPicker.tsx
create mode 100644 web/src/qaWeeks.test.ts
create mode 100644 web/src/qaWeeks.ts
diff --git a/CHANGELOG.md b/CHANGELOG.md
index efafebb..a32ce9b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,8 @@
### Added
+- 问答记录新增年份与自然周选择,周次展示起止日期,支持跨年及每年实际周数;按北京时间周一至周日填入查询范围,默认本周且仅查询截至当前的数据。保留自定义时间与原查询按钮,浏览器时区不改变查询边界。
+
- 问答运营按已确认口径显示知识覆盖率、回答正确率及原始分子/分母、排除数量与构成。使用完整筛选范围和当前有效人工优先结论,精确规则命中的未覆盖可进入覆盖分母;部分覆盖不算完全覆盖,待确认/未评估/失效/不计入按对应指标排除,零分母显示“暂无可计算数据”。返回独立规则版本,AI 模型与绩效范围仍未接入。
- 问答详情支持治理侧人工复核及不可变审计:覆盖、正确性、产品分类、问题类型、根因与理由由管理员明确填写,操作人取登录身份;保存后独立读回复核历史。保留源端判断和自动规则,输入变化使旧人工结论失效,已观测的内容回退不自动恢复旧结论;并发修改冲突、重复请求不重复留档。
diff --git a/web/src/QAOperations.tsx b/web/src/QAOperations.tsx
index 5dce526..7118e61 100644
--- a/web/src/QAOperations.tsx
+++ b/web/src/QAOperations.tsx
@@ -10,6 +10,8 @@ import { QAMonthly } from './QAMonthly'
import { QAQualityEditor, QAQualityCounts } from './QAQuality'
import { qualityLabels } from './qaQuality'
import { usageLabels } from './qaUsage'
+import { QAWeekPicker } from './QAWeekPicker'
+import { currentQAWeek, qaDateTimeToISO, qaWeekQueryRange } from './qaWeeks'
interface ViewProps {
onQualitySaved?: (record: QARecord) => void
@@ -290,12 +292,10 @@ export function QAOperationsView(props: ViewProps) {
)
}
-function localInput(value: Date): string {
- return new Date(value.getTime() - value.getTimezoneOffset() * 60_000).toISOString().slice(0, 16)
-}
function initialDraft() {
- const end = new Date()
- return { start: localInput(new Date(end.getTime() - 7 * 24 * 3600_000)), end: localInput(end), keyword: '' }
+ const current = currentQAWeek()
+ const { year, week, start, end } = qaWeekQueryRange(current.year, current.week)
+ return { year, week: week as number | null, start, end, keyword: '' }
}
export function QAOperations() {
@@ -322,8 +322,8 @@ export function QAOperations() {
useEffect(() => {
if (!canRead || query) return
setQuery({
- start: new Date(draft.start).toISOString(),
- end: new Date(draft.end).toISOString(),
+ start: qaDateTimeToISO(draft.start),
+ end: qaDateTimeToISO(draft.end),
keyword: draft.keyword,
cursor: '',
})
@@ -377,10 +377,11 @@ export function QAOperations() {
const submit = (event: FormEvent) => {
event.preventDefault()
try {
- const start = new Date(draft.start),
- end = new Date(draft.end)
- if (!(start < end)) throw new Error('开始时间必须早于结束时间')
- setQuery({ start: start.toISOString(), end: end.toISOString(), keyword: draft.keyword, cursor: '' })
+ const start = qaDateTimeToISO(draft.start),
+ end = qaDateTimeToISO(draft.end)
+ if (!(Date.parse(start) < Date.parse(end))) throw new Error('开始时间必须早于结束时间')
+ if (Date.parse(start) >= Date.now()) throw new Error('所选周或时间尚未开始,请选择已开始的时间范围')
+ setQuery({ start, end, keyword: draft.keyword, cursor: '' })
} catch (reason) {
setError(reason instanceof Error ? reason.message : '时间格式无效')
}
@@ -470,22 +471,35 @@ export function QAOperations() {
) : (
<>