Files
zkxw/openspec/changes/zkxw-engineering-standards/specs/architecture-conventions/spec.md
T
zlwuandCursor 245b8c9a81 docs(agents): 区分应用运行凭据与 Agent 操作账号
避免排障时把管理账号写进应用配置,操作账号只从本工程授权来源按需读取。

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-02 09:19:54 +08:00

56 lines
4.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## ADDED Requirements
> 来源说明:文中《中科兴皖需求 V0.3》及其章节引用为历史出处,原文已清理;以下既有 SHALL 要求继续有效,当前入口见根 `AGENTS.md` 与本工程标准。
### Requirement: 仓库采用前后端分离的一体化门户形态
中科兴皖一体化门户 SHALL 以「Python 后端 + Web 管理端 + 小程序端」的形态组织代码与部署单元;业务域(细胞存储、中试、系统管理等)共享同一后端与租户模型,除非需求文档明确声明独立子系统。
#### Scenario: 新人识别工程边界
- **WHEN** 阅读仓库根目录说明或 OpenSpec `architecture-conventions`
- **THEN** 文档 SHALL 指明后端入口、管理端入口、小程序工程目录及 API 前缀约定(与 `AGENTS.md` 一致)
### Requirement: 技术栈与需求文档 §3 对齐
系统 SHALL 使用 MySQL 5.7 作为关系型数据库;后端 SHALL 使用 Python 实现;Web 管理端 SHALL 基于 Vue 技术栈在精简后的管理端模板工程上扩展;小程序 SHALL 基于 uni-app、Vue 3 与 Vant 体系实现业务界面(与《中科兴皖需求 V0.3》§3 及当前 `miniprogram` 工程一致或可文档化迁移)。
#### Scenario: 技术选型评审
- **WHEN** 新增服务或子工程选型
- **THEN** 选型说明 SHALL 论证与上述栈的兼容性,或作为独立变更更新本 spec 与 `proposal.md`
### Requirement: 附件与对象存储
业务附件 SHALL 通过对象存储(如 MinIO)保存可访问 URL;多附件在同一字段内存储时 SHALL 使用英文逗号分隔多个 URL(与需求 §3 一致)。
#### Scenario: 上传列表回显
- **WHEN** 业务实体包含多个附件
- **THEN** 持久化字段 SHALL 为逗号分隔的 URL 字符串,且接口契约与前端解析逻辑一致
### Requirement: 权威文档索引
实现类变更 SHALL 将根 `AGENTS.md`、`openspec/changes/zkxw-engineering-standards/specs/`、`docs/web-admin-ui-spec-fresh-mint.md`、`docs/web-admin-ui-pattern-index.md` 及 `docs/miniprogram-ui-spec-sanqiang.md` 视为架构与规范的索引入口;OpenSpec 变更 SHALL 在 `proposal.md` / `design.md` 中保持对上述路径的引用。
#### Scenario: UI 相关 PR 描述
- **WHEN** 提交涉及 Web 或小程序界面的 PR
- **THEN** PR 或关联 OpenSpec SHALL 声明遵循的 UI 规范文档路径
### Requirement: 运行凭据与 Agent 操作凭据分离
应用运行凭据 SHALL 继续由对应应用的 `.env`、配置文件或部署环境注入管理,包括数据库、Redis、MinIO、业务微信接口及应用签名或加密密钥。现有 `backend/.env`、`backend/.env.production`、`deploy/docker/.env` 等来源按实际环境使用,不为统一账号保存位置而迁移或复制其中的值。
工程根目录 `.local/secrets/access.json` SHALL 仅用于 Agent 操作账号,如服务器 SSH、GitHub/Gitea 仓库管理及 Figma 平台访问;它不是应用运行配置源,不接入业务代码或容器启动配置。可用的 MCP、OAuth、CLI 会话继续复用,不为填文件重复索要密码。应用排障按需读取原运行配置,不使用平台管理账号替换应用身份。
Agent 使用操作账号前 SHALL 核对当前工程、服务用途、环境和任务授权,只读取所需字段;服务器测试与生产账号分开。该文件不纳入 Git、镜像、交付包或更新器,目录权限为 `700`、文件为 `600`(macOS/Linux);不得在聊天、日志或工单回显真实值。worktree 缺文件时仅核对并复用同仓库主工作目录的已授权来源,不能跨工程搜集或自动回退生产。
#### Scenario: 应用数据库认证失败
- **WHEN** 后端连接数据库失败,而操作账号文件中有其他管理账号
- **THEN** 核对后端实际加载的环境配置及其账号,不把管理账号写入运行配置,也不改为读取操作账号文件。
#### Scenario: Agent 访问仓库或设计平台
- **WHEN** 已授权任务需要 Gitea、GitHub 或 Figma 身份认证
- **THEN** 优先复用可用工具会话;需要账号时从本工程操作账号来源按需读取,仅缺失或无效时补充,不改动应用运行配置。