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 }) => ( + + ))} + + + + + {page.items.map((item) => ( + + {columns.map(({ key }) => ( + + ))} + + + ))} + +
{label}操作
+ + {qaCellValue(item, key) ?? '—'} + + + +
+
+ ) : page && !props.loading && !props.error ? ( +

没有符合条件的问答,请调整时间范围或关键词。

+ ) : null} + {page ? ( +
+ 本次读取:{stamp(page.as_of)} · 空列按整个筛选结果隐藏 + {page.has_more ? ( + + ) : page.items.length > 0 ? ( + 已显示全部 + ) : null} +
+ ) : null} + {showDrawer ? ( + <> + + + {props.detailLoading ?

正在读取完整问答…

: null} + {props.detailError ? ( +

+ {props.detailError} +

+ ) : null} + {detail ? ( +
+
+
提问时间
+
+ {stamp(detail.asked_at)} + {detail.time_source === 'turn.created_at' ? '(问答时间回退,入站消息缺失)' : ''} +
+
提问人
+
{detail.asker || '未关联'}
+
问答状态
+
{statusLabels[detail.status] ?? detail.status}
+
流程触发人员信息
+
{detail.trigger_person || '未记录'}
+
+

原始问题

+
{detail.question || '无文本问题'}
+

AI答案

+
{detail.answer || '尚无答案;不默认判覆盖或正确'}
+

治理侧覆盖复检

+

+ {detail.coverage.verdict === 'uncovered' + ? '未覆盖:答案包含“暂无已发布”,引用不能抵消这一结果。' + : '待评估:未命中“暂无已发布”不代表已覆盖。'} +

+

规则:{detail.coverage.rule_version}

+

源端覆盖(仅对照)

+

+ {sourceCoverageLabels[detail.source_coverage.verdict] ?? '未记录'} ·{' '} + {detail.source_coverage.evaluator_version || '无版本'} +

+

{detail.source_coverage.reason_code || '未记录判定原因'}

+

用户反馈

+

+ 提问人: + {detail.feedback.asker_value === 'up' + ? '点赞' + : detail.feedback.asker_value === 'down' + ? '点踩' + : '无反馈'} + ;全部反馈:赞 {detail.feedback.up} / 踩 {detail.feedback.down} +

+

引用知识

+
{JSON.stringify(detail.references, null, 2)}
+
+ 问题媒体记录 +
{JSON.stringify(detail.media, null, 2)}
+
+
+ ) : null} + + + ) : 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'],