feat(qaops): 接入独立只读问答查询与治理覆盖复检

This commit is contained in:
姚章浩
2026-10-17 09:04:19 +08:00
parent c1d49adb62
commit fd04bf7886
42 changed files with 4479 additions and 5 deletions
+12
View File
@@ -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
+3 -1
View File
@@ -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 成功不等于已部署。
+54 -1
View File
@@ -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": [
+11
View File
@@ -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,
+21
View File
@@ -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
}
+18
View File
@@ -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")
}
}
+159
View File
@@ -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
}
+104
View File
@@ -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
}
+26
View File
@@ -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")
}
}
}
+309
View File
@@ -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)
}
}
+107
View File
@@ -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
}
+125
View File
@@ -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
}
+101
View File
@@ -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("放行时必须返回库名")
}
})
}
}
+225
View File
@@ -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
}
+163
View File
@@ -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
}
+243
View File
@@ -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
}
@@ -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)
}
}
@@ -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)
}
+307
View File
@@ -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
}
@@ -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)
}
}
+71
View File
@@ -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
}
@@ -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)
}
}
+37
View File
@@ -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")
}
}
}
+85
View File
@@ -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
}
+66
View File
@@ -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)
}
}
+133
View File
@@ -0,0 +1,133 @@
package dobotaiops
import (
"context"
"fmt"
"io"
"net"
"os"
"os/exec"
"strings"
"sync"
"syscall"
"time"
)
// SSHDialer 复用既有的 SSH direct-tcpip 能力:`ssh -W <host>:<port> <target>` ——
// 由 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
}
+104
View File
@@ -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 子进程没有被回收")
}
}
+87
View File
@@ -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
}
+1 -1
View File
@@ -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 {
+143
View File
@@ -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})
}
+87
View File
@@ -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")
}
}
+14
View File
@@ -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)
}
}
}
+28
View File
@@ -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)
}
}
+13
View File
@@ -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"})
})
+40
View File
@@ -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)"
+4
View File
@@ -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() {
<DocumentWorkbench mode="attention" connections={connectionPage.items} />
) : workspace.activeTab === 'versions' ? (
<VersionHistory />
) : workspace.activeTab === 'qaops' ? (
<QAOperations />
) : (
<ModulePage
moduleId={workspace.activeTab}
+83
View File
@@ -0,0 +1,83 @@
import { renderToStaticMarkup } from 'react-dom/server'
import { describe, expect, it, vi } from 'vitest'
import { QAOperationsView } from './QAOperations'
import type { QARecord, QARecordPage } from './qaOps'
import { restoreWorkspace } from './workspace'
const item: QARecord = {
id: 'fixture',
status: 'succeeded',
question: '<script>not executable</script>',
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(<QAOperationsView {...props} />)
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('<th>部门</th>')
expect(html).not.toContain('<th>产品分类</th>')
expect(html).not.toContain('<script>not executable</script>')
})
it('distinguishes an unavailable source from a successful empty query', () => {
const html = renderToStaticMarkup(<QAOperationsView {...props} page={null} error="只读源不可用" />)
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(<QAOperationsView {...props} detail={item} />)
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')
})
})
+428
View File
@@ -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<string, string> = {
database_temp_enabled: '数据库仍允许临时对象:未视为完全只读验收通过',
database_transport_unencrypted: '数据库连接未启用 TLS:上线前须完成传输安全审核',
}
const stamp = (value: string) => new Date(value).toLocaleString('zh-CN', { hour12: false })
const statusLabels: Record<string, string> = {
succeeded: '成功',
failed: '失败',
running: '处理中',
cancelled: '已取消',
}
const sourceCoverageLabels: Record<string, string> = { 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 (
<section className="qa-ops-results" aria-label="问答记录">
<div className="qa-ops-result-bar">
<span>
{props.loading ? '正在读取…' : page ? `共 ${page.total} 条 · 已显示 ${page.items.length} 条` : '尚未读取问答'}
</span>
<span className="qa-ops-source">
DobotAI 2.0 / 钉钉 · 独立只读连接{props.status ? ` · ${stateLabels[props.status.state]}` : ''}
</span>
</div>
{props.status?.warnings.map((warning) => (
<p className="qa-ops-warning" key={warning}>
{warningLabels[warning] ?? '数据源有待审核的安全告警'}
</p>
))}
{props.error ? (
<div className="error-banner" role="alert">
{props.error}{' '}
<button type="button" onClick={props.onRetry} disabled={props.loading}>
重试读取
</button>
</div>
) : null}
{page && page.items.length > 0 ? (
<div className="qa-ops-table-scroll" aria-label="问答表格滚动区" tabIndex={0}>
<table className="qa-ops-table">
<thead>
<tr>
{columns.map(({ key, label }) => (
<th key={key}>{label}</th>
))}
<th>操作</th>
</tr>
</thead>
<tbody>
{page.items.map((item) => (
<tr key={item.id}>
{columns.map(({ key }) => (
<td
key={key}
className={
key === 'answer' || key === 'question' || key === 'question_chinese' ? 'qa-ops-text-cell' : ''
}
>
<span
className={
key === 'coverage' && item.coverage.verdict === 'uncovered' ? 'qa-ops-uncovered' : ''
}
>
{qaCellValue(item, key) ?? '—'}
</span>
</td>
))}
<td>
<button
type="button"
onClick={() => props.onSelect(item.id)}
aria-label={`查看问答 ${item.id} 的详情`}
>
详情
</button>
</td>
</tr>
))}
</tbody>
</table>
</div>
) : page && !props.loading && !props.error ? (
<p className="qa-ops-empty">没有符合条件的问答,请调整时间范围或关键词。</p>
) : null}
{page ? (
<footer className="qa-ops-page-bar">
<span>本次读取:{stamp(page.as_of)} · 空列按整个筛选结果隐藏</span>
{page.has_more ? (
<button type="button" onClick={props.onLoadMore} disabled={props.loading}>
{props.loading ? '读取中…' : '加载更多'}
</button>
) : page.items.length > 0 ? (
<span>已显示全部</span>
) : null}
</footer>
) : null}
{showDrawer ? (
<>
<button
className="qa-ops-backdrop"
type="button"
onClick={props.onCloseDetail}
aria-label="关闭问答详情遮罩"
/>
<aside
className="qa-ops-drawer"
role="dialog"
aria-modal="true"
aria-label="问答详情"
onKeyDown={(event) => {
if (event.key === 'Escape') props.onCloseDetail()
if (event.key === 'Tab') {
const buttons = Array.from(
event.currentTarget.querySelectorAll<HTMLElement>('button, a[href], input, [tabindex="0"]')
)
const first = buttons[0],
last = buttons[buttons.length - 1]
if (event.shiftKey && document.activeElement === first) {
event.preventDefault()
last?.focus()
}
if (!event.shiftKey && document.activeElement === last) {
event.preventDefault()
first?.focus()
}
}
}}
>
<header>
<h3>问答详情</h3>
<button type="button" autoFocus onClick={props.onCloseDetail}>
关闭详情
</button>
</header>
{props.detailLoading ? <p role="status">正在读取完整问答…</p> : null}
{props.detailError ? (
<p className="error-banner" role="alert">
{props.detailError}
</p>
) : null}
{detail ? (
<div className="qa-ops-detail-content">
<dl className="qa-ops-detail-meta">
<dt>提问时间</dt>
<dd>
{stamp(detail.asked_at)}
{detail.time_source === 'turn.created_at' ? '(问答时间回退,入站消息缺失)' : ''}
</dd>
<dt>提问人</dt>
<dd>{detail.asker || '未关联'}</dd>
<dt>问答状态</dt>
<dd>{statusLabels[detail.status] ?? detail.status}</dd>
<dt>流程触发人员信息</dt>
<dd>{detail.trigger_person || '未记录'}</dd>
</dl>
<h4>原始问题</h4>
<div className="qa-ops-full-text">{detail.question || '无文本问题'}</div>
<h4>AI答案</h4>
<div className="qa-ops-full-text">{detail.answer || '尚无答案;不默认判覆盖或正确'}</div>
<h4>治理侧覆盖复检</h4>
<p>
{detail.coverage.verdict === 'uncovered'
? '未覆盖:答案包含“暂无已发布”,引用不能抵消这一结果。'
: '待评估:未命中“暂无已发布”不代表已覆盖。'}
</p>
<p className="qa-ops-muted">规则:{detail.coverage.rule_version}</p>
<h4>源端覆盖(仅对照)</h4>
<p>
{sourceCoverageLabels[detail.source_coverage.verdict] ?? '未记录'} ·{' '}
{detail.source_coverage.evaluator_version || '无版本'}
</p>
<p className="qa-ops-muted">{detail.source_coverage.reason_code || '未记录判定原因'}</p>
<h4>用户反馈</h4>
<p>
提问人:
{detail.feedback.asker_value === 'up'
? '点赞'
: detail.feedback.asker_value === 'down'
? '点踩'
: '无反馈'}
;全部反馈:赞 {detail.feedback.up} / 踩 {detail.feedback.down}
</p>
<h4>引用知识</h4>
<pre>{JSON.stringify(detail.references, null, 2)}</pre>
<details>
<summary>问题媒体记录</summary>
<pre>{JSON.stringify(detail.media, null, 2)}</pre>
</details>
</div>
) : null}
</aside>
</>
) : null}
</section>
)
}
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<QAQuery | null>(null)
const [page, setPage] = useState<QARecordPage | null>(null)
const [status, setStatus] = useState<QAStatus | null>(null)
const [error, setError] = useState<string | null>(null)
const [loading, setLoading] = useState(false)
const [revision, setRevision] = useState(0)
const [detail, setDetail] = useState<QARecord | null>(null)
const [detailLoading, setDetailLoading] = useState(false)
const [detailError, setDetailError] = useState<string | null>(null)
const generation = useRef(0)
const detailRequest = useRef<AbortController | null>(null)
const moreRequest = useRef<AbortController | null>(null)
const returnFocus = useRef<HTMLElement | null>(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 (
<section className="qa-ops" aria-label="问答运营">
<header className="qa-ops-header">
<h2>
问答运营 <span>/ 问答记录</span>
</h2>
<p>真实问答只读查询;原始记录、源端判断与治理复检分开保留。</p>
</header>
{!canRead ? (
<p className="error-banner" role="alert">
尚未配置员工问答可见范围,当前仅管理员可访问。
</p>
) : (
<>
<form className="qa-ops-query" onSubmit={submit}>
<label>
开始时间
<input
type="datetime-local"
required
value={draft.start}
onChange={(event) => setDraft({ ...draft, start: event.target.value })}
/>
</label>
<label>
结束时间(不含)
<input
type="datetime-local"
required
value={draft.end}
onChange={(event) => setDraft({ ...draft, end: event.target.value })}
/>
</label>
<label className="qa-ops-keyword">
关键词
<input
type="search"
maxLength={200}
placeholder="检索原始问题"
value={draft.keyword}
onChange={(event) => setDraft({ ...draft, keyword: event.target.value })}
/>
</label>
<button type="submit" disabled={loading}>
查询
</button>
</form>
<p className="qa-ops-slice-note">
当前切片:问答查询与覆盖复检。外语翻译、AI评估及人员映射尚未接入;空值不默认填“否”。
</p>
<QAOperationsView
page={page}
status={status}
error={error}
loading={loading}
detail={detail}
detailLoading={detailLoading}
detailError={detailError}
onSelect={(id) => void select(id)}
onCloseDetail={close}
onLoadMore={() => void loadMore()}
onRetry={() => setRevision((value) => value + 1)}
/>
</>
)}
</section>
)
}
+267
View File
@@ -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;
}
}
+66
View File
@@ -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('只读权限校验未通过')
})
})
+197
View File
@@ -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<string, unknown> => {
if (!value || typeof value !== 'object' || Array.isArray(value)) return invalid()
return value as Record<string, unknown>
}
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<string>(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<unknown> {
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<string, unknown>) : 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<QARecordPage> {
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<QARecord> {
return parseQARecord(await getPayload(`/api/v1/qa-ops/records/${encodeURIComponent(id)}`, signal))
}
export async function fetchQAStatus(signal?: AbortSignal): Promise<QAStatus> {
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
}
+2 -2
View File
@@ -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<ModuleId>(['dashboard', 'tasks', 'releases', 'settings'])
const moduleIds = new Set<ModuleId>(['dashboard', 'tasks', 'releases', 'settings', 'qaops'])
export const initialWorkspace: WorkspaceState = {
openTabs: ['dashboard'],