Ai-Helper-Detail on GzzhM

AutoApprove

Mon, 10 Aug 2026 00:00:00 +0000

最终实现

能够自动创建对应的请假审批

整体流程如下

注册 ApproveHandle 这里由上层 Agent 判断调度
ApproveHandle 支持 ApproveAdd 和 ApproveFind 分别对应创建审批和查找审批

细节

ApproveAdd

这里的逻辑很简单

根据 Agent 传递的 input 解析出对应的参数
根据参数build对应的 Service实现
然后透传用户原始信息去 Create


// Call 解析审批类型与原文，并创建审批
func (a *ApprovalAdd) Call(ctx context.Context, input string) (string, error) {
	// ... 
	out, err := a.outputparser.Parse(input)
	if err != nil {
		return "", err
	}
	data := out.(map[string]any)

	var approvalType float64
	if t, ok := data["type"]; ok {
		switch v := t.(type) {
		case float64:
			approvalType = v
		case int:
			approvalType = float64(v)
		}
	}
	userInput := input
	if v, ok := data["input"].(string); ok && v != "" {
		userInput = v
	}

	// 保留用户原文，同时补充工时上下文供二级抽取使用
	enriched := fmt.Sprintf("%s\n%s", userInput, workHoursHint)

	ap, err := approval.NewApproval(a.svc, model.ApprovalType(approvalType))
	if err != nil {
		return "", err
	}

	id, err := ap.Create(ctx, enriched)
	if err != nil {
		return "", err
	}

	return Success + "\n created approval id : " + id, nil
}

我们可以看到一个 Create实现，这里由额外进行了一次LLM操作，根据透传的 input 进行额外的解析

func (m *GoOut) Create(ctx context.Context, input string) (string, error) {
	out, err := chains.Predict(ctx, m.c, map[string]any{
		langchain.Input: input,
	}, chains.WithCallback(m.svc.Callbacks))
	if err != nil {
		return "", xerr.WithMessage(err, "chains.Predict : "+input)
	}

	v, err := m.outPutParser.Parse(out)
	if err != nil {
		return "", xerr.WithMessage(err, "m.outPutParser.Parse")
	}

	var data domain.GoOut
	if err := decodeJSON(v, &data); err != nil {
		return "", xerr.WithMessage(err, "decode goOut")
	}

	return createApproval(ctx, m.svc, domain.Approval{
		Type:  int(model.GoOutApproval),
		GoOut: &data,
	})
}

ApproveFind

Approve Find 同样内容更加简单

func (a *ApprovalFind) Call(ctx context.Context, input string) (string, error) {
	if a.Callback != nil {
		a.Callback.HandleText(ctx, "approval find start input : "+input)
	}

	out, err := a.outputparser.Parse(input)
	if err != nil {
		return "", err
	}

	data := out.(map[string]any)
	if data == nil {
		data = make(map[string]any)
	}

	// List API 使用当前登录用户；type 为「我提交/我审核」
	listType := float64(model.ApprovalSubmit)
	if t, ok := data["type"].(float64); ok && t > 0 {
		listType = t
	}
	data["type"] = int(listType)
	if data["count"] == nil {
		data["count"] = 10
	}
	if data["page"] == nil {
		data["page"] = 1
	}

	res, err := curl.GetRequest(token.GetTokenStr(ctx), a.svc.Config.Host+"/v1/approval/list", data)
	if err != nil {
		return "", err
	}

	if a.Callback != nil {
		a.Callback.HandleText(ctx, "approval find end data : "+string(res))
	}

	return ResParser(res, domain.ApprovalFind, nil)
}

SummaryChat

Mon, 10 Aug 2026 00:00:00 +0000

最终实现

用户可以通过 @机器人, 实现总结自己所发的内容

整体流程如下

前端发起调用传入 Time Range
后端获取对应的群聊消息。整理聚合给 LLM
LLM 处理之后进行输出

细节

创建的时候制定一下 templatePrompt ，然后自己开辟一条chain

func NewChatLogHandle(svc *svc.ServiceContext) *ChatLogHandle {
	return &ChatLogHandle{
		svc: svc,
		chains: chains.NewLLMChain(svc.LLMs, prompts.NewPromptTemplate(
			_defaultChatLogPrompts, []string{"input"},
		)),
	}
}

func (c *ChatLogHandle) Chains() chains.Chain {
	return chains.NewTransform(c.transform, nil, nil)
}

去数据库获取对应的MSG 然后整合给LLM 进行输出

func (c *ChatLogHandle) transform(ctx context.Context, inputs map[string]any,
	opts ...chains.ChainCallOption) (map[string]any, error) {

//...

	msgs, err := c.chatLog(ctx, cid, startTime, endTime)
	if err != nil {
		return nil, err
	}
//...
	res, err := chains.Call(ctx, c.chains, map[string]any{
		"input": msgs,
	}, opts...)
	if err != nil {
		return nil, err
	}

	text, ok := res[langchain.OutPut].(string)
	if !ok {
		return nil, chains.ErrInvalidOutputValues
	}
//...
	if err != nil {
		return nil, err
	}
	return map[string]any{
		langchain.OutPut: string(b),
	}, nil
}

Rag-Knowledge

Sun, 09 Aug 2026 00:00:00 +0000

最终实现

我们能够通过前端上传 pdf 进行知识库的更新
我们可以通过自然语言询问文章里面的内容。并且更新对应的内容
同样我们可以重新上传文章进行更新

细节

大体框架

我们提供了一个 KnowLedgeHandle 其中 . 介绍我们这个 Handle 是做什么内容的

Name : knowledge
Desc : This is the company's knowledge base.
Use for: summarizing uploaded documents, retrieving knowledge content, answering questions about employee manuals, attendance, leave, approval process, and other office policies.
Also use for updating/ingesting the knowledge base from uploaded files, and for revising/correcting knowledge facts (e.g. 更改工作时间).
Prefer this destination whenever the user mentions 知识库 / 文档 / 手册 / 总结 / 更改手册内容

这个Handle 对应3个 Tool

KnowledgeQA 用于进行 RAG 回答问题
KnowledgePatch 部分更新 vector 中的内容
KnowledgeUpdate 更新全量的文章

knowledgeQa

我们看一下 knowledgeQa 这里做的内容

获取 Store 也就是获取我们的 Redis CLi
后去其中的 Content 内容。并且存入到 qa 里面。这里使用了 RAG 相似度匹配
然后去询问 AI

整个流程大致这样，相似度匹配也是框架帮我们做的事

func (k *KnowledgeRetrievalQA) Call(ctx context.Context, input string) (string, error) {
	var err error
	if k.qa == nil {
		k.store, err = getKnowledgeStore(ctx, k.svc)
		if err != nil {
			return "", fmt.Errorf("连接知识库向量存储失败(请确认 Redis Stack 已启动): %v", err)
		}

		// topK 取多块，目录/全文结构类问题才有足够上下文
		k.qa = chains.NewRetrievalQAFromLLM(k.svc.LLMs, vectorstores.ToRetriever(k.store, 5))
	}

	res, err := chains.Predict(ctx, k.qa, map[string]any{
		"query": input,
	})
	if err != nil {
		return "", err
	}

	return `请基于检索资料回答用户。写作要求：
1. 直接输出当前有效规定，语气像员工手册正文，条理清晰。
2. 若资料里同一主题有多条说法，只保留最新有效内容合并进答案；不要对比新旧，不要出现「修订」「原规定」「冲突」「优先于」「最新版本」等词。
3. 用户问某类政策时，尽量给出完整条目，而不是只讲变更点。
检索资料：
` + res, nil
}

KnowledgeUPdate

KnowledgeUPdate 就好像是一个 Python 脚本，可以看作想是一个skills

不过这里还是有几点需要注意的

Param . 我们可以看到 Update 在操作之前解析了参数 path,name,time . 这几个参数从哪里来？
我们上传完文件之后会传入到放入到 memory 中

func (l *chat) File(ctx context.Context, files []*domain.FileResp) (err error) {
	// ... 
	err = l.memory.SaveContext(ctx, map[string]any{ // 将文件信息保存到记忆机制中
		langchain.OutPut: string(b), // langchain.OutPut: `[{"Path":"upload/xxx.pdf","Name":"...","Time":"..."}]`
	}, map[string]any{
		langchain.OutPut: "uploaded files", // AI 的回复内容
	})
	// ...
}

然后框架会自动把 memory 挂载到 history 中。从而模型就能够看到这部分memory

1
2

newValues := memory.LoadMemoryVariables(...)  // → {"history": "Human: [{Path,Name,Time}]\nAI: uploaded files\n..."}
合并进 fullValues

通过 PDFprocess 解析pdf文件然后通过 redis 重新更新 Vector

func NewKnowledgeUpdate(svc *svc.ServiceContext) *KnowledgeUpdate {
	return &KnowledgeUpdate{
		//. .. 
		outPutParser: outputparserx.NewStructured([]outputparserx.ResponseSchema{
			{
				Name:        "path",
				Description: "the path to file",
			}, {
				Name:        "name",
				Description: "the name to file",
			}, {
				Name:        "time",
				Description: "file update time",
			},
		}),
	}
}

func (k *KnowledgeUpdate) Call(ctx context.Context, input string) (string, error) {
	 // ... 
	var data any
	data, err := k.outPutParser.Parse(input)
	// ... 

	file := data.(map[string]any)
	filePath := resolveKnowledgeFilePath(fmt.Sprintf("%v", file["path"]))

	if _, err := os.Stat(filePath); err != nil {
		return "", fmt.Errorf("文件不存在: %s", filePath)
	}

	pdfProcessor := NewPDFProcessor()
	chunkedDocuments, err := pdfProcessor.LoadAndSplitPDF(ctx, filePath, 800, 100)
	if err != nil {
		return "", fmt.Errorf("PDF处理失败: %v", err)
	}
	if len(chunkedDocuments) == 0 {
		return "", fmt.Errorf("PDF处理失败: 未生成任何文档块")
	}

	// ... 
	if _, err = k.store.AddDocuments(ctx, chunkedDocuments); err != nil {
		return "", fmt.Errorf("写入知识库失败: %v", err)
	}

	return fmt.Sprintf("%s：文件 %s 已入库，共 %d 个文档块（已覆盖同内容旧数据）。若用户还要求总结或问答文档内容，请继续调用 knowledge_retrieval_qa；若仅要求更新知识库，再给出 Final Answer。",
		knowledgeUpdateSuccessPrefix, filepath.Base(filePath), len(chunkedDocuments)), nil
}

遗留问题

memory 的实现
多个Handle共用memory
- 方案： chatid = uid + busienss_type 根据业务进行区分

RouterChain

Sun, 09 Aug 2026 00:00:00 +0000

最终实现

在聊天窗口让 AI 创建一个待办。给出具体信息之后会创建对应的待办信息

整体流程如下

前端调用 /call 接口传入自然语言信息
后端拼接已经注册的路由Handle + input 去查找然后返回对应的 key

给你一份路由清单，请根据用户输入选出一个最合适的，
如果都不合适就返回Default:

intput : req -front - xxxx

并且根据 xxx 格式返回

查找到对应的 Handle 然后去访问对应 Handle 支持的 Tool
使用 langchain.OneShotAgent 再次询问AI 应该访问哪一个 Tool
调用Tool 发起请求。返回响应

细节

第一次 LLM 拼接 prompts

我们在 NewRouter 的时候就把所有已经实现的 Handler 写进去 . 这里会根据 handle 进行整合 opt

func NewRouter(llm llms.Model, handler []Handler, opts ...Option) *Router {
	opt := executorDefaultOptions(handler)
	for _, o := range opts {
		o(&opt)
	}
	// ...
}

Option 会返回一个 prompt . 类型 PromptTemplate

我们可以看到这里会遍历没用过 hander 然后拼接他们的 Name() 和 Descritipn()

type Option func(options *Options)

// executorDefaultOptions 创建默认的路由器配置选项
func executorDefaultOptions(handler []Handler) Options {
	return Options{
		prompt: createPrompt(handler),
		memory: memory.NewSimple(),
	}
}


func createPrompt(handler []Handler) prompts.PromptTemplate {
	return prompts.PromptTemplate{
		Template:       MULTI_PROMPT_ROUTER_TEMPLATE,
		InputVariables: []string{_input},
		TemplateFormat: prompts.TemplateFormatGoTemplate,
		PartialVariables: map[string]any{
			_destinations: handlerDestinations(handler),
			_formatting:   _outputparser.GetFormatInstructions(),
		},
	}
}

这里可以看到 handle 的定义如下 , 和 Tool 一样自带说明书

func NewTodoHandle(svc *svc.ServiceContext) *TodoHandle {
	//...
}

// Name 返回处理器名称，用于路由识别
func (t *TodoHandle) Name() string {
	return "todo"
}

// Description 返回处理器描述，帮助 AI 理解何时使用此处理器
func (t *TodoHandle) Description() string {
	return "suitable for todo processing, such as todo creation, query, modification, deletion, etc"
}

// Chains 返回处理链，使用转换链包装代理输出
func (t *TodoHandle) Chains() chains.Chain {
	return chains.NewTransform(t.transform, nil, nil)
}

寻找Handle进行处理

因为我们在提示词中增加了,格式化返回 . 我们可以从会使用 outputparser 解析对应的 output

我们通过 chains.Call(ctx, r.handlers[next].Chains(), inputs) 调用对应的 Tool

1
2
3

<< FORMATTING >>
Return a markdown code snippet with a JSON object formatted to look like:
{{.formatting}}

func (r *Router) Call(ctx context.Context, inputs map[string]any, options ...chains.ChainCallOption) (map[string]any, error) {
// ... 
	out, err := r.outputparser.Parse(text.(string))
	if err != nil {
		return nil, err
	}

	if r.callbacks != nil {
		r.callbacks.HandleChainEnd(ctx, map[string]any{
			"out": out,
		})
	}

	data := out.(map[string]string)
	next, ok := data[_destinations]
	if !ok || next == Empty || r.handlers[next] == nil {
		if r.emptyHandle != nil {
			return chains.Call(ctx, r.emptyHandle.Chains(), inputs)
		}
		return nil, ErrNotHandles
	}

	return chains.Call(ctx, r.handlers[next].Chains(), inputs)
}

Agents Find tool

我们可以看到 TodoHandle 支持了 todoAdd和 TodoFind 这两个Tool

对于每一个 Tool 都会有格式化输出配置同样也有 Name +Desc 。Tool 的基本定义一个说明书

func NewTodoHandle(svc *svc.ServiceContext) *TodoHandle {
	return &TodoHandle{
		svc: svc,
		// 创建包含待办工具的 AI 代理
		agentChain: agents.NewExecutor(agents.NewOneShotAgent(svc.LLMs, []tools.Tool{
			toolx.NewTodoAdd(svc),  // 待办创建工具
			toolx.NewTodoFind(svc), // 待办查询工具
		})),
	}
}


func NewTodoAdd(svc *svc.ServiceContext) *TodoAdd {
	return &TodoAdd{
		svc:      svc,
		callback: svc.Callbacks,
		// 配置结构化输出解析器，定义待办事项的字段格式
		outputparser: outputparserx.NewStructured([]outputparserx.ResponseSchema{
			{
				Name:        "title",
				Description: "todo title",
			}, {
				Name:        "deadlineAt",
				Description: "calculate the final deadline based on the time information entered by the user and combined with today's time. a Unix time",
				Type:        "int64",
			}, {
				Name:        "desc",
				Description: "todo description",
			}, {
				Name:        "executeIds",
				Description: "list of participating users in the backlog. the data type is a set of string ids. none is empty",
				Type:        "[]string",
			},
		}),
	}
}

// Name 返回工具名称，用于 AI 代理识别
func (t *TodoAdd) Name() string {
	return "todo_add"
}

// Description 返回工具描述和使用说明，包含输出格式指令
func (t *TodoAdd) Description() string {
	template := `
	a todo add interface.
	use when you need to create a todo.
	keep Chinese output.
` + t.outputparser.GetFormatInstructions()

	return template
}

我们看 NewOneShotAgent ，这里也是单独创建了一个 LLM Chain 。并且使用自己的 getMrklPrompt 传入了 tools 用于寻找 tool .方式和我们实现 Router 一样

func NewOneShotAgent(llm llms.Model, tools []tools.Tool, opts ...Option) *OneShotZeroAgent {
	options := mrklDefaultOptions()
	for _, opt := range opts {
		opt(&options)
	}

	return &OneShotZeroAgent{
		Chain: chains.NewLLMChain(
			llm,
			options.getMrklPrompt(tools),
			chains.WithCallback(options.callbacksHandler),
		),
		Tools:            tools,
		OutputKey:        options.outputKey,
		CallbacksHandler: options.callbacksHandler,
	}
}

AI helper 常规开发

Sat, 08 Aug 2026 00:00:00 +0000

鉴权 & 白名单

使用 group 加上 Jwt Parse 实现 Check

func (h *User) InitRegister(engine *gin.Engine) {
	g0 := engine.Group("v1/user")
	g0.POST("/login", h.Login)

	g1 := engine.Group("v1/user", h.svcCtx.Jwt.Handler)
	g1.GET("/:id", h.Info)
	g1.POST("", h.Create)
	g1.PUT("", h.Edit)
	g1.DELETE("/:id", h.Delete)
	g1.GET("/list", h.List)
	g1.POST("/password", h.UpdatePassword)
}

func (m *Jwt) Handler(ctx *gin.Context) {
	r, err := m.tokenParser.ParseWithContext(ctx.Request)
	if err != nil {
		httpx.FailWithErr(ctx, err)
		ctx.Abort()
		return
	}

	ctx.Request = r
	ctx.Next()
}

同样的我们在 Websocket 那边也是使用 JWT 进行鉴权

func (s *Ws) auth(r *http.Request) (uid string, tokenStr string, err error) {
   // 优先从请求头中获取WebSocket认证Token（保持原有功能）
   tok := r.Header.Get("websocket")
//...

   // 解析JWT Token，获取用户身份信息
   claims, tokenStr, err := s.tokenParser.ParseToken(tok)
   if err != nil {
   	return "", "", err
   }
   //...
}

用户模块

支持 Login、Info、Create、Edit、Delete、List、UpdatePassword

这一部分基本上都是 CRUD 并且没有做并发控制。

// User 用户业务逻辑接口
type User interface {
   // Login 用户登录验证
   Login(ctx context.Context, req *domain.LoginReq) (resp *domain.LoginResp, err error)
   // Info 根据ID获取用户信息
   Info(ctx context.Context, req *domain.IdPathReq) (resp *domain.User, err error)
   // Create 创建新用户
   Create(ctx context.Context, req *domain.User) (err error)
   // Edit 更新用户信息
   Edit(ctx context.Context, req *domain.User) (err error)
   // Delete 删除指定用户
   Delete(ctx context.Context, req *domain.IdPathReq) (err error)
   // List 分页查询用户列表
   List(ctx context.Context, req *domain.UserListReq) (resp *domain.UserListResp, err error)
   // UpdatePassword 更新用户密码
   UpdatePassword(ctx context.Context, req *domain.UpdatePasswordReq) (err error)
}

表结构设计

type User struct {
	ID primitive.ObjectID `bson:"_id,omitempty" json:"id,omitempty"`
	// TODO: Fill your own fields

	Name     string `bson:"name" json:"name"`
	Password string `bson:"Password" json:"Password"`
	Status   int    `bson:"status" json:"status"`
	IsAdmin  bool   `bson:"isAdmin" json:"isAdmin"` // 是否为管理员
	UpdateAt int64  `bson:"updateAt" json:"updateAt"`
	CreateAt int64  `bson:"createAt" json:"createAt"`
}

Department

Soa 方法会根据所有的部门构建一个部门树进行展示
- 全量查出所有部门
- 按 ParentPath 分组
- 否则按照父路径放进 groupDep

1
2
3

公司(A) ParentPath=""
  └─ 技术部(B) ParentPath=":A"
       └─ 后端组(C) ParentPath=":A:B"

其他的设计基本上都是 CRUD

type Department interface {
   Soa(ctx context.Context) (resp *domain.DepartmentSoaResp, err error)
   Info(ctx context.Context, req *domain.IdPathReq) (resp *domain.Department, err error)
   Create(ctx context.Context, req *domain.Department) (err error)
   Edit(ctx context.Context, req *domain.Department) (err error)
   Delete(ctx context.Context, req *domain.IdPathReq) (err error)
   SetDepartmentUsers(ctx context.Context, req *domain.SetDepartmentUser) (err error)
   AddDepartmentUser(ctx context.Context, req *domain.AddDepartmentUser) (err error)
   RemoveDepartmentUser(ctx context.Context, req *domain.RemoveDepartmentUser) (err error)
   DepartmentUserInfo(ctx context.Context, req *domain.IdPathReq) (resp *domain.Department, err error)
}

表结构设计

设计一个部门数据表一个部门用户表

type Department struct {
	ID         primitive.ObjectID `bson:"_id,omitempty" json:"id,omitempty"`                // 部门ID
	Name       string             `bson:"name" json:"name"`                                 // 部门名称
	ParentId   string             `bson:"parentId,omitempty" json:"parentId,omitempty"`     // 父部门ID
	ParentPath string             `bson:"parentPath,omitempty" json:"parentPath,omitempty"` // 父部门路径
	Level      int                `bson:"level" json:"level"`                               // 部门层级
	LeaderId   string             `bson:"leaderId,omitempty" json:"leaderId,omitempty"`     // 部门负责人ID
	Leader     string             `bson:"leader,omitempty" json:"leader,omitempty"`         // 部门负责人姓名
	Count      int64              `bson:"count" json:"count"`                               // 部门人数
	UpdateAt   int64              `bson:"updateAt,omitempty" json:"updateAt,omitempty"`     // 更新时间
	CreateAt   int64              `bson:"createAt,omitempty" json:"createAt,omitempty"`     // 创建时间
}

type DepartmentUser struct {
	ID primitive.ObjectID `bson:"_id,omitempty" json:"id,omitempty"` // 关联ID

	DepId  string `bson:"depId,omitempty"`  // 部门ID
	UserId string `bson:"userId,omitempty"` // 用户ID

	UpdateAt int64 `bson:"updateAt,omitempty" json:"updateAt,omitempty"` // 更新时间
	CreateAt int64 `bson:"createAt,omitempty" json:"createAt,omitempty"` // 创建时间
}

Todo

基本上也都是CRUD接口

type Todo interface {
	Info(ctx context.Context, req *domain.IdPathReq) (resp *domain.TodoInfoResp, err error)   // 获取待办事项详情
	Create(ctx context.Context, req *domain.Todo) (resp *domain.IdResp, err error)            // 创建待办事项
	Edit(ctx context.Context, req *domain.Todo) (err error)                                   // 编辑待办事项
	Delete(ctx context.Context, req *domain.IdPathReq) (err error)                            // 删除待办事项
	Finish(ctx context.Context, req *domain.FinishedTodoReq) (err error)                      // 完成待办事项
	CreateRecord(ctx context.Context, req *domain.TodoRecord) (err error)                     // 创建待办操作记录
	List(ctx context.Context, req *domain.TodoListReq) (resp *domain.TodoListResp, err error) // 获取待办事项列表
}

表结构设计

type TodoRecord struct {
	TodoId   string `json:"todoId,omitempty"`
	UserId   string `json:"userId,omitempty"`
	UserName string `json:"userName,omitempty"`
	Content  string `json:"content,omitempty"`
	Image    string `json:"image,omitempty"`
	CreateAt int64  `json:"createAt,omitempty"`
}

type Todo struct {
	ID          string        `json:"id,omitempty"`
	CreatorId   string        `json:"creatorId,omitempty"`
	CreatorName string        `json:"creatorName,omitempty"`
	Title       string        `json:"title,omitempty"`
	DeadlineAt  int64         `json:"deadlineAt,omitempty"`
	Desc        string        `json:"desc,omitempty"`
	Status      int           `json:"status,omitempty"`
	Records     []*TodoRecord `json:"records,omitempty"`
	ExecuteIds  []string      `json:"executeIds,omitempty"` // 待办执行人
	TodoStatus  int           `json:"todoStatus,omitempty"`
}

type UserTodo struct {
	ID         string `json:"id,omitempty"`
	UserId     string `json:"userId,omitempty"`
	UserName   string `json:"userName,omitempty"`
	TodoId     string `json:"todoId,omitempty"`
	TodoStatus int    `json:"todoStatus,omitempty"` // 待办事项的状态
}

type TodoInfoResp struct {
	ID          string        `json:"id,omitempty"`
	CreatorId   string        `json:"creatorId,omitempty"`
	CreatorName string        `json:"creatorName,omitempty"`
	Title       string        `json:"title,omitempty"`
	DeadlineAt  int64         `json:"deadlineAt,omitempty"`
	Desc        string        `json:"desc,omitempty"`
	Records     []*TodoRecord `json:"records,omitempty"`
	ExecuteIds  []*UserTodo   `json:"executeIds,omitempty"`
	Status      int           `json:"status,omitempty"`
	TodoStatus  int           `json:"todoStatus,omitempty"`
}

审批

基本上也是CRUD

func (h *Approval) InitRegister(engine *gin.Engine) {
	// 创建审批路由组，添加JWT中间件进行身份验证
	g := engine.Group("v1/approval", h.svcCtx.Jwt.Handler)
	g.GET("/:id", h.Info)        // 获取审批详情
	g.POST("", h.Create)         // 创建审批申请
	g.PUT("/dispose", h.Dispose) // 处理审批（通过/拒绝/撤销）
	g.GET("/list", h.List)       // 获取审批列表
}

表结构设计

一张超级无敌巨宽的表

	Approval struct {
		ID primitive.ObjectID `bson:"_id,omitempty" json:"id,omitempty"` // 数据库ID

		UserId   string         `bson:"userId,omitempty" json:"userId,omitempty"`     // 申请人用户ID
		No       string         `bson:"no,omitempty" json:"no,omitempty"`             // 审批编号
		Type     ApprovalType   `bson:"type,omitempty" json:"type,omitempty"`         // 审批类型
		Status   ApprovalStatus `bson:"status,omitempty" json:"status,omitempty"`     // 审批状态
		Title    string         `bson:"title,omitempty" json:"title,omitempty"`       // 审批标题
		Abstract string         `bson:"abstract,omitempty" json:"abstract,omitempty"` // 审批摘要
		Reason   string         `bson:"reason,omitempty" json:"reason,omitempty"`     // 申请理由

		ApprovalId    string      `bson:"approvalId,omitempty"`    // 当前审批人ID
		ApprovalIdx   int         `bson:"approvalIdx,omitempty"`   // 当前审批人索引
		Approvers     []*Approver `bson:"approvers,omitempty"`     // 审批人列表
		CopyPersons   []*Approver `bson:"copyPersons,omitempty"`   // 抄送人列表
		Participation []string    `bson:"participation,omitempty"` // 参与人员ID列表

		FinishAt    int64 `bson:"finishAt,omitempty" json:"finishAt,omitempty"`       // 完成时间戳
		FinishDay   int64 `bson:"finishDay,omitempty" json:"finishDay,omitempty"`     // 完成日期
		FinishMonth int64 `bson:"finishMonth,omitempty" json:"finishMonth,omitempty"` // 完成月份
		FinishYeas  int64 `bson:"finishYeas,omitempty" json:"finishYeas,omitempty"`   // 完成年份

		MakeCard *MakeCard `bson:"makeCard,omitempty" json:"makeCard,omitempty"` // 补卡申请详情
		Leave    *Leave    `bson:"leave,omitempty" json:"leave,omitempty"`       // 请假申请详情
		GoOut    *GoOut    `bson:"goOut,omitempty" json:"goOut,omitempty"`       // 外出申请详情

		UpdateAt int64 `bson:"updateAt,omitempty" json:"updateAt,omitempty"` // 更新时间戳
		CreateAt int64 `bson:"createAt,omitempty" json:"createAt,omitempty"` // 创建时间戳
	}

	// Approver 审批人数据模型
	Approver struct {
		UserId   string         `bson:"userId,omitempty"`   // 用户ID
		UserName string         `bson:"userName,omitempty"` // 用户姓名
		Status   ApprovalStatus `bson:"status,omitempty"`   // 审批状态
		Reason   string         `bson:"reason,omitempty"`   // 审批理由
	}

	// MakeCard 补卡
	MakeCard struct {
		Date      int64         `bson:"date,omitempty"`          //补卡时间
		Reason    string        `bson:"reason,omitempty"`        //补卡理由
		Day       int64         `bson:"day,omitempty"`           //补卡日期(20221011)
		CheckType WorkCheckType `bson:"workCheckType,omitempty"` //补卡类型
	}

	// Leave 请假
	Leave struct {
		Type      LeaveType      `bson:"type,omitempty"`      //请假类型
		StartTime int64          `bson:"startTime,omitempty"` //开始时间
		EndTime   int64          `bson:"endTime,omitempty"`   //结束时间
		Reason    string         `bson:"reason,omitempty"`    //请假原由
		TimeType  TimeFormatType `bson:"timeType,omitempty"`  //请假类型  1=小时 2=天
	}

	// GoOut 外出
	GoOut struct {
		StartTime int64   `bson:"startTime,omitempty"` //开始时间
		EndTime   int64   `bson:"endTime,omitempty"`   //结束时间
		Duration  float32 `bson:"duration,omitempty"`  //时长(小时)
		Reason    string  `bson:"reason,omitempty"`    //外出原由
	}

Chat

AiHelper WebSocket 聊天技术总结

结论：聊天能力集中在后端独立 WS 服务（gorilla/websocket），与 Gin REST 共用 JWT；front/ 为空，无正式客户端。仓库内无架构图，设计意图主要体现在代码注释与 Chat_API_测试指南.md。

1. 整体架构

进程内双服务并行启动（共享同一 svc.ServiceContext）：

服务	框架	默认地址	职责
REST API	Gin	`0.0.0.0:8888`	登录、用户管理等
WebSocket	`net/http` + gorilla	`0.0.0.0:9000`，路径 `/ws`	实时私聊/群聊

客户端
  │
  ├─ POST /v1/user/login ──► Gin API ──► JWT(AccessToken)
  │
  └─ WS /ws (Header: websocket: <JWT>)
         │
         ▼
   handler/ws.Ws ──► logic.Chat ──► MongoDB chat_log
         │
         └─ 内存 uidToConn / ConnToUid 推送

入口：/Users/gzm/gopath/src/AiHelper/backend/main.go

api.NewHandle(svcContext).Run()
ws.NewWs(svcContext).Run()

依赖：github.com/gorilla/websocket v1.5.3（无 nhooyr、无 gin-websocket）

2. 连接生命周期

核心文件：/Users/gzm/gopath/src/AiHelper/backend/internal/handler/ws/ws.go

阶段	函数	行为
启动	`Ws.Run`	`http.HandleFunc("/ws", ServerWs)` + `ListenAndServe`
握手前鉴权	`Ws.auth`	读 Header `websocket`，JWT 解析取 uid
升级	`ServerWs` → `Upgrader.Upgrade`	响应头回写 `websocket: <token>`
登记连接	`addConn`	写入双向 map；同 uid 旧连接先 `Close`（单点在线）
读循环	`handleConn`（goroutine）	`ReadMessage` → JSON → 按 `chatType` 分发
发送	`send` / `sendByUids`	TextMessage + JSON
断开	`closeConn`	读失败或处理失败时清理 map 并关闭

要点：

CheckOrigin 恒为 true（注释写明生产应收紧）
鉴权失败只打日志并 return，不写 HTTP 错误体
JSON 解析失败或业务错误会 return 结束循环，但不一定走 closeConn（潜在连接泄漏）
无 ping/pong、心跳、重连协议

3. 消息协议

领域模型：domain.Message（/Users/gzm/gopath/src/AiHelper/backend/internal/domain/ws.go）

{
  "conversationId": "string",
  "recvId": "string",
  "sendId": "string",
  "chatType": 1,
  "content": "string",
  "contentType": 1
}

字段	说明
`conversationId`	群聊强制 `"all"`；私聊空则服务端生成
`recvId`	私聊必填；群聊可空
`sendId`	服务端强制覆盖为 JWT uid，防伪造
`chatType`	见下表（以代码为准）
`content` / `contentType`	内容；`contentType` 注释为 1 文字 / 2 图片 / 3 表情等，未入库

model.ChatType（chatlogtypes.go）：

值	常量	含义
1	`GroupChatType`	群聊
2	`SingleChatType`	私聊

分发（handleConn）：

SingleChatType → privateChat → logic.Chat.PrivateChat → sendByUids(recvId)
GroupChatType → groupChat → logic.Chat.GroupChat → sendByUids()（全员广播）

注意：backend/doc/Chat_API_测试指南.md 把私聊写成 chatType:1、群聊写成 2，与代码相反；以 domain/model 注释为准。

无独立事件类型字段（无 event/type/ack）；协议即「一条 JSON = 一条聊天消息」。

4. Auth / Session 与 REST 关系

登录（REST）

POST /v1/user/login → User.Login → logic.user.Login
token.GetJwtToken(secret, iat, expire, user.ID.Hex())
Claims：exp/iat + 自定义键 aihelper（常量 token.Identify）= uid
响应：LoginResp.AccessToken（JSON 字段名 token）

REST 鉴权

Header：Authorization: Bearer <JWT>
中间件：middleware.Jwt.Handler → token.Parse.ParseWithContext

WS 鉴权

Header：websocket: <JWT>（非 Bearer）
Ws.auth → 同一 token.Parse + 同一 Jwt.Secret
连接期把 uid/token 放入 context（Ws.context），供业务/日志使用

会话模型：

无独立 chat room / WS session 表
在线态 = 进程内 uidToConn / ConnToUid
会话 ID：
- 群聊："all"（全局大厅）
- 私聊：GenerateUniqueID(sendId, recvId) = 排序后拼接 → SHA256 → Base64Raw 取前 22 位（顺序无关、稳定）

持久化：ChatLogModel.Insert → MongoDB chat_log；无按会话拉历史的 REST/WS API（模型仅有 Insert/FindOne/Update/Delete）。

5. 关键组件与数据流

关键文件

路径	角色
`backend/main.go`	API + WS 双 goroutine 启动
`backend/internal/handler/ws/ws.go`	连接管理、鉴权、读写循环
`backend/internal/handler/ws/conversation.go`	`privateChat` / `groupChat` 推送
`backend/internal/domain/ws.go`	`Message` 协议结构
`backend/internal/logic/chat.go`	落库、`GenerateUniqueID`
`backend/internal/model/chatlogtypes.go`	`ChatLog`、`ChatType`
`backend/internal/model/chatlogmodel.go`	MongoDAO
`backend/pkg/token/{token,ctxtoken}.go`	JWT 签发/解析
`backend/internal/middleware/jwt.go`	REST JWT
`backend/internal/logic/user.go`	登录发 Token
`backend/internal/config/config.go` + `etc/*/api.yaml`	`Ws.Addr`、`Jwt.*`
`backend/doc/Chat_API_测试指南.md`	手工联调文档（部分与代码不一致）
`backend/internal/logic/chat_test.go`	仅测 `GenerateUniqueID`

客户端

front/ 目录为空
文档用 wscat -c ws://localhost:9000/ws -H "websocket:{token}"

数据流（私聊）

A 发 JSON（recvId=B, chatType=2）
handleConn 设 SendId=A
PrivateChat → 必要时生成 conversationId → Insert
sendByUids(ctx, msg, B) → 仅 B 在线则推送
发送者 A 收不到自己消息的 echo（代码注释已说明）

数据流（群聊）

chatType=1 → ConversationId="all" → 落库
sendByUids 无 uid → 广播所有在线用户（含发送者）
文档写「除发送者外」与代码不符；也不是真实群组房间，而是全站在线广播

6. 重要设计决策

API/WS 端口分离：Gin 与裸 net/http 各占端口，共享 Mongo/JWT 配置
共享 ServiceContext：避免双实例初始化竞态（main.go 注释）
Header 传 Token：自定义 websocket 头，规避部分 WS 客户端难带 Authorization 的问题
服务端信任边界：sendId 只认 JWT，客户端不可伪造
单连接/用户：新连踢旧连
轻量会话：无私聊房间实体；群聊固定 "all"
先存后推：落库成功再推送；接收方离线则只落库、不推
内存连接表：单机、无 Redis；水平扩展需改造
协议极简：无 ACK、回执、已读、错误帧、心跳
安全简化：全放行 Origin；鉴权失败无标准 HTTP 状态

7. 配置与联调

本地配置示例（backend/etc/local/api.yaml）：

API：0.0.0.0:8888
WS：0.0.0.0:9000
JWT：Secret + Expire

推荐联调顺序（与文档一致、chatType 按代码）：

POST /v1/user/login 取 token 与 id
wscat 带 websocket 头连 /ws
私聊：chatType: 2 + recvId
群聊：chatType: 1

8. 缺口与风险（实现现状）

无前端 WS 客户端
无聊天历史查询 API
contentType 未持久化
文档 chatType、群聊是否回显发送者与代码不一致
处理错误路径可能未清理连接
群聊非真实群组，而是全局广播
无多实例在线路由能力