# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

英国 CDS（海关申报系统）账户管理系统：PHP API（导入 CDS 账户凭证、查询已下载 PVA/C79 海关文件记录）+ 内部 HTML 仪表盘（中文界面），后端 SQL Server（`rpa` 库）。对外对接说明见 README.md。

## 常用命令

- 本地服务：`php -S 0.0.0.0:8888 -t .`（需 `pdo_sqlsrv` 扩展）
- 单文件校验：`php -l api/<file>.php`
- 无构建、无包管理器、无测试框架——改完只能语法校验 + 手动调接口验证

## 架构总览

- `api/`：全部 PHP 入口 + `auth_check.php`；`config.php`：数据库与仪表盘登录配置（硬编码，无环境变量层）
- 环境切换：`config.php` 顶部 `APP_ENV` 常量——`production`（默认，内网 `172.16.16.13:1433`）/`test`（本地测试，Tencent CDB 外网 `gz-mssql-4jvvbair.sql.tencentcdb.com:25944`）。同实例，正式服务器保持默认即可
- JSON API（响应统一 `{code, msg, data}`，不受登录限制）：
  - `api_import.php`（POST）— 老系统批量 upsert 账户凭证。**先删后插**（按 account_id/account_alias 删旧插新，**仅限 `DataSource='source'` 行**，硬编码初始状态）——重导入会重置老系统行执行进度；整批事务 + `strict_mode`（true 任一错全回滚）
  - `api_cds_register.php`（POST，新系统）— 接收 `GB_VAT_REGISTER_CDS_FILE` 推送（UNIFIED 信封 + `bizParam` 原样 + async 受理），写入/接管 `DataSource='api'` 行；**进度不重置**；文件下载完成后经 delivery 异步结果通知接口回调
  - `api_search.php`（GET）— 查询已下载文件（**全量，不按归属过滤——老系统可查新系统数据**）。**每次查询都会调用外部 PDF 解析服务并回写 `total_postponed`，有副作用，不是只读语义**
- HTML 仪表盘：输出前 `auth_check.php`（session 校验 → `login.php`，`next` 仅白名单防开放重定向；仅仪表盘受限，JSON API 免登录）
  - `dashboard.php` 账户总览 / `cdsAccountCheck.php` 失败账户（`last_execute_result=3`）/ `ukVatRegistration.php` VAT 注册跟踪
- 数据库表：`cds_download`（账户+状态+归属`DataSource` source/api + `biz_param`；`account_id` 唯一索引）、`cds_download_log`（每文件一行，UQ(account_id, file_type, file_date) 三列）、`cds_download_notify_log`（新系统通知日志）、`uk_vat_register`（VAT 流水线）

## 执行状态码（PHP 与外部调度器通用约定）

`last_execute_result`：`0`=未开始 `1`=执行中 `2`=已完成 `3`=失败

## 红线与不可推导约定

- 签名验证已禁用：`api_import.php` 的 MD5 校验（ksort 参数值+盐值）`throw` 已注释，`api_search.php` 读 `sign` 不校验
- 双系统归属：`cds_download.DataSource` 是账号**当前归属**（非数据来源），只能单向交接 source→api（api_cds_register 接管）；`api_import.php` 的先删后插**不会**抢回已交接行；`rpa_cds_get.py` 不区分系统按状态领取，`rpa_cds_save.py` 保存时按**当时归属**分流（api 行发通知、解析走 `NEW_FILE_ANALYSIS_API`）
- 新系统解析接口地址 `NEW_FILE_ANALYSIS_API`（python/rpa_cds_save.py 顶部常量）**暂为老接口地址**，待新系统提供后替换（传参/返回与老接口一致）
- 通知只为新插入的日志行发送：账号被接管时本月文件若已存在（老系统时期已下载），不补发通知；`cds_download_notify_log` 表尚未迁移时仅告警，不影响主流程
- 以代码为准：旧文档《CDS数据导入API接口文档-有MD5验证.md》的 `{success,message,data}` 格式与 `MY_SECRET_SALT` 盐值已过时
- 每个端点顶部 `error_reporting(0)`：PHP 错误不输出到响应，排查看日志
- 仪表盘登录账号密码在 `config.php` 的 `DASHBOARD_AUTH_*`；登录失败按 IP 限流
- 外部调度参考脚本（原 api_doc/py/，已删除可查 git 历史）使用 MySQL 占位凭据，与 PHP 层 SQL Server 不共享连接；其目标 `file_date` 按"每月 10 号"规则：10 号前→上上月，10 号起→上月（外部系统逻辑，勿当本仓契约）

## 详细说明（按需加载）

- `docs/CDS数据对接新系统接口文档.md` — 新系统（GB_VAT_REGISTER_CDS_FILE）对外契约：请求/响应/归属语义/结果通知回调/通知日志表/部署顺序
- `@.claude/docs/api-endpoints.md` — API 端点细节：upsert 先删后插参数、懒加载回写机制、验证逻辑、新系统接收接口
- `@.claude/docs/ukVatRegistration.md` — 重置绑定弹层：VRS 格式校验（12 位数字每 4 位空格）、税号生效日期、写回与错误类型
- `@.claude/docs/database.md` — 表字段明细、连接串、`database/cds_schema_export_legacy.sql` 三表实时结构快照