Veyra/docs/development-state.md

# 开发记忆与交接状态

更新日期：2026-10-08。

## 产品与依据

- 产品名称「见势 · Veyra」，面向从空仓开始的 A 股投资者。
- 根目录 `hengce_fullstack_technical_design_v1.md` 为实施设计，`hengce_app_admin_prototype.html` 为双端交互与视觉参考，均保留。
- 目标闭环：偏好 → 观察候选 → 证据 → 买入计划 → 条件提醒 → 用户记录成交 → 持仓监控 → 退出 → 复盘。
- Go 负责业务、账本与风控；Python 负责量化研究与回测；App 使用 React Native + Expo。
- 首期用户自行交易，提醒不代表成交，不自动下单。

## 用户确认的硬性规则

- 后端严格遵循 Go 工程规范，采用根目录唯一入口/internal 分层、依赖注入、显式 SQL、context、错误处理及 gofmt/go vet。
- 所有数据库表以 `veyra_` 开头，字段 snake_case。
- 主键为字符串 UUID：数据库 varchar(36)，Go string；外键同类型。
- 映射去前缀后 PascalCase，例如 `veyra_user` 对应 `User`。
- 管理端使用 Vite + React + Tailwind CSS + shadcn/ui，并通过 Go embed 嵌入后端。同一二进制提供页面和 API。
- PostgreSQL：192.168.100.127:5432，数据库 veyra；Redis：192.168.100.127:6379，无用户名、有密码。
- 凭据保存在本地 `configs/.env`，禁止写进 Git 或项目记忆。

## 已实现

- Go API：健康检查、结构化日志、请求 ID、超时、优雅停机。
- 独立建库与迁移命令，迁移使用事务、并发锁、checksum 和字符串 UUID 迁移记录。
- 十二版迁移已应用开发数据库，覆盖身份、配置、候选、计划、账本、通知、策略、回测与自动行情。
- local/test 开发身份初始化；密码 bcrypt 哈希、随机会话凭据、数据库只保存会话哈希。
- 管理端 Cookie 和 App Bearer 会话隔离，退出撤销、过期与状态校验、管理员权限校验。
- Redis 登录限流；管理端 Cookie 为 HttpOnly、SameSite=Strict，写操作校验同源 Origin。
- 账户创建、归属查询、账户列表；模拟资金初始化原子入账，整数分计算、金额字符串 API；真实记录账户现金未知。
- 管理端登录页、服务总览、用户列表、模型配置、行情源配置、审计日志和十个工作区入口；未实现业务页面显示建设中。
- 主模型、备用模型、审核模型与行情源由管理员配置，供应商/地址/模型/密钥初始留空并关闭，不在环境模板预选厂家。配置保存和启用均不代表真实连通性或模型能力已验证。
- 供应商密钥采用 AES-256-GCM 加密，主密钥只在本地环境保存；查询、历史 JSON 与审计不返回密钥。保留/替换/清除密钥与版本保护已实现；更换地址不能静默复用密钥。配置、历史与审计同事务保存。
- Expo App 位于 apps/mobile：SDK 55、React Native 0.83.10、React 19.2.4、Expo Router 五导航；白底、石墨黑与柔紫。开发 USER 登录、SecureStore 会话恢复/到期清理/服务端退出撤销、真实账户列表/创建/切换/现金展示已接通。
- TanStack Query 查询、Zustand 当前账户选择；账户切换中断旧查询并清理详情缓存，退出清理身份缓存，迟到响应不能影响新会话。金额保持十进制字符串。
- App 首页、机会、计划、持仓、我的与提醒入口；未接入业务准确标注尚未开放，不展示原型股票或预设盈亏。
- OpenAPI、依赖锁文件和带 PostgreSQL 集成测试服务的 CI；CI 增加 App 类型检查、客户端测试与双平台 bundle 导出。
- npm --prefix web/admin run build 构建管理端并复制至 embed；go build -o bin/veyra . 生成唯一可执行文件。

## 当前工程目录

- 用户指出旧后端目录过深，当前已改为仓库根目录的单 Go module。
- module 为 git.sundynix.cn/Blizzard/Veyra，与仓库地址一致；删除单模块 go.work。
- 用户进一步要求一个 main 函数：三个 cmd 入口已合并到根目录 main.go，初始化操作通过 -command 参数切换，默认启动 HTTP 服务。
- internal/model 放模型，internal/service 放业务，internal/repository 放 SQL 与事务，internal/handler 放 HTTP 路由和协议适配。
- internal/config、database、adminui、apperror、ratelimit 放当前实际需要的设施；避免多余嵌套和空目录。
- 管理端由 apps/admin 迁至 web/admin；embed 构建产物由 internal/adminui/dist 提供。App 保留独立 apps/mobile 目录，与后端单 module 无冲突。
- 管理端和 App 各自维护 npm 配置、锁文件与 node_modules；根目录不再使用 npm workspace 或声明 Expo Router。Metro 与 Babel 使用 App 本地依赖。App 固定 React 19.2.4，满足 React Native ^19.2.0 peer，显式排除 SDK 建议补丁版本比较；其余配套检查保留，实际设备验证仍待完成。
- Makefile 已移除，CI、npm scripts 与文档均直接使用 Go/npm 命令；原 HTTP 接口保持一致，CLI 统一到根目录。
- 原始设计报告中的 monorepo 目录仅为旧规划，当前实现以本文件、AGENTS.md 和 README 的结构为准。
- 迁移文件仅移动路径，已逐字节核对两版 SQL 与原提交一致，不影响已执行迁移的 checksum。
- 新结构已通过前端构建与 embed、Go 编译、race 检查和 go vet；本轮已补充真实数据库集成验证。

## 验证与环境事实

- 当前执行环境已允许访问内网与监听本机端口。PostgreSQL 和 Redis 均已验证可连接；以前的 Operation not permitted 属于旧沙箱限制，不能继续当作当前阻塞。
- 已在 veyra 应用全部十二版迁移，初始化本地环境指定的开发管理员。用户随后提供 LLM 连接信息，已通过后台 API 把 base_url 与加密密钥保存到主模型配置；模型名称仍为空、未启用，备用/审核/行情源未填入用户配置。此前配置表为空是接入前状态，现已变化。
- `go test -race ./...` 已带真实数据库连接执行，在随机临时 schema 中验证迁移幂等/checksum/UUID、身份事务与会话撤销、账户归属与金额、供应商加密保存/密钥保留清除/并发版本冲突/历史审计原子性、配置 API 认证和 Origin 保护。
- `go vet ./...`、前端 TypeScript 检查与生产构建、Go 入口构建通过，管理端产物已复制至 embed 目录。
- 实际 HTTP 服务验证：页面 200、readyz 200、管理员登录/配置读取/审计读取/退出均 200。测试未填入供应商或调用外部 AI/行情接口。
- Chrome 已完成候选录入表单、通知任务与行情搜索的页面验证；App 真机与模拟器界面仍未验证。

## 启动与后续

- 已初始化数据库使用 `go run . -command db-migrate` 应用后续迁移，无需重复建库。
- 管理端初始化：`configs/.env` 的 ADMIN_LOGIN / ADMIN_PASSWORD，执行 `go run . -command user-create -role ADMIN`；App 测试身份使用 DEV_USER_LOGIN / DEV_USER_PASSWORD 和 `go run . -command user-create -role USER`。
- 本地 `configs/.env` 保存开发身份配置和供应商凭据加密主密钥，管理员配置已按用户指示更新；模板不含秘密值，已有身份不会由初始化命令覆盖。加密主密钥须持久保存并随数据库备份，不能直接更换后继续读取旧密文。
- 先 npm --prefix web/admin run build 构建前端，再 go run . 启动后端；默认 http://127.0.0.1:8080，自动读取当前目录的 configs/.env。
- 当前开发密码登录仅限 local/test；正式短信登录、刷新流程、MFA 和细分 RBAC 待实现。
- 候选、计划、模拟成交、冲正、持仓和累计账本复盘已接通；后续待自动候选筛选及真实规则与授权集成。
- 自动公开行情、日线查询、Python 历史回测与 Worker 已实现；AI 调用、正式授权行情及完整产品仍未完成。
- App 初始化与启动：go run . -command user-create -role USER → 设置 apps/mobile/.env 的 EXPO_PUBLIC_API_URL → npm --prefix apps/mobile run start；npm --prefix apps/mobile run typecheck && npm --prefix apps/mobile run test 检查类型与客户端测试，npm --prefix apps/mobile run build 导出双平台 Hermes bundle。公开环境配置只放 API 地址，不放秘密。

## Git 状态

- 本轮开始时已有用户提交 bffdb38（feat: 基础框架搭建完毕），旧文档中“无提交/无 Git 写权限”是历史状态，现已失效。
- 本次提交包含供应商后台配置与后续业务实现；推送以 Git 远端记录和提交完成报告为准。

## 本轮开发状态与待办

- 用户明确要求供应商选择留空，后续在后台配置，已完成上述配置管理与审计功能；没有预选模型厂商或行情供应商。
- 候选审核草稿已整合到当前 model/service/repository/handler 目录，使用第五版迁移并复用原有审计表。
- 下一步：候选修订/审核发布 → 计划预算与确认 → 成交账本/冲正/持仓 → 条件提醒与复盘，同时落实 Expo App。
- 供应商适配器、服务端连接测试、真实行情与 AI 调用仍待实现；配置页面没有虚构在线测试结果。正式认证、策略回测、Worker/任务、细分 RBAC 仍待完成。

## App 本轮验证与待办

- App USER 测试身份已用本地环境配置创建，未写入客户端或文档凭据；真实账户未注入测试资金。
- npm ci 成功，React 补丁版本已与管理端统一，Expo Doctor 20/20 检查通过；React 建议版本比较按前述规则显式排除，其余配套检查保留。客户端 11 项测试通过，覆盖请求鉴权/取消/网络错误、会话变更隔离、安全存储写入顺序与精确金额边界。
- Android/iOS Metro 和 Hermes bundle 导出已成功；App 请求客户端对实际 Go API 的登录、身份、账户查询、退出和退出后 401 验证通过。
- 本机 xcrun 无 simctl，且无 adb；尚未进行模拟器/真机交互与安全存储实机验证，没有生成 APK 或 IPA。不能将 bundle 导出记作原生包或设备运行验证。
- 仍需接入偏好、候选证据、计划预算、成交/冲正、持仓监控、提醒与复盘页面及 API，正式手机号身份、设备推送与原生发布也未完成。
- 本轮改动纳入此次用户授权的提交；原始两个设计文件未修改。

## LLM 连接配置

- 用户明确要求只保存连接配置，禁止将供应商地址、模型名或密钥写死到代码中；已保存 base_url 与 api_key，密钥经 AES-256-GCM 加密。
- 用户最后确认本轮只使用 base_url 和 api_key；未填写模型名称、未改动备用或审核配置、未执行模型调用或连接测试。
- 配置保存后通过后台 GET 回读核对版本与 has_api_key，响应不含明文密钥或密文；临时引导环境变量已从本地环境文件清除。文档不记录密钥或真实连接地址。
- 第四版迁移仅新增可配置元数据，无供应商地址或模型种子值。后台支持协议、模型目录及响应存储/认证开关，目录地址须与接口同源；这些设置仍属配置管理，调用适配器未实现。
- 原消息中的 Codex 网络、WSL、goals 等运行参数不写入产品 LLM 连接配置。本轮不修改 Codex 自身配置。

## 单入口与管理员设置

- 用户要求一个 main 函数、不使用 Makefile，已删除 cmd/api、cmd/db、cmd/user 与 Makefile，保留根目录 main.go；仓库仍是根目录单 Go module，不引入 go.work。
- 运行 go run . 启动服务；维护操作使用 -command db-create/db-migrate/user-create/admin-set。前端构建使用 npm --prefix web/admin run build，再 go build -o bin/veyra .；IDE 可直接运行 main.go。
- 按用户指示修改现有开发管理员的登录名与密码；凭据只保存在本地环境与数据库 bcrypt 哈希中，文档不记录密码。管理员 ID 保持不变，旧会话撤销。
- admin-set 仅允许 local/test 与已有 ACTIVE ADMIN，不允许把普通用户提升成管理员；冲突事务回滚。登录创建会话时重新检查已验证的密码哈希并锁定身份，避免凭据修改后的旧验证结果创建新会话。
- 开发管理员密码范围为 8–72 字节，App 用户仍要求 12–72 字节；正式认证边界保持不变。

- 本轮验证：根目录 go run . 成功启动；管理端页面/readyz/新管理员登录/me/供应商配置回读/退出均通过实际 HTTP 校验。单入口 db-migrate 已验证幂等执行。
- 带真实 PostgreSQL 临时 schema 的 go test -race ./...、go vet 与唯一二进制编译通过；新增管理员修改测试覆盖身份 ID 保留、原会话失效、登录名冲突回滚、禁止修改普通用户与禁止生产环境使用，以及旧密码验证结果不能创建会话。

## 工程目录清理

- 后端环境文件与模板移至 configs/.env、configs/.env.example，配置值及加密主密钥保持原样；唯一入口默认读取新路径，仍支持 -env-file 与进程环境变量。
- 删除根目录 package.json、package-lock.json 和 node_modules。web/admin 与 apps/mobile 分别维护独立配置、锁文件和依赖；兼容版本约束下放到各自 package.json。
- CI、README、App 说明、AGENTS.md 与未构建管理端的提示已同步更新；构建直接使用 npm --prefix <前端目录> run build。单 Go module、单 main 函数和无 Makefile 保持不变。
- 两个前端均已在移除根目录依赖后通过 npm ci；管理端类型检查/生产构建/embed、App 类型检查/11 项测试/iOS 和 Android Hermes bundle 导出通过。Go vet、唯一二进制编译、真实 PostgreSQL 临时 schema 下的 race 测试通过。
- 根目录 go run . 已验证自动加载 configs/.env，嵌入页面、PostgreSQL/Redis 就绪、管理员登录、供应商配置回读与退出均通过；测试服务已停止。原始设计文件未修改，本轮改动纳入此次用户授权的提交。
- App 安装时 npm audit 报告 35 项依赖问题（14 moderate、21 high）；未在目录清理中强制升级 Expo 依赖，后续需单独处理并复验原生兼容性。

## 模拟交易闭环（本轮进行中）

- 已实现第五至第八版迁移，第五至第八版已应用开发数据库；当前总计十二版；原始迁移保留 checksum，不修改已经执行的版本。
- 候选审核：手工模拟候选录入、独立修订、提交审核、发布、退回、撤回、时效与版本保护。发布内容保留历史，App 仅能访问曾发布修订；有效列表仅显示当前未过期发布。App 可查看撤回原因，内部审核身份与完整意见列表不返回 App。
- 计划：模拟账户买入预算预览、确认重检候选版本与时效、现金争用保护、同一预览幂等确认、取消、失效与预算释放。预览五分钟内有效。当前模拟数量规则为 100 股倍数，不代表完整真实交易所规则。
- 成交账本：模拟买入/卖出录入、实际费用、发生时间顺序与幂等保护、部分成交与计划保留额度、FIFO 批次及成本分摊、含费用已实现盈亏、最新未冲正成交的冲正。数据库触发器禁止覆盖或删除已入账成交、现金流水、分摊与冲正事实；冲正保留原记录，不自动重开原计划。
- 可卖时间由模拟成交明确输入，不根据自然日冒充交易日历或真实 T+1。真实记录账户的成交账本仍未接通，市场价格、浮盈亏与市值保持未知。
- 通知：同一后端进程中的轮询 Worker，Outbox 事务处理、手工模拟价格回放、当前快照/时效/候选/计划重检、每计划一次条件提醒、撤回或过期失效通知、本人站内列表与已读。远程推送未实现；提醒不产生交易或现金变动。
- 管理端候选审核、通知任务、数据健康中的模拟价格回放已替代占位；App 候选/证据/预算/计划/成交/持仓/冲正/站内通知及累计账本复盘已接通。
- 真实 PostgreSQL 临时 schema 下的 race 测试通过：候选并发审核、历史保护、发布与事件失败回滚、计划现金争用与取消、部分成交、偏离说明、冲正不重开计划、FIFO 舍入、重复请求、冲正失败回滚、不可覆盖成交、模拟可卖时间、过期快照、不重复提醒、提醒不改账本与复盘金额。
- 管理端类型检查/生产构建/embed、App 类型检查/12 项客户端测试/iOS 与 Android Hermes 导出、go vet/唯一二进制编译已通过；后续代码变更按需复验。
- 本机 8080 由用户 IDE 的旧进程占用，没有关闭用户进程。当前自有验证服务运行 8081；新增管理端与 App HTTP 读接口及登录/退出已通过，不向开发账户插入候选、资金或成交。
- 本轮 Chrome 已可用，实际验证新版候选队列、空白录入表单、通知任务与模拟价格入口，未保存任何业务数据。先前无浏览器是历史环境事实；尚未验证 App 真机/模拟器。
- 待继续：策略版本管理、Python 历史回测、自动行情与供应商调用、偏好与关注、生产服务授权及正式认证/远程推送。本轮改动纳入此次用户授权的提交。


## 本轮完成：日志、研究与 A 股自动接入

- 按用户要求引入 zap；控制台使用易读编码，文件为 JSON，默认写入当前工作目录 logs/veyra.log。50 MB 轮转、保留 10 个备份及 14 天、压缩历史；LOG_DIR/LOG_LEVEL/LOG_MAX_SIZE_MB/LOG_MAX_BACKUPS/LOG_MAX_AGE_DAYS 可在配置文件修改。文件初建权限 0600，日志忽略 Git，不记录口令、请求正文、Cookie 或原始查询串。
- 策略中心支持新建研究策略、不可覆盖版本、选用研究版本、暂停和审计。研究版本管理尚未控制手工候选或既有计划，不冒充已部署自动交易策略。开发数据库已保存一个暂停的均线研究基线，可在后台修订；该基线没有性能背书。
- Python 回测使用固定策略版本、参数、输入 SHA-256 和原始数据快照。异步任务带独立 lease、过期恢复、完成保护和失败状态；使用此前完成日线生成信号、次日开盘模拟成交，整数价格/费用/滑点，保存权益序列和成本后成交结果。未实现复权企业行为、停牌、涨跌停、交易日历成交限制或样本外研究。
- 用户明确要求自动 A 股接入，已增加可配置公开行情适配器。东方财富接口首次读取得到数据，后续连接关闭；未把失败当成同步成功。现开发配置采用新浪公开接口，全部地址保存后台配置，免账号；东方财富适配器仍可选。没有静默运行时切源或覆盖失败事实。
- 自动同步沪深证券列表和有效报价，启动执行、每五分钟更新；配置变更十秒内检测，保存源配置版本、供应商行情时间、接收时间与同步记录。首次成功写入 5213 条沪深有效报价，不含北交所，不代表全部证券主数据或正式授权行情。API 查询默认最多 100 条，支持名称/代码搜索。
- 后台数据健康显示股票与同步结果；系统设置可修改适配器及列表/报价/历史地址、启停。App 机会页有 A 股行情入口，支持搜索与明确的历史快照时间；不把接收时间伪装成行情产生时间。
- 回测默认按股票、交易所与日期自动获取日线，CSV 作为复验入口保留。实际从新浪接口读取一个标的的 2025 年一季度 57 根不复权日线，回测任务完成并得到 3 条模拟成交；没有产生真实交易、资金或账户持仓。
- 真实 PostgreSQL 临时 schema 的 race 测试、行情精度/供应商时间/非法 OHLC/不可舍入价格测试、Python 无未来数据与费用计算测试通过；go vet、唯一二进制、管理端类型检查/构建/embed、App 类型检查与双平台 Hermes 导出通过。App 客户端 12 项测试通过。
- 开发预览后端保留在 0.0.0.0:8083；管理端 http://127.0.0.1:8083。App 本地公开配置为 http://192.168.100.2:8083，Metro 为 exp://192.168.100.2:8081，使用同一内网 Expo Go 查看。固定了 Metro 的网卡选择，避免发布 VPN 虚拟地址。本地常规 HTTP_ADDR 已设 0.0.0.0:8080，需要用户 IDE 重启才读取新代码；未关闭用户 IDE 进程。
- 公开源仅为开发研究接入，缺少官方服务保障和商业展示授权确认。行情自动同步还没有驱动自动候选筛选、AI 解释或计划条件触发；现有提醒仍由明确标记的模拟价格回放驱动。
- 用户要求“做完这个功能就先停止”，本轮在 A 股自动接入验证后停止开发，预览服务保留。后续待自动筛选/审核、AI 分析、偏好与关注、生产授权、正式认证和远程推送；不自动继续扩展。本轮改动纳入此次用户授权的提交，原始两份设计文件未修改。


## 本轮提交准备

- 用户已明确要求提交并 push，本次提交包含工程目录整理、后台配置、App 模拟业务闭环、zap 日志、策略与回测及 A 股自动接入。验证状态和未完成能力以上文最新记录为准。
- 本地环境、密钥、日志、依赖目录和构建产物不纳入提交；原始设计文件保持不变。目标分支为 master，远端为 origin。